mirror of
https://git.rtems.org/rtems-docs/
synced 2025-05-15 05:46:49 +08:00
c-user: Clarify object services
Add a "Constraints" paragraph to the documentation. Use function prototypes for the directives. Update #3993.
This commit is contained in:
Sebastian Huber
parent
221b61a9d3
commit
95e2f933cb
@ -1,6 +1,6 @@
|
||||
.. SPDX-License-Identifier: CC-BY-SA-4.0
|
||||
|
||||
.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
|
||||
.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de)
|
||||
.. Copyright (C) 1988, 2009 On-Line Applications Research Corporation (OAR)
|
||||
|
||||
.. This file is part of the RTEMS quality process and was automatically
|
||||
@ -47,14 +47,19 @@ components.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#define rtems_build_id( api, class, node, index )
|
||||
rtems_id rtems_build_id(
|
||||
uint32_t api,
|
||||
uint32_t the_class,
|
||||
uint32_t node,
|
||||
uint32_t index
|
||||
);
|
||||
|
||||
.. rubric:: PARAMETERS:
|
||||
|
||||
``api``
|
||||
This parameter is the API of the object identifier to build.
|
||||
|
||||
``class``
|
||||
``the_class``
|
||||
This parameter is the class of the object identifier to build.
|
||||
|
||||
``node``
|
||||
@ -68,9 +73,15 @@ components.
|
||||
Returns the object identifier built from the API, class, MPCI node, and index
|
||||
components.
|
||||
|
||||
.. rubric:: NOTES:
|
||||
.. rubric:: CONSTRAINTS:
|
||||
|
||||
This directive is strictly local and does not impact task scheduling.
|
||||
The following constraints apply to this directive:
|
||||
|
||||
* The directive is implemented by a macro and may be called from within C/C++
|
||||
constant expressions. In addition, a function implementation of the
|
||||
directive exists for bindings to other programming languages.
|
||||
|
||||
* The directive will not cause the calling task to be preempted.
|
||||
|
||||
.. Generated from spec:/rtems/object/if/build-name
|
||||
|
||||
@ -91,7 +102,7 @@ Builds the object name composed of the four characters.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#define rtems_build_name( c1, c2, c3, c4 )
|
||||
rtems_name rtems_build_name( char c1, char c2, char c3, char c4 );
|
||||
|
||||
.. rubric:: PARAMETERS:
|
||||
|
||||
@ -117,9 +128,15 @@ least significant 8-bits.
|
||||
|
||||
Returns the object name composed of the four characters.
|
||||
|
||||
.. rubric:: NOTES:
|
||||
.. rubric:: CONSTRAINTS:
|
||||
|
||||
This directive is strictly local and does not impact task scheduling.
|
||||
The following constraints apply to this directive:
|
||||
|
||||
* The directive is implemented by a macro and may be called from within C/C++
|
||||
constant expressions. In addition, a function implementation of the
|
||||
directive exists for bindings to other programming languages.
|
||||
|
||||
* The directive will not cause the calling task to be preempted.
|
||||
|
||||
.. Generated from spec:/rtems/object/if/get-classic-name
|
||||
|
||||
@ -173,9 +190,13 @@ Gets the object name associated with the object identifier.
|
||||
:c:macro:`RTEMS_INVALID_ID`
|
||||
There was no object associated with the object identifier.
|
||||
|
||||
.. rubric:: NOTES:
|
||||
.. rubric:: CONSTRAINTS:
|
||||
|
||||
This directive is strictly local and does not impact task scheduling.
|
||||
The following constraints apply to this directive:
|
||||
|
||||
* The directive may be called from within any runtime context.
|
||||
|
||||
* The directive will not cause the calling task to be preempted.
|
||||
|
||||
.. Generated from spec:/rtems/object/if/get-name
|
||||
|
||||
@ -235,10 +256,13 @@ string even if the object has the Classic API 32-bit integer style name.
|
||||
Returns the ``name`` parameter value, if there is an object name associated
|
||||
with the object identifier.
|
||||
|
||||
.. rubric:: NOTES:
|
||||
.. rubric:: CONSTRAINTS:
|
||||
|
||||
This directive may cause the calling task to be preempted due to an obtain and
|
||||
release of the object allocator mutex.
|
||||
The following constraints apply to this directive:
|
||||
|
||||
* The directive may be called from within any runtime context.
|
||||
|
||||
* The directive will not cause the calling task to be preempted.
|
||||
|
||||
.. Generated from spec:/rtems/object/if/set-name
|
||||
|
||||
@ -293,9 +317,6 @@ This directive will set the object name based upon the user string.
|
||||
|
||||
.. rubric:: NOTES:
|
||||
|
||||
This directive may cause the calling task to be preempted due to an obtain and
|
||||
release of the object allocator mutex.
|
||||
|
||||
This directive can be used to set the name of objects which do not have a
|
||||
naming scheme per their API.
|
||||
|
||||
@ -308,6 +329,17 @@ If the object specified by ``id`` is of a class that has a 32-bit integer style
|
||||
name, then the first four characters in ``name`` will be used to construct the
|
||||
name.
|
||||
|
||||
.. rubric:: CONSTRAINTS:
|
||||
|
||||
The following constraints apply to this directive:
|
||||
|
||||
* The directive may be called from within device driver initialization context.
|
||||
|
||||
* The directive may be called from within task context.
|
||||
|
||||
* The directive may obtain and release the object allocator mutex. This may
|
||||
cause the calling task to be preempted.
|
||||
|
||||
.. Generated from spec:/rtems/object/if/id-get-api
|
||||
|
||||
.. raw:: latex
|
||||
@ -327,7 +359,7 @@ Gets the API component of the object identifier.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#define rtems_object_id_get_api( id )
|
||||
int rtems_object_id_get_api( rtems_id id );
|
||||
|
||||
.. rubric:: PARAMETERS:
|
||||
|
||||
@ -340,11 +372,17 @@ Returns the API component of the object identifier.
|
||||
|
||||
.. rubric:: NOTES:
|
||||
|
||||
This directive is strictly local and does not impact task scheduling.
|
||||
|
||||
This directive does not validate the object identifier provided in ``id``.
|
||||
|
||||
A body is also provided.
|
||||
.. rubric:: CONSTRAINTS:
|
||||
|
||||
The following constraints apply to this directive:
|
||||
|
||||
* The directive is implemented by a macro and may be called from within C/C++
|
||||
constant expressions. In addition, a function implementation of the
|
||||
directive exists for bindings to other programming languages.
|
||||
|
||||
* The directive will not cause the calling task to be preempted.
|
||||
|
||||
.. Generated from spec:/rtems/object/if/id-get-class
|
||||
|
||||
@ -365,7 +403,7 @@ Gets the class component of the object identifier.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#define rtems_object_id_get_class( id )
|
||||
int rtems_object_id_get_class( rtems_id id );
|
||||
|
||||
.. rubric:: PARAMETERS:
|
||||
|
||||
@ -378,11 +416,17 @@ Returns the class component of the object identifier.
|
||||
|
||||
.. rubric:: NOTES:
|
||||
|
||||
This directive is strictly local and does not impact task scheduling.
|
||||
|
||||
This directive does not validate the object identifier provided in ``id``.
|
||||
|
||||
A body is also provided.
|
||||
.. rubric:: CONSTRAINTS:
|
||||
|
||||
The following constraints apply to this directive:
|
||||
|
||||
* The directive is implemented by a macro and may be called from within C/C++
|
||||
constant expressions. In addition, a function implementation of the
|
||||
directive exists for bindings to other programming languages.
|
||||
|
||||
* The directive will not cause the calling task to be preempted.
|
||||
|
||||
.. Generated from spec:/rtems/object/if/id-get-node
|
||||
|
||||
@ -403,7 +447,7 @@ Gets the MPCI node component of the object identifier.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#define rtems_object_id_get_node( id )
|
||||
int rtems_object_id_get_node( rtems_id id );
|
||||
|
||||
.. rubric:: PARAMETERS:
|
||||
|
||||
@ -417,11 +461,17 @@ Returns the MPCI node component of the object identifier.
|
||||
|
||||
.. rubric:: NOTES:
|
||||
|
||||
This directive is strictly local and does not impact task scheduling.
|
||||
|
||||
This directive does not validate the object identifier provided in ``id``.
|
||||
|
||||
A body is also provided.
|
||||
.. rubric:: CONSTRAINTS:
|
||||
|
||||
The following constraints apply to this directive:
|
||||
|
||||
* The directive is implemented by a macro and may be called from within C/C++
|
||||
constant expressions. In addition, a function implementation of the
|
||||
directive exists for bindings to other programming languages.
|
||||
|
||||
* The directive will not cause the calling task to be preempted.
|
||||
|
||||
.. Generated from spec:/rtems/object/if/id-get-index
|
||||
|
||||
@ -442,7 +492,7 @@ Gets the index component of the object identifier.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#define rtems_object_id_get_index( id )
|
||||
int rtems_object_id_get_index( rtems_id id );
|
||||
|
||||
.. rubric:: PARAMETERS:
|
||||
|
||||
@ -455,11 +505,17 @@ Returns the index component of the object identifier.
|
||||
|
||||
.. rubric:: NOTES:
|
||||
|
||||
This directive is strictly local and does not impact task scheduling.
|
||||
|
||||
This directive does not validate the object identifier provided in ``id``.
|
||||
|
||||
A body is also provided.
|
||||
.. rubric:: CONSTRAINTS:
|
||||
|
||||
The following constraints apply to this directive:
|
||||
|
||||
* The directive is implemented by a macro and may be called from within C/C++
|
||||
constant expressions. In addition, a function implementation of the
|
||||
directive exists for bindings to other programming languages.
|
||||
|
||||
* The directive will not cause the calling task to be preempted.
|
||||
|
||||
.. Generated from spec:/rtems/object/if/id-api-minimum
|
||||
|
||||
@ -480,17 +536,21 @@ Gets the lowest valid value for the API component of an object identifier.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#define rtems_object_id_api_minimum()
|
||||
int rtems_object_id_api_minimum( void );
|
||||
|
||||
.. rubric:: RETURN VALUES:
|
||||
|
||||
Returns the lowest valid value for the API component of an object identifier.
|
||||
|
||||
.. rubric:: NOTES:
|
||||
.. rubric:: CONSTRAINTS:
|
||||
|
||||
This directive is strictly local and does not impact task scheduling.
|
||||
The following constraints apply to this directive:
|
||||
|
||||
A body is also provided.
|
||||
* The directive is implemented by a macro and may be called from within C/C++
|
||||
constant expressions. In addition, a function implementation of the
|
||||
directive exists for bindings to other programming languages.
|
||||
|
||||
* The directive will not cause the calling task to be preempted.
|
||||
|
||||
.. Generated from spec:/rtems/object/if/id-api-maximum
|
||||
|
||||
@ -511,17 +571,21 @@ Gets the highest valid value for the API component of an object identifier.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#define rtems_object_id_api_maximum()
|
||||
int rtems_object_id_api_maximum( void );
|
||||
|
||||
.. rubric:: RETURN VALUES:
|
||||
|
||||
Returns the highest valid value for the API component of an object identifier.
|
||||
|
||||
.. rubric:: NOTES:
|
||||
.. rubric:: CONSTRAINTS:
|
||||
|
||||
This directive is strictly local and does not impact task scheduling.
|
||||
The following constraints apply to this directive:
|
||||
|
||||
A body is also provided.
|
||||
* The directive is implemented by a macro and may be called from within C/C++
|
||||
constant expressions. In addition, a function implementation of the
|
||||
directive exists for bindings to other programming languages.
|
||||
|
||||
* The directive will not cause the calling task to be preempted.
|
||||
|
||||
.. Generated from spec:/rtems/object/if/api-minimum-class
|
||||
|
||||
@ -556,9 +620,13 @@ Gets the lowest valid class value of the object API.
|
||||
|
||||
Returns the lowest valid class value of the object API.
|
||||
|
||||
.. rubric:: NOTES:
|
||||
.. rubric:: CONSTRAINTS:
|
||||
|
||||
This directive is strictly local and does not impact task scheduling.
|
||||
The following constraints apply to this directive:
|
||||
|
||||
* The directive may be called from within any runtime context.
|
||||
|
||||
* The directive will not cause the calling task to be preempted.
|
||||
|
||||
.. Generated from spec:/rtems/object/if/api-maximum-class
|
||||
|
||||
@ -593,9 +661,13 @@ Gets the highest valid class value of the object API.
|
||||
|
||||
Returns the highest valid class value of the object API.
|
||||
|
||||
.. rubric:: NOTES:
|
||||
.. rubric:: CONSTRAINTS:
|
||||
|
||||
This directive is strictly local and does not impact task scheduling.
|
||||
The following constraints apply to this directive:
|
||||
|
||||
* The directive may be called from within any runtime context.
|
||||
|
||||
* The directive will not cause the calling task to be preempted.
|
||||
|
||||
.. Generated from spec:/rtems/object/if/get-api-name
|
||||
|
||||
@ -632,10 +704,16 @@ Returns a descriptive name of the API, if the API was valid.
|
||||
|
||||
.. rubric:: 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.
|
||||
|
||||
.. rubric:: CONSTRAINTS:
|
||||
|
||||
The following constraints apply to this directive:
|
||||
|
||||
* The directive may be called from within any runtime context.
|
||||
|
||||
* The directive will not cause the calling task to be preempted.
|
||||
|
||||
.. Generated from spec:/rtems/object/if/get-api-class-name
|
||||
|
||||
.. raw:: latex
|
||||
@ -678,10 +756,16 @@ the API were valid.
|
||||
|
||||
.. rubric:: 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.
|
||||
|
||||
.. rubric:: CONSTRAINTS:
|
||||
|
||||
The following constraints apply to this directive:
|
||||
|
||||
* The directive may be called from within any runtime context.
|
||||
|
||||
* The directive will not cause the calling task to be preempted.
|
||||
|
||||
.. Generated from spec:/rtems/object/if/get-class-information
|
||||
|
||||
.. raw:: latex
|
||||
@ -733,9 +817,13 @@ Gets the object class information of the object class of the object API.
|
||||
:c:macro:`RTEMS_INVALID_NUMBER`
|
||||
The class of the API or the API was invalid.
|
||||
|
||||
.. rubric:: NOTES:
|
||||
.. rubric:: CONSTRAINTS:
|
||||
|
||||
This directive is strictly local and does not impact task scheduling.
|
||||
The following constraints apply to this directive:
|
||||
|
||||
* The directive may be called from within any runtime context.
|
||||
|
||||
* The directive will not cause the calling task to be preempted.
|
||||
|
||||
.. Generated from spec:/rtems/object/if/get-local-node
|
||||
|
||||
@ -762,9 +850,13 @@ Gets the local MPCI node number.
|
||||
|
||||
Returns the local MPCI node number.
|
||||
|
||||
.. rubric:: NOTES:
|
||||
.. rubric:: CONSTRAINTS:
|
||||
|
||||
This directive is strictly local and does not impact task scheduling.
|
||||
The following constraints apply to this directive:
|
||||
|
||||
* The directive may be called from within any runtime context.
|
||||
|
||||
* The directive will not cause the calling task to be preempted.
|
||||
|
||||
.. Generated from spec:/rtems/object/if/id-initial
|
||||
|
||||
@ -804,6 +896,10 @@ MPCI node components.
|
||||
Returns the object identifier with the lowest index built from the API, class,
|
||||
and MPCI node components.
|
||||
|
||||
.. rubric:: NOTES:
|
||||
.. rubric:: CONSTRAINTS:
|
||||
|
||||
This directive is strictly local and does not impact task scheduling.
|
||||
The following constraints apply to this directive:
|
||||
|
||||
* The directive may be called from within any runtime context.
|
||||
|
||||
* The directive will not cause the calling task to be preempted.
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
.. SPDX-License-Identifier: CC-BY-SA-4.0
|
||||
|
||||
.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
|
||||
.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de)
|
||||
.. Copyright (C) 1988, 2009 On-Line Applications Research Corporation (OAR)
|
||||
|
||||
.. This file is part of the RTEMS quality process and was automatically
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user