Object Core APIs

Data Structures
struct	k_obj_core_stats_desc
	Object core statistics descriptor. More...
struct	k_obj_range
	Contiguous range of permanent objects of one type. More...
struct	k_obj_type
	Object type structure. More...
struct	k_obj_core
	Object core structure. More...

Macros
#define	K_OBJ_CORE(kobj)
	Convert kernel object pointer into its object core pointer.
#define	K_OBJ_TYPE_ID_GEN(s)
	Generate new object type IDs based on a 4 letter string.
#define	K_OBJ_TYPE_CONDVAR_ID   K_OBJ_TYPE_ID_GEN("COND")
	Condition variable object type.
#define	K_OBJ_TYPE_CPU_ID   K_OBJ_TYPE_ID_GEN("CPU_")
	CPU object type.
#define	K_OBJ_TYPE_EVENT_ID   K_OBJ_TYPE_ID_GEN("EVNT")
	Event object type.
#define	K_OBJ_TYPE_FIFO_ID   K_OBJ_TYPE_ID_GEN("FIFO")
	FIFO object type.
#define	K_OBJ_TYPE_KERNEL_ID   K_OBJ_TYPE_ID_GEN("KRNL")
	Kernel object type.
#define	K_OBJ_TYPE_LIFO_ID   K_OBJ_TYPE_ID_GEN("LIFO")
	LIFO object type.
#define	K_OBJ_TYPE_MEM_BLOCK_ID   K_OBJ_TYPE_ID_GEN("MBLK")
	Memory block object type.
#define	K_OBJ_TYPE_MBOX_ID   K_OBJ_TYPE_ID_GEN("MBOX")
	Mailbox object type.
#define	K_OBJ_TYPE_MEM_SLAB_ID   K_OBJ_TYPE_ID_GEN("SLAB")
	Memory slab object type.
#define	K_OBJ_TYPE_MSGQ_ID   K_OBJ_TYPE_ID_GEN("MSGQ")
	Message queue object type.
#define	K_OBJ_TYPE_MUTEX_ID   K_OBJ_TYPE_ID_GEN("MUTX")
	Mutex object type.
#define	K_OBJ_TYPE_PIPE_ID   K_OBJ_TYPE_ID_GEN("PIPE")
	Pipe object type.
#define	K_OBJ_TYPE_QUEUE_ID   K_OBJ_TYPE_ID_GEN("QUEU")
	Queue object type.
#define	K_OBJ_TYPE_SEM_ID   K_OBJ_TYPE_ID_GEN("SEM4")
	Semaphore object type.
#define	K_OBJ_TYPE_STACK_ID   K_OBJ_TYPE_ID_GEN("STCK")
	Stack object type.
#define	K_OBJ_TYPE_THREAD_ID   K_OBJ_TYPE_ID_GEN("THRD")
	Thread object type.
#define	K_OBJ_TYPE_TIMER_ID   K_OBJ_TYPE_ID_GEN("TIMR")
	Timer object type.
#define	K_OBJ_TYPE_MAX_RANGES   3
	Maximum number of permanent object ranges of an object type.

Functions
void	k_obj_type_init_range (struct k_obj_type *type, const void *start, const void *end, size_t stride, bool indirect)
	Register the permanent objects of an object type.
struct k_obj_type *	k_obj_type_find (uint32_t type_id)
	Find a specific object type by ID.
int	k_obj_type_walk_locked (struct k_obj_type *type, int(*func)(struct k_obj_core *obj_core, void *data), void *data)
	Walk the object cores of an object type.
int	k_obj_type_walk_unlocked (struct k_obj_type *type, int(*func)(struct k_obj_core *obj_core, void *data), void *data)
	Walk the object cores of an object type.
void	k_obj_core_init (struct k_obj_core *obj_core, struct k_obj_type *type)
	Initialize the core of the kernel object.
void	k_obj_core_link (struct k_obj_core *obj_core)
	Register the kernel object with its object type.
void	k_obj_core_init_and_link (struct k_obj_core *obj_core, struct k_obj_type *type)
	Automatically link the kernel object after initializing it.
void	k_obj_core_unlink (struct k_obj_core *obj_core)
	Unregister the kernel object from its object type.
void	k_obj_core_evict_range (const void *addr, size_t len)
	Unregister every kernel object located in a memory range.

Detailed Description

Macro Definition Documentation

K_OBJ_CORE

#define K_OBJ_CORE

(

kobj

)

#include <zephyr/kernel/obj_core.h>

Value:

(&((kobj)->obj_core))

Convert kernel object pointer into its object core pointer.

K_OBJ_TYPE_CONDVAR_ID

#define K_OBJ_TYPE_CONDVAR_ID   K_OBJ_TYPE_ID_GEN("COND")

