michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: usermode: fix terminology

Browse source 
Handler functions are now referred to as verification functions,
update documentation to reflect this.

Signed-off-by: Andrew Boie <andrew.p.boie@intel.com>
This commit is contained in:
Andrew Boie 2020-03-31 14:24:52 -07:00 • committed by Anas Nashif
commit 68a2fe8262
1 changed files with 25 additions and 24 deletions
Download patch file Download diff file Expand all files Collapse all files

49
doc/reference/usermode/syscalls.rst
View file

@ -73,12 +73,12 @@ limitations:
* :c:macro:`__syscall` must be the first thing in the prototype. * :c:macro:`__syscall` must be the first thing in the prototype.
The preprocessor is intentionally not used when determining the set of The preprocessor is intentionally not used when determining the set of system
system calls to generate. However, any generated system calls that don't calls to generate. However, any generated system calls that don't actually have
actually have a handler function defined (because the related feature is not a verification function defined (because the related feature is not enabled in
enabled in the kernel configuration) will instead point to a special handler the kernel configuration) will instead point to a special verification for
for unimplemented system calls. Data type definitions for APIs should not unimplemented system calls. Data type definitions for APIs should not have
have conditional visibility to the compiler. conditional visibility to the compiler.
Any header file that declares system calls must include a special generated Any header file that declares system calls must include a special generated
header at the very bottom of the header file. This header follows the header at the very bottom of the header file. This header follows the
@ -138,11 +138,11 @@ the project out directory under ``include/generated/``:
* An entry for the system call is created in the dispatch table * An entry for the system call is created in the dispatch table
``_k_sycall_table``, expressed in ``include/generated/syscall_dispatch.c`` ``_k_sycall_table``, expressed in ``include/generated/syscall_dispatch.c``
* A weak handler function is declared, which is just an alias of the * A weak verification function is declared, which is just an alias of the
'unimplemented system call' handler. This is necessary since the real 'unimplemented system call' verifier. This is necessary since the real
handler function may or may not be built depending on the kernel verification function may or may not be built depending on the kernel
configuration. For example, if a user thread makes a sensor subsystem configuration. For example, if a user thread makes a sensor subsystem
API call, but the sensor subsystem is not enabled, the weak handler API call, but the sensor subsystem is not enabled, the weak verifier
will be invoked instead. will be invoked instead.
* An unmarshalling function is defined in ``include/generated/<name>_mrsh.c`` * An unmarshalling function is defined in ``include/generated/<name>_mrsh.c``
@ -191,7 +191,7 @@ Some system calls may have more than six arguments. The number of
arguments passed via registers is limited to six for all arguments passed via registers is limited to six for all
architectures. Additional arguments will need to be passed in an array architectures. Additional arguments will need to be passed in an array
in the source memory space, which needs to be treated as untrusted in the source memory space, which needs to be treated as untrusted
memory in the handler function. This code (packing, unpacking and memory in the verification function. This code (packing, unpacking and
validation) is generated automatically as needed in the stub above and validation) is generated automatically as needed in the stub above and
in the unmarshalling function. in the unmarshalling function.
@ -215,20 +215,21 @@ declared in the same header as the API as a static inline function or
declared in some C file. There is no prototype needed for implementation declared in some C file. There is no prototype needed for implementation
functions, these are automatically generated. functions, these are automatically generated.
Handler Function Verification Function
**************** *********************
The handler function runs on the kernel side when a user thread makes The verification function runs on the kernel side when a user thread makes
a system call. When the user thread makes a software interrupt to elevate to a system call. When the user thread makes a software interrupt to elevate to
supervisor mode, the common system call entry point uses the system call ID supervisor mode, the common system call entry point uses the system call ID
provided by the user to look up the appropriate handler function for that provided by the user to look up the appropriate unmarshalling function for that
system call and jump into it. system call and jump into it. This in turn calls the verification function.
Handler functions only run when system call APIs are invoked from user mode. Verification and unmarshalling functions only run when system call APIs are
If an API is invoked from supervisor mode, the implementation is simply called. invoked from user mode. If an API is invoked from supervisor mode, the
implementation is simply called and there is no software trap.
The purpose of the handler function is to validate all the arguments passed in. The purpose of the verification function is to validate all the arguments
This includes: passed in. This includes:
* Any kernel object pointers provided. For example, the semaphore APIs must * Any kernel object pointers provided. For example, the semaphore APIs must
ensure that the semaphore object passed in is a valid semaphore and that ensure that the semaphore object passed in is a valid semaphore and that
@ -239,9 +240,9 @@ This includes:
* Any other arguments that have a limited range of valid values. * Any other arguments that have a limited range of valid values.
Handler functions involve a great deal of boilerplate code which has been Verification functions involve a great deal of boilerplate code which has been
made simpler by some macros in ``kernel/include/syscall_handlers.h``. made simpler by some macros in ``kernel/include/syscall_handlers.h``.
Handler functions should be declared using these macros. Verification functions should be declared using these macros.
Argument Validation Argument Validation
=================== ===================
@ -254,7 +255,7 @@ Several macros exist to validate arguments:
* :c:macro:`Z_SYSCALL_OBJ_INIT()` is the same as * :c:macro:`Z_SYSCALL_OBJ_INIT()` is the same as
:c:macro:`Z_SYSCALL_OBJ()`, except that the provided object may be :c:macro:`Z_SYSCALL_OBJ()`, except that the provided object may be
uninitialized. This is useful for handlers of object init functions. uninitialized. This is useful for verifiers of object init functions.
* :c:macro:`Z_SYSCALL_OBJ_NEVER_INIT()` is the same as * :c:macro:`Z_SYSCALL_OBJ_NEVER_INIT()` is the same as
:c:macro:`Z_SYSCALL_OBJ()`, except that the provided object must be :c:macro:`Z_SYSCALL_OBJ()`, except that the provided object must be
@ -406,7 +407,7 @@ Related configuration options:
APIs APIs
**** ****
Helper macros for creating system call handlers are provided in Helper macros for creating system call verification functions are provided in
:zephyr_file:`kernel/include/syscall_handler.h`: :zephyr_file:`kernel/include/syscall_handler.h`:
* :c:macro:`Z_SYSCALL_OBJ()` * :c:macro:`Z_SYSCALL_OBJ()`