Zephyr API Documentation
3.7.0
A Scalable Open Source RTOS
|
User mode and Syscall APIs. More...
Macros | |
#define | K_OOPS(expr) |
Induce a kernel oops. | |
#define | K_SYSCALL_VERIFY_MSG(expr, fmt, ...) |
Runtime expression check for system call arguments. | |
#define | K_SYSCALL_VERIFY(expr) K_SYSCALL_VERIFY_MSG(expr, #expr) |
Runtime expression check for system call arguments. | |
#define | K_SYSCALL_MEMORY_SIZE_CHECK(ptr, size) (((uintptr_t)(ptr) + (size)) >= (uintptr_t)(ptr)) |
Macro to check if size is negative. | |
#define | K_SYSCALL_MEMORY(ptr, size, write) |
Runtime check that a user thread has read and/or write permission to a memory area. | |
#define | K_SYSCALL_MEMORY_READ(ptr, size) K_SYSCALL_MEMORY(ptr, size, 0) |
Runtime check that a user thread has read permission to a memory area. | |
#define | K_SYSCALL_MEMORY_WRITE(ptr, size) K_SYSCALL_MEMORY(ptr, size, 1) |
Runtime check that a user thread has write permission to a memory area. | |
#define | K_SYSCALL_MEMORY_ARRAY(ptr, nmemb, size, write) |
#define | K_SYSCALL_MEMORY_ARRAY_READ(ptr, nmemb, size) K_SYSCALL_MEMORY_ARRAY(ptr, nmemb, size, 0) |
Validate user thread has read permission for sized array. | |
#define | K_SYSCALL_MEMORY_ARRAY_WRITE(ptr, nmemb, size) K_SYSCALL_MEMORY_ARRAY(ptr, nmemb, size, 1) |
Validate user thread has read/write permission for sized array. | |
#define | K_SYSCALL_IS_OBJ(ptr, type, init) |
#define | K_SYSCALL_DRIVER_OP(ptr, api_name, op) |
Runtime check driver object pointer for presence of operation. | |
#define | K_SYSCALL_SPECIFIC_DRIVER(_device, _dtype, _api) |
Runtime check that device object is of a specific driver type. | |
#define | K_SYSCALL_OBJ(ptr, type) K_SYSCALL_IS_OBJ(ptr, type, _OBJ_INIT_TRUE) |
Runtime check kernel object pointer for non-init functions. | |
#define | K_SYSCALL_OBJ_INIT(ptr, type) K_SYSCALL_IS_OBJ(ptr, type, _OBJ_INIT_ANY) |
Runtime check kernel object pointer for non-init functions. | |
#define | K_SYSCALL_OBJ_NEVER_INIT(ptr, type) K_SYSCALL_IS_OBJ(ptr, type, _OBJ_INIT_FALSE) |
Runtime check kernel object pointer for non-init functions. | |
Functions | |
static bool | k_is_in_user_syscall (void) |
Return true if we are currently handling a system call from user mode. | |
int | k_object_validate (struct k_object *ko, enum k_objects otype, enum _obj_init_check init) |
Ensure a system object is a valid object of the expected type. | |
void | k_object_dump_error (int retval, const void *obj, struct k_object *ko, enum k_objects otype) |
Dump out error information on failed k_object_validate() call. | |
struct k_object * | k_object_find (const void *obj) |
Kernel object validation function. | |
void | k_object_wordlist_foreach (_wordlist_cb_func_t func, void *context) |
Iterate over all the kernel object metadata in the system. | |
void | k_thread_perms_inherit (struct k_thread *parent, struct k_thread *child) |
Copy all kernel object permissions from the parent to the child. | |
void | k_thread_perms_set (struct k_object *ko, struct k_thread *thread) |
Grant a thread permission to a kernel object. | |
void | k_thread_perms_clear (struct k_object *ko, struct k_thread *thread) |
Revoke a thread's permission to a kernel object. | |
void | k_thread_perms_all_clear (struct k_thread *thread) |
Revoke access to all objects for the provided thread. | |
void | k_object_uninit (const void *obj) |
Clear initialization state of a kernel object. | |
void | k_object_recycle (const void *obj) |
Initialize and reset permissions to only access by the caller. | |
static size_t | k_usermode_string_nlen (const char *src, size_t maxlen, int *err) |
Obtain the size of a C string passed from user mode. | |
void * | k_usermode_alloc_from_copy (const void *src, size_t size) |
Copy data from userspace into a resource pool allocation. | |
int | k_usermode_from_copy (void *dst, const void *src, size_t size) |
Copy data from user mode. | |
int | k_usermode_to_copy (void *dst, const void *src, size_t size) |
Copy data to user mode. | |
char * | k_usermode_string_alloc_copy (const char *src, size_t maxlen) |
Copy a C string from userspace into a resource pool allocation. | |
int | k_usermode_string_copy (char *dst, const char *src, size_t maxlen) |
Copy a C string from userspace into a provided buffer. | |
static int | k_object_validation_check (struct k_object *ko, const void *obj, enum k_objects otype, enum _obj_init_check init) |
User mode and Syscall APIs.
#define K_OOPS | ( | expr | ) |
#include <zephyr/internal/syscall_handler.h>
Induce a kernel oops.
This macro can be used to induce a kernel oops which will kill the calling thread.
expr | Expression to be evaluated |
#define K_SYSCALL_DRIVER_OP | ( | ptr, | |
api_name, | |||
op | |||
) |
#include <zephyr/internal/syscall_handler.h>
Runtime check driver object pointer for presence of operation.
Validates if the driver object is capable of performing a certain operation.
ptr | Untrusted device instance object pointer |
api_name | Name of the driver API struct (e.g. gpio_driver_api) |
op | Driver operation (e.g. manage_callback) |
#define K_SYSCALL_IS_OBJ | ( | ptr, | |
type, | |||
init | |||
) |
#include <zephyr/internal/syscall_handler.h>
#define K_SYSCALL_MEMORY | ( | ptr, | |
size, | |||
write | |||
) |
#include <zephyr/internal/syscall_handler.h>
Runtime check that a user thread has read and/or write permission to a memory area.
Checks that the particular memory area is readable and/or writeable by the currently running thread if the CPU was in user mode, and generates a kernel oops if it wasn't. Prevents userspace from getting the kernel to read and/or modify memory the thread does not have access to, or passing in garbage pointers that would crash/pagefault the kernel if dereferenced.
ptr | Memory area to examine |
size | Size of the memory area |
write | If the thread should be able to write to this memory, not just read it |
#define K_SYSCALL_MEMORY_ARRAY | ( | ptr, | |
nmemb, | |||
size, | |||
write | |||
) |
#include <zephyr/internal/syscall_handler.h>
#define K_SYSCALL_MEMORY_ARRAY_READ | ( | ptr, | |
nmemb, | |||
size | |||
) | K_SYSCALL_MEMORY_ARRAY(ptr, nmemb, size, 0) |
#include <zephyr/internal/syscall_handler.h>
Validate user thread has read permission for sized array.
Used when the memory region is expressed in terms of number of elements and each element size, handles any overflow issues with computing the total array bounds. Otherwise see _SYSCALL_MEMORY_READ.
ptr | Memory area to examine |
nmemb | Number of elements in the array |
size | Size of each array element |
#define K_SYSCALL_MEMORY_ARRAY_WRITE | ( | ptr, | |
nmemb, | |||
size | |||
) | K_SYSCALL_MEMORY_ARRAY(ptr, nmemb, size, 1) |
#include <zephyr/internal/syscall_handler.h>
Validate user thread has read/write permission for sized array.
Used when the memory region is expressed in terms of number of elements and each element size, handles any overflow issues with computing the total array bounds. Otherwise see _SYSCALL_MEMORY_WRITE.
ptr | Memory area to examine |
nmemb | Number of elements in the array |
size | Size of each array element |
#define K_SYSCALL_MEMORY_READ | ( | ptr, | |
size | |||
) | K_SYSCALL_MEMORY(ptr, size, 0) |
#include <zephyr/internal/syscall_handler.h>
Runtime check that a user thread has read permission to a memory area.
Checks that the particular memory area is readable by the currently running thread if the CPU was in user mode, and generates a kernel oops if it wasn't. Prevents userspace from getting the kernel to read memory the thread does not have access to, or passing in garbage pointers that would crash/pagefault the kernel if dereferenced.
ptr | Memory area to examine |
size | Size of the memory area |
#include <zephyr/internal/syscall_handler.h>
Macro to check if size is negative.
K_SYSCALL_MEMORY can be called with signed/unsigned types and because of that if we check if size is greater or equal to zero, many static analyzers complain about no effect expression.
ptr | Memory area to examine |
size | Size of the memory area |
#define K_SYSCALL_MEMORY_WRITE | ( | ptr, | |
size | |||
) | K_SYSCALL_MEMORY(ptr, size, 1) |
#include <zephyr/internal/syscall_handler.h>
Runtime check that a user thread has write permission to a memory area.
Checks that the particular memory area is readable and writable by the currently running thread if the CPU was in user mode, and generates a kernel oops if it wasn't. Prevents userspace from getting the kernel to read or modify memory the thread does not have access to, or passing in garbage pointers that would crash/pagefault the kernel if dereferenced.
ptr | Memory area to examine |
size | Size of the memory area |
#define K_SYSCALL_OBJ | ( | ptr, | |
type | |||
) | K_SYSCALL_IS_OBJ(ptr, type, _OBJ_INIT_TRUE) |
#include <zephyr/internal/syscall_handler.h>
Runtime check kernel object pointer for non-init functions.
Calls k_object_validate and triggers a kernel oops if the check fails. For use in system call handlers which are not init functions; a fatal error will occur if the object is not initialized.
ptr | Untrusted kernel object pointer |
type | Expected kernel object type |
#define K_SYSCALL_OBJ_INIT | ( | ptr, | |
type | |||
) | K_SYSCALL_IS_OBJ(ptr, type, _OBJ_INIT_ANY) |
#include <zephyr/internal/syscall_handler.h>
Runtime check kernel object pointer for non-init functions.
See description of _SYSCALL_IS_OBJ. No initialization checks are done. Intended for init functions where objects may be re-initialized at will.
ptr | Untrusted kernel object pointer |
type | Expected kernel object type |
#define K_SYSCALL_OBJ_NEVER_INIT | ( | ptr, | |
type | |||
) | K_SYSCALL_IS_OBJ(ptr, type, _OBJ_INIT_FALSE) |
#include <zephyr/internal/syscall_handler.h>
Runtime check kernel object pointer for non-init functions.
See description of _SYSCALL_IS_OBJ. Triggers a fatal error if the object is initialized. Intended for init functions where objects, once initialized, can only be re-used when their initialization state expires due to some other mechanism.
ptr | Untrusted kernel object pointer |
type | Expected kernel object type |
#define K_SYSCALL_SPECIFIC_DRIVER | ( | _device, | |
_dtype, | |||
_api | |||
) |
#include <zephyr/internal/syscall_handler.h>
Runtime check that device object is of a specific driver type.
Checks that the driver object passed in is initialized, the caller has correct permissions, and that it belongs to the specified driver subsystems. Additionally, all devices store a structure pointer of the driver's API. If this doesn't match the value provided, the check will fail.
This provides an easy way to determine if a device object not only belongs to a particular subsystem, but is of a specific device driver implementation. Useful for defining out-of-subsystem system calls which are implemented for only one driver.
_device | Untrusted device pointer |
_dtype | Expected kernel object type for the provided device pointer |
_api | Expected driver API structure memory address |
#define K_SYSCALL_VERIFY | ( | expr | ) | K_SYSCALL_VERIFY_MSG(expr, #expr) |
#include <zephyr/internal/syscall_handler.h>
Runtime expression check for system call arguments.
Used in handler functions to perform various runtime checks on arguments, and generate a kernel oops if anything is not expected.
expr | Boolean expression to verify, a false result will trigger an oops. A stringified version of this expression will be printed. |
#define K_SYSCALL_VERIFY_MSG | ( | expr, | |
fmt, | |||
... | |||
) |
#include <zephyr/internal/syscall_handler.h>
Runtime expression check for system call arguments.
Used in handler functions to perform various runtime checks on arguments, and generate a kernel oops if anything is not expected, printing a custom message.
expr | Boolean expression to verify, a false result will trigger an oops |
fmt | Printf-style format string (followed by appropriate variadic arguments) to print on verification failure |
|
inlinestatic |
#include <zephyr/internal/syscall_handler.h>
Return true if we are currently handling a system call from user mode.
Inside z_vrfy functions, we always know that we are handling a system call invoked from user context.
However, some checks that are only relevant to user mode must instead be placed deeper within the implementation. This API is useful to conditionally make these checks.
For performance reasons, whenever possible, checks should be placed in the relevant z_vrfy function since these are completely skipped when a syscall is invoked.
This will return true only if we are handling a syscall for a user thread. If the system call was invoked from supervisor mode, or we are not handling a system call, this will return false.
void k_object_dump_error | ( | int | retval, |
const void * | obj, | ||
struct k_object * | ko, | ||
enum k_objects | otype | ||
) |
#include <zephyr/internal/syscall_handler.h>
Dump out error information on failed k_object_validate() call.
retval | Return value from k_object_validate() |
obj | Kernel object we were trying to verify |
ko | If retval=-EPERM, struct k_object * that was looked up, or NULL |
otype | Expected type of the kernel object |
struct k_object * k_object_find | ( | const void * | obj | ) |
#include <zephyr/internal/syscall_handler.h>
Kernel object validation function.
Retrieve metadata for a kernel object. This function is implemented in the gperf script footer, see gen_kobject_list.py
obj | Address of kernel object to get metadata |
void k_object_recycle | ( | const void * | obj | ) |
#include <zephyr/internal/syscall_handler.h>
Initialize and reset permissions to only access by the caller.
Intended for scenarios where objects are fetched from slab pools and may have had different permissions set during prior usage.
This is only intended for pools of objects, where such objects are acquired and released to the pool. If an object has already been used, we do not want stale permission information hanging around, the object should only have permissions on the caller. Objects which are not managed by a pool-like mechanism should not use this API.
The object will be marked as initialized and the calling thread granted access to it.
obj | Address of the kernel object |
void k_object_uninit | ( | const void * | obj | ) |
#include <zephyr/internal/syscall_handler.h>
Clear initialization state of a kernel object.
Intended for thread objects upon thread exit, or for other kernel objects that were released back to an object pool.
obj | Address of the kernel object |
#include <zephyr/internal/syscall_handler.h>
Ensure a system object is a valid object of the expected type.
Searches for the object and ensures that it is indeed an object of the expected type, that the caller has the right permissions on it, and that the object has been initialized.
This function is intended to be called on the kernel-side system call handlers to validate kernel object pointers passed in from userspace.
ko | Kernel object metadata pointer, or NULL |
otype | Expected type of the kernel object, or K_OBJ_ANY if type doesn't matter |
init | Indicate whether the object needs to already be in initialized or uninitialized state, or that we don't care |
|
inlinestatic |
#include <zephyr/internal/syscall_handler.h>
void k_object_wordlist_foreach | ( | _wordlist_cb_func_t | func, |
void * | context | ||
) |
#include <zephyr/internal/syscall_handler.h>
Iterate over all the kernel object metadata in the system.
func | function to run on each struct k_object |
context | Context pointer to pass to each invocation |
void k_thread_perms_all_clear | ( | struct k_thread * | thread | ) |
#include <zephyr/internal/syscall_handler.h>
Revoke access to all objects for the provided thread.
thread | Thread object to revoke access |
#include <zephyr/internal/syscall_handler.h>
Revoke a thread's permission to a kernel object.
ko | Kernel object metadata to update |
thread | The thread to grant permission |
#include <zephyr/internal/syscall_handler.h>
Copy all kernel object permissions from the parent to the child.
parent | Parent thread, to get permissions from |
child | Child thread, to copy permissions to |
#include <zephyr/internal/syscall_handler.h>
Grant a thread permission to a kernel object.
ko | Kernel object metadata to update |
thread | The thread to grant permission |
void * k_usermode_alloc_from_copy | ( | const void * | src, |
size_t | size | ||
) |
#include <zephyr/internal/syscall_handler.h>
Copy data from userspace into a resource pool allocation.
Given a pointer and a size, allocate a similarly sized buffer in the caller's resource pool and copy all the data within it to the newly allocated buffer. This will need to be freed later with k_free().
Checks are done to ensure that the current thread would have read access to the provided buffer.
src | Source memory address |
size | Size of the memory buffer |
int k_usermode_from_copy | ( | void * | dst, |
const void * | src, | ||
size_t | size | ||
) |
#include <zephyr/internal/syscall_handler.h>
Copy data from user mode.
Given a userspace pointer and a size, copies data from it into a provided destination buffer, performing checks to ensure that the caller would have appropriate access when in user mode.
dst | Destination memory buffer |
src | Source memory buffer, in userspace |
size | Number of bytes to copy |
0 | On success |
EFAULT | On memory access error |
char * k_usermode_string_alloc_copy | ( | const char * | src, |
size_t | maxlen | ||
) |
#include <zephyr/internal/syscall_handler.h>
Copy a C string from userspace into a resource pool allocation.
Given a C string and maximum length, duplicate the string using an allocation from the calling thread's resource pool. This will need to be freed later with k_free().
Checks are performed to ensure that the string is valid memory and that the caller has access to it in user mode.
src | Source string pointer, in userspace |
maxlen | Maximum size of the string including trailing NULL |
int k_usermode_string_copy | ( | char * | dst, |
const char * | src, | ||
size_t | maxlen | ||
) |
#include <zephyr/internal/syscall_handler.h>
Copy a C string from userspace into a provided buffer.
Given a C string and maximum length, copy the string into a buffer.
Checks are performed to ensure that the string is valid memory and that the caller has access to it in user mode.
dst | Destination buffer |
src | Source string pointer, in userspace |
maxlen | Maximum size of the string including trailing NULL |
0 | on success |
EINVAL | if the source string is too long with respect to maxlen |
EFAULT | On memory access error |
#include <zephyr/internal/syscall_handler.h>
Obtain the size of a C string passed from user mode.
Given a C string pointer and a maximum size, obtain the true size of the string (not including the trailing NULL byte) just as if calling strnlen() on it, with the same semantics of strnlen() with respect to the return value and the maxlen parameter.
Any memory protection faults triggered by the examination of the string will be safely handled and an error code returned.
NOTE: Doesn't guarantee that user mode has actual access to this string, you will need to still do a K_SYSCALL_MEMORY_READ() with the obtained size value to guarantee this.
src | String to measure size of |
maxlen | Maximum number of characters to examine |
err | Pointer to int, filled in with -1 on memory error, 0 on success |
int k_usermode_to_copy | ( | void * | dst, |
const void * | src, | ||
size_t | size | ||
) |
#include <zephyr/internal/syscall_handler.h>
Copy data to user mode.
Given a userspace pointer and a size, copies data to it from a provided source buffer, performing checks to ensure that the caller would have appropriate access when in user mode.
dst | Destination memory buffer, in userspace |
src | Source memory buffer |
size | Number of bytes to copy |
0 | On success |
EFAULT | On memory access error |