[a2e3f33] | 1 | /** |
---|
| 2 | * @file |
---|
| 3 | * |
---|
| 4 | * @brief Inlined Routines in the Object Handler |
---|
| 5 | * |
---|
| 6 | * This include file contains the static inline implementation of all |
---|
| 7 | * of the inlined routines in the Object Handler. |
---|
| 8 | */ |
---|
| 9 | |
---|
| 10 | /* |
---|
| 11 | * COPYRIGHT (c) 1989-2011. |
---|
| 12 | * On-Line Applications Research Corporation (OAR). |
---|
| 13 | * |
---|
| 14 | * The license and distribution terms for this file may be |
---|
| 15 | * found in the file LICENSE in this distribution or at |
---|
[c499856] | 16 | * http://www.rtems.org/license/LICENSE. |
---|
[a2e3f33] | 17 | */ |
---|
| 18 | |
---|
| 19 | #ifndef _RTEMS_SCORE_OBJECTIMPL_H |
---|
| 20 | #define _RTEMS_SCORE_OBJECTIMPL_H |
---|
| 21 | |
---|
[a6e7d5e4] | 22 | #include <rtems/score/objectdata.h> |
---|
[23fec9f0] | 23 | #include <rtems/score/apimutex.h> |
---|
[4db0ae8e] | 24 | #include <rtems/score/isrlock.h> |
---|
[a2e3f33] | 25 | #include <rtems/score/threaddispatch.h> |
---|
| 26 | |
---|
| 27 | #ifdef __cplusplus |
---|
| 28 | extern "C" { |
---|
| 29 | #endif |
---|
| 30 | |
---|
| 31 | /** |
---|
| 32 | * @addtogroup ScoreObject |
---|
| 33 | * |
---|
| 34 | * @{ |
---|
| 35 | */ |
---|
| 36 | |
---|
| 37 | /** |
---|
| 38 | * Functions which compare names are prototyped like this. |
---|
| 39 | */ |
---|
| 40 | typedef bool (*Objects_Name_comparators)( |
---|
| 41 | void * /* name_1 */, |
---|
| 42 | void * /* name_2 */, |
---|
| 43 | uint16_t /* length */ |
---|
| 44 | ); |
---|
| 45 | |
---|
| 46 | /** This macro is used to generically specify the last API index. */ |
---|
[6c2b8a4b] | 47 | #define OBJECTS_INTERNAL_CLASSES_LAST OBJECTS_INTERNAL_THREADS |
---|
[a2e3f33] | 48 | |
---|
| 49 | /** This macro is used to generically specify the last API index. */ |
---|
| 50 | #define OBJECTS_RTEMS_CLASSES_LAST OBJECTS_RTEMS_BARRIERS |
---|
| 51 | |
---|
| 52 | /** This macro is used to generically specify the last API index. */ |
---|
[ba776282] | 53 | #define OBJECTS_POSIX_CLASSES_LAST OBJECTS_POSIX_SHMS |
---|
[a2e3f33] | 54 | |
---|
[b427a92] | 55 | /* |
---|
| 56 | * For fake objects, which have an object identifier, but no objects |
---|
| 57 | * information block. |
---|
| 58 | */ |
---|
| 59 | typedef enum { |
---|
| 60 | OBJECTS_FAKE_OBJECTS_NO_CLASS = 0, |
---|
| 61 | OBJECTS_FAKE_OBJECTS_SCHEDULERS = 1 |
---|
| 62 | } Objects_Fake_objects_API; |
---|
| 63 | |
---|
[a2e3f33] | 64 | /** |
---|
| 65 | * The following is referenced to the node number of the local node. |
---|
| 66 | */ |
---|
| 67 | #if defined(RTEMS_MULTIPROCESSING) |
---|
[358bd740] | 68 | extern uint16_t _Objects_Local_node; |
---|
[a2e3f33] | 69 | #else |
---|
| 70 | #define _Objects_Local_node ((uint16_t)1) |
---|
| 71 | #endif |
---|
| 72 | |
---|
| 73 | /** |
---|
| 74 | * The following is referenced to the number of nodes in the system. |
---|
| 75 | */ |
---|
| 76 | #if defined(RTEMS_MULTIPROCESSING) |
---|
[358bd740] | 77 | extern uint16_t _Objects_Maximum_nodes; |
---|
[a2e3f33] | 78 | #else |
---|
| 79 | #define _Objects_Maximum_nodes 1 |
---|
| 80 | #endif |
---|
| 81 | |
---|
[3899bc1a] | 82 | /** |
---|
| 83 | * This is the minimum object ID index associated with an object. |
---|
| 84 | */ |
---|
| 85 | #define OBJECTS_INDEX_MINIMUM 1U |
---|
| 86 | |
---|
[a2e3f33] | 87 | /** |
---|
| 88 | * The following is the list of information blocks per API for each object |
---|
| 89 | * class. From the ID, we can go to one of these information blocks, |
---|
| 90 | * and obtain a pointer to the appropriate object control block. |
---|
| 91 | */ |
---|
[876dde7a] | 92 | extern Objects_Information ** const |
---|
| 93 | _Objects_Information_table[ OBJECTS_APIS_LAST + 1 ]; |
---|
[a2e3f33] | 94 | |
---|
| 95 | /** |
---|
| 96 | * This function extends an object class information record. |
---|
| 97 | * |
---|
| 98 | * @param[in] information points to an object class information block. |
---|
| 99 | */ |
---|
| 100 | void _Objects_Extend_information( |
---|
| 101 | Objects_Information *information |
---|
| 102 | ); |
---|
| 103 | |
---|
| 104 | /** |
---|
| 105 | * @brief Shrink an object class information record |
---|
| 106 | * |
---|
| 107 | * This function shrink an object class information record. |
---|
| 108 | * The object's name and object space are released. The local_table |
---|
| 109 | * etc block does not shrink. The InActive list needs to be scanned |
---|
| 110 | * to find the objects are remove them. |
---|
| 111 | * |
---|
| 112 | * @param[in] information points to an object class information block. |
---|
| 113 | */ |
---|
| 114 | void _Objects_Shrink_information( |
---|
| 115 | Objects_Information *information |
---|
| 116 | ); |
---|
| 117 | |
---|
[9c9c6a9] | 118 | /** |
---|
[21275b58] | 119 | * @brief Initializes the specified objects information. |
---|
[a2e3f33] | 120 | * |
---|
[21275b58] | 121 | * The objects information must be statically pre-initialized with the |
---|
| 122 | * OBJECTS_INFORMATION_DEFINE() macro before this function is called. |
---|
[a2e3f33] | 123 | */ |
---|
[21275b58] | 124 | void _Objects_Initialize_information( Objects_Information *information ); |
---|
[a2e3f33] | 125 | |
---|
| 126 | /** |
---|
| 127 | * @brief Object API Maximum Class |
---|
| 128 | * |
---|
| 129 | * This function returns the highest numeric value of a valid |
---|
| 130 | * API for the specified @a api. |
---|
| 131 | * |
---|
| 132 | * @param[in] api is the API of interest |
---|
| 133 | * |
---|
| 134 | * @retval A positive integer on success and 0 otherwise. |
---|
| 135 | */ |
---|
| 136 | unsigned int _Objects_API_maximum_class( |
---|
| 137 | uint32_t api |
---|
| 138 | ); |
---|
| 139 | |
---|
| 140 | /** |
---|
[23fec9f0] | 141 | * @brief Allocates an object without locking the allocator mutex. |
---|
[a2e3f33] | 142 | * |
---|
[23fec9f0] | 143 | * This function can be called in two contexts |
---|
| 144 | * - the executing thread is the owner of the object allocator mutex, or |
---|
| 145 | * - in case the system state is not up, e.g. during sequential system |
---|
| 146 | * initialization. |
---|
[a2e3f33] | 147 | * |
---|
[23fec9f0] | 148 | * @param[in] information The object information block. |
---|
| 149 | * |
---|
| 150 | * @retval NULL No object available. |
---|
| 151 | * @retval object The allocated object. |
---|
| 152 | * |
---|
| 153 | * @see _Objects_Allocate() and _Objects_Free(). |
---|
[a2e3f33] | 154 | */ |
---|
[23fec9f0] | 155 | Objects_Control *_Objects_Allocate_unprotected( |
---|
[a2e3f33] | 156 | Objects_Information *information |
---|
| 157 | ); |
---|
| 158 | |
---|
| 159 | /** |
---|
[23fec9f0] | 160 | * @brief Allocates an object. |
---|
[a2e3f33] | 161 | * |
---|
[23fec9f0] | 162 | * This function locks the object allocator mutex via |
---|
| 163 | * _Objects_Allocator_lock(). The caller must later unlock the object |
---|
| 164 | * allocator mutex via _Objects_Allocator_unlock(). The caller must unlock the |
---|
| 165 | * mutex in any case, even if the allocation failed due to resource shortage. |
---|
[a2e3f33] | 166 | * |
---|
[23fec9f0] | 167 | * A typical object allocation code looks like this: |
---|
| 168 | * @code |
---|
| 169 | * rtems_status_code some_create( rtems_id *id ) |
---|
| 170 | * { |
---|
| 171 | * rtems_status_code sc; |
---|
| 172 | * Some_Control *some; |
---|
| 173 | * |
---|
| 174 | * // The object allocator mutex protects the executing thread from |
---|
| 175 | * // asynchronous thread restart and deletion. |
---|
| 176 | * some = (Some_Control *) _Objects_Allocate( &_Some_Information ); |
---|
| 177 | * |
---|
| 178 | * if ( some != NULL ) { |
---|
| 179 | * _Some_Initialize( some ); |
---|
| 180 | * sc = RTEMS_SUCCESSFUL; |
---|
| 181 | * } else { |
---|
| 182 | * sc = RTEMS_TOO_MANY; |
---|
| 183 | * } |
---|
| 184 | * |
---|
| 185 | * _Objects_Allocator_unlock(); |
---|
| 186 | * |
---|
| 187 | * return sc; |
---|
| 188 | * } |
---|
| 189 | * @endcode |
---|
| 190 | * |
---|
| 191 | * @param[in] information The object information block. |
---|
| 192 | * |
---|
| 193 | * @retval NULL No object available. |
---|
| 194 | * @retval object The allocated object. |
---|
| 195 | * |
---|
| 196 | * @see _Objects_Free(). |
---|
| 197 | */ |
---|
| 198 | Objects_Control *_Objects_Allocate( Objects_Information *information ); |
---|
| 199 | |
---|
| 200 | /** |
---|
| 201 | * @brief Frees an object. |
---|
| 202 | * |
---|
| 203 | * Appends the object to the chain of inactive objects. |
---|
| 204 | * |
---|
| 205 | * @param[in] information The object information block. |
---|
| 206 | * @param[in] the_object The object to free. |
---|
| 207 | * |
---|
| 208 | * @see _Objects_Allocate(). |
---|
| 209 | * |
---|
| 210 | * A typical object deletion code looks like this: |
---|
| 211 | * @code |
---|
| 212 | * rtems_status_code some_delete( rtems_id id ) |
---|
| 213 | * { |
---|
| 214 | * Some_Control *some; |
---|
| 215 | * |
---|
| 216 | * // The object allocator mutex protects the executing thread from |
---|
| 217 | * // asynchronous thread restart and deletion. |
---|
| 218 | * _Objects_Allocator_lock(); |
---|
| 219 | * |
---|
[ee710ef] | 220 | * // Get the object under protection of the object allocator mutex. |
---|
[23fec9f0] | 221 | * some = (Semaphore_Control *) |
---|
[ee710ef] | 222 | * _Objects_Get_no_protection( id, &_Some_Information ); |
---|
[23fec9f0] | 223 | * |
---|
[ee710ef] | 224 | * if ( some == NULL ) { |
---|
| 225 | * _Objects_Allocator_unlock(); |
---|
| 226 | * return RTEMS_INVALID_ID; |
---|
| 227 | * } |
---|
[23fec9f0] | 228 | * |
---|
[ee710ef] | 229 | * // After the object close an object get with this identifier will |
---|
| 230 | * // fail. |
---|
| 231 | * _Objects_Close( &_Some_Information, &some->Object ); |
---|
[23fec9f0] | 232 | * |
---|
[ee710ef] | 233 | * _Some_Delete( some ); |
---|
[23fec9f0] | 234 | * |
---|
[ee710ef] | 235 | * // Thread dispatching is enabled. The object free is only protected |
---|
| 236 | * // by the object allocator mutex. |
---|
| 237 | * _Objects_Free( &_Some_Information, &some->Object ); |
---|
[23fec9f0] | 238 | * |
---|
| 239 | * _Objects_Allocator_unlock(); |
---|
[ee710ef] | 240 | * return RTEMS_SUCCESSFUL; |
---|
[23fec9f0] | 241 | * } |
---|
| 242 | * @endcode |
---|
[a2e3f33] | 243 | */ |
---|
| 244 | void _Objects_Free( |
---|
| 245 | Objects_Information *information, |
---|
| 246 | Objects_Control *the_object |
---|
| 247 | ); |
---|
| 248 | |
---|
| 249 | /** |
---|
| 250 | * This function implements the common portion of the object |
---|
| 251 | * identification directives. This directive returns the object |
---|
| 252 | * id associated with name. If more than one object of this class |
---|
| 253 | * is named name, then the object to which the id belongs is |
---|
| 254 | * arbitrary. Node indicates the extent of the search for the |
---|
| 255 | * id of the object named name. If the object class supports global |
---|
| 256 | * objects, then the search can be limited to a particular node |
---|
| 257 | * or allowed to encompass all nodes. |
---|
| 258 | */ |
---|
| 259 | typedef enum { |
---|
| 260 | OBJECTS_NAME_OR_ID_LOOKUP_SUCCESSFUL, |
---|
| 261 | OBJECTS_INVALID_NAME, |
---|
| 262 | OBJECTS_INVALID_ADDRESS, |
---|
| 263 | OBJECTS_INVALID_ID, |
---|
| 264 | OBJECTS_INVALID_NODE |
---|
| 265 | } Objects_Name_or_id_lookup_errors; |
---|
| 266 | |
---|
| 267 | /** |
---|
| 268 | * This macro defines the first entry in the |
---|
| 269 | * @ref Objects_Name_or_id_lookup_errors enumerated list. |
---|
| 270 | */ |
---|
| 271 | #define OBJECTS_NAME_ERRORS_FIRST OBJECTS_NAME_OR_ID_LOOKUP_SUCCESSFUL |
---|
| 272 | |
---|
| 273 | /** |
---|
| 274 | * This macro defines the last entry in the |
---|
| 275 | * @ref Objects_Name_or_id_lookup_errors enumerated list. |
---|
| 276 | */ |
---|
| 277 | #define OBJECTS_NAME_ERRORS_LAST OBJECTS_INVALID_NODE |
---|
| 278 | |
---|
| 279 | /** |
---|
| 280 | * @brief Converts an object name to an Id. |
---|
| 281 | * |
---|
| 282 | * This method converts an object name to an Id. It performs a look up |
---|
| 283 | * using the object information block for this object class. |
---|
| 284 | * |
---|
| 285 | * @param[in] information points to an object class information block. |
---|
| 286 | * @param[in] name is the name of the object to find. |
---|
| 287 | * @param[in] node is the set of nodes to search. |
---|
| 288 | * @param[in] id will contain the Id if the search is successful. |
---|
| 289 | * |
---|
| 290 | * @retval This method returns one of the values from the |
---|
| 291 | * @ref Objects_Name_or_id_lookup_errors enumeration to indicate |
---|
| 292 | * successful or failure. On success @a id will contain the Id of |
---|
| 293 | * the requested object. |
---|
| 294 | */ |
---|
| 295 | Objects_Name_or_id_lookup_errors _Objects_Name_to_id_u32( |
---|
| 296 | Objects_Information *information, |
---|
| 297 | uint32_t name, |
---|
| 298 | uint32_t node, |
---|
| 299 | Objects_Id *id |
---|
| 300 | ); |
---|
| 301 | |
---|
[c904df5] | 302 | typedef enum { |
---|
| 303 | OBJECTS_GET_BY_NAME_INVALID_NAME, |
---|
| 304 | OBJECTS_GET_BY_NAME_NAME_TOO_LONG, |
---|
| 305 | OBJECTS_GET_BY_NAME_NO_OBJECT |
---|
| 306 | } Objects_Get_by_name_error; |
---|
| 307 | |
---|
[a2e3f33] | 308 | /** |
---|
[c904df5] | 309 | * @brief Gets an object control block identified by its name. |
---|
[a2e3f33] | 310 | * |
---|
[c904df5] | 311 | * The object information must use string names. |
---|
[a2e3f33] | 312 | * |
---|
[c904df5] | 313 | * @param information The object information. Must not be NULL. |
---|
| 314 | * @param name The object name. |
---|
| 315 | * @param name_length_p Optional parameter to return the name length. |
---|
| 316 | * @param error The error indication in case of failure. Must not be NULL. |
---|
[a2e3f33] | 317 | * |
---|
[c904df5] | 318 | * @retval NULL No object exists for this name or invalid parameters. |
---|
| 319 | * @retval other The first object according to object index associated with |
---|
| 320 | * this name. |
---|
[a2e3f33] | 321 | */ |
---|
[c904df5] | 322 | Objects_Control *_Objects_Get_by_name( |
---|
| 323 | const Objects_Information *information, |
---|
| 324 | const char *name, |
---|
| 325 | size_t *name_length_p, |
---|
| 326 | Objects_Get_by_name_error *error |
---|
[a2e3f33] | 327 | ); |
---|
| 328 | |
---|
| 329 | /** |
---|
| 330 | * @brief Implements the common portion of the object Id to name directives. |
---|
| 331 | * |
---|
| 332 | * This function implements the common portion of the object Id |
---|
| 333 | * to name directives. This function returns the name |
---|
| 334 | * associated with object id. |
---|
| 335 | * |
---|
| 336 | * @param[in] id is the Id of the object whose name we are locating. |
---|
| 337 | * @param[in] name will contain the name of the object, if found. |
---|
| 338 | * |
---|
| 339 | * @retval This method returns one of the values from the |
---|
| 340 | * @ref Objects_Name_or_id_lookup_errors enumeration to indicate |
---|
| 341 | * successful or failure. On success @a name will contain the name of |
---|
| 342 | * the requested object. |
---|
| 343 | * |
---|
| 344 | * @note This function currently does not support string names. |
---|
| 345 | */ |
---|
| 346 | Objects_Name_or_id_lookup_errors _Objects_Id_to_name ( |
---|
| 347 | Objects_Id id, |
---|
| 348 | Objects_Name *name |
---|
| 349 | ); |
---|
| 350 | |
---|
[77e6eba7] | 351 | /** |
---|
| 352 | * @brief Maps the specified object identifier to the associated local object |
---|
| 353 | * control block. |
---|
| 354 | * |
---|
| 355 | * In this function interrupts are disabled during the object lookup. In case |
---|
| 356 | * an associated object exists, then interrupts remain disabled, otherwise the |
---|
| 357 | * previous interrupt state is restored. |
---|
| 358 | * |
---|
[88575577] | 359 | * @param id The object identifier. This is the first parameter since usual |
---|
| 360 | * callers get the object identifier as the first parameter themself. |
---|
[0a68d8e] | 361 | * @param lock_context The interrupt lock context. This is the second |
---|
| 362 | * parameter since usual callers get the interrupt lock context as the second |
---|
| 363 | * parameter themself. |
---|
[77e6eba7] | 364 | * @param information The object class information block. |
---|
| 365 | * |
---|
| 366 | * @retval NULL No associated object exists. |
---|
| 367 | * @retval other The pointer to the associated object control block. |
---|
| 368 | * Interrupts are now disabled and must be restored using the specified lock |
---|
| 369 | * context via _ISR_lock_ISR_enable() or _ISR_lock_Release_and_ISR_enable(). |
---|
| 370 | */ |
---|
[582bb23c] | 371 | Objects_Control *_Objects_Get( |
---|
[77e6eba7] | 372 | Objects_Id id, |
---|
[0a68d8e] | 373 | ISR_lock_Context *lock_context, |
---|
| 374 | const Objects_Information *information |
---|
[77e6eba7] | 375 | ); |
---|
| 376 | |
---|
[a2e3f33] | 377 | /** |
---|
| 378 | * @brief Maps object ids to object control blocks. |
---|
| 379 | * |
---|
| 380 | * This function maps object ids to object control blocks. |
---|
| 381 | * If id corresponds to a local object, then it returns |
---|
| 382 | * the_object control pointer which maps to id and location |
---|
| 383 | * is set to OBJECTS_LOCAL. If the object class supports global |
---|
| 384 | * objects and the object id is global and resides on a remote |
---|
| 385 | * node, then location is set to OBJECTS_REMOTE, and the_object |
---|
| 386 | * is undefined. Otherwise, location is set to OBJECTS_ERROR |
---|
| 387 | * and the_object is undefined. |
---|
| 388 | * |
---|
| 389 | * @param[in] id is the Id of the object whose name we are locating. |
---|
[d7a12be9] | 390 | * This is the first parameter since usual callers get the object identifier |
---|
| 391 | * as the first parameter themself. |
---|
| 392 | * @param[in] information points to an object class information block. |
---|
[a2e3f33] | 393 | * |
---|
| 394 | * @retval This method returns one of the values from the |
---|
| 395 | * @ref Objects_Name_or_id_lookup_errors enumeration to indicate |
---|
| 396 | * successful or failure. On success @a id will contain the Id of |
---|
| 397 | * the requested object. |
---|
| 398 | */ |
---|
| 399 | Objects_Control *_Objects_Get_no_protection( |
---|
[d7a12be9] | 400 | Objects_Id id, |
---|
| 401 | const Objects_Information *information |
---|
[a2e3f33] | 402 | ); |
---|
| 403 | |
---|
| 404 | /** |
---|
[ee710ef] | 405 | * Gets the next open object after the specified object identifier. |
---|
[474b9be] | 406 | * |
---|
| 407 | * Locks the object allocator mutex in case a next object exists. |
---|
[a2e3f33] | 408 | * |
---|
| 409 | * @param[in] id is the Id of the object whose name we are locating. |
---|
[36cd27c] | 410 | * This is the first parameter since usual callers get the object identifier |
---|
| 411 | * as the first parameter themself. |
---|
| 412 | * @param[in] information points to an object class information block. |
---|
[a2e3f33] | 413 | * @param[in] next_id_p is the Id of the next object we will look at. |
---|
| 414 | * |
---|
| 415 | * @retval This method returns the pointer to the object located or |
---|
| 416 | * NULL on error. |
---|
| 417 | */ |
---|
| 418 | Objects_Control *_Objects_Get_next( |
---|
[36cd27c] | 419 | Objects_Id id, |
---|
| 420 | const Objects_Information *information, |
---|
| 421 | Objects_Id *next_id_p |
---|
[a2e3f33] | 422 | ); |
---|
| 423 | |
---|
| 424 | /** |
---|
| 425 | * @brief Get object information. |
---|
| 426 | * |
---|
| 427 | * This function return the information structure given |
---|
| 428 | * an the API and Class. This can be done independent of |
---|
| 429 | * the existence of any objects created by the API. |
---|
| 430 | * |
---|
| 431 | * @param[in] the_api indicates the API for the information we want |
---|
| 432 | * @param[in] the_class indicates the Class for the information we want |
---|
| 433 | * |
---|
| 434 | * @retval This method returns a pointer to the Object Information Table |
---|
| 435 | * for the class of objects which corresponds to this object ID. |
---|
| 436 | */ |
---|
| 437 | Objects_Information *_Objects_Get_information( |
---|
| 438 | Objects_APIs the_api, |
---|
| 439 | uint16_t the_class |
---|
| 440 | ); |
---|
| 441 | |
---|
| 442 | /** |
---|
| 443 | * @brief Get information of an object from an ID. |
---|
| 444 | * |
---|
| 445 | * This function return the information structure given |
---|
| 446 | * an @a id of an object. |
---|
| 447 | * |
---|
| 448 | * @param[in] id is the object ID to get the information from |
---|
| 449 | * |
---|
| 450 | * @retval This method returns a pointer to the Object Information Table |
---|
| 451 | * for the class of objects which corresponds to this object ID. |
---|
| 452 | */ |
---|
| 453 | Objects_Information *_Objects_Get_information_id( |
---|
| 454 | Objects_Id id |
---|
| 455 | ); |
---|
| 456 | |
---|
| 457 | /** |
---|
| 458 | * @brief Gets object name in the form of a C string. |
---|
| 459 | * |
---|
| 460 | * This method objects the name of an object and returns its name |
---|
| 461 | * in the form of a C string. It attempts to be careful about |
---|
| 462 | * overflowing the user's string and about returning unprintable characters. |
---|
| 463 | * |
---|
| 464 | * @param[in] id is the object to obtain the name of |
---|
| 465 | * @param[in] length indicates the length of the caller's buffer |
---|
| 466 | * @param[in] name points a string which will be filled in. |
---|
| 467 | * |
---|
| 468 | * @retval This method returns @a name or NULL on error. @a *name will |
---|
| 469 | * contain the name if successful. |
---|
| 470 | */ |
---|
| 471 | char *_Objects_Get_name_as_string( |
---|
| 472 | Objects_Id id, |
---|
| 473 | size_t length, |
---|
| 474 | char *name |
---|
| 475 | ); |
---|
| 476 | |
---|
[b8bcebe] | 477 | /** |
---|
| 478 | * @brief Converts the specified object name to a text representation. |
---|
| 479 | * |
---|
| 480 | * Non-printable characters according to isprint() are converted to '*'. |
---|
| 481 | * |
---|
| 482 | * @param[in] name The object name. |
---|
| 483 | * @param[in] is_string Indicates if the object name is a string or a four |
---|
| 484 | * character array (32-bit unsigned integer). |
---|
| 485 | * @param[in] buffer The string buffer for the text representation. |
---|
| 486 | * @param[in] buffer_size The buffer size in characters. |
---|
| 487 | * |
---|
| 488 | * @retval The length of the text representation. May be greater than or equal |
---|
| 489 | * to the buffer size if truncation occurred. |
---|
| 490 | */ |
---|
| 491 | size_t _Objects_Name_to_string( |
---|
| 492 | Objects_Name name, |
---|
| 493 | bool is_string, |
---|
| 494 | char *buffer, |
---|
| 495 | size_t buffer_size |
---|
| 496 | ); |
---|
| 497 | |
---|
[a2e3f33] | 498 | /** |
---|
| 499 | * @brief Set objects name. |
---|
| 500 | * |
---|
| 501 | * This method sets the object name to either a copy of a string |
---|
| 502 | * or up to the first four characters of the string based upon |
---|
| 503 | * whether this object class uses strings for names. |
---|
| 504 | * |
---|
| 505 | * @param[in] information points to the object information structure |
---|
| 506 | * @param[in] the_object is the object to operate upon |
---|
| 507 | * @param[in] name is a pointer to the name to use |
---|
| 508 | * |
---|
| 509 | * @retval If successful, true is returned. Otherwise false is returned. |
---|
| 510 | */ |
---|
| 511 | bool _Objects_Set_name( |
---|
[7038271] | 512 | const Objects_Information *information, |
---|
| 513 | Objects_Control *the_object, |
---|
| 514 | const char *name |
---|
[a2e3f33] | 515 | ); |
---|
| 516 | |
---|
| 517 | /** |
---|
[7038271] | 518 | * @brief Removes object with a 32-bit integer name from its namespace. |
---|
[a2e3f33] | 519 | * |
---|
[7038271] | 520 | * @param[in] information The corresponding object information table. |
---|
| 521 | * @param[in] the_object The object. |
---|
| 522 | */ |
---|
| 523 | void _Objects_Namespace_remove_u32( |
---|
| 524 | const Objects_Information *information, |
---|
| 525 | Objects_Control *the_object |
---|
| 526 | ); |
---|
| 527 | |
---|
| 528 | /** |
---|
| 529 | * @brief Removes object with a string name from its namespace. |
---|
[a2e3f33] | 530 | * |
---|
[7038271] | 531 | * @param[in] information The corresponding object information table. |
---|
| 532 | * @param[in] the_object The object. |
---|
[a2e3f33] | 533 | */ |
---|
[7038271] | 534 | void _Objects_Namespace_remove_string( |
---|
| 535 | const Objects_Information *information, |
---|
| 536 | Objects_Control *the_object |
---|
[a2e3f33] | 537 | ); |
---|
| 538 | |
---|
| 539 | /** |
---|
| 540 | * @brief Close object. |
---|
| 541 | * |
---|
| 542 | * This function removes the_object control pointer and object name |
---|
| 543 | * in the Local Pointer and Local Name Tables. |
---|
| 544 | * |
---|
| 545 | * @param[in] information points to an Object Information Table |
---|
| 546 | * @param[in] the_object is a pointer to an object |
---|
| 547 | */ |
---|
| 548 | void _Objects_Close( |
---|
[7038271] | 549 | const Objects_Information *information, |
---|
| 550 | Objects_Control *the_object |
---|
[a2e3f33] | 551 | ); |
---|
| 552 | |
---|
| 553 | /** |
---|
| 554 | * @brief Returns the count of active objects. |
---|
| 555 | * |
---|
| 556 | * @param[in] information The object information table. |
---|
| 557 | * |
---|
| 558 | * @retval The count of active objects. |
---|
| 559 | */ |
---|
| 560 | Objects_Maximum _Objects_Active_count( |
---|
| 561 | const Objects_Information *information |
---|
| 562 | ); |
---|
| 563 | |
---|
[9c9c6a9] | 564 | RTEMS_INLINE_ROUTINE bool _Objects_Has_string_name( |
---|
| 565 | const Objects_Information *information |
---|
| 566 | ) |
---|
| 567 | { |
---|
| 568 | return information->name_length > 0; |
---|
| 569 | } |
---|
| 570 | |
---|
[d7665823] | 571 | RTEMS_INLINE_ROUTINE Objects_Maximum _Objects_Extend_size( |
---|
| 572 | const Objects_Information *information |
---|
| 573 | ) |
---|
| 574 | { |
---|
[8b0e752f] | 575 | return information->objects_per_block; |
---|
[d7665823] | 576 | } |
---|
| 577 | |
---|
[a2e3f33] | 578 | /** |
---|
| 579 | * This function returns true if the api is valid. |
---|
| 580 | * |
---|
| 581 | * @param[in] the_api is the api portion of an object ID. |
---|
| 582 | * |
---|
| 583 | * @return This method returns true if the specified api value is valid |
---|
| 584 | * and false otherwise. |
---|
| 585 | */ |
---|
| 586 | RTEMS_INLINE_ROUTINE bool _Objects_Is_api_valid( |
---|
| 587 | uint32_t the_api |
---|
| 588 | ) |
---|
| 589 | { |
---|
| 590 | if ( !the_api || the_api > OBJECTS_APIS_LAST ) |
---|
| 591 | return false; |
---|
| 592 | return true; |
---|
| 593 | } |
---|
| 594 | |
---|
| 595 | /** |
---|
| 596 | * This function returns true if the node is of the local object, and |
---|
| 597 | * false otherwise. |
---|
| 598 | * |
---|
| 599 | * @param[in] node is the node number and corresponds to the node number |
---|
| 600 | * portion of an object ID. |
---|
| 601 | * |
---|
| 602 | * @return This method returns true if the specified node is the local node |
---|
| 603 | * and false otherwise. |
---|
| 604 | */ |
---|
| 605 | RTEMS_INLINE_ROUTINE bool _Objects_Is_local_node( |
---|
| 606 | uint32_t node |
---|
| 607 | ) |
---|
| 608 | { |
---|
| 609 | return ( node == _Objects_Local_node ); |
---|
| 610 | } |
---|
| 611 | |
---|
| 612 | /** |
---|
| 613 | * This function returns true if the id is of a local object, and |
---|
| 614 | * false otherwise. |
---|
| 615 | * |
---|
| 616 | * @param[in] id is an object ID |
---|
| 617 | * |
---|
| 618 | * @return This method returns true if the specified object Id is local |
---|
| 619 | * and false otherwise. |
---|
| 620 | * |
---|
| 621 | * @note On a single processor configuration, this always returns true. |
---|
| 622 | */ |
---|
| 623 | RTEMS_INLINE_ROUTINE bool _Objects_Is_local_id( |
---|
| 624 | #if defined(RTEMS_MULTIPROCESSING) |
---|
| 625 | Objects_Id id |
---|
| 626 | #else |
---|
[f97536d] | 627 | Objects_Id id RTEMS_UNUSED |
---|
[a2e3f33] | 628 | #endif |
---|
| 629 | ) |
---|
| 630 | { |
---|
| 631 | #if defined(RTEMS_MULTIPROCESSING) |
---|
| 632 | return _Objects_Is_local_node( _Objects_Get_node(id) ); |
---|
| 633 | #else |
---|
| 634 | return true; |
---|
| 635 | #endif |
---|
| 636 | } |
---|
| 637 | |
---|
| 638 | /** |
---|
| 639 | * This function returns true if left and right are equal, |
---|
| 640 | * and false otherwise. |
---|
| 641 | * |
---|
| 642 | * @param[in] left is the Id on the left hand side of the comparison |
---|
| 643 | * @param[in] right is the Id on the right hand side of the comparison |
---|
| 644 | * |
---|
| 645 | * @return This method returns true if the specified object IDs are equal |
---|
| 646 | * and false otherwise. |
---|
| 647 | */ |
---|
| 648 | RTEMS_INLINE_ROUTINE bool _Objects_Are_ids_equal( |
---|
| 649 | Objects_Id left, |
---|
| 650 | Objects_Id right |
---|
| 651 | ) |
---|
| 652 | { |
---|
| 653 | return ( left == right ); |
---|
| 654 | } |
---|
| 655 | |
---|
[3899bc1a] | 656 | /** |
---|
| 657 | * Returns the identifier with the minimum index for the specified identifier. |
---|
| 658 | * |
---|
| 659 | * The specified identifier must have valid API, class and node fields. |
---|
| 660 | * |
---|
| 661 | * @param[in] id The identifier to be processed. |
---|
| 662 | * |
---|
| 663 | * @return The corresponding ID with the minimum index. |
---|
| 664 | */ |
---|
| 665 | RTEMS_INLINE_ROUTINE Objects_Id _Objects_Get_minimum_id( Objects_Id id ) |
---|
| 666 | { |
---|
| 667 | id &= ~OBJECTS_INDEX_MASK; |
---|
| 668 | id += (Objects_Id) OBJECTS_INDEX_MINIMUM << OBJECTS_INDEX_START_BIT; |
---|
| 669 | return id; |
---|
| 670 | } |
---|
| 671 | |
---|
[1c2d178] | 672 | /** |
---|
| 673 | * Returns the maximum index of the specified object class. |
---|
| 674 | * |
---|
| 675 | * @param[in] information The object information. |
---|
| 676 | * |
---|
| 677 | * @return The maximum index of the specified object class. |
---|
| 678 | */ |
---|
| 679 | RTEMS_INLINE_ROUTINE Objects_Maximum _Objects_Get_maximum_index( |
---|
| 680 | const Objects_Information *information |
---|
| 681 | ) |
---|
| 682 | { |
---|
| 683 | return _Objects_Get_index( information->maximum_id ); |
---|
| 684 | } |
---|
| 685 | |
---|
[8b0e752f] | 686 | /** |
---|
| 687 | * @brief Returns true if the automatic object extension (unlimited objects) is |
---|
| 688 | * enabled, otherwise false. |
---|
| 689 | * |
---|
| 690 | * @param[in] information The object information. |
---|
| 691 | * |
---|
| 692 | * @retval true The automatic object extension (unlimited objects) is enabled. |
---|
| 693 | * @retval false Otherwise. |
---|
| 694 | */ |
---|
| 695 | RTEMS_INLINE_ROUTINE Objects_Maximum _Objects_Is_auto_extend( |
---|
| 696 | const Objects_Information *information |
---|
| 697 | ) |
---|
| 698 | { |
---|
| 699 | return information->objects_per_block != 0; |
---|
| 700 | } |
---|
| 701 | |
---|
[a2e3f33] | 702 | /** |
---|
| 703 | * This function sets the pointer to the local_table object |
---|
| 704 | * referenced by the index. |
---|
| 705 | * |
---|
| 706 | * @param[in] information points to an Object Information Table |
---|
| 707 | * @param[in] index is the index of the object the caller wants to access |
---|
| 708 | * @param[in] the_object is the local object pointer |
---|
| 709 | * |
---|
| 710 | * @note This routine is ONLY to be called in places where the |
---|
| 711 | * index portion of the Id is known to be good. This is |
---|
| 712 | * OK since it is normally called from object create/init |
---|
| 713 | * or delete/destroy operations. |
---|
| 714 | */ |
---|
| 715 | |
---|
| 716 | RTEMS_INLINE_ROUTINE void _Objects_Set_local_object( |
---|
[7038271] | 717 | const Objects_Information *information, |
---|
| 718 | uint32_t index, |
---|
| 719 | Objects_Control *the_object |
---|
[a2e3f33] | 720 | ) |
---|
| 721 | { |
---|
| 722 | /* |
---|
| 723 | * This routine is ONLY to be called from places in the code |
---|
| 724 | * where the Id is known to be good. Therefore, this should NOT |
---|
| 725 | * occur in normal situations. |
---|
| 726 | */ |
---|
[3899bc1a] | 727 | _Assert( index >= OBJECTS_INDEX_MINIMUM ); |
---|
[1c2d178] | 728 | _Assert( index <= _Objects_Get_maximum_index( information ) ); |
---|
[a2e3f33] | 729 | |
---|
[3899bc1a] | 730 | information->local_table[ index - OBJECTS_INDEX_MINIMUM ] = the_object; |
---|
[a2e3f33] | 731 | } |
---|
| 732 | |
---|
| 733 | /** |
---|
| 734 | * This function sets the pointer to the local_table object |
---|
| 735 | * referenced by the index to a NULL so the object Id is invalid |
---|
| 736 | * after this call. |
---|
| 737 | * |
---|
| 738 | * @param[in] information points to an Object Information Table |
---|
| 739 | * @param[in] the_object is the local object pointer |
---|
| 740 | * |
---|
| 741 | * @note This routine is ONLY to be called in places where the |
---|
| 742 | * index portion of the Id is known to be good. This is |
---|
| 743 | * OK since it is normally called from object create/init |
---|
| 744 | * or delete/destroy operations. |
---|
| 745 | */ |
---|
| 746 | |
---|
| 747 | RTEMS_INLINE_ROUTINE void _Objects_Invalidate_Id( |
---|
[7038271] | 748 | const Objects_Information *information, |
---|
| 749 | Objects_Control *the_object |
---|
[a2e3f33] | 750 | ) |
---|
| 751 | { |
---|
[c562d0c] | 752 | _Assert( information != NULL ); |
---|
| 753 | _Assert( the_object != NULL ); |
---|
| 754 | |
---|
[a2e3f33] | 755 | _Objects_Set_local_object( |
---|
| 756 | information, |
---|
| 757 | _Objects_Get_index( the_object->id ), |
---|
| 758 | NULL |
---|
| 759 | ); |
---|
| 760 | } |
---|
| 761 | |
---|
| 762 | /** |
---|
| 763 | * This function places the_object control pointer and object name |
---|
| 764 | * in the Local Pointer and Local Name Tables, respectively. |
---|
| 765 | * |
---|
| 766 | * @param[in] information points to an Object Information Table |
---|
| 767 | * @param[in] the_object is a pointer to an object |
---|
| 768 | * @param[in] name is the name of the object to make accessible |
---|
| 769 | */ |
---|
| 770 | RTEMS_INLINE_ROUTINE void _Objects_Open( |
---|
| 771 | Objects_Information *information, |
---|
| 772 | Objects_Control *the_object, |
---|
| 773 | Objects_Name name |
---|
| 774 | ) |
---|
| 775 | { |
---|
[c562d0c] | 776 | _Assert( information != NULL ); |
---|
| 777 | _Assert( the_object != NULL ); |
---|
| 778 | |
---|
[3b5e7dc] | 779 | the_object->name = name; |
---|
| 780 | |
---|
[a2e3f33] | 781 | _Objects_Set_local_object( |
---|
| 782 | information, |
---|
| 783 | _Objects_Get_index( the_object->id ), |
---|
| 784 | the_object |
---|
| 785 | ); |
---|
| 786 | } |
---|
| 787 | |
---|
| 788 | /** |
---|
| 789 | * This function places the_object control pointer and object name |
---|
| 790 | * in the Local Pointer and Local Name Tables, respectively. |
---|
| 791 | * |
---|
| 792 | * @param[in] information points to an Object Information Table |
---|
| 793 | * @param[in] the_object is a pointer to an object |
---|
| 794 | * @param[in] name is the name of the object to make accessible |
---|
| 795 | */ |
---|
| 796 | RTEMS_INLINE_ROUTINE void _Objects_Open_u32( |
---|
[7038271] | 797 | const Objects_Information *information, |
---|
| 798 | Objects_Control *the_object, |
---|
| 799 | uint32_t name |
---|
[a2e3f33] | 800 | ) |
---|
| 801 | { |
---|
[9c9c6a9] | 802 | _Assert( !_Objects_Has_string_name( information ) ); |
---|
[3b5e7dc] | 803 | the_object->name.name_u32 = name; |
---|
| 804 | |
---|
[a2e3f33] | 805 | _Objects_Set_local_object( |
---|
| 806 | information, |
---|
| 807 | _Objects_Get_index( the_object->id ), |
---|
| 808 | the_object |
---|
| 809 | ); |
---|
| 810 | } |
---|
| 811 | |
---|
| 812 | /** |
---|
| 813 | * This function places the_object control pointer and object name |
---|
| 814 | * in the Local Pointer and Local Name Tables, respectively. |
---|
| 815 | * |
---|
| 816 | * @param[in] information points to an Object Information Table |
---|
| 817 | * @param[in] the_object is a pointer to an object |
---|
| 818 | * @param[in] name is the name of the object to make accessible |
---|
| 819 | */ |
---|
| 820 | RTEMS_INLINE_ROUTINE void _Objects_Open_string( |
---|
[7038271] | 821 | const Objects_Information *information, |
---|
| 822 | Objects_Control *the_object, |
---|
| 823 | const char *name |
---|
[a2e3f33] | 824 | ) |
---|
| 825 | { |
---|
[9c9c6a9] | 826 | _Assert( _Objects_Has_string_name( information ) ); |
---|
[7038271] | 827 | the_object->name.name_p = name; |
---|
[3b5e7dc] | 828 | |
---|
[a2e3f33] | 829 | _Objects_Set_local_object( |
---|
| 830 | information, |
---|
| 831 | _Objects_Get_index( the_object->id ), |
---|
| 832 | the_object |
---|
| 833 | ); |
---|
| 834 | } |
---|
| 835 | |
---|
[23fec9f0] | 836 | /** |
---|
| 837 | * @brief Locks the object allocator mutex. |
---|
| 838 | * |
---|
| 839 | * While holding the allocator mutex the executing thread is protected from |
---|
| 840 | * asynchronous thread restart and deletion. |
---|
| 841 | * |
---|
| 842 | * The usage of the object allocator mutex with the thread life protection |
---|
| 843 | * makes it possible to allocate and free objects without thread dispatching |
---|
| 844 | * disabled. The usage of a unified workspace and unlimited objects may lead |
---|
| 845 | * to heap fragmentation. Thus the execution time of the _Objects_Allocate() |
---|
| 846 | * function may increase during system run-time. |
---|
| 847 | * |
---|
| 848 | * @see _Objects_Allocator_unlock() and _Objects_Allocate(). |
---|
| 849 | */ |
---|
| 850 | RTEMS_INLINE_ROUTINE void _Objects_Allocator_lock( void ) |
---|
| 851 | { |
---|
| 852 | _RTEMS_Lock_allocator(); |
---|
| 853 | } |
---|
| 854 | |
---|
| 855 | /** |
---|
| 856 | * @brief Unlocks the object allocator mutex. |
---|
| 857 | * |
---|
| 858 | * In case the mutex is fully unlocked, then this function restores the |
---|
| 859 | * previous thread life protection state and thus may not return if the |
---|
| 860 | * executing thread was restarted or deleted in the mean-time. |
---|
| 861 | */ |
---|
| 862 | RTEMS_INLINE_ROUTINE void _Objects_Allocator_unlock( void ) |
---|
| 863 | { |
---|
| 864 | _RTEMS_Unlock_allocator(); |
---|
| 865 | } |
---|
| 866 | |
---|
[c904df5] | 867 | RTEMS_INLINE_ROUTINE bool _Objects_Allocator_is_owner( void ) |
---|
| 868 | { |
---|
| 869 | return _RTEMS_Allocator_is_owner(); |
---|
| 870 | } |
---|
| 871 | |
---|
[a2e3f33] | 872 | /** @} */ |
---|
| 873 | |
---|
| 874 | #ifdef __cplusplus |
---|
| 875 | } |
---|
| 876 | #endif |
---|
| 877 | |
---|
| 878 | #if defined(RTEMS_MULTIPROCESSING) |
---|
| 879 | #include <rtems/score/objectmp.h> |
---|
| 880 | #endif |
---|
| 881 | |
---|
| 882 | |
---|
| 883 | #endif |
---|
| 884 | /* end of include file */ |
---|