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)

Detailed Description

User mode and Syscall APIs.

Macro Definition Documentation

◆ K_OOPS

#define K_OOPS ( expr )

#include <zephyr/internal/syscall_handler.h>

Value:

        do { \
                if (expr) { \
                        arch_syscall_oops(_current->syscall_frame); \
                } \
        } while (false)

Induce a kernel oops.

This macro can be used to induce a kernel oops which will kill the calling thread.

Parameters

expr	Expression to be evaluated

Note: This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ K_SYSCALL_DRIVER_OP

#define K_SYSCALL_DRIVER_OP	(	ptr,
		api_name,
		op
	)

#include <zephyr/internal/syscall_handler.h>

Value:

        ({ \
                struct api_name *__device__ = (struct api_name *) \
                        ((const struct device *)ptr)->api; \
                K_SYSCALL_VERIFY_MSG(__device__->op != NULL, \
                                    "Operation %s not defined for driver " \
                                    "instance %p", \
                                    # op, __device__); \
        })

Runtime check driver object pointer for presence of operation.

Validates if the driver object is capable of performing a certain operation.

Parameters

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)

Returns: 0 on success, nonzero on failure

Note: This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ K_SYSCALL_IS_OBJ

#define K_SYSCALL_IS_OBJ	(	ptr,
		type,
		init
	)

#include <zephyr/internal/syscall_handler.h>

Value:

        K_SYSCALL_VERIFY_MSG(k_object_validation_check(                 \
                                     k_object_find((const void *)ptr),  \
                                     (const void *)ptr,                 \
                                     type, init) == 0, "access denied")

◆ K_SYSCALL_MEMORY

#define K_SYSCALL_MEMORY	(	ptr,
		size,
		write
	)

#include <zephyr/internal/syscall_handler.h>

Value:

        K_SYSCALL_VERIFY_MSG(K_SYSCALL_MEMORY_SIZE_CHECK(ptr, size) \
                             && !Z_DETECT_POINTER_OVERFLOW(ptr, size) \
                             && (arch_buffer_validate((void *)ptr, size, write) \
                             == 0), \
                             "Memory region %p (size %zu) %s access denied", \
                             (void *)(ptr), (size_t)(size), \
                             write ? "write" : "read")

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.

Parameters

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

Returns: 0 on success, nonzero on failure

Note: This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ K_SYSCALL_MEMORY_ARRAY

#define K_SYSCALL_MEMORY_ARRAY	(	ptr,
		nmemb,
		size,
		write
	)

#include <zephyr/internal/syscall_handler.h>

Value:

        ({ \
                size_t product; \
                K_SYSCALL_VERIFY_MSG(!size_mul_overflow((size_t)(nmemb), \
                                                        (size_t)(size), \
                                                        &product), \
                                     "%zux%zu array is too large", \
                                     (size_t)(nmemb), (size_t)(size)) ||  \
                        K_SYSCALL_MEMORY(ptr, product, write); \
        })

◆ K_SYSCALL_MEMORY_ARRAY_READ

#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.

Parameters

ptr	Memory area to examine
nmemb	Number of elements in the array
size	Size of each array element

Returns: 0 on success, nonzero on failure

Note: This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ K_SYSCALL_MEMORY_ARRAY_WRITE

#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.

Parameters

ptr	Memory area to examine
nmemb	Number of elements in the array
size	Size of each array element

Returns: 0 on success, nonzero on failure

Note: This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ K_SYSCALL_MEMORY_READ

#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.

Parameters

ptr	Memory area to examine
size	Size of the memory area

Returns: 0 on success, nonzero on failure

Note: This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ K_SYSCALL_MEMORY_SIZE_CHECK

#define K_SYSCALL_MEMORY_SIZE_CHECK	(	ptr,
		size
	)	(((uintptr_t)(ptr) + (size)) >= (uintptr_t)(ptr))

#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.

Parameters

ptr	Memory area to examine
size	Size of the memory area

Returns: true if size is valid, false otherwise

Note: This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ K_SYSCALL_MEMORY_WRITE

