1.. _object_cores_api:
2
3Object Cores
4############
5
6Object cores are a kernel debugging tool that can be used to both identify and
7perform operations on registered objects.
8
9.. contents::
10    :local:
11    :depth: 2
12
13Object Core Concepts
14********************
15
16Each instance of an object embeds an object core field named `obj_core`.
17Objects of the same type are linked together via their respective object
18cores to form a singly linked list. Each object core also links to the their
19respective object type. Each object type contains a singly linked list
20linking together all the object cores of that type. Object types are also
21linked together via a singly linked list. Together, this can allow debugging
22tools to traverse all the objects in the system.
23
24Object cores have been integrated into following kernel objects:
25 * :ref:`Condition Variables <condvar>`
26 * :ref:`Events <events>`
27 * :ref:`FIFOs <fifos_v2>` and :ref:`LIFOs <lifos_v2>`
28 * :ref:`Mailboxes <mailboxes_v2>`
29 * :ref:`Memory Slabs <memory_slabs_v2>`
30 * :ref:`Message Queues <message_queues_v2>`
31 * :ref:`Mutexes <mutexes_v2>`
32 * :ref:`Pipes <pipes_v2>`
33 * :ref:`Semaphores <semaphores_v2>`
34 * :ref:`Threads <threads_v2>`
35 * :ref:`Timers <timers_v2>`
36 * :ref:`System Memory Blocks <sys_mem_blocks>`
37
38Developers are free to integrate them if desired into other objects within
39their projects.
40
41Object Core Statistics Concepts
42*******************************
43A variety of kernel objects allow for the gathering and reporting of statistics.
44Object cores provide a uniform means to retrieve that information via object
45core statistics. When enabled, the object type contains a pointer to a
46statistics descriptor that defines the various operations that have been
47enabled for interfacing with the object's statistics. Additionally, the object
48core contains a pointer to the "raw" statistical information associated with
49that object. Raw data is the raw, unmanipulated data associated with the
50statistics. Queried data may be "raw", but it may also have been manipulated in
51some way by calculation (such as determining an average).
52
53The following table indicates both what objects have been integrated into the
54object core statistics as well as the structures used for both "raw" and
55"queried" data.
56
57=====================  ============================== ==============================
58Object                 Raw Data Type                  Query Data Type
59=====================  ============================== ==============================
60struct mem_slab        struct mem_slab_info            struct sys_memory_stats
61struct sys_mem_blocks  struct sys_mem_blocks_info      struct sys_memory_stats
62struct k_thread        struct k_cycle_stats            struct k_thread_runtime_stats
63struct _cpu            struct k_cycle_stats            struct k_thread_runtime_stats
64struct z_kernel        struct k_cycle_stats[num CPUs]  struct k_thread_runtime_stats
65=====================  ============================== ==============================
66
67Implementation
68**************
69
70Defining a New Object Type
71==========================
72
73An object type is defined using a global variable of type
74:c:struct:`k_obj_type`. It must be initialized before any objects of that type
75are initialized. The following code shows how a new object type can be
76initialized for use with object cores and object core statistics.
77
78.. code-block:: c
79
80    /* Unique object type ID */
81
82    #define K_OBJ_TYPE_MY_NEW_TYPE  K_OBJ_TYPE_ID_GEN("UNIQ")
83    struct k_obj_type  my_obj_type;
84
85    struct my_obj_type_raw_info {
86        ...
87    };
88
89    struct my_obj_type_query_stats {
90        ...
91    };
92
93    struct my_new_obj {
94        ...
95        struct k_obj_core obj_core;
96        struct my_obj_type_raw_info  info;
97    };
98
99    struct k_obj_core_stats_desc my_obj_type_stats_desc = {
100        .raw_size = sizeof(struct my_obj_type_raw_stats),
101        .query_size = sizeof(struct my_obj_type_query_stats),
102        .raw = my_obj_type_stats_raw,
103        .query = my_obj_type_stats_query,
104        .reset = my_obj_type_stats_reset,
105        .disable = NULL,    /* Stats gathering is always on */
106        .enable = NULL,     /* Stats gathering is always on */
107    };
108
109    void my_obj_type_init(void)
110    {
111        z_obj_type_init(&my_obj_type, K_OBJ_TYPE_MY_NEW_TYPE,
112                        offsetof(struct my_new_obj, obj_core);
113        k_obj_type_stats_init(&my_obj_type, &my_obj_type_stats_desc);
114    }
115
116Initializing a New Object Core
117==============================
118
119Kernel objects that have already been integrated into the object core framework
120automatically have their object cores initialized when the object is
121initialized. However, developers that wish to add their own objects into the
122framework need to both initialize the object core and link it. The following
123code builds on the example above and initializes the object core.
124
125.. code-block:: c
126
127    void my_new_obj_init(struct my_new_obj *new_obj)
128    {
129        ...
130        k_obj_core_init(K_OBJ_CORE(new_obj), &my_obj_type);
131        k_obj_core_link(K_OBJ_CORE(new_obj));
132        k_obj_core_stats_register(K_OBJ_CORE(new_obj), &new_obj->raw_stats,
133                                  sizeof(struct my_obj_type_raw_info));
134    }
135
136Walking a List of Object Cores
137==============================
138
139Two routines exist for walking the list of object cores linked to an object
140type. These are :c:func:`k_obj_type_walk_locked` and
141:c:func:`k_obj_type_walk_unlocked`. The following code builds upon the example
142above and prints the addresses of all the objects of that new object type.
143
144.. code-block:: c
145
146    int walk_op(struct k_obj_core *obj_core, void *data)
147    {
148        uint8_t *ptr;
149
150        ptr = obj_core;
151        ptr -= obj_core->type->obj_core_offset;
152
153        printk("%p\n", ptr);
154
155        return 0;
156    }
157
158    void print_object_addresses(void)
159    {
160        struct k_obj_type *obj_type;
161
162        /* Find the object type */
163
164        obj_type = k_obj_type_find(K_OBJ_TYPE_MY_NEW_TYPE);
165
166        /* Walk the list of objects */
167
168        k_obj_type_walk_unlocked(obj_type, walk_op, NULL);
169    }
170
171Object Core Statistics Querying
172===============================
173
174The following code builds on the examples above and shows how an object
175integrated into the object core statistics framework can both retrieve queried
176data and reset the stats associated with the object.
177
178.. code-block:: c
179
180    struct my_new_obj my_obj;
181
182    ...
183
184    void my_func(void)
185    {
186        struct my_obj_type_query_stats  my_stats;
187        int  status;
188
189        my_obj_type_init(&my_obj);
190
191        ...
192
193        status = k_obj_core_stats_query(K_OBJ_CORE(&my_obj),
194                                        &my_stats, sizeof(my_stats));
195        if (status != 0) {
196            /* Failed to get stats */
197            ...
198        } else {
199            k_obj_core_stats_reset(K_OBJ_CORE(&my_obj));
200        }
201
202        ...
203    }
204
205Configuration Options
206*********************
207
208Related configuration options:
209
210* :kconfig:option:`CONFIG_OBJ_CORE`
211* :kconfig:option:`CONFIG_OBJ_CORE_CONDVAR`
212* :kconfig:option:`CONFIG_OBJ_CORE_EVENT`
213* :kconfig:option:`CONFIG_OBJ_CORE_FIFO`
214* :kconfig:option:`CONFIG_OBJ_CORE_LIFO`
215* :kconfig:option:`CONFIG_OBJ_CORE_MAILBOX`
216* :kconfig:option:`CONFIG_OBJ_CORE_MEM_SLAB`
217* :kconfig:option:`CONFIG_OBJ_CORE_MSGQ`
218* :kconfig:option:`CONFIG_OBJ_CORE_MUTEX`
219* :kconfig:option:`CONFIG_OBJ_CORE_PIPE`
220* :kconfig:option:`CONFIG_OBJ_CORE_SEM`
221* :kconfig:option:`CONFIG_OBJ_CORE_STACK`
222* :kconfig:option:`CONFIG_OBJ_CORE_THREAD`
223* :kconfig:option:`CONFIG_OBJ_CORE_TIMER`
224* :kconfig:option:`CONFIG_OBJ_CORE_SYS_MEM_BLOCKS`
225* :kconfig:option:`CONFIG_OBJ_CORE_STATS`
226* :kconfig:option:`CONFIG_OBJ_CORE_STATS_MEM_SLAB`
227* :kconfig:option:`CONFIG_OBJ_CORE_STATS_THREAD`
228* :kconfig:option:`CONFIG_OBJ_CORE_STATS_SYSTEM`
229* :kconfig:option:`CONFIG_OBJ_CORE_STATS_SYS_MEM_BLOCKS`
230
231API Reference
232*************
233
234.. doxygengroup:: obj_core_apis
235.. doxygengroup:: obj_core_stats_apis
236