From 0d86b7111e378286bd61613c363c06cec39d0538 Mon Sep 17 00:00:00 2001 From: Chris Johns Date: Thu, 18 Feb 2016 15:29:28 +1100 Subject: Clean up. --- c_user/object_services.rst | 415 ++++++++++++++++++++++++--------------------- 1 file changed, 223 insertions(+), 192 deletions(-) (limited to 'c_user/object_services.rst') diff --git a/c_user/object_services.rst b/c_user/object_services.rst index f0437df..074af3f 100644 --- a/c_user/object_services.rst +++ b/c_user/object_services.rst @@ -1,3 +1,7 @@ +.. COMMENT: COPYRIGHT (c) 1988-2008. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + Object Services ############### @@ -6,46 +10,44 @@ Object Services Introduction ============ -RTEMS provides a collection of services to assist in the -management and usage of the objects created and utilized -via other managers. These services assist in the -manipulation of RTEMS objects independent of the API used -to create them. The object related services provided by -RTEMS are: +RTEMS provides a collection of services to assist in the management and usage +of the objects created and utilized via other managers. These services assist +in the manipulation of RTEMS objects independent of the API used to create +them. The object related services provided by RTEMS are: - build_id -- ``rtems_build_name`` - build object name from characters +- rtems_build_name_ - build object name from characters -- ``rtems_object_get_classic_name`` - lookup name from Id +- rtems_object_get_classic_name_ - lookup name from Id -- ``rtems_object_get_name`` - obtain object name as string +- rtems_object_get_name_ - obtain object name as string -- ``rtems_object_set_name`` - set object name +- rtems_object_set_name_ - set object name -- ``rtems_object_id_get_api`` - obtain API from Id +- rtems_object_id_get_api_ - obtain API from Id -- ``rtems_object_id_get_class`` - obtain class from Id +- rtems_object_id_get_class_ - obtain class from Id -- ``rtems_object_id_get_node`` - obtain node from Id +- rtems_object_id_get_node_ - obtain node from Id -- ``rtems_object_id_get_index`` - obtain index from Id +- rtems_object_id_get_index_ - obtain index from Id -- ``rtems_build_id`` - build object id from components +- rtems_build_id_ - build object id from components -- ``rtems_object_id_api_minimum`` - obtain minimum API value +- rtems_object_id_api_minimum_ - obtain minimum API value -- ``rtems_object_id_api_maximum`` - obtain maximum API value +- rtems_object_id_api_maximum_ - obtain maximum API value -- ``rtems_object_id_api_minimum_class`` - obtain minimum class value +- rtems_object_id_api_minimum_class_ - obtain minimum class value -- ``rtems_object_id_api_maximum_class`` - obtain maximum class value +- rtems_object_id_api_maximum_class_ - obtain maximum class value -- ``rtems_object_get_api_name`` - obtain API name +- rtems_object_get_api_name_ - obtain API name -- ``rtems_object_get_api_class_name`` - obtain class name +- rtems_object_get_api_class_name_ - obtain class name -- ``rtems_object_get_class_information`` - obtain class information +- rtems_object_get_class_information_ - obtain class information Background ========== @@ -53,46 +55,39 @@ Background APIs ---- -RTEMS implements multiple APIs including an Internal API, -the Classic API, and the POSIX API. These -APIs share the common foundation of SuperCore objects and -thus share object management code. This includes a common -scheme for object Ids and for managing object names whether -those names be in the thirty-two bit form used by the Classic -API or C strings. +RTEMS implements multiple APIs including an Internal API, the Classic API, and +the POSIX API. These APIs share the common foundation of SuperCore objects and +thus share object management code. This includes a common scheme for object Ids +and for managing object names whether those names be in the thirty-two bit form +used by the Classic API or C strings. -The object Id contains a field indicating the API that -an object instance is associated with. This field -holds a numerically small non-zero integer. +The object Id contains a field indicating the API that an object instance is +associated with. This field holds a numerically small non-zero integer. Object Classes -------------- -Each API consists of a collection of managers. Each manager -is responsible for instances of a particular object class. -Classic API Tasks and POSIX Mutexes example classes. +Each API consists of a collection of managers. Each manager is responsible for +instances of a particular object class. Classic API Tasks and POSIX Mutexes +example classes. -The object Id contains a field indicating the class that -an object instance is associated with. This field -holds a numerically small non-zero integer. In all APIs, -a class value of one is reserved for tasks or threads. +The object Id contains a field indicating the class that an object instance is +associated with. This field holds a numerically small non-zero integer. In +all APIs, a class value of one is reserved for tasks or threads. Object Names ------------ -Every RTEMS object which has an Id may also have a -name associated with it. Depending on the API, names -may be either thirty-two bit integers as in the Classic -API or strings as in the POSIX API. +Every RTEMS object which has an Id may also have a name associated with it. +Depending on the API, names may be either thirty-two bit integers as in the +Classic API or strings as in the POSIX API. -Some objects have Ids but do not have a defined way to associate -a name with them. For example, POSIX threads have -Ids but per POSIX do not have names. In RTEMS, objects -not defined to have thirty-two bit names may have string -names assigned to them via the ``rtems_object_set_name`` -service. The original impetus in providing this service -was so the normally anonymous POSIX threads could have -a user defined name in CPU Usage Reports. +Some objects have Ids but do not have a defined way to associate a name with +them. For example, POSIX threads have Ids but per POSIX do not have names. In +RTEMS, objects not defined to have thirty-two bit names may have string names +assigned to them via the ``rtems_object_set_name`` service. The original +impetus in providing this service was so the normally anonymous POSIX threads +could have a user defined name in CPU Usage Reports. Operations ========== @@ -100,9 +95,8 @@ Operations Decomposing and Recomposing an Object Id ---------------------------------------- -Services are provided to decompose an object Id into its -subordinate components. The following services are used -to do this: +Services are provided to decompose an object Id into its subordinate +components. The following services are used to do this: - ``rtems_object_id_get_api`` @@ -112,37 +106,38 @@ to do this: - ``rtems_object_id_get_index`` -The following C language example illustrates the -decomposition of an Id and printing the values. +The following C language example illustrates the decomposition of an Id and +printing the values. + .. code:: c void printObjectId(rtems_id id) { - printf( - "API=%d Class=%d Node=%d Index=%d\\n", - rtems_object_id_get_api(id), - rtems_object_id_get_class(id), - rtems_object_id_get_node(id), - rtems_object_id_get_index(id) - ); + printf( + "API=%d Class=%d Node=%d Index=%d\n", + rtems_object_id_get_api(id), + rtems_object_id_get_class(id), + rtems_object_id_get_node(id), + rtems_object_id_get_index(id) + ); } This prints the components of the Ids as integers. -It is also possible to construct an arbitrary Id using -the ``rtems_build_id`` service. The following -C language example illustrates how to construct the +It is also possible to construct an arbitrary Id using the ``rtems_build_id`` +service. The following C language example illustrates how to construct the "next Id." + .. code:: c rtems_id nextObjectId(rtems_id id) { - return rtems_build_id( - rtems_object_id_get_api(id), - rtems_object_id_get_class(id), - rtems_object_id_get_node(id), - rtems_object_id_get_index(id) + 1 - ); + return rtems_build_id( + rtems_object_id_get_api(id), + rtems_object_id_get_class(id), + rtems_object_id_get_node(id), + rtems_object_id_get_index(id) + 1 + ); } Note that this Id may not be valid in this @@ -151,32 +146,36 @@ system or associated with an allocated object. Printing an Object Id --------------------- -RTEMS also provides services to associate the API and Class -portions of an Object Id with strings. This allows the -application developer to provide more information about -an object in diagnostic messages. +RTEMS also provides services to associate the API and Class portions of an +Object Id with strings. This allows the application developer to provide more +information about an object in diagnostic messages. + +In the following C language example, an Id is decomposed into its constituent +parts and "pretty-printed." -In the following C language example, an Id is decomposed into -its constituent parts and "pretty-printed." .. code:: c void prettyPrintObjectId(rtems_id id) { - int tmpAPI, tmpClass; - tmpAPI = rtems_object_id_get_api(id), - tmpClass = rtems_object_id_get_class(id), - printf( - "API=%s Class=%s Node=%d Index=%d\\n", - rtems_object_get_api_name(tmpAPI), - rtems_object_get_api_class_name(tmpAPI, tmpClass), - rtems_object_id_get_node(id), - rtems_object_id_get_index(id) - ); + int tmpAPI, tmpClass; + + tmpAPI = rtems_object_id_get_api(id), + tmpClass = rtems_object_id_get_class(id), + + printf( + "API=%s Class=%s Node=%d Index=%d\n", + rtems_object_get_api_name(tmpAPI), + rtems_object_get_api_class_name(tmpAPI, tmpClass), + rtems_object_id_get_node(id), + rtems_object_id_get_index(id) + ); } Directives ========== +.. _rtems_build_name: + BUILD_NAME - Build object name from characters ---------------------------------------------- .. index:: build object name @@ -188,10 +187,10 @@ BUILD_NAME - Build object name from characters .. code:: c rtems_name rtems_build_name( - uint8_t c1, - uint8_t c2, - uint8_t c3, - uint8_t c4 + uint8_t c1, + uint8_t c2, + uint8_t c3, + uint8_t c4 ); **DIRECTIVE STATUS CODES** @@ -200,15 +199,16 @@ Returns a name constructed from the four characters. **DESCRIPTION:** -This service takes the four characters provided as arguments -and constructs a thirty-two bit object name with ``c1`` -in the most significant byte and ``c4`` in the least -significant byte. +This service takes the four characters provided as arguments and constructs a +thirty-two bit object name with ``c1`` in the most significant byte and ``c4`` +in the least significant byte. **NOTES:** This directive is strictly local and does not impact task scheduling. +.. _rtems_object_get_classic_name: + OBJECT_GET_CLASSIC_NAME - Lookup name from id --------------------------------------------- .. index:: get name from id @@ -216,30 +216,38 @@ OBJECT_GET_CLASSIC_NAME - Lookup name from id **CALLING SEQUENCE:** -.. index:: rtems_build_name +.. index:: rtems_object_get_classic_name .. code:: c rtems_status_code rtems_object_get_classic_name( - rtems_id id, - rtems_name \*name + rtems_id id, + rtems_name *name ); **DIRECTIVE STATUS CODES** -``RTEMS_SUCCESSFUL`` - name looked up successfully -``RTEMS_INVALID_ADDRESS`` - invalid name pointer -``RTEMS_INVALID_ID`` - invalid object id +.. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - name looked up successfully + * - ``RTEMS_INVALID_ADDRESS`` + - invalid name pointer + * - ``RTEMS_INVALID_ID`` + - invalid object id **DESCRIPTION:** -This service looks up the name for the object ``id`` specified -and, if found, places the result in ``*name``. +This service looks up the name for the object ``id`` specified and, if found, +places the result in ``*name``. **NOTES:** This directive is strictly local and does not impact task scheduling. +.. _rtems_object_get_name: + OBJECT_GET_NAME - Obtain object name as string ---------------------------------------------- .. index:: get object name as string @@ -251,27 +259,29 @@ OBJECT_GET_NAME - Obtain object name as string .. code:: c - char \*rtems_object_get_name( - rtems_id id, - size_t length, - char \*name + char* rtems_object_get_name( + rtems_id id, + size_t length, + char *name ); **DIRECTIVE STATUS CODES** -Returns a pointer to the name if successful or ``NULL`` -otherwise. +Returns a pointer to the name if successful or ``NULL`` otherwise. **DESCRIPTION:** -This service looks up the name of the object specified by``id`` and places it in the memory pointed to by ``name``. -Every attempt is made to return name as a printable string even -if the object has the Classic API thirty-two bit style name. +This service looks up the name of the object specified by ``id`` and places it +in the memory pointed to by ``name``. Every attempt is made to return name as +a printable string even if the object has the Classic API thirty-two bit style +name. **NOTES:** This directive is strictly local and does not impact task scheduling. +.. _rtems_object_set_name: + OBJECT_SET_NAME - Set object name --------------------------------- .. index:: set object name @@ -283,38 +293,43 @@ OBJECT_SET_NAME - Set object name .. code:: c rtems_status_code rtems_object_set_name( - rtems_id id, - const char \*name + rtems_id id, + const char *name ); **DIRECTIVE STATUS CODES** -``RTEMS_SUCCESSFUL`` - name looked up successfully -``RTEMS_INVALID_ADDRESS`` - invalid name pointer -``RTEMS_INVALID_ID`` - invalid object id +.. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - name looked up successfully + * - ``RTEMS_INVALID_ADDRESS`` + - invalid name pointer + * - ``RTEMS_INVALID_ID`` + - invalid object id **DESCRIPTION:** -This service sets the name of ``id`` to that specified -by the string located at ``name``. +This service sets the name of ``id`` to that specified by the string located at +``name``. **NOTES:** This directive is strictly local and does not impact task scheduling. -If the object specified by ``id`` is of a class that -has a string name, this method will free the existing -name to the RTEMS Workspace and allocate enough memory -from the RTEMS Workspace to make a copy of the string -located at ``name``. +If the object specified by ``id`` is of a class that has a string name, this +method will free the existing name to the RTEMS Workspace and allocate enough +memory from the RTEMS Workspace to make a copy of the string located at +``name``. -If the object specified by ``id`` is of a class that -has a thirty-two bit integer style name, then the first -four characters in ``*name`` will be used to construct -the name. -name to the RTEMS Workspace and allocate enough memory +If the object specified by ``id`` is of a class that has a thirty-two bit +integer style name, then the first four characters in ``*name`` will be used to +construct the name. name to the RTEMS Workspace and allocate enough memory from the RTEMS Workspace to make a copy of the string +.. _rtems_object_id_get_api: + OBJECT_ID_GET_API - Obtain API from Id -------------------------------------- .. index:: obtain API from id @@ -326,7 +341,7 @@ OBJECT_ID_GET_API - Obtain API from Id .. code:: c int rtems_object_id_get_api( - rtems_id id + rtems_id id ); **DIRECTIVE STATUS CODES** @@ -343,6 +358,8 @@ This directive is strictly local and does not impact task scheduling. This directive does NOT validate the ``id`` provided. +.. _rtems_object_id_get_class: + OBJECT_ID_GET_CLASS - Obtain Class from Id ------------------------------------------ .. index:: obtain class from object id @@ -354,7 +371,7 @@ OBJECT_ID_GET_CLASS - Obtain Class from Id .. code:: c int rtems_object_id_get_class( - rtems_id id + rtems_id id ); **DIRECTIVE STATUS CODES** @@ -371,6 +388,8 @@ This directive is strictly local and does not impact task scheduling. This directive does NOT validate the ``id`` provided. +.. _rtems_object_id_get_node: + OBJECT_ID_GET_NODE - Obtain Node from Id ---------------------------------------- .. index:: obtain node from object id @@ -382,7 +401,7 @@ OBJECT_ID_GET_NODE - Obtain Node from Id .. code:: c int rtems_object_id_get_node( - rtems_id id + rtems_id id ); **DIRECTIVE STATUS CODES** @@ -399,6 +418,8 @@ This directive is strictly local and does not impact task scheduling. This directive does NOT validate the ``id`` provided. +.. _rtems_object_id_get_index: + OBJECT_ID_GET_INDEX - Obtain Index from Id ------------------------------------------ .. index:: obtain index from object id @@ -410,7 +431,7 @@ OBJECT_ID_GET_INDEX - Obtain Index from Id .. code:: c int rtems_object_id_get_index( - rtems_id id + rtems_id id ); **DIRECTIVE STATUS CODES** @@ -427,6 +448,8 @@ This directive is strictly local and does not impact task scheduling. This directive does NOT validate the ``id`` provided. +.. _rtems_build_id: + BUILD_ID - Build Object Id From Components ------------------------------------------ .. index:: build object id from components @@ -438,10 +461,10 @@ BUILD_ID - Build Object Id From Components .. code:: c rtems_id rtems_build_id( - int the_api, - int the_class, - int the_node, - int the_index + int the_api, + int the_class, + int the_node, + int the_index ); **DIRECTIVE STATUS CODES** @@ -450,14 +473,17 @@ Returns an object Id constructed from the provided arguments. **DESCRIPTION:** -This service constructs an object Id from the provided``the_api``, ``the_class``, ``the_node``, and ``the_index``. +This service constructs an object Id from the provided ``the_api``, +``the_class``, ``the_node``, and ``the_index``. **NOTES:** This directive is strictly local and does not impact task scheduling. -This directive does NOT validate the arguments provided -or the Object id returned. +This directive does NOT validate the arguments provided or the Object id +returned. + +.. _rtems_object_id_api_minimum: OBJECT_ID_API_MINIMUM - Obtain Minimum API Value ------------------------------------------------ @@ -477,13 +503,14 @@ Returns the minimum valid for the API portion of an object Id. **DESCRIPTION:** -This service returns the minimum valid for the API portion of -an object Id. +This service returns the minimum valid for the API portion of an object Id. **NOTES:** This directive is strictly local and does not impact task scheduling. +.. _rtems_object_id_api_maximum: + OBJECT_ID_API_MAXIMUM - Obtain Maximum API Value ------------------------------------------------ .. index:: obtain maximum API value @@ -502,13 +529,14 @@ Returns the maximum valid for the API portion of an object Id. **DESCRIPTION:** -This service returns the maximum valid for the API portion of -an object Id. +This service returns the maximum valid for the API portion of an object Id. **NOTES:** This directive is strictly local and does not impact task scheduling. +.. _rtems_object_api_minimum_class: + OBJECT_API_MINIMUM_CLASS - Obtain Minimum Class Value ----------------------------------------------------- .. index:: obtain minimum class value @@ -520,25 +548,27 @@ OBJECT_API_MINIMUM_CLASS - Obtain Minimum Class Value .. code:: c int rtems_object_api_minimum_class( - int api + int api ); **DIRECTIVE STATUS CODES** If ``api`` is not valid, -1 is returned. -If successful, this service returns the minimum valid for the class -portion of an object Id for the specified ``api``. +If successful, this service returns the minimum valid for the class portion of +an object Id for the specified ``api``. **DESCRIPTION:** -This service returns the minimum valid for the class portion of -an object Id for the specified ``api``. +This service returns the minimum valid for the class portion of an object Id +for the specified ``api``. **NOTES:** This directive is strictly local and does not impact task scheduling. +.. _rtems_object_api_maximum_class: + OBJECT_API_MAXIMUM_CLASS - Obtain Maximum Class Value ----------------------------------------------------- .. index:: obtain maximum class value @@ -550,25 +580,27 @@ OBJECT_API_MAXIMUM_CLASS - Obtain Maximum Class Value .. code:: c int rtems_object_api_maximum_class( - int api + int api ); **DIRECTIVE STATUS CODES** If ``api`` is not valid, -1 is returned. -If successful, this service returns the maximum valid for the class -portion of an object Id for the specified ``api``. +If successful, this service returns the maximum valid for the class portion of +an object Id for the specified ``api``. **DESCRIPTION:** -This service returns the maximum valid for the class portion of -an object Id for the specified ``api``. +This service returns the maximum valid for the class portion of an object Id +for the specified ``api``. **NOTES:** This directive is strictly local and does not impact task scheduling. +.. _rtems_object_get_api_name: + OBJECT_GET_API_NAME - Obtain API Name ------------------------------------- .. index:: obtain API name @@ -579,16 +611,16 @@ OBJECT_GET_API_NAME - Obtain API Name .. code:: c - const char \*rtems_object_get_api_name( - int api + const char* rtems_object_get_api_name( + int api ); **DIRECTIVE STATUS CODES** If ``api`` is not valid, the string ``"BAD API"`` is returned. -If successful, this service returns a pointer to a string -containing the name of the specified ``api``. +If successful, this service returns a pointer to a string containing the name +of the specified ``api``. **DESCRIPTION:** @@ -598,8 +630,9 @@ This service returns the name of the specified ``api``. This directive is strictly local and does not impact task scheduling. -The string returned is from constant space. Do not modify -or free it. +The string returned is from constant space. Do not modify or free it. + +.. _rtems_object_get_api_class_name: OBJECT_GET_API_CLASS_NAME - Obtain Class Name --------------------------------------------- @@ -611,9 +644,9 @@ OBJECT_GET_API_CLASS_NAME - Obtain Class Name .. code:: c - const char \*rtems_object_get_api_class_name( - int the_api, - int the_class + const char *rtems_object_get_api_class_name( + int the_api, + int the_class ); **DIRECTIVE STATUS CODES** @@ -622,20 +655,19 @@ If ``the_api`` is not valid, the string ``"BAD API"`` is returned. If ``the_class`` is not valid, the string ``"BAD CLASS"`` is returned. -If successful, this service returns a pointer to a string -containing the name of the specified ``the_api``/``the_class`` pair. +If successful, this service returns a pointer to a string containing the name +of the specified ``the_api`` / ``the_class`` pair. **DESCRIPTION:** -This service returns the name of the object class indicated by the -specified ``the_api`` and ``the_class``. +This service returns the name of the object class indicated by the specified +``the_api`` and ``the_class``. **NOTES:** This directive is strictly local and does not impact task scheduling. -The string returned is from constant space. Do not modify -or free it. +The string returned is from constant space. Do not modify or free it. OBJECT_GET_CLASS_INFORMATION - Obtain Class Information ------------------------------------------------------- @@ -648,42 +680,41 @@ OBJECT_GET_CLASS_INFORMATION - Obtain Class Information .. code:: c rtems_status_code rtems_object_get_class_information( - int the_api, - int the_class, - rtems_object_api_class_information \*info + int the_api, + int the_class, + rtems_object_api_class_information *info ); **DIRECTIVE STATUS CODES** -``RTEMS_SUCCESSFUL`` - information obtained successfully -``RTEMS_INVALID_ADDRESS`` - ``info`` is NULL -``RTEMS_INVALID_NUMBER`` - invalid ``api`` or ``the_class`` +.. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - information obtained successfully + * - ``RTEMS_INVALID_ADDRESS`` + - ``info`` is NULL + * - ``RTEMS_INVALID_NUMBER`` + - invalid ``api`` or ``the_class`` -If successful, the structure located at ``info`` will be filled -in with information about the specified ``api``/``the_class`` pairing. +If successful, the structure located at ``info`` will be filled in with +information about the specified ``api`` / ``the_class`` pairing. **DESCRIPTION:** This service returns information about the object class indicated by the -specified ``api`` and ``the_class``. This structure is defined as -follows: +specified ``api`` and ``the_class``. This structure is defined as follows: + .. code:: c typedef struct { - rtems_id minimum_id; - rtems_id maximum_id; - int maximum; - bool auto_extend; - int unallocated; + rtems_id minimum_id; + rtems_id maximum_id; + int maximum; + bool auto_extend; + int unallocated; } rtems_object_api_class_information; **NOTES:** This directive is strictly local and does not impact task scheduling. - -.. COMMENT: COPYRIGHT (c) 1988-2008. - -.. COMMENT: On-Line Applications Research Corporation (OAR). - -.. COMMENT: All rights reserved. - -- cgit v1.2.3