#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.

Parameters

ptr	Memory area to examine
size	Size of the memory area

Returns: 0 on success, nonzero on failure

Note: This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ K_SYSCALL_OBJ

#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.

Parameters

ptr	Untrusted kernel object pointer
type	Expected kernel object type

Returns: 0 on success, nonzero on failure

Note: This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ K_SYSCALL_OBJ_INIT

#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.

Parameters

ptr	Untrusted kernel object pointer
type	Expected kernel object type

Returns: 0 on success, nonzero on failure

Note: This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ K_SYSCALL_OBJ_NEVER_INIT

#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.

Parameters

ptr	Untrusted kernel object pointer
type	Expected kernel object type

Returns: 0 on success, nonzero on failure

Note: This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ K_SYSCALL_SPECIFIC_DRIVER

#define K_SYSCALL_SPECIFIC_DRIVER	(	_device,
		_dtype,
		_api
	)

#include <zephyr/internal/syscall_handler.h>

Value:

        ({ \
                const struct device *_dev = (const struct device *)_device; \
                K_SYSCALL_OBJ(_dev, _dtype) || \
                        K_SYSCALL_VERIFY_MSG(_dev->api == _api, \
                                             "API structure mismatch"); \
        })

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.

Parameters

_device	Untrusted device pointer
_dtype	Expected kernel object type for the provided device pointer
_api	Expected driver API structure memory address

Returns: 0 on success, nonzero on failure

Note: This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ K_SYSCALL_VERIFY

#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.

Parameters

expr	Boolean expression to verify, a false result will trigger an oops. A stringified version of this expression will be printed.

Returns: 0 on success, nonzero on failure

Note: This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ K_SYSCALL_VERIFY_MSG

#define K_SYSCALL_VERIFY_MSG	(	expr,
		fmt,
		...
	)

#include <zephyr/internal/syscall_handler.h>

