michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: Add object core documentation

Browse source 
Adds documentation for both object cores and object core statistics.

Signed-off-by: Peter Mitsis <peter.mitsis@intel.com>
This commit is contained in:
Peter Mitsis 2023-06-11 16:50:52 -04:00 • committed by Johan Hedberg
commit 1afc32e762
2 changed files with 234 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

1
doc/kernel/index.rst
View file

@ -12,6 +12,7 @@ Kernel
memory_management/index.rst
data_structures/index.rst
timing_functions/index.rst
object_cores/index.rst
timeutil.rst
util/index.rst
iterable_sections/index.rst

233
doc/kernel/object_cores/index.rst Normal file
View file

@ -0,0 +1,233 @@
.. _object_cores_api:
Object Cores
############
Object cores are a kernel debugging tool that can be used to both identify and
perform operations on registered objects.
.. contents::
:local:
:depth: 2
Object Core Concepts
********************
Each instance of an object embeds an object core field named `obj_core`.
Objects of the same type are linked together via their respective object
cores to form a singly linked list. Each object core also links to the their
respective object type. Each object type contains a singly linked list
linking together all the object cores of that type. Object types are also
linked together via a singly linked list. Together, this can allow debugging
tools to traverse all the objects in the system.
Object cores have been integrated into following kernel objects:
* :ref:`Condition Variables <condvar>`
* :ref:`Events <events>`
* :ref:`FIFOs <fifos_v2>` and :ref:`LIFOs <lifos_v2>`
* :ref:`Mailboxes <mailboxes_v2>`
* :ref:`Memory Slabs <memory_slabs_v2>`
* :ref:`Message Queues <message_queues_v2>`
* :ref:`Mutexes <mutexes_v2>`
* :ref:`Pipes <pipes_v2>`
* :ref:`Semaphores <semaphores_v2>`
* :ref:`Timers <timers_v2>`
* :ref:`System Memory Blocks <sys_mem_blocks>`
Developers are free to integrate them if desired into other objects within
their projects.
Object Core Statistics Concepts
*******************************
A variety of kernel objects allow for the gathering and reporting of statistics.
Object cores provide a uniform means to retrieve that information via object
core statistics. When enabled, the object type contains a pointer to a
statistics descriptor that defines the various operations that have been
enabled for interfacing with the object's statistics. Additionally, the object
core contains a pointer to the "raw" statistical information associated with
that object. Raw data is the raw, unmanipulated data associated with the
statistics. Queried data may be "raw", but it may also have been manipulated in
some way by calculation (such as determining an average).
The following table indicates both what objects have been integrated into the
object core statistics as well as the structures used for both "raw" and
"queried" data.
===================== ============================== ==============================
Object Raw Data Type Query Data Type
===================== ============================== ==============================
struct mem_slab struct mem_slab_info struct sys_memory_stats
struct sys_mem_blocks struct sys_mem_blocks_info struct sys_memory_stats
struct k_thread struct k_cycle_stats struct k_thread_runtime_stats
struct _cpu struct k_cycle_stats struct k_thread_runtime_stats
struct z_kernel struct k_cycle_stats[num CPUs] struct k_thread_runtime_stats
===================== ============================== ==============================
Implementation
**************
Defining a New Object Type
==========================
An object type is defined using a global variable of type
:c:struct:`k_obj_type`. It must be initialized before any objects of that type
are initialized. The following code shows how a new object type can be
initialized for use with object cores and object core statistics.
.. code-block:: c
/* Unique object type ID */
#define K_OBJ_TYPE_MY_NEW_TYPE K_OBJ_TYPE_ID_GEN("UNIQ")
struct k_obj_type my_obj_type;
struct my_obj_type_raw_info {
...
};
struct my_obj_type_query_stats {
...
};
struct my_new_obj {
...
struct k_obj_core obj_core;
struct my_obj_type_raw_info info;
};
struct k_obj_core_stats_desc my_obj_type_stats_desc = {
.raw_size = sizeof(struct my_obj_type_raw_stats),
.query_size = sizeof(struct my_obj_type_query_stats),
.raw = my_obj_type_stats_raw,
.query = my_obj_type_stats_query,
.reset = my_obj_type_stats_reset,
.disable = NULL, /* Stats gathering is always on */
.enable = NULL, /* Stats gathering is always on */
};
void my_obj_type_init(void)
{
z_obj_type_init(&my_obj_type, K_OBJ_TYPE_MY_NEW_TYPE,
offsetof(struct my_new_obj, obj_core);
k_obj_type_stats_init(&my_obj_type, &my_obj_type_stats_desc);
}
Initializing a New Object Core
==============================
Kernel objects that have already been integrated into the object core framework
automatically have their object cores initialized when the object is
initialized. However, developers that wish to add their own objects into the
framework need to both initialize the object core and link it. The following
code builds on the example above and initializes the object core.
.. code-block:: c
void my_new_obj_init(struct my_new_obj *new_obj)
{
...
k_obj_core_init(K_OBJ_CORE(new_obj), &my_obj_type);
k_obj_core_link(K_OBJ_CORE(new_obj));
k_obj_core_stats_register(K_OBJ_CORE(new_obj), &new_obj->raw_stats,
sizeof(struct my_obj_type_raw_info));
}
Walking a List of Object Cores
==============================
Two routines exist for walking the list of object cores linked to an object
type. These are :c:func:`k_obj_type_walk_locked` and
:c:func:`k_obj_type_walk_unlocked`. The following code builds upon the example
above and prints the addresses of all the objects of that new object type.
.. code-block:: c
int walk_op(struct k_obj_core *obj_core, void *data)
{
uint8_t *ptr;
ptr = obj_core;
ptr -= obj_core->type->obj_core_offset;
printk("%p\n", ptr);
return 0;
}
void print_object_addresses(void)
{
struct k_obj_type *obj_type;
/* Find the object type */
obj_type = k_obj_type_find(K_OBJ_TYPE_MY_NEW_TYPE);
/* Walk the list of objects */
k_obj_type_walk_unlocked(obj_type, walk_op, NULL);
}
Object Core Statistics Querying
===============================
The following code builds on the examples above and shows how an object
integrated into the object core statistics framework can both retrieve queried
data and reset the stats associated with the object.
.. code-block:: c
struct my_new_obj my_obj;
...
void my_func(void)
{
struct my_obj_type_query_stats my_stats;
int status;
my_obj_type_init(&my_obj);
...
status = k_obj_core_stats_query(K_OBJ_CORE(&my_obj),
&my_stats, sizeof(my_stats));
if (status != 0) {
/* Failed to get stats */
...
} else {
k_obj_core_stats_reset(K_OBJ_CORE(&my_obj));
}
...
}
Configuration Options
*********************
Related configuration options:
* :kconfig:option:`CONFIG_OBJ_CORE`
* :kconfig:option:`CONFIG_OBJ_CORE_CONDVAR`
* :kconfig:option:`CONFIG_OBJ_CORE_EVENT`
* :kconfig:option:`CONFIG_OBJ_CORE_FIFO`
* :kconfig:option:`CONFIG_OBJ_CORE_LIFO`
* :kconfig:option:`CONFIG_OBJ_CORE_MAILBOX`
* :kconfig:option:`CONFIG_OBJ_CORE_MEM_SLAB`
* :kconfig:option:`CONFIG_OBJ_CORE_MSGQ`
* :kconfig:option:`CONFIG_OBJ_CORE_MUTEX`
* :kconfig:option:`CONFIG_OBJ_CORE_PIPE`
* :kconfig:option:`CONFIG_OBJ_CORE_SEM`
* :kconfig:option:`CONFIG_OBJ_CORE_STACK`
* :kconfig:option:`CONFIG_OBJ_CORE_TIMER`
* :kconfig:option:`CONFIG_OBJ_CORE_SYS_MEM_BLOCKS`
* :kconfig:option:`CONFIG_OBJ_CORE_STATS`
* :kconfig:option:`CONFIG_OBJ_CORE_STATS_MEM_SLAB`
* :kconfig:option:`CONFIG_OBJ_CORE_STATS_THREAD`
* :kconfig:option:`CONFIG_OBJ_CORE_STATS_SYSTEM`
* :kconfig:option:`CONFIG_OBJ_CORE_STATS_SYS_MEM_BLOCKS`
API Reference
*************
.. doxygengroup:: obj_core_apis
.. doxygengroup:: obj_core_stats_apis