User Mode APIs

Macros
#define	K_THREAD_ACCESS_GRANT(name_, ...)
	Grant a static thread access to a list of kernel objects.
#define	K_OBJ_FLAG_INITIALIZED   BIT(0)
	Object initialized.
#define	K_OBJ_FLAG_PUBLIC   BIT(1)
	Object is Public.
#define	K_OBJ_FLAG_ALLOC   BIT(2)
	Object allocated.
#define	K_OBJ_FLAG_DRIVER   BIT(3)
	Driver Object.

Functions
void	k_object_access_grant (const void *object, struct k_thread *thread)
	Grant a thread access to a kernel object.
void	k_object_access_revoke (const void *object, struct k_thread *thread)
	Revoke a thread's access to a kernel object.
void	k_object_release (const void *object)
	Release an object.
void	k_object_access_all_grant (const void *object)
	Grant all present and future threads access to an object.
bool	k_object_is_valid (const void *obj, enum k_objects otype)
	Check if a kernel object is of certain type and is valid.
void *	k_object_alloc (enum k_objects otype)
	Allocate a kernel object of a designated type.
void *	k_object_alloc_size (enum k_objects otype, size_t size)
	Allocate a kernel object of a designated type and a given size.
void	k_object_free (void *obj)
	Free a kernel object previously allocated with k_object_alloc()

Detailed Description

Macro Definition Documentation

K_OBJ_FLAG_ALLOC

#define K_OBJ_FLAG_ALLOC   BIT(2)

#include <zephyr/sys/kobject.h>

Object allocated.

K_OBJ_FLAG_DRIVER

#define K_OBJ_FLAG_DRIVER   BIT(3)

#include <zephyr/sys/kobject.h>

Driver Object.

K_OBJ_FLAG_INITIALIZED

#define K_OBJ_FLAG_INITIALIZED   BIT(0)

#include <zephyr/sys/kobject.h>

Object initialized.

K_OBJ_FLAG_PUBLIC

#define K_OBJ_FLAG_PUBLIC   BIT(1)

#include <zephyr/sys/kobject.h>

Object is Public.

K_THREAD_ACCESS_GRANT

#define K_THREAD_ACCESS_GRANT	(		name_,
			... )

#include <zephyr/sys/kobject.h>

Value:

        static void * const _CONCAT(_object_list_, name_)[] = \
                { __VA_ARGS__, NULL }; \
        static const STRUCT_SECTION_ITERABLE(k_object_assignment, \
                                        _CONCAT(_object_access_, name_)) = \
                        { (&_k_thread_obj_ ## name_), \
                          (_CONCAT(_object_list_, name_)) }

Grant a static thread access to a list of kernel objects.

For threads declared with K_THREAD_DEFINE(), grant the thread access to a set of kernel objects. These objects do not need to be in an initialized state. The permissions will be granted when the threads are initialized in the early boot sequence.

All arguments beyond the first must be pointers to kernel objects.

Parameters

name_

Name of the thread, as passed to K_THREAD_DEFINE()

Function Documentation

k_object_access_all_grant()

void k_object_access_all_grant

(

const void *

object

)

#include <zephyr/sys/kobject.h>

Grant all present and future threads access to an object.

If the caller is from supervisor mode, or the caller is from user mode and have sufficient permissions on the object, then that object will have permissions granted to it for all current and future threads running in the system, effectively becoming a public kernel object.

Use of this API should be avoided on systems that are running untrusted code as it is possible for such code to derive the addresses of kernel objects and perform unwanted operations on them.

It is not possible to revoke permissions on public objects; once public, any thread may use it.

Parameters

object

Address of kernel object

k_object_access_grant()

void k_object_access_grant	(	const void *	object,
		struct k_thread *	thread )

#include <zephyr/sys/kobject.h>

Grant a thread access to a kernel object.

The thread will be granted access to the object if the caller is from supervisor mode, or the caller is from user mode AND has permissions on both the object and the thread whose access is being granted.

Parameters

object	Address of kernel object
thread	Thread to grant access to the object

k_object_access_revoke()

void k_object_access_revoke	(	const void *	object,
		struct k_thread *	thread )

#include <zephyr/sys/kobject.h>

Revoke a thread's access to a kernel object.

The thread will lose access to the object if the caller is from supervisor mode, or the caller is from user mode AND has permissions on both the object and the thread whose access is being revoked.

Parameters

object	Address of kernel object
thread	Thread to remove access to the object

k_object_alloc()

void * k_object_alloc

(

enum k_objects

otype

)

#include <zephyr/sys/kobject.h>

Allocate a kernel object of a designated type.

This will instantiate at runtime a kernel object of the specified type, returning a pointer to it. The object will be returned in an uninitialized state, with the calling thread being granted permission on it. The memory for the object will be allocated out of the calling thread's resource pool.

Note

This function is available only if

CONFIG_DYNAMIC_OBJECTS 

is selected.

Thread stack object has to use k_object_alloc_size() since stacks may have different sizes.

Parameters

otype

Requested kernel object type

Returns

A pointer to the allocated kernel object, or NULL if memory wasn't available

k_object_alloc_size()

void * k_object_alloc_size	(	enum k_objects	otype,
		size_t	size )

#include <zephyr/sys/kobject.h>

Allocate a kernel object of a designated type and a given size.

This will instantiate at runtime a kernel object of the specified type, returning a pointer to it. The object will be returned in an uninitialized state, with the calling thread being granted permission on it. The memory for the object will be allocated out of the calling thread's resource pool.

This function is specially helpful for thread stack objects because their sizes can vary. Other objects should probably look k_object_alloc().

Note

This function is available only if

CONFIG_DYNAMIC_OBJECTS 

is selected.

Parameters

otype	Requested kernel object type
size	Requested kernel object size

Returns

A pointer to the allocated kernel object, or NULL if memory wasn't available

k_object_free()

void k_object_free

(

void *

obj

)

#include <zephyr/sys/kobject.h>

Free a kernel object previously allocated with k_object_alloc()

This will return memory for a kernel object back to resource pool it was allocated from. Care must be exercised that the object will not be used during or after when this call is made.

Note

This function is available only if

CONFIG_DYNAMIC_OBJECTS 

is selected.

Parameters

obj	Pointer to the kernel object memory address.

k_object_is_valid()

bool k_object_is_valid	(	const void *	obj,
		enum k_objects	otype )

#include <zephyr/sys/kobject.h>

Check if a kernel object is of certain type and is valid.

This checks if the kernel object exists, of certain type, and has been initialized.

Parameters

obj	Address of the kernel object
otype	Object type (use K_OBJ_ANY for ignoring type checking)

Returns

True if kernel object (obj) exists, of certain type, and has been initialized. False otherwise.

k_object_release()

void k_object_release

(

const void *

object

)

#include <zephyr/sys/kobject.h>

Release an object.

Allows user threads to drop their own permission on an object Their permissions are automatically cleared when a thread terminates.

Parameters

object

The object to be released