Value:

        ({ \
        bool expr_copy = !(expr); \
        if (expr_copy) { \
                TOOLCHAIN_IGNORE_WSHADOW_BEGIN \
                LOG_MODULE_DECLARE(os, CONFIG_KERNEL_LOG_LEVEL); \
                TOOLCHAIN_IGNORE_WSHADOW_END \
                LOG_ERR("syscall %s failed check: " fmt, \
                        __func__, ##__VA_ARGS__); \
        } \
        expr_copy; })

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.

Parameters

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

Returns: False on success, True on failure

Note: This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

Function Documentation

◆ k_is_in_user_syscall()

static bool k_is_in_user_syscall ( void )

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.

Note: This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

Returns: whether the current context is handling a syscall for a user mode thread

◆ k_object_dump_error()

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.

Parameters

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

Note: This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ k_object_find()

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

Parameters

obj	Address of kernel object to get metadata

Returns: Kernel object's metadata, or NULL if the parameter wasn't the memory address of a kernel object

Note: This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ k_object_recycle()

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.

Parameters

obj	Address of the kernel object

Note: This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ k_object_uninit()

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.

Parameters

obj	Address of the kernel object

Note: This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ k_object_validate()

int k_object_validate	(	struct k_object *	ko,
		enum k_objects	otype,
		enum _obj_init_check	init
	)

#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.

Parameters

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

Note: This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

Returns: 0 If the object is valid -EBADF if not a valid object of the specified type -EPERM If the caller does not have permissions -EINVAL Object is not initialized

◆ k_object_validation_check()

static int k_object_validation_check	(	struct k_object *	ko,
		const void *	obj,
		enum k_objects	otype,
		enum _obj_init_check	init
	)

inlinestatic

#include <zephyr/internal/syscall_handler.h>

◆ k_object_wordlist_foreach()

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.

Parameters

func	function to run on each struct k_object
context	Context pointer to pass to each invocation

Note: This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ k_thread_perms_all_clear()

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.

Note: Unlike k_thread_perms_clear(), this function will not clear permissions on public objects.; This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

Parameters

thread Thread object to revoke access

◆ k_thread_perms_clear()

void k_thread_perms_clear	(	struct k_object *	ko,
		struct k_thread *	thread
	)

#include <zephyr/internal/syscall_handler.h>

Revoke a thread's permission to a kernel object.

Parameters

ko	Kernel object metadata to update
thread	The thread to grant permission

Note: This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ k_thread_perms_inherit()

void k_thread_perms_inherit	(	struct k_thread *	parent,
		struct k_thread *	child
	)

#include <zephyr/internal/syscall_handler.h>

Copy all kernel object permissions from the parent to the child.

Parameters

parent	Parent thread, to get permissions from
child	Child thread, to copy permissions to

Note: This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ k_thread_perms_set()

void k_thread_perms_set	(	struct k_object *	ko,
		struct k_thread *	thread
	)

#include <zephyr/internal/syscall_handler.h>

Grant a thread permission to a kernel object.

Parameters

ko	Kernel object metadata to update
thread	The thread to grant permission

Note: This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ k_usermode_alloc_from_copy()

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.

Parameters

src	Source memory address
size	Size of the memory buffer

Returns: An allocated buffer with the data copied within it, or NULL if some error condition occurred

Note: This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ k_usermode_from_copy()

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.

Parameters

dst	Destination memory buffer
src	Source memory buffer, in userspace
size	Number of bytes to copy

Return values

0	On success
EFAULT	On memory access error

Note: This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ k_usermode_string_alloc_copy()

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.

Parameters

src	Source string pointer, in userspace
maxlen	Maximum size of the string including trailing NULL

Returns: The duplicated string, or NULL if an error occurred.

Note: This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ k_usermode_string_copy()

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.

Parameters

dst	Destination buffer
src	Source string pointer, in userspace
maxlen	Maximum size of the string including trailing NULL

Return values

0	on success
EINVAL	if the source string is too long with respect to maxlen
EFAULT	On memory access error

Note: This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ k_usermode_string_nlen()

static size_t k_usermode_string_nlen	(	const char *	src,
		size_t	maxlen,
		int *	err
	)

inlinestatic

#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.

Parameters

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

Returns: undefined on error, or strlen(src) if that is less than maxlen, or maxlen if there were no NULL terminating characters within the first maxlen bytes.

Note: This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ k_usermode_to_copy()

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.

Parameters

dst	Destination memory buffer, in userspace
src	Source memory buffer
size	Number of bytes to copy

Return values

0	On success
EFAULT	On memory access error

Note: This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ K_OOPS

◆ K_SYSCALL_DRIVER_OP

◆ K_SYSCALL_IS_OBJ

◆ K_SYSCALL_MEMORY

◆ K_SYSCALL_MEMORY_ARRAY

◆ K_SYSCALL_MEMORY_ARRAY_READ

◆ K_SYSCALL_MEMORY_ARRAY_WRITE

◆ K_SYSCALL_MEMORY_READ

◆ K_SYSCALL_MEMORY_SIZE_CHECK

◆ K_SYSCALL_MEMORY_WRITE

◆ K_SYSCALL_OBJ

◆ K_SYSCALL_OBJ_INIT

◆ K_SYSCALL_OBJ_NEVER_INIT

◆ K_SYSCALL_SPECIFIC_DRIVER

◆ K_SYSCALL_VERIFY

◆ K_SYSCALL_VERIFY_MSG

Function Documentation

◆ k_is_in_user_syscall()

◆ k_object_dump_error()

◆ k_object_find()

◆ k_object_recycle()

◆ k_object_uninit()

◆ k_object_validate()

◆ k_object_validation_check()

◆ k_object_wordlist_foreach()

◆ k_thread_perms_all_clear()

◆ k_thread_perms_clear()

◆ k_thread_perms_inherit()

◆ k_thread_perms_set()

◆ k_usermode_alloc_from_copy()

◆ k_usermode_from_copy()

◆ k_usermode_string_alloc_copy()

◆ k_usermode_string_copy()

◆ k_usermode_string_nlen()

◆ k_usermode_to_copy()