Line data Source code
1 0 : /*
2 : * Copyright (c) 2023, Intel Corporation
3 : *
4 : * SPDX-License-Identifier: Apache-2.0
5 : */
6 :
7 : #ifndef __KERNEL_OBJ_CORE_H__
8 : #define __KERNEL_OBJ_CORE_H__
9 :
10 : #include <zephyr/sys/slist.h>
11 :
12 : /**
13 : * @defgroup obj_core_apis Object Core APIs
14 : * @ingroup kernel_apis
15 : * @{
16 : */
17 :
18 : /**
19 : * @brief Convert kernel object pointer into its object core pointer
20 : */
21 1 : #define K_OBJ_CORE(kobj) (&((kobj)->obj_core))
22 :
23 : /**
24 : * @brief Generate new object type IDs based on a 4 letter string
25 : */
26 1 : #define K_OBJ_TYPE_ID_GEN(s) ((s[0] << 24) | (s[1] << 16) | (s[2] << 8) | (s[3]))
27 :
28 : /* Known kernel object types */
29 :
30 : /** Condition variable object type */
31 1 : #define K_OBJ_TYPE_CONDVAR_ID K_OBJ_TYPE_ID_GEN("COND")
32 : /** CPU object type */
33 1 : #define K_OBJ_TYPE_CPU_ID K_OBJ_TYPE_ID_GEN("CPU_")
34 : /** Event object type */
35 1 : #define K_OBJ_TYPE_EVENT_ID K_OBJ_TYPE_ID_GEN("EVNT")
36 : /** FIFO object type */
37 1 : #define K_OBJ_TYPE_FIFO_ID K_OBJ_TYPE_ID_GEN("FIFO")
38 : /** Kernel object type */
39 1 : #define K_OBJ_TYPE_KERNEL_ID K_OBJ_TYPE_ID_GEN("KRNL")
40 : /** LIFO object type */
41 1 : #define K_OBJ_TYPE_LIFO_ID K_OBJ_TYPE_ID_GEN("LIFO")
42 : /** Memory block object type */
43 1 : #define K_OBJ_TYPE_MEM_BLOCK_ID K_OBJ_TYPE_ID_GEN("MBLK")
44 : /** Mailbox object type */
45 1 : #define K_OBJ_TYPE_MBOX_ID K_OBJ_TYPE_ID_GEN("MBOX")
46 : /** Memory slab object type */
47 1 : #define K_OBJ_TYPE_MEM_SLAB_ID K_OBJ_TYPE_ID_GEN("SLAB")
48 : /** Message queue object type */
49 1 : #define K_OBJ_TYPE_MSGQ_ID K_OBJ_TYPE_ID_GEN("MSGQ")
50 : /** Mutex object type */
51 1 : #define K_OBJ_TYPE_MUTEX_ID K_OBJ_TYPE_ID_GEN("MUTX")
52 : /** Pipe object type */
53 1 : #define K_OBJ_TYPE_PIPE_ID K_OBJ_TYPE_ID_GEN("PIPE")
54 : /** Semaphore object type */
55 1 : #define K_OBJ_TYPE_SEM_ID K_OBJ_TYPE_ID_GEN("SEM4")
56 : /** Stack object type */
57 1 : #define K_OBJ_TYPE_STACK_ID K_OBJ_TYPE_ID_GEN("STCK")
58 : /** Thread object type */
59 1 : #define K_OBJ_TYPE_THREAD_ID K_OBJ_TYPE_ID_GEN("THRD")
60 : /** Timer object type */
61 1 : #define K_OBJ_TYPE_TIMER_ID K_OBJ_TYPE_ID_GEN("TIMR")
62 :
63 : struct k_obj_type;
64 : struct k_obj_core;
65 :
66 : /**
67 : * @cond INTERNAL_HIDDEN
68 : */
69 :
70 : #ifdef CONFIG_OBJ_CORE
71 : #define K_OBJ_CORE_INIT(_objp, _obj_type) \
72 : extern struct k_obj_type _obj_type; \
73 : k_obj_core_init(_objp, &_obj_type)
74 :
75 : #define K_OBJ_CORE_LINK(objp) k_obj_core_link(objp)
76 : #else
77 : #define K_OBJ_CORE_INIT(objp, type) do { } while (0)
78 : #define K_OBJ_CORE_LINK(objp) do { } while (0)
79 : #endif /* CONFIG_OBJ_CORE */
80 :
81 : /**
82 : * INTERNAL_HIDDEN @endcond
83 : */
84 :
85 : /**
86 : * Tools may use this list as an entry point to identify all registered
87 : * object types and the object cores linked to them.
88 : */
89 : extern sys_slist_t z_obj_type_list;
90 :
91 : /** Object core statistics descriptor */
92 1 : struct k_obj_core_stats_desc {
93 1 : size_t raw_size; /**< Internal representation stats buffer size */
94 1 : size_t query_size; /**< Stats buffer size used for reporting */
95 :
96 : /** Function pointer to retrieve internal representation of stats */
97 1 : int (*raw)(struct k_obj_core *obj_core, void *stats);
98 : /** Function pointer to retrieve reported statistics */
99 1 : int (*query)(struct k_obj_core *obj_core, void *stats);
100 : /** Function pointer to reset object's statistics */
101 1 : int (*reset)(struct k_obj_core *obj_core);
102 : /** Function pointer to disable object's statistics gathering */
103 1 : int (*disable)(struct k_obj_core *obj_core);
104 : /** Function pointer to enable object's statistics gathering */
105 1 : int (*enable)(struct k_obj_core *obj_core);
106 : };
107 :
108 : /** Object type structure */
109 1 : struct k_obj_type {
110 1 : sys_snode_t node; /**< Node within list of object types */
111 1 : sys_slist_t list; /**< List of objects of this object type */
112 1 : uint32_t id; /**< Unique type ID */
113 1 : size_t obj_core_offset; /**< Offset to obj_core field */
114 : #ifdef CONFIG_OBJ_CORE_STATS
115 : /** Pointer to object core statistics descriptor */
116 : struct k_obj_core_stats_desc *stats_desc;
117 : #endif /* CONFIG_OBJ_CORE_STATS */
118 : };
119 :
120 : /** Object core structure */
121 1 : struct k_obj_core {
122 1 : sys_snode_t node; /**< Object node within object type's list */
123 1 : struct k_obj_type *type; /**< Object type to which object belongs */
124 : #ifdef CONFIG_OBJ_CORE_STATS
125 : void *stats; /**< Pointer to kernel object's stats */
126 : #endif /* CONFIG_OBJ_CORE_STATS */
127 : };
128 :
129 : /**
130 : * @brief Initialize a specific object type
131 : *
132 : * Initializes a specific object type and links it into the object core
133 : * framework.
134 : *
135 : * @param type Pointer to the object type to initialize
136 : * @param id A means to identify the object type
137 : * @param off Offset of object core within the structure
138 : *
139 : * @retval Pointer to initialized object type
140 : */
141 : struct k_obj_type *z_obj_type_init(struct k_obj_type *type,
142 : uint32_t id, size_t off);
143 :
144 : /**
145 : * @brief Find a specific object type by ID
146 : *
147 : * Given an object type ID, this function searches for the object type that
148 : * is associated with the specified type ID @a type_id.
149 : *
150 : * @param type_id Type ID associated with object type
151 : *
152 : * @retval NULL if object type not found
153 : * @retval Pointer to object type if found
154 : */
155 1 : struct k_obj_type *k_obj_type_find(uint32_t type_id);
156 :
157 : /**
158 : * @brief Walk the object type's list of object cores
159 : *
160 : * This function takes a global spinlock and walks the object type's list
161 : * of object cores and invokes the callback function on each element while
162 : * holding that lock. Although this will ensure that the list is not modified,
163 : * one can expect a significant penalty in terms of performance and latency.
164 : *
165 : * The callback function shall either return non-zero to stop further walking,
166 : * or it shall return 0 to continue walking.
167 : *
168 : * @param type Pointer to the object type
169 : * @param func Callback to invoke on each object core of the object type
170 : * @param data Custom data passed to the callback
171 : *
172 : * @retval non-zero if walk is terminated by the callback; otherwise 0
173 : */
174 1 : int k_obj_type_walk_locked(struct k_obj_type *type,
175 : int (*func)(struct k_obj_core *, void *),
176 : void *data);
177 :
178 : /**
179 : * @brief Walk the object type's list of object cores
180 : *
181 : * This function is similar to k_obj_type_walk_locked() except that it walks
182 : * the list without obtaining the global spinlock. No synchronization is
183 : * provided here. Mutation of the list of objects while this function is in
184 : * progress must be prevented at the application layer, otherwise
185 : * undefined/unreliable behavior, corruption and/or crashes may result.
186 : *
187 : * The callback function shall either return non-zero to stop further walking,
188 : * or it shall return 0 to continue walking.
189 : *
190 : * @param type Pointer to the object type
191 : * @param func Callback to invoke on each object core of the object type
192 : * @param data Custom data passed to the callback
193 : *
194 : * @retval non-zero if walk is terminated by the callback; otherwise 0
195 : */
196 1 : int k_obj_type_walk_unlocked(struct k_obj_type *type,
197 : int (*func)(struct k_obj_core *, void *),
198 : void *data);
199 :
200 : /**
201 : * @brief Initialize the core of the kernel object
202 : *
203 : * Initializing the kernel object core associates it with the specified
204 : * kernel object type.
205 : *
206 : * @param obj_core Pointer to the kernel object to initialize
207 : * @param type Pointer to the kernel object type
208 : */
209 1 : void k_obj_core_init(struct k_obj_core *obj_core, struct k_obj_type *type);
210 :
211 : /**
212 : * @brief Link the kernel object to the kernel object type list
213 : *
214 : * A kernel object can be optionally linked into the kernel object type's
215 : * list of objects. A kernel object must have been initialized before it
216 : * can be linked. Linked kernel objects can be traversed and have information
217 : * extracted from them by system tools.
218 : *
219 : * @param obj_core Pointer to the kernel object
220 : */
221 1 : void k_obj_core_link(struct k_obj_core *obj_core);
222 :
223 : /**
224 : * @brief Automatically link the kernel object after initializing it
225 : *
226 : * A useful wrapper to both initialize the core of the kernel object and
227 : * automatically link it into the kernel object type's list of objects.
228 : *
229 : * @param obj_core Pointer to the kernel object to initialize
230 : * @param type Pointer to the kernel object type
231 : */
232 1 : void k_obj_core_init_and_link(struct k_obj_core *obj_core,
233 : struct k_obj_type *type);
234 :
235 : /**
236 : * @brief Unlink the kernel object from the kernel object type list
237 : *
238 : * Kernel objects can be unlinked from their respective kernel object type
239 : * lists. If on a list, it must be done at the end of the kernel object's life
240 : * cycle.
241 : *
242 : * @param obj_core Pointer to the kernel object
243 : */
244 1 : void k_obj_core_unlink(struct k_obj_core *obj_core);
245 :
246 : /** @} */
247 :
248 : /**
249 : * @defgroup obj_core_stats_apis Object Core Statistics APIs
250 : * @ingroup kernel_apis
251 : * @{
252 : */
253 :
254 : #ifdef CONFIG_OBJ_CORE_STATS
255 : /**
256 : * @brief Initialize the object type's stats descriptor
257 : *
258 : * This routine initializes the object type's stats descriptor.
259 : *
260 : * @param type Pointer to the object type
261 : * @param stats_desc Pointer to the object core statistics descriptor
262 : */
263 : static inline void k_obj_type_stats_init(struct k_obj_type *type,
264 : struct k_obj_core_stats_desc *stats_desc)
265 : {
266 : type->stats_desc = stats_desc;
267 : }
268 :
269 : /**
270 : * @brief Initialize the object core for statistics
271 : *
272 : * This routine initializes the object core to operate within the object core
273 : * statistics framework.
274 : *
275 : * @param obj_core Pointer to the object core
276 : * @param stats Pointer to the object's raw statistics
277 : */
278 : static inline void k_obj_core_stats_init(struct k_obj_core *obj_core,
279 : void *stats)
280 : {
281 : obj_core->stats = stats;
282 : }
283 : #endif /* CONFIG_OBJ_CORE_STATS */
284 :
285 : /**
286 : * @brief Register kernel object for gathering statistics
287 : *
288 : * Before a kernel object can gather statistics, it must be registered to do
289 : * so. Registering will also automatically enable the kernel object to gather
290 : * its statistics.
291 : *
292 : * @param obj_core Pointer to kernel object core
293 : * @param stats Pointer to raw kernel statistics
294 : * @param stats_len Size of raw kernel statistics buffer
295 : *
296 : * @retval 0 on success
297 : * @retval -errno on failure
298 : */
299 1 : int k_obj_core_stats_register(struct k_obj_core *obj_core, void *stats,
300 : size_t stats_len);
301 :
302 : /**
303 : * @brief Deregister kernel object from gathering statistics
304 : *
305 : * Deregistering a kernel object core from gathering statistics prevents it
306 : * from gathering any more statistics. It is expected to be invoked at the end
307 : * of a kernel object's life cycle.
308 : *
309 : * @param obj_core Pointer to kernel object core
310 : *
311 : * @retval 0 on success
312 : * @retval -errno on failure
313 : */
314 1 : int k_obj_core_stats_deregister(struct k_obj_core *obj_core);
315 :
316 : /**
317 : * @brief Retrieve the raw statistics associated with the kernel object
318 : *
319 : * This function copies the raw statistics associated with the kernel object
320 : * core specified by @a obj_core into the buffer @a stats. Note that the size
321 : * of the buffer (@a stats_len) must match the size specified by the kernel
322 : * object type's statistics descriptor.
323 : *
324 : * @param obj_core Pointer to kernel object core
325 : * @param stats Pointer to memory buffer into which to copy raw stats
326 : * @param stats_len Length of the memory buffer
327 : *
328 : * @retval 0 on success
329 : * @retval -errno on failure
330 : */
331 1 : int k_obj_core_stats_raw(struct k_obj_core *obj_core, void *stats,
332 : size_t stats_len);
333 :
334 : /**
335 : * @brief Retrieve the statistics associated with the kernel object
336 : *
337 : * This function copies the statistics associated with the kernel object core
338 : * specified by @a obj_core into the buffer @a stats. Unlike the raw statistics
339 : * this may report calculated values such as averages. Note that the size of
340 : * the buffer (@a stats_len) must match the size specified by the kernel object
341 : * type's statistics descriptor.
342 : *
343 : * @param obj_core Pointer to kernel object core
344 : * @param stats Pointer to memory buffer into which to copy the queried stats
345 : * @param stats_len Length of the memory buffer
346 : *
347 : * @retval 0 on success
348 : * @retval -errno on failure
349 : */
350 1 : int k_obj_core_stats_query(struct k_obj_core *obj_core, void *stats,
351 : size_t stats_len);
352 :
353 : /**
354 : * @brief Reset the stats associated with the kernel object
355 : *
356 : * This function resets the statistics associated with the kernel object core
357 : * specified by @a obj_core.
358 : *
359 : * @param obj_core Pointer to kernel object core
360 : *
361 : * @retval 0 on success
362 : * @retval -errno on failure
363 : */
364 1 : int k_obj_core_stats_reset(struct k_obj_core *obj_core);
365 :
366 : /**
367 : * @brief Stop gathering the stats associated with the kernel object
368 : *
369 : * This function temporarily stops the gathering of statistics associated with
370 : * the kernel object core specified by @a obj_core. The gathering of statistics
371 : * can be resumed by invoking :c:func :`k_obj_core_stats_enable`.
372 : *
373 : * @param obj_core Pointer to kernel object core
374 : *
375 : * @retval 0 on success
376 : * @retval -errno on failure
377 : */
378 1 : int k_obj_core_stats_disable(struct k_obj_core *obj_core);
379 :
380 : /**
381 : * @brief Reset the stats associated with the kernel object
382 : *
383 : * This function resumes the gathering of statistics associated with the kernel
384 : * object core specified by @a obj_core.
385 : *
386 : * @param obj_core Pointer to kernel object core
387 : *
388 : * @retval 0 on success
389 : * @retval -errno on failure
390 : */
391 1 : int k_obj_core_stats_enable(struct k_obj_core *obj_core);
392 :
393 : /** @} */
394 : #endif /* __KERNEL_OBJ_CORE_H__ */
|
