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