Zephyr API Documentation  3.7.0-rc3
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
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 }; \
_CONCAT(_object_access_, name_)) = \
{ (&_k_thread_obj_ ## name_), \
(_CONCAT(_object_list_, name_)) }
#define STRUCT_SECTION_ITERABLE(struct_type, varname)
Defines a new element for an iterable section.
Definition: iterable_sections.h:216
Definition: kobject_internal.h:69

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
objectAddress 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
objectAddress of kernel object
threadThread 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
objectAddress of kernel object
threadThread 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
otypeRequested 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
otypeRequested kernel object type
sizeRequested 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
objPointer 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
objAddress of the kernel object
otypeObject 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
objectThe object to be released