#include <zephyr/kernel/obj_core.h>

Condition variable object type.

K_OBJ_TYPE_CPU_ID

#define K_OBJ_TYPE_CPU_ID   K_OBJ_TYPE_ID_GEN("CPU_")

#include <zephyr/kernel/obj_core.h>

CPU object type.

K_OBJ_TYPE_EVENT_ID

#define K_OBJ_TYPE_EVENT_ID   K_OBJ_TYPE_ID_GEN("EVNT")

#include <zephyr/kernel/obj_core.h>

Event object type.

K_OBJ_TYPE_FIFO_ID

#define K_OBJ_TYPE_FIFO_ID   K_OBJ_TYPE_ID_GEN("FIFO")

#include <zephyr/kernel/obj_core.h>

FIFO object type.

K_OBJ_TYPE_ID_GEN

#define K_OBJ_TYPE_ID_GEN

(

s

)

#include <zephyr/kernel/obj_core.h>

Value:

((s[0] << 24) | (s[1] << 16) | (s[2] << 8) | (s[3]))

Generate new object type IDs based on a 4 letter string.

K_OBJ_TYPE_KERNEL_ID

#define K_OBJ_TYPE_KERNEL_ID   K_OBJ_TYPE_ID_GEN("KRNL")

#include <zephyr/kernel/obj_core.h>

Kernel object type.

K_OBJ_TYPE_LIFO_ID

#define K_OBJ_TYPE_LIFO_ID   K_OBJ_TYPE_ID_GEN("LIFO")

#include <zephyr/kernel/obj_core.h>

LIFO object type.

K_OBJ_TYPE_MAX_RANGES

#define K_OBJ_TYPE_MAX_RANGES   3

#include <zephyr/kernel/obj_core.h>

Maximum number of permanent object ranges of an object type.

K_OBJ_TYPE_MBOX_ID

#define K_OBJ_TYPE_MBOX_ID   K_OBJ_TYPE_ID_GEN("MBOX")

#include <zephyr/kernel/obj_core.h>

Mailbox object type.

K_OBJ_TYPE_MEM_BLOCK_ID

#define K_OBJ_TYPE_MEM_BLOCK_ID   K_OBJ_TYPE_ID_GEN("MBLK")

#include <zephyr/kernel/obj_core.h>

Memory block object type.

K_OBJ_TYPE_MEM_SLAB_ID

#define K_OBJ_TYPE_MEM_SLAB_ID   K_OBJ_TYPE_ID_GEN("SLAB")

#include <zephyr/kernel/obj_core.h>

Memory slab object type.

K_OBJ_TYPE_MSGQ_ID

#define K_OBJ_TYPE_MSGQ_ID   K_OBJ_TYPE_ID_GEN("MSGQ")

#include <zephyr/kernel/obj_core.h>

Message queue object type.

K_OBJ_TYPE_MUTEX_ID

#define K_OBJ_TYPE_MUTEX_ID   K_OBJ_TYPE_ID_GEN("MUTX")

#include <zephyr/kernel/obj_core.h>

Mutex object type.

K_OBJ_TYPE_PIPE_ID

#define K_OBJ_TYPE_PIPE_ID   K_OBJ_TYPE_ID_GEN("PIPE")

#include <zephyr/kernel/obj_core.h>

Pipe object type.

K_OBJ_TYPE_QUEUE_ID

#define K_OBJ_TYPE_QUEUE_ID   K_OBJ_TYPE_ID_GEN("QUEU")

#include <zephyr/kernel/obj_core.h>

Queue object type.

K_OBJ_TYPE_SEM_ID

#define K_OBJ_TYPE_SEM_ID   K_OBJ_TYPE_ID_GEN("SEM4")

#include <zephyr/kernel/obj_core.h>

Semaphore object type.

K_OBJ_TYPE_STACK_ID

#define K_OBJ_TYPE_STACK_ID   K_OBJ_TYPE_ID_GEN("STCK")

#include <zephyr/kernel/obj_core.h>

Stack object type.

K_OBJ_TYPE_THREAD_ID

#define K_OBJ_TYPE_THREAD_ID   K_OBJ_TYPE_ID_GEN("THRD")

#include <zephyr/kernel/obj_core.h>

Thread object type.

K_OBJ_TYPE_TIMER_ID

#define K_OBJ_TYPE_TIMER_ID   K_OBJ_TYPE_ID_GEN("TIMR")

#include <zephyr/kernel/obj_core.h>

Timer object type.

Function Documentation

k_obj_core_evict_range()

void k_obj_core_evict_range	(	const void *	addr,
		size_t	len )

#include <zephyr/kernel/obj_core.h>

Unregister every kernel object located in a memory range.

