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__ */
