[d5671b1] | 1 | @c |
---|
| 2 | @c COPYRIGHT (c) 1988-2008. |
---|
| 3 | @c On-Line Applications Research Corporation (OAR). |
---|
| 4 | @c All rights reserved. |
---|
| 5 | @c |
---|
| 6 | @c $Id$ |
---|
| 7 | @c |
---|
| 8 | |
---|
| 9 | @chapter Object Services |
---|
| 10 | |
---|
| 11 | @cindex object manipulation |
---|
| 12 | |
---|
| 13 | @section Introduction |
---|
| 14 | |
---|
| 15 | RTEMS provides a collection of services to assist in the |
---|
| 16 | management and usage of the objects created and utilized |
---|
| 17 | via other managers. These services assist in the |
---|
| 18 | manipulation of RTEMS objects independent of the API used |
---|
| 19 | to create them. The object related services provided by |
---|
| 20 | RTEMS are: |
---|
| 21 | |
---|
| 22 | @itemize @bullet |
---|
| 23 | @c build_id |
---|
| 24 | @item @code{@value{DIRPREFIX}build_name} - build object name from characters |
---|
| 25 | @item @code{@value{DIRPREFIX}object_get_classic_name} - lookup name from Id |
---|
| 26 | @item @code{@value{DIRPREFIX}object_get_name} - obtain object name as string |
---|
| 27 | @item @code{@value{DIRPREFIX}object_set_name} - set object name |
---|
| 28 | @item @code{@value{DIRPREFIX}object_id_get_api} - obtain API from Id |
---|
| 29 | @item @code{@value{DIRPREFIX}object_id_get_class} - obtain class from Id |
---|
| 30 | @item @code{@value{DIRPREFIX}object_id_get_node} - obtain node from Id |
---|
| 31 | @item @code{@value{DIRPREFIX}object_id_get_index} - obtain index from Id |
---|
| 32 | @item @code{@value{DIRPREFIX}build_id} - build object id from components |
---|
| 33 | @item @code{@value{DIRPREFIX}object_id_api_minimum} - obtain minimum API value |
---|
| 34 | @item @code{@value{DIRPREFIX}object_id_api_maximum} - obtain maximum API value |
---|
| 35 | @item @code{@value{DIRPREFIX}object_id_api_minimum_class} - obtain minimum class value |
---|
| 36 | @item @code{@value{DIRPREFIX}object_id_api_maximum_class} - obtain maximum class value |
---|
| 37 | @item @code{@value{DIRPREFIX}object_get_api_name} - obtain API name |
---|
| 38 | @item @code{@value{DIRPREFIX}object_get_api_class_name} - obtain class name |
---|
| 39 | @item @code{@value{DIRPREFIX}object_get_class_information} - obtain class information |
---|
| 40 | @end itemize |
---|
| 41 | |
---|
| 42 | @section Background |
---|
| 43 | |
---|
| 44 | @subsection APIs |
---|
| 45 | |
---|
| 46 | RTEMS implements multiple APIs including an Internal API, |
---|
| 47 | the Classic API, the POSIX API, and the uITRON API. These |
---|
| 48 | APIs share the common foundation of SuperCore objects and |
---|
| 49 | thus share object management code. This includes a common |
---|
| 50 | scheme for object Ids and for managing object names whether |
---|
| 51 | those names be in the thirty-two bit form used by the Classic |
---|
| 52 | API or C strings. |
---|
| 53 | |
---|
| 54 | The object Id contains a field indicating the API that |
---|
| 55 | an object instance is associated with. This field |
---|
| 56 | holds a numerically small non-zero integer. |
---|
| 57 | |
---|
| 58 | @subsection Object Classes |
---|
| 59 | |
---|
| 60 | Each API consists of a collection of managers. Each manager |
---|
| 61 | is responsible for instances of a particular object class. |
---|
| 62 | Classic API Tasks and POSIX Mutexes example classes. |
---|
| 63 | |
---|
| 64 | The object Id contains a field indicating the class that |
---|
| 65 | an object instance is associated with. This field |
---|
| 66 | holds a numerically small non-zero integer. In all APIs, |
---|
| 67 | a class value of one is reserved for tasks or threads. |
---|
| 68 | |
---|
| 69 | @subsection Object Names |
---|
| 70 | |
---|
| 71 | Every RTEMS object which has an Id may also have a |
---|
| 72 | name associated with it. Depending on the API, names |
---|
| 73 | may be either thirty-two bit integers as in the Classic |
---|
| 74 | API or strings as in the POSIX API. |
---|
| 75 | |
---|
| 76 | Some objects have Ids but do not have a defined way to associate |
---|
| 77 | a name with them. For example, POSIX threads have |
---|
| 78 | Ids but per POSIX do not have names. In RTEMS, objects |
---|
| 79 | not defined to have thirty-two bit names may have string |
---|
| 80 | names assigned to them via the @code{@value{DIRPREFIX}object_set_name} |
---|
| 81 | service. The original impetus in providing this service |
---|
| 82 | was so the normally anonymous POSIX threads could have |
---|
| 83 | a user defined name in CPU Usage Reports. |
---|
| 84 | |
---|
| 85 | @section Operations |
---|
| 86 | |
---|
[235fb7a] | 87 | @subsection Decomposing and Recomposing an Object Id |
---|
[d5671b1] | 88 | |
---|
[235fb7a] | 89 | Services are provided to decompose an object Id into its |
---|
| 90 | subordinate components. The following services are used |
---|
| 91 | to do this: |
---|
[d5671b1] | 92 | |
---|
[235fb7a] | 93 | @itemize @bullet |
---|
| 94 | @item @code{@value{DIRPREFIX}object_id_get_api} |
---|
| 95 | @item @code{@value{DIRPREFIX}object_id_get_class} |
---|
| 96 | @item @code{@value{DIRPREFIX}object_id_get_node} |
---|
| 97 | @item @code{@value{DIRPREFIX}object_id_get_index} |
---|
| 98 | @end itemize |
---|
| 99 | |
---|
| 100 | The following C language example illustrates the |
---|
| 101 | decomposition of an Id and printing the values. |
---|
| 102 | |
---|
| 103 | @example |
---|
| 104 | void printObjectId(rtems_id id) |
---|
| 105 | @{ |
---|
| 106 | printf( |
---|
| 107 | "API=%d Class=%d Node=%d Index=%d\n", |
---|
| 108 | rtems_object_id_get_api(id), |
---|
| 109 | rtems_object_id_get_class(id), |
---|
| 110 | rtems_object_id_get_node(id), |
---|
| 111 | rtems_object_id_get_index(id) |
---|
| 112 | ); |
---|
| 113 | @} |
---|
| 114 | @end example |
---|
| 115 | |
---|
| 116 | This prints the components of the Ids as integers. |
---|
| 117 | |
---|
| 118 | It is also possible to construct an arbitrary Id using |
---|
| 119 | the @code{@value{DIRPREFIX}build_id} service. The following |
---|
| 120 | C language example illustrates how to construct the |
---|
| 121 | "next Id." |
---|
| 122 | |
---|
| 123 | @example |
---|
| 124 | rtems_id nextObjectId(rtems_id id) |
---|
| 125 | @{ |
---|
| 126 | return rtems_build_id( |
---|
| 127 | rtems_object_id_get_api(id), |
---|
| 128 | rtems_object_id_get_class(id), |
---|
| 129 | rtems_object_id_get_node(id), |
---|
| 130 | rtems_object_id_get_index(id) + 1 |
---|
| 131 | ); |
---|
| 132 | @} |
---|
| 133 | @end example |
---|
| 134 | |
---|
| 135 | Note that this Id may not be valid in this |
---|
| 136 | system or associated with an allocated object. |
---|
| 137 | |
---|
| 138 | @subsection Printing an Object Id |
---|
| 139 | |
---|
| 140 | RTEMS also provides services to associate the API and Class |
---|
| 141 | portions of an Object Id with strings. This allows the |
---|
| 142 | application developer to provide more information about |
---|
| 143 | an object in diagnostic messages. |
---|
| 144 | |
---|
| 145 | In the following C language example, an Id is decomposed into |
---|
| 146 | its constituent parts and "pretty-printed." |
---|
| 147 | |
---|
| 148 | @example |
---|
| 149 | void prettyPrintObjectId(rtems_id id) |
---|
| 150 | @{ |
---|
[e25611d] | 151 | int tmpAPI, tmpClass; |
---|
[235fb7a] | 152 | |
---|
| 153 | tmpAPI = rtems_object_id_get_api(id), |
---|
| 154 | tmpClass = rtems_object_id_get_class(id), |
---|
| 155 | |
---|
| 156 | printf( |
---|
| 157 | "API=%s Class=%s Node=%d Index=%d\n", |
---|
| 158 | rtems_object_get_api_name(tmpAPI), |
---|
| 159 | rtems_object_get_api_class_name(tmpAPI, tmpClass), |
---|
| 160 | rtems_object_id_get_node(id), |
---|
| 161 | rtems_object_id_get_index(id) |
---|
| 162 | ); |
---|
| 163 | @} |
---|
| 164 | @end example |
---|
[d5671b1] | 165 | |
---|
[235fb7a] | 166 | @section Directives |
---|
[d5671b1] | 167 | |
---|
| 168 | @c |
---|
| 169 | @c |
---|
| 170 | @c |
---|
| 171 | @page |
---|
| 172 | @subsection BUILD_NAME - Build object name from characters |
---|
| 173 | |
---|
| 174 | @cindex build object name |
---|
| 175 | |
---|
| 176 | @subheading CALLING SEQUENCE: |
---|
| 177 | |
---|
| 178 | @ifset is-C |
---|
| 179 | @findex rtems_build_name |
---|
| 180 | @example |
---|
| 181 | rtems_name rtems_build_name( |
---|
| 182 | uint8_t c1, |
---|
| 183 | uint8_t c2, |
---|
| 184 | uint8_t c3, |
---|
| 185 | uint8_t c4 |
---|
| 186 | ); |
---|
| 187 | @end example |
---|
| 188 | @end ifset |
---|
| 189 | |
---|
| 190 | @ifset is-Ada |
---|
| 191 | @example |
---|
[0bc8e5c] | 192 | procedure Build_Name( |
---|
| 193 | c1 : in RTEMS.Unsigned8; |
---|
| 194 | c2 : in RTEMS.Unsigned8; |
---|
| 195 | c3 : in RTEMS.Unsigned8; |
---|
| 196 | c4 : in RTEMS.Unsigned8; |
---|
| 197 | Name : out RTEMS.Name |
---|
| 198 | ); |
---|
[d5671b1] | 199 | @end example |
---|
| 200 | @end ifset |
---|
| 201 | |
---|
| 202 | @subheading DIRECTIVE STATUS CODES |
---|
| 203 | |
---|
| 204 | Returns a name constructed from the four characters. |
---|
| 205 | |
---|
| 206 | @subheading DESCRIPTION: |
---|
| 207 | |
---|
| 208 | This service takes the four characters provided as arguments |
---|
| 209 | and constructs a thirty-two bit object name with @code{c1} |
---|
| 210 | in the most significant byte and @code{c4} in the least |
---|
| 211 | significant byte. |
---|
| 212 | |
---|
| 213 | @subheading NOTES: |
---|
| 214 | |
---|
| 215 | This directive is strictly local and does not impact task scheduling. |
---|
| 216 | |
---|
| 217 | @c |
---|
| 218 | @c |
---|
| 219 | @c |
---|
| 220 | @page |
---|
| 221 | @subsection OBJECT_GET_CLASSIC_NAME - Lookup name from id |
---|
| 222 | |
---|
| 223 | @cindex get name from id |
---|
| 224 | @cindex obtain name from id |
---|
| 225 | |
---|
| 226 | @subheading CALLING SEQUENCE: |
---|
| 227 | |
---|
| 228 | @ifset is-C |
---|
| 229 | @findex rtems_build_name |
---|
| 230 | @example |
---|
| 231 | rtems_status_code rtems_object_get_classic_name( |
---|
| 232 | rtems_id id, |
---|
| 233 | rtems_name *name |
---|
| 234 | ); |
---|
| 235 | @end example |
---|
| 236 | @end ifset |
---|
| 237 | |
---|
| 238 | @ifset is-Ada |
---|
| 239 | @example |
---|
[0bc8e5c] | 240 | procedure Object_Get_Classic_Name( |
---|
| 241 | ID : in RTEMS.ID; |
---|
| 242 | Name : out RTEMS.Name; |
---|
| 243 | Result : out RTEMS.Status_Codes |
---|
| 244 | ); |
---|
[d5671b1] | 245 | @end example |
---|
| 246 | @end ifset |
---|
| 247 | |
---|
| 248 | @subheading DIRECTIVE STATUS CODES |
---|
| 249 | |
---|
| 250 | @code{@value{RPREFIX}SUCCESSFUL} - name looked up successfully@* |
---|
| 251 | @code{@value{RPREFIX}INVALID_ADDRESS} - invalid name pointer@* |
---|
| 252 | @code{@value{RPREFIX}INVALID_ID} - invalid object id@* |
---|
| 253 | |
---|
| 254 | @subheading DESCRIPTION: |
---|
| 255 | |
---|
| 256 | This service looks up the name for the object @code{id} specified |
---|
| 257 | and, if found, places the result in @code{*name}. |
---|
| 258 | |
---|
| 259 | @subheading NOTES: |
---|
| 260 | |
---|
| 261 | This directive is strictly local and does not impact task scheduling. |
---|
| 262 | |
---|
| 263 | @c |
---|
| 264 | @c |
---|
| 265 | @c |
---|
| 266 | @page |
---|
| 267 | @subsection OBJECT_GET_NAME - Obtain object name as string |
---|
| 268 | |
---|
| 269 | @cindex get object name as string |
---|
| 270 | @cindex obtain object name as string |
---|
| 271 | |
---|
| 272 | @subheading CALLING SEQUENCE: |
---|
| 273 | |
---|
| 274 | @ifset is-C |
---|
[0bc8e5c] | 275 | @findex rtems_object_get_name |
---|
[d5671b1] | 276 | @example |
---|
| 277 | char *rtems_object_get_name( |
---|
| 278 | rtems_id id, |
---|
| 279 | size_t length, |
---|
| 280 | char *name |
---|
| 281 | ); |
---|
| 282 | @end example |
---|
| 283 | @end ifset |
---|
| 284 | |
---|
| 285 | @ifset is-Ada |
---|
| 286 | @example |
---|
[0bc8e5c] | 287 | procedure Object_Get_Name( |
---|
| 288 | ID : in RTEMS.ID; |
---|
| 289 | Name : out RTEMS.Name; |
---|
| 290 | Result : out RTEMS.Status_Codes |
---|
| 291 | ); |
---|
[d5671b1] | 292 | @end example |
---|
| 293 | @end ifset |
---|
| 294 | |
---|
| 295 | @subheading DIRECTIVE STATUS CODES |
---|
| 296 | |
---|
| 297 | Returns a pointer to the name if successful or @code{NULL} |
---|
| 298 | otherwise. |
---|
| 299 | |
---|
| 300 | @subheading DESCRIPTION: |
---|
| 301 | |
---|
| 302 | This service looks up the name of the object specified by |
---|
| 303 | @code{id} and places it in the memory pointed to by @code{name}. |
---|
| 304 | Every attempt is made to return name as a printable string even |
---|
| 305 | if the object has the Classic API thirty-two bit style name. |
---|
| 306 | |
---|
| 307 | @subheading NOTES: |
---|
| 308 | |
---|
| 309 | This directive is strictly local and does not impact task scheduling. |
---|
| 310 | |
---|
| 311 | @c |
---|
| 312 | @c |
---|
| 313 | @c |
---|
| 314 | @page |
---|
[0bc8e5c] | 315 | @subsection OBJECT_SET_NAME - Set object name |
---|
[d5671b1] | 316 | |
---|
| 317 | @cindex set object name |
---|
| 318 | |
---|
| 319 | @subheading CALLING SEQUENCE: |
---|
| 320 | |
---|
| 321 | @ifset is-C |
---|
[0bc8e5c] | 322 | @findex rtems_object_set_name |
---|
[d5671b1] | 323 | @example |
---|
| 324 | rtems_status_code rtems_object_set_name( |
---|
| 325 | rtems_id id, |
---|
| 326 | const char *name |
---|
| 327 | ); |
---|
| 328 | @end example |
---|
| 329 | @end ifset |
---|
| 330 | |
---|
| 331 | @ifset is-Ada |
---|
| 332 | @example |
---|
[0bc8e5c] | 333 | procedure Object_Set_Name( |
---|
| 334 | ID : in RTEMS.ID; |
---|
| 335 | Name : in String; |
---|
| 336 | Result : out RTEMS.Status_Codes |
---|
| 337 | ); |
---|
[d5671b1] | 338 | @end example |
---|
| 339 | @end ifset |
---|
| 340 | |
---|
| 341 | @subheading DIRECTIVE STATUS CODES |
---|
| 342 | |
---|
| 343 | @code{@value{RPREFIX}SUCCESSFUL} - name looked up successfully@* |
---|
| 344 | @code{@value{RPREFIX}INVALID_ADDRESS} - invalid name pointer@* |
---|
| 345 | @code{@value{RPREFIX}INVALID_ID} - invalid object id@* |
---|
| 346 | |
---|
| 347 | @subheading DESCRIPTION: |
---|
| 348 | |
---|
| 349 | This service sets the name of @code{id} to that specified |
---|
| 350 | by the string located at @code{name}. |
---|
| 351 | |
---|
| 352 | @subheading NOTES: |
---|
| 353 | |
---|
| 354 | This directive is strictly local and does not impact task scheduling. |
---|
| 355 | |
---|
| 356 | If the object specified by @code{id} is of a class that |
---|
| 357 | has a string name, this method will free the existing |
---|
| 358 | name to the RTEMS Workspace and allocate enough memory |
---|
| 359 | from the RTEMS Workspace to make a copy of the string |
---|
| 360 | located at @code{name}. |
---|
| 361 | |
---|
| 362 | If the object specified by @code{id} is of a class that |
---|
| 363 | has a thirty-two bit integer style name, then the first |
---|
| 364 | four characters in @code{*name} will be used to construct |
---|
| 365 | the name. |
---|
| 366 | name to the RTEMS Workspace and allocate enough memory |
---|
| 367 | from the RTEMS Workspace to make a copy of the string |
---|
| 368 | |
---|
| 369 | |
---|
| 370 | @c |
---|
| 371 | @c |
---|
| 372 | @c |
---|
| 373 | @page |
---|
| 374 | @subsection OBJECT_ID_GET_API - Obtain API from Id |
---|
| 375 | |
---|
| 376 | @cindex obtain API from id |
---|
| 377 | |
---|
| 378 | @subheading CALLING SEQUENCE: |
---|
| 379 | |
---|
| 380 | @ifset is-C |
---|
| 381 | @findex rtems_object_id_get_api |
---|
| 382 | @example |
---|
[e25611d] | 383 | int rtems_object_id_get_api( |
---|
[d5671b1] | 384 | rtems_id id |
---|
| 385 | ); |
---|
| 386 | @end example |
---|
| 387 | @end ifset |
---|
| 388 | |
---|
| 389 | @ifset is-Ada |
---|
| 390 | @example |
---|
[0bc8e5c] | 391 | procedure Object_Id_Get_API( |
---|
| 392 | ID : in RTEMS.ID; |
---|
| 393 | API : out RTEMS.Unsigned32 |
---|
| 394 | ); |
---|
[d5671b1] | 395 | @end example |
---|
| 396 | @end ifset |
---|
| 397 | |
---|
| 398 | @subheading DIRECTIVE STATUS CODES |
---|
| 399 | |
---|
| 400 | Returns the API portion of the object Id. |
---|
| 401 | |
---|
| 402 | @subheading DESCRIPTION: |
---|
| 403 | |
---|
| 404 | This directive returns the API portion of the provided object @code{id}. |
---|
| 405 | |
---|
| 406 | @subheading NOTES: |
---|
| 407 | |
---|
| 408 | This directive is strictly local and does not impact task scheduling. |
---|
| 409 | |
---|
| 410 | This directive does NOT validate the @code{id} provided. |
---|
| 411 | |
---|
| 412 | @c |
---|
| 413 | @c |
---|
| 414 | @c |
---|
| 415 | @page |
---|
| 416 | @subsection OBJECT_ID_GET_CLASS - Obtain Class from Id |
---|
| 417 | |
---|
| 418 | @cindex obtain class from object id |
---|
| 419 | |
---|
| 420 | @subheading CALLING SEQUENCE: |
---|
| 421 | |
---|
| 422 | @ifset is-C |
---|
| 423 | @findex rtems_object_id_get_class |
---|
| 424 | @example |
---|
[e25611d] | 425 | int rtems_object_id_get_class( |
---|
[d5671b1] | 426 | rtems_id id |
---|
| 427 | ); |
---|
| 428 | @end example |
---|
| 429 | @end ifset |
---|
| 430 | |
---|
| 431 | @ifset is-Ada |
---|
| 432 | @example |
---|
[0bc8e5c] | 433 | procedure Object_Id_Get_Class( |
---|
| 434 | ID : in RTEMS.ID; |
---|
| 435 | The_Class : out RTEMS.Unsigned32 |
---|
| 436 | ); |
---|
[d5671b1] | 437 | @end example |
---|
| 438 | @end ifset |
---|
| 439 | |
---|
| 440 | @subheading DIRECTIVE STATUS CODES |
---|
| 441 | |
---|
| 442 | Returns the class portion of the object Id. |
---|
| 443 | |
---|
| 444 | @subheading DESCRIPTION: |
---|
| 445 | |
---|
| 446 | This directive returns the class portion of the provided object @code{id}. |
---|
| 447 | |
---|
| 448 | @subheading NOTES: |
---|
| 449 | |
---|
| 450 | This directive is strictly local and does not impact task scheduling. |
---|
| 451 | |
---|
| 452 | This directive does NOT validate the @code{id} provided. |
---|
| 453 | |
---|
| 454 | @c |
---|
| 455 | @c |
---|
| 456 | @c |
---|
| 457 | @page |
---|
| 458 | @subsection OBJECT_ID_GET_NODE - Obtain Node from Id |
---|
| 459 | |
---|
| 460 | @cindex obtain node from object id |
---|
| 461 | |
---|
| 462 | @subheading CALLING SEQUENCE: |
---|
| 463 | |
---|
| 464 | @ifset is-C |
---|
| 465 | @findex rtems_object_id_get_node |
---|
| 466 | @example |
---|
[e25611d] | 467 | int rtems_object_id_get_node( |
---|
[d5671b1] | 468 | rtems_id id |
---|
| 469 | ); |
---|
| 470 | @end example |
---|
| 471 | @end ifset |
---|
| 472 | |
---|
| 473 | @ifset is-Ada |
---|
| 474 | @example |
---|
[0bc8e5c] | 475 | procedure Object_Id_Get_Node( |
---|
| 476 | ID : in RTEMS.ID; |
---|
| 477 | Node : out RTEMS.Unsigned32 |
---|
| 478 | ); |
---|
[d5671b1] | 479 | @end example |
---|
| 480 | @end ifset |
---|
| 481 | |
---|
| 482 | @subheading DIRECTIVE STATUS CODES |
---|
| 483 | |
---|
| 484 | Returns the node portion of the object Id. |
---|
| 485 | |
---|
| 486 | @subheading DESCRIPTION: |
---|
| 487 | |
---|
| 488 | This directive returns the node portion of the provided object @code{id}. |
---|
| 489 | |
---|
| 490 | @subheading NOTES: |
---|
| 491 | |
---|
| 492 | This directive is strictly local and does not impact task scheduling. |
---|
| 493 | |
---|
| 494 | This directive does NOT validate the @code{id} provided. |
---|
| 495 | |
---|
| 496 | @c |
---|
| 497 | @c |
---|
| 498 | @c |
---|
| 499 | @page |
---|
| 500 | @subsection OBJECT_ID_GET_INDEX - Obtain Index from Id |
---|
| 501 | |
---|
| 502 | @cindex obtain index from object id |
---|
| 503 | |
---|
| 504 | @subheading CALLING SEQUENCE: |
---|
| 505 | |
---|
| 506 | @ifset is-C |
---|
| 507 | @findex rtems_object_id_get_index |
---|
| 508 | @example |
---|
[e25611d] | 509 | int rtems_object_id_get_index( |
---|
[d5671b1] | 510 | rtems_id id |
---|
| 511 | ); |
---|
| 512 | @end example |
---|
| 513 | @end ifset |
---|
| 514 | |
---|
| 515 | @ifset is-Ada |
---|
| 516 | @example |
---|
[0bc8e5c] | 517 | procedure Object_Id_Get_Index( |
---|
| 518 | ID : in RTEMS.ID; |
---|
| 519 | Index : out RTEMS.Unsigned32 |
---|
| 520 | ); |
---|
[d5671b1] | 521 | @end example |
---|
| 522 | @end ifset |
---|
| 523 | |
---|
| 524 | @subheading DIRECTIVE STATUS CODES |
---|
| 525 | |
---|
| 526 | Returns the index portion of the object Id. |
---|
| 527 | |
---|
| 528 | @subheading DESCRIPTION: |
---|
| 529 | |
---|
| 530 | This directive returns the index portion of the provided object @code{id}. |
---|
| 531 | |
---|
| 532 | @subheading NOTES: |
---|
| 533 | |
---|
| 534 | This directive is strictly local and does not impact task scheduling. |
---|
| 535 | |
---|
| 536 | This directive does NOT validate the @code{id} provided. |
---|
| 537 | |
---|
| 538 | @c |
---|
| 539 | @c |
---|
| 540 | @c |
---|
| 541 | @page |
---|
| 542 | @subsection BUILD_ID - Build Object Id From Components |
---|
| 543 | |
---|
| 544 | @cindex build object id from components |
---|
| 545 | |
---|
| 546 | @subheading CALLING SEQUENCE: |
---|
| 547 | |
---|
| 548 | @ifset is-C |
---|
| 549 | @findex rtems_build_id |
---|
| 550 | @example |
---|
| 551 | rtems_id rtems_build_id( |
---|
[e25611d] | 552 | int the_api, |
---|
| 553 | int the_class, |
---|
| 554 | int the_node, |
---|
| 555 | int the_index |
---|
[d5671b1] | 556 | ); |
---|
| 557 | @end example |
---|
| 558 | @end ifset |
---|
| 559 | |
---|
| 560 | @ifset is-Ada |
---|
| 561 | @example |
---|
[0bc8e5c] | 562 | function Build_Id( |
---|
| 563 | the_api : in RTEMS.Unsigned32; |
---|
| 564 | the_class : in RTEMS.Unsigned32; |
---|
| 565 | the_node : in RTEMS.Unsigned32; |
---|
| 566 | the_index : in RTEMS.Unsigned32 |
---|
| 567 | ) return RTEMS.Id; |
---|
[d5671b1] | 568 | @end example |
---|
| 569 | @end ifset |
---|
| 570 | |
---|
| 571 | @subheading DIRECTIVE STATUS CODES |
---|
| 572 | |
---|
| 573 | Returns an object Id constructed from the provided arguments. |
---|
| 574 | |
---|
| 575 | @subheading DESCRIPTION: |
---|
| 576 | |
---|
| 577 | This service constructs an object Id from the provided |
---|
[0bc8e5c] | 578 | @code{the_api}, @code{the_class}, @code{the_node}, and @code{the_index}. |
---|
[d5671b1] | 579 | |
---|
| 580 | |
---|
| 581 | @subheading NOTES: |
---|
| 582 | |
---|
| 583 | This directive is strictly local and does not impact task scheduling. |
---|
| 584 | |
---|
| 585 | This directive does NOT validate the arguments provided |
---|
| 586 | or the Object id returned. |
---|
| 587 | |
---|
| 588 | @c |
---|
| 589 | @c |
---|
| 590 | @c |
---|
| 591 | @page |
---|
| 592 | @subsection OBJECT_ID_API_MINIMUM - Obtain Minimum API Value |
---|
| 593 | |
---|
| 594 | @cindex obtain minimum API value |
---|
| 595 | |
---|
| 596 | @subheading CALLING SEQUENCE: |
---|
| 597 | |
---|
| 598 | @ifset is-C |
---|
| 599 | @findex rtems_object_id_api_minimum |
---|
| 600 | @example |
---|
[e25611d] | 601 | int rtems_object_id_api_minimum(void); |
---|
[d5671b1] | 602 | @end example |
---|
| 603 | @end ifset |
---|
| 604 | |
---|
| 605 | @ifset is-Ada |
---|
| 606 | @example |
---|
[0bc8e5c] | 607 | function Object_Id_API_Minimum return RTEMS.Unsigned32; |
---|
[d5671b1] | 608 | @end example |
---|
| 609 | @end ifset |
---|
| 610 | |
---|
| 611 | @subheading DIRECTIVE STATUS CODES |
---|
| 612 | |
---|
| 613 | Returns the minimum valid for the API portion of an object Id. |
---|
| 614 | |
---|
| 615 | @subheading DESCRIPTION: |
---|
| 616 | |
---|
| 617 | This service returns the minimum valid for the API portion of |
---|
| 618 | an object Id. |
---|
| 619 | |
---|
| 620 | @subheading NOTES: |
---|
| 621 | |
---|
| 622 | This directive is strictly local and does not impact task scheduling. |
---|
| 623 | |
---|
| 624 | @c |
---|
| 625 | @c |
---|
| 626 | @c |
---|
| 627 | @page |
---|
| 628 | @subsection OBJECT_ID_API_MAXIMUM - Obtain Maximum API Value |
---|
| 629 | |
---|
| 630 | @cindex obtain maximum API value |
---|
| 631 | |
---|
| 632 | @subheading CALLING SEQUENCE: |
---|
| 633 | |
---|
| 634 | @ifset is-C |
---|
| 635 | @findex rtems_object_id_api_maximum |
---|
| 636 | @example |
---|
[e25611d] | 637 | int rtems_object_id_api_maximum(void); |
---|
[d5671b1] | 638 | @end example |
---|
| 639 | @end ifset |
---|
| 640 | |
---|
| 641 | @ifset is-Ada |
---|
| 642 | @example |
---|
[0bc8e5c] | 643 | function Object_Id_API_Maximum return RTEMS.Unsigned32; |
---|
[d5671b1] | 644 | @end example |
---|
| 645 | @end ifset |
---|
| 646 | |
---|
| 647 | @subheading DIRECTIVE STATUS CODES |
---|
| 648 | |
---|
| 649 | Returns the maximum valid for the API portion of an object Id. |
---|
| 650 | |
---|
| 651 | @subheading DESCRIPTION: |
---|
| 652 | |
---|
| 653 | This service returns the maximum valid for the API portion of |
---|
| 654 | an object Id. |
---|
| 655 | |
---|
| 656 | @subheading NOTES: |
---|
| 657 | |
---|
| 658 | This directive is strictly local and does not impact task scheduling. |
---|
| 659 | |
---|
| 660 | @c |
---|
| 661 | @c |
---|
| 662 | @c |
---|
| 663 | @page |
---|
| 664 | @subsection OBJECT_API_MINIMUM_CLASS - Obtain Minimum Class Value |
---|
| 665 | |
---|
| 666 | @cindex obtain minimum class value |
---|
| 667 | |
---|
| 668 | @subheading CALLING SEQUENCE: |
---|
| 669 | |
---|
| 670 | @ifset is-C |
---|
| 671 | @findex rtems_object_api_minimum_class |
---|
| 672 | @example |
---|
[e25611d] | 673 | int rtems_object_api_minimum_class( |
---|
| 674 | int api |
---|
[d5671b1] | 675 | ); |
---|
| 676 | @end example |
---|
| 677 | @end ifset |
---|
| 678 | |
---|
| 679 | @ifset is-Ada |
---|
| 680 | @example |
---|
[0bc8e5c] | 681 | procedure Object_API_Minimum_Class( |
---|
| 682 | API : in RTEMS.Unsigned32; |
---|
| 683 | Minimum : out RTEMS.Unsigned32 |
---|
| 684 | ); |
---|
[d5671b1] | 685 | @end example |
---|
| 686 | @end ifset |
---|
| 687 | |
---|
| 688 | @subheading DIRECTIVE STATUS CODES |
---|
| 689 | |
---|
| 690 | If @code{api} is not valid, -1 is returned. |
---|
| 691 | |
---|
| 692 | If successful, this service returns the minimum valid for the class |
---|
| 693 | portion of an object Id for the specified @code{api}. |
---|
| 694 | |
---|
| 695 | @subheading DESCRIPTION: |
---|
| 696 | |
---|
| 697 | This service returns the minimum valid for the class portion of |
---|
| 698 | an object Id for the specified @code{api}. |
---|
| 699 | |
---|
| 700 | @subheading NOTES: |
---|
| 701 | |
---|
| 702 | This directive is strictly local and does not impact task scheduling. |
---|
| 703 | |
---|
| 704 | @c |
---|
| 705 | @c |
---|
| 706 | @c |
---|
| 707 | @page |
---|
| 708 | @subsection OBJECT_API_MAXIMUM_CLASS - Obtain Maximum Class Value |
---|
| 709 | |
---|
| 710 | @cindex obtain maximum class value |
---|
| 711 | |
---|
| 712 | @subheading CALLING SEQUENCE: |
---|
| 713 | |
---|
| 714 | @ifset is-C |
---|
| 715 | @findex rtems_object_api_maximum_class |
---|
| 716 | @example |
---|
[e25611d] | 717 | int rtems_object_api_maximum_class( |
---|
| 718 | int api |
---|
[d5671b1] | 719 | ); |
---|
| 720 | @end example |
---|
| 721 | @end ifset |
---|
| 722 | |
---|
| 723 | @ifset is-Ada |
---|
| 724 | @example |
---|
[0bc8e5c] | 725 | procedure Object_API_Maximum_Class( |
---|
| 726 | API : in RTEMS.Unsigned32; |
---|
| 727 | Maximum : out RTEMS.Unsigned32 |
---|
| 728 | ); |
---|
[d5671b1] | 729 | @end example |
---|
| 730 | @end ifset |
---|
| 731 | |
---|
| 732 | @subheading DIRECTIVE STATUS CODES |
---|
| 733 | |
---|
| 734 | If @code{api} is not valid, -1 is returned. |
---|
| 735 | |
---|
| 736 | If successful, this service returns the maximum valid for the class |
---|
| 737 | portion of an object Id for the specified @code{api}. |
---|
| 738 | |
---|
| 739 | @subheading DESCRIPTION: |
---|
| 740 | |
---|
| 741 | This service returns the maximum valid for the class portion of |
---|
| 742 | an object Id for the specified @code{api}. |
---|
| 743 | |
---|
| 744 | @subheading NOTES: |
---|
| 745 | |
---|
| 746 | This directive is strictly local and does not impact task scheduling. |
---|
| 747 | |
---|
| 748 | |
---|
| 749 | @c |
---|
| 750 | @c |
---|
| 751 | @c |
---|
| 752 | @page |
---|
| 753 | @subsection OBJECT_GET_API_NAME - Obtain API Name |
---|
| 754 | |
---|
| 755 | @cindex obtain API name |
---|
| 756 | |
---|
| 757 | @subheading CALLING SEQUENCE: |
---|
| 758 | |
---|
| 759 | @ifset is-C |
---|
| 760 | @findex rtems_object_get_api_name |
---|
| 761 | @example |
---|
| 762 | const char *rtems_object_get_api_name( |
---|
[e25611d] | 763 | int api |
---|
[d5671b1] | 764 | ); |
---|
| 765 | @end example |
---|
| 766 | @end ifset |
---|
| 767 | |
---|
| 768 | @ifset is-Ada |
---|
| 769 | @example |
---|
[0bc8e5c] | 770 | procedure Object_Get_API_Name( |
---|
| 771 | API : in RTEMS.Unsigned32; |
---|
| 772 | Name : out String |
---|
| 773 | ); |
---|
[d5671b1] | 774 | @end example |
---|
| 775 | @end ifset |
---|
| 776 | |
---|
| 777 | @subheading DIRECTIVE STATUS CODES |
---|
| 778 | |
---|
| 779 | If @code{api} is not valid, the string @code{"BAD API"} is returned. |
---|
| 780 | |
---|
| 781 | If successful, this service returns a pointer to a string |
---|
| 782 | containing the name of the specified @code{api}. |
---|
| 783 | |
---|
| 784 | @subheading DESCRIPTION: |
---|
| 785 | |
---|
| 786 | This service returns the name of the specified @code{api}. |
---|
| 787 | |
---|
| 788 | @subheading NOTES: |
---|
| 789 | |
---|
| 790 | This directive is strictly local and does not impact task scheduling. |
---|
| 791 | |
---|
| 792 | The string returned is from constant space. Do not modify |
---|
| 793 | or free it. |
---|
| 794 | |
---|
| 795 | @c |
---|
| 796 | @c |
---|
| 797 | @c |
---|
| 798 | @page |
---|
| 799 | @subsection OBJECT_GET_API_CLASS_NAME - Obtain Class Name |
---|
| 800 | |
---|
| 801 | @cindex obtain class name |
---|
| 802 | |
---|
| 803 | @subheading CALLING SEQUENCE: |
---|
| 804 | |
---|
| 805 | @ifset is-C |
---|
| 806 | @findex rtems_object_get_api_class_name |
---|
| 807 | @example |
---|
| 808 | const char *rtems_object_get_api_class_name( |
---|
[e25611d] | 809 | int the_api, |
---|
| 810 | int the_class |
---|
[d5671b1] | 811 | ); |
---|
| 812 | @end example |
---|
| 813 | @end ifset |
---|
| 814 | |
---|
| 815 | @ifset is-Ada |
---|
| 816 | @example |
---|
[0bc8e5c] | 817 | procedure Object_Get_API_Class_Name( |
---|
| 818 | The_API : in RTEMS.Unsigned32; |
---|
| 819 | The_Class : in RTEMS.Unsigned32; |
---|
| 820 | Name : out String |
---|
| 821 | ); |
---|
[d5671b1] | 822 | @end example |
---|
| 823 | @end ifset |
---|
| 824 | |
---|
| 825 | @subheading DIRECTIVE STATUS CODES |
---|
| 826 | |
---|
[0bc8e5c] | 827 | If @code{the_api} is not valid, the string @code{"BAD API"} is returned. |
---|
[d5671b1] | 828 | |
---|
[0bc8e5c] | 829 | If @code{the_class} is not valid, the string @code{"BAD CLASS"} is returned. |
---|
[d5671b1] | 830 | |
---|
| 831 | If successful, this service returns a pointer to a string |
---|
[0bc8e5c] | 832 | containing the name of the specified @code{the_api}/@code{the_class} pair. |
---|
[d5671b1] | 833 | |
---|
| 834 | @subheading DESCRIPTION: |
---|
| 835 | |
---|
| 836 | This service returns the name of the object class indicated by the |
---|
[0bc8e5c] | 837 | specified @code{the_api} and @code{the_class}. |
---|
[d5671b1] | 838 | |
---|
| 839 | @subheading NOTES: |
---|
| 840 | |
---|
| 841 | This directive is strictly local and does not impact task scheduling. |
---|
| 842 | |
---|
| 843 | The string returned is from constant space. Do not modify |
---|
| 844 | or free it. |
---|
| 845 | |
---|
| 846 | @c |
---|
| 847 | @c |
---|
| 848 | @c |
---|
| 849 | @page |
---|
| 850 | @subsection OBJECT_GET_CLASS_INFORMATION - Obtain Class Information |
---|
| 851 | |
---|
| 852 | @cindex obtain class information |
---|
| 853 | |
---|
| 854 | @subheading CALLING SEQUENCE: |
---|
| 855 | |
---|
| 856 | @ifset is-C |
---|
| 857 | @findex rtems_object_get_class_information |
---|
| 858 | @example |
---|
| 859 | rtems_status_code rtems_object_get_class_information( |
---|
[e25611d] | 860 | int the_api, |
---|
| 861 | int the_class, |
---|
[d5671b1] | 862 | rtems_object_api_class_information *info |
---|
| 863 | ); |
---|
| 864 | @end example |
---|
| 865 | @end ifset |
---|
| 866 | |
---|
| 867 | @ifset is-Ada |
---|
| 868 | @example |
---|
[0bc8e5c] | 869 | procedure Object_Get_Class_Information( |
---|
| 870 | The_API : in RTEMS.Unsigned32; |
---|
| 871 | The_Class : in RTEMS.Unsigned32; |
---|
| 872 | Info : out RTEMS.Object_API_Class_Information; |
---|
| 873 | Result : out RTEMS.Status_Codes |
---|
| 874 | ); |
---|
[d5671b1] | 875 | @end example |
---|
| 876 | @end ifset |
---|
| 877 | |
---|
| 878 | @subheading DIRECTIVE STATUS CODES |
---|
| 879 | @code{@value{RPREFIX}SUCCESSFUL} - information obtained successfully@* |
---|
| 880 | @code{@value{RPREFIX}INVALID_ADDRESS} - @code{info} is NULL@* |
---|
[0bc8e5c] | 881 | @code{@value{RPREFIX}INVALID_NUMBER} - invalid @code{api} or @code{the_class} |
---|
[d5671b1] | 882 | |
---|
| 883 | If successful, the structure located at @code{info} will be filled |
---|
[0bc8e5c] | 884 | in with information about the specified @code{api}/@code{the_class} pairing. |
---|
[d5671b1] | 885 | |
---|
| 886 | @subheading DESCRIPTION: |
---|
| 887 | |
---|
| 888 | This service returns information about the object class indicated by the |
---|
[0bc8e5c] | 889 | specified @code{api} and @code{the_class}. This structure is defined as |
---|
[d5671b1] | 890 | follows: |
---|
| 891 | |
---|
[0bc8e5c] | 892 | @ifset is-C |
---|
[d5671b1] | 893 | @example |
---|
| 894 | typedef struct @{ |
---|
| 895 | rtems_id minimum_id; |
---|
| 896 | rtems_id maximum_id; |
---|
[e25611d] | 897 | int maximum; |
---|
[eaf1c0c] | 898 | bool auto_extend; |
---|
[e25611d] | 899 | int unallocated; |
---|
[d5671b1] | 900 | @} rtems_object_api_class_information; |
---|
| 901 | @end example |
---|
[0bc8e5c] | 902 | @end ifset |
---|
| 903 | |
---|
| 904 | @ifset is-Ada |
---|
| 905 | @example |
---|
| 906 | |
---|
| 907 | @end example |
---|
| 908 | @end ifset |
---|
| 909 | |
---|
[d5671b1] | 910 | |
---|
| 911 | @subheading NOTES: |
---|
| 912 | |
---|
| 913 | This directive is strictly local and does not impact task scheduling. |
---|
| 914 | |
---|