Intended for memory allocators: removes the registry entries of all objects whose object core lies in [addr, addr + len) as the memory is released. This function takes no lock and may be called while holding the allocator's lock.

Parameters

addr	Start of the released memory
len	Size of the released memory in bytes

k_obj_core_init()

void k_obj_core_init	(	struct k_obj_core *	obj_core,
		struct k_obj_type *	type )

#include <zephyr/kernel/obj_core.h>

Initialize the core of the kernel object.

Initializing the kernel object core associates it with the specified kernel object type.

Parameters

obj_core	Pointer to the kernel object to initialize
type	Pointer to the kernel object type

k_obj_core_init_and_link()

void k_obj_core_init_and_link	(	struct k_obj_core *	obj_core,
		struct k_obj_type *	type )

#include <zephyr/kernel/obj_core.h>

Automatically link the kernel object after initializing it.

A useful wrapper to both initialize the core of the kernel object and automatically link it into the kernel object type's list of objects.

Parameters

obj_core	Pointer to the kernel object to initialize
type	Pointer to the kernel object type

k_obj_core_link()

void k_obj_core_link

(

struct k_obj_core *

obj_core

)

#include <zephyr/kernel/obj_core.h>

Register the kernel object with its object type.

A kernel object can be optionally registered so that it is reported by k_obj_type_walk_locked() and k_obj_type_walk_unlocked(). It must have been initialized with k_obj_core_init() first. Registering an object that is already registered, or that belongs to the permanent range of its type, has no effect. An object located in the current thread's stack or in the interrupt stack is not registered and the type's skipped count is incremented. The registry holds no reference inside the object, so an object may be discarded without unregistering it; the stale entry is dropped when its storage is reused or when the registry is full. When the registry is full the object is not registered and the type's dropped count is incremented.

Parameters

obj_core

Pointer to the kernel object

k_obj_core_unlink()

void k_obj_core_unlink

(

struct k_obj_core *

obj_core

)

#include <zephyr/kernel/obj_core.h>

Unregister the kernel object from its object type.

Unregistering is optional and removes the object from the walks immediately, instead of when its storage is reused. Unregistering an object that is not registered has no effect. This function takes no lock and may be called from any context.

Parameters

obj_core

Pointer to the kernel object

k_obj_type_find()

struct k_obj_type * k_obj_type_find

(

uint32_t

type_id

)

#include <zephyr/kernel/obj_core.h>

Find a specific object type by ID.

Given an object type ID, this function searches for the object type that is associated with the specified type ID type_id.

Parameters

type_id

Type ID associated with object type

Return values

NULL	if object type not found

Returns

Pointer to object type if found

k_obj_type_init_range()

void k_obj_type_init_range	(	struct k_obj_type *	type,
		const void *	start,
		const void *	end,
		size_t	stride,
		bool	indirect )

#include <zephyr/kernel/obj_core.h>

Register the permanent objects of an object type.

Objects in [start, end) are enumerated by walking the range and are not registered individually. The storage must outlive the object type.

Parameters

type	Pointer to the object type
start	First element of the range
end	One past the last element of the range
stride	Element size
indirect	True if the elements are pointers to the objects

k_obj_type_walk_locked()

int k_obj_type_walk_locked	(	struct k_obj_type *	type,
		int(*	func )(struct k_obj_core *obj_core, void *data),
		void *	data )

#include <zephyr/kernel/obj_core.h>

Walk the object cores of an object type.

This function invokes the callback on every object core of the object type: first the permanent objects of the type, then the objects registered at run time. It takes the registry spinlock to read each entry and releases it before invoking the callback, so the callback may use any kernel or object core function. A registered object whose storage has been reused is removed from the registry instead of being reported.

The callback function shall either return non-zero to stop further walking, or it shall return 0 to continue walking.

Parameters

type	Pointer to the object type
func	Callback to invoke on each object core of the object type
data	Custom data passed to the callback

Return values

non-zero

if walk is terminated by the callback; otherwise 0

k_obj_type_walk_unlocked()

int k_obj_type_walk_unlocked	(	struct k_obj_type *	type,
		int(*	func )(struct k_obj_core *obj_core, void *data),
		void *	data )

#include <zephyr/kernel/obj_core.h>

Walk the object cores of an object type.

This function is similar to k_obj_type_walk_locked() except that it reads the registry without taking the spinlock, so it can be used where the lock cannot. Objects registered or unregistered during the walk may or may not be reported, and a registered object whose storage has been reused is skipped rather than removed.

The callback function shall either return non-zero to stop further walking, or it shall return 0 to continue walking.

Parameters

type	Pointer to the object type
func	Callback to invoke on each object core of the object type
data	Custom data passed to the callback

Return values

non-zero

if walk is terminated by the callback; otherwise 0