[11874561] | 1 | /** |
---|
| 2 | * @file rtems/score/object.h |
---|
[9c191ee] | 3 | * |
---|
| 4 | * |
---|
[ac7d5ef0] | 5 | * This include file contains all the constants and structures associated |
---|
[3a4ae6c] | 6 | * with the Object Handler. This Handler provides mechanisms which |
---|
[a0ed4ed] | 7 | * can be used to initialize and manipulate all objects which have |
---|
[3a4ae6c] | 8 | * ids. |
---|
[9c191ee] | 9 | */ |
---|
| 10 | |
---|
| 11 | /* |
---|
[6a07436] | 12 | * COPYRIGHT (c) 1989-2006. |
---|
[ac7d5ef0] | 13 | * On-Line Applications Research Corporation (OAR). |
---|
| 14 | * |
---|
[98e4ebf5] | 15 | * The license and distribution terms for this file may be |
---|
| 16 | * found in the file LICENSE in this distribution or at |
---|
[dd687d97] | 17 | * http://www.rtems.com/license/LICENSE. |
---|
[ac7d5ef0] | 18 | * |
---|
| 19 | * $Id$ |
---|
| 20 | */ |
---|
| 21 | |
---|
[092f142a] | 22 | #ifndef _RTEMS_SCORE_OBJECT_H |
---|
| 23 | #define _RTEMS_SCORE_OBJECT_H |
---|
[ac7d5ef0] | 24 | |
---|
| 25 | #ifdef __cplusplus |
---|
| 26 | extern "C" { |
---|
| 27 | #endif |
---|
| 28 | |
---|
[5e9b32b] | 29 | #include <rtems/score/chain.h> |
---|
[c6f111b] | 30 | #include <rtems/score/isr.h> |
---|
[ac7d5ef0] | 31 | |
---|
[6a07436] | 32 | /** |
---|
[ac7d5ef0] | 33 | * The following type defines the control block used to manage |
---|
| 34 | * object names. |
---|
| 35 | */ |
---|
[3235ad9] | 36 | typedef void * Objects_Name; |
---|
| 37 | |
---|
[6a07436] | 38 | /** |
---|
[3235ad9] | 39 | * Space for object names is allocated in multiples of this. |
---|
| 40 | * |
---|
| 41 | * NOTE: Must be a power of 2. Matches the name manipulation routines. |
---|
| 42 | */ |
---|
[50269c46] | 43 | #define OBJECTS_NAME_ALIGNMENT sizeof( uint32_t ) |
---|
[3235ad9] | 44 | |
---|
[6a07436] | 45 | /** |
---|
[3235ad9] | 46 | * Functions which compare names are prototyped like this. |
---|
| 47 | */ |
---|
| 48 | typedef boolean (*Objects_Name_comparators)( |
---|
| 49 | void * /* name_1 */, |
---|
| 50 | void * /* name_2 */, |
---|
[712fe15] | 51 | uint16_t /* length */ |
---|
[3235ad9] | 52 | ); |
---|
[ac7d5ef0] | 53 | |
---|
[85b7605] | 54 | #if defined(RTEMS_USE_16_BIT_OBJECT) |
---|
[6a07436] | 55 | /** |
---|
[85b7605] | 56 | * The following type defines the control block used to manage |
---|
| 57 | * object IDs. The format is as follows (0=LSB): |
---|
| 58 | * |
---|
| 59 | * Bits 0 .. 7 = index (up to 254 objects of a type) |
---|
| 60 | * Bits 8 .. 10 = API (up to 7 API classes) |
---|
| 61 | * Bits 11 .. 15 = class (up to 31 object types per API) |
---|
| 62 | */ |
---|
| 63 | typedef uint16_t Objects_Id; |
---|
[6a07436] | 64 | |
---|
| 65 | /** |
---|
| 66 | * This type is used to store the maximum number of allowed objects |
---|
| 67 | * of each type. |
---|
| 68 | */ |
---|
[85b7605] | 69 | typedef uint8_t Objects_Maximum; |
---|
| 70 | |
---|
| 71 | #define OBJECTS_INDEX_START_BIT 0 |
---|
| 72 | #define OBJECTS_API_START_BIT 8 |
---|
| 73 | #define OBJECTS_CLASS_START_BIT 11 |
---|
| 74 | |
---|
[50269c46] | 75 | #define OBJECTS_INDEX_MASK (Objects_Id)0x00ff |
---|
| 76 | #define OBJECTS_API_MASK (Objects_Id)0x0700 |
---|
| 77 | #define OBJECTS_CLASS_MASK (Objects_Id)0xF800 |
---|
| 78 | |
---|
| 79 | #define OBJECTS_INDEX_VALID_BITS (Objects_Id)0x00ff |
---|
| 80 | #define OBJECTS_API_VALID_BITS (Objects_Id)0x0007 |
---|
| 81 | /* OBJECTS_NODE_VALID_BITS should not be used with 16 bit Ids */ |
---|
| 82 | #define OBJECTS_CLASS_VALID_BITS (Objects_Id)0x001f |
---|
| 83 | |
---|
| 84 | #define OBJECTS_UNLIMITED_OBJECTS 0x8000 |
---|
[85b7605] | 85 | |
---|
[6a07436] | 86 | #define OBJECTS_ID_INITIAL_INDEX (0) |
---|
| 87 | #define OBJECTS_ID_FINAL_INDEX (0xff) |
---|
| 88 | |
---|
[85b7605] | 89 | #else |
---|
[6a07436] | 90 | /** |
---|
[ac7d5ef0] | 91 | * The following type defines the control block used to manage |
---|
[95fbca1] | 92 | * object IDs. The format is as follows (0=LSB): |
---|
| 93 | * |
---|
[ef9505a9] | 94 | * Bits 0 .. 15 = index (up to 65535 objects of a type) |
---|
| 95 | * Bits 16 .. 23 = node (up to 255 nodes) |
---|
| 96 | * Bits 24 .. 26 = API (up to 7 API classes) |
---|
| 97 | * Bits 27 .. 31 = class (up to 31 object types per API) |
---|
[ac7d5ef0] | 98 | */ |
---|
[d6154c7] | 99 | typedef uint32_t Objects_Id; |
---|
[6a07436] | 100 | |
---|
| 101 | /** |
---|
| 102 | * This type is used to store the maximum number of allowed objects |
---|
| 103 | * of each type. |
---|
| 104 | */ |
---|
[85b7605] | 105 | typedef uint16_t Objects_Maximum; |
---|
[ac7d5ef0] | 106 | |
---|
[6a07436] | 107 | /** |
---|
| 108 | * This is the bit position of the starting bit of the index portion of |
---|
| 109 | * the object Id. |
---|
| 110 | */ |
---|
[95fbca1] | 111 | #define OBJECTS_INDEX_START_BIT 0 |
---|
[6a07436] | 112 | |
---|
| 113 | |
---|
| 114 | /** |
---|
| 115 | * This is the bit position of the starting bit of the node portion of |
---|
| 116 | * the object Id. |
---|
| 117 | */ |
---|
[95fbca1] | 118 | #define OBJECTS_NODE_START_BIT 16 |
---|
[6a07436] | 119 | |
---|
| 120 | /** |
---|
| 121 | * This is the bit position of the starting bit of the API portion of |
---|
| 122 | * the object Id. |
---|
| 123 | */ |
---|
[ef9505a9] | 124 | #define OBJECTS_API_START_BIT 24 |
---|
[6a07436] | 125 | |
---|
| 126 | /** |
---|
| 127 | * This is the bit position of the starting bit of the class portion of |
---|
| 128 | * the object Id. |
---|
| 129 | */ |
---|
[ef9505a9] | 130 | #define OBJECTS_CLASS_START_BIT 27 |
---|
[95fbca1] | 131 | |
---|
[6a07436] | 132 | /** |
---|
| 133 | * This mask is used to extract the index portion of an object Id. |
---|
| 134 | */ |
---|
[2728d9cf] | 135 | #define OBJECTS_INDEX_MASK (Objects_Id)0x0000ffff |
---|
[6a07436] | 136 | |
---|
| 137 | /** |
---|
| 138 | * This mask is used to extract the node portion of an object Id. |
---|
| 139 | */ |
---|
[2728d9cf] | 140 | #define OBJECTS_NODE_MASK (Objects_Id)0x00ff0000 |
---|
[6a07436] | 141 | |
---|
| 142 | /** |
---|
| 143 | * This mask is used to extract the API portion of an object Id. |
---|
| 144 | */ |
---|
[2728d9cf] | 145 | #define OBJECTS_API_MASK (Objects_Id)0x07000000 |
---|
[6a07436] | 146 | |
---|
| 147 | /** |
---|
| 148 | * This mask is used to extract the class portion of an object Id. |
---|
| 149 | */ |
---|
[2728d9cf] | 150 | #define OBJECTS_CLASS_MASK (Objects_Id)0xf8000000 |
---|
| 151 | |
---|
[6a07436] | 152 | /** |
---|
| 153 | * This mask represents the bits that is used to ensure no extra bits |
---|
| 154 | * are set after shifting to extract the index portion of an object Id. |
---|
| 155 | */ |
---|
[2728d9cf] | 156 | #define OBJECTS_INDEX_VALID_BITS (Objects_Id)0x0000ffff |
---|
[6a07436] | 157 | |
---|
| 158 | /** |
---|
| 159 | * This mask represents the bits that is used to ensure no extra bits |
---|
| 160 | * are set after shifting to extract the node portion of an object Id. |
---|
| 161 | */ |
---|
[2728d9cf] | 162 | #define OBJECTS_NODE_VALID_BITS (Objects_Id)0x000000ff |
---|
[6a07436] | 163 | |
---|
| 164 | /** |
---|
| 165 | * This mask represents the bits that is used to ensure no extra bits |
---|
| 166 | * are set after shifting to extract the API portion of an object Id. |
---|
| 167 | */ |
---|
[2728d9cf] | 168 | #define OBJECTS_API_VALID_BITS (Objects_Id)0x00000007 |
---|
[6a07436] | 169 | |
---|
| 170 | /** |
---|
| 171 | * This mask represents the bits that is used to ensure no extra bits |
---|
| 172 | * are set after shifting to extract the class portion of an object Id. |
---|
| 173 | */ |
---|
[2728d9cf] | 174 | #define OBJECTS_CLASS_VALID_BITS (Objects_Id)0x0000001f |
---|
[50269c46] | 175 | |
---|
[6a07436] | 176 | /** |
---|
[50269c46] | 177 | * Mask to enable unlimited objects. This is used in the configuration |
---|
| 178 | * table when specifying the number of configured objects. |
---|
| 179 | */ |
---|
| 180 | #define OBJECTS_UNLIMITED_OBJECTS 0x80000000 |
---|
| 181 | |
---|
[6a07436] | 182 | /** |
---|
| 183 | * This is the lowest value for the index portion of an object Id. |
---|
| 184 | */ |
---|
| 185 | #define OBJECTS_ID_INITIAL_INDEX (0) |
---|
| 186 | |
---|
| 187 | /** |
---|
| 188 | * This is the highest value for the index portion of an object Id. |
---|
| 189 | */ |
---|
| 190 | #define OBJECTS_ID_FINAL_INDEX (0xff) |
---|
[85b7605] | 191 | #endif |
---|
[95fbca1] | 192 | |
---|
[6a07436] | 193 | /** |
---|
[95fbca1] | 194 | * This enumerated type is used in the class field of the object ID. |
---|
| 195 | */ |
---|
| 196 | typedef enum { |
---|
[ef9505a9] | 197 | OBJECTS_NO_API = 0, |
---|
| 198 | OBJECTS_INTERNAL_API = 1, |
---|
| 199 | OBJECTS_CLASSIC_API = 2, |
---|
| 200 | OBJECTS_POSIX_API = 3, |
---|
| 201 | OBJECTS_ITRON_API = 4 |
---|
| 202 | } Objects_APIs; |
---|
| 203 | |
---|
[6a07436] | 204 | /** This macro is used to generically specify the last API index. */ |
---|
[ef9505a9] | 205 | #define OBJECTS_APIS_LAST OBJECTS_ITRON_API |
---|
| 206 | |
---|
[6a07436] | 207 | /** |
---|
| 208 | * This enumerated type is used in the class field of the object ID |
---|
| 209 | * for RTEMS internal object classes. |
---|
| 210 | */ |
---|
[ef9505a9] | 211 | typedef enum { |
---|
| 212 | OBJECTS_INTERNAL_NO_CLASS = 0, |
---|
| 213 | OBJECTS_INTERNAL_THREADS = 1, |
---|
| 214 | OBJECTS_INTERNAL_MUTEXES = 2 |
---|
| 215 | } Objects_Internal_API; |
---|
| 216 | |
---|
[6a07436] | 217 | /** This macro is used to generically specify the last API index. */ |
---|
[ef9505a9] | 218 | #define OBJECTS_INTERNAL_CLASSES_LAST OBJECTS_INTERNAL_MUTEXES |
---|
| 219 | |
---|
[6a07436] | 220 | /** |
---|
| 221 | * This enumerated type is used in the class field of the object ID |
---|
| 222 | * for the RTEMS Classic API. |
---|
| 223 | */ |
---|
[ef9505a9] | 224 | typedef enum { |
---|
| 225 | OBJECTS_CLASSIC_NO_CLASS = 0, |
---|
| 226 | OBJECTS_RTEMS_TASKS = 1, |
---|
| 227 | OBJECTS_RTEMS_TIMERS = 2, |
---|
| 228 | OBJECTS_RTEMS_SEMAPHORES = 3, |
---|
| 229 | OBJECTS_RTEMS_MESSAGE_QUEUES = 4, |
---|
| 230 | OBJECTS_RTEMS_PARTITIONS = 5, |
---|
| 231 | OBJECTS_RTEMS_REGIONS = 6, |
---|
| 232 | OBJECTS_RTEMS_PORTS = 7, |
---|
| 233 | OBJECTS_RTEMS_PERIODS = 8, |
---|
[9c191ee] | 234 | OBJECTS_RTEMS_EXTENSIONS = 9, |
---|
| 235 | OBJECTS_RTEMS_BARRIERS = 10 |
---|
[ef9505a9] | 236 | } Objects_Classic_API; |
---|
| 237 | |
---|
[6a07436] | 238 | /** This macro is used to generically specify the last API index. */ |
---|
[f41dd23] | 239 | #define OBJECTS_RTEMS_CLASSES_LAST OBJECTS_RTEMS_BARRIERS |
---|
[ef9505a9] | 240 | |
---|
[6a07436] | 241 | /** |
---|
| 242 | * This enumerated type is used in the class field of the object ID |
---|
| 243 | * for the POSIX API. |
---|
| 244 | */ |
---|
[ef9505a9] | 245 | typedef enum { |
---|
| 246 | OBJECTS_POSIX_NO_CLASS = 0, |
---|
| 247 | OBJECTS_POSIX_THREADS = 1, |
---|
| 248 | OBJECTS_POSIX_KEYS = 2, |
---|
| 249 | OBJECTS_POSIX_INTERRUPTS = 3, |
---|
| 250 | OBJECTS_POSIX_MESSAGE_QUEUE_FDS = 4, |
---|
| 251 | OBJECTS_POSIX_MESSAGE_QUEUES = 5, |
---|
| 252 | OBJECTS_POSIX_MUTEXES = 6, |
---|
| 253 | OBJECTS_POSIX_SEMAPHORES = 7, |
---|
[0243b0d] | 254 | OBJECTS_POSIX_CONDITION_VARIABLES = 8, |
---|
[9c191ee] | 255 | OBJECTS_POSIX_TIMERS = 9, |
---|
| 256 | OBJECTS_POSIX_BARRIERS = 10, |
---|
| 257 | OBJECTS_POSIX_SPINLOCKS = 11, |
---|
| 258 | OBJECTS_POSIX_RWLOCKS = 12 |
---|
[ef9505a9] | 259 | } Objects_POSIX_API; |
---|
| 260 | |
---|
[6a07436] | 261 | /** This macro is used to generically specify the last API index. */ |
---|
[9c191ee] | 262 | #define OBJECTS_POSIX_CLASSES_LAST OBJECTS_POSIX_RWLOCKS |
---|
[ef9505a9] | 263 | |
---|
[6a07436] | 264 | /** |
---|
| 265 | * This enumerated type is used in the class field of the object ID |
---|
| 266 | * for the ITRON API. |
---|
| 267 | */ |
---|
[ef9505a9] | 268 | typedef enum { |
---|
| 269 | OBJECTS_ITRON_NO_CLASS = 0, |
---|
| 270 | OBJECTS_ITRON_TASKS = 1, |
---|
| 271 | OBJECTS_ITRON_EVENTFLAGS = 2, |
---|
| 272 | OBJECTS_ITRON_MAILBOXES = 3, |
---|
| 273 | OBJECTS_ITRON_MESSAGE_BUFFERS = 4, |
---|
| 274 | OBJECTS_ITRON_PORTS = 5, |
---|
| 275 | OBJECTS_ITRON_SEMAPHORES = 6, |
---|
| 276 | OBJECTS_ITRON_VARIABLE_MEMORY_POOLS = 7, |
---|
| 277 | OBJECTS_ITRON_FIXED_MEMORY_POOLS = 8 |
---|
| 278 | } Objects_ITRON_API; |
---|
| 279 | |
---|
[6a07436] | 280 | /** This macro is used to generically specify the last API index. */ |
---|
[ef9505a9] | 281 | #define OBJECTS_ITRON_CLASSES_LAST OBJECTS_ITRON_FIXED_MEMORY_POOLS |
---|
[5250ff39] | 282 | |
---|
[6a07436] | 283 | /** |
---|
[ac7d5ef0] | 284 | * This enumerated type lists the locations which may be returned |
---|
| 285 | * by _Objects_Get. These codes indicate the success of locating |
---|
| 286 | * an object with the specified ID. |
---|
| 287 | */ |
---|
| 288 | typedef enum { |
---|
| 289 | OBJECTS_LOCAL = 0, /* object is local */ |
---|
| 290 | OBJECTS_REMOTE = 1, /* object is remote */ |
---|
| 291 | OBJECTS_ERROR = 2 /* id was invalid */ |
---|
[85b7605] | 292 | } Objects_Locations; |
---|
[ac7d5ef0] | 293 | |
---|
[6a07436] | 294 | /** |
---|
[ef9505a9] | 295 | * The following type defines the callout used when a local task |
---|
| 296 | * is extracted from a remote thread queue (i.e. it's proxy must |
---|
| 297 | * extracted from the remote queue). |
---|
| 298 | */ |
---|
| 299 | typedef void ( *Objects_Thread_queue_Extract_callout )( void * ); |
---|
| 300 | |
---|
[6a07436] | 301 | /** |
---|
[ac7d5ef0] | 302 | * The following defines the Object Control Block used to manage |
---|
| 303 | * each object local to this node. |
---|
| 304 | */ |
---|
| 305 | typedef struct { |
---|
[6a07436] | 306 | /** This is the chain node portion of an object. */ |
---|
[f4a8ee1] | 307 | Chain_Node Node; |
---|
[6a07436] | 308 | /** This is the object's ID. */ |
---|
[f4a8ee1] | 309 | Objects_Id id; |
---|
[6a07436] | 310 | /** This is the object's name. */ |
---|
[f4a8ee1] | 311 | Objects_Name name; |
---|
[85b7605] | 312 | } Objects_Control; |
---|
[ac7d5ef0] | 313 | |
---|
[6a07436] | 314 | /** |
---|
[ac7d5ef0] | 315 | * The following defines the structure for the information used to |
---|
| 316 | * manage each class of objects. |
---|
| 317 | */ |
---|
| 318 | typedef struct { |
---|
[6a07436] | 319 | /** This field indicates the API of this object class. */ |
---|
| 320 | Objects_APIs the_api; |
---|
| 321 | /** This is the class of this object set. */ |
---|
| 322 | uint16_t the_class; |
---|
| 323 | /** This is the minimum valid id of this object class. */ |
---|
| 324 | Objects_Id minimum_id; |
---|
| 325 | /** This is the maximum valid id of this object class. */ |
---|
| 326 | Objects_Id maximum_id; |
---|
| 327 | /** This is the maximum number of objects in this class. */ |
---|
| 328 | Objects_Maximum maximum; |
---|
| 329 | /** This is the TRUE if unlimited objects in this class. */ |
---|
| 330 | boolean auto_extend; |
---|
| 331 | /** This is the number of objects in a block. */ |
---|
| 332 | uint32_t allocation_size; |
---|
| 333 | /** This is the size in bytes of each object instance. */ |
---|
[7a5e8fb6] | 334 | size_t size; |
---|
[6a07436] | 335 | /** This points to the table of local objects. */ |
---|
[f4a8ee1] | 336 | Objects_Control **local_table; |
---|
[6a07436] | 337 | /** This points to the table of local object names. */ |
---|
[f4a8ee1] | 338 | Objects_Name *name_table; |
---|
[6a07436] | 339 | /** This is the chain of inactive control blocks. */ |
---|
| 340 | Chain_Control Inactive; |
---|
| 341 | /** This is the number of objects on the Inactive list. */ |
---|
| 342 | Objects_Maximum inactive; |
---|
| 343 | /** This is the number of inactive objects per block. */ |
---|
| 344 | uint32_t *inactive_per_block; |
---|
| 345 | /** This is a table to the chain of inactive object memory blocks. */ |
---|
| 346 | void **object_blocks; |
---|
| 347 | /** This is the TRUE if names are strings. */ |
---|
| 348 | boolean is_string; |
---|
| 349 | /** This is the maximum length of names. */ |
---|
| 350 | uint16_t name_length; |
---|
| 351 | /** This is this object class' method called when extracting a thread. */ |
---|
[9b3f187] | 352 | Objects_Thread_queue_Extract_callout extract; |
---|
[ef9505a9] | 353 | #if defined(RTEMS_MULTIPROCESSING) |
---|
[6a07436] | 354 | /** This is this object class' pointer to the global name table */ |
---|
| 355 | Chain_Control *global_table; |
---|
[ef9505a9] | 356 | #endif |
---|
[ac7d5ef0] | 357 | } Objects_Information; |
---|
| 358 | |
---|
[6a07436] | 359 | /** |
---|
| 360 | * The following is referenced to the node number of the local node. |
---|
[ac7d5ef0] | 361 | */ |
---|
[85b7605] | 362 | #if defined(RTEMS_MULTIPROCESSING) |
---|
[0337a9c5] | 363 | SCORE_EXTERN uint16_t _Objects_Local_node; |
---|
[85b7605] | 364 | #else |
---|
[0337a9c5] | 365 | #define _Objects_Local_node ((uint16_t)1) |
---|
[6a07436] | 366 | #endif |
---|
| 367 | |
---|
| 368 | /** |
---|
| 369 | * The following is referenced to the number of nodes in the system. |
---|
| 370 | */ |
---|
| 371 | #if defined(RTEMS_MULTIPROCESSING) |
---|
| 372 | SCORE_EXTERN uint16_t _Objects_Maximum_nodes; |
---|
| 373 | #else |
---|
[85b7605] | 374 | #define _Objects_Maximum_nodes 1 |
---|
| 375 | #endif |
---|
[ac7d5ef0] | 376 | |
---|
[6a07436] | 377 | /** |
---|
[ef9505a9] | 378 | * The following is the list of information blocks per API for each object |
---|
[5250ff39] | 379 | * class. From the ID, we can go to one of these information blocks, |
---|
| 380 | * and obtain a pointer to the appropriate object control block. |
---|
| 381 | */ |
---|
[ef9505a9] | 382 | SCORE_EXTERN Objects_Information |
---|
| 383 | **_Objects_Information_table[OBJECTS_APIS_LAST + 1]; |
---|
[5250ff39] | 384 | |
---|
[6a07436] | 385 | /** |
---|
[ac7d5ef0] | 386 | * The following defines the constant which may be used |
---|
| 387 | * with _Objects_Get to manipulate the calling task. |
---|
| 388 | */ |
---|
[95fbca1] | 389 | #define OBJECTS_ID_OF_SELF ((Objects_Id) 0) |
---|
[ac7d5ef0] | 390 | |
---|
[6a07436] | 391 | /** |
---|
| 392 | * The following constant is used to specify that a name to ID search |
---|
| 393 | * should search through all nodes. |
---|
[ac7d5ef0] | 394 | */ |
---|
[3a4ae6c] | 395 | #define OBJECTS_SEARCH_ALL_NODES 0 |
---|
[6a07436] | 396 | |
---|
| 397 | /** |
---|
| 398 | * The following constant is used to specify that a name to ID search |
---|
| 399 | * should search through all nodes except the current node. |
---|
| 400 | */ |
---|
[3a4ae6c] | 401 | #define OBJECTS_SEARCH_OTHER_NODES 0x7FFFFFFE |
---|
[ac7d5ef0] | 402 | |
---|
[6a07436] | 403 | /** |
---|
| 404 | * The following constant is used to specify that a name to ID search |
---|
| 405 | * should search only on this node. |
---|
[b06e68ef] | 406 | */ |
---|
[6a07436] | 407 | #define OBJECTS_SEARCH_LOCAL_NODE 0x7FFFFFFF |
---|
[b06e68ef] | 408 | |
---|
[6a07436] | 409 | /** |
---|
| 410 | * The following constant is used to specify that a name to ID search |
---|
| 411 | * is being asked for the ID of the currently executing task. |
---|
| 412 | */ |
---|
| 413 | #define OBJECTS_WHO_AM_I 0 |
---|
[b06e68ef] | 414 | |
---|
[6a07436] | 415 | /** |
---|
| 416 | * This macros calculates the lowest ID for the specified api, class, |
---|
| 417 | * and node. |
---|
| 418 | */ |
---|
[ef9505a9] | 419 | #define OBJECTS_ID_INITIAL(_api, _class, _node) \ |
---|
| 420 | _Objects_Build_id( (_api), (_class), (_node), OBJECTS_ID_INITIAL_INDEX ) |
---|
[6a07436] | 421 | |
---|
| 422 | /** |
---|
| 423 | * This macro specifies the highest object ID value |
---|
| 424 | */ |
---|
[3a4ae6c] | 425 | #define OBJECTS_ID_FINAL ((Objects_Id)~0) |
---|
[b06e68ef] | 426 | |
---|
[6a07436] | 427 | /** |
---|
[ac7d5ef0] | 428 | * This function performs the initialization necessary for this handler. |
---|
| 429 | * |
---|
[6a07436] | 430 | * @param[in] node indicates the identifying number of this node. |
---|
| 431 | * @param[in] maximum_nodes is the maximum number of nodes in this system. |
---|
| 432 | * @param[in] maximum_global_objects is maximum number of global objects |
---|
| 433 | * concurrently offered in the system. |
---|
[ac7d5ef0] | 434 | */ |
---|
| 435 | void _Objects_Handler_initialization( |
---|
[d6154c7] | 436 | uint32_t node, |
---|
| 437 | uint32_t maximum_nodes, |
---|
| 438 | uint32_t maximum_global_objects |
---|
[ac7d5ef0] | 439 | ); |
---|
| 440 | |
---|
[6a07436] | 441 | /** |
---|
[f4a8ee1] | 442 | * This function extends an object class information record. |
---|
[6a07436] | 443 | * |
---|
| 444 | * @param[in] information points to an object class information block. |
---|
[f4a8ee1] | 445 | */ |
---|
| 446 | void _Objects_Extend_information( |
---|
| 447 | Objects_Information *information |
---|
| 448 | ); |
---|
| 449 | |
---|
[6a07436] | 450 | /** |
---|
[f4a8ee1] | 451 | * This function shrink an object class information record. |
---|
[6a07436] | 452 | * |
---|
| 453 | * @param[in] information points to an object class information block. |
---|
[f4a8ee1] | 454 | */ |
---|
| 455 | void _Objects_Shrink_information( |
---|
| 456 | Objects_Information *information |
---|
| 457 | ); |
---|
| 458 | |
---|
[6a07436] | 459 | /** |
---|
[ac7d5ef0] | 460 | * This function initializes an object class information record. |
---|
| 461 | * SUPPORTS_GLOBAL is TRUE if the object class supports global |
---|
| 462 | * objects, and FALSE otherwise. Maximum indicates the number |
---|
| 463 | * of objects required in this class and size indicates the size |
---|
[5e9b32b] | 464 | * in bytes of each control block for this object class. The |
---|
| 465 | * name length and string designator are also set. In addition, |
---|
| 466 | * the class may be a task, therefore this information is also included. |
---|
[6a07436] | 467 | * |
---|
| 468 | * @param[in] information points to an object class information block. |
---|
| 469 | * @param[in] the_api indicates the API associated with this information block. |
---|
| 470 | * @param[in] the_class indicates the class of object being managed |
---|
| 471 | * by this information block. It is specific to @a the_api. |
---|
| 472 | * @param[in] maximum is the maximum number of instances of this object |
---|
| 473 | * class which may be concurrently active. |
---|
| 474 | * @param[in] size is the size of the data structure for this class. |
---|
| 475 | * @param[in] is_string is TRUE if this object uses string style names. |
---|
| 476 | * @param[in] maximum_name_length is the maximum length of object names. |
---|
[ac7d5ef0] | 477 | */ |
---|
| 478 | void _Objects_Initialize_information ( |
---|
| 479 | Objects_Information *information, |
---|
[ef9505a9] | 480 | Objects_APIs the_api, |
---|
[d6154c7] | 481 | uint32_t the_class, |
---|
[50269c46] | 482 | uint32_t maximum, |
---|
[85b7605] | 483 | uint16_t size, |
---|
[3235ad9] | 484 | boolean is_string, |
---|
[d6154c7] | 485 | uint32_t maximum_name_length |
---|
[ef9505a9] | 486 | #if defined(RTEMS_MULTIPROCESSING) |
---|
| 487 | , |
---|
| 488 | boolean supports_global, |
---|
[9b3f187] | 489 | Objects_Thread_queue_Extract_callout extract |
---|
[ef9505a9] | 490 | #endif |
---|
[3235ad9] | 491 | ); |
---|
| 492 | |
---|
[6a07436] | 493 | /** |
---|
[f4a8ee1] | 494 | * This function allocates a object control block from |
---|
| 495 | * the inactive chain of free object control blocks. |
---|
[6a07436] | 496 | * |
---|
| 497 | * @param[in] information points to an object class information block. |
---|
[f4a8ee1] | 498 | */ |
---|
| 499 | Objects_Control *_Objects_Allocate( |
---|
| 500 | Objects_Information *information |
---|
| 501 | ); |
---|
| 502 | |
---|
[6a07436] | 503 | /** |
---|
[352c9b2] | 504 | * This function allocates the object control block |
---|
| 505 | * specified by the index from the inactive chain of |
---|
| 506 | * free object control blocks. |
---|
[6a07436] | 507 | * |
---|
| 508 | * @param[in] information points to an object class information block. |
---|
| 509 | * @param[in] index is the index of the object to allocate. |
---|
| 510 | * @param[in] sizeof_control is the size of the object control block. |
---|
[352c9b2] | 511 | */ |
---|
| 512 | Objects_Control *_Objects_Allocate_by_index( |
---|
| 513 | Objects_Information *information, |
---|
[85b7605] | 514 | uint16_t index, |
---|
| 515 | uint16_t sizeof_control |
---|
[352c9b2] | 516 | ); |
---|
| 517 | |
---|
[6a07436] | 518 | /** |
---|
[f4a8ee1] | 519 | * |
---|
| 520 | * This function frees a object control block to the |
---|
| 521 | * inactive chain of free object control blocks. |
---|
[6a07436] | 522 | * |
---|
| 523 | * @param[in] information points to an object class information block. |
---|
| 524 | * @param[in] the_object points to the object to deallocate. |
---|
[f4a8ee1] | 525 | */ |
---|
| 526 | void _Objects_Free( |
---|
| 527 | Objects_Information *information, |
---|
| 528 | Objects_Control *the_object |
---|
| 529 | ); |
---|
| 530 | |
---|
[6a07436] | 531 | /** |
---|
[c6f111b] | 532 | * This method zeroes out the name. |
---|
[6a07436] | 533 | * |
---|
| 534 | * @param[in] name points to the name to be zeroed out. |
---|
| 535 | * @param[in] length is the length of the object name field. |
---|
[3235ad9] | 536 | */ |
---|
| 537 | void _Objects_Clear_name( |
---|
[f5c5a1db] | 538 | void *name, |
---|
| 539 | const size_t length |
---|
[3235ad9] | 540 | ); |
---|
| 541 | |
---|
[6a07436] | 542 | /** |
---|
[c6f111b] | 543 | * This method copies a string style object name from source to destination. |
---|
[6a07436] | 544 | * |
---|
| 545 | * @param[in] source is the source name to copy. |
---|
| 546 | * @param[in] destination is the destination of the copy. |
---|
| 547 | * @param[in] length is the number of bytes to copy. |
---|
[3235ad9] | 548 | */ |
---|
| 549 | void _Objects_Copy_name_string( |
---|
[f5c5a1db] | 550 | const void *source, |
---|
| 551 | void *destination, |
---|
| 552 | const size_t length |
---|
[3235ad9] | 553 | ); |
---|
| 554 | |
---|
[6a07436] | 555 | /** |
---|
[c6f111b] | 556 | * This method copies a raw style object name from source to destination. |
---|
[6a07436] | 557 | * |
---|
| 558 | * @param[in] source is the source name to copy. |
---|
| 559 | * @param[in] destination is the destination of the copy. |
---|
| 560 | * @param[in] length is the number of bytes to copy. |
---|
[3235ad9] | 561 | */ |
---|
| 562 | void _Objects_Copy_name_raw( |
---|
[f5c5a1db] | 563 | const void *source, |
---|
| 564 | void *destination, |
---|
| 565 | const size_t length |
---|
[3235ad9] | 566 | ); |
---|
| 567 | |
---|
[6a07436] | 568 | /** |
---|
[c6f111b] | 569 | * This method compares two string style object names. |
---|
[6a07436] | 570 | * |
---|
| 571 | * @param[in] name_1 is the left hand name to compare. |
---|
| 572 | * @param[in] name_2 is the right hand name to compare. |
---|
| 573 | * @param[in] length is the length of the names to compare. |
---|
[3235ad9] | 574 | */ |
---|
| 575 | boolean _Objects_Compare_name_string( |
---|
| 576 | void *name_1, |
---|
| 577 | void *name_2, |
---|
[85b7605] | 578 | uint16_t length |
---|
[ac7d5ef0] | 579 | ); |
---|
| 580 | |
---|
[6a07436] | 581 | /** |
---|
[c6f111b] | 582 | * This method compares two raw style object names. |
---|
[6a07436] | 583 | * |
---|
| 584 | * @param[in] name_1 is the left hand name to compare. |
---|
| 585 | * @param[in] name_2 is the right hand name to compare. |
---|
| 586 | * @param[in] length is the length of the names to compare. |
---|
[3235ad9] | 587 | */ |
---|
| 588 | boolean _Objects_Compare_name_raw( |
---|
| 589 | void *name_1, |
---|
| 590 | void *name_2, |
---|
[85b7605] | 591 | uint16_t length |
---|
[3235ad9] | 592 | ); |
---|
[ff08b808] | 593 | |
---|
[6a07436] | 594 | /** |
---|
[ac7d5ef0] | 595 | * This function implements the common portion of the object |
---|
| 596 | * identification directives. This directive returns the object |
---|
| 597 | * id associated with name. If more than one object of this class |
---|
| 598 | * is named name, then the object to which the id belongs is |
---|
| 599 | * arbitrary. Node indicates the extent of the search for the |
---|
| 600 | * id of the object named name. If the object class supports global |
---|
| 601 | * objects, then the search can be limited to a particular node |
---|
| 602 | * or allowed to encompass all nodes. |
---|
| 603 | */ |
---|
[3a4ae6c] | 604 | typedef enum { |
---|
[ff08b808] | 605 | OBJECTS_NAME_OR_ID_LOOKUP_SUCCESSFUL, |
---|
[3a4ae6c] | 606 | OBJECTS_INVALID_NAME, |
---|
[e980b219] | 607 | OBJECTS_INVALID_ADDRESS, |
---|
[ff08b808] | 608 | OBJECTS_INVALID_ID, |
---|
[3a4ae6c] | 609 | OBJECTS_INVALID_NODE |
---|
[ff08b808] | 610 | } Objects_Name_or_id_lookup_errors; |
---|
[3a4ae6c] | 611 | |
---|
[6a07436] | 612 | /** This macro defines the first entry in the |
---|
| 613 | * @ref Objects_Name_or_id_lookup_errors enumerated list. |
---|
| 614 | */ |
---|
[ff08b808] | 615 | #define OBJECTS_NAME_ERRORS_FIRST OBJECTS_NAME_OR_ID_LOOKUP_SUCCESSFUL |
---|
[6a07436] | 616 | |
---|
| 617 | /** This macro defines the last entry in the |
---|
| 618 | * @ref Objects_Name_or_id_lookup_errors enumerated list. |
---|
| 619 | */ |
---|
[3a4ae6c] | 620 | #define OBJECTS_NAME_ERRORS_LAST OBJECTS_INVALID_NODE |
---|
| 621 | |
---|
[6a07436] | 622 | /** |
---|
| 623 | * This method converts an object name to an Id. It performs a look up |
---|
| 624 | * using the object information block for this object class. |
---|
| 625 | * |
---|
| 626 | * @param[in] information points to an object class information block. |
---|
| 627 | * @param[in] name is the name of the object to find. |
---|
| 628 | * @param[in] node is the set of nodes to search. |
---|
| 629 | * @param[in] id will contain the Id if the search is successful. |
---|
| 630 | * |
---|
| 631 | * @return This method returns one of the values from the |
---|
| 632 | * @ref Objects_Name_or_id_lookup_errors enumeration to indicate |
---|
| 633 | * successful or failure. On success @a id will contain the Id of |
---|
| 634 | * the requested object. |
---|
| 635 | */ |
---|
[ff08b808] | 636 | Objects_Name_or_id_lookup_errors _Objects_Name_to_id( |
---|
[ac7d5ef0] | 637 | Objects_Information *information, |
---|
| 638 | Objects_Name name, |
---|
[d6154c7] | 639 | uint32_t node, |
---|
[ac7d5ef0] | 640 | Objects_Id *id |
---|
| 641 | ); |
---|
| 642 | |
---|
[6a07436] | 643 | /** |
---|
[ff08b808] | 644 | * This function implements the common portion of the object Id |
---|
| 645 | * to name directives. This function returns the name |
---|
[a0ed4ed] | 646 | * associated with object id. |
---|
[ff08b808] | 647 | * |
---|
[6a07436] | 648 | * @param[in] id is the Id of the object whose name we are locating. |
---|
| 649 | * @param[in] name will contain the name of the object, if found. |
---|
| 650 | * |
---|
| 651 | * @return This method returns one of the values from the |
---|
| 652 | * @ref Objects_Name_or_id_lookup_errors enumeration to indicate |
---|
| 653 | * successful or failure. On success @a name will contain the name of |
---|
| 654 | * the requested object. |
---|
[ff08b808] | 655 | * |
---|
[6a07436] | 656 | * @note This function currently does not support string names. |
---|
[ff08b808] | 657 | */ |
---|
| 658 | Objects_Name_or_id_lookup_errors _Objects_Id_to_name ( |
---|
| 659 | Objects_Id id, |
---|
| 660 | Objects_Name *name |
---|
| 661 | ); |
---|
| 662 | |
---|
[6a07436] | 663 | /** |
---|
[ac7d5ef0] | 664 | * This function maps object ids to object control blocks. |
---|
| 665 | * If id corresponds to a local object, then it returns |
---|
| 666 | * the_object control pointer which maps to id and location |
---|
| 667 | * is set to OBJECTS_LOCAL. If the object class supports global |
---|
| 668 | * objects and the object id is global and resides on a remote |
---|
| 669 | * node, then location is set to OBJECTS_REMOTE, and the_object |
---|
| 670 | * is undefined. Otherwise, location is set to OBJECTS_ERROR |
---|
| 671 | * and the_object is undefined. |
---|
| 672 | * |
---|
[6a07436] | 673 | * @param[in] information points to an object class information block. |
---|
| 674 | * @param[in] id is the Id of the object whose name we are locating. |
---|
| 675 | * @param[in] location will contain an indication of success or failure. |
---|
| 676 | * |
---|
| 677 | * @return This method returns one of the values from the |
---|
| 678 | * @ref Objects_Name_or_id_lookup_errors enumeration to indicate |
---|
| 679 | * successful or failure. On success @a id will contain the Id of |
---|
| 680 | * the requested object. |
---|
| 681 | * |
---|
| 682 | * @note _Objects_Get returns with dispatching disabled for |
---|
| 683 | * local and remote objects. _Objects_Get_isr_disable returns with |
---|
| 684 | * dispatching disabled for remote objects and interrupts for local |
---|
| 685 | * objects. |
---|
[ac7d5ef0] | 686 | */ |
---|
| 687 | Objects_Control *_Objects_Get ( |
---|
| 688 | Objects_Information *information, |
---|
| 689 | Objects_Id id, |
---|
| 690 | Objects_Locations *location |
---|
| 691 | ); |
---|
| 692 | |
---|
[6a07436] | 693 | /** |
---|
| 694 | * This function maps object ids to object control blocks. |
---|
| 695 | * If id corresponds to a local object, then it returns |
---|
| 696 | * the_object control pointer which maps to id and location |
---|
| 697 | * is set to OBJECTS_LOCAL. If the object class supports global |
---|
| 698 | * objects and the object id is global and resides on a remote |
---|
| 699 | * node, then location is set to OBJECTS_REMOTE, and the_object |
---|
| 700 | * is undefined. Otherwise, location is set to OBJECTS_ERROR |
---|
| 701 | * and the_object is undefined. |
---|
| 702 | * |
---|
| 703 | * @param[in] information points to an object class information block. |
---|
| 704 | * @param[in] id is the Id of the object whose name we are locating. |
---|
| 705 | * @param[in] location will contain an indication of success or failure. |
---|
| 706 | * @param[in] level is the interrupt level being turned. |
---|
| 707 | * |
---|
| 708 | * @return This method returns one of the values from the |
---|
| 709 | * @ref Objects_Name_or_id_lookup_errors enumeration to indicate |
---|
| 710 | * successful or failure. On success @a name will contain the name of |
---|
| 711 | * the requested object. |
---|
| 712 | * |
---|
| 713 | * @note _Objects_Get returns with dispatching disabled for |
---|
| 714 | * local and remote objects. _Objects_Get_isr_disable returns with |
---|
| 715 | * dispatching disabled for remote objects and interrupts for local |
---|
| 716 | * objects. |
---|
| 717 | */ |
---|
[c6f111b] | 718 | Objects_Control *_Objects_Get_isr_disable( |
---|
| 719 | Objects_Information *information, |
---|
| 720 | Objects_Id id, |
---|
| 721 | Objects_Locations *location, |
---|
| 722 | ISR_Level *level |
---|
| 723 | ); |
---|
| 724 | |
---|
[6a07436] | 725 | /** |
---|
| 726 | * This function maps object index to object control blocks which must. |
---|
| 727 | * be local. The parameter the_object control pointer which maps to id |
---|
| 728 | * and location is set to OBJECTS_LOCAL. Otherwise, location is set to |
---|
| 729 | OBJECTS_ERROR and the_object is undefined. |
---|
| 730 | * |
---|
| 731 | * @param[in] information points to an object class information block. |
---|
| 732 | * @param[in] id is the Id of the object whose name we are locating. |
---|
| 733 | * @param[in] location will contain an indication of success or failure. |
---|
| 734 | * |
---|
| 735 | * @return This method returns a pointer to the object associated with ID. |
---|
| 736 | * |
---|
| 737 | * @return This method returns one of the values from the |
---|
| 738 | * @ref Objects_Name_or_id_lookup_errors enumeration to indicate |
---|
| 739 | * successful or failure. On success @a id will contain the id of |
---|
| 740 | * the requested object. |
---|
| 741 | * |
---|
| 742 | * @note _Objects_Get returns with dispatching disabled for |
---|
| 743 | * local and remote objects. _Objects_Get_isr_disable returns with |
---|
| 744 | * dispatching disabled for remote objects and interrupts for local |
---|
| 745 | * objects. |
---|
| 746 | */ |
---|
[c31c15c] | 747 | Objects_Control *_Objects_Get_by_index ( |
---|
| 748 | Objects_Information *information, |
---|
| 749 | Objects_Id id, |
---|
| 750 | Objects_Locations *location |
---|
| 751 | ); |
---|
[ef9505a9] | 752 | |
---|
[6a07436] | 753 | /** |
---|
| 754 | * This function maps object ids to object control blocks. |
---|
| 755 | * If id corresponds to a local object, then it returns |
---|
| 756 | * the_object control pointer which maps to id and location |
---|
| 757 | * is set to OBJECTS_LOCAL. If the object class supports global |
---|
| 758 | * objects and the object id is global and resides on a remote |
---|
| 759 | * node, then location is set to OBJECTS_REMOTE, and the_object |
---|
| 760 | * is undefined. Otherwise, location is set to OBJECTS_ERROR |
---|
| 761 | * and the_object is undefined. |
---|
| 762 | * |
---|
| 763 | * @param[in] information points to an object class information block. |
---|
| 764 | * @param[in] id is the Id of the object whose name we are locating. |
---|
| 765 | * @param[in] location will contain an indication of success or failure. |
---|
| 766 | * |
---|
| 767 | * @return This method returns one of the values from the |
---|
| 768 | * @ref Objects_Name_or_id_lookup_errors enumeration to indicate |
---|
| 769 | * successful or failure. On success @a id will contain the Id of |
---|
| 770 | * the requested object. |
---|
| 771 | * |
---|
| 772 | * @note _Objects_Get returns with dispatching disabled for |
---|
| 773 | * local and remote objects. _Objects_Get_isr_disable returns with |
---|
| 774 | * dispatching disabled for remote objects and interrupts for local |
---|
| 775 | * objects. |
---|
| 776 | */ |
---|
[ef9505a9] | 777 | Objects_Control *_Objects_Get_no_protection( |
---|
| 778 | Objects_Information *information, |
---|
| 779 | Objects_Id id, |
---|
| 780 | Objects_Locations *location |
---|
| 781 | ); |
---|
| 782 | |
---|
[6a07436] | 783 | /** |
---|
| 784 | * Like @ref _Objects_Get, but is used to find "next" open object. |
---|
[b06e68ef] | 785 | * |
---|
[6a07436] | 786 | * @param[in] information points to an object class information block. |
---|
| 787 | * @param[in] id is the Id of the object whose name we are locating. |
---|
| 788 | * @param[in] location_p will contain an indication of success or failure. |
---|
| 789 | * @param[in] next_id_p is the Id of the next object we will look at. |
---|
[b06e68ef] | 790 | * |
---|
[6a07436] | 791 | * @return This method returns the pointer to the object located or |
---|
| 792 | * NULL on error. |
---|
[b06e68ef] | 793 | */ |
---|
| 794 | Objects_Control *_Objects_Get_next( |
---|
| 795 | Objects_Information *information, |
---|
| 796 | Objects_Id id, |
---|
[4944b5bf] | 797 | Objects_Locations *location_p, |
---|
[b06e68ef] | 798 | Objects_Id *next_id_p |
---|
| 799 | ); |
---|
| 800 | |
---|
[e1bce86] | 801 | /** |
---|
| 802 | * This method objects the name of an object and returns its name |
---|
| 803 | * in the form of a C string. It attempts to be careful about |
---|
| 804 | * overflowing the user's string and about returning unprintable characters. |
---|
| 805 | * |
---|
| 806 | * @param[in] id is the object to obtain the name of |
---|
| 807 | * @param[in] length indicates the length of the caller's buffer |
---|
| 808 | * @param[inout] name is a string which will be filled in. |
---|
| 809 | * |
---|
| 810 | * @return This method returns @a name or NULL on error. |
---|
| 811 | */ |
---|
| 812 | |
---|
| 813 | char *_Objects_Get_name_as_string( |
---|
| 814 | Objects_Id id, |
---|
| 815 | size_t length, |
---|
| 816 | char *name |
---|
| 817 | ); |
---|
| 818 | |
---|
[ac7d5ef0] | 819 | /* |
---|
[1a8fde6c] | 820 | * Pieces of object.inl are promoted out to the user |
---|
[ac7d5ef0] | 821 | */ |
---|
| 822 | |
---|
[5e9b32b] | 823 | #include <rtems/score/object.inl> |
---|
[97e2729d] | 824 | #if defined(RTEMS_MULTIPROCESSING) |
---|
[5e9b32b] | 825 | #include <rtems/score/objectmp.h> |
---|
[97e2729d] | 826 | #endif |
---|
[ac7d5ef0] | 827 | |
---|
| 828 | #ifdef __cplusplus |
---|
| 829 | } |
---|
| 830 | #endif |
---|
| 831 | |
---|
| 832 | #endif |
---|
| 833 | /* end of include file */ |
---|