diff options
Diffstat (limited to 'include/apos/uapi.h')
| -rw-r--r-- | include/apos/uapi.h | 451 |
1 files changed, 420 insertions, 31 deletions
diff --git a/include/apos/uapi.h b/include/apos/uapi.h index f0cb9b7..9155c30 100644 --- a/include/apos/uapi.h +++ b/include/apos/uapi.h @@ -9,21 +9,98 @@ #include <apos/syscalls.h> #include <apos/vmem.h> -/* syscall function type, let's start with four arguments and see where that - * goes */ +/** + * Syscall function type. + * Let's start with four arguments and see where that goes + */ typedef struct sys_ret (*sys_t)(long, long, long, long); -/* TODO: should this be arch specific? should be the size of an integer register */ + +/** + * Syscall argument type. + * + * \todo: Should this be arch specific? should be the size of an integer + * register. + */ typedef long sys_arg_t; +/** + * Return structure of syscall. + * \note Field names are generic, and can be used for two values or two error + * codes, check documentation of whatever you're doing. + */ struct sys_ret { + /** Error code of syscall. */ sys_arg_t err; + + /** Value returned by syscall. */ sys_arg_t val; }; -#define SYSCALL_DECLARE(name) \ +/** + * Helper macro for declaring syscalls with zero arguments. + * + * The idea is that all syscalls externally have the same amount of arguments, + * but then by using some helper macros (see below) we can make actually + * implementing the syscall more intuitive and less noisy. + * + * @param name Name of syscall. + */ +#define SYSCALL_DECLARE0(name) \ + struct sys_ret sys_##name(sys_arg_t a, sys_arg_t b, \ + sys_arg_t c, \ + sys_arg_t d); + +/** + * Helper macro for declaring syscalls with one argument. + * + * @param name Name of syscall. + * @param a Name of argument. + */ +#define SYSCALL_DECLARE1(name, a) \ + struct sys_ret sys_##name(sys_arg_t a, sys_arg_t b, sys_arg_t c, \ + sys_arg_t d); + +/** + * Helper macro for declaring syscalls with two arguments. + * + * @param name Name of syscall. + * @param a Name of first argument. + * @param b Name of second argument. + */ +#define SYSCALL_DECLARE2(name, a, b) \ + struct sys_ret sys_##name(sys_arg_t a, sys_arg_t b, sys_arg_t c, \ + sys_arg_t d); + +/** + * Helper macro for declaring syscalls with three arguments. + * + * @param name Name of syscall. + * @param a Name of first argument. + * @param b Name of second argument. + * @param c Name of third argument. + */ +#define SYSCALL_DECLARE3(name, a, b, c) \ + struct sys_ret sys_##name(sys_arg_t a, sys_arg_t b, sys_arg_t c, \ + sys_arg_t d); + +/** + * Helper macro for declaring syscalls with four arguments. + * + * @param name Name of syscall. + * @param a Name of first argument. + * @param b Name of second argument. + * @param c Name of third argument. + * @param d Name of fourth argument. + */ +#define SYSCALL_DECLARE4(name, a, b, c, d) \ struct sys_ret sys_##name(sys_arg_t a, sys_arg_t b, sys_arg_t c, \ sys_arg_t d); +/** + * Helper macro for defining syscall with zero arguments. + * + * @param name Name of syscall. + */ #define SYSCALL_DEFINE0(name) \ static inline struct sys_ret __##name(); \ struct sys_ret sys_##name(sys_arg_t a, sys_arg_t b, sys_arg_t c, \ @@ -37,6 +114,11 @@ struct sys_ret { } \ static struct sys_ret __##name +/** + * Helper macro for defining syscall with one argument. + * + * @param name Name of syscall. + */ #define SYSCALL_DEFINE1(name) \ static inline struct sys_ret __##name(sys_arg_t); \ struct sys_ret sys_##name(sys_arg_t a, sys_arg_t b, sys_arg_t c, \ @@ -49,6 +131,11 @@ struct sys_ret { } \ static inline struct sys_ret __##name +/** + * Helper macro for defining syscall with two arguments. + * + * @param name Name of syscall. + */ #define SYSCALL_DEFINE2(name) \ static inline struct sys_ret __##name(sys_arg_t, sys_arg_t); \ struct sys_ret sys_##name(sys_arg_t a, sys_arg_t b, sys_arg_t c, \ @@ -60,6 +147,11 @@ struct sys_ret { } \ static inline struct sys_ret __##name +/** + * Helper macro for defining syscall with three arguments. + * + * @param name Name of syscall. + */ #define SYSCALL_DEFINE3(name) \ static inline struct sys_ret __##name(sys_arg_t, sys_arg_t, \ sys_arg_t); \ @@ -71,6 +163,11 @@ struct sys_ret { } \ static inline struct sys_ret __##name +/** + * Helper macro for defining syscall with four arguments. + * + * @param name Name of syscall. + */ #define SYSCALL_DEFINE4(name) \ static inline struct sys_ret __##name(sys_arg_t, sys_arg_t, sys_arg_t, \ sys_arg_t); \ @@ -81,40 +178,332 @@ struct sys_ret { } \ static inline struct sys_ret __##name -/* noop */ -SYSCALL_DECLARE(noop); +/** + * Noop syscall. + * + * @param a Unused. + * @param b Unused. + * @param c Unused. + * @param d Unused. + * @return \ref OK and 0. + */ +SYSCALL_DECLARE0(noop); + +/* @name Memory handling syscalls. */ +/** @{ */ +/** + * Request memory syscall. + * + * Allocates at least the specified size of allocation to current effective + * process. + * + * @param size Size of allocation. + * @param flags Flags of allocation. + * @param c Unused. + * @param d Unused. + * @return \ref OK and start of memory allocation. + */ +SYSCALL_DECLARE2(req_mem, size, flags); + +/** + * Request physical memory syscall. + * + * Allocates at least the specified size of allocation which includes the + * physical start address somewhere in the allocation to the current effective + * process. + * + * @param paddr Start of physical allocation. + * @param size Size of physical allocation. + * @param flags Flags of physical allocation. + * @param d Unused. + * @return \ref OK and start of memory allocation. + */ +SYSCALL_DECLARE3(req_pmem, paddr, size, flags); + +/** + * Request fixed memory syscall. + * + * Allocates at least the specified size of allocation which includes the start + * address of allocation to the current effective process. + * + * @param start Start of allocation. + * @param size Size of allocation. + * @param flags Flags of allocation. + * @param d Unused. + * @return \ref OK and start of memory allocation. + */ +SYSCALL_DECLARE3(req_fixmem, start, size, flags); + +/** + * Request shared memory syscall. + * + * Allocates a region that can be shared between different processes, that is at + * least the specified size of allocation. When clients are freeing memory, the + * underlying physical allocation will not be freed unless the owning reference + * (server) frees it. + * + * @param size Size of allocation. + * @param flags Flags of allocation. + * @param c Unused. + * @param d Unused. + * @return \ref OK and start of memory allocation. + */ +SYSCALL_DECLARE2(req_sharedmem, size, flags); + +/** + * Reference shared memory syscall. + * + * \see sys_req_sharedmem(). + * + * @param tid Thread ID of owner of shared memory. + * @param va Start address of shared memory. + * @param flags Flags to use for reference. + * @param d Unused. + * @return \ref OK and start of shared memory. + */ +SYSCALL_DECLARE3(ref_sharedmem, tid, va, flags); + +/** + * Free memory syscall. + * + * Frees the memory region pointed to. + * + * @param start Start of memory. + * @param b Unused. + * @param c Unused. + * @param d Unused. + * @return \ref OK and 0. + */ +SYSCALL_DECLARE1(free_mem, start); +/** @} */ + +/** @name Timer syscalls. */ +/** @{ */ +/** + * Get timer accuracy in Hertz syscall. + * + * @param a Unused. + * @param b Unused. + * @param c Unused. + * @param d Unused. + * @return \ref OK and frequency. + * \todo Should this be some kind of config request instead of a separate + * syscall? + */ +SYSCALL_DECLARE0(timebase); + +/** + * Request relative timer syscall. + * + * Request timer that triggers a number of ticks in the future. + * + * @param ticks Number of ticks from now. + * @param repeat Number of times to trigger. + * @param c Unused. + * @param d Unused. + * @return \ref OK and ID of timer. + */ +SYSCALL_DECLARE2(req_rel_timer, ticks, repeat); + +/** + * Request absolute timer syscall. + * + * Request timer that triggers at some absolute timepoint. + * + * @param ticks Timepoint. + * @param repeat Number of times to trigger. (What? Why is this here?). + * @param c Unused. + * @param d Unused. + * @return \ref OK and ID of timer. + * \todo Check repeat value. + */ +SYSCALL_DECLARE2(req_abs_timer, ticks, repeat); + +/** + * Free timer syscall. + * + * @param cid ID of timer to free. + * @param b Unused. + * @param c Unused. + * @param d Unused. + * @return \ref OK and 0. + */ +SYSCALL_DECLARE1(free_timer, cid); +/** @} */ + +/** @name IPC syscalls. */ +/** @{ */ +/** + * Report process status as server syscall. + * + * @param callback Callback to request handler. + * @param b Unused. + * @param c Unused. + * @param d Unused. + * @return \ref OK and 0. + */ +SYSCALL_DECLARE1(ipc_server, callback); + +/** + * Request syscall. + * + * @param pid Request target process. + * @param d0 First request argument. + * @param d1 Second request argument. + * @param d Unused. + * @return \c d0 and \c d1. + */ +SYSCALL_DECLARE3(ipc_req, pid, d0, d1); + +/** + * Forwarding syscall. + * + * In a server request handler, do a request to some other server on behalf of + * whoever called us up. + * + * @param pid Forwarding target process. + * @param d0 First forwarding argument. + * @param d1 Second forwarding argument. + * @param d Unused. + * @return \c d0 and \c d1. + */ +SYSCALL_DECLARE3(ipc_fwd, pid, d0, d1); + +/** + * Response syscall. + * + * @param d0 First response argument. + * @param d1 Second response argument. + * @param c Unused. + * @param d Unused. + * @return \c d0 and \c d1. + */ +SYSCALL_DECLARE2(ipc_resp, d0, d1); +/** @} */ + +/** @name Process handling syscalls. */ +/** @{ */ +/** + * Create thread syscall. + * + * Creates thread in current effective process context. + * + * @param a Unused. + * @param b Unused. + * @param c Unused. + * @param d Unused. + * @return \ref OK and 0. + * \todo Should this take stack size etc? + */ +SYSCALL_DECLARE0(create); + +/** + * Fork process syscall. + * + * Forks a process, much like in *nix systems. + * + * @param a Unused. + * @param b Unused. + * @param c Unused. + * @param d Unused. + * @return \ref OK and 0. + */ +SYSCALL_DECLARE0(fork); + +/** + * Execute binary syscall. + * + * Executes a new binary in existing process space. + * + * @param bin Address of binary. + * @param interp Optional address of interpreter. + * @param c Unused. + * @param d Unused. + * @return \ref OK and 0. + * \todo Check other return codes. + */ +SYSCALL_DECLARE2(exec, bin, interp); -/* memory */ -SYSCALL_DECLARE(req_mem); -SYSCALL_DECLARE(req_pmem); -SYSCALL_DECLARE(req_fixmem); -SYSCALL_DECLARE(req_sharedmem); -SYSCALL_DECLARE(free_mem); +/** + * Signal process syscall. + * + * @param tid Thread ID to signal. + * @param signal Signal to send. + * @param c Unused. + * @param d Unused. + * @return \ref OK and 0. + */ +SYSCALL_DECLARE2(signal, tid, signal); -/* timers */ -SYSCALL_DECLARE(timebase); -SYSCALL_DECLARE(req_rel_timer); -SYSCALL_DECLARE(req_abs_timer); -SYSCALL_DECLARE(free_timer); +/** + * Swap syscall. + * + * Swap currently running thread. + * + * @param tid Thread to swap to. + * @param b Unused. + * @param c Unused. + * @param d Unused. + * @return \ref OK and 0. + */ +SYSCALL_DECLARE1(swap, tid); +/** @} */ -/* ipc */ -SYSCALL_DECLARE(ipc_server); -SYSCALL_DECLARE(ipc_req); -SYSCALL_DECLARE(ipc_fwd); -SYSCALL_DECLARE(ipc_resp); +/** @name Configuration syscalls. */ +/** @{ */ +/** + * Set configuration syscall. + * + * Set some runtime parameter. + * + * @param param Parameter to set. + * @param val Value to set parameter to. + * @param c Unused. + * @param d Unused. + * @return \ref OK and 0. + */ +SYSCALL_DECLARE2(conf_set, param, val); -/* proc */ -SYSCALL_DECLARE(create); -SYSCALL_DECLARE(fork); -SYSCALL_DECLARE(exec); -SYSCALL_DECLARE(signal); -SYSCALL_DECLARE(swap); +/** + * Get configuration syscall. + * + * Get some runtime parameter. + * + * @param param Parameter to get. + * @param b Unused. + * @param c Unused. + * @param d Unused. + * @return \ref OK and 0. + */ +SYSCALL_DECLARE1(conf_get, param); -/* conf */ -SYSCALL_DECLARE(conf); -SYSCALL_DECLARE(poweroff); +/** + * Power off syscall. + * + * Either shut down or reboot system. + * + * @param type Type of shutdown. \see poweroff_type. + * @param b Unused. + * @param c Unused. + * @param d Unused. + * @return Shouldn't return at all. + */ +SYSCALL_DECLARE1(poweroff, type); +/** @} */ +/** + * Dispatch to correct syscall handler. + * + * @param syscall Syscall number. + * @param a Syscall argument 0. + * @param b Syscall argument 1. + * @param c Syscall argument 2. + * @param d Syscall argument 3. + * @return Whatever the specified syscall returns. + */ struct sys_ret syscall_dispatch(sys_arg_t syscall, sys_arg_t a, sys_arg_t b, sys_arg_t c, sys_arg_t d); +/** \todo Should I add variable names as well, to make the documentation a bit + * more readable? */ #endif /* APOS_UAPI_H */ |