diff options
Diffstat (limited to 'c-user')
162 files changed, 34254 insertions, 16223 deletions
diff --git a/c-user/barrier/background.rst b/c-user/barrier/background.rst new file mode 100644 index 0000000..7a42d97 --- /dev/null +++ b/c-user/barrier/background.rst @@ -0,0 +1,68 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2018 On-Line Applications Research Corporation (OAR) + +Background +========== + +A barrier can be viewed as a gate at which tasks wait until the gate is opened. +This has many analogies in the real world. Horses and other farm animals may +approach a closed gate and gather in front of it, waiting for someone to open +the gate so they may proceed. Similarly, ticket holders gather at the gates of +arenas before concerts or sporting events waiting for the arena personnel to +open the gates so they may enter. + +Barriers are useful during application initialization. Each application task +can perform its local initialization before waiting for the application as a +whole to be initialized. Once all tasks have completed their independent +initializations, the "application ready" barrier can be released. + +Automatic Versus Manual Barriers +-------------------------------- + +Just as with a real-world gate, barriers may be configured to be manually +opened or automatically opened. All tasks calling the ``rtems_barrier_wait`` +directive will block until a controlling task invokes +the ``rtems_barrier_release`` directive. + +Automatic barriers are created with a limit to the number of tasks which may +simultaneously block at the barrier. Once this limit is reached, all of the +tasks are released. For example, if the automatic limit is ten tasks, then the +first nine tasks calling the ``rtems_barrier_wait`` directive will block. When +the tenth task calls the ``rtems_barrier_wait`` directive, the nine blocked +tasks will be released and the tenth task returns to the caller without +blocking. + +Building a Barrier Attribute Set +-------------------------------- + +In general, an attribute set is built by a bitwise OR of the desired attribute +components. The following table lists the set of valid barrier attributes: + +``RTEMS_BARRIER_AUTOMATIC_RELEASE`` + automatically release the barrier when the configured number of tasks are + blocked + +``RTEMS_BARRIER_MANUAL_RELEASE`` + only release the barrier when the application invokes the + ``rtems_barrier_release`` directive. (default) + +.. note:: + + Barriers only support FIFO blocking order because all waiting tasks are + released as a set. Thus the released tasks will all become ready to execute + at the same time and compete for the processor based upon their priority. + +Attribute values are specifically designed to be mutually exclusive, therefore +bitwise OR and addition operations are equivalent as long as each attribute +appears exactly once in the component list. An attribute listed as a default +is not required to appear in the attribute list, although it is a good +programming practice to specify default attributes. If all defaults are +desired, the attribute ``RTEMS_DEFAULT_ATTRIBUTES`` should be specified on this +call. + +This example demonstrates the attribute_set parameter needed to create a +barrier with the automatic release policy. The ``attribute_set`` parameter +passed to the ``rtems_barrier_create`` directive will be +``RTEMS_BARRIER_AUTOMATIC_RELEASE``. In this case, the user must also specify +the ``maximum_waiters`` parameter. diff --git a/c-user/barrier/directives.rst b/c-user/barrier/directives.rst new file mode 100644 index 0000000..4eded62 --- /dev/null +++ b/c-user/barrier/directives.rst @@ -0,0 +1,415 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. _BarrierManagerDirectives: + +Directives +========== + +This section details the directives of the Barrier Manager. A subsection is +dedicated to each of this manager's directives and lists the calling sequence, +parameters, description, return values, and notes of the directive. + +.. Generated from spec:/rtems/barrier/if/create + +.. raw:: latex + + \clearpage + +.. index:: rtems_barrier_create() +.. index:: create a barrier + +.. _InterfaceRtemsBarrierCreate: + +rtems_barrier_create() +---------------------- + +Creates a barrier. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_barrier_create( + rtems_name name, + rtems_attribute attribute_set, + uint32_t maximum_waiters, + rtems_id *id + ); + +.. rubric:: PARAMETERS: + +``name`` + This parameter is the object name of the barrier. + +``attribute_set`` + This parameter is the attribute set of the barrier. + +``maximum_waiters`` + This parameter is the maximum count of waiters on an automatic release + barrier. + +``id`` + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the identifier of the created barrier + will be stored in this object. + +.. rubric:: DESCRIPTION: + +This directive creates a barrier which resides on the local node. The barrier +has the user-defined object name specified in ``name`` and the initial count +specified in ``attribute_set``. The assigned object identifier is returned in +``id``. This identifier is used to access the barrier with other barrier +related directives. + +The **attribute set** specified in ``attribute_set`` is built through a +*bitwise or* of the attribute constants described below. Not all combinations +of attributes are allowed. Some attributes are mutually exclusive. If +mutually exclusive attributes are combined, the behaviour is undefined. +Attributes not mentioned below are not evaluated by this directive and have no +effect. Default attributes can be selected by using the +:c:macro:`RTEMS_DEFAULT_ATTRIBUTES` constant. + +The **barrier class** is selected by the mutually exclusive +:c:macro:`RTEMS_BARRIER_MANUAL_RELEASE` and +:c:macro:`RTEMS_BARRIER_AUTOMATIC_RELEASE` attributes. + +* The **manual release class** is the default and can be emphasized through use + of the :c:macro:`RTEMS_BARRIER_MANUAL_RELEASE` attribute. For this class, + there is no limit on the number of tasks that will block at the barrier. Only + when the :ref:`InterfaceRtemsBarrierRelease` directive is invoked, are the + tasks waiting at the barrier unblocked. + +* The **automatic release class** is selected by the + :c:macro:`RTEMS_BARRIER_AUTOMATIC_RELEASE` attribute. For this class, tasks + calling the :ref:`InterfaceRtemsBarrierWait` directive will block until there + are ``maximum_waiters`` minus one tasks waiting at the barrier. When the + ``maximum_waiters`` task invokes the :ref:`InterfaceRtemsBarrierWait` + directive, the previous ``maximum_waiters`` - 1 tasks are automatically + released and the caller returns. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_NAME` + The ``name`` parameter was invalid. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``id`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_NUMBER` + The ``maximum_waiters`` parameter was 0 for an automatic release barrier. + +:c:macro:`RTEMS_TOO_MANY` + There was no inactive object available to create a barrier. The number of + barriers available to the application is configured through the + :ref:`CONFIGURE_MAXIMUM_BARRIERS` application configuration option. + +.. rubric:: NOTES: + +For control and maintenance of the barrier, RTEMS allocates a :term:`BCB` from +the local BCB free pool and initializes it. + +.. 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. + +* The number of barriers available to the application is configured through the + :ref:`CONFIGURE_MAXIMUM_BARRIERS` application configuration option. + +* Where the object class corresponding to the directive is configured to use + unlimited objects, the directive may allocate memory from the RTEMS + Workspace. + +.. Generated from spec:/rtems/barrier/if/ident + +.. raw:: latex + + \clearpage + +.. index:: rtems_barrier_ident() + +.. _InterfaceRtemsBarrierIdent: + +rtems_barrier_ident() +--------------------- + +Identifies a barrier by the object name. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_barrier_ident( rtems_name name, rtems_id *id ); + +.. rubric:: PARAMETERS: + +``name`` + This parameter is the object name to look up. + +``id`` + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the object identifier of an object with + the specified name will be stored in this object. + +.. rubric:: DESCRIPTION: + +This directive obtains a barrier identifier associated with the barrier name +specified in ``name``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``id`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_NAME` + The ``name`` parameter was 0. + +:c:macro:`RTEMS_INVALID_NAME` + There was no object with the specified name on the local node. + +.. rubric:: NOTES: + +If the barrier name is not unique, then the barrier identifier will match the +first barrier with that name in the search order. However, this barrier +identifier is not guaranteed to correspond to the desired barrier. + +The objects are searched from lowest to the highest index. Only the local node +is searched. + +The barrier identifier is used with other barrier related directives to access +the barrier. + +.. 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/barrier/if/delete + +.. raw:: latex + + \clearpage + +.. index:: rtems_barrier_delete() +.. index:: delete a barrier + +.. _InterfaceRtemsBarrierDelete: + +rtems_barrier_delete() +---------------------- + +Deletes the barrier. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_barrier_delete( rtems_id id ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the barrier identifier. + +.. rubric:: DESCRIPTION: + +This directive deletes the barrier specified by ``id``. All tasks blocked +waiting for the barrier to be released will be readied and returned a status +code which indicates that the barrier was deleted. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no barrier associated with the identifier specified by ``id``. + +.. rubric:: NOTES: + +The :term:`BCB` for the deleted barrier is reclaimed by RTEMS. + +.. 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. + +* The calling task does not have to be the task that created the object. Any + local task that knows the object identifier can delete the object. + +* Where the object class corresponding to the directive is configured to use + unlimited objects, the directive may free memory to the RTEMS Workspace. + +.. Generated from spec:/rtems/barrier/if/wait + +.. raw:: latex + + \clearpage + +.. index:: rtems_barrier_wait() +.. index:: wait at a barrier + +.. _InterfaceRtemsBarrierWait: + +rtems_barrier_wait() +-------------------- + +Waits at the barrier. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_barrier_wait( rtems_id id, rtems_interval timeout ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the barrier identifier. + +``timeout`` + This parameter is the timeout in clock ticks. Use + :c:macro:`RTEMS_NO_TIMEOUT` to wait potentially forever. + +.. rubric:: DESCRIPTION: + +This directive waits at the barrier specified by ``id``. The ``timeout`` +parameter defines how long the calling task is willing to wait. Use +:c:macro:`RTEMS_NO_TIMEOUT` to wait potentially forever, otherwise set a +timeout interval in clock ticks. + +Conceptually, the calling task should always be thought of as blocking when it +makes this call and being unblocked when the barrier is released. If the +barrier is configured for manual release, this rule of thumb will always be +valid. If the barrier is configured for automatic release, all callers will +block except for the one which trips the automatic release condition. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no barrier associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_TIMEOUT` + The timeout happened while the calling task was waiting at the barrier. + +:c:macro:`RTEMS_OBJECT_WAS_DELETED` + The barrier was deleted while the calling task was waiting at the barrier. + +.. rubric:: NOTES: + +For automatic release barriers, the maximum count of waiting tasks is defined +during barrier creation, see :ref:`InterfaceRtemsBarrierCreate`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within task context. + +* The timeout functionality of the directive requires a :term:`clock tick`. + +.. Generated from spec:/rtems/barrier/if/release + +.. raw:: latex + + \clearpage + +.. index:: rtems_barrier_release() +.. index:: release a barrier + +.. _InterfaceRtemsBarrierRelease: + +rtems_barrier_release() +----------------------- + +Releases the barrier. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_barrier_release( rtems_id id, uint32_t *released ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the barrier identifier. + +``released`` + This parameter is the pointer to an `uint32_t + <https://en.cppreference.com/w/c/types/integer>`_ object. When the + directive call is successful, the number of released tasks will be stored + in this object. + +.. rubric:: DESCRIPTION: + +This directive releases the barrier specified by ``id``. All tasks waiting at +the barrier will be unblocked. The number of released tasks will be returned +in ``released``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``released`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no barrier associated with the identifier specified by ``id``. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within task context. + +* The directive may unblock a task. This may cause the calling task to be + preempted. diff --git a/c-user/barrier/index.rst b/c-user/barrier/index.rst new file mode 100644 index 0000000..e924c83 --- /dev/null +++ b/c-user/barrier/index.rst @@ -0,0 +1,16 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 embedded brains GmbH & Co. KG + +.. index:: barrier + +.. _RTEMSAPIClassicBarrier: + +Barrier Manager +*************** + +.. toctree:: + + introduction + background + directives diff --git a/c-user/barrier/introduction.rst b/c-user/barrier/introduction.rst new file mode 100644 index 0000000..e1c957f --- /dev/null +++ b/c-user/barrier/introduction.rst @@ -0,0 +1,47 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/rtems/barrier/if/group + +.. _BarrierManagerIntroduction: + +Introduction +============ + +.. The following list was generated from: +.. spec:/rtems/barrier/if/create +.. spec:/rtems/barrier/if/ident +.. spec:/rtems/barrier/if/delete +.. spec:/rtems/barrier/if/wait +.. spec:/rtems/barrier/if/release + +The Barrier Manager provides a unique synchronization capability which can be +used to have a set of tasks block and be unblocked as a set. The directives +provided by the Barrier Manager are: + +* :ref:`InterfaceRtemsBarrierCreate` - Creates a barrier. + +* :ref:`InterfaceRtemsBarrierIdent` - Identifies a barrier by the object name. + +* :ref:`InterfaceRtemsBarrierDelete` - Deletes the barrier. + +* :ref:`InterfaceRtemsBarrierWait` - Waits at the barrier. + +* :ref:`InterfaceRtemsBarrierRelease` - Releases the barrier. diff --git a/c-user/barrier/operations.rst b/c-user/barrier/operations.rst new file mode 100644 index 0000000..52fd5d4 --- /dev/null +++ b/c-user/barrier/operations.rst @@ -0,0 +1,60 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2018 On-Line Applications Research Corporation (OAR) + +Operations +========== + +Creating a Barrier +------------------ + +The ``rtems_barrier_create`` directive creates a barrier with a user-specified +name and the desired attributes. RTEMS allocates a Barrier Control Block (BCB) +from the BCB free list. This data structure is used by RTEMS to manage the +newly created barrier. Also, a unique barrier ID is generated and returned to +the calling task. + +Obtaining Barrier IDs +--------------------- + +When a barrier is created, RTEMS generates a unique barrier ID and assigns it +to the created barrier until it is deleted. The barrier ID may be obtained by +either of two methods. First, as the result of an invocation of the +``rtems_barrier_create`` directive, the barrier ID is stored in a user provided +location. Second, the barrier ID may be obtained later using the +``rtems_barrier_ident`` directive. The barrier ID is used by other barrier +manager directives to access this barrier. + +Waiting at a Barrier +-------------------- + +The ``rtems_barrier_wait`` directive is used to wait at +the specified barrier. The task may wait forever for the barrier to be +released or it may specify a timeout. Specifying a timeout limits the interval +the task will wait before returning with an error status code. + +If the barrier is configured as automatic and there are already one less then +the maximum number of waiters, then the call will unblock all tasks waiting at +the barrier and the caller will return immediately. + +When the task does wait to acquire the barrier, then it is placed in the +barrier's task wait queue in FIFO order. All tasks waiting on a barrier are +returned an error code when the barrier is deleted. + +Releasing a Barrier +------------------- + +The ``rtems_barrier_release`` directive is used to release the specified +barrier. When the ``rtems_barrier_release`` is invoked, all tasks waiting at +the barrier are immediately made ready to execute and begin to compete for the +processor to execute. + +Deleting a Barrier +------------------ + +The ``rtems_barrier_delete`` directive removes a barrier from the system and +frees its control block. A barrier can be deleted by any local task that knows +the barrier's ID. As a result of this directive, all tasks blocked waiting for +the barrier to be released, will be readied and returned a status code which +indicates that the barrier was deleted. Any subsequent references to the +barrier's name and ID are invalid. diff --git a/c-user/barrier_manager.rst b/c-user/barrier_manager.rst deleted file mode 100644 index dc50eb5..0000000 --- a/c-user/barrier_manager.rst +++ /dev/null @@ -1,408 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-4.0 - -.. Copyright (C) 1988, 2008, 2018. -.. COMMENT: On-Line Applications Research Corporation (OAR). - -.. index:: barrier - -.. _barrier_manager: - -Barrier Manager -*************** - -Introduction -============ - -The barrier manager provides a unique synchronization capability which can be -used to have a set of tasks block and be unblocked as a set. The directives -provided by the barrier manager are: - -- rtems_barrier_create_ - Create a barrier - -- rtems_barrier_ident_ - Get ID of a barrier - -- rtems_barrier_delete_ - Delete a barrier - -- rtems_barrier_wait_ - Wait at a barrier - -- rtems_barrier_release_ - Release a barrier - -Background -========== - -A barrier can be viewed as a gate at which tasks wait until the gate is opened. -This has many analogies in the real world. Horses and other farm animals may -approach a closed gate and gather in front of it, waiting for someone to open -the gate so they may proceed. Similarly, ticket holders gather at the gates of -arenas before concerts or sporting events waiting for the arena personnel to -open the gates so they may enter. - -Barriers are useful during application initialization. Each application task -can perform its local initialization before waiting for the application as a -whole to be initialized. Once all tasks have completed their independent -initializations, the "application ready" barrier can be released. - -Automatic Versus Manual Barriers --------------------------------- - -Just as with a real-world gate, barriers may be configured to be manually -opened or automatically opened. All tasks calling the ``rtems_barrier_wait`` -directive will block until a controlling task invokes -the ``rtems_barrier_release`` directive. - -Automatic barriers are created with a limit to the number of tasks which may -simultaneously block at the barrier. Once this limit is reached, all of the -tasks are released. For example, if the automatic limit is ten tasks, then the -first nine tasks calling the ``rtems_barrier_wait`` directive will block. When -the tenth task calls the ``rtems_barrier_wait`` directive, the nine blocked -tasks will be released and the tenth task returns to the caller without -blocking. - -Building a Barrier Attribute Set --------------------------------- - -In general, an attribute set is built by a bitwise OR of the desired attribute -components. The following table lists the set of valid barrier attributes: - -``RTEMS_BARRIER_AUTOMATIC_RELEASE`` - automatically release the barrier when the configured number of tasks are - blocked - -``RTEMS_BARRIER_MANUAL_RELEASE`` - only release the barrier when the application invokes the - ``rtems_barrier_release`` directive. (default) - -.. note:: - - Barriers only support FIFO blocking order because all waiting tasks are - released as a set. Thus the released tasks will all become ready to execute - at the same time and compete for the processor based upon their priority. - -Attribute values are specifically designed to be mutually exclusive, therefore -bitwise OR and addition operations are equivalent as long as each attribute -appears exactly once in the component list. An attribute listed as a default -is not required to appear in the attribute list, although it is a good -programming practice to specify default attributes. If all defaults are -desired, the attribute ``RTEMS_DEFAULT_ATTRIBUTES`` should be specified on this -call. - -This example demonstrates the attribute_set parameter needed to create a -barrier with the automatic release policy. The ``attribute_set`` parameter -passed to the ``rtems_barrier_create`` directive will be -``RTEMS_BARRIER_AUTOMATIC_RELEASE``. In this case, the user must also specify -the ``maximum_waiters`` parameter. - -Operations -========== - -Creating a Barrier ------------------- - -The ``rtems_barrier_create`` directive creates a barrier with a user-specified -name and the desired attributes. RTEMS allocates a Barrier Control Block (BCB) -from the BCB free list. This data structure is used by RTEMS to manage the -newly created barrier. Also, a unique barrier ID is generated and returned to -the calling task. - -Obtaining Barrier IDs ---------------------- - -When a barrier is created, RTEMS generates a unique barrier ID and assigns it -to the created barrier until it is deleted. The barrier ID may be obtained by -either of two methods. First, as the result of an invocation of the -``rtems_barrier_create`` directive, the barrier ID is stored in a user provided -location. Second, the barrier ID may be obtained later using the -``rtems_barrier_ident`` directive. The barrier ID is used by other barrier -manager directives to access this barrier. - -Waiting at a Barrier --------------------- - -The ``rtems_barrier_wait`` directive is used to wait at -the specified barrier. The task may wait forever for the barrier to be -released or it may specify a timeout. Specifying a timeout limits the interval -the task will wait before returning with an error status code. - -If the barrier is configured as automatic and there are already one less then -the maximum number of waiters, then the call will unblock all tasks waiting at -the barrier and the caller will return immediately. - -When the task does wait to acquire the barrier, then it is placed in the -barrier's task wait queue in FIFO order. All tasks waiting on a barrier are -returned an error code when the barrier is deleted. - -Releasing a Barrier -------------------- - -The ``rtems_barrier_release`` directive is used to release the specified -barrier. When the ``rtems_barrier_release`` is invoked, all tasks waiting at -the barrier are immediately made ready to execute and begin to compete for the -processor to execute. - -Deleting a Barrier ------------------- - -The ``rtems_barrier_delete`` directive removes a barrier from the system and -frees its control block. A barrier can be deleted by any local task that knows -the barrier's ID. As a result of this directive, all tasks blocked waiting for -the barrier to be released, will be readied and returned a status code which -indicates that the barrier was deleted. Any subsequent references to the -barrier's name and ID are invalid. - -Directives -========== - -This section details the barrier manager's directives. A subsection is -dedicated to each of this manager's directives and describes the calling -sequence, related constants, usage, and status codes. - -.. raw:: latex - - \clearpage - -.. _rtems_barrier_create: - -.. index:: create a barrier -.. index:: rtems_barrier_create - -BARRIER_CREATE - Create a barrier ---------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_barrier_create( - rtems_name name, - rtems_attribute attribute_set, - uint32_t maximum_waiters, - rtems_id *id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - barrier created successfully - * - ``RTEMS_INVALID_NAME`` - - invalid barrier name - * - ``RTEMS_INVALID_ADDRESS`` - - ``id`` is NULL - * - ``RTEMS_TOO_MANY`` - - too many barriers created - -DESCRIPTION: - This directive creates a barrier which resides on the local node. The - created barrier has the user-defined name specified in ``name`` and the - initial count specified in ``count``. For control and maintenance of the - barrier, RTEMS allocates and initializes a BCB. The RTEMS-assigned barrier - id is returned in ``id``. This barrier id is used with other barrier - related directives to access the barrier. - - .. list-table:: - :class: rtems-table - - * - ``RTEMS_BARRIER_MANUAL_RELEASE`` - - only release - - Specifying ``RTEMS_BARRIER_AUTOMATIC_RELEASE`` in ``attribute_set`` causes - tasks calling the ``rtems_barrier_wait`` directive to block until there are - ``maximum_waiters - 1`` tasks waiting at the barrier. When the - ``maximum_waiters`` task invokes the ``rtems_barrier_wait`` directive, the - previous ``maximum_waiters - 1`` tasks are automatically released and the - caller returns. - - In contrast, when the ``RTEMS_BARRIER_MANUAL_RELEASE`` attribute is - specified, there is no limit on the number of tasks that will block at the - barrier. Only when the ``rtems_barrier_release`` directive is invoked, are - the tasks waiting at the barrier unblocked. - -NOTES: - This directive will not cause the calling task to be preempted. - - The following barrier attribute constants are defined by RTEMS: - - .. list-table:: - :class: rtems-table - - * - ``RTEMS_BARRIER_AUTOMATIC_RELEASE`` - - automatically release the barrier when the configured number of tasks are - blocked - * - ``RTEMS_BARRIER_MANUAL_RELEASE`` - - only release the barrier when the application invokes - the ``rtems_barrier_release`` directive. (default) - -.. raw:: latex - - \clearpage - -.. _rtems_barrier_ident: - -.. index:: get ID of a barrier -.. index:: obtain ID of a barrier -.. index:: rtems_barrier_ident - -BARRIER_IDENT - Get ID of a barrier ------------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_barrier_ident( - rtems_name name, - rtems_id *id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - barrier identified successfully - * - ``RTEMS_INVALID_NAME`` - - barrier name not found - * - ``RTEMS_INVALID_NODE`` - - invalid node id - -DESCRIPTION: - This directive obtains the barrier id associated with the barrier name. If - the barrier name is not unique, then the barrier id will match one of the - barriers with that name. However, this barrier id is not guaranteed to - correspond to the desired barrier. The barrier id is used by other barrier - related directives to access the barrier. - -NOTES: - This directive will not cause the running task to be preempted. - -.. raw:: latex - - \clearpage - -.. _rtems_barrier_delete: - -.. index:: delete a barrier -.. index:: rtems_barrier_delete - -BARRIER_DELETE - Delete a barrier ---------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_barrier_delete( - rtems_id id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - barrier deleted successfully - * - ``RTEMS_INVALID_ID`` - - invalid barrier id - -DESCRIPTION: - This directive deletes the barrier specified by ``id``. All tasks blocked - waiting for the barrier to be released will be readied and returned a - status code which indicates that the barrier was deleted. The BCB for this - barrier is reclaimed by RTEMS. - -NOTES: - The calling task will be preempted if it is enabled by the task's execution - mode and a higher priority local task is waiting on the deleted barrier. - The calling task will NOT be preempted if all of the tasks that are waiting - on the barrier are remote tasks. - - The calling task does not have to be the task that created the barrier. - Any local task that knows the barrier id can delete the barrier. - -.. raw:: latex - - \clearpage - -.. _rtems_barrier_wait: - -.. index:: wait at a barrier -.. index:: rtems_barrier_wait - -BARRIER_WAIT - Wait at a barrier ----------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_barrier_wait( - rtems_id id, - rtems_interval timeout - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - barrier released and task unblocked - * - ``RTEMS_UNSATISFIED`` - - barrier not available - * - ``RTEMS_TIMEOUT`` - - timed out waiting for barrier - * - ``RTEMS_OBJECT_WAS_DELETED`` - - barrier deleted while waiting - * - ``RTEMS_INVALID_ID`` - - invalid barrier id - -DESCRIPTION: - - This directive waits at the barrier specified by ``id``. The timeout - parameter specifies the maximum interval the calling task is willing to be - blocked waiting for the barrier. If it is set to ``RTEMS_NO_TIMEOUT``, - then the calling task will wait until the barrier is released. - - Conceptually, the calling task should always be thought of as blocking when - it makes this call and being unblocked when the barrier is released. If - the barrier is configured for manual release, this rule of thumb will - always be valid. If the barrier is configured for automatic release, all - callers will block except for the one which is the Nth task which trips the - automatic release condition. - -NOTES: - A clock tick is required to support the timeout functionality of this - directive. - -.. raw:: latex - - \clearpage - -.. _rtems_barrier_release: - -.. index:: release a barrier -.. index:: rtems_barrier_release - -BARRIER_RELEASE - Release a barrier ------------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_barrier_release( - rtems_id id, - uint32_t *released - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - barrier released successfully - * - ``RTEMS_INVALID_ID`` - - invalid barrier id - -DESCRIPTION: - This directive releases the barrier specified by id. All tasks waiting at - the barrier will be unblocked. - -NOTES: - The calling task may be preempted if it causes a higher priority task to be - made ready for execution. diff --git a/c-user/board_support_packages.rst b/c-user/board_support_packages.rst index e163190..4e1c991 100644 --- a/c-user/board_support_packages.rst +++ b/c-user/board_support_packages.rst @@ -205,7 +205,7 @@ deallocating the context area, the task initiation and reinitiation extensions would be responsible for priming the context area, and the task context switch extension would save and restore the context of the device. -For more information on user extensions, refer to :ref:`User Extensions Manager`. +For more information on user extensions, refer to :ref:`RTEMSAPIClassicUserext`. Multiprocessor Communications Interface (MPCI) ============================================== diff --git a/c-user/cache/directives.rst b/c-user/cache/directives.rst new file mode 100644 index 0000000..a97654e --- /dev/null +++ b/c-user/cache/directives.rst @@ -0,0 +1,665 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2016 Pavel Pisa +.. Copyright (C) 2014, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 2000, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. _CacheManagerDirectives: + +Directives +========== + +This section details the directives of the Cache Manager. A subsection is +dedicated to each of this manager's directives and lists the calling sequence, +parameters, description, return values, and notes of the directive. + +.. Generated from spec:/rtems/cache/if/flush-multiple-data-lines + +.. raw:: latex + + \clearpage + +.. index:: rtems_cache_flush_multiple_data_lines() + +.. _InterfaceRtemsCacheFlushMultipleDataLines: + +rtems_cache_flush_multiple_data_lines() +--------------------------------------- + +Flushes the data cache lines covering the memory area. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_cache_flush_multiple_data_lines( const void *begin, size_t size ); + +.. rubric:: PARAMETERS: + +``begin`` + This parameter is the begin address of the memory area to flush. + +``size`` + This parameter is the size in bytes of the memory area to flush. + +.. rubric:: DESCRIPTION: + +Dirty data cache lines covering the area are transfered to memory. Depending +on the cache implementation this may mark the lines as invalid. + +.. 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/cache/if/invalidate-multiple-data-lines + +.. raw:: latex + + \clearpage + +.. index:: rtems_cache_invalidate_multiple_data_lines() + +.. _InterfaceRtemsCacheInvalidateMultipleDataLines: + +rtems_cache_invalidate_multiple_data_lines() +-------------------------------------------- + +Invalidates the data cache lines covering the memory area. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_cache_invalidate_multiple_data_lines( + const void *begin, + size_t size + ); + +.. rubric:: PARAMETERS: + +``begin`` + This parameter is the begin address of the memory area to invalidate. + +``size`` + This parameter is the size in bytes of the memory area to invalidate. + +.. rubric:: DESCRIPTION: + +The cache lines covering the area are marked as invalid. A later read access +in the area will load the data from memory. + +.. rubric:: NOTES: + +In case the area is not aligned on cache line boundaries, then this operation +may destroy unrelated data. + +On some systems, the cache lines may be flushed before they are invalidated. + +.. 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/cache/if/invalidate-multiple-instruction-lines + +.. raw:: latex + + \clearpage + +.. index:: rtems_cache_invalidate_multiple_instruction_lines() + +.. _InterfaceRtemsCacheInvalidateMultipleInstructionLines: + +rtems_cache_invalidate_multiple_instruction_lines() +--------------------------------------------------- + +Invalidates the instruction cache lines covering the memory area. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_cache_invalidate_multiple_instruction_lines( + const void *begin, + size_t size + ); + +.. rubric:: PARAMETERS: + +``begin`` + This parameter is the begin address of the memory area to invalidate. + +``size`` + This parameter is the size in bytes of the memory area to invalidate. + +.. rubric:: DESCRIPTION: + +The cache lines covering the area are marked as invalid. A later instruction +fetch from the area will result in a load from memory. + +.. rubric:: NOTES: + +In SMP configurations, on processors without instruction cache snooping, this +operation will invalidate the instruction cache lines on all processors. + +.. 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/cache/if/instruction-sync-after-code-change + +.. raw:: latex + + \clearpage + +.. index:: rtems_cache_instruction_sync_after_code_change() + +.. _InterfaceRtemsCacheInstructionSyncAfterCodeChange: + +rtems_cache_instruction_sync_after_code_change() +------------------------------------------------ + +Ensures necessary synchronization required after code changes. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_cache_instruction_sync_after_code_change( + const void *begin, + size_t size + ); + +.. rubric:: PARAMETERS: + +``begin`` + This parameter is the begin address of the code area to synchronize. + +``size`` + This parameter is the size in bytes of the code area to synchronize. + +.. rubric:: NOTES: + +When code is loaded or modified, then most systems require synchronization +instructions to update the instruction caches so that the loaded or modified +code is fetched. For example, systems with separate data and instruction +caches or systems without instruction cache snooping. The directives should be +used by run time loader for example. + +.. 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/cache/if/get-maximal-line-size + +.. raw:: latex + + \clearpage + +.. index:: rtems_cache_get_maximal_line_size() + +.. _InterfaceRtemsCacheGetMaximalLineSize: + +rtems_cache_get_maximal_line_size() +----------------------------------- + +Gets the maximal cache line size in bytes of all caches (data, instruction, or +unified). + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + size_t rtems_cache_get_maximal_line_size( void ); + +.. rubric:: RETURN VALUES: + +``0`` + There is no cache present. + +Returns the maximal cache line size in bytes of all caches (data, instruction, +or unified). + +.. 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/cache/if/get-data-line-size + +.. raw:: latex + + \clearpage + +.. index:: rtems_cache_get_data_line_size() + +.. _InterfaceRtemsCacheGetDataLineSize: + +rtems_cache_get_data_line_size() +-------------------------------- + +Gets the data cache line size in bytes. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + size_t rtems_cache_get_data_line_size( void ); + +.. rubric:: RETURN VALUES: + +``0`` + There is no data cache present. + +Returns the data cache line size in bytes. For multi-level caches this is the +maximum of the cache line sizes of all levels. + +.. 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/cache/if/get-instruction-line-size + +.. raw:: latex + + \clearpage + +.. index:: rtems_cache_get_instruction_line_size() + +.. _InterfaceRtemsCacheGetInstructionLineSize: + +rtems_cache_get_instruction_line_size() +--------------------------------------- + +Gets the instruction cache line size in bytes. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + size_t rtems_cache_get_instruction_line_size( void ); + +.. rubric:: RETURN VALUES: + +``0`` + There is no instruction cache present. + +Returns the instruction cache line size in bytes. For multi-level caches this +is the maximum of the cache line sizes of all levels. + +.. 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/cache/if/get-data-size + +.. raw:: latex + + \clearpage + +.. index:: rtems_cache_get_data_cache_size() + +.. _InterfaceRtemsCacheGetDataCacheSize: + +rtems_cache_get_data_cache_size() +--------------------------------- + +Gets the data cache size in bytes for the cache level. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + size_t rtems_cache_get_data_cache_size( uint32_t level ); + +.. rubric:: PARAMETERS: + +``level`` + This parameter is the requested data cache level. The cache level zero + specifies the entire data cache. + +.. rubric:: RETURN VALUES: + +``0`` + There is no data cache present at the requested cache level. + +Returns the data cache size in bytes of the requested cache level. + +.. 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/cache/if/get-instruction-size + +.. raw:: latex + + \clearpage + +.. index:: rtems_cache_get_instruction_cache_size() + +.. _InterfaceRtemsCacheGetInstructionCacheSize: + +rtems_cache_get_instruction_cache_size() +---------------------------------------- + +Gets the instruction cache size in bytes for the cache level. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + size_t rtems_cache_get_instruction_cache_size( uint32_t level ); + +.. rubric:: PARAMETERS: + +``level`` + This parameter is the requested instruction cache level. The cache level + zero specifies the entire instruction cache. + +.. rubric:: RETURN VALUES: + +``0`` + There is no instruction cache present at the requested cache level. + +Returns the instruction cache size in bytes of the requested cache level. + +.. 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/cache/if/flush-entire-data + +.. raw:: latex + + \clearpage + +.. index:: rtems_cache_flush_entire_data() + +.. _InterfaceRtemsCacheFlushEntireData: + +rtems_cache_flush_entire_data() +------------------------------- + +Flushes the entire data cache. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_cache_flush_entire_data( void ); + +.. 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/cache/if/invalidate-entire-data + +.. raw:: latex + + \clearpage + +.. index:: rtems_cache_invalidate_entire_data() + +.. _InterfaceRtemsCacheInvalidateEntireData: + +rtems_cache_invalidate_entire_data() +------------------------------------ + +Invalidates the entire data cache. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_cache_invalidate_entire_data( void ); + +.. 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/cache/if/invalidate-entire-instruction + +.. raw:: latex + + \clearpage + +.. index:: rtems_cache_invalidate_entire_instruction() + +.. _InterfaceRtemsCacheInvalidateEntireInstruction: + +rtems_cache_invalidate_entire_instruction() +------------------------------------------- + +Invalidates the entire instruction cache. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_cache_invalidate_entire_instruction( void ); + +.. 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/cache/if/enable-data + +.. raw:: latex + + \clearpage + +.. index:: rtems_cache_enable_data() + +.. _InterfaceRtemsCacheEnableData: + +rtems_cache_enable_data() +------------------------- + +Enables the data cache. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_cache_enable_data( void ); + +.. 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/cache/if/disable-data + +.. raw:: latex + + \clearpage + +.. index:: rtems_cache_disable_data() + +.. _InterfaceRtemsCacheDisableData: + +rtems_cache_disable_data() +-------------------------- + +Disables the data cache. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_cache_disable_data( void ); + +.. 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/cache/if/enable-instruction + +.. raw:: latex + + \clearpage + +.. index:: rtems_cache_enable_instruction() + +.. _InterfaceRtemsCacheEnableInstruction: + +rtems_cache_enable_instruction() +-------------------------------- + +Enables the instruction cache. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_cache_enable_instruction( void ); + +.. 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/cache/if/disable-instruction + +.. raw:: latex + + \clearpage + +.. index:: rtems_cache_disable_instruction() + +.. _InterfaceRtemsCacheDisableInstruction: + +rtems_cache_disable_instruction() +--------------------------------- + +Disables the instruction cache. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_cache_disable_instruction( void ); + +.. 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/cache/if/aligned-malloc + +.. raw:: latex + + \clearpage + +.. index:: rtems_cache_aligned_malloc() + +.. _InterfaceRtemsCacheAlignedMalloc: + +rtems_cache_aligned_malloc() +---------------------------- + +Allocates memory from the C Program Heap which begins at a cache line boundary. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void *rtems_cache_aligned_malloc( size_t size ); + +.. rubric:: PARAMETERS: + +``size`` + This parameter is the size in bytes of the memory area to allocate. + +.. rubric:: RETURN VALUES: + +`NULL <https://en.cppreference.com/w/c/types/NULL>`_ + There is not enough memory available to satisfy the allocation request. + +Returns the begin address of the allocated memory. The begin address is on a +cache line boundary. + +.. 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. diff --git a/c-user/cache/index.rst b/c-user/cache/index.rst new file mode 100644 index 0000000..57c124f --- /dev/null +++ b/c-user/cache/index.rst @@ -0,0 +1,15 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2021 embedded brains GmbH & Co. KG + +.. index:: cache + +.. _RTEMSAPIClassicCache: + +Cache Manager +************* + +.. toctree:: + + introduction + directives diff --git a/c-user/cache/introduction.rst b/c-user/cache/introduction.rst new file mode 100644 index 0000000..a632c9c --- /dev/null +++ b/c-user/cache/introduction.rst @@ -0,0 +1,101 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2016 Pavel Pisa +.. Copyright (C) 2014, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 2000, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/rtems/cache/if/group + +.. _CacheManagerIntroduction: + +Introduction +============ + +.. The following list was generated from: +.. spec:/rtems/cache/if/flush-multiple-data-lines +.. spec:/rtems/cache/if/invalidate-multiple-data-lines +.. spec:/rtems/cache/if/invalidate-multiple-instruction-lines +.. spec:/rtems/cache/if/instruction-sync-after-code-change +.. spec:/rtems/cache/if/get-maximal-line-size +.. spec:/rtems/cache/if/get-data-line-size +.. spec:/rtems/cache/if/get-instruction-line-size +.. spec:/rtems/cache/if/get-data-size +.. spec:/rtems/cache/if/get-instruction-size +.. spec:/rtems/cache/if/flush-entire-data +.. spec:/rtems/cache/if/invalidate-entire-data +.. spec:/rtems/cache/if/invalidate-entire-instruction +.. spec:/rtems/cache/if/enable-data +.. spec:/rtems/cache/if/disable-data +.. spec:/rtems/cache/if/enable-instruction +.. spec:/rtems/cache/if/disable-instruction +.. spec:/rtems/cache/if/aligned-malloc + +The Cache Manager provides functions to perform maintenance operations for data +and instruction caches. + +The actual actions of the Cache Manager operations depend on the hardware and +the implementation provided by the CPU architecture port or a board support +package. Cache implementations tend to be highly hardware dependent. The +directives provided by the Cache Manager are: + +* :ref:`InterfaceRtemsCacheFlushMultipleDataLines` - Flushes the data cache + lines covering the memory area. + +* :ref:`InterfaceRtemsCacheInvalidateMultipleDataLines` - Invalidates the data + cache lines covering the memory area. + +* :ref:`InterfaceRtemsCacheInvalidateMultipleInstructionLines` - Invalidates + the instruction cache lines covering the memory area. + +* :ref:`InterfaceRtemsCacheInstructionSyncAfterCodeChange` - Ensures necessary + synchronization required after code changes. + +* :ref:`InterfaceRtemsCacheGetMaximalLineSize` - Gets the maximal cache line + size in bytes of all caches (data, instruction, or unified). + +* :ref:`InterfaceRtemsCacheGetDataLineSize` - Gets the data cache line size in + bytes. + +* :ref:`InterfaceRtemsCacheGetInstructionLineSize` - Gets the instruction cache + line size in bytes. + +* :ref:`InterfaceRtemsCacheGetDataCacheSize` - Gets the data cache size in + bytes for the cache level. + +* :ref:`InterfaceRtemsCacheGetInstructionCacheSize` - Gets the instruction + cache size in bytes for the cache level. + +* :ref:`InterfaceRtemsCacheFlushEntireData` - Flushes the entire data cache. + +* :ref:`InterfaceRtemsCacheInvalidateEntireData` - Invalidates the entire data + cache. + +* :ref:`InterfaceRtemsCacheInvalidateEntireInstruction` - Invalidates the + entire instruction cache. + +* :ref:`InterfaceRtemsCacheEnableData` - Enables the data cache. + +* :ref:`InterfaceRtemsCacheDisableData` - Disables the data cache. + +* :ref:`InterfaceRtemsCacheEnableInstruction` - Enables the instruction cache. + +* :ref:`InterfaceRtemsCacheDisableInstruction` - Disables the instruction + cache. + +* :ref:`InterfaceRtemsCacheAlignedMalloc` - Allocates memory from the C Program + Heap which begins at a cache line boundary. diff --git a/c-user/chains.rst b/c-user/chains.rst index 0dce1d9..ca80b4b 100644 --- a/c-user/chains.rst +++ b/c-user/chains.rst @@ -192,11 +192,12 @@ placed on another chain: rtems_chain_initialize_empty (out); - node = rtems_chain_head (chain); + node = rtems_chain_first (chain); + while (!rtems_chain_is_tail (chain, node)) { bar = (foo*) node; - rtems_chain_node* next_node = node->next; + rtems_chain_node* next_node = rtems_chain_next(node); if (strcmp (match, bar->data) == 0) { rtems_chain_extract (node); @@ -220,7 +221,7 @@ The section details the Chains directives. .. _rtems_chain_initialize: .. index:: chain initialize -.. index:: rtems_chain_initialize +.. index:: rtems_chain_initialize() Initialize Chain With Nodes --------------------------- @@ -258,7 +259,7 @@ NOTES: .. _rtems_chain_initialize_empty: .. index:: chain initialize empty -.. index:: rtems_chain_initialize_empty +.. index:: rtems_chain_initialize_empty() Initialize Empty ---------------- @@ -287,7 +288,7 @@ NOTES: .. _rtems_chain_is_null_node: .. index:: chain is node null -.. index:: rtems_chain_is_null_node +.. index:: rtems_chain_is_null_node() Is Null Node ? -------------- @@ -313,7 +314,7 @@ DESCRIPTION: .. _rtems_chain_head: .. index:: chain get head -.. index:: rtems_chain_head +.. index:: rtems_chain_head() Head ---- @@ -338,7 +339,7 @@ DESCRIPTION: .. _rtems_chain_tail: .. index:: chain get tail -.. index:: rtems_chain_tail +.. index:: rtems_chain_tail() Tail ---- @@ -363,7 +364,7 @@ DESCRIPTION: .. _rtems_chain_are_nodes_equal: .. index:: chare are nodes equal -.. index:: rtems_chain_are_nodes_equal +.. index:: rtems_chain_are_nodes_equal() Are Two Nodes Equal ? --------------------- @@ -391,7 +392,7 @@ DESCRIPTION: .. _rtems_chain_is_empty: .. index:: chain is chain empty -.. index:: rtems_chain_is_empty +.. index:: rtems_chain_is_empty() Is the Chain Empty ------------------ @@ -418,7 +419,7 @@ DESCRIPTION: .. _rtems_chain_is_first: .. index:: chain is node the first -.. index:: rtems_chain_is_first +.. index:: rtems_chain_is_first() Is this the First Node on the Chain ? ------------------------------------- @@ -445,7 +446,7 @@ DESCRIPTION: .. _rtems_chain_is_last: .. index:: chain is node the last -.. index:: rtems_chain_is_last +.. index:: rtems_chain_is_last() Is this the Last Node on the Chain ? ------------------------------------ @@ -472,7 +473,7 @@ DESCRIPTION: .. _rtems_chain_has_only_one_node: .. index:: chain only one node -.. index:: rtems_chain_has_only_one_node +.. index:: rtems_chain_has_only_one_node() Does this Chain have only One Node ? ------------------------------------ @@ -499,7 +500,7 @@ DESCRIPTION: .. _rtems_chain_node_count_unprotected: .. index:: chain only one node -.. index:: rtems_chain_node_count_unprotected +.. index:: rtems_chain_node_count_unprotected() Returns the node count of the chain (unprotected) ------------------------------------------------- @@ -524,7 +525,7 @@ DESCRIPTION: .. _rtems_chain_is_head: .. index:: chain is node the head -.. index:: rtems_chain_is_head +.. index:: rtems_chain_is_head() Is this Node the Chain Head ? ----------------------------- @@ -552,7 +553,7 @@ DESCRIPTION: .. _rtems_chain_is_tail: .. index:: chain is node the tail -.. index:: rtems_chain_is_tail +.. index:: rtems_chain_is_tail() Is this Node the Chain Tail ? ----------------------------- @@ -580,7 +581,7 @@ DESCRIPTION: .. _rtems_chain_extract: .. index:: chain extract a node -.. index:: rtems_chain_extract +.. index:: rtems_chain_extract() Extract a Node -------------- @@ -611,7 +612,7 @@ NOTES: .. _rtems_chain_extract_unprotected: .. index:: chain extract a node unprotected -.. index:: rtems_chain_extract_unprotected +.. index:: rtems_chain_extract_unprotected() Extract a Node (unprotected) ---------------------------- @@ -639,7 +640,7 @@ NOTES: .. _rtems_chain_get: .. index:: chain get first node -.. index:: rtems_chain_get +.. index:: rtems_chain_get() Get the First Node ------------------ @@ -672,7 +673,7 @@ NOTES: .. _rtems_chain_get_unprotected: .. index:: chain get first node -.. index:: rtems_chain_get_unprotected +.. index:: rtems_chain_get_unprotected() Get the First Node (unprotected) -------------------------------- @@ -701,7 +702,7 @@ NOTES: .. _rtems_chain_insert: .. index:: chain insert a node -.. index:: rtems_chain_insert +.. index:: rtems_chain_insert() Insert a Node ------------- @@ -734,7 +735,7 @@ NOTES: .. _rtems_chain_insert_unprotected: .. index:: chain insert a node unprotected -.. index:: rtems_chain_insert_unprotected +.. index:: rtems_chain_insert_unprotected() Insert a Node (unprotected) --------------------------- @@ -764,7 +765,7 @@ NOTES: .. _rtems_chain_append: .. index:: chain append a node -.. index:: rtems_chain_append +.. index:: rtems_chain_append() Append a Node ------------- @@ -796,7 +797,7 @@ NOTES: .. _rtems_chain_append_unprotected: .. index:: chain append a node unprotected -.. index:: rtems_chain_append_unprotected +.. index:: rtems_chain_append_unprotected() Append a Node (unprotected) --------------------------- @@ -825,7 +826,7 @@ NOTES: .. _rtems_chain_prepend: .. index:: prepend node -.. index:: rtems_chain_prepend +.. index:: rtems_chain_prepend() Prepend a Node -------------- @@ -857,7 +858,7 @@ NOTES: .. _rtems_chain_prepend_unprotected: .. index:: prepend node unprotected -.. index:: rtems_chain_prepend_unprotected +.. index:: rtems_chain_prepend_unprotected() Prepend a Node (unprotected) ---------------------------- diff --git a/c-user/clock/background.rst b/c-user/clock/background.rst new file mode 100644 index 0000000..11a3cb5 --- /dev/null +++ b/c-user/clock/background.rst @@ -0,0 +1,121 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Background +========== + +Required Support +---------------- + +For the features provided by the Clock Manager to be utilized, a :term:`Clock +Driver` is required. The Clock Driver usually provides a clock interrupt which +is serviced on each configured processor at each :term:`clock tick`. In +addition, the Clock Driver provides three clock sources: + +* clock tick + +* :term:`CLOCK_REALTIME` + +* :term:`CLOCK_MONOTONIC` + +The time of these clock sources advances at each clock tick. This yields the +time of the clock sources in a coarse resolution. To get the time of the +``CLOCK_REALTIME`` or ``CLOCK_MONOTONIC`` clock sources in a higher resolution, +the Clock Driver may use a clock device to get the time between clock ticks. + +.. _Time and Date Data Structures: + +Time and Date Data Structures +----------------------------- + +The clock facilities of the Clock Manager operate upon calendar time. These +directives utilize the following date and time structure for the native time +and date format: + +.. index:: rtems_time_of_day + +.. code-block:: c + + typedef struct { + uint32_t year; /* greater than 1987 */ + uint32_t month; /* 1 - 12 */ + uint32_t day; /* 1 - 31 */ + uint32_t hour; /* 0 - 23 */ + uint32_t minute; /* 0 - 59 */ + uint32_t second; /* 0 - 59 */ + uint32_t ticks; /* elapsed between seconds */ + } rtems_time_of_day; + +The native date and time format is the only format supported when setting the +system date and time using the :ref:`InterfaceRtemsClockSet` directive. Some +applications expect to operate on a *UNIX-style* date and time data structure. +For example, the :ref:`InterfaceRtemsClockGetTodTimeval` returns the date and +time in ``struct timeval`` format. + +.. index:: struct timeval +.. index:: struct timespec + +Some directives use data structures defined by :term:`POSIX`. The ``struct +timeval`` data structure has two members: ``tv_sec`` and ``tv_usec`` which are +seconds and microseconds, respectively. The ``struct timespec`` data structure +has two members: ``tv_sec`` and ``tv_nsec`` which are seconds and nanoseconds, +respectively. For :term:`CLOCK_REALTIME` time points, the ``tv_sec`` member in +these data structures is the number of seconds since the :term:`Unix epoch` but +will never be prior to the :term:`RTEMS epoch`. + +.. index:: struct bintime +.. index:: sbintime_t + +The ``struct bintime`` and ``sbintime_t`` time formats used by some directives +originate in FreeBSD. The ``struct bintime`` data structure which represents +time in a binary time format has two members: ``sec`` and ``frac`` which are +seconds and fractions of a second in units of :math:`1 / 2^{64}` seconds, +respectively. The ``sbintime_t`` type is a signed 64-bit integer type used to +represent time in units of :math:`1 / 2^{32}` seconds. + +.. index:: timeslicing + +Clock Tick and Timeslicing +-------------------------- + +Timeslicing is a task scheduling discipline in which tasks of equal priority +are executed for a specific period of time before control of the CPU is passed +to another task. It is also sometimes referred to as the automatic round-robin +scheduling algorithm. The length of time allocated to each task is known as +the quantum or timeslice. + +The system's timeslice is defined as an integral number of ticks, and is +specified by the :ref:`CONFIGURE_TICKS_PER_TIMESLICE` application configuration +option. The timeslice is defined for the entire system of tasks, but +timeslicing is enabled and disabled on a per task basis. + +The clock tick directives implement timeslicing by decrementing the +running task's time-remaining counter when both timeslicing and preemption are +enabled. If the task's timeslice has expired, then that task will be preempted +if there exists a ready task of equal priority. + +.. index:: delays + +Delays +------ + +A sleep timer allows a task to delay for a given interval or up until a given +time, and then wake and continue execution. This type of timer is created +automatically by the :ref:`InterfaceRtemsTaskWakeAfter` and +:ref:`InterfaceRtemsTaskWakeWhen` directives and, as a result, does not have an +object identifier. Once activated, a sleep timer cannot be explicitly deleted. +Each task may activate one and only one sleep timer at a time. + +.. index:: timeouts + +Timeouts +-------- + +Timeouts are a special type of timer automatically created when the timeout +option is used on the :ref:`InterfaceRtemsBarrierWait`, +:ref:`InterfaceRtemsEventReceive`, :ref:`InterfaceRtemsMessageQueueReceive`, +:ref:`InterfaceRtemsRegionGetSegment`, and :ref:`InterfaceRtemsSemaphoreObtain` +directives. Each task may have one and only one timeout active at a time. +When a timeout expires, it unblocks the task with a timeout status code. diff --git a/c-user/clock/directives.rst b/c-user/clock/directives.rst new file mode 100644 index 0000000..a6e00ca --- /dev/null +++ b/c-user/clock/directives.rst @@ -0,0 +1,1513 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2014, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. _ClockManagerDirectives: + +Directives +========== + +This section details the directives of the Clock Manager. A subsection is +dedicated to each of this manager's directives and lists the calling sequence, +parameters, description, return values, and notes of the directive. + +.. Generated from spec:/rtems/clock/if/set + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_set() + +.. _InterfaceRtemsClockSet: + +rtems_clock_set() +----------------- + +Sets the :term:`CLOCK_REALTIME` to the time of day. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_clock_set( const rtems_time_of_day *time_of_day ); + +.. rubric:: PARAMETERS: + +``time_of_day`` + This parameter is the time of day to set the clock. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``time_of_day`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_CLOCK` + The time of day specified by ``time_of_day`` was invalid. + +.. rubric:: NOTES: + +The date, time, and ticks specified by ``time_of_day`` are all range-checked, +and an error is returned if any one is out of its valid range. + +RTEMS can represent time points of the :term:`CLOCK_REALTIME` clock in +nanoseconds ranging from 1988-01-01T00:00:00.000000000Z to +2514-05-31T01:53:03.999999999Z. The future uptime of the system shall be in +this range, otherwise the system behaviour is undefined. Due to implementation +constraints, the time of day set by the directive shall be before +2100-01-01:00:00.000000000Z. The latest valid time of day accepted by the +POSIX `clock_settime() +<https://pubs.opengroup.org/onlinepubs/9699919799/functions/clock_settime.html>`_ +is 2400-01-01T00:00:00.999999999Z. + +The specified time is based on the configured :term:`clock tick` rate, see the +:ref:`CONFIGURE_MICROSECONDS_PER_TICK` application configuration option. + +Setting the time forward will fire all :term:`CLOCK_REALTIME` timers which are +scheduled at a time point before or at the time set by the directive. This may +unblock tasks, which may preempt the calling task. User-provided timer routines +will execute in the context of the caller. + +It is allowed to call this directive from within interrupt context, however, +this is not recommended since an arbitrary number of timers may fire. + +The directive shall be called at least once to enable the service of +:term:`CLOCK_REALTIME` related directives. If the clock is not set at least +once, they may return an error status. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive may change the priority of a task. This may cause the calling + task to be preempted. + +* The directive may unblock a task. This may cause the calling task to be + preempted. + +* The time of day set by the directive shall be 1988-01-01T00:00:00.000000000Z + or later. + +* The time of day set by the directive shall be before + 2100-01-01T00:00:00.000000000Z. + +.. Generated from spec:/rtems/clock/if/get-tod + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_tod() + +.. _InterfaceRtemsClockGetTod: + +rtems_clock_get_tod() +--------------------- + +Gets the time of day associated with the current :term:`CLOCK_REALTIME`. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_clock_get_tod( rtems_time_of_day *time_of_day ); + +.. rubric:: PARAMETERS: + +``time_of_day`` + This parameter is the pointer to an :ref:`InterfaceRtemsTimeOfDay` object. + When the directive call is successful, the time of day associated with the + :term:`CLOCK_REALTIME` at some point during the directive call will be + stored in this object. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``time_of_day`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_NOT_DEFINED` + The :term:`CLOCK_REALTIME` was not set. It can be set with + :ref:`InterfaceRtemsClockSet`. + +.. 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. + +* The directive requires a :term:`Clock Driver`. + +.. Generated from spec:/rtems/clock/if/get-tod-timeval + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_tod_timeval() + +.. _InterfaceRtemsClockGetTodTimeval: + +rtems_clock_get_tod_timeval() +----------------------------- + +Gets the seconds and microseconds elapsed since the :term:`Unix epoch` and the +current :term:`CLOCK_REALTIME`. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_clock_get_tod_timeval( struct timeval *time_of_day ); + +.. rubric:: PARAMETERS: + +``time_of_day`` + This parameter is the pointer to a `struct timeval + <https://pubs.opengroup.org/onlinepubs/009695399/basedefs/sys/time.h.html>`_ + object. When the directive call is successful, the seconds and + microseconds elapsed since the :term:`Unix epoch` and the + :term:`CLOCK_REALTIME` at some point during the directive call will be + stored in this object. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``time_of_day`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_NOT_DEFINED` + The :term:`CLOCK_REALTIME` was not set. It can be set with + :ref:`InterfaceRtemsClockSet`. + +.. 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. + +* The directive requires a :term:`Clock Driver`. + +.. Generated from spec:/rtems/clock/if/get-realtime + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_realtime() + +.. _InterfaceRtemsClockGetRealtime: + +rtems_clock_get_realtime() +-------------------------- + +Gets the time elapsed since the :term:`Unix epoch` measured using +:term:`CLOCK_REALTIME` in seconds and nanoseconds format. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_clock_get_realtime( struct timespec *time_snapshot ); + +.. rubric:: PARAMETERS: + +``time_snapshot`` + This parameter is the pointer to a `struct timespec + <https://en.cppreference.com/w/c/chrono/timespec>`_ object. The time + elapsed since the :term:`Unix epoch` measured using the + :term:`CLOCK_REALTIME` at some time point during the directive call will be + stored in this object. Calling the directive with a pointer equal to `NULL + <https://en.cppreference.com/w/c/types/NULL>`_ is undefined behaviour. + +.. rubric:: NOTES: + +The directive accesses a device provided by the :term:`Clock Driver` to get the +time in the highest resolution available to the system. Alternatively, the +:ref:`InterfaceRtemsClockGetRealtimeCoarse` directive may be used to get the +time in a lower resolution and with less runtime overhead. + +See :ref:`InterfaceRtemsClockGetRealtimeBintime` and +:ref:`InterfaceRtemsClockGetRealtimeTimeval` to get the time in alternative +formats. + +.. 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. + +* The directive requires a :term:`Clock Driver`. + +.. Generated from spec:/rtems/clock/if/get-realtime-bintime + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_realtime_bintime() + +.. _InterfaceRtemsClockGetRealtimeBintime: + +rtems_clock_get_realtime_bintime() +---------------------------------- + +Gets the time elapsed since the :term:`Unix epoch` measured using +:term:`CLOCK_REALTIME` in binary time format. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_clock_get_realtime_bintime( struct bintime *time_snapshot ); + +.. rubric:: PARAMETERS: + +``time_snapshot`` + This parameter is the pointer to a ``struct bintime`` object. The time + elapsed since the :term:`Unix epoch` measured using the + :term:`CLOCK_REALTIME` at some time point during the directive call will be + stored in this object. Calling the directive with a pointer equal to `NULL + <https://en.cppreference.com/w/c/types/NULL>`_ is undefined behaviour. + +.. rubric:: NOTES: + +The directive accesses a device provided by the :term:`Clock Driver` to get the +time in the highest resolution available to the system. Alternatively, the +:ref:`InterfaceRtemsClockGetRealtimeCoarseBintime` directive may be used to get +the time in a lower resolution and with less runtime overhead. + +See :ref:`InterfaceRtemsClockGetRealtime` and +:ref:`InterfaceRtemsClockGetRealtimeTimeval` to get the time in alternative +formats. + +.. 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. + +* The directive requires a :term:`Clock Driver`. + +.. Generated from spec:/rtems/clock/if/get-realtime-timeval + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_realtime_timeval() + +.. _InterfaceRtemsClockGetRealtimeTimeval: + +rtems_clock_get_realtime_timeval() +---------------------------------- + +Gets the time elapsed since the :term:`Unix epoch` measured using +:term:`CLOCK_REALTIME` in seconds and microseconds format. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_clock_get_realtime_timeval( struct timeval *time_snapshot ); + +.. rubric:: PARAMETERS: + +``time_snapshot`` + This parameter is the pointer to a `struct timeval + <https://pubs.opengroup.org/onlinepubs/009695399/basedefs/sys/time.h.html>`_ + object. The time elapsed since the :term:`Unix epoch` measured using the + :term:`CLOCK_REALTIME` at some time point during the directive call will be + stored in this object. Calling the directive with a pointer equal to `NULL + <https://en.cppreference.com/w/c/types/NULL>`_ is undefined behaviour. + +.. rubric:: NOTES: + +The directive accesses a device provided by the :term:`Clock Driver` to get the +time in the highest resolution available to the system. Alternatively, the +:ref:`InterfaceRtemsClockGetRealtimeCoarseTimeval` directive may be used to get +the time in a lower resolution and with less runtime overhead. + +See :ref:`InterfaceRtemsClockGetRealtime` and +:ref:`InterfaceRtemsClockGetRealtimeBintime` to get the time in alternative +formats. + +.. 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. + +* The directive requires a :term:`Clock Driver`. + +.. Generated from spec:/rtems/clock/if/get-realtime-coarse + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_realtime_coarse() + +.. _InterfaceRtemsClockGetRealtimeCoarse: + +rtems_clock_get_realtime_coarse() +--------------------------------- + +Gets the time elapsed since the :term:`Unix epoch` measured using +:term:`CLOCK_REALTIME` in coarse resolution in seconds and nanoseconds format. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_clock_get_realtime_coarse( struct timespec *time_snapshot ); + +.. rubric:: PARAMETERS: + +``time_snapshot`` + This parameter is the pointer to a `struct timespec + <https://en.cppreference.com/w/c/chrono/timespec>`_ object. The time + elapsed since the :term:`Unix epoch` measured using the + :term:`CLOCK_REALTIME` at some time point close to the directive call will + be stored in this object. Calling the directive with a pointer equal to + `NULL <https://en.cppreference.com/w/c/types/NULL>`_ is undefined + behaviour. + +.. rubric:: NOTES: + +The directive does not access a device to get the time. It uses a recent +snapshot provided by the :term:`Clock Driver`. Alternatively, the +:ref:`InterfaceRtemsClockGetRealtime` directive may be used to get the time in +a higher resolution and with a higher runtime overhead. + +See :ref:`InterfaceRtemsClockGetRealtimeCoarseBintime` and +:ref:`InterfaceRtemsClockGetRealtimeCoarseTimeval` to get the time in +alternative formats. + +.. 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. + +* The directive requires a :term:`Clock Driver`. + +.. Generated from spec:/rtems/clock/if/get-realtime-coarse-bintime + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_realtime_coarse_bintime() + +.. _InterfaceRtemsClockGetRealtimeCoarseBintime: + +rtems_clock_get_realtime_coarse_bintime() +----------------------------------------- + +Gets the time elapsed since the :term:`Unix epoch` measured using +:term:`CLOCK_REALTIME` in coarse resolution in binary time format. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_clock_get_realtime_coarse_bintime( struct bintime *time_snapshot ); + +.. rubric:: PARAMETERS: + +``time_snapshot`` + This parameter is the pointer to a ``struct bintime`` object. The time + elapsed since the :term:`Unix epoch` measured using the + :term:`CLOCK_REALTIME` at some time point close to the directive call will + be stored in this object. Calling the directive with a pointer equal to + `NULL <https://en.cppreference.com/w/c/types/NULL>`_ is undefined + behaviour. + +.. rubric:: NOTES: + +The directive does not access a device to get the time. It uses a recent +snapshot provided by the :term:`Clock Driver`. Alternatively, the +:ref:`InterfaceRtemsClockGetRealtimeBintime` directive may be used to get the +time in a higher resolution and with a higher runtime overhead. + +See :ref:`InterfaceRtemsClockGetRealtimeCoarse` and +:ref:`InterfaceRtemsClockGetRealtimeCoarseTimeval` to get the time in +alternative formats. + +.. 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. + +* The directive requires a :term:`Clock Driver`. + +.. Generated from spec:/rtems/clock/if/get-realtime-coarse-timeval + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_realtime_coarse_timeval() + +.. _InterfaceRtemsClockGetRealtimeCoarseTimeval: + +rtems_clock_get_realtime_coarse_timeval() +----------------------------------------- + +Gets the time elapsed since the :term:`Unix epoch` measured using +:term:`CLOCK_REALTIME` in coarse resolution in seconds and microseconds format. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_clock_get_realtime_coarse_timeval( struct timeval *time_snapshot ); + +.. rubric:: PARAMETERS: + +``time_snapshot`` + This parameter is the pointer to a `struct timeval + <https://pubs.opengroup.org/onlinepubs/009695399/basedefs/sys/time.h.html>`_ + object. The time elapsed since the :term:`Unix epoch` measured using the + :term:`CLOCK_REALTIME` at some time point close to the directive call will + be stored in this object. Calling the directive with a pointer equal to + `NULL <https://en.cppreference.com/w/c/types/NULL>`_ is undefined + behaviour. + +.. rubric:: NOTES: + +The directive does not access a device to get the time. It uses a recent +snapshot provided by the :term:`Clock Driver`. Alternatively, the +:ref:`InterfaceRtemsClockGetRealtimeTimeval` directive may be used to get the +time in a higher resolution and with a higher runtime overhead. + +See :ref:`InterfaceRtemsClockGetRealtimeCoarse` and +:ref:`InterfaceRtemsClockGetRealtimeCoarseTimeval` to get the time in +alternative formats. + +.. 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. + +* The directive requires a :term:`Clock Driver`. + +.. Generated from spec:/rtems/clock/if/get-monotonic + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_monotonic() + +.. _InterfaceRtemsClockGetMonotonic: + +rtems_clock_get_monotonic() +--------------------------- + +Gets the time elapsed since some fixed time point in the past measured using +the :term:`CLOCK_MONOTONIC` in seconds and nanoseconds format. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_clock_get_monotonic( struct timespec *time_snapshot ); + +.. rubric:: PARAMETERS: + +``time_snapshot`` + This parameter is the pointer to a `struct timespec + <https://en.cppreference.com/w/c/chrono/timespec>`_ object. The time + elapsed since some fixed time point in the past measured using the + :term:`CLOCK_MONOTONIC` at some time point during the directive call will + be stored in this object. Calling the directive with a pointer equal to + `NULL <https://en.cppreference.com/w/c/types/NULL>`_ is undefined + behaviour. + +.. rubric:: NOTES: + +The directive accesses a device provided by the :term:`Clock Driver` to get the +time in the highest resolution available to the system. Alternatively, the +:ref:`InterfaceRtemsClockGetMonotonicCoarse` directive may be used to get the +time with in a lower resolution and with less runtime overhead. + +See :ref:`InterfaceRtemsClockGetMonotonicBintime`, +:ref:`InterfaceRtemsClockGetMonotonicSbintime`, and +:ref:`InterfaceRtemsClockGetMonotonicTimeval` to get the time in alternative +formats. + +.. 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. + +* The directive requires a :term:`Clock Driver`. + +.. Generated from spec:/rtems/clock/if/get-monotonic-bintime + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_monotonic_bintime() + +.. _InterfaceRtemsClockGetMonotonicBintime: + +rtems_clock_get_monotonic_bintime() +----------------------------------- + +Gets the time elapsed since some fixed time point in the past measured using +the :term:`CLOCK_MONOTONIC` in binary time format. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_clock_get_monotonic_bintime( struct bintime *time_snapshot ); + +.. rubric:: PARAMETERS: + +``time_snapshot`` + This parameter is the pointer to a ``struct bintime`` object. The time + elapsed since some fixed time point in the past measured using the + :term:`CLOCK_MONOTONIC` at some time point during the directive call will + be stored in this object. Calling the directive with a pointer equal to + `NULL <https://en.cppreference.com/w/c/types/NULL>`_ is undefined + behaviour. + +.. rubric:: NOTES: + +The directive accesses a device provided by the :term:`Clock Driver` to get the +time in the highest resolution available to the system. Alternatively, the +:ref:`InterfaceRtemsClockGetMonotonicCoarseBintime` directive may be used to +get the time in a lower resolution and with less runtime overhead. + +See :ref:`InterfaceRtemsClockGetMonotonic`, +:ref:`InterfaceRtemsClockGetMonotonicSbintime`, and +:ref:`InterfaceRtemsClockGetMonotonicTimeval` to get the time in alternative +formats. + +.. 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. + +* The directive requires a :term:`Clock Driver`. + +.. Generated from spec:/rtems/clock/if/get-monotonic-sbintime + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_monotonic_sbintime() + +.. _InterfaceRtemsClockGetMonotonicSbintime: + +rtems_clock_get_monotonic_sbintime() +------------------------------------ + +Gets the time elapsed since some fixed time point in the past measured using +the :term:`CLOCK_MONOTONIC` in signed binary time format. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + int64_t rtems_clock_get_monotonic_sbintime( void ); + +.. rubric:: RETURN VALUES: + +Returns the time elapsed since some fixed time point in the past measured using +the :term:`CLOCK_MONOTONIC` at some time point during the directive call. + +.. rubric:: NOTES: + +The directive accesses a device provided by the :term:`Clock Driver` to get the +time in the highest resolution available to the system. + +See :ref:`InterfaceRtemsClockGetMonotonic`, +:ref:`InterfaceRtemsClockGetMonotonicBintime`, and +:ref:`InterfaceRtemsClockGetMonotonicTimeval` to get the time in alternative +formats. + +.. 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. + +* The directive requires a :term:`Clock Driver`. + +.. Generated from spec:/rtems/clock/if/get-monotonic-timeval + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_monotonic_timeval() + +.. _InterfaceRtemsClockGetMonotonicTimeval: + +rtems_clock_get_monotonic_timeval() +----------------------------------- + +Gets the time elapsed since some fixed time point in the past measured using +the :term:`CLOCK_MONOTONIC` in seconds and microseconds format. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_clock_get_monotonic_timeval( struct timeval *time_snapshot ); + +.. rubric:: PARAMETERS: + +``time_snapshot`` + This parameter is the pointer to a `struct timeval + <https://pubs.opengroup.org/onlinepubs/009695399/basedefs/sys/time.h.html>`_ + object. The time elapsed since some fixed time point in the past measured + using the :term:`CLOCK_MONOTONIC` at some time point during the directive + call will be stored in this object. Calling the directive with a pointer + equal to `NULL <https://en.cppreference.com/w/c/types/NULL>`_ is undefined + behaviour. + +.. rubric:: NOTES: + +The directive accesses a device provided by the :term:`Clock Driver` to get the +time in the highest resolution available to the system. Alternatively, the +:ref:`InterfaceRtemsClockGetMonotonicCoarseTimeval` directive may be used to +get the time in a lower resolution and with less runtime overhead. + +See :ref:`InterfaceRtemsClockGetMonotonic`, +:ref:`InterfaceRtemsClockGetMonotonicBintime`, and +:ref:`InterfaceRtemsClockGetMonotonicSbintime` to get the time in alternative +formats. + +.. 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. + +* The directive requires a :term:`Clock Driver`. + +.. Generated from spec:/rtems/clock/if/get-monotonic-coarse + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_monotonic_coarse() + +.. _InterfaceRtemsClockGetMonotonicCoarse: + +rtems_clock_get_monotonic_coarse() +---------------------------------- + +Gets the time elapsed since some fixed time point in the past measured using +the :term:`CLOCK_MONOTONIC` in coarse resolution in seconds and nanoseconds +format. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_clock_get_monotonic_coarse( struct timespec *time_snapshot ); + +.. rubric:: PARAMETERS: + +``time_snapshot`` + This parameter is the pointer to a `struct timespec + <https://en.cppreference.com/w/c/chrono/timespec>`_ object. The time + elapsed since some fixed time point in the past measured using the + :term:`CLOCK_MONOTONIC` at some time point close to the directive call will + be stored in this object. Calling the directive with a pointer equal to + `NULL <https://en.cppreference.com/w/c/types/NULL>`_ is undefined + behaviour. + +.. rubric:: NOTES: + +The directive does not access a device to get the time. It uses a recent +snapshot provided by the :term:`Clock Driver`. Alternatively, the +:ref:`InterfaceRtemsClockGetMonotonic` directive may be used to get the time in +a higher resolution and with a higher runtime overhead. + +See :ref:`InterfaceRtemsClockGetMonotonicCoarseBintime` and +:ref:`InterfaceRtemsClockGetMonotonicCoarseTimeval` to get the time in +alternative formats. + +.. 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. + +* The directive requires a :term:`Clock Driver`. + +.. Generated from spec:/rtems/clock/if/get-monotonic-coarse-bintime + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_monotonic_coarse_bintime() + +.. _InterfaceRtemsClockGetMonotonicCoarseBintime: + +rtems_clock_get_monotonic_coarse_bintime() +------------------------------------------ + +Gets the time elapsed since some fixed time point in the past measured using +the :term:`CLOCK_MONOTONIC` in coarse resolution in binary time format. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_clock_get_monotonic_coarse_bintime( struct bintime *time_snapshot ); + +.. rubric:: PARAMETERS: + +``time_snapshot`` + This parameter is the pointer to a ``struct bintime`` object. The time + elapsed since some fixed time point in the past measured using the + :term:`CLOCK_MONOTONIC` at some time point close to the directive call will + be stored in this object. Calling the directive with a pointer equal to + `NULL <https://en.cppreference.com/w/c/types/NULL>`_ is undefined + behaviour. + +.. rubric:: NOTES: + +The directive does not access a device to get the time. It uses a recent +snapshot provided by the :term:`Clock Driver`. Alternatively, the +:ref:`InterfaceRtemsClockGetMonotonicBintime` directive may be used to get the +time in a higher resolution and with a higher runtime overhead. + +See :ref:`InterfaceRtemsClockGetMonotonicCoarse` and +:ref:`InterfaceRtemsClockGetMonotonicCoarseTimeval` to get the time in +alternative formats. + +.. 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. + +* The directive requires a :term:`Clock Driver`. + +.. Generated from spec:/rtems/clock/if/get-monotonic-coarse-timeval + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_monotonic_coarse_timeval() + +.. _InterfaceRtemsClockGetMonotonicCoarseTimeval: + +rtems_clock_get_monotonic_coarse_timeval() +------------------------------------------ + +Gets the time elapsed since some fixed time point in the past measured using +the :term:`CLOCK_MONOTONIC` in coarse resolution in seconds and microseconds +format. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_clock_get_monotonic_coarse_timeval( struct timeval *time_snapshot ); + +.. rubric:: PARAMETERS: + +``time_snapshot`` + This parameter is the pointer to a `struct timeval + <https://pubs.opengroup.org/onlinepubs/009695399/basedefs/sys/time.h.html>`_ + object. The time elapsed since some fixed time point in the past measured + using the :term:`CLOCK_MONOTONIC` at some time point close to the directive + call will be stored in this object. Calling the directive with a pointer + equal to `NULL <https://en.cppreference.com/w/c/types/NULL>`_ is undefined + behaviour. + +.. rubric:: NOTES: + +The directive does not access a device to get the time. It uses a recent +snapshot provided by the :term:`Clock Driver`. Alternatively, the +:ref:`InterfaceRtemsClockGetMonotonicTimeval` directive may be used to get the +time in a higher resolution and with a higher runtime overhead. + +See :ref:`InterfaceRtemsClockGetMonotonicCoarse` and +:ref:`InterfaceRtemsClockGetMonotonicCoarseBintime` to get the time in +alternative formats. + +.. 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. + +* The directive requires a :term:`Clock Driver`. + +.. Generated from spec:/rtems/clock/if/get-boot-time + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_boot_time() + +.. _InterfaceRtemsClockGetBootTime: + +rtems_clock_get_boot_time() +--------------------------- + +Gets the time elapsed since the :term:`Unix epoch` at some time point during +system initialization in seconds and nanoseconds format. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_clock_get_boot_time( struct timespec *boot_time ); + +.. rubric:: PARAMETERS: + +``boot_time`` + This parameter is the pointer to a `struct timespec + <https://en.cppreference.com/w/c/chrono/timespec>`_ object. The time + elapsed since the :term:`Unix epoch` at some time point during system + initialization call will be stored in this object. Calling the directive + with a pointer equal to `NULL + <https://en.cppreference.com/w/c/types/NULL>`_ is undefined behaviour. + +.. rubric:: NOTES: + +See :ref:`InterfaceRtemsClockGetBootTimeBintime` and +:ref:`InterfaceRtemsClockGetBootTimeTimeval` to get the boot time in +alternative formats. Setting the :term:`CLOCK_REALTIME` will also set the boot +time. + +.. 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. + +* The directive requires a :term:`Clock Driver`. + +.. Generated from spec:/rtems/clock/if/get-boot-time-bintime + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_boot_time_bintime() + +.. _InterfaceRtemsClockGetBootTimeBintime: + +rtems_clock_get_boot_time_bintime() +----------------------------------- + +Gets the time elapsed since the :term:`Unix epoch` at some time point during +system initialization in binary time format. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_clock_get_boot_time_bintime( struct bintime *boot_time ); + +.. rubric:: PARAMETERS: + +``boot_time`` + This parameter is the pointer to a ``struct bintime`` object. The time + elapsed since the :term:`Unix epoch` at some time point during system + initialization call will be stored in this object. Calling the directive + with a pointer equal to `NULL + <https://en.cppreference.com/w/c/types/NULL>`_ is undefined behaviour. + +.. rubric:: NOTES: + +See :ref:`InterfaceRtemsClockGetBootTime` and +:ref:`InterfaceRtemsClockGetBootTimeTimeval` to get the boot time in +alternative formats. Setting the :term:`CLOCK_REALTIME` will also set the boot +time. + +.. 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. + +* The directive requires a :term:`Clock Driver`. + +.. Generated from spec:/rtems/clock/if/get-boot-time-timeval + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_boot_time_timeval() + +.. _InterfaceRtemsClockGetBootTimeTimeval: + +rtems_clock_get_boot_time_timeval() +----------------------------------- + +Gets the time elapsed since the :term:`Unix epoch` at some time point during +system initialization in seconds and microseconds format. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_clock_get_boot_time_timeval( struct timeval *boot_time ); + +.. rubric:: PARAMETERS: + +``boot_time`` + This parameter is the pointer to a `struct timeval + <https://pubs.opengroup.org/onlinepubs/009695399/basedefs/sys/time.h.html>`_ + object. The time elapsed since the :term:`Unix epoch` at some time point + during system initialization call will be stored in this object. Calling + the directive with a pointer equal to `NULL + <https://en.cppreference.com/w/c/types/NULL>`_ is undefined behaviour. + +.. rubric:: NOTES: + +See :ref:`InterfaceRtemsClockGetBootTime` and +:ref:`InterfaceRtemsClockGetBootTimeBintime` to get the boot time in +alternative formats. Setting the :term:`CLOCK_REALTIME` will also set the boot +time. + +.. 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. + +* The directive requires a :term:`Clock Driver`. + +.. Generated from spec:/rtems/clock/if/get-seconds-since-epoch + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_seconds_since_epoch() + +.. _InterfaceRtemsClockGetSecondsSinceEpoch: + +rtems_clock_get_seconds_since_epoch() +------------------------------------- + +Gets the seconds elapsed since the :term:`RTEMS epoch` and the current +:term:`CLOCK_REALTIME`. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_clock_get_seconds_since_epoch( + rtems_interval *seconds_since_rtems_epoch + ); + +.. rubric:: PARAMETERS: + +``seconds_since_rtems_epoch`` + This parameter is the pointer to an :ref:`InterfaceRtemsInterval` object. + When the directive call is successful, the seconds elapsed since the + :term:`RTEMS epoch` and the :term:`CLOCK_REALTIME` at some point during the + directive call will be stored in this object. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``seconds_since_rtems_epoch`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_NOT_DEFINED` + The :term:`CLOCK_REALTIME` was not set. It can be set with + :ref:`InterfaceRtemsClockSet`. + +.. 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. + +* The directive requires a :term:`Clock Driver`. + +.. Generated from spec:/rtems/clock/if/get-ticks-per-second + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_ticks_per_second() + +.. _InterfaceRtemsClockGetTicksPerSecond: + +rtems_clock_get_ticks_per_second() +---------------------------------- + +Gets the number of :term:`clock ticks <clock tick>` per second configured for +the application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_interval rtems_clock_get_ticks_per_second( void ); + +.. rubric:: RETURN VALUES: + +Returns the number of clock ticks per second configured for this application. + +.. rubric:: NOTES: + +The number of clock ticks per second is defined indirectly by the +:ref:`CONFIGURE_MICROSECONDS_PER_TICK` configuration option. + +.. 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/clock/if/get-ticks-since-boot + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_ticks_since_boot() + +.. _InterfaceRtemsClockGetTicksSinceBoot: + +rtems_clock_get_ticks_since_boot() +---------------------------------- + +Gets the number of :term:`clock ticks <clock tick>` since some time point +during the system initialization or the last overflow of the clock tick +counter. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_interval rtems_clock_get_ticks_since_boot( void ); + +.. rubric:: RETURN VALUES: + +Returns the number of :term:`clock ticks <clock tick>` since some time point +during the system initialization or the last overflow of the clock tick +counter. + +.. rubric:: NOTES: + +With a 1ms clock tick, this counter overflows after 50 days since boot. This +is the historical measure of uptime in an RTEMS system. The newer service +:ref:`InterfaceRtemsClockGetUptime` is another and potentially more accurate +way of obtaining similar information. + +.. 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/clock/if/get-uptime + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_uptime() + +.. _InterfaceRtemsClockGetUptime: + +rtems_clock_get_uptime() +------------------------ + +Gets the seconds and nanoseconds elapsed since some time point during the +system initialization using :term:`CLOCK_MONOTONIC`. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_clock_get_uptime( struct timespec *uptime ); + +.. rubric:: PARAMETERS: + +``uptime`` + This parameter is the pointer to a `struct timespec + <https://en.cppreference.com/w/c/chrono/timespec>`_ object. When the + directive call is successful, the seconds and nanoseconds elapsed since + some time point during the system initialization and some point during the + directive call using :term:`CLOCK_MONOTONIC` will be stored in this object. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``uptime`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +.. 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. + +* The directive requires a :term:`Clock Driver`. + +.. Generated from spec:/rtems/clock/if/get-uptime-timeval + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_uptime_timeval() + +.. _InterfaceRtemsClockGetUptimeTimeval: + +rtems_clock_get_uptime_timeval() +-------------------------------- + +Gets the seconds and microseconds elapsed since some time point during the +system initialization using :term:`CLOCK_MONOTONIC`. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_clock_get_uptime_timeval( struct timeval *uptime ); + +.. rubric:: PARAMETERS: + +``uptime`` + This parameter is the pointer to a `struct timeval + <https://pubs.opengroup.org/onlinepubs/009695399/basedefs/sys/time.h.html>`_ + object. The seconds and microseconds elapsed since some time point during + the system initialization and some point during the directive call using + :term:`CLOCK_MONOTONIC` will be stored in this object. The pointer shall + be valid, otherwise the behaviour is undefined. + +.. 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. + +* The directive requires a :term:`Clock Driver`. + +.. Generated from spec:/rtems/clock/if/get-uptime-seconds + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_uptime_seconds() + +.. _InterfaceRtemsClockGetUptimeSeconds: + +rtems_clock_get_uptime_seconds() +-------------------------------- + +Gets the seconds elapsed since some time point during the system initialization +using :term:`CLOCK_MONOTONIC`. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + time_t rtems_clock_get_uptime_seconds( void ); + +.. rubric:: RETURN VALUES: + +Returns the seconds elapsed since some time point during the system +initialization and some point during the directive call using +:term:`CLOCK_MONOTONIC`. + +.. 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. + +* The directive requires a :term:`Clock Driver`. + +.. Generated from spec:/rtems/clock/if/get-uptime-nanoseconds + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_uptime_nanoseconds() + +.. _InterfaceRtemsClockGetUptimeNanoseconds: + +rtems_clock_get_uptime_nanoseconds() +------------------------------------ + +Gets the nanoseconds elapsed since some time point during the system +initialization using :term:`CLOCK_MONOTONIC`. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint64_t rtems_clock_get_uptime_nanoseconds( void ); + +.. rubric:: RETURN VALUES: + +Returns the nanoseconds elapsed since some time point during the system +initialization and some point during the directive call using +:term:`CLOCK_MONOTONIC`. + +.. 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. + +* The directive requires a :term:`Clock Driver`. + +.. Generated from spec:/rtems/clock/if/tick-later + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_tick_later() + +.. _InterfaceRtemsClockTickLater: + +rtems_clock_tick_later() +------------------------ + +Gets a :term:`clock tick` value which is at least delta clock ticks in the +future. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_interval rtems_clock_tick_later( rtems_interval delta ); + +.. rubric:: PARAMETERS: + +``delta`` + This parameter is the delta value in clock ticks. + +.. rubric:: RETURN VALUES: + +Returns a :term:`clock tick` counter value which is at least ``delta`` clock +ticks in the future. + +.. 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. + +* The directive requires a :term:`Clock Driver`. + +.. Generated from spec:/rtems/clock/if/tick-later-usec + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_tick_later_usec() + +.. _InterfaceRtemsClockTickLaterUsec: + +rtems_clock_tick_later_usec() +----------------------------- + +Gets a :term:`clock tick` value which is at least delta microseconds in the +future. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_interval rtems_clock_tick_later_usec( rtems_interval delta_in_usec ); + +.. rubric:: PARAMETERS: + +``delta_in_usec`` + This parameter is the delta value in microseconds. + +.. rubric:: RETURN VALUES: + +Returns a :term:`clock tick` counter value which is at least ``delta_in_usec`` +microseconds in the future. + +.. 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. + +* The directive requires a :term:`Clock Driver`. + +.. Generated from spec:/rtems/clock/if/tick-before + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_tick_before() + +.. _InterfaceRtemsClockTickBefore: + +rtems_clock_tick_before() +------------------------- + +Indicates if the current :term:`clock tick` counter is before the ticks. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + bool rtems_clock_tick_before( rtems_interval ticks ); + +.. rubric:: PARAMETERS: + +``ticks`` + This parameter is the ticks value to check. + +.. rubric:: RETURN VALUES: + +Returns true, if current :term:`clock tick` counter indicates a time before the +time in ticks, otherwise returns false. + +.. rubric:: NOTES: + +This directive can be used to write busy loops with a timeout. + +.. code-block:: c + :linenos: + + status busy( void ) + { + rtems_interval timeout; + + timeout = rtems_clock_tick_later_usec( 10000 ); + + do { + if ( ok() ) { + return success; + } + } while ( rtems_clock_tick_before( timeout ) ); + + return timeout; + } + +.. 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. + +* The directive requires a :term:`Clock Driver`. diff --git a/c-user/clock/index.rst b/c-user/clock/index.rst new file mode 100644 index 0000000..cf41998 --- /dev/null +++ b/c-user/clock/index.rst @@ -0,0 +1,18 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 embedded brains GmbH & Co. KG + +.. index:: clock + +.. _RTEMSAPIClassicClock: + +Clock Manager +************* + +.. toctree:: + + introduction + background + operations + directives + removed-directives diff --git a/c-user/clock/introduction.rst b/c-user/clock/introduction.rst new file mode 100644 index 0000000..6ba814b --- /dev/null +++ b/c-user/clock/introduction.rst @@ -0,0 +1,169 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2014, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/rtems/clock/if/group + +.. _ClockManagerIntroduction: + +Introduction +============ + +.. The following list was generated from: +.. spec:/rtems/clock/if/set +.. spec:/rtems/clock/if/get-tod +.. spec:/rtems/clock/if/get-tod-timeval +.. spec:/rtems/clock/if/get-realtime +.. spec:/rtems/clock/if/get-realtime-bintime +.. spec:/rtems/clock/if/get-realtime-timeval +.. spec:/rtems/clock/if/get-realtime-coarse +.. spec:/rtems/clock/if/get-realtime-coarse-bintime +.. spec:/rtems/clock/if/get-realtime-coarse-timeval +.. spec:/rtems/clock/if/get-monotonic +.. spec:/rtems/clock/if/get-monotonic-bintime +.. spec:/rtems/clock/if/get-monotonic-sbintime +.. spec:/rtems/clock/if/get-monotonic-timeval +.. spec:/rtems/clock/if/get-monotonic-coarse +.. spec:/rtems/clock/if/get-monotonic-coarse-bintime +.. spec:/rtems/clock/if/get-monotonic-coarse-timeval +.. spec:/rtems/clock/if/get-boot-time +.. spec:/rtems/clock/if/get-boot-time-bintime +.. spec:/rtems/clock/if/get-boot-time-timeval +.. spec:/rtems/clock/if/get-seconds-since-epoch +.. spec:/rtems/clock/if/get-ticks-per-second +.. spec:/rtems/clock/if/get-ticks-since-boot +.. spec:/rtems/clock/if/get-uptime +.. spec:/rtems/clock/if/get-uptime-timeval +.. spec:/rtems/clock/if/get-uptime-seconds +.. spec:/rtems/clock/if/get-uptime-nanoseconds +.. spec:/rtems/clock/if/tick-later +.. spec:/rtems/clock/if/tick-later-usec +.. spec:/rtems/clock/if/tick-before + +The Clock Manager provides support for time of day and other time related +capabilities. The directives provided by the Clock Manager are: + +* :ref:`InterfaceRtemsClockSet` - Sets the :term:`CLOCK_REALTIME` to the time + of day. + +* :ref:`InterfaceRtemsClockGetTod` - Gets the time of day associated with the + current :term:`CLOCK_REALTIME`. + +* :ref:`InterfaceRtemsClockGetTodTimeval` - Gets the seconds and microseconds + elapsed since the :term:`Unix epoch` and the current :term:`CLOCK_REALTIME`. + +* :ref:`InterfaceRtemsClockGetRealtime` - Gets the time elapsed since the + :term:`Unix epoch` measured using :term:`CLOCK_REALTIME` in seconds and + nanoseconds format. + +* :ref:`InterfaceRtemsClockGetRealtimeBintime` - Gets the time elapsed since + the :term:`Unix epoch` measured using :term:`CLOCK_REALTIME` in binary time + format. + +* :ref:`InterfaceRtemsClockGetRealtimeTimeval` - Gets the time elapsed since + the :term:`Unix epoch` measured using :term:`CLOCK_REALTIME` in seconds and + microseconds format. + +* :ref:`InterfaceRtemsClockGetRealtimeCoarse` - Gets the time elapsed since the + :term:`Unix epoch` measured using :term:`CLOCK_REALTIME` in coarse resolution + in seconds and nanoseconds format. + +* :ref:`InterfaceRtemsClockGetRealtimeCoarseBintime` - Gets the time elapsed + since the :term:`Unix epoch` measured using :term:`CLOCK_REALTIME` in coarse + resolution in binary time format. + +* :ref:`InterfaceRtemsClockGetRealtimeCoarseTimeval` - Gets the time elapsed + since the :term:`Unix epoch` measured using :term:`CLOCK_REALTIME` in coarse + resolution in seconds and microseconds format. + +* :ref:`InterfaceRtemsClockGetMonotonic` - Gets the time elapsed since some + fixed time point in the past measured using the :term:`CLOCK_MONOTONIC` in + seconds and nanoseconds format. + +* :ref:`InterfaceRtemsClockGetMonotonicBintime` - Gets the time elapsed since + some fixed time point in the past measured using the :term:`CLOCK_MONOTONIC` + in binary time format. + +* :ref:`InterfaceRtemsClockGetMonotonicSbintime` - Gets the time elapsed since + some fixed time point in the past measured using the :term:`CLOCK_MONOTONIC` + in signed binary time format. + +* :ref:`InterfaceRtemsClockGetMonotonicTimeval` - Gets the time elapsed since + some fixed time point in the past measured using the :term:`CLOCK_MONOTONIC` + in seconds and microseconds format. + +* :ref:`InterfaceRtemsClockGetMonotonicCoarse` - Gets the time elapsed since + some fixed time point in the past measured using the :term:`CLOCK_MONOTONIC` + in coarse resolution in seconds and nanoseconds format. + +* :ref:`InterfaceRtemsClockGetMonotonicCoarseBintime` - Gets the time elapsed + since some fixed time point in the past measured using the + :term:`CLOCK_MONOTONIC` in coarse resolution in binary time format. + +* :ref:`InterfaceRtemsClockGetMonotonicCoarseTimeval` - Gets the time elapsed + since some fixed time point in the past measured using the + :term:`CLOCK_MONOTONIC` in coarse resolution in seconds and microseconds + format. + +* :ref:`InterfaceRtemsClockGetBootTime` - Gets the time elapsed since the + :term:`Unix epoch` at some time point during system initialization in seconds + and nanoseconds format. + +* :ref:`InterfaceRtemsClockGetBootTimeBintime` - Gets the time elapsed since + the :term:`Unix epoch` at some time point during system initialization in + binary time format. + +* :ref:`InterfaceRtemsClockGetBootTimeTimeval` - Gets the time elapsed since + the :term:`Unix epoch` at some time point during system initialization in + seconds and microseconds format. + +* :ref:`InterfaceRtemsClockGetSecondsSinceEpoch` - Gets the seconds elapsed + since the :term:`RTEMS epoch` and the current :term:`CLOCK_REALTIME`. + +* :ref:`InterfaceRtemsClockGetTicksPerSecond` - Gets the number of :term:`clock + ticks <clock tick>` per second configured for the application. + +* :ref:`InterfaceRtemsClockGetTicksSinceBoot` - Gets the number of :term:`clock + ticks <clock tick>` since some time point during the system initialization or + the last overflow of the clock tick counter. + +* :ref:`InterfaceRtemsClockGetUptime` - Gets the seconds and nanoseconds + elapsed since some time point during the system initialization using + :term:`CLOCK_MONOTONIC`. + +* :ref:`InterfaceRtemsClockGetUptimeTimeval` - Gets the seconds and + microseconds elapsed since some time point during the system initialization + using :term:`CLOCK_MONOTONIC`. + +* :ref:`InterfaceRtemsClockGetUptimeSeconds` - Gets the seconds elapsed since + some time point during the system initialization using + :term:`CLOCK_MONOTONIC`. + +* :ref:`InterfaceRtemsClockGetUptimeNanoseconds` - Gets the nanoseconds elapsed + since some time point during the system initialization using + :term:`CLOCK_MONOTONIC`. + +* :ref:`InterfaceRtemsClockTickLater` - Gets a :term:`clock tick` value which + is at least delta clock ticks in the future. + +* :ref:`InterfaceRtemsClockTickLaterUsec` - Gets a :term:`clock tick` value + which is at least delta microseconds in the future. + +* :ref:`InterfaceRtemsClockTickBefore` - Indicates if the current :term:`clock + tick` counter is before the ticks. diff --git a/c-user/clock/operations.rst b/c-user/clock/operations.rst new file mode 100644 index 0000000..c4dd0a6 --- /dev/null +++ b/c-user/clock/operations.rst @@ -0,0 +1,78 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Operations +========== + +Announcing a Tick +----------------- + +RTEMS provides the several clock tick directives which are called from the +user's real-time clock ISR to inform RTEMS that a tick has elapsed. Depending +on the timer hardware capabilities the clock driver must choose the most +appropriate clock tick directive. The tick frequency value, defined in +microseconds, is a configuration parameter found in the Configuration Table. +RTEMS divides one million microseconds (one second) by the number of +microseconds per tick to determine the number of calls to the clock tick +directive per second. The frequency of clock tick calls determines the +resolution (granularity) for all time dependent RTEMS actions. For example, +calling the clock tick directive ten times per second yields a higher +resolution than calling the clock tick two times per second. The clock tick +directives are responsible for maintaining both calendar time and the dynamic +set of timers. + +Setting the Time +---------------- + +The ``rtems_clock_set`` directive allows a task or an ISR to set the date and +time maintained by RTEMS. If setting the date and time causes any outstanding +timers to pass their deadline, then the expired timers will be fired during the +invocation of the ``rtems_clock_set`` directive. + +Obtaining the Time +------------------ + +RTEMS provides multiple directives which can be used by an application to obtain the current date and time or date and time related information. These directives allow a task or an ISR to obtain the current date and time or date and time related information. The current date and time can be returned in either native or *UNIX-style* format. Additionally, the application can obtain date and time related information such as the number of seconds since the RTEMS epoch, the number of ticks since the executive was initialized, and the number of ticks per second. The following directives are available: + +``rtems_clock_get_tod`` + obtain native style date and time + +``rtems_clock_get_time_value`` + obtain *UNIX-style* date and time + +``rtems_clock_get_ticks_since_boot`` + obtain number of ticks since RTEMS was initialized + +``rtems_clock_get_seconds_since_epoch`` + obtain number of seconds since RTEMS epoch + +``rtems_clock_get_ticks_per_second`` + obtain number of clock ticks per second + +Calendar time operations will return an error code if invoked before the date +and time have been set. + +.. _ClockManagerAdviceClockGet: + +Transition Advice for the Removed rtems_clock_get() +--------------------------------------------------- + +The directive :ref:`rtems_clock_get` took an untyped pointer with an options +argument to indicate the time information desired. This has been replaced with +a set of typed directives: + +* :ref:`rtems_clock_get_seconds_since_epoch` + +* :ref:`rtems_clock_get_ticks_per_second` + +* :ref:`rtems_clock_get_ticks_since_boot` + +* :ref:`rtems_clock_get_tod` + +* :ref:`rtems_clock_get_tod_timeval` + +These directives directly correspond to what were previously referred to as +*clock options*. These strongly typed directives were available for multiple +releases in parallel with :c:func:`rtems_clock_get` until that directive was +removed. diff --git a/c-user/clock/removed-directives.rst b/c-user/clock/removed-directives.rst new file mode 100644 index 0000000..66be74e --- /dev/null +++ b/c-user/clock/removed-directives.rst @@ -0,0 +1,81 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Removed Directives +================== + +.. raw:: latex + + \clearpage + +.. _rtems_clock_get: + +CLOCK_GET - Get date and time information +----------------------------------------- +.. index:: obtain the time of day +.. index:: rtems_clock_get() + +.. warning:: + + This directive was removed in RTEMS 5.1. See also + :ref:`ClockManagerAdviceClockGet`. + +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_clock_get( + rtems_clock_get_options option, + void *time_buffer + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - current time obtained successfully + * - ``RTEMS_NOT_DEFINED`` + - system date and time is not set + * - ``RTEMS_INVALID_ADDRESS`` + - ``time_buffer`` is NULL + +DESCRIPTION: + This directive obtains the system date and time. If the caller is + attempting to obtain the date and time (i.e. option is set to either + ``RTEMS_CLOCK_GET_SECONDS_SINCE_EPOCH``, ``RTEMS_CLOCK_GET_TOD``, or + ``RTEMS_CLOCK_GET_TIME_VALUE``) and the date and time has not been set with + a previous call to ``rtems_clock_set``, then the ``RTEMS_NOT_DEFINED`` + status code is returned. The caller can always obtain the number of ticks + per second (option is ``RTEMS_CLOCK_GET_TICKS_PER_SECOND``) and the number + of ticks since the executive was initialized option is + ``RTEMS_CLOCK_GET_TICKS_SINCE_BOOT``). + + The ``option`` argument may taken on any value of the enumerated type + ``rtems_clock_get_options``. The data type expected for ``time_buffer`` is + based on the value of ``option`` as indicated below: + + .. index:: rtems_clock_get_options + + +-----------------------------------------+---------------------------+ + | Option | Return type | + +=========================================+===========================+ + | ``RTEMS_CLOCK_GET_TOD`` | ``(rtems_time_of_day *)`` | + +-----------------------------------------+---------------------------+ + | ``RTEMS_CLOCK_GET_SECONDS_SINCE_EPOCH`` | ``(rtems_interval *)`` | + +-----------------------------------------+---------------------------+ + | ``RTEMS_CLOCK_GET_TICKS_SINCE_BOOT`` | ``(rtems_interval *)`` | + +-----------------------------------------+---------------------------+ + |``RTEMS_CLOCK_GET_TICKS_PER_SECOND`` | ``(rtems_interval *)`` | + +-----------------------------------------+---------------------------+ + | ``RTEMS_CLOCK_GET_TIME_VALUE`` | ``(struct timeval *)`` | + +-----------------------------------------+---------------------------+ + +NOTES: + This directive is callable from an ISR. + + This directive will not cause the running task to be preempted. + Re-initializing RTEMS causes the system date and time to be reset to an + uninitialized state. Another call to ``rtems_clock_set`` is required to + re-initialize the system date and time to application specific + specifications. diff --git a/c-user/clock_manager.rst b/c-user/clock_manager.rst deleted file mode 100644 index c825d7b..0000000 --- a/c-user/clock_manager.rst +++ /dev/null @@ -1,755 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-4.0 - -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) - -.. index:: clock - -Clock Manager -************* - -Introduction -============ - -The clock manager provides support for time of day -and other time related capabilities. The directives provided by -the clock manager are: - -- rtems_clock_set_ - Set date and time - -- rtems_clock_get_tod_ - Get date and time in TOD format - -- rtems_clock_get_tod_timeval_ - Get date and time in timeval format - -- rtems_clock_get_seconds_since_epoch_ - Get seconds since epoch - -- rtems_clock_get_ticks_per_second_ - Get ticks per second - -- rtems_clock_get_ticks_since_boot_ - Get current ticks counter value - -- rtems_clock_tick_later_ - Get tick value in the future - -- rtems_clock_tick_later_usec_ - Get tick value in the future in microseconds - -- rtems_clock_tick_before_ - Is tick value is before a point in time - -- rtems_clock_get_uptime_ - Get time since boot - -- rtems_clock_get_uptime_timeval_ - Get time since boot in timeval format - -- rtems_clock_get_uptime_seconds_ - Get seconds since boot - -- rtems_clock_get_uptime_nanoseconds_ - Get nanoseconds since boot - -Background -========== - -Required Support ----------------- - -For the features provided by the clock manager to be utilized, periodic timer -interrupts are required. Therefore, a real-time clock or hardware timer is -necessary to create the timer interrupts. The clock tick directive -is normally called by the timer ISR to announce to RTEMS that a system clock -tick has occurred. Elapsed time is measured in ticks. A tick is defined to be -an integral number of microseconds which is specified by the user in the -Configuration Table. - -.. _Time and Date Data Structures: - -Time and Date Data Structures ------------------------------ - -The clock facilities of the clock manager operate upon calendar time. These -directives utilize the following date and time structure for the native time -and date format: - -.. index:: rtems_time_of_day - -.. code-block:: c - - struct rtems_tod_control { - uint32_t year; /* greater than 1987 */ - uint32_t month; /* 1 - 12 */ - uint32_t day; /* 1 - 31 */ - uint32_t hour; /* 0 - 23 */ - uint32_t minute; /* 0 - 59 */ - uint32_t second; /* 0 - 59 */ - uint32_t ticks; /* elapsed between seconds */ - }; - typedef struct rtems_tod_control rtems_time_of_day; - -The native date and time format is the only format supported when setting the -system date and time using the ``rtems_clock_set`` directive. Some -applications expect to operate on a *UNIX-style* date and time data structure. -The ``rtems_clock_get_tod_timeval`` always returns the date and time in -``struct timeval`` format. - -The ``struct timeval`` data structure has two fields: ``tv_sec`` and -``tv_usec`` which are seconds and microseconds, respectively. The ``tv_sec`` -field in this data structure is the number of seconds since the POSIX epoch of -*January 1, 1970* but will never be prior to the RTEMS epoch of *January 1, -1988*. - -.. index:: timeslicing - -Clock Tick and Timeslicing --------------------------- - -Timeslicing is a task scheduling discipline in which tasks of equal priority -are executed for a specific period of time before control of the CPU is passed -to another task. It is also sometimes referred to as the automatic round-robin -scheduling algorithm. The length of time allocated to each task is known as -the quantum or timeslice. - -The system's timeslice is defined as an integral number of ticks, and is -specified in the Configuration Table. The timeslice is defined for the entire -system of tasks, but timeslicing is enabled and disabled on a per task basis. - -The clock tick directives implement timeslicing by decrementing the -running task's time-remaining counter when both timeslicing and preemption are -enabled. If the task's timeslice has expired, then that task will be preempted -if there exists a ready task of equal priority. - -.. index:: delays - -Delays ------- - -A sleep timer allows a task to delay for a given interval or up until a given -time, and then wake and continue execution. This type of timer is created -automatically by the ``rtems_task_wake_after`` and ``rtems_task_wake_when`` -directives and, as a result, does not have an RTEMS ID. Once activated, a -sleep timer cannot be explicitly deleted. Each task may activate one and only -one sleep timer at a time. - -.. index:: timeouts - -Timeouts --------- - -Timeouts are a special type of timer automatically created when the timeout -option is used on the ``rtems_message_queue_receive``, ``rtems_event_receive``, -``rtems_semaphore_obtain`` and ``rtems_region_get_segment`` directives. Each -task may have one and only one timeout active at a time. When a timeout -expires, it unblocks the task with a timeout status code. - -Operations -========== - -Announcing a Tick ------------------ - -RTEMS provides the several clock tick directives which are called from the -user's real-time clock ISR to inform RTEMS that a tick has elapsed. Depending -on the timer hardware capabilities the clock driver must choose the most -appropriate clock tick directive. The tick frequency value, defined in -microseconds, is a configuration parameter found in the Configuration Table. -RTEMS divides one million microseconds (one second) by the number of -microseconds per tick to determine the number of calls to the clock tick -directive per second. The frequency of clock tick calls determines the -resolution (granularity) for all time dependent RTEMS actions. For example, -calling the clock tick directive ten times per second yields a higher -resolution than calling the clock tick two times per second. The clock tick -directives are responsible for maintaining both calendar time and the dynamic -set of timers. - -Setting the Time ----------------- - -The ``rtems_clock_set`` directive allows a task or an ISR to set the date and -time maintained by RTEMS. If setting the date and time causes any outstanding -timers to pass their deadline, then the expired timers will be fired during the -invocation of the ``rtems_clock_set`` directive. - -Obtaining the Time ------------------- - -RTEMS provides multiple directives which can be used by an application to obtain the current date and time or date and time related information. These directives allow a task or an ISR to obtain the current date and time or date and time related information. The current date and time can be returned in either native or *UNIX-style* format. Additionally, the application can obtain date and time related information such as the number of seconds since the RTEMS epoch, the number of ticks since the executive was initialized, and the number of ticks per second. The following directives are available: - -``rtems_clock_get_tod`` - obtain native style date and time - -``rtems_clock_get_time_value`` - obtain *UNIX-style* date and time - -``rtems_clock_get_ticks_since_boot`` - obtain number of ticks since RTEMS was initialized - -``rtems_clock_get_seconds_since_epoch`` - obtain number of seconds since RTEMS epoch - -``rtems_clock_get_ticks_per_second`` - obtain number of clock ticks per second - -Calendar time operations will return an error code if invoked before the date -and time have been set. - -.. _ClockManagerAdviceClockGet: - -Transition Advice for the Removed rtems_clock_get() ---------------------------------------------------- - -The directive :ref:`rtems_clock_get` took an untyped pointer with an options -argument to indicate the time information desired. This has been replaced with -a set of typed directives: - -* :ref:`rtems_clock_get_seconds_since_epoch` - -* :ref:`rtems_clock_get_ticks_per_second` - -* :ref:`rtems_clock_get_ticks_since_boot` - -* :ref:`rtems_clock_get_tod` - -* :ref:`rtems_clock_get_tod_timeval` - -These directives directly correspond to what were previously referred to as -*clock options*. These strongly typed directives were available for multiple -releases in parallel with :c:func:`rtems_clock_get` until that directive was -removed. - -Directives -========== - -This section details the clock manager's directives. A subsection is dedicated -to each of this manager's directives and describes the calling sequence, -related constants, usage, and status codes. - -.. raw:: latex - - \clearpage - -.. _rtems_clock_set: - -.. index:: set the time of day -.. index:: rtems_clock_set - -CLOCK_SET - Set date and time ------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_clock_set( - rtems_time_of_day *time_buffer - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - date and time set successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``time_buffer`` is NULL - * - ``RTEMS_INVALID_CLOCK`` - - invalid time of day - -DESCRIPTION: - This directive sets the system date and time. The date, time, and ticks in - the time_buffer structure are all range-checked, and an error is returned - if any one is out of its valid range. - -NOTES: - Years before 1988 are invalid. - - The system date and time are based on the configured tick rate (number of - microseconds in a tick). - - Setting the time forward may cause a higher priority task, blocked waiting - on a specific time, to be made ready. In this case, the calling task will - be preempted after the next clock tick. - - Re-initializing RTEMS causes the system date and time to be reset to an - uninitialized state. Another call to ``rtems_clock_set`` is required to - re-initialize the system date and time to application specific - specifications. - -.. raw:: latex - - \clearpage - -.. index:: obtain the time of day -.. index:: rtems_clock_get_tod - -.. _rtems_clock_get_tod: - -CLOCK_GET_TOD - Get date and time in TOD format ------------------------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_clock_get_tod( - rtems_time_of_day *time_buffer - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - current time obtained successfully - * - ``RTEMS_NOT_DEFINED`` - - system date and time is not set - * - ``RTEMS_INVALID_ADDRESS`` - - ``time_buffer`` is NULL - -DESCRIPTION: - This directive obtains the system date and time. If the date and time has - not been set with a previous call to ``rtems_clock_set``, then the - ``RTEMS_NOT_DEFINED`` status code is returned. - -NOTES: - This directive is callable from an ISR. - - This directive will not cause the running task to be preempted. - Re-initializing RTEMS causes the system date and time to be reset to an - uninitialized state. Another call to ``rtems_clock_set`` is required to - re-initialize the system date and time to application specific - specifications. - -.. raw:: latex - - \clearpage - -.. index:: obtain the time of day -.. index:: rtems_clock_get_tod_timeval - -.. _rtems_clock_get_tod_timeval: - -CLOCK_GET_TOD_TIMEVAL - Get date and time in timeval format ------------------------------------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_clock_get_tod_interval( - struct timeval *time - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - * - ``RTEMS_SUCCESSFUL`` - - current time obtained successfully - * - ``RTEMS_NOT_DEFINED`` - - system date and time is not set - * - ``RTEMS_INVALID_ADDRESS`` - - ``time`` is NULL - -DESCRIPTION: - This directive obtains the system date and time in POSIX ``struct timeval`` - format. If the date and time has not been set with a previous call to - ``rtems_clock_set``, then the ``RTEMS_NOT_DEFINED`` status code is - returned. - -NOTES: - This directive is callable from an ISR. - - This directive will not cause the running task to be preempted. - Re-initializing RTEMS causes the system date and time to be reset to an - uninitialized state. Another call to ``rtems_clock_set`` is required to - re-initialize the system date and time to application specific - specifications. - -.. raw:: latex - - \clearpage - -.. index:: obtain seconds since epoch -.. index:: rtems_clock_get_seconds_since_epoch - -.. _rtems_clock_get_seconds_since_epoch: - -CLOCK_GET_SECONDS_SINCE_EPOCH - Get seconds since epoch -------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_clock_get_seconds_since_epoch( - rtems_interval *the_interval - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - * - ``RTEMS_SUCCESSFUL`` - - current time obtained successfully - * - ``RTEMS_NOT_DEFINED`` - - system date and time is not set - * - ``RTEMS_INVALID_ADDRESS`` - - ``the_interval`` is NULL - -DESCRIPTION: - This directive returns the number of seconds since the RTEMS epoch and the - current system date and time. If the date and time has not been set with a - previous call to ``rtems_clock_set``, then the ``RTEMS_NOT_DEFINED`` status - code is returned. - -NOTES: - This directive is callable from an ISR. - - This directive will not cause the running task to be preempted. - Re-initializing RTEMS causes the system date and time to be reset to an - uninitialized state. Another call to ``rtems_clock_set`` is required to - re-initialize the system date and time to application specific - specifications. - -.. raw:: latex - - \clearpage - -.. index:: obtain seconds since epoch -.. index:: rtems_clock_get_ticks_per_second - -.. _rtems_clock_get_ticks_per_second: - -CLOCK_GET_TICKS_PER_SECOND - Get ticks per second -------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_interval rtems_clock_get_ticks_per_second(void); - -DIRECTIVE STATUS CODES: - NONE - -DESCRIPTION: - This directive returns the number of clock ticks per second. This is - strictly based upon the microseconds per clock tick that the application - has configured. - -NOTES: - This directive is callable from an ISR. - - This directive will not cause the running task to be preempted. - -.. raw:: latex - - \clearpage - -.. index:: obtain ticks since boot -.. index:: get current ticks counter value -.. index:: rtems_clock_get_ticks_since_boot - -.. _rtems_clock_get_ticks_since_boot: - -CLOCK_GET_TICKS_SINCE_BOOT - Get current ticks counter value ------------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_interval rtems_clock_get_ticks_since_boot(void); - -DIRECTIVE STATUS CODES: - NONE - -DESCRIPTION: - - This directive returns the current tick counter value. With a 1ms clock - tick, this counter overflows after 50 days since boot. This is the - historical measure of uptime in an RTEMS system. The newer service - ``rtems_clock_get_uptime`` is another and potentially more accurate way of - obtaining similar information. - -NOTES: - - This directive is callable from an ISR. - - This directive will not cause the running task to be preempted. - -.. raw:: latex - - \clearpage - -.. _rtems_clock_tick_later: - -.. index:: rtems_clock_tick_later - -CLOCK_TICK_LATER - Get tick value in the future ------------------------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - rtems_interval rtems_clock_tick_later( - rtems_interval delta - ); - -DESCRIPTION: - Returns the ticks counter value delta ticks in the future. - -NOTES: - This directive is callable from an ISR. - - This directive will not cause the running task to be preempted. - -.. raw:: latex - - \clearpage - -.. _rtems_clock_tick_later_usec: - -.. index:: rtems_clock_tick_later_usec - -CLOCK_TICK_LATER_USEC - Get tick value in the future in microseconds --------------------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_interval rtems_clock_tick_later_usec( - rtems_interval delta_in_usec - ); - -DESCRIPTION: - Returns the ticks counter value at least delta microseconds in the future. - -NOTES: - This directive is callable from an ISR. - - This directive will not cause the running task to be preempted. - -.. raw:: latex - - \clearpage - -.. _rtems_clock_tick_before: - -.. index:: rtems_clock_tick_before - -CLOCK_TICK_BEFORE - Is tick value is before a point in time ------------------------------------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - rtems_interval rtems_clock_tick_before( - rtems_interval tick - ); - -DESCRIPTION: - Returns true if the current ticks counter value indicates a time before the - time specified by the tick value and false otherwise. - -NOTES: - This directive is callable from an ISR. - - This directive will not cause the running task to be preempted. - -EXAMPLE: - .. code-block:: c - - status busy( void ) - { - rtems_interval timeout = rtems_clock_tick_later_usec( 10000 ); - do { - if ( ok() ) { - return success; - } - } while ( rtems_clock_tick_before( timeout ) ); - return timeout; - } - -.. raw:: latex - - \clearpage - -.. _rtems_clock_get_uptime: - -.. index:: clock get uptime -.. index:: uptime -.. index:: rtems_clock_get_uptime - -CLOCK_GET_UPTIME - Get the time since boot ------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_clock_get_uptime( - struct timespec *uptime - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - * - ``RTEMS_SUCCESSFUL`` - - clock tick processed successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``time_buffer`` is ``NULL`` - -DESCRIPTION: - This directive returns the seconds and nanoseconds since the system was - booted. If the BSP supports nanosecond clock accuracy, the time reported - will probably be different on every call. - -NOTES: - This directive may be called from an ISR. - -.. raw:: latex - - \clearpage - -.. _rtems_clock_get_uptime_timeval: - -.. index:: clock get uptime interval -.. index:: uptime -.. index:: rtems_clock_get_uptime_timeval - -CLOCK_GET_UPTIME_TIMEVAL - Get the time since boot in timeval format --------------------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - void rtems_clock_get_uptime_timeval( - struct timeval *uptime - ); - -DIRECTIVE STATUS CODES: - NONE - -DESCRIPTION: - This directive returns the seconds and microseconds since the system was - booted. If the BSP supports nanosecond clock accuracy, the time reported - will probably be different on every call. - -NOTES: - This directive may be called from an ISR. - -.. raw:: latex - - \clearpage - -.. _rtems_clock_get_uptime_seconds: - -.. index:: clock get uptime seconds -.. index:: uptime -.. index:: rtems_clock_get_uptime_seconds - -CLOCK_GET_UPTIME_SECONDS - Get the seconds since boot ------------------------------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - time_t rtems_clock_get_uptime_seconds(void); - -DIRECTIVE STATUS CODES: - The system uptime in seconds. - -DESCRIPTION: - This directive returns the seconds since the system was booted. - -NOTES: - This directive may be called from an ISR. - -.. raw:: latex - - \clearpage - -.. _rtems_clock_get_uptime_nanoseconds: - -.. index:: clock get nanoseconds uptime -.. index:: uptime -.. index:: rtems_clock_get_uptime_nanoseconds - -CLOCK_GET_UPTIME_NANOSECONDS - Get the nanoseconds since boot -------------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - uint64_t rtems_clock_get_uptime_nanoseconds(void); - -DIRECTIVE STATUS CODES: - The system uptime in nanoseconds. - -DESCRIPTION: - This directive returns the nanoseconds since the system was booted. - -NOTES: - This directive may be called from an ISR. - -Removed Directives -================== - -.. raw:: latex - - \clearpage - -.. _rtems_clock_get: - -CLOCK_GET - Get date and time information ------------------------------------------ -.. index:: obtain the time of day -.. index:: rtems_clock_get - -.. warning:: - - This directive was removed in RTEMS 5.1. See also - :ref:`ClockManagerAdviceClockGet`. - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_clock_get( - rtems_clock_get_options option, - void *time_buffer - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - current time obtained successfully - * - ``RTEMS_NOT_DEFINED`` - - system date and time is not set - * - ``RTEMS_INVALID_ADDRESS`` - - ``time_buffer`` is NULL - -DESCRIPTION: - This directive obtains the system date and time. If the caller is - attempting to obtain the date and time (i.e. option is set to either - ``RTEMS_CLOCK_GET_SECONDS_SINCE_EPOCH``, ``RTEMS_CLOCK_GET_TOD``, or - ``RTEMS_CLOCK_GET_TIME_VALUE``) and the date and time has not been set with - a previous call to ``rtems_clock_set``, then the ``RTEMS_NOT_DEFINED`` - status code is returned. The caller can always obtain the number of ticks - per second (option is ``RTEMS_CLOCK_GET_TICKS_PER_SECOND``) and the number - of ticks since the executive was initialized option is - ``RTEMS_CLOCK_GET_TICKS_SINCE_BOOT``). - - The ``option`` argument may taken on any value of the enumerated type - ``rtems_clock_get_options``. The data type expected for ``time_buffer`` is - based on the value of ``option`` as indicated below: - - .. index:: rtems_clock_get_options - - +-----------------------------------------+---------------------------+ - | Option | Return type | - +=========================================+===========================+ - | ``RTEMS_CLOCK_GET_TOD`` | ``(rtems_time_of_day *)`` | - +-----------------------------------------+---------------------------+ - | ``RTEMS_CLOCK_GET_SECONDS_SINCE_EPOCH`` | ``(rtems_interval *)`` | - +-----------------------------------------+---------------------------+ - | ``RTEMS_CLOCK_GET_TICKS_SINCE_BOOT`` | ``(rtems_interval *)`` | - +-----------------------------------------+---------------------------+ - |``RTEMS_CLOCK_GET_TICKS_PER_SECOND`` | ``(rtems_interval *)`` | - +-----------------------------------------+---------------------------+ - | ``RTEMS_CLOCK_GET_TIME_VALUE`` | ``(struct timeval *)`` | - +-----------------------------------------+---------------------------+ - -NOTES: - This directive is callable from an ISR. - - This directive will not cause the running task to be preempted. - Re-initializing RTEMS causes the system date and time to be reset to an - uninitialized state. Another call to ``rtems_clock_set`` is required to - re-initialize the system date and time to application specific - specifications. diff --git a/c-user/config/bdbuf.rst b/c-user/config/bdbuf.rst index 604f887..2d27d54 100644 --- a/c-user/config/bdbuf.rst +++ b/c-user/config/bdbuf.rst @@ -1,14 +1,37 @@ .. 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 & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/acfg/if/group-bdbuf + Block Device Cache Configuration ================================ This section describes configuration options related to the Block Device Cache (bdbuf). +.. Generated from spec:/acfg/if/appl-needs-libblock + +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_APPLICATION_NEEDS_LIBBLOCK .. _CONFIGURE_APPLICATION_NEEDS_LIBBLOCK: @@ -16,24 +39,35 @@ This section describes configuration options related to the Block Device Cache CONFIGURE_APPLICATION_NEEDS_LIBBLOCK ------------------------------------ -CONSTANT: - ``CONFIGURE_APPLICATION_NEEDS_LIBBLOCK`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_LIBBLOCK`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: -OPTION TYPE: - This configuration option is a boolean feature define. +If this configuration option is undefined, then the described feature is not +enabled. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DESCRIPTION: -DESCRIPTION: - In case this configuration option is defined, then the Block Device Cache is - initialized during system initialization. +In case this configuration option is defined, then the Block Device Cache is +initialized during system initialization. -NOTES: - Each option of the Block Device Cache (bdbuf) configuration can be explicitly - set by the user with the configuration options below. The Block Device Cache - is used for example by the RFS and DOSFS filesystems. +.. rubric:: NOTES: + +Each option of the Block Device Cache (bdbuf) configuration can be explicitly +set by the user with the configuration options below. The Block Device Cache +is used for example by the RFS and DOSFS filesystems. + +.. Generated from spec:/acfg/if/bdbuf-buffer-max-size + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_BDBUF_BUFFER_MAX_SIZE @@ -42,29 +76,37 @@ NOTES: CONFIGURE_BDBUF_BUFFER_MAX_SIZE ------------------------------- -CONSTANT: - ``CONFIGURE_BDBUF_BUFFER_MAX_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_BDBUF_BUFFER_MAX_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: -OPTION TYPE: - This configuration option is an integer define. +The default value is 4096. -DEFAULT VALUE: - The default value is 4096. +.. rubric:: DESCRIPTION: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The value of this configuration option defines the maximum size of a buffer +in bytes. - * It shall be greater than or equal to 0. +.. rubric:: CONSTRAINTS: - * It shall be an integral multiple of :ref:`CONFIGURE_BDBUF_BUFFER_MIN_SIZE`. +The following constraints apply to this configuration option: -DESCRIPTION: - The value of this configuration option defines the maximum size of a buffer - in bytes. +* The value of the configuration option shall be greater than or equal to zero. -NOTES: - None. +* The value of the configuration option shall be an integral multiple of + :ref:`CONFIGURE_BDBUF_BUFFER_MIN_SIZE`. + +.. Generated from spec:/acfg/if/bdbuf-buffer-min-size + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_BDBUF_BUFFER_MIN_SIZE @@ -73,25 +115,37 @@ NOTES: CONFIGURE_BDBUF_BUFFER_MIN_SIZE ------------------------------- -CONSTANT: - ``CONFIGURE_BDBUF_BUFFER_MIN_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_BDBUF_BUFFER_MIN_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 512. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DESCRIPTION: -DEFAULT VALUE: - The default value is 512. +The value of this configuration option defines the minimum size of a buffer +in bytes. -VALUE CONSTRAINTS: - The value of this configuration option shall be greater than or equal to 0 - and less than or equal to ``UINT32_MAX``. +.. rubric:: CONSTRAINTS: -DESCRIPTION: - The value of this configuration option defines the minimum size of a buffer - in bytes. +The following constraints apply to this configuration option: -NOTES: - None. +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. + +.. Generated from spec:/acfg/if/bdbuf-cache-memory-size + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_BDBUF_CACHE_MEMORY_SIZE @@ -100,25 +154,37 @@ NOTES: CONFIGURE_BDBUF_CACHE_MEMORY_SIZE --------------------------------- -CONSTANT: - ``CONFIGURE_BDBUF_CACHE_MEMORY_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_BDBUF_CACHE_MEMORY_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DEFAULT VALUE: -DEFAULT VALUE: - The default value is 32768. +The default value is 32768. -VALUE CONSTRAINTS: - The value of this configuration option shall be greater than or equal to 0 - and less than or equal to ``SIZE_MAX``. +.. rubric:: DESCRIPTION: -DESCRIPTION: - The value of this configuration option defines the size of the cache memory - in bytes. +The value of this configuration option defines the size of the cache memory +in bytes. -NOTES: - None. +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_. + +.. Generated from spec:/acfg/if/bdbuf-max-read-ahead-blocks + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_BDBUF_MAX_READ_AHEAD_BLOCKS @@ -127,27 +193,43 @@ NOTES: CONFIGURE_BDBUF_MAX_READ_AHEAD_BLOCKS ------------------------------------- -CONSTANT: - ``CONFIGURE_BDBUF_MAX_READ_AHEAD_BLOCKS`` +.. rubric:: CONSTANT: + +``CONFIGURE_BDBUF_MAX_READ_AHEAD_BLOCKS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the maximum blocks per +read-ahead request. + +.. rubric:: NOTES: + +A value of 0 disables the read-ahead task (default). The read-ahead task +will issue speculative read transfers if a sequential access pattern is +detected. This can improve the performance on some systems. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: CONSTRAINTS: -DEFAULT VALUE: - The default value is 0. +The following constraints apply to this configuration option: -VALUE CONSTRAINTS: - The value of this configuration option shall be greater than or equal to 0 - and less than or equal to ``UINT32_MAX``. +* The value of the configuration option shall be greater than or equal to zero. -DESCRIPTION: - The value of this configuration option defines the maximum blocks per - read-ahead request. +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. -NOTES: - A value of 0 disables the read-ahead task (default). The read-ahead task - will issue speculative read transfers if a sequential access pattern is - detected. This can improve the performance on some systems. +.. Generated from spec:/acfg/if/bdbuf-max-write-blocks + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_BDBUF_MAX_WRITE_BLOCKS @@ -156,25 +238,37 @@ NOTES: CONFIGURE_BDBUF_MAX_WRITE_BLOCKS -------------------------------- -CONSTANT: - ``CONFIGURE_BDBUF_MAX_WRITE_BLOCKS`` +.. rubric:: CONSTANT: + +``CONFIGURE_BDBUF_MAX_WRITE_BLOCKS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 16. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is an integer define. +The value of this configuration option defines the maximum blocks per write +request. -DEFAULT VALUE: - The default value is 16. +.. rubric:: CONSTRAINTS: -VALUE CONSTRAINTS: - The value of this configuration option shall be greater than or equal to 0 - and less than or equal to ``UINT32_MAX``. +The following constraints apply to this configuration option: -DESCRIPTION: - The value of this configuration option defines the maximum blocks per write - request. +* The value of the configuration option shall be greater than or equal to zero. -NOTES: - None. +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. + +.. Generated from spec:/acfg/if/bdbuf-read-ahead-task-priority + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY @@ -183,24 +277,33 @@ NOTES: CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY ---------------------------------------- -CONSTANT: - ``CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY`` +.. rubric:: CONSTANT: + +``CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: -OPTION TYPE: - This configuration option is an integer define. +The default value is 15. -DEFAULT VALUE: - The default value is 15. +.. rubric:: DESCRIPTION: -VALUE CONSTRAINTS: - The value of this configuration option shall be a valid Classic API task - priority. The set of valid task priorities is scheduler-specific. +The value of this configuration option defines the read-ahead task priority. -DESCRIPTION: - The value of this configuration option defines the read-ahead task priority. +.. rubric:: CONSTRAINTS: -NOTES: - None. +The value of the configuration option shall be a valid Classic API task +priority. The set of valid task priorities depends on the scheduler +configuration. + +.. Generated from spec:/acfg/if/bdbuf-task-stack-size + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_BDBUF_TASK_STACK_SIZE @@ -209,35 +312,44 @@ NOTES: CONFIGURE_BDBUF_TASK_STACK_SIZE ------------------------------- -CONSTANT: - ``CONFIGURE_BDBUF_TASK_STACK_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_BDBUF_TASK_STACK_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is :c:macro:`RTEMS_MINIMUM_STACK_SIZE`. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DESCRIPTION: -DEFAULT VALUE: - The default value is ``RTEMS_MINIMUM_STACK_SIZE``. +The value of this configuration option defines the task stack size of the +Block Device Cache tasks in bytes. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: CONSTRAINTS: - * It shall be greater than or equal to :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. +The following constraints apply to this configuration option: - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +* The value of the configuration option shall be greater than or equal to + :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. - * It shall be small enough so that the task - stack space calculation carried out by ``<rtems/confdefs.h>`` does not - overflow an integer of type ``uintptr_t``. +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. -DESCRIPTION: - The value of this configuration option defines the task stack size of the - Block Device Cache tasks in bytes. +* The value of the configuration option shall be small enough so that the task + stack space calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. -NOTES: - None. +.. Generated from spec:/acfg/if/bdbuf-swapout-block-hold + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_SWAPOUT_BLOCK_HOLD @@ -246,25 +358,37 @@ NOTES: CONFIGURE_SWAPOUT_BLOCK_HOLD ---------------------------- -CONSTANT: - ``CONFIGURE_SWAPOUT_BLOCK_HOLD`` +.. rubric:: CONSTANT: + +``CONFIGURE_SWAPOUT_BLOCK_HOLD`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 1000. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DESCRIPTION: -DEFAULT VALUE: - The default value is 1000. +The value of this configuration option defines the swapout task maximum block +hold time in milliseconds. -VALUE CONSTRAINTS: - The value of this configuration option shall be greater than or equal to 0 - and less than or equal to ``UINT32_MAX``. +.. rubric:: CONSTRAINTS: -DESCRIPTION: - The value of this configuration option defines the swapout task maximum block - hold time in milliseconds. +The following constraints apply to this configuration option: -NOTES: - None. +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. + +.. Generated from spec:/acfg/if/bdbuf-swapout-swap-period + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_SWAPOUT_SWAP_PERIOD @@ -273,25 +397,37 @@ NOTES: CONFIGURE_SWAPOUT_SWAP_PERIOD ----------------------------- -CONSTANT: - ``CONFIGURE_SWAPOUT_SWAP_PERIOD`` +.. rubric:: CONSTANT: + +``CONFIGURE_SWAPOUT_SWAP_PERIOD`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: -OPTION TYPE: - This configuration option is an integer define. +The default value is 250. -DEFAULT VALUE: - The default value is 250. +.. rubric:: DESCRIPTION: -VALUE CONSTRAINTS: - The value of this configuration option shall be greater than or equal to 0 - and less than or equal to ``UINT32_MAX``. +The value of this configuration option defines the swapout task swap period +in milliseconds. -DESCRIPTION: - The value of this configuration option defines the swapout task swap period - in milliseconds. +.. rubric:: CONSTRAINTS: -NOTES: - None. +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. + +.. Generated from spec:/acfg/if/bdbuf-swapout-task-priority + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_SWAPOUT_TASK_PRIORITY @@ -300,51 +436,33 @@ NOTES: CONFIGURE_SWAPOUT_TASK_PRIORITY ------------------------------- -CONSTANT: - ``CONFIGURE_SWAPOUT_TASK_PRIORITY`` - -OPTION TYPE: - This configuration option is an integer define. - -DEFAULT VALUE: - The default value is 15. +.. rubric:: CONSTANT: -VALUE CONSTRAINTS: - The value of this configuration option shall be a valid Classic API task - priority. The set of valid task priorities is scheduler-specific. +``CONFIGURE_SWAPOUT_TASK_PRIORITY`` -DESCRIPTION: - The value of this configuration option defines the swapout task priority. +.. rubric:: OPTION TYPE: -NOTES: - None. +This configuration option is an integer define. -.. index:: CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY +.. rubric:: DEFAULT VALUE: -.. _CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY: +The default value is 15. -CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY --------------------------------------- +.. rubric:: DESCRIPTION: -CONSTANT: - ``CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY`` +The value of this configuration option defines the swapout task priority. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: CONSTRAINTS: -DEFAULT VALUE: - The default value is 15. +The value of the configuration option shall be a valid Classic API task +priority. The set of valid task priorities depends on the scheduler +configuration. -VALUE CONSTRAINTS: - The value of this configuration option shall be a valid Classic API task - priority. The set of valid task priorities is scheduler-specific. +.. Generated from spec:/acfg/if/bdbuf-swapout-worker-tasks -DESCRIPTION: - The value of this configuration option defines the swapout worker task - priority. +.. raw:: latex -NOTES: - None. + \clearpage .. index:: CONFIGURE_SWAPOUT_WORKER_TASKS @@ -353,21 +471,63 @@ NOTES: CONFIGURE_SWAPOUT_WORKER_TASKS ------------------------------ -CONSTANT: - ``CONFIGURE_SWAPOUT_WORKER_TASKS`` +.. rubric:: CONSTANT: + +``CONFIGURE_SWAPOUT_WORKER_TASKS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the swapout worker task count. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. + +.. Generated from spec:/acfg/if/bdbuf-swapout-worker-taskp-riority + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY + +.. _CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY: + +CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY +-------------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: -OPTION TYPE: - This configuration option is an integer define. +The default value is 15. -DEFAULT VALUE: - The default value is 0. +.. rubric:: DESCRIPTION: -VALUE CONSTRAINTS: - The value of this configuration option shall be greater than or equal to 0 - and less than or equal to ``UINT32_MAX``. +The value of this configuration option defines the swapout worker task +priority. -DESCRIPTION: - The value of this configuration option defines the swapout worker task count. +.. rubric:: CONSTRAINTS: -NOTES: - None. +The value of the configuration option shall be a valid Classic API task +priority. The set of valid task priorities depends on the scheduler +configuration. diff --git a/c-user/config/bsp-related.rst b/c-user/config/bsp-related.rst deleted file mode 100644 index ba5ca93..0000000 --- a/c-user/config/bsp-related.rst +++ /dev/null @@ -1,268 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-4.0 - -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) - -BSP Related Configuration Options -================================= - -This section describes configuration options related to the BSP. Some -configuration options may have a BSP-specific setting which is defined by -``<bsp.h>``. The BSP-specific settings can be disabled by the -:ref:`CONFIGURE_DISABLE_BSP_SETTINGS` configuration option. - -.. index:: BSP_IDLE_TASK_BODY - -.. _BSP_IDLE_TASK_BODY: - -BSP_IDLE_TASK_BODY ------------------- - -CONSTANT: - ``BSP_IDLE_TASK_BODY`` - -OPTION TYPE: - This configuration option is an initializer define. - -DEFAULT VALUE: - The default value is BSP-specific. - -VALUE CONSTRAINTS: - The value of this configuration option shall be defined to a valid function - pointer of the type ``void *( *idle_body )( uintptr_t )``. - -DESCRIPTION: - If - - * this configuration option is defined by the BSP - - * and :ref:`CONFIGURE_DISABLE_BSP_SETTINGS` is undefined, - - then the value of this configuration option defines the default value of - :ref:`CONFIGURE_IDLE_TASK_BODY`. - -NOTES: - As it has knowledge of the specific CPU model, system controller logic, and - peripheral buses, a BSP-specific IDLE task may be capable of turning - components off to save power during extended periods of no task activity. - -.. index:: BSP_IDLE_TASK_STACK_SIZE - -.. _BSP_IDLE_TASK_STACK_SIZE: - -BSP_IDLE_TASK_STACK_SIZE ------------------------- - -CONSTANT: - ``BSP_IDLE_TASK_STACK_SIZE`` - -OPTION TYPE: - This configuration option is an integer define. - -DEFAULT VALUE: - The default value is BSP-specific. - -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: - - * It shall be greater than or equal to a - BSP-specific and application-specific minimum value. - - * It shall be small enough so that the IDLE - task stack area calculation carried out by ``<rtems/confdefs.h>`` does not - overflow an integer of type ``size_t``. - -DESCRIPTION: - If - - * this configuration option is defined by the BSP - - * and :ref:`CONFIGURE_DISABLE_BSP_SETTINGS` is undefined, - - then the value of this configuration option defines the default value of - :ref:`CONFIGURE_IDLE_TASK_SIZE`. - -NOTES: - None. - -.. index:: BSP_INITIAL_EXTENSION - -.. _BSP_INITIAL_EXTENSION: - -BSP_INITIAL_EXTENSION ---------------------- - -CONSTANT: - ``BSP_INITIAL_EXTENSION`` - -OPTION TYPE: - This configuration option is an initializer define. - -DEFAULT VALUE: - The default value is BSP-specific. - -VALUE CONSTRAINTS: - The value of this configuration option shall be a list of initializers for - structures of type :c:type:`rtems_extensions_table`. - -DESCRIPTION: - If - - * this configuration option is defined by the BSP - - * and :ref:`CONFIGURE_DISABLE_BSP_SETTINGS` is undefined, - - then the value of this configuration option is used to initialize the table - of initial user extensions. - -NOTES: - The value of this configuration option is placed after the entries of all - other initial user extensions. - -.. index:: BSP_INTERRUPT_STACK_SIZE - -.. _BSP_INTERRUPT_STACK_SIZE: - -BSP_INTERRUPT_STACK_SIZE ------------------------- - -CONSTANT: - ``BSP_INTERRUPT_STACK_SIZE`` - -OPTION TYPE: - This configuration option is an integer define. - -DEFAULT VALUE: - The default value is BSP-specific. - -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: - - * It shall be greater than or equal to a - BSP-specific and application-specific minimum value. - - * It shall be small enough so that the - interrupt stack area calculation carried out by ``<rtems/confdefs.h>`` does - not overflow an integer of type ``size_t``. - - * It shall be aligned according to - ``CPU_INTERRUPT_STACK_ALIGNMENT``. - -DESCRIPTION: - If - - * this configuration option is defined by the BSP - - * and :ref:`CONFIGURE_DISABLE_BSP_SETTINGS` is undefined, - - then the value of this configuration option defines the default value of - :ref:`CONFIGURE_INTERRUPT_STACK_SIZE`. - -NOTES: - None. - -.. index:: CONFIGURE_BSP_PREREQUISITE_DRIVERS - -.. _CONFIGURE_BSP_PREREQUISITE_DRIVERS: - -CONFIGURE_BSP_PREREQUISITE_DRIVERS ----------------------------------- - -CONSTANT: - ``CONFIGURE_BSP_PREREQUISITE_DRIVERS`` - -OPTION TYPE: - This configuration option is an initializer define. - -DEFAULT VALUE: - The default value is BSP-specific. - -VALUE CONSTRAINTS: - The value of this configuration option shall be a list of initializers for - structures of type :c:type:`rtems_extensions_table`. - -DESCRIPTION: - If - - * this configuration option is defined by the BSP - - * and :ref:`CONFIGURE_DISABLE_BSP_SETTINGS` is undefined, - - then the value of this configuration option is used to initialize the table - of initial user extensions. - -NOTES: - The value of this configuration option is placed before the entries of all - other initial user extensions (including - :ref:`CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS`). - -.. index:: CONFIGURE_DISABLE_BSP_SETTINGS - -.. _CONFIGURE_DISABLE_BSP_SETTINGS: - -CONFIGURE_DISABLE_BSP_SETTINGS ------------------------------- - -CONSTANT: - ``CONFIGURE_DISABLE_BSP_SETTINGS`` - -OPTION TYPE: - This configuration option is a boolean feature define. - -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. - -DESCRIPTION: - In case this configuration option is defined, then the following BSP related - configuration options are undefined: - - - :ref:`BSP_IDLE_TASK_BODY` - - - :ref:`BSP_IDLE_TASK_STACK_SIZE` - - - :ref:`BSP_INITIAL_EXTENSION` - - - :ref:`BSP_INTERRUPT_STACK_SIZE` - - - :ref:`CONFIGURE_BSP_PREREQUISITE_DRIVERS` - - - :ref:`CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK` - -NOTES: - None. - -.. index:: CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK - -.. _CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK: - -CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK ----------------------------------- - -CONSTANT: - ``CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK`` - -OPTION TYPE: - This configuration option is a boolean feature define. - -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. - -DESCRIPTION: - If - - * this configuration option is defined by the BSP - - * and :ref:`CONFIGURE_DISABLE_BSP_SETTINGS` is undefined, - - then not all memory is made available to the C Program Heap immediately at - system initialization time. When :c:func:`malloc()` or other standard memory - allocation functions are unable to allocate memory, they will call the BSP - supplied :c:func:`sbrk()` function to obtain more memory. - -NOTES: - This option should not be defined by the application. Only the BSP knows how - it allocates memory to the C Program Heap. diff --git a/c-user/config/classic-api.rst b/c-user/config/classic-api.rst index bd2fa00..212f666 100644 --- a/c-user/config/classic-api.rst +++ b/c-user/config/classic-api.rst @@ -1,13 +1,36 @@ .. 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 & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/acfg/if/group-classic + Classic API Configuration ========================= This section describes configuration options related to the Classic API. +.. Generated from spec:/acfg/if/max-barriers + +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MAXIMUM_BARRIERS .. _CONFIGURE_MAXIMUM_BARRIERS: @@ -15,39 +38,50 @@ This section describes configuration options related to the Classic API. CONFIGURE_MAXIMUM_BARRIERS -------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_BARRIERS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_BARRIERS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DEFAULT VALUE: -DEFAULT VALUE: - The default value is 0. +The default value is 0. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: DESCRIPTION: - * It shall be greater than or equal to 0. +The value of this configuration option defines the maximum number of Classic +API Barriers that can be concurrently active. - * It shall be less than or equal to 65535. +.. rubric:: NOTES: - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. - * It may be defined through - :c:func:`rtems_resource_unlimited` the enable unlimited objects for this - object class, if the value passed to :c:func:`rtems_resource_unlimited` - satisfies all other constraints of this configuration option. +.. rubric:: CONSTRAINTS: -DESCRIPTION: - The value of this configuration option defines the maximum number of Classic - API Barriers that can be concurrently active. +The following constraints apply to this configuration option: -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +* The value of the configuration option may be defined through + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` + satisfies all other constraints of the configuration option. + +.. Generated from spec:/acfg/if/max-message-queues + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_MAXIMUM_MESSAGE_QUEUES @@ -56,41 +90,52 @@ NOTES: CONFIGURE_MAXIMUM_MESSAGE_QUEUES -------------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_MESSAGE_QUEUES`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_MESSAGE_QUEUES`` -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: OPTION TYPE: -DEFAULT VALUE: - The default value is 0. +This configuration option is an integer define. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: DEFAULT VALUE: - * It shall be greater than or equal to 0. +The default value is 0. - * It shall be less than or equal to 65535. +.. rubric:: DESCRIPTION: - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +The value of this configuration option defines the maximum number of Classic +API Message Queues that can be concurrently active. - * It may be defined through - :c:func:`rtems_resource_unlimited` the enable unlimited objects for this - object class, if the value passed to :c:func:`rtems_resource_unlimited` - satisfies all other constraints of this configuration option. +.. rubric:: NOTES: -DESCRIPTION: - The value of this configuration option defines the maximum number of Classic - API Message Queues that can be concurrently active. +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. You have to account for the memory used to +store the messages of each message queue, see +:ref:`CONFIGURE_MESSAGE_BUFFER_MEMORY`. -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. You have to account for the memory used to - store the messages of each message queue, see - :ref:`CONFIGURE_MESSAGE_BUFFER_MEMORY`. +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +* The value of the configuration option may be defined through + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` + satisfies all other constraints of the configuration option. + +.. Generated from spec:/acfg/if/max-partitions + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_MAXIMUM_PARTITIONS @@ -99,39 +144,50 @@ NOTES: CONFIGURE_MAXIMUM_PARTITIONS ---------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_PARTITIONS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_PARTITIONS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is an integer define. +The value of this configuration option defines the maximum number of Classic +API Partitions that can be concurrently active. -DEFAULT VALUE: - The default value is 0. +.. rubric:: NOTES: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. - * It shall be greater than or equal to 0. +.. rubric:: CONSTRAINTS: - * It shall be less than or equal to 65535. +The following constraints apply to this configuration option: - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +* The value of the configuration option shall be greater than or equal to zero. - * It may be defined through - :c:func:`rtems_resource_unlimited` the enable unlimited objects for this - object class, if the value passed to :c:func:`rtems_resource_unlimited` - satisfies all other constraints of this configuration option. +* The value of the configuration option shall be less than or equal to 65535. -DESCRIPTION: - The value of this configuration option defines the maximum number of Classic - API Partitions that can be concurrently active. +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. +* The value of the configuration option may be defined through + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` + satisfies all other constraints of the configuration option. + +.. Generated from spec:/acfg/if/max-periods + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_MAXIMUM_PERIODS @@ -140,39 +196,50 @@ NOTES: CONFIGURE_MAXIMUM_PERIODS ------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_PERIODS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_PERIODS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: -OPTION TYPE: - This configuration option is an integer define. +The default value is 0. -DEFAULT VALUE: - The default value is 0. +.. rubric:: DESCRIPTION: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The value of this configuration option defines the maximum number of Classic +API Periods that can be concurrently active. - * It shall be greater than or equal to 0. +.. rubric:: NOTES: - * It shall be less than or equal to 65535. +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +.. rubric:: CONSTRAINTS: - * It may be defined through - :c:func:`rtems_resource_unlimited` the enable unlimited objects for this - object class, if the value passed to :c:func:`rtems_resource_unlimited` - satisfies all other constraints of this configuration option. +The following constraints apply to this configuration option: -DESCRIPTION: - The value of this configuration option defines the maximum number of Classic - API Periods that can be concurrently active. +* The value of the configuration option shall be greater than or equal to zero. -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +* The value of the configuration option may be defined through + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` + satisfies all other constraints of the configuration option. + +.. Generated from spec:/acfg/if/max-ports + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_MAXIMUM_PORTS @@ -181,39 +248,50 @@ NOTES: CONFIGURE_MAXIMUM_PORTS ----------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_PORTS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_PORTS`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is an integer define. +This configuration option is an integer define. -DEFAULT VALUE: - The default value is 0. +.. rubric:: DEFAULT VALUE: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The default value is 0. - * It shall be greater than or equal to 0. +.. rubric:: DESCRIPTION: - * It shall be less than or equal to 65535. +The value of this configuration option defines the maximum number of Classic +API Ports that can be concurrently active. - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +.. rubric:: NOTES: - * It may be defined through - :c:func:`rtems_resource_unlimited` the enable unlimited objects for this - object class, if the value passed to :c:func:`rtems_resource_unlimited` - satisfies all other constraints of this configuration option. +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. -DESCRIPTION: - The value of this configuration option defines the maximum number of Classic - API Ports that can be concurrently active. +.. rubric:: CONSTRAINTS: -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +* The value of the configuration option may be defined through + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` + satisfies all other constraints of the configuration option. + +.. Generated from spec:/acfg/if/max-regions + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_MAXIMUM_REGIONS @@ -222,39 +300,50 @@ NOTES: CONFIGURE_MAXIMUM_REGIONS ------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_REGIONS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_REGIONS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the maximum number of Classic +API Regions that can be concurrently active. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: NOTES: -DEFAULT VALUE: - The default value is 0. +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: CONSTRAINTS: - * It shall be greater than or equal to 0. +The following constraints apply to this configuration option: - * It shall be less than or equal to 65535. +* The value of the configuration option shall be greater than or equal to zero. - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +* The value of the configuration option shall be less than or equal to 65535. - * It may be defined through - :c:func:`rtems_resource_unlimited` the enable unlimited objects for this - object class, if the value passed to :c:func:`rtems_resource_unlimited` - satisfies all other constraints of this configuration option. +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. -DESCRIPTION: - The value of this configuration option defines the maximum number of Classic - API Regions that can be concurrently active. +* The value of the configuration option may be defined through + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` + satisfies all other constraints of the configuration option. -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. +.. Generated from spec:/acfg/if/max-semaphores + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_MAXIMUM_SEMAPHORES @@ -263,43 +352,54 @@ NOTES: CONFIGURE_MAXIMUM_SEMAPHORES ---------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_SEMAPHORES`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_SEMAPHORES`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DESCRIPTION: -DEFAULT VALUE: - The default value is 0. +The value of this configuration option defines the maximum number of Classic +API Semaphore that can be concurrently active. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: NOTES: - * It shall be greater than or equal to 0. +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. - * It shall be less than or equal to 65535. +In SMP configurations, the size of a Semaphore Control Block depends on the +scheduler count (see :ref:`ConfigurationSchedulerTable`). The semaphores +using the :ref:`MrsP` need a ceiling priority per scheduler. - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +.. rubric:: CONSTRAINTS: - * It may be defined through - :c:func:`rtems_resource_unlimited` the enable unlimited objects for this - object class, if the value passed to :c:func:`rtems_resource_unlimited` - satisfies all other constraints of this configuration option. +The following constraints apply to this configuration option: -DESCRIPTION: - The value of this configuration option defines the maximum number of Classic - API Semaphore that can be concurrently active. +* The value of the configuration option shall be greater than or equal to zero. -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. +* The value of the configuration option shall be less than or equal to 65535. - In SMP configurations, the size of a Semaphore Control Block depends on the - scheduler count (see :ref:`ConfigurationSchedulerTable`). The semaphores - using the :ref:`MrsP` need a ceiling priority per scheduler. +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +* The value of the configuration option may be defined through + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` + satisfies all other constraints of the configuration option. + +.. Generated from spec:/acfg/if/max-tasks + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_MAXIMUM_TASKS @@ -308,59 +408,68 @@ NOTES: CONFIGURE_MAXIMUM_TASKS ----------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_TASKS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_TASKS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DEFAULT VALUE: -DEFAULT VALUE: - The default value is 0. +The default value is 0. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: DESCRIPTION: - * It shall be greater than or equal to 0. +The value of this configuration option defines the maximum number of Classic +API Tasks that can be concurrently active. - * It shall be less than or equal to 65535. +.. rubric:: NOTES: - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. - * It shall be small enough so that the task - stack space calculation carried out by ``<rtems/confdefs.h>`` does not - overflow an integer of type ``uintptr_t``. +The calculations for the required memory in the RTEMS Workspace for tasks +assume that each task has a minimum stack size and has floating point +support enabled. The configuration option :ref:`CONFIGURE_EXTRA_TASK_STACKS` is used +to specify task stack requirements *above* the minimum size required. - * It may be defined through - :c:func:`rtems_resource_unlimited` the enable unlimited objects for this - object class, if the value passed to :c:func:`rtems_resource_unlimited` - satisfies all other constraints of this configuration option. +The maximum number of POSIX threads is specified by +:ref:`CONFIGURE_MAXIMUM_POSIX_THREADS`. -DESCRIPTION: - The value of this configuration option defines the maximum number of Classic - API Tasks that can be concurrently active. +A future enhancement to ``<rtems/confdefs.h>`` could be to eliminate the +assumption that all tasks have floating point enabled. This would require +the addition of a new configuration parameter to specify the number of +tasks which enable floating point support. -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. +.. rubric:: CONSTRAINTS: - The calculations for the required memory in the RTEMS Workspace for tasks - assume that each task has a minimum stack size and has floating point - support enabled. The configuration parameter - ``CONFIGURE_EXTRA_TASK_STACKS`` is used to specify task stack requirements - *ABOVE* the minimum size required. See :ref:`Reserve Task/Thread Stack - Memory Above Minimum` for more information about - ``CONFIGURE_EXTRA_TASK_STACKS``. +The following constraints apply to this configuration option: - The maximum number of POSIX threads is specified by - :ref:`CONFIGURE_MAXIMUM_POSIX_THREADS`. +* The value of the configuration option shall be greater than or equal to zero. - A future enhancement to ``<rtems/confdefs.h>`` could be to eliminate the - assumption that all tasks have floating point enabled. This would require - the addition of a new configuration parameter to specify the number of - tasks which enable floating point support. +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +* The value of the configuration option shall be small enough so that the task + stack space calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. + +* The value of the configuration option may be defined through + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` + satisfies all other constraints of the configuration option. + +.. Generated from spec:/acfg/if/max-timers + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_MAXIMUM_TIMERS @@ -369,39 +478,50 @@ NOTES: CONFIGURE_MAXIMUM_TIMERS ------------------------ -CONSTANT: - ``CONFIGURE_MAXIMUM_TIMERS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_TIMERS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the maximum number of Classic +API Timers that can be concurrently active. + +.. rubric:: NOTES: -OPTION TYPE: - This configuration option is an integer define. +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. -DEFAULT VALUE: - The default value is 0. +.. rubric:: CONSTRAINTS: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The following constraints apply to this configuration option: - * It shall be greater than or equal to 0. +* The value of the configuration option shall be greater than or equal to zero. - * It shall be less than or equal to 65535. +* The value of the configuration option shall be less than or equal to 65535. - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. - * It may be defined through - :c:func:`rtems_resource_unlimited` the enable unlimited objects for this - object class, if the value passed to :c:func:`rtems_resource_unlimited` - satisfies all other constraints of this configuration option. +* The value of the configuration option may be defined through + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` + satisfies all other constraints of the configuration option. -DESCRIPTION: - The value of this configuration option defines the maximum number of Classic - API Timers that can be concurrently active. +.. Generated from spec:/acfg/if/max-user-extensions -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. +.. raw:: latex + + \clearpage .. index:: CONFIGURE_MAXIMUM_USER_EXTENSIONS @@ -410,30 +530,83 @@ NOTES: CONFIGURE_MAXIMUM_USER_EXTENSIONS --------------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_USER_EXTENSIONS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_USER_EXTENSIONS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the maximum number of Classic +API User Extensions that can be concurrently active. + +.. rubric:: NOTES: + +This object class cannot be configured in unlimited allocation mode. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +.. Generated from spec:/acfg/if/min-tasks-with-user-provided-storage + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_MINIMUM_TASKS_WITH_USER_PROVIDED_STORAGE + +.. _CONFIGURE_MINIMUM_TASKS_WITH_USER_PROVIDED_STORAGE: + +CONFIGURE_MINIMUM_TASKS_WITH_USER_PROVIDED_STORAGE +-------------------------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_MINIMUM_TASKS_WITH_USER_PROVIDED_STORAGE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DESCRIPTION: -DEFAULT VALUE: - The default value is 0. +The value of this configuration option defines the minimum count of Classic +API Tasks which are constructed by :ref:`InterfaceRtemsTaskConstruct`. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: NOTES: - * It shall be greater than or equal to 0. +By default, the calculation for the required memory in the RTEMS Workspace +for tasks assumes that all Classic API Tasks are created by +:ref:`InterfaceRtemsTaskCreate`. This configuration option can be used to +reduce the required memory for the system-provided task storage areas since +tasks constructed by :ref:`InterfaceRtemsTaskConstruct` use a user-provided +task storage area. - * It shall be less than or equal to 65535. +.. rubric:: CONSTRAINTS: - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +The following constraints apply to this configuration option: -DESCRIPTION: - The value of this configuration option defines the maximum number of Classic - API User Extensions that can be concurrently active. +* The value of the configuration option shall be greater than or equal to zero. -NOTES: - This object class cannot be configured in unlimited allocation mode. +* The value of the configuration option shall be less than or equal to + :ref:`CONFIGURE_MAXIMUM_TASKS`. diff --git a/c-user/config/classic-init-task.rst b/c-user/config/classic-init-task.rst index ca300e7..f65bb8a 100644 --- a/c-user/config/classic-init-task.rst +++ b/c-user/config/classic-init-task.rst @@ -1,14 +1,37 @@ .. 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 & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/acfg/if/group-classicinit + Classic API Initialization Task Configuration ============================================= This section describes configuration options related to the Classic API initialization task. +.. Generated from spec:/acfg/if/init-task-arguments + +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_INIT_TASK_ARGUMENTS .. _CONFIGURE_INIT_TASK_ARGUMENTS: @@ -16,25 +39,33 @@ initialization task. CONFIGURE_INIT_TASK_ARGUMENTS ----------------------------- -CONSTANT: - ``CONFIGURE_INIT_TASK_ARGUMENTS`` +.. rubric:: CONSTANT: + +``CONFIGURE_INIT_TASK_ARGUMENTS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DEFAULT VALUE: -DEFAULT VALUE: - The default value is 0. +The default value is 0. -VALUE CONSTRAINTS: - The value of this configuration option shall be a valid integer of type - ``rtems_task_argument``. +.. rubric:: DESCRIPTION: -DESCRIPTION: - The value of this configuration option defines task argument of the Classic - API initialization task. +The value of this configuration option defines task argument of the Classic +API initialization task. -NOTES: - None. +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be convertible to an integer of +type :ref:`InterfaceRtemsTaskArgument`. + +.. Generated from spec:/acfg/if/init-task-attributes + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_INIT_TASK_ATTRIBUTES @@ -43,24 +74,103 @@ NOTES: CONFIGURE_INIT_TASK_ATTRIBUTES ------------------------------ -CONSTANT: - ``CONFIGURE_INIT_TASK_ATTRIBUTES`` +.. rubric:: CONSTANT: + +``CONFIGURE_INIT_TASK_ATTRIBUTES`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is :c:macro:`RTEMS_DEFAULT_ATTRIBUTES`. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the task attributes of the +Classic API initialization task. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be a valid task attribute set. + +.. Generated from spec:/acfg/if/init-task-construct-storage-size + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_INIT_TASK_CONSTRUCT_STORAGE_SIZE + +.. _CONFIGURE_INIT_TASK_CONSTRUCT_STORAGE_SIZE: -OPTION TYPE: - This configuration option is an integer define. +CONFIGURE_INIT_TASK_CONSTRUCT_STORAGE_SIZE +------------------------------------------ -DEFAULT VALUE: - The default value is ``RTEMS_DEFAULT_ATTRIBUTES``. +.. rubric:: CONSTANT: -VALUE CONSTRAINTS: - The value of this configuration option shall be a valid task attribute set. +``CONFIGURE_INIT_TASK_CONSTRUCT_STORAGE_SIZE`` -DESCRIPTION: - The value of this configuration option defines the task attributes of the - Classic API initialization task. +.. rubric:: OPTION TYPE: -NOTES: - None. +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +This configuration option has no default value. If it is not specified, then +the Classic API initialization task will be created with the stack size +defined by the :ref:`CONFIGURE_INIT_TASK_STACK_SIZE` configuration option. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the task storage size of the +Classic API initialization task. + +.. rubric:: NOTES: + +If this configuration option is specified, then + +* a task storage area of the specified size is statically allocated by + ``<rtems/confdefs.h>`` for the Classic API initialization task, + +* the Classic API initialization task is constructed by + :ref:`InterfaceRtemsTaskConstruct` instead of using + :ref:`InterfaceRtemsTaskCreate`, + +* the maximum thread-local storage size defined by + :ref:`CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE` is used for the Classic API + initialization task, + +* the Classic API initialization task should be accounted for in + :ref:`CONFIGURE_MINIMUM_TASKS_WITH_USER_PROVIDED_STORAGE`, and + +* the task storage area used for the Classic API initialization task is not + reclaimed by the system if the task is deleted. + +The + +* :ref:`CONFIGURE_INIT_TASK_STACK_SIZE` and + +* ``CONFIGURE_INIT_TASK_CONSTRUCT_STORAGE_SIZE`` + +configuration options are mutually exclusive. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to + :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. + +* The value of the configuration option shall be defined using + :ref:`InterfaceRTEMSTASKSTORAGESIZE`. + +.. Generated from spec:/acfg/if/init-task-entrypoint + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_INIT_TASK_ENTRY_POINT @@ -69,26 +179,38 @@ NOTES: CONFIGURE_INIT_TASK_ENTRY_POINT ------------------------------- -CONSTANT: - ``CONFIGURE_INIT_TASK_ENTRY_POINT`` +.. rubric:: CONSTANT: + +``CONFIGURE_INIT_TASK_ENTRY_POINT`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is an initializer define. +This configuration option is an initializer define. -DEFAULT VALUE: - The default value is ``Init``. +.. rubric:: DEFAULT VALUE: -VALUE CONSTRAINTS: - The value of this configuration option shall be defined to a valid function - pointer of the type ``void ( *entry_point )( rtems_task_argument )``. +The default value is ``Init``. -DESCRIPTION: - The value of this configuration option initializes the entry point of the - Classic API initialization task. +.. rubric:: DESCRIPTION: -NOTES: - The application shall provide the function referenced by this configuration - option. +The value of this configuration option initializes the entry point of the +Classic API initialization task. + +.. rubric:: NOTES: + +The application shall provide the function referenced by this configuration +option. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be defined to a valid function +pointer of the type ``void ( *entry_point )( rtems_task_argument )``. + +.. Generated from spec:/acfg/if/init-task-initial-modes + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_INIT_TASK_INITIAL_MODES @@ -97,25 +219,33 @@ NOTES: CONFIGURE_INIT_TASK_INITIAL_MODES --------------------------------- -CONSTANT: - ``CONFIGURE_INIT_TASK_INITIAL_MODES`` +.. rubric:: CONSTANT: + +``CONFIGURE_INIT_TASK_INITIAL_MODES`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +In SMP configurations, the default value is :c:macro:`RTEMS_DEFAULT_MODES` +otherwise the default value is :c:macro:`RTEMS_NO_PREEMPT`. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is an integer define. +The value of this configuration option defines the initial execution mode of +the Classic API initialization task. -DEFAULT VALUE: - In SMP configurations, the default value is ``RTEMS_DEFAULT_MODES``, - otherwise the default value is ``RTEMS_NO_PREEMPT``. +.. rubric:: CONSTRAINTS: -VALUE CONSTRAINTS: - The value of this configuration option shall be a valid task mode set. +The value of the configuration option shall be a valid task mode set. -DESCRIPTION: - The value of this configuration option defines the initial execution mode of - the Classic API initialization task. +.. Generated from spec:/acfg/if/init-task-name -NOTES: - None. +.. raw:: latex + + \clearpage .. index:: CONFIGURE_INIT_TASK_NAME @@ -124,25 +254,37 @@ NOTES: CONFIGURE_INIT_TASK_NAME ------------------------ -CONSTANT: - ``CONFIGURE_INIT_TASK_NAME`` +.. rubric:: CONSTANT: + +``CONFIGURE_INIT_TASK_NAME`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is ``rtems_build_name( 'U', 'I', '1', ' ' )``. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DESCRIPTION: -DEFAULT VALUE: - The default value is ``rtems_build_name( 'U', 'I', '1', ' ' )``. +The value of this configuration option defines the name of the Classic API +initialization task. + +.. rubric:: NOTES: + +Use :ref:`InterfaceRtemsBuildName` to define the task name. -VALUE CONSTRAINTS: - The value of this configuration option shall be a valid integer of type - ``rtems_name``. +.. rubric:: CONSTRAINTS: -DESCRIPTION: - The value of this configuration option defines the name of the Classic API - initialization task. +The value of the configuration option shall be convertible to an integer of +type :c:type:`rtems_name`. -NOTES: - Use :c:func:`rtems_build_name` to define the task name. +.. Generated from spec:/acfg/if/init-task-priority + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_INIT_TASK_PRIORITY @@ -151,25 +293,34 @@ NOTES: CONFIGURE_INIT_TASK_PRIORITY ---------------------------- -CONSTANT: - ``CONFIGURE_INIT_TASK_PRIORITY`` +.. rubric:: CONSTANT: + +``CONFIGURE_INIT_TASK_PRIORITY`` -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: OPTION TYPE: -DEFAULT VALUE: - The default value is 1. +This configuration option is an integer define. -VALUE CONSTRAINTS: - The value of this configuration option shall be a valid Classic API task - priority. The set of valid task priorities is scheduler-specific. +.. rubric:: DEFAULT VALUE: -DESCRIPTION: - The value of this configuration option defines the initial priority of the - Classic API initialization task. +The default value is 1. -NOTES: - None. +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the initial priority of the +Classic API initialization task. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be a valid Classic API task +priority. The set of valid task priorities depends on the scheduler +configuration. + +.. Generated from spec:/acfg/if/init-task-stack-size + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_INIT_TASK_STACK_SIZE @@ -178,31 +329,50 @@ NOTES: CONFIGURE_INIT_TASK_STACK_SIZE ------------------------------ -CONSTANT: - ``CONFIGURE_INIT_TASK_STACK_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_INIT_TASK_STACK_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is an integer define. +The value of this configuration option defines the task stack size of the +Classic API initialization task. -DEFAULT VALUE: - The default value is :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. +.. rubric:: NOTES: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The - * It shall be greater than or equal to :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. +* ``CONFIGURE_INIT_TASK_STACK_SIZE`` and - * It shall be small enough so that the task - stack space calculation carried out by ``<rtems/confdefs.h>`` does not - overflow an integer of type ``uintptr_t``. +* :ref:`CONFIGURE_INIT_TASK_CONSTRUCT_STORAGE_SIZE` -DESCRIPTION: - The value of this configuration option defines the task stack size of the - Classic API initialization task. +configuration options are mutually exclusive. -NOTES: - None. +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to + :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. + +* The value of the configuration option shall be small enough so that the task + stack space calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. + +.. Generated from spec:/acfg/if/rtems-init-tasks-table + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_RTEMS_INIT_TASKS_TABLE @@ -211,28 +381,36 @@ NOTES: CONFIGURE_RTEMS_INIT_TASKS_TABLE -------------------------------- -CONSTANT: - ``CONFIGURE_RTEMS_INIT_TASKS_TABLE`` +.. rubric:: CONSTANT: + +``CONFIGURE_RTEMS_INIT_TASKS_TABLE`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is a boolean feature define. +In case this configuration option is defined, then exactly one Classic API +initialization task is configured. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: NOTES: -DESCRIPTION: - In case this configuration option is defined, then exactly one Classic API - initialization task is configured. +The application shall define at least one of the following configuration +options -NOTES: - The application shall define exactly one of the following configuration - options +* ``CONFIGURE_RTEMS_INIT_TASKS_TABLE``, - * `CONFIGURE_RTEMS_INIT_TASKS_TABLE`, +* :ref:`CONFIGURE_POSIX_INIT_THREAD_TABLE`, or - * :ref:`CONFIGURE_POSIX_INIT_THREAD_TABLE`, or +* :ref:`CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION` - * :ref:`CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION` +otherwise a compile time error in the configuration file will occur. - otherwise a compile time error in the configuration file will occur. +The Classic API initialization task performs the +:ref:`GlobalConstruction`. diff --git a/c-user/config/device-driver.rst b/c-user/config/device-driver.rst index 627c346..1e31575 100644 --- a/c-user/config/device-driver.rst +++ b/c-user/config/device-driver.rst @@ -1,7 +1,24 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2021 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/acfg/if/group-devdrv Device Driver Configuration =========================== @@ -9,6 +26,12 @@ Device Driver Configuration This section describes configuration options related to the device drivers. Note that network device drivers are not covered by the following options. +.. Generated from spec:/acfg/if/appl-does-not-need-clock-driver + +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER .. _CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER: @@ -16,34 +39,45 @@ Note that network device drivers are not covered by the following options. CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER ------------------------------------------------ -CONSTANT: - ``CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DEFAULT CONFIGURATION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then a Clock Driver may be - initialized during system initialization. +If this configuration option is undefined, then a Clock Driver may be +initialized during system initialization. -DESCRIPTION: - In case this configuration option is defined, then **no** Clock Driver is - initialized during system initialization. +.. rubric:: DESCRIPTION: -NOTES: - This configuration parameter is intended to prevent the common user error - of using the Hello World example as the baseline for an application and - leaving out a clock tick source. +In case this configuration option is defined, then **no** Clock Driver is +initialized during system initialization. - The application shall define exactly one of the following configuration options +.. rubric:: NOTES: - * :ref:`CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER`, +This configuration parameter is intended to prevent the common user error +of using the Hello World example as the baseline for an application and +leaving out a clock tick source. - * `CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`, or +The application shall define exactly one of the following configuration options - * :ref:`CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER`, +* :ref:`CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER`, - otherwise a compile time error in the configuration file will occur. +* ``CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER``, or + +* :ref:`CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER`, + +otherwise a compile time error in the configuration file will occur. + +.. Generated from spec:/acfg/if/appl-extra-drivers + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_APPLICATION_EXTRA_DRIVERS @@ -52,29 +86,41 @@ NOTES: CONFIGURE_APPLICATION_EXTRA_DRIVERS ----------------------------------- -CONSTANT: - ``CONFIGURE_APPLICATION_EXTRA_DRIVERS`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_EXTRA_DRIVERS`` -OPTION TYPE: - This configuration option is an initializer define. +.. rubric:: OPTION TYPE: -DEFAULT VALUE: - The default value is the empty list. +This configuration option is an initializer define. -VALUE CONSTRAINTS: - The value of this configuration option shall be a list of initializers for - structures of type :c:type:`rtems_driver_address_table`. +.. rubric:: DEFAULT VALUE: -DESCRIPTION: - The value of this configuration option is used to initialize the Device - Driver Table. +The default value is the empty list. -NOTES: - The value of this configuration option is placed after the entries of other - device driver configuration options. +.. rubric:: DESCRIPTION: - See :ref:`CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS` for an alternative - placement of application device driver initializers. +The value of this configuration option is used to initialize the Device +Driver Table. + +.. rubric:: NOTES: + +The value of this configuration option is placed after the entries of other +device driver configuration options. + +See :ref:`CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS` for an alternative +placement of application device driver initializers. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be a list of initializers for +structures of type :ref:`InterfaceRtemsDriverAddressTable`. + +.. Generated from spec:/acfg/if/appl-needs-ata-driver + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_APPLICATION_NEEDS_ATA_DRIVER @@ -83,25 +129,36 @@ NOTES: CONFIGURE_APPLICATION_NEEDS_ATA_DRIVER -------------------------------------- -CONSTANT: - ``CONFIGURE_APPLICATION_NEEDS_ATA_DRIVER`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_ATA_DRIVER`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DEFAULT CONFIGURATION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +If this configuration option is undefined, then the described feature is not +enabled. -DESCRIPTION: - In case this configuration option is defined, then the ATA Driver is - initialized during system initialization. +.. rubric:: DESCRIPTION: -NOTES: - Most BSPs do not include support for an ATA Driver. +In case this configuration option is defined, then the ATA Driver is +initialized during system initialization. - If this option is defined and the BSP does not have this device driver, then - the user will get a link time error for an undefined symbol. +.. rubric:: NOTES: + +Most BSPs do not include support for an ATA Driver. + +If this option is defined and the BSP does not have this device driver, then +the user will get a link time error for an undefined symbol. + +.. Generated from spec:/acfg/if/appl-needs-clock-driver + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER @@ -110,33 +167,44 @@ NOTES: CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER ---------------------------------------- -CONSTANT: - ``CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the Clock Driver is +initialized during system initialization. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: NOTES: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +The Clock Driver is responsible for providing a regular interrupt +which invokes a clock tick directive. -DESCRIPTION: - In case this configuration option is defined, then the Clock Driver is - initialized during system initialization. +The application shall define exactly one of the following configuration options -NOTES: - The Clock Driver is responsible for providing a regular interrupt - which invokes a clock tick directive. +* ``CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER``, - The application shall define exactly one of the following configuration options +* :ref:`CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`, or - * `CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER`, +* :ref:`CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER`, - * :ref:`CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`, or +otherwise a compile time error in the configuration file will occur. - * :ref:`CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER`, +.. Generated from spec:/acfg/if/appl-needs-console-driver - otherwise a compile time error in the configuration file will occur. +.. raw:: latex + + \clearpage .. index:: CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER @@ -145,37 +213,48 @@ NOTES: CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER ------------------------------------------ -CONSTANT: - ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DESCRIPTION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +In case this configuration option is defined, then the Console Driver is +initialized during system initialization. -DESCRIPTION: - In case this configuration option is defined, then the Console Driver is - initialized during system initialization. +.. rubric:: NOTES: -NOTES: - The Console Driver is responsible for providing the :file:`/dev/console` - device file. This device is used to initialize the standard input, output, - and error file descriptors. +The Console Driver is responsible for providing the :file:`/dev/console` +device file. This device is used to initialize the standard input, output, +and error file descriptors. - BSPs should be constructed in a manner that allows :c:func:`printk` to work - properly without the need for the Console Driver to be configured. +BSPs should be constructed in a manner that allows :ref:`InterfacePrintk` to work +properly without the need for the Console Driver to be configured. - The +The - * :ref:`CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`, +* ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER``, - * :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER`, and +* :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER`, and - * :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER` +* :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER` - configuration options are mutually exclusive. +configuration options are mutually exclusive. + +.. Generated from spec:/acfg/if/appl-needs-framebuffer-driver + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER @@ -184,26 +263,37 @@ NOTES: CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER ----------------------------------------------- -CONSTANT: - ``CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then the Frame Buffer Driver is - initialized during system initialization. +If this configuration option is undefined, then the described feature is not +enabled. -NOTES: - Most BSPs do not include support for a Frame Buffer Driver. This is - because many boards do not include the required hardware. +.. rubric:: DESCRIPTION: - If this option is defined and the BSP does not have this device driver, then - the user will get a link time error for an undefined symbol. +In case this configuration option is defined, then the Frame Buffer Driver is +initialized during system initialization. + +.. rubric:: NOTES: + +Most BSPs do not include support for a Frame Buffer Driver. This is +because many boards do not include the required hardware. + +If this option is defined and the BSP does not have this device driver, then +the user will get a link time error for an undefined symbol. + +.. Generated from spec:/acfg/if/appl-needs-ide-driver + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_APPLICATION_NEEDS_IDE_DRIVER @@ -212,25 +302,36 @@ NOTES: CONFIGURE_APPLICATION_NEEDS_IDE_DRIVER -------------------------------------- -CONSTANT: - ``CONFIGURE_APPLICATION_NEEDS_IDE_DRIVER`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_IDE_DRIVER`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is a boolean feature define. +In case this configuration option is defined, then the IDE Driver is +initialized during system initialization. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: NOTES: -DESCRIPTION: - In case this configuration option is defined, then the IDE Driver is - initialized during system initialization. +Most BSPs do not include support for an IDE Driver. -NOTES: - Most BSPs do not include support for an IDE Driver. +If this option is defined and the BSP does not have this device driver, then +the user will get a link time error for an undefined symbol. - If this option is defined and the BSP does not have this device driver, then - the user will get a link time error for an undefined symbol. +.. Generated from spec:/acfg/if/appl-needs-null-driver + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER .. index:: /dev/null @@ -240,22 +341,33 @@ NOTES: CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER --------------------------------------- -CONSTANT: - ``CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: -OPTION TYPE: - This configuration option is a boolean feature define. +If this configuration option is undefined, then the described feature is not +enabled. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DESCRIPTION: -DESCRIPTION: - In case this configuration option is defined, then the :file:`/dev/null` - Driver is initialized during system initialization. +In case this configuration option is defined, then the :file:`/dev/null` +Driver is initialized during system initialization. -NOTES: - This device driver is supported by all BSPs. +.. rubric:: NOTES: + +This device driver is supported by all BSPs. + +.. Generated from spec:/acfg/if/appl-needs-rtc-driver + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER @@ -264,26 +376,37 @@ NOTES: CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER -------------------------------------- -CONSTANT: - ``CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER`` -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: OPTION TYPE: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +This configuration option is a boolean feature define. -DESCRIPTION: - In case this configuration option is defined, then the Real-Time Clock Driver - is initialized during system initialization. +.. rubric:: DEFAULT CONFIGURATION: -NOTES: - Most BSPs do not include support for a real-time clock (RTC). This is because - many boards do not include the required hardware. +If this configuration option is undefined, then the described feature is not +enabled. - If this is defined and the BSP does not have this device driver, then the - user will get a link time error for an undefined symbol. +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the Real-Time Clock Driver +is initialized during system initialization. + +.. rubric:: NOTES: + +Most BSPs do not include support for a real-time clock (RTC). This is because +many boards do not include the required hardware. + +If this is defined and the BSP does not have this device driver, then the +user will get a link time error for an undefined symbol. + +.. Generated from spec:/acfg/if/appl-needs-simple-console-driver + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER @@ -292,41 +415,52 @@ NOTES: CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER ------------------------------------------------- -CONSTANT: - ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: -OPTION TYPE: - This configuration option is a boolean feature define. +If this configuration option is undefined, then the described feature is not +enabled. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DESCRIPTION: -DESCRIPTION: - In case this configuration option is defined, then the Simple Console Driver - is initialized during system initialization. +In case this configuration option is defined, then the Simple Console Driver +is initialized during system initialization. -NOTES: - This device driver is responsible for providing the :file:`/dev/console` - device file. This device is used to initialize the standard input, output, - and error file descriptors. +.. rubric:: NOTES: - This device driver reads via :c:func:`getchark`. +This device driver is responsible for providing the :file:`/dev/console` +device file. This device is used to initialize the standard input, output, +and error file descriptors. - This device driver writes via :c:func:`rtems_putc`. +This device driver reads via :ref:`InterfaceGetchark`. - The Termios framework is not used. There is no support to change device - settings, e.g. baud, stop bits, parity, etc. +This device driver writes via :ref:`InterfaceRtemsPutc`. - The +The Termios framework is not used. There is no support to change device +settings, e.g. baud, stop bits, parity, etc. - * :ref:`CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`, +The - * :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER`, and +* :ref:`CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`, - * :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER` +* ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER``, and - configuration options are mutually exclusive. +* :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER` + +configuration options are mutually exclusive. + +.. Generated from spec:/acfg/if/appl-needs-simple-task-console-driver + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER @@ -335,50 +469,61 @@ NOTES: CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER ------------------------------------------------------ -CONSTANT: - ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the Simple Task Console +Driver is initialized during system initialization. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: NOTES: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +This device driver is responsible for providing the :file:`/dev/console` +device file. This device is used to initialize the standard input, output, +and error file descriptors. -DESCRIPTION: - In case this configuration option is defined, then the Simple Task Console - Driver is initialized during system initialization. +This device driver reads via :ref:`InterfaceGetchark`. -NOTES: - This device driver is responsible for providing the :file:`/dev/console` - device file. This device is used to initialize the standard input, output, - and error file descriptors. +This device driver writes into a write buffer. The count of characters +written into the write buffer is returned. It might be less than the +requested count, in case the write buffer is full. The write is +non-blocking and may be called from interrupt context. A dedicated task +reads from the write buffer and outputs the characters via +:ref:`InterfaceRtemsPutc`. This task runs with the least important priority. +The write buffer size is 2047 characters and it is not configurable. - This device driver reads via :c:func:`getchark`. +Use ``fsync( STDOUT_FILENO )`` or ``fdatasync( STDOUT_FILENO )`` to drain the +write buffer. - This device driver writes into a write buffer. The count of characters - written into the write buffer is returned. It might be less than the - requested count, in case the write buffer is full. The write is - non-blocking and may be called from interrupt context. A dedicated task - reads from the write buffer and outputs the characters via - :c:func:`rtems_putc`. This task runs with the least important priority. - The write buffer size is 2047 characters and it is not configurable. +The Termios framework is not used. There is no support to change device +settings, e.g. baud, stop bits, parity, etc. - Use ``fsync(STDOUT_FILENO)`` or ``fdatasync(STDOUT_FILENO)`` to drain the - write buffer. +The - The Termios framework is not used. There is no support to change device - settings, e.g. baud, stop bits, parity, etc. +* :ref:`CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`, - The +* :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER`, and - * :ref:`CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`, +* ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER`` - * :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER`, and +configuration options are mutually exclusive. - * :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER` +.. Generated from spec:/acfg/if/appl-needs-stub-driver - configuration options are mutually exclusive. +.. raw:: latex + + \clearpage .. index:: CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER @@ -387,23 +532,34 @@ NOTES: CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER --------------------------------------- -CONSTANT: - ``CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DESCRIPTION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +In case this configuration option is defined, then the Stub Driver is +initialized during system initialization. -DESCRIPTION: - In case this configuration option is defined, then the Stub Driver is - initialized during system initialization. +.. rubric:: NOTES: -NOTES: - This device driver simply provides entry points that return successful and - is primarily a test fixture. It is supported by all BSPs. +This device driver simply provides entry points that return successful and +is primarily a test fixture. It is supported by all BSPs. + +.. Generated from spec:/acfg/if/appl-needs-timer-driver + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER @@ -412,33 +568,44 @@ NOTES: CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER ---------------------------------------- -CONSTANT: - ``CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DEFAULT CONFIGURATION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +If this configuration option is undefined, then the described feature is not +enabled. -DESCRIPTION: - In case this configuration option is defined, then the Benchmark Timer Driver is - initialized during system initialization. +.. rubric:: DESCRIPTION: -NOTES: - The Benchmark Timer Driver is intended for the benchmark tests of the RTEMS - Testsuite. Applications should not use this driver. +In case this configuration option is defined, then the Benchmark Timer Driver is +initialized during system initialization. - The application shall define exactly one of the following configuration options +.. rubric:: NOTES: - * :ref:`CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER`, +The Benchmark Timer Driver is intended for the benchmark tests of the RTEMS +Testsuite. Applications should not use this driver. - * :ref:`CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`, or +The application shall define exactly one of the following configuration options - * `CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER`, +* :ref:`CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER`, - otherwise a compile time error will occur. +* :ref:`CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`, or + +* ``CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER``, + +otherwise a compile time error will occur. + +.. Generated from spec:/acfg/if/appl-needs-watchdog-driver + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER @@ -447,26 +614,37 @@ NOTES: CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER ------------------------------------------- -CONSTANT: - ``CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is a boolean feature define. +In case this configuration option is defined, then the Watchdog Driver is +initialized during system initialization. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: NOTES: -DESCRIPTION: - In case this configuration option is defined, then the Watchdog Driver is - initialized during system initialization. +Most BSPs do not include support for a watchdog device driver. This is +because many boards do not include the required hardware. -NOTES: - Most BSPs do not include support for a watchdog device driver. This is - because many boards do not include the required hardware. +If this is defined and the BSP does not have this device driver, then the +user will get a link time error for an undefined symbol. - If this is defined and the BSP does not have this device driver, then the - user will get a link time error for an undefined symbol. +.. Generated from spec:/acfg/if/appl-needs-zero-driver + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER .. index:: /dev/zero @@ -476,22 +654,33 @@ NOTES: CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER --------------------------------------- -CONSTANT: - ``CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: -OPTION TYPE: - This configuration option is a boolean feature define. +If this configuration option is undefined, then the described feature is not +enabled. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DESCRIPTION: -DESCRIPTION: - In case this configuration option is defined, then the :file:`/dev/zero` - Driver is initialized during system initialization. +In case this configuration option is defined, then the :file:`/dev/zero` +Driver is initialized during system initialization. -NOTES: - This device driver is supported by all BSPs. +.. rubric:: NOTES: + +This device driver is supported by all BSPs. + +.. Generated from spec:/acfg/if/appl-prerequisite-drivers + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS @@ -500,30 +689,42 @@ NOTES: CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS ------------------------------------------ -CONSTANT: - ``CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is an initializer define. +This configuration option is an initializer define. -DEFAULT VALUE: - The default value is the empty list. +.. rubric:: DEFAULT VALUE: -VALUE CONSTRAINTS: - The value of this configuration option shall be a list of initializers for - structures of type :c:type:`rtems_driver_address_table`. +The default value is the empty list. -DESCRIPTION: - The value of this configuration option is used to initialize the Device - Driver Table. +.. rubric:: DESCRIPTION: -NOTES: - The value of this configuration option is placed after the entries defined by - :ref:`CONFIGURE_BSP_PREREQUISITE_DRIVERS` and before all other device driver - configuration options. +The value of this configuration option is used to initialize the Device +Driver Table. - See :ref:`CONFIGURE_APPLICATION_EXTRA_DRIVERS` for an alternative placement - of application device driver initializers. +.. rubric:: NOTES: + +The value of this configuration option is placed after the entries defined by +:c:macro:`CONFIGURE_BSP_PREREQUISITE_DRIVERS` and before all other device driver +configuration options. + +See :ref:`CONFIGURE_APPLICATION_EXTRA_DRIVERS` for an alternative placement +of application device driver initializers. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be a list of initializers for +structures of type :ref:`InterfaceRtemsDriverAddressTable`. + +.. Generated from spec:/acfg/if/ata-driver-task-priority + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_ATA_DRIVER_TASK_PRIORITY @@ -532,25 +733,77 @@ NOTES: CONFIGURE_ATA_DRIVER_TASK_PRIORITY ---------------------------------- -CONSTANT: - ``CONFIGURE_ATA_DRIVER_TASK_PRIORITY`` +.. rubric:: CONSTANT: + +``CONFIGURE_ATA_DRIVER_TASK_PRIORITY`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: -OPTION TYPE: - This configuration option is an integer define. +The default value is 140. -DEFAULT VALUE: - The default value is 140. +.. rubric:: DESCRIPTION: -VALUE CONSTRAINTS: - The value of this configuration option shall be a valid Classic API task - priority. The set of valid task priorities is scheduler-specific. +The value of this configuration option defines the ATA task priority. -DESCRIPTION: - The value of this configuration option defines the ATA task priority. +.. rubric:: NOTES: -NOTES: - This configuration option is only evaluated if the configuration option - :ref:`CONFIGURE_APPLICATION_NEEDS_ATA_DRIVER` is defined. +This configuration option is only evaluated if the configuration option +:ref:`CONFIGURE_APPLICATION_NEEDS_ATA_DRIVER` is defined. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be a valid Classic API task +priority. The set of valid task priorities depends on the scheduler +configuration. + +.. Generated from spec:/acfg/if/exception-to-signal-mapping + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_EXCEPTION_TO_SIGNAL_MAPPING + +.. _CONFIGURE_EXCEPTION_TO_SIGNAL_MAPPING: + +CONFIGURE_EXCEPTION_TO_SIGNAL_MAPPING +------------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_EXCEPTION_TO_SIGNAL_MAPPING`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the machine exception to +POSIX signal mapping is configured during system initialization. + +.. rubric:: NOTES: + +This device driver is responsible for setting up a mapping from machine +exceptions to POSIX signals so that applications may consume them and alter +task execution as necessary. + +This is especially useful for applications written in Ada or C++. + +.. Generated from spec:/acfg/if/max-drivers + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_MAXIMUM_DRIVERS @@ -559,36 +812,77 @@ NOTES: CONFIGURE_MAXIMUM_DRIVERS ------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_DRIVERS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_DRIVERS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +This is computed by default, and is set to the number of statically +configured device drivers configured using the following configuration +options: + +* :ref:`CONFIGURE_APPLICATION_EXTRA_DRIVERS` + +* :ref:`CONFIGURE_APPLICATION_NEEDS_ATA_DRIVER` + +* :ref:`CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER` + +* :ref:`CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER` + +* :ref:`CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER` + +* :ref:`CONFIGURE_APPLICATION_NEEDS_IDE_DRIVER` + +* :ref:`CONFIGURE_APPLICATION_NEEDS_LIBBLOCK` + +* :ref:`CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER` + +* :ref:`CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER` + +* :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER` + +* :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER` + +* :ref:`CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER` + +* :ref:`CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER` + +* :ref:`CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER` + +* :ref:`CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER` + +* :ref:`CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS` + +If the :ref:`CONFIGURE_DISABLE_BSP_SETTINGS` configuration option is not defined and +the :term:`BSP` provides +:c:macro:`CONFIGURE_BSP_PREREQUISITE_DRIVERS`, then the BSP-provided +prerequisite device drivers are also taken into account. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is an integer define. +The value of this configuration option defines the number of device drivers. -DEFAULT VALUE: - This is computed by default, and is set to the number of device drivers - configured using the ``CONFIGURE_APPLICATIONS_NEEDS_XXX_DRIVER`` - configuration options. +.. rubric:: NOTES: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +If the application will dynamically install device drivers, then the +configuration option value shall be larger than the number of statically +configured device drivers. - * It shall be less than or equal to ``SIZE_MAX``. +.. rubric:: CONSTRAINTS: - * It shall be greater than or equal than the number of statically configured - device drivers. +The following constraints apply to this configuration option: - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +* The value of the configuration option shall be less than or equal to + `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_. -DESCRIPTION: - The value of this configuration option defines the number of device drivers. +* The value of the configuration option shall be greater than or equal than the + number of statically configured device drivers. -NOTES: - If the application will dynamically install device drivers, then this - configuration parameter shall be larger than the number of statically - configured device drivers. Drivers configured using the - ``CONFIGURE_APPLICATIONS_NEEDS_XXX_DRIVER`` configuration options are - statically installed. +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. diff --git a/c-user/config/directives.rst b/c-user/config/directives.rst new file mode 100644 index 0000000..25351e9 --- /dev/null +++ b/c-user/config/directives.rst @@ -0,0 +1,1550 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2009, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2021 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. _ApplicationConfigurationInformationDirectives: + +Directives +========== + +This section details the directives of the Application Configuration +Information. A subsection is dedicated to each of this manager's directives and +lists the calling sequence, parameters, description, return values, and notes +of the directive. + +.. Generated from spec:/rtems/config/if/get-build-label + +.. raw:: latex + + \clearpage + +.. index:: rtems_get_build_label() + +.. _InterfaceRtemsGetBuildLabel: + +rtems_get_build_label() +----------------------- + +Gets the RTEMS build label. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + const char *rtems_get_build_label( void ); + +.. rubric:: DESCRIPTION: + +The build label is a user-provided string defined by the build configuration +through the ``RTEMS_BUILD_LABEL`` build option. The format of the string is +completely user-defined. + +.. rubric:: RETURN VALUES: + +Returns a pointer to the RTEMS build label. + +.. rubric:: NOTES: + +The build label can be used to distinguish test suite results obtained from +different build configurations. A use case is to record test results with +performance data to track performance regressions. For this a database of +performance limits is required. The build label and the target hash obtained +from :ref:`InterfaceRtemsGetTargetHash` can be used as a key to obtain +performance limits. + +.. 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/config/if/get-copyright-notice + +.. raw:: latex + + \clearpage + +.. index:: rtems_get_copyright_notice() + +.. _InterfaceRtemsGetCopyrightNotice: + +rtems_get_copyright_notice() +---------------------------- + +Gets the RTEMS copyright notice. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + const char *rtems_get_copyright_notice( void ); + +.. rubric:: RETURN VALUES: + +Returns a pointer to the RTEMS copyright notice. + +.. 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/config/if/get-target-hash + +.. raw:: latex + + \clearpage + +.. index:: rtems_get_target_hash() + +.. _InterfaceRtemsGetTargetHash: + +rtems_get_target_hash() +----------------------- + +Gets the RTEMS target hash. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + const char *rtems_get_target_hash( void ); + +.. rubric:: DESCRIPTION: + +The target hash is calculated from BSP-specific values which characterize a +target system. The target hash is encoded as a base64url string. The target +hash algorithm is unspecified. + +.. rubric:: RETURN VALUES: + +Returns a pointer to the RTEMS target hash. + +.. rubric:: NOTES: + +For example, the device tree, settings of the memory controller, processor and +bus frequencies, a serial number of a chip may be used to calculate the target +hash. + +The target hash can be used to distinguish test suite results obtained from +different target systems. See also :ref:`InterfaceRtemsGetBuildLabel`. + +.. 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/config/if/get-version-string + +.. raw:: latex + + \clearpage + +.. index:: rtems_get_version_string() + +.. _InterfaceRtemsGetVersionString: + +rtems_get_version_string() +-------------------------- + +Gets the RTEMS version string. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + const char *rtems_get_version_string( void ); + +.. rubric:: RETURN VALUES: + +Returns a pointer to the RTEMS version string. + +.. rubric:: NOTES: + +The version string has no particular format. Parsing the string may break +across RTEMS releases. + +.. 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/config/if/get-do-zero-of-workspace + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_do_zero_of_workspace() + +.. _InterfaceRtemsConfigurationGetDoZeroOfWorkspace: + +rtems_configuration_get_do_zero_of_workspace() +---------------------------------------------- + +Indicates if the RTEMS Workspace is configured to be zeroed during system +initialization for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + bool rtems_configuration_get_do_zero_of_workspace( void ); + +.. rubric:: RETURN VALUES: + +Returns true, if the RTEMS Workspace is configured to be zeroed during system +initialization for this application, otherwise false. + +.. rubric:: NOTES: + +The setting is defined by the :ref:`CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY` +application configuration option. + +.. 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/config/if/get-idle-task-stack-size + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_idle_task_stack_size() + +.. _InterfaceRtemsConfigurationGetIdleTaskStackSize: + +rtems_configuration_get_idle_task_stack_size() +---------------------------------------------- + +Gets the IDLE task stack size in bytes of this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + size_t rtems_configuration_get_idle_task_stack_size( void ); + +.. rubric:: RETURN VALUES: + +Returns the IDLE task stack size in bytes of this application. + +.. rubric:: NOTES: + +The IDLE task stack size is defined by the +:ref:`CONFIGURE_IDLE_TASK_STACK_SIZE` application configuration option. + +.. 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/config/if/get-idle-task + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_idle_task() + +.. _InterfaceRtemsConfigurationGetIdleTask: + +rtems_configuration_get_idle_task() +----------------------------------- + +Gets the IDLE task body of this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void *( * )( uintptr_t ) rtems_configuration_get_idle_task( void ); + +.. rubric:: RETURN VALUES: + +Returns the IDLE task body of this application. + +.. rubric:: NOTES: + +The IDLE task body is defined by the :ref:`CONFIGURE_IDLE_TASK_BODY` +application configuration option. + +.. 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/config/if/get-interrupt-stack-size + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_interrupt_stack_size() + +.. _InterfaceRtemsConfigurationGetInterruptStackSize: + +rtems_configuration_get_interrupt_stack_size() +---------------------------------------------- + +Gets the interrupt stack size in bytes of this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + size_t rtems_configuration_get_interrupt_stack_size( void ); + +.. rubric:: RETURN VALUES: + +Returns the interrupt stack size in bytes of this application. + +.. rubric:: NOTES: + +The interrupt stack size is defined by the +:ref:`CONFIGURE_INTERRUPT_STACK_SIZE` application configuration option. + +.. 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/config/if/get-maximum-barriers + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_maximum_barriers() + +.. _InterfaceRtemsConfigurationGetMaximumBarriers: + +rtems_configuration_get_maximum_barriers() +------------------------------------------ + +Gets the resource number of :ref:`RTEMSAPIClassicBarrier` objects configured +for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_maximum_barriers( void ); + +.. rubric:: RETURN VALUES: + +Returns the resource number of :ref:`RTEMSAPIClassicBarrier` objects configured +for this application. + +.. rubric:: NOTES: + +The resource number is defined by the :ref:`CONFIGURE_MAXIMUM_BARRIERS` +application configuration option. See also +:ref:`InterfaceRtemsResourceIsUnlimited` and +:ref:`InterfaceRtemsResourceMaximumPerAllocation`. + +.. 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/config/if/get-maximum-extensions + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_maximum_extensions() + +.. _InterfaceRtemsConfigurationGetMaximumExtensions: + +rtems_configuration_get_maximum_extensions() +-------------------------------------------- + +Gets the resource number of :ref:`RTEMSAPIClassicUserExt` objects configured +for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_maximum_extensions( void ); + +.. rubric:: RETURN VALUES: + +Returns the resource number of :ref:`RTEMSAPIClassicUserExt` objects configured +for this application. + +.. rubric:: NOTES: + +The resource number is defined by the :ref:`CONFIGURE_MAXIMUM_USER_EXTENSIONS` +application configuration option. See also +:ref:`InterfaceRtemsResourceIsUnlimited` and +:ref:`InterfaceRtemsResourceMaximumPerAllocation`. + +.. 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/config/if/get-maximum-message-queues + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_maximum_message_queues() + +.. _InterfaceRtemsConfigurationGetMaximumMessageQueues: + +rtems_configuration_get_maximum_message_queues() +------------------------------------------------ + +Gets the resource number of :ref:`RTEMSAPIClassicMessage` objects configured +for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_maximum_message_queues( void ); + +.. rubric:: RETURN VALUES: + +Returns the resource number of :ref:`RTEMSAPIClassicMessage` objects configured +for this application. + +.. rubric:: NOTES: + +The resource number is defined by the :ref:`CONFIGURE_MAXIMUM_MESSAGE_QUEUES` +application configuration option. See also +:ref:`InterfaceRtemsResourceIsUnlimited` and +:ref:`InterfaceRtemsResourceMaximumPerAllocation`. + +.. 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/config/if/get-maximum-partitions + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_maximum_partitions() + +.. _InterfaceRtemsConfigurationGetMaximumPartitions: + +rtems_configuration_get_maximum_partitions() +-------------------------------------------- + +Gets the resource number of :ref:`RTEMSAPIClassicPart` objects configured for +this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_maximum_partitions( void ); + +.. rubric:: RETURN VALUES: + +Returns the resource number of :ref:`RTEMSAPIClassicPart` objects configured +for this application. + +.. rubric:: NOTES: + +The resource number is defined by the :ref:`CONFIGURE_MAXIMUM_PARTITIONS` +application configuration option. See also +:ref:`InterfaceRtemsResourceIsUnlimited` and +:ref:`InterfaceRtemsResourceMaximumPerAllocation`. + +.. 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/config/if/get-maximum-periods + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_maximum_periods() + +.. _InterfaceRtemsConfigurationGetMaximumPeriods: + +rtems_configuration_get_maximum_periods() +----------------------------------------- + +Gets the resource number of :ref:`RTEMSAPIClassicRatemon` objects configured +for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_maximum_periods( void ); + +.. rubric:: RETURN VALUES: + +Returns the resource number of :ref:`RTEMSAPIClassicRatemon` objects configured +for this application. + +.. rubric:: NOTES: + +The resource number is defined by the :ref:`CONFIGURE_MAXIMUM_PERIODS` +application configuration option. See also +:ref:`InterfaceRtemsResourceIsUnlimited` and +:ref:`InterfaceRtemsResourceMaximumPerAllocation`. + +.. 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/config/if/get-maximum-ports + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_maximum_ports() + +.. _InterfaceRtemsConfigurationGetMaximumPorts: + +rtems_configuration_get_maximum_ports() +--------------------------------------- + +Gets the resource number of :ref:`RTEMSAPIClassicDPMem` objects configured for +this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_maximum_ports( void ); + +.. rubric:: RETURN VALUES: + +Returns the resource number of :ref:`RTEMSAPIClassicDPMem` objects configured +for this application. + +.. rubric:: NOTES: + +The resource number is defined by the :ref:`CONFIGURE_MAXIMUM_PORTS` +application configuration option. See also +:ref:`InterfaceRtemsResourceIsUnlimited` and +:ref:`InterfaceRtemsResourceMaximumPerAllocation`. + +.. 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/config/if/get-maximum-processors + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_maximum_processors() + +.. _InterfaceRtemsConfigurationGetMaximumProcessors: + +rtems_configuration_get_maximum_processors() +-------------------------------------------- + +Gets the maximum number of processors configured for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_maximum_processors( void ); + +.. rubric:: RETURN VALUES: + +Returns the maximum number of processors configured for this application. + +.. rubric:: NOTES: + +The actual number of processors available to the application is returned by +:ref:`InterfaceRtemsSchedulerGetProcessorMaximum` which less than or equal to +the configured maximum number of processors +(:ref:`CONFIGURE_MAXIMUM_PROCESSORS`). + +In uniprocessor configurations, this macro is a compile time constant which +evaluates to one. + +.. 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/config/if/get-maximum-regions + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_maximum_regions() + +.. _InterfaceRtemsConfigurationGetMaximumRegions: + +rtems_configuration_get_maximum_regions() +----------------------------------------- + +Gets the resource number of :ref:`RTEMSAPIClassicRegion` objects configured for +this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_maximum_regions( void ); + +.. rubric:: RETURN VALUES: + +Returns the resource number of :ref:`RTEMSAPIClassicRegion` objects configured +for this application. + +.. rubric:: NOTES: + +The resource number is defined by the :ref:`CONFIGURE_MAXIMUM_REGIONS` +application configuration option. See also +:ref:`InterfaceRtemsResourceIsUnlimited` and +:ref:`InterfaceRtemsResourceMaximumPerAllocation`. + +.. 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/config/if/get-maximum-semaphores + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_maximum_semaphores() + +.. _InterfaceRtemsConfigurationGetMaximumSemaphores: + +rtems_configuration_get_maximum_semaphores() +-------------------------------------------- + +Gets the resource number of :ref:`RTEMSAPIClassicSem` objects configured for +this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_maximum_semaphores( void ); + +.. rubric:: RETURN VALUES: + +Returns the resource number of :ref:`RTEMSAPIClassicSem` objects configured for +this application. + +.. rubric:: NOTES: + +The resource number is defined by the :ref:`CONFIGURE_MAXIMUM_SEMAPHORES` +application configuration option. See also +:ref:`InterfaceRtemsResourceIsUnlimited` and +:ref:`InterfaceRtemsResourceMaximumPerAllocation`. + +.. 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/config/if/get-maximum-tasks + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_maximum_tasks() + +.. _InterfaceRtemsConfigurationGetMaximumTasks: + +rtems_configuration_get_maximum_tasks() +--------------------------------------- + +Gets the resource number of :ref:`RTEMSAPIClassicTasks` objects configured for +this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_maximum_tasks( void ); + +.. rubric:: RETURN VALUES: + +Returns the resource number of :ref:`RTEMSAPIClassicTasks` objects configured +for this application. + +.. rubric:: NOTES: + +The resource number is defined by the :ref:`CONFIGURE_MAXIMUM_TASKS` +application configuration option. See also +:ref:`InterfaceRtemsResourceIsUnlimited` and +:ref:`InterfaceRtemsResourceMaximumPerAllocation`. + +.. 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/config/if/get-maximum-timers + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_maximum_timers() + +.. _InterfaceRtemsConfigurationGetMaximumTimers: + +rtems_configuration_get_maximum_timers() +---------------------------------------- + +Gets the resource number of :ref:`RTEMSAPIClassicTimer` objects configured for +this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_maximum_timers( void ); + +.. rubric:: RETURN VALUES: + +Returns the resource number of :ref:`RTEMSAPIClassicTimer` objects configured +for this application. + +.. rubric:: NOTES: + +The resource number is defined by the :ref:`CONFIGURE_MAXIMUM_TIMERS` +application configuration option. See also +:ref:`InterfaceRtemsResourceIsUnlimited` and +:ref:`InterfaceRtemsResourceMaximumPerAllocation`. + +.. 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/config/if/get-microseconds-per-tick + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_microseconds_per_tick() + +.. _InterfaceRtemsConfigurationGetMicrosecondsPerTick: + +rtems_configuration_get_microseconds_per_tick() +----------------------------------------------- + +Gets the number of microseconds per clock tick configured for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_microseconds_per_tick( void ); + +.. rubric:: RETURN VALUES: + +Returns the number of microseconds per clock tick configured for this +application. + +.. rubric:: NOTES: + +The number of microseconds per :term:`clock tick` is defined by the +:ref:`CONFIGURE_MICROSECONDS_PER_TICK` application configuration option. + +.. 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/config/if/get-milliseconds-per-tick + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_milliseconds_per_tick() + +.. _InterfaceRtemsConfigurationGetMillisecondsPerTick: + +rtems_configuration_get_milliseconds_per_tick() +----------------------------------------------- + +Gets the number of milliseconds per clock tick configured for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_milliseconds_per_tick( void ); + +.. rubric:: RETURN VALUES: + +Returns the number of milliseconds per clock tick configured for this +application. + +.. rubric:: NOTES: + +The number of milliseconds per :term:`clock tick` is defined by the +:ref:`CONFIGURE_MICROSECONDS_PER_TICK` application configuration option. + +.. 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/config/if/get-nanoseconds-per-tick + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_nanoseconds_per_tick() + +.. _InterfaceRtemsConfigurationGetNanosecondsPerTick: + +rtems_configuration_get_nanoseconds_per_tick() +---------------------------------------------- + +Gets the number of microseconds per clock tick configured for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_nanoseconds_per_tick( void ); + +.. rubric:: RETURN VALUES: + +Returns the number of microseconds per clock tick configured for this +application. + +.. rubric:: NOTES: + +The number of nanoseconds per :term:`clock tick` is defined by the +:ref:`CONFIGURE_MICROSECONDS_PER_TICK` application configuration option. + +.. 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/config/if/get-number-of-initial-extensions + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_number_of_initial_extensions() + +.. _InterfaceRtemsConfigurationGetNumberOfInitialExtensions: + +rtems_configuration_get_number_of_initial_extensions() +------------------------------------------------------ + +Gets the number of initial extensions configured for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_number_of_initial_extensions( void ); + +.. rubric:: RETURN VALUES: + +Returns the number of initial extensions configured for this application. + +.. rubric:: NOTES: + +The number of initial extensions is defined by the +:ref:`CONFIGURE_INITIAL_EXTENSIONS` application configuration option and +related options. + +.. 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/config/if/get-stack-allocate-for-idle-hook + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_stack_allocate_for_idle_hook() + +.. _InterfaceRtemsConfigurationGetStackAllocateForIdleHook: + +rtems_configuration_get_stack_allocate_for_idle_hook() +------------------------------------------------------ + +Gets the task stack allocator allocate hook used to allocate the stack of each +:term:`IDLE task` configured for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void *( * )( uint32_t, size_t * ) + rtems_configuration_get_stack_allocate_for_idle_hook( void ); + +.. rubric:: RETURN VALUES: + +Returns the task stack allocator allocate hook used to allocate the stack of +each :term:`IDLE task` configured for this application. + +.. rubric:: NOTES: + +The task stack allocator allocate hook for idle tasks is defined by the +:ref:`CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE` application configuration +option. + +.. 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/config/if/get-stack-allocate-hook + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_stack_allocate_hook() + +.. _InterfaceRtemsConfigurationGetStackAllocateHook: + +rtems_configuration_get_stack_allocate_hook() +--------------------------------------------- + +Gets the task stack allocator allocate hook configured for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void *( * )( size_t ) rtems_configuration_get_stack_allocate_hook( void ); + +.. rubric:: RETURN VALUES: + +Returns the task stack allocator allocate hook configured for this application. + +.. rubric:: NOTES: + +The task stack allocator allocate hook is defined by the +:ref:`CONFIGURE_TASK_STACK_ALLOCATOR` application configuration option. + +.. 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/config/if/get-stack-allocate-init-hook + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_stack_allocate_init_hook() + +.. _InterfaceRtemsConfigurationGetStackAllocateInitHook: + +rtems_configuration_get_stack_allocate_init_hook() +-------------------------------------------------- + +Gets the task stack allocator initialization hook configured for this +application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void ( * )( size_t ) rtems_configuration_get_stack_allocate_init_hook( void ); + +.. rubric:: RETURN VALUES: + +Returns the task stack allocator initialization hook configured for this +application. + +.. rubric:: NOTES: + +The task stack allocator initialization hook is defined by the +:ref:`CONFIGURE_TASK_STACK_ALLOCATOR_INIT` application configuration option. + +.. 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/config/if/get-stack-allocator-avoids-work-space + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_stack_allocator_avoids_work_space() + +.. _InterfaceRtemsConfigurationGetStackAllocatorAvoidsWorkSpace: + +rtems_configuration_get_stack_allocator_avoids_work_space() +----------------------------------------------------------- + +Indicates if the task stack allocator is configured to avoid the RTEMS +Workspace for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + bool rtems_configuration_get_stack_allocator_avoids_work_space( void ); + +.. rubric:: RETURN VALUES: + +Returns true, if the task stack allocator is configured to avoid the RTEMS +Workspace for this application, otherwise false. + +.. rubric:: NOTES: + +The setting is defined by the +:ref:`CONFIGURE_TASK_STACK_ALLOCATOR_AVOIDS_WORK_SPACE` application +configuration option. + +.. 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/config/if/get-stack-free-hook + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_stack_free_hook() + +.. _InterfaceRtemsConfigurationGetStackFreeHook: + +rtems_configuration_get_stack_free_hook() +----------------------------------------- + +Gets the task stack allocator free hook configured for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void ( * )( void * ) rtems_configuration_get_stack_free_hook( void ); + +.. rubric:: RETURN VALUES: + +Returns the task stack allocator free hook configured for this application. + +.. rubric:: NOTES: + +The task stack allocator free hook is defined by the +:ref:`CONFIGURE_TASK_STACK_DEALLOCATOR` application configuration option. + +.. 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/config/if/get-stack-space-size + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_stack_space_size() + +.. _InterfaceRtemsConfigurationGetStackSpaceSize: + +rtems_configuration_get_stack_space_size() +------------------------------------------ + +Gets the configured size in bytes of the memory space used to allocate thread +stacks for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uintptr_t rtems_configuration_get_stack_space_size( void ); + +.. rubric:: RETURN VALUES: + +Returns the configured size in bytes of the memory space used to allocate +thread stacks for this application. + +.. rubric:: NOTES: + +The size takes only threads and tasks into account with are known at the +application configuration time. + +.. 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/config/if/get-ticks-per-timeslice + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_ticks_per_timeslice() + +.. _InterfaceRtemsConfigurationGetTicksPerTimeslice: + +rtems_configuration_get_ticks_per_timeslice() +--------------------------------------------- + +Gets the clock ticks per timeslice configured for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_ticks_per_timeslice( void ); + +.. rubric:: RETURN VALUES: + +Returns the clock ticks per timeslice configured for this application. + +.. rubric:: NOTES: + +The :term:`clock ticks <clock tick>` per timeslice is defined by the +:ref:`CONFIGURE_TICKS_PER_TIMESLICE` application configuration option. + +.. 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/config/if/get-unified-work-area + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_unified_work_area() + +.. _InterfaceRtemsConfigurationGetUnifiedWorkArea: + +rtems_configuration_get_unified_work_area() +------------------------------------------- + +Indicates if the RTEMS Workspace and C Program Heap are configured to be +unified for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + bool rtems_configuration_get_unified_work_area( void ); + +.. rubric:: RETURN VALUES: + +Returns true, if the RTEMS Workspace and C Program Heap are configured to be +unified for this application, otherwise false. + +.. rubric:: NOTES: + +The setting is defined by the :ref:`CONFIGURE_UNIFIED_WORK_AREAS` application +configuration option. + +.. 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/config/if/get-user-extension-table + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_user_extension_table() + +.. _InterfaceRtemsConfigurationGetUserExtensionTable: + +rtems_configuration_get_user_extension_table() +---------------------------------------------- + +Gets the initial extensions table configured for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + const rtems_extensions_table *rtems_configuration_get_user_extension_table( + void + ); + +.. rubric:: RETURN VALUES: + +Returns a pointer to the initial extensions table configured for this +application. + +.. 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/config/if/get-user-multiprocessing-table + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_user_multiprocessing_table() + +.. _InterfaceRtemsConfigurationGetUserMultiprocessingTable: + +rtems_configuration_get_user_multiprocessing_table() +---------------------------------------------------- + +Gets the MPCI configuration table configured for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + const MPCI_Configuration *rtems_configuration_get_user_multiprocessing_table( + void + ); + +.. rubric:: RETURN VALUES: + +Returns a pointer to the MPCI configuration table configured for this +application. + +.. 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/config/if/get-work-space-size + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_work_space_size() + +.. _InterfaceRtemsConfigurationGetWorkSpaceSize: + +rtems_configuration_get_work_space_size() +----------------------------------------- + +Gets the RTEMS Workspace size in bytes configured for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uintptr_t rtems_configuration_get_work_space_size( void ); + +.. rubric:: RETURN VALUES: + +Returns the RTEMS Workspace size in bytes configured for this application. + +.. 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/config/if/get-api-configuration + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_rtems_api_configuration() + +.. _InterfaceRtemsConfigurationGetRtemsApiConfiguration: + +rtems_configuration_get_rtems_api_configuration() +------------------------------------------------- + +Gets the Classic API Configuration Table of this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + const rtems_api_configuration_table * + rtems_configuration_get_rtems_api_configuration( void ); + +.. rubric:: RETURN VALUES: + +Returns a pointer to the Classic API Configuration Table of this application. + +.. 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/config/if/resource-is-unlimited + +.. raw:: latex + + \clearpage + +.. index:: rtems_resource_is_unlimited() + +.. _InterfaceRtemsResourceIsUnlimited: + +rtems_resource_is_unlimited() +----------------------------- + +Indicates if the resource is unlimited. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + bool rtems_resource_is_unlimited( uint32_t resource ); + +.. rubric:: PARAMETERS: + +``resource`` + This parameter is the resource number. + +.. rubric:: RETURN VALUES: + +Returns true, if the resource is unlimited, otherwise false. + +.. 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/config/if/resource-maximum-per-allocation + +.. raw:: latex + + \clearpage + +.. index:: rtems_resource_maximum_per_allocation() + +.. _InterfaceRtemsResourceMaximumPerAllocation: + +rtems_resource_maximum_per_allocation() +--------------------------------------- + +Gets the maximum number per allocation of a resource number. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_resource_maximum_per_allocation( uint32_t resource ); + +.. rubric:: PARAMETERS: + +``resource`` + This parameter is the resource number. + +.. rubric:: RETURN VALUES: + +Returns the maximum number per allocation of a resource number. + +.. 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/config/if/resource-unlimited + +.. raw:: latex + + \clearpage + +.. index:: rtems_resource_unlimited() + +.. _InterfaceRtemsResourceUnlimited: + +rtems_resource_unlimited() +-------------------------- + +Augments the resource number so that it indicates an unlimited resource. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_resource_unlimited( uint32_t resource ); + +.. rubric:: PARAMETERS: + +``resource`` + This parameter is the resource number to augment. + +.. rubric:: RETURN VALUES: + +Returns the resource number augmented to indicate an unlimited resource. + +.. rubric:: NOTES: + +This directive should be used to configure unlimited objects, see +:ref:`ConfigUnlimitedObjects`. + +.. 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. diff --git a/c-user/config/event-record.rst b/c-user/config/event-record.rst index 6c93a3a..1e5c52a 100644 --- a/c-user/config/event-record.rst +++ b/c-user/config/event-record.rst @@ -1,12 +1,35 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2019, 2020 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2019, 2022 embedded brains GmbH & Co. KG + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/acfg/if/group-eventrecord Event Recording Configuration ============================= This section describes configuration options related to the event recording. +.. Generated from spec:/acfg/if/record-extensions-enabled + +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_RECORD_EXTENSIONS_ENABLED .. _CONFIGURE_RECORD_EXTENSIONS_ENABLED: @@ -14,28 +37,39 @@ This section describes configuration options related to the event recording. CONFIGURE_RECORD_EXTENSIONS_ENABLED ----------------------------------- -CONSTANT: - ``CONFIGURE_RECORD_EXTENSIONS_ENABLED`` +.. rubric:: CONSTANT: + +``CONFIGURE_RECORD_EXTENSIONS_ENABLED`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: -OPTION TYPE: - This configuration option is a boolean feature define. +If this configuration option is undefined, then the described feature is not +enabled. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DESCRIPTION: -DESCRIPTION: - In case +In case - * this configuration option is defined +* this configuration option is defined - * and :ref:`CONFIGURE_RECORD_PER_PROCESSOR_ITEMS` is properly defined, +* and :ref:`CONFIGURE_RECORD_PER_PROCESSOR_ITEMS` is properly defined, - then the event record extensions are enabled. +then the event record extensions are enabled. -NOTES: - The record extensions capture thread create, start, restart, delete, switch, - begin, exitted and terminate events. +.. rubric:: NOTES: + +The record extensions capture thread create, start, restart, delete, switch, +begin, exitted and terminate events. + +.. Generated from spec:/acfg/if/record-fatal-dump-base64 + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_RECORD_FATAL_DUMP_BASE64 @@ -44,30 +78,41 @@ NOTES: CONFIGURE_RECORD_FATAL_DUMP_BASE64 ---------------------------------- -CONSTANT: - ``CONFIGURE_RECORD_FATAL_DUMP_BASE64`` +.. rubric:: CONSTANT: + +``CONFIGURE_RECORD_FATAL_DUMP_BASE64`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DEFAULT CONFIGURATION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +If this configuration option is undefined, then the described feature is not +enabled. -DESCRIPTION: - In case +.. rubric:: DESCRIPTION: - * this configuration option is defined +In case - * and :ref:`CONFIGURE_RECORD_PER_PROCESSOR_ITEMS` is properly defined, +* this configuration option is defined - * and :ref:`CONFIGURE_RECORD_FATAL_DUMP_BASE64_ZLIB` is undefined, +* and :ref:`CONFIGURE_RECORD_PER_PROCESSOR_ITEMS` is properly defined, - then the event records are dumped in Base64 encoding in a fatal error - extension (see :ref:`Terminate`). +* and :ref:`CONFIGURE_RECORD_FATAL_DUMP_BASE64_ZLIB` is undefined, -NOTES: - This extension can be used to produce crash dumps. +then the event records are dumped in Base64 encoding in a fatal error +extension (see :ref:`Terminate`). + +.. rubric:: NOTES: + +This extension can be used to produce crash dumps. + +.. Generated from spec:/acfg/if/record-fatal-dump-base64-zlib + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_RECORD_FATAL_DUMP_BASE64_ZLIB @@ -76,29 +121,81 @@ NOTES: CONFIGURE_RECORD_FATAL_DUMP_BASE64_ZLIB --------------------------------------- -CONSTANT: - ``CONFIGURE_RECORD_FATAL_DUMP_BASE64_ZLIB`` +.. rubric:: CONSTANT: + +``CONFIGURE_RECORD_FATAL_DUMP_BASE64_ZLIB`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case + +* this configuration option is defined -OPTION TYPE: - This configuration option is a boolean feature define. +* and :ref:`CONFIGURE_RECORD_PER_PROCESSOR_ITEMS` is properly defined, -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +then the event records are compressed by zlib and dumped in Base64 encoding +in a fatal error extension (see :ref:`Terminate`). -DESCRIPTION: - In case +.. rubric:: NOTES: - * this configuration option is defined +The zlib compression needs about 512KiB of RAM. This extension can be used +to produce crash dumps. - * and :ref:`CONFIGURE_RECORD_PER_PROCESSOR_ITEMS` is properly defined, +.. Generated from spec:/acfg/if/record-interrupts-enabled - then the event records are compressed by zlib and dumped in Base64 encoding - in a fatal error extension (see :ref:`Terminate`). +.. raw:: latex -NOTES: - The zlib compression needs about 512KiB of RAM. This extension can be used - to produce crash dumps. + \clearpage + +.. index:: CONFIGURE_RECORD_INTERRUPTS_ENABLED + +.. _CONFIGURE_RECORD_INTERRUPTS_ENABLED: + +CONFIGURE_RECORD_INTERRUPTS_ENABLED +----------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_RECORD_INTERRUPTS_ENABLED`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case + +* this configuration option is defined + +* and :ref:`CONFIGURE_RECORD_PER_PROCESSOR_ITEMS` is properly defined, + +then the interrupt event recording is enabled. + +.. rubric:: NOTES: + +The interrupt event recording generates interrupt entry and exit events when +interrupt entries are dispatched. + +.. Generated from spec:/acfg/if/record-per-processor-items + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_RECORD_PER_PROCESSOR_ITEMS @@ -107,34 +204,40 @@ NOTES: CONFIGURE_RECORD_PER_PROCESSOR_ITEMS ------------------------------------ -CONSTANT: - ``CONFIGURE_RECORD_PER_PROCESSOR_ITEMS`` +.. rubric:: CONSTANT: + +``CONFIGURE_RECORD_PER_PROCESSOR_ITEMS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is an integer define. +The value of this configuration option defines the event record item count +per processor. -DEFAULT VALUE: - The default value is 0. +.. rubric:: NOTES: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The event record buffers are statically allocated for each configured +processor (:ref:`CONFIGURE_MAXIMUM_PROCESSORS`). If the value of this +configuration option is zero, then nothing is allocated. - * It shall be greater than or equal to 16. +.. rubric:: CONSTRAINTS: - * It shall be less than or equal to ``SIZE_MAX``. +The following constraints apply to this configuration option: - * It shall be a power of two. +* The value of the configuration option shall be greater than or equal to 16. - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +* The value of the configuration option shall be less than or equal to + `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_. -DESCRIPTION: - The value of this configuration option defines the event record item count - per processor. +* The value of the configuration option shall be a power of two. -NOTES: - The event record buffers are statically allocated for each configured - processor (:ref:`CONFIGURE_MAXIMUM_PROCESSORS`). If the value of this - configuration option is zero, then nothing is allocated. +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. diff --git a/c-user/config/face-technical-standard.rst b/c-user/config/face-technical-standard.rst new file mode 100644 index 0000000..8772773 --- /dev/null +++ b/c-user/config/face-technical-standard.rst @@ -0,0 +1,76 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2022 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/acfg/if/group-face + +FACE Technical Standard Related Configuration +============================================= + +This section describes configuration options related to adapting +RTEMS behavior to be aligned with the FACE Technical Standard. +The FACE Technical Standard is a product of the FACE Consortium +which operates under the Open Group. The FACE Consortium was founded +by avionics organizations to improve the portability of cockpit software +across various platforms. It addresses technical and business concerns. + +Most important from an RTEMS perspective, the FACE Technical Standard +defines four POSIX profiles: Security, Safety Base, Safety Extended, and +the General Purpose Profile. Each has an increasingly larger subset of +POSIX APIs. In the Security and Safety profiles, ARINC 653 is required. +It is optional in the General Purpose Profile. + +The RTEMS Project has been tracking alignment with the FACE POSIX profiles +and they are included in the "RTEMS POSIX 1003.1 Compliance Guide." + +.. Generated from spec:/acfg/if/posix-timer-face-behavior + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_POSIX_TIMERS_FACE_BEHAVIOR + +.. _CONFIGURE_POSIX_TIMERS_FACE_BEHAVIOR: + +CONFIGURE_POSIX_TIMERS_FACE_BEHAVIOR +------------------------------------ + +.. rubric:: CONSTANT: + +``CONFIGURE_POSIX_TIMERS_FACE_BEHAVIOR`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +If this configuration option is defined, then POSIX timers may not be created +to use the :term:`CLOCK_REALTIME`. Per POSIX, this is allowed +behavior but per the FACE Technical Standard, it is not. Using POSIX timers +based on CLOCK_REALTIME (e.g., time of day) is unsafe for real-time safety +systems as setting CLOCK_REALTIME will perturb any active timers. + +If this option is not defined, POSIX timers may be created to use the +CLOCK_REALTIME in compliance with the POSIX specification. diff --git a/c-user/config/filesystem.rst b/c-user/config/filesystem.rst index ef37307..c565f4c 100644 --- a/c-user/config/filesystem.rst +++ b/c-user/config/filesystem.rst @@ -1,7 +1,24 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2023 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/acfg/if/group-filesystem Filesystem Configuration ======================== @@ -48,6 +65,12 @@ configuration options: * :ref:`CONFIGURE_IMFS_ENABLE_MKFIFO` +.. Generated from spec:/acfg/if/appl-disable-filesystem + +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_APPLICATION_DISABLE_FILESYSTEM .. _CONFIGURE_APPLICATION_DISABLE_FILESYSTEM: @@ -55,25 +78,36 @@ configuration options: CONFIGURE_APPLICATION_DISABLE_FILESYSTEM ---------------------------------------- -CONSTANT: - ``CONFIGURE_APPLICATION_DISABLE_FILESYSTEM`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_DISABLE_FILESYSTEM`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: -OPTION TYPE: - This configuration option is a boolean feature define. +If this configuration option is undefined, then a base filesystem and the +configured filesystems are initialized during system initialization. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then a base filesystem and the - configured filesystems are initialized during system initialization. +.. rubric:: DESCRIPTION: -DESCRIPTION: - In case this configuration option is defined, then **no** base filesystem is - initialized during system initialization and **no** filesystems are - configured. +In case this configuration option is defined, then **no base filesystem** is +initialized during system initialization and **no filesystems** are +configured. -NOTES: - Filesystems shall be initialized to support file descriptor based device - drivers and basic input/output functions such as :c:func:`printf`. - Filesystems can be disabled to reduce the memory footprint of an application. +.. rubric:: NOTES: + +Filesystems shall be initialized to support file descriptor based device +drivers and basic input/output functions such as :c:func:`printf`. +Filesystems can be disabled to reduce the memory footprint of an application. + +.. Generated from spec:/acfg/if/filesystem-all + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_FILESYSTEM_ALL @@ -82,36 +116,43 @@ NOTES: CONFIGURE_FILESYSTEM_ALL ------------------------ -CONSTANT: - ``CONFIGURE_FILESYSTEM_ALL`` +.. rubric:: CONSTANT: + +``CONFIGURE_FILESYSTEM_ALL`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then the following - configuration options will be defined as well +If this configuration option is undefined, then the described feature is not +enabled. - - :ref:`CONFIGURE_FILESYSTEM_DOSFS`, +.. rubric:: DESCRIPTION: - - :ref:`CONFIGURE_FILESYSTEM_FTPFS`, +In case this configuration option is defined, then the following +configuration options will be defined as well - - :ref:`CONFIGURE_FILESYSTEM_IMFS`, +* :ref:`CONFIGURE_FILESYSTEM_DOSFS`, - - :ref:`CONFIGURE_FILESYSTEM_JFFS2`, +* :ref:`CONFIGURE_FILESYSTEM_FTPFS`, - - :ref:`CONFIGURE_FILESYSTEM_NFS`, +* :ref:`CONFIGURE_FILESYSTEM_IMFS`, - - :ref:`CONFIGURE_FILESYSTEM_RFS`, and +* :ref:`CONFIGURE_FILESYSTEM_JFFS2`, - - :ref:`CONFIGURE_FILESYSTEM_TFTPFS`. +* :ref:`CONFIGURE_FILESYSTEM_NFS`, -NOTES: - None. +* :ref:`CONFIGURE_FILESYSTEM_RFS`, and + +* :ref:`CONFIGURE_FILESYSTEM_TFTPFS`. + +.. Generated from spec:/acfg/if/filesystem-dosfs + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_FILESYSTEM_DOSFS @@ -120,24 +161,35 @@ NOTES: CONFIGURE_FILESYSTEM_DOSFS -------------------------- -CONSTANT: - ``CONFIGURE_FILESYSTEM_DOSFS`` +.. rubric:: CONSTANT: + +``CONFIGURE_FILESYSTEM_DOSFS`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the DOS (FAT) filesystem +is registered, so that instances of this filesystem can be mounted by the +application. + +.. rubric:: NOTES: -OPTION TYPE: - This configuration option is a boolean feature define. +This filesystem requires a Block Device Cache configuration, see +:ref:`CONFIGURE_APPLICATION_NEEDS_LIBBLOCK`. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. Generated from spec:/acfg/if/filesystem-ftpfs -DESCRIPTION: - In case this configuration option is defined, then the DOS (FAT) filesystem - is registered, so that instances of this filesystem can be mounted by the - application. +.. raw:: latex -NOTES: - This filesystem requires a Block Device Cache configuration, see - :ref:`CONFIGURE_APPLICATION_NEEDS_LIBBLOCK`. + \clearpage .. index:: CONFIGURE_FILESYSTEM_FTPFS @@ -146,23 +198,30 @@ NOTES: CONFIGURE_FILESYSTEM_FTPFS -------------------------- -CONSTANT: - ``CONFIGURE_FILESYSTEM_FTPFS`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is a boolean feature define. +``CONFIGURE_FILESYSTEM_FTPFS`` -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: OPTION TYPE: -DESCRIPTION: - In case this configuration option is defined, then the FTP filesystem (FTP - client) is registered, so that instances of this filesystem - can be mounted by the application. +This configuration option is a boolean feature define. -NOTES: - None. +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the FTP filesystem (FTP +client) is registered, so that instances of this filesystem +can be mounted by the application. + +.. Generated from spec:/acfg/if/filesystem-imfs + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_FILESYSTEM_IMFS @@ -171,25 +230,36 @@ NOTES: CONFIGURE_FILESYSTEM_IMFS ------------------------- -CONSTANT: - ``CONFIGURE_FILESYSTEM_IMFS`` +.. rubric:: CONSTANT: + +``CONFIGURE_FILESYSTEM_IMFS`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is a boolean feature define. +In case this configuration option is defined, then the In-Memory Filesystem +(IMFS) is registered, so that instances of this filesystem can be mounted by +the application. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: NOTES: -DESCRIPTION: - In case this configuration option is defined, then the In-Memory Filesystem - (IMFS) is registered, so that instances of this filesystem can be mounted by - the application. +Applications will rarely need this configuration option. This configuration +option is intended for test programs. You do not need to define this +configuration option for the base filesystem (also known as root filesystem). -NOTES: - Applications will rarely need this configuration option. This configuration - option is intended for test programs. You do not need to define this - configuration option for the base filesystem (also known as root filesystem). +.. Generated from spec:/acfg/if/filesystem-jffs2 + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_FILESYSTEM_JFFS2 @@ -198,23 +268,30 @@ NOTES: CONFIGURE_FILESYSTEM_JFFS2 -------------------------- -CONSTANT: - ``CONFIGURE_FILESYSTEM_JFFS2`` +.. rubric:: CONSTANT: + +``CONFIGURE_FILESYSTEM_JFFS2`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: -OPTION TYPE: - This configuration option is a boolean feature define. +If this configuration option is undefined, then the described feature is not +enabled. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DESCRIPTION: -DESCRIPTION: - In case this configuration option is defined, then the JFFS2 filesystem - is registered, so that instances of this filesystem can be mounted by the - application. +In case this configuration option is defined, then the JFFS2 filesystem +is registered, so that instances of this filesystem can be mounted by the +application. -NOTES: - None. +.. Generated from spec:/acfg/if/filesystem-nfs + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_FILESYSTEM_NFS @@ -223,23 +300,30 @@ NOTES: CONFIGURE_FILESYSTEM_NFS ------------------------ -CONSTANT: - ``CONFIGURE_FILESYSTEM_NFS`` +.. rubric:: CONSTANT: + +``CONFIGURE_FILESYSTEM_NFS`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: -OPTION TYPE: - This configuration option is a boolean feature define. +If this configuration option is undefined, then the described feature is not +enabled. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DESCRIPTION: -DESCRIPTION: - In case this configuration option is defined, then the Network Filesystem - (NFS) client is registered, so that instances of this filesystem can be - mounted by the application. +In case this configuration option is defined, then the Network Filesystem +(NFS) client is registered, so that instances of this filesystem can be +mounted by the application. -NOTES: - None. +.. Generated from spec:/acfg/if/filesystem-rfs + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_FILESYSTEM_RFS @@ -248,24 +332,35 @@ NOTES: CONFIGURE_FILESYSTEM_RFS ------------------------ -CONSTANT: - ``CONFIGURE_FILESYSTEM_RFS`` +.. rubric:: CONSTANT: + +``CONFIGURE_FILESYSTEM_RFS`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: -OPTION TYPE: - This configuration option is a boolean feature define. +If this configuration option is undefined, then the described feature is not +enabled. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DESCRIPTION: -DESCRIPTION: - In case this configuration option is defined, then the RTEMS Filesystem (RFS) - is registered, so that instances of this filesystem can be mounted by the - application. +In case this configuration option is defined, then the RTEMS Filesystem (RFS) +is registered, so that instances of this filesystem can be mounted by the +application. -NOTES: - This filesystem requires a Block Device Cache configuration, see - :ref:`CONFIGURE_APPLICATION_NEEDS_LIBBLOCK`. +.. rubric:: NOTES: + +This filesystem requires a Block Device Cache configuration, see +:ref:`CONFIGURE_APPLICATION_NEEDS_LIBBLOCK`. + +.. Generated from spec:/acfg/if/filesystem-tftpfs + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_FILESYSTEM_TFTPFS @@ -274,23 +369,30 @@ NOTES: CONFIGURE_FILESYSTEM_TFTPFS --------------------------- -CONSTANT: - ``CONFIGURE_FILESYSTEM_TFTPFS`` +.. rubric:: CONSTANT: + +``CONFIGURE_FILESYSTEM_TFTPFS`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then the TFTP filesystem (TFTP - client) is registered, so that instances of this filesystem can be mounted by - the application. +If this configuration option is undefined, then the described feature is not +enabled. -NOTES: - None. +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the TFTP filesystem (TFTP +client) is registered, so that instances of this filesystem can be mounted by +the application. + +.. Generated from spec:/acfg/if/imfs-disable-chmod + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_IMFS_DISABLE_CHMOD @@ -299,22 +401,29 @@ NOTES: CONFIGURE_IMFS_DISABLE_CHMOD ---------------------------- -CONSTANT: - ``CONFIGURE_IMFS_DISABLE_CHMOD`` +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_CHMOD`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the root IMFS supports - changing the mode of files. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then the root IMFS does not - support changing the mode of files (no support for :c:func:`chmod`). +If this configuration option is undefined, then the root IMFS supports +changing the mode of files. -NOTES: - None. +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the root IMFS does not +support changing the mode of files (no support for :c:func:`chmod`). + +.. Generated from spec:/acfg/if/imfs-disable-chown + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_IMFS_DISABLE_CHOWN @@ -323,22 +432,29 @@ NOTES: CONFIGURE_IMFS_DISABLE_CHOWN ---------------------------- -CONSTANT: - ``CONFIGURE_IMFS_DISABLE_CHOWN`` +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_CHOWN`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the root IMFS supports - changing the ownership of files. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then the root IMFS does not - support changing the ownership of files (no support for :c:func:`chown`). +If this configuration option is undefined, then the root IMFS supports +changing the ownership of files. -NOTES: - None. +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the root IMFS does not +support changing the ownership of files (no support for :c:func:`chown`). + +.. Generated from spec:/acfg/if/imfs-disable-link + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_IMFS_DISABLE_LINK @@ -347,22 +463,29 @@ NOTES: CONFIGURE_IMFS_DISABLE_LINK --------------------------- -CONSTANT: - ``CONFIGURE_IMFS_DISABLE_LINK`` +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_LINK`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the root IMFS supports hard - links. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then the root IMFS does not - support hard links (no support for :c:func:`link`). +If this configuration option is undefined, then the root IMFS supports hard +links. -NOTES: - None. +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the root IMFS does not +support hard links (no support for :c:func:`link`). + +.. Generated from spec:/acfg/if/imfs-disable-mknod + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_IMFS_DISABLE_MKNOD @@ -371,22 +494,29 @@ NOTES: CONFIGURE_IMFS_DISABLE_MKNOD ---------------------------- -CONSTANT: - ``CONFIGURE_IMFS_DISABLE_MKNOD`` +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_MKNOD`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the root IMFS supports making - files. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then the root IMFS does not - support making files (no support for :c:func:`mknod`). +If this configuration option is undefined, then the root IMFS supports making +files. -NOTES: - None. +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the root IMFS does not +support making files (no support for :c:func:`mknod`). + +.. Generated from spec:/acfg/if/imfs-disable-mknod-device + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_IMFS_DISABLE_MKNOD_DEVICE @@ -395,22 +525,29 @@ NOTES: CONFIGURE_IMFS_DISABLE_MKNOD_DEVICE ----------------------------------- -CONSTANT: - ``CONFIGURE_IMFS_DISABLE_MKNOD_DEVICE`` +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_MKNOD_DEVICE`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the root IMFS supports making - device files. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then the root IMFS does not - support making device files. +If this configuration option is undefined, then the root IMFS supports making +device files. -NOTES: - None. +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the root IMFS does not +support making device files. + +.. Generated from spec:/acfg/if/imfs-disable-mknod-file + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_IMFS_DISABLE_MKNOD_FILE @@ -419,22 +556,29 @@ NOTES: CONFIGURE_IMFS_DISABLE_MKNOD_FILE --------------------------------- -CONSTANT: - ``CONFIGURE_IMFS_DISABLE_MKNOD_FILE`` +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_MKNOD_FILE`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the root IMFS supports making - regular files. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then the root IMFS does not - support making regular files. +If this configuration option is undefined, then the root IMFS supports making +regular files. -NOTES: - None. +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the root IMFS does not +support making regular files. + +.. Generated from spec:/acfg/if/imfs-disable-mount + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_IMFS_DISABLE_MOUNT @@ -443,22 +587,30 @@ NOTES: CONFIGURE_IMFS_DISABLE_MOUNT ---------------------------- -CONSTANT: - ``CONFIGURE_IMFS_DISABLE_MOUNT`` +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_MOUNT`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the root IMFS supports - mounting other filesystems. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then the root IMFS does not - support mounting other filesystems (no support for :c:func:`mount`). +If this configuration option is undefined, then the root IMFS supports +mounting other filesystems. -NOTES: - None. +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the root IMFS does not +support mounting other filesystems (no support for +:c:func:`mount`). + +.. Generated from spec:/acfg/if/imfs-disable-readdir + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_IMFS_DISABLE_READDIR @@ -467,23 +619,30 @@ NOTES: CONFIGURE_IMFS_DISABLE_READDIR ------------------------------ -CONSTANT: - ``CONFIGURE_IMFS_DISABLE_READDIR`` +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_READDIR`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the root IMFS supports - reading directories. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then the root IMFS does not - support reading directories (no support for :c:func:`readdir`). It is still - possible to open files in a directory. +If this configuration option is undefined, then the root IMFS supports +reading directories. -NOTES: - None. +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the root IMFS does not +support reading directories (no support for :c:func:`readdir`). It is +still possible to open files in a directory. + +.. Generated from spec:/acfg/if/imfs-disable-readlink + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_IMFS_DISABLE_READLINK @@ -492,22 +651,29 @@ NOTES: CONFIGURE_IMFS_DISABLE_READLINK ------------------------------- -CONSTANT: - ``CONFIGURE_IMFS_DISABLE_READLINK`` +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_READLINK`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the root IMFS supports - reading symbolic links. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then the root IMFS does not - support reading symbolic links (no support for :c:func:`readlink`). +If this configuration option is undefined, then the root IMFS supports +reading symbolic links. -NOTES: - None. +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the root IMFS does not +support reading symbolic links (no support for :c:func:`readlink`). + +.. Generated from spec:/acfg/if/imfs-disable-rename + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_IMFS_DISABLE_RENAME @@ -516,22 +682,29 @@ NOTES: CONFIGURE_IMFS_DISABLE_RENAME ----------------------------- -CONSTANT: - ``CONFIGURE_IMFS_DISABLE_RENAME`` +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_RENAME`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the root IMFS supports - renaming files. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then the root IMFS does not - support renaming files (no support for :c:func:`rename`). +If this configuration option is undefined, then the root IMFS supports +renaming files. -NOTES: - None. +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the root IMFS does not +support renaming files (no support for :c:func:`rename`). + +.. Generated from spec:/acfg/if/imfs-disable-rmnod + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_IMFS_DISABLE_RMNOD @@ -540,22 +713,29 @@ NOTES: CONFIGURE_IMFS_DISABLE_RMNOD ---------------------------- -CONSTANT: - ``CONFIGURE_IMFS_DISABLE_RMNOD`` +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_RMNOD`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the root IMFS supports - removing files. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then the root IMFS does not - support removing files (no support for :c:func:`rmnod`). +If this configuration option is undefined, then the root IMFS supports +removing files. -NOTES: - None. +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the root IMFS does not +support removing files (no support for :c:func:`rmnod`). + +.. Generated from spec:/acfg/if/imfs-disable-symlink + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_IMFS_DISABLE_SYMLINK @@ -564,22 +744,29 @@ NOTES: CONFIGURE_IMFS_DISABLE_SYMLINK ------------------------------ -CONSTANT: - ``CONFIGURE_IMFS_DISABLE_SYMLINK`` +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_SYMLINK`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the root IMFS supports - creating symbolic links. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then the root IMFS does not - support creating symbolic links (no support for :c:func:`symlink`). +If this configuration option is undefined, then the root IMFS supports +creating symbolic links. -NOTES: - None. +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the root IMFS does not +support creating symbolic links (no support for :c:func:`symlink`). + +.. Generated from spec:/acfg/if/imfs-disable-unmount + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_IMFS_DISABLE_UNMOUNT @@ -588,22 +775,30 @@ NOTES: CONFIGURE_IMFS_DISABLE_UNMOUNT ------------------------------ -CONSTANT: - ``CONFIGURE_IMFS_DISABLE_UNMOUNT`` +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_UNMOUNT`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the root IMFS supports - unmounting other filesystems. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then the root IMFS does not - support unmounting other filesystems (no support for :c:func:`unmount`). +If this configuration option is undefined, then the root IMFS supports +unmounting other filesystems. -NOTES: - None. +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the root IMFS does not +support unmounting other filesystems (no support for +:c:func:`unmount`). + +.. Generated from spec:/acfg/if/imfs-disable-utime + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_IMFS_DISABLE_UTIME @@ -612,22 +807,29 @@ NOTES: CONFIGURE_IMFS_DISABLE_UTIME ---------------------------- -CONSTANT: - ``CONFIGURE_IMFS_DISABLE_UTIME`` +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_UTIME`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the root IMFS supports - changing file times. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then the root IMFS does not - support changing file times (no support for :c:func:`utime`). +If this configuration option is undefined, then the root IMFS supports +changing file times. -NOTES: - None. +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the root IMFS does not +support changing file times (no support for :c:func:`utime`). + +.. Generated from spec:/acfg/if/imfs-enable-mkfifo + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_IMFS_ENABLE_MKFIFO @@ -636,22 +838,29 @@ NOTES: CONFIGURE_IMFS_ENABLE_MKFIFO ---------------------------- -CONSTANT: - ``CONFIGURE_IMFS_ENABLE_MKFIFO`` +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_ENABLE_MKFIFO`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the root IMFS does not - support making FIFOs (no support for :c:func:`mkfifo`). +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then the root IMFS supports - making FIFOs. +If this configuration option is undefined, then the root IMFS does not +support making FIFOs (no support for :c:func:`mkfifo`). -NOTES: - None. +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the root IMFS supports +making FIFOs. + +.. Generated from spec:/acfg/if/imfs-memfile-bytes-per-block + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_IMFS_MEMFILE_BYTES_PER_BLOCK @@ -660,49 +869,96 @@ NOTES: CONFIGURE_IMFS_MEMFILE_BYTES_PER_BLOCK -------------------------------------- -CONSTANT: - ``CONFIGURE_IMFS_MEMFILE_BYTES_PER_BLOCK`` +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_MEMFILE_BYTES_PER_BLOCK`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 128. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the block size for in-memory +files managed by the IMFS. + +.. rubric:: NOTES: + +The configured block size has two impacts. The first is the average amount of +unused memory in the last block of each file. For example, when the block +size is 512, on average one-half of the last block of each file will remain +unused and the memory is wasted. In contrast, when the block size is 16, the +average unused memory per file is only 8 bytes. However, it requires more +allocations for the same size file and thus more overhead per block for the +dynamic memory management. + +Second, the block size has an impact on the maximum size file that can be +stored in the IMFS. With smaller block size, the maximum file size is +correspondingly smaller. The following shows the maximum file size possible +based on the configured block size: + +* when the block size is 16 bytes, the maximum file size is 1,328 bytes. + +* when the block size is 32 bytes, the maximum file size is 18,656 bytes. + +* when the block size is 64 bytes, the maximum file size is 279,488 bytes. + +* when the block size is 128 bytes, the maximum file size is 4,329,344 bytes. -OPTION TYPE: - This configuration option is an integer define. +* when the block size is 256 bytes, the maximum file size is 68,173,568 bytes. -DEFAULT VALUE: - The default value is 128. +* when the block size is 512 bytes, the maximum file size is 1,082,195,456 + bytes. -VALUE CONSTRAINTS: - The value of this configuration option shall be - an element of {16, 32, 64, 128, 256, 512}. +.. rubric:: CONSTRAINTS: -DESCRIPTION: - The value of this configuration option defines the block size for in-memory - files managed by the IMFS. +The value of the configuration option shall be equal to 16, 32, 64, 128, 256, +or 512. -NOTES: - The configured block size has two impacts. The first is the average amount of - unused memory in the last block of each file. For example, when the block - size is 512, on average one-half of the last block of each file will remain - unused and the memory is wasted. In contrast, when the block size is 16, the - average unused memory per file is only 8 bytes. However, it requires more - allocations for the same size file and thus more overhead per block for the - dynamic memory management. +.. Generated from spec:/acfg/if/jffs2-delayed-write-task-priority - Second, the block size has an impact on the maximum size file that can be - stored in the IMFS. With smaller block size, the maximum file size is - correspondingly smaller. The following shows the maximum file size possible - based on the configured block size: +.. raw:: latex - - when the block size is 16 bytes, the maximum file size is 1,328 bytes. + \clearpage - - when the block size is 32 bytes, the maximum file size is 18,656 bytes. +.. index:: CONFIGURE_JFFS2_DELAYED_WRITE_TASK_PRIORITY - - when the block size is 64 bytes, the maximum file size is 279,488 bytes. +.. _CONFIGURE_JFFS2_DELAYED_WRITE_TASK_PRIORITY: - - when the block size is 128 bytes, the maximum file size is 4,329,344 bytes. +CONFIGURE_JFFS2_DELAYED_WRITE_TASK_PRIORITY +------------------------------------------- - - when the block size is 256 bytes, the maximum file size is 68,173,568 bytes. +.. rubric:: CONSTANT: - - when the block size is 512 bytes, the maximum file size is 1,082,195,456 - bytes. +``CONFIGURE_JFFS2_DELAYED_WRITE_TASK_PRIORITY`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 15. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the JFFS2 delayed write task priority. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be a valid Classic API task +priority. The set of valid task priorities depends on the scheduler +configuration. + +.. Generated from spec:/acfg/if/use-devfs-as-base-filesystem + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM @@ -711,54 +967,65 @@ NOTES: CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM -------------------------------------- -CONSTANT: - ``CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM`` +.. rubric:: CONSTANT: + +``CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM`` -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: OPTION TYPE: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +This configuration option is a boolean feature define. -DESCRIPTION: - In case this configuration option is defined, then an IMFS with a reduced - feature set will be the base filesystem (also known as root filesystem). +.. rubric:: DEFAULT CONFIGURATION: -NOTES: - In case this configuration option is defined, then the following - configuration options will be defined as well +If this configuration option is undefined, then the described feature is not +enabled. - - :ref:`CONFIGURE_IMFS_DISABLE_CHMOD`, +.. rubric:: DESCRIPTION: - - :ref:`CONFIGURE_IMFS_DISABLE_CHOWN`, +In case this configuration option is defined, then an IMFS with a reduced +feature set will be the base filesystem (also known as root filesystem). - - :ref:`CONFIGURE_IMFS_DISABLE_LINK`, +.. rubric:: NOTES: - - :ref:`CONFIGURE_IMFS_DISABLE_MKNOD_FILE`, +In case this configuration option is defined, then the following +configuration options will be defined as well - - :ref:`CONFIGURE_IMFS_DISABLE_MOUNT`, +* :ref:`CONFIGURE_IMFS_DISABLE_CHMOD`, - - :ref:`CONFIGURE_IMFS_DISABLE_READDIR`, +* :ref:`CONFIGURE_IMFS_DISABLE_CHOWN`, - - :ref:`CONFIGURE_IMFS_DISABLE_READLINK`, +* :ref:`CONFIGURE_IMFS_DISABLE_LINK`, - - :ref:`CONFIGURE_IMFS_DISABLE_RENAME`, +* :ref:`CONFIGURE_IMFS_DISABLE_MKNOD_FILE`, - - :ref:`CONFIGURE_IMFS_DISABLE_RMNOD`, +* :ref:`CONFIGURE_IMFS_DISABLE_MOUNT`, - - :ref:`CONFIGURE_IMFS_DISABLE_SYMLINK`, +* :ref:`CONFIGURE_IMFS_DISABLE_READDIR`, - - :ref:`CONFIGURE_IMFS_DISABLE_UTIME`, and +* :ref:`CONFIGURE_IMFS_DISABLE_READLINK`, - - :ref:`CONFIGURE_IMFS_DISABLE_UNMOUNT`. +* :ref:`CONFIGURE_IMFS_DISABLE_RENAME`, - In addition, a simplified path evaluation is enabled. It allows only a look - up of absolute paths. +* :ref:`CONFIGURE_IMFS_DISABLE_RMNOD`, - This configuration of the IMFS is basically a device-only filesystem. It is - comparable in functionality to the pseudo-filesystem name space provided - before RTEMS release 4.5.0. +* :ref:`CONFIGURE_IMFS_DISABLE_SYMLINK`, + +* :ref:`CONFIGURE_IMFS_DISABLE_UTIME`, and + +* :ref:`CONFIGURE_IMFS_DISABLE_UNMOUNT`. + +In addition, a simplified path evaluation is enabled. It allows only a look +up of absolute paths. + +This configuration of the IMFS is basically a device-only filesystem. It is +comparable in functionality to the pseudo-filesystem name space provided +before RTEMS release 4.5.0. + +.. Generated from spec:/acfg/if/use-miniimfs-as-base-filesystem + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_USE_MINIIMFS_AS_BASE_FILESYSTEM @@ -767,36 +1034,41 @@ NOTES: CONFIGURE_USE_MINIIMFS_AS_BASE_FILESYSTEM ----------------------------------------- -CONSTANT: - ``CONFIGURE_USE_MINIIMFS_AS_BASE_FILESYSTEM`` +.. rubric:: CONSTANT: + +``CONFIGURE_USE_MINIIMFS_AS_BASE_FILESYSTEM`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DESCRIPTION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +In case this configuration option is defined, then an IMFS with a reduced +feature set will be the base filesystem (also known as root filesystem). -DESCRIPTION: - In case this configuration option is defined, then an IMFS with a reduced - feature set will be the base filesystem (also known as root filesystem). +.. rubric:: NOTES: -NOTES: - In case this configuration option is defined, then the following - configuration options will be defined as well +In case this configuration option is defined, then the following +configuration options will be defined as well - - :ref:`CONFIGURE_IMFS_DISABLE_CHMOD`, +* :ref:`CONFIGURE_IMFS_DISABLE_CHMOD`, - - :ref:`CONFIGURE_IMFS_DISABLE_CHOWN`, +* :ref:`CONFIGURE_IMFS_DISABLE_CHOWN`, - - :ref:`CONFIGURE_IMFS_DISABLE_LINK`, +* :ref:`CONFIGURE_IMFS_DISABLE_LINK`, - - :ref:`CONFIGURE_IMFS_DISABLE_READLINK`, +* :ref:`CONFIGURE_IMFS_DISABLE_READLINK`, - - :ref:`CONFIGURE_IMFS_DISABLE_RENAME`, +* :ref:`CONFIGURE_IMFS_DISABLE_RENAME`, - - :ref:`CONFIGURE_IMFS_DISABLE_SYMLINK`, +* :ref:`CONFIGURE_IMFS_DISABLE_SYMLINK`, - - :ref:`CONFIGURE_IMFS_DISABLE_UTIME`, and +* :ref:`CONFIGURE_IMFS_DISABLE_UTIME`, and - - :ref:`CONFIGURE_IMFS_DISABLE_UNMOUNT`. +* :ref:`CONFIGURE_IMFS_DISABLE_UNMOUNT`. diff --git a/c-user/config/general.rst b/c-user/config/general.rst index b1bca61..61bfa1e 100644 --- a/c-user/config/general.rst +++ b/c-user/config/general.rst @@ -1,13 +1,36 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +.. Copyright (C) 2020, 2023 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2022 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/acfg/if/group-general General System Configuration ============================ This section describes general system configuration options. +.. Generated from spec:/acfg/if/dirty-memory + +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_DIRTY_MEMORY .. _CONFIGURE_DIRTY_MEMORY: @@ -15,29 +38,89 @@ This section describes general system configuration options. CONFIGURE_DIRTY_MEMORY ---------------------- -CONSTANT: - ``CONFIGURE_DIRTY_MEMORY`` +.. rubric:: CONSTANT: + +``CONFIGURE_DIRTY_MEMORY`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is a boolean feature define. +In case this configuration option is defined, then the memory areas used for +the RTEMS Workspace and the C Program Heap are dirtied with a ``0xCF`` byte +pattern during system initialization. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: NOTES: -DESCRIPTION: - In case this configuration option is defined, then the memory areas used for - the RTEMS Workspace and the C Program Heap are dirtied with a ``0xCF`` byte - pattern during system initialization. +Dirtying memory can add significantly to system initialization time. It may +assist in finding code that incorrectly assumes the contents of free memory +areas is cleared to zero during system initialization. In case +:ref:`CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY` is also defined, then the +memory is first dirtied and then zeroed. + +See also :ref:`CONFIGURE_MALLOC_DIRTY`. + +.. Generated from spec:/acfg/if/disable-bsp-settings + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_DISABLE_BSP_SETTINGS + +.. _CONFIGURE_DISABLE_BSP_SETTINGS: + +CONFIGURE_DISABLE_BSP_SETTINGS +------------------------------ -NOTES: - Dirtying memory can add significantly to system initialization time. It may - assist in finding code that incorrectly assumes the contents of free memory - areas is cleared to zero during system initialization. In case - :ref:`CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY` is also defined, then the - memory is first dirtied and then zeroed. +.. rubric:: CONSTANT: - See also :ref:`CONFIGURE_MALLOC_DIRTY`. +``CONFIGURE_DISABLE_BSP_SETTINGS`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the optional BSP provided +settings listed below are disabled. + +The optional BSP provided default values for the following application +configuration options are disabled: + +* :ref:`CONFIGURE_IDLE_TASK_BODY` + +* :ref:`CONFIGURE_IDLE_TASK_STACK_SIZE` + +* :ref:`CONFIGURE_INTERRUPT_STACK_SIZE` + +The optional BSP provided initial extension set is disabled (see +:term:`initial extension sets`). The optional BSP provided +prerequisite IO device drivers are disabled (see +Device Driver Configuration). The optional BSP provided support for +:c:func:`sbrk` is disabled. + +This configuration option provides an all or nothing choice with respect to +the optional BSP provided settings. + +.. Generated from spec:/acfg/if/disable-newlib-reentrancy + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_DISABLE_NEWLIB_REENTRANCY @@ -46,25 +129,36 @@ NOTES: CONFIGURE_DISABLE_NEWLIB_REENTRANCY ----------------------------------- -CONSTANT: - ``CONFIGURE_DISABLE_NEWLIB_REENTRANCY`` +.. rubric:: CONSTANT: + +``CONFIGURE_DISABLE_NEWLIB_REENTRANCY`` -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: OPTION TYPE: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +This configuration option is a boolean feature define. -DESCRIPTION: - In case this configuration option is defined, then the Newlib reentrancy - support per thread is disabled and a global reentrancy structure is used. +.. rubric:: DEFAULT CONFIGURATION: -NOTES: - You can enable this option to reduce the size of the :term:`TCB`. Use this - option with care, since it can lead to race conditions and undefined system - behaviour. For example, :c:data:`errno` is no longer a thread-local variable - if this option is enabled. +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the Newlib reentrancy +support per thread is disabled and a global reentrancy structure is used. + +.. rubric:: NOTES: + +You can enable this option to reduce the size of the :term:`TCB`. Use this +option with care, since it can lead to race conditions and undefined system +behaviour. For example, :c:macro:`errno` is no longer a thread-local +variable if this option is enabled. + +.. Generated from spec:/acfg/if/executive-ram-size + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_EXECUTIVE_RAM_SIZE @@ -73,36 +167,48 @@ NOTES: CONFIGURE_EXECUTIVE_RAM_SIZE ---------------------------- -CONSTANT: - ``CONFIGURE_EXECUTIVE_RAM_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_EXECUTIVE_RAM_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +If this configuration option is undefined, then the RTEMS Workspace and task +stack space size is calculated by ``<rtems/confdefs.h>`` based on the +values configuration options. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the RTEMS Workspace size in +bytes. + +.. rubric:: NOTES: + +This is an advanced configuration option. Use it only if you know exactly +what you are doing. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: CONSTRAINTS: -DEFAULT VALUE: - If this configuration option is undefined, then the RTEMS Workspace and task - stack space size is calculated by ``<rtems/confdefs.h>`` based on the values - configuration options. +The following constraints apply to this configuration option: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +* The value of the configuration option shall be greater than or equal to zero. - * It shall be greater than or equal to 0. +* The value of the configuration option shall be less than or equal to + `UINTPTR_MAX <https://en.cppreference.com/w/c/types/integer>`_. - * It shall be less than or equal to ``UINTPTR_MAX``. +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +.. Generated from spec:/acfg/if/extra-task-stacks -DESCRIPTION: - The value of this configuration option defines the RTEMS Workspace size in - bytes. +.. raw:: latex -NOTES: - This is an advanced configuration option. Use it only if you know exactly - what you are doing. + \clearpage .. index:: CONFIGURE_EXTRA_TASK_STACKS .. index:: memory for task tasks @@ -112,34 +218,82 @@ NOTES: CONFIGURE_EXTRA_TASK_STACKS --------------------------- -CONSTANT: - ``CONFIGURE_EXTRA_TASK_STACKS`` +.. rubric:: CONSTANT: + +``CONFIGURE_EXTRA_TASK_STACKS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the number of bytes the +applications wishes to add to the task stack requirements calculated by +``<rtems/confdefs.h>``. + +.. rubric:: NOTES: + +This parameter is very important. If the application creates tasks with +stacks larger then the minimum, then that memory is **not** accounted for by +``<rtems/confdefs.h>``. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be small enough so that the task + stack space calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. + +.. Generated from spec:/acfg/if/init + +.. raw:: latex + + \clearpage -OPTION TYPE: - This configuration option is an integer define. +.. index:: CONFIGURE_INIT -DEFAULT VALUE: - The default value is 0. +.. _CONFIGURE_INIT: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +CONFIGURE_INIT +-------------- - * It shall be greater than or equal to 0. +.. rubric:: CONSTANT: - * It shall be small enough so that the task - stack space calculation carried out by ``<rtems/confdefs.h>`` does not - overflow an integer of type ``uintptr_t``. +``CONFIGURE_INIT`` -DESCRIPTION: - The value of this configuration option defines the number of bytes the - applications wishes to add to the task stack requirements calculated by - ``<rtems/confdefs.h>``. +.. rubric:: OPTION TYPE: -NOTES: - This parameter is very important. If the application creates tasks with - stacks larger then the minimum, then that memory is **not** accounted for by - ``<rtems/confdefs.h>``. +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +There is no default configuration associated with this configuration option. +If ``<rtems/confdefs.h>`` is included and this configuration option is not +defined, then only white space is included. + +.. rubric:: DESCRIPTION: + +While this configuration option is defined, when the ``<rtems/confdefs.h>`` +is included, the system settings defined by present application configuration +options are statically allocated and initialized. All user provided +application configuration options defined before the include of +``<rtems/confdefs.h>`` are evaluated. They define the actual system +settings. + +.. Generated from spec:/acfg/if/initial-extensions + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_INITIAL_EXTENSIONS @@ -148,27 +302,39 @@ NOTES: CONFIGURE_INITIAL_EXTENSIONS ---------------------------- -CONSTANT: - ``CONFIGURE_INITIAL_EXTENSIONS`` +.. rubric:: CONSTANT: + +``CONFIGURE_INITIAL_EXTENSIONS`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is an initializer define. +This configuration option is an initializer define. -DEFAULT VALUE: - The default value is the empty list. +.. rubric:: DEFAULT VALUE: -VALUE CONSTRAINTS: - The value of this configuration option shall be a list of initializers for - structures of type :c:type:`rtems_extensions_table`. +The default value is the empty list. -DESCRIPTION: - The value of this configuration option is used to initialize the table of - initial user extensions. +.. rubric:: DESCRIPTION: -NOTES: - The value of this configuration option is placed before the entries of - :ref:`BSP_INITIAL_EXTENSION` and after the entries of all other initial - user extensions. +The value of this configuration option is used to initialize the table of +initial user extensions. + +.. rubric:: NOTES: + +The value of this configuration option is placed before the entries of +:c:macro:`BSP_INITIAL_EXTENSION` and after the entries of all other +initial user extensions. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be a list of initializers for +structures of type :ref:`InterfaceRtemsExtensionsTable`. + +.. Generated from spec:/acfg/if/interrupt-stack-size + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_INTERRUPT_STACK_SIZE .. index:: interrupt stack size @@ -178,50 +344,66 @@ NOTES: CONFIGURE_INTERRUPT_STACK_SIZE ------------------------------ -CONSTANT: - ``CONFIGURE_INTERRUPT_STACK_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_INTERRUPT_STACK_SIZE`` -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: OPTION TYPE: -DEFAULT VALUE: - The default value is :ref:`BSP_INTERRUPT_STACK_SIZE` in case it is defined, - otherwise the default value is ``CPU_STACK_MINIMUM_SIZE``. +This configuration option is an integer define. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: DEFAULT VALUE: - * It shall be greater than or equal to a - BSP-specific and application-specific minimum value. +If the :ref:`CONFIGURE_DISABLE_BSP_SETTINGS` configuration option is not defined and +:c:macro:`BSP_INTERRUPT_STACK_SIZE` is provided by the +:term:`BSP`, then the default value is defined by +:c:macro:`BSP_INTERRUPT_STACK_SIZE`, otherwise the default value is +:c:macro:`CPU_STACK_MINIMUM_SIZE`. - * It shall be small enough so that the - interrupt stack area calculation carried out by ``<rtems/confdefs.h>`` does - not overflow an integer of type ``size_t``. +.. rubric:: DESCRIPTION: - * It shall be aligned according to - ``CPU_INTERRUPT_STACK_ALIGNMENT``. +The value of this configuration option defines the size of an interrupt stack +in bytes. -DESCRIPTION: - The value of this configuration option defines the size of an interrupt stack - in bytes. +.. rubric:: NOTES: -NOTES: - There is one interrupt stack available for each configured processor - (:ref:`CONFIGURE_MAXIMUM_PROCESSORS`). The interrupt stack areas are - statically allocated in a special linker section (``.rtemsstack.interrupt``). - The placement of this linker section is BSP-specific. +There is one interrupt stack available for each configured processor +(:ref:`CONFIGURE_MAXIMUM_PROCESSORS`). The interrupt stack areas are +statically allocated in a special linker section (``.rtemsstack.interrupt``). +The placement of this linker section is BSP-specific. - Some BSPs use the interrupt stack as the initialization stack which is used - to perform the sequential system initialization before the multithreading - is started. +Some BSPs use the interrupt stack as the initialization stack which is used +to perform the sequential system initialization before the multithreading +is started. - The interrupt stacks are covered by the :ref:`stack checker - <CONFIGURE_STACK_CHECKER_ENABLED>`. However, using a too small interrupt - stack size may still result in undefined behaviour. +The interrupt stacks are covered by the stack checker, see +:ref:`CONFIGURE_STACK_CHECKER_ENABLED`. However, using a too small interrupt stack +size may still result in undefined behaviour. - In releases before RTEMS 5.1 the default value was - :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE` instead of ``CPU_STACK_MINIMUM_SIZE``. +In releases before RTEMS 5.1 the default value was +:ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE` instead of +:c:macro:`CPU_STACK_MINIMUM_SIZE`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to a + BSP-specific and application-specific minimum value. + +* The value of the configuration option shall be small enough so that the + interrupt stack area calculation carried out by ``<rtems/confdefs.h>`` does + not overflow an integer of type `size_t + <https://en.cppreference.com/w/c/types/size_t>`_. + +* The value of the configuration option shall be aligned according to + :c:macro:`CPU_INTERRUPT_STACK_ALIGNMENT`. + +.. Generated from spec:/acfg/if/malloc-dirty + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_MALLOC_DIRTY @@ -230,26 +412,37 @@ NOTES: CONFIGURE_MALLOC_DIRTY ---------------------- -CONSTANT: - ``CONFIGURE_MALLOC_DIRTY`` +.. rubric:: CONSTANT: + +``CONFIGURE_MALLOC_DIRTY`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then each memory area returned +by C Program Heap allocator functions such as :c:func:`malloc` is dirtied +with a ``0xCF`` byte pattern before it is handed over to the application. + +.. rubric:: NOTES: -OPTION TYPE: - This configuration option is a boolean feature define. +The dirtying performed by this option is carried out for each successful +memory allocation from the C Program Heap in contrast to +:ref:`CONFIGURE_DIRTY_MEMORY` which dirties the memory only once during the +system initialization. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. Generated from spec:/acfg/if/max-file-descriptors -DESCRIPTION: - In case this configuration option is defined, then each memory area returned - by C Program Heap allocator functions such as :c:func:`malloc` is dirtied - with a ``0xCF`` byte pattern before it is handed over to the application. +.. raw:: latex -NOTES: - The dirtying performed by this option is carried out for each successful - memory allocation from the C Program Heap in contrast to - :ref:`CONFIGURE_DIRTY_MEMORY` which dirties the memory only once during the - system initialization. + \clearpage .. index:: CONFIGURE_MAXIMUM_FILE_DESCRIPTORS .. index:: maximum file descriptors @@ -259,34 +452,46 @@ NOTES: CONFIGURE_MAXIMUM_FILE_DESCRIPTORS ---------------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_FILE_DESCRIPTORS`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is an integer define. +``CONFIGURE_MAXIMUM_FILE_DESCRIPTORS`` -DEFAULT VALUE: - The default value is 3. +.. rubric:: OPTION TYPE: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +This configuration option is an integer define. - * It shall be greater than or equal to 0. +.. rubric:: DEFAULT VALUE: - * It shall be less than or equal to ``SIZE_MAX``. +The default value is 3. - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +.. rubric:: DESCRIPTION: -DESCRIPTION: - The value of this configuration option defines the maximum number of file - like objects that can be concurrently open. +The value of this configuration option defines the maximum number of file +like objects that can be concurrently open. -NOTES: - The default value of three file descriptors allows RTEMS to support standard - input, output, and error I/O streams on ``/dev/console``. +.. rubric:: NOTES: + +The default value of three file descriptors allows RTEMS to support standard +input, output, and error I/O streams on :file:`/dev/console`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +.. Generated from spec:/acfg/if/max-processors + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_MAXIMUM_PROCESSORS @@ -295,33 +500,112 @@ NOTES: CONFIGURE_MAXIMUM_PROCESSORS ---------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_PROCESSORS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_PROCESSORS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 1. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the maximum number of +processors an application intends to use. The number of actually available +processors depends on the hardware and may be less. It is recommended to use +the smallest value suitable for the application in order to save memory. +Each processor needs an IDLE task stack and interrupt stack for example. + +.. rubric:: NOTES: + +If there are more processors available than configured, the rest will be +ignored. + +This configuration option is only evaluated in SMP configurations of RTEMS +(e.g. RTEMS was built with the SMP build configuration option enabled). +In all other configurations it has no effect. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to one. + +* The value of the configuration option shall be less than or equal to + :c:macro:`CPU_MAXIMUM_PROCESSORS`. + +.. Generated from spec:/acfg/if/max-thread-local-storage-size + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE + +.. _CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE: + +CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE +------------------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is an integer define. +This configuration option is an integer define. -DEFAULT VALUE: - The default value is 1. +.. rubric:: DEFAULT VALUE: -VALUE CONSTRAINTS: - The value of this configuration option shall be greater than or equal to 0 - and less than or equal to ``CPU_MAXIMUM_PROCESSORS``. +The default value is 0. -DESCRIPTION: - The value of this configuration option defines the maximum number of - processors an application intends to use. The number of actually available - processors depends on the hardware and may be less. It is recommended to use - the smallest value suitable for the application in order to save memory. - Each processor needs an IDLE task stack and interrupt stack for example. +.. rubric:: DESCRIPTION: -NOTES: - If there are more processors available than configured, the rest will be - ignored. +If the value of this configuration option is greater than zero, then it +defines the maximum thread-local storage size, otherwise the thread-local +storage size is defined by the linker depending on the thread-local storage +objects used by the application in the statically-linked executable. - This configuration option is only evaluated in SMP configurations (e.g. RTEMS - was built with the ``--enable-smp`` build configuration option). In all - other configurations it has no effect. +.. rubric:: NOTES: + +This configuration option can be used to reserve space for the dynamic linking +of modules with thread-local storage objects. + +If the thread-local storage size defined by the thread-local storage +objects used by the application in the statically-linked executable is greater +than a non-zero value of this configuration option, then a fatal error will +occur during system initialization. + +Use :c:func:`RTEMS_ALIGN_UP` and +:c:macro:`RTEMS_TASK_STORAGE_ALIGNMENT` to adjust the size to meet the +minimum alignment requirement of a thread-local storage area. + +The actual thread-local storage size is determined when the application +executable is linked. The ``rtems-exeinfo`` command line tool included in +the RTEMS Tools can be used to obtain the thread-local storage size and +alignment of an application executable. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_. + +* The value of the configuration option shall be an integral multiple of + :c:macro:`RTEMS_TASK_STORAGE_ALIGNMENT`. + +.. Generated from spec:/acfg/if/max-thread-name-size + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_MAXIMUM_THREAD_NAME_SIZE .. index:: maximum thread name size @@ -331,39 +615,51 @@ NOTES: CONFIGURE_MAXIMUM_THREAD_NAME_SIZE ---------------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_THREAD_NAME_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_THREAD_NAME_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 16. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DESCRIPTION: -DEFAULT VALUE: - The default value is 16. +The value of this configuration option defines the maximum thread name size +including the terminating ``NUL`` character. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: NOTES: - * It shall be greater than or equal to 0. +The default value was chosen for Linux compatibility, see +`pthread_setname_np() <http://man7.org/linux/man-pages/man3/pthread_setname_np.3.html>`_. - * It shall be less than or equal to ``SIZE_MAX``. +The size of the thread control block is increased by the maximum thread name +size. - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +This configuration option is available since RTEMS 5.1. -DESCRIPTION: - The value of this configuration option defines the maximum thread name size - including the terminating ``NUL`` character. +.. rubric:: CONSTRAINTS: -NOTES: - The default value was chosen for Linux compatibility, see - `PTHREAD_SETNAME_NP(3) <http://man7.org/linux/man-pages/man3/pthread_setname_np.3.html>`_. +The following constraints apply to this configuration option: - The size of the thread control block is increased by the maximum thread name - size. +* The value of the configuration option shall be greater than or equal to zero. - This configuration option is available since RTEMS 5.1. +* The value of the configuration option shall be less than or equal to + `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +.. Generated from spec:/acfg/if/memory-overhead + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_MEMORY_OVERHEAD @@ -372,40 +668,52 @@ NOTES: CONFIGURE_MEMORY_OVERHEAD ------------------------- -CONSTANT: - ``CONFIGURE_MEMORY_OVERHEAD`` +.. rubric:: CONSTANT: + +``CONFIGURE_MEMORY_OVERHEAD`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: -OPTION TYPE: - This configuration option is an integer define. +The default value is 0. -DEFAULT VALUE: - The default value is 0. +.. rubric:: DESCRIPTION: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The value of this configuration option defines the number of kilobytes the +application wishes to add to the RTEMS Workspace size calculated by +``<rtems/confdefs.h>``. - * It shall be greater than or equal to 0. +.. rubric:: NOTES: - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +This configuration option should only be used when it is suspected that a bug +in ``<rtems/confdefs.h>`` has resulted in an underestimation. Typically the +memory allocation will be too low when an application does not account for +all message queue buffers or task stacks, see +:ref:`CONFIGURE_MESSAGE_BUFFER_MEMORY`. - * It shall be small enough so that the - RTEMS Workspace size calculation carried out by ``<rtems/confdefs.h>`` does - not overflow an integer of type ``uintptr_t``. +.. rubric:: CONSTRAINTS: -DESCRIPTION: - The value of this configuration option defines the number of kilobytes the - application wishes to add to the RTEMS Workspace size calculated by - ``<rtems/confdefs.h>``. +The following constraints apply to this configuration option: -NOTES: - This configuration option should only be used when it is suspected that a bug - in ``<rtems/confdefs.h>`` has resulted in an underestimation. Typically the - memory allocation will be too low when an application does not account for - all message queue buffers or task stacks, see - :ref:`CONFIGURE_MESSAGE_BUFFER_MEMORY`. +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +* The value of the configuration option shall be small enough so that the RTEMS + Workspace size calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. + +.. Generated from spec:/acfg/if/message-buffer-memory + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_MESSAGE_BUFFER_MEMORY .. index:: configure message queue buffer memory @@ -417,79 +725,91 @@ NOTES: CONFIGURE_MESSAGE_BUFFER_MEMORY ------------------------------- -CONSTANT: - ``CONFIGURE_MESSAGE_BUFFER_MEMORY`` - -OPTION TYPE: - This configuration option is an integer define. - -DEFAULT VALUE: - The default value is 0. - -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: - - * It shall be greater than or equal to 0. - - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. - - * It shall be small enough so that the - RTEMS Workspace size calculation carried out by ``<rtems/confdefs.h>`` does - not overflow an integer of type ``uintptr_t``. - -DESCRIPTION: - The value of this configuration option defines the number of bytes reserved - for message queue buffers in the RTEMS Workspace. - -NOTES: - The configuration options :ref:`CONFIGURE_MAXIMUM_MESSAGE_QUEUES` and - :ref:`CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES` define only how many message - queues can be created by the application. The memory for the message - buffers is configured by this option. For each message queue you have to - reserve some memory for the message buffers. The size dependes on the - maximum number of pending messages and the maximum size of the messages of - a message queue. Use the ``CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE()`` macro - to specify the message buffer memory for each message queue and sum them up - to define the value for ``CONFIGURE_MAXIMUM_MESSAGE_QUEUES``. - - The interface for the ``CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE()`` help - macro is as follows: - - .. code-block:: c - - CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE( max_messages, max_msg_size ) - - Where ``max_messages`` is the maximum number of pending messages and - ``max_msg_size`` is the maximum size in bytes of the messages of the - corresponding message queue. Both parameters shall be compile time - constants. Not using this help macro (e.g. just using - ``max_messages * max_msg_size``) may result in an underestimate of the - RTEMS Workspace size. - - The following example illustrates how the - `CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE()` help macro can be used to assist in - calculating the message buffer memory required. In this example, there are - two message queues used in this application. The first message queue has a - maximum of 24 pending messages with the message structure defined by the - type ``one_message_type``. The other message queue has a maximum of 500 - pending messages with the message structure defined by the type - ``other_message_type``. - - .. code-block:: c - - #define CONFIGURE_MESSAGE_BUFFER_MEMORY ( \ - CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE( \ - 24, \ - sizeof( one_message_type ) \ - ) \ - + CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE( \ - 500, \ - sizeof( other_message_type ) \ - ) \ - ) +.. rubric:: CONSTANT: + +``CONFIGURE_MESSAGE_BUFFER_MEMORY`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the number of bytes reserved +for message queue buffers in the RTEMS Workspace. + +.. rubric:: NOTES: + +The configuration options :ref:`CONFIGURE_MAXIMUM_MESSAGE_QUEUES` and +:ref:`CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES` define only how many message +queues can be created by the application. The memory for the message +buffers is configured by this option. For each message queue you have to +reserve some memory for the message buffers. The size depends on the +maximum number of pending messages and the maximum size of the messages of +a message queue. Use the ``CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE()`` macro +to specify the message buffer memory for each message queue and sum them up +to define the value for ``CONFIGURE_MAXIMUM_MESSAGE_QUEUES``. + +The interface for the ``CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE()`` help +macro is as follows: + +.. code-block:: c + + CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE( max_messages, max_msg_size ) + +Where ``max_messages`` is the maximum number of pending messages and +``max_msg_size`` is the maximum size in bytes of the messages of the +corresponding message queue. Both parameters shall be compile time +constants. Not using this help macro (e.g. just using +``max_messages * max_msg_size``) may result in an underestimate of the +RTEMS Workspace size. + +The following example illustrates how the +``CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE()`` help macro can be used to assist in +calculating the message buffer memory required. In this example, there are +two message queues used in this application. The first message queue has a +maximum of 24 pending messages with the message structure defined by the +type ``one_message_type``. The other message queue has a maximum of 500 +pending messages with the message structure defined by the type +``other_message_type``. + +.. code-block:: c + + #define CONFIGURE_MESSAGE_BUFFER_MEMORY ( \ + CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE( \ + 24, \ + sizeof( one_message_type ) \ + ) \ + + CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE( \ + 500, \ + sizeof( other_message_type ) \ + ) \ + ) + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +* The value of the configuration option shall be small enough so that the RTEMS + Workspace size calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. + +.. Generated from spec:/acfg/if/microseconds-per-tick + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_MICROSECONDS_PER_TICK .. index:: clock tick quantum @@ -500,50 +820,63 @@ NOTES: CONFIGURE_MICROSECONDS_PER_TICK ------------------------------- -CONSTANT: - ``CONFIGURE_MICROSECONDS_PER_TICK`` +.. rubric:: CONSTANT: + +``CONFIGURE_MICROSECONDS_PER_TICK`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DEFAULT VALUE: -DEFAULT VALUE: - The default value is 10000. +The default value is 10000. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: DESCRIPTION: - * It shall be greater than or equal to a Clock Driver specific value. +The value of this configuration option defines the length of time in +microseconds between clock ticks (clock tick quantum). - * It shall be less than or equal to a Clock Driver specific value. +When the clock tick quantum value is too low, the system will spend so much +time processing clock ticks that it does not have processing time available +to perform application work. In this case, the system will become +unresponsive. - * The resulting clock ticks per second should be an integer. +The lowest practical time quantum varies widely based upon the speed of the +target hardware and the architectural overhead associated with +interrupts. In general terms, you do not want to configure it lower than is +needed for the application. -DESCRIPTION: - The value of this configuration option defines the length of time in - microseconds between clock ticks (clock tick quantum). +The clock tick quantum should be selected such that it all blocking and +delay times in the application are evenly divisible by it. Otherwise, +rounding errors will be introduced which may negatively impact the +application. - When the clock tick quantum value is too low, the system will spend so much - time processing clock ticks that it does not have processing time available - to perform application work. In this case, the system will become - unresponsive. +.. rubric:: NOTES: - The lowest practical time quantum varies widely based upon the speed of the - target hardware and the architectural overhead associated with - interrupts. In general terms, you do not want to configure it lower than is - needed for the application. +This configuration option has no impact if the Clock Driver is not +configured, see :ref:`CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`. - The clock tick quantum should be selected such that it all blocking and - delay times in the application are evenly divisible by it. Otherwise, - rounding errors will be introduced which may negatively impact the - application. +There may be Clock Driver specific limits on the resolution or maximum value +of a clock tick quantum. -NOTES: - This configuration option has no impact if the Clock Driver is not - configured, see :ref:`CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`. +.. rubric:: CONSTRAINTS: - There may be Clock Driver specific limits on the resolution or maximum value - of a clock tick quantum. +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to a + value defined by the :term:`Clock Driver`. + +* The value of the configuration option shall be less than or equal to a value + defined by the :term:`Clock Driver`. + +* The resulting clock ticks per second should be an integer. + +.. Generated from spec:/acfg/if/min-task-stack-size + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_MINIMUM_TASK_STACK_SIZE .. index:: minimum task stack size @@ -553,51 +886,63 @@ NOTES: CONFIGURE_MINIMUM_TASK_STACK_SIZE --------------------------------- -CONSTANT: - ``CONFIGURE_MINIMUM_TASK_STACK_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_MINIMUM_TASK_STACK_SIZE`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is an integer define. +This configuration option is an integer define. -DEFAULT VALUE: - The default value is ``CPU_STACK_MINIMUM_SIZE``. +.. rubric:: DEFAULT VALUE: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The default value is :c:macro:`CPU_STACK_MINIMUM_SIZE`. - * It shall be small enough so that the task - stack space calculation carried out by ``<rtems/confdefs.h>`` does not - overflow an integer of type ``uintptr_t``. +.. rubric:: DESCRIPTION: - * It shall be greater than or equal to a - BSP-specific and application-specific minimum value. +The value of this configuration option defines the minimum stack size in +bytes for every user task or thread in the system. -DESCRIPTION: - The value of this configuration option defines the minimum stack size in - bytes for every user task or thread in the system. +.. rubric:: NOTES: -NOTES: - Adjusting this parameter should be done with caution. Examining the actual - stack usage using the stack checker usage reporting facility is recommended - (see also :ref:`CONFIGURE_STACK_CHECKER_ENABLED`). +Adjusting this parameter should be done with caution. Examining the actual +stack usage using the stack checker usage reporting facility is recommended +(see also :ref:`CONFIGURE_STACK_CHECKER_ENABLED`). - This parameter can be used to lower the minimum from that recommended. This - can be used in low memory systems to reduce memory consumption for - stacks. However, this shall be done with caution as it could increase the - possibility of a blown task stack. +This parameter can be used to lower the minimum from that recommended. This +can be used in low memory systems to reduce memory consumption for +stacks. However, this shall be done with caution as it could increase the +possibility of a blown task stack. - This parameter can be used to increase the minimum from that - recommended. This can be used in higher memory systems to reduce the risk - of stack overflow without performing analysis on actual consumption. +This parameter can be used to increase the minimum from that +recommended. This can be used in higher memory systems to reduce the risk +of stack overflow without performing analysis on actual consumption. - By default, this configuration parameter defines also the minimum stack - size of POSIX threads. This can be changed with the - :ref:`CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE` - configuration option. +By default, this configuration parameter defines also the minimum stack +size of POSIX threads. This can be changed with the +:ref:`CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE` +configuration option. - In releases before RTEMS 5.1 the ``CONFIGURE_MINIMUM_TASK_STACK_SIZE`` was - used to define the default value of :ref:`CONFIGURE_INTERRUPT_STACK_SIZE`. +In releases before RTEMS 5.1 the ``CONFIGURE_MINIMUM_TASK_STACK_SIZE`` was +used to define the default value of :ref:`CONFIGURE_INTERRUPT_STACK_SIZE`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be small enough so that the task + stack space calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. + +* The value of the configuration option shall be greater than or equal to a + BSP-specific and application-specific minimum value. + +.. Generated from spec:/acfg/if/stack-checker-enabled + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_STACK_CHECKER_ENABLED @@ -606,26 +951,37 @@ NOTES: CONFIGURE_STACK_CHECKER_ENABLED ------------------------------- -CONSTANT: - ``CONFIGURE_STACK_CHECKER_ENABLED`` +.. rubric:: CONSTANT: + +``CONFIGURE_STACK_CHECKER_ENABLED`` -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: OPTION TYPE: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +This configuration option is a boolean feature define. -DESCRIPTION: - In case this configuration option is defined, then the stack checker is - enabled. +.. rubric:: DEFAULT CONFIGURATION: -NOTES: - The stack checker performs run-time stack bounds checking. This increases - the time required to create tasks as well as adding overhead to each context - switch. +If this configuration option is undefined, then the described feature is not +enabled. - In 4.9 and older, this configuration option was named ``STACK_CHECKER_ON``. +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the stack checker is +enabled. + +.. rubric:: NOTES: + +The stack checker performs run-time stack bounds checking. This increases +the time required to create tasks as well as adding overhead to each context +switch. + +In 4.9 and older, this configuration option was named ``STACK_CHECKER_ON``. + +.. Generated from spec:/acfg/if/ticks-per-time-slice + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_TICKS_PER_TIMESLICE .. index:: ticks per timeslice @@ -635,26 +991,42 @@ NOTES: CONFIGURE_TICKS_PER_TIMESLICE ----------------------------- -CONSTANT: - ``CONFIGURE_TICKS_PER_TIMESLICE`` +.. rubric:: CONSTANT: + +``CONFIGURE_TICKS_PER_TIMESLICE`` -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: OPTION TYPE: -DEFAULT VALUE: - The default value is 50. +This configuration option is an integer define. -VALUE CONSTRAINTS: - The value of this configuration option shall be greater than or equal to 0 - and less than or equal to ``UINT32_MAX``. +.. rubric:: DEFAULT VALUE: -DESCRIPTION: - The value of this configuration option defines the length of the timeslice - quantum in ticks for each task. +The default value is 50. -NOTES: - This configuration option has no impact if the Clock Driver is not - configured, see :ref:`CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`. +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the length of the timeslice +quantum in ticks for each task. + +.. rubric:: NOTES: + +This configuration option has no impact if the Clock Driver is not +configured, see :ref:`CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to one. + +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. + +.. Generated from spec:/acfg/if/unified-work-areas + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_UNIFIED_WORK_AREAS .. index:: unified work areas @@ -667,30 +1039,41 @@ NOTES: CONFIGURE_UNIFIED_WORK_AREAS ---------------------------- -CONSTANT: - ``CONFIGURE_UNIFIED_WORK_AREAS`` +.. rubric:: CONSTANT: + +``CONFIGURE_UNIFIED_WORK_AREAS`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then there will be separate memory +pools for the RTEMS Workspace and C Program Heap. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is a boolean feature define. +In case this configuration option is defined, then the RTEMS Workspace and +the C Program Heap will be one pool of memory. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then there will be separate memory - pools for the RTEMS Workspace and C Program Heap. +.. rubric:: NOTES: -DESCRIPTION: - In case this configuration option is defined, then the RTEMS Workspace and - the C Program Heap will be one pool of memory. +Having separate pools does have some advantages in the event a task blows a +stack or writes outside its memory area. However, in low memory systems the +overhead of the two pools plus the potential for unused memory in either +pool is very undesirable. -NOTES: - Having separate pools does have some advantages in the event a task blows a - stack or writes outside its memory area. However, in low memory systems the - overhead of the two pools plus the potential for unused memory in either - pool is very undesirable. +In high memory environments, this is desirable when you want to use the +:ref:`ConfigUnlimitedObjects` option. You will be able to create objects +until you run out of all available memory rather then just until you run out +of RTEMS Workspace. - In high memory environments, this is desirable when you want to use the - :ref:`ConfigUnlimitedObjects` option. You will be able to create objects - until you run out of all available memory rather then just until you run out - of RTEMS Workspace. +.. Generated from spec:/acfg/if/unlimited-allocation-size + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_UNLIMITED_ALLOCATION_SIZE @@ -699,31 +1082,43 @@ NOTES: CONFIGURE_UNLIMITED_ALLOCATION_SIZE ----------------------------------- -CONSTANT: - ``CONFIGURE_UNLIMITED_ALLOCATION_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_UNLIMITED_ALLOCATION_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 8. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is an integer define. +If :ref:`CONFIGURE_UNLIMITED_OBJECTS` is defined, then the value of this +configuration option defines the default objects maximum of all object +classes supporting :ref:`ConfigUnlimitedObjects` to +``rtems_resource_unlimited( CONFIGURE_UNLIMITED_ALLOCATION_SIZE )``. -DEFAULT VALUE: - The default value is 8. +.. rubric:: NOTES: -VALUE CONSTRAINTS: - The value of this configuration option shall meet the constraints of all - object classes to which it is applied. +By allowing users to declare all resources as being unlimited the user can +avoid identifying and limiting the resources used. -DESCRIPTION: - If :ref:`CONFIGURE_UNLIMITED_OBJECTS` is defined, then the value of this - configuration option defines the default objects maximum of all object - classes supporting :ref:`ConfigUnlimitedObjects` to - ``rtems_resource_unlimited(CONFIGURE_UNLIMITED_ALLOCATION_SIZE)``. +The object maximum of each class can be configured also individually using +the :ref:`InterfaceRtemsResourceUnlimited` macro. -NOTES: - By allowing users to declare all resources as being unlimited the user can - avoid identifying and limiting the resources used. +.. rubric:: CONSTRAINTS: - The object maximum of each class can be configured also individually using - the :c:func:`rtems_resource_unlimited` macro. +The value of the configuration option shall meet the constraints of all object +classes to which it is applied. + +.. Generated from spec:/acfg/if/unlimited-objects + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_UNLIMITED_OBJECTS @@ -732,29 +1127,40 @@ NOTES: CONFIGURE_UNLIMITED_OBJECTS --------------------------- -CONSTANT: - ``CONFIGURE_UNLIMITED_OBJECTS`` +.. rubric:: CONSTANT: + +``CONFIGURE_UNLIMITED_OBJECTS`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DESCRIPTION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +In case this configuration option is defined, then unlimited objects are used +by default. -DESCRIPTION: - In case this configuration option is defined, then unlimited objects are used - by default. +.. rubric:: NOTES: -NOTES: - When using unlimited objects, it is common practice to also specify - :ref:`CONFIGURE_UNIFIED_WORK_AREAS` so the system operates with a single pool - of memory for both RTEMS Workspace and C Program Heap. +When using unlimited objects, it is common practice to also specify +:ref:`CONFIGURE_UNIFIED_WORK_AREAS` so the system operates with a single pool +of memory for both RTEMS Workspace and C Program Heap. - This option does not override an explicit configuration for a particular - object class by the user. +This option does not override an explicit configuration for a particular +object class by the user. - See also :ref:`CONFIGURE_UNLIMITED_ALLOCATION_SIZE`. +See also :ref:`CONFIGURE_UNLIMITED_ALLOCATION_SIZE`. + +.. Generated from spec:/acfg/if/verbose-system-init + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_VERBOSE_SYSTEM_INITIALIZATION @@ -763,23 +1169,34 @@ NOTES: CONFIGURE_VERBOSE_SYSTEM_INITIALIZATION --------------------------------------- -CONSTANT: - ``CONFIGURE_VERBOSE_SYSTEM_INITIALIZATION`` +.. rubric:: CONSTANT: + +``CONFIGURE_VERBOSE_SYSTEM_INITIALIZATION`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DESCRIPTION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +In case this configuration option is defined, then the system initialization +is verbose. -DESCRIPTION: - In case this configuration option is defined, then the system initialization - is verbose. +.. rubric:: NOTES: -NOTES: - You may use this feature to debug system initialization issues. The - :c:func:`printk` function is used to print the information. +You may use this feature to debug system initialization issues. The +:ref:`InterfacePrintk` function is used to print the information. + +.. Generated from spec:/acfg/if/zero-workspace-automatically + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY .. index:: clear C Program Heap @@ -792,23 +1209,28 @@ NOTES: CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY -------------------------------------- -CONSTANT: - ``CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY`` +.. rubric:: CONSTANT: + +``CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DESCRIPTION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +In case this configuration option is defined, then the memory areas used for +the RTEMS Workspace and the C Program Heap are zeroed with a ``0x00`` byte +pattern during system initialization. -DESCRIPTION: - In case this configuration option is defined, then the memory areas used for - the RTEMS Workspace and the C Program Heap are zeroed with a ``0x00`` byte - pattern during system initialization. +.. rubric:: NOTES: -NOTES: - Zeroing memory can add significantly to the system initialization time. It is - not necessary for RTEMS but is often assumed by support libraries. In case - :ref:`CONFIGURE_DIRTY_MEMORY` is also defined, then the memory is first - dirtied and then zeroed. +Zeroing memory can add significantly to the system initialization time. It is +not necessary for RTEMS but is often assumed by support libraries. In case +:ref:`CONFIGURE_DIRTY_MEMORY` is also defined, then the memory is first +dirtied and then zeroed. diff --git a/c-user/config/idle-task.rst b/c-user/config/idle-task.rst index 12e7f46..793fb5c 100644 --- a/c-user/config/idle-task.rst +++ b/c-user/config/idle-task.rst @@ -1,13 +1,36 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020, 2022 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/acfg/if/group-idle + Idle Task Configuration ======================= This section describes configuration options related to the idle tasks. +.. Generated from spec:/acfg/if/idle-task-body + +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_IDLE_TASK_BODY .. _CONFIGURE_IDLE_TASK_BODY: @@ -15,30 +38,50 @@ This section describes configuration options related to the idle tasks. CONFIGURE_IDLE_TASK_BODY ------------------------ -CONSTANT: - ``CONFIGURE_IDLE_TASK_BODY`` +.. rubric:: CONSTANT: + +``CONFIGURE_IDLE_TASK_BODY`` + +.. rubric:: OPTION TYPE: + +This configuration option is an initializer define. + +.. rubric:: DEFAULT VALUE: + +If the :ref:`CONFIGURE_DISABLE_BSP_SETTINGS` configuration option is not defined and +:c:macro:`BSP_IDLE_TASK_BODY` is provided by the +:term:`BSP`, then the default value is defined by +:c:macro:`BSP_IDLE_TASK_BODY`, otherwise the default value is +``_CPU_Thread_Idle_body``. + +.. rubric:: DESCRIPTION: + +The value of this configuration option initializes the IDLE thread body. + +.. rubric:: NOTES: + +IDLE threads shall not block. A blocking IDLE thread results in undefined +system behaviour because the scheduler assume that at least one ready thread +exists. -OPTION TYPE: - This configuration option is an initializer define. +IDLE threads can be used to initialize the application, see configuration +option :ref:`CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION`. -DEFAULT VALUE: - If :ref:`BSP_IDLE_TASK_BODY` is defined, then this will be the default value, - otherwise the default value is ``_CPU_Thread_Idle_body``. +The BSP may have knowledge of the specific CPU model, system controller +logic, and peripheral buses, so a BSP-specific IDLE task may be capable of +turning components off to save power during extended periods of no task +activity. -VALUE CONSTRAINTS: - The value of this configuration option shall be defined to a valid function - pointer of the type ``void *( *idle_body )( uintptr_t )``. +.. rubric:: CONSTRAINTS: -DESCRIPTION: - The value of this configuration option initializes the IDLE thread body. +The value of the configuration option shall be defined to a valid function +pointer of the type ``void *( *idle_body )( uintptr_t )``. -NOTES: - IDLE threads shall not block. A blocking IDLE thread results in undefined - system behaviour because the scheduler assume that at least one ready thread - exists. +.. Generated from spec:/acfg/if/idle-task-init-appl - IDLE threads can be used to initialize the application, see configuration - option :ref:`CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION`. +.. raw:: latex + + \clearpage .. index:: CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION @@ -47,44 +90,58 @@ NOTES: CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION ------------------------------------------- -CONSTANT: - ``CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION`` +.. rubric:: CONSTANT: + +``CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the user is assumed to +provide one or more initialization tasks. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is defined to indicate that the user has configured +**no** user initialization tasks or threads and that the user provided IDLE +task will perform application initialization and then transform itself into +an IDLE task. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the user is assumed to - provide one or more initialization tasks. +.. rubric:: NOTES: -DESCRIPTION: - This configuration option is defined to indicate that the user has configured - **no** user initialization tasks or threads and that the user provided IDLE - task will perform application initialization and then transform itself into - an IDLE task. +If you use this option be careful, the user IDLE task **cannot** block at all +during the initialization sequence. Further, once application +initialization is complete, it shall make itself preemptible and enter an idle +body loop. -NOTES: - If you use this option be careful, the user IDLE task **cannot** block at all - during the initialization sequence. Further, once application - initialization is complete, it shall make itself preemptible and enter an idle - body loop. +The IDLE task shall run at the lowest priority of all tasks in the system. - The IDLE task shall run at the lowest priority of all tasks in the system. +If this configuration option is defined, then it is mandatory to configure a +user IDLE task with the :ref:`CONFIGURE_IDLE_TASK_BODY` configuration option, +otherwise a compile time error in the configuration file will occur. - If this configuration option is defined, then it is mandatory to configure a - user IDLE task with the :ref:`CONFIGURE_IDLE_TASK_BODY` configuration option, - otherwise a compile time error in the configuration file will occur. +The application shall define at least one of the following configuration +options - The application shall define exactly one of the following configuration - options +* :ref:`CONFIGURE_RTEMS_INIT_TASKS_TABLE`, - * :ref:`CONFIGURE_RTEMS_INIT_TASKS_TABLE`, +* :ref:`CONFIGURE_POSIX_INIT_THREAD_TABLE`, or - * :ref:`CONFIGURE_POSIX_INIT_THREAD_TABLE`, or +* ``CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION`` - * `CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION` +otherwise a compile time error in the configuration file will occur. - otherwise a compile time error in the configuration file will occur. +If no Classic API initialization task and no POSIX API initialization thread +is configured, then no :ref:`GlobalConstruction` is performed. + +.. Generated from spec:/acfg/if/idle-task-stack-size + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_IDLE_TASK_STACK_SIZE @@ -93,30 +150,111 @@ NOTES: CONFIGURE_IDLE_TASK_STACK_SIZE ------------------------------ -CONSTANT: - ``CONFIGURE_IDLE_TASK_STACK_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_IDLE_TASK_STACK_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +If the :ref:`CONFIGURE_DISABLE_BSP_SETTINGS` configuration option is not defined and +:c:macro:`BSP_IDLE_TASK_STACK_SIZE` is provided by the +:term:`BSP`, then the default value is defined by +:c:macro:`BSP_IDLE_TASK_STACK_SIZE`, otherwise the default value is +defined by the :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE` configuration option. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the task stack size for an +IDLE task. + +.. rubric:: NOTES: + +In SMP configurations, there is one IDLE task per configured processor, see +:ref:`CONFIGURE_MAXIMUM_PROCESSORS`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to a + BSP-specific and application-specific minimum value. + +* The value of the configuration option shall be small enough so that the IDLE + task stack area calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `size_t + <https://en.cppreference.com/w/c/types/size_t>`_. + +.. Generated from spec:/acfg/if/idle-task-storage-size + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_IDLE_TASK_STORAGE_SIZE +.. index:: IDLE task storage size + +.. _CONFIGURE_IDLE_TASK_STORAGE_SIZE: + +CONFIGURE_IDLE_TASK_STORAGE_SIZE +-------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_IDLE_TASK_STORAGE_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +This configuration option has no default value. If it is not specified, then +the task storage area for each :term:`IDLE task` will allocated +from the RTEMS Workspace or through a custom IDLE task stack allocator. + +.. rubric:: DESCRIPTION: + +If this configuration option is specified, then the task storage areas for +the :term:`IDLE tasks <IDLE task>` are statically allocated by +``<rtems/confdefs.h>``. The value of this configuration option defines the +size in bytes of the task storage area of each IDLE task in the system. + +.. rubric:: NOTES: + +By default, the IDLE task storage areas are allocated from the RTEMS +Workspace. Applications which do not want to use a heap allocator can use +this configuration option to use statically allocated memory for the IDLE +task storage areas. The task storage area contains the task stack, the +thread-local storage, and the floating-point context on architectures with a +separate floating-point context. The size of the thread-local storage area +is defined at link time or by the :ref:`CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE` +configuration option. You have to estimate the actual thread-local storage +size if you want to use this configuration option. If the IDLE task stack +size would be less than the value defined by the +:ref:`CONFIGURE_IDLE_TASK_STACK_SIZE` configuration option, for example because the +thread-local storage size is larger than expected, then the system terminates +with the :ref:`INTERNAL_ERROR_CORE <FatalErrorSources>` fatal source and the +:ref:`INTERNAL_ERROR_IDLE_THREAD_STACK_TOO_SMALL <internal_errors>` fatal code during +system initialization. -OPTION TYPE: - This configuration option is an integer define. +The value of this configuration option is passed to +:ref:`InterfaceRTEMSTASKSTORAGESIZE` by ``<rtems/confdefs.h>`` to determine +the actual size of the statically allocated area to take +architecture-specific overheads into account. -DEFAULT VALUE: - The default value is :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. +The -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +* ``CONFIGURE_IDLE_TASK_STORAGE_SIZE``, and - * It shall be greater than or equal to a - BSP-specific and application-specific minimum value. +* :ref:`CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE` - * It shall be small enough so that the IDLE - task stack area calculation carried out by ``<rtems/confdefs.h>`` does not - overflow an integer of type ``size_t``. +configuration options are mutually exclusive. -DESCRIPTION: - The value of this configuration option defines the task stack size for an - IDLE task. +.. rubric:: CONSTRAINTS: -NOTES: - In SMP configurations, there is one IDLE task per configured processor, see - :ref:`CONFIGURE_MAXIMUM_PROCESSORS`. +The value of the configuration option shall be greater than or equal to +:ref:`CONFIGURE_IDLE_TASK_STACK_SIZE`. diff --git a/c-user/config/index.rst b/c-user/config/index.rst index b0e21a4..b669ea2 100644 --- a/c-user/config/index.rst +++ b/c-user/config/index.rst @@ -10,6 +10,7 @@ Configuring a System .. toctree:: + introduction intro general device-driver @@ -24,8 +25,9 @@ Configuring a System idle-task scheduler-general scheduler-clustered - bsp-related + face-technical-standard mpci libpci ada + directives obsolete diff --git a/c-user/config/intro.rst b/c-user/config/intro.rst index 4c2f715..eb9c4c1 100644 --- a/c-user/config/intro.rst +++ b/c-user/config/intro.rst @@ -3,49 +3,6 @@ .. Copyright (C) 2012 Gedare Bloom .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) -Introduction -============ - -RTEMS must be configured for an application. This configuration encompasses a -variety of information including the length of each clock tick, the maximum -number of each information RTEMS object that can be created, the application -initialization tasks, the task scheduling algorithm to be used, and the device -drivers in the application. - -Although this information is contained in data structures that are used by -RTEMS at system initialization time, the data structures themselves must not be -generated by hand. RTEMS provides a set of macros system which provides a -simple standard mechanism to automate the generation of these structures. - -.. index:: confdefs.h -.. index:: <rtems/confdefs.h> - -The RTEMS header file ``<rtems/confdefs.h>`` is at the core of the automatic -generation of system configuration. It is based on the idea of setting macros -which define configuration parameters of interest to the application and -defaulting or calculating all others. This variety of macros can automatically -produce all of the configuration data required for an RTEMS application. - -.. sidebar: Trivia: - - The term ``confdefs`` is shorthand for a *Configuration Defaults*. - -As a general rule, application developers only specify values for the -configuration parameters of interest to them. They define what resources or -features they require. In most cases, when a parameter is not specified, it -defaults to zero (0) instances, a standards compliant value, or disabled as -appropriate. For example, by default there will be 256 task priority levels but -this can be lowered by the application. This number of priority levels is -required to be compliant with the RTEID/ORKID standards upon which the Classic -API is based. There are similar cases where the default is selected to be -compliant with the POSIX standard. - -For each configuration parameter in the configuration tables, the macro -corresponding to that field is discussed. The RTEMS Maintainers expect that all -systems can be easily configured using the ``<rtems/confdefs.h>`` mechanism and -that using this mechanism will avoid internal RTEMS configuration changes -impacting applications. - Default Value Selection Philosophy ================================== @@ -71,9 +28,9 @@ automatically. It assumes that all tasks are floating point and that all will be allocated the minimum stack space. This calculation includes the amount of memory that will be allocated for internal use by RTEMS. The automatic calculation may underestimate the workspace size truly needed by the -application, in which case one can use the ``CONFIGURE_MEMORY_OVERHEAD`` macro -to add a value to the estimate. See :ref:`Specify Memory Overhead` for more -details. +application, in which case one can use the :ref:`CONFIGURE_MEMORY_OVERHEAD` +macro to add a value to the estimate. See :ref:`Specify Memory Overhead` for +more details. The memory area for the RTEMS Workspace is determined by the BSP. In case the RTEMS Workspace is too large for the available memory, then a fatal run-time @@ -83,8 +40,8 @@ The file ``<rtems/confdefs.h>`` will calculate the value of the ``work_space_size`` parameter of the Configuration Table. There are many parameters the application developer can specify to help ``<rtems/confdefs.h>`` in its calculations. Correctly specifying the application requirements via -parameters such as ``CONFIGURE_EXTRA_TASK_STACKS`` and -``CONFIGURE_MAXIMUM_TASKS`` is critical for production software. +parameters such as :ref:`CONFIGURE_EXTRA_TASK_STACKS` and +:ref:`CONFIGURE_MAXIMUM_TASKS` is critical for production software. For each class of objects, the allocation can operate in one of two ways. The default way has an ceiling on the maximum number of object instances which can @@ -176,44 +133,45 @@ milliseconds is as follows: In this example, only a few configuration parameters are specified. The impact of these are as follows: -- The example specified ``CONFIGURE_RTEMS_INIT_TASK_TABLE`` but did not specify - any additional parameters. This results in a configuration of an application - which will begin execution of a single initialization task named ``Init`` - which is non-preemptible and at priority one (1). - -- By specifying ``CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER``, this application - is configured to have a clock tick device driver. Without a clock tick device - driver, RTEMS has no way to know that time is passing and will be unable to - support delays and wall time. Further configuration details about time are - provided. Per ``CONFIGURE_MICROSECONDS_PER_TICK`` and - ``CONFIGURE_TICKS_PER_TIMESLICE``, the user specified they wanted a clock +- The example specified :ref:`CONFIGURE_RTEMS_INIT_TASKS_TABLE` but did not + specify any additional parameters. This results in a configuration of an + application which will begin execution of a single initialization task named + ``Init`` which is non-preemptible and at priority one (1). + +- By specifying :ref:`CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER`, this + application is configured to have a clock tick device driver. Without a clock + tick device driver, RTEMS has no way to know that time is passing and will be + unable to support delays and wall time. Further configuration details about + time are provided. Per :ref:`CONFIGURE_MICROSECONDS_PER_TICK` and + :ref:`CONFIGURE_TICKS_PER_TIMESLICE`, the user specified they wanted a clock tick to occur each millisecond, and that the length of a timeslice would be fifty (50) milliseconds. -- By specifying ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER``, the application - will include a console device driver. Although the console device driver may - support a combination of multiple serial ports and display and keyboard - combinations, it is only required to provide a single device named +- By specifying :ref:`CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`, the + application will include a console device driver. Although the console device + driver may support a combination of multiple serial ports and display and + keyboard combinations, it is only required to provide a single device named ``/dev/console``. This device will be used for Standard Input, Output and - Error I/O Streams. Thus when ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`` - is specified, implicitly three (3) file descriptors are reserved for the - Standard I/O Streams and those file descriptors are associated with - ``/dev/console`` during initialization. All console devices are expected to - support the POSIX*termios* interface. - -- The example above specifies via ``CONFIGURE_MAXIMUM_TASKS`` that the + Error I/O Streams. Thus when + :ref:`CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER` is specified, implicitly + three (3) file descriptors are reserved for the Standard I/O Streams and + those file descriptors are associated with ``/dev/console`` during + initialization. All console devices are expected to support the + POSIX*termios* interface. + +- The example above specifies via :ref:`CONFIGURE_MAXIMUM_TASKS` that the application requires a maximum of four (4) simultaneously existing Classic - API tasks. Similarly, by specifying ``CONFIGURE_MAXIMUM_MESSAGE_QUEUES``, + API tasks. Similarly, by specifying :ref:`CONFIGURE_MAXIMUM_MESSAGE_QUEUES`, there may be a maximum of only one (1) concurrently existent Classic API message queues. - The most surprising configuration parameter in this example is the use of - ``CONFIGURE_MESSAGE_BUFFER_MEMORY``. Message buffer memory is allocated from - the RTEMS Workspace and must be accounted for. In this example, the single - message queue will have up to twenty (20) messages of type ``struct + :ref:`CONFIGURE_MESSAGE_BUFFER_MEMORY`. Message buffer memory is allocated + from the RTEMS Workspace and must be accounted for. In this example, the + single message queue will have up to twenty (20) messages of type ``struct USER_MESSAGE``. -- The ``CONFIGURE_INIT`` constant must be defined in order to make +- The :ref:`CONFIGURE_INIT` constant must be defined in order to make ``<rtems/confdefs.h>`` instantiate the configuration data structures. This can only be defined in one source file per application that includes ``<rtems/confdefs.h>`` or the symbol table will be instantiated multiple @@ -321,8 +279,6 @@ generally considered a safer embedded systems programming practice to know the system limits rather than experience an out of memory error at an arbitrary and largely unpredictable time in the field. -.. index:: rtems_resource_unlimited - .. _ConfigUnlimitedObjectsClass: Unlimited Objects by Class @@ -330,7 +286,7 @@ Unlimited Objects by Class When the number of objects is not known ahead of time, RTEMS provides an auto-extending mode that can be enabled individually for each object type by -using the macro ``rtems_resource_unlimited``. This takes a value as a +using the macro :ref:`InterfaceRtemsResourceUnlimited`. This takes a value as a parameter, and is used to set the object maximum number field in an API Configuration table. The value is an allocation unit size. When RTEMS is required to grow the object table it is grown by this size. The kernel will @@ -338,18 +294,15 @@ return the object memory back to the RTEMS Workspace when an object is destroyed. The kernel will only return an allocated block of objects to the RTEMS Workspace if at least half the allocation size of free objects remain allocated. RTEMS always keeps one allocation block of objects allocated. Here -is an example of using ``rtems_resource_unlimited``: +is an example of using :c:func:`rtems_resource_unlimited`: .. code-block:: c - #define CONFIGURE_MAXIMUM_TASKS rtems_resource_unlimited(5) - -.. index:: rtems_resource_is_unlimited -.. index:: rtems_resource_maximum_per_allocation + #define CONFIGURE_MAXIMUM_TASKS rtems_resource_unlimited( 5 ) Object maximum specifications can be evaluated with the -``rtems_resource_is_unlimited`` and``rtems_resource_maximum_per_allocation`` -macros. +:ref:`InterfaceRtemsResourceIsUnlimited` and +:ref:`InterfaceRtemsResourceMaximumPerAllocation` macros. .. _ConfigUnlimitedObjectsDefault: diff --git a/c-user/config/introduction.rst b/c-user/config/introduction.rst new file mode 100644 index 0000000..8852a24 --- /dev/null +++ b/c-user/config/introduction.rst @@ -0,0 +1,227 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2009, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2021 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/rtems/config/if/group + +.. _ApplicationConfigurationInformationIntroduction: + +Introduction +============ + +.. The following list was generated from: +.. spec:/rtems/config/if/get-build-label +.. spec:/rtems/config/if/get-copyright-notice +.. spec:/rtems/config/if/get-target-hash +.. spec:/rtems/config/if/get-version-string +.. spec:/rtems/config/if/get-do-zero-of-workspace +.. spec:/rtems/config/if/get-idle-task-stack-size +.. spec:/rtems/config/if/get-idle-task +.. spec:/rtems/config/if/get-interrupt-stack-size +.. spec:/rtems/config/if/get-maximum-barriers +.. spec:/rtems/config/if/get-maximum-extensions +.. spec:/rtems/config/if/get-maximum-message-queues +.. spec:/rtems/config/if/get-maximum-partitions +.. spec:/rtems/config/if/get-maximum-periods +.. spec:/rtems/config/if/get-maximum-ports +.. spec:/rtems/config/if/get-maximum-processors +.. spec:/rtems/config/if/get-maximum-regions +.. spec:/rtems/config/if/get-maximum-semaphores +.. spec:/rtems/config/if/get-maximum-tasks +.. spec:/rtems/config/if/get-maximum-timers +.. spec:/rtems/config/if/get-microseconds-per-tick +.. spec:/rtems/config/if/get-milliseconds-per-tick +.. spec:/rtems/config/if/get-nanoseconds-per-tick +.. spec:/rtems/config/if/get-number-of-initial-extensions +.. spec:/rtems/config/if/get-stack-allocate-for-idle-hook +.. spec:/rtems/config/if/get-stack-allocate-hook +.. spec:/rtems/config/if/get-stack-allocate-init-hook +.. spec:/rtems/config/if/get-stack-allocator-avoids-work-space +.. spec:/rtems/config/if/get-stack-free-hook +.. spec:/rtems/config/if/get-stack-space-size +.. spec:/rtems/config/if/get-ticks-per-timeslice +.. spec:/rtems/config/if/get-unified-work-area +.. spec:/rtems/config/if/get-user-extension-table +.. spec:/rtems/config/if/get-user-multiprocessing-table +.. spec:/rtems/config/if/get-work-space-size +.. spec:/rtems/config/if/get-api-configuration +.. spec:/rtems/config/if/resource-is-unlimited +.. spec:/rtems/config/if/resource-maximum-per-allocation +.. spec:/rtems/config/if/resource-unlimited + +The application configuration information group provides an API to get the +configuration of an application. + +RTEMS must be configured for an application. This configuration encompasses a +variety of information including the length of each clock tick, the maximum +number of each information RTEMS object that can be created, the application +initialization tasks, the task scheduling algorithm to be used, and the device +drivers in the application. + +Although this information is contained in data structures that are used by +RTEMS at system initialization time, the data structures themselves must not be +generated by hand. RTEMS provides a set of macros system which provides a +simple standard mechanism to automate the generation of these structures. + +The RTEMS header file ``<rtems/confdefs.h>`` is at the core of the automatic +generation of system configuration. It is based on the idea of setting macros +which define configuration parameters of interest to the application and +defaulting or calculating all others. This variety of macros can automatically +produce all of the configuration data required for an RTEMS application. The +term ``confdefs`` is shorthand for a *Configuration Defaults*. + +As a general rule, application developers only specify values for the +configuration parameters of interest to them. They define what resources or +features they require. In most cases, when a parameter is not specified, it +defaults to zero (0) instances, a standards compliant value, or disabled as +appropriate. For example, by default there will be 256 task priority levels but +this can be lowered by the application. This number of priority levels is +required to be compliant with the RTEID/ORKID standards upon which the Classic +API is based. There are similar cases where the default is selected to be +compliant with the POSIX standard. + +For each configuration parameter in the configuration tables, the macro +corresponding to that field is discussed. The RTEMS Maintainers expect that all +systems can be easily configured using the ``<rtems/confdefs.h>`` mechanism and +that using this mechanism will avoid internal RTEMS configuration changes +impacting applications. + +Some application configuration settings and other system parameters can be +queried by the application. The directives provided by the Application +Configuration Information are: + +* :ref:`InterfaceRtemsGetBuildLabel` - Gets the RTEMS build label. + +* :ref:`InterfaceRtemsGetCopyrightNotice` - Gets the RTEMS copyright notice. + +* :ref:`InterfaceRtemsGetTargetHash` - Gets the RTEMS target hash. + +* :ref:`InterfaceRtemsGetVersionString` - Gets the RTEMS version string. + +* :ref:`InterfaceRtemsConfigurationGetDoZeroOfWorkspace` - Indicates if the + RTEMS Workspace is configured to be zeroed during system initialization for + this application. + +* :ref:`InterfaceRtemsConfigurationGetIdleTaskStackSize` - Gets the IDLE task + stack size in bytes of this application. + +* :ref:`InterfaceRtemsConfigurationGetIdleTask` - Gets the IDLE task body of + this application. + +* :ref:`InterfaceRtemsConfigurationGetInterruptStackSize` - Gets the interrupt + stack size in bytes of this application. + +* :ref:`InterfaceRtemsConfigurationGetMaximumBarriers` - Gets the resource + number of :ref:`RTEMSAPIClassicBarrier` objects configured for this + application. + +* :ref:`InterfaceRtemsConfigurationGetMaximumExtensions` - Gets the resource + number of :ref:`RTEMSAPIClassicUserExt` objects configured for this + application. + +* :ref:`InterfaceRtemsConfigurationGetMaximumMessageQueues` - Gets the resource + number of :ref:`RTEMSAPIClassicMessage` objects configured for this + application. + +* :ref:`InterfaceRtemsConfigurationGetMaximumPartitions` - Gets the resource + number of :ref:`RTEMSAPIClassicPart` objects configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetMaximumPeriods` - Gets the resource + number of :ref:`RTEMSAPIClassicRatemon` objects configured for this + application. + +* :ref:`InterfaceRtemsConfigurationGetMaximumPorts` - Gets the resource number + of :ref:`RTEMSAPIClassicDPMem` objects configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetMaximumProcessors` - Gets the maximum + number of processors configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetMaximumRegions` - Gets the resource + number of :ref:`RTEMSAPIClassicRegion` objects configured for this + application. + +* :ref:`InterfaceRtemsConfigurationGetMaximumSemaphores` - Gets the resource + number of :ref:`RTEMSAPIClassicSem` objects configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetMaximumTasks` - Gets the resource number + of :ref:`RTEMSAPIClassicTasks` objects configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetMaximumTimers` - Gets the resource number + of :ref:`RTEMSAPIClassicTimer` objects configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetMicrosecondsPerTick` - Gets the number of + microseconds per clock tick configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetMillisecondsPerTick` - Gets the number of + milliseconds per clock tick configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetNanosecondsPerTick` - Gets the number of + microseconds per clock tick configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetNumberOfInitialExtensions` - Gets the + number of initial extensions configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetStackAllocateForIdleHook` - Gets the task + stack allocator allocate hook used to allocate the stack of each :term:`IDLE + task` configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetStackAllocateHook` - Gets the task stack + allocator allocate hook configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetStackAllocateInitHook` - Gets the task + stack allocator initialization hook configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetStackAllocatorAvoidsWorkSpace` - + Indicates if the task stack allocator is configured to avoid the RTEMS + Workspace for this application. + +* :ref:`InterfaceRtemsConfigurationGetStackFreeHook` - Gets the task stack + allocator free hook configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetStackSpaceSize` - Gets the configured + size in bytes of the memory space used to allocate thread stacks for this + application. + +* :ref:`InterfaceRtemsConfigurationGetTicksPerTimeslice` - Gets the clock ticks + per timeslice configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetUnifiedWorkArea` - Indicates if the RTEMS + Workspace and C Program Heap are configured to be unified for this + application. + +* :ref:`InterfaceRtemsConfigurationGetUserExtensionTable` - Gets the initial + extensions table configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetUserMultiprocessingTable` - Gets the MPCI + configuration table configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetWorkSpaceSize` - Gets the RTEMS Workspace + size in bytes configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetRtemsApiConfiguration` - Gets the Classic + API Configuration Table of this application. + +* :ref:`InterfaceRtemsResourceIsUnlimited` - Indicates if the resource is + unlimited. + +* :ref:`InterfaceRtemsResourceMaximumPerAllocation` - Gets the maximum number + per allocation of a resource number. + +* :ref:`InterfaceRtemsResourceUnlimited` - Augments the resource number so that + it indicates an unlimited resource. diff --git a/c-user/config/mpci.rst b/c-user/config/mpci.rst index 854600b..ab9d568 100644 --- a/c-user/config/mpci.rst +++ b/c-user/config/mpci.rst @@ -1,82 +1,130 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2022 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/acfg/if/group-mpci Multiprocessing Configuration ============================= -This section describes multiprocessing related configuration options. The -options are only used if RTEMS was built with the ``--enable-multiprocessing`` -build configuration option. Additionally, this class of configuration options -are only applicable if the configuration option :ref:`CONFIGURE_MP_APPLICATION` -is defined. The multiprocessing (MPCI) support must not be confused with the -SMP support. +This section describes multiprocessing related configuration options. +The options are only used if RTEMS was built when the multiprocessing +build configuration option is enabled. The multiprocessing configuration +is distinct from the SMP configuration. Additionally, this class of +configuration options are only applicable if the configuration option +:ref:`CONFIGURE_MP_APPLICATION` is defined. The multiprocessing (MPCI) +support must not be confused with the SMP support. -.. index:: CONFIGURE_MP_APPLICATION +.. Generated from spec:/acfg/if/mp-extra-server-stack -.. _CONFIGURE_MP_APPLICATION: +.. raw:: latex -CONFIGURE_MP_APPLICATION ------------------------- + \clearpage -CONSTANT: - ``CONFIGURE_MP_APPLICATION`` +.. index:: CONFIGURE_EXTRA_MPCI_RECEIVE_SERVER_STACK -OPTION TYPE: - This configuration option is a boolean feature define. +.. _CONFIGURE_EXTRA_MPCI_RECEIVE_SERVER_STACK: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the multiprocessing services - are not initialized. +CONFIGURE_EXTRA_MPCI_RECEIVE_SERVER_STACK +----------------------------------------- -DESCRIPTION: - This configuration option is defined to indicate that the application intends - to be part of a multiprocessing configuration. Additional configuration - options are assumed to be provided. +.. rubric:: CONSTANT: -NOTES: - This configuration option shall be undefined if the multiprocessing support - is not enabled (e.g. RTEMS was built without the ``--enable-multiprocessing`` - build configuration option). Otherwise a compile time error in the - configuration file will occur. +``CONFIGURE_EXTRA_MPCI_RECEIVE_SERVER_STACK`` -.. index:: CONFIGURE_EXTRA_MPCI_RECEIVE_SERVER_STACK +.. rubric:: OPTION TYPE: -.. _CONFIGURE_EXTRA_MPCI_RECEIVE_SERVER_STACK: +This configuration option is an integer define. -CONFIGURE_EXTRA_MPCI_RECEIVE_SERVER_STACK ------------------------------------------ +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: -CONSTANT: - ``CONFIGURE_EXTRA_MPCI_RECEIVE_SERVER_STACK`` +The value of this configuration option defines the number of bytes the +applications wishes to add to the MPCI task stack on top of +:ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: NOTES: -DEFAULT VALUE: - The default value is 0. +This configuration option is only evaluated if +:ref:`CONFIGURE_MP_APPLICATION` is defined. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: CONSTRAINTS: - * It shall be greater than or equal to 0. +The following constraints apply to this configuration option: - * It shall be less than or equal to ``UINT32_MAX``. +* The value of the configuration option shall be greater than or equal to zero. - * It shall be small enough so that the - MPCI receive server stack area calculation carried out by - ``<rtems/confdefs.h>`` does not overflow an integer of type ``size_t``. +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. -DESCRIPTION: - The value of this configuration option defines the number of bytes the - applications wishes to add to the MPCI task stack on top of - :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. +* The value of the configuration option shall be small enough so that the MPCI + receive server stack area calculation carried out by ``<rtems/confdefs.h>`` + does not overflow an integer of type `size_t + <https://en.cppreference.com/w/c/types/size_t>`_. -NOTES: - This configuration option is only evaluated if - :ref:`CONFIGURE_MP_APPLICATION` is defined. +.. Generated from spec:/acfg/if/mp-appl + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_MP_APPLICATION + +.. _CONFIGURE_MP_APPLICATION: + +CONFIGURE_MP_APPLICATION +------------------------ + +.. rubric:: CONSTANT: + +``CONFIGURE_MP_APPLICATION`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the multiprocessing services +are not initialized. + +.. rubric:: DESCRIPTION: + +This configuration option is defined to indicate that the application intends +to be part of a multiprocessing configuration. Additional configuration +options are assumed to be provided. + +.. rubric:: NOTES: + +This configuration option shall be undefined if the multiprocessing support +is not enabled (e.g. RTEMS was built without the multiprocessing build +configuration option enabled). Otherwise a compile time error in the +configuration file will occur. + +.. Generated from spec:/acfg/if/mp-max-global-objects + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS @@ -85,29 +133,45 @@ NOTES: CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS ----------------------------------- -CONSTANT: - ``CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 32. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the maximum number of +concurrently active global objects in a multiprocessor system. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: NOTES: -DEFAULT VALUE: - The default value is 32. +This value corresponds to the total number of objects which can be created +with the :c:macro:`RTEMS_GLOBAL` attribute. -VALUE CONSTRAINTS: - The value of this configuration option shall be greater than or equal to 0 - and less than or equal to ``UINT32_MAX``. +This configuration option is only evaluated if +:ref:`CONFIGURE_MP_APPLICATION` is defined. -DESCRIPTION: - The value of this configuration option defines the maximum number of - concurrently active global objects in a multiprocessor system. +.. rubric:: CONSTRAINTS: -NOTES: - This value corresponds to the total number of objects which can be created - with the ``RTEMS_GLOBAL`` attribute. +The following constraints apply to this configuration option: - This configuration option is only evaluated if - :ref:`CONFIGURE_MP_APPLICATION` is defined. +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. + +.. Generated from spec:/acfg/if/mp-max-nodes + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_MP_MAXIMUM_NODES @@ -116,26 +180,42 @@ NOTES: CONFIGURE_MP_MAXIMUM_NODES -------------------------- -CONSTANT: - ``CONFIGURE_MP_MAXIMUM_NODES`` +.. rubric:: CONSTANT: + +``CONFIGURE_MP_MAXIMUM_NODES`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 2. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the maximum number of nodes in +a multiprocessor system. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: NOTES: -DEFAULT VALUE: - The default value is 2. +This configuration option is only evaluated if +:ref:`CONFIGURE_MP_APPLICATION` is defined. -VALUE CONSTRAINTS: - The value of this configuration option shall be greater than or equal to 0 - and less than or equal to ``UINT32_MAX``. +.. rubric:: CONSTRAINTS: -DESCRIPTION: - The value of this configuration option defines the maximum number of nodes in - a multiprocessor system. +The following constraints apply to this configuration option: -NOTES: - This configuration option is only evaluated if - :ref:`CONFIGURE_MP_APPLICATION` is defined. +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. + +.. Generated from spec:/acfg/if/mp-max-proxies + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_MP_MAXIMUM_PROXIES @@ -144,32 +224,48 @@ NOTES: CONFIGURE_MP_MAXIMUM_PROXIES ---------------------------- -CONSTANT: - ``CONFIGURE_MP_MAXIMUM_PROXIES`` +.. rubric:: CONSTANT: + +``CONFIGURE_MP_MAXIMUM_PROXIES`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 32. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the maximum number of +concurrently active thread/task proxies on this node in a multiprocessor +system. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: NOTES: -DEFAULT VALUE: - The default value is 32. +Since a proxy is used to represent a remote task/thread which is blocking +on this node. This configuration parameter reflects the maximum number of +remote tasks/threads which can be blocked on objects on this node, see +:ref:`MPCIProxies`. -VALUE CONSTRAINTS: - The value of this configuration option shall be greater than or equal to 0 - and less than or equal to ``UINT32_MAX``. +This configuration option is only evaluated if +:ref:`CONFIGURE_MP_APPLICATION` is defined. -DESCRIPTION: - The value of this configuration option defines the maximum number of - concurrently active thread/task proxies on this node in a multiprocessor - system. +.. rubric:: CONSTRAINTS: -NOTES: - Since a proxy is used to represent a remote task/thread which is blocking - on this node. This configuration parameter reflects the maximum number of - remote tasks/threads which can be blocked on objects on this node, see - :ref:`MPCIProxies`. +The following constraints apply to this configuration option: - This configuration option is only evaluated if - :ref:`CONFIGURE_MP_APPLICATION` is defined. +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. + +.. Generated from spec:/acfg/if/mp-mpci-table-pointer + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_MP_MPCI_TABLE_POINTER @@ -178,30 +274,42 @@ NOTES: CONFIGURE_MP_MPCI_TABLE_POINTER ------------------------------- -CONSTANT: - ``CONFIGURE_MP_MPCI_TABLE_POINTER`` +.. rubric:: CONSTANT: + +``CONFIGURE_MP_MPCI_TABLE_POINTER`` + +.. rubric:: OPTION TYPE: + +This configuration option is an initializer define. + +.. rubric:: DEFAULT VALUE: + +The default value is ``&MPCI_table``. + +.. rubric:: DESCRIPTION: + +The value of this configuration option initializes the MPCI Configuration +Table. -OPTION TYPE: - This configuration option is an initializer define. +.. rubric:: NOTES: -DEFAULT VALUE: - The default value is ``&MPCI_table``. +RTEMS provides a Shared Memory MPCI Device Driver which can be used on any +Multiprocessor System assuming the BSP provides the proper set of +supporting methods. -VALUE CONSTRAINTS: - The value of this configuration option shall be a pointer to - :c:type:`rtems_mpci_table`. +This configuration option is only evaluated if +:ref:`CONFIGURE_MP_APPLICATION` is defined. -DESCRIPTION: - The value of this configuration option initializes the MPCI Configuration - Table. +.. rubric:: CONSTRAINTS: -NOTES: - RTEMS provides a Shared Memory MPCI Device Driver which can be used on any - Multiprocessor System assuming the BSP provides the proper set of - supporting methods. +The value of the configuration option shall be a pointer to +:c:type:`rtems_mpci_table`. - This configuration option is only evaluated if - :ref:`CONFIGURE_MP_APPLICATION` is defined. +.. Generated from spec:/acfg/if/mp-node-number + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_MP_NODE_NUMBER @@ -210,28 +318,38 @@ NOTES: CONFIGURE_MP_NODE_NUMBER ------------------------ -CONSTANT: - ``CONFIGURE_MP_NODE_NUMBER`` +.. rubric:: CONSTANT: + +``CONFIGURE_MP_NODE_NUMBER`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is ``NODE_NUMBER``. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the node number of this node +in a multiprocessor system. + +.. rubric:: NOTES: -OPTION TYPE: - This configuration option is an integer define. +In the RTEMS Multiprocessing Test Suite, the node number is derived from +the Makefile variable ``NODE_NUMBER``. The same code is compiled with the +``NODE_NUMBER`` set to different values. The test programs behave +differently based upon their node number. -DEFAULT VALUE: - The default value is ``NODE_NUMBER``. +This configuration option is only evaluated if +:ref:`CONFIGURE_MP_APPLICATION` is defined. -VALUE CONSTRAINTS: - The value of this configuration option shall be greater than or equal to 0 - and less than or equal to ``UINT32_MAX``. +.. rubric:: CONSTRAINTS: -DESCRIPTION: - The value of this configuration option defines the node number of this node - in a multiprocessor system. +The following constraints apply to this configuration option: -NOTES: - In the RTEMS Multiprocessing Test Suite, the node number is derived from - the Makefile variable ``NODE_NUMBER``. The same code is compiled with the - ``NODE_NUMBER`` set to different values. The test programs behave - differently based upon their node number. +* The value of the configuration option shall be greater than or equal to zero. - This configuration option is only evaluated if - :ref:`CONFIGURE_MP_APPLICATION` is defined. +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. diff --git a/c-user/config/posix-api.rst b/c-user/config/posix-api.rst index 1359909..f788c08 100644 --- a/c-user/config/posix-api.rst +++ b/c-user/config/posix-api.rst @@ -1,16 +1,39 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2022 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/acfg/if/group-posix POSIX API Configuration ======================= This section describes configuration options related to the POSIX API. Most POSIX API objects are available by default since RTEMS 5.1. The queued signals -and timers are only available if RTEMS was built with the ``--enable-posix`` +and timers are only available if RTEMS was built with the enable POSIX build configuration option. +.. Generated from spec:/acfg/if/max-posix-keys + +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MAXIMUM_POSIX_KEYS .. _CONFIGURE_MAXIMUM_POSIX_KEYS: @@ -18,39 +41,50 @@ build configuration option. CONFIGURE_MAXIMUM_POSIX_KEYS ---------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_POSIX_KEYS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_POSIX_KEYS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the maximum number of POSIX +API Keys that can be concurrently active. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: NOTES: -DEFAULT VALUE: - The default value is 0. +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: CONSTRAINTS: - * It shall be greater than or equal to 0. +The following constraints apply to this configuration option: - * It shall be less than or equal to 65535. +* The value of the configuration option shall be greater than or equal to zero. - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +* The value of the configuration option shall be less than or equal to 65535. - * It may be defined through - :c:func:`rtems_resource_unlimited` the enable unlimited objects for this - object class, if the value passed to :c:func:`rtems_resource_unlimited` - satisfies all other constraints of this configuration option. +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. -DESCRIPTION: - The value of this configuration option defines the maximum number of POSIX - API Keys that can be concurrently active. +* The value of the configuration option may be defined through + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` + satisfies all other constraints of the configuration option. -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. +.. Generated from spec:/acfg/if/max-posix-key-value-pairs + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS @@ -59,45 +93,56 @@ NOTES: CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS --------------------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is +:ref:`CONFIGURE_MAXIMUM_POSIX_KEYS` * +( :ref:`CONFIGURE_MAXIMUM_TASKS` + +:ref:`CONFIGURE_MAXIMUM_POSIX_THREADS` ). + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the maximum number of key +value pairs used by POSIX API Keys that can be concurrently active. + +.. rubric:: NOTES: -OPTION TYPE: - This configuration option is an integer define. +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. -DEFAULT VALUE: - The default value is - :ref:`CONFIGURE_MAXIMUM_POSIX_KEYS` * - :ref:`CONFIGURE_MAXIMUM_TASKS` + - :ref:`CONFIGURE_MAXIMUM_POSIX_THREADS`. +A key value pair is created by :c:func:`pthread_setspecific` if the value +is not `NULL <https://en.cppreference.com/w/c/types/NULL>`_, otherwise it is deleted. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: CONSTRAINTS: - * It shall be greater than or equal to 0. +The following constraints apply to this configuration option: - * It shall be less than or equal to 65535. +* The value of the configuration option shall be greater than or equal to zero. - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +* The value of the configuration option shall be less than or equal to 65535. - * It may be defined through - :c:func:`rtems_resource_unlimited` the enable unlimited objects for this - object class, if the value passed to :c:func:`rtems_resource_unlimited` - satisfies all other constraints of this configuration option. +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. -DESCRIPTION: - The value of this configuration option defines the maximum number of key - value pairs used by POSIX API Keys that can be concurrently active. +* The value of the configuration option may be defined through + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` + satisfies all other constraints of the configuration option. -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. +.. Generated from spec:/acfg/if/max-posix-message-queues - A key value pair is created by :c:func:`pthread_setspecific` if the value - is not :c:macro:`NULL`, otherwise it is deleted. +.. raw:: latex + + \clearpage .. index:: CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES @@ -106,45 +151,57 @@ NOTES: CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES -------------------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the maximum number of POSIX +API Message Queues that can be concurrently active. + +.. rubric:: NOTES: + +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. You have to account for the memory used to +store the messages of each message queue, see +:ref:`CONFIGURE_MESSAGE_BUFFER_MEMORY`. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: CONSTRAINTS: -DEFAULT VALUE: - The default value is 0. +The following constraints apply to this configuration option: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +* The value of the configuration option shall be greater than or equal to zero. - * It shall be greater than or equal to 0. +* The value of the configuration option shall be less than or equal to 65535. - * It shall be less than or equal to 65535. +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +* The value of the configuration option shall be small enough so that the RTEMS + Workspace size calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. - * It shall be small enough so that the - RTEMS Workspace size calculation carried out by ``<rtems/confdefs.h>`` does - not overflow an integer of type ``uintptr_t``. +* The value of the configuration option may be defined through + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` + satisfies all other constraints of the configuration option. - * It may be defined through - :c:func:`rtems_resource_unlimited` the enable unlimited objects for this - object class, if the value passed to :c:func:`rtems_resource_unlimited` - satisfies all other constraints of this configuration option. +.. Generated from spec:/acfg/if/max-posix-queued-signals -DESCRIPTION: - The value of this configuration option defines the maximum number of POSIX - API Message Queues that can be concurrently active. +.. raw:: latex -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. You have to account for the memory used to - store the messages of each message queue, see - :ref:`CONFIGURE_MESSAGE_BUFFER_MEMORY`. + \clearpage .. index:: CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS @@ -153,43 +210,55 @@ NOTES: CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS -------------------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is an integer define. +``CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS`` -DEFAULT VALUE: - The default value is 0. +.. rubric:: OPTION TYPE: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +This configuration option is an integer define. - * It shall be greater than or equal to 0. +.. rubric:: DEFAULT VALUE: - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +The default value is 0. - * It shall be small enough so that the - RTEMS Workspace size calculation carried out by ``<rtems/confdefs.h>`` does - not overflow an integer of type ``uintptr_t``. +.. rubric:: DESCRIPTION: - * It shall be zero if the POSIX API is not - enabled (e.g. RTEMS was built without the ``--enable-posix`` build - configuration option). Otherwise a compile time error in the configuration - file will occur. +The value of this configuration option defines the maximum number of POSIX +API Queued Signals that can be concurrently active. -DESCRIPTION: - The value of this configuration option defines the maximum number of POSIX - API Queued Signals that can be concurrently active. +.. rubric:: NOTES: -NOTES: - Unlimited objects are not available for queued signals. +Unlimited objects are not available for queued signals. - Queued signals are only available if RTEMS was built with the - ``--enable-posix`` build configuration option. +Queued signals are only available if RTEMS was built with the POSIX API +build configuration option enabled. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +* The value of the configuration option shall be small enough so that the RTEMS + Workspace size calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. + +* The value of the configuration option shall be zero if the POSIX API is not + enabled (e.g. RTEMS was built without the ``RTEMS_POSIX_API = True`` build + configuration option). Otherwise a compile time error in the configuration + file will occur. + +.. Generated from spec:/acfg/if/max-posix-semaphores + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_MAXIMUM_POSIX_SEMAPHORES @@ -198,47 +267,60 @@ NOTES: CONFIGURE_MAXIMUM_POSIX_SEMAPHORES ---------------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_POSIX_SEMAPHORES`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_POSIX_SEMAPHORES`` -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: OPTION TYPE: -DEFAULT VALUE: - The default value is 0. +This configuration option is an integer define. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: DEFAULT VALUE: - * It shall be greater than or equal to 0. +The default value is 0. - * It shall be less than or equal to 65535. +.. rubric:: DESCRIPTION: - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +The value of this configuration option defines the maximum number of POSIX +API Named Semaphores that can be concurrently active. - * It shall be small enough so that the - RTEMS Workspace size calculation carried out by ``<rtems/confdefs.h>`` does - not overflow an integer of type ``uintptr_t``. +.. rubric:: NOTES: - * It may be defined through - :c:func:`rtems_resource_unlimited` the enable unlimited objects for this - object class, if the value passed to :c:func:`rtems_resource_unlimited` - satisfies all other constraints of this configuration option. +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. -DESCRIPTION: - The value of this configuration option defines the maximum number of POSIX - API Named Semaphores that can be concurrently active. +Named semaphores are created with :c:func:`sem_open`. Semaphores +initialized with :c:func:`sem_init` are not affected by this +configuration option since the storage space for these semaphores is +user-provided. -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. +.. rubric:: CONSTRAINTS: - Named semaphores are created with :c:func:`sem_open()`. Semaphores - initialized with :c:func:`sem_init()` are not affected by this configuration - option since the storage space for these semaphores is user-provided. +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +* The value of the configuration option shall be small enough so that the RTEMS + Workspace size calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. + +* The value of the configuration option may be defined through + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` + satisfies all other constraints of the configuration option. + +.. Generated from spec:/acfg/if/max-posix-shms + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_MAXIMUM_POSIX_SHMS @@ -247,43 +329,55 @@ NOTES: CONFIGURE_MAXIMUM_POSIX_SHMS ---------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_POSIX_SHMS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_POSIX_SHMS`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is an integer define. +This configuration option is an integer define. -DEFAULT VALUE: - The default value is 0. +.. rubric:: DEFAULT VALUE: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The default value is 0. - * It shall be greater than or equal to 0. +.. rubric:: DESCRIPTION: - * It shall be less than or equal to 65535. +The value of this configuration option defines the maximum number of POSIX +API Shared Memory objects that can be concurrently active. - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +.. rubric:: NOTES: - * It shall be small enough so that the - RTEMS Workspace size calculation carried out by ``<rtems/confdefs.h>`` does - not overflow an integer of type ``uintptr_t``. +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. - * It may be defined through - :c:func:`rtems_resource_unlimited` the enable unlimited objects for this - object class, if the value passed to :c:func:`rtems_resource_unlimited` - satisfies all other constraints of this configuration option. +.. rubric:: CONSTRAINTS: -DESCRIPTION: - The value of this configuration option defines the maximum number of POSIX - API Shared Memory objects that can be concurrently active. +The following constraints apply to this configuration option: -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +* The value of the configuration option shall be small enough so that the RTEMS + Workspace size calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. + +* The value of the configuration option may be defined through + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` + satisfies all other constraints of the configuration option. + +.. Generated from spec:/acfg/if/max-posix-threads + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_MAXIMUM_POSIX_THREADS @@ -292,51 +386,60 @@ NOTES: CONFIGURE_MAXIMUM_POSIX_THREADS ------------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_POSIX_THREADS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_POSIX_THREADS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DEFAULT VALUE: -DEFAULT VALUE: - The default value is 0. +The default value is 0. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: DESCRIPTION: - * It shall be greater than or equal to 0. +The value of this configuration option defines the maximum number of POSIX +API Threads that can be concurrently active. - * It shall be less than or equal to 65535. +.. rubric:: NOTES: - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. - * It shall be small enough so that the task - stack space calculation carried out by ``<rtems/confdefs.h>`` does not - overflow an integer of type ``uintptr_t``. +This calculations for the required memory in the RTEMS Workspace for threads +assume that each thread has a minimum stack size and has floating point +support enabled. The configuration option :ref:`CONFIGURE_EXTRA_TASK_STACKS` is used +to specify thread stack requirements **above** the minimum size required. -DESCRIPTION: - The value of this configuration option defines the maximum number of POSIX - API Threads that can be concurrently active. +The maximum number of Classic API Tasks is specified by +:ref:`CONFIGURE_MAXIMUM_TASKS`. -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. +All POSIX threads have floating point enabled. - This calculations for the required memory in the RTEMS Workspace for - threads assume that each thread has a minimum stack size and has floating - point support enabled. The configuration option - :ref:`CONFIGURE_EXTRA_TASK_STACKS` is used to specify thread stack - requirements **above** the minimum size required. See :ref:`Reserve - Task/Thread Stack Memory Above Minimum` for more information about - ``CONFIGURE_EXTRA_TASK_STACKS``. +.. rubric:: CONSTRAINTS: - The maximum number of Classic API Tasks is specified by - :ref:`CONFIGURE_MAXIMUM_TASKS`. +The following constraints apply to this configuration option: - All POSIX threads have floating point enabled. +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +* The value of the configuration option shall be small enough so that the task + stack space calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. + +.. Generated from spec:/acfg/if/max-posix-timers + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_MAXIMUM_POSIX_TIMERS @@ -345,47 +448,58 @@ NOTES: CONFIGURE_MAXIMUM_POSIX_TIMERS ------------------------------ -CONSTANT: - ``CONFIGURE_MAXIMUM_POSIX_TIMERS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_POSIX_TIMERS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: -OPTION TYPE: - This configuration option is an integer define. +The default value is 0. -DEFAULT VALUE: - The default value is 0. +.. rubric:: DESCRIPTION: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The value of this configuration option defines the maximum number of POSIX +API Timers that can be concurrently active. - * It shall be greater than or equal to 0. +.. rubric:: NOTES: - * It shall be less than or equal to 65535. +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +Timers are only available if RTEMS was built with the POSIX API build +configuration option enabled. - * It may be defined through - :c:func:`rtems_resource_unlimited` the enable unlimited objects for this - object class, if the value passed to :c:func:`rtems_resource_unlimited` - satisfies all other constraints of this configuration option. +.. rubric:: CONSTRAINTS: - * It shall be zero if the POSIX API is not - enabled (e.g. RTEMS was built without the ``--enable-posix`` build - configuration option). Otherwise a compile time error in the configuration - file will occur. +The following constraints apply to this configuration option: -DESCRIPTION: - The value of this configuration option defines the maximum number of POSIX - API Timers that can be concurrently active. +* The value of the configuration option shall be greater than or equal to zero. -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. +* The value of the configuration option shall be less than or equal to 65535. - Timers are only available if RTEMS was built with the - ``--enable-posix`` build configuration option. +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +* The value of the configuration option may be defined through + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` + satisfies all other constraints of the configuration option. + +* The value of the configuration option shall be zero if the POSIX API is not + enabled (e.g. RTEMS was built without the ``RTEMS_POSIX_API = True`` build + configuration option). Otherwise a compile time error in the configuration + file will occur. + +.. Generated from spec:/acfg/if/min-posix-thread-stack-size + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE .. index:: minimum POSIX thread stack size @@ -395,30 +509,32 @@ NOTES: CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE ----------------------------------------- -CONSTANT: - ``CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: -OPTION TYPE: - This configuration option is an integer define. +The default value is two times the value of +:ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. -DEFAULT VALUE: - The default value is two times the value of - :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. +.. rubric:: DESCRIPTION: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The value of this configuration option defines the minimum stack size in +bytes for every POSIX thread in the system. - * It shall be small enough so that the task - stack space calculation carried out by ``<rtems/confdefs.h>`` does not - overflow an integer of type ``uintptr_t``. +.. rubric:: CONSTRAINTS: - * It shall be greater than or equal to a - BSP-specific and application-specific minimum value. +The following constraints apply to this configuration option: -DESCRIPTION: - The value of this configuration option defines the minimum stack size in - bytes for every POSIX thread in the system. +* The value of the configuration option shall be small enough so that the task + stack space calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. -NOTES: - None. +* The value of the configuration option shall be greater than or equal to a + BSP-specific and application-specific minimum value. diff --git a/c-user/config/posix-init-thread.rst b/c-user/config/posix-init-thread.rst index 65ccfe8..ee09ba0 100644 --- a/c-user/config/posix-init-thread.rst +++ b/c-user/config/posix-init-thread.rst @@ -1,14 +1,37 @@ .. 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 & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/acfg/if/group-posixinit + POSIX Initialization Thread Configuration ========================================= This section describes configuration options related to the POSIX initialization thread. +.. Generated from spec:/acfg/if/posix-init-thread-entry-point + +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT .. _CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT: @@ -16,26 +39,38 @@ initialization thread. CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT --------------------------------------- -CONSTANT: - ``CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT`` +.. rubric:: CONSTANT: + +``CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT`` + +.. rubric:: OPTION TYPE: + +This configuration option is an initializer define. + +.. rubric:: DEFAULT VALUE: + +The default value is ``POSIX_Init``. + +.. rubric:: DESCRIPTION: + +The value of this configuration option initializes the entry point of the +POSIX API initialization thread. + +.. rubric:: NOTES: + +The application shall provide the function referenced by this configuration +option. -OPTION TYPE: - This configuration option is an initializer define. +.. rubric:: CONSTRAINTS: -DEFAULT VALUE: - The default value is ``POSIX_Init``. +The value of the configuration option shall be defined to a valid function +pointer of the type ``void *( *entry_point )( void * )``. -VALUE CONSTRAINTS: - The value of this configuration option shall be defined to a valid function - pointer of the type ``void *( *entry_point )( void * )``. +.. Generated from spec:/acfg/if/posix-init-thread-stack-size -DESCRIPTION: - The value of this configuration option initializes the entry point of the - POSIX API initialization thread. +.. raw:: latex -NOTES: - The application shall provide the function referenced by this configuration - option. + \clearpage .. index:: CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE @@ -44,31 +79,40 @@ NOTES: CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE -------------------------------------- -CONSTANT: - ``CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is an integer define. +``CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE`` -DEFAULT VALUE: - The default value is :ref:`CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE`. +.. rubric:: OPTION TYPE: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +This configuration option is an integer define. - * It shall be greater than or equal to :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. +.. rubric:: DEFAULT VALUE: - * It shall be small enough so that the task - stack space calculation carried out by ``<rtems/confdefs.h>`` does not - overflow an integer of type ``uintptr_t``. +The default value is :ref:`CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE`. -DESCRIPTION: - The value of this configuration option defines the thread stack size of the - POSIX API initialization thread. +.. rubric:: DESCRIPTION: -NOTES: - None. +The value of this configuration option defines the thread stack size of the +POSIX API initialization thread. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to + :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. + +* The value of the configuration option shall be small enough so that the task + stack space calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. + +.. Generated from spec:/acfg/if/posix-init-thread-table + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_POSIX_INIT_THREAD_TABLE @@ -77,28 +121,36 @@ NOTES: CONFIGURE_POSIX_INIT_THREAD_TABLE --------------------------------- -CONSTANT: - ``CONFIGURE_POSIX_INIT_THREAD_TABLE`` +.. rubric:: CONSTANT: + +``CONFIGURE_POSIX_INIT_THREAD_TABLE`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is a boolean feature define. +In case this configuration option is defined, then exactly one POSIX +initialization thread is configured. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: NOTES: -DESCRIPTION: - In case this configuration option is defined, then exactly one POSIX - initialization thread is configured. +The application shall define at least one of the following configuration +options -NOTES: - The application shall define exactly one of the following configuration - options +* :ref:`CONFIGURE_RTEMS_INIT_TASKS_TABLE`, - * :ref:`CONFIGURE_RTEMS_INIT_TASKS_TABLE`, +* ``CONFIGURE_POSIX_INIT_THREAD_TABLE``, or - * `CONFIGURE_POSIX_INIT_THREAD_TABLE`, or +* :ref:`CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION` - * :ref:`CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION` +otherwise a compile time error in the configuration file will occur. - otherwise a compile time error in the configuration file will occur. +If no Classic API initialization task is configured, then the POSIX API +initialization thread performs the :ref:`GlobalConstruction`. diff --git a/c-user/config/scheduler-general.rst b/c-user/config/scheduler-general.rst index 438e9a3..d347d6b 100644 --- a/c-user/config/scheduler-general.rst +++ b/c-user/config/scheduler-general.rst @@ -1,9 +1,26 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020, 2022 embedded brains GmbH & Co. KG .. Copyright (C) 2010 Gedare Bloom .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/acfg/if/group-schedgeneral + General Scheduler Configuration =============================== @@ -13,22 +30,29 @@ and only necessary in very specific circumstances. A normal application configuration does not need any of the configuration options described in this section. -By default, the :ref:`Deterministic Priority Scheduler <SchedulerPriority>` +By default, the :ref:`SchedulerPriority` algorithm is used in uniprocessor configurations. In case SMP is enabled and the configured maximum processors -(:ref:`CONFIGURE_MAXIMUM_PROCESSORS <CONFIGURE_MAXIMUM_PROCESSORS>`) is greater -than one, then the :ref:`Earliest Deadline First (EDF) SMP Scheduler -<SchedulerSMPEDF>` is selected as the default scheduler algorithm. +(:ref:`CONFIGURE_MAXIMUM_PROCESSORS`) is greater +than one, then the +:ref:`SchedulerSMPEDF` +is selected as the default scheduler algorithm. -For the :ref:`schedulers built into -RTEMS <SchedulingConcepts>`, the configuration is straightforward. All that is -required is to define the configuration option which specifies which scheduler -you want for in your application. +For the schedulers provided by RTEMS (see :ref:`RTEMSAPIClassicScheduler`), the +configuration is straightforward. All that is required is to define the +configuration option which specifies which scheduler you want for in your +application. The pluggable scheduler interface also enables the user to provide their own scheduling algorithm. If you choose to do this, you must define multiple configuration option. +.. Generated from spec:/acfg/if/cbs-max-servers + +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_CBS_MAXIMUM_SERVERS .. _CONFIGURE_CBS_MAXIMUM_SERVERS: @@ -36,34 +60,46 @@ configuration option. CONFIGURE_CBS_MAXIMUM_SERVERS ----------------------------- -CONSTANT: - ``CONFIGURE_CBS_MAXIMUM_SERVERS`` +.. rubric:: CONSTANT: + +``CONFIGURE_CBS_MAXIMUM_SERVERS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is :ref:`CONFIGURE_MAXIMUM_TASKS`. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is an integer define. +The value of this configuration option defines the maximum number Constant +Bandwidth Servers that can be concurrently active. -DEFAULT VALUE: - The default value is :ref:`CONFIGURE_MAXIMUM_TASKS`. +.. rubric:: NOTES: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +This configuration option is only evaluated if the configuration option +:ref:`CONFIGURE_SCHEDULER_CBS` is defined. - * It shall be greater than or equal to 0. +.. rubric:: CONSTRAINTS: - * It shall be less than or equal to ``SIZE_MAX``. +The following constraints apply to this configuration option: - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +* The value of the configuration option shall be greater than or equal to zero. -DESCRIPTION: - The value of this configuration option defines the maximum number Constant - Bandwidth Servers that can be concurrently active. +* The value of the configuration option shall be less than or equal to + `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_. -NOTES: - This configuration option is only evaluated if the configuration option - :ref:`CONFIGURE_SCHEDULER_CBS` is defined. +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +.. Generated from spec:/acfg/if/max-priority + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_MAXIMUM_PRIORITY .. index:: maximum priority @@ -74,54 +110,66 @@ NOTES: CONFIGURE_MAXIMUM_PRIORITY -------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_PRIORITY`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_PRIORITY`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 255. + +.. rubric:: DESCRIPTION: + +For the following schedulers -OPTION TYPE: - This configuration option is an integer define. +* :ref:`SchedulerPriority`, which is the default in uniprocessor + configurations and can be configured through the + :ref:`CONFIGURE_SCHEDULER_PRIORITY` configuration option, -DEFAULT VALUE: - The default value is 255. +* :ref:`SchedulerSMPPriority` which can be configured through the + :ref:`CONFIGURE_SCHEDULER_PRIORITY_SMP` configuration option, and -VALUE CONSTRAINTS: - The value of this configuration option shall be - an element of {3, 7, 31, 63, 127, 255}. +* :ref:`SchedulerSMPPriorityAffinity` which can be configured through the + :ref:`CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP` configuration option -DESCRIPTION: - For the following schedulers +this configuration option specifies the maximum numeric priority of any task +for these schedulers and one less that the number of priority levels for +these schedulers. For all other schedulers provided by RTEMS, this +configuration option has no effect. - * :ref:`SchedulerPriority`, which is the default in uniprocessor - configurations and can be configured through the - :ref:`CONFIGURE_SCHEDULER_PRIORITY` configuration option, +.. rubric:: NOTES: - * :ref:`SchedulerSMPPriority` which can be configured through the - :ref:`CONFIGURE_SCHEDULER_PRIORITY_SMP` configuration option, and +The numerically greatest priority is the logically lowest priority in the +system and will thus be used by the IDLE task. - * :ref:`SchedulerSMPPriorityAffinity` which can be configured through the - :ref:`CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP` configuration option +Priority zero is reserved for internal use by RTEMS and is not available to +applications. - this configuration option specifies the maximum numeric priority of any task - for these schedulers and one less that the number of priority levels for - these schedulers. For all other schedulers provided by RTEMS, this - configuration option has no effect. +Reducing the number of priorities through this configuration option reduces +the amount of memory allocated by the schedulers listed above. These +schedulers use a chain control structure per priority and this structure +consists of three pointers. On a 32-bit architecture, the allocated memory +is 12 bytes * (``CONFIGURE_MAXIMUM_PRIORITY`` + 1), e.g. 3072 bytes for 256 +priority levels (default), 48 bytes for 4 priority levels +(``CONFIGURE_MAXIMUM_PRIORITY == 3``). -NOTES: - The numerically greatest priority is the logically lowest priority in the - system and will thus be used by the IDLE task. +The default value is 255, because RTEMS shall support 256 priority levels to +be compliant with various standards. These priorities range from 0 to 255. - Priority zero is reserved for internal use by RTEMS and is not available to - applications. +.. rubric:: CONSTRAINTS: - Reducing the number of priorities through this configuration option reduces - the amount of memory allocated by the schedulers listed above. These - schedulers use a chain control structure per priority and this structure - consists of three pointers. On a 32-bit architecture, the allocated memory - is 12 bytes * (``CONFIGURE_MAXIMUM_PRIORITY`` + 1), e.g. 3072 bytes for 256 - priority levels (default), 48 bytes for 4 priority levels - (``CONFIGURE_MAXIMUM_PRIORITY == 3``). +The value of the configuration option shall be equal to 3, 7, 31, 63, 127, or +255. - The default value is 255, because RTEMS shall support 256 priority levels to - be compliant with various standards. These priorities range from 0 to 255. +.. Generated from spec:/acfg/if/scheduler-assignments + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_SCHEDULER_ASSIGNMENTS @@ -130,39 +178,62 @@ NOTES: CONFIGURE_SCHEDULER_ASSIGNMENTS ------------------------------- -CONSTANT: - ``CONFIGURE_SCHEDULER_ASSIGNMENTS`` +.. rubric:: CONSTANT: + +``CONFIGURE_SCHEDULER_ASSIGNMENTS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an initializer define. + +.. rubric:: DEFAULT VALUE: + +The default value of this configuration option is computed so that the +default scheduler is assigned to each configured processor (up to 32). + +.. rubric:: DESCRIPTION: + +The value of this configuration option is used to initialize the initial +scheduler to processor assignments. + +.. rubric:: NOTES: -OPTION TYPE: - This configuration option is an initializer define. +Where the system was built with SMP support enabled, this configuration +option is evaluated, otherwise it is ignored. -DEFAULT VALUE: - The default value of this configuration option is computed so that the - default scheduler is assigned to each configured processor (up to 32). +This is an advanced configuration option, see +:ref:`ConfigurationSchedulersClustered`. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: CONSTRAINTS: - * It shall be a list of the following - macros: +The following constraints apply to this configuration option: - * ``RTEMS_SCHEDULER_ASSIGN( processor_index, attributes )`` +* The value of the configuration option shall be a list of the following + macros: - * :c:macro:`RTEMS_SCHEDULER_ASSIGN_NO_SCHEDULER` + * ``RTEMS_SCHEDULER_ASSIGN( scheduler_index, attributes )`` - * It shall be a list of exactly - :ref:`CONFIGURE_MAXIMUM_PROCESSORS` elements. + * ``RTEMS_SCHEDULER_ASSIGN_NO_SCHEDULER`` -DESCRIPTION: - The value of this configuration option is used to initialize the initial - scheduler to processor assignments. + The ``scheduler_index`` macro parameter shall be a valid index of the + scheduler table defined by the :ref:`CONFIGURE_SCHEDULER_TABLE_ENTRIES` + configuration option. -NOTES: - This configuration option is only evaluated in SMP configurations. + The ``attributes`` macro parameter shall be set to exactly one of the + following constants: - This is an advanced configuration option, see - :ref:`ConfigurationSchedulersClustered`. + * ``RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY`` + + * ``RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL`` + +* The value of the configuration option shall be a list of exactly + :ref:`CONFIGURE_MAXIMUM_PROCESSORS` elements. + +.. Generated from spec:/acfg/if/scheduler-cbs + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_SCHEDULER_CBS @@ -171,28 +242,38 @@ NOTES: CONFIGURE_SCHEDULER_CBS ----------------------- -CONSTANT: - ``CONFIGURE_SCHEDULER_CBS`` +.. rubric:: CONSTANT: + +``CONFIGURE_SCHEDULER_CBS`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: -OPTION TYPE: - This configuration option is a boolean feature define. +If this configuration option is undefined, then the described feature is not +enabled. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DESCRIPTION: -DESCRIPTION: - In case this configuration option is defined, then - :ref:`Constant Bandwidth Server (CBS) Scheduler <SchedulerCBS>` - algorithm is made available to the application. +In case this configuration option is defined, then the +:ref:`SchedulerCBS` +algorithm is made available to the application. -NOTES: - This scheduler configuration option is an advanced configuration option. - Think twice before you use it. +.. rubric:: NOTES: - In case no explicit :ref:`clustered scheduler configuration - <ConfigurationSchedulersClustered>` is present, then it is used as the - scheduler for exactly one processor. +This scheduler configuration option is an advanced configuration option. +Think twice before you use it. + +In case no explicit :ref:`ConfigurationSchedulersClustered` +is present, then it is used as the scheduler for exactly one processor. + +.. Generated from spec:/acfg/if/scheduler-edf + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_SCHEDULER_EDF @@ -201,28 +282,38 @@ NOTES: CONFIGURE_SCHEDULER_EDF ----------------------- -CONSTANT: - ``CONFIGURE_SCHEDULER_EDF`` +.. rubric:: CONSTANT: + +``CONFIGURE_SCHEDULER_EDF`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is a boolean feature define. +In case this configuration option is defined, then the +:ref:`SchedulerEDF` +algorithm is made available to the application. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: NOTES: -DESCRIPTION: - In case this configuration option is defined, then - :ref:`Earliest Deadline First (EDF) Scheduler <SchedulerEDF>` - algorithm is made available to the application. +This scheduler configuration option is an advanced configuration option. +Think twice before you use it. -NOTES: - This scheduler configuration option is an advanced configuration option. - Think twice before you use it. +In case no explicit :ref:`ConfigurationSchedulersClustered` +is present, then it is used as the scheduler for exactly one processor. - In case no explicit :ref:`clustered scheduler configuration - <ConfigurationSchedulersClustered>` is present, then it is used as the - scheduler for exactly one processor. +.. Generated from spec:/acfg/if/scheduler-edf-smp + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_SCHEDULER_EDF_SMP @@ -231,35 +322,45 @@ NOTES: CONFIGURE_SCHEDULER_EDF_SMP --------------------------- -CONSTANT: - ``CONFIGURE_SCHEDULER_EDF_SMP`` +.. rubric:: CONSTANT: + +``CONFIGURE_SCHEDULER_EDF_SMP`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the +:ref:`SchedulerSMPEDF` +algorithm is made available to the application. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: NOTES: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +This scheduler configuration option is an advanced configuration option. +Think twice before you use it. -DESCRIPTION: - In case this configuration option is defined, then - :ref:`Earliest Deadline First (EDF) SMP Scheduler <SchedulerSMPEDF>` - algorithm is made available to the application. +This scheduler algorithm is only available when RTEMS is built with SMP +support enabled. -NOTES: - This scheduler configuration option is an advanced configuration option. - Think twice before you use it. +In case no explicit :ref:`ConfigurationSchedulersClustered` +is present, then it is used as the scheduler for up to 32 processors. - This scheduler algorithm is only available when RTEMS is built with SMP - support enabled. +This scheduler algorithm is the default in SMP configurations if +:ref:`CONFIGURE_MAXIMUM_PROCESSORS` is +greater than one. - In case no explicit :ref:`clustered scheduler configuration - <ConfigurationSchedulersClustered>` is present, then it is used as the - scheduler for up to 32 processors. +.. Generated from spec:/acfg/if/scheduler-name - This scheduler algorithm is the default in SMP configurations if - :ref:`CONFIGURE_MAXIMUM_PROCESSORS` is - greater than one. +.. raw:: latex + + \clearpage .. index:: CONFIGURE_SCHEDULER_NAME @@ -268,46 +369,58 @@ NOTES: CONFIGURE_SCHEDULER_NAME ------------------------ -CONSTANT: - ``CONFIGURE_SCHEDULER_NAME`` +.. rubric:: CONSTANT: + +``CONFIGURE_SCHEDULER_NAME`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is + +* ``"MEDF"`` for the :ref:`SchedulerSMPEDF`, + +* ``"MPA "`` for the :ref:`SchedulerSMPPriorityAffinity`, + +* ``"MPD "`` for the :ref:`SchedulerSMPPriority`, + +* ``"MPS "`` for the :ref:`SchedulerSMPPrioritySimple`, -OPTION TYPE: - This configuration option is an integer define. +* ``"UCBS"`` for the :ref:`SchedulerCBS`, -DEFAULT VALUE: - The default value is +* ``"UEDF"`` for the :ref:`SchedulerEDF`, - * ``"MEDF"`` for the :ref:`EDF SMP Scheduler <SchedulerSMPEDF>`, +* ``"UPD "`` for the :ref:`SchedulerPriority`, and - * ``"MPA "`` for the :ref:`Arbitrary Processor Affinity Priority SMP Scheduler <SchedulerSMPPriorityAffinity>`, +* ``"UPS "`` for the :ref:`SchedulerPrioritySimple`. - * ``"MPD "`` for the :ref:`Deterministic Priority SMP Scheduler <SchedulerSMPPriority>`, +.. rubric:: DESCRIPTION: - * ``"MPS "`` for the :ref:`Simple Priority SMP Scheduler <SchedulerSMPPrioritySimple>`, +The value of this configuration option defines the name of the default +scheduler. - * ``"UCBS"`` for the :ref:`Uniprocessor CBS Scheduler <SchedulerCBS>`, +.. rubric:: NOTES: - * ``"UEDF"`` for the :ref:`Uniprocessor EDF Scheduler <SchedulerEDF>`, +This scheduler configuration option is an advanced configuration option. +Think twice before you use it. - * ``"UPD "`` for the :ref:`Uniprocessor Deterministic Priority Scheduler <SchedulerPriority>`, and +Schedulers can be identified via :ref:`InterfaceRtemsSchedulerIdent`. - * ``"UPS "`` for the :ref:`Uniprocessor Simple Priority Scheduler <SchedulerPrioritySimple>`. +Use :ref:`InterfaceRtemsBuildName` to define the scheduler name. -VALUE CONSTRAINTS: - The value of this configuration option shall be a valid integer of type - ``rtems_name``. +.. rubric:: CONSTRAINTS: -DESCRIPTION: - The value of this configuration option defines the name of the default - scheduler. +The value of the configuration option shall be convertible to an integer of +type :c:type:`rtems_name`. -NOTES: - This scheduler configuration option is an advanced configuration option. - Think twice before you use it. +.. Generated from spec:/acfg/if/scheduler-priority - Schedulers can be identified via c:func:`rtems_scheduler_ident`. +.. raw:: latex - Use :c:func:`rtems_build_name` to define the scheduler name. + \clearpage .. index:: CONFIGURE_SCHEDULER_PRIORITY @@ -316,35 +429,45 @@ NOTES: CONFIGURE_SCHEDULER_PRIORITY ---------------------------- -CONSTANT: - ``CONFIGURE_SCHEDULER_PRIORITY`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is a boolean feature define. +``CONFIGURE_SCHEDULER_PRIORITY`` -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: OPTION TYPE: -DESCRIPTION: - In case this configuration option is defined, then - :ref:`Deterministic Priority Scheduler <SchedulerPriority>` - algorithm is made available to the application. +This configuration option is a boolean feature define. -NOTES: - This scheduler configuration option is an advanced configuration option. - Think twice before you use it. +.. rubric:: DEFAULT CONFIGURATION: - In case no explicit :ref:`clustered scheduler configuration - <ConfigurationSchedulersClustered>` is present, then it is used as the - scheduler for exactly one processor. +If this configuration option is undefined, then the described feature is not +enabled. - This scheduler algorithm is the default when - :ref:`CONFIGURE_MAXIMUM_PROCESSORS` is - exactly one. +.. rubric:: DESCRIPTION: - The memory allocated for this scheduler depends on the - :ref:`CONFIGURE_MAXIMUM_PRIORITY` configuration option. +In case this configuration option is defined, then the +:ref:`SchedulerPriority` +algorithm is made available to the application. + +.. rubric:: NOTES: + +This scheduler configuration option is an advanced configuration option. +Think twice before you use it. + +In case no explicit :ref:`ConfigurationSchedulersClustered` +is present, then it is used as the scheduler for exactly one processor. + +This scheduler algorithm is the default when +:ref:`CONFIGURE_MAXIMUM_PROCESSORS` is +exactly one. + +The memory allocated for this scheduler depends on the +:ref:`CONFIGURE_MAXIMUM_PRIORITY` configuration option. + +.. Generated from spec:/acfg/if/scheduler-priority-affinity-smp + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP @@ -353,34 +476,44 @@ NOTES: CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP ----------------------------------------- -CONSTANT: - ``CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP`` +.. rubric:: CONSTANT: + +``CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP`` -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: OPTION TYPE: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +This configuration option is a boolean feature define. -DESCRIPTION: - In case this configuration option is defined, then - :ref:`Arbitrary Processor Affinity SMP Scheduler <SchedulerSMPPriorityAffinity>` - algorithm is made available to the application. +.. rubric:: DEFAULT CONFIGURATION: -NOTES: - This scheduler configuration option is an advanced configuration option. - Think twice before you use it. +If this configuration option is undefined, then the described feature is not +enabled. - This scheduler algorithm is only available when RTEMS is built with SMP - support enabled. +.. rubric:: DESCRIPTION: - In case no explicit :ref:`clustered scheduler configuration - <ConfigurationSchedulersClustered>` is present, then it is used as the - scheduler for up to 32 processors. +In case this configuration option is defined, then the +:ref:`SchedulerSMPPriorityAffinity` +algorithm is made available to the application. - The memory allocated for this scheduler depends on the - :ref:`CONFIGURE_MAXIMUM_PRIORITY` configuration option. +.. rubric:: NOTES: + +This scheduler configuration option is an advanced configuration option. +Think twice before you use it. + +This scheduler algorithm is only available when RTEMS is built with SMP +support enabled. + +In case no explicit :ref:`ConfigurationSchedulersClustered` +is present, then it is used as the scheduler for up to 32 processors. + +The memory allocated for this scheduler depends on the +:ref:`CONFIGURE_MAXIMUM_PRIORITY` configuration option. + +.. Generated from spec:/acfg/if/scheduler-priority-smp + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_SCHEDULER_PRIORITY_SMP @@ -389,34 +522,44 @@ NOTES: CONFIGURE_SCHEDULER_PRIORITY_SMP -------------------------------- -CONSTANT: - ``CONFIGURE_SCHEDULER_PRIORITY_SMP`` +.. rubric:: CONSTANT: + +``CONFIGURE_SCHEDULER_PRIORITY_SMP`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DEFAULT CONFIGURATION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +If this configuration option is undefined, then the described feature is not +enabled. -DESCRIPTION: - In case this configuration option is defined, then - :ref:`Deterministic Priority SMP Scheduler <SchedulerSMPPriority>` - algorithm is made available to the application. +.. rubric:: DESCRIPTION: -NOTES: - This scheduler configuration option is an advanced configuration option. - Think twice before you use it. +In case this configuration option is defined, then the +:ref:`SchedulerSMPPriority` +algorithm is made available to the application. - This scheduler algorithm is only available when RTEMS is built with SMP - support enabled. +.. rubric:: NOTES: - In case no explicit :ref:`clustered scheduler configuration - <ConfigurationSchedulersClustered>` is present, then it is used as the - scheduler for up to 32 processors. +This scheduler configuration option is an advanced configuration option. +Think twice before you use it. - The memory allocated for this scheduler depends on the - :ref:`CONFIGURE_MAXIMUM_PRIORITY` configuration option. +This scheduler algorithm is only available when RTEMS is built with SMP +support enabled. + +In case no explicit :ref:`ConfigurationSchedulersClustered` +is present, then it is used as the scheduler for up to 32 processors. + +The memory allocated for this scheduler depends on the +:ref:`CONFIGURE_MAXIMUM_PRIORITY` configuration option. + +.. Generated from spec:/acfg/if/scheduler-simple + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_SCHEDULER_SIMPLE @@ -425,28 +568,38 @@ NOTES: CONFIGURE_SCHEDULER_SIMPLE -------------------------- -CONSTANT: - ``CONFIGURE_SCHEDULER_SIMPLE`` +.. rubric:: CONSTANT: + +``CONFIGURE_SCHEDULER_SIMPLE`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: -OPTION TYPE: - This configuration option is a boolean feature define. +If this configuration option is undefined, then the described feature is not +enabled. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DESCRIPTION: -DESCRIPTION: - In case this configuration option is defined, then - :ref:`Simple Priority Scheduler <SchedulerPrioritySimple>` - algorithm is made available to the application. +In case this configuration option is defined, then the +:ref:`SchedulerPrioritySimple` +algorithm is made available to the application. -NOTES: - This scheduler configuration option is an advanced configuration option. - Think twice before you use it. +.. rubric:: NOTES: - In case no explicit :ref:`clustered scheduler configuration - <ConfigurationSchedulersClustered>` is present, then it is used as the - scheduler for exactly one processor. +This scheduler configuration option is an advanced configuration option. +Think twice before you use it. + +In case no explicit :ref:`ConfigurationSchedulersClustered` +is present, then it is used as the scheduler for exactly one processor. + +.. Generated from spec:/acfg/if/scheduler-simple-smp + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_SCHEDULER_SIMPLE_SMP @@ -455,32 +608,41 @@ NOTES: CONFIGURE_SCHEDULER_SIMPLE_SMP ------------------------------ -CONSTANT: - ``CONFIGURE_SCHEDULER_SIMPLE_SMP`` +.. rubric:: CONSTANT: + +``CONFIGURE_SCHEDULER_SIMPLE_SMP`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is a boolean feature define. +In case this configuration option is defined, then the +:ref:`SchedulerSMPPrioritySimple` +algorithm is made available to the application. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: NOTES: -DESCRIPTION: - In case this configuration option is defined, then - :ref:`Simple Priority SMP Scheduler <SchedulerSMPPrioritySimple>` - algorithm is made available to the application. - application. +This scheduler configuration option is an advanced configuration option. +Think twice before you use it. -NOTES: - This scheduler configuration option is an advanced configuration option. - Think twice before you use it. +This scheduler algorithm is only available when RTEMS is built with SMP +support enabled. - This scheduler algorithm is only available when RTEMS is built with SMP - support enabled. +In case no explicit :ref:`ConfigurationSchedulersClustered` +is present, then it is used as the scheduler for up to 32 processors. - In case no explicit :ref:`clustered scheduler configuration - <ConfigurationSchedulersClustered>` is present, then it is used as the - scheduler for up to 32 processors. +.. Generated from spec:/acfg/if/scheduler-strong-apa + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_SCHEDULER_STRONG_APA @@ -489,28 +651,114 @@ NOTES: CONFIGURE_SCHEDULER_STRONG_APA ------------------------------ -CONSTANT: - ``CONFIGURE_SCHEDULER_STRONG_APA`` +.. rubric:: CONSTANT: + +``CONFIGURE_SCHEDULER_STRONG_APA`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the Strong APA algorithm +is made available to the application. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: NOTES: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +This scheduler configuration option is an advanced configuration option. +Think twice before you use it. -DESCRIPTION: - In case this configuration option is defined, then Strong APA algorithm is - made available to the application. +This scheduler algorithm is only available when RTEMS is built with SMP +support enabled. -NOTES: - This scheduler configuration option is an advanced configuration option. - Think twice before you use it. +This scheduler algorithm is not correctly implemented. Do not use it. - This scheduler algorithm is only available when RTEMS is built with SMP - support enabled. +.. Generated from spec:/acfg/if/scheduler-table-entries - This scheduler algorithm is not correctly implemented. Do not use it. +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_SCHEDULER_TABLE_ENTRIES + +.. _CONFIGURE_SCHEDULER_TABLE_ENTRIES: + +CONFIGURE_SCHEDULER_TABLE_ENTRIES +--------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_SCHEDULER_TABLE_ENTRIES`` + +.. rubric:: OPTION TYPE: + +This configuration option is an initializer define. + +.. rubric:: DEFAULT VALUE: + +The default value of this configuration option is the definition of exactly +one table entry for the configured scheduler. + +.. rubric:: DESCRIPTION: + +The value of this configuration option is used to initialize the table of +configured schedulers. + +.. rubric:: NOTES: + +Schedulers registered in the scheduler table by this configuration option are +available to the application. The scheduler table entry index defines the +index of the scheduler. + +This is an advanced configuration option, see +:ref:`ConfigurationSchedulersClustered`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be a list of the following + macros: + + * ``RTEMS_SCHEDULER_TABLE_CBS( name, obj_name )`` + + * ``RTEMS_SCHEDULER_TABLE_EDF( name, obj_name )`` + + * ``RTEMS_SCHEDULER_TABLE_EDF_SMP( name, obj_name )`` + + * ``RTEMS_SCHEDULER_TABLE_PRIORITY_AFFINITY_SMP( name, obj_name )`` + + * ``RTEMS_SCHEDULER_TABLE_PRIORITY( name, obj_name )`` + + * ``RTEMS_SCHEDULER_TABLE_PRIORITY_SMP( name, obj_name )`` + + * ``RTEMS_SCHEDULER_TABLE_SIMPLE( name, obj_name )`` + + * ``RTEMS_SCHEDULER_TABLE_SIMPLE_SMP( name, obj_name )`` + + * ``RTEMS_SCHEDULER_TABLE_STRONG_APA( name, obj_name )`` + + The ``name`` macro parameter shall be the name associated with the scheduler + data structures, see :ref:`ConfigurationSchedulersClustered`. + + The ``obj_name`` macro parameter shall be the scheduler object name. It is + recommended to define the scheduler object name through + :ref:`InterfaceRtemsBuildName`. + +* Where the system was build with SMP support enabled, the table shall have one + or more entries, otherwise it shall have exactly one entry. + +.. Generated from spec:/acfg/if/scheduler-user + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_SCHEDULER_USER @@ -519,42 +767,48 @@ NOTES: CONFIGURE_SCHEDULER_USER ------------------------ -CONSTANT: - ``CONFIGURE_SCHEDULER_USER`` +.. rubric:: CONSTANT: + +``CONFIGURE_SCHEDULER_USER`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DESCRIPTION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +In case this configuration option is defined, then the user shall provide a +scheduler algorithm to the application. -DESCRIPTION: - In case this configuration option is defined, then the user shall provide a - scheduler algorithm to the application. +.. rubric:: NOTES: -NOTES: - This scheduler configuration option is an advanced configuration option. - Think twice before you use it. +This scheduler configuration option is an advanced configuration option. +Think twice before you use it. - RTEMS allows the application to provide its own task/thread scheduling - algorithm. In order to do this, one shall define - ``CONFIGURE_SCHEDULER_USER`` to indicate the application provides its own - scheduling algorithm. If ``CONFIGURE_SCHEDULER_USER`` is defined then the - following additional macros shall be defined: +RTEMS allows the application to provide its own task/thread scheduling +algorithm. In order to do this, one shall define +``CONFIGURE_SCHEDULER_USER`` to indicate the application provides its own +scheduling algorithm. If ``CONFIGURE_SCHEDULER_USER`` is defined then the +following additional macros shall be defined: - - ``CONFIGURE_SCHEDULER`` shall be defined to a static definition of - the scheduler data structures of the user scheduler. +* ``CONFIGURE_SCHEDULER`` shall be defined to a static definition of + the scheduler data structures of the user scheduler. - - ``CONFIGURE_SCHEDULER_TABLE_ENTRIES`` shall be defined to a scheduler - table entry initializer for the user scheduler. +* ``CONFIGURE_SCHEDULER_TABLE_ENTRIES`` shall be defined to a scheduler + table entry initializer for the user scheduler. - - ``CONFIGURE_SCHEDULER_USER_PER_THREAD`` shall be defined to the type of - the per-thread information of the user scheduler. +* ``CONFIGURE_SCHEDULER_USER_PER_THREAD`` shall be defined to the type of + the per-thread information of the user scheduler. - At this time, the mechanics and requirements for writing a new scheduler - are evolving and not fully documented. It is recommended that you look at - the existing Deterministic Priority Scheduler in - ``cpukit/score/src/schedulerpriority*.c`` for guidance. For guidance on - the configuration macros, please examine ``cpukit/sapi/include/confdefs.h`` - for how these are defined for the Deterministic Priority Scheduler. +At this time, the mechanics and requirements for writing a new scheduler +are evolving and not fully documented. It is recommended that you look at +the existing Deterministic Priority Scheduler in +``cpukit/score/src/schedulerpriority*.c`` for guidance. For guidance on +the configuration macros, please examine +``cpukit/include/rtems/confdefs/scheduler.h`` for how these are defined for +the Deterministic Priority Scheduler. diff --git a/c-user/config/task-stack-alloc.rst b/c-user/config/task-stack-alloc.rst index 005a643..c79833f 100644 --- a/c-user/config/task-stack-alloc.rst +++ b/c-user/config/task-stack-alloc.rst @@ -1,7 +1,24 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +.. Copyright (C) 2020, 2022 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2021 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/acfg/if/group-stackalloc Task Stack Allocator Configuration ================================== @@ -12,6 +29,12 @@ and deallocation methods for task stacks. This can be used to place task stacks in special areas of memory or to utilize a Memory Management Unit so that stack overflows are detected in hardware. +.. Generated from spec:/acfg/if/task-stack-allocator + +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_TASK_STACK_ALLOCATOR .. index:: task stack allocator @@ -20,32 +43,145 @@ overflows are detected in hardware. CONFIGURE_TASK_STACK_ALLOCATOR ------------------------------ -CONSTANT: - ``CONFIGURE_TASK_STACK_ALLOCATOR`` +.. rubric:: CONSTANT: + +``CONFIGURE_TASK_STACK_ALLOCATOR`` + +.. rubric:: OPTION TYPE: + +This configuration option is an initializer define. + +.. rubric:: DEFAULT VALUE: + +The default value is ``_Workspace_Allocate``, which indicates that task +stacks will be allocated from the RTEMS Workspace. + +.. rubric:: DESCRIPTION: + +The value of this configuration option initializes the stack allocator +allocate handler. + +.. rubric:: NOTES: + +A correctly configured system shall configure the following to be consistent: + +* :ref:`CONFIGURE_TASK_STACK_ALLOCATOR_INIT` + +* ``CONFIGURE_TASK_STACK_ALLOCATOR`` + +* :ref:`CONFIGURE_TASK_STACK_DEALLOCATOR` + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be defined to a valid function +pointer of the type ``void *( *allocate )( size_t )``. + +.. Generated from spec:/acfg/if/task-stack-no-workspace + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_TASK_STACK_ALLOCATOR_AVOIDS_WORK_SPACE + +.. _CONFIGURE_TASK_STACK_ALLOCATOR_AVOIDS_WORK_SPACE: + +CONFIGURE_TASK_STACK_ALLOCATOR_AVOIDS_WORK_SPACE +------------------------------------------------ + +.. rubric:: CONSTANT: + +``CONFIGURE_TASK_STACK_ALLOCATOR_AVOIDS_WORK_SPACE`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the system is informed +that the task stack allocator does not use the RTEMS Workspace. + +.. rubric:: NOTES: + +This configuration option may be used if a custom task stack allocator is +configured, see :ref:`CONFIGURE_TASK_STACK_ALLOCATOR`. + +.. Generated from spec:/acfg/if/task-stack-allocator-for-idle + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE +.. index:: task stack allocator for IDLE tasks -OPTION TYPE: - This configuration option is an initializer define. +.. _CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE: -DEFAULT VALUE: - The default value is ``_Workspace_Allocate``, which indicates that task - stacks will be allocated from the RTEMS Workspace. +CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE +--------------------------------------- -VALUE CONSTRAINTS: - The value of this configuration option shall be defined to a valid function - pointer of the type ``void *( *allocate )( size_t )``. +.. rubric:: CONSTANT: -DESCRIPTION: - The value of this configuration option initializes the stack allocator - allocate handler. +``CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE`` -NOTES: - A correctly configured system shall configure the following to be consistent: +.. rubric:: OPTION TYPE: - - :ref:`CONFIGURE_TASK_STACK_ALLOCATOR_INIT` +This configuration option is an initializer define. - - `CONFIGURE_TASK_STACK_ALLOCATOR` +.. rubric:: DEFAULT VALUE: - - :ref:`CONFIGURE_TASK_STACK_DEALLOCATOR` +By default, the IDLE task storage area will be allocated from the RTEMS +Workspace. + +.. rubric:: DESCRIPTION: + +The value of this configuration option is the address for the stack allocator +allocate handler used to allocate the task storage area of each +:term:`IDLE task`. + +.. rubric:: NOTES: + +This configuration option is independent of the other thread stack allocator +configuration options. It is assumed that any memory allocated for the task +storage area of an :term:`IDLE task` will not be from the RTEMS +Workspace. + +The IDLE task stack allocator may increase the size of the allocated memory +area to account for the actually allocated memory area. + +The + +* :ref:`CONFIGURE_IDLE_TASK_STORAGE_SIZE`, and + +* ``CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE`` + +configuration options are mutually exclusive. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be defined to a valid function + pointer of the type ``void *( *allocate )( uint32_t, size_t * )``. + +* The IDLE task stack allocator shall return a pointer to the allocated memory + area or terminate the system with a fatal error if the allocation request + cannot be satisfied. + +* The IDLE task stack allocator may increase the size of the allocated memory + area. + +.. Generated from spec:/acfg/if/task-stack-allocator-init + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_TASK_STACK_ALLOCATOR_INIT @@ -54,31 +190,44 @@ NOTES: CONFIGURE_TASK_STACK_ALLOCATOR_INIT ----------------------------------- -CONSTANT: - ``CONFIGURE_TASK_STACK_ALLOCATOR_INIT`` +.. rubric:: CONSTANT: + +``CONFIGURE_TASK_STACK_ALLOCATOR_INIT`` + +.. rubric:: OPTION TYPE: + +This configuration option is an initializer define. + +.. rubric:: DEFAULT VALUE: -OPTION TYPE: - This configuration option is an initializer define. +The default value is `NULL <https://en.cppreference.com/w/c/types/NULL>`_. -DEFAULT VALUE: - The default value is ``NULL``. +.. rubric:: DESCRIPTION: -VALUE CONSTRAINTS: - The value of this configuration option shall be defined to a valid function - pointer of the type ``void ( *initialize )( size_t )`` or to ``NULL``. +The value of this configuration option initializes the stack allocator +initialization handler. -DESCRIPTION: - The value of this configuration option initializes the stack allocator - initialization handler. +.. rubric:: NOTES: -NOTES: - A correctly configured system shall configure the following to be consistent: +A correctly configured system shall configure the following to be consistent: - - `CONFIGURE_TASK_STACK_ALLOCATOR_INIT` +* ``CONFIGURE_TASK_STACK_ALLOCATOR_INIT`` - - :ref:`CONFIGURE_TASK_STACK_ALLOCATOR` +* :ref:`CONFIGURE_TASK_STACK_ALLOCATOR` - - :ref:`CONFIGURE_TASK_STACK_DEALLOCATOR` +* :ref:`CONFIGURE_TASK_STACK_DEALLOCATOR` + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be defined to a valid function +pointer of the type ``void ( *initialize )( size_t )`` or to `NULL +<https://en.cppreference.com/w/c/types/NULL>`_. + +.. Generated from spec:/acfg/if/task-stack-deallocator + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_TASK_STACK_DEALLOCATOR .. index:: task stack deallocator @@ -88,32 +237,44 @@ NOTES: CONFIGURE_TASK_STACK_DEALLOCATOR -------------------------------- -CONSTANT: - ``CONFIGURE_TASK_STACK_DEALLOCATOR`` +.. rubric:: CONSTANT: + +``CONFIGURE_TASK_STACK_DEALLOCATOR`` + +.. rubric:: OPTION TYPE: + +This configuration option is an initializer define. + +.. rubric:: DEFAULT VALUE: + +The default value is ``_Workspace_Free``, which indicates that task stacks +will be allocated from the RTEMS Workspace. -OPTION TYPE: - This configuration option is an initializer define. +.. rubric:: DESCRIPTION: -DEFAULT VALUE: - The default value is ``_Workspace_Free``, which indicates that task stacks - will be allocated from the RTEMS Workspace. +The value of this configuration option initializes the stack allocator +deallocate handler. -VALUE CONSTRAINTS: - The value of this configuration option shall be defined to a valid function - pointer of the type ``void ( *deallocate )( void * )``. +.. rubric:: NOTES: -DESCRIPTION: - The value of this configuration option initializes the stack allocator - deallocate handler. +A correctly configured system shall configure the following to be consistent: -NOTES: - A correctly configured system shall configure the following to be consistent: +* :ref:`CONFIGURE_TASK_STACK_ALLOCATOR_INIT` - - :ref:`CONFIGURE_TASK_STACK_ALLOCATOR_INIT` +* :ref:`CONFIGURE_TASK_STACK_ALLOCATOR` - - :ref:`CONFIGURE_TASK_STACK_ALLOCATOR` +* ``CONFIGURE_TASK_STACK_DEALLOCATOR`` - - `CONFIGURE_TASK_STACK_DEALLOCATOR` +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be defined to a valid function +pointer of the type ``void ( *deallocate )( void * )``. + +.. Generated from spec:/acfg/if/task-stack-from-alloc + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_TASK_STACK_FROM_ALLOCATOR .. index:: task stack allocator @@ -123,51 +284,31 @@ NOTES: CONFIGURE_TASK_STACK_FROM_ALLOCATOR ----------------------------------- -CONSTANT: - ``CONFIGURE_TASK_STACK_FROM_ALLOCATOR`` - -OPTION TYPE: - This configuration option is an initializer define. +.. rubric:: CONSTANT: -DEFAULT VALUE: - The default value is a macro which supports the system heap allocator. +``CONFIGURE_TASK_STACK_FROM_ALLOCATOR`` -VALUE CONSTRAINTS: - The value of this configuration option shall be defined to a macro which - accepts exactly one parameter and returns an unsigned integer. The - parameter will be an allocation size and the macro shall return this size - plus the overhead of the allocator to manage an allocation request for this - size. +.. rubric:: OPTION TYPE: -DESCRIPTION: - The value of this configuration option is used to calculate the task stack - space size. +This configuration option is an initializer define. -NOTES: - This configuration option may be used if a custom task stack allocator is - configured, see :ref:`CONFIGURE_TASK_STACK_ALLOCATOR`. +.. rubric:: DEFAULT VALUE: -.. index:: CONFIGURE_TASK_STACK_ALLOCATOR_AVOIDS_WORK_SPACE - -.. _CONFIGURE_TASK_STACK_ALLOCATOR_AVOIDS_WORK_SPACE: +The default value is a macro which supports the system heap allocator. -CONFIGURE_TASK_STACK_ALLOCATOR_AVOIDS_WORK_SPACE ------------------------------------------------- +.. rubric:: DESCRIPTION: -CONSTANT: - ``CONFIGURE_TASK_STACK_ALLOCATOR_AVOIDS_WORK_SPACE`` +The value of this configuration option is used to calculate the task stack +space size. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: NOTES: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +This configuration option may be used if a custom task stack allocator is +configured, see :ref:`CONFIGURE_TASK_STACK_ALLOCATOR`. -DESCRIPTION: - In case this configuration option is defined, then the system is informed - that the task stack allocator does not use the RTEMS Workspace. +.. rubric:: CONSTRAINTS: -NOTES: - This configuration option may be used if a custom task stack allocator is - configured, see :ref:`CONFIGURE_TASK_STACK_ALLOCATOR`. +The value of the configuration option shall be defined to a macro which accepts +exactly one parameter and returns an unsigned integer. The parameter will be +an allocation size and the macro shall return this size plus the overhead of +the allocator to manage an allocation request for this size. diff --git a/c-user/constant_bandwidth_server.rst b/c-user/constant_bandwidth_server.rst index eddc89a..d610ad9 100644 --- a/c-user/constant_bandwidth_server.rst +++ b/c-user/constant_bandwidth_server.rst @@ -233,7 +233,7 @@ sequence, related constants, usage, and status codes. \clearpage .. index:: initialize the CBS library -.. index:: rtems_cbs_initialize +.. index:: rtems_cbs_initialize() .. _rtems_cbs_initialize: CBS_INITIALIZE - Initialize the CBS library @@ -271,7 +271,7 @@ NOTES: \clearpage .. index:: cleanup the CBS library -.. index:: rtems_cbs_cleanup +.. index:: rtems_cbs_cleanup() .. _rtems_cbs_cleanup: @@ -302,7 +302,7 @@ NOTES: \clearpage .. index:: create a new bandwidth server -.. index:: rtems_cbs_create_server +.. index:: rtems_cbs_create_server() .. _rtems_cbs_create_server: @@ -351,7 +351,7 @@ NOTES: \clearpage .. index:: attach a thread to server -.. index:: rtems_cbs_attach_thread +.. index:: rtems_cbs_attach_thread() .. _rtems_cbs_attach_thread: @@ -394,7 +394,7 @@ NOTES: \clearpage .. index:: detach a thread from server -.. index:: rtems_cbs_detach_thread +.. index:: rtems_cbs_detach_thread() .. _rtems_cbs_detach_thread: @@ -432,7 +432,7 @@ NOTES: \clearpage .. index:: destroy a bandwidth server -.. index:: rtems_cbs_destroy_server +.. index:: rtems_cbs_destroy_server() .. _rtems_cbs_destroy_server: @@ -470,7 +470,7 @@ NOTES: \clearpage .. index:: get an ID of a server -.. index:: rtems_cbs_get_server_id +.. index:: rtems_cbs_get_server_id() .. _rtems_cbs_get_server_id: @@ -502,7 +502,7 @@ DESCRIPTION: \clearpage .. index:: get scheduling parameters of a server -.. index:: rtems_cbs_get_parameters +.. index:: rtems_cbs_get_parameters() .. _rtems_cbs_get_parameters: @@ -540,7 +540,7 @@ NOTES: \clearpage .. index:: set scheduling parameters -.. index:: rtems_cbs_set_parameters +.. index:: rtems_cbs_set_parameters() .. _rtems_cbs_set_parameters: @@ -580,7 +580,7 @@ NOTES: \clearpage .. index:: get elapsed execution time -.. index:: rtems_cbs_get_execution_time +.. index:: rtems_cbs_get_execution_time() .. _rtems_cbs_get_execution_time: @@ -619,7 +619,7 @@ NOTES: \clearpage .. index:: get remaining execution time -.. index:: rtems_cbs_get_remaining_budget +.. index:: rtems_cbs_get_remaining_budget() .. _rtems_cbs_get_remaining_budget: @@ -658,7 +658,7 @@ NOTES: \clearpage .. index:: get scheduler approved execution time -.. index:: rtems_cbs_get_approved_budget +.. index:: rtems_cbs_get_approved_budget() .. _rtems_cbs_get_approved_budget: diff --git a/c-user/cpu_usage_statistics.rst b/c-user/cpu_usage_statistics.rst index 46d130c..4f98b75 100644 --- a/c-user/cpu_usage_statistics.rst +++ b/c-user/cpu_usage_statistics.rst @@ -108,7 +108,7 @@ calling sequence, related constants, usage, and status codes. \clearpage -.. index:: rtems_cpu_usage_report +.. index:: rtems_cpu_usage_report() .. _rtems_cpu_usage_report: @@ -134,7 +134,7 @@ NOTES: \clearpage -.. index:: rtems_cpu_usage_reset +.. index:: rtems_cpu_usage_reset() .. _rtems_cpu_usage_reset: diff --git a/c-user/directive_status_codes.rst b/c-user/directive_status_codes.rst index 1331076..0421af7 100644 --- a/c-user/directive_status_codes.rst +++ b/c-user/directive_status_codes.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2015 embedded brains GmbH +.. Copyright (C) 2015 embedded brains GmbH & Co. KG .. index:: Status Codes @@ -87,7 +87,7 @@ The directives are: \clearpage -.. index:: rtems_status_text +.. index:: rtems_status_text() .. _rtems_status_text: diff --git a/c-user/dual-ported-memory/background.rst b/c-user/dual-ported-memory/background.rst new file mode 100644 index 0000000..3b6301e --- /dev/null +++ b/c-user/dual-ported-memory/background.rst @@ -0,0 +1,23 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. index:: dual ported memory, definition +.. index:: external addresses, definition +.. index:: internal addresses, definition + +Background +========== + +A dual-ported memory area (DPMA) is an contiguous block of RAM owned by a +particular processor but which can be accessed by other processors in the +system. The owner accesses the memory using internal addresses, while other +processors must use external addresses. RTEMS defines a port as a particular +mapping of internal and external addresses. + +There are two system configurations in which dual-ported memory is commonly +found. The first is tightly-coupled multiprocessor computer systems where the +dual-ported memory is shared between all nodes and is used for inter-node +communication. The second configuration is computer systems with intelligent +peripheral controllers. These controllers typically utilize the DPMA for +high-performance data transfers. diff --git a/c-user/dual-ported-memory/directives.rst b/c-user/dual-ported-memory/directives.rst new file mode 100644 index 0000000..b96e3c7 --- /dev/null +++ b/c-user/dual-ported-memory/directives.rst @@ -0,0 +1,403 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. _DualPortedMemoryManagerDirectives: + +Directives +========== + +This section details the directives of the Dual-Ported Memory Manager. A +subsection is dedicated to each of this manager's directives and lists the +calling sequence, parameters, description, return values, and notes of the +directive. + +.. Generated from spec:/rtems/dpmem/if/create + +.. raw:: latex + + \clearpage + +.. index:: rtems_port_create() +.. index:: create a port + +.. _InterfaceRtemsPortCreate: + +rtems_port_create() +------------------- + +Creates a port. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_port_create( + rtems_name name, + void *internal_start, + void *external_start, + uint32_t length, + rtems_id *id + ); + +.. rubric:: PARAMETERS: + +``name`` + This parameter is the object name of the port. + +``internal_start`` + This parameter is the internal start address of the memory area. + +``external_start`` + This parameter is the external start address of the memory area. + +``length`` + This parameter is the length in bytes of the memory area. + +``id`` + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the identifier of the created port will + be stored in this object. + +.. rubric:: DESCRIPTION: + +This directive creates a port which resides on the local node. The port has +the user-defined object name specified in ``name``. The assigned object +identifier is returned in ``id``. This identifier is used to access the port +with other dual-ported memory port related directives. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_NAME` + The ``name`` parameter was invalid. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``id`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``internal_start`` parameter was not properly aligned. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``external_start`` parameter was not properly aligned. + +:c:macro:`RTEMS_TOO_MANY` + There was no inactive object available to create a port. The number of + port available to the application is configured through the + :ref:`CONFIGURE_MAXIMUM_PORTS` application configuration option. + +.. rubric:: NOTES: + +The ``internal_start`` and ``external_start`` parameters must be on a boundary +defined by the target processor architecture. + +For control and maintenance of the port, RTEMS allocates a :term:`DPCB` from +the local DPCB free pool and initializes it. + +.. 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. + +* The number of ports available to the application is configured through the + :ref:`CONFIGURE_MAXIMUM_PORTS` application configuration option. + +* Where the object class corresponding to the directive is configured to use + unlimited objects, the directive may allocate memory from the RTEMS + Workspace. + +.. Generated from spec:/rtems/dpmem/if/ident + +.. raw:: latex + + \clearpage + +.. index:: rtems_port_ident() + +.. _InterfaceRtemsPortIdent: + +rtems_port_ident() +------------------ + +Identifies a port by the object name. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_port_ident( rtems_name name, rtems_id *id ); + +.. rubric:: PARAMETERS: + +``name`` + This parameter is the object name to look up. + +``id`` + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the object identifier of an object with + the specified name will be stored in this object. + +.. rubric:: DESCRIPTION: + +This directive obtains a port identifier associated with the port name +specified in ``name``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``id`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_NAME` + The ``name`` parameter was 0. + +:c:macro:`RTEMS_INVALID_NAME` + There was no object with the specified name on the local node. + +.. rubric:: NOTES: + +If the port name is not unique, then the port identifier will match the first +port with that name in the search order. However, this port identifier is not +guaranteed to correspond to the desired port. + +The objects are searched from lowest to the highest index. Only the local node +is searched. + +The port identifier is used with other dual-ported memory related directives to +access the port. + +.. 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/dpmem/if/delete + +.. raw:: latex + + \clearpage + +.. index:: rtems_port_delete() +.. index:: delete a port + +.. _InterfaceRtemsPortDelete: + +rtems_port_delete() +------------------- + +Deletes the port. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_port_delete( rtems_id id ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the port identifier. + +.. rubric:: DESCRIPTION: + +This directive deletes the port specified by ``id``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no port associated with the identifier specified by ``id``. + +.. rubric:: NOTES: + +The :term:`DPCB` for the deleted port is reclaimed by RTEMS. + +.. 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. + +* The calling task does not have to be the task that created the object. Any + local task that knows the object identifier can delete the object. + +* Where the object class corresponding to the directive is configured to use + unlimited objects, the directive may free memory to the RTEMS Workspace. + +.. Generated from spec:/rtems/dpmem/if/external-to-internal + +.. raw:: latex + + \clearpage + +.. index:: rtems_port_external_to_internal() +.. index:: convert external to internal address + +.. _InterfaceRtemsPortExternalToInternal: + +rtems_port_external_to_internal() +--------------------------------- + +Converts the external address to the internal address. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_port_external_to_internal( + rtems_id id, + void *external, + void **internal + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the port identifier. + +``external`` + This parameter is the external address to convert. + +``internal`` + This parameter is the pointer to a ``void`` pointer object. When the + directive call is successful, the external address associated with the + internal address will be stored in this object. + +.. rubric:: DESCRIPTION: + +This directive converts a dual-ported memory address from external to internal +representation for the specified port. If the given external address is +invalid for the specified port, then the internal address is set to the given +external address. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_NAME` + The ``id`` parameter was invalid. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``internal`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/dpmem/if/internal-to-external + +.. raw:: latex + + \clearpage + +.. index:: rtems_port_internal_to_external() +.. index:: convert internal to external address + +.. _InterfaceRtemsPortInternalToExternal: + +rtems_port_internal_to_external() +--------------------------------- + +Converts the internal address to the external address. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_port_internal_to_external( + rtems_id id, + void *internal, + void **external + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the port identifier. + +``internal`` + This parameter is the internal address to convert. + +``external`` + This parameter is the pointer to a ``void`` pointer object. When the + directive call is successful, the external address associated with the + internal address will be stored in this object. + +.. rubric:: DESCRIPTION: + +This directive converts a dual-ported memory address from internal to external +representation so that it can be passed to owner of the DPMA represented by the +specified port. If the given internal address is an invalid dual-ported +address, then the external address is set to the given internal address. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_NAME` + The ``id`` parameter was invalid. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``external`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. diff --git a/c-user/dual-ported-memory/index.rst b/c-user/dual-ported-memory/index.rst new file mode 100644 index 0000000..98dd9fe --- /dev/null +++ b/c-user/dual-ported-memory/index.rst @@ -0,0 +1,18 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 embedded brains GmbH & Co. KG + +.. index:: ports +.. index:: dual ported memory + +.. _RTEMSAPIClassicDPMem: + +Dual-Ported Memory Manager +************************** + +.. toctree:: + + introduction + background + operations + directives diff --git a/c-user/dual-ported-memory/introduction.rst b/c-user/dual-ported-memory/introduction.rst new file mode 100644 index 0000000..515a1f1 --- /dev/null +++ b/c-user/dual-ported-memory/introduction.rst @@ -0,0 +1,49 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/rtems/dpmem/if/group + +.. _DualPortedMemoryManagerIntroduction: + +Introduction +============ + +.. The following list was generated from: +.. spec:/rtems/dpmem/if/create +.. spec:/rtems/dpmem/if/ident +.. spec:/rtems/dpmem/if/delete +.. spec:/rtems/dpmem/if/external-to-internal +.. spec:/rtems/dpmem/if/internal-to-external + +The Dual-Ported Memory Manager provides a mechanism for converting addresses +between internal and external representations for multiple dual-ported memory +areas (DPMA). The directives provided by the Dual-Ported Memory Manager are: + +* :ref:`InterfaceRtemsPortCreate` - Creates a port. + +* :ref:`InterfaceRtemsPortIdent` - Identifies a port by the object name. + +* :ref:`InterfaceRtemsPortDelete` - Deletes the port. + +* :ref:`InterfaceRtemsPortExternalToInternal` - Converts the external address + to the internal address. + +* :ref:`InterfaceRtemsPortInternalToExternal` - Converts the internal address + to the external address. diff --git a/c-user/dual-ported-memory/operations.rst b/c-user/dual-ported-memory/operations.rst new file mode 100644 index 0000000..15efb36 --- /dev/null +++ b/c-user/dual-ported-memory/operations.rst @@ -0,0 +1,44 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Operations +========== + +Creating a Port +--------------- + +The ``rtems_port_create`` directive creates a port into a DPMA with the +user-defined name. The user specifies the association between internal and +external representations for the port being created. RTEMS allocates a +Dual-Ported Memory Control Block (DPCB) from the DPCB free list to maintain the +newly created DPMA. RTEMS also generates a unique dual-ported memory port ID +which is returned to the calling task. RTEMS does not initialize the +dual-ported memory area or access any memory within it. + +Obtaining Port IDs +------------------ + +When a port is created, RTEMS generates a unique port ID and assigns it to the +created port until it is deleted. The port ID may be obtained by either of two +methods. First, as the result of an invocation of the``rtems_port_create`` +directive, the task ID is stored in a user provided location. Second, the port +ID may be obtained later using the ``rtems_port_ident`` directive. The port ID +is used by other dual-ported memory manager directives to access this port. + +Converting an Address +--------------------- + +The ``rtems_port_external_to_internal`` directive is used to convert an address +from external to internal representation for the specified port. The +``rtems_port_internal_to_external`` directive is used to convert an address +from internal to external representation for the specified port. If an attempt +is made to convert an address which lies outside the specified DPMA, then the +address to be converted will be returned. + +Deleting a DPMA Port +-------------------- + +A port can be removed from the system and returned to RTEMS with the +``rtems_port_delete`` directive. When a port is deleted, its control block is +returned to the DPCB free list. diff --git a/c-user/dual_ports_memory_manager.rst b/c-user/dual_ports_memory_manager.rst deleted file mode 100644 index 2c864ad..0000000 --- a/c-user/dual_ports_memory_manager.rst +++ /dev/null @@ -1,311 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-4.0 - -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) - -.. index:: ports -.. index:: dual ported memory - -Dual-Ported Memory Manager -************************** - -Introduction -============ - -The dual-ported memory manager provides a mechanism for converting addresses -between internal and external representations for multiple dual-ported memory -areas (DPMA). The directives provided by the dual-ported memory manager are: - -- rtems_port_create_ - Create a port - -- rtems_port_ident_ - Get ID of a port - -- rtems_port_delete_ - Delete a port - -- rtems_port_external_to_internal_ - Convert external to internal address - -- rtems_port_internal_to_external_ - Convert internal to external address - -.. index:: dual ported memory, definition -.. index:: external addresses, definition -.. index:: internal addresses, definition - -Background -========== - -A dual-ported memory area (DPMA) is an contiguous block of RAM owned by a -particular processor but which can be accessed by other processors in the -system. The owner accesses the memory using internal addresses, while other -processors must use external addresses. RTEMS defines a port as a particular -mapping of internal and external addresses. - -There are two system configurations in which dual-ported memory is commonly -found. The first is tightly-coupled multiprocessor computer systems where the -dual-ported memory is shared between all nodes and is used for inter-node -communication. The second configuration is computer systems with intelligent -peripheral controllers. These controllers typically utilize the DPMA for -high-performance data transfers. - -Operations -========== - -Creating a Port ---------------- - -The ``rtems_port_create`` directive creates a port into a DPMA with the -user-defined name. The user specifies the association between internal and -external representations for the port being created. RTEMS allocates a -Dual-Ported Memory Control Block (DPCB) from the DPCB free list to maintain the -newly created DPMA. RTEMS also generates a unique dual-ported memory port ID -which is returned to the calling task. RTEMS does not initialize the -dual-ported memory area or access any memory within it. - -Obtaining Port IDs ------------------- - -When a port is created, RTEMS generates a unique port ID and assigns it to the -created port until it is deleted. The port ID may be obtained by either of two -methods. First, as the result of an invocation of the``rtems_port_create`` -directive, the task ID is stored in a user provided location. Second, the port -ID may be obtained later using the ``rtems_port_ident`` directive. The port ID -is used by other dual-ported memory manager directives to access this port. - -Converting an Address ---------------------- - -The ``rtems_port_external_to_internal`` directive is used to convert an address -from external to internal representation for the specified port. The -``rtems_port_internal_to_external`` directive is used to convert an address -from internal to external representation for the specified port. If an attempt -is made to convert an address which lies outside the specified DPMA, then the -address to be converted will be returned. - -Deleting a DPMA Port --------------------- - -A port can be removed from the system and returned to RTEMS with the -``rtems_port_delete`` directive. When a port is deleted, its control block is -returned to the DPCB free list. - -Directives -========== - -This section details the dual-ported memory manager's directives. A subsection -is dedicated to each of this manager's directives and describes the calling -sequence, related constants, usage, and status codes. - -.. raw:: latex - - \clearpage - -.. index:: create a port -.. index:: rtems_port_create - -.. _rtems_port_create: - -PORT_CREATE - Create a port ---------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_port_create( - rtems_name name, - void *internal_start, - void *external_start, - uint32_t length, - rtems_id *id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - port created successfully - * - ``RTEMS_INVALID_NAME`` - - invalid port name - * - ``RTEMS_INVALID_ADDRESS`` - - address not on four byte boundary - * - ``RTEMS_INVALID_ADDRESS`` - - ``id`` is NULL - * - ``RTEMS_TOO_MANY`` - - too many DP memory areas created - -DESCRIPTION: - This directive creates a port which resides on the local node for the - specified DPMA. The assigned port id is returned in id. This port id is - used as an argument to other dual-ported memory manager directives to - convert addresses within this DPMA. - - For control and maintenance of the port, RTEMS allocates and initializes an - DPCB from the DPCB free pool. Thus memory from the dual-ported memory area - is not used to store the DPCB. - -NOTES: - The internal_address and external_address parameters must be on a four byte - boundary. - - This directive will not cause the calling task to be preempted. - -.. raw:: latex - - \clearpage - -.. index:: get ID of a port -.. index:: obtain ID of a port -.. index:: rtems_port_ident - -.. _rtems_port_ident: - -PORT_IDENT - Get ID of a port ------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_port_ident( - rtems_name name, - rtems_id *id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - port identified successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``id`` is NULL - * - ``RTEMS_INVALID_NAME`` - - port name not found - -DESCRIPTION: - This directive obtains the port id associated with the specified name to be - acquired. If the port name is not unique, then the port id will match one - of the DPMAs with that name. However, this port id is not guaranteed to - correspond to the desired DPMA. The port id is used to access this DPMA in - other dual-ported memory area related directives. - -NOTES: - This directive will not cause the running task to be preempted. - -.. raw:: latex - - \clearpage - -.. index:: delete a port -.. index:: rtems_port_delete - -.. _rtems_port_delete: - -PORT_DELETE - Delete a port ---------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_port_delete( - rtems_id id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - port deleted successfully - * - ``RTEMS_INVALID_ID`` - - invalid port id - -DESCRIPTION: - This directive deletes the dual-ported memory area specified by id. The - DPCB for the deleted dual-ported memory area is reclaimed by RTEMS. - -NOTES: - This directive will not cause the calling task to be preempted. - - The calling task does not have to be the task that created the port. Any - local task that knows the port id can delete the port. - -.. raw:: latex - - \clearpage - -.. index:: convert external to internal address -.. index:: rtems_port_external_to_internal - -.. _rtems_port_external_to_internal: - -PORT_EXTERNAL_TO_INTERNAL - Convert external to internal address ----------------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_port_external_to_internal( - rtems_id id, - void *external, - void **internal - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_INVALID_ADDRESS`` - - ``internal`` is NULL - * - ``RTEMS_SUCCESSFUL`` - - successful conversion - -DESCRIPTION: - This directive converts a dual-ported memory address from external to - internal representation for the specified port. If the given external - address is invalid for the specified port, then the internal address is set - to the given external address. - -NOTES: - This directive is callable from an ISR. - - This directive will not cause the calling task to be preempted. - -.. raw:: latex - - \clearpage - -.. index:: convert internal to external address -.. index:: rtems_port_internal_to_external - -.. _rtems_port_internal_to_external: - -PORT_INTERNAL_TO_EXTERNAL - Convert internal to external address ----------------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_port_internal_to_external( - rtems_id id, - void *internal, - void **external - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_INVALID_ADDRESS`` - - ``external`` is NULL - * - ``RTEMS_SUCCESSFUL`` - - successful conversion - -DESCRIPTION: - This directive converts a dual-ported memory address from internal to - external representation so that it can be passed to owner of the DPMA - represented by the specified port. If the given internal address is an - invalid dual-ported address, then the external address is set to the given - internal address. - -NOTES: - This directive is callable from an ISR. - - This directive will not cause the calling task to be preempted. diff --git a/c-user/event/background.rst b/c-user/event/background.rst new file mode 100644 index 0000000..f14e55f --- /dev/null +++ b/c-user/event/background.rst @@ -0,0 +1,96 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Background +========== + +.. index:: event flag, definition +.. index:: event set, definition +.. index:: rtems_event_set + +Event Sets +---------- + +An event flag is used by a task (or ISR) to inform another task of the +occurrence of a significant situation. Thirty-two event flags are associated +with each task. A collection of one or more event flags is referred to as an +event set. The data type ``rtems_event_set`` is used to manage event sets. + +The application developer should remember the following key characteristics of +event operations when utilizing the event manager: + +- Events provide a simple synchronization facility. + +- Events are aimed at tasks. + +- Tasks can wait on more than one event simultaneously. + +- Events are independent of one another. + +- Events do not hold or transport data. + +- Events are not queued. In other words, if an event is sent more than once to + a task before being received, the second and subsequent send operations to + that same task have no effect. + +An event set is posted when it is directed (or sent) to a task. A pending +event is an event that has been posted but not received. An event condition is +used to specify the event set which the task desires to receive and the +algorithm which will be used to determine when the request is satisfied. An +event condition is satisfied based upon one of two algorithms which are +selected by the user. The ``RTEMS_EVENT_ANY`` algorithm states that an event +condition is satisfied when at least a single requested event is posted. The +``RTEMS_EVENT_ALL`` algorithm states that an event condition is satisfied when +every requested event is posted. + +.. index:: event condition, building +.. index:: event set, building + +Building an Event Set or Condition +---------------------------------- + +An event set or condition is built by a bitwise OR of the desired events. The +set of valid events is ``RTEMS_EVENT_0`` through ``RTEMS_EVENT_31``. If an +event is not explicitly specified in the set or condition, then it is not +present. Events are specifically designed to be mutually exclusive, therefore +bitwise OR and addition operations are equivalent as long as each event appears +exactly once in the event set list. + +For example, when sending the event set consisting of ``RTEMS_EVENT_6``, +``RTEMS_EVENT_15``, and ``RTEMS_EVENT_31``, the event parameter to the +``rtems_event_send`` directive should be ``RTEMS_EVENT_6 | RTEMS_EVENT_15 | +RTEMS_EVENT_31``. + +Building an EVENT_RECEIVE Option Set +------------------------------------ + +In general, an option is built by a bitwise OR of the desired option +components. The set of valid options for the ``rtems_event_receive`` directive +are listed in the following table: + +.. list-table:: + :class: rtems-table + + * - ``RTEMS_WAIT`` + - task will wait for event (default) + * - ``RTEMS_NO_WAIT`` + - task should not wait + * - ``RTEMS_EVENT_ALL`` + - return after all events (default) + * - ``RTEMS_EVENT_ANY`` + - return after any events + +Option values are specifically designed to be mutually exclusive, therefore +bitwise OR and addition operations are equivalent as long as each option +appears exactly once in the component list. An option listed as a default is +not required to appear in the option list, although it is a good programming +practice to specify default options. If all defaults are desired, the option +``RTEMS_DEFAULT_OPTIONS`` should be specified on this call. + +This example demonstrates the option parameter needed to poll for all events in +a particular event condition to arrive. The option parameter passed to the +``rtems_event_receive`` directive should be either ``RTEMS_EVENT_ALL | +RTEMS_NO_WAIT`` or ``RTEMS_NO_WAIT``. The option parameter can be set to +``RTEMS_NO_WAIT`` because ``RTEMS_EVENT_ALL`` is the default condition for +``rtems_event_receive``. diff --git a/c-user/event/directives.rst b/c-user/event/directives.rst new file mode 100644 index 0000000..04a2894 --- /dev/null +++ b/c-user/event/directives.rst @@ -0,0 +1,255 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. _EventManagerDirectives: + +Directives +========== + +This section details the directives of the Event Manager. A subsection is +dedicated to each of this manager's directives and lists the calling sequence, +parameters, description, return values, and notes of the directive. + +.. Generated from spec:/rtems/event/if/send + +.. raw:: latex + + \clearpage + +.. index:: rtems_event_send() + +.. _InterfaceRtemsEventSend: + +rtems_event_send() +------------------ + +Sends the event set to the task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_event_send( rtems_id id, rtems_event_set event_in ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the identifier of the target task to receive the event + set. + +``event_in`` + This parameter is the event set to send. + +.. rubric:: DESCRIPTION: + +This directive sends the event set, ``event_in``, to the target task identified +by ``id``. Based upon the state of the target task, one of the following +situations applies: + +* The target task is blocked waiting for events, then + + * if the waiting task's input event condition is satisfied, then the task is + made ready for execution, or + + * otherwise, the event set is posted but left pending and the task remains + blocked. + +* The target task is not waiting for events, then the event set is posted and + left pending. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``id``. + +.. rubric:: NOTES: + +Events can be sent by tasks or an :term:`ISR`. + +Specifying :c:macro:`RTEMS_SELF` for ``id`` results in the event set being sent +to the calling task. + +The event set to send shall be built by a *bitwise or* of the desired events. +The set of valid events is :c:macro:`RTEMS_EVENT_0` through +:c:macro:`RTEMS_EVENT_31`. If an event is not explicitly specified in the set, +then it is not present. + +Identical events sent to a task are not queued. In other words, the second, +and subsequent, posting of an event to a task before it can perform an +:ref:`InterfaceRtemsEventReceive` has no effect. + +The calling task will be preempted if it has preemption enabled and a higher +priority task is unblocked as the result of this directive. + +Sending an event set to a global task which does not reside on the local node +will generate a request telling the remote node to send the event set to the +appropriate task. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may unblock a task. This may cause the calling task to be + preempted. + +.. Generated from spec:/rtems/event/if/receive + +.. raw:: latex + + \clearpage + +.. index:: rtems_event_receive() + +.. _InterfaceRtemsEventReceive: + +rtems_event_receive() +--------------------- + +Receives or gets an event set from the calling task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_event_receive( + rtems_event_set event_in, + rtems_option option_set, + rtems_interval ticks, + rtems_event_set *event_out + ); + +.. rubric:: PARAMETERS: + +``event_in`` + This parameter is the event set of interest. Use + :c:macro:`RTEMS_PENDING_EVENTS` to get the pending events. + +``option_set`` + This parameter is the option set. + +``ticks`` + This parameter is the timeout in clock ticks if the :c:macro:`RTEMS_WAIT` + option is set. Use :c:macro:`RTEMS_NO_TIMEOUT` to wait potentially + forever. + +``event_out`` + This parameter is the pointer to an event set. The received or pending + events are stored in the referenced event set if the operation was + successful. + +.. rubric:: DESCRIPTION: + +This directive can be used to + +* get the pending events of the calling task, or + +* receive events. + +To **get the pending events** use the constant :c:macro:`RTEMS_PENDING_EVENTS` +for the ``event_in`` parameter. The pending events are returned to the calling +task but the event set of the calling task is left unaltered. The +``option_set`` and ``ticks`` parameters are ignored in this case. The +directive returns immediately and does not block. + +To **receive events** you have to define an input event condition and some +options. + +The **option set** specified in ``option_set`` is built through a *bitwise or* +of the option constants described below. Not all combinations of options are +allowed. Some options are mutually exclusive. If mutually exclusive options +are combined, the behaviour is undefined. Options not mentioned below are not +evaluated by this directive and have no effect. Default options can be selected +by using the :c:macro:`RTEMS_DEFAULT_OPTIONS` constant. The option set defines + +* if the calling task will wait or poll for the events, and + +* if the calling task wants to receive all or any of the input events. + +The calling task can **wait** or **poll** for the events. + +* **Waiting** for events is the default and can be emphasized through the use + of the :c:macro:`RTEMS_WAIT` option. The ``ticks`` parameter defines how + long the calling task is willing to wait. Use :c:macro:`RTEMS_NO_TIMEOUT` to + wait potentially forever, otherwise set a timeout interval in clock ticks. + +* Not waiting for events (**polling**) is selected by the + :c:macro:`RTEMS_NO_WAIT` option. If this option is defined, then the + ``ticks`` parameter is ignored. + +The calling task can receive **all** or **any** of the input events specified +in ``event_in``. + +* Receiving **all** input events is the default and can be emphasized through + the use of the :c:macro:`RTEMS_EVENT_ALL` option. + +* Receiving **any** of the input events is selected by the + :c:macro:`RTEMS_EVENT_ANY` option. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``event_out`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_UNSATISFIED` + The events of interest were not immediately available. + +:c:macro:`RTEMS_TIMEOUT` + The events of interest were not available within the specified timeout + interval. + +.. rubric:: NOTES: + +This directive only affects the events specified in ``event_in``. Any pending +events that do not correspond to any of the events specified in ``event_in`` +will be left pending. + +To receive all events use the event set constant :c:macro:`RTEMS_ALL_EVENTS` +for the ``event_in`` parameter. Do not confuse this event set constant with +the directive option :c:macro:`RTEMS_EVENT_ALL`. + +A task can **receive all of the pending events** by calling the directive with +a value of :c:macro:`RTEMS_ALL_EVENTS` for the ``event_in`` parameter and the +bitwise or of the :c:macro:`RTEMS_NO_WAIT` and :c:macro:`RTEMS_EVENT_ANY` +options for the ``option_set`` parameter. The pending events are returned and +the event set of the task is cleared. If no events are pending then the +:c:macro:`RTEMS_UNSATISFIED` status code will be returned. + +.. 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 timeout functionality of the directive requires a :term:`clock tick`. diff --git a/c-user/event/index.rst b/c-user/event/index.rst new file mode 100644 index 0000000..dd926e1 --- /dev/null +++ b/c-user/event/index.rst @@ -0,0 +1,17 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 embedded brains GmbH & Co. KG + +.. index:: events + +.. _RTEMSAPIClassicEvent: + +Event Manager +************* + +.. toctree:: + + introduction + background + operations + directives diff --git a/c-user/event/introduction.rst b/c-user/event/introduction.rst new file mode 100644 index 0000000..ebdec2d --- /dev/null +++ b/c-user/event/introduction.rst @@ -0,0 +1,39 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/rtems/event/if/group + +.. _EventManagerIntroduction: + +Introduction +============ + +.. The following list was generated from: +.. spec:/rtems/event/if/send +.. spec:/rtems/event/if/receive + +The Event Manager provides a high performance method of inter-task +communication and synchronization. The directives provided by the Event Manager +are: + +* :ref:`InterfaceRtemsEventSend` - Sends the event set to the task. + +* :ref:`InterfaceRtemsEventReceive` - Receives or gets an event set from the + calling task. diff --git a/c-user/event/operations.rst b/c-user/event/operations.rst new file mode 100644 index 0000000..e01b6dc --- /dev/null +++ b/c-user/event/operations.rst @@ -0,0 +1,63 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Operations +========== + +Sending an Event Set +-------------------- + +The ``rtems_event_send`` directive allows a task (or an ISR) to direct an event +set to a target task. Based upon the state of the target task, one of the +following situations applies: + +- Target Task is Blocked Waiting for Events + + - If the waiting task's input event condition is satisfied, then the task is + made ready for execution. + + - If the waiting task's input event condition is not satisfied, then the + event set is posted but left pending and the task remains blocked. + +- Target Task is Not Waiting for Events + + - The event set is posted and left pending. + +Receiving an Event Set +---------------------- + +The ``rtems_event_receive`` directive is used by tasks to accept a specific +input event condition. The task also specifies whether the request is +satisfied when all requested events are available or any single requested event +is available. If the requested event condition is satisfied by pending events, +then a successful return code and the satisfying event set are returned +immediately. If the condition is not satisfied, then one of the following +situations applies: + +- By default, the calling task will wait forever for the event condition to be + satisfied. + +- Specifying the ``RTEMS_NO_WAIT`` option forces an immediate return with an + error status code. + +- Specifying a timeout limits the period the task will wait before returning + with an error status code. + +Determining the Pending Event Set +--------------------------------- + +A task can determine the pending event set by calling the +``rtems_event_receive`` directive with a value of ``RTEMS_PENDING_EVENTS`` for +the input event condition. The pending events are returned to the calling task +but the event set is left unaltered. + +Receiving all Pending Events +---------------------------- + +A task can receive all of the currently pending events by calling the +``rtems_event_receive`` directive with a value of ``RTEMS_ALL_EVENTS`` for the +input event condition and ``RTEMS_NO_WAIT | RTEMS_EVENT_ANY`` for the option +set. The pending events are returned to the calling task and the event set is +cleared. If no events are pending then the ``RTEMS_UNSATISFIED`` status code +will be returned. diff --git a/c-user/event_manager.rst b/c-user/event_manager.rst deleted file mode 100644 index f7593e5..0000000 --- a/c-user/event_manager.rst +++ /dev/null @@ -1,309 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-4.0 - -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) - -.. index:: events - -Event Manager -************* - -Introduction -============ - -The event manager provides a high performance method of intertask communication -and synchronization. The directives provided by the event manager are: - -- rtems_event_send_ - Send event set to a task -- rtems_event_receive_ - Receive event condition - -Background -========== - -.. index:: event flag, definition -.. index:: event set, definition -.. index:: rtems_event_set - -Event Sets ----------- - -An event flag is used by a task (or ISR) to inform another task of the -occurrence of a significant situation. Thirty-two event flags are associated -with each task. A collection of one or more event flags is referred to as an -event set. The data type ``rtems_event_set`` is used to manage event sets. - -The application developer should remember the following key characteristics of -event operations when utilizing the event manager: - -- Events provide a simple synchronization facility. - -- Events are aimed at tasks. - -- Tasks can wait on more than one event simultaneously. - -- Events are independent of one another. - -- Events do not hold or transport data. - -- Events are not queued. In other words, if an event is sent more than once to - a task before being received, the second and subsequent send operations to - that same task have no effect. - -An event set is posted when it is directed (or sent) to a task. A pending -event is an event that has been posted but not received. An event condition is -used to specify the event set which the task desires to receive and the -algorithm which will be used to determine when the request is satisfied. An -event condition is satisfied based upon one of two algorithms which are -selected by the user. The ``RTEMS_EVENT_ANY`` algorithm states that an event -condition is satisfied when at least a single requested event is posted. The -``RTEMS_EVENT_ALL`` algorithm states that an event condition is satisfied when -every requested event is posted. - -.. index:: event condition, building -.. index:: event set, building - -Building an Event Set or Condition ----------------------------------- - -An event set or condition is built by a bitwise OR of the desired events. The -set of valid events is ``RTEMS_EVENT_0`` through ``RTEMS_EVENT_31``. If an -event is not explicitly specified in the set or condition, then it is not -present. Events are specifically designed to be mutually exclusive, therefore -bitwise OR and addition operations are equivalent as long as each event appears -exactly once in the event set list. - -For example, when sending the event set consisting of ``RTEMS_EVENT_6``, -``RTEMS_EVENT_15``, and ``RTEMS_EVENT_31``, the event parameter to the -``rtems_event_send`` directive should be ``RTEMS_EVENT_6 | RTEMS_EVENT_15 | -RTEMS_EVENT_31``. - -Building an EVENT_RECEIVE Option Set ------------------------------------- - -In general, an option is built by a bitwise OR of the desired option -components. The set of valid options for the ``rtems_event_receive`` directive -are listed in the following table: - -.. list-table:: - :class: rtems-table - - * - ``RTEMS_WAIT`` - - task will wait for event (default) - * - ``RTEMS_NO_WAIT`` - - task should not wait - * - ``RTEMS_EVENT_ALL`` - - return after all events (default) - * - ``RTEMS_EVENT_ANY`` - - return after any events - -Option values are specifically designed to be mutually exclusive, therefore -bitwise OR and addition operations are equivalent as long as each option -appears exactly once in the component list. An option listed as a default is -not required to appear in the option list, although it is a good programming -practice to specify default options. If all defaults are desired, the option -``RTEMS_DEFAULT_OPTIONS`` should be specified on this call. - -This example demonstrates the option parameter needed to poll for all events in -a particular event condition to arrive. The option parameter passed to the -``rtems_event_receive`` directive should be either ``RTEMS_EVENT_ALL | -RTEMS_NO_WAIT`` or ``RTEMS_NO_WAIT``. The option parameter can be set to -``RTEMS_NO_WAIT`` because ``RTEMS_EVENT_ALL`` is the default condition for -``rtems_event_receive``. - -Operations -========== - -Sending an Event Set --------------------- - -The ``rtems_event_send`` directive allows a task (or an ISR) to direct an event -set to a target task. Based upon the state of the target task, one of the -following situations applies: - -- Target Task is Blocked Waiting for Events - - - If the waiting task's input event condition is satisfied, then the task is - made ready for execution. - - - If the waiting task's input event condition is not satisfied, then the - event set is posted but left pending and the task remains blocked. - -- Target Task is Not Waiting for Events - - - The event set is posted and left pending. - -Receiving an Event Set ----------------------- - -The ``rtems_event_receive`` directive is used by tasks to accept a specific -input event condition. The task also specifies whether the request is -satisfied when all requested events are available or any single requested event -is available. If the requested event condition is satisfied by pending events, -then a successful return code and the satisfying event set are returned -immediately. If the condition is not satisfied, then one of the following -situations applies: - -- By default, the calling task will wait forever for the event condition to be - satisfied. - -- Specifying the ``RTEMS_NO_WAIT`` option forces an immediate return with an - error status code. - -- Specifying a timeout limits the period the task will wait before returning - with an error status code. - -Determining the Pending Event Set ---------------------------------- - -A task can determine the pending event set by calling the -``rtems_event_receive`` directive with a value of ``RTEMS_PENDING_EVENTS`` for -the input event condition. The pending events are returned to the calling task -but the event set is left unaltered. - -Receiving all Pending Events ----------------------------- - -A task can receive all of the currently pending events by calling the -``rtems_event_receive`` directive with a value of ``RTEMS_ALL_EVENTS`` for the -input event condition and ``RTEMS_NO_WAIT | RTEMS_EVENT_ANY`` for the option -set. The pending events are returned to the calling task and the event set is -cleared. If no events are pending then the ``RTEMS_UNSATISFIED`` status code -will be returned. - -Directives -========== - -This section details the event manager's directives. A subsection is dedicated -to each of this manager's directives and describes the calling sequence, -related constants, usage, and status codes. - -.. raw:: latex - - \clearpage - -.. index:: send event set to a task -.. index:: rtems_event_send - -.. _rtems_event_send: - -EVENT_SEND - Send event set to a task -------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_event_send ( - rtems_id id, - rtems_event_set event_in - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - event set sent successfully - * - ``RTEMS_INVALID_ID`` - - invalid task id - -DESCRIPTION: - This directive sends an event set, event_in, to the task specified by id. - If a blocked task's input event condition is satisfied by this directive, - then it will be made ready. If its input event condition is not satisfied, - then the events satisfied are updated and the events not satisfied are left - pending. If the task specified by id is not blocked waiting for events, - then the events sent are left pending. - -NOTES: - Specifying ``RTEMS_SELF`` for id results in the event set being sent to the - calling task. - - Identical events sent to a task are not queued. In other words, the - second, and subsequent, posting of an event to a task before it can perform - an ``rtems_event_receive`` has no effect. - - The calling task will be preempted if it has preemption enabled and a - higher priority task is unblocked as the result of this directive. - - Sending an event set to a global task which does not reside on the local - node will generate a request telling the remote node to send the event set - to the appropriate task. - -.. raw:: latex - - \clearpage - -.. index:: receive event condition -.. index:: rtems_event_receive - -.. _rtems_event_receive: - -EVENT_RECEIVE - Receive event condition ---------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_event_receive ( - rtems_event_set event_in, - rtems_option option_set, - rtems_interval ticks, - rtems_event_set *event_out - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - event received successfully - * - ``RTEMS_UNSATISFIED`` - - input event not satisfied (``RTEMS_NO_WAIT``) - * - ``RTEMS_INVALID_ADDRESS`` - - ``event_out`` is NULL - * - ``RTEMS_TIMEOUT`` - - timed out waiting for event - -DESCRIPTION: - - This directive attempts to receive the event condition specified in - event_in. If event_in is set to ``RTEMS_PENDING_EVENTS``, then the current - pending events are returned in event_out and left pending. The - ``RTEMS_WAIT`` and ``RTEMS_NO_WAIT`` options in the option_set parameter - are used to specify whether or not the task is willing to wait for the - event condition to be satisfied. ``RTEMS_EVENT_ANY`` and - ``RTEMS_EVENT_ALL`` are used in the option_set parameter are used to - specify whether a single event or the complete event set is necessary to - satisfy the event condition. The event_out parameter is returned to the - calling task with the value that corresponds to the events in event_in that - were satisfied. - - If pending events satisfy the event condition, then event_out is set to the - satisfied events and the pending events in the event condition are cleared. - If the event condition is not satisfied and ``RTEMS_NO_WAIT`` is specified, - then event_out is set to the currently satisfied events. If the calling - task chooses to wait, then it will block waiting for the event condition. - - If the calling task must wait for the event condition to be satisfied, then - the timeout parameter is used to specify the maximum interval to wait. If - it is set to ``RTEMS_NO_TIMEOUT``, then the calling task will wait forever. - -NOTES: - This directive only affects the events specified in event_in. Any pending - events that do not correspond to any of the events specified in event_in - will be left pending. - - The following event receive option constants are defined by RTEMS: - - .. list-table:: - :class: rtems-table - - * - ``RTEMS_WAIT`` - - task will wait for event (default) - * - ``RTEMS_NO_WAIT`` - - task should not wait - * - ``RTEMS_EVENT_ALL`` - - return after all events (default) - * - ``RTEMS_EVENT_ANY`` - - return after any events - - A clock tick is required to support the functionality of this directive. diff --git a/c-user/fatal_error.rst b/c-user/fatal-error/background.rst index 2c72deb..e3d7320 100644 --- a/c-user/fatal_error.rst +++ b/c-user/fatal-error/background.rst @@ -2,35 +2,6 @@ .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) -.. index:: fatal errors - -.. _fatal_error_manager: - -Fatal Error Manager -******************* - -Introduction -============ - -The fatal error manager processes all fatal or irrecoverable errors and other -sources of system termination (for example after :c:func:`exit()`). Fatal -errors are identified by the (fatal source, error code) pair. The directives -provided by the fatal error manager are: - -- rtems_fatal_ - Invoke the fatal error handler - -- rtems_panic_ - Print a message and invoke the fatal error handler - -- rtems_shutdown_executive_ - Shutdown RTEMS - -- rtems_exception_frame_print_ - Print the CPU exception frame - -- rtems_fatal_source_text_ - Return the fatal source text - -- rtems_internal_error_text_ - Return the error code text - -- rtems_fatal_error_occurred_ - Invoke the fatal error handler (deprecated) - Background ========== @@ -73,6 +44,8 @@ a register), and halt the processor. The precise actions of the RTEMS fatal error are discussed in the Default Fatal Error Processing chapter of the Applications Supplement document for a specific target processor. +.. _FatalErrorSources: + Fatal Sources ------------- @@ -146,15 +119,6 @@ INTERNAL_ERROR_TOO_LITTLE_WORKSPACE (2) There is not enough memory for the workspace. This fatal error may occur during system initialization. It is an application configuration error. -INTERNAL_ERROR_WORKSPACE_ALLOCATION (3) - An allocation from the workspace failed. This fatal error may occur during - system initialization. It is an application configuration error. - -INTERNAL_ERROR_INTERRUPT_STACK_TOO_SMALL (4) - The configured interrupt stack size is too small. This fatal error may - occur during system initialization. It is an application configuration - error. - INTERNAL_ERROR_THREAD_EXITTED (5) A non-POSIX thread entry function returned. This is an API usage error. @@ -222,17 +186,6 @@ INTERNAL_ERROR_INVALID_GLOBAL_ID (13) find the global object for a specific object identifier. In case this happens, then this is probably an operating system bug. -INTERNAL_ERROR_BAD_STACK_HOOK (14) - The stack allocator hook or stack free hook is NULL. This fatal error may - occur during system initialization. It is an application configuration - error. - -INTERNAL_ERROR_UNLIMITED_AND_MAXIMUM_IS_0 (19) - An object class is configured to use the unlimited objects option, however, - the count of objects for each extension is zero. This fatal error may - occur during system initialization. It is an application configuration - error. - INTERNAL_ERROR_NO_MEMORY_FOR_HEAP (23) There is not enough memory for the C program heap. This fatal error may occur during system initialization. It is an application configuration @@ -363,24 +316,15 @@ INTERNAL_ERROR_BAD_THREAD_DISPATCH_ENVIRONMENT (31) } INTERNAL_ERROR_RTEMS_INIT_TASK_CREATE_FAILED (32) - Creation of an RTEMS initialization task failed. This fatal error may + The creation of the RTEMS initialization task failed. This fatal error may occur during system initialization. It is an application configuration error. INTERNAL_ERROR_POSIX_INIT_THREAD_CREATE_FAILED (33) - Creation of a POSIX initialization thread failed. This fatal error may - occur during system initialization. It is an application configuration + The creation of the POSIX initialization thread failed. This fatal error + may occur during system initialization. It is an application configuration error. -INTERNAL_ERROR_LIBIO_USER_ENV_KEY_CREATE_FAILED (34) - Creation of the IO library user environment POSIX key failed. This fatal - error may occur during system initialization. It is an application - configuration error. - -INTERNAL_ERROR_LIBIO_SEM_CREATE_FAILED (35) - Creation of the IO library semaphore failed. This fatal error may occur - during system initialization. It is an application configuration error. - INTERNAL_ERROR_LIBIO_STDOUT_FD_OPEN_FAILED (36) Open of the standard output file descriptor failed or resulted in an unexpected file descriptor number. This fatal error may occur during @@ -405,273 +349,32 @@ INTERNAL_ERROR_NO_MEMORY_FOR_PER_CPU_DATA (40) enough memory available to populate the per-CPU data areas, see `<rtems/score/percpudata.h> <https://git.rtems.org/rtems/tree/cpukit/include/rtems/score/percpudata.h>`_. -Operations -========== - -.. index:: _Terminate - -.. _Terminate: - -Announcing a Fatal Error ------------------------- - -The :c:func:`_Terminate()` internal error handler is invoked when the -application or the executive itself determines that a fatal error has occurred -or a final system state is reached (for example after :c:func:`rtems_fatal()` -or :c:func:`exit()`). - -The first action of the internal error handler is to call the fatal extension of -the user extensions. For the initial extensions the following conditions are -required - -- a valid stack pointer and enough stack space, - -- a valid code memory, and - -- valid read-only data. - -For the initial extensions the read-write data (including .bss segment) is not -required on single processor configurations. In SMP configurations, however, -the read-write data must be initialized since this function must determine the -state of the other processors and request them to shut-down if necessary. - -Non-initial extensions require in addition valid read-write data. The board -support package (BSP) may install an initial extension that performs a system -reset. In this case the non-initial extensions will be not called. - -The fatal extensions are called with three parameters: - -- the fatal source, - -- a legacy parameter which is always false, and - -- an error code with a fatal source dependent content. - -Once all fatal extensions executed, the error information will be stored to -:c:data:`_Internal_errors_What_happened` and the system state is set to -:c:macro:`SYSTEM_STATE_TERMINATED`. - -The final step is to call the CPU port specific :c:func:`_CPU_Fatal_halt()`. - -Directives -========== - -This section details the fatal error manager's directives. A subsection is -dedicated to each of this manager's directives and describes the calling -sequence, related constants, usage, and status codes. - -.. raw:: latex - - \clearpage - -.. index:: announce fatal error -.. index:: fatal error, announce -.. index:: rtems_fatal - -.. _rtems_fatal: - -FATAL - Invoke the fatal error handler --------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - void rtems_fatal( - rtems_fatal_source fatal_source, - rtems_fatal_code error_code - ) RTEMS_NO_RETURN; - -DIRECTIVE STATUS CODES: - NONE - This function will not return to the caller. - -DESCRIPTION: - This directive terminates the system. - -NOTE: - Registered :c:func:`atexit()` or :c:func:`on_exit()` handlers are not - called. Use :c:func:`exit()` in case these handlers should be invoked. - -.. raw:: latex - - \clearpage - -.. index:: panic -.. index:: rtems_panic - -.. _rtems_panic: - -PANIC - Print a message and invoke the fatal error handler ----------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - void rtems_panic( - const char *fmt, - ... - ) RTEMS_NO_RETURN RTEMS_PRINTFLIKE( 1, 2 ); - -DIRECTIVE STATUS CODES: - NONE - This function will not return to the caller. - -DESCRIPTION: - This directive prints a message via :c:func:`printk` specified by the - format and optional parameters and then terminates the system with the - :c:macro:`RTEMS_FATAL_SOURCE_PANIC` fatal source. The fatal code is set to - the format string address. - -NOTE: - Registered :c:func:`atexit()` or :c:func:`on_exit()` handlers are not - called. Use :c:func:`exit()` in case these handlers should be invoked. - -.. raw:: latex - - \clearpage - -.. index:: shutdown RTEMS -.. index:: rtems_shutdown_executive - -.. _rtems_shutdown_executive: - -SHUTDOWN_EXECUTIVE - Shutdown RTEMS ------------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - void rtems_shutdown_executive( - uint32_t result - ); - -DIRECTIVE STATUS CODES: - NONE - This function will not return to the caller. - -DESCRIPTION: - This directive is called when the application wishes to shutdown RTEMS. - The system is terminated with a fatal source of ``RTEMS_FATAL_SOURCE_EXIT`` - and the specified ``result`` code. - -NOTES: - This directive *must* be the last RTEMS directive invoked by an application - and it *does not return* to the caller. - - This directive may be called any time. - -.. raw:: latex - - \clearpage - -.. index:: exception frame -.. index:: rtems_exception_frame_print - -.. _rtems_exception_frame_print: - -EXCEPTION_FRAME_PRINT - Prints the exception frame --------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - void rtems_exception_frame_print( - const rtems_exception_frame *frame - ); - -DIRECTIVE STATUS CODES: - NONE - -DESCRIPTION: - Prints the exception frame via ``printk()``. - -.. raw:: latex - - \clearpage - -.. index:: fatal error -.. index:: rtems_fatal_source_text - -.. _rtems_fatal_source_text: - -FATAL_SOURCE_TEXT - Returns a text for a fatal source ------------------------------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - const char *rtems_fatal_source_text( - rtems_fatal_source source - ); - -DIRECTIVE STATUS CODES: - The fatal source text or "?" in case the passed fatal source is invalid. - -DESCRIPTION: - Returns a text for a fatal source. The text for fatal source is the - enumerator constant. - -.. raw:: latex - - \clearpage - -.. index:: fatal error -.. index:: rtems_internal_error_text - -.. _rtems_internal_error_text: - -INTERNAL_ERROR_TEXT - Returns a text for an internal error code ---------------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - const char *rtems_internal_error_text( - rtems_fatal_code error - ); - -DIRECTIVE STATUS CODES: - The error code text or "?" in case the passed error code is invalid. - -DESCRIPTION: - Returns a text for an internal error code. The text for each internal - error code is the enumerator constant. - -.. raw:: latex - - \clearpage - -.. index:: announce fatal error -.. index:: fatal error, announce -.. index:: rtems_fatal_error_occurred - -.. _rtems_fatal_error_occurred: - -FATAL_ERROR_OCCURRED - Invoke the fatal error handler (deprecated) ------------------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - void rtems_fatal_error_occurred( - uint32_t the_error - ) RTEMS_NO_RETURN; - -DIRECTIVE STATUS CODES: - NONE - This function will not return to the caller. - -DESCRIPTION: - This directive processes fatal errors. If the FATAL error extension is - defined in the configuration table, then the user-defined error extension - is called. If configured and the provided FATAL error extension returns, - then the RTEMS default error handler is invoked. This directive can be - invoked by RTEMS or by the user's application code including initialization - tasks, other tasks, and ISRs. - -NOTES: - This directive is deprecated and should not be used in new code. +INTERNAL_ERROR_TOO_LARGE_TLS_SIZE (41) + This fatal error may happen during system initialization. The actual + thread-local storage (TLS) size of the application exceeds the configured + maximum, see + :ref:`CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE <CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE>`. + You can get the thread-local storage size of an application using the RTEMS + tool ``rtems-execinfo``. + +INTERNAL_ERROR_RTEMS_INIT_TASK_CONSTRUCT_FAILED (42) + The construction of the RTEMS initialization task failed. This fatal error + may occur during system initialization. It is an application configuration + error. - This directive supports local operations only. +INTERNAL_ERROR_IDLE_THREAD_CREATE_FAILED (43) + The creation of an IDLE task failed. This fatal error may occur during + system initialization. It happens if a task create extension fails for an + IDLE task. - Unless the user-defined error extension takes special actions such as - restarting the calling task, this directive WILL NOT RETURN to the caller. +INTERNAL_ERROR_NO_MEMORY_FOR_IDLE_TASK_STORAGE (44) + There was not enough memory available to allocate an IDLE task stack. This + fatal error may occur during system initialization. It is an application + configuration error. - The user-defined extension for this directive may wish to initiate a global - shutdown. +INTERNAL_ERROR_IDLE_THREAD_STACK_TOO_SMALL (45) + The task stack size of an IDLE task would have been less than the + configured stack size for IDLE tasks, see + :ref:`CONFIGURE_IDLE_TASK_STACK_SIZE <CONFIGURE_IDLE_TASK_STACK_SIZE>`. + This fatal error may occur during system initialization. It is an + application configuration error. diff --git a/c-user/fatal-error/directives.rst b/c-user/fatal-error/directives.rst new file mode 100644 index 0000000..434172f --- /dev/null +++ b/c-user/fatal-error/directives.rst @@ -0,0 +1,355 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2015, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. _FatalErrorManagerDirectives: + +Directives +========== + +This section details the directives of the Fatal Error Manager. A subsection is +dedicated to each of this manager's directives and lists the calling sequence, +parameters, description, return values, and notes of the directive. + +.. Generated from spec:/rtems/fatal/if/fatal + +.. raw:: latex + + \clearpage + +.. index:: rtems_fatal() +.. index:: announce fatal error +.. index:: fatal error, announce + +.. _InterfaceRtemsFatal: + +rtems_fatal() +------------- + +Invokes the fatal error handler. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_fatal( + rtems_fatal_source fatal_source, + rtems_fatal_code fatal_code + ); + +.. rubric:: PARAMETERS: + +``fatal_source`` + This parameter is the fatal source. + +``fatal_code`` + This parameter is the fatal code. + +.. rubric:: DESCRIPTION: + +This directive processes fatal errors. The fatal source is set to the value of +the ``fatal_source`` parameter. The fatal code is set to the value of the +``fatal_code`` parameter. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not return to the caller. + +* The directive invokes the fatal error extensions in :term:`extension forward + order`. + +* The directive does not invoke handlers registered by :c:func:`atexit` or + :c:func:`on_exit`. + +* The directive may terminate the system. + +.. Generated from spec:/rtems/fatal/if/panic + +.. raw:: latex + + \clearpage + +.. index:: rtems_panic() +.. index:: panic + +.. _InterfaceRtemsPanic: + +rtems_panic() +------------- + +Prints the message and invokes the fatal error handler. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_panic( const char *fmt, ... ); + +.. rubric:: PARAMETERS: + +``fmt`` + This parameter is the message format. + +``...`` + This parameter is a list of optional parameters required by the message + format. + +.. rubric:: DESCRIPTION: + +This directive prints a message via :ref:`InterfacePrintk` specified by the +``fmt`` parameter and optional parameters and then invokes the fatal error +handler. The fatal source is set to :c:macro:`RTEMS_FATAL_SOURCE_PANIC`. The +fatal code is set to the value of the ``fmt`` parameter value. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not return to the caller. + +* The directive invokes the fatal error extensions in :term:`extension forward + order`. + +* The directive does not invoke handlers registered by :c:func:`atexit` or + :c:func:`on_exit`. + +* The directive may terminate the system. + +.. Generated from spec:/rtems/fatal/if/shutdown-executive + +.. raw:: latex + + \clearpage + +.. index:: rtems_shutdown_executive() +.. index:: shutdown RTEMS + +.. _InterfaceRtemsShutdownExecutive: + +rtems_shutdown_executive() +-------------------------- + +Invokes the fatal error handler. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_shutdown_executive( uint32_t fatal_code ); + +.. rubric:: PARAMETERS: + +``fatal_code`` + This parameter is the fatal code. + +.. rubric:: DESCRIPTION: + +This directive processes fatal errors. The fatal source is set to +:c:macro:`RTEMS_FATAL_SOURCE_EXIT`. The fatal code is set to the value of the +``fatal_code`` parameter. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not return to the caller. + +* The directive invokes the fatal error extensions in :term:`extension forward + order`. + +* The directive does not invoke handlers registered by :c:func:`atexit` or + :c:func:`on_exit`. + +* The directive may terminate the system. + +.. Generated from spec:/rtems/fatal/if/exception-frame-print + +.. raw:: latex + + \clearpage + +.. index:: rtems_exception_frame_print() +.. index:: exception frame + +.. _InterfaceRtemsExceptionFramePrint: + +rtems_exception_frame_print() +----------------------------- + +Prints the exception frame. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_exception_frame_print( const rtems_exception_frame *frame ); + +.. rubric:: PARAMETERS: + +``frame`` + This parameter is the reference to the exception frame to print. + +.. rubric:: DESCRIPTION: + +The exception frame is printed in an architecture-dependent format using +:ref:`InterfacePrintk`. + +.. Generated from spec:/rtems/fatal/if/source-text + +.. raw:: latex + + \clearpage + +.. index:: rtems_fatal_source_text() +.. index:: fatal error + +.. _InterfaceRtemsFatalSourceText: + +rtems_fatal_source_text() +------------------------- + +Returns a descriptive text for the fatal source. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + const char *rtems_fatal_source_text( rtems_fatal_source fatal_source ); + +.. rubric:: PARAMETERS: + +``fatal_source`` + This parameter is the fatal source. + +.. rubric:: RETURN VALUES: + +"?" + The ``fatal_source`` parameter value was not a fatal source. + +Returns a descriptive text for the fatal source. The text for the fatal source +is the enumerator constant name. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +.. Generated from spec:/rtems/fatal/if/internal-error-text + +.. raw:: latex + + \clearpage + +.. index:: rtems_internal_error_text() +.. index:: fatal error + +.. _InterfaceRtemsInternalErrorText: + +rtems_internal_error_text() +--------------------------- + +Returns a descriptive text for the internal error code. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + const char *rtems_internal_error_text( rtems_fatal_code internal_error_code ); + +.. rubric:: PARAMETERS: + +``internal_error_code`` + This parameter is the internal error code. + +.. rubric:: RETURN VALUES: + +"?" + The ``internal_error_code`` parameter value was not an internal error code. + +Returns a descriptive text for the internal error code. The text for the +internal error code is the enumerator constant name. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +.. Generated from spec:/rtems/fatal/if/error-occurred + +.. raw:: latex + + \clearpage + +.. index:: rtems_fatal_error_occurred() + +.. _InterfaceRtemsFatalErrorOccurred: + +rtems_fatal_error_occurred() +---------------------------- + +Invokes the fatal error handler. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_fatal_error_occurred( uint32_t fatal_code ); + +.. rubric:: PARAMETERS: + +``fatal_code`` + This parameter is the fatal code. + +.. rubric:: DESCRIPTION: + +This directive processes fatal errors. The fatal source is set to +:c:macro:`INTERNAL_ERROR_RTEMS_API`. The fatal code is set to the value of the +``fatal_code`` parameter. + +.. rubric:: NOTES: + +This directive is deprecated and should not be used in new code. It is +recommended to not use this directive since error locations cannot be uniquely +identified. A recommended alternative directive is :ref:`InterfaceRtemsFatal`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not return to the caller. + +* The directive invokes the fatal error extensions in :term:`extension forward + order`. + +* The directive does not invoke handlers registered by :c:func:`atexit` or + :c:func:`on_exit`. + +* The directive may terminate the system. diff --git a/c-user/fatal-error/index.rst b/c-user/fatal-error/index.rst new file mode 100644 index 0000000..40eca3b --- /dev/null +++ b/c-user/fatal-error/index.rst @@ -0,0 +1,17 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2021 embedded brains GmbH & Co. KG + +.. index:: fatal errors + +.. _RTEMSAPIClassicFatal: + +Fatal Error Manager +******************* + +.. toctree:: + + introduction + background + operations + directives diff --git a/c-user/fatal-error/introduction.rst b/c-user/fatal-error/introduction.rst new file mode 100644 index 0000000..fc310f4 --- /dev/null +++ b/c-user/fatal-error/introduction.rst @@ -0,0 +1,57 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2015, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/rtems/fatal/if/group + +.. _FatalErrorManagerIntroduction: + +Introduction +============ + +.. The following list was generated from: +.. spec:/rtems/fatal/if/fatal +.. spec:/rtems/fatal/if/panic +.. spec:/rtems/fatal/if/shutdown-executive +.. spec:/rtems/fatal/if/exception-frame-print +.. spec:/rtems/fatal/if/source-text +.. spec:/rtems/fatal/if/internal-error-text +.. spec:/rtems/fatal/if/error-occurred + +The Fatal Error Manager processes all fatal or irrecoverable errors and other +sources of system termination (for example after :c:func:`exit`). Fatal errors +are identified by the fatal source and code pair. The directives provided by +the Fatal Error Manager are: + +* :ref:`InterfaceRtemsFatal` - Invokes the fatal error handler. + +* :ref:`InterfaceRtemsPanic` - Prints the message and invokes the fatal error + handler. + +* :ref:`InterfaceRtemsShutdownExecutive` - Invokes the fatal error handler. + +* :ref:`InterfaceRtemsExceptionFramePrint` - Prints the exception frame. + +* :ref:`InterfaceRtemsFatalSourceText` - Returns a descriptive text for the + fatal source. + +* :ref:`InterfaceRtemsInternalErrorText` - Returns a descriptive text for the + internal error code. + +* :ref:`InterfaceRtemsFatalErrorOccurred` - Invokes the fatal error handler. diff --git a/c-user/fatal-error/operations.rst b/c-user/fatal-error/operations.rst new file mode 100644 index 0000000..6d03a26 --- /dev/null +++ b/c-user/fatal-error/operations.rst @@ -0,0 +1,50 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Operations +========== + +.. index:: _Terminate + +.. _Terminate: + +Announcing a Fatal Error +------------------------ + +The :c:func:`_Terminate()` internal error handler is invoked when the +application or the executive itself determines that a fatal error has occurred +or a final system state is reached (for example after :c:func:`rtems_fatal()` +or :c:func:`exit()`). + +The first action of the internal error handler is to call the fatal extension of +the user extensions. For the initial extensions the following conditions are +required + +- a valid stack pointer and enough stack space, + +- a valid code memory, and + +- valid read-only data. + +For the initial extensions the read-write data (including .bss segment) is not +required on single processor configurations. In SMP configurations, however, +the read-write data must be initialized since this function must determine the +state of the other processors and request them to shut-down if necessary. + +Non-initial extensions require in addition valid read-write data. The board +support package (BSP) may install an initial extension that performs a system +reset. In this case the non-initial extensions will be not called. + +The fatal extensions are called with three parameters: + +- the fatal source, + +- a legacy parameter which is always set to :c:macro:`false`, and + +- an error code with a fatal source dependent content. + +Once all fatal extensions executed, the system state is set to +:c:macro:`SYSTEM_STATE_TERMINATED`. + +The final step is to call the CPU port specific :c:func:`_CPU_Fatal_halt()`. diff --git a/c-user/glossary.rst b/c-user/glossary.rst index dfbda11..2516e90 100644 --- a/c-user/glossary.rst +++ b/c-user/glossary.rst @@ -1,6 +1,8 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2017, 2019 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2022, 2023 Trinity College Dublin +.. Copyright (C) 2020 Richi Dubey (richidubey@gmail.com) +.. Copyright (C) 2015, 2023 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 1998 On-Line Applications Research Corporation (OAR) Glossary @@ -10,24 +12,35 @@ Glossary :sorted: ABI - An acronym for Application Binary Interface. + This term is an acronym for Application Binary Interface. active A term used to describe an object which has been created by an application. + AMP + This term is an acronym for Asymmetric Multiprocessing. + + APA + This term is an acronym for Arbitrary Processor Affinity. APA schedulers + allow a thread to have an arbitrary affinity to a processor set, rather than + a restricted mapping to only one processor of the set or the ability to run + on all processors of the set. + + It has two variants, :term:`Weak APA` and :term:`Strong APA`. + aperiodic task A task which must execute only at irregular intervals and has only a soft deadline. API - An acronym for Application Programming Interface. + This term is an acronym for Application Programming Interface. application In this document, software which makes use of RTEMS. ASR - An acronym for :term:`Asynchronous Signal Routine`. + This term is an acronym for :term:`Asynchronous Signal Routine`. assembler language The assembler language is a programming language which can be translated very @@ -50,6 +63,9 @@ Glossary A term used to describe a task that has been unblocked and may be scheduled to the CPU. + BCB + This term is an acronym for Barrier Control Block. + big endian A data representation scheme in which the bytes composing a numeric value are arranged such that the most significant byte is at the lowest @@ -77,7 +93,7 @@ Glossary To simultaneously send a message to a logical set of destinations. BSP - An acronym for :term:`Board Support Package`. + This term is an acronym for :term:`Board Support Package`. buffer A fixed length block of memory allocated from a partition. @@ -89,9 +105,21 @@ Glossary C++11 The standard ISO/IEC 14882:2011. + C++14 + The standard ISO/IEC 14882:2014. + + C++17 + The standard ISO/IEC 14882:2017. + + C++20 + The standard ISO/IEC 14882:2020. + C11 The standard ISO/IEC 9899:2011. + C17 + The standard ISO/IEC 9899:2018. + calling convention The processor and compiler dependent rules which define the mechanism used to invoke subroutines in a high-level language. These rules define @@ -99,7 +127,7 @@ Glossary set which must be preserved. CCB - An acronym for Change Control Board. + This term is an acronym for Change Control Board. Central Processing Unit This term is equivalent to the terms processor and microprocessor. @@ -109,6 +137,39 @@ Glossary of elements. It differs from an array in that it is not limited to a predefined size. + Clock Driver + The Clock Driver is a driver which provides the :term:`clock tick` and a + time counter. The time counter is used to drive the :term:`CLOCK_REALTIME` + and :term:`CLOCK_MONOTONIC`. The Clock Driver can be initialized by the + application with the :ref:`CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER` and + :ref:`CONFIGURE_MICROSECONDS_PER_TICK` application configuration options. + + clock tick + The clock tick is a coarse time measure provided by RTEMS. The + :term:`Clock Driver` emits clock ticks at rate specified by the + :ref:`CONFIGURE_MICROSECONDS_PER_TICK` application configuration option. In + contrast to :term:`CLOCK_REALTIME` and :term:`CLOCK_MONOTONIC`, the clock + tick rate is not affected by incremental adjustments. + + CLOCK_MONOTONIC + The CLOCK_MONOTONIC is a clock provided by RTEMS which measures the time + since an unspecified starting point. In contrast to :term:`CLOCK_REALTIME`, + this clock cannot be set. It may be affected by incremental adjustments for + example carried out by the :term:`NTP` or the use of a :term:`PPS` signal. + See also :term:`CLOCK_REALTIME`, :term:`clock tick`, and + :term:`Clock Driver`. + + CLOCK_REALTIME + The CLOCK_REALTIME is a clock provided by RTEMS which measures the real time + (also known as wall-clock time). It is defined by :term:`POSIX`. In + particular, every day is treated as if it contains exactly 86400 seconds and + leap seconds are ignored. This clock can be set by the application which may + result in time jumps. It may be affected by incremental adjustments for + example carried out by the :term:`NTP` or the use of a :term:`PPS` signal. + RTEMS can represent time points of this clock in nanoseconds ranging from + 1988-01-01T00:00:00.000000000Z to 2514-05-31T01:53:03.999999999Z. See also + :term:`CLOCK_MONOTONIC`, :term:`clock tick`, and :term:`Clock Driver`. + cluster We have clustered scheduling in case the set of processors of a system is partitioned into non-empty pairwise disjoint subsets. These subsets are @@ -140,14 +201,22 @@ Glossary of the executive should not be used directly by applications. CPU - An acronym for :term:`Central Processing Unit`. + This term is an acronym for :term:`Central Processing Unit`. critical section A section of code which must be executed indivisibly. CRT - An acronym for Cathode Ray Tube. Normally used in reference to the - man-machine interface. + This term is an acronym for Cathode Ray Tube. Normally used in reference to + the man-machine interface. + + current priority + The current priority of a :term:`task` is the :term:`task priority` with + respect to the :term:`home scheduler` of the task. It is an aggregation of + the :term:`real priority` and temporary priority adjustments due to locking + protocols, the rate-monotonic period objects on some schedulers such as EDF, + and the :term:`POSIX` sporadic server. The current priority is an + :term:`eligible priority`. deadline A fixed time limit by which a task must have completed a set of actions. @@ -181,17 +250,39 @@ Glossary The state entered by a task after it is created and before it has been started. + DPCB + This term is an acronym for Dual-Ported Memory Control Block. + dual-ported A term used to describe memory which can be accessed at two different addresses. + dynamic extension sets + The dynamic extension sets are a list of :term:`user extensions`. The list + is defined by the system services used by the application and directive calls + such as :ref:`InterfaceRtemsExtensionCreate`. See also + :term:`initial extension sets`. + EARS - An acronym for Easy Approach to Requirements Syntax. + This term is an acronym for Easy Approach to Requirements Syntax. + + EDF + This term is an acronym for Earliest Deadline First. ELF - An acronym for + This term is an acronym for `Executable and Linkable Format <https://en.wikipedia.org/wiki/Executable_and_Linkable_Format>`_. + eligible priority + An eligible priority of a :term:`task` is the :term:`task priority` with + respect to the corresponding :term:`eligible scheduler` of the task. An + eligible priority is either the :term:`current priority` or a + :term:`helping priority` of a task. + + eligible scheduler + An eligible scheduler of a :term:`task` is a :term:`scheduler` which can be + used by the task to allocate a processor for the task. + embedded An application that is delivered as a hidden part of a larger system. For example, the software in a fuel-injection control system is an @@ -210,6 +301,9 @@ Glossary error code This term has the same meaning as :term:`status code`. + ESCB + This term is an acronym for Extension Set Control Block. + events A method for task communication and synchronization. The directives provided by the event manager are used to service events. @@ -231,37 +325,98 @@ Glossary An object known by all nodes in a multiprocessor system. An object created with the GLOBAL attribute will be exported. + extension forward order + The :term:`user extensions` may be invoked in extension forward order. In + forward order, all user extensions of the :term:`initial extension sets` are + invoked before all user extensions of the :term:`dynamic extension sets`. + In the initial extension sets the order is defined by the table index. The + user extension with the lowest table index is invoked first. In the dynamic + extension sets the order is defined by the registration order. The first + registered user extension is invoked first. See also + :term:`extension reverse order`. + + extension reverse order + The :term:`user extensions` may be invoked in extension reverse order. In + reverse order, all user extensions of the :term:`dynamic extension sets` are + invoked before all user extensions of the :term:`initial extension sets`. + In the dynamic extension sets the order is defined by the registration order. + The last registered user extension is invoked first. In the initial + extension sets the order is defined by the table index. The user extension + with the highest table index is invoked first. See also + :term:`extension forward order`. + external address The address used to access dual-ported memory by all the nodes in a system which do not own the memory. FIFO - An acronym for :term:`First In First Out`. + This term is an acronym for :term:`First In First Out`. First In First Out - A discipline for manipulating entries in a data structure. + A discipline for manipulating entries in a data structure. See also + :term:`Last In First Out`. floating point coprocessor A component used in computer systems to enhance performance in mathematically intensive situations. It is typically viewed as a logical extension of the primary processor. + formal model + A model of a computing component (hardware or software) that has a + mathematically based :term:`semantics`. + freed A resource that has been released by the application to RTEMS. + Futex + This term is an abbreviation for + `Fast User-Space Locking <https://man7.org/linux/man-pages/man2/futex.2.html>`_. + The futex support in RTEMS is provided for the barriers of the + :term:`OpenMP` library provided by :term:`GCC`. It could be used to + implement high performance :term:`SMP` synchronization primitives which + offer random-fairness. + GCC - An acronym for `GNU Compiler Collection <https://gcc.gnu.org/>`_. + This term is an acronym for `GNU Compiler Collection <https://gcc.gnu.org/>`_. global An object that has been created with the GLOBAL attribute and exported to all nodes in a multiprocessor system. + global construction + In the global construction, the C++ global constructors and constructor + functions are invoked. See :ref:`GlobalConstruction`. + GNAT *GNAT* is the :term:`GNU` compiler for Ada, integrated into the :term:`GCC`. GNU - An acronym for `GNU's Not Unix <https://www.gnu.org/>`_. + This term is an acronym for `GNU's Not Unix <https://www.gnu.org/>`_. + + GPL + This term is an acronym for + `GNU General Public License <https://www.gnu.org/licenses>`__. + + GPLv2 + This term is an acronym for + `GNU General Public License Version 2 <https://www.gnu.org/licenses/old-licenses/gpl-2.0.html>`__. + + GPLv3 + This term is an acronym for + `GNU General Public License Version 3 <https://www.gnu.org/licenses/gpl-3.0.html>`__. + + GR712RC + The + `GR712RC <https://www.gaisler.com/index.php/products/components/gr712rc>`_ + is a :term:`system-on-chip` containing two processors of the :term:`SPARC` + :term:`target architecture`. + + GR740 + The + `GR740 <https://www.gaisler.com/index.php/products/components/gr740>`_ + is a :term:`system-on-chip` containing four processors of the :term:`SPARC` + :term:`target architecture`. handler The equivalent of a manager, except that it is internal to RTEMS and @@ -285,14 +440,34 @@ Glossary dispatch is marked as necessary, then the next thread dispatch will make the heir task the executing task. + helping priority + A helping priority of a :term:`task` is the :term:`task priority` with + respect to the corresponding :term:`helping scheduler` of the task. A + helping priority is an :term:`eligible priority`. + + helping scheduler + A helping scheduler of a :term:`task` is a :term:`scheduler` which is a + :term:`eligible scheduler` and which is not the :term:`home scheduler` of + the task. + heterogeneous A multiprocessor computer system composed of dissimilar processors. + higher priority + A :term:`task` ``H`` has a higher :term:`priority` than a task ``L``, if + task ``H`` is more important than task ``L``. + + home scheduler + The home scheduler of a :term:`task` is a :term:`scheduler` which is an + :term:`eligible scheduler` and which is assigned to the task during its + initialization or explicitly via a directive call such as + :ref:`InterfaceRtemsTaskSetScheduler`. + homogeneous A multiprocessor computer system composed of a single type of processor. I/O - An acronym for Input/Output. + This term is an acronym for Input/Output. ID An RTEMS assigned identification tag used to access an active object. @@ -301,6 +476,17 @@ Glossary A special low priority task which assumes control of the CPU when no other task is able to execute. + ineligible scheduler + An ineligible scheduler of a :term:`task` is a :term:`scheduler` which is + not an :term:`eligible scheduler`. + + initial extension sets + The initial extension sets are a table of :term:`user extensions`. The table + is defined by the application configuration for example through the + :ref:`CONFIGURE_INITIAL_EXTENSIONS` application configuration option. The + initial extension sets cannot be altered during runtime through directive + calls. See also :term:`dynamic extension sets`. + interface A specification of the methodology used to connect multiple independent subsystems. @@ -330,14 +516,25 @@ Glossary An ISR is invoked by the CPU to process a pending interrupt. ISR - An acronym for :term:`Interrupt Service Routine`. + This term is an acronym for :term:`Interrupt Service Routine`. ISVV - An acronym for Independent Software Verification and Validation. + This term is an acronym for Independent Software Verification and Validation. kernel In this document, this term is used as a synonym for executive. + Last In First Out + A discipline for manipulating entries in a data structure. See also + :term:`First In First Out`. + + LIFO + This term is an acronym for :term:`Last In First Out`. + + Linear Temporal Logic + This is a logic that states properties about (possibly infinite) sequences of + states. + list A data structure which allows for dynamic addition and removal of entries. It is not statically limited to a particular size. @@ -347,6 +544,12 @@ Glossary are arranged such that the least significant byte is at the lowest address. + LLVM + This term is an acronym for + `Low Level Virtual Machine <https://www.llvm.org>`__. + The LLVM Project is a collection of modular and reusable compiler and + toolchain technologies. + local An object which was created with the LOCAL attribute and is accessible only on the node it was created and resides upon. In a single processor @@ -364,6 +567,13 @@ Glossary A multiprocessor configuration where shared memory is not used for communication. + lower priority + A :term:`task` ``L`` has a lower :term:`priority` than a task ``H``, if + task ``L`` is less important than task ``H``. + + LTL + This term is an acronym for :term:`Linear Temporal Logic`. + major number The index of a device driver in the Device Driver Table. @@ -372,7 +582,7 @@ Glossary over resources. MCS - An acronym for Mellor-Crummey Scott. + This term is an acronym for Mellor-Crummey Scott. memory pool Used interchangeably with heap. @@ -402,7 +612,11 @@ Glossary disable level used by the task. MPCI - An acronym for :term:`Multiprocessor Communications Interface Layer`. + This term is an acronym for + :term:`Multiprocessor Communications Interface Layer`. + + MrsP + This term is an acronym for Multiprocessor Resource-Sharing Protocol. multiprocessing The simultaneous execution of two or more processes by a multiple @@ -439,14 +653,21 @@ Glossary non-existent The state occupied by an uncreated or deleted task. + NTP + This term is an acronym for + `Network Time Protocol <https://en.wikipedia.org/wiki/Network_Time_Protocol>`_. + NUMA - An acronym for Non-Uniform Memory Access. + This term is an acronym for Non-Uniform Memory Access. numeric coprocessor A component used in computer systems to enhance performance in mathematically intensive situations. It is typically viewed as a logical extension of the primary processor. + OBC + This term is an acronym for On-Board Computer. + object In this document, this term is used to refer collectively to tasks, timers, message queues, partitions, regions, semaphores, ports, and rate @@ -457,6 +678,16 @@ Glossary variety of entities. Object-oriented systems shield the application from implementation details. + OMIP + This term is an acronym for O(m) Independence-Preserving Protocol. OMIP is a + generalization of the :term:`priority inheritance` locking protocol to + clustered scheduling. The ``m`` denotes the number of processors in the + system. + + OpenMP + This term is an acronym for + `Open Multi-Processing <https://www.openmp.org/>`_. + operating system The software which controls all the computer's resources and provides the base upon which application programs can be written. @@ -482,6 +713,9 @@ Glossary A data structure associated with each partition used by RTEMS to manage that partition. + PCB + This term is an acronym for Period Control Block. + pending A term used to describe a task blocked waiting for an event, message, semaphore, or signal. @@ -505,23 +739,46 @@ Glossary A term used to describe the ease with which software can be rehosted on another computer. + POSIX + This term is an acronym for + `Portable Operating System Interface <https://en.wikipedia.org/wiki/POSIX>`_. + posting The act of sending an event, message, semaphore, or signal to a task. + PPS + This term is an acronym for + `Pulse-Per-Second <https://en.wikipedia.org/wiki/Pulse-per-second_signal>`_. + preempt The act of forcing a task to relinquish the processor and dispatching to another task. priority - A mechanism used to represent the relative importance of an element in a - set of items. RTEMS uses priority to determine which task should - execute. + The priority is a mechanism used to represent the relative importance of an + element in a set of items. + + For example, :term:`RTEMS` uses :term:`task priorities <task priority>` to determine which + :term:`task` should execute on a processor. In RTEMS, priorities are + represented by non-negative integers. + + For the Classic :term:`API`, if a numerical priority value ``A`` is greater + than a numerical priority value ``B``, then ``A`` expresses a + :term:`lower priority` than ``B``. If a numerical priority value ``C`` is + less than a numerical priority value ``D``, then ``C`` expresses a + :term:`higher priority` than ``D``. + + For the :term:`POSIX` API, if a numerical priority value ``R`` is less than + a numerical priority value ``S``, then ``R`` expresses a lower priority than + ``S``. If a numerical priority value ``T`` is greater than a numerical + priority value ``U``, then ``T`` expresses a higher priority than ``U``. priority boosting A simple approach to extend the priority inheritance protocol for clustered scheduling is priority boosting. In case a mutex is owned by a task of another cluster, then the priority of the owner task is raised to - an artificially high priority, the pseudo-interrupt priority. + an artificially high priority. This approach is not used in RTEMS, see also + :term:`OMIP`. priority inheritance An algorithm that calls for the lower priority task holding a resource to @@ -547,13 +804,13 @@ Glossary proxy. PTCB - An acronym for :term:`Partition Control Block`. + This term is an acronym for :term:`Partition Control Block`. PXCB - An acronym for :term:`Proxy Control Block`. + This term is an acronym for :term:`Proxy Control Block`. QCB - An acronym for :term:`Message Queue Control Block`. + This term is an acronym for :term:`Message Queue Control Block`. quantum The application defined unit of time in which the processor is allocated. @@ -567,6 +824,14 @@ Glossary decided that other tasks are currently more important. A task that is ready to execute and has a processor assigned is called scheduled. + real priority + Each :term:`task` has exactly one real priority. The real priority is + always with respect to the :term:`home scheduler` of a task. It is defined + during task initialization. It may be changed by directives such as + :ref:`InterfaceRtemsTaskSetPriority` and + :ref:`InterfaceRtemsTaskSetScheduler`. The real priority is the foundation + of the :term:`current priority`. + real-time A term used to describe systems which are characterized by requiring deterministic response times to external stimuli. The external stimuli @@ -577,6 +842,10 @@ Glossary A term used to describe routines which do not modify themselves or global variables. + refinement + A *refinement* is a relationship between a specification and its + implementation as code. + region An RTEMS object which is used to allocate and deallocate variable size blocks of memory from a dynamically specified area of memory. @@ -589,6 +858,9 @@ Glossary Registers are locations physically located within a component, typically used for device control or general purpose storage. + reification + Another term used to denote :term:`refinement`. + remote Any object that does not reside on the local node. @@ -597,7 +869,7 @@ Glossary the calling task. ReqIF - An acronym for + This term is an acronym for `Requirements Interchange Format <https://www.omg.org/spec/ReqIF/About-ReqIF/>`_. resource @@ -616,7 +888,7 @@ Glossary :term:`status code`. RNCB - An acronym for :term:`Region Control Block`. + This term is an acronym for :term:`Region Control Block`. round-robin A task scheduling discipline in which tasks of equal priority are @@ -626,12 +898,22 @@ Glossary A standard for serial communications. RTEMS - An acronym for Real-Time Executive for Multiprocessor Systems. + This term is an acronym for Real-Time Executive for Multiprocessor Systems. + + RTEMS epoch + The RTEMS epoch is a point in time. It is 1988-01-01T00:00:00Z in + `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_ time format. running The state of a rate monotonic timer while it is being used to delineate a period. The timer exits this state by either expiring or being canceled. + scenario + In the context of formal verification, in a setting that involves many + concurrent tasks that interleave in arbitrary ways, a scenario describes a + single specific possible interleaving. One interpretation of the behaviour + of a concurrent system is the set of all its scenarios. + schedulable A set of tasks which can be guaranteed to meet their deadlines based upon a specific scheduling algorithm. @@ -653,6 +935,11 @@ Glossary priority number and assign the tasks with the lowest priority number to one processor of the set of processors owned by a scheduler instance. + A scheduler is either an :term:`eligible scheduler` or a + :term:`ineligible scheduler` for a task. An :term:`eligible scheduler` is + either the :term:`home scheduler` or a :term:`helping scheduler` for a + task. + scheduler instance A scheduler instance is a scheduling algorithm with a corresponding context to store its internal state. Each processor in the system is @@ -663,6 +950,11 @@ Glossary segments Variable sized memory blocks allocated from a region. + semantics + This term refers to the meaning of text or utterances in some language. In a + software engineering context these will be programming, modelling or + specification languages. + semaphore An RTEMS object which is used to synchronize tasks and provide mutually exclusive access to resources. @@ -683,11 +975,15 @@ Glossary A thirty-two bit entity which is used to represent a task's collection of pending signals and the signals sent to a task. + SIS + This term is an acronym for Simple Instruction Simulator. The SIS is a + :term:`SPARC` V7/V8 and RISC-V RV32IMACFD :term:`target architecture` simulator. + SMCB - An acronym for :term:`Semaphore Control Block`. + This term is an acronym for :term:`Semaphore Control Block`. SMP - An acronym for Symmetric Multiprocessing. + This term is an acronym for Symmetric Multiprocessing. SMP barriers The SMP barriers ensure that a defined set of independent threads of @@ -760,6 +1056,11 @@ Glossary software as it is originally written (i.e., typed into a computer) by a human in plain text (i.e., human readable alphanumeric characters)." + SPARC + This term is an acronym for + `Scalable Processor ARChitecture <https://en.wikipedia.org/wiki/SPARC>`_. + See also :term:`target architecture`. + sporadic task A task which executes at irregular intervals and must comply with a hard deadline. A minimum period of time between successive iterations of the @@ -776,6 +1077,17 @@ Glossary :term:`return value` to indicate a successful operation or error conditions. + Strong APA + Strong APA is a specialization of :term:`APA`. Schedulers which implement + strong APA recursively searches for a processor in the :term:`thread`'s + affinity set, whenever a thread becomes ready for execution, followed by the + processors in the affinity set of threads that are assigned the processor + present in the ready thread's affinity set. This is done to find a thread to + processor mapping that does not violate the priority ordering and to provide + a thread to processor mapping with a higher total priority of the threads + allocated a processor. Similar analysis is done when a thread blocks. See + also :cite:`Cerqueira:2014:LPA`. + suspend A term used to describe a task that is not competing for the CPU because it has had a ``rtems_task_suspend`` directive. @@ -786,11 +1098,25 @@ Glossary system call In this document, this is used as an alternate term for directive. + system-on-chip + This project uses the `system on a chip definition of Wikipedia + <https://en.wikipedia.org/wiki/System_on_a_chip>`_: "A system on a chip or + system-on-chip is an integrated circuit that integrates most or all + components of a computer or other electronic system." + + Systems on a chip are :term:`target` systems for applications using + :term:`RTEMS`. + target The system on which the application will ultimately execute. + target architecture + The target architecture is the instruction set architecture (ISA) of the + :term:`target`. Some RTEMS features depend on the target architecture. For + the details consult the *RTEMS CPU Architecture Supplement*. + TAS - An acronym for Test-And-Set. + This term is an acronym for Test-And-Set. task This project uses the @@ -811,10 +1137,32 @@ Glossary A data structure associated with each task used by RTEMS to manage that task. + task entry + The task entry is invoked to execute the task's job. Before the task entry + is invoked, the thread begin :term:`user extensions` run in the context of + the task. After the return of the task entry, the thread exitted user + extensions run in the context of the task. The first user initialization + task performs the :term:`global construction` after running the thread begin + extensions and before the task entry is invoked. See also + :ref:`InterfaceRtemsTaskStart`. + task migration Task migration happens in case a task stops execution on one processor and resumes execution on another processor. + task priority + A task :term:`priority` of a :term:`task` determines its importance + relative to other tasks. + + The scheduler use task priorities to determine which :term:`ready task` gets + a processor allocated, see :term:`scheduled task`. The + :term:`eligible priorities <eligible priority>` of a task define the position of the task in a + :term:`wait queue` which uses the priority discipline. Each task has at + least the :term:`real priority`. + + Task priorities are used in :term:`wait queues <wait queue>` which use the priority + discipline to determine the dequeueing order of tasks. + task processor affinity The set of processors on which a task is allowed to execute. @@ -823,7 +1171,7 @@ Glossary processor from one task and given to another. TCB - An acronym for :term:`Task Control Block`. + This term is an acronym for :term:`Task Control Block`. thread This term has the same meaning as :term:`task`. @@ -862,12 +1210,12 @@ Glossary task. TLS - An acronym for Thread-Local Storage :cite:`Drepper:2013:TLS`. TLS is - available in :term:`C11` and :term:`C++11`. The support for TLS depends - on the CPU port :cite:`RTEMS:CPU`. + This term is an acronym for Thread-Local Storage :cite:`Drepper:2013:TLS`. + TLS is available in :term:`C11` and :term:`C++11`. The support for TLS + depends on the CPU port :cite:`RTEMS:CPU`. TMCB - An acronym for :term:`Timer Control Block`. + This term is an acronym for :term:`Timer Control Block`. transient overload A temporary rise in system activity which may cause deadlines to be @@ -875,14 +1223,21 @@ Glossary deadlines will be met under transient overload. TTAS - An acronym for Test and Test-And-Set. + This term is an acronym for Test and Test-And-Set. + + Unix epoch + The Unix epoch is a point in time. It is 1970-01-01T00:00:00Z in + `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_ time format. User Extension Table A table which contains the entry points for each user extensions. user extensions - Software routines provided by the application to enhance the - functionality of RTEMS. + User extensions are software routines provided by the application to enhance + the functionality of RTEMS. An active user extension is either in the + :term:`initial extension sets` or the :term:`dynamic extension sets`. User + extensions are invoked in :term:`extension forward order` or + :term:`extension reverse order`. User Initialization Tasks Table A table which contains the information needed to create and start each of @@ -904,8 +1259,16 @@ Glossary Message queues, regions, and semaphores have a wait queue associated with them. + Weak APA + Weak APA is a specialization of :term:`APA`. This refers to Linux's push + and pull implementation of APA model. When a :term:`thread` becomes ready + for execution, it is allocated a processor if there is an idle processor, or + a processor executing a lower priority thread in its affinity set. Unlike + :term:`Strong APA`, no thread is migrated from its processor to find a thread + to processor mapping. See also :cite:`Cerqueira:2014:LPA`. + YAML - An acronym for `YAML Ain't Markup Language <https://yaml.org/>`_. + This term is an acronym for `YAML Ain't Markup Language <https://yaml.org/>`_. yield When a task voluntarily releases control of the processor. diff --git a/c-user/index.rst b/c-user/index.rst index e958481..b4ad322 100644 --- a/c-user/index.rst +++ b/c-user/index.rst @@ -10,7 +10,7 @@ RTEMS Classic API Guide (|version|). | |copy| 2017 Chris Johns | |copy| 2017 Kuan-Hsun Chen - | |copy| 2015, 2020 embedded brains GmbH + | |copy| 2015, 2020 embedded brains GmbH & Co. KG | |copy| 2015, 2020 Sebastian Huber | |copy| 2011 Petr Benes | |copy| 2010 Gedare Bloom @@ -28,33 +28,36 @@ RTEMS Classic API Guide (|version|). overview key_concepts rtems_data_types - scheduling_concepts - initialization - task_manager - interrupt_manager - clock_manager - timer_manager - rate_monotonic_manager - semaphore_manager - barrier_manager - message_manager - event_manager - signal_manager - partition_manager - region_manager - dual_ports_memory_manager - io_manager - fatal_error + scheduling-concepts/index + initialization/index + task/index + interrupt/index + clock/index + timer/index + rate-monotonic/index + semaphore/index + barrier/index + message/index + event/index + signal/index + partition/index + region/index + dual-ported-memory/index + io/index + kernel-character-io/index + cache/index + fatal-error/index board_support_packages - user_extensions + user-extensions/index config/index self_contained_objects - multiprocessing + regulator/index + multiprocessing/index symmetric_multiprocessing_services pci_library stack_bounds_checker cpu_usage_statistics - object_services + object-services/index chains red_black_trees timespec_helpers diff --git a/c-user/initialization/background.rst b/c-user/initialization/background.rst new file mode 100644 index 0000000..36d8ebd --- /dev/null +++ b/c-user/initialization/background.rst @@ -0,0 +1,48 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Background +========== + +.. index:: initialization tasks + +Initialization Tasks +-------------------- + +Initialization task(s) are the mechanism by which RTEMS transfers initial +control to the user's application. Initialization tasks differ from other +application tasks in that they are defined in the User Initialization Tasks +Table and automatically created and started by RTEMS as part of its +initialization sequence. Since the initialization tasks are scheduled using +the same algorithm as all other RTEMS tasks, they must be configured at a +priority and mode which will ensure that they will complete execution before +other application tasks execute. Although there is no upper limit on the +number of initialization tasks, an application is required to define at least +one. + +A typical initialization task will create and start the static set of +application tasks. It may also create any other objects used by the +application. Initialization tasks which only perform initialization should +delete themselves upon completion to free resources for other tasks. +Initialization tasks may transform themselves into a "normal" application task. +This transformation typically involves changing priority and execution mode. +RTEMS does not automatically delete the initialization tasks. + +The Idle Task +------------- + +The Idle Task is the lowest priority task in a system and executes only when no +other task is ready to execute. The default implementation of this task +consists of an infinite loop. RTEMS allows the Idle Task body to be replaced by +a CPU specific implementation, a BSP specific implementation or an application +specific implementation. + +The Idle Task is preemptible and *WILL* be preempted when any other task is +made ready to execute. This characteristic is critical to the overall behavior +of any application. + +Initialization Manager Failure +------------------------------ + +System initialization errors are fatal. See :ref:`internal_errors`. diff --git a/c-user/initialization/directives.rst b/c-user/initialization/directives.rst new file mode 100644 index 0000000..bb3fa95 --- /dev/null +++ b/c-user/initialization/directives.rst @@ -0,0 +1,69 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2015, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. _InitializationManagerDirectives: + +Directives +========== + +This section details the directives of the Initialization Manager. A subsection +is dedicated to each of this manager's directives and lists the calling +sequence, parameters, description, return values, and notes of the directive. + +.. Generated from spec:/rtems/init/if/initialize-executive + +.. raw:: latex + + \clearpage + +.. index:: rtems_initialize_executive() +.. index:: initialize RTEMS +.. index:: start multitasking + +.. _InterfaceRtemsInitializeExecutive: + +rtems_initialize_executive() +---------------------------- + +Initializes the system and starts multitasking. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_initialize_executive( void ); + +.. rubric:: DESCRIPTION: + +Iterates through the system initialization linker set and invokes the +registered handlers. The final step is to start multitasking. + +.. rubric:: NOTES: + +Errors in the initialization sequence are usually fatal and lead to a system +termination. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive should be called by :c:func:`boot_card` only. + +* The directive will not return to the caller. diff --git a/c-user/initialization/index.rst b/c-user/initialization/index.rst new file mode 100644 index 0000000..cbca400 --- /dev/null +++ b/c-user/initialization/index.rst @@ -0,0 +1,15 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2021 embedded brains GmbH & Co. KG + +.. _RTEMSAPIClassicInit: + +Initialization Manager +********************** + +.. toctree:: + + introduction + background + operations + directives diff --git a/c-user/initialization/introduction.rst b/c-user/initialization/introduction.rst new file mode 100644 index 0000000..15722f6 --- /dev/null +++ b/c-user/initialization/introduction.rst @@ -0,0 +1,39 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2015, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/rtems/init/if/group + +.. _InitializationManagerIntroduction: + +Introduction +============ + +.. The following list was generated from: +.. spec:/rtems/init/if/initialize-executive + +The Initialization Manager is responsible for initializing the system. + +The system initialization includes the initialization of the Board Support +Package, RTEMS, device drivers, the root filesystem, and the application. The +:ref:`RTEMSAPIClassicFatal` is responsible for the system shutdown. The +directives provided by the Initialization Manager are: + +* :ref:`InterfaceRtemsInitializeExecutive` - Initializes the system and starts + multitasking. diff --git a/c-user/initialization.rst b/c-user/initialization/operations.rst index fa7afb5..e7d310c 100644 --- a/c-user/initialization.rst +++ b/c-user/initialization/operations.rst @@ -2,66 +2,6 @@ .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) -Initialization Manager -********************** - -Introduction -============ - -The Initialization Manager is responsible for initializing the Board Support -Package, RTEMS, device drivers, the root filesystem and the application. The -:ref:`Fatal Error Manager <fatal_error_manager>` is responsible for the system -shutdown. - -The Initialization Manager provides only one directive: - -- rtems_initialize_executive_ - Initialize RTEMS - -Background -========== - -.. index:: initialization tasks - -Initialization Tasks --------------------- - -Initialization task(s) are the mechanism by which RTEMS transfers initial -control to the user's application. Initialization tasks differ from other -application tasks in that they are defined in the User Initialization Tasks -Table and automatically created and started by RTEMS as part of its -initialization sequence. Since the initialization tasks are scheduled using -the same algorithm as all other RTEMS tasks, they must be configured at a -priority and mode which will ensure that they will complete execution before -other application tasks execute. Although there is no upper limit on the -number of initialization tasks, an application is required to define at least -one. - -A typical initialization task will create and start the static set of -application tasks. It may also create any other objects used by the -application. Initialization tasks which only perform initialization should -delete themselves upon completion to free resources for other tasks. -Initialization tasks may transform themselves into a "normal" application task. -This transformation typically involves changing priority and execution mode. -RTEMS does not automatically delete the initialization tasks. - -The Idle Task -------------- - -The Idle Task is the lowest priority task in a system and executes only when no -other task is ready to execute. The default implementation of this task -consists of an infinite loop. RTEMS allows the Idle Task body to be replaced by -a CPU specific implementation, a BSP specific implementation or an application -specific implementation. - -The Idle Task is preemptible and *WILL* be preempted when any other task is -made ready to execute. This characteristic is critical to the overall behavior -of any application. - -Initialization Manager Failure ------------------------------- - -System initialization errors are fatal. See :ref:`internal_errors`. - Operations ========== @@ -345,19 +285,24 @@ Many of RTEMS actions during initialization are based upon the contents of the Configuration Table. For more information regarding the format and contents of this table, please refer to the chapter :ref:`Configuring a System`. +.. index:: global construction + +.. _GlobalConstruction: + Global Construction ------------------- -The global construction is carried out by the first Classic API initialization -task (first is defined by index zero in the Classic API initialization task -configuration table). If no Classic API initialization task exists, then it is -carried out by the first POSIX API initialization thread. If no initialization -task or thread exists, then no global construction is performed, see for -example :ref:`Specify Idle Task Performs Application Initialization`. The -Classic API task or POSIX API thread which carries out global construction is -called the main thread. - -Global construction runs before the entry function of the main thread. The +The :term:`global construction` is carried out by the Classic API +initialization task. If no Classic API initialization task exists, then it is +carried out by the POSIX API initialization thread. If no initialization task +or thread exists, then no global construction is performed. The Classic API +task or POSIX API thread which carries out global construction is called the +main thread. For configuration options related to initialization tasks, see +:ref:`CONFIGURE_RTEMS_INIT_TASKS_TABLE`, +:ref:`CONFIGURE_POSIX_INIT_THREAD_TABLE`, and +:ref:`CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION`. + +Global construction runs before the :term:`task entry` of the main thread. The configuration of the main thread must take the global construction into account. In particular, the main thread stack size, priority, attributes and initial modes must be set accordingly. Thread-local objects and POSIX key @@ -418,41 +363,3 @@ should output: c() b() A:A() - -Directives -========== - -This section details the Initialization Manager's directives. A subsection is -dedicated to each of this manager's directives and describes the calling -sequence, related constants, usage, and status codes. - -.. raw:: latex - - \clearpage - -.. index:: initialize RTEMS -.. index:: start multitasking -.. index:: rtems_initialize_executive - -.. _rtems_initialize_executive: - -INITIALIZE_EXECUTIVE - Initialize RTEMS ---------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - void rtems_initialize_executive(void); - -DIRECTIVE STATUS CODES: - NONE - This function will not return to the caller. - -DESCRIPTION: - Iterates through the system initialization linker set and invokes the - registered handlers. The final step is to start multitasking. - -NOTES: - This directive should be called by :c:func:`boot_card()` only. - - This directive *does not return* to the caller. Errors in the - initialization sequence are usually fatal and lead to a system termination. diff --git a/c-user/interrupt/background.rst b/c-user/interrupt/background.rst new file mode 100644 index 0000000..b626640 --- /dev/null +++ b/c-user/interrupt/background.rst @@ -0,0 +1,106 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Background +========== + +.. index:: interrupt processing + +Processing an Interrupt +----------------------- + +The interrupt manager allows the application to connect a function to a +hardware interrupt vector. When an interrupt occurs, the processor will +automatically vector to RTEMS. RTEMS saves and restores all registers which +are not preserved by the normal C calling convention for the target processor +and invokes the user's ISR. The user's ISR is responsible for processing the +interrupt, clearing the interrupt if necessary, and device specific +manipulation. + +.. index:: rtems_vector_number + +The ``rtems_interrupt_catch`` directive connects a procedure to an interrupt +vector. The vector number is managed using the ``rtems_vector_number`` data +type. + +The interrupt service routine is assumed to abide by these conventions and have +a prototype similar to the following: + +.. index:: rtems_isr + +.. code-block:: c + + rtems_isr user_isr( + rtems_vector_number vector + ); + +The vector number argument is provided by RTEMS to allow the application to +identify the interrupt source. This could be used to allow a single routine to +service interrupts from multiple instances of the same device. For example, a +single routine could service interrupts from multiple serial ports and use the +vector number to identify which port requires servicing. + +To minimize the masking of lower or equal priority level interrupts, the ISR +should perform the minimum actions required to service the interrupt. Other +non-essential actions should be handled by application tasks. Once the user's +ISR has completed, it returns control to the RTEMS interrupt manager which will +perform task dispatching and restore the registers saved before the ISR was +invoked. + +The RTEMS interrupt manager guarantees that proper task scheduling and +dispatching are performed at the conclusion of an ISR. A system call made by +the ISR may have readied a task of higher priority than the interrupted task. +Therefore, when the ISR completes, the postponed dispatch processing must be +performed. No dispatch processing is performed as part of directives which +have been invoked by an ISR. + +Applications must adhere to the following rule if proper task scheduling and +dispatching is to be performed: + +.. note:: + + The interrupt manager must be used for all ISRs which may be interrupted by + the highest priority ISR which invokes an RTEMS directive. + +Consider a processor which allows a numerically low interrupt level to +interrupt a numerically greater interrupt level. In this example, if an RTEMS +directive is used in a level 4 ISR, then all ISRs which execute at levels 0 +through 4 must use the interrupt manager. + +Interrupts are nested whenever an interrupt occurs during the execution of +another ISR. RTEMS supports efficient interrupt nesting by allowing the nested +ISRs to terminate without performing any dispatch processing. Only when the +outermost ISR terminates will the postponed dispatching occur. + +.. index:: interrupt levels + +RTEMS Interrupt Levels +---------------------- + +Many processors support multiple interrupt levels or priorities. The exact +number of interrupt levels is processor dependent. RTEMS internally supports +256 interrupt levels which are mapped to the processor's interrupt levels. For +specific information on the mapping between RTEMS and the target processor's +interrupt levels, refer to the Interrupt Processing chapter of the Applications +Supplement document for a specific target processor. + +.. index:: disabling interrupts + +Disabling of Interrupts by RTEMS +-------------------------------- + +During the execution of directive calls, critical sections of code may be +executed. When these sections are encountered, RTEMS disables all maskable +interrupts before the execution of the section and restores them to the +previous level upon completion of the section. RTEMS has been optimized to +ensure that interrupts are disabled for a minimum length of time. The maximum +length of time interrupts are disabled by RTEMS is processor dependent and is +detailed in the Timing Specification chapter of the Applications Supplement +document for a specific target processor. + +Non-maskable interrupts (NMI) cannot be disabled, and ISRs which execute at +this level MUST NEVER issue RTEMS system calls. If a directive is invoked, +unpredictable results may occur due to the inability of RTEMS to protect its +critical sections. However, ISRs that make no system calls may safely execute +as non-maskable interrupts. diff --git a/c-user/interrupt/directives.rst b/c-user/interrupt/directives.rst new file mode 100644 index 0000000..80eddfd --- /dev/null +++ b/c-user/interrupt/directives.rst @@ -0,0 +1,3646 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2008, 2022 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. _InterruptManagerDirectives: + +Directives +========== + +This section details the directives of the Interrupt Manager. A subsection is +dedicated to each of this manager's directives and lists the calling sequence, +parameters, description, return values, and notes of the directive. + +.. Generated from spec:/rtems/intr/if/catch + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_catch() +.. index:: establish an ISR +.. index:: install an ISR + +.. _InterfaceRtemsInterruptCatch: + +rtems_interrupt_catch() +----------------------- + +Establishes an interrupt service routine. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_catch( + rtems_isr_entry new_isr_handler, + rtems_vector_number vector, + rtems_isr_entry *old_isr_handler + ); + +.. rubric:: PARAMETERS: + +``new_isr_handler`` + This parameter is the new interrupt service routine. + +``vector`` + This parameter is the interrupt vector number. + +``old_isr_handler`` + This parameter is the pointer to an :ref:`InterfaceRtemsIsrEntry` object. + When the directive call is successful, the previous interrupt service + routine established for this interrupt vector will be stored in this + object. + +.. rubric:: DESCRIPTION: + +This directive establishes an interrupt service routine (ISR) for the interrupt +specified by the ``vector`` number. The ``new_isr_handler`` parameter +specifies the entry point of the ISR. The entry point of the previous ISR for +the specified vector is returned in ``old_isr_handler``. + +To release an interrupt vector, pass the old handler's address obtained when +the vector was first capture. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_NUMBER` + The interrupt vector number was illegal. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``new_isr_handler`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``old_isr_handler`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +* The directive is only available where the :term:`target architecture` support + enabled simple vectored interrupts. + +.. Generated from spec:/rtems/intr/if/disable + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_disable() +.. index:: disable interrupts + +.. _InterfaceRtemsInterruptDisable: + +rtems_interrupt_disable() +------------------------- + +Disables the maskable interrupts on the current processor. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_interrupt_disable( rtems_interrupt_level isr_cookie ); + +.. rubric:: PARAMETERS: + +``isr_cookie`` + This parameter is a variable of type :ref:`InterfaceRtemsInterruptLevel` + which will be used to save the previous interrupt level. + +.. rubric:: DESCRIPTION: + +This directive disables all maskable interrupts on the current processor and +returns the previous interrupt level in ``isr_cookie``. + +.. rubric:: NOTES: + +A later invocation of the :ref:`InterfaceRtemsInterruptEnable` directive should +be used to restore the previous interrupt level. + +This directive is implemented as a macro which sets the ``isr_cookie`` +parameter. + +.. code-block:: c + :linenos: + + #include <rtems.h> + + void local_critical_section( void ) + { + rtems_interrupt_level level; + + // Please note that the rtems_interrupt_disable() is a macro. The + // previous interrupt level (before the maskable interrupts are + // disabled) is returned here in the level macro parameter. This + // would be wrong: + // + // rtems_interrupt_disable( &level ); + rtems_interrupt_disable( level ); + + // Here is the critical section: maskable interrupts are disabled + + { + rtems_interrupt_level nested_level; + + rtems_interrupt_disable( nested_level ); + + // Here is a nested critical section + + rtems_interrupt_enable( nested_level ); + } + + // Maskable interrupts are still disabled + + rtems_interrupt_enable( level ); + } + +.. 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. + +* Where the system was built with SMP support enabled, the directive is not + available. Its use will result in compiler warnings and linker errors. The + :ref:`InterfaceRtemsInterruptLocalDisable` and + :ref:`InterfaceRtemsInterruptLocalEnable` directives are available in all + build configurations. + +.. Generated from spec:/rtems/intr/if/enable + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_enable() +.. index:: enable interrupts +.. index:: restore interrupt level + +.. _InterfaceRtemsInterruptEnable: + +rtems_interrupt_enable() +------------------------ + +Restores the previous interrupt level on the current processor. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_interrupt_enable( rtems_interrupt_level isr_cookie ); + +.. rubric:: PARAMETERS: + +``isr_cookie`` + This parameter is the previous interrupt level to restore. The value must + be obtained by a previous call to :ref:`InterfaceRtemsInterruptDisable` or + :ref:`InterfaceRtemsInterruptFlash`. + +.. rubric:: DESCRIPTION: + +This directive restores the interrupt level specified by ``isr_cookie`` on the +current processor. + +.. rubric:: NOTES: + +The ``isr_cookie`` parameter value must be obtained by a previous call to +:ref:`InterfaceRtemsInterruptDisable` or :ref:`InterfaceRtemsInterruptFlash`. +Using an otherwise obtained value is undefined behaviour. + +This directive is unsuitable to enable particular interrupt sources, for +example in an interrupt controller. + +.. 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. + +* While at least one maskable interrupt is pending, when the directive enables + maskable interrupts, the pending interrupts are immediately serviced. The + interrupt service routines may unblock higher priority tasks which may + preempt the calling task. + +* Where the system was built with SMP support enabled, the directive is not + available. Its use will result in compiler warnings and linker errors. The + :ref:`InterfaceRtemsInterruptLocalDisable` and + :ref:`InterfaceRtemsInterruptLocalEnable` directives are available in all + build configurations. + +.. Generated from spec:/rtems/intr/if/flash + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_flash() +.. index:: flash interrupts + +.. _InterfaceRtemsInterruptFlash: + +rtems_interrupt_flash() +----------------------- + +Flashes interrupts on the current processor. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_interrupt_flash( rtems_interrupt_level isr_cookie ); + +.. rubric:: PARAMETERS: + +``isr_cookie`` + This parameter is the previous interrupt level. + +.. rubric:: DESCRIPTION: + +This directive is functionally equivalent to a calling +:ref:`InterfaceRtemsInterruptEnable` immediately followed by a +:ref:`InterfaceRtemsInterruptDisable`. On some architectures it is possible to +provide an optimized implementation for this sequence. + +.. rubric:: NOTES: + +The ``isr_cookie`` parameter value must be obtained by a previous call to +:ref:`InterfaceRtemsInterruptDisable` or :ref:`InterfaceRtemsInterruptFlash`. +Using an otherwise obtained value is undefined behaviour. + +Historically, the interrupt flash directive was heavily used in the operating +system implementation. However, this is no longer the case. The interrupt +flash directive is provided for backward compatibility reasons. + +.. 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. + +* Where the system was built with SMP support enabled, the directive is not + available. Its use will result in compiler warnings and linker errors. The + :ref:`InterfaceRtemsInterruptLocalDisable` and + :ref:`InterfaceRtemsInterruptLocalEnable` directives are available in all + build configurations. + +.. Generated from spec:/rtems/intr/if/local-disable + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_local_disable() +.. index:: disable interrupts + +.. _InterfaceRtemsInterruptLocalDisable: + +rtems_interrupt_local_disable() +------------------------------- + +Disables the maskable interrupts on the current processor. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_interrupt_local_disable( rtems_interrupt_level isr_cookie ); + +.. rubric:: PARAMETERS: + +``isr_cookie`` + This parameter is a variable of type :ref:`InterfaceRtemsInterruptLevel` + which will be used to save the previous interrupt level. + +.. rubric:: DESCRIPTION: + +This directive disables all maskable interrupts on the current processor and +returns the previous interrupt level in ``isr_cookie``. + +.. rubric:: NOTES: + +A later invocation of the :ref:`InterfaceRtemsInterruptLocalEnable` directive +should be used to restore the previous interrupt level. + +This directive is implemented as a macro which sets the ``isr_cookie`` +parameter. + +Where the system was built with SMP support enabled, this will not ensure +system wide mutual exclusion. Use interrupt locks instead, see +:ref:`InterfaceRtemsInterruptLockAcquire`. Interrupt disabled critical +sections may be used to access processor-specific data structures or disable +thread dispatching. + +.. code-block:: c + :linenos: + + #include <rtems.h> + + void local_critical_section( void ) + { + rtems_interrupt_level level; + + // Please note that the rtems_interrupt_local_disable() is a macro. + // The previous interrupt level (before the maskable interrupts are + // disabled) is returned here in the level macro parameter. This would + // be wrong: + // + // rtems_interrupt_local_disable( &level ); + rtems_interrupt_local_disable( level ); + + // Here is the critical section: maskable interrupts are disabled + + { + rtems_interrupt_level nested_level; + + rtems_interrupt_local_disable( nested_level ); + + // Here is a nested critical section + + rtems_interrupt_local_enable( nested_level ); + } + + // Maskable interrupts are still disabled + + rtems_interrupt_local_enable( level ); + } + +.. 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/intr/if/local-enable + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_local_enable() +.. index:: enable interrupts +.. index:: restore interrupt level + +.. _InterfaceRtemsInterruptLocalEnable: + +rtems_interrupt_local_enable() +------------------------------ + +Restores the previous interrupt level on the current processor. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_interrupt_local_enable( rtems_interrupt_level isr_cookie ); + +.. rubric:: PARAMETERS: + +``isr_cookie`` + This parameter is the previous interrupt level to restore. The value must + be obtained by a previous call to + :ref:`InterfaceRtemsInterruptLocalDisable`. + +.. rubric:: DESCRIPTION: + +This directive restores the interrupt level specified by ``isr_cookie`` on the +current processor. + +.. rubric:: NOTES: + +The ``isr_cookie`` parameter value must be obtained by a previous call to +:ref:`InterfaceRtemsInterruptLocalDisable`. Using an otherwise obtained value +is undefined behaviour. + +This directive is unsuitable to enable particular interrupt sources, for +example in an interrupt controller. + +.. 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. + +* While at least one maskable interrupt is pending, when the directive enables + maskable interrupts, the pending interrupts are immediately serviced. The + interrupt service routines may unblock higher priority tasks which may + preempt the calling task. + +.. Generated from spec:/rtems/intr/if/is-in-progress + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_is_in_progress() +.. index:: is interrupt in progress + +.. _InterfaceRtemsInterruptIsInProgress: + +rtems_interrupt_is_in_progress() +-------------------------------- + +Checks if an ISR is in progress on the current processor. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + bool rtems_interrupt_is_in_progress( void ); + +.. rubric:: DESCRIPTION: + +This directive returns ``true``, if the current processor is currently +servicing an interrupt, and ``false`` otherwise. A return value of ``true`` +indicates that the caller is an interrupt service routine, **not** a task. The +directives available to an interrupt service routine are restricted. + +.. rubric:: RETURN VALUES: + +Returns true, if the current processor is currently servicing an interrupt, +otherwise false. + +.. 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/intr/if/lock-initialize + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_lock_initialize() + +.. _InterfaceRtemsInterruptLockInitialize: + +rtems_interrupt_lock_initialize() +--------------------------------- + +Initializes the ISR lock. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_interrupt_lock_initialize( + rtems_interrupt_lock *lock, + const char *name + ); + +.. rubric:: PARAMETERS: + +``lock`` + This parameter is the ISR lock to initialize. + +``name`` + This parameter is the ISR lock name. It shall be a string. The name is + only used where the system was built with profiling support enabled. + +.. rubric:: NOTES: + +ISR locks may also be statically defined by +:ref:`InterfaceRTEMSINTERRUPTLOCKDEFINE` or statically initialized by +:ref:`InterfaceRTEMSINTERRUPTLOCKINITIALIZER`. + +.. Generated from spec:/rtems/intr/if/lock-destroy + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_lock_destroy() + +.. _InterfaceRtemsInterruptLockDestroy: + +rtems_interrupt_lock_destroy() +------------------------------ + +Destroys the ISR lock. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_interrupt_lock_destroy( rtems_interrupt_lock *lock ); + +.. rubric:: PARAMETERS: + +``lock`` + This parameter is the ISR lock to destroy. + +.. rubric:: NOTES: + +The lock must have been dynamically initialized by +:ref:`InterfaceRtemsInterruptLockInitialize`, statically defined by +:ref:`InterfaceRTEMSINTERRUPTLOCKDEFINE`, or statically initialized by +:ref:`InterfaceRTEMSINTERRUPTLOCKINITIALIZER`. + +Concurrent lock use during the destruction or concurrent destruction leads to +unpredictable results. + +.. 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/intr/if/lock-acquire + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_lock_acquire() + +.. _InterfaceRtemsInterruptLockAcquire: + +rtems_interrupt_lock_acquire() +------------------------------ + +Acquires the ISR lock. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_interrupt_lock_acquire( + rtems_interrupt_lock *lock, + rtems_interrupt_lock_context *lock_context + ); + +.. rubric:: PARAMETERS: + +``lock`` + This parameter is the ISR lock to acquire. + +``lock_context`` + This parameter is the ISR lock context. This lock context shall be used to + release the lock by calling :ref:`InterfaceRtemsInterruptLockRelease`. + +.. rubric:: DESCRIPTION: + +This directive acquires the ISR lock specified by ``lock`` using the lock +context provided by ``lock_context``. Maskable interrupts will be disabled on +the current processor. + +.. rubric:: NOTES: + +A caller-specific lock context shall be provided for each acquire/release pair, +for example an automatic variable. + +Where the system was built with SMP support enabled, this directive acquires an +SMP lock. An attempt to recursively acquire the lock may result in an infinite +loop with maskable interrupts disabled. + +This directive establishes a non-preemptive critical section with system wide +mutual exclusion on the local node in all RTEMS build configurations. + +.. code-block:: c + :linenos: + + #include <rtems.h> + + void critical_section( rtems_interrupt_lock *lock ) + { + rtems_interrupt_lock_context lock_context; + + rtems_interrupt_lock_acquire( lock, &lock_context ); + + // Here is the critical section. Maskable interrupts are disabled. + // Where the system was built with SMP support enabled, this section + // is protected by an SMP lock. + + rtems_interrupt_lock_release( lock, &lock_context ); + } + +.. 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/intr/if/lock-release + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_lock_release() + +.. _InterfaceRtemsInterruptLockRelease: + +rtems_interrupt_lock_release() +------------------------------ + +Releases the ISR lock. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_interrupt_lock_release( rtems_interrupt_lock_context *lock ); + +.. rubric:: PARAMETERS: + +``lock`` + This parameter is the ISR lock to release. + +``lock_context`` + This parameter is the ISR lock context. This lock context shall have been + used to acquire the lock by calling + :ref:`InterfaceRtemsInterruptLockAcquire`. + +.. rubric:: DESCRIPTION: + +This directive releases the ISR lock specified by ``lock`` using the lock +context provided by ``lock_context``. The previous interrupt level will be +restored on the current processor. + +.. rubric:: NOTES: + +The lock context shall be the one used to acquire the lock, otherwise the +result is unpredictable. + +Where the system was built with SMP support enabled, this directive releases an +SMP lock. + +.. 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. + +* While at least one maskable interrupt is pending, when the directive enables + maskable interrupts, the pending interrupts are immediately serviced. The + interrupt service routines may unblock higher priority tasks which may + preempt the calling task. + +.. Generated from spec:/rtems/intr/if/lock-acquire-isr + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_lock_acquire_isr() + +.. _InterfaceRtemsInterruptLockAcquireIsr: + +rtems_interrupt_lock_acquire_isr() +---------------------------------- + +Acquires the ISR lock from within an ISR. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_interrupt_lock_acquire_isr( + rtems_interrupt_lock *lock, + rtems_interrupt_lock_context *lock_context + ); + +.. rubric:: PARAMETERS: + +``lock`` + This parameter is the ISR lock to acquire within an ISR. + +``lock_context`` + This parameter is the ISR lock context. This lock context shall be used to + release the lock by calling :ref:`InterfaceRtemsInterruptLockReleaseIsr`. + +.. rubric:: DESCRIPTION: + +This directive acquires the ISR lock specified by ``lock`` using the lock +context provided by ``lock_context``. The interrupt level will remain +unchanged. + +.. rubric:: NOTES: + +A caller-specific lock context shall be provided for each acquire/release pair, +for example an automatic variable. + +Where the system was built with SMP support enabled, this directive acquires an +SMP lock. An attempt to recursively acquire the lock may result in an infinite +loop. + +This directive is intended for device drivers and should be called from the +corresponding interrupt service routine. + +In case the corresponding interrupt service routine can be interrupted by +higher priority interrupts and these interrupts enter the critical section +protected by this lock, then the result is unpredictable. This directive may +be used under specific circumstances as an optimization. In doubt, use +:ref:`InterfaceRtemsInterruptLockAcquire` and +:ref:`InterfaceRtemsInterruptLockRelease`. + +.. 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/intr/if/lock-release-isr + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_lock_release_isr() + +.. _InterfaceRtemsInterruptLockReleaseIsr: + +rtems_interrupt_lock_release_isr() +---------------------------------- + +Releases the ISR lock from within an ISR. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_interrupt_lock_release_isr( + rtems_interrupt_lock *lock, + rtems_interrupt_lock_context *lock_context + ); + +.. rubric:: PARAMETERS: + +``lock`` + This parameter is the ISR lock to release within an ISR. + +``lock_context`` + This parameter is the ISR lock context. This lock context shall have been + used to acquire the lock by calling + :ref:`InterfaceRtemsInterruptLockAcquireIsr`. + +.. rubric:: DESCRIPTION: + +This directive releases the ISR lock specified by ``lock`` using the lock +context provided by ``lock_context``. The interrupt level will remain +unchanged. + +.. rubric:: NOTES: + +The lock context shall be the one used to acquire the lock, otherwise the +result is unpredictable. + +Where the system was built with SMP support enabled, this directive releases an +SMP lock. + +.. 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/intr/if/lock-isr-disable + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_lock_interrupt_disable() + +.. _InterfaceRtemsInterruptLockInterruptDisable: + +rtems_interrupt_lock_interrupt_disable() +---------------------------------------- + +Disables maskable interrupts on the current processor. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_interrupt_lock_interrupt_disable( + rtems_interrupt_lock_context *lock_context + ); + +.. rubric:: PARAMETERS: + +``lock_context`` + This parameter is the ISR lock context for an acquire and release pair. + +.. rubric:: DESCRIPTION: + +This directive disables maskable interrupts on the current processor and stores +the previous interrupt level in ``lock_context``. + +.. 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/intr/if/lock-declare + +.. raw:: latex + + \clearpage + +.. index:: RTEMS_INTERRUPT_LOCK_DECLARE() + +.. _InterfaceRTEMSINTERRUPTLOCKDECLARE: + +RTEMS_INTERRUPT_LOCK_DECLARE() +------------------------------ + +Declares an ISR lock object. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + RTEMS_INTERRUPT_LOCK_DECLARE( specifier, designator ); + +.. rubric:: PARAMETERS: + +``specifier`` + This parameter is the storage-class specifier for the ISR lock to declare, + for example ``extern`` or ``static``. + +``designator`` + This parameter is the ISR lock object designator. + +.. rubric:: NOTES: + +Do not add a ";" after this macro. + +.. Generated from spec:/rtems/intr/if/lock-define + +.. raw:: latex + + \clearpage + +.. index:: RTEMS_INTERRUPT_LOCK_DEFINE() + +.. _InterfaceRTEMSINTERRUPTLOCKDEFINE: + +RTEMS_INTERRUPT_LOCK_DEFINE() +----------------------------- + +Defines an ISR lock object. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + RTEMS_INTERRUPT_LOCK_DEFINE( specifier, designator, const char *name ); + +.. rubric:: PARAMETERS: + +``specifier`` + This parameter is the storage-class specifier for the ISR lock to declare, + for example ``extern`` or ``static``. + +``designator`` + This parameter is the ISR lock object designator. + +``name`` + This parameter is the ISR lock name. It shall be a string. The name is + only used where the system was built with profiling support enabled. + +.. rubric:: NOTES: + +Do not add a ";" after this macro. + +ISR locks may also be dynamically initialized by +:ref:`InterfaceRtemsInterruptLockInitialize` or statically by +:ref:`InterfaceRTEMSINTERRUPTLOCKINITIALIZER`. + +.. Generated from spec:/rtems/intr/if/lock-initializer + +.. raw:: latex + + \clearpage + +.. index:: RTEMS_INTERRUPT_LOCK_INITIALIZER() + +.. _InterfaceRTEMSINTERRUPTLOCKINITIALIZER: + +RTEMS_INTERRUPT_LOCK_INITIALIZER() +---------------------------------- + +Statically initializes an ISR lock object. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + RTEMS_INTERRUPT_LOCK_INITIALIZER( const char *name ); + +.. rubric:: PARAMETERS: + +``name`` + This parameter is the ISR lock name. It shall be a string. The name is + only used where the system was built with profiling support enabled. + +.. rubric:: NOTES: + +ISR locks may also be dynamically initialized by +:ref:`InterfaceRtemsInterruptLockInitialize` or statically defined by +:ref:`InterfaceRTEMSINTERRUPTLOCKDEFINE`. + +.. Generated from spec:/rtems/intr/if/lock-member + +.. raw:: latex + + \clearpage + +.. index:: RTEMS_INTERRUPT_LOCK_MEMBER() + +.. _InterfaceRTEMSINTERRUPTLOCKMEMBER: + +RTEMS_INTERRUPT_LOCK_MEMBER() +----------------------------- + +Defines an ISR lock member. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + RTEMS_INTERRUPT_LOCK_MEMBER( designator ); + +.. rubric:: PARAMETERS: + +``designator`` + This parameter is the ISR lock member designator. + +.. rubric:: NOTES: + +Do not add a ";" after this macro. + +.. Generated from spec:/rtems/intr/if/lock-reference + +.. raw:: latex + + \clearpage + +.. index:: RTEMS_INTERRUPT_LOCK_REFERENCE() + +.. _InterfaceRTEMSINTERRUPTLOCKREFERENCE: + +RTEMS_INTERRUPT_LOCK_REFERENCE() +-------------------------------- + +Defines an ISR lock object reference. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + RTEMS_INTERRUPT_LOCK_REFERENCE( designator, rtems_interrupt_lock *target ); + +.. rubric:: PARAMETERS: + +``designator`` + This parameter is the ISR lock reference designator. + +``target`` + This parameter is the target object to reference. + +.. rubric:: NOTES: + +Do not add a ";" after this macro. + +.. Generated from spec:/rtems/intr/if/entry-initializer + +.. raw:: latex + + \clearpage + +.. index:: RTEMS_INTERRUPT_ENTRY_INITIALIZER() + +.. _InterfaceRTEMSINTERRUPTENTRYINITIALIZER: + +RTEMS_INTERRUPT_ENTRY_INITIALIZER() +----------------------------------- + +Statically initializes an interrupt entry object. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + RTEMS_INTERRUPT_ENTRY_INITIALIZER( + rtems_interrupt_handler routine, + void *arg, + const char *info + ); + +.. rubric:: PARAMETERS: + +``routine`` + This parameter is the interrupt handler routine for the entry. + +``arg`` + This parameter is the interrupt handler argument for the entry. + +``info`` + This parameter is the descriptive information for the entry. + +.. rubric:: NOTES: + +Alternatively, :ref:`InterfaceRtemsInterruptEntryInitialize` may be used to +dynamically initialize an interrupt entry. + +.. Generated from spec:/rtems/intr/if/entry-initialize + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_entry_initialize() + +.. _InterfaceRtemsInterruptEntryInitialize: + +rtems_interrupt_entry_initialize() +---------------------------------- + +Initializes the interrupt entry. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_interrupt_entry_initialize( + rtems_interrupt_entry *entry, + rtems_interrupt_handler routine, + void *arg, + const char *info + ); + +.. rubric:: PARAMETERS: + +``entry`` + This parameter is the interrupt entry to initialize. + +``routine`` + This parameter is the interrupt handler routine for the entry. + +``arg`` + This parameter is the interrupt handler argument for the entry. + +``info`` + This parameter is the descriptive information for the entry. + +.. rubric:: NOTES: + +Alternatively, :ref:`InterfaceRTEMSINTERRUPTENTRYINITIALIZER` may be used to +statically initialize an interrupt entry. + +.. 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/intr/if/entry-install + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_entry_install() + +.. _InterfaceRtemsInterruptEntryInstall: + +rtems_interrupt_entry_install() +------------------------------- + +Installs the interrupt entry at the interrupt vector. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_entry_install( + rtems_vector_number vector, + rtems_option options, + rtems_interrupt_entry *entry + ); + +.. rubric:: PARAMETERS: + +``vector`` + This parameter is the interrupt vector number. + +``options`` + This parameter is the interrupt entry install option set. + +``entry`` + This parameter is the interrupt entry to install. + +.. rubric:: DESCRIPTION: + +One of the following mutually exclusive options + +* :c:macro:`RTEMS_INTERRUPT_UNIQUE`, and + +* :c:macro:`RTEMS_INTERRUPT_SHARED` + +shall be set in the ``options`` parameter. + +The handler routine of the entry specified by ``entry`` will be called with the +handler argument of the entry when dispatched. The order in which shared +interrupt handlers are dispatched for one vector is defined by the installation +order. The first installed handler is dispatched first. + +If the option :c:macro:`RTEMS_INTERRUPT_UNIQUE` is set, then it will be ensured +that the handler will be the only one for the interrupt vector. + +If the option :c:macro:`RTEMS_INTERRUPT_SHARED` is set, then multiple handlers +may be installed for the interrupt vector. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``entry`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INCORRECT_STATE` + The service was not initialized. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The handler routine of the entry was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt vector associated with the number specified by + ``vector``. + +:c:macro:`RTEMS_CALLED_FROM_ISR` + The directive was called from within interrupt context. + +:c:macro:`RTEMS_INVALID_NUMBER` + An option specified by ``options`` was not applicable. + +:c:macro:`RTEMS_RESOURCE_IN_USE` + The :c:macro:`RTEMS_INTERRUPT_UNIQUE` option was set in ``entry`` and the + interrupt vector was already occupied by a handler. + +:c:macro:`RTEMS_RESOURCE_IN_USE` + The :c:macro:`RTEMS_INTERRUPT_SHARED` option was set in ``entry`` and the + interrupt vector was already occupied by a unique handler. + +:c:macro:`RTEMS_TOO_MANY` + The handler routine of the entry specified by ``entry`` was already + installed for the interrupt vector specified by ``vector`` with an argument + equal to the handler argument of the entry. + +.. rubric:: NOTES: + +When the directive call was successful, the ownership of the interrupt entry +has been transferred from the caller to the interrupt service. An installed +interrupt entry may be removed from the interrupt service by calling +:ref:`InterfaceRtemsInterruptEntryRemove`. + +.. 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. + +* The interrupt entry shall have been initialized by + :ref:`InterfaceRtemsInterruptEntryInitialize` or + :ref:`InterfaceRTEMSINTERRUPTENTRYINITIALIZER`. + +.. Generated from spec:/rtems/intr/if/entry-remove + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_entry_remove() + +.. _InterfaceRtemsInterruptEntryRemove: + +rtems_interrupt_entry_remove() +------------------------------ + +Removes the interrupt entry from the interrupt vector. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_entry_remove( + rtems_vector_number vector, + rtems_interrupt_entry *entry + ); + +.. rubric:: PARAMETERS: + +``vector`` + This parameter is the interrupt vector number. + +``entry`` + This parameter is the interrupt entry to remove. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INCORRECT_STATE` + The service was not initialized. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``entry`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt vector associated with the number specified by + ``vector``. + +:c:macro:`RTEMS_CALLED_FROM_ISR` + The directive was called from within interrupt context. + +:c:macro:`RTEMS_UNSATISFIED` + The entry specified by ``entry`` was not installed at the interrupt vector + specified by ``vector``. + +.. rubric:: NOTES: + +When the directive call was successful, the ownership of the interrupt entry +has been transferred from the interrupt service to the caller. + +.. 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. + +* The interrupt entry shall have been installed by + :ref:`InterfaceRtemsInterruptEntryInstall`. + +.. Generated from spec:/rtems/intr/if/handler-install + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_handler_install() + +.. _InterfaceRtemsInterruptHandlerInstall: + +rtems_interrupt_handler_install() +--------------------------------- + +Installs the interrupt handler routine and argument at the interrupt vector. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_handler_install( + rtems_vector_number vector, + const char *info, + rtems_option options, + rtems_interrupt_handler routine, + void *arg + ); + +.. rubric:: PARAMETERS: + +``vector`` + This parameter is the interrupt vector number. + +``info`` + This parameter is the descriptive information of the interrupt handler to + install. + +``options`` + This parameter is the interrupt handler install option set. + +``routine`` + This parameter is the interrupt handler routine to install. + +``arg`` + This parameter is the interrupt handler argument to install. + +.. rubric:: DESCRIPTION: + +One of the following mutually exclusive options + +* :c:macro:`RTEMS_INTERRUPT_UNIQUE`, + +* :c:macro:`RTEMS_INTERRUPT_SHARED`, and + +* :c:macro:`RTEMS_INTERRUPT_REPLACE` + +shall be set in the ``options`` parameter. + +The handler routine will be called with the argument specified by ``arg`` when +dispatched. The order in which shared interrupt handlers are dispatched for +one vector is defined by the installation order. The first installed handler +is dispatched first. + +If the option :c:macro:`RTEMS_INTERRUPT_UNIQUE` is set, then it will be ensured +that the handler will be the only one for the interrupt vector. + +If the option :c:macro:`RTEMS_INTERRUPT_SHARED` is set, then multiple handler +may be installed for the interrupt vector. + +If the option :c:macro:`RTEMS_INTERRUPT_REPLACE` is set, then the handler +specified by ``routine`` will replace the first handler with the same argument +for the interrupt vector if it exists, otherwise an error status will be +returned. A second handler with the same argument for the interrupt vector +will remain unchanged. The new handler will inherit the unique or shared +options from the replaced handler. + +An informative description may be provided in ``info``. It may be used for +system debugging and diagnostic tools. The referenced string has to be +persistent as long as the handler is installed. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INCORRECT_STATE` + The service was not initialized. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``routine`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt vector associated with the number specified by + ``vector``. + +:c:macro:`RTEMS_CALLED_FROM_ISR` + The directive was called from within interrupt context. + +:c:macro:`RTEMS_NO_MEMORY` + There was not enough memory available to allocate data structures to + install the handler. + +:c:macro:`RTEMS_RESOURCE_IN_USE` + The :c:macro:`RTEMS_INTERRUPT_UNIQUE` option was set in ``options`` and the + interrupt vector was already occupied by a handler. + +:c:macro:`RTEMS_RESOURCE_IN_USE` + The :c:macro:`RTEMS_INTERRUPT_SHARED` option was set in ``options`` and the + interrupt vector was already occupied by a unique handler. + +:c:macro:`RTEMS_TOO_MANY` + The handler specified by ``routine`` was already installed for the + interrupt vector specified by ``vector`` with an argument equal to the + argument specified by ``arg``. + +:c:macro:`RTEMS_UNSATISFIED` + The :c:macro:`RTEMS_INTERRUPT_REPLACE` option was set in ``options`` and no + handler to replace was installed. + +.. 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/intr/if/handler-remove + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_handler_remove() + +.. _InterfaceRtemsInterruptHandlerRemove: + +rtems_interrupt_handler_remove() +-------------------------------- + +Removes the interrupt handler routine and argument from the interrupt vector. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_handler_remove( + rtems_vector_number vector, + rtems_interrupt_handler routine, + void *arg + ); + +.. rubric:: PARAMETERS: + +``vector`` + This parameter is the interrupt vector number. + +``routine`` + This parameter is the interrupt handler routine to remove. + +``arg`` + This parameter is the interrupt handler argument to remove. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INCORRECT_STATE` + The service was not initialized. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``routine`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt vector associated with the number specified by + ``vector``. + +:c:macro:`RTEMS_CALLED_FROM_ISR` + The directive was called from within interrupt context. + +:c:macro:`RTEMS_UNSATISFIED` + There was no handler routine and argument pair installed specified by + ``routine`` and ``arg``. + +.. 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/intr/if/vector-is-enabled + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_vector_is_enabled() + +.. _InterfaceRtemsInterruptVectorIsEnabled: + +rtems_interrupt_vector_is_enabled() +----------------------------------- + +Checks if the interrupt vector is enabled. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_vector_is_enabled( + rtems_vector_number vector, + bool *enabled + ); + +.. rubric:: PARAMETERS: + +``vector`` + This parameter is the interrupt vector number. + +``enabled`` + This parameter is the pointer to a ``bool`` object. When the directive + call is successful, the enabled status of the interrupt associated with the + interrupt vector specified by ``vector`` will be stored in this object. + When the interrupt was enabled for the processor executing the directive + call at some time point during the call, the object value will be set to + :c:macro:`true`, otherwise to :c:macro:`false`. + +.. rubric:: DESCRIPTION: + +The directive checks if the interrupt associated with the interrupt vector +specified by ``vector`` was enabled for the processor executing the directive +call at some time point during the call. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``enabled`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt vector associated with the number specified by + ``vector``. + +.. rubric:: NOTES: + +Interrupt vectors may be enabled by :ref:`InterfaceRtemsInterruptVectorEnable` +and disabled by :ref:`InterfaceRtemsInterruptVectorDisable`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/intr/if/vector-enable + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_vector_enable() + +.. _InterfaceRtemsInterruptVectorEnable: + +rtems_interrupt_vector_enable() +------------------------------- + +Enables the interrupt vector. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_vector_enable( rtems_vector_number vector ); + +.. rubric:: PARAMETERS: + +``vector`` + This parameter is the number of the interrupt vector to enable. + +.. rubric:: DESCRIPTION: + +The directive enables the interrupt vector specified by ``vector``. This allows +that interrupt service requests are issued to the target processors of the +interrupt vector. Interrupt service requests for an interrupt vector may be +raised by :ref:`InterfaceRtemsInterruptRaise`, +:ref:`InterfaceRtemsInterruptRaiseOn`, external signals, or messages. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt vector associated with the number specified by + ``vector``. + +:c:macro:`RTEMS_UNSATISFIED` + The request to enable the interrupt vector has not been satisfied. + +.. rubric:: NOTES: + +The :ref:`InterfaceRtemsInterruptGetAttributes` directive may be used to check +if an interrupt vector can be enabled. Interrupt vectors may be disabled by +:ref:`InterfaceRtemsInterruptVectorDisable`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/intr/if/vector-disable + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_vector_disable() + +.. _InterfaceRtemsInterruptVectorDisable: + +rtems_interrupt_vector_disable() +-------------------------------- + +Disables the interrupt vector. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_vector_disable( rtems_vector_number vector ); + +.. rubric:: PARAMETERS: + +``vector`` + This parameter is the number of the interrupt vector to disable. + +.. rubric:: DESCRIPTION: + +The directive disables the interrupt vector specified by ``vector``. This +prevents that an interrupt service request is issued to the target processors +of the interrupt vector. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt vector associated with the number specified by + ``vector``. + +:c:macro:`RTEMS_UNSATISFIED` + The request to disable the interrupt vector has not been satisfied. + +.. rubric:: NOTES: + +The :ref:`InterfaceRtemsInterruptGetAttributes` directive may be used to check +if an interrupt vector can be disabled. Interrupt vectors may be enabled by +:ref:`InterfaceRtemsInterruptVectorEnable`. There may be targets on which some +interrupt vectors cannot be disabled, for example a hardware watchdog interrupt +or software generated interrupts. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/intr/if/is-pending + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_is_pending() + +.. _InterfaceRtemsInterruptIsPending: + +rtems_interrupt_is_pending() +---------------------------- + +Checks if the interrupt is pending. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_is_pending( + rtems_vector_number vector, + bool *pending + ); + +.. rubric:: PARAMETERS: + +``vector`` + This parameter is the interrupt vector number. + +``pending`` + This parameter is the pointer to a ``bool`` object. When the directive + call is successful, the pending status of the interrupt associated with the + interrupt vector specified by ``vector`` will be stored in this object. + When the interrupt was pending for the processor executing the directive + call at some time point during the call, the object value will be set to + :c:macro:`true`, otherwise to :c:macro:`false`. + +.. rubric:: DESCRIPTION: + +The directive checks if the interrupt associated with the interrupt vector +specified by ``vector`` was pending for the processor executing the directive +call at some time point during the call. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``pending`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt vector associated with the number specified by + ``vector``. + +:c:macro:`RTEMS_UNSATISFIED` + The request to get the pending status has not been satisfied. + +.. rubric:: NOTES: + +Interrupts may be made pending by calling the +:ref:`InterfaceRtemsInterruptRaise` or :ref:`InterfaceRtemsInterruptRaiseOn` +directives or due to external signals or messages. The pending state may be +cleared by :ref:`InterfaceRtemsInterruptClear`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/intr/if/raise + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_raise() + +.. _InterfaceRtemsInterruptRaise: + +rtems_interrupt_raise() +----------------------- + +Raises the interrupt vector. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_raise( rtems_vector_number vector ); + +.. rubric:: PARAMETERS: + +``vector`` + This parameter is the number of the interrupt vector to raise. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt vector associated with the number specified by + ``vector``. + +:c:macro:`RTEMS_UNSATISFIED` + The request to raise the interrupt vector has not been satisfied. + +.. rubric:: NOTES: + +The :ref:`InterfaceRtemsInterruptGetAttributes` directive may be used to check +if an interrupt vector can be raised. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/intr/if/raise-on + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_raise_on() + +.. _InterfaceRtemsInterruptRaiseOn: + +rtems_interrupt_raise_on() +-------------------------- + +Raises the interrupt vector on the processor. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_raise_on( + rtems_vector_number vector, + uint32_t cpu_index + ); + +.. rubric:: PARAMETERS: + +``vector`` + This parameter is the number of the interrupt vector to raise. + +``cpu_index`` + This parameter is the index of the target processor of the interrupt vector + to raise. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt vector associated with the number specified by + ``vector``. + +:c:macro:`RTEMS_NOT_CONFIGURED` + The processor specified by ``cpu_index`` was not configured to be used by + the application. + +:c:macro:`RTEMS_INCORRECT_STATE` + The processor specified by ``cpu_index`` was configured to be used by the + application, however, it was not online. + +:c:macro:`RTEMS_UNSATISFIED` + The request to raise the interrupt vector has not been satisfied. + +.. rubric:: NOTES: + +The :ref:`InterfaceRtemsInterruptGetAttributes` directive may be used to check +if an interrupt vector can be raised on a processor. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/intr/if/clear + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_clear() + +.. _InterfaceRtemsInterruptClear: + +rtems_interrupt_clear() +----------------------- + +Clears the interrupt vector. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_clear( rtems_vector_number vector ); + +.. rubric:: PARAMETERS: + +``vector`` + This parameter is the number of the interrupt vector to clear. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt vector associated with the number specified by + ``vector``. + +:c:macro:`RTEMS_UNSATISFIED` + The request to raise the interrupt vector has not been satisfied. + +.. rubric:: NOTES: + +The :ref:`InterfaceRtemsInterruptGetAttributes` directive may be used to check +if an interrupt vector can be cleared. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/intr/if/get-affinity + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_get_affinity() + +.. _InterfaceRtemsInterruptGetAffinity: + +rtems_interrupt_get_affinity() +------------------------------ + +Gets the processor affinity set of the interrupt vector. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_get_affinity( + rtems_vector_number vector, + size_t affinity_size, + cpu_set_t *affinity + ); + +.. rubric:: PARAMETERS: + +``vector`` + This parameter is the interrupt vector number. + +``affinity_size`` + This parameter is the size of the processor set referenced by ``affinity`` + in bytes. + +``affinity`` + This parameter is the pointer to a :c:type:`cpu_set_t` object. When the + directive call is successful, the processor affinity set of the interrupt + vector will be stored in this object. A set bit in the processor set means + that the corresponding processor is in the processor affinity set of the + interrupt vector, otherwise the bit is cleared. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``affinity`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt vector associated with the number specified by + ``vector``. + +:c:macro:`RTEMS_INVALID_SIZE` + The size specified by ``affinity_size`` of the processor set was too small + for the processor affinity set of the interrupt vector. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/intr/if/set-affinity + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_set_affinity() + +.. _InterfaceRtemsInterruptSetAffinity: + +rtems_interrupt_set_affinity() +------------------------------ + +Sets the processor affinity set of the interrupt vector. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_set_affinity( + rtems_vector_number vector, + size_t affinity_size, + const cpu_set_t *affinity + ); + +.. rubric:: PARAMETERS: + +``vector`` + This parameter is the interrupt vector number. + +``affinity_size`` + This parameter is the size of the processor set referenced by ``affinity`` + in bytes. + +``affinity`` + This parameter is the pointer to a :c:type:`cpu_set_t` object. The + processor set defines the new processor affinity set of the interrupt + vector. A set bit in the processor set means that the corresponding + processor shall be in the processor affinity set of the interrupt vector, + otherwise the bit shall be cleared. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``affinity`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt vector associated with the number specified by + ``vector``. + +:c:macro:`RTEMS_INVALID_NUMBER` + The referenced processor set was not a valid new processor affinity set for + the interrupt vector. + +:c:macro:`RTEMS_UNSATISFIED` + The request to set the processor affinity of the interrupt vector has not + been satisfied. + +.. rubric:: NOTES: + +The :ref:`InterfaceRtemsInterruptGetAttributes` directive may be used to check +if the processor affinity of an interrupt vector can be set. + +Only online processors of the affinity set specified by ``affinity_size`` and +``affinity`` are considered by the directive. Other processors of the set are +ignored. If the set contains no online processor, then the set is invalid and +an error status is returned. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/intr/if/get-attributes + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_get_attributes() + +.. _InterfaceRtemsInterruptGetAttributes: + +rtems_interrupt_get_attributes() +-------------------------------- + +Gets the attributes of the interrupt vector. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_get_attributes( + rtems_vector_number vector, + rtems_interrupt_attributes *attributes + ); + +.. rubric:: PARAMETERS: + +``vector`` + This parameter is the interrupt vector number. + +``attributes`` + This parameter is the pointer to an + :ref:`InterfaceRtemsInterruptAttributes` object. When the directive call + is successful, the attributes of the interrupt vector will be stored in + this object. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``attributes`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt vector associated with the number specified by + ``vector``. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/intr/if/handler-iterate + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_handler_iterate() + +.. _InterfaceRtemsInterruptHandlerIterate: + +rtems_interrupt_handler_iterate() +--------------------------------- + +Iterates over all interrupt handler installed at the interrupt vector. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_handler_iterate( + rtems_vector_number vector, + rtems_interrupt_per_handler_routine routine, + void *arg + ); + +.. rubric:: PARAMETERS: + +``vector`` + This parameter is the interrupt vector number. + +``routine`` + This parameter is the visitor routine. + +``arg`` + This parameter is the visitor argument. + +.. rubric:: DESCRIPTION: + +For each installed handler at the interrupt vector the visitor function +specified by ``routine`` will be called with the argument specified by ``arg`` +and the handler information, options, routine and argument. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INCORRECT_STATE` + The service was not initialized. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``routine`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt vector associated with the number specified by + ``vector``. + +:c:macro:`RTEMS_CALLED_FROM_ISR` + The directive was called from within interrupt context. + +.. rubric:: NOTES: + +The directive is intended for system information and diagnostics. + +Never install or remove an interrupt handler within the visitor function. This +may result in a deadlock. + +.. 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/intr/if/server-initialize + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_server_initialize() + +.. _InterfaceRtemsInterruptServerInitialize: + +rtems_interrupt_server_initialize() +----------------------------------- + +Initializes the interrupt server tasks. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_server_initialize( + rtems_task_priority priority, + size_t stack_size, + rtems_mode modes, + rtems_attribute attributes, + uint32_t *server_count + ); + +.. rubric:: PARAMETERS: + +``priority`` + This parameter is the initial :term:`task priority` of the created + interrupt servers. + +``stack_size`` + This parameter is the task stack size of the created interrupt servers. + +``modes`` + This parameter is the initial mode set of the created interrupt servers. + +``attributes`` + This parameter is the attribute set of the created interrupt servers. + +``server_count`` + This parameter is the pointer to an `uint32_t + <https://en.cppreference.com/w/c/types/integer>`_ object or `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. When the pointer is not + equal to `NULL <https://en.cppreference.com/w/c/types/NULL>`_, the count of + successfully created interrupt servers is stored in this object regardless + of the return status. + +.. rubric:: DESCRIPTION: + +The directive tries to create an interrupt server task for each online +processor in the system. The tasks will have the initial priority specified by +``priority``, the stack size specified by ``stack_size``, the initial mode set +specified by ``modes``, and the attribute set specified by ``attributes``. The +count of successfully created server tasks will be returned in ``server_count`` +if the pointer is not equal to `NULL +<https://en.cppreference.com/w/c/types/NULL>`_. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INCORRECT_STATE` + The interrupt servers were already initialized. + +The directive uses :ref:`InterfaceRtemsTaskCreate`. If this directive fails, +then its error status will be returned. + +.. rubric:: NOTES: + +Interrupt handlers may be installed on an interrupt server with +:ref:`InterfaceRtemsInterruptServerHandlerInstall` and removed with +:ref:`InterfaceRtemsInterruptServerHandlerRemove` using a server index. In +case of an interrupt, the request will be forwarded to the interrupt server. +The handlers are executed within the interrupt server context. If one handler +blocks on something this may delay the processing of other handlers. + +Interrupt servers may be deleted by :ref:`InterfaceRtemsInterruptServerDelete`. + +.. 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/intr/if/server-create + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_server_create() + +.. _InterfaceRtemsInterruptServerCreate: + +rtems_interrupt_server_create() +------------------------------- + +Creates an interrupt server. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_server_create( + rtems_interrupt_server_control *control, + const rtems_interrupt_server_config *config, + uint32_t *server_index + ); + +.. rubric:: PARAMETERS: + +``control`` + This parameter is the pointer to an + :ref:`InterfaceRtemsInterruptServerControl` object. When the directive + call was successful, the ownership of the object was transferred from the + caller of the directive to the interrupt server management. + +``config`` + This parameter is the interrupt server configuration. + +``server_index`` + This parameter is the pointer to an `uint32_t + <https://en.cppreference.com/w/c/types/integer>`_ object. When the + directive call was successful, the index of the created interrupt server + will be stored in this object. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +The directive uses :ref:`InterfaceRtemsTaskCreate`. If this directive fails, +then its error status will be returned. + +.. rubric:: NOTES: + +See also :ref:`InterfaceRtemsInterruptServerInitialize` and +:ref:`InterfaceRtemsInterruptServerDelete`. + +.. 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/intr/if/server-handler-install + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_server_handler_install() + +.. _InterfaceRtemsInterruptServerHandlerInstall: + +rtems_interrupt_server_handler_install() +---------------------------------------- + +Installs the interrupt handler routine and argument at the interrupt vector on +the interrupt server. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_server_handler_install( + uint32_t server_index, + rtems_vector_number vector, + const char *info, + rtems_option options, + rtems_interrupt_handler routine, + void *arg + ); + +.. rubric:: PARAMETERS: + +``server_index`` + This parameter is the interrupt server index. The constant + :c:macro:`RTEMS_INTERRUPT_SERVER_DEFAULT` may be used to specify the + default interrupt server. + +``vector`` + This parameter is the interrupt vector number. + +``info`` + This parameter is the descriptive information of the interrupt handler to + install. + +``options`` + This parameter is the interrupt handler install option set. + +``routine`` + This parameter is the interrupt handler routine to install. + +``arg`` + This parameter is the interrupt handler argument to install. + +.. rubric:: DESCRIPTION: + +The handler routine specified by ``routine`` will be executed within the +context of the interrupt server task specified by ``server_index``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt server associated with the index specified by + ``server_index``. + +:c:macro:`RTEMS_CALLED_FROM_ISR` + The directive was called from within interrupt context. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``routine`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt vector associated with the number specified by + ``vector``. + +:c:macro:`RTEMS_INVALID_NUMBER` + An option specified by ``info`` was not applicable. + +:c:macro:`RTEMS_RESOURCE_IN_USE` + The :c:macro:`RTEMS_INTERRUPT_UNIQUE` option was set in ``info`` and the + interrupt vector was already occupied by a handler. + +:c:macro:`RTEMS_RESOURCE_IN_USE` + The :c:macro:`RTEMS_INTERRUPT_SHARED` option was set in ``info`` and the + interrupt vector was already occupied by a unique handler. + +:c:macro:`RTEMS_TOO_MANY` + The handler specified by ``routine`` was already installed for the + interrupt vector specified by ``vector`` with an argument equal to the + argument specified by ``arg``. + +:c:macro:`RTEMS_UNSATISFIED` + The :c:macro:`RTEMS_INTERRUPT_REPLACE` option was set in ``info`` and no + handler to replace was installed. + +.. rubric:: NOTES: + +See also :ref:`InterfaceRtemsInterruptHandlerInstall`. + +.. 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/intr/if/server-handler-remove + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_server_handler_remove() + +.. _InterfaceRtemsInterruptServerHandlerRemove: + +rtems_interrupt_server_handler_remove() +--------------------------------------- + +Removes the interrupt handler routine and argument from the interrupt vector +and the interrupt server. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_server_handler_remove( + uint32_t server_index, + rtems_vector_number vector, + rtems_interrupt_handler routine, + void *arg + ); + +.. rubric:: PARAMETERS: + +``server_index`` + This parameter is the interrupt server index. The constant + :c:macro:`RTEMS_INTERRUPT_SERVER_DEFAULT` may be used to specify the + default interrupt server. + +``vector`` + This parameter is the interrupt vector number. + +``routine`` + This parameter is the interrupt handler routine to remove. + +``arg`` + This parameter is the interrupt handler argument to remove. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt server associated with the index specified by + ``server_index``. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt vector associated with the number specified by + ``vector``. + +:c:macro:`RTEMS_UNSATISFIED` + There was no handler routine and argument pair installed specified by + ``routine`` and ``arg``. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* 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. + +* The directive sends a request to another task and waits for a response. This + may cause the calling task to be blocked and unblocked. + +* The directive shall not be called from within the context of an interrupt + server. Calling the directive from within the context of an interrupt server + is undefined behaviour. + +.. Generated from spec:/rtems/intr/if/server-set-affinity + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_server_set_affinity() + +.. _InterfaceRtemsInterruptServerSetAffinity: + +rtems_interrupt_server_set_affinity() +------------------------------------- + +Sets the processor affinity of the interrupt server. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_server_set_affinity( + uint32_t server_index, + size_t affinity_size, + const cpu_set_t *affinity, + rtems_task_priority priority + ); + +.. rubric:: PARAMETERS: + +``server_index`` + This parameter is the interrupt server index. The constant + :c:macro:`RTEMS_INTERRUPT_SERVER_DEFAULT` may be used to specify the + default interrupt server. + +``affinity_size`` + This parameter is the size of the processor set referenced by ``affinity`` + in bytes. + +``affinity`` + This parameter is the pointer to a :c:type:`cpu_set_t` object. The + processor set defines the new processor affinity set of the interrupt + server. A set bit in the processor set means that the corresponding + processor shall be in the processor affinity set of the task, otherwise the + bit shall be cleared. + +``priority`` + This parameter is the new :term:`real priority` for the interrupt server. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt server associated with the index specified by + ``server_index``. + +The directive uses :ref:`InterfaceRtemsSchedulerIdentByProcessorSet`, +:ref:`InterfaceRtemsTaskSetScheduler`, and +:ref:`InterfaceRtemsTaskSetAffinity`. If one of these directive fails, then +its error status will be returned. + +.. rubric:: NOTES: + +The scheduler is set determined by the highest numbered processor in the +affinity set specified by ``affinity``. + +This operation is only reliable in case the interrupt server was suspended via +:ref:`InterfaceRtemsInterruptServerSuspend`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may change the processor affinity of a task. This may cause + the calling task to be preempted. + +* The directive may change the priority of a task. This may cause the calling + task to be preempted. + +.. Generated from spec:/rtems/intr/if/server-delete + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_server_delete() + +.. _InterfaceRtemsInterruptServerDelete: + +rtems_interrupt_server_delete() +------------------------------- + +Deletes the interrupt server. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_server_delete( uint32_t server_index ); + +.. rubric:: PARAMETERS: + +``server_index`` + This parameter is the index of the interrupt server to delete. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt server associated with the server index specified by + ``server_index``. + +.. rubric:: NOTES: + +The interrupt server deletes itself, so after the return of the directive the +interrupt server may be still in the termination process depending on the task +priorities of the system. + +See also :ref:`InterfaceRtemsInterruptServerCreate`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within task context. + +* The directive shall not be called from within the context of an interrupt + server. Calling the directive from within the context of an interrupt server + is undefined behaviour. + +* The directive sends a request to another task and waits for a response. This + may cause the calling task to be blocked and unblocked. + +.. Generated from spec:/rtems/intr/if/server-suspend + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_server_suspend() + +.. _InterfaceRtemsInterruptServerSuspend: + +rtems_interrupt_server_suspend() +-------------------------------- + +Suspends the interrupt server. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_server_suspend( uint32_t server_index ); + +.. rubric:: PARAMETERS: + +``server_index`` + This parameter is the index of the interrupt server to suspend. The + constant :c:macro:`RTEMS_INTERRUPT_SERVER_DEFAULT` may be used to specify + the default interrupt server. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt server associated with the index specified by + ``server_index``. + +.. rubric:: NOTES: + +Interrupt server may be resumed by :ref:`InterfaceRtemsInterruptServerResume`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within task context. + +* The directive shall not be called from within the context of an interrupt + server. Calling the directive from within the context of an interrupt server + is undefined behaviour. + +* The directive sends a request to another task and waits for a response. This + may cause the calling task to be blocked and unblocked. + +.. Generated from spec:/rtems/intr/if/server-resume + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_server_resume() + +.. _InterfaceRtemsInterruptServerResume: + +rtems_interrupt_server_resume() +------------------------------- + +Resumes the interrupt server. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_server_resume( uint32_t server_index ); + +.. rubric:: PARAMETERS: + +``server_index`` + This parameter is the index of the interrupt server to resume. The + constant :c:macro:`RTEMS_INTERRUPT_SERVER_DEFAULT` may be used to specify + the default interrupt server. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt server associated with the index specified by + ``server_index``. + +.. rubric:: NOTES: + +Interrupt server may be suspended by +:ref:`InterfaceRtemsInterruptServerSuspend`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within task context. + +* The directive shall not be called from within the context of an interrupt + server. Calling the directive from within the context of an interrupt server + is undefined behaviour. + +* The directive sends a request to another task and waits for a response. This + may cause the calling task to be blocked and unblocked. + +.. Generated from spec:/rtems/intr/if/server-move + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_server_move() + +.. _InterfaceRtemsInterruptServerMove: + +rtems_interrupt_server_move() +----------------------------- + +Moves the interrupt handlers installed at the interrupt vector and the source +interrupt server to the destination interrupt server. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_server_move( + uint32_t source_server_index, + rtems_vector_number vector, + uint32_t destination_server_index + ); + +.. rubric:: PARAMETERS: + +``source_server_index`` + This parameter is the index of the source interrupt server. The constant + :c:macro:`RTEMS_INTERRUPT_SERVER_DEFAULT` may be used to specify the + default interrupt server. + +``vector`` + This parameter is the interrupt vector number. + +``destination_server_index`` + This parameter is the index of the destination interrupt server. The + constant :c:macro:`RTEMS_INTERRUPT_SERVER_DEFAULT` may be used to specify + the default interrupt server. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt server associated with the index specified by + ``source_server_index``. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt server associated with the index specified by + ``destination_server_index``. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt vector associated with the number specified by + ``vector``. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within task context. + +* The directive shall not be called from within the context of an interrupt + server. Calling the directive from within the context of an interrupt server + is undefined behaviour. + +* The directive sends a request to another task and waits for a response. This + may cause the calling task to be blocked and unblocked. + +.. Generated from spec:/rtems/intr/if/server-handler-iterate + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_server_handler_iterate() + +.. _InterfaceRtemsInterruptServerHandlerIterate: + +rtems_interrupt_server_handler_iterate() +---------------------------------------- + +Iterates over all interrupt handler installed at the interrupt vector and +interrupt server. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_server_handler_iterate( + uint32_t server_index, + rtems_vector_number vector, + rtems_interrupt_per_handler_routine routine, + void *arg + ); + +.. rubric:: PARAMETERS: + +``server_index`` + This parameter is the index of the interrupt server. + +``vector`` + This parameter is the interrupt vector number. + +``routine`` + This parameter is the visitor routine. + +``arg`` + This parameter is the visitor argument. + +.. rubric:: DESCRIPTION: + +For each installed handler at the interrupt vector and interrupt server the +visitor function specified by ``vector`` will be called with the argument +specified by ``routine`` and the handler information, options, routine and +argument. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt server associated with the index specified by + ``server_index``. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt vector associated with the number specified by + ``vector``. + +.. rubric:: NOTES: + +The directive is intended for system information and diagnostics. + +Never install or remove an interrupt handler within the visitor function. This +may result in a deadlock. + +.. 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/intr/if/server-entry-initialize + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_server_entry_initialize() + +.. _InterfaceRtemsInterruptServerEntryInitialize: + +rtems_interrupt_server_entry_initialize() +----------------------------------------- + +Initializes the interrupt server entry. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_server_entry_initialize( + uint32_t server_index, + rtems_interrupt_server_entry *entry + ); + +.. rubric:: PARAMETERS: + +``server_index`` + This parameter is the interrupt server index. The constant + :c:macro:`RTEMS_INTERRUPT_SERVER_DEFAULT` may be used to specify the + default interrupt server. + +``entry`` + This parameter is the interrupt server entry to initialize. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt server associated with the index specified by + ``server_index``. + +.. rubric:: NOTES: + +After initialization, the list of actions of the interrupt server entry is +empty. Actions may be prepended by +:ref:`InterfaceRtemsInterruptServerActionPrepend`. Interrupt server entries may +be moved to another interrupt vector with +:ref:`InterfaceRtemsInterruptServerEntryMove`. Server entries may be submitted +to get serviced by the interrupt server with +:ref:`InterfaceRtemsInterruptServerEntrySubmit`. Server entries may be +destroyed by :ref:`InterfaceRtemsInterruptServerEntryDestroy`. + +.. 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/intr/if/server-action-prepend + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_server_action_prepend() + +.. _InterfaceRtemsInterruptServerActionPrepend: + +rtems_interrupt_server_action_prepend() +--------------------------------------- + +Prepends the interrupt server action to the list of actions of the interrupt +server entry. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_interrupt_server_action_prepend( + rtems_interrupt_server_entry *entry, + rtems_interrupt_server_action *action, + rtems_interrupt_handler routine, + void *arg + ); + +.. rubric:: PARAMETERS: + +``entry`` + This parameter is the interrupt server entry to prepend the interrupt + server action. It shall have been initialized via + :ref:`InterfaceRtemsInterruptServerEntryInitialize`. + +``action`` + This parameter is the interrupt server action to initialize and prepend to + the list of actions of the entry. + +``routine`` + This parameter is the interrupt handler routine to set in the action. + +``arg`` + This parameter is the interrupt handler argument to set in the action. + +.. rubric:: NOTES: + +No error checking is performed by the directive. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +* The interrupt server entry shall have been initialized by + :ref:`InterfaceRtemsInterruptServerEntryInitialize` and further optional + calls to :ref:`InterfaceRtemsInterruptServerActionPrepend`. + +* The directive shall not be called concurrently with + :ref:`InterfaceRtemsInterruptServerActionPrepend` with the same interrupt + server entry. Calling the directive under this condition is undefined + behaviour. + +* The directive shall not be called concurrently with + :ref:`InterfaceRtemsInterruptServerEntryMove` with the same interrupt server + entry. Calling the directive under this condition is undefined behaviour. + +* The directive shall not be called concurrently with + :ref:`InterfaceRtemsInterruptServerEntrySubmit` with the same interrupt + server entry. Calling the directive under this condition is undefined + behaviour. + +* The directive shall not be called while the interrupt server entry is pending + on or serviced by its current interrupt server. Calling the directive under + these conditions is undefined behaviour. + +.. Generated from spec:/rtems/intr/if/server-entry-destroy + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_server_entry_destroy() + +.. _InterfaceRtemsInterruptServerEntryDestroy: + +rtems_interrupt_server_entry_destroy() +-------------------------------------- + +Destroys the interrupt server entry. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_interrupt_server_entry_destroy( + rtems_interrupt_server_entry *entry + ); + +.. rubric:: PARAMETERS: + +``entry`` + This parameter is the interrupt server entry to destroy. + +.. rubric:: NOTES: + +No error checking is performed by the directive. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within task context. + +* The directive shall not be called from within the context of an interrupt + server. Calling the directive from within the context of an interrupt server + is undefined behaviour. + +* The directive sends a request to another task and waits for a response. This + may cause the calling task to be blocked and unblocked. + +* The interrupt server entry shall have been initialized by + :ref:`InterfaceRtemsInterruptServerEntryInitialize` and further optional + calls to :ref:`InterfaceRtemsInterruptServerActionPrepend`. + +.. Generated from spec:/rtems/intr/if/server-entry-submit + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_server_entry_submit() + +.. _InterfaceRtemsInterruptServerEntrySubmit: + +rtems_interrupt_server_entry_submit() +------------------------------------- + +Submits the interrupt server entry to be serviced by the interrupt server. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_interrupt_server_entry_submit( + rtems_interrupt_server_entry *entry + ); + +.. rubric:: PARAMETERS: + +``entry`` + This parameter is the interrupt server entry to submit. + +.. rubric:: DESCRIPTION: + +The directive appends the entry to the pending entries of the interrupt server. +The interrupt server is notified that a new entry is pending. Once the +interrupt server is scheduled it services the actions of all pending entries. + +.. rubric:: NOTES: + +This directive may be used to do a two-step interrupt processing. The first +step is done from within interrupt context by a call to this directive. The +second step is then done from within the context of the interrupt server. + +No error checking is performed by the directive. + +A submitted entry may be destroyed by +:ref:`InterfaceRtemsInterruptServerEntryDestroy`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may unblock a task. This may cause the calling task to be + preempted. + +* The interrupt server entry shall have been initialized by + :ref:`InterfaceRtemsInterruptServerEntryInitialize` and further optional + calls to :ref:`InterfaceRtemsInterruptServerActionPrepend`. + +* The directive shall not be called concurrently with + :ref:`InterfaceRtemsInterruptServerActionPrepend` with the same interrupt + server entry. Calling the directive under this condition is undefined + behaviour. + +* The directive shall not be called concurrently with + :ref:`InterfaceRtemsInterruptServerEntryMove` with the same interrupt server + entry. Calling the directive under this condition is undefined behaviour. + +.. Generated from spec:/rtems/intr/if/server-entry-move + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_server_entry_move() + +.. _InterfaceRtemsInterruptServerEntryMove: + +rtems_interrupt_server_entry_move() +----------------------------------- + +Moves the interrupt server entry to the interrupt server. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_server_entry_move( + rtems_interrupt_server_entry *entry, + uint32_t server_index + ); + +.. rubric:: PARAMETERS: + +``entry`` + This parameter is the interrupt server entry to move. + +``server_index`` + This parameter is the index of the destination interrupt server. The + constant :c:macro:`RTEMS_INTERRUPT_SERVER_DEFAULT` may be used to specify + the default interrupt server. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt server associated with the index specified by + ``server_index``. + +.. 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. + +* The interrupt server entry shall have been initialized by + :ref:`InterfaceRtemsInterruptServerEntryInitialize` and further optional + calls to :ref:`InterfaceRtemsInterruptServerActionPrepend`. + +* The directive shall not be called concurrently with + :ref:`InterfaceRtemsInterruptServerActionPrepend` with the same interrupt + server entry. Calling the directive under this condition is undefined + behaviour. + +* The directive shall not be called concurrently with + :ref:`InterfaceRtemsInterruptServerEntryMove` with the same interrupt server + entry. Calling the directive under this condition is undefined behaviour. + +* The directive shall not be called concurrently with + :ref:`InterfaceRtemsInterruptServerEntrySubmit` with the same interrupt + server entry. Calling the directive under this condition is undefined + behaviour. + +* The directive shall not be called while the interrupt server entry is pending + on or serviced by its current interrupt server. Calling the directive under + these conditions is undefined behaviour. + +.. Generated from spec:/rtems/intr/if/server-request-initialize + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_server_request_initialize() + +.. _InterfaceRtemsInterruptServerRequestInitialize: + +rtems_interrupt_server_request_initialize() +------------------------------------------- + +Initializes the interrupt server request. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_server_request_initialize( + uint32_t server_index, + rtems_interrupt_server_request *request, + rtems_interrupt_handler routine, + void *arg + ); + +.. rubric:: PARAMETERS: + +``server_index`` + This parameter is the interrupt server index. The constant + :c:macro:`RTEMS_INTERRUPT_SERVER_DEFAULT` may be used to specify the + default interrupt server. + +``request`` + This parameter is the interrupt server request to initialize. + +``routine`` + This parameter is the interrupt handler routine for the request action. + +``arg`` + This parameter is the interrupt handler argument for the request action. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt server associated with the index specified by + ``server_index``. + +.. rubric:: NOTES: + +An interrupt server requests consists of an interrupt server entry and exactly +one interrupt server action. The interrupt vector of the request may be +changed with :ref:`InterfaceRtemsInterruptServerRequestSetVector`. Interrupt +server requests may be submitted to get serviced by the interrupt server with +:ref:`InterfaceRtemsInterruptServerRequestSubmit`. Requests may be destroyed +by :ref:`InterfaceRtemsInterruptServerRequestDestroy`. + +.. 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/intr/if/server-request-set-vector + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_server_request_set_vector() + +.. _InterfaceRtemsInterruptServerRequestSetVector: + +rtems_interrupt_server_request_set_vector() +------------------------------------------- + +Sets the interrupt vector in the interrupt server request. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_interrupt_server_request_set_vector( + rtems_interrupt_server_request *request, + rtems_vector_number vector + ); + +.. rubric:: PARAMETERS: + +``request`` + This parameter is the interrupt server request to change. + +``vector`` + This parameter is the interrupt vector number to be used by the request. + +.. rubric:: NOTES: + +By default, the interrupt vector of an interrupt server request is set to a +special value which is outside the range of vectors supported by the interrupt +controller hardware. + +Calls to :ref:`InterfaceRtemsInterruptServerRequestSubmit` will disable the +interrupt vector of the request. After processing of the request by the +interrupt server the interrupt vector will be enabled again. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +* The interrupt server request shall have been initialized by + :ref:`InterfaceRtemsInterruptServerRequestInitialize`. + +* The directive shall not be called concurrently with + :ref:`InterfaceRtemsInterruptServerRequestSetVector` with the same interrupt + server request. Calling the directive under this condition is undefined + behaviour. + +* The directive shall not be called concurrently with + :ref:`InterfaceRtemsInterruptServerRequestSubmit` with the same interrupt + server request. Calling the directive under this condition is undefined + behaviour. + +* The directive shall not be called while the interrupt server entry is pending + on or serviced by its current interrupt server. Calling the directive under + these conditions is undefined behaviour. + +.. Generated from spec:/rtems/intr/if/server-request-destroy + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_server_request_destroy() + +.. _InterfaceRtemsInterruptServerRequestDestroy: + +rtems_interrupt_server_request_destroy() +---------------------------------------- + +Destroys the interrupt server request. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_interrupt_server_request_destroy( + rtems_interrupt_server_request *request + ); + +.. rubric:: PARAMETERS: + +``request`` + This parameter is the interrupt server request to destroy. + +.. rubric:: NOTES: + +No error checking is performed by the directive. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within task context. + +* The directive shall not be called from within the context of an interrupt + server. Calling the directive from within the context of an interrupt server + is undefined behaviour. + +* The directive sends a request to another task and waits for a response. This + may cause the calling task to be blocked and unblocked. + +* The interrupt server request shall have been initialized by + :ref:`InterfaceRtemsInterruptServerRequestInitialize`. + +.. Generated from spec:/rtems/intr/if/server-request-submit + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_server_request_submit() + +.. _InterfaceRtemsInterruptServerRequestSubmit: + +rtems_interrupt_server_request_submit() +--------------------------------------- + +Submits the interrupt server request to be serviced by the interrupt server. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_interrupt_server_request_submit( + rtems_interrupt_server_request *request + ); + +.. rubric:: PARAMETERS: + +``request`` + This parameter is the interrupt server request to submit. + +.. rubric:: DESCRIPTION: + +The directive appends the interrupt server entry of the request to the pending +entries of the interrupt server. The interrupt server is notified that a new +entry is pending. Once the interrupt server is scheduled it services the +actions of all pending entries. + +.. rubric:: NOTES: + +This directive may be used to do a two-step interrupt processing. The first +step is done from within interrupt context by a call to this directive. The +second step is then done from within the context of the interrupt server. + +No error checking is performed by the directive. + +A submitted request may be destroyed by +:ref:`InterfaceRtemsInterruptServerRequestDestroy`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may unblock a task. This may cause the calling task to be + preempted. + +* The interrupt server request shall have been initialized by + :ref:`InterfaceRtemsInterruptServerRequestInitialize`. + +* The directive shall not be called concurrently with + :ref:`InterfaceRtemsInterruptServerRequestSetVector` with the same interrupt + server request. Calling the directive under this condition is undefined + behaviour. diff --git a/c-user/interrupt/index.rst b/c-user/interrupt/index.rst new file mode 100644 index 0000000..92d332d --- /dev/null +++ b/c-user/interrupt/index.rst @@ -0,0 +1,17 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 embedded brains GmbH & Co. KG + +.. index:: interrupts + +.. _RTEMSAPIClassicIntr: + +Interrupt Manager +***************** + +.. toctree:: + + introduction + background + operations + directives diff --git a/c-user/interrupt/introduction.rst b/c-user/interrupt/introduction.rst new file mode 100644 index 0000000..14ea275 --- /dev/null +++ b/c-user/interrupt/introduction.rst @@ -0,0 +1,241 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2008, 2022 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/rtems/intr/if/group + +.. _InterruptManagerIntroduction: + +Introduction +============ + +.. The following list was generated from: +.. spec:/rtems/intr/if/catch +.. spec:/rtems/intr/if/disable +.. spec:/rtems/intr/if/enable +.. spec:/rtems/intr/if/flash +.. spec:/rtems/intr/if/local-disable +.. spec:/rtems/intr/if/local-enable +.. spec:/rtems/intr/if/is-in-progress +.. spec:/rtems/intr/if/lock-initialize +.. spec:/rtems/intr/if/lock-destroy +.. spec:/rtems/intr/if/lock-acquire +.. spec:/rtems/intr/if/lock-release +.. spec:/rtems/intr/if/lock-acquire-isr +.. spec:/rtems/intr/if/lock-release-isr +.. spec:/rtems/intr/if/lock-isr-disable +.. spec:/rtems/intr/if/lock-declare +.. spec:/rtems/intr/if/lock-define +.. spec:/rtems/intr/if/lock-initializer +.. spec:/rtems/intr/if/lock-member +.. spec:/rtems/intr/if/lock-reference +.. spec:/rtems/intr/if/entry-initializer +.. spec:/rtems/intr/if/entry-initialize +.. spec:/rtems/intr/if/entry-install +.. spec:/rtems/intr/if/entry-remove +.. spec:/rtems/intr/if/handler-install +.. spec:/rtems/intr/if/handler-remove +.. spec:/rtems/intr/if/vector-is-enabled +.. spec:/rtems/intr/if/vector-enable +.. spec:/rtems/intr/if/vector-disable +.. spec:/rtems/intr/if/is-pending +.. spec:/rtems/intr/if/raise +.. spec:/rtems/intr/if/raise-on +.. spec:/rtems/intr/if/clear +.. spec:/rtems/intr/if/get-affinity +.. spec:/rtems/intr/if/set-affinity +.. spec:/rtems/intr/if/get-attributes +.. spec:/rtems/intr/if/handler-iterate +.. spec:/rtems/intr/if/server-initialize +.. spec:/rtems/intr/if/server-create +.. spec:/rtems/intr/if/server-handler-install +.. spec:/rtems/intr/if/server-handler-remove +.. spec:/rtems/intr/if/server-set-affinity +.. spec:/rtems/intr/if/server-delete +.. spec:/rtems/intr/if/server-suspend +.. spec:/rtems/intr/if/server-resume +.. spec:/rtems/intr/if/server-move +.. spec:/rtems/intr/if/server-handler-iterate +.. spec:/rtems/intr/if/server-entry-initialize +.. spec:/rtems/intr/if/server-action-prepend +.. spec:/rtems/intr/if/server-entry-destroy +.. spec:/rtems/intr/if/server-entry-submit +.. spec:/rtems/intr/if/server-entry-move +.. spec:/rtems/intr/if/server-request-initialize +.. spec:/rtems/intr/if/server-request-set-vector +.. spec:/rtems/intr/if/server-request-destroy +.. spec:/rtems/intr/if/server-request-submit + +Any real-time executive must provide a mechanism for quick response to +externally generated interrupts to satisfy the critical time constraints of the +application. The Interrupt Manager provides this mechanism for RTEMS. This +manager permits quick interrupt response times by providing the critical +ability to alter task execution which allows a task to be preempted upon exit +from an ISR. The directives provided by the Interrupt Manager are: + +* :ref:`InterfaceRtemsInterruptCatch` - Establishes an interrupt service + routine. + +* :ref:`InterfaceRtemsInterruptDisable` - Disables the maskable interrupts on + the current processor. + +* :ref:`InterfaceRtemsInterruptEnable` - Restores the previous interrupt level + on the current processor. + +* :ref:`InterfaceRtemsInterruptFlash` - Flashes interrupts on the current + processor. + +* :ref:`InterfaceRtemsInterruptLocalDisable` - Disables the maskable interrupts + on the current processor. + +* :ref:`InterfaceRtemsInterruptLocalEnable` - Restores the previous interrupt + level on the current processor. + +* :ref:`InterfaceRtemsInterruptIsInProgress` - Checks if an ISR is in progress + on the current processor. + +* :ref:`InterfaceRtemsInterruptLockInitialize` - Initializes the ISR lock. + +* :ref:`InterfaceRtemsInterruptLockDestroy` - Destroys the ISR lock. + +* :ref:`InterfaceRtemsInterruptLockAcquire` - Acquires the ISR lock. + +* :ref:`InterfaceRtemsInterruptLockRelease` - Releases the ISR lock. + +* :ref:`InterfaceRtemsInterruptLockAcquireIsr` - Acquires the ISR lock from + within an ISR. + +* :ref:`InterfaceRtemsInterruptLockReleaseIsr` - Releases the ISR lock from + within an ISR. + +* :ref:`InterfaceRtemsInterruptLockInterruptDisable` - Disables maskable + interrupts on the current processor. + +* :ref:`InterfaceRTEMSINTERRUPTLOCKDECLARE` - Declares an ISR lock object. + +* :ref:`InterfaceRTEMSINTERRUPTLOCKDEFINE` - Defines an ISR lock object. + +* :ref:`InterfaceRTEMSINTERRUPTLOCKINITIALIZER` - Statically initializes an ISR + lock object. + +* :ref:`InterfaceRTEMSINTERRUPTLOCKMEMBER` - Defines an ISR lock member. + +* :ref:`InterfaceRTEMSINTERRUPTLOCKREFERENCE` - Defines an ISR lock object + reference. + +* :ref:`InterfaceRTEMSINTERRUPTENTRYINITIALIZER` - Statically initializes an + interrupt entry object. + +* :ref:`InterfaceRtemsInterruptEntryInitialize` - Initializes the interrupt + entry. + +* :ref:`InterfaceRtemsInterruptEntryInstall` - Installs the interrupt entry at + the interrupt vector. + +* :ref:`InterfaceRtemsInterruptEntryRemove` - Removes the interrupt entry from + the interrupt vector. + +* :ref:`InterfaceRtemsInterruptHandlerInstall` - Installs the interrupt handler + routine and argument at the interrupt vector. + +* :ref:`InterfaceRtemsInterruptHandlerRemove` - Removes the interrupt handler + routine and argument from the interrupt vector. + +* :ref:`InterfaceRtemsInterruptVectorIsEnabled` - Checks if the interrupt + vector is enabled. + +* :ref:`InterfaceRtemsInterruptVectorEnable` - Enables the interrupt vector. + +* :ref:`InterfaceRtemsInterruptVectorDisable` - Disables the interrupt vector. + +* :ref:`InterfaceRtemsInterruptIsPending` - Checks if the interrupt is pending. + +* :ref:`InterfaceRtemsInterruptRaise` - Raises the interrupt vector. + +* :ref:`InterfaceRtemsInterruptRaiseOn` - Raises the interrupt vector on the + processor. + +* :ref:`InterfaceRtemsInterruptClear` - Clears the interrupt vector. + +* :ref:`InterfaceRtemsInterruptGetAffinity` - Gets the processor affinity set + of the interrupt vector. + +* :ref:`InterfaceRtemsInterruptSetAffinity` - Sets the processor affinity set + of the interrupt vector. + +* :ref:`InterfaceRtemsInterruptGetAttributes` - Gets the attributes of the + interrupt vector. + +* :ref:`InterfaceRtemsInterruptHandlerIterate` - Iterates over all interrupt + handler installed at the interrupt vector. + +* :ref:`InterfaceRtemsInterruptServerInitialize` - Initializes the interrupt + server tasks. + +* :ref:`InterfaceRtemsInterruptServerCreate` - Creates an interrupt server. + +* :ref:`InterfaceRtemsInterruptServerHandlerInstall` - Installs the interrupt + handler routine and argument at the interrupt vector on the interrupt server. + +* :ref:`InterfaceRtemsInterruptServerHandlerRemove` - Removes the interrupt + handler routine and argument from the interrupt vector and the interrupt + server. + +* :ref:`InterfaceRtemsInterruptServerSetAffinity` - Sets the processor affinity + of the interrupt server. + +* :ref:`InterfaceRtemsInterruptServerDelete` - Deletes the interrupt server. + +* :ref:`InterfaceRtemsInterruptServerSuspend` - Suspends the interrupt server. + +* :ref:`InterfaceRtemsInterruptServerResume` - Resumes the interrupt server. + +* :ref:`InterfaceRtemsInterruptServerMove` - Moves the interrupt handlers + installed at the interrupt vector and the source interrupt server to the + destination interrupt server. + +* :ref:`InterfaceRtemsInterruptServerHandlerIterate` - Iterates over all + interrupt handler installed at the interrupt vector and interrupt server. + +* :ref:`InterfaceRtemsInterruptServerEntryInitialize` - Initializes the + interrupt server entry. + +* :ref:`InterfaceRtemsInterruptServerActionPrepend` - Prepends the interrupt + server action to the list of actions of the interrupt server entry. + +* :ref:`InterfaceRtemsInterruptServerEntryDestroy` - Destroys the interrupt + server entry. + +* :ref:`InterfaceRtemsInterruptServerEntrySubmit` - Submits the interrupt + server entry to be serviced by the interrupt server. + +* :ref:`InterfaceRtemsInterruptServerEntryMove` - Moves the interrupt server + entry to the interrupt server. + +* :ref:`InterfaceRtemsInterruptServerRequestInitialize` - Initializes the + interrupt server request. + +* :ref:`InterfaceRtemsInterruptServerRequestSetVector` - Sets the interrupt + vector in the interrupt server request. + +* :ref:`InterfaceRtemsInterruptServerRequestDestroy` - Destroys the interrupt + server request. + +* :ref:`InterfaceRtemsInterruptServerRequestSubmit` - Submits the interrupt + server request to be serviced by the interrupt server. diff --git a/c-user/interrupt/operations.rst b/c-user/interrupt/operations.rst new file mode 100644 index 0000000..67988c3 --- /dev/null +++ b/c-user/interrupt/operations.rst @@ -0,0 +1,112 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Operations +========== + +Establishing an ISR +------------------- + +The ``rtems_interrupt_catch`` directive establishes an ISR for the system. The +address of the ISR and its associated CPU vector number are specified to this +directive. This directive installs the RTEMS interrupt wrapper in the +processor's Interrupt Vector Table and the address of the user's ISR in the +RTEMS' Vector Table. This directive returns the previous contents of the +specified vector in the RTEMS' Vector Table. + +Directives Allowed from an ISR +------------------------------ + +Using the interrupt manager ensures that RTEMS knows when a directive is being +called from an ISR. The ISR may then use system calls to synchronize itself +with an application task. The synchronization may involve messages, events or +signals being passed by the ISR to the desired task. Directives invoked by an +ISR must operate only on objects which reside on the local node. The following +is a list of RTEMS system calls that may be made from an ISR: + +- Task Management + Although it is acceptable to operate on the RTEMS_SELF task (e.g. the + currently executing task), while in an ISR, this will refer to the + interrupted task. Most of the time, it is an application implementation + error to use RTEMS_SELF from an ISR. + + - rtems_task_suspend + - rtems_task_resume + +- Interrupt Management + + - rtems_interrupt_enable + - rtems_interrupt_disable + - rtems_interrupt_flash + - rtems_interrupt_lock_acquire + - rtems_interrupt_lock_release + - rtems_interrupt_lock_acquire_isr + - rtems_interrupt_lock_release_isr + - rtems_interrupt_is_in_progress + - rtems_interrupt_catch + +- Clock Management + + - rtems_clock_set + - rtems_clock_get_tod + - rtems_clock_get_tod_timeval + - rtems_clock_get_seconds_since_epoch + - rtems_clock_get_ticks_per_second + - rtems_clock_get_ticks_since_boot + - rtems_clock_get_uptime + +- Timer Management + + - rtems_timer_cancel + - rtems_timer_reset + - rtems_timer_fire_after + - rtems_timer_fire_when + - rtems_timer_server_fire_after + - rtems_timer_server_fire_when + +- Event Management + + - rtems_event_send + - rtems_event_system_send + - rtems_event_transient_send + +- Semaphore Management + + - rtems_semaphore_release + +- Message Management + + - rtems_message_queue_broadcast + - rtems_message_queue_send + - rtems_message_queue_urgent + +- Signal Management + + - rtems_signal_send + +- Dual-Ported Memory Management + + - rtems_port_external_to_internal + - rtems_port_internal_to_external + +- IO Management + The following services are safe to call from an ISR if and only if + the device driver service invoked is also safe. The IO Manager itself + is safe but the invoked driver entry point may or may not be. + + - rtems_io_initialize + - rtems_io_open + - rtems_io_close + - rtems_io_read + - rtems_io_write + - rtems_io_control + +- Fatal Error Management + + - rtems_fatal + - rtems_fatal_error_occurred + +- Multiprocessing + + - rtems_multiprocessing_announce diff --git a/c-user/interrupt_manager.rst b/c-user/interrupt_manager.rst deleted file mode 100644 index 5eb7270..0000000 --- a/c-user/interrupt_manager.rst +++ /dev/null @@ -1,772 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-4.0 - -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) - -.. index:: interrupts - -Interrupt Manager -***************** - -Introduction -============ - -Any real-time executive must provide a mechanism for quick response to -externally generated interrupts to satisfy the critical time constraints of the -application. The interrupt manager provides this mechanism for RTEMS. This -manager permits quick interrupt response times by providing the critical -ability to alter task execution which allows a task to be preempted upon exit -from an ISR. The interrupt manager includes the following directive: - -- rtems_interrupt_catch_ - Establish an ISR - -- rtems_interrupt_disable_ - Disable Interrupts - -- rtems_interrupt_enable_ - Restore Interrupt Level - -- rtems_interrupt_flash_ - Flash Interrupt - -- rtems_interrupt_local_disable_ - Disable Interrupts on Current Processor - -- rtems_interrupt_local_enable_ - Restore Interrupt Level on Current Processor - -- rtems_interrupt_lock_initialize_ - Initialize an ISR Lock - -- rtems_interrupt_lock_acquire_ - Acquire an ISR Lock - -- rtems_interrupt_lock_release_ - Release an ISR Lock - -- rtems_interrupt_lock_acquire_isr_ - Acquire an ISR Lock from ISR - -- rtems_interrupt_lock_release_isr_ - Release an ISR Lock from ISR - -- rtems_interrupt_is_in_progress_ - Is an ISR in Progress - -Background -========== - -.. index:: interrupt processing - -Processing an Interrupt ------------------------ - -The interrupt manager allows the application to connect a function to a -hardware interrupt vector. When an interrupt occurs, the processor will -automatically vector to RTEMS. RTEMS saves and restores all registers which -are not preserved by the normal C calling convention for the target processor -and invokes the user's ISR. The user's ISR is responsible for processing the -interrupt, clearing the interrupt if necessary, and device specific -manipulation. - -.. index:: rtems_vector_number - -The ``rtems_interrupt_catch`` directive connects a procedure to an interrupt -vector. The vector number is managed using the ``rtems_vector_number`` data -type. - -The interrupt service routine is assumed to abide by these conventions and have -a prototype similar to the following: - -.. index:: rtems_isr - -.. code-block:: c - - rtems_isr user_isr( - rtems_vector_number vector - ); - -The vector number argument is provided by RTEMS to allow the application to -identify the interrupt source. This could be used to allow a single routine to -service interrupts from multiple instances of the same device. For example, a -single routine could service interrupts from multiple serial ports and use the -vector number to identify which port requires servicing. - -To minimize the masking of lower or equal priority level interrupts, the ISR -should perform the minimum actions required to service the interrupt. Other -non-essential actions should be handled by application tasks. Once the user's -ISR has completed, it returns control to the RTEMS interrupt manager which will -perform task dispatching and restore the registers saved before the ISR was -invoked. - -The RTEMS interrupt manager guarantees that proper task scheduling and -dispatching are performed at the conclusion of an ISR. A system call made by -the ISR may have readied a task of higher priority than the interrupted task. -Therefore, when the ISR completes, the postponed dispatch processing must be -performed. No dispatch processing is performed as part of directives which -have been invoked by an ISR. - -Applications must adhere to the following rule if proper task scheduling and -dispatching is to be performed: - -.. note:: - - The interrupt manager must be used for all ISRs which may be interrupted by - the highest priority ISR which invokes an RTEMS directive. - -Consider a processor which allows a numerically low interrupt level to -interrupt a numerically greater interrupt level. In this example, if an RTEMS -directive is used in a level 4 ISR, then all ISRs which execute at levels 0 -through 4 must use the interrupt manager. - -Interrupts are nested whenever an interrupt occurs during the execution of -another ISR. RTEMS supports efficient interrupt nesting by allowing the nested -ISRs to terminate without performing any dispatch processing. Only when the -outermost ISR terminates will the postponed dispatching occur. - -.. index:: interrupt levels - -RTEMS Interrupt Levels ----------------------- - -Many processors support multiple interrupt levels or priorities. The exact -number of interrupt levels is processor dependent. RTEMS internally supports -256 interrupt levels which are mapped to the processor's interrupt levels. For -specific information on the mapping between RTEMS and the target processor's -interrupt levels, refer to the Interrupt Processing chapter of the Applications -Supplement document for a specific target processor. - -.. index:: disabling interrupts - -Disabling of Interrupts by RTEMS --------------------------------- - -During the execution of directive calls, critical sections of code may be -executed. When these sections are encountered, RTEMS disables all maskable -interrupts before the execution of the section and restores them to the -previous level upon completion of the section. RTEMS has been optimized to -ensure that interrupts are disabled for a minimum length of time. The maximum -length of time interrupts are disabled by RTEMS is processor dependent and is -detailed in the Timing Specification chapter of the Applications Supplement -document for a specific target processor. - -Non-maskable interrupts (NMI) cannot be disabled, and ISRs which execute at -this level MUST NEVER issue RTEMS system calls. If a directive is invoked, -unpredictable results may occur due to the inability of RTEMS to protect its -critical sections. However, ISRs that make no system calls may safely execute -as non-maskable interrupts. - -Operations -========== - -Establishing an ISR -------------------- - -The ``rtems_interrupt_catch`` directive establishes an ISR for the system. The -address of the ISR and its associated CPU vector number are specified to this -directive. This directive installs the RTEMS interrupt wrapper in the -processor's Interrupt Vector Table and the address of the user's ISR in the -RTEMS' Vector Table. This directive returns the previous contents of the -specified vector in the RTEMS' Vector Table. - -Directives Allowed from an ISR ------------------------------- - -Using the interrupt manager ensures that RTEMS knows when a directive is being -called from an ISR. The ISR may then use system calls to synchronize itself -with an application task. The synchronization may involve messages, events or -signals being passed by the ISR to the desired task. Directives invoked by an -ISR must operate only on objects which reside on the local node. The following -is a list of RTEMS system calls that may be made from an ISR: - -- Task Management - Although it is acceptable to operate on the RTEMS_SELF task (e.g. the - currently executing task), while in an ISR, this will refer to the - interrupted task. Most of the time, it is an application implementation - error to use RTEMS_SELF from an ISR. - - - rtems_task_suspend - - rtems_task_resume - -- Interrupt Management - - - rtems_interrupt_enable - - rtems_interrupt_disable - - rtems_interrupt_flash - - rtems_interrupt_lock_acquire - - rtems_interrupt_lock_release - - rtems_interrupt_lock_acquire_isr - - rtems_interrupt_lock_release_isr - - rtems_interrupt_is_in_progress - - rtems_interrupt_catch - -- Clock Management - - - rtems_clock_set - - rtems_clock_get_tod - - rtems_clock_get_tod_timeval - - rtems_clock_get_seconds_since_epoch - - rtems_clock_get_ticks_per_second - - rtems_clock_get_ticks_since_boot - - rtems_clock_get_uptime - -- Timer Management - - - rtems_timer_cancel - - rtems_timer_reset - - rtems_timer_fire_after - - rtems_timer_fire_when - - rtems_timer_server_fire_after - - rtems_timer_server_fire_when - -- Event Management - - - rtems_event_send - - rtems_event_system_send - - rtems_event_transient_send - -- Semaphore Management - - - rtems_semaphore_release - -- Message Management - - - rtems_message_queue_broadcast - - rtems_message_queue_send - - rtems_message_queue_urgent - -- Signal Management - - - rtems_signal_send - -- Dual-Ported Memory Management - - - rtems_port_external_to_internal - - rtems_port_internal_to_external - -- IO Management - The following services are safe to call from an ISR if and only if - the device driver service invoked is also safe. The IO Manager itself - is safe but the invoked driver entry point may or may not be. - - - rtems_io_initialize - - rtems_io_open - - rtems_io_close - - rtems_io_read - - rtems_io_write - - rtems_io_control - -- Fatal Error Management - - - rtems_fatal - - rtems_fatal_error_occurred - -- Multiprocessing - - - rtems_multiprocessing_announce - -Directives -========== - -This section details the interrupt manager's directives. A subsection is -dedicated to each of this manager's directives and describes the calling -sequence, related constants, usage, and status codes. - -.. raw:: latex - - \clearpage - -.. index:: establish an ISR -.. index:: install an ISR -.. index:: rtems_interrupt_catch - -.. _rtems_interrupt_catch: - -INTERRUPT_CATCH - Establish an ISR ----------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_interrupt_catch( - rtems_isr_entry new_isr_handler, - rtems_vector_number vector, - rtems_isr_entry *old_isr_handler - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-wrap - - * - ``RTEMS_SUCCESSFUL`` - - ISR established successfully - * - ``RTEMS_INVALID_NUMBER`` - - illegal vector number - * - ``RTEMS_INVALID_ADDRESS`` - - illegal ISR entry point or invalid ``old_isr_handler`` - -DESCRIPTION: - This directive establishes an interrupt service routine (ISR) for the - specified interrupt vector number. The ``new_isr_handler`` parameter - specifies the entry point of the ISR. The entry point of the previous ISR - for the specified vector is returned in ``old_isr_handler``. - - To release an interrupt vector, pass the old handler's address obtained - when the vector was first capture. - -NOTES: - This directive will not cause the calling task to be preempted. - -.. raw:: latex - - \clearpage - -.. index:: disable interrupts -.. index:: rtems_interrupt_disable - -.. _rtems_interrupt_disable: - -INTERRUPT_DISABLE - Disable Interrupts --------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - void rtems_interrupt_disable( - rtems_interrupt_level level - ); - -DIRECTIVE STATUS CODES: - NONE - -DESCRIPTION: - This directive disables all maskable interrupts and returns the previous - interrupt level in ``level``. - -NOTES: - A later invocation of the ``rtems_interrupt_enable`` directive should be - used to restore the interrupt level. - - This directive is implemented as a macro which sets the ``level`` - parameter. - - This directive will not cause the calling task to be preempted. - - This directive is only available in uniprocessor configurations. The - directive ``rtems_interrupt_local_disable`` is available in all - configurations. - - .. code-block:: c - - void critical_section( void ) - { - rtems_interrupt_level level; - - /* - * Please note that the rtems_interrupt_disable() is a macro. The - * previous interrupt level (before the maskable interrupts are - * disabled) is returned here in the level macro parameter. This - * would be wrong: - * - * rtems_interrupt_disable( &level ); - */ - rtems_interrupt_disable( level ); - - /* Critical section, maskable interrupts are disabled */ - - { - rtems_interrupt_level level2; - - rtems_interrupt_disable( level2 ); - - /* Nested critical section */ - - rtems_interrupt_enable( level2 ); - } - - /* Maskable interrupts are still disabled */ - - rtems_interrupt_enable( level ); - } - -.. raw:: latex - - \clearpage - -.. index:: enable interrupts -.. index:: restore interrupt level -.. index:: rtems_interrupt_enable - -.. _rtems_interrupt_enable: - -INTERRUPT_ENABLE - Restore Interrupt Level ------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - void rtems_interrupt_enable( - rtems_interrupt_level level - ); - -DIRECTIVE STATUS CODES: - NONE - -DESCRIPTION: - This directive restores the interrupt level specified by ``level``. - -NOTES: - The ``level`` parameter value must be obtained by a previous call to - ``rtems_interrupt_disable`` or ``rtems_interrupt_flash``. Using an - otherwise obtained value is undefined behaviour. - - This directive is unsuitable to enable particular interrupt sources, for - example in an interrupt controller. - - This directive will not cause the calling task to be preempted. - - This directive is only available in uniprocessor configurations. The - directive ``rtems_interrupt_local_enable`` is available in all - configurations. - -.. raw:: latex - - \clearpage - -.. index:: flash interrupts -.. index:: rtems_interrupt_flash - -.. _rtems_interrupt_flash: - -INTERRUPT_FLASH - Flash Interrupts ----------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - void rtems_interrupt_flash( - rtems_interrupt_level level - ); - -DIRECTIVE STATUS CODES: - NONE - -DESCRIPTION: - This directive is functionally equivalent to a - ``rtems_interrupt_enable( level )`` immediately followed by a - ``rtems_interrupt_disable( level )``. On some - architectures it is possible to provide an optimized implementation for - this sequence. - -NOTES: - The ``level`` parameter value must be obtained by a previous call to - ``rtems_interrupt_disable`` or ``rtems_interrupt_flash``. Using an - otherwise obtained value is undefined behaviour. - - This directive will not cause the calling task to be preempted. - - This directive is only available in uniprocessor configurations. The - directives ``rtems_interrupt_local_disable`` and - ``rtems_interrupt_local_enable`` are available in all configurations. - - Historically, the interrupt flash directive was heavily used in the - operating system implementation. However, this is no longer the case. The - interrupt flash directive is provided for backward compatibility reasons. - -.. raw:: latex - - \clearpage - -.. index:: disable interrupts -.. index:: rtems_interrupt_local_disable - -.. _rtems_interrupt_local_disable: - -INTERRUPT_LOCAL_DISABLE - Disable Interrupts on Current Processor ------------------------------------------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - void rtems_interrupt_local_disable( - rtems_interrupt_level level - ); - -DIRECTIVE STATUS CODES: - NONE - -DESCRIPTION: - This directive disables all maskable interrupts on the current processor - and returns the previous interrupt level in ``level``. - -NOTES: - A later invocation of the ``rtems_interrupt_local_enable`` directive should - be used to restore the interrupt level. - - This directive is implemented as a macro which sets the ``level`` - parameter. - - This directive will not cause the calling task to be preempted. - - In SMP configurations, this will not ensure system wide mutual exclusion. - Use interrupt locks instead. - - .. code-block:: c - - void local_critical_section( void ) - { - rtems_interrupt_level level; - - /* - * Please note that the rtems_interrupt_local_disable() is a macro. - * The previous interrupt level (before the maskable interrupts are - * disabled) is returned here in the level macro parameter. This - * would be wrong: - * - * rtems_interrupt_local_disable( &level ); - */ - rtems_interrupt_local_disable( level ); - - /* - * Local critical section, maskable interrupts on the current - * processor are disabled. - */ - - { - rtems_interrupt_level level2; - - rtems_interrupt_local_disable( level2 ); - - /* Nested local critical section */ - - rtems_interrupt_local_enable( level2 ); - } - - /* Maskable interrupts are still disabled */ - - rtems_interrupt_local_enable( level ); - } - -.. raw:: latex - - \clearpage - -.. index:: enable interrupts -.. index:: restore interrupt level -.. index:: rtems_interrupt_local_enable - -.. _rtems_interrupt_local_enable: - -INTERRUPT_LOCAL_ENABLE - Restore Interrupt Level on Current Processor ---------------------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - void rtems_interrupt_local_enable( - rtems_interrupt_level level - ); - -DIRECTIVE STATUS CODES: - NONE - -DESCRIPTION: - This directive restores the interrupt level specified by ``level`` on the - current processor. - -NOTES: - The ``level`` parameter value must be obtained by a previous call to - ``rtems_interrupt_local_disable``. Using an otherwise obtained value is - undefined behaviour. - - This directive is unsuitable to enable particular interrupt sources, for - example in an interrupt controller. - - This directive will not cause the calling task to be preempted. - -.. raw:: latex - - \clearpage - -.. index:: rtems_interrupt_lock_initialize - -.. _rtems_interrupt_lock_initialize: - -INTERRUPT_LOCK_INITIALIZE - Initialize an ISR Lock --------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - void rtems_interrupt_lock_initialize( - rtems_interrupt_lock *lock, - const char *name - ); - -DIRECTIVE STATUS CODES: - NONE - -DESCRIPTION: - Initializes an interrupt lock. The name must be persistent throughout the - lifetime of the lock. - -NOTES: - Concurrent initialization leads to unpredictable results. - -.. raw:: latex - - \clearpage - -.. index:: rtems_interrupt_lock_acquire - -.. _rtems_interrupt_lock_acquire: - -INTERRUPT_LOCK_ACQUIRE - Acquire an ISR Lock --------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - void rtems_interrupt_lock_acquire( - rtems_interrupt_lock *lock, - rtems_interrupt_lock_context *lock_context - ); - -DIRECTIVE STATUS CODES: - NONE - -DESCRIPTION: - Maskable interrupts will be disabled. In SMP configurations, this - directive acquires an SMP lock. - -NOTES: - A separate lock context must be provided for each acquire/release pair, for - example an automatic variable. - - An attempt to recursively acquire the lock may result in an infinite loop - with maskable interrupts disabled. - - This directive will not cause the calling thread to be preempted. This - directive can be used in thread and interrupt context. - -.. raw:: latex - - \clearpage - -.. index:: rtems_interrupt_lock_release - -.. _rtems_interrupt_lock_release: - -INTERRUPT_LOCK_RELEASE - Release an ISR Lock --------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - void rtems_interrupt_lock_release( - rtems_interrupt_lock *lock, - rtems_interrupt_lock_context *lock_context - ); - -DIRECTIVE STATUS CODES: - NONE - -DESCRIPTION: - The interrupt level will be restored. In SMP configurations, this - directive releases an SMP lock. - -NOTES: - The lock context must be the one used to acquire the lock, otherwise the - result is unpredictable. - - This directive will not cause the calling thread to be preempted. This - directive can be used in thread and interrupt context. - -.. raw:: latex - - \clearpage - -.. index:: rtems_interrupt_lock_acquire_isr - -.. _rtems_interrupt_lock_acquire_isr: - -INTERRUPT_LOCK_ACQUIRE_ISR - Acquire an ISR Lock from ISR ---------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - void rtems_interrupt_lock_acquire_isr( - rtems_interrupt_lock *lock, - rtems_interrupt_lock_context *lock_context - ); - -DIRECTIVE STATUS CODES: - NONE - -DESCRIPTION: - The interrupt level will remain unchanged. In SMP configurations, this - directive acquires an SMP lock. - -NOTES: - A separate lock context must be provided for each acquire/release pair, for - example an automatic variable. - - An attempt to recursively acquire the lock may result in an infinite loop. - - This directive is intended for device drivers and should be called from the - corresponding interrupt service routine. - - In case the corresponding interrupt service routine can be interrupted by - higher priority interrupts and these interrupts enter the critical section - protected by this lock, then the result is unpredictable. - -.. raw:: latex - - \clearpage - -.. index:: rtems_interrupt_lock_release_isr - -.. _rtems_interrupt_lock_release_isr: - -INTERRUPT_LOCK_RELEASE_ISR - Release an ISR Lock from ISR ---------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - void rtems_interrupt_lock_release_isr( - rtems_interrupt_lock *lock, - rtems_interrupt_lock_context *lock_context - ); - -DIRECTIVE STATUS CODES: - NONE - -DESCRIPTION: - The interrupt level will remain unchanged. In SMP configurations, this - directive releases an SMP lock. - -NOTES: - The lock context must be the one used to acquire the lock, otherwise the - result is unpredictable. - - This directive is intended for device drivers and should be called from the - corresponding interrupt service routine. - -.. raw:: latex - - \clearpage - -.. index:: is interrupt in progress -.. index:: rtems_interrupt_is_in_progress - -.. _rtems_interrupt_is_in_progress: - -INTERRUPT_IS_IN_PROGRESS - Is an ISR in Progress ------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - bool rtems_interrupt_is_in_progress( void ); - -DIRECTIVE STATUS CODES: - NONE - -DESCRIPTION: - This directive returns ``TRUE`` if the processor is currently servicing an - interrupt and ``FALSE`` otherwise. A return value of ``TRUE`` indicates - that the caller is an interrupt service routine, *NOT* a task. The - directives available to an interrupt service routine are restricted. - -NOTES: - This directive will not cause the calling task to be preempted. diff --git a/c-user/io/background.rst b/c-user/io/background.rst new file mode 100644 index 0000000..28e5369 --- /dev/null +++ b/c-user/io/background.rst @@ -0,0 +1,162 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Background +========== + +.. index:: Device Driver Table + +Device Driver Table +------------------- + +Each application utilizing the RTEMS I/O manager must specify the address of a +Device Driver Table in its Configuration Table. This table contains each device +driver's entry points that is to be initialised by RTEMS during initialization. +Each device driver may contain the following entry points: + +- Initialization + +- Open + +- Close + +- Read + +- Write + +- Control + +If the device driver does not support a particular entry point, then that entry +in the Configuration Table should be NULL. RTEMS will return +``RTEMS_SUCCESSFUL`` as the executive's and zero (0) as the device driver's +return code for these device driver entry points. + +Applications can register and unregister drivers with the RTEMS I/O manager +avoiding the need to have all drivers statically defined and linked into this +table. + +The :file:`confdefs.h` entry ``CONFIGURE_MAXIMUM_DRIVERS`` configures the +number of driver slots available to the application. + +.. index:: major device number +.. index:: minor device number + +Major and Minor Device Numbers +------------------------------ + +Each call to the I/O manager must provide a device's major and minor numbers as +arguments. The major number is the index of the requested driver's entry +points in the Device Driver Table, and is used to select a specific device +driver. The exact usage of the minor number is driver specific, but is +commonly used to distinguish between a number of devices controlled by the same +driver. + +.. index:: rtems_device_major_number +.. index:: rtems_device_minor_number + +The data types ``rtems_device_major_number`` and ``rtems_device_minor_number`` +are used to manipulate device major and minor numbers, respectively. + +.. index:: device names + +Device Names +------------ + +The I/O Manager provides facilities to associate a name with a particular +device. Directives are provided to register the name of a device and to look +up the major/minor number pair associated with a device name. + +Device Driver Environment +------------------------- + +Application developers, as well as device driver developers, must be aware of +the following regarding the RTEMS I/O Manager: + +- A device driver routine executes in the context of the invoking task. Thus + if the driver blocks, the invoking task blocks. + +- The device driver is free to change the modes of the invoking task, although + the driver should restore them to their original values. + +- Device drivers may be invoked from ISRs. + +- Only local device drivers are accessible through the I/O manager. + +- A device driver routine may invoke all other RTEMS directives, including I/O + directives, on both local and global objects. + +Although the RTEMS I/O manager provides a framework for device drivers, it +makes no assumptions regarding the construction or operation of a device +driver. + +.. index:: runtime driver registration + +Runtime Driver Registration +--------------------------- + +Board support package and application developers can select wether a device +driver is statically entered into the default device table or registered at +runtime. + +Dynamic registration helps applications where: + +- The BSP and kernel libraries are common to a range of applications for a + specific target platform. An application may be built upon a common library + with all drivers. The application selects and registers the drivers. Uniform + driver name lookup protects the application. + +- The type and range of drivers may vary as the application probes a bus during + initialization. + +- Support for hot swap bus system such as Compact PCI. + +- Support for runtime loadable driver modules. + +.. index:: device driver interface + +Device Driver Interface +----------------------- + +When an application invokes an I/O manager directive, RTEMS determines which +device driver entry point must be invoked. The information passed by the +application to RTEMS is then passed to the correct device driver entry point. +RTEMS will invoke each device driver entry point assuming it is compatible with +the following prototype: + +.. code-block:: c + + rtems_device_driver io_entry( + rtems_device_major_number major, + rtems_device_minor_number minor, + void *argument_block + ); + +The format and contents of the parameter block are device driver and entry +point dependent. + +It is recommended that a device driver avoid generating error codes which +conflict with those used by application components. A common technique used to +generate driver specific error codes is to make the most significant part of +the status indicate a driver specific code. + +Device Driver Initialization +---------------------------- + +RTEMS automatically initializes all device drivers when multitasking is +initiated via the ``rtems_initialize_executive`` directive. RTEMS initializes +the device drivers by invoking each device driver initialization entry point +with the following parameters: + +``major`` + the major device number for this device driver. + +``minor`` + zero. + +``argument_block`` + will point to the Configuration Table. + +The returned status will be ignored by RTEMS. If the driver cannot +successfully initialize the device, then it should invoke the +fatal_error_occurred directive. diff --git a/c-user/io/directives.rst b/c-user/io/directives.rst new file mode 100644 index 0000000..7def56a --- /dev/null +++ b/c-user/io/directives.rst @@ -0,0 +1,553 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. _IOManagerDirectives: + +Directives +========== + +This section details the directives of the I/O Manager. A subsection is +dedicated to each of this manager's directives and lists the calling sequence, +parameters, description, return values, and notes of the directive. + +.. Generated from spec:/rtems/io/if/register-driver + +.. raw:: latex + + \clearpage + +.. index:: rtems_io_register_driver() +.. index:: register a device driver + +.. _InterfaceRtemsIoRegisterDriver: + +rtems_io_register_driver() +-------------------------- + +Registers and initializes the device with the specified device driver address +table and device major number in the Device Driver Table. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_io_register_driver( + rtems_device_major_number major, + const rtems_driver_address_table *driver_table, + rtems_device_major_number *registered_major + ); + +.. rubric:: PARAMETERS: + +``major`` + This parameter is the device major number. Use a value of zero to let the + system obtain a device major number automatically. + +``driver_table`` + This parameter is the device driver address table. + +``registered_major`` + This parameter is the pointer to an :ref:`InterfaceRtemsDeviceMajorNumber` + object. When the directive call is successful, the device major number of + the registered device will be stored in this object. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The device major number of the device was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The device driver address table was empty. + +:c:macro:`RTEMS_INVALID_NUMBER` + The device major number of the device was out of range, see + :ref:`CONFIGURE_MAXIMUM_DRIVERS`. + +:c:macro:`RTEMS_TOO_MANY` + The system was unable to obtain a device major number. + +:c:macro:`RTEMS_RESOURCE_IN_USE` + The device major number was already in use. + +:c:macro:`RTEMS_CALLED_FROM_ISR` + The directive was called from interrupt context. + +Other status codes may be returned by :ref:`InterfaceRtemsIoInitialize`. + +.. rubric:: NOTES: + +If the device major number equals zero a device major number will be obtained. +The device major number of the registered driver will be returned. + +After a successful registration, the :ref:`InterfaceRtemsIoInitialize` +directive will be called to initialize the device. + +.. Generated from spec:/rtems/io/if/unregister-driver + +.. raw:: latex + + \clearpage + +.. index:: rtems_io_unregister_driver() +.. index:: unregister a device driver + +.. _InterfaceRtemsIoUnregisterDriver: + +rtems_io_unregister_driver() +---------------------------- + +Removes a device driver specified by the device major number from the Device +Driver Table. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_io_unregister_driver( + rtems_device_major_number major + ); + +.. rubric:: PARAMETERS: + +``major`` + This parameter is the major number of the device. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_UNSATISFIED` + The device major number was invalid. + +:c:macro:`RTEMS_CALLED_FROM_ISR` + The directive was called from interrupt context. + +.. rubric:: NOTES: + +Currently no specific checks are made and the driver is not closed. + +.. Generated from spec:/rtems/io/if/initialize + +.. raw:: latex + + \clearpage + +.. index:: rtems_io_initialize() +.. index:: initialize a device driver + +.. _InterfaceRtemsIoInitialize: + +rtems_io_initialize() +--------------------- + +Initializes the device specified by the device major and minor numbers. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_io_initialize( + rtems_device_major_number major, + rtems_device_minor_number minor, + void *argument + ); + +.. rubric:: PARAMETERS: + +``major`` + This parameter is the major number of the device. + +``minor`` + This parameter is the minor number of the device. + +``argument`` + This parameter is the argument passed to the device driver initialization + entry. + +.. rubric:: DESCRIPTION: + +This directive calls the device driver initialization entry registered in the +Device Driver Table for the specified device major number. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_NUMBER` + The device major number was invalid. + +Other status codes may be returned by the device driver initialization entry. + +.. rubric:: NOTES: + +This directive is automatically invoked for each device driver defined by the +application configuration during the system initialization and via the +:ref:`InterfaceRtemsIoRegisterDriver` directive. + +A device driver initialization entry is responsible for initializing all +hardware and data structures associated with a device. If necessary, it can +allocate memory to be used during other operations. + +.. Generated from spec:/rtems/io/if/register-name + +.. raw:: latex + + \clearpage + +.. index:: rtems_io_register_name() +.. index:: register a device in the file system + +.. _InterfaceRtemsIoRegisterName: + +rtems_io_register_name() +------------------------ + +Registers the device specified by the device major and minor numbers in the +file system under the specified name. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_io_register_name( + const char *device_name, + rtems_device_major_number major, + rtems_device_minor_number minor + ); + +.. rubric:: PARAMETERS: + +``device_name`` + This parameter is the device name in the file system. + +``major`` + This parameter is the device major number. + +``minor`` + This parameter is the device minor number. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_TOO_MANY` + The name was already in use or other errors occurred. + +.. rubric:: NOTES: + +The device is registered as a character device. + +.. Generated from spec:/rtems/io/if/open + +.. raw:: latex + + \clearpage + +.. index:: rtems_io_open() +.. index:: open a device + +.. _InterfaceRtemsIoOpen: + +rtems_io_open() +--------------- + +Opens the device specified by the device major and minor numbers. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_io_open( + rtems_device_major_number major, + rtems_device_minor_number minor, + void *argument + ); + +.. rubric:: PARAMETERS: + +``major`` + This parameter is the major number of the device. + +``minor`` + This parameter is the minor number of the device. + +``argument`` + This parameter is the argument passed to the device driver close entry. + +.. rubric:: DESCRIPTION: + +This directive calls the device driver open entry registered in the Device +Driver Table for the specified device major number. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_NUMBER` + The device major number was invalid. + +Other status codes may be returned by the device driver open entry. + +.. rubric:: NOTES: + +The open entry point is commonly used by device drivers to provide exclusive +access to a device. + +.. Generated from spec:/rtems/io/if/close + +.. raw:: latex + + \clearpage + +.. index:: rtems_io_close() +.. index:: close a device + +.. _InterfaceRtemsIoClose: + +rtems_io_close() +---------------- + +Closes the device specified by the device major and minor numbers. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_io_close( + rtems_device_major_number major, + rtems_device_minor_number minor, + void *argument + ); + +.. rubric:: PARAMETERS: + +``major`` + This parameter is the major number of the device. + +``minor`` + This parameter is the minor number of the device. + +``argument`` + This parameter is the argument passed to the device driver close entry. + +.. rubric:: DESCRIPTION: + +This directive calls the device driver close entry registered in the Device +Driver Table for the specified device major number. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_NUMBER` + The device major number was invalid. + +Other status codes may be returned by the device driver close entry. + +.. rubric:: NOTES: + +The close entry point is commonly used by device drivers to relinquish +exclusive access to a device. + +.. Generated from spec:/rtems/io/if/read + +.. raw:: latex + + \clearpage + +.. index:: rtems_io_read() +.. index:: read from a device + +.. _InterfaceRtemsIoRead: + +rtems_io_read() +--------------- + +Reads from the device specified by the device major and minor numbers. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_io_read( + rtems_device_major_number major, + rtems_device_minor_number minor, + void *argument + ); + +.. rubric:: PARAMETERS: + +``major`` + This parameter is the major number of the device. + +``minor`` + This parameter is the minor number of the device. + +``argument`` + This parameter is the argument passed to the device driver read entry. + +.. rubric:: DESCRIPTION: + +This directive calls the device driver read entry registered in the Device +Driver Table for the specified device major number. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_NUMBER` + The device major number was invalid. + +Other status codes may be returned by the device driver read entry. + +.. rubric:: NOTES: + +Read operations typically require a buffer address as part of the argument +parameter block. The contents of this buffer will be replaced with data from +the device. + +.. Generated from spec:/rtems/io/if/write + +.. raw:: latex + + \clearpage + +.. index:: rtems_io_write() +.. index:: write to a device + +.. _InterfaceRtemsIoWrite: + +rtems_io_write() +---------------- + +Writes to the device specified by the device major and minor numbers. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_io_write( + rtems_device_major_number major, + rtems_device_minor_number minor, + void *argument + ); + +.. rubric:: PARAMETERS: + +``major`` + This parameter is the major number of the device. + +``minor`` + This parameter is the minor number of the device. + +``argument`` + This parameter is the argument passed to the device driver write entry. + +.. rubric:: DESCRIPTION: + +This directive calls the device driver write entry registered in the Device +Driver Table for the specified device major number. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_NUMBER` + The device major number was invalid. + +Other status codes may be returned by the device driver write entry. + +.. rubric:: NOTES: + +Write operations typically require a buffer address as part of the argument +parameter block. The contents of this buffer will be sent to the device. + +.. Generated from spec:/rtems/io/if/control + +.. raw:: latex + + \clearpage + +.. index:: rtems_io_control() +.. index:: IO control +.. index:: special device services + +.. _InterfaceRtemsIoControl: + +rtems_io_control() +------------------ + +Controls the device specified by the device major and minor numbers. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_io_control( + rtems_device_major_number major, + rtems_device_minor_number minor, + void *argument + ); + +.. rubric:: PARAMETERS: + +``major`` + This parameter is the major number of the device. + +``minor`` + This parameter is the minor number of the device. + +``argument`` + This parameter is the argument passed to the device driver I/O control + entry. + +.. rubric:: DESCRIPTION: + +This directive calls the device driver I/O control entry registered in the +Device Driver Table for the specified device major number. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_NUMBER` + The device major number was invalid. + +Other status codes may be returned by the device driver I/O control entry. + +.. rubric:: NOTES: + +The exact functionality of the driver entry called by this directive is driver +dependent. It should not be assumed that the control entries of two device +drivers are compatible. For example, an RS-232 driver I/O control operation +may change the baud of a serial line, while an I/O control operation for a +floppy disk driver may cause a seek operation. diff --git a/c-user/io/index.rst b/c-user/io/index.rst new file mode 100644 index 0000000..b1147a9 --- /dev/null +++ b/c-user/io/index.rst @@ -0,0 +1,18 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 embedded brains GmbH & Co. KG + +.. index:: device drivers +.. index:: IO Manager + +.. _RTEMSAPIClassicIO: + +I/O Manager +*********** + +.. toctree:: + + introduction + background + operations + directives diff --git a/c-user/io/introduction.rst b/c-user/io/introduction.rst new file mode 100644 index 0000000..95a5942 --- /dev/null +++ b/c-user/io/introduction.rst @@ -0,0 +1,69 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/rtems/io/if/group + +.. _IOManagerIntroduction: + +Introduction +============ + +.. The following list was generated from: +.. spec:/rtems/io/if/register-driver +.. spec:/rtems/io/if/unregister-driver +.. spec:/rtems/io/if/initialize +.. spec:/rtems/io/if/register-name +.. spec:/rtems/io/if/open +.. spec:/rtems/io/if/close +.. spec:/rtems/io/if/read +.. spec:/rtems/io/if/write +.. spec:/rtems/io/if/control + +The Input/Output (I/O) Manager provides a well-defined mechanism for accessing +device drivers and a structured methodology for organizing device drivers. The +directives provided by the I/O Manager are: + +* :ref:`InterfaceRtemsIoRegisterDriver` - Registers and initializes the device + with the specified device driver address table and device major number in the + Device Driver Table. + +* :ref:`InterfaceRtemsIoUnregisterDriver` - Removes a device driver specified + by the device major number from the Device Driver Table. + +* :ref:`InterfaceRtemsIoInitialize` - Initializes the device specified by the + device major and minor numbers. + +* :ref:`InterfaceRtemsIoRegisterName` - Registers the device specified by the + device major and minor numbers in the file system under the specified name. + +* :ref:`InterfaceRtemsIoOpen` - Opens the device specified by the device major + and minor numbers. + +* :ref:`InterfaceRtemsIoClose` - Closes the device specified by the device + major and minor numbers. + +* :ref:`InterfaceRtemsIoRead` - Reads from the device specified by the device + major and minor numbers. + +* :ref:`InterfaceRtemsIoWrite` - Writes to the device specified by the device + major and minor numbers. + +* :ref:`InterfaceRtemsIoControl` - Controls the device specified by the device + major and minor numbers. diff --git a/c-user/io/operations.rst b/c-user/io/operations.rst new file mode 100644 index 0000000..ec0212d --- /dev/null +++ b/c-user/io/operations.rst @@ -0,0 +1,26 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Operations +========== + +Register and Lookup Name +------------------------ + +The ``rtems_io_register`` directive associates a name with the specified device +(i.e. major/minor number pair). Device names are typically registered as part +of the device driver initialization sequence. The ``rtems_io_lookup`` +directive is used to determine the major/minor number pair associated with the +specified device name. The use of these directives frees the application from +being dependent on the arbitrary assignment of major numbers in a particular +application. No device naming conventions are dictated by RTEMS. + +Accessing an Device Driver +-------------------------- + +The I/O manager provides directives which enable the application program to +utilize device drivers in a standard manner. There is a direct correlation +between the RTEMS I/O manager directives ``rtems_io_initialize``, +``rtems_io_open``, ``rtems_io_close``, ``rtems_io_read``, ``rtems_io_write``, +and ``rtems_io_control`` and the underlying device driver entry points. diff --git a/c-user/io_manager.rst b/c-user/io_manager.rst deleted file mode 100644 index 12282d7..0000000 --- a/c-user/io_manager.rst +++ /dev/null @@ -1,636 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-4.0 - -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) - -.. index:: device drivers -.. index:: IO Manager - -I/O Manager -*********** - -Introduction -============ - -The input/output interface manager provides a well-defined mechanism for -accessing device drivers and a structured methodology for organizing device -drivers. The directives provided by the I/O manager are: - -- rtems_io_initialize_ - Initialize a device driver - -- rtems_io_register_driver_ - Register a device driver - -- rtems_io_unregister_driver_ - Unregister a device driver - -- rtems_io_register_name_ - Register a device name - -- rtems_io_lookup_name_ - Look up a device name - -- rtems_io_open_ - Open a device - -- rtems_io_close_ - Close a device - -- rtems_io_read_ - Read from a device - -- rtems_io_write_ - Write to a device - -- rtems_io_control_ - Special device services - -Background -========== - -.. index:: Device Driver Table - -Device Driver Table -------------------- - -Each application utilizing the RTEMS I/O manager must specify the address of a -Device Driver Table in its Configuration Table. This table contains each device -driver's entry points that is to be initialised by RTEMS during initialization. -Each device driver may contain the following entry points: - -- Initialization - -- Open - -- Close - -- Read - -- Write - -- Control - -If the device driver does not support a particular entry point, then that entry -in the Configuration Table should be NULL. RTEMS will return -``RTEMS_SUCCESSFUL`` as the executive's and zero (0) as the device driver's -return code for these device driver entry points. - -Applications can register and unregister drivers with the RTEMS I/O manager -avoiding the need to have all drivers statically defined and linked into this -table. - -The :file:`confdefs.h` entry ``CONFIGURE_MAXIMUM_DRIVERS`` configures the -number of driver slots available to the application. - -.. index:: major device number -.. index:: minor device number - -Major and Minor Device Numbers ------------------------------- - -Each call to the I/O manager must provide a device's major and minor numbers as -arguments. The major number is the index of the requested driver's entry -points in the Device Driver Table, and is used to select a specific device -driver. The exact usage of the minor number is driver specific, but is -commonly used to distinguish between a number of devices controlled by the same -driver. - -.. index:: rtems_device_major_number -.. index:: rtems_device_minor_number - -The data types ``rtems_device_major_number`` and ``rtems_device_minor_number`` -are used to manipulate device major and minor numbers, respectively. - -.. index:: device names - -Device Names ------------- - -The I/O Manager provides facilities to associate a name with a particular -device. Directives are provided to register the name of a device and to look -up the major/minor number pair associated with a device name. - -Device Driver Environment -------------------------- - -Application developers, as well as device driver developers, must be aware of -the following regarding the RTEMS I/O Manager: - -- A device driver routine executes in the context of the invoking task. Thus - if the driver blocks, the invoking task blocks. - -- The device driver is free to change the modes of the invoking task, although - the driver should restore them to their original values. - -- Device drivers may be invoked from ISRs. - -- Only local device drivers are accessible through the I/O manager. - -- A device driver routine may invoke all other RTEMS directives, including I/O - directives, on both local and global objects. - -Although the RTEMS I/O manager provides a framework for device drivers, it -makes no assumptions regarding the construction or operation of a device -driver. - -.. index:: runtime driver registration - -Runtime Driver Registration ---------------------------- - -Board support package and application developers can select wether a device -driver is statically entered into the default device table or registered at -runtime. - -Dynamic registration helps applications where: - -- The BSP and kernel libraries are common to a range of applications for a - specific target platform. An application may be built upon a common library - with all drivers. The application selects and registers the drivers. Uniform - driver name lookup protects the application. - -- The type and range of drivers may vary as the application probes a bus during - initialization. - -- Support for hot swap bus system such as Compact PCI. - -- Support for runtime loadable driver modules. - -.. index:: device driver interface - -Device Driver Interface ------------------------ - -When an application invokes an I/O manager directive, RTEMS determines which -device driver entry point must be invoked. The information passed by the -application to RTEMS is then passed to the correct device driver entry point. -RTEMS will invoke each device driver entry point assuming it is compatible with -the following prototype: - -.. code-block:: c - - rtems_device_driver io_entry( - rtems_device_major_number major, - rtems_device_minor_number minor, - void *argument_block - ); - -The format and contents of the parameter block are device driver and entry -point dependent. - -It is recommended that a device driver avoid generating error codes which -conflict with those used by application components. A common technique used to -generate driver specific error codes is to make the most significant part of -the status indicate a driver specific code. - -Device Driver Initialization ----------------------------- - -RTEMS automatically initializes all device drivers when multitasking is -initiated via the ``rtems_initialize_executive`` directive. RTEMS initializes -the device drivers by invoking each device driver initialization entry point -with the following parameters: - -``major`` - the major device number for this device driver. - -``minor`` - zero. - -``argument_block`` - will point to the Configuration Table. - -The returned status will be ignored by RTEMS. If the driver cannot -successfully initialize the device, then it should invoke the -fatal_error_occurred directive. - -Operations -========== - -Register and Lookup Name ------------------------- - -The ``rtems_io_register`` directive associates a name with the specified device -(i.e. major/minor number pair). Device names are typically registered as part -of the device driver initialization sequence. The ``rtems_io_lookup`` -directive is used to determine the major/minor number pair associated with the -specified device name. The use of these directives frees the application from -being dependent on the arbitrary assignment of major numbers in a particular -application. No device naming conventions are dictated by RTEMS. - -Accessing an Device Driver --------------------------- - -The I/O manager provides directives which enable the application program to -utilize device drivers in a standard manner. There is a direct correlation -between the RTEMS I/O manager directives ``rtems_io_initialize``, -``rtems_io_open``, ``rtems_io_close``, ``rtems_io_read``, ``rtems_io_write``, -and ``rtems_io_control`` and the underlying device driver entry points. - -Directives -========== - -This section details the I/O manager's directives. A subsection is dedicated -to each of this manager's directives and describes the calling sequence, -related constants, usage, and status codes. - -.. raw:: latex - - \clearpage - -.. index:: register a device driver -.. index:: rtems_io_register_driver - -.. _rtems_io_register_driver: - -IO_REGISTER_DRIVER - Register a device driver ---------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_io_register_driver( - rtems_device_major_number major, - rtems_driver_address_table *driver_table, - rtems_device_major_number *registered_major - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - successfully registered - * - ``RTEMS_INVALID_ADDRESS`` - - invalid registered major pointer - * - ``RTEMS_INVALID_ADDRESS`` - - invalid driver table - * - ``RTEMS_INVALID_NUMBER`` - - invalid major device number - * - ``RTEMS_TOO_MANY`` - - no available major device table slot - * - ``RTEMS_RESOURCE_IN_USE`` - - major device number entry in use - -DESCRIPTION: - This directive attempts to add a new device driver to the Device Driver - Table. The user can specify a specific major device number via the - directive's ``major`` parameter, or let the registration routine find the - next available major device number by specifing a major number of - ``0``. The selected major device number is returned via the - ``registered_major`` directive parameter. The directive automatically - allocation major device numbers from the highest value down. - - This directive automatically invokes the ``IO_INITIALIZE`` directive if the - driver address table has an initialization and open entry. - - The directive returns ``RTEMS_TOO_MANY`` if Device Driver Table is full, - and ``RTEMS_RESOURCE_IN_USE`` if a specific major device number is - requested and it is already in use. - -NOTES: - The Device Driver Table size is specified in the Configuration Table - condiguration. This needs to be set to maximum size the application - requires. - -.. raw:: latex - - \clearpage - -.. index:: unregister a device driver -.. index:: rtems_io_unregister_driver - -.. _rtems_io_unregister_driver: - -IO_UNREGISTER_DRIVER - Unregister a device driver -------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_io_unregister_driver( - rtems_device_major_number major - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - successfully registered - * - ``RTEMS_INVALID_NUMBER`` - - invalid major device number - -DESCRIPTION: - This directive removes a device driver from the Device Driver Table. - -NOTES: - Currently no specific checks are made and the driver is not closed. - -.. raw:: latex - - \clearpage - -.. index:: initialize a device driver -.. index:: rtems_io_initialize - -.. _rtems_io_initialize: - -IO_INITIALIZE - Initialize a device driver ------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_io_initialize( - rtems_device_major_number major, - rtems_device_minor_number minor, - void *argument - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - successfully initialized - * - ``RTEMS_INVALID_NUMBER`` - - invalid major device number - -DESCRIPTION: - This directive calls the device driver initialization routine specified in - the Device Driver Table for this major number. This directive is - automatically invoked for each device driver when multitasking is initiated - via the initialize_executive directive. - - A device driver initialization module is responsible for initializing all - hardware and data structures associated with a device. If necessary, it can - allocate memory to be used during other operations. - -NOTES: - This directive may or may not cause the calling task to be preempted. This - is dependent on the device driver being initialized. - -.. raw:: latex - - \clearpage - -.. index:: register device -.. index:: rtems_io_register_name - -.. _rtems_io_register_name: - -IO_REGISTER_NAME - Register a device ------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_io_register_name( - const char *name, - rtems_device_major_number major, - rtems_device_minor_number minor - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - successfully initialized - * - ``RTEMS_TOO_MANY`` - - too many devices registered - -DESCRIPTION: - This directive associates name with the specified major/minor number pair. - -NOTES: - This directive will not cause the calling task to be preempted. - -.. raw:: latex - - \clearpage - -.. index:: lookup device major and minor number -.. index:: rtems_io_lookup_name - -.. _rtems_io_lookup_name: - -IO_LOOKUP_NAME - Lookup a device --------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_io_lookup_name( - const char *name, - rtems_driver_name_t *device_info - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - successfully initialized - * - ``RTEMS_UNSATISFIED`` - - name not registered - -DESCRIPTION: - This directive returns the major/minor number pair associated with the - given device name in ``device_info``. - -NOTES: - This directive will not cause the calling task to be preempted. - -.. raw:: latex - - \clearpage - -.. index:: open a devive -.. index:: rtems_io_open - -.. _rtems_io_open: - -IO_OPEN - Open a device ------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_io_open( - rtems_device_major_number major, - rtems_device_minor_number minor, - void *argument - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - successfully initialized - * - ``RTEMS_INVALID_NUMBER`` - - invalid major device number - -DESCRIPTION: - This directive calls the device driver open routine specified in the Device - Driver Table for this major number. The open entry point is commonly used - by device drivers to provide exclusive access to a device. - -NOTES: - This directive may or may not cause the calling task to be preempted. This - is dependent on the device driver being invoked. - -.. raw:: latex - - \clearpage - -.. index:: close a device -.. index:: rtems_io_close - -.. _rtems_io_close: - -IO_CLOSE - Close a device -------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_io_close( - rtems_device_major_number major, - rtems_device_minor_number minor, - void *argument - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - successfully initialized - * - ``RTEMS_INVALID_NUMBER`` - - invalid major device number - -DESCRIPTION: - This directive calls the device driver close routine specified in the - Device Driver Table for this major number. The close entry point is - commonly used by device drivers to relinquish exclusive access to a device. - -NOTES: - This directive may or may not cause the calling task to be preempted. This - is dependent on the device driver being invoked. - -.. raw:: latex - - \clearpage - -.. index:: read from a device -.. index:: rtems_io_read - -.. _rtems_io_read: - -IO_READ - Read from a device ----------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_io_read( - rtems_device_major_number major, - rtems_device_minor_number minor, - void *argument - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - successfully initialized - * - ``RTEMS_INVALID_NUMBER`` - - invalid major device number - -DESCRIPTION: - This directive calls the device driver read routine specified in the Device - Driver Table for this major number. Read operations typically require a - buffer address as part of the argument parameter block. The contents of - this buffer will be replaced with data from the device. - -NOTES: - This directive may or may not cause the calling task to be preempted. This - is dependent on the device driver being invoked. - -.. raw:: latex - - \clearpage - -.. index:: write to a device -.. index:: rtems_io_write - -.. _rtems_io_write: - -IO_WRITE - Write to a device ----------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_io_write( - rtems_device_major_number major, - rtems_device_minor_number minor, - void *argument - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - successfully initialized - * - ``RTEMS_INVALID_NUMBER`` - - invalid major device number - -DESCRIPTION: - This directive calls the device driver write routine specified in the - Device Driver Table for this major number. Write operations typically - require a buffer address as part of the argument parameter block. The - contents of this buffer will be sent to the device. - -NOTES: - This directive may or may not cause the calling task to be preempted. This - is dependent on the device driver being invoked. - -.. raw:: latex - - \clearpage - -.. index:: special device services -.. index:: IO Control -.. index:: rtems_io_control - -.. _rtems_io_control: - -IO_CONTROL - Special device services ------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_io_control( - rtems_device_major_number major, - rtems_device_minor_number minor, - void *argument - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - successfully initialized - * - ``RTEMS_INVALID_NUMBER`` - - invalid major device number - -DESCRIPTION: - This directive calls the device driver I/O control routine specified in the - Device Driver Table for this major number. The exact functionality of the - driver entry called by this directive is driver dependent. It should not - be assumed that the control entries of two device drivers are compatible. - For example, an RS-232 driver I/O control operation may change the baud - rate of a serial line, while an I/O control operation for a floppy disk - driver may cause a seek operation. - -NOTES: - This directive may or may not cause the calling task to be preempted. This - is dependent on the device driver being invoked. diff --git a/c-user/kernel-character-io/directives.rst b/c-user/kernel-character-io/directives.rst new file mode 100644 index 0000000..e0476fe --- /dev/null +++ b/c-user/kernel-character-io/directives.rst @@ -0,0 +1,372 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 2015 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. _KernelCharacterIOSupportDirectives: + +Directives +========== + +This section details the directives of the Kernel Character I/O Support. A +subsection is dedicated to each of this manager's directives and lists the +calling sequence, parameters, description, return values, and notes of the +directive. + +.. Generated from spec:/rtems/io/if/putc + +.. raw:: latex + + \clearpage + +.. index:: rtems_putc() + +.. _InterfaceRtemsPutc: + +rtems_putc() +------------ + +Outputs the character to the kernel character output device. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_putc( char c ); + +.. rubric:: PARAMETERS: + +``c`` + This parameter is the character to output. + +.. rubric:: DESCRIPTION: + +The directive outputs the character specified by ``c`` to the kernel character +output device using the polled character output implementation provided by +BSP_output_char. The directive performs a character translation from ``NL`` to +``CR`` followed by ``NR``. + +If the kernel character output device is concurrently accessed, then +interleaved output may occur. + +.. 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/io/if/put-char + +.. raw:: latex + + \clearpage + +.. index:: rtems_put_char() + +.. _InterfaceRtemsPutChar: + +rtems_put_char() +---------------- + +Puts the character using :ref:`InterfaceRtemsPutc` + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_put_char( int c, void *unused ); + +.. rubric:: PARAMETERS: + +``c`` + This parameter is the character to output. + +``unused`` + This parameter is an unused argument. + +.. rubric:: NOTES: + +The directive is provided to support the RTEMS Testing Framework. + +.. 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/io/if/putk + +.. raw:: latex + + \clearpage + +.. index:: putk() + +.. _InterfacePutk: + +putk() +------ + +Outputs the characters of the string and a newline character to the kernel +character output device. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + int putk( const char *s ); + +.. rubric:: PARAMETERS: + +``s`` + This parameter is the string to output. + +.. rubric:: RETURN VALUES: + +Returns the number of characters output to the kernel character output device. + +.. rubric:: NOTES: + +The directive may be used to print debug and test information. It uses +:ref:`InterfaceRtemsPutc` to output the characters. This directive performs a +character translation from ``NL`` to ``CR`` followed by ``NR``. + +If the kernel character output device is concurrently accessed, then +interleaved output may occur. + +.. 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/io/if/printk + +.. raw:: latex + + \clearpage + +.. index:: printk() + +.. _InterfacePrintk: + +printk() +-------- + +Outputs the characters defined by the format string and the arguments to the +kernel character output device. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + int printk( const char *fmt, ... ); + +.. rubric:: PARAMETERS: + +``fmt`` + This parameter is a printf()-style format string. + +``...`` + This parameter is a list of optional parameters required by the format + string. + +.. rubric:: RETURN VALUES: + +Returns the number of characters output to the kernel character output device. + +.. rubric:: NOTES: + +The directive may be used to print debug and test information. It uses +:ref:`InterfaceRtemsPutc` to output the characters. This directive performs a +character translation from ``NL`` to ``CR`` followed by ``NR``. + +If the kernel character output device is concurrently accessed, then +interleaved output may occur. + +.. 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. + +* Formatting of floating point numbers is not supported. + +.. Generated from spec:/rtems/io/if/vprintk + +.. raw:: latex + + \clearpage + +.. index:: vprintk() + +.. _InterfaceVprintk: + +vprintk() +--------- + +Outputs the characters defined by the format string and the variable argument +list to the kernel character output device. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + int vprintk( const char *fmt, va_list ap ); + +.. rubric:: PARAMETERS: + +``fmt`` + This parameter is a printf()-style format string. + +``ap`` + This parameter is the variable argument list required by the format string. + +.. rubric:: RETURN VALUES: + +Returns the number of characters output to the kernel character output device. + +.. rubric:: NOTES: + +The directive may be used to print debug and test information. It uses +:ref:`InterfaceRtemsPutc` to output the characters. This directive performs a +character translation from ``NL`` to ``CR`` followed by ``NR``. + +If the kernel character output device is concurrently accessed, then +interleaved output may occur. + +.. 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. + +* Formatting of floating point numbers is not supported. + +.. Generated from spec:/rtems/io/if/printk-printer + +.. raw:: latex + + \clearpage + +.. index:: rtems_printk_printer() + +.. _InterfaceRtemsPrintkPrinter: + +rtems_printk_printer() +---------------------- + +Outputs the characters defined by the format string and the variable argument +list to the kernel character output device. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + int rtems_printk_printer( void *unused, const char *fmt, va_list ap ); + +.. rubric:: PARAMETERS: + +``unused`` + This parameter is an unused argument. + +``fmt`` + This parameter is a printf()-style format string. + +``ap`` + This parameter is the variable argument list required by the format string. + +.. rubric:: RETURN VALUES: + +Returns the number of characters output to the kernel character output device. + +.. rubric:: NOTES: + +The directive may be used to print debug and test information. It uses +:ref:`InterfaceRtemsPutc` to output the characters. This directive performs a +character translation from ``NL`` to ``CR`` followed by ``NR``. + +If the kernel character output device is concurrently accessed, then +interleaved output may occur. + +.. 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. + +* Formatting of floating point numbers is not supported. + +.. Generated from spec:/rtems/io/if/getchark + +.. raw:: latex + + \clearpage + +.. index:: getchark() + +.. _InterfaceGetchark: + +getchark() +---------- + +Tries to dequeue a character from the kernel character input device. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + int getchark( void ); + +.. rubric:: DESCRIPTION: + +The directive tries to dequeue a character from the kernel character input +device using the polled character input implementation referenced by +BSP_poll_char if it is available. + +.. rubric:: RETURN VALUES: + +``-1`` + The BSP_poll_char pointer was equal to `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +``-1`` + There was no character enqueued on the kernel character input device. + +Returns the character least recently enqueued on the kernel character input +device as an unsigned character value. + +.. 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. diff --git a/c-user/kernel-character-io/index.rst b/c-user/kernel-character-io/index.rst new file mode 100644 index 0000000..2d1d13b --- /dev/null +++ b/c-user/kernel-character-io/index.rst @@ -0,0 +1,15 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2021 embedded brains GmbH & Co. KG + +.. index:: Kernel Character I/O Support + +.. _RTEMSAPIKernelCharIO: + +Kernel Character I/O Support +**************************** + +.. toctree:: + + introduction + directives diff --git a/c-user/kernel-character-io/introduction.rst b/c-user/kernel-character-io/introduction.rst new file mode 100644 index 0000000..dc3ac26 --- /dev/null +++ b/c-user/kernel-character-io/introduction.rst @@ -0,0 +1,69 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 2015 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/rtems/io/if/group-3 + +.. _KernelCharacterIOSupportIntroduction: + +Introduction +============ + +.. The following list was generated from: +.. spec:/rtems/io/if/putc +.. spec:/rtems/io/if/put-char +.. spec:/rtems/io/if/putk +.. spec:/rtems/io/if/printk +.. spec:/rtems/io/if/vprintk +.. spec:/rtems/io/if/printk-printer +.. spec:/rtems/io/if/getchark + +The kernel character input/output support is an extension of the +:ref:`RTEMSAPIClassicIO` to output characters to the kernel character output +device and receive characters from the kernel character input device using a +polled and non-blocking implementation. + +The directives may be used to print debug and test information. The kernel +character input/output support should work even if no Console Driver is +configured, see :ref:`CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`. The kernel +character input and output device is provided by the :term:`BSP`. Applications +may change the device. The directives provided by the Kernel Character I/O +Support are: + +* :ref:`InterfaceRtemsPutc` - Outputs the character to the kernel character + output device. + +* :ref:`InterfaceRtemsPutChar` - Puts the character using + :ref:`InterfaceRtemsPutc` + +* :ref:`InterfacePutk` - Outputs the characters of the string and a newline + character to the kernel character output device. + +* :ref:`InterfacePrintk` - Outputs the characters defined by the format string + and the arguments to the kernel character output device. + +* :ref:`InterfaceVprintk` - Outputs the characters defined by the format string + and the variable argument list to the kernel character output device. + +* :ref:`InterfaceRtemsPrintkPrinter` - Outputs the characters defined by the + format string and the variable argument list to the kernel character output + device. + +* :ref:`InterfaceGetchark` - Tries to dequeue a character from the kernel + character input device. diff --git a/c-user/key_concepts.rst b/c-user/key_concepts.rst index 6bc1c3e..fe8e90e 100644 --- a/c-user/key_concepts.rst +++ b/c-user/key_concepts.rst @@ -45,7 +45,7 @@ An object name is an unsigned thirty-two bit entity associated with the object by the user. The data type ``rtems_name`` is used to store object names. -.. index:: rtems_build_name +.. index:: rtems_build_name() Although not required by RTEMS, object names are often composed of four ASCII characters which help identify that object. For example, a task which causes a @@ -64,7 +64,7 @@ would be difficult to assign meaningful ASCII names to each task. A more convenient approach would be to name them the binary values one through one-hundred, respectively. -.. index:: rtems_object_get_name +.. index:: rtems_object_get_name() RTEMS provides a helper routine, ``rtems_object_get_name``, which can be used to obtain the name of any RTEMS object using just its ID. This routine @@ -85,18 +85,75 @@ name: printk( "ID=0x%08x name=%s\n", id, ((result) ? result : "no name") ); } -.. index:: object ID -.. index:: object ID composition +.. index:: object id +.. index:: object id composition .. index:: rtems_id -Object IDs +Object Ids ---------- -An object ID is a unique 32-bit unsigned integer value which uniquely -identifies an object instance. Object IDs are passed as arguments to many -directives in RTEMS and RTEMS translates the ID to an internal object pointer. -The efficient manipulation of object IDs is critical to the performance of some -RTEMS services. +an object id is a unique 32-bit unsigned integer value which uniquely +identifies an object instance. object ids are passed as arguments to many +directives in rtems and rtems translates the id to an internal object pointer. +the efficient manipulation of object ids is critical to the performance of some +rtems services. + +.. index:: rtems_extension_ident() +.. index:: rtems_barrier_ident() +.. index:: rtems_port_ident() +.. index:: rtems_message_queue_ident() +.. index:: rtems_partition_ident() +.. index:: rtems_region_ident() +.. index:: rtems_semaphore_ident() +.. index:: rtems_task_ident() +.. index:: rtems_timer_ident() + +There are multiple directives with names of the form +``rtems_@CLASS@_ident`` that take a name as argument and return the associated +id if the name is found. The following is the set of name to id services: +which can look up an object + +* ``rtems_extension_ident()`` +* ``rtems_barrier_ident()`` +* ``rtems_port_ident()`` +* ``rtems_message_queue_ident()`` +* ``rtems_partition_ident()`` +* ``rtems_region_ident()`` +* ``rtems_semaphore_ident()`` +* ``rtems_task_ident()`` +* ``rtems_timer_ident()`` + +Local and Global Scope +---------------------- + +.. index:: uniprocesor +.. index:: multiprocessing +.. index:: distributed multiprocessing +.. index:: symmetric multiprocessing (SMP) +.. index:: local scope +.. index:: global scope +.. index:: RTEMS_GLOBAL +.. index:: RTEMS_LOCAL +.. index:: RTEMS_GLOBAL + +RTEMS supports uniprocessing, distributed multiprocessing, and Symmetric +Multiprocessing (SMP) configurations. A uniprocessor system includes only +a single processor in a single node. Distributed multiprocessor systems +include multiple nodes, each of which is a single processor and is usually +referred to as just multiprocessor mode for historical reasons. SMP +systems consist of multiple processors cores in a single node. + +In distributed multiprocessing configurations, there are multiple nodes in +the system and object instances may be visible on just the creating node +or to all nodes. If visible only to the creating node, this is referred to +as **local scope** and corresponds to the RTEMS_LOCAL attribute setting +which is the default. If RTEMS GLOBAL is specified as part of the object +attributes, then the object instance has **global scope** and the object +id can be used anywhere in the system to identify that object instance. + +In uniprocessing and SMP configurations, there is only one node in +the system and object instances are locally scoped to that node. Any +attempt to create with the RTEMS_GLOBAL attribute is an error. Object ID Format ~~~~~~~~~~~~~~~~ @@ -122,6 +179,9 @@ sixteen bits form an identifier within a particular object type. This identifier, called the object index, ranges in value from 1 to the maximum number of objects configured for this object type. +None of the fields in an object id may be zero except for the special +case of RTEMS_SELF to indicate the currently running thread. + Object ID Description --------------------- @@ -150,10 +210,10 @@ prototyped as follows: .. index:: get class from object ID .. index:: get node from object ID .. index:: get index from object ID -.. index:: rtems_object_id_get_api -.. index:: rtems_object_id_get_class -.. index:: rtems_object_id_get_node -.. index:: rtems_object_id_get_index +.. index:: rtems_object_id_get_api() +.. index:: rtems_object_id_get_class() +.. index:: rtems_object_id_get_node() +.. index:: rtems_object_id_get_index() .. code-block:: c @@ -330,7 +390,7 @@ O(m) Independence-Preserving Protocol (OMIP) The :math:`O(m)` Independence-Preserving Protocol (OMIP) is a generalization of the priority inheritance protocol to clustered scheduling which avoids the -non-preemptive sections present with priority boosting +non-preemptive sections present with :term:`priority boosting` :cite:`Brandenburg:2013:OMIP`. The :math:`m` denotes the number of processors in the system. Similar to the uniprocessor priority inheritance protocol, the OMIP mutexes do not need any external configuration data, e.g. a ceiling diff --git a/c-user/linker_sets.rst b/c-user/linker_sets.rst index 8ad4846..74fc957 100644 --- a/c-user/linker_sets.rst +++ b/c-user/linker_sets.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2015, 2020 embedded brains GmbH +.. Copyright (C) 2015, 2020 embedded brains GmbH & Co. KG .. Copyright (C) 2015, 2020 Sebastian Huber .. index:: linkersets diff --git a/c-user/message/background.rst b/c-user/message/background.rst new file mode 100644 index 0000000..2ab43fe --- /dev/null +++ b/c-user/message/background.rst @@ -0,0 +1,91 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Background +========== + +Messages +-------- + +A message is a variable length buffer where information can be stored to +support communication. The length of the message and the information stored in +that message are user-defined and can be actual data, pointer(s), or empty. + +Message Queues +-------------- + +A message queue permits the passing of messages among tasks and ISRs. Message +queues can contain a variable number of messages. Normally messages are sent +to and received from the queue in FIFO order using the +``rtems_message_queue_send`` directive. However, the +``rtems_message_queue_urgent`` directive can be used to place messages at the +head of a queue in LIFO order. + +Synchronization can be accomplished when a task can wait for a message to +arrive at a queue. Also, a task may poll a queue for the arrival of a message. + +The maximum length message which can be sent is set on a per message queue +basis. The message content must be copied in general to/from an internal +buffer of the message queue or directly to a peer in certain cases. This copy +operation is performed with interrupts disabled. So it is advisable to keep +the messages as short as possible. + +.. index:: message queue attributes + +Building a Message Queue Attribute Set +-------------------------------------- + +In general, an attribute set is built by a bitwise OR of the desired attribute +components. The set of valid message queue attributes is provided in the +following table: + +.. list-table:: + :class: rtems-table + + * - ``RTEMS_FIFO`` + - tasks wait by FIFO (default) + * - ``RTEMS_PRIORITY`` + - tasks wait by priority + * - ``RTEMS_LOCAL`` + - local message queue (default) + * - ``RTEMS_GLOBAL`` + - global message queue + +An attribute listed as a default is not required to appear in the attribute +list, although it is a good programming practice to specify default attributes. +If all defaults are desired, the attribute ``RTEMS_DEFAULT_ATTRIBUTES`` should +be specified on this call. + +This example demonstrates the attribute_set parameter needed to create a local +message queue with the task priority waiting queue discipline. The +attribute_set parameter to the ``rtems_message_queue_create`` directive could +be either ``RTEMS_PRIORITY`` or ``RTEMS_LOCAL | RTEMS_PRIORITY``. The +attribute_set parameter can be set to ``RTEMS_PRIORITY`` because +``RTEMS_LOCAL`` is the default for all created message queues. If a similar +message queue were to be known globally, then the attribute_set parameter would +be ``RTEMS_GLOBAL | RTEMS_PRIORITY``. + +Building a MESSAGE_QUEUE_RECEIVE Option Set +------------------------------------------- + +In general, an option is built by a bitwise OR of the desired option +components. The set of valid options for the ``rtems_message_queue_receive`` +directive are listed in the following table: + +.. list-table:: + :class: rtems-table + + * - ``RTEMS_WAIT`` + - task will wait for a message (default) + * - ``RTEMS_NO_WAIT`` + - task should not wait + +An option listed as a default is not required to appear in the option OR list, +although it is a good programming practice to specify default options. If all +defaults are desired, the option ``RTEMS_DEFAULT_OPTIONS`` should be specified +on this call. + +This example demonstrates the option parameter needed to poll for a message to +arrive. The option parameter passed to the ``rtems_message_queue_receive`` +directive should be ``RTEMS_NO_WAIT``. diff --git a/c-user/message/directives.rst b/c-user/message/directives.rst new file mode 100644 index 0000000..7039b2e --- /dev/null +++ b/c-user/message/directives.rst @@ -0,0 +1,1086 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. _MessageManagerDirectives: + +Directives +========== + +This section details the directives of the Message Manager. A subsection is +dedicated to each of this manager's directives and lists the calling sequence, +parameters, description, return values, and notes of the directive. + +.. Generated from spec:/rtems/message/if/create + +.. raw:: latex + + \clearpage + +.. index:: rtems_message_queue_create() +.. index:: create a message queue + +.. _InterfaceRtemsMessageQueueCreate: + +rtems_message_queue_create() +---------------------------- + +Creates a message queue. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_message_queue_create( + rtems_name name, + uint32_t count, + size_t max_message_size, + rtems_attribute attribute_set, + rtems_id *id + ); + +.. rubric:: PARAMETERS: + +``name`` + This parameter is the object name of the message queue. + +``count`` + This parameter is the maximum count of pending messages supported by the + message queue. + +``max_message_size`` + This parameter is the maximum size in bytes of a message supported by the + message queue. + +``attribute_set`` + This parameter is the attribute set of the message queue. + +``id`` + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the identifier of the created message + queue will be stored in this object. + +.. rubric:: DESCRIPTION: + +This directive creates a message queue which resides on the local node. The +message queue has the user-defined object name specified in ``name``. Memory +is allocated from the RTEMS Workspace for the count of messages specified in +``count``, each of ``max_message_size`` bytes in length. The assigned object +identifier is returned in ``id``. This identifier is used to access the +message queue with other message queue related directives. + +The **attribute set** specified in ``attribute_set`` is built through a +*bitwise or* of the attribute constants described below. Not all combinations +of attributes are allowed. Some attributes are mutually exclusive. If +mutually exclusive attributes are combined, the behaviour is undefined. +Attributes not mentioned below are not evaluated by this directive and have no +effect. Default attributes can be selected by using the +:c:macro:`RTEMS_DEFAULT_ATTRIBUTES` constant. The attribute set defines + +* the scope of the message queue: :c:macro:`RTEMS_LOCAL` (default) or + :c:macro:`RTEMS_GLOBAL` and + +* the task wait queue discipline used by the message queue: + :c:macro:`RTEMS_FIFO` (default) or :c:macro:`RTEMS_PRIORITY`. + +The message queue has a local or global **scope** in a multiprocessing network +(this attribute does not refer to SMP systems). The scope is selected by the +mutually exclusive :c:macro:`RTEMS_LOCAL` and :c:macro:`RTEMS_GLOBAL` +attributes. + +* A **local scope** is the default and can be emphasized through the use of the + :c:macro:`RTEMS_LOCAL` attribute. A local message queue can be only used by + the node which created it. + +* A **global scope** is established if the :c:macro:`RTEMS_GLOBAL` attribute is + set. Setting the global attribute in a single node system has no effect. + +The **task wait queue discipline** is selected by the mutually exclusive +:c:macro:`RTEMS_FIFO` and :c:macro:`RTEMS_PRIORITY` attributes. The discipline +defines the order in which tasks wait for a message to receive on a currently +empty message queue. + +* The **FIFO discipline** is the default and can be emphasized through use of + the :c:macro:`RTEMS_FIFO` attribute. + +* The **priority discipline** is selected by the :c:macro:`RTEMS_PRIORITY` + attribute. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_NAME` + The ``name`` parameter was invalid. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``id`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_NUMBER` + The ``count`` parameter was invalid. + +:c:macro:`RTEMS_INVALID_SIZE` + The ``max_message_size`` parameter was invalid. + +:c:macro:`RTEMS_TOO_MANY` + There was no inactive object available to create a message queue. The + number of message queue available to the application is configured through + the :ref:`CONFIGURE_MAXIMUM_MESSAGE_QUEUES` application configuration + option. + +:c:macro:`RTEMS_TOO_MANY` + In multiprocessing configurations, there was no inactive global object + available to create a global message queue. The number of global objects + available to the application is configured through the + :ref:`CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS` application configuration + option. + +:c:macro:`RTEMS_INVALID_NUMBER` + The product of ``count`` and ``max_message_size`` is greater than the + maximum storage size. + +:c:macro:`RTEMS_UNSATISFIED` + There was not enough memory available in the RTEMS Workspace to allocate + the message buffers for the message queue. + +.. rubric:: NOTES: + +For message queues with a global scope, the maximum message size is effectively +limited to the longest message which the :term:`MPCI` is capable of +transmitting. + +For control and maintenance of the message queue, RTEMS allocates a :term:`QCB` +from the local QCB free pool and initializes it. + +The QCB for a global message queue is allocated on the local node. Message +queues should not be made global unless remote tasks must interact with the +message queue. This is to avoid the system overhead incurred by the creation +of a global message queue. When a global message queue is created, the message +queue's name and identifier must be transmitted to every node in the system for +insertion in the local copy of the global object table. + +.. 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. + +* When the directive operates on a global object, the directive sends a message + to remote nodes. This may preempt the calling task. + +* The number of message queues available to the application is configured + through the :ref:`CONFIGURE_MAXIMUM_MESSAGE_QUEUES` application configuration + option. + +* Where the object class corresponding to the directive is configured to use + unlimited objects, the directive may allocate memory from the RTEMS + Workspace. + +* The number of global objects available to the application is configured + through the :ref:`CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS` application + configuration option. + +.. Generated from spec:/rtems/message/if/construct + +.. raw:: latex + + \clearpage + +.. index:: rtems_message_queue_construct() + +.. _InterfaceRtemsMessageQueueConstruct: + +rtems_message_queue_construct() +------------------------------- + +Constructs a message queue from the specified the message queue configuration. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_message_queue_construct( + const rtems_message_queue_config *config, + rtems_id *id + ); + +.. rubric:: PARAMETERS: + +``config`` + This parameter is the pointer to an :ref:`InterfaceRtemsMessageQueueConfig` + object. It configures the message queue. + +``id`` + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the identifier of the constructed message + queue will be stored in this object. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``config`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_NAME` + The message queue name in the configuration was invalid. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``id`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_NUMBER` + The maximum number of pending messages in the configuration was zero. + +:c:macro:`RTEMS_INVALID_SIZE` + The maximum message size in the configuration was zero. + +:c:macro:`RTEMS_TOO_MANY` + There was no inactive message queue object available to construct a message + queue. + +:c:macro:`RTEMS_TOO_MANY` + In multiprocessing configurations, there was no inactive global object + available to construct a global message queue. + +:c:macro:`RTEMS_INVALID_SIZE` + The maximum message size in the configuration was too big and resulted in + integer overflows in calculations carried out to determine the size of the + message buffer area. + +:c:macro:`RTEMS_INVALID_NUMBER` + The maximum number of pending messages in the configuration was too big and + resulted in integer overflows in calculations carried out to determine the + size of the message buffer area. + +:c:macro:`RTEMS_UNSATISFIED` + The message queue storage area begin pointer in the configuration was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_UNSATISFIED` + The message queue storage area size in the configuration was not equal to + the size calculated from the maximum number of pending messages and the + maximum message size. + +.. rubric:: NOTES: + +In contrast to message queues created by +:ref:`InterfaceRtemsMessageQueueCreate`, the message queues constructed by this +directive use a user-provided message buffer storage area. + +This directive is intended for applications which do not want to use the RTEMS +Workspace and instead statically allocate all operating system resources. An +application based solely on static allocation can avoid any runtime memory +allocators. This can simplify the application architecture as well as any +analysis that may be required. + +The value for :ref:`CONFIGURE_MESSAGE_BUFFER_MEMORY` should not include memory +for message queues constructed by :ref:`InterfaceRtemsMessageQueueConstruct`. + +.. 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. + +* When the directive operates on a global object, the directive sends a message + to remote nodes. This may preempt the calling task. + +* The number of message queues available to the application is configured + through the :ref:`CONFIGURE_MAXIMUM_MESSAGE_QUEUES` application configuration + option. + +* Where the object class corresponding to the directive is configured to use + unlimited objects, the directive may allocate memory from the RTEMS + Workspace. + +* The number of global objects available to the application is configured + through the :ref:`CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS` application + configuration option. + +.. Generated from spec:/rtems/message/if/ident + +.. raw:: latex + + \clearpage + +.. index:: rtems_message_queue_ident() + +.. _InterfaceRtemsMessageQueueIdent: + +rtems_message_queue_ident() +--------------------------- + +Identifies a message queue by the object name. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_message_queue_ident( + rtems_name name, + uint32_t node, + rtems_id *id + ); + +.. rubric:: PARAMETERS: + +``name`` + This parameter is the object name to look up. + +``node`` + This parameter is the node or node set to search for a matching object. + +``id`` + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the object identifier of an object with + the specified name will be stored in this object. + +.. rubric:: DESCRIPTION: + +This directive obtains a message queue identifier associated with the message +queue name specified in ``name``. + +The node to search is specified in ``node``. It shall be + +* a valid node number, + +* the constant :c:macro:`RTEMS_SEARCH_ALL_NODES` to search in all nodes, + +* the constant :c:macro:`RTEMS_SEARCH_LOCAL_NODE` to search in the local node + only, or + +* the constant :c:macro:`RTEMS_SEARCH_OTHER_NODES` to search in all nodes + except the local node. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``id`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_NAME` + The ``name`` parameter was 0. + +:c:macro:`RTEMS_INVALID_NAME` + There was no object with the specified name on the specified nodes. + +:c:macro:`RTEMS_INVALID_NODE` + In multiprocessing configurations, the specified node was invalid. + +.. rubric:: NOTES: + +If the message queue name is not unique, then the message queue identifier will +match the first message queue with that name in the search order. However, this +message queue identifier is not guaranteed to correspond to the desired message +queue. + +The objects are searched from lowest to the highest index. If ``node`` is +:c:macro:`RTEMS_SEARCH_ALL_NODES`, all nodes are searched with the local node +being searched first. All other nodes are searched from lowest to the highest +node number. + +If node is a valid node number which does not represent the local node, then +only the message queues exported by the designated node are searched. + +This directive does not generate activity on remote nodes. It accesses only +the local copy of the global object table. + +The message queue identifier is used with other message related directives to +access the message queue. + +.. 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/message/if/delete + +.. raw:: latex + + \clearpage + +.. index:: rtems_message_queue_delete() +.. index:: delete a message queue + +.. _InterfaceRtemsMessageQueueDelete: + +rtems_message_queue_delete() +---------------------------- + +Deletes the message queue. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_message_queue_delete( rtems_id id ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the message queue identifier. + +.. rubric:: DESCRIPTION: + +This directive deletes the message queue specified by ``id``. As a result of +this directive, all tasks blocked waiting to receive a message from this queue +will be readied and returned a status code which indicates that the message +queue was deleted. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no message queue associated with the identifier specified by + ``id``. + +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT` + The message queue resided on a remote node. + +.. rubric:: NOTES: + +When the message queue is deleted, any messages in the queue are returned to +the free message buffer pool. Any information stored in those messages is +lost. The message buffers allocated for the message queue are reclaimed. + +The :term:`QCB` for the deleted message queue is reclaimed by RTEMS. + +When a global message queue is deleted, the message queue identifier must be +transmitted to every node in the system for deletion from the local copy of the +global object table. + +The message queue must reside on the local node, even if the message queue was +created with the :c:macro:`RTEMS_GLOBAL` attribute. + +Proxies, used to represent remote tasks, are reclaimed when the message queue +is deleted. + +.. 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. + +* When the directive operates on a global object, the directive sends a message + to remote nodes. This may preempt the calling task. + +* The calling task does not have to be the task that created the object. Any + local task that knows the object identifier can delete the object. + +* Where the object class corresponding to the directive is configured to use + unlimited objects, the directive may free memory to the RTEMS Workspace. + +.. Generated from spec:/rtems/message/if/send + +.. raw:: latex + + \clearpage + +.. index:: rtems_message_queue_send() +.. index:: send message to a queue + +.. _InterfaceRtemsMessageQueueSend: + +rtems_message_queue_send() +-------------------------- + +Puts the message at the rear of the queue. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_message_queue_send( + rtems_id id, + const void *buffer, + size_t size + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the queue identifier. + +``buffer`` + This parameter is the begin address of the message buffer to send. + +``size`` + This parameter is the size in bytes of the message buffer to send. + +.. rubric:: DESCRIPTION: + +This directive sends the message ``buffer`` of ``size`` bytes in length to the +queue specified by ``id``. If a task is waiting at the queue, then the message +is copied to the waiting task's buffer and the task is unblocked. If no tasks +are waiting at the queue, then the message is copied to a message buffer which +is obtained from this message queue's message buffer pool. The message buffer +is then placed at the rear of the queue. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no queue associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``buffer`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_SIZE` + The size of the message exceeded the maximum message size of the queue as + defined by :ref:`InterfaceRtemsMessageQueueCreate` or + :ref:`InterfaceRtemsMessageQueueConstruct`. + +:c:macro:`RTEMS_TOO_MANY` + The maximum number of pending messages supported by the queue as defined by + :ref:`InterfaceRtemsMessageQueueCreate` or + :ref:`InterfaceRtemsMessageQueueConstruct` has been reached. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within task context. + +* The directive may be called from within interrupt context. + +* The directive may unblock a task. This may cause the calling task to be + preempted. + +* When the directive operates on a remote object, the directive sends a message + to the remote node and waits for a reply. This will preempt the calling + task. + +.. Generated from spec:/rtems/message/if/urgent + +.. raw:: latex + + \clearpage + +.. index:: rtems_message_queue_urgent() +.. index:: put message at front of queue + +.. _InterfaceRtemsMessageQueueUrgent: + +rtems_message_queue_urgent() +---------------------------- + +Puts the message at the front of the queue. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_message_queue_urgent( + rtems_id id, + const void *buffer, + size_t size + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the queue identifier. + +``buffer`` + This parameter is the begin address of the message buffer to send urgently. + +``size`` + This parameter is the size in bytes of the message buffer to send urgently. + +.. rubric:: DESCRIPTION: + +This directive sends the message ``buffer`` of ``size`` bytes in length to the +queue specified by ``id``. If a task is waiting at the queue, then the message +is copied to the waiting task's buffer and the task is unblocked. If no tasks +are waiting at the queue, then the message is copied to a message buffer which +is obtained from this message queue's message buffer pool. The message buffer +is then placed at the front of the queue. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no queue associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``buffer`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_SIZE` + The size of the message exceeded the maximum message size of the queue as + defined by :ref:`InterfaceRtemsMessageQueueCreate` or + :ref:`InterfaceRtemsMessageQueueConstruct`. + +:c:macro:`RTEMS_TOO_MANY` + The maximum number of pending messages supported by the queue as defined by + :ref:`InterfaceRtemsMessageQueueCreate` or + :ref:`InterfaceRtemsMessageQueueConstruct` has been reached. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within task context. + +* The directive may be called from within interrupt context. + +* The directive may unblock a task. This may cause the calling task to be + preempted. + +* When the directive operates on a remote object, the directive sends a message + to the remote node and waits for a reply. This will preempt the calling + task. + +.. Generated from spec:/rtems/message/if/broadcast + +.. raw:: latex + + \clearpage + +.. index:: rtems_message_queue_broadcast() +.. index:: broadcast message to a queue + +.. _InterfaceRtemsMessageQueueBroadcast: + +rtems_message_queue_broadcast() +------------------------------- + +Broadcasts the messages to the tasks waiting at the queue. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_message_queue_broadcast( + rtems_id id, + const void *buffer, + size_t size, + uint32_t *count + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the queue identifier. + +``buffer`` + This parameter is the begin address of the message buffer to broadcast. + +``size`` + This parameter is the size in bytes of the message buffer to broadcast. + +``count`` + This parameter is the pointer to an `uint32_t + <https://en.cppreference.com/w/c/types/integer>`_ object. When the + directive call is successful, the number of unblocked tasks will be stored + in this object. + +.. rubric:: DESCRIPTION: + +This directive causes all tasks that are waiting at the queue specified by +``id`` to be unblocked and sent the message contained in ``buffer``. Before a +task is unblocked, the message ``buffer`` of ``size`` bytes in length is copied +to that task's message buffer. The number of tasks that were unblocked is +returned in ``count``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no queue associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``buffer`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``count`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_SIZE` + The size of the message exceeded the maximum message size of the queue as + defined by :ref:`InterfaceRtemsMessageQueueCreate` or + :ref:`InterfaceRtemsMessageQueueConstruct`. + +.. rubric:: NOTES: + +The execution time of this directive is directly related to the number of tasks +waiting on the message queue, although it is more efficient than the equivalent +number of invocations of :ref:`InterfaceRtemsMessageQueueSend`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within task context. + +* The directive may be called from within interrupt context. + +* The directive may unblock a task. This may cause the calling task to be + preempted. + +* When the directive operates on a remote object, the directive sends a message + to the remote node and waits for a reply. This will preempt the calling + task. + +.. Generated from spec:/rtems/message/if/receive + +.. raw:: latex + + \clearpage + +.. index:: rtems_message_queue_receive() +.. index:: receive message from a queue + +.. _InterfaceRtemsMessageQueueReceive: + +rtems_message_queue_receive() +----------------------------- + +Receives a message from the queue. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_message_queue_receive( + rtems_id id, + void *buffer, + size_t *size, + rtems_option option_set, + rtems_interval timeout + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the queue identifier. + +``buffer`` + This parameter is the begin address of the buffer to receive the message. + The buffer shall be large enough to receive a message of the maximum length + of the queue as defined by :ref:`InterfaceRtemsMessageQueueCreate` or + :ref:`InterfaceRtemsMessageQueueConstruct`. The ``size`` parameter cannot + be used to specify the size of the buffer. + +``size`` + This parameter is the pointer to a `size_t + <https://en.cppreference.com/w/c/types/size_t>`_ object. When the + directive call is successful, the size in bytes of the received messages + will be stored in this object. This parameter cannot be used to specify + the size of the buffer. + +``option_set`` + This parameter is the option set. + +``timeout`` + This parameter is the timeout in :term:`clock ticks <clock tick>` if the + :c:macro:`RTEMS_WAIT` option is set. Use :c:macro:`RTEMS_NO_TIMEOUT` to + wait potentially forever. + +.. rubric:: DESCRIPTION: + +This directive receives a message from the queue specified by ``id``. + +The **option set** specified in ``option_set`` is built through a *bitwise or* +of the option constants described below. Not all combinations of options are +allowed. Some options are mutually exclusive. If mutually exclusive options +are combined, the behaviour is undefined. Options not mentioned below are not +evaluated by this directive and have no effect. Default options can be selected +by using the :c:macro:`RTEMS_DEFAULT_OPTIONS` constant. + +The calling task can **wait** or **try to receive** a message from the queue +according to the mutually exclusive :c:macro:`RTEMS_WAIT` and +:c:macro:`RTEMS_NO_WAIT` options. + +* **Waiting to receive** a message from the queue is the default and can be + emphasized through the use of the :c:macro:`RTEMS_WAIT` option. The + ``timeout`` parameter defines how long the calling task is willing to wait. + Use :c:macro:`RTEMS_NO_TIMEOUT` to wait potentially forever, otherwise set a + timeout interval in clock ticks. + +* **Trying to receive** a message from the queue is selected by the + :c:macro:`RTEMS_NO_WAIT` option. If this option is defined, then the + ``timeout`` parameter is ignored. When a message from the queue cannot be + immediately received, then the :c:macro:`RTEMS_UNSATISFIED` status is + returned. + +With either :c:macro:`RTEMS_WAIT` or :c:macro:`RTEMS_NO_WAIT` if there is at +least one message in the queue, then it is copied to the buffer, the size is +set to return the length of the message in bytes, and this directive returns +immediately with the :c:macro:`RTEMS_SUCCESSFUL` status code. The buffer has +to be big enough to receive a message of the maximum length with respect to +this message queue. + +If the calling task chooses to return immediately and the queue is empty, then +the directive returns immediately with the :c:macro:`RTEMS_UNSATISFIED` status +code. If the calling task chooses to wait at the message queue and the queue +is empty, then the calling task is placed on the message wait queue and +blocked. If the queue was created with the :c:macro:`RTEMS_PRIORITY` option +specified, then the calling task is inserted into the wait queue according to +its priority. But, if the queue was created with the :c:macro:`RTEMS_FIFO` +option specified, then the calling task is placed at the rear of the wait +queue. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no queue associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``buffer`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``size`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_UNSATISFIED` + The queue was empty. + +:c:macro:`RTEMS_TIMEOUT` + The timeout happened while the calling task was waiting to receive a + message + +:c:macro:`RTEMS_OBJECT_WAS_DELETED` + The queue was deleted while the calling task was waiting to receive a + message. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* When a local queue is accessed and the :c:macro:`RTEMS_NO_WAIT` option is + set, the directive may be called from within interrupt context. + +* The directive may be called from within task context. + +* When the request cannot be immediately satisfied and the + :c:macro:`RTEMS_WAIT` option is set, the calling task blocks at some point + during the directive call. + +* The timeout functionality of the directive requires a :term:`clock tick`. + +* When the directive operates on a remote object, the directive sends a message + to the remote node and waits for a reply. This will preempt the calling + task. + +.. Generated from spec:/rtems/message/if/get-number-pending + +.. raw:: latex + + \clearpage + +.. index:: rtems_message_queue_get_number_pending() +.. index:: get number of pending messages + +.. _InterfaceRtemsMessageQueueGetNumberPending: + +rtems_message_queue_get_number_pending() +---------------------------------------- + +Gets the number of messages pending on the queue. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_message_queue_get_number_pending( + rtems_id id, + uint32_t *count + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the queue identifier. + +``count`` + This parameter is the pointer to an `uint32_t + <https://en.cppreference.com/w/c/types/integer>`_ object. When the + directive call is successful, the number of pending messages will be stored + in this object. + +.. rubric:: DESCRIPTION: + +This directive returns the number of messages pending on the queue specified by +``id`` in ``count``. If no messages are present on the queue, count is set to +zero. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no queue associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``count`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within task context. + +* The directive may be called from within interrupt context. + +* When the directive operates on a remote object, the directive sends a message + to the remote node and waits for a reply. This will preempt the calling + task. + +.. Generated from spec:/rtems/message/if/flush + +.. raw:: latex + + \clearpage + +.. index:: rtems_message_queue_flush() +.. index:: flush messages on a queue + +.. _InterfaceRtemsMessageQueueFlush: + +rtems_message_queue_flush() +--------------------------- + +Flushes all messages on the queue. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_message_queue_flush( rtems_id id, uint32_t *count ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the queue identifier. + +``count`` + This parameter is the pointer to an `uint32_t + <https://en.cppreference.com/w/c/types/integer>`_ object. When the + directive call is successful, the number of pending messages removed from + the queue will be stored in this object. + +.. rubric:: DESCRIPTION: + +This directive removes all pending messages from the queue specified by ``id``. +The number of messages removed is returned in ``count``. If no messages are +present on the queue, count is set to zero. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no queue associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``count`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +.. rubric:: NOTES: + +The directive does not flush tasks waiting to receive a message from the +:term:`wait queue` of the message queue. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/message/if/buffer + +.. raw:: latex + + \clearpage + +.. index:: RTEMS_MESSAGE_QUEUE_BUFFER() + +.. _InterfaceRTEMSMESSAGEQUEUEBUFFER: + +RTEMS_MESSAGE_QUEUE_BUFFER() +---------------------------- + +Defines a structure which can be used as a message queue buffer for messages of +the specified maximum size. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + RTEMS_MESSAGE_QUEUE_BUFFER( size_t maximum_message_size ); + +.. rubric:: PARAMETERS: + +``maximum_message_size`` + This parameter is the maximum message size in bytes. + +.. rubric:: NOTES: + +Use this macro to define the message buffer storage area for +:ref:`InterfaceRtemsMessageQueueConstruct`. diff --git a/c-user/message/index.rst b/c-user/message/index.rst new file mode 100644 index 0000000..b797cd1 --- /dev/null +++ b/c-user/message/index.rst @@ -0,0 +1,18 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 embedded brains GmbH & Co. KG + +.. index:: messages +.. index:: message queues + +.. _RTEMSAPIClassicMessage: + +Message Manager +*************** + +.. toctree:: + + introduction + background + operations + directives diff --git a/c-user/message/introduction.rst b/c-user/message/introduction.rst new file mode 100644 index 0000000..989cd33 --- /dev/null +++ b/c-user/message/introduction.rst @@ -0,0 +1,71 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/rtems/message/if/group + +.. _MessageManagerIntroduction: + +Introduction +============ + +.. The following list was generated from: +.. spec:/rtems/message/if/create +.. spec:/rtems/message/if/construct +.. spec:/rtems/message/if/ident +.. spec:/rtems/message/if/delete +.. spec:/rtems/message/if/send +.. spec:/rtems/message/if/urgent +.. spec:/rtems/message/if/broadcast +.. spec:/rtems/message/if/receive +.. spec:/rtems/message/if/get-number-pending +.. spec:/rtems/message/if/flush +.. spec:/rtems/message/if/buffer + +The Message Manager provides communication and synchronization capabilities +using RTEMS message queues. The directives provided by the Message Manager are: + +* :ref:`InterfaceRtemsMessageQueueCreate` - Creates a message queue. + +* :ref:`InterfaceRtemsMessageQueueConstruct` - Constructs a message queue from + the specified the message queue configuration. + +* :ref:`InterfaceRtemsMessageQueueIdent` - Identifies a message queue by the + object name. + +* :ref:`InterfaceRtemsMessageQueueDelete` - Deletes the message queue. + +* :ref:`InterfaceRtemsMessageQueueSend` - Puts the message at the rear of the + queue. + +* :ref:`InterfaceRtemsMessageQueueUrgent` - Puts the message at the front of + the queue. + +* :ref:`InterfaceRtemsMessageQueueBroadcast` - Broadcasts the messages to the + tasks waiting at the queue. + +* :ref:`InterfaceRtemsMessageQueueReceive` - Receives a message from the queue. + +* :ref:`InterfaceRtemsMessageQueueGetNumberPending` - Gets the number of + messages pending on the queue. + +* :ref:`InterfaceRtemsMessageQueueFlush` - Flushes all messages on the queue. + +* :ref:`InterfaceRTEMSMESSAGEQUEUEBUFFER` - Defines a structure which can be + used as a message queue buffer for messages of the specified maximum size. diff --git a/c-user/message/operations.rst b/c-user/message/operations.rst new file mode 100644 index 0000000..4d34661 --- /dev/null +++ b/c-user/message/operations.rst @@ -0,0 +1,89 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Operations +========== + +Creating a Message Queue +------------------------ + +The ``rtems_message_queue_create`` directive creates a message queue with the +user-defined name. The user specifies the maximum message size and maximum +number of messages which can be placed in the message queue at one time. The +user may select FIFO or task priority as the method for placing waiting tasks +in the task wait queue. RTEMS allocates a Queue Control Block (QCB) from the +QCB free list to maintain the newly created queue as well as memory for the +message buffer pool associated with this message queue. RTEMS also generates a +message queue ID which is returned to the calling task. + +For GLOBAL message queues, the maximum message size is effectively limited to +the longest message which the MPCI is capable of transmitting. + +Obtaining Message Queue IDs +--------------------------- + +When a message queue is created, RTEMS generates a unique message queue ID. +The message queue ID may be obtained by either of two methods. First, as the +result of an invocation of the ``rtems_message_queue_create`` directive, the +queue ID is stored in a user provided location. Second, the queue ID may be +obtained later using the ``rtems_message_queue_ident`` directive. The queue ID +is used by other message manager directives to access this message queue. + +Receiving a Message +------------------- + +The ``rtems_message_queue_receive`` directive attempts to retrieve a message +from the specified message queue. If at least one message is in the queue, +then the message is removed from the queue, copied to the caller's message +buffer, and returned immediately along with the length of the message. When +messages are unavailable, one of the following situations applies: + +- By default, the calling task will wait forever for the message to arrive. + +- Specifying the ``RTEMS_NO_WAIT`` option forces an immediate return with an + error status code. + +- Specifying a timeout limits the period the task will wait before returning + with an error status. + +If the task waits for a message, then it is placed in the message queue's task +wait queue in either FIFO or task priority order. All tasks waiting on a +message queue are returned an error code when the message queue is deleted. + +Sending a Message +----------------- + +Messages can be sent to a queue with the ``rtems_message_queue_send`` and +``rtems_message_queue_urgent`` directives. These directives work identically +when tasks are waiting to receive a message. A task is removed from the task +waiting queue, unblocked, and the message is copied to a waiting task's message +buffer. + +When no tasks are waiting at the queue, ``rtems_message_queue_send`` places the +message at the rear of the message queue, while ``rtems_message_queue_urgent`` +places the message at the front of the queue. The message is copied to a +message buffer from this message queue's buffer pool and then placed in the +message queue. Neither directive can successfully send a message to a message +queue which has a full queue of pending messages. + +Broadcasting a Message +---------------------- + +The ``rtems_message_queue_broadcast`` directive sends the same message to every +task waiting on the specified message queue as an atomic operation. The +message is copied to each waiting task's message buffer and each task is +unblocked. The number of tasks which were unblocked is returned to the caller. + +Deleting a Message Queue +------------------------ + +The ``rtems_message_queue_delete`` directive removes a message queue from the +system and frees its control block as well as the memory associated with this +message queue's message buffer pool. A message queue can be deleted by any +local task that knows the message queue's ID. As a result of this directive, +all tasks blocked waiting to receive a message from the message queue will be +readied and returned a status code which indicates that the message queue was +deleted. Any subsequent references to the message queue's name and ID are +invalid. Any messages waiting at the message queue are also deleted and +deallocated. diff --git a/c-user/message_manager.rst b/c-user/message_manager.rst deleted file mode 100644 index 3132f2c..0000000 --- a/c-user/message_manager.rst +++ /dev/null @@ -1,762 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-4.0 - -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) - -.. index:: messages -.. index:: message queues - -Message Manager -*************** - -Introduction -============ - -The message manager provides communication and synchronization capabilities -using RTEMS message queues. The directives provided by the message manager -are: - -- rtems_message_queue_create_ - Create a queue - -- rtems_message_queue_ident_ - Get ID of a queue - -- rtems_message_queue_delete_ - Delete a queue - -- rtems_message_queue_send_ - Put message at rear of a queue - -- rtems_message_queue_urgent_ - Put message at front of a queue - -- rtems_message_queue_broadcast_ - Broadcast N messages to a queue - -- rtems_message_queue_receive_ - Receive message from a queue - -- rtems_message_queue_get_number_pending_ - Get number of messages pending on a queue - -- rtems_message_queue_flush_ - Flush all messages on a queue - -Background -========== - -Messages --------- - -A message is a variable length buffer where information can be stored to -support communication. The length of the message and the information stored in -that message are user-defined and can be actual data, pointer(s), or empty. - -Message Queues --------------- - -A message queue permits the passing of messages among tasks and ISRs. Message -queues can contain a variable number of messages. Normally messages are sent -to and received from the queue in FIFO order using the -``rtems_message_queue_send`` directive. However, the -``rtems_message_queue_urgent`` directive can be used to place messages at the -head of a queue in LIFO order. - -Synchronization can be accomplished when a task can wait for a message to -arrive at a queue. Also, a task may poll a queue for the arrival of a message. - -The maximum length message which can be sent is set on a per message queue -basis. The message content must be copied in general to/from an internal -buffer of the message queue or directly to a peer in certain cases. This copy -operation is performed with interrupts disabled. So it is advisable to keep -the messages as short as possible. - -.. index:: message queue attributes - -Building a Message Queue Attribute Set --------------------------------------- - -In general, an attribute set is built by a bitwise OR of the desired attribute -components. The set of valid message queue attributes is provided in the -following table: - -.. list-table:: - :class: rtems-table - - * - ``RTEMS_FIFO`` - - tasks wait by FIFO (default) - * - ``RTEMS_PRIORITY`` - - tasks wait by priority - * - ``RTEMS_LOCAL`` - - local message queue (default) - * - ``RTEMS_GLOBAL`` - - global message queue - -An attribute listed as a default is not required to appear in the attribute -list, although it is a good programming practice to specify default attributes. -If all defaults are desired, the attribute ``RTEMS_DEFAULT_ATTRIBUTES`` should -be specified on this call. - -This example demonstrates the attribute_set parameter needed to create a local -message queue with the task priority waiting queue discipline. The -attribute_set parameter to the ``rtems_message_queue_create`` directive could -be either ``RTEMS_PRIORITY`` or ``RTEMS_LOCAL | RTEMS_PRIORITY``. The -attribute_set parameter can be set to ``RTEMS_PRIORITY`` because -``RTEMS_LOCAL`` is the default for all created message queues. If a similar -message queue were to be known globally, then the attribute_set parameter would -be ``RTEMS_GLOBAL | RTEMS_PRIORITY``. - -Building a MESSAGE_QUEUE_RECEIVE Option Set -------------------------------------------- - -In general, an option is built by a bitwise OR of the desired option -components. The set of valid options for the ``rtems_message_queue_receive`` -directive are listed in the following table: - -.. list-table:: - :class: rtems-table - - * - ``RTEMS_WAIT`` - - task will wait for a message (default) - * - ``RTEMS_NO_WAIT`` - - task should not wait - -An option listed as a default is not required to appear in the option OR list, -although it is a good programming practice to specify default options. If all -defaults are desired, the option ``RTEMS_DEFAULT_OPTIONS`` should be specified -on this call. - -This example demonstrates the option parameter needed to poll for a message to -arrive. The option parameter passed to the ``rtems_message_queue_receive`` -directive should be ``RTEMS_NO_WAIT``. - -Operations -========== - -Creating a Message Queue ------------------------- - -The ``rtems_message_queue_create`` directive creates a message queue with the -user-defined name. The user specifies the maximum message size and maximum -number of messages which can be placed in the message queue at one time. The -user may select FIFO or task priority as the method for placing waiting tasks -in the task wait queue. RTEMS allocates a Queue Control Block (QCB) from the -QCB free list to maintain the newly created queue as well as memory for the -message buffer pool associated with this message queue. RTEMS also generates a -message queue ID which is returned to the calling task. - -For GLOBAL message queues, the maximum message size is effectively limited to -the longest message which the MPCI is capable of transmitting. - -Obtaining Message Queue IDs ---------------------------- - -When a message queue is created, RTEMS generates a unique message queue ID. -The message queue ID may be obtained by either of two methods. First, as the -result of an invocation of the ``rtems_message_queue_create`` directive, the -queue ID is stored in a user provided location. Second, the queue ID may be -obtained later using the ``rtems_message_queue_ident`` directive. The queue ID -is used by other message manager directives to access this message queue. - -Receiving a Message -------------------- - -The ``rtems_message_queue_receive`` directive attempts to retrieve a message -from the specified message queue. If at least one message is in the queue, -then the message is removed from the queue, copied to the caller's message -buffer, and returned immediately along with the length of the message. When -messages are unavailable, one of the following situations applies: - -- By default, the calling task will wait forever for the message to arrive. - -- Specifying the ``RTEMS_NO_WAIT`` option forces an immediate return with an - error status code. - -- Specifying a timeout limits the period the task will wait before returning - with an error status. - -If the task waits for a message, then it is placed in the message queue's task -wait queue in either FIFO or task priority order. All tasks waiting on a -message queue are returned an error code when the message queue is deleted. - -Sending a Message ------------------ - -Messages can be sent to a queue with the ``rtems_message_queue_send`` and -``rtems_message_queue_urgent`` directives. These directives work identically -when tasks are waiting to receive a message. A task is removed from the task -waiting queue, unblocked, and the message is copied to a waiting task's message -buffer. - -When no tasks are waiting at the queue, ``rtems_message_queue_send`` places the -message at the rear of the message queue, while ``rtems_message_queue_urgent`` -places the message at the front of the queue. The message is copied to a -message buffer from this message queue's buffer pool and then placed in the -message queue. Neither directive can successfully send a message to a message -queue which has a full queue of pending messages. - -Broadcasting a Message ----------------------- - -The ``rtems_message_queue_broadcast`` directive sends the same message to every -task waiting on the specified message queue as an atomic operation. The -message is copied to each waiting task's message buffer and each task is -unblocked. The number of tasks which were unblocked is returned to the caller. - -Deleting a Message Queue ------------------------- - -The ``rtems_message_queue_delete`` directive removes a message queue from the -system and frees its control block as well as the memory associated with this -message queue's message buffer pool. A message queue can be deleted by any -local task that knows the message queue's ID. As a result of this directive, -all tasks blocked waiting to receive a message from the message queue will be -readied and returned a status code which indicates that the message queue was -deleted. Any subsequent references to the message queue's name and ID are -invalid. Any messages waiting at the message queue are also deleted and -deallocated. - -Directives -========== - -This section details the message manager's directives. A subsection is -dedicated to each of this manager's directives and describes the calling -sequence, related constants, usage, and status codes. - -.. raw:: latex - - \clearpage - -.. index:: create a message queue -.. index:: rtems_message_queue_create - -.. _rtems_message_queue_create: - -MESSAGE_QUEUE_CREATE - Create a queue -------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_message_queue_create( - rtems_name name, - uint32_t count, - size_t max_message_size, - rtems_attribute attribute_set, - rtems_id *id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - queue created successfully - * - ``RTEMS_INVALID_NAME`` - - invalid queue name - * - ``RTEMS_INVALID_ADDRESS`` - - ``id`` is NULL - * - ``RTEMS_INVALID_NUMBER`` - - invalid message count - * - ``RTEMS_INVALID_SIZE`` - - invalid message size - * - ``RTEMS_TOO_MANY`` - - too many queues created - * - ``RTEMS_UNSATISFIED`` - - unable to allocate message buffers - * - ``RTEMS_MP_NOT_CONFIGURED`` - - multiprocessing not configured - * - ``RTEMS_TOO_MANY`` - - too many global objects - -DESCRIPTION: - This directive creates a message queue which resides on the local node with - the user-defined name specified in name. For control and maintenance of - the queue, RTEMS allocates and initializes a QCB. Memory is allocated from - the RTEMS Workspace for the specified count of messages, each of - max_message_size bytes in length. The RTEMS-assigned queue id, returned in - id, is used to access the message queue. - - Specifying ``RTEMS_PRIORITY`` in attribute_set causes tasks waiting for a - message to be serviced according to task priority. When ``RTEMS_FIFO`` is - specified, waiting tasks are serviced in First In-First Out order. - -NOTES: - This directive will not cause the calling task to be preempted. - - The following message queue attribute constants are defined by RTEMS: - - .. list-table:: - :class: rtems-table - - * - ``RTEMS_FIFO`` - - tasks wait by FIFO (default) - * - ``RTEMS_PRIORITY`` - - tasks wait by priority - * - ``RTEMS_LOCAL`` - - local message queue (default) - * - ``RTEMS_GLOBAL`` - - global message queue - - Message queues should not be made global unless remote tasks must interact - with the created message queue. This is to avoid the system overhead - incurred by the creation of a global message queue. When a global message - queue is created, the message queue's name and id must be transmitted to - every node in the system for insertion in the local copy of the global - object table. - - For GLOBAL message queues, the maximum message size is effectively limited - to the longest message which the MPCI is capable of transmitting. - - The total number of global objects, including message queues, is limited by - the ``maximum_global_objects`` field in the configuration table. - -.. raw:: latex - - \clearpage - -.. index:: get ID of a message queue -.. index:: rtems_message_queue_ident - -.. _rtems_message_queue_ident: - -MESSAGE_QUEUE_IDENT - Get ID of a queue ---------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_message_queue_ident( - rtems_name name, - uint32_t node, - rtems_id *id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - queue identified successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``id`` is NULL - * - ``RTEMS_INVALID_NAME`` - - queue name not found - * - ``RTEMS_INVALID_NODE`` - - invalid node id - -DESCRIPTION: - This directive obtains the queue id associated with the queue name - specified in name. If the queue name is not unique, then the queue id will - match one of the queues with that name. However, this queue id is not - guaranteed to correspond to the desired queue. The queue id is used with - other message related directives to access the message queue. - -NOTES: - This directive will not cause the running task to be preempted. - - If node is ``RTEMS_SEARCH_ALL_NODES``, all nodes are searched with the - local node being searched first. All other nodes are searched with the - lowest numbered node searched first. - - If node is a valid node number which does not represent the local node, - then only the message queues exported by the designated node are searched. - - This directive does not generate activity on remote nodes. It accesses - only the local copy of the global object table. - -.. raw:: latex - - \clearpage - -.. index:: delete a message queue -.. index:: rtems_message_queue_delete - -.. _rtems_message_queue_delete: - -MESSAGE_QUEUE_DELETE - Delete a queue -------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_message_queue_delete( - rtems_id id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - queue deleted successfully - * - ``RTEMS_INVALID_ID`` - - invalid queue id - * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - - cannot delete remote queue - -DESCRIPTION: - This directive deletes the message queue specified by ``id``. As a result - of this directive, all tasks blocked waiting to receive a message from this - queue will be readied and returned a status code which indicates that the - message queue was deleted. If no tasks are waiting, but the queue contains - messages, then RTEMS returns these message buffers back to the system - message buffer pool. The QCB for this queue as well as the memory for the - message buffers is reclaimed by RTEMS. - -NOTES: - The calling task will be preempted if its preemption mode is enabled and - one or more local tasks with a higher priority than the calling task are - waiting on the deleted queue. The calling task will NOT be preempted if - the tasks that are waiting are remote tasks. - - The calling task does not have to be the task that created the queue, - although the task and queue must reside on the same node. - - When the queue is deleted, any messages in the queue are returned to the - free message buffer pool. Any information stored in those messages is - lost. - - When a global message queue is deleted, the message queue id must be - transmitted to every node in the system for deletion from the local copy of - the global object table. - - Proxies, used to represent remote tasks, are reclaimed when the message - queue is deleted. - -.. raw:: latex - - \clearpage - -.. index:: send message to a queue -.. index:: rtems_message_queue_send - -.. _rtems_message_queue_send: - -MESSAGE_QUEUE_SEND - Put message at rear of a queue ---------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_message_queue_send( - rtems_id id, - const void *buffer, - size_t size - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - message sent successfully - * - ``RTEMS_INVALID_ID`` - - invalid queue id - * - ``RTEMS_INVALID_SIZE`` - - invalid message size - * - ``RTEMS_INVALID_ADDRESS`` - - ``buffer`` is NULL - * - ``RTEMS_UNSATISFIED`` - - out of message buffers - * - ``RTEMS_TOO_MANY`` - - queue's limit has been reached - -DESCRIPTION: - This directive sends the message buffer of size bytes in length to the - queue specified by id. If a task is waiting at the queue, then the message - is copied to the waiting task's buffer and the task is unblocked. If no - tasks are waiting at the queue, then the message is copied to a message - buffer which is obtained from this message queue's message buffer pool. - The message buffer is then placed at the rear of the queue. - -NOTES: - The calling task will be preempted if it has preemption enabled and a - higher priority task is unblocked as the result of this directive. - - Sending a message to a global message queue which does not reside on the - local node will generate a request to the remote node to post the message - on the specified message queue. - - If the task to be unblocked resides on a different node from the message - queue, then the message is forwarded to the appropriate node, the waiting - task is unblocked, and the proxy used to represent the task is reclaimed. - -.. raw:: latex - - \clearpage - -.. index:: put message at front of queue -.. index:: rtems_message_queue_urgent - -.. _rtems_message_queue_urgent: - -MESSAGE_QUEUE_URGENT - Put message at front of a queue ------------------------------------------------------- - -**CALLING SEQUENCE:** - .. code-block:: c - - rtems_status_code rtems_message_queue_urgent( - rtems_id id, - const void *buffer, - size_t size - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - message sent successfully - * - ``RTEMS_INVALID_ID`` - - invalid queue id - * - ``RTEMS_INVALID_SIZE`` - - invalid message size - * - ``RTEMS_INVALID_ADDRESS`` - - ``buffer`` is NULL - * - ``RTEMS_UNSATISFIED`` - - out of message buffers - * - ``RTEMS_TOO_MANY`` - - queue's limit has been reached - -DESCRIPTION: - This directive sends the message buffer of size bytes in length to the - queue specified by id. If a task is waiting on the queue, then the message - is copied to the task's buffer and the task is unblocked. If no tasks are - waiting on the queue, then the message is copied to a message buffer which - is obtained from this message queue's message buffer pool. The message - buffer is then placed at the front of the queue. - -NOTES: - The calling task will be preempted if it has preemption enabled and a - higher priority task is unblocked as the result of this directive. - - Sending a message to a global message queue which does not reside on the - local node will generate a request telling the remote node to post the - message on the specified message queue. - - If the task to be unblocked resides on a different node from the message - queue, then the message is forwarded to the appropriate node, the waiting - task is unblocked, and the proxy used to represent the task is reclaimed. - -.. raw:: latex - - \clearpage - -.. index:: broadcast message to a queue -.. index:: rtems_message_queue_broadcast - -.. _rtems_message_queue_broadcast: - -MESSAGE_QUEUE_BROADCAST - Broadcast N messages to a queue ---------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_message_queue_broadcast( - rtems_id id, - const void *buffer, - size_t size, - uint32_t *count - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - message broadcasted successfully - * - ``RTEMS_INVALID_ID`` - - invalid queue id - * - ``RTEMS_INVALID_ADDRESS`` - - ``buffer`` is NULL - * - ``RTEMS_INVALID_ADDRESS`` - - ``count`` is NULL - * - ``RTEMS_INVALID_SIZE`` - - invalid message size - -DESCRIPTION: - This directive causes all tasks that are waiting at the queue specified by - id to be unblocked and sent the message contained in buffer. Before a task - is unblocked, the message buffer of size byes in length is copied to that - task's message buffer. The number of tasks that were unblocked is returned - in count. - -NOTES: - The calling task will be preempted if it has preemption enabled and a - higher priority task is unblocked as the result of this directive. - - The execution time of this directive is directly related to the number of - tasks waiting on the message queue, although it is more efficient than the - equivalent number of invocations of ``rtems_message_queue_send``. - - Broadcasting a message to a global message queue which does not reside on - the local node will generate a request telling the remote node to broadcast - the message to the specified message queue. - - When a task is unblocked which resides on a different node from the message - queue, a copy of the message is forwarded to the appropriate node, the - waiting task is unblocked, and the proxy used to represent the task is - reclaimed. - -.. raw:: latex - - \clearpage - -.. index:: receive message from a queue -.. index:: rtems_message_queue_receive - -.. _rtems_message_queue_receive: - -MESSAGE_QUEUE_RECEIVE - Receive message from a queue ----------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_message_queue_receive( - rtems_id id, - void *buffer, - size_t *size, - rtems_option option_set, - rtems_interval timeout - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - message received successfully - * - ``RTEMS_INVALID_ID`` - - invalid queue id - * - ``RTEMS_INVALID_ADDRESS`` - - ``buffer`` is NULL - * - ``RTEMS_INVALID_ADDRESS`` - - ``size`` is NULL - * - ``RTEMS_UNSATISFIED`` - - queue is empty - * - ``RTEMS_TIMEOUT`` - - timed out waiting for message - * - ``RTEMS_OBJECT_WAS_DELETED`` - - queue deleted while waiting - -DESCRIPTION: - This directive receives a message from the message queue specified in id. - The ``RTEMS_WAIT`` and ``RTEMS_NO_WAIT`` options of the options parameter - allow the calling task to specify whether to wait for a message to become - available or return immediately. For either option, if there is at least - one message in the queue, then it is copied to buffer, size is set to - return the length of the message in bytes, and this directive returns - immediately with a successful return code. The buffer has to be big enough - to receive a message of the maximum length with respect to this message - queue. - - If the calling task chooses to return immediately and the queue is empty, - then a status code indicating this condition is returned. If the calling - task chooses to wait at the message queue and the queue is empty, then the - calling task is placed on the message wait queue and blocked. If the queue - was created with the ``RTEMS_PRIORITY`` option specified, then the calling - task is inserted into the wait queue according to its priority. But, if - the queue was created with the ``RTEMS_FIFO`` option specified, then the - calling task is placed at the rear of the wait queue. - - A task choosing to wait at the queue can optionally specify a timeout value - in the timeout parameter. The timeout parameter specifies the maximum - interval to wait before the calling task desires to be unblocked. If it is - set to ``RTEMS_NO_TIMEOUT``, then the calling task will wait forever. - -NOTES: - The following message receive option constants are defined by RTEMS: - - .. list-table:: - :class: rtems-table - - * - ``RTEMS_WAIT`` - - task will wait for a message (default) - * - ``RTEMS_NO_WAIT`` - - task should not wait - - Receiving a message from a global message queue which does not reside on - the local node will generate a request to the remote node to obtain a - message from the specified message queue. If no message is available and - ``RTEMS_WAIT`` was specified, then the task must be blocked until a message - is posted. A proxy is allocated on the remote node to represent the task - until the message is posted. - - A clock tick is required to support the timeout functionality of this - directive. - -.. raw:: latex - - \clearpage - -.. index:: get number of pending messages -.. index:: rtems_message_queue_get_number_pending - -.. _rtems_message_queue_get_number_pending: - -MESSAGE_QUEUE_GET_NUMBER_PENDING - Get number of messages pending on a queue ----------------------------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_message_queue_get_number_pending( - rtems_id id, - uint32_t *count - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - number of messages pending returned successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``count`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid queue id - -DESCRIPTION: - This directive returns the number of messages pending on this message queue - in count. If no messages are present on the queue, count is set to zero. - -NOTES: - Getting the number of pending messages on a global message queue which does - not reside on the local node will generate a request to the remote node to - actually obtain the pending message count for the specified message queue. - -.. raw:: latex - - \clearpage - -.. index:: flush messages on a queue -.. index:: rtems_message_queue_flush - -.. _rtems_message_queue_flush: - -MESSAGE_QUEUE_FLUSH - Flush all messages on a queue ---------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_message_queue_flush( - rtems_id id, - uint32_t *count - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - message queue flushed successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``count`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid queue id - -DESCRIPTION: - This directive removes all pending messages from the specified queue id. - The number of messages removed is returned in count. If no messages are - present on the queue, count is set to zero. - -NOTES: - Flushing all messages on a global message queue which does not reside on - the local node will generate a request to the remote node to actually flush - the specified message queue. diff --git a/c-user/multiprocessing.rst b/c-user/multiprocessing/background.rst index f207106..2aaae6e 100644 --- a/c-user/multiprocessing.rst +++ b/c-user/multiprocessing/background.rst @@ -2,44 +2,6 @@ .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) -.. index:: multiprocessing - -Multiprocessing Manager -*********************** - -Introduction -============ - -In multiprocessor real-time systems, new requirements, such as sharing data and -global resources between processors, are introduced. This requires an -efficient and reliable communications vehicle which allows all processors to -communicate with each other as necessary. In addition, the ramifications of -multiple processors affect each and every characteristic of a real-time system, -almost always making them more complicated. - -RTEMS addresses these issues by providing simple and flexible real-time -multiprocessing capabilities. The executive easily lends itself to both -tightly-coupled and loosely-coupled configurations of the target system -hardware. In addition, RTEMS supports systems composed of both homogeneous and -heterogeneous mixtures of processors and target boards. - -A major design goal of the RTEMS executive was to transcend the physical -boundaries of the target hardware configuration. This goal is achieved by -presenting the application software with a logical view of the target system -where the boundaries between processor nodes are transparent. As a result, the -application developer may designate objects such as tasks, queues, events, -signals, semaphores, and memory blocks as global objects. These global objects -may then be accessed by any task regardless of the physical location of the -object and the accessing task. RTEMS automatically determines that the object -being accessed resides on another processor and performs the actions required -to access the desired object. Simply stated, RTEMS allows the entire system, -both hardware and software, to be viewed logically as a single system. - -The directives provided by the Manager are: - -- rtems_multiprocessing_announce_ - A multiprocessing communications packet has - arrived - .. index:: multiprocessing topologies Background @@ -455,54 +417,3 @@ of the following: - RTEMS makes no assumptions regarding the application data component of the packet. - -Operations -========== - -Announcing a Packet -------------------- - -The ``rtems_multiprocessing_announce`` directive is called by the MPCI layer to -inform RTEMS that a packet has arrived from another node. This directive can -be called from an interrupt service routine or from within a polling routine. - -Directives -========== - -This section details the additional directives required to support RTEMS in a -multiprocessor configuration. A subsection is dedicated to each of this -manager's directives and describes the calling sequence, related constants, -usage, and status codes. - -.. raw:: latex - - \clearpage - -.. index:: announce arrival of package -.. index:: rtems_multiprocessing_announce - -.. _rtems_multiprocessing_announce: - -MULTIPROCESSING_ANNOUNCE - Announce the arrival of a packet ------------------------------------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - void rtems_multiprocessing_announce( void ); - -DIRECTIVE STATUS CODES: - NONE - -DESCRIPTION: - This directive informs RTEMS that a multiprocessing communications packet - has arrived from another node. This directive is called by the - user-provided MPCI, and is only used in multiprocessor configurations. - -NOTES: - This directive is typically called from an ISR. - - This directive will almost certainly cause the calling task to be - preempted. - - This directive does not generate activity on remote nodes. diff --git a/c-user/multiprocessing/directives.rst b/c-user/multiprocessing/directives.rst new file mode 100644 index 0000000..a12599c --- /dev/null +++ b/c-user/multiprocessing/directives.rst @@ -0,0 +1,75 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. _MultiprocessingManagerDirectives: + +Directives +========== + +This section details the directives of the Multiprocessing Manager. A +subsection is dedicated to each of this manager's directives and lists the +calling sequence, parameters, description, return values, and notes of the +directive. + +.. Generated from spec:/rtems/mp/if/announce + +.. raw:: latex + + \clearpage + +.. index:: rtems_multiprocessing_announce() + +.. _InterfaceRtemsMultiprocessingAnnounce: + +rtems_multiprocessing_announce() +-------------------------------- + +Announces the arrival of a packet. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_multiprocessing_announce( void ); + +.. rubric:: DESCRIPTION: + +This directive informs RTEMS that a multiprocessing communications packet has +arrived from another node. This directive is called by the user-provided MPCI, +and is only used in multiprocessing configurations. + +.. rubric:: NOTES: + +This directive is typically called from an :term:`ISR`. + +This directive does not generate activity on remote nodes. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may unblock a task. This may cause the calling task to be + preempted. diff --git a/c-user/multiprocessing/index.rst b/c-user/multiprocessing/index.rst new file mode 100644 index 0000000..351105d --- /dev/null +++ b/c-user/multiprocessing/index.rst @@ -0,0 +1,17 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2021 embedded brains GmbH & Co. KG + +.. index:: multiprocessing + +.. _RTEMSAPIClassicMP: + +Multiprocessing Manager +*********************** + +.. toctree:: + + introduction + background + operations + directives diff --git a/c-user/multiprocessing/introduction.rst b/c-user/multiprocessing/introduction.rst new file mode 100644 index 0000000..45c90bd --- /dev/null +++ b/c-user/multiprocessing/introduction.rst @@ -0,0 +1,61 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/rtems/mp/if/group + +.. _MultiprocessingManagerIntroduction: + +Introduction +============ + +.. The following list was generated from: +.. spec:/rtems/mp/if/announce + +The Multiprocessing Manager provides support for heterogeneous multiprocessing +systems based on message passing in a network of multiprocessing nodes. + +In multiprocessor real-time systems, new requirements, such as sharing data and +global resources between processors, are introduced. This requires an +efficient and reliable communications vehicle which allows all processors to +communicate with each other as necessary. In addition, the ramifications of +multiple processors affect each and every characteristic of a real-time system, +almost always making them more complicated. + +RTEMS addresses these issues by providing simple and flexible real-time +multiprocessing capabilities. The executive easily lends itself to both +tightly-coupled and loosely-coupled configurations of the target system +hardware. In addition, RTEMS supports systems composed of both homogeneous and +heterogeneous mixtures of processors and target boards. + +A major design goal of the RTEMS executive was to transcend the physical +boundaries of the target hardware configuration. This goal is achieved by +presenting the application software with a logical view of the target system +where the boundaries between processor nodes are transparent. As a result, the +application developer may designate objects such as tasks, queues, events, +signals, semaphores, and memory blocks as global objects. These global objects +may then be accessed by any task regardless of the physical location of the +object and the accessing task. RTEMS automatically determines that the object +being accessed resides on another processor and performs the actions required +to access the desired object. Simply stated, RTEMS allows the entire system, +both hardware and software, to be viewed logically as a single system. The +directives provided by the Multiprocessing Manager are: + +* :ref:`InterfaceRtemsMultiprocessingAnnounce` - Announces the arrival of a + packet. diff --git a/c-user/multiprocessing/operations.rst b/c-user/multiprocessing/operations.rst new file mode 100644 index 0000000..08dcded --- /dev/null +++ b/c-user/multiprocessing/operations.rst @@ -0,0 +1,13 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Operations +========== + +Announcing a Packet +------------------- + +The ``rtems_multiprocessing_announce`` directive is called by the MPCI layer to +inform RTEMS that a packet has arrived from another node. This directive can +be called from an interrupt service routine or from within a polling routine. diff --git a/c-user/object-services/background.rst b/c-user/object-services/background.rst new file mode 100644 index 0000000..efa9e94 --- /dev/null +++ b/c-user/object-services/background.rst @@ -0,0 +1,43 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +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. + +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. + +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. + +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. diff --git a/c-user/object-services/directives.rst b/c-user/object-services/directives.rst new file mode 100644 index 0000000..c692168 --- /dev/null +++ b/c-user/object-services/directives.rst @@ -0,0 +1,910 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2009 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. _ObjectServicesDirectives: + +Directives +========== + +This section details the directives of the Object Services. A subsection is +dedicated to each of this manager's directives and lists the calling sequence, +parameters, description, return values, and notes of the directive. + +.. Generated from spec:/rtems/object/if/build-id + +.. raw:: latex + + \clearpage + +.. index:: rtems_build_id() + +.. _InterfaceRtemsBuildId: + +rtems_build_id() +---------------- + +Builds the object identifier from the API, class, MPCI node, and index +components. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + 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. + +``the_class`` + This parameter is the class of the object identifier to build. + +``node`` + This parameter is the MPCI node of the object identifier to build. + +``index`` + This parameter is the index of the object identifier to build. + +.. rubric:: RETURN VALUES: + +Returns the object identifier built from the API, class, MPCI node, and index +components. + +.. 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/build-name + +.. raw:: latex + + \clearpage + +.. index:: rtems_build_name() + +.. _InterfaceRtemsBuildName: + +rtems_build_name() +------------------ + +Builds the object name composed of the four characters. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_name rtems_build_name( char c1, char c2, char c3, char c4 ); + +.. rubric:: PARAMETERS: + +``c1`` + This parameter is the first character of the name. + +``c2`` + This parameter is the second character of the name. + +``c3`` + This parameter is the third character of the name. + +``c4`` + This parameter is the fourth character of the name. + +.. rubric:: DESCRIPTION: + +This directive takes the four characters provided as arguments and composes a +32-bit object name with ``c1`` in the most significant 8-bits and ``c4`` in the +least significant 8-bits. + +.. rubric:: RETURN VALUES: + +Returns the object name composed of the four characters. + +.. 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/get-classic-name + +.. raw:: latex + + \clearpage + +.. index:: rtems_object_get_classic_name() + +.. _InterfaceRtemsObjectGetClassicName: + +rtems_object_get_classic_name() +------------------------------- + +Gets the object name associated with the object identifier. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_object_get_classic_name( + rtems_id id, + rtems_name *name + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the object identifier to get the name. + +``name`` + This parameter is the pointer to an :ref:`InterfaceRtemsName` object. When + the directive call is successful, the object name associated with the + object identifier will be stored in this object. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``name`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no object information available for the object identifier. + +:c:macro:`RTEMS_INVALID_ID` + The object name associated with the object identifier was a string. + +:c:macro:`RTEMS_INVALID_ID` + There was no object associated with the object identifier. + +.. 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-name + +.. raw:: latex + + \clearpage + +.. index:: rtems_object_get_name() + +.. _InterfaceRtemsObjectGetName: + +rtems_object_get_name() +----------------------- + +Gets the object name associated with the object identifier as a string. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + char *rtems_object_get_name( rtems_id id, size_t length, char *name ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the object identifier to get the name. + +``length`` + This parameter is the buffer length in bytes. + +``name`` + This parameter is the pointer to a buffer of the specified length. + +.. rubric:: DESCRIPTION: + +The object name is stored in the name buffer. If the name buffer length is +greater than zero, then the stored object name will be ``NUL`` terminated. The +stored object name may be truncated to fit the length. There is no indication +if a truncation occurred. Every attempt is made to return name as a printable +string even if the object has the Classic API 32-bit integer style name. + +.. rubric:: RETURN VALUES: + +`NULL <https://en.cppreference.com/w/c/types/NULL>`_ + The ``length`` parameter was 0. + +`NULL <https://en.cppreference.com/w/c/types/NULL>`_ + The ``name`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +`NULL <https://en.cppreference.com/w/c/types/NULL>`_ + There was no object information available for the object identifier. + +`NULL <https://en.cppreference.com/w/c/types/NULL>`_ + There was no object associated with the object identifier. + +Returns the ``name`` parameter value, if there is an object name associated +with the object identifier. + +.. 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/set-name + +.. raw:: latex + + \clearpage + +.. index:: rtems_object_set_name() + +.. _InterfaceRtemsObjectSetName: + +rtems_object_set_name() +----------------------- + +Sets the object name of the object associated with the object identifier. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_object_set_name( rtems_id id, const char *name ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the object identifier of the object to set the name. + +``name`` + This parameter is the object name to set. + +.. rubric:: DESCRIPTION: + +This directive will set the object name based upon the user string. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``name`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no object information available for the object identifier. + +:c:macro:`RTEMS_INVALID_ID` + There was no object associated with the object identifier. + +:c:macro:`RTEMS_NO_MEMORY` + There was no memory available to duplicate the name. + +.. rubric:: NOTES: + +This directive can be used to set the name of objects which do not have a +naming scheme per their API. + +If the object specified by ``id`` is of a class that has a string name, this +directive 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 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 + + \clearpage + +.. index:: rtems_object_id_get_api() + +.. _InterfaceRtemsObjectIdGetApi: + +rtems_object_id_get_api() +------------------------- + +Gets the API component of the object identifier. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + int rtems_object_id_get_api( rtems_id id ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the object identifier with the API component to get. + +.. rubric:: RETURN VALUES: + +Returns the API component of the object identifier. + +.. rubric:: NOTES: + +This directive does not validate the object identifier provided in ``id``. + +.. 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 + +.. raw:: latex + + \clearpage + +.. index:: rtems_object_id_get_class() + +.. _InterfaceRtemsObjectIdGetClass: + +rtems_object_id_get_class() +--------------------------- + +Gets the class component of the object identifier. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + int rtems_object_id_get_class( rtems_id id ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the object identifier with the class component to get. + +.. rubric:: RETURN VALUES: + +Returns the class component of the object identifier. + +.. rubric:: NOTES: + +This directive does not validate the object identifier provided in ``id``. + +.. 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 + +.. raw:: latex + + \clearpage + +.. index:: rtems_object_id_get_node() + +.. _InterfaceRtemsObjectIdGetNode: + +rtems_object_id_get_node() +-------------------------- + +Gets the MPCI node component of the object identifier. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + int rtems_object_id_get_node( rtems_id id ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the object identifier with the MPCI node component to + get. + +.. rubric:: RETURN VALUES: + +Returns the MPCI node component of the object identifier. + +.. rubric:: NOTES: + +This directive does not validate the object identifier provided in ``id``. + +.. 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 + +.. raw:: latex + + \clearpage + +.. index:: rtems_object_id_get_index() + +.. _InterfaceRtemsObjectIdGetIndex: + +rtems_object_id_get_index() +--------------------------- + +Gets the index component of the object identifier. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + int rtems_object_id_get_index( rtems_id id ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the object identifier with the index component to get. + +.. rubric:: RETURN VALUES: + +Returns the index component of the object identifier. + +.. rubric:: NOTES: + +This directive does not validate the object identifier provided in ``id``. + +.. 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 + +.. raw:: latex + + \clearpage + +.. index:: rtems_object_id_api_minimum() + +.. _InterfaceRtemsObjectIdApiMinimum: + +rtems_object_id_api_minimum() +----------------------------- + +Gets the lowest valid value for the API component of an object identifier. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + int rtems_object_id_api_minimum( void ); + +.. rubric:: RETURN VALUES: + +Returns the lowest valid value for the API component of an object identifier. + +.. 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-maximum + +.. raw:: latex + + \clearpage + +.. index:: rtems_object_id_api_maximum() + +.. _InterfaceRtemsObjectIdApiMaximum: + +rtems_object_id_api_maximum() +----------------------------- + +Gets the highest valid value for the API component of an object identifier. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + int rtems_object_id_api_maximum( void ); + +.. rubric:: RETURN VALUES: + +Returns the highest valid value for the API component of an object identifier. + +.. 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/api-minimum-class + +.. raw:: latex + + \clearpage + +.. index:: rtems_object_api_minimum_class() + +.. _InterfaceRtemsObjectApiMinimumClass: + +rtems_object_api_minimum_class() +-------------------------------- + +Gets the lowest valid class value of the object API. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + int rtems_object_api_minimum_class( int api ); + +.. rubric:: PARAMETERS: + +``api`` + This parameter is the object API to get the lowest valid class value. + +.. rubric:: RETURN VALUES: + +``-1`` + The object API was invalid. + +Returns the lowest valid class value of the object API. + +.. 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/api-maximum-class + +.. raw:: latex + + \clearpage + +.. index:: rtems_object_api_maximum_class() + +.. _InterfaceRtemsObjectApiMaximumClass: + +rtems_object_api_maximum_class() +-------------------------------- + +Gets the highest valid class value of the object API. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + int rtems_object_api_maximum_class( int api ); + +.. rubric:: PARAMETERS: + +``api`` + This parameter is the object API to get the highest valid class value. + +.. rubric:: RETURN VALUES: + +``0`` + The object API was invalid. + +Returns the highest valid class value of the object API. + +.. 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-name + +.. raw:: latex + + \clearpage + +.. index:: rtems_object_get_api_name() + +.. _InterfaceRtemsObjectGetApiName: + +rtems_object_get_api_name() +--------------------------- + +Gets a descriptive name of the object API. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + const char *rtems_object_get_api_name( int api ); + +.. rubric:: PARAMETERS: + +``api`` + This parameter is the object API to get the name. + +.. rubric:: RETURN VALUES: + +"BAD API" + The API was invalid. + +Returns a descriptive name of the API, if the API was valid. + +.. rubric:: NOTES: + +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 + + \clearpage + +.. index:: rtems_object_get_api_class_name() + +.. _InterfaceRtemsObjectGetApiClassName: + +rtems_object_get_api_class_name() +--------------------------------- + +Gets a descriptive name of the object class of the object API. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + const char *rtems_object_get_api_class_name( int the_api, int the_class ); + +.. rubric:: PARAMETERS: + +``the_api`` + This parameter is the object API of the object class. + +``the_class`` + This parameter is the object class of the object API to get the name. + +.. rubric:: RETURN VALUES: + +"BAD API" + The API was invalid. + +"BAD CLASS" + The class of the API was invalid. + +Returns a descriptive name of the class of the API, if the class of the API and +the API were valid. + +.. rubric:: NOTES: + +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 + + \clearpage + +.. index:: rtems_object_get_class_information() + +.. _InterfaceRtemsObjectGetClassInformation: + +rtems_object_get_class_information() +------------------------------------ + +Gets the object class information of the object class of the object API. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_object_get_class_information( + int the_api, + int the_class, + rtems_object_api_class_information *info + ); + +.. rubric:: PARAMETERS: + +``the_api`` + This parameter is the object API of the object class. + +``the_class`` + This parameter is the object class of the object API to get the class + information. + +``info`` + This parameter is the pointer to an + :ref:`InterfaceRtemsObjectApiClassInformation` object. When the directive + call is successful, the object class information of the class of the API + will be stored in this object. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``info`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_NUMBER` + The class of the API or the API was invalid. + +.. 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-local-node + +.. raw:: latex + + \clearpage + +.. index:: rtems_object_get_local_node() + +.. _InterfaceRtemsObjectGetLocalNode: + +rtems_object_get_local_node() +----------------------------- + +Gets the local MPCI node number. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint16_t rtems_object_get_local_node( void ); + +.. rubric:: RETURN VALUES: + +Returns the local MPCI node number. + +.. 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/id-initial + +.. raw:: latex + + \clearpage + +.. index:: RTEMS_OBJECT_ID_INITIAL() + +.. _InterfaceRTEMSOBJECTIDINITIAL: + +RTEMS_OBJECT_ID_INITIAL() +------------------------- + +Builds the object identifier with the lowest index from the API, class, and +MPCI node components. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_id RTEMS_OBJECT_ID_INITIAL( + uint32_t api, + uint32_t class, + uint32_t node + ); + +.. rubric:: PARAMETERS: + +``api`` + This parameter is the API of the object identifier to build. + +``class`` + This parameter is the class of the object identifier to build. + +``node`` + This parameter is the MPCI node of the object identifier to build. + +.. rubric:: RETURN VALUES: + +Returns the object identifier with the lowest index built from the API, class, +and MPCI node components. + +.. 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. diff --git a/c-user/object-services/index.rst b/c-user/object-services/index.rst new file mode 100644 index 0000000..3218551 --- /dev/null +++ b/c-user/object-services/index.rst @@ -0,0 +1,17 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 embedded brains GmbH & Co. KG + +.. index:: object manipulation + +.. _RTEMSAPIClassicObject: + +Object Services +*************** + +.. toctree:: + + introduction + background + operations + directives diff --git a/c-user/object-services/introduction.rst b/c-user/object-services/introduction.rst new file mode 100644 index 0000000..adff786 --- /dev/null +++ b/c-user/object-services/introduction.rst @@ -0,0 +1,104 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2009 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/rtems/object/if/group + +.. _ObjectServicesIntroduction: + +Introduction +============ + +.. The following list was generated from: +.. spec:/rtems/object/if/build-id +.. spec:/rtems/object/if/build-name +.. spec:/rtems/object/if/get-classic-name +.. spec:/rtems/object/if/get-name +.. spec:/rtems/object/if/set-name +.. spec:/rtems/object/if/id-get-api +.. spec:/rtems/object/if/id-get-class +.. spec:/rtems/object/if/id-get-node +.. spec:/rtems/object/if/id-get-index +.. spec:/rtems/object/if/id-api-minimum +.. spec:/rtems/object/if/id-api-maximum +.. spec:/rtems/object/if/api-minimum-class +.. spec:/rtems/object/if/api-maximum-class +.. spec:/rtems/object/if/get-api-name +.. spec:/rtems/object/if/get-api-class-name +.. spec:/rtems/object/if/get-class-information +.. spec:/rtems/object/if/get-local-node +.. spec:/rtems/object/if/id-initial + +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 directives provided by the Object Services are: + +* :ref:`InterfaceRtemsBuildId` - Builds the object identifier from the API, + class, MPCI node, and index components. + +* :ref:`InterfaceRtemsBuildName` - Builds the object name composed of the four + characters. + +* :ref:`InterfaceRtemsObjectGetClassicName` - Gets the object name associated + with the object identifier. + +* :ref:`InterfaceRtemsObjectGetName` - Gets the object name associated with the + object identifier as a string. + +* :ref:`InterfaceRtemsObjectSetName` - Sets the object name of the object + associated with the object identifier. + +* :ref:`InterfaceRtemsObjectIdGetApi` - Gets the API component of the object + identifier. + +* :ref:`InterfaceRtemsObjectIdGetClass` - Gets the class component of the + object identifier. + +* :ref:`InterfaceRtemsObjectIdGetNode` - Gets the MPCI node component of the + object identifier. + +* :ref:`InterfaceRtemsObjectIdGetIndex` - Gets the index component of the + object identifier. + +* :ref:`InterfaceRtemsObjectIdApiMinimum` - Gets the lowest valid value for the + API component of an object identifier. + +* :ref:`InterfaceRtemsObjectIdApiMaximum` - Gets the highest valid value for + the API component of an object identifier. + +* :ref:`InterfaceRtemsObjectApiMinimumClass` - Gets the lowest valid class + value of the object API. + +* :ref:`InterfaceRtemsObjectApiMaximumClass` - Gets the highest valid class + value of the object API. + +* :ref:`InterfaceRtemsObjectGetApiName` - Gets a descriptive name of the object + API. + +* :ref:`InterfaceRtemsObjectGetApiClassName` - Gets a descriptive name of the + object class of the object API. + +* :ref:`InterfaceRtemsObjectGetClassInformation` - Gets the object class + information of the object class of the object API. + +* :ref:`InterfaceRtemsObjectGetLocalNode` - Gets the local MPCI node number. + +* :ref:`InterfaceRTEMSOBJECTIDINITIAL` - Builds the object identifier with the + lowest index from the API, class, and MPCI node components. diff --git a/c-user/object-services/operations.rst b/c-user/object-services/operations.rst new file mode 100644 index 0000000..d900835 --- /dev/null +++ b/c-user/object-services/operations.rst @@ -0,0 +1,86 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +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: + +- ``rtems_object_id_get_api`` + +- ``rtems_object_id_get_class`` + +- ``rtems_object_id_get_node`` + +- ``rtems_object_id_get_index`` + +The following C language example illustrates the decomposition of an Id and +printing the values. + +.. code-block:: c + + void printObjectId(rtems_id id) + { + printf( + "API=%d Class=%" PRIu32 " Node=%" PRIu32 " Index=%" PRIu16 "\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 +"next Id." + +.. code-block:: 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 + ); + } + +Note that this Id may not be valid in this +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. + +In the following C language example, an Id is decomposed into its constituent +parts and "pretty-printed." + +.. code-block:: c + + void prettyPrintObjectId(rtems_id id) + { + int tmpAPI; + uint32_t tmpClass; + + tmpAPI = rtems_object_id_get_api(id), + tmpClass = rtems_object_id_get_class(id), + + printf( + "API=%s Class=%s Node=%" PRIu32 " Index=%" PRIu16 "\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) + ); + } diff --git a/c-user/object_services.rst b/c-user/object_services.rst deleted file mode 100644 index 860ce8c..0000000 --- a/c-user/object_services.rst +++ /dev/null @@ -1,815 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-4.0 - -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) - -.. index:: object manipulation - -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: - -- build_id - -- rtems_build_name_ - build object name from characters - -- rtems_object_get_classic_name_ - lookup name from Id - -- rtems_object_get_name_ - obtain object name as string - -- rtems_object_set_name_ - set object name - -- rtems_object_id_get_api_ - obtain API from Id - -- rtems_object_id_get_class_ - obtain class from Id - -- rtems_object_id_get_node_ - obtain node from Id - -- rtems_object_id_get_index_ - obtain index from Id - -- rtems_build_id_ - build object id from components - -- rtems_object_id_api_minimum_ - obtain minimum 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_maximum_class_ - obtain maximum class value - -- rtems_object_get_api_name_ - obtain API name - -- rtems_object_get_api_class_name_ - obtain class name - -- rtems_object_get_class_information_ - obtain class information - -- rtems_object_get_local_node_ - obtain local node - -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. - -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. - -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. - -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 -========== - -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: - -- ``rtems_object_id_get_api`` - -- ``rtems_object_id_get_class`` - -- ``rtems_object_id_get_node`` - -- ``rtems_object_id_get_index`` - -The following C language example illustrates the decomposition of an Id and -printing the values. - -.. code-block:: c - - void printObjectId(rtems_id id) - { - printf( - "API=%d Class=%" PRIu32 " Node=%" PRIu32 " Index=%" PRIu16 "\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 -"next Id." - -.. code-block:: 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 - ); - } - -Note that this Id may not be valid in this -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. - -In the following C language example, an Id is decomposed into its constituent -parts and "pretty-printed." - -.. code-block:: c - - void prettyPrintObjectId(rtems_id id) - { - int tmpAPI; - uint32_t tmpClass; - - tmpAPI = rtems_object_id_get_api(id), - tmpClass = rtems_object_id_get_class(id), - - printf( - "API=%s Class=%s Node=%" PRIu32 " Index=%" PRIu16 "\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 -========== - -.. raw:: latex - - \clearpage - -.. index:: build object name -.. index:: rtems_build_name - -.. _rtems_build_name: - -BUILD_NAME - Build object name from characters ----------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_name rtems_build_name( - uint8_t c1, - uint8_t c2, - uint8_t c3, - uint8_t c4 - ); - -DIRECTIVE STATUS CODES: - 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. - -NOTES: - This directive is strictly local and does not impact task scheduling. - -.. raw:: latex - - \clearpage - -.. index:: get name from id -.. index:: obtain name from id -.. index:: rtems_object_get_classic_name - -.. _rtems_object_get_classic_name: - -OBJECT_GET_CLASSIC_NAME - Lookup name from id ---------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_object_get_classic_name( - rtems_id id, - rtems_name *name - ); - -DIRECTIVE STATUS CODES: - .. 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``. - -NOTES: - This directive is strictly local and does not impact task scheduling. - -.. raw:: latex - - \clearpage - -.. index:: get object name as string -.. index:: obtain object name as string -.. index:: rtems_object_get_name - -.. _rtems_object_get_name: - -OBJECT_GET_NAME - Obtain object name as string ----------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - 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. - -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. - -NOTES: - This directive is strictly local and does not impact task scheduling. - -.. raw:: latex - - \clearpage - -.. index:: set object name -.. index:: rtems_object_set_name - -.. _rtems_object_set_name: - -OBJECT_SET_NAME - Set object name ---------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_object_set_name( - rtems_id id, - const char *name - ); - -DIRECTIVE STATUS CODES: - .. 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``. - -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 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 - -.. raw:: latex - - \clearpage - -.. index:: obtain API from id -.. index:: rtems_object_id_get_api - -.. _rtems_object_id_get_api: - -OBJECT_ID_GET_API - Obtain API from Id --------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - int rtems_object_id_get_api( - rtems_id id - ); - -DIRECTIVE STATUS CODES: - Returns the API portion of the object Id. - -DESCRIPTION: - This directive returns the API portion of the provided object ``id``. - -NOTES: - This directive is strictly local and does not impact task scheduling. - - This directive does NOT validate the ``id`` provided. - -.. raw:: latex - - \clearpage - -.. index:: obtain class from object id -.. index:: rtems_object_id_get_class - -.. _rtems_object_id_get_class: - -OBJECT_ID_GET_CLASS - Obtain Class from Id ------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - uint32_t rtems_object_id_get_class( - rtems_id id - ); - -DIRECTIVE STATUS CODES: - Returns the class portion of the object Id. - -DESCRIPTION: - This directive returns the class portion of the provided object ``id``. - -NOTES: - This directive is strictly local and does not impact task scheduling. - - This directive does NOT validate the ``id`` provided. - -.. raw:: latex - - \clearpage - -.. index:: obtain node from object id -.. index:: rtems_object_id_get_node - -.. _rtems_object_id_get_node: - -OBJECT_ID_GET_NODE - Obtain Node from Id ----------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - uint32_t rtems_object_id_get_node( - rtems_id id - ); - -DIRECTIVE STATUS CODES: - Returns the node portion of the object Id. - -DESCRIPTION: - This directive returns the node portion of the provided object ``id``. - -NOTES: - This directive is strictly local and does not impact task scheduling. - - This directive does NOT validate the ``id`` provided. - -.. raw:: latex - - \clearpage - -.. index:: obtain index from object id -.. index:: rtems_object_id_get_index - -.. _rtems_object_id_get_index: - -OBJECT_ID_GET_INDEX - Obtain Index from Id ------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - uint16_t rtems_object_id_get_index( - rtems_id id - ); - -DIRECTIVE STATUS CODES: - Returns the index portion of the object Id. - -DESCRIPTION: - This directive returns the index portion of the provided object ``id``. - -NOTES: - This directive is strictly local and does not impact task scheduling. - - This directive does NOT validate the ``id`` provided. - -.. raw:: latex - - \clearpage - -.. index:: build object id from components -.. index:: rtems_build_id - -.. _rtems_build_id: - -BUILD_ID - Build Object Id From Components ------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_id rtems_build_id( - int the_api, - int the_class, - int the_node, - int the_index - ); - -DIRECTIVE STATUS CODES: - 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``. - -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. - -.. raw:: latex - - \clearpage - -.. index:: obtain minimum API value -.. index:: rtems_object_id_api_minimum - -.. _rtems_object_id_api_minimum: - -OBJECT_ID_API_MINIMUM - Obtain Minimum API Value ------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - int rtems_object_id_api_minimum(void); - -DIRECTIVE STATUS CODES: - 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. - -NOTES: - This directive is strictly local and does not impact task scheduling. - -.. raw:: latex - - \clearpage - -.. index:: obtain maximum API value -.. index:: rtems_object_id_api_maximum - -.. _rtems_object_id_api_maximum: - -OBJECT_ID_API_MAXIMUM - Obtain Maximum API Value ------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - int rtems_object_id_api_maximum(void); - -DIRECTIVE STATUS CODES: - 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. - -NOTES: - This directive is strictly local and does not impact task scheduling. - -.. raw:: latex - - \clearpage - -.. index:: obtain minimum class value -.. index:: rtems_object_api_minimum_class - -.. _rtems_object_api_minimum_class: - -OBJECT_API_MINIMUM_CLASS - Obtain Minimum Class Value ------------------------------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - int rtems_object_api_minimum_class( - 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``. - -DESCRIPTION: - 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. - -.. raw:: latex - - \clearpage - -.. index:: obtain maximum class value -.. index:: rtems_object_api_maximum_class - -.. _rtems_object_api_maximum_class: - -OBJECT_API_MAXIMUM_CLASS - Obtain Maximum Class Value ------------------------------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - int rtems_object_api_maximum_class( - 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``. - -DESCRIPTION: - 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. - -.. raw:: latex - - \clearpage - -.. index:: obtain minimum class value for an API -.. index:: rtems_object_id_api_minimum_class - -.. _rtems_object_id_api_minimum_class: - -OBJECT_ID_API_MINIMUM_CLASS - Obtain Minimum Class Value for an API -------------------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - int rtems_object_get_id_api_minimum_class( - int api - ); - -DIRECTIVE STATUS CODES: - If ``api`` is not valid, -1 is returned. - - If successful, this service returns the index corresponding to the first - object class of the specified ``api``. - -DESCRIPTION: - This service returns the index for the first object class associated with - the specified ``api``. - -NOTES: - This directive is strictly local and does not impact task scheduling. - -.. raw:: latex - - \clearpage - -.. index:: obtain maximum class value for an API -.. index:: rtems_object_id_api_maximum_class - -.. _rtems_object_id_api_maximum_class: - -OBJECT_ID_API_MAXIMUM_CLASS - Obtain Maximum Class Value for an API -------------------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - int rtems_object_get_api_maximum_class( - int api - ); - -DIRECTIVE STATUS CODES: - If ``api`` is not valid, -1 is returned. - - If successful, this service returns the index corresponding to the last - object class of the specified ``api``. - -DESCRIPTION: - This service returns the index for the last object class associated with - the specified ``api``. - -NOTES: - This directive is strictly local and does not impact task scheduling. - -.. raw:: latex - - \clearpage - -.. index:: obtain API name -.. index:: rtems_object_get_api_name - -.. _rtems_object_get_api_name: - -OBJECT_GET_API_NAME - Obtain API Name -------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - 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``. - -DESCRIPTION: - This service returns the name of the specified ``api``. - -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. - -.. raw:: latex - - \clearpage - -.. index:: obtain class name -.. index:: rtems_object_get_api_class_name - -.. _rtems_object_get_api_class_name: - -OBJECT_GET_API_CLASS_NAME - Obtain Class Name ---------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - const char *rtems_object_get_api_class_name( - int the_api, - int the_class - ); - -DIRECTIVE STATUS CODES: - 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. - -DESCRIPTION: - 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. - -.. raw:: latex - - \clearpage - -.. index:: obtain class information -.. index:: rtems_object_get_class_information - -.. _rtems_object_get_class_information: - -OBJECT_GET_CLASS_INFORMATION - Obtain Class Information -------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_object_get_class_information( - int the_api, - int the_class, - rtems_object_api_class_information *info - ); - -DIRECTIVE STATUS CODES: - .. 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. - -DESCRIPTION: - This service returns information about the object class indicated by the - specified ``api`` and ``the_class``. This structure is defined as follows: - - .. code-block:: c - - typedef struct { - 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. - -.. raw:: latex - - \clearpage - -.. index:: obtain local node -.. index:: rtems_object_get_local_node - -.. _rtems_object_get_local_node: - -OBJECT_GET_LOCAL_NODE - Obtain Local Node ------------------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - uint16_t rtems_object_get_local_node( void ); - -DIRECTIVE STATUS CODES: - NONE - -DESCRIPTION: - This service returns the local MPCI node. - -NOTES: - This directive is strictly local and does not impact task scheduling. diff --git a/c-user/partition/background.rst b/c-user/partition/background.rst new file mode 100644 index 0000000..ce38fc7 --- /dev/null +++ b/c-user/partition/background.rst @@ -0,0 +1,50 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Background +========== + +.. index:: partition, definition + +Partition Manager Definitions +----------------------------- + +A partition is a physically contiguous memory area divided into fixed-size +buffers that can be dynamically allocated and deallocated. + +.. index:: buffers, definition + +Partitions are managed and maintained as a list of buffers. Buffers are +obtained from the front of the partition's free buffer chain and returned to +the rear of the same chain. When a buffer is on the free buffer chain, RTEMS +uses two pointers of memory from each buffer as the free buffer chain. When a +buffer is allocated, the entire buffer is available for application use. +Therefore, modifying memory that is outside of an allocated buffer could +destroy the free buffer chain or the contents of an adjacent allocated buffer. + +.. index:: partition attribute set, building + +Building a Partition Attribute Set +---------------------------------- + +In general, an attribute set is built by a bitwise OR of the desired attribute +components. The set of valid partition attributes is provided in the following +table: + +.. list-table:: + :class: rtems-table + + * - ``RTEMS_LOCAL`` + - local partition (default) + * - ``RTEMS_GLOBAL`` + - global partition + +Attribute values are specifically designed to be mutually exclusive, therefore +bitwise OR and addition operations are equivalent as long as each attribute +appears exactly once in the component list. An attribute listed as a default +is not required to appear in the attribute list, although it is a good +programming practice to specify default attributes. If all defaults are +desired, the attribute ``RTEMS_DEFAULT_ATTRIBUTES`` should be specified on this +call. The attribute_set parameter should be ``RTEMS_GLOBAL`` to indicate that +the partition is to be known globally. diff --git a/c-user/partition/directives.rst b/c-user/partition/directives.rst new file mode 100644 index 0000000..da5983c --- /dev/null +++ b/c-user/partition/directives.rst @@ -0,0 +1,535 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. _PartitionManagerDirectives: + +Directives +========== + +This section details the directives of the Partition Manager. A subsection is +dedicated to each of this manager's directives and lists the calling sequence, +parameters, description, return values, and notes of the directive. + +.. Generated from spec:/rtems/part/if/create + +.. raw:: latex + + \clearpage + +.. index:: rtems_partition_create() +.. index:: create a partition + +.. _InterfaceRtemsPartitionCreate: + +rtems_partition_create() +------------------------ + +Creates a partition. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_partition_create( + rtems_name name, + void *starting_address, + uintptr_t length, + size_t buffer_size, + rtems_attribute attribute_set, + rtems_id *id + ); + +.. rubric:: PARAMETERS: + +``name`` + This parameter is the object name of the partition. + +``starting_address`` + This parameter is the starting address of the buffer area used by the + partition. + +``length`` + This parameter is the length in bytes of the buffer area used by the + partition. + +``buffer_size`` + This parameter is the size in bytes of a buffer managed by the partition. + +``attribute_set`` + This parameter is the attribute set of the partition. + +``id`` + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the identifier of the created partition + will be stored in this object. + +.. rubric:: DESCRIPTION: + +This directive creates a partition of fixed size buffers from a physically +contiguous memory space which starts at ``starting_address`` and is ``length`` +bytes in size. Each allocated buffer is to be of ``buffer_size`` in bytes. +The partition has the user-defined object name specified in ``name``. The +assigned object identifier is returned in ``id``. This identifier is used to +access the partition with other partition related directives. + +The **attribute set** specified in ``attribute_set`` is built through a +*bitwise or* of the attribute constants described below. Not all combinations +of attributes are allowed. Some attributes are mutually exclusive. If +mutually exclusive attributes are combined, the behaviour is undefined. +Attributes not mentioned below are not evaluated by this directive and have no +effect. Default attributes can be selected by using the +:c:macro:`RTEMS_DEFAULT_ATTRIBUTES` constant. + +The partition has a local or global **scope** in a multiprocessing network +(this attribute does not refer to SMP systems). The scope is selected by the +mutually exclusive :c:macro:`RTEMS_LOCAL` and :c:macro:`RTEMS_GLOBAL` +attributes. + +* A **local scope** is the default and can be emphasized through the use of the + :c:macro:`RTEMS_LOCAL` attribute. A local partition can be only used by the + node which created it. + +* A **global scope** is established if the :c:macro:`RTEMS_GLOBAL` attribute is + set. The memory space used for the partition must reside in shared memory. + Setting the global attribute in a single node system has no effect. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_NAME` + The ``name`` parameter was invalid. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``id`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_SIZE` + The ``length`` parameter was 0. + +:c:macro:`RTEMS_INVALID_SIZE` + The ``buffer_size`` parameter was 0. + +:c:macro:`RTEMS_INVALID_SIZE` + The ``length`` parameter was less than the ``buffer_size`` parameter. + +:c:macro:`RTEMS_INVALID_SIZE` + The ``buffer_size`` parameter was not an integral multiple of the pointer + size. + +:c:macro:`RTEMS_INVALID_SIZE` + The ``buffer_size`` parameter was less than two times the pointer size. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``starting_address`` parameter was not on a pointer size boundary. + +:c:macro:`RTEMS_TOO_MANY` + There was no inactive object available to create a partition. The number + of partitions available to the application is configured through the + :ref:`CONFIGURE_MAXIMUM_PARTITIONS` application configuration option. + +:c:macro:`RTEMS_TOO_MANY` + In multiprocessing configurations, there was no inactive global object + available to create a global semaphore. The number of global objects + available to the application is configured through the + :ref:`CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS` application configuration + option. + +.. rubric:: NOTES: + +The partition buffer area specified by the ``starting_address`` must be +properly aligned. It must be possible to directly store target architecture +pointers and also the user data. For example, if the user data contains some +long double or vector data types, the partition buffer area and the buffer size +must take the alignment of these types into account which is usually larger +than the pointer alignment. A cache line alignment may be also a factor. Use +:c:macro:`RTEMS_PARTITION_ALIGNMENT` to specify the minimum alignment of a +partition buffer type. + +The ``buffer_size`` parameter must be an integral multiple of the pointer size +on the target architecture. Additionally, ``buffer_size`` must be large enough +to hold two pointers on the target architecture. This is required for RTEMS to +manage the buffers when they are free. + +For control and maintenance of the partition, RTEMS allocates a :term:`PTCB` +from the local PTCB free pool and initializes it. Memory from the partition +buffer area is not used by RTEMS to store the PTCB. + +The PTCB for a global partition is allocated on the local node. Partitions +should not be made global unless remote tasks must interact with the partition. +This is to avoid the overhead incurred by the creation of a global partition. +When a global partition is created, the partition's name and identifier must be +transmitted to every node in the system for insertion in the local copy of the +global object table. + +.. 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. + +* When the directive operates on a global object, the directive sends a message + to remote nodes. This may preempt the calling task. + +* The number of partitions available to the application is configured through + the :ref:`CONFIGURE_MAXIMUM_PARTITIONS` application configuration option. + +* Where the object class corresponding to the directive is configured to use + unlimited objects, the directive may allocate memory from the RTEMS + Workspace. + +* The number of global objects available to the application is configured + through the :ref:`CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS` application + configuration option. + +.. Generated from spec:/rtems/part/if/ident + +.. raw:: latex + + \clearpage + +.. index:: rtems_partition_ident() +.. index:: get ID of a partition +.. index:: obtain ID of a partition + +.. _InterfaceRtemsPartitionIdent: + +rtems_partition_ident() +----------------------- + +Identifies a partition by the object name. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_partition_ident( + rtems_name name, + uint32_t node, + rtems_id *id + ); + +.. rubric:: PARAMETERS: + +``name`` + This parameter is the object name to look up. + +``node`` + This parameter is the node or node set to search for a matching object. + +``id`` + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the object identifier of an object with + the specified name will be stored in this object. + +.. rubric:: DESCRIPTION: + +This directive obtains a partition identifier associated with the partition +name specified in ``name``. + +The node to search is specified in ``node``. It shall be + +* a valid node number, + +* the constant :c:macro:`RTEMS_SEARCH_ALL_NODES` to search in all nodes, + +* the constant :c:macro:`RTEMS_SEARCH_LOCAL_NODE` to search in the local node + only, or + +* the constant :c:macro:`RTEMS_SEARCH_OTHER_NODES` to search in all nodes + except the local node. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``id`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_NAME` + The ``name`` parameter was 0. + +:c:macro:`RTEMS_INVALID_NAME` + There was no object with the specified name on the specified nodes. + +:c:macro:`RTEMS_INVALID_NODE` + In multiprocessing configurations, the specified node was invalid. + +.. rubric:: NOTES: + +If the partition name is not unique, then the partition identifier will match +the first partition with that name in the search order. However, this +partition identifier is not guaranteed to correspond to the desired partition. + +The objects are searched from lowest to the highest index. If ``node`` is +:c:macro:`RTEMS_SEARCH_ALL_NODES`, all nodes are searched with the local node +being searched first. All other nodes are searched from lowest to the highest +node number. + +If node is a valid node number which does not represent the local node, then +only the partitions exported by the designated node are searched. + +This directive does not generate activity on remote nodes. It accesses only +the local copy of the global object table. + +The partition identifier is used with other partition related directives to +access the partition. + +.. 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/part/if/delete + +.. raw:: latex + + \clearpage + +.. index:: rtems_partition_delete() +.. index:: delete a partition + +.. _InterfaceRtemsPartitionDelete: + +rtems_partition_delete() +------------------------ + +Deletes the partition. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_partition_delete( rtems_id id ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the partition identifier. + +.. rubric:: DESCRIPTION: + +This directive deletes the partition specified by ``id``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no partition associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT` + The partition resided on a remote node. + +:c:macro:`RTEMS_RESOURCE_IN_USE` + There were buffers of the partition still in use. + +.. rubric:: NOTES: + +The partition cannot be deleted if any of its buffers are still allocated. + +The :term:`PTCB` for the deleted partition is reclaimed by RTEMS. + +When a global partition is deleted, the partition identifier must be +transmitted to every node in the system for deletion from the local copy of the +global object table. + +The partition must reside on the local node, even if the partition was created +with the :c:macro:`RTEMS_GLOBAL` attribute. + +.. 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. + +* When the directive operates on a global object, the directive sends a message + to remote nodes. This may preempt the calling task. + +* The calling task does not have to be the task that created the object. Any + local task that knows the object identifier can delete the object. + +* Where the object class corresponding to the directive is configured to use + unlimited objects, the directive may free memory to the RTEMS Workspace. + +.. Generated from spec:/rtems/part/if/get-buffer + +.. raw:: latex + + \clearpage + +.. index:: rtems_partition_get_buffer() +.. index:: get buffer from partition +.. index:: obtain buffer from partition + +.. _InterfaceRtemsPartitionGetBuffer: + +rtems_partition_get_buffer() +---------------------------- + +Tries to get a buffer from the partition. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_partition_get_buffer( rtems_id id, void **buffer ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the partition identifier. + +``buffer`` + This parameter is the pointer to a ``void`` pointer object. When the + directive call is successful, the pointer to the allocated buffer will be + stored in this object. + +.. rubric:: DESCRIPTION: + +This directive allows a buffer to be obtained from the partition specified by +``id``. The address of the allocated buffer is returned through the ``buffer`` +parameter. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no partition associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``buffer`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_UNSATISFIED` + There was no free buffer available to allocate and return. + +.. rubric:: NOTES: + +The buffer start alignment is determined by the memory area and buffer size +used to create the partition. + +A task cannot wait on a buffer to become available. + +Getting a buffer from a global partition which does not reside on the local +node will generate a request telling the remote node to allocate a buffer from +the partition. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* When the directive operates on a local object, the directive may be called + from within interrupt context. + +* The directive may be called from within task context. + +* When the directive operates on a local object, the directive will not cause + the calling task to be preempted. + +* When the directive operates on a remote object, the directive sends a message + to the remote node and waits for a reply. This will preempt the calling + task. + +.. Generated from spec:/rtems/part/if/return-buffer + +.. raw:: latex + + \clearpage + +.. index:: rtems_partition_return_buffer() +.. index:: return buffer to partition + +.. _InterfaceRtemsPartitionReturnBuffer: + +rtems_partition_return_buffer() +------------------------------- + +Returns the buffer to the partition. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_partition_return_buffer( rtems_id id, void *buffer ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the partition identifier. + +``buffer`` + This parameter is the pointer to the buffer to return. + +.. rubric:: DESCRIPTION: + +This directive returns the buffer specified by ``buffer`` to the partition +specified by ``id``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no partition associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The buffer referenced by ``buffer`` was not in the partition. + +.. rubric:: NOTES: + +Returning a buffer multiple times is an error. It will corrupt the internal +state of the partition. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* When the directive operates on a local object, the directive may be called + from within interrupt context. + +* The directive may be called from within task context. + +* When the directive operates on a local object, the directive will not cause + the calling task to be preempted. + +* When the directive operates on a remote object, the directive sends a message + to the remote node and waits for a reply. This will preempt the calling + task. diff --git a/c-user/partition/index.rst b/c-user/partition/index.rst new file mode 100644 index 0000000..652fdfa --- /dev/null +++ b/c-user/partition/index.rst @@ -0,0 +1,17 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 embedded brains GmbH & Co. KG + +.. index:: partitions + +.. _RTEMSAPIClassicPart: + +Partition Manager +***************** + +.. toctree:: + + introduction + background + operations + directives diff --git a/c-user/partition/introduction.rst b/c-user/partition/introduction.rst new file mode 100644 index 0000000..ca26de9 --- /dev/null +++ b/c-user/partition/introduction.rst @@ -0,0 +1,49 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/rtems/part/if/group + +.. _PartitionManagerIntroduction: + +Introduction +============ + +.. The following list was generated from: +.. spec:/rtems/part/if/create +.. spec:/rtems/part/if/ident +.. spec:/rtems/part/if/delete +.. spec:/rtems/part/if/get-buffer +.. spec:/rtems/part/if/return-buffer + +The Partition Manager provides facilities to dynamically allocate memory in +fixed-size units. The directives provided by the Partition Manager are: + +* :ref:`InterfaceRtemsPartitionCreate` - Creates a partition. + +* :ref:`InterfaceRtemsPartitionIdent` - Identifies a partition by the object + name. + +* :ref:`InterfaceRtemsPartitionDelete` - Deletes the partition. + +* :ref:`InterfaceRtemsPartitionGetBuffer` - Tries to get a buffer from the + partition. + +* :ref:`InterfaceRtemsPartitionReturnBuffer` - Returns the buffer to the + partition. diff --git a/c-user/partition/operations.rst b/c-user/partition/operations.rst new file mode 100644 index 0000000..d0eff5b --- /dev/null +++ b/c-user/partition/operations.rst @@ -0,0 +1,55 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Operations +========== + +Creating a Partition +-------------------- + +The ``rtems_partition_create`` directive creates a partition with a +user-specified name. The partition's name, starting address, length and buffer +size are all specified to the ``rtems_partition_create`` directive. RTEMS +allocates a Partition Control Block (PTCB) from the PTCB free list. This data +structure is used by RTEMS to manage the newly created partition. The number +of buffers in the partition is calculated based upon the specified partition +length and buffer size. If successful,the unique partition ID is returned to +the calling task. + +Obtaining Partition IDs +----------------------- + +When a partition is created, RTEMS generates a unique partition ID and assigned +it to the created partition until it is deleted. The partition ID may be +obtained by either of two methods. First, as the result of an invocation of +the ``rtems_partition_create`` directive, the partition ID is stored in a user +provided location. Second, the partition ID may be obtained later using the +``rtems_partition_ident`` directive. The partition ID is used by other +partition manager directives to access this partition. + +Acquiring a Buffer +------------------ + +A buffer can be obtained by calling the ``rtems_partition_get_buffer`` +directive. If a buffer is available, then it is returned immediately with a +successful return code. Otherwise, an unsuccessful return code is returned +immediately to the caller. Tasks cannot block to wait for a buffer to become +available. + +Releasing a Buffer +------------------ + +Buffers are returned to a partition's free buffer chain with the +``rtems_partition_return_buffer`` directive. This directive returns an error +status code if the returned buffer was not previously allocated from this +partition. + +Deleting a Partition +-------------------- + +The ``rtems_partition_delete`` directive allows a partition to be removed and +returned to RTEMS. When a partition is deleted, the PTCB for that partition is +returned to the PTCB free list. A partition with buffers still allocated +cannot be deleted. Any task attempting to do so will be returned an error +status code. diff --git a/c-user/partition_manager.rst b/c-user/partition_manager.rst deleted file mode 100644 index 0590c0b..0000000 --- a/c-user/partition_manager.rst +++ /dev/null @@ -1,469 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-4.0 - -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) - -.. index:: partitions - -Partition Manager -***************** - -Introduction -============ - -The partition manager provides facilities to dynamically allocate memory in -fixed-size units. The directives provided by the partition manager are: - -- rtems_partition_create_ - Create a partition - -- rtems_partition_ident_ - Get ID of a partition - -- rtems_partition_delete_ - Delete a partition - -- rtems_partition_get_buffer_ - Get buffer from a partition - -- rtems_partition_return_buffer_ - Return buffer to a partition - -Background -========== - -.. index:: partition, definition - -Partition Manager Definitions ------------------------------ - -A partition is a physically contiguous memory area divided into fixed-size -buffers that can be dynamically allocated and deallocated. - -.. index:: buffers, definition - -Partitions are managed and maintained as a list of buffers. Buffers are -obtained from the front of the partition's free buffer chain and returned to -the rear of the same chain. When a buffer is on the free buffer chain, RTEMS -uses two pointers of memory from each buffer as the free buffer chain. When a -buffer is allocated, the entire buffer is available for application use. -Therefore, modifying memory that is outside of an allocated buffer could -destroy the free buffer chain or the contents of an adjacent allocated buffer. - -.. index:: partition attribute set, building - -Building a Partition Attribute Set ----------------------------------- - -In general, an attribute set is built by a bitwise OR of the desired attribute -components. The set of valid partition attributes is provided in the following -table: - -.. list-table:: - :class: rtems-table - - * - ``RTEMS_LOCAL`` - - local partition (default) - * - ``RTEMS_GLOBAL`` - - global partition - -Attribute values are specifically designed to be mutually exclusive, therefore -bitwise OR and addition operations are equivalent as long as each attribute -appears exactly once in the component list. An attribute listed as a default -is not required to appear in the attribute list, although it is a good -programming practice to specify default attributes. If all defaults are -desired, the attribute ``RTEMS_DEFAULT_ATTRIBUTES`` should be specified on this -call. The attribute_set parameter should be ``RTEMS_GLOBAL`` to indicate that -the partition is to be known globally. - -Operations -========== - -Creating a Partition --------------------- - -The ``rtems_partition_create`` directive creates a partition with a -user-specified name. The partition's name, starting address, length and buffer -size are all specified to the ``rtems_partition_create`` directive. RTEMS -allocates a Partition Control Block (PTCB) from the PTCB free list. This data -structure is used by RTEMS to manage the newly created partition. The number -of buffers in the partition is calculated based upon the specified partition -length and buffer size. If successful,the unique partition ID is returned to -the calling task. - -Obtaining Partition IDs ------------------------ - -When a partition is created, RTEMS generates a unique partition ID and assigned -it to the created partition until it is deleted. The partition ID may be -obtained by either of two methods. First, as the result of an invocation of -the ``rtems_partition_create`` directive, the partition ID is stored in a user -provided location. Second, the partition ID may be obtained later using the -``rtems_partition_ident`` directive. The partition ID is used by other -partition manager directives to access this partition. - -Acquiring a Buffer ------------------- - -A buffer can be obtained by calling the ``rtems_partition_get_buffer`` -directive. If a buffer is available, then it is returned immediately with a -successful return code. Otherwise, an unsuccessful return code is returned -immediately to the caller. Tasks cannot block to wait for a buffer to become -available. - -Releasing a Buffer ------------------- - -Buffers are returned to a partition's free buffer chain with the -``rtems_partition_return_buffer`` directive. This directive returns an error -status code if the returned buffer was not previously allocated from this -partition. - -Deleting a Partition --------------------- - -The ``rtems_partition_delete`` directive allows a partition to be removed and -returned to RTEMS. When a partition is deleted, the PTCB for that partition is -returned to the PTCB free list. A partition with buffers still allocated -cannot be deleted. Any task attempting to do so will be returned an error -status code. - -Directives -========== - -This section details the partition manager's directives. A subsection is -dedicated to each of this manager's directives and describes the calling -sequence, related constants, usage, and status codes. - -.. raw:: latex - - \clearpage - -.. index:: create a partition -.. index:: rtems_partition_create - -.. _rtems_partition_create: - -PARTITION_CREATE - Create a partition -------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_partition_create( - rtems_name name, - void *starting_address, - uintptr_t length, - size_t buffer_size, - rtems_attribute attribute_set, - rtems_id *id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - partition created successfully - * - ``RTEMS_INVALID_NAME`` - - invalid partition ``name`` - * - ``RTEMS_TOO_MANY`` - - too many partitions created - * - ``RTEMS_INVALID_ADDRESS`` - - ``starting_address`` is not on a pointer size boundary - * - ``RTEMS_INVALID_ADDRESS`` - - ``starting_address`` is NULL - * - ``RTEMS_INVALID_ADDRESS`` - - ``id`` is NULL - * - ``RTEMS_INVALID_SIZE`` - - ``length`` or ``buffer_size`` is 0 - * - ``RTEMS_INVALID_SIZE`` - - ``length`` is less than the ``buffer_size`` - * - ``RTEMS_INVALID_SIZE`` - - ``buffer_size`` is not an integral multiple of the pointer size - * - ``RTEMS_INVALID_SIZE`` - - ``buffer_size`` is less than two times the pointer size - * - ``RTEMS_MP_NOT_CONFIGURED`` - - multiprocessing not configured - * - ``RTEMS_TOO_MANY`` - - too many global objects - -DESCRIPTION: - This directive creates a partition of fixed size buffers from a physically - contiguous memory space which starts at starting_address and is length - bytes in size. Each allocated buffer is to be of ``buffer_size`` in bytes. - The assigned partition id is returned in ``id``. This partition id is used - to access the partition with other partition related directives. For - control and maintenance of the partition, RTEMS allocates a PTCB from the - local PTCB free pool and initializes it. - -NOTES: - This directive will not cause the calling task to be preempted. - - The partition buffer area specified by the ``starting_address`` must be - properly aligned. It must be possible to directly store target - architecture pointers and the also the user data. For example, if the user - data contains some long double or vector data types, the partition buffer - area and the buffer size must take the alignment of these types into - account which is usually larger than the pointer alignment. A cache line - alignment may be also a factor. - - The ``buffer_size`` parameter must be an integral multiple of the pointer - size on the target architecture. Additionally, ``buffer_size`` must be - large enough to hold two pointers on the target architecture. This is - required for RTEMS to manage the buffers when they are free. - - Memory from the partition is not used by RTEMS to store the Partition - Control Block. - - The following partition attribute constants are defined by RTEMS: - - .. list-table:: - :class: rtems-table - - * - ``RTEMS_LOCAL`` - - local partition (default) - * - ``RTEMS_GLOBAL`` - - global partition - - The PTCB for a global partition is allocated on the local node. The memory - space used for the partition must reside in shared memory. Partitions - should not be made global unless remote tasks must interact with the - partition. This is to avoid the overhead incurred by the creation of a - global partition. When a global partition is created, the partition's name - and id must be transmitted to every node in the system for insertion in the - local copy of the global object table. - - The total number of global objects, including partitions, is limited by the - maximum_global_objects field in the Configuration Table. - -EXAMPLE: - .. code-block:: c - - #include <rtems.h> - #include <rtems/chain.h> - - #include <assert.h> - - typedef struct { - char less; - short more; - } item; - - union { - item data; - rtems_chain_node node; - } items[ 13 ]; - - rtems_id create_partition(void) - { - rtems_id id; - rtems_status_code sc; - - sc = rtems_partition_create( - rtems_build_name( 'P', 'A', 'R', 'T' ), - items, - sizeof( items ), - sizeof( items[ 0 ] ), - RTEMS_DEFAULT_ATTRIBUTES, - &id - ); - assert(sc == RTEMS_SUCCESSFUL); - - return id; - } - -.. raw:: latex - - \clearpage - -.. index:: get ID of a partition -.. index:: obtain ID of a partition -.. index:: rtems_partition_ident - -.. _rtems_partition_ident: - -PARTITION_IDENT - Get ID of a partition ---------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_partition_ident( - rtems_name name, - uint32_t node, - rtems_id *id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - partition identified successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``id`` is NULL - * - ``RTEMS_INVALID_NAME`` - - partition name not found - * - ``RTEMS_INVALID_NODE`` - - invalid node id - -DESCRIPTION: - This directive obtains the partition id associated with the partition name. - If the partition name is not unique, then the partition id will match one - of the partitions with that name. However, this partition id is not - guaranteed to correspond to the desired partition. The partition id is - used with other partition related directives to access the partition. - -NOTES: - This directive will not cause the running task to be preempted. - - If node is ``RTEMS_SEARCH_ALL_NODES``, all nodes are searched with the - local node being searched first. All other nodes are searched with the - lowest numbered node searched first. - - If node is a valid node number which does not represent the local node, - then only the partitions exported by the designated node are searched. - - This directive does not generate activity on remote nodes. It accesses - only the local copy of the global object table. - -.. raw:: latex - - \clearpage - -.. index:: delete a partition -.. index:: rtems_partition_delete - -.. _rtems_partition_delete: - -PARTITION_DELETE - Delete a partition -------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_partition_delete( - rtems_id id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - partition deleted successfully - * - ``RTEMS_INVALID_ID`` - - invalid partition id - * - ``RTEMS_RESOURCE_IN_USE`` - - buffers still in use - * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - - cannot delete remote partition - -DESCRIPTION: - This directive deletes the partition specified by id. The partition cannot - be deleted if any of its buffers are still allocated. The PTCB for the - deleted partition is reclaimed by RTEMS. - -NOTES: - This directive will not cause the calling task to be preempted. - - The calling task does not have to be the task that created the partition. - Any local task that knows the partition id can delete the partition. - - When a global partition is deleted, the partition id must be transmitted to - every node in the system for deletion from the local copy of the global - object table. - - The partition must reside on the local node, even if the partition was - created with the ``RTEMS_GLOBAL`` option. - -.. raw:: latex - - \clearpage - -.. index:: get buffer from partition -.. index:: obtain buffer from partition -.. index:: rtems_partition_get_buffer - -.. _rtems_partition_get_buffer: - -PARTITION_GET_BUFFER - Get buffer from a partition --------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_partition_get_buffer( - rtems_id id, - void **buffer - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - buffer obtained successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``buffer`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid partition id - * - ``RTEMS_UNSATISFIED`` - - all buffers are allocated - -DESCRIPTION: - This directive allows a buffer to be obtained from the partition specified - in id. The address of the allocated buffer is returned in buffer. - -NOTES: - This directive will not cause the running task to be preempted. - - All buffers begin on a four byte boundary. - - A task cannot wait on a buffer to become available. - - Getting a buffer from a global partition which does not reside on the local - node will generate a request telling the remote node to allocate a buffer - from the specified partition. - -.. raw:: latex - - \clearpage - -.. index:: return buffer to partitition -.. index:: rtems_partition_return_buffer - -.. _rtems_partition_return_buffer: - -PARTITION_RETURN_BUFFER - Return buffer to a partition ------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_partition_return_buffer( - rtems_id id, - void *buffer - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - buffer returned successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``buffer`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid partition id - * - ``RTEMS_INVALID_ADDRESS`` - - buffer address not in partition - -DESCRIPTION: - This directive returns the buffer specified by buffer to the partition - specified by id. - -NOTES: - This directive will not cause the running task to be preempted. - - Returning a buffer to a global partition which does not reside on the local - node will generate a request telling the remote node to return the buffer - to the specified partition. - - Returning a buffer multiple times is an error. It will corrupt the - internal state of the partition. diff --git a/c-user/rate-monotonic/background.rst b/c-user/rate-monotonic/background.rst new file mode 100644 index 0000000..af54591 --- /dev/null +++ b/c-user/rate-monotonic/background.rst @@ -0,0 +1,393 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +.. Copyright (C) 2017 Kuan-Hsun Chen. + +Background +========== + +The rate monotonic manager provides facilities to manage the execution of +periodic tasks. This manager was designed to support application designers who +utilize the Rate Monotonic Scheduling Algorithm (RMS) to ensure that their +periodic tasks will meet their deadlines, even under transient overload +conditions. Although designed for hard real-time systems, the services +provided by the rate monotonic manager may be used by any application which +requires periodic tasks. + +Rate Monotonic Manager Required Support +--------------------------------------- + +A clock tick is required to support the functionality provided by this manager. + +Period Statistics +----------------- + +This manager maintains a set of statistics on each period object. These +statistics are reset implictly at period creation time and may be reset or +obtained at any time by the application. The following is a list of the +information kept: + +``owner`` + is the id of the thread that owns this period. + +``count`` + is the total number of periods executed. + +``missed_count`` + is the number of periods that were missed. + +``min_cpu_time`` + is the minimum amount of CPU execution time consumed on any execution of the + periodic loop. + +``max_cpu_time`` + is the maximum amount of CPU execution time consumed on any execution of the + periodic loop. + +``total_cpu_time`` + is the total amount of CPU execution time consumed by executions of the + periodic loop. + +``min_wall_time`` + is the minimum amount of wall time that passed on any execution of the + periodic loop. + +``max_wall_time`` + is the maximum amount of wall time that passed on any execution of the + periodic loop. + +``total_wall_time`` + is the total amount of wall time that passed during executions of the + periodic loop. + +Each period is divided into two consecutive phases. The period starts with the +active phase of the task and is followed by the inactive phase of the task. In +the inactive phase the task is blocked and waits for the start of the next +period. The inactive phase is skipped in case of a period miss. The wall time +includes the time during the active phase of the task on which the task is not +executing on a processor. The task is either blocked (for example it waits for +a resource) or a higher priority tasks executes, thus preventing it from +executing. In case the wall time exceeds the period time, then this is a +period miss. The gap between the wall time and the period time is the margin +between a period miss or success. + +The period statistics information is inexpensive to maintain and can provide +very useful insights into the execution characteristics of a periodic task +loop. But it is just information. The period statistics reported must be +analyzed by the user in terms of what the applications is. For example, in an +application where priorities are assigned by the Rate Monotonic Algorithm, it +would be very undesirable for high priority (i.e. frequency) tasks to miss +their period. Similarly, in nearly any application, if a task were supposed to +execute its periodic loop every 10 milliseconds and it averaged 11 +milliseconds, then application requirements are not being met. + +The information reported can be used to determine the "hot spots" in the +application. Given a period's id, the user can determine the length of that +period. From that information and the CPU usage, the user can calculate the +percentage of CPU time consumed by that periodic task. For example, a task +executing for 20 milliseconds every 200 milliseconds is consuming 10 percent of +the processor's execution time. This is usually enough to make it a good +candidate for optimization. + +However, execution time alone is not enough to gauge the value of optimizing a +particular task. It is more important to optimize a task executing 2 +millisecond every 10 milliseconds (20 percent of the CPU) than one executing 10 +milliseconds every 100 (10 percent of the CPU). As a general rule of thumb, +the higher frequency at which a task executes, the more important it is to +optimize that task. + +.. index:: periodic task, definition + +Periodicity Definitions +---------------------------------- + +A periodic task is one which must be executed at a regular interval. The +interval between successive iterations of the task is referred to as its +period. Periodic tasks can be characterized by the length of their period and +execution time. The period and execution time of a task can be used to +determine the processor utilization for that task. Processor utilization is +the percentage of processor time used and can be calculated on a per-task or +system-wide basis. Typically, the task's worst-case execution time will be +less than its period. For example, a periodic task's requirements may state +that it should execute for 10 milliseconds every 100 milliseconds. Although +the execution time may be the average, worst, or best case, the worst-case +execution time is more appropriate for use when analyzing system behavior under +transient overload conditions. + +.. index:: aperiodic task, definition + +In contrast, an aperiodic task executes at irregular intervals and has only a +soft deadline. In other words, the deadlines for aperiodic tasks are not +rigid, but adequate response times are desirable. For example, an aperiodic +task may process user input from a terminal. + +.. index:: sporadic task, definition + +Finally, a sporadic task is an aperiodic task with a hard deadline and minimum +interarrival time. The minimum interarrival time is the minimum period of time +which exists between successive iterations of the task. For example, a +sporadic task could be used to process the pressing of a fire button on a +joystick. The mechanical action of the fire button ensures a minimum time +period between successive activations, but the missile must be launched by a +hard deadline. + +.. index:: Rate Monotonic Scheduling Algorithm, definition +.. index:: RMS Algorithm, definition + +Rate Monotonic Scheduling Algorithm +----------------------------------- + +The Rate Monotonic Scheduling Algorithm (RMS) is important to real-time systems +designers because it allows one to sufficiently guarantee that a set of tasks +is schedulable (see :cite:`Liu:1973:Scheduling`, :cite:`Lehoczky:1989:RM`, +:cite:`Sha:1990:Ada`, :cite:`Burns:1991:Review`). + +A set of tasks is said to be schedulable if all of the tasks can meet their +deadlines. RMS provides a set of rules which can be used to perform +a guaranteed schedulability analysis for a task set. This analysis determines +whether a task set is schedulable under worst-case conditions and emphasizes +the predictability of the system's behavior. It has been proven that: + +.. sidebar:: *RMS* + + RMS is an optimal fixed-priority algorithm for scheduling independent, + preemptible, periodic tasks on a single processor. + +RMS is optimal in the sense that if a set of tasks can be scheduled by any +fixed-priority algorithm, then RMS will be able to schedule that task set. +RMS bases it schedulability analysis on the processor utilization level below +which all deadlines can be met. + +RMS calls for the static assignment of task priorities based upon their period. +The shorter a task's period, the higher its priority. For example, a task with +a 1 millisecond period has higher priority than a task with a 100 millisecond +period. If two tasks have the same period, then RMS does not distinguish +between the tasks. However, RTEMS specifies that when given tasks of equal +priority, the task which has been ready longest will execute first. RMS's +priority assignment scheme does not provide one with exact numeric values for +task priorities. For example, consider the following task set and priority +assignments: + ++--------------------+---------------------+---------------------+ +| Task | Period | Priority | +| | (in milliseconds) | | ++====================+=====================+=====================+ +| 1 | 100 | Low | ++--------------------+---------------------+---------------------+ +| 2 | 50 | Medium | ++--------------------+---------------------+---------------------+ +| 3 | 50 | Medium | ++--------------------+---------------------+---------------------+ +| 4 | 25 | High | ++--------------------+---------------------+---------------------+ + +RMS only calls for task 1 to have the lowest priority, task 4 to have the +highest priority, and tasks 2 and 3 to have an equal priority between that of +tasks 1 and 4. The actual RTEMS priorities assigned to the tasks must only +adhere to those guidelines. + +Many applications have tasks with both hard and soft deadlines. The tasks with +hard deadlines are typically referred to as the critical task set, with the +soft deadline tasks being the non-critical task set. The critical task set can +be scheduled using RMS, with the non-critical tasks not executing under +transient overload, by simply assigning priorities such that the lowest +priority critical task (i.e. longest period) has a higher priority than the +highest priority non-critical task. Although RMS may be used to assign +priorities to the non-critical tasks, it is not necessary. In this instance, +schedulability is only guaranteed for the critical task set. + +.. index:: RMS schedulability analysis + +Schedulability Analysis +----------------------- + +RMS allows application designers to ensure that tasks can meet all deadlines under fixed-priority assignment, +even under transient overload, without knowing exactly when any given task will +execute by applying proven schedulability analysis rules. + +Assumptions +^^^^^^^^^^^ + +The schedulability analysis rules for RMS were developed based on the following +assumptions: + +- The requests for all tasks for which hard deadlines exist are periodic, with + a constant interval between requests. + +- Each task must complete before the next request for it occurs. + +- The tasks are independent in that a task does not depend on the initiation or + completion of requests for other tasks. + +- The execution time for each task without preemption or interruption is + constant and does not vary. + +- Any non-periodic tasks in the system are special. These tasks should not + displace periodic tasks while executing and do not have hard, critical + deadlines. + +Once the basic schedulability analysis is understood, some of the above +assumptions can be relaxed and the side-effects accounted for. + +.. index:: RMS Processor Utilization Rule + +Processor Utilization Rule +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The Processor Utilization Rule requires that processor utilization be +calculated based upon the period and execution time of each task. +The fraction of processor time spent executing task index is ``Time(i) +/ Period(i)``. The processor utilization can be calculated as follows +where n is the number of tasks in the set being analyzed: + +.. math:: + + Utilization = \sum_{i=1}^{n} Time_i/Period_i + +To ensure schedulability even under transient overload, the processor +utilization must adhere to the following rule: + +.. math:: + + maximumUtilization = n * (2^{\frac{1}{n}} - 1) + +As the number of tasks increases, the above formula approaches ln(2) for a +worst-case utilization factor of approximately 0.693. Many tasks sets can be +scheduled with a greater utilization factor. In fact, the average processor +utilization threshold for a randomly generated task set is approximately 0.88. +See more detail in :cite:`Liu:1973:Scheduling`. + +Processor Utilization Rule Example +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This example illustrates the application of the Processor Utilization Rule to +an application with three critical periodic tasks. The following table details +the RMS priority, period, execution time, and processor utilization for each +task: + ++------------+----------+--------+-----------+-------------+ +| Task | RMS | Period | Execution | Processor | +| | Priority | | Time | Utilization | ++============+==========+========+===========+=============+ +| 1 | High | 100 | 15 | 0.15 | ++------------+----------+--------+-----------+-------------+ +| 2 | Medium | 200 | 50 | 0.25 | ++------------+----------+--------+-----------+-------------+ +| 3 | Low | 300 | 100 | 0.33 | ++------------+----------+--------+-----------+-------------+ + +The total processor utilization for this task set is 0.73 which is below the +upper bound of 3 * (2**(1/3) - 1), or 0.779, imposed by the Processor +Utilization Rule. Therefore, this task set is guaranteed to be schedulable +using RMS. + +.. index:: RMS First Deadline Rule + +First Deadline Rule +^^^^^^^^^^^^^^^^^^^ + +If a given set of tasks do exceed the processor utilization upper limit imposed +by the Processor Utilization Rule, they can still be guaranteed to meet all +their deadlines by application of the First Deadline Rule. This rule can be +stated as follows: + + For a given set of independent periodic tasks, if each task meets its first + deadline when all tasks are started at the same time, then the + deadlines will always be met for any combination of start times. + +A key point with this rule is that ALL periodic tasks are assumed to start at +the exact same instant in time. Although this assumption may seem to be +invalid, RTEMS makes it quite easy to ensure. By having a non-preemptible user +initialization task, all application tasks, regardless of priority, can be +created and started before the initialization deletes itself. This technique +ensures that all tasks begin to compete for execution time at the same instant +- when the user initialization task deletes itself. +See more detail in :cite:`Lehoczky:1989:RM`. + +First Deadline Rule Example +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The First Deadline Rule can ensure schedulability even when the Processor +Utilization Rule fails. The example below is a modification of the Processor +Utilization Rule example where task execution time has been increased from 15 +to 25 units. The following table details the RMS priority, period, execution +time, and processor utilization for each task: + ++------------+----------+--------+-----------+-------------+ +| Task | RMS | Period | Execution | Processor | +| | Priority | | Time | Utilization | ++============+==========+========+===========+=============+ +| 1 | High | 100 | 25 | 0.25 | ++------------+----------+--------+-----------+-------------+ +| 2 | Medium | 200 | 50 | 0.25 | ++------------+----------+--------+-----------+-------------+ +| 3 | Low | 300 | 100 | 0.33 | ++------------+----------+--------+-----------+-------------+ + +The total processor utilization for the modified task set is 0.83 which is +above the upper bound of 3 * (2**(1/3) - 1), or 0.779, imposed by the Processor +Utilization Rule. Therefore, this task set is not guaranteed to be schedulable +using RMS. However, the First Deadline Rule can guarantee the schedulability +of this task set. This rule calls for one to examine each occurrence of +deadline until either all tasks have met their deadline or one task failed to +meet its first deadline. The following table details the time of each deadline +occurrence, the maximum number of times each task may have run, the total +execution time, and whether all the deadlines have been met: + ++----------+------+------+------+----------------------+---------------+ +| Deadline | Task | Task | Task | Total | All Deadlines | +| Time | 1 | 2 | 3 | Execution Time | Met? | ++==========+======+======+======+======================+===============+ +| 100 | 1 | 1 | 1 | 25 + 50 + 100 = 175 | NO | ++----------+------+------+------+----------------------+---------------+ +| 200 | 2 | 1 | 1 | 50 + 50 + 100 = 200 | YES | ++----------+------+------+------+----------------------+---------------+ + +The key to this analysis is to recognize when each task will execute. For +example at time 100, task 1 must have met its first deadline, but tasks 2 and 3 +may also have begun execution. In this example, at time 100 tasks 1 and 2 have +completed execution and thus have met their first deadline. Tasks 1 and 2 have +used (25 + 50) = 75 time units, leaving (100 - 75) = 25 time units for task 3 +to begin. Because task 3 takes 100 ticks to execute, it will not have +completed execution at time 100. Thus at time 100, all of the tasks except +task 3 have met their first deadline. + +At time 200, task 1 must have met its second deadline and task 2 its first +deadline. As a result, of the first 200 time units, task 1 uses (2 * 25) = 50 +and task 2 uses 50, leaving (200 - 100) time units for task 3. Task 3 requires +100 time units to execute, thus it will have completed execution at time 200. +Thus, all of the tasks have met their first deadlines at time 200, and the task +set is schedulable using the First Deadline Rule. + +Relaxation of Assumptions +^^^^^^^^^^^^^^^^^^^^^^^^^ + +The assumptions used to develop the RMS schedulability rules are uncommon in +most real-time systems. For example, it was assumed that tasks have constant +unvarying execution time. It is possible to relax this assumption, simply by +using the worst-case execution time of each task. + +Another assumption is that the tasks are independent. This means that the +tasks do not wait for one another or contend for resources. This assumption +can be relaxed by accounting for the amount of time a task spends waiting to +acquire resources. Similarly, each task's execution time must account for any +I/O performed and any RTEMS directive calls. + +In addition, the assumptions did not account for the time spent executing +interrupt service routines. This can be accounted for by including all the +processor utilization by interrupt service routines in the utilization +calculation. Similarly, one should also account for the impact of delays in +accessing local memory caused by direct memory access and other processors +accessing local dual-ported memory. + +The assumption that nonperiodic tasks are used only for initialization or +failure-recovery can be relaxed by placing all periodic tasks in the critical +task set. This task set can be scheduled and analyzed using RMS. All +nonperiodic tasks are placed in the non-critical task set. Although the +critical task set can be guaranteed to execute even under transient overload, +the non-critical task set is not guaranteed to execute. + +In conclusion, the application designer must be fully cognizant of the system +and its run-time behavior when performing schedulability analysis for a system +using RMS. Every hardware and software factor which impacts the execution time +of each task must be accounted for in the schedulability analysis. diff --git a/c-user/rate-monotonic/directives.rst b/c-user/rate-monotonic/directives.rst new file mode 100644 index 0000000..f0467d1 --- /dev/null +++ b/c-user/rate-monotonic/directives.rst @@ -0,0 +1,720 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 2017 Kuan-Hsun Chen +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. _RateMonotonicManagerDirectives: + +Directives +========== + +This section details the directives of the Rate-Monotonic Manager. A subsection +is dedicated to each of this manager's directives and lists the calling +sequence, parameters, description, return values, and notes of the directive. + +.. Generated from spec:/rtems/ratemon/if/create + +.. raw:: latex + + \clearpage + +.. index:: rtems_rate_monotonic_create() +.. index:: create a period + +.. _InterfaceRtemsRateMonotonicCreate: + +rtems_rate_monotonic_create() +----------------------------- + +Creates a period. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_rate_monotonic_create( rtems_name name, rtems_id *id ); + +.. rubric:: PARAMETERS: + +``name`` + This parameter is the object name of the period. + +``id`` + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the identifier of the created period will + be stored in this object. + +.. rubric:: DESCRIPTION: + +This directive creates a period which resides on the local node. The period +has the user-defined object name specified in ``name`` The assigned object +identifier is returned in ``id``. This identifier is used to access the period +with other rate monotonic related directives. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_NAME` + The ``name`` parameter was invalid. + +:c:macro:`RTEMS_TOO_MANY` + There was no inactive object available to create a period. The number of + periods available to the application is configured through the + :ref:`CONFIGURE_MAXIMUM_PERIODS` application configuration option. + +.. rubric:: NOTES: + +The calling task is registered as the owner of the created period. Some +directives can be only used by this task for the created period. + +For control and maintenance of the period, RTEMS allocates a :term:`PCB` from +the local PCB free pool and initializes it. + +.. 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. + +* The number of periods available to the application is configured through the + :ref:`CONFIGURE_MAXIMUM_PERIODS` application configuration option. + +* Where the object class corresponding to the directive is configured to use + unlimited objects, the directive may allocate memory from the RTEMS + Workspace. + +.. Generated from spec:/rtems/ratemon/if/ident + +.. raw:: latex + + \clearpage + +.. index:: rtems_rate_monotonic_ident() + +.. _InterfaceRtemsRateMonotonicIdent: + +rtems_rate_monotonic_ident() +---------------------------- + +Identifies a period by the object name. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_rate_monotonic_ident( rtems_name name, rtems_id *id ); + +.. rubric:: PARAMETERS: + +``name`` + This parameter is the object name to look up. + +``id`` + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the object identifier of an object with + the specified name will be stored in this object. + +.. rubric:: DESCRIPTION: + +This directive obtains a period identifier associated with the period name +specified in ``name``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``id`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_NAME` + The ``name`` parameter was 0. + +:c:macro:`RTEMS_INVALID_NAME` + There was no object with the specified name on the local node. + +.. rubric:: NOTES: + +If the period name is not unique, then the period identifier will match the +first period with that name in the search order. However, this period +identifier is not guaranteed to correspond to the desired period. + +The objects are searched from lowest to the highest index. Only the local node +is searched. + +The period identifier is used with other rate monotonic related directives to +access the period. + +.. 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/ratemon/if/cancel + +.. raw:: latex + + \clearpage + +.. index:: rtems_rate_monotonic_cancel() +.. index:: cancel a period + +.. _InterfaceRtemsRateMonotonicCancel: + +rtems_rate_monotonic_cancel() +----------------------------- + +Cancels the period. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_rate_monotonic_cancel( rtems_id id ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the rate monotonic period identifier. + +.. rubric:: DESCRIPTION: + +This directive cancels the rate monotonic period specified by ``id``. This +period may be reinitiated by the next invocation of +:ref:`InterfaceRtemsRateMonotonicPeriod`. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no rate monotonic period associated with the identifier specified + by ``id``. + +:c:macro:`RTEMS_NOT_OWNER_OF_RESOURCE` + The rate monotonic period was not created by the calling task. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +* The directive may be used exclusively by the task which created the + associated object. + +.. Generated from spec:/rtems/ratemon/if/delete + +.. raw:: latex + + \clearpage + +.. index:: rtems_rate_monotonic_delete() +.. index:: delete a period + +.. _InterfaceRtemsRateMonotonicDelete: + +rtems_rate_monotonic_delete() +----------------------------- + +Deletes the period. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_rate_monotonic_delete( rtems_id id ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the period identifier. + +.. rubric:: DESCRIPTION: + +This directive deletes the period specified by ``id``. If the period is +running, it is automatically canceled. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no period associated with the identifier specified by ``id``. + +.. rubric:: NOTES: + +The :term:`PCB` for the deleted period is reclaimed by RTEMS. + +.. 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. + +* The calling task does not have to be the task that created the object. Any + local task that knows the object identifier can delete the object. + +* Where the object class corresponding to the directive is configured to use + unlimited objects, the directive may free memory to the RTEMS Workspace. + +.. Generated from spec:/rtems/ratemon/if/period + +.. raw:: latex + + \clearpage + +.. index:: rtems_rate_monotonic_period() +.. index:: conclude current period +.. index:: start current period +.. index:: period initiation + +.. _InterfaceRtemsRateMonotonicPeriod: + +rtems_rate_monotonic_period() +----------------------------- + +Concludes the current period and start the next period, or gets the period +status. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_rate_monotonic_period( + rtems_id id, + rtems_interval length + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the rate monotonic period identifier. + +``length`` + This parameter is the period length in :term:`clock ticks <clock tick>` or + :c:macro:`RTEMS_PERIOD_STATUS` to get the period status. + +.. rubric:: DESCRIPTION: + +This directive initiates the rate monotonic period specified by ``id`` with a +length of period ticks specified by ``length``. If the period is running, then +the calling task will block for the remainder of the period before reinitiating +the period with the specified period length. If the period was not running +(either expired or never initiated), the period is immediately initiated and +the directive returns immediately. If the period has expired, the postponed +job will be released immediately and the following calls of this directive will +release postponed jobs until there is no more deadline miss. + +If invoked with a period length of :c:macro:`RTEMS_PERIOD_STATUS` ticks, the +current state of the period will be returned. The directive status indicates +the current state of the period. This does not alter the state or period +length of the period. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no rate monotonic period associated with the identifier specified + by ``id``. + +:c:macro:`RTEMS_NOT_OWNER_OF_RESOURCE` + The rate monotonic period was not created by the calling task. + +:c:macro:`RTEMS_NOT_DEFINED` + The rate monotonic period has never been initiated (only possible when the + ``length`` parameter was equal to :c:macro:`RTEMS_PERIOD_STATUS`). + +:c:macro:`RTEMS_TIMEOUT` + The rate monotonic period has expired. + +.. rubric:: NOTES: + +Resetting the processor usage time of tasks has no impact on the period status +and statistics. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within task context. + +* The directive may be used exclusively by the task which created the + associated object. + +.. Generated from spec:/rtems/ratemon/if/get-status + +.. raw:: latex + + \clearpage + +.. index:: rtems_rate_monotonic_get_status() +.. index:: get status of period +.. index:: obtain status of period + +.. _InterfaceRtemsRateMonotonicGetStatus: + +rtems_rate_monotonic_get_status() +--------------------------------- + +Gets the detailed status of the period. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_rate_monotonic_get_status( + rtems_id id, + rtems_rate_monotonic_period_status *status + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the rate monotonic period identifier. + +``status`` + This parameter is the pointer to an + :ref:`InterfaceRtemsRateMonotonicPeriodStatus` object. When the directive + call is successful, the detailed period status will be stored in this + object. + +.. rubric:: DESCRIPTION: + +This directive returns the detailed status of the rate monotonic period +specified by ``id``. The detailed status of the period will be returned in the +members of the period status object referenced by ``status``: + +* The ``owner`` member is set to the identifier of the owner task of the + period. + +* The ``state`` member is set to the current state of the period. + +* The ``postponed_jobs_count`` member is set to the count of jobs which are not + released yet. + +* If the current state of the period is :c:macro:`RATE_MONOTONIC_INACTIVE`, the + ``since_last_period`` and ``executed_since_last_period`` members will be set + to zero. Otherwise, both members will contain time information since the + last successful invocation of the :ref:`InterfaceRtemsRateMonotonicPeriod` + directive by the owner task. More specifically, the ``since_last_period`` + member will be set to the time elapsed since the last successful invocation. + The ``executed_since_last_period`` member will be set to the processor time + consumed by the owner task since the last successful invocation. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no rate monotonic period associated with the identifier specified + by ``id``. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``status`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within task context. + +* The directive may be called from within interrupt context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/ratemon/if/get-statistics + +.. raw:: latex + + \clearpage + +.. index:: rtems_rate_monotonic_get_statistics() +.. index:: get statistics of period +.. index:: obtain statistics of period + +.. _InterfaceRtemsRateMonotonicGetStatistics: + +rtems_rate_monotonic_get_statistics() +------------------------------------- + +Gets the statistics of the period. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_rate_monotonic_get_statistics( + rtems_id id, + rtems_rate_monotonic_period_statistics *status + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the rate monotonic period identifier. + +``status`` + This parameter is the pointer to an + :ref:`InterfaceRtemsRateMonotonicPeriodStatistics` object. When the + directive call is successful, the period statistics will be stored in this + object. + +.. rubric:: DESCRIPTION: + +This directive returns the statistics of the rate monotonic period specified by +``id``. The statistics of the period will be returned in the members of the +period statistics object referenced by ``status``: + +* The ``count`` member is set to the number of periods executed. + +* The ``missed_count`` member is set to the number of periods missed. + +* The ``min_cpu_time`` member is set to the least amount of processor time used + in the period. + +* The ``max_cpu_time`` member is set to the highest amount of processor time + used in the period. + +* The ``total_cpu_time`` member is set to the total amount of processor time + used in the period. + +* The ``min_wall_time`` member is set to the least amount of + :term:`CLOCK_MONOTONIC` time used in the period. + +* The ``max_wall_time`` member is set to the highest amount of + :term:`CLOCK_MONOTONIC` time used in the period. + +* The ``total_wall_time`` member is set to the total amount of + :term:`CLOCK_MONOTONIC` time used in the period. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no rate monotonic period associated with the identifier specified + by ``id``. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``status`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within task context. + +* The directive may be called from within interrupt context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/ratemon/if/reset-statistics + +.. raw:: latex + + \clearpage + +.. index:: rtems_rate_monotonic_reset_statistics() +.. index:: reset statistics of period + +.. _InterfaceRtemsRateMonotonicResetStatistics: + +rtems_rate_monotonic_reset_statistics() +--------------------------------------- + +Resets the statistics of the period. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_rate_monotonic_reset_statistics( rtems_id id ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the rate monotonic period identifier. + +.. rubric:: DESCRIPTION: + +This directive resets the statistics of the rate monotonic period specified by +``id``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no rate monotonic period associated with the identifier specified + by ``id``. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within task context. + +* The directive may be called from within interrupt context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/ratemon/if/reset-all-statistics + +.. raw:: latex + + \clearpage + +.. index:: rtems_rate_monotonic_reset_all_statistics() +.. index:: reset statistics of all periods + +.. _InterfaceRtemsRateMonotonicResetAllStatistics: + +rtems_rate_monotonic_reset_all_statistics() +------------------------------------------- + +Resets the statistics of all periods. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_rate_monotonic_reset_all_statistics( void ); + +.. rubric:: DESCRIPTION: + +This directive resets the statistics information associated with all rate +monotonic period instances. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* 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/ratemon/if/report-statistics + +.. raw:: latex + + \clearpage + +.. index:: rtems_rate_monotonic_report_statistics() +.. index:: print period statistics report +.. index:: period statistics report + +.. _InterfaceRtemsRateMonotonicReportStatistics: + +rtems_rate_monotonic_report_statistics() +---------------------------------------- + +Reports the period statistics using the :ref:`InterfacePrintk` printer. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_rate_monotonic_report_statistics( void ); + +.. rubric:: DESCRIPTION: + +This directive prints a report on all active periods which have executed at +least one period using the :ref:`InterfacePrintk` printer. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* 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/ratemon/if/report-statistics-with-plugin + +.. raw:: latex + + \clearpage + +.. index:: rtems_rate_monotonic_report_statistics_with_plugin() +.. index:: print period statistics report +.. index:: period statistics report + +.. _InterfaceRtemsRateMonotonicReportStatisticsWithPlugin: + +rtems_rate_monotonic_report_statistics_with_plugin() +---------------------------------------------------- + +Reports the period statistics using the printer plugin. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_rate_monotonic_report_statistics_with_plugin( + const struct rtems_printer *printer + ); + +.. rubric:: PARAMETERS: + +``printer`` + This parameter is the printer plugin to output the report. + +.. rubric:: DESCRIPTION: + +This directive prints a report on all active periods which have executed at +least one period using the printer plugin specified by ``printer``. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* 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. diff --git a/c-user/rate-monotonic/index.rst b/c-user/rate-monotonic/index.rst new file mode 100644 index 0000000..9c5b4b6 --- /dev/null +++ b/c-user/rate-monotonic/index.rst @@ -0,0 +1,18 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 embedded brains GmbH & Co. KG + +.. index:: rate mononitonic tasks +.. index:: periodic tasks + +.. _RTEMSAPIClassicRatemon: + +Rate Monotonic Manager +********************** + +.. toctree:: + + introduction + background + operations + directives diff --git a/c-user/rate-monotonic/introduction.rst b/c-user/rate-monotonic/introduction.rst new file mode 100644 index 0000000..b33b0b8 --- /dev/null +++ b/c-user/rate-monotonic/introduction.rst @@ -0,0 +1,76 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 2017 Kuan-Hsun Chen +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/rtems/ratemon/if/group + +.. _RateMonotonicManagerIntroduction: + +Introduction +============ + +.. The following list was generated from: +.. spec:/rtems/ratemon/if/create +.. spec:/rtems/ratemon/if/ident +.. spec:/rtems/ratemon/if/cancel +.. spec:/rtems/ratemon/if/delete +.. spec:/rtems/ratemon/if/period +.. spec:/rtems/ratemon/if/get-status +.. spec:/rtems/ratemon/if/get-statistics +.. spec:/rtems/ratemon/if/reset-statistics +.. spec:/rtems/ratemon/if/reset-all-statistics +.. spec:/rtems/ratemon/if/report-statistics +.. spec:/rtems/ratemon/if/report-statistics-with-plugin + +The Rate-Monotonic Manager provides facilities to implement tasks which execute +in a periodic fashion. Critically, it also gathers information about the +execution of those periods and can provide important statistics to the user +which can be used to analyze and tune the application. The directives provided +by the Rate-Monotonic Manager are: + +* :ref:`InterfaceRtemsRateMonotonicCreate` - Creates a period. + +* :ref:`InterfaceRtemsRateMonotonicIdent` - Identifies a period by the object + name. + +* :ref:`InterfaceRtemsRateMonotonicCancel` - Cancels the period. + +* :ref:`InterfaceRtemsRateMonotonicDelete` - Deletes the period. + +* :ref:`InterfaceRtemsRateMonotonicPeriod` - Concludes the current period and + start the next period, or gets the period status. + +* :ref:`InterfaceRtemsRateMonotonicGetStatus` - Gets the detailed status of the + period. + +* :ref:`InterfaceRtemsRateMonotonicGetStatistics` - Gets the statistics of the + period. + +* :ref:`InterfaceRtemsRateMonotonicResetStatistics` - Resets the statistics of + the period. + +* :ref:`InterfaceRtemsRateMonotonicResetAllStatistics` - Resets the statistics + of all periods. + +* :ref:`InterfaceRtemsRateMonotonicReportStatistics` - Reports the period + statistics using the :ref:`InterfacePrintk` printer. + +* :ref:`InterfaceRtemsRateMonotonicReportStatisticsWithPlugin` - Reports the + period statistics using the printer plugin. diff --git a/c-user/rate-monotonic/operations.rst b/c-user/rate-monotonic/operations.rst new file mode 100644 index 0000000..d7a91b1 --- /dev/null +++ b/c-user/rate-monotonic/operations.rst @@ -0,0 +1,200 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +.. Copyright (C) 2017 Kuan-Hsun Chen. + +Operations +========== + +Creating a Rate Monotonic Period +-------------------------------- + +The ``rtems_rate_monotonic_create`` directive creates a rate monotonic period +which is to be used by the calling task to delineate a period. RTEMS allocates +a Period Control Block (PCB) from the PCB free list. This data structure is +used by RTEMS to manage the newly created rate monotonic period. RTEMS returns +a unique period ID to the application which is used by other rate monotonic +manager directives to access this rate monotonic period. + +Manipulating a Period +--------------------- + +The ``rtems_rate_monotonic_period`` directive is used to establish and maintain +periodic execution utilizing a previously created rate monotonic period. Once +initiated by the ``rtems_rate_monotonic_period`` directive, the period is said +to run until it either expires or is reinitiated. The state of the rate +monotonic period results in one of the following scenarios: + +- If the rate monotonic period is running, the calling task will be blocked for + the remainder of the outstanding period and, upon completion of that period, + the period will be reinitiated with the specified period. + +- If the rate monotonic period is not currently running and has not expired, it + is initiated with a length of period ticks and the calling task returns + immediately. + +- If the rate monotonic period has expired before the task invokes the + ``rtems_rate_monotonic_period`` directive, the postponed job will be released + until there is no more postponed jobs. The calling task returns immediately + with a timeout error status. In the watchdog routine, the period will still + be updated periodically and track the count of the postponed jobs :cite:`Chen:2016:Overrun`. + Please note, the count of the postponed jobs is only saturated until 0xffffffff. + +Obtaining the Status of a Period +-------------------------------- + +If the ``rtems_rate_monotonic_period`` directive is invoked with a period of +``RTEMS_PERIOD_STATUS`` ticks, the current state of the specified rate +monotonic period will be returned. The following table details the +relationship between the period's status and the directive status code returned +by the ``rtems_rate_monotonic_period`` directive: + +.. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - period is running + * - ``RTEMS_TIMEOUT`` + - period has expired + * - ``RTEMS_NOT_DEFINED`` + - period has never been initiated + +Obtaining the status of a rate monotonic period does not alter the state or +length of that period. + +Canceling a Period +------------------ + +The ``rtems_rate_monotonic_cancel`` directive is used to stop the period +maintained by the specified rate monotonic period. The period is stopped and +the rate monotonic period can be reinitiated using the +``rtems_rate_monotonic_period`` directive. + +Deleting a Rate Monotonic Period +-------------------------------- + +The ``rtems_rate_monotonic_delete`` directive is used to delete a rate +monotonic period. If the period is running and has not expired, the period is +automatically canceled. The rate monotonic period's control block is returned +to the PCB free list when it is deleted. A rate monotonic period can be +deleted by a task other than the task which created the period. + +Examples +-------- + +The following sections illustrate common uses of rate monotonic periods to +construct periodic tasks. + +Simple Periodic Task +-------------------- + +This example consists of a single periodic task which, after initialization, +executes every 100 clock ticks. + +.. code-block:: c + :linenos: + + rtems_task Periodic_task(rtems_task_argument arg) + { + rtems_name name; + rtems_id period; + rtems_status_code status; + name = rtems_build_name( 'P', 'E', 'R', 'D' ); + status = rtems_rate_monotonic_create( name, &period ); + if ( status != RTEMS_SUCCESSFUL ) { + printf( "rtems_monotonic_create failed with status of %d.\n", status ); + exit( 1 ); + } + while ( 1 ) { + if ( rtems_rate_monotonic_period( period, 100 ) == RTEMS_TIMEOUT ) + break; + /* Perform some periodic actions */ + } + /* missed period so delete period and SELF */ + status = rtems_rate_monotonic_delete( period ); + if ( status != RTEMS_SUCCESSFUL ) { + printf( "rtems_rate_monotonic_delete failed with status of %d.\n", status ); + exit( 1 ); + } + status = rtems_task_delete( RTEMS_SELF ); /* should not return */ + printf( "rtems_task_delete returned with status of %d.\n", status ); + exit( 1 ); + } + +The above task creates a rate monotonic period as part of its initialization. +The first time the loop is executed, the ``rtems_rate_monotonic_period`` +directive will initiate the period for 100 ticks and return immediately. +Subsequent invocations of the ``rtems_rate_monotonic_period`` directive will +result in the task blocking for the remainder of the 100 tick period. If, for +any reason, the body of the loop takes more than 100 ticks to execute, the +``rtems_rate_monotonic_period`` directive will return the ``RTEMS_TIMEOUT`` +status. If the above task misses its deadline, it will delete the rate +monotonic period and itself. + +Task with Multiple Periods +-------------------------- + +This example consists of a single periodic task which, after initialization, +performs two sets of actions every 100 clock ticks. The first set of actions +is performed in the first forty clock ticks of every 100 clock ticks, while the +second set of actions is performed between the fortieth and seventieth clock +ticks. The last thirty clock ticks are not used by this task. + +.. code-block:: c + :linenos: + + rtems_task Periodic_task(rtems_task_argument arg) + { + rtems_name name_1, name_2; + rtems_id period_1, period_2; + name_1 = rtems_build_name( 'P', 'E', 'R', '1' ); + name_2 = rtems_build_name( 'P', 'E', 'R', '2' ); + (void ) rtems_rate_monotonic_create( name_1, &period_1 ); + (void ) rtems_rate_monotonic_create( name_2, &period_2 ); + while ( 1 ) { + if ( rtems_rate_monotonic_period( period_1, 100 ) == RTEMS_TIMEOUT ) + break; + if ( rtems_rate_monotonic_period( period_2, 40 ) == RTEMS_TIMEOUT ) + break; + /* + * Perform first set of actions between clock + * ticks 0 and 39 of every 100 ticks. + */ + if ( rtems_rate_monotonic_period( period_2, 30 ) == RTEMS_TIMEOUT ) + break; + /* + * Perform second set of actions between clock 40 and 69 + * of every 100 ticks. THEN ... + * + * Check to make sure we didn't miss the period_2 period. + */ + if ( rtems_rate_monotonic_period( period_2, RTEMS_PERIOD_STATUS ) == RTEMS_TIMEOUT ) + break; + (void) rtems_rate_monotonic_cancel( period_2 ); + } + /* missed period so delete period and SELF */ + (void ) rtems_rate_monotonic_delete( period_1 ); + (void ) rtems_rate_monotonic_delete( period_2 ); + (void ) rtems_task_delete( RTEMS_SELF ); + } + +The above task creates two rate monotonic periods as part of its +initialization. The first time the loop is executed, the +``rtems_rate_monotonic_period`` directive will initiate the period_1 period for +100 ticks and return immediately. Subsequent invocations of the +``rtems_rate_monotonic_period`` directive for period_1 will result in the task +blocking for the remainder of the 100 tick period. The period_2 period is used +to control the execution time of the two sets of actions within each 100 tick +period established by period_1. The ``rtems_rate_monotonic_cancel( period_2 +)`` call is performed to ensure that the period_2 period does not expire while +the task is blocked on the period_1 period. If this cancel operation were not +performed, every time the ``rtems_rate_monotonic_period( period_2, 40 )`` call +is executed, except for the initial one, a directive status of +``RTEMS_TIMEOUT`` is returned. It is important to note that every time this +call is made, the period_2 period will be initiated immediately and the task +will not block. + +If, for any reason, the task misses any deadline, the +``rtems_rate_monotonic_period`` directive will return the ``RTEMS_TIMEOUT`` +directive status. If the above task misses its deadline, it will delete the +rate monotonic periods and itself. diff --git a/c-user/rate_monotonic_manager.rst b/c-user/rate_monotonic_manager.rst deleted file mode 100644 index 6152005..0000000 --- a/c-user/rate_monotonic_manager.rst +++ /dev/null @@ -1,1089 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-4.0 - -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) -.. Copyright (C) 2017 Kuan-Hsun Chen. - -.. index:: rate mononitonic tasks -.. index:: periodic tasks - -Rate Monotonic Manager -********************** - -Introduction -============ - -The rate monotonic manager provides facilities to implement tasks which execute -in a periodic fashion. Critically, it also gathers information about the -execution of those periods and can provide important statistics to the user -which can be used to analyze and tune the application. The directives provided -by the rate monotonic manager are: - -- rtems_rate_monotonic_create_ - Create a rate monotonic period - -- rtems_rate_monotonic_ident_ - Get ID of a period - -- rtems_rate_monotonic_cancel_ - Cancel a period - -- rtems_rate_monotonic_delete_ - Delete a rate monotonic period - -- rtems_rate_monotonic_period_ - Conclude current/Start next period - -- rtems_rate_monotonic_get_status_ - Obtain status from a period - -- rtems_rate_monotonic_get_statistics_ - Obtain statistics from a period - -- rtems_rate_monotonic_reset_statistics_ - Reset statistics for a period - -- rtems_rate_monotonic_reset_all_statistics_ - Reset statistics for all periods - -- rtems_rate_monotonic_report_statistics_ - Print period statistics report - -Background -========== - -The rate monotonic manager provides facilities to manage the execution of -periodic tasks. This manager was designed to support application designers who -utilize the Rate Monotonic Scheduling Algorithm (RMS) to ensure that their -periodic tasks will meet their deadlines, even under transient overload -conditions. Although designed for hard real-time systems, the services -provided by the rate monotonic manager may be used by any application which -requires periodic tasks. - -Rate Monotonic Manager Required Support ---------------------------------------- - -A clock tick is required to support the functionality provided by this manager. - -Period Statistics ------------------ - -This manager maintains a set of statistics on each period object. These -statistics are reset implictly at period creation time and may be reset or -obtained at any time by the application. The following is a list of the -information kept: - -``owner`` - is the id of the thread that owns this period. - -``count`` - is the total number of periods executed. - -``missed_count`` - is the number of periods that were missed. - -``min_cpu_time`` - is the minimum amount of CPU execution time consumed on any execution of the - periodic loop. - -``max_cpu_time`` - is the maximum amount of CPU execution time consumed on any execution of the - periodic loop. - -``total_cpu_time`` - is the total amount of CPU execution time consumed by executions of the - periodic loop. - -``min_wall_time`` - is the minimum amount of wall time that passed on any execution of the - periodic loop. - -``max_wall_time`` - is the maximum amount of wall time that passed on any execution of the - periodic loop. - -``total_wall_time`` - is the total amount of wall time that passed during executions of the - periodic loop. - -Each period is divided into two consecutive phases. The period starts with the -active phase of the task and is followed by the inactive phase of the task. In -the inactive phase the task is blocked and waits for the start of the next -period. The inactive phase is skipped in case of a period miss. The wall time -includes the time during the active phase of the task on which the task is not -executing on a processor. The task is either blocked (for example it waits for -a resource) or a higher priority tasks executes, thus preventing it from -executing. In case the wall time exceeds the period time, then this is a -period miss. The gap between the wall time and the period time is the margin -between a period miss or success. - -The period statistics information is inexpensive to maintain and can provide -very useful insights into the execution characteristics of a periodic task -loop. But it is just information. The period statistics reported must be -analyzed by the user in terms of what the applications is. For example, in an -application where priorities are assigned by the Rate Monotonic Algorithm, it -would be very undesirable for high priority (i.e. frequency) tasks to miss -their period. Similarly, in nearly any application, if a task were supposed to -execute its periodic loop every 10 milliseconds and it averaged 11 -milliseconds, then application requirements are not being met. - -The information reported can be used to determine the "hot spots" in the -application. Given a period's id, the user can determine the length of that -period. From that information and the CPU usage, the user can calculate the -percentage of CPU time consumed by that periodic task. For example, a task -executing for 20 milliseconds every 200 milliseconds is consuming 10 percent of -the processor's execution time. This is usually enough to make it a good -candidate for optimization. - -However, execution time alone is not enough to gauge the value of optimizing a -particular task. It is more important to optimize a task executing 2 -millisecond every 10 milliseconds (20 percent of the CPU) than one executing 10 -milliseconds every 100 (10 percent of the CPU). As a general rule of thumb, -the higher frequency at which a task executes, the more important it is to -optimize that task. - -.. index:: periodic task, definition - -Periodicity Definitions ----------------------------------- - -A periodic task is one which must be executed at a regular interval. The -interval between successive iterations of the task is referred to as its -period. Periodic tasks can be characterized by the length of their period and -execution time. The period and execution time of a task can be used to -determine the processor utilization for that task. Processor utilization is -the percentage of processor time used and can be calculated on a per-task or -system-wide basis. Typically, the task's worst-case execution time will be -less than its period. For example, a periodic task's requirements may state -that it should execute for 10 milliseconds every 100 milliseconds. Although -the execution time may be the average, worst, or best case, the worst-case -execution time is more appropriate for use when analyzing system behavior under -transient overload conditions... index:: aperiodic task, definition - -In contrast, an aperiodic task executes at irregular intervals and has only a -soft deadline. In other words, the deadlines for aperiodic tasks are not -rigid, but adequate response times are desirable. For example, an aperiodic -task may process user input from a terminal. - -.. index:: sporadic task, definition - -Finally, a sporadic task is an aperiodic task with a hard deadline and minimum -interarrival time. The minimum interarrival time is the minimum period of time -which exists between successive iterations of the task. For example, a -sporadic task could be used to process the pressing of a fire button on a -joystick. The mechanical action of the fire button ensures a minimum time -period between successive activations, but the missile must be launched by a -hard deadline. - -.. index:: Rate Monotonic Scheduling Algorithm, definition -.. index:: RMS Algorithm, definition - -Rate Monotonic Scheduling Algorithm ------------------------------------ - -The Rate Monotonic Scheduling Algorithm (RMS) is important to real-time systems -designers because it allows one to sufficiently guarantee that a set of tasks -is schedulable (see :cite:`Liu:1973:Scheduling`, :cite:`Lehoczky:1989:RM`, -:cite:`Sha:1990:Ada`, :cite:`Burns:1991:Review`). - -A set of tasks is said to be schedulable if all of the tasks can meet their -deadlines. RMS provides a set of rules which can be used to perform -a guaranteed schedulability analysis for a task set. This analysis determines -whether a task set is schedulable under worst-case conditions and emphasizes -the predictability of the system's behavior. It has been proven that: - -.. sidebar:: *RMS* - - RMS is an optimal fixed-priority algorithm for scheduling independent, - preemptible, periodic tasks on a single processor. - -RMS is optimal in the sense that if a set of tasks can be scheduled by any -fixed-priority algorithm, then RMS will be able to schedule that task set. -RMS bases it schedulability analysis on the processor utilization level below -which all deadlines can be met. - -RMS calls for the static assignment of task priorities based upon their period. -The shorter a task's period, the higher its priority. For example, a task with -a 1 millisecond period has higher priority than a task with a 100 millisecond -period. If two tasks have the same period, then RMS does not distinguish -between the tasks. However, RTEMS specifies that when given tasks of equal -priority, the task which has been ready longest will execute first. RMS's -priority assignment scheme does not provide one with exact numeric values for -task priorities. For example, consider the following task set and priority -assignments: - -+--------------------+---------------------+---------------------+ -| Task | Period | Priority | -| | (in milliseconds) | | -+====================+=====================+=====================+ -| 1 | 100 | Low | -+--------------------+---------------------+---------------------+ -| 2 | 50 | Medium | -+--------------------+---------------------+---------------------+ -| 3 | 50 | Medium | -+--------------------+---------------------+---------------------+ -| 4 | 25 | High | -+--------------------+---------------------+---------------------+ - -RMS only calls for task 1 to have the lowest priority, task 4 to have the -highest priority, and tasks 2 and 3 to have an equal priority between that of -tasks 1 and 4. The actual RTEMS priorities assigned to the tasks must only -adhere to those guidelines. - -Many applications have tasks with both hard and soft deadlines. The tasks with -hard deadlines are typically referred to as the critical task set, with the -soft deadline tasks being the non-critical task set. The critical task set can -be scheduled using RMS, with the non-critical tasks not executing under -transient overload, by simply assigning priorities such that the lowest -priority critical task (i.e. longest period) has a higher priority than the -highest priority non-critical task. Although RMS may be used to assign -priorities to the non-critical tasks, it is not necessary. In this instance, -schedulability is only guaranteed for the critical task set. - -.. index:: RMS schedulability analysis - -Schedulability Analysis ------------------------ - -RMS allows application designers to ensure that tasks can meet all deadlines under fixed-priority assignment, -even under transient overload, without knowing exactly when any given task will -execute by applying proven schedulability analysis rules. - -Assumptions -^^^^^^^^^^^ - -The schedulability analysis rules for RMS were developed based on the following -assumptions: - -- The requests for all tasks for which hard deadlines exist are periodic, with - a constant interval between requests. - -- Each task must complete before the next request for it occurs. - -- The tasks are independent in that a task does not depend on the initiation or - completion of requests for other tasks. - -- The execution time for each task without preemption or interruption is - constant and does not vary. - -- Any non-periodic tasks in the system are special. These tasks displace - periodic tasks while executing and do not have hard, critical deadlines. - -Once the basic schedulability analysis is understood, some of the above -assumptions can be relaxed and the side-effects accounted for. - -.. index:: RMS Processor Utilization Rule - -Processor Utilization Rule -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The Processor Utilization Rule requires that processor utilization be -calculated based upon the period and execution time of each task. -The fraction of processor time spent executing task index is ``Time(i) -/ Period(i)``. The processor utilization can be calculated as follows -where n is the number of tasks in the set being analyzed: - -.. math:: - - Utilization = \sum_{i=1}^{n} Time_i/Period_i - -To ensure schedulability even under transient overload, the processor -utilization must adhere to the following rule: - -.. math:: - - maximumUtilization = n * (2^{\frac{1}{n}} - 1) - -As the number of tasks increases, the above formula approaches ln(2) for a -worst-case utilization factor of approximately 0.693. Many tasks sets can be -scheduled with a greater utilization factor. In fact, the average processor -utilization threshold for a randomly generated task set is approximately 0.88. -See more detail in :cite:`Liu:1973:Scheduling`. - -Processor Utilization Rule Example -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This example illustrates the application of the Processor Utilization Rule to -an application with three critical periodic tasks. The following table details -the RMS priority, period, execution time, and processor utilization for each -task: - -+------------+----------+--------+-----------+-------------+ -| Task | RMS | Period | Execution | Processor | -| | Priority | | Time | Utilization | -+============+==========+========+===========+=============+ -| 1 | High | 100 | 15 | 0.15 | -+------------+----------+--------+-----------+-------------+ -| 2 | Medium | 200 | 50 | 0.25 | -+------------+----------+--------+-----------+-------------+ -| 3 | Low | 300 | 100 | 0.33 | -+------------+----------+--------+-----------+-------------+ - -The total processor utilization for this task set is 0.73 which is below the -upper bound of 3 * (2**(1/3) - 1), or 0.779, imposed by the Processor -Utilization Rule. Therefore, this task set is guaranteed to be schedulable -using RMS. - -.. index:: RMS First Deadline Rule - -First Deadline Rule -^^^^^^^^^^^^^^^^^^^ - -If a given set of tasks do exceed the processor utilization upper limit imposed -by the Processor Utilization Rule, they can still be guaranteed to meet all -their deadlines by application of the First Deadline Rule. This rule can be -stated as follows: - -For a given set of independent periodic tasks, if each task meets its first -deadline when all tasks are started at the same time, then the deadlines will -always be met for any combination of start times. - -A key point with this rule is that ALL periodic tasks are assumed to start at -the exact same instant in time. Although this assumption may seem to be -invalid, RTEMS makes it quite easy to ensure. By having a non-preemptible user -initialization task, all application tasks, regardless of priority, can be -created and started before the initialization deletes itself. This technique -ensures that all tasks begin to compete for execution time at the same instant -- when the user initialization task deletes itself. -See more detail in :cite:`Lehoczky:1989:RM`. - -First Deadline Rule Example -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The First Deadline Rule can ensure schedulability even when the Processor -Utilization Rule fails. The example below is a modification of the Processor -Utilization Rule example where task execution time has been increased from 15 -to 25 units. The following table details the RMS priority, period, execution -time, and processor utilization for each task: - -+------------+----------+--------+-----------+-------------+ -| Task | RMS | Period | Execution | Processor | -| | Priority | | Time | Utilization | -+============+==========+========+===========+=============+ -| 1 | High | 100 | 25 | 0.25 | -+------------+----------+--------+-----------+-------------+ -| 2 | Medium | 200 | 50 | 0.25 | -+------------+----------+--------+-----------+-------------+ -| 3 | Low | 300 | 100 | 0.33 | -+------------+----------+--------+-----------+-------------+ - -The total processor utilization for the modified task set is 0.83 which is -above the upper bound of 3 * (2**(1/3) - 1), or 0.779, imposed by the Processor -Utilization Rule. Therefore, this task set is not guaranteed to be schedulable -using RMS. However, the First Deadline Rule can guarantee the schedulability -of this task set. This rule calls for one to examine each occurrence of -deadline until either all tasks have met their deadline or one task failed to -meet its first deadline. The following table details the time of each deadline -occurrence, the maximum number of times each task may have run, the total -execution time, and whether all the deadlines have been met: - -+----------+------+------+------+----------------------+---------------+ -| Deadline | Task | Task | Task | Total | All Deadlines | -| Time | 1 | 2 | 3 | Execution Time | Met? | -+==========+======+======+======+======================+===============+ -| 100 | 1 | 1 | 1 | 25 + 50 + 100 = 175 | NO | -+----------+------+------+------+----------------------+---------------+ -| 200 | 2 | 1 | 1 | 50 + 50 + 100 = 200 | YES | -+----------+------+------+------+----------------------+---------------+ - -The key to this analysis is to recognize when each task will execute. For -example at time 100, task 1 must have met its first deadline, but tasks 2 and 3 -may also have begun execution. In this example, at time 100 tasks 1 and 2 have -completed execution and thus have met their first deadline. Tasks 1 and 2 have -used (25 + 50) = 75 time units, leaving (100 - 75) = 25 time units for task 3 -to begin. Because task 3 takes 100 ticks to execute, it will not have -completed execution at time 100. Thus at time 100, all of the tasks except -task 3 have met their first deadline. - -At time 200, task 1 must have met its second deadline and task 2 its first -deadline. As a result, of the first 200 time units, task 1 uses (2 * 25) = 50 -and task 2 uses 50, leaving (200 - 100) time units for task 3. Task 3 requires -100 time units to execute, thus it will have completed execution at time 200. -Thus, all of the tasks have met their first deadlines at time 200, and the task -set is schedulable using the First Deadline Rule. - -Relaxation of Assumptions -^^^^^^^^^^^^^^^^^^^^^^^^^ - -The assumptions used to develop the RMS schedulability rules are uncommon in -most real-time systems. For example, it was assumed that tasks have constant -unvarying execution time. It is possible to relax this assumption, simply by -using the worst-case execution time of each task. - -Another assumption is that the tasks are independent. This means that the -tasks do not wait for one another or contend for resources. This assumption -can be relaxed by accounting for the amount of time a task spends waiting to -acquire resources. Similarly, each task's execution time must account for any -I/O performed and any RTEMS directive calls. - -In addition, the assumptions did not account for the time spent executing -interrupt service routines. This can be accounted for by including all the -processor utilization by interrupt service routines in the utilization -calculation. Similarly, one should also account for the impact of delays in -accessing local memory caused by direct memory access and other processors -accessing local dual-ported memory. - -The assumption that nonperiodic tasks are used only for initialization or -failure-recovery can be relaxed by placing all periodic tasks in the critical -task set. This task set can be scheduled and analyzed using RMS. All -nonperiodic tasks are placed in the non-critical task set. Although the -critical task set can be guaranteed to execute even under transient overload, -the non-critical task set is not guaranteed to execute. - -In conclusion, the application designer must be fully cognizant of the system -and its run-time behavior when performing schedulability analysis for a system -using RMS. Every hardware and software factor which impacts the execution time -of each task must be accounted for in the schedulability analysis. - -Operations -========== - -Creating a Rate Monotonic Period --------------------------------- - -The ``rtems_rate_monotonic_create`` directive creates a rate monotonic period -which is to be used by the calling task to delineate a period. RTEMS allocates -a Period Control Block (PCB) from the PCB free list. This data structure is -used by RTEMS to manage the newly created rate monotonic period. RTEMS returns -a unique period ID to the application which is used by other rate monotonic -manager directives to access this rate monotonic period. - -Manipulating a Period ---------------------- - -The ``rtems_rate_monotonic_period`` directive is used to establish and maintain -periodic execution utilizing a previously created rate monotonic period. Once -initiated by the ``rtems_rate_monotonic_period`` directive, the period is said -to run until it either expires or is reinitiated. The state of the rate -monotonic period results in one of the following scenarios: - -- If the rate monotonic period is running, the calling task will be blocked for - the remainder of the outstanding period and, upon completion of that period, - the period will be reinitiated with the specified period. - -- If the rate monotonic period is not currently running and has not expired, it - is initiated with a length of period ticks and the calling task returns - immediately. - -- If the rate monotonic period has expired before the task invokes the - ``rtems_rate_monotonic_period`` directive, the postponed job will be released - until there is no more postponed jobs. The calling task returns immediately - with a timeout error status. In the watchdog routine, the period will still - be updated periodically and track the count of the postponed jobs :cite:`Chen:2016:Overrun`. - Please note, the count of the postponed jobs is only saturated until 0xffffffff. - -Obtaining the Status of a Period --------------------------------- - -If the ``rtems_rate_monotonic_period`` directive is invoked with a period of -``RTEMS_PERIOD_STATUS`` ticks, the current state of the specified rate -monotonic period will be returned. The following table details the -relationship between the period's status and the directive status code returned -by the ``rtems_rate_monotonic_period`` directive: - -.. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - period is running - * - ``RTEMS_TIMEOUT`` - - period has expired - * - ``RTEMS_NOT_DEFINED`` - - period has never been initiated - -Obtaining the status of a rate monotonic period does not alter the state or -length of that period. - -Canceling a Period ------------------- - -The ``rtems_rate_monotonic_cancel`` directive is used to stop the period -maintained by the specified rate monotonic period. The period is stopped and -the rate monotonic period can be reinitiated using the -``rtems_rate_monotonic_period`` directive. - -Deleting a Rate Monotonic Period --------------------------------- - -The ``rtems_rate_monotonic_delete`` directive is used to delete a rate -monotonic period. If the period is running and has not expired, the period is -automatically canceled. The rate monotonic period's control block is returned -to the PCB free list when it is deleted. A rate monotonic period can be -deleted by a task other than the task which created the period. - -Examples --------- - -The following sections illustrate common uses of rate monotonic periods to -construct periodic tasks. - -Simple Periodic Task --------------------- - -This example consists of a single periodic task which, after initialization, -executes every 100 clock ticks. - -.. code-block:: c - :linenos: - - rtems_task Periodic_task(rtems_task_argument arg) - { - rtems_name name; - rtems_id period; - rtems_status_code status; - name = rtems_build_name( 'P', 'E', 'R', 'D' ); - status = rtems_rate_monotonic_create( name, &period ); - if ( status != RTEMS_SUCCESSFUL ) { - printf( "rtems_monotonic_create failed with status of %d.\n", status ); - exit( 1 ); - } - while ( 1 ) { - if ( rtems_rate_monotonic_period( period, 100 ) == RTEMS_TIMEOUT ) - break; - /* Perform some periodic actions */ - } - /* missed period so delete period and SELF */ - status = rtems_rate_monotonic_delete( period ); - if ( status != RTEMS_SUCCESSFUL ) { - printf( "rtems_rate_monotonic_delete failed with status of %d.\n", status ); - exit( 1 ); - } - status = rtems_task_delete( RTEMS_SELF ); /* should not return */ - printf( "rtems_task_delete returned with status of %d.\n", status ); - exit( 1 ); - } - -The above task creates a rate monotonic period as part of its initialization. -The first time the loop is executed, the ``rtems_rate_monotonic_period`` -directive will initiate the period for 100 ticks and return immediately. -Subsequent invocations of the ``rtems_rate_monotonic_period`` directive will -result in the task blocking for the remainder of the 100 tick period. If, for -any reason, the body of the loop takes more than 100 ticks to execute, the -``rtems_rate_monotonic_period`` directive will return the ``RTEMS_TIMEOUT`` -status. If the above task misses its deadline, it will delete the rate -monotonic period and itself. - -Task with Multiple Periods --------------------------- - -This example consists of a single periodic task which, after initialization, -performs two sets of actions every 100 clock ticks. The first set of actions -is performed in the first forty clock ticks of every 100 clock ticks, while the -second set of actions is performed between the fortieth and seventieth clock -ticks. The last thirty clock ticks are not used by this task. - -.. code-block:: c - :linenos: - - rtems_task Periodic_task(rtems_task_argument arg) - { - rtems_name name_1, name_2; - rtems_id period_1, period_2; - name_1 = rtems_build_name( 'P', 'E', 'R', '1' ); - name_2 = rtems_build_name( 'P', 'E', 'R', '2' ); - (void ) rtems_rate_monotonic_create( name_1, &period_1 ); - (void ) rtems_rate_monotonic_create( name_2, &period_2 ); - while ( 1 ) { - if ( rtems_rate_monotonic_period( period_1, 100 ) == RTEMS_TIMEOUT ) - break; - if ( rtems_rate_monotonic_period( period_2, 40 ) == RTEMS_TIMEOUT ) - break; - /* - * Perform first set of actions between clock - * ticks 0 and 39 of every 100 ticks. - */ - if ( rtems_rate_monotonic_period( period_2, 30 ) == RTEMS_TIMEOUT ) - break; - /* - * Perform second set of actions between clock 40 and 69 - * of every 100 ticks. THEN ... - * - * Check to make sure we didn't miss the period_2 period. - */ - if ( rtems_rate_monotonic_period( period_2, RTEMS_PERIOD_STATUS ) == RTEMS_TIMEOUT ) - break; - (void) rtems_rate_monotonic_cancel( period_2 ); - } - /* missed period so delete period and SELF */ - (void ) rtems_rate_monotonic_delete( period_1 ); - (void ) rtems_rate_monotonic_delete( period_2 ); - (void ) rtems_task_delete( RTEMS_SELF ); - } - -The above task creates two rate monotonic periods as part of its -initialization. The first time the loop is executed, the -``rtems_rate_monotonic_period`` directive will initiate the period_1 period for -100 ticks and return immediately. Subsequent invocations of the -``rtems_rate_monotonic_period`` directive for period_1 will result in the task -blocking for the remainder of the 100 tick period. The period_2 period is used -to control the execution time of the two sets of actions within each 100 tick -period established by period_1. The ``rtems_rate_monotonic_cancel( period_2 -)`` call is performed to ensure that the period_2 period does not expire while -the task is blocked on the period_1 period. If this cancel operation were not -performed, every time the ``rtems_rate_monotonic_period( period_2, 40 )`` call -is executed, except for the initial one, a directive status of -``RTEMS_TIMEOUT`` is returned. It is important to note that every time this -call is made, the period_2 period will be initiated immediately and the task -will not block. - -If, for any reason, the task misses any deadline, the -``rtems_rate_monotonic_period`` directive will return the ``RTEMS_TIMEOUT`` -directive status. If the above task misses its deadline, it will delete the -rate monotonic periods and itself. - -Directives -========== - -This section details the rate monotonic manager's directives. A subsection is -dedicated to each of this manager's directives and describes the calling -sequence, related constants, usage, and status codes. - -.. raw:: latex - - \clearpage - -.. index:: create a period -.. index:: rtems_rate_monotonic_create - -.. _rtems_rate_monotonic_create: - -RATE_MONOTONIC_CREATE - Create a rate monotonic period ------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_rate_monotonic_create( - rtems_name name, - rtems_id *id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - rate monotonic period created successfully - * - ``RTEMS_INVALID_NAME`` - - invalid period name - * - ``RTEMS_TOO_MANY`` - - too many periods created - -DESCRIPTION: - This directive creates a rate monotonic period. The assigned rate - monotonic id is returned in id. This id is used to access the period with - other rate monotonic manager directives. For control and maintenance of - the rate monotonic period, RTEMS allocates a PCB from the local PCB free - pool and initializes it. - -NOTES: - This directive will not cause the calling task to be preempted. - -.. raw:: latex - - \clearpage - -.. index:: get ID of a period -.. index:: obtain ID of a period -.. index:: rtems_rate_monotonic_ident - -.. _rtems_rate_monotonic_ident: - -RATE_MONOTONIC_IDENT - Get ID of a period ------------------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_rate_monotonic_ident( - rtems_name name, - rtems_id *id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - period identified successfully - * - ``RTEMS_INVALID_NAME`` - - period name not found - -DESCRIPTION: - This directive obtains the period id associated with the period name to be - acquired. If the period name is not unique, then the period id will match - one of the periods with that name. However, this period id is not - guaranteed to correspond to the desired period. The period id is used to - access this period in other rate monotonic manager directives. - -NOTES: - This directive will not cause the running task to be preempted. - -.. raw:: latex - - \clearpage - -.. index:: cancel a period -.. index:: rtems_rate_monotonic_cancel - -.. _rtems_rate_monotonic_cancel: - -RATE_MONOTONIC_CANCEL - Cancel a period ---------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_rate_monotonic_cancel( - rtems_id id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - period canceled successfully - * - ``RTEMS_INVALID_ID`` - - invalid rate monotonic period id - * - ``RTEMS_NOT_OWNER_OF_RESOURCE`` - - rate monotonic period not created by calling task - -DESCRIPTION: - - This directive cancels the rate monotonic period id. This period will be - reinitiated by the next invocation of ``rtems_rate_monotonic_period`` - with id. - -NOTES: - This directive will not cause the running task to be preempted. - - The rate monotonic period specified by id must have been created by the - calling task. - -.. raw:: latex - - \clearpage - -.. index:: rtems_rate_monotonic_delete -.. index:: delete a period - -.. _rtems_rate_monotonic_delete: - -RATE_MONOTONIC_DELETE - Delete a rate monotonic period ------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_rate_monotonic_delete( - rtems_id id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - period deleted successfully - * - ``RTEMS_INVALID_ID`` - - invalid rate monotonic period id - -DESCRIPTION: - - This directive deletes the rate monotonic period specified by id. If the - period is running, it is automatically canceled. The PCB for the deleted - period is reclaimed by RTEMS. - -NOTES: - This directive will not cause the running task to be preempted. - - A rate monotonic period can be deleted by a task other than the task which - created the period. - -.. raw:: latex - - \clearpage - -.. index:: conclude current period -.. index:: start current period -.. index:: period initiation -.. index:: rtems_rate_monotonic_period - -.. _rtems_rate_monotonic_period: - -RATE_MONOTONIC_PERIOD - Conclude current/Start next period ----------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_rate_monotonic_period( - rtems_id id, - rtems_interval length - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - period initiated successfully - * - ``RTEMS_INVALID_ID`` - - invalid rate monotonic period id - * - ``RTEMS_NOT_OWNER_OF_RESOURCE`` - - period not created by calling task - * - ``RTEMS_NOT_DEFINED`` - - period has never been initiated (only possible when period is set to PERIOD_STATUS) - * - ``RTEMS_TIMEOUT`` - - period has expired - -DESCRIPTION: - This directive initiates the rate monotonic period id with a length of - period ticks. If id is running, then the calling task will block for the - remainder of the period before reinitiating the period with the specified - period. If id was not running (either expired or never initiated), the - period is immediately initiated and the directive returns immediately. - If id has expired its period, the postponed job will be released immediately - and the following calls of this directive will release postponed - jobs until there is no more deadline miss. - - If invoked with a period of ``RTEMS_PERIOD_STATUS`` ticks, the current - state of id will be returned. The directive status indicates the current - state of the period. This does not alter the state or period of the - period. - -NOTES: - This directive will not cause the running task to be preempted. - -.. raw:: latex - - \clearpage - -.. index:: get status of period -.. index:: obtain status of period -.. index:: rtems_rate_monotonic_get_status - -.. _rtems_rate_monotonic_get_status: - -RATE_MONOTONIC_GET_STATUS - Obtain status from a period -------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_rate_monotonic_get_status( - rtems_id id, - rtems_rate_monotonic_period_status *status - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - period status retrieved successfully - * - ``RTEMS_INVALID_ID`` - - invalid rate monotonic period id - * - ``RTEMS_INVALID_ADDRESS`` - - invalid address of status - * - ``RTEMS_NOT_DEFINED`` - - no status is available due to the cpu usage of the task having been - reset since the period initiated - -*DESCRIPTION: - This directive returns status information associated with the rate - monotonic period id in the following data structure: - - .. index:: rtems_rate_monotonic_period_status - - .. code-block:: c - - typedef struct { - rtems_id owner; - rtems_rate_monotonic_period_states state; - rtems_rate_monotonic_period_time_t since_last_period; - rtems_thread_cpu_usage_t executed_since_last_period; - uint32_t postponed_jobs_count; - } rtems_rate_monotonic_period_status; - - .. COMMENT: RATE_MONOTONIC_INACTIVE does not have RTEMS in front of it. - - A configure time option can be used to select whether the time information - is given in ticks or seconds and nanoseconds. The default is seconds and - nanoseconds. If the period's state is ``RATE_MONOTONIC_INACTIVE``, both - time values will be set to 0. Otherwise, both time values will contain - time information since the last invocation of the - ``rtems_rate_monotonic_period`` directive. More specifically, the - since_last_period value contains the elapsed time which has occurred since - the last invocation of the ``rtems_rate_monotonic_period`` directive and - the ``executed_since_last_period`` contains how much processor time the - owning task has consumed since the invocation of the - ``rtems_rate_monotonic_period`` directive. In addition, the - ``postponed_jobs_count value`` contains the count of jobs which are not - released yet. - -NOTES: - This directive will not cause the running task to be preempted. - -.. raw:: latex - - \clearpage - -.. index:: get statistics of period -.. index:: obtain statistics of period -.. index:: rtems_rate_monotonic_get_statistics - -.. _rtems_rate_monotonic_get_statistics: - -RATE_MONOTONIC_GET_STATISTICS - Obtain statistics from a period ---------------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_rate_monotonic_get_statistics( - rtems_id id, - rtems_rate_monotonic_period_statistics *statistics - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - period statistics retrieved successfully - * - ``RTEMS_INVALID_ID`` - - invalid rate monotonic period id - * - ``RTEMS_INVALID_ADDRESS`` - - invalid address of statistics - -DESCRIPTION: - This directive returns statistics information associated with the rate - monotonic period id in the following data structure: - - .. index:: rtems_rate_monotonic_period_statistics - - .. code-block:: c - - typedef struct { - uint32_t count; - uint32_t missed_count; - #ifdef RTEMS_ENABLE_NANOSECOND_CPU_USAGE_STATISTICS - struct timespec min_cpu_time; - struct timespec max_cpu_time; - struct timespec total_cpu_time; - #else - uint32_t min_cpu_time; - uint32_t max_cpu_time; - uint32_t total_cpu_time; - #endif - #ifdef RTEMS_ENABLE_NANOSECOND_RATE_MONOTONIC_STATISTICS - struct timespec min_wall_time; - struct timespec max_wall_time; - struct timespec total_wall_time; - #else - uint32_t min_wall_time; - uint32_t max_wall_time; - uint32_t total_wall_time; - #endif - } rtems_rate_monotonic_period_statistics; - - This directive returns the current statistics information for the period - instance assocaited with ``id``. The information returned is indicated by - the structure above. - -NOTES: - This directive will not cause the running task to be preempted. - -.. raw:: latex - - \clearpage - -.. index:: reset statistics of period -.. index:: rtems_rate_monotonic_reset_statistics - -.. _rtems_rate_monotonic_reset_statistics: - -RATE_MONOTONIC_RESET_STATISTICS - Reset statistics for a period ---------------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_rate_monotonic_reset_statistics( - rtems_id id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - period initiated successfully - * - ``RTEMS_INVALID_ID`` - - invalid rate monotonic period id - -DESCRIPTION: - This directive resets the statistics information associated with this rate - monotonic period instance. - -NOTES: - This directive will not cause the running task to be preempted. - -.. raw:: latex - - \clearpage - -.. index:: reset statistics of all periods -.. index:: rtems_rate_monotonic_reset_all_statistics - -.. _rtems_rate_monotonic_reset_all_statistics: - -RATE_MONOTONIC_RESET_ALL_STATISTICS - Reset statistics for all periods ----------------------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - void rtems_rate_monotonic_reset_all_statistics(void); - -DIRECTIVE STATUS CODES: - NONE - -DESCRIPTION: - This directive resets the statistics information associated with all rate - monotonic period instances. - -NOTES: - This directive will not cause the running task to be preempted. - -.. raw:: latex - - \clearpage - -.. index:: print period statistics report -.. index:: period statistics report -.. index:: rtems_rate_monotonic_report_statistics - -.. _rtems_rate_monotonic_report_statistics: - -RATE_MONOTONIC_REPORT_STATISTICS - Print period statistics report ------------------------------------------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - void rtems_rate_monotonic_report_statistics(void); - -DIRECTIVE STATUS CODES: - NONE - -DESCRIPTION: - This directive prints a report on all active periods which have executed at - least one period. The following is an example of the output generated by - this directive. - - .. index:: rtems_rate_monotonic_period_statistics - - .. code-block:: c - - ID OWNER PERIODS MISSED CPU TIME WALL TIME - MIN/MAX/AVG MIN/MAX/AVG - 0x42010001 TA1 502 0 0/1/0.99 0/0/0.00 - 0x42010002 TA2 502 0 0/1/0.99 0/0/0.00 - 0x42010003 TA3 501 0 0/1/0.99 0/0/0.00 - 0x42010004 TA4 501 0 0/1/0.99 0/0/0.00 - 0x42010005 TA5 10 0 0/1/0.90 0/0/0.00 - -NOTES: - This directive will not cause the running task to be preempted. diff --git a/c-user/region/background.rst b/c-user/region/background.rst new file mode 100644 index 0000000..cf22a76 --- /dev/null +++ b/c-user/region/background.rst @@ -0,0 +1,87 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Background +========== + +.. index:: region, definition +.. index:: segment, definition + +Region Manager Definitions +-------------------------- + +A region makes up a physically contiguous memory space with user-defined +boundaries from which variable-sized segments are dynamically allocated and +deallocated. A segment is a variable size section of memory which is allocated +in multiples of a user-defined page size. This page size is required to be a +multiple of four greater than or equal to four. For example, if a request for +a 350-byte segment is made in a region with 256-byte pages, then a 512-byte +segment is allocated. + +Regions are organized as doubly linked chains of variable sized memory blocks. +Memory requests are allocated using a first-fit algorithm. If available, the +requester receives the number of bytes requested (rounded up to the next page +size). RTEMS requires some overhead from the region's memory for each segment +that is allocated. Therefore, an application should only modify the memory of +a segment that has been obtained from the region. The application should NOT +modify the memory outside of any obtained segments and within the region's +boundaries while the region is currently active in the system. + +Upon return to the region, the free block is coalesced with its neighbors (if +free) on both sides to produce the largest possible unused block. + +.. index:: region attribute set, building + +Building an Attribute Set +------------------------- + +In general, an attribute set is built by a bitwise OR of the desired attribute +components. The set of valid region attributes is provided in the following +table: + +.. list-table:: + :class: rtems-table + + * - ``RTEMS_FIFO`` + - tasks wait by FIFO (default) + * - ``RTEMS_PRIORITY`` + - tasks wait by priority + +Attribute values are specifically designed to be mutually exclusive, therefore +bitwise OR and addition operations are equivalent as long as each attribute +appears exactly once in the component list. An attribute listed as a default +is not required to appear in the attribute list, although it is a good +programming practice to specify default attributes. If all defaults are +desired, the attribute ``RTEMS_DEFAULT_ATTRIBUTES`` should be specified on this +call. + +This example demonstrates the attribute_set parameter needed to create a region +with the task priority waiting queue discipline. The attribute_set parameter +to the ``rtems_region_create`` directive should be ``RTEMS_PRIORITY``. + +Building an Option Set +---------------------- + +In general, an option is built by a bitwise OR of the desired option +components. The set of valid options for the ``rtems_region_get_segment`` +directive are listed in the following table: + +.. list-table:: + :class: rtems-table + + * - ``RTEMS_WAIT`` + - task will wait for segment (default) + * - ``RTEMS_NO_WAIT`` + - task should not wait + +Option values are specifically designed to be mutually exclusive, therefore +bitwise OR and addition operations are equivalent as long as each option +appears exactly once in the component list. An option listed as a default is +not required to appear in the option list, although it is a good programming +practice to specify default options. If all defaults are desired, the +option ``RTEMS_DEFAULT_OPTIONS`` should be specified on this call. + +This example demonstrates the option parameter needed to poll for a segment. +The option parameter passed to the ``rtems_region_get_segment`` directive +should be ``RTEMS_NO_WAIT``. diff --git a/c-user/region/directives.rst b/c-user/region/directives.rst new file mode 100644 index 0000000..557b89e --- /dev/null +++ b/c-user/region/directives.rst @@ -0,0 +1,916 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. _RegionManagerDirectives: + +Directives +========== + +This section details the directives of the Region Manager. A subsection is +dedicated to each of this manager's directives and lists the calling sequence, +parameters, description, return values, and notes of the directive. + +.. Generated from spec:/rtems/region/if/create + +.. raw:: latex + + \clearpage + +.. index:: rtems_region_create() +.. index:: create a region + +.. _InterfaceRtemsRegionCreate: + +rtems_region_create() +--------------------- + +Creates a region. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_region_create( + rtems_name name, + void *starting_address, + uintptr_t length, + uintptr_t page_size, + rtems_attribute attribute_set, + rtems_id *id + ); + +.. rubric:: PARAMETERS: + +``name`` + This parameter is the object name of the region. + +``starting_address`` + This parameter is the starting address of the memory area managed by the + region. + +``length`` + This parameter is the length in bytes of the memory area managed by the + region. + +``page_size`` + This parameter is the alignment of the starting address and length of each + allocated segment of the region. + +``attribute_set`` + This parameter is the attribute set of the region. + +``id`` + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the identifier of the created region will + be stored in this object. + +.. rubric:: DESCRIPTION: + +This directive creates a region which resides on the local node. The region +has the user-defined object name specified in ``name``. The assigned object +identifier is returned in ``id``. This identifier is used to access the region +with other region related directives. + +The region manages the **contiguous memory area** which starts at +``starting_address`` and is ``length`` bytes long. The memory area shall be +large enough to contain some internal region administration data. + +The **starting address** and **length of segments** allocated from the region +will be an integral multiple of ``page_size``. The specified page size will be +aligned to an implementation-dependent minimum alignment if necessary. + +The **attribute set** specified in ``attribute_set`` is built through a +*bitwise or* of the attribute constants described below. Not all combinations +of attributes are allowed. Some attributes are mutually exclusive. If +mutually exclusive attributes are combined, the behaviour is undefined. +Attributes not mentioned below are not evaluated by this directive and have no +effect. Default attributes can be selected by using the +:c:macro:`RTEMS_DEFAULT_ATTRIBUTES` constant. + +The **task wait queue discipline** is selected by the mutually exclusive +:c:macro:`RTEMS_FIFO` and :c:macro:`RTEMS_PRIORITY` attributes. The discipline +defines the order in which tasks wait for allocatable segments on a currently +empty region. + +* The **FIFO discipline** is the default and can be emphasized through use of + the :c:macro:`RTEMS_FIFO` attribute. + +* The **priority discipline** is selected by the :c:macro:`RTEMS_PRIORITY` + attribute. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_NAME` + The ``name`` parameter was invalid. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``id`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``starting_address`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_TOO_MANY` + There was no inactive object available to create a region. The number of + regions available to the application is configured through the + :ref:`CONFIGURE_MAXIMUM_REGIONS` application configuration option. + +:c:macro:`RTEMS_INVALID_SIZE` + The ``page_size`` parameter was invalid. + +:c:macro:`RTEMS_INVALID_SIZE` + The memory area specified in ``starting_address`` and ``length`` was too + small. + +.. rubric:: NOTES: + +For control and maintenance of the region, RTEMS allocates a :term:`RNCB` from +the local RNCB free pool and initializes it. + +.. 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. + +* The number of regions available to the application is configured through the + :ref:`CONFIGURE_MAXIMUM_REGIONS` application configuration option. + +* Where the object class corresponding to the directive is configured to use + unlimited objects, the directive may allocate memory from the RTEMS + Workspace. + +.. Generated from spec:/rtems/region/if/ident + +.. raw:: latex + + \clearpage + +.. index:: rtems_region_ident() + +.. _InterfaceRtemsRegionIdent: + +rtems_region_ident() +-------------------- + +Identifies a region by the object name. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_region_ident( rtems_name name, rtems_id *id ); + +.. rubric:: PARAMETERS: + +``name`` + This parameter is the object name to look up. + +``id`` + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the object identifier of an object with + the specified name will be stored in this object. + +.. rubric:: DESCRIPTION: + +This directive obtains a region identifier associated with the region name +specified in ``name``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``id`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_NAME` + The ``name`` parameter was 0. + +:c:macro:`RTEMS_INVALID_NAME` + There was no object with the specified name on the local node. + +.. rubric:: NOTES: + +If the region name is not unique, then the region identifier will match the +first region with that name in the search order. However, this region +identifier is not guaranteed to correspond to the desired region. + +The objects are searched from lowest to the highest index. Only the local node +is searched. + +The region identifier is used with other region related directives to access +the region. + +.. 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/region/if/delete + +.. raw:: latex + + \clearpage + +.. index:: rtems_region_delete() +.. index:: delete a region + +.. _InterfaceRtemsRegionDelete: + +rtems_region_delete() +--------------------- + +Deletes the region. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_region_delete( rtems_id id ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the region identifier. + +.. rubric:: DESCRIPTION: + +This directive deletes the region specified by ``id``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no region associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_RESOURCE_IN_USE` + There were segments of the region still in use. + +.. rubric:: NOTES: + +The region cannot be deleted if any of its segments are still allocated. + +The :term:`RNCB` for the deleted region is reclaimed by RTEMS. + +.. 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. + +* The calling task does not have to be the task that created the object. Any + local task that knows the object identifier can delete the object. + +* Where the object class corresponding to the directive is configured to use + unlimited objects, the directive may free memory to the RTEMS Workspace. + +.. Generated from spec:/rtems/region/if/extend + +.. raw:: latex + + \clearpage + +.. index:: rtems_region_extend() +.. index:: add memory to a region +.. index:: region, add memory + +.. _InterfaceRtemsRegionExtend: + +rtems_region_extend() +--------------------- + +Extends the region. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_region_extend( + rtems_id id, + void *starting_address, + uintptr_t length + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the region identifier. + +``starting_address`` + This parameter is the starting address of the memory area to extend the + region. + +``length`` + This parameter is the length in bytes of the memory area to extend the + region. + +.. rubric:: DESCRIPTION: + +This directive adds the memory area which starts at ``starting_address`` for +``length`` bytes to the region specified by ``id``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``starting_address`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no region associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The memory area specified by ``starting_address`` and ``length`` was + insufficient to extend the heap. + +.. rubric:: NOTES: + +There are no alignment requirements for the memory area. The memory area must +be big enough to contain some maintenance blocks. It must not overlap parts of +the current heap memory areas. Disconnected memory areas added to the heap +will lead to used blocks which cover the gaps. Extending with an inappropriate +memory area will corrupt the heap resulting in undefined behaviour. + +.. 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/region/if/get-segment + +.. raw:: latex + + \clearpage + +.. index:: rtems_region_get_segment() +.. index:: get segment from region + +.. _InterfaceRtemsRegionGetSegment: + +rtems_region_get_segment() +-------------------------- + +Gets a segment from the region. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_region_get_segment( + rtems_id id, + uintptr_t size, + rtems_option option_set, + rtems_interval timeout, + void **segment + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the region identifier. + +``size`` + This parameter is the size in bytes of the segment to allocate. + +``option_set`` + This parameter is the option set. + +``timeout`` + This parameter is the timeout in :term:`clock ticks <clock tick>` if the + :c:macro:`RTEMS_WAIT` option is set. Use :c:macro:`RTEMS_NO_TIMEOUT` to + wait potentially forever. + +``segment`` + This parameter is the pointer to a ``void`` pointer object. When the + directive call is successful, the begin address of the allocated segment + will be stored in this object. + +.. rubric:: DESCRIPTION: + +This directive gets a segment from the region specified by ``id``. + +The **option set** specified in ``option_set`` is built through a *bitwise or* +of the option constants described below. Not all combinations of options are +allowed. Some options are mutually exclusive. If mutually exclusive options +are combined, the behaviour is undefined. Options not mentioned below are not +evaluated by this directive and have no effect. Default options can be selected +by using the :c:macro:`RTEMS_DEFAULT_OPTIONS` constant. + +The calling task can **wait** or **try to get** a segment from the region +according to the mutually exclusive :c:macro:`RTEMS_WAIT` and +:c:macro:`RTEMS_NO_WAIT` options. + +* **Waiting to get** a segment from the region is the default and can be + emphasized through the use of the :c:macro:`RTEMS_WAIT` option. The + ``timeout`` parameter defines how long the calling task is willing to wait. + Use :c:macro:`RTEMS_NO_TIMEOUT` to wait potentially forever, otherwise set a + timeout interval in clock ticks. + +* **Trying to get** a segment from the region is selected by the + :c:macro:`RTEMS_NO_WAIT` option. If this option is defined, then the + ``timeout`` parameter is ignored. When a segment from the region cannot be + immediately allocated, then the :c:macro:`RTEMS_UNSATISFIED` status is + returned. + +With either :c:macro:`RTEMS_WAIT` or :c:macro:`RTEMS_NO_WAIT` if there is a +segment of the requested size is available, then it is returned in ``segment`` +and this directive returns immediately with the :c:macro:`RTEMS_SUCCESSFUL` +status code. + +If the calling task chooses to return immediately and the region has no segment +of the requested size available, then the directive returns immediately with +the :c:macro:`RTEMS_UNSATISFIED` status code. If the calling task chooses to +wait for a segment, then the calling task is placed on the region wait queue +and blocked. If the region was created with the :c:macro:`RTEMS_PRIORITY` +option specified, then the calling task is inserted into the wait queue +according to its priority. But, if the region was created with the +:c:macro:`RTEMS_FIFO` option specified, then the calling task is placed at the +rear of the wait queue. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``segment`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_SIZE` + The ``size`` parameter was zero. + +:c:macro:`RTEMS_INVALID_ID` + There was no region associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_INVALID_SIZE` + The ``size`` parameter exceeded the maximum segment size which is possible + for the region. + +:c:macro:`RTEMS_UNSATISFIED` + The region had no segment of the requested size immediately available. + +:c:macro:`RTEMS_TIMEOUT` + The timeout happened while the calling task was waiting to get a segment + from the region. + +.. rubric:: NOTES: + +The actual length of the allocated segment may be larger than the requested +size because a segment size is always a multiple of the region's page size. + +.. 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. + +* When the request cannot be immediately satisfied and the + :c:macro:`RTEMS_WAIT` option is set, the calling task blocks at some point + during the directive call. + +* The timeout functionality of the directive requires a :term:`clock tick`. + +.. Generated from spec:/rtems/region/if/return-segment + +.. raw:: latex + + \clearpage + +.. index:: rtems_region_return_segment() +.. index:: return segment to region + +.. _InterfaceRtemsRegionReturnSegment: + +rtems_region_return_segment() +----------------------------- + +Returns the segment to the region. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_region_return_segment( rtems_id id, void *segment ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the region identifier. + +``segment`` + This parameter is the begin address of the segment to return. + +.. rubric:: DESCRIPTION: + +This directive returns the segment specified by ``segment`` to the region +specified by ``id``. The returned segment is merged with its neighbors to form +the largest possible segment. The first task on the wait queue is examined to +determine if its segment request can now be satisfied. If so, it is given a +segment and unblocked. This process is repeated until the first task's segment +request cannot be satisfied. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no region associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The segment was not within the region. + +.. rubric:: NOTES: + +This directive will cause the calling task to be preempted if one or more local +tasks are waiting for a segment and the following conditions exist: + +* A waiting task has a higher priority than the calling task. + +* The size of the segment required by the waiting task is less than or equal to + the size of the segment returned. + +.. 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 unblock a task. This may cause the calling task to be + preempted. + +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. + +.. Generated from spec:/rtems/region/if/resize-segment + +.. raw:: latex + + \clearpage + +.. index:: rtems_region_resize_segment() +.. index:: resize segment + +.. _InterfaceRtemsRegionResizeSegment: + +rtems_region_resize_segment() +----------------------------- + +Changes the size of the segment. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_region_resize_segment( + rtems_id id, + void *segment, + uintptr_t size, + uintptr_t *old_size + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the region identifier. + +``segment`` + This parameter is the begin address of the segment to resize. + +``size`` + This parameter is the requested new size of the segment. + +``old_size`` + This parameter is the pointer to an `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_ object. When the + directive call is successful, the old size of the segment will be stored in + this object. + +.. rubric:: DESCRIPTION: + +This directive is used to increase or decrease the size of the ``segment`` of +the region specified by ``id``. When increasing the size of a segment, it is +possible that there is no memory available contiguous to the segment. In this +case, the request is unsatisfied. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``old_size`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no region associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The segment was not within the region. + +:c:macro:`RTEMS_UNSATISFIED` + The region was unable to resize the segment. + +.. rubric:: NOTES: + +If an attempt to increase the size of a segment fails, then the application may +want to allocate a new segment of the desired size, copy the contents of the +original segment to the new, larger segment and then return the original +segment. + +.. 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/region/if/get-information + +.. raw:: latex + + \clearpage + +.. index:: rtems_region_get_information() +.. index:: obtain region information + +.. _InterfaceRtemsRegionGetInformation: + +rtems_region_get_information() +------------------------------ + +Gets the region information. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_region_get_information( + rtems_id id, + Heap_Information_block *the_info + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the region identifier. + +``the_info`` + This parameter is the pointer to a :c:type:`Heap_Information_block` object. + When the directive call is successful, the information of the region will + be stored in this object. + +.. rubric:: DESCRIPTION: + +This directive is used to obtain information about the used and free memory in +the region specified by ``id``. This is a snapshot at the time of the call. The +information will be returned in the structure pointed to by ``the_info``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``the_info`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no region associated with the identifier specified by ``id``. + +.. rubric:: NOTES: + +This is primarily intended as a mechanism to obtain a diagnostic information. +This method forms am O(n) scan of the free and an O(n) scan of the used blocks +in the region to calculate the information provided. Given that the execution +time is driven by the number of used and free blocks, it can take a +non-deterministic time to execute. + +To get only the free information of the region use +:ref:`InterfaceRtemsRegionGetFreeInformation`. + +.. 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/region/if/get-free-information + +.. raw:: latex + + \clearpage + +.. index:: rtems_region_get_free_information() +.. index:: obtain region information on free blocks + +.. _InterfaceRtemsRegionGetFreeInformation: + +rtems_region_get_free_information() +----------------------------------- + +Gets the region free information. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_region_get_free_information( + rtems_id id, + Heap_Information_block *the_info + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the region identifier. + +``the_info`` + This parameter is the pointer to a :c:type:`Heap_Information_block` object. + When the directive call is successful, the free information of the region + will be stored in this object. + +.. rubric:: DESCRIPTION: + +This directive is used to obtain information about the free memory in the +region specified by ``id``. This is a snapshot at the time of the call. The +information will be returned in the structure pointed to by ``the_info``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``the_info`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no region associated with the identifier specified by ``id``. + +.. rubric:: NOTES: + +This directive uses the same structure to return information as the +:ref:`InterfaceRtemsRegionGetInformation` directive but does not fill in the +used information. + +This is primarily intended as a mechanism to obtain a diagnostic information. +This method forms am O(n) scan of the free in the region to calculate the +information provided. Given that the execution time is driven by the number of +used and free blocks, it can take a non-deterministic time to execute. +Typically, there are many used blocks and a much smaller number of used blocks +making a call to this directive less expensive than a call to +:ref:`InterfaceRtemsRegionGetInformation`. + +.. 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/region/if/get-segment-size + +.. raw:: latex + + \clearpage + +.. index:: rtems_region_get_segment_size() +.. index:: get size of segment + +.. _InterfaceRtemsRegionGetSegmentSize: + +rtems_region_get_segment_size() +------------------------------- + +Gets the size of the region segment. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_region_get_segment_size( + rtems_id id, + void *segment, + uintptr_t *size + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the region identifier. + +``segment`` + This parameter is the begin address of the segment. + +``size`` + This parameter is the pointer to a `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_ object. When the + directive call is successful, the size of the segment in bytes will be + stored in this object. + +.. rubric:: DESCRIPTION: + +This directive obtains the size in bytes of the segment specified by +``segment`` of the region specified by ``id`` in ``size``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``segment`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``size`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no region associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The segment was not within the region. + +.. rubric:: NOTES: + +The actual length of the allocated segment may be larger than the requested +size because a segment size is always a multiple of the region's page size. + +.. 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. diff --git a/c-user/region/index.rst b/c-user/region/index.rst new file mode 100644 index 0000000..2fb01ec --- /dev/null +++ b/c-user/region/index.rst @@ -0,0 +1,17 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 embedded brains GmbH & Co. KG + +.. index:: regions + +.. _RTEMSAPIClassicRegion: + +Region Manager +************** + +.. toctree:: + + introduction + background + operations + directives diff --git a/c-user/region/introduction.rst b/c-user/region/introduction.rst new file mode 100644 index 0000000..ec44d2e --- /dev/null +++ b/c-user/region/introduction.rst @@ -0,0 +1,63 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/rtems/region/if/group + +.. _RegionManagerIntroduction: + +Introduction +============ + +.. The following list was generated from: +.. spec:/rtems/region/if/create +.. spec:/rtems/region/if/ident +.. spec:/rtems/region/if/delete +.. spec:/rtems/region/if/extend +.. spec:/rtems/region/if/get-segment +.. spec:/rtems/region/if/return-segment +.. spec:/rtems/region/if/resize-segment +.. spec:/rtems/region/if/get-information +.. spec:/rtems/region/if/get-free-information +.. spec:/rtems/region/if/get-segment-size + +The Region Manager provides facilities to dynamically allocate memory in +variable sized units. The directives provided by the Region Manager are: + +* :ref:`InterfaceRtemsRegionCreate` - Creates a region. + +* :ref:`InterfaceRtemsRegionIdent` - Identifies a region by the object name. + +* :ref:`InterfaceRtemsRegionDelete` - Deletes the region. + +* :ref:`InterfaceRtemsRegionExtend` - Extends the region. + +* :ref:`InterfaceRtemsRegionGetSegment` - Gets a segment from the region. + +* :ref:`InterfaceRtemsRegionReturnSegment` - Returns the segment to the region. + +* :ref:`InterfaceRtemsRegionResizeSegment` - Changes the size of the segment. + +* :ref:`InterfaceRtemsRegionGetInformation` - Gets the region information. + +* :ref:`InterfaceRtemsRegionGetFreeInformation` - Gets the region free + information. + +* :ref:`InterfaceRtemsRegionGetSegmentSize` - Gets the size of the region + segment. diff --git a/c-user/region/operations.rst b/c-user/region/operations.rst new file mode 100644 index 0000000..ef41d39 --- /dev/null +++ b/c-user/region/operations.rst @@ -0,0 +1,101 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Operations +========== + +Creating a Region +----------------- + +The ``rtems_region_create`` directive creates a region with the user-defined +name. The user may select FIFO or task priority as the method for placing +waiting tasks in the task wait queue. RTEMS allocates a Region Control Block +(RNCB) from the RNCB free list to maintain the newly created region. RTEMS +also generates a unique region ID which is returned to the calling task. + +It is not possible to calculate the exact number of bytes available to the user +since RTEMS requires overhead for each segment allocated. For example, a +region with one segment that is the size of the entire region has more +available bytes than a region with two segments that collectively are the size +of the entire region. This is because the region with one segment requires +only the overhead for one segment, while the other region requires the overhead +for two segments. + +Due to automatic coalescing, the number of segments in the region dynamically +changes. Therefore, the total overhead required by RTEMS dynamically changes. + +Obtaining Region IDs +-------------------- + +When a region is created, RTEMS generates a unique region ID and assigns it to +the created region until it is deleted. The region ID may be obtained by +either of two methods. First, as the result of an invocation of the +``rtems_region_create`` directive, the region ID is stored in a user provided +location. Second, the region ID may be obtained later using the +``rtems_region_ident`` directive. The region ID is used by other region +manager directives to access this region. + +Adding Memory to a Region +------------------------- + +The ``rtems_region_extend`` directive may be used to add memory to an existing +region. The caller specifies the size in bytes and starting address of the +memory being added. + +Acquiring a Segment +------------------- + +The ``rtems_region_get_segment`` directive attempts to acquire a segment from a +specified region. If the region has enough available free memory, then a +segment is returned successfully to the caller. When the segment cannot be +allocated, one of the following situations applies: + +- By default, the calling task will wait forever to acquire the segment. + +- Specifying the ``RTEMS_NO_WAIT`` option forces an immediate return with an + error status code. + +- Specifying a timeout limits the interval the task will wait before returning + with an error status code. + +If the task waits for the segment, then it is placed in the region's task wait +queue in either FIFO or task priority order. All tasks waiting on a region are +returned an error when the message queue is deleted. + +Releasing a Segment +------------------- + +When a segment is returned to a region by the ``rtems_region_return_segment`` +directive, it is merged with its unallocated neighbors to form the largest +possible segment. The first task on the wait queue is examined to determine if +its segment request can now be satisfied. If so, it is given a segment and +unblocked. This process is repeated until the first task's segment request +cannot be satisfied. + +Obtaining the Size of a Segment +------------------------------- + +The ``rtems_region_get_segment_size`` directive returns the size in bytes of +the specified segment. The size returned includes any "extra" memory included +in the segment because of rounding up to a page size boundary. + +Changing the Size of a Segment +------------------------------ + +The ``rtems_region_resize_segment`` directive is used to change the size in +bytes of the specified segment. The size may be increased or decreased. When +increasing the size of a segment, it is possible that the request cannot be +satisfied. This directive provides functionality similar to the ``realloc()`` +function in the Standard C Library. + +Deleting a Region +----------------- + +A region can be removed from the system and returned to RTEMS with the +``rtems_region_delete`` directive. When a region is deleted, its control block +is returned to the RNCB free list. A region with segments still allocated is +not allowed to be deleted. Any task attempting to do so will be returned an +error. As a result of this directive, all tasks blocked waiting to obtain a +segment from the region will be readied and returned a status code which +indicates that the region was deleted. diff --git a/c-user/region_manager.rst b/c-user/region_manager.rst deleted file mode 100644 index f9cfb46..0000000 --- a/c-user/region_manager.rst +++ /dev/null @@ -1,774 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-4.0 - -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) - -.. index:: regions - -Region Manager -************** - -Introduction -============ - -The region manager provides facilities to dynamically allocate memory in -variable sized units. The directives provided by the region manager are: - -- rtems_region_create_ - Create a region - -- rtems_region_ident_ - Get ID of a region - -- rtems_region_delete_ - Delete a region - -- rtems_region_extend_ - Add memory to a region - -- rtems_region_get_segment_ - Get segment from a region - -- rtems_region_return_segment_ - Return segment to a region - -- rtems_region_get_segment_size_ - Obtain size of a segment - -- rtems_region_resize_segment_ - Change size of a segment - -- rtems_region_get_information_ - Get region information - -- rtems_region_get_free_information_ - Get region free information - -Background -========== - -.. index:: region, definition -.. index:: segment, definition - -Region Manager Definitions --------------------------- - -A region makes up a physically contiguous memory space with user-defined -boundaries from which variable-sized segments are dynamically allocated and -deallocated. A segment is a variable size section of memory which is allocated -in multiples of a user-defined page size. This page size is required to be a -multiple of four greater than or equal to four. For example, if a request for -a 350-byte segment is made in a region with 256-byte pages, then a 512-byte -segment is allocated. - -Regions are organized as doubly linked chains of variable sized memory blocks. -Memory requests are allocated using a first-fit algorithm. If available, the -requester receives the number of bytes requested (rounded up to the next page -size). RTEMS requires some overhead from the region's memory for each segment -that is allocated. Therefore, an application should only modify the memory of -a segment that has been obtained from the region. The application should NOT -modify the memory outside of any obtained segments and within the region's -boundaries while the region is currently active in the system. - -Upon return to the region, the free block is coalesced with its neighbors (if -free) on both sides to produce the largest possible unused block. - -.. index:: region attribute set, building - -Building an Attribute Set -------------------------- - -In general, an attribute set is built by a bitwise OR of the desired attribute -components. The set of valid region attributes is provided in the following -table: - -.. list-table:: - :class: rtems-table - - * - ``RTEMS_FIFO`` - - tasks wait by FIFO (default) - * - ``RTEMS_PRIORITY`` - - tasks wait by priority - -Attribute values are specifically designed to be mutually exclusive, therefore -bitwise OR and addition operations are equivalent as long as each attribute -appears exactly once in the component list. An attribute listed as a default -is not required to appear in the attribute list, although it is a good -programming practice to specify default attributes. If all defaults are -desired, the attribute ``RTEMS_DEFAULT_ATTRIBUTES`` should be specified on this -call. - -This example demonstrates the attribute_set parameter needed to create a region -with the task priority waiting queue discipline. The attribute_set parameter -to the ``rtems_region_create`` directive should be ``RTEMS_PRIORITY``. - -Building an Option Set ----------------------- - -In general, an option is built by a bitwise OR of the desired option -components. The set of valid options for the ``rtems_region_get_segment`` -directive are listed in the following table: - -.. list-table:: - :class: rtems-table - - * - ``RTEMS_WAIT`` - - task will wait for segment (default) - * - ``RTEMS_NO_WAIT`` - - task should not wait - -Option values are specifically designed to be mutually exclusive, therefore -bitwise OR and addition operations are equivalent as long as each option -appears exactly once in the component list. An option listed as a default is -not required to appear in the option list, although it is a good programming -practice to specify default options. If all defaults are desired, the -option ``RTEMS_DEFAULT_OPTIONS`` should be specified on this call. - -This example demonstrates the option parameter needed to poll for a segment. -The option parameter passed to the ``rtems_region_get_segment`` directive -should be ``RTEMS_NO_WAIT``. - -Operations -========== - -Creating a Region ------------------ - -The ``rtems_region_create`` directive creates a region with the user-defined -name. The user may select FIFO or task priority as the method for placing -waiting tasks in the task wait queue. RTEMS allocates a Region Control Block -(RNCB) from the RNCB free list to maintain the newly created region. RTEMS -also generates a unique region ID which is returned to the calling task. - -It is not possible to calculate the exact number of bytes available to the user -since RTEMS requires overhead for each segment allocated. For example, a -region with one segment that is the size of the entire region has more -available bytes than a region with two segments that collectively are the size -of the entire region. This is because the region with one segment requires -only the overhead for one segment, while the other region requires the overhead -for two segments. - -Due to automatic coalescing, the number of segments in the region dynamically -changes. Therefore, the total overhead required by RTEMS dynamically changes. - -Obtaining Region IDs --------------------- - -When a region is created, RTEMS generates a unique region ID and assigns it to -the created region until it is deleted. The region ID may be obtained by -either of two methods. First, as the result of an invocation of the -``rtems_region_create`` directive, the region ID is stored in a user provided -location. Second, the region ID may be obtained later using the -``rtems_region_ident`` directive. The region ID is used by other region -manager directives to access this region. - -Adding Memory to a Region -------------------------- - -The ``rtems_region_extend`` directive may be used to add memory to an existing -region. The caller specifies the size in bytes and starting address of the -memory being added. - -Acquiring a Segment -------------------- - -The ``rtems_region_get_segment`` directive attempts to acquire a segment from a -specified region. If the region has enough available free memory, then a -segment is returned successfully to the caller. When the segment cannot be -allocated, one of the following situations applies: - -- By default, the calling task will wait forever to acquire the segment. - -- Specifying the ``RTEMS_NO_WAIT`` option forces an immediate return with an - error status code. - -- Specifying a timeout limits the interval the task will wait before returning - with an error status code. - -If the task waits for the segment, then it is placed in the region's task wait -queue in either FIFO or task priority order. All tasks waiting on a region are -returned an error when the message queue is deleted. - -Releasing a Segment -------------------- - -When a segment is returned to a region by the ``rtems_region_return_segment`` -directive, it is merged with its unallocated neighbors to form the largest -possible segment. The first task on the wait queue is examined to determine if -its segment request can now be satisfied. If so, it is given a segment and -unblocked. This process is repeated until the first task's segment request -cannot be satisfied. - -Obtaining the Size of a Segment -------------------------------- - -The ``rtems_region_get_segment_size`` directive returns the size in bytes of -the specified segment. The size returned includes any "extra" memory included -in the segment because of rounding up to a page size boundary. - -Changing the Size of a Segment ------------------------------- - -The ``rtems_region_resize_segment`` directive is used to change the size in -bytes of the specified segment. The size may be increased or decreased. When -increasing the size of a segment, it is possible that the request cannot be -satisfied. This directive provides functionality similar to the ``realloc()`` -function in the Standard C Library. - -Deleting a Region ------------------ - -A region can be removed from the system and returned to RTEMS with the -``rtems_region_delete`` directive. When a region is deleted, its control block -is returned to the RNCB free list. A region with segments still allocated is -not allowed to be deleted. Any task attempting to do so will be returned an -error. As a result of this directive, all tasks blocked waiting to obtain a -segment from the region will be readied and returned a status code which -indicates that the region was deleted. - -Directives -========== - -This section details the region manager's directives. A subsection is -dedicated to each of this manager's directives and describes the calling -sequence, related constants, usage, and status codes. - -.. raw:: latex - - \clearpage - -.. index:: create a region - -.. _rtems_region_create: - -REGION_CREATE - Create a region -------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_region_create( - rtems_name name, - void *starting_address, - uintptr_t length, - uintptr_t page_size, - rtems_attribute attribute_set, - rtems_id *id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - region created successfully - * - ``RTEMS_INVALID_NAME`` - - invalid region name - * - ``RTEMS_INVALID_ADDRESS`` - - ``id`` is NULL - * - ``RTEMS_INVALID_ADDRESS`` - - ``starting_address`` is NULL - * - ``RTEMS_TOO_MANY`` - - too many regions created - * - ``RTEMS_INVALID_SIZE`` - - invalid page size - * - ``RTEMS_INVALID_SIZE`` - - the memory area defined by the starting address and the length - parameters is too small - -DESCRIPTION: - This directive creates a region from a contiguous memory area - which starts at starting_address and is length bytes long. The memory area - must be large enough to contain some internal region administration data. - Segments allocated from the region will be a multiple of page_size bytes in - length. The specified page size will be aligned to an - architecture-specific minimum alignment if necessary. - - The assigned region id is returned in id. This region id is used as an - argument to other region related directives to access the region. - - For control and maintenance of the region, RTEMS allocates and initializes - an RNCB from the RNCB free pool. Thus memory from the region is not used - to store the RNCB. However, some overhead within the region is required by - RTEMS each time a segment is constructed in the region. - - Specifying ``RTEMS_PRIORITY`` in attribute_set causes tasks waiting for a - segment to be serviced according to task priority. Specifying - ``RTEMS_FIFO`` in attribute_set or selecting ``RTEMS_DEFAULT_ATTRIBUTES`` - will cause waiting tasks to be serviced in First In-First Out order. - -NOTES: - This directive will obtain the allocator mutex and may cause the calling - task to be preempted. - - The following region attribute constants are defined by RTEMS: - - .. list-table:: - :class: rtems-table - - * - ``RTEMS_FIFO`` - - tasks wait by FIFO (default) - * - ``RTEMS_PRIORITY`` - - tasks wait by priority - -.. raw:: latex - - \clearpage - -.. index:: get ID of a region -.. index:: obtain ID of a region -.. index:: rtems_region_ident - -.. _rtems_region_ident: - -REGION_IDENT - Get ID of a region ---------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_region_ident( - rtems_name name, - rtems_id *id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - region identified successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``id`` is NULL - * - ``RTEMS_INVALID_NAME`` - - region name not found - -DESCRIPTION: - - This directive obtains the region id associated with the region name to be - acquired. If the region name is not unique, then the region id will match - one of the regions with that name. However, this region id is not - guaranteed to correspond to the desired region. The region id is used to - access this region in other region manager directives. - -NOTES: - This directive will not cause the running task to be preempted. - -.. raw:: latex - - \clearpage - -.. index:: delete a region -.. index:: rtems_region_delete - -.. _rtems_region_delete: - -REGION_DELETE - Delete a region -------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_region_delete( - rtems_id id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - region deleted successfully - * - ``RTEMS_INVALID_ID`` - - invalid region id - * - ``RTEMS_RESOURCE_IN_USE`` - - segments still in use - -DESCRIPTION: - This directive deletes the region specified by id. The region cannot be - deleted if any of its segments are still allocated. The RNCB for the - deleted region is reclaimed by RTEMS. - -NOTES: - This directive will obtain the allocator mutex and may cause the calling - task to be preempted. - - The calling task does not have to be the task that created the region. Any - local task that knows the region id can delete the region. - -.. raw:: latex - - \clearpage - -.. index:: add memory to a region -.. index:: region, add memory -.. index:: rtems_region_extend - -.. _rtems_region_extend: - -REGION_EXTEND - Add memory to a region --------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_region_extend( - rtems_id id, - void *starting_address, - uintptr_t length - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - region extended successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``starting_address`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid region id - * - ``RTEMS_INVALID_ADDRESS`` - - invalid address of area to add - -DESCRIPTION: - This directive adds the memory area which starts at - :c:data:`starting_address` for :c:data:`length` bytes to the region - specified by :c:data:`id`. - - There are no alignment requirements for the memory area. The memory area - must be big enough to contain some maintenance blocks. It must not overlap - parts of the current heap memory areas. Disconnected memory areas added to - the heap will lead to used blocks which cover the gaps. Extending with an - inappropriate memory area will corrupt the heap resulting in undefined - behaviour. - -NOTES: - This directive will obtain the allocator mutex and may cause the calling - task to be preempted. - - The calling task does not have to be the task that created the region. Any - local task that knows the region identifier can extend the region. - -.. raw:: latex - - \clearpage - -.. index:: get segment from region -.. index:: rtems_region_get_segment - -.. _rtems_region_get_segment: - -REGION_GET_SEGMENT - Get segment from a region ----------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_region_get_segment( - rtems_id id, - uintptr_t size, - rtems_option option_set, - rtems_interval timeout, - void **segment - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - segment obtained successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``segment`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid region id - * - ``RTEMS_INVALID_SIZE`` - - request is for zero bytes or exceeds the size of maximum segment which is - possible for this region - * - ``RTEMS_UNSATISFIED`` - - segment of requested size not available - * - ``RTEMS_TIMEOUT`` - - timed out waiting for segment - * - ``RTEMS_OBJECT_WAS_DELETED`` - - region deleted while waiting - -DESCRIPTION: - This directive obtains a variable size segment from the region specified by - ``id``. The address of the allocated segment is returned in segment. The - ``RTEMS_WAIT`` and ``RTEMS_NO_WAIT`` components of the options parameter - are used to specify whether the calling tasks wish to wait for a segment to - become available or return immediately if no segment is available. For - either option, if a sufficiently sized segment is available, then the - segment is successfully acquired by returning immediately with the - ``RTEMS_SUCCESSFUL`` status code. - - If the calling task chooses to return immediately and a segment large - enough is not available, then an error code indicating this fact is - returned. If the calling task chooses to wait for the segment and a - segment large enough is not available, then the calling task is placed on - the region's segment wait queue and blocked. If the region was created - with the ``RTEMS_PRIORITY`` option, then the calling task is inserted into - the wait queue according to its priority. However, if the region was - created with the ``RTEMS_FIFO`` option, then the calling task is placed at - the rear of the wait queue. - - The timeout parameter specifies the maximum interval that a task is willing - to wait to obtain a segment. If timeout is set to ``RTEMS_NO_TIMEOUT``, - then the calling task will wait forever. - -NOTES: - This directive will obtain the allocator mutex and may cause the calling - task to be preempted. - - The actual length of the allocated segment may be larger than the requested - size because a segment size is always a multiple of the region's page size. - - The following segment acquisition option constants are defined by RTEMS: - - .. list-table:: - :class: rtems-table - - * - ``RTEMS_WAIT`` - - task will wait for segment (default) - * - ``RTEMS_NO_WAIT`` - - task should not wait - - A clock tick is required to support the timeout functionality of this - directive. - -.. raw:: latex - - \clearpage - -.. index:: return segment to region -.. index:: rtems_region_return_segment - -.. _rtems_region_return_segment: - -REGION_RETURN_SEGMENT - Return segment to a region --------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_region_return_segment( - rtems_id id, - void *segment - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - segment returned successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``segment`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid region id - * - ``RTEMS_INVALID_ADDRESS`` - - segment address not in region - -DESCRIPTION: - This directive returns the segment specified by segment to the region - specified by id. The returned segment is merged with its neighbors to form - the largest possible segment. The first task on the wait queue is examined - to determine if its segment request can now be satisfied. If so, it is - given a segment and unblocked. This process is repeated until the first - task's segment request cannot be satisfied. - -NOTES: - This directive will cause the calling task to be preempted if one or more - local tasks are waiting for a segment and the following conditions exist: - - - a waiting task has a higher priority than the calling task - - - the size of the segment required by the waiting task is less than or - equal to the size of the segment returned. - -.. raw:: latex - - \clearpage - -.. index:: get size of segment -.. index:: rtems_region_get_segment_size - -.. _rtems_region_get_segment_size: - -REGION_GET_SEGMENT_SIZE - Obtain size of a segment --------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_region_get_segment_size( - rtems_id id, - void *segment, - uintptr_t *size - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - segment obtained successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``segment`` is NULL - * - ``RTEMS_INVALID_ADDRESS`` - - ``size`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid region id - * - ``RTEMS_INVALID_ADDRESS`` - - segment address not in region - -DESCRIPTION: - This directive obtains the size in bytes of the specified segment. - -NOTES: - The actual length of the allocated segment may be larger than the requested - size because a segment size is always a multiple of the region's page size. - -.. raw:: latex - - \clearpage - -.. index:: resize segment -.. index:: rtems_region_resize_segment - -.. _rtems_region_resize_segment: - -REGION_RESIZE_SEGMENT - Change size of a segment ------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_region_resize_segment( - rtems_id id, - void *segment, - uintptr_t new_size, - uintptr_t *old_size - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - segment obtained successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``segment`` is NULL - * - ``RTEMS_INVALID_ADDRESS`` - - ``old_size`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid region id - * - ``RTEMS_INVALID_ADDRESS`` - - segment address not in region - * - ``RTEMS_UNSATISFIED`` - - unable to make segment larger - -DESCRIPTION: - This directive is used to increase or decrease the size of a segment. When - increasing the size of a segment, it is possible that there is not memory - available contiguous to the segment. In this case, the request is - unsatisfied. - -NOTES: - This directive will obtain the allocator mutex and may cause the calling - task to be preempted. - - If an attempt to increase the size of a segment fails, then the application - may want to allocate a new segment of the desired size, copy the contents - of the original segment to the new, larger segment and then return the - original segment. - -.. raw:: latex - - \clearpage - -.. index:: obtain region information -.. index:: rtems_region_get_information - -.. _rtems_region_get_information: - -REGION_GET_INFORMATION - Get region information ------------------------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_region_get_information( - rtems_id id, - Heap_Information_block *the_info - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - information obtained successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``the_info`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid region id - -DESCRIPTION: - This directive is used to obtain information about the used and free memory - in the region specified by ``id``. This is a snapshot at the time - of the call. The information will be returned in the structure pointed to - by ``the_info``. - -NOTES: - This directive will obtain the allocator mutex and may cause the calling - task to be preempted. - - This is primarily intended as a mechanism to obtain a diagnostic information. - This method forms am O(n) scan of the free and an O(n) scan of the - used blocks in the region to calculate the information provided. Given that - the execution time is driven by the number of used and free blocks, it can - take a non-deterministic time to execute. - -.. raw:: latex - - \clearpage - -.. index:: obtain region information on free blocks -.. index:: rtems_region_get_free_information - -.. _rtems_region_get_free_information: - -REGION_GET_FREE_INFORMATION - Get region free information ---------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_region_get_free_information( - rtems_id id, - Heap_Information_block *the_info - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - information obtained successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``the_info`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid region id - -DESCRIPTION: - This directive is used to obtain information about the free memory - in the region specified by ``id``. This is a snapshot at the time - of the call. The information will be returned in the structure pointed to - by ``the_info``. - -NOTES: - This directive will obtain the allocator mutex and may cause the calling - task to be preempted. - - This uses the same structure to return information as the - ``rtems_region_get_information`` directive but does not fill in the - used information. - - This is primarily intended as a mechanism to obtain a diagnostic information. - This method forms am O(n) scan of the free in the region to calculate - the information provided. Given that the execution time is driven by - the number of used and free blocks, it can take a non-deterministic - time to execute. Typically, there are many used blocks and a much smaller - number of used blocks making a call to this directive less expensive than - a call to ``rtems_region_get_information``. diff --git a/c-user/regulator/background.rst b/c-user/regulator/background.rst new file mode 100644 index 0000000..f6a6bff --- /dev/null +++ b/c-user/regulator/background.rst @@ -0,0 +1,90 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2023 On-Line Applications Research Corporation (OAR) + +.. _RegulatorManagerBackground: + +Background +========== +The regulator provides facilities to accept bursty input and buffer it +as needed before delivering it at a pre-defined periodic rate. The input +is referred to as the Source, with the output referred to as the +Destination. Messages are accepted from the Source and delivered to +the Destination by a user-provided Delivery function. + +The Regulator implementation uses the RTEMS Classic API Partition Manager +to manage the buffer pool and the RTEMS Classic API Message Queue +Manager to send the buffer to the Delivery thread. The Delivery thread +invokes a user-provided delivery function to get the message to the +Destination. + +Regulator Buffering +------------------- +The regulator is designed to sit logically between two entities -- a +source and a destination, where it limits the traffic sent to the +destination to prevent it from being flooded with messages from the +source. This can be used to accommodate bursts of input from a source +and meter it out to a destination. The maximum number of messages +which can be buffered in the regulator is specified by the +``maximum_messages`` field in the :ref:`InterfaceRtemsRegulatorAttributes` +structure passed as an argument to :ref:`InterfaceRtemsRegulatorCreate`. + +The regulator library accepts an input stream of messages from a +source and delivers them to a destination. The regulator assumes that the +input stream from the source contains sporadic bursts of data which can +exceed the acceptable rate of the destination. By limiting the message rate, +the regulator prevents an overflow of messages. + +The regulator can be configured for the input buffering required to manage +the maximum burst and for the metering rate for the delivery. The delivery +rate is in messages per second. If the sender produces data too fast, +the regulator will buffer the configured number of messages. + +A configuration capability is provided to allow for adaptation to different +message streams. The regulator can also support running multiple instances, +which could be used on independent message streams. + +It is assumed that the application has a design limit on the number of +messages which may be buffered. All messages accepted by the regulator, +assuming no overflow on input, will eventually be output by the Delivery +thread. + +Message Delivery Rate +--------------------- + +The Source sends buffers to the Regulator instance. The Regulator +then sends the buffer via a message queue which delivers them to the +Delivery thread. The Delivery thread executes periodically at a rate +specified by the ``delivery_thread_period`` field in the +:ref:`InterfaceRtemsRegulatorAttributes` structure passed as an argument +to :ref:`InterfaceRtemsRegulatorCreate`. + +During each period, the Delivery thread attempts to receive +up to ``maximum_to_dequeue_per_period`` number of buffers and +invoke the Delivery function to deliver each of them to the +Destination. The ``maximum_to_dequeue_per_period`` field in the +:ref:`InterfaceRtemsRegulatorAttributes` structure passed as an argument +to :ref:`InterfaceRtemsRegulatorCreate`. + +For example, consider a Source that may produce a burst of up to seven +messages every five seconds. But the Destination cannot handle a burst +of seven and either drops messages or gives an error. This can be +accommodated by a Regulator instance configured as follows: + +* ``maximum_messages`` - 7 +* ``delivery_thread_period`` - one second +* ``maximum_to_dequeue_per_period`` - 3 + +In this scenario, the application will use the Delivery thread +:ref:`InterfaceRtemsRegulatorSend` to enqueue the seven messages when they +arrive. The Delivery thread will deliver three messages per second. The +following illustrates this sequence: + +* Time 0: Source sends seven messages +* Time 1: Delivery of messages 1 to 3 +* Time 3: Delivery of messages 4 to 6 +* Time 3: Delivery of message 7 +* Time 4: No messages to deliver + +This configuration of the regulator ensures that the Destination does +not overflow. diff --git a/c-user/regulator/directives.rst b/c-user/regulator/directives.rst new file mode 100644 index 0000000..eea3fff --- /dev/null +++ b/c-user/regulator/directives.rst @@ -0,0 +1,549 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2023 On-Line Applications Research Corporation (OAR) + +.. _RegulatorManagerDirectives: + +Directives +========== + +This section details the directives of the Regulator Manager. A subsection is +dedicated to each of this manager's directives and lists the calling sequence, +parameters, description, return values, and notes of the directive. + +.. *** START of rtems_regulator_create() + +.. raw:: latex + + \clearpage + +.. index:: rtems_regulator_create() +.. index:: create a regulator + +.. _InterfaceRtemsRegulatorCreate: + +rtems_regulator_create() +------------------------ + +Creates a regulator. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_regulator_create( + rtems_regulator_attributes *attributes, + rtems_regulator_instance **regulator + ); + +.. rubric:: PARAMETERS: + +``attributes`` + This parameter is the attributes associated with the regulator + being created. + +``regulator`` + This parameter is the pointer to a regulator instance. When the + directive call is successful, a pointer to the created regulator + will be stored in this object. + +.. rubric:: DESCRIPTION: + +This function creates an instance of a regulator. It uses the provided +``attributes`` to create the instance return in ``regulator``. This instance +will allocate the buffers associated with the regulator instance as well +as the Delivery Thread. + +The ``attributes`` parameter points to an instance of +:ref:`InterfaceRtemsRegulatorAttributes` which is filled in to reflect +the desired configuration of the regulator instance. It defines multiple +characteristics of the the Delivery thread dedicated to this regulator +instance including the priority and stack size. It also defines the +period of the Delivery thread and the maximum number of messages that may +be delivered per period via invocation of the delivery function. + +For each regulator instance, the following resources are allocated: + +* A memory area for the regulator control block using ``malloc()``. + +* A RTEMS Classic API Message Queue is constructed with message + buffer memory allocated using ``malloc()``. Each message consists + of a pointer to the contents and a length field. + +* A RTEMS Classic API Partition. + +* A RTEMS Classic API Rate Monotonic Period. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``attributes`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``regulator`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``deliverer`` field in the structure pointed to by the + ``attributes`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_SIZE` + The ``maximum_messages`` field in the structure pointed to by the + ``attributes`` parameter was 0. + +:c:macro:`RTEMS_INVALID_NUMBER` + The ``maximum_to_dequeue_per_period`` field in the structure pointed + to by the ``attributes`` parameter was 0. + +:c:macro:`RTEMS_NO_MEMORY` + The allocation of memory for the regulator instance failed. + +:c:macro:`RTEMS_NO_MEMORY` + The allocation of memory for the buffers failed. + +:c:macro:`RTEMS_NO_MEMORY` + The allocation of memory for the internal message queue failed. + +.. rubric:: NOTES: + +:ref:`InterfaceRtemsRegulatorCreate` uses +:ref:`InterfaceRtemsPartitionCreate`, +:ref:`InterfaceRtemsMessageQueueConstruct`, +:ref:`InterfaceRtemsTaskCreate`, and :ref:`InterfaceRtemsTaskStart`. If +any of those directives return a status indicating failure, it will be +returned to the caller. + +.. 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. + +* The number of tasks available to the application is configured through the + :ref:`CONFIGURE_MAXIMUM_TASKS` application configuration option. + +* Where the object class corresponding to the directive is configured to use + unlimited objects, the directive may allocate memory from the RTEMS + Workspace. + +.. *** START of rtems_regulator_delete() + +.. raw:: latex + + \clearpage + +.. index:: rtems_regulator_delete() +.. index:: delete a regulator + +.. _InterfaceRtemsRegulatorDelete: + +rtems_regulator_delete() +------------------------ + +Deletes the regulator. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_regulator_delete( + rtems_regulator_instance *regulator, + rtems_interval ticks + ); + +.. rubric:: PARAMETERS: + +``regulator`` + This parameter points to the regulator instance. + +``ticks`` + This parameter specifies the maximum length of time to wait. + +.. rubric:: DESCRIPTION: + +This directive is used to delete the specified ``regulator`` +instance. It will deallocate the resources that were allocated by the +:ref:`InterfaceRtemsRegulatorCreate` directive. + + +This directive ensures that no buffers are outstanding either because the +Source is holding one of more buffers or because they are being held by +the regulator instance pending delivery. + +If the Delivery Thread has been created and is running, this directive will +request the thread to voluntarily exit. This call will wait up to ``ticks`` for the thread to exit. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``regulator`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INCORRECT_STATE` + The ``regulator`` instance was not initialized. + +:c:macro:`RTEMS_RESOURCE_IN_USE` + The ``regulator`` instance has buffers outstanding. + +:c:macro:`RTEMS_TIMEOUT` + The ``regulator`` instance was not able to be deleted within the + specific number of ``ticks``. + +.. rubric:: NOTES: + +It is the responsibility of the user to ensure that any resources +such as sockets or open file descriptors used by the Source or delivery +function are also deleted if necessary. It is likely safer to delete those +delivery resources after deleting the regulator instance rather than before. + + +It is the responsibility of the user to ensure that all buffers associated +with this regulator instance have been released and that none are in +the process of being delivered. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* 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. + +* The calling task does not have to be the task that created the object. Any + local task that knows the object identifier can delete the object. + +* Where the object class corresponding to the directive is configured to use + unlimited objects, the directive may free memory to the RTEMS Workspace. + +.. *** START of rtems_regulator_obtain_buffer() + +.. raw:: latex + + \clearpage + +.. index:: rtems_regulator_obtain_buffer() +.. index:: obtain buffer from regulator + +.. _InterfaceRtemsRegulatorObtainBuffer: + +rtems_regulator_obtain_buffer() +------------------------------- + +Obtain buffer from regulator. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_regulator_obtain_buffer( + rtems_regulator_instance *regulator, + void **buffer + ); + +.. rubric:: PARAMETERS: + +``regulator`` + This parameter is the regulator instance to operate upon. + +``buffer`` + This parameter will point to the buffer allocated. + +.. rubric:: DESCRIPTION: + +This function is used to obtain a buffer from the regulator's pool. The +``buffer`` returned is assumed to be filled in with contents and used +in a subsequent call to :ref:`InterfaceRtemsRegulatorSend`. + +When the ``buffer`` is delivered, it is expected to be released. If the +``buffer`` is not successfully accepted by this method, then it should +be returned using :ref:`InterfaceRtemsRegulatorReleaseBuffer` or used +to send another message. + +The ``buffer`` returned is of the maximum_message_size specified in the +attributes passed in to :ref:`InterfaceRtemsRegulatorCreate`. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``regulator`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INCORRECT_STATE` + The ``regulator`` instance was not initialized. + +.. rubric:: NOTES: + +:ref:`InterfaceRtemsRegulatorObtainBuffer` uses +:ref:`InterfaceRtemsPartitionGetBuffer` and if it returns a status +indicating failure, it will be returned to the caller. + +.. 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. + +.. *** START of rtems_regulator_release_buffer() + +.. raw:: latex + + \clearpage + +.. index:: rtems_regulator_release_buffer() +.. index:: release buffer back to regulator + +.. _InterfaceRtemsRegulatorReleaseBuffer: + +rtems_regulator_release_buffer() +-------------------------------- + +Release buffer to regulator. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_regulator_release_buffer( + rtems_regulator_instance *regulator, + void *buffer + ); + +.. rubric:: PARAMETERS: + +``regulator`` + This parameter is the regulator instance to operate upon. + +``buffer`` + This parameter will point to the buffer to be released. + +.. rubric:: DESCRIPTION: + +This function is used to release a buffer to the regulator's pool. It is +assumed that the ``buffer`` returned will not be used by the application +anymore. + +The ``buffer`` must have previously been allocated by +:ref:`InterfaceRtemsRegulatorObtainBuffer` and NOT yet passed to +:ref:`InterfaceRtemsRegulatorSend`, or it has been sent and delivery +has been completed by the delivery function. + +If a subsequent :ref:`InterfaceRtemsRegulatorSend` using this ``buffer`` +is successful, the ``buffer`` will eventually be processed by the delivery +thread and released. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``regulator`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INCORRECT_STATE` + The ``regulator`` instance was not initialized. + +.. rubric:: NOTES: + +:ref:`InterfaceRtemsRegulatorReleaseBuffer` uses +:ref:`InterfaceRtemsPartitionReturnBuffer` and if it returns a status +indicating failure, it will be returned to the caller. + +.. 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. + +.. *** START of rtems_regulator_send() + +.. raw:: latex + + \clearpage + +.. index:: rtems_regulator_send() +.. index:: send buffer to regulator for delivery + +.. _InterfaceRtemsRegulatorSend: + +rtems_regulator_send() +---------------------- + +Send buffer to regulator. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_regulator_send( + rtems_regulator_instance *regulator, + void *message, + size_t length + ); + +.. rubric:: PARAMETERS: + +``regulator`` + This parameter is the regulator instance to operate upon. + +``message`` + This parameter points to the buffer to send. + +``length`` + This parameter specifies the number of bytes in the ``message``. + +.. rubric:: DESCRIPTION: + +This method is used by the producer to send a ``message`` to the +``regulator`` for later delivery by the delivery thread. The message is +contained in the memory pointed to by ``message`` and is ``length`` +bytes in length. + +It is required that the message buffer was obtained via +:ref:`InterfaceRtemsRegulatorObtainBuffer`. + +It is assumed that the ``message`` buffer has been filled in with +application content to deliver. + +If the :ref:`InterfaceRtemsRegulatorSend` is successful, the ``message`` +buffer is enqueued inside the regulator instance for subsequent delivery. +After the ``message`` is delivered, it may be released by either delivery +function or other application code depending on the implementation. + +The status ``RTEMS_TOO_MANY`` is returned if the regulator's +internal queue is full. This indicates that the configured +maximum number of messages was insufficient. It is the +responsibility of the caller to decide whether to hold messages, +drop them, or print a message that the maximum number of messages +should be increased + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``regulator`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INCORRECT_STATE` + The ``regulator`` instance was not initialized. + +.. rubric:: NOTES: + +:ref:`InterfaceRtemsRegulatorSend` uses +:ref:`InterfaceRtemsMessageQueueSend` and if it returns a status +indicating failure, it will be returned to the caller. + + +.. 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. + +.. *** START of rtems_regulator_get_statistics() + +.. raw:: latex + + \clearpage + +.. index:: rtems_regulator_get_statistics() +.. index:: obtain statistics from regulator + +.. _InterfaceRtemsRegulatorGetStatistics: + +rtems_regulator_get_statistics() +-------------------------------- + +Obtain statistics from regulator. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_regulator_get_statistics( + rtems_regulator_instance *regulator, + rtems_regulator_statistics *statistics + ); + +.. rubric:: PARAMETERS: + +``regulator`` + This parameter is the regulator instance to operate upon. + +``statistics`` + This parameter points to the statistics structure to be filled in. + +.. rubric:: DESCRIPTION: + +This method is used by the application to obtain the current +``statistics`` for this ``regulator``. The statistics information +provided includes: + +* the number of buffers obtained via + :ref:`InterfaceRtemsRegulatorObtainBuffer` +* the number of buffers released via + :ref:`InterfaceRtemsRegulatorReleaseBuffer` +* the number of buffers delivered by the Delivery + Thread via the ``deliverer`` function specified in the + :ref:`InterfaceRtemsRegulatorAttributes` structure provided to + :ref:`InterfaceRtemsRegulatorCreate`` via the ``attibutes`` parameter. +* the ``period_statistics`` for the Delivery Thread. For more details on + period statistics, see :ref:`InterfaceRtemsRateMonotonicPeriodStatistics`. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``regulator`` or ``statistics`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INCORRECT_STATE` + The ``regulator`` instance was not initialized. + +.. rubric:: NOTES: + +The number of buffers outstanding is ``released`` minus +``obtained``. The regulator instance cannot be deleted using +:ref:`InterfaceRtemsRegulatorDelete` until all buffers are released. + +The ``obtained`` and ``released`` values are cumulative over +the life of the Regulator instance and are likely to larger than the +``maximum_messages`` value in the ``attributes`` structure +(:ref:`InterfaceRtemsRegulatorAttributes` +provided to :ref:`InterfaceRtemsRegulatorCreate`. + +.. 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. + diff --git a/c-user/regulator/index.rst b/c-user/regulator/index.rst new file mode 100644 index 0000000..4731b7b --- /dev/null +++ b/c-user/regulator/index.rst @@ -0,0 +1,19 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2023 OAR Corporation + +.. index:: regulator + +.. _RTEMSAPIRegulator + +Regulator Manager +***************** + +.. toctree:: + + introduction + background + operations + directives +.. deprecated-directives +.. removed-directives diff --git a/c-user/regulator/introduction.rst b/c-user/regulator/introduction.rst new file mode 100644 index 0000000..3ad90d3 --- /dev/null +++ b/c-user/regulator/introduction.rst @@ -0,0 +1,25 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2023 On-Line Applications Research Corporation (OAR) + +.. _RegulatorManagerIntroduction: + +Introduction +============ + +The Regulator Manager provides a set of directives to manage a data flow +from a source to a destination. The focus is on regulating the bursty +input so that it is delivered to the destination at a regular rate. +The directives provided by the Regulator Manager are: + +* :ref:`InterfaceRtemsRegulatorCreate` - Creates a regulator. + +* :ref:`InterfaceRtemsRegulatorDelete` - Deletes the regulator. + +* :ref:`InterfaceRtemsRegulatorObtainBuffer` - Obtain buffer from a regulator. + +* :ref:`InterfaceRtemsRegulatorReleaseBuffer` - Release buffer to a regulator. + +* :ref:`InterfaceRtemsRegulatorSend` - Send buffer to a regulator. + +* :ref:`InterfaceRtemsRegulatorGetStatistics` - Obtain statistics for a regulator. diff --git a/c-user/regulator/operations.rst b/c-user/regulator/operations.rst new file mode 100644 index 0000000..a9e5a44 --- /dev/null +++ b/c-user/regulator/operations.rst @@ -0,0 +1,67 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2023 On-Line Applications Research Corporation (OAR) + +.. _RegulatorManagerOperations: + +Operations +========== + +Application Sourcing Data +------------------------- + +The application interacting with the Source will obtain buffers from +the regulator instance, fill them with information, and send them to +the regulator instance. This allows the regulator to buffer bursty input. + +A regulator instance is used as follows from the Source side: + +.. code-block:: c + + while (1) { + use rtems_regulator_obtain_buffer to obtain a buffer + // Perform some input operation to fetch data into the buffer + rtems_regulator_send(buffer, size of message) + } + +The delivery of message buffers to the Destination and subsequent release is +performed in the context of the delivery thread by either the delivery +function or delivery thread. Details are below. + +The sequence diagram below shows the interaction between a message Source, +a Regulator instance, and RTEMS, given the usage described in the above +paragraphs. + +.. _fig-regulator_input_sequence: + +.. figure:: ../../images/c_user/regulator_input_sequence.png + :width: 90% + :alt: Regulator Application Input Source Usage + :figclass: align-center + +As illustrated in the preceding sequence diagram, the Source usually +corresponds to application software reading a system input. The Source +obtains a buffer from the Regulator instance and fills it with incoming +data. The application explicitly obtaining a buffer and filling it in +allows for zero copy operations on the Source side. + +After the Source has sent the message to the Regulator instance, +the Source is free to process another input and the Regulator +instance will ensure that the buffer is delivered to the Delivery +function and Destination. + +Delivery Function +----------------- +The Delivery function is provided by the application for a specific +Regulator instance. Depending on the Destination, it may use a function which +copies the buffer contents (e.g., write()) or which operates directly +on the buffer contents (e.g. DMA from buffer). In the case of a +Destination which copies the buffer contents, the buffer can be released +via :ref:`InterfaceRtemsRegulatorReleaseBuffer` as soon as the function +or copying completes. In the case where the delivery uses the buffer +and returns, the call to :ref:`InterfaceRtemsRegulatorReleaseBuffer` +will occur when the use of the buffer is complete (e.g. completion +of DMA transfer). This explicit and deliberate exposure of buffering +provides the application with the ability to avoid copying the contents. + + diff --git a/c-user/rtems_data_types.rst b/c-user/rtems_data_types.rst index 121d37e..0a5461c 100644 --- a/c-user/rtems_data_types.rst +++ b/c-user/rtems_data_types.rst @@ -1,6 +1,22 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +.. Copyright (C) 2008, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org .. index:: RTEMS Data Types .. index:: data types @@ -8,6 +24,8 @@ RTEMS Data Types **************** +.. _Introduction: + Introduction ============ @@ -16,368 +34,1849 @@ alphabetical order. This is intended to be an overview and the user is encouraged to look at the appropriate chapters in the manual for more information about the usage of the various data types. +.. _ListOfDataTypes: + List of Data Types ================== The following is a complete list of the RTEMS primitive data types in alphabetical order: -.. index:: rtems_address +.. Generated from spec:/rtems/io/if/bsp-output-char-function-type + +.. index:: BSP_output_char_function_type + +.. _InterfaceBSPOutputCharFunctionType: + +BSP_output_char_function_type +----------------------------- + +Polled character output functions shall have this type. + +.. Generated from spec:/rtems/io/if/bsp-polling-getchar-function-type + +.. index:: BSP_polling_getchar_function_type + +.. _InterfaceBSPPollingGetcharFunctionType: + +BSP_polling_getchar_function_type +--------------------------------- + +Polled character input functions shall have this type. + +.. Generated from spec:/rtems/timer/if/classes + +.. index:: Timer_Classes + +.. _InterfaceTimerClasses: + +Timer_Classes +------------- + +The timer class indicates how the timer was most recently fired. + +.. rubric:: ENUMERATORS: + +TIMER_DORMANT + This timer class indicates that the timer was never in use. + +TIMER_INTERVAL + This timer class indicates that the timer is currently in use as an + interval timer which will fire in the context of the clock tick + :term:`ISR`. + +TIMER_INTERVAL_ON_TASK + This timer class indicates that the timer is currently in use as an + interval timer which will fire in the context of the Timer Server task. + +TIMER_TIME_OF_DAY + This timer class indicates that the timer is currently in use as an time of + day timer which will fire in the context of the clock tick :term:`ISR`. + +TIMER_TIME_OF_DAY_ON_TASK + This timer class indicates that the timer is currently in use as an time of + day timer which will fire in the context of the Timer Server task. + +.. Generated from spec:/rtems/config/if/api-table + +.. index:: rtems_api_configuration_table + +.. _InterfaceRtemsApiConfigurationTable: + +rtems_api_configuration_table +----------------------------- + +This structure contains a summary of the Classic API configuration. + +.. rubric:: MEMBERS: + +maximum_tasks + This member contains the maximum number of Classic API Tasks configured for + this application. See :ref:`CONFIGURE_MAXIMUM_TASKS`. + +notepads_enabled + This member is true, if the Classic API Notepads are enabled, otherwise it + is false. + +maximum_timers + This member contains the maximum number of Classic API Timers configured + for this application. See :ref:`CONFIGURE_MAXIMUM_TIMERS`. + +maximum_semaphores + This member contains the maximum number of Classic API Semaphores + configured for this application. See :ref:`CONFIGURE_MAXIMUM_SEMAPHORES`. + +maximum_message_queues + This member contains the maximum number of Classic API Message Queues + configured for this application. See + :ref:`CONFIGURE_MAXIMUM_MESSAGE_QUEUES`. + +maximum_partitions + This member contains the maximum number of Classic API Partitions + configured for this application. See :ref:`CONFIGURE_MAXIMUM_PARTITIONS`. + +maximum_regions + This member contains the maximum number of Classic API Regions configured + for this application. See :ref:`CONFIGURE_MAXIMUM_REGIONS`. + +maximum_ports + This member contains the maximum number of Classic API Dual-Ported Memories + configured for this application. See :ref:`CONFIGURE_MAXIMUM_PORTS`. -``rtems_address`` - The data type used to manage addresses. It is equivalent to a ``void *`` - pointer. +maximum_periods + This member contains the maximum number of Classic API Rate Monotonic + Periods configured for this application. See + :ref:`CONFIGURE_MAXIMUM_PERIODS`. + +maximum_barriers + This member contains the maximum number of Classic API Barriers configured + for this application. See :ref:`CONFIGURE_MAXIMUM_BARRIERS`. + +number_of_initialization_tasks + This member contains the number of Classic API Initialization Tasks + configured for this application. See + :ref:`CONFIGURE_RTEMS_INIT_TASKS_TABLE`. + +User_initialization_tasks_table + This member contains the pointer to Classic API Initialization Tasks Table + of this application. See :ref:`CONFIGURE_RTEMS_INIT_TASKS_TABLE`. + +.. rubric:: DESCRIPTION: + +Use :ref:`InterfaceRtemsConfigurationGetRtemsApiConfiguration` to get the +configuration table. + +.. Generated from spec:/rtems/signal/if/asr .. index:: rtems_asr -``rtems_asr`` - The return type for an RTEMS ASR. +.. _InterfaceRtemsAsr: + +rtems_asr +--------- + +This type defines the return type of routines which are used to process +asynchronous signals. + +.. rubric:: NOTES: + +This type can be used to document asynchronous signal routines in the source +code. + +.. Generated from spec:/rtems/signal/if/asr-entry .. index:: rtems_asr_entry -``rtems_asr_entry`` - The address of the entry point to an RTEMS ASR. +.. _InterfaceRtemsAsrEntry: -.. index:: rtems_attribute +rtems_asr_entry +--------------- + +This type defines the prototype of routines which are used to process +asynchronous signals. + +.. Generated from spec:/rtems/fatal/if/assert-context -``rtems_attribute`` - The data type used to manage the attributes for RTEMS objects. It is - primarily used as an argument to object create routines to specify - characteristics of the new object. +.. index:: rtems_assert_context -.. index:: rtems_boolean +.. _InterfaceRtemsAssertContext: -``rtems_boolean`` - This type is deprecated will be removed in RTEMS 6.1. Use ``bool`` instead. +rtems_assert_context +-------------------- -.. index:: rtems_context +This structure provides the context in which an assertion failed. -``rtems_context`` - This type is deprecated will be removed in RTEMS 6.1. +.. rubric:: MEMBERS: -.. index:: rtems_context_fp +file + This member provides the file name of the source code file containing the + failed assertion statement. -``rtems_context_fp`` - This type is deprecated will be removed in RTEMS 6.1. +line + This member provides the line number in the source code file containing the + failed assertion statement. + +function + This member provides the function name containing the failed assertion + statement. + +failed_expression + This member provides the expression of the failed assertion statement. + +.. Generated from spec:/rtems/attr/if/attribute + +.. index:: rtems_attribute + +.. _InterfaceRtemsAttribute: + +rtems_attribute +--------------- + +This type represents Classic API attributes. + +.. rubric:: NOTES: + +Attributes are primarily used when creating objects. + +.. Generated from spec:/rtems/io/if/device-driver .. index:: rtems_device_driver -``rtems_device_driver`` - The return type for a RTEMS device driver routine. +.. _InterfaceRtemsDeviceDriver: + +rtems_device_driver +------------------- + +This type shall be used in device driver entry declarations and definitions. + +.. rubric:: NOTES: + +Device driver entries return an :c:type:`rtems_status_code` status code. This +type definition helps to document device driver entries in the source code. + +.. Generated from spec:/rtems/io/if/device-driver-entry .. index:: rtems_device_driver_entry -``rtems_device_driver_entry`` - The entry point to a RTEMS device driver routine. +.. _InterfaceRtemsDeviceDriverEntry: + +rtems_device_driver_entry +------------------------- + +Device driver entries shall have this type. + +.. Generated from spec:/rtems/io/if/device-major-number .. index:: rtems_device_major_number -``rtems_device_major_number`` - The data type used to manage device major numbers. +.. _InterfaceRtemsDeviceMajorNumber: + +rtems_device_major_number +------------------------- + +This integer type represents the major number of devices. + +.. rubric:: NOTES: + +The major number of a device is determined by +:ref:`InterfaceRtemsIoRegisterDriver` and the application configuration (see +:ref:`CONFIGURE_MAXIMUM_DRIVERS`) . + +.. Generated from spec:/rtems/io/if/device-minor-number .. index:: rtems_device_minor_number -``rtems_device_minor_number`` - The data type used to manage device minor numbers. +.. _InterfaceRtemsDeviceMinorNumber: + +rtems_device_minor_number +------------------------- + +This integer type represents the minor number of devices. + +.. rubric:: NOTES: + +The minor number of devices is managed by the device driver. + +.. Generated from spec:/rtems/io/if/driver-address-table + +.. index:: rtems_driver_address_table + +.. _InterfaceRtemsDriverAddressTable: + +rtems_driver_address_table +-------------------------- + +This structure contains the device driver entries. + +.. rubric:: MEMBERS: + +initialization_entry + This member is the device driver initialization entry. This entry is called + by :ref:`InterfaceRtemsIoInitialize`. + +open_entry + This member is the device driver open entry. This entry is called by + :ref:`InterfaceRtemsIoOpen`. + +close_entry + This member is the device driver close entry. This entry is called by + :ref:`InterfaceRtemsIoClose`. + +read_entry + This member is the device driver read entry. This entry is called by + :ref:`InterfaceRtemsIoRead`. + +write_entry + This member is the device driver write entry. This entry is called by + :ref:`InterfaceRtemsIoWrite`. -.. index:: rtems_double +control_entry + This member is the device driver control entry. This entry is called by + :ref:`InterfaceRtemsIoControl`. -``rtems_double`` - This type is deprecated will be removed in RTEMS 6.1. Use ``double`` instead. +.. rubric:: DESCRIPTION: + +This structure is used to register a device driver via +:ref:`InterfaceRtemsIoRegisterDriver`. + +.. Generated from spec:/rtems/event/if/set .. index:: rtems_event_set -``rtems_event_set`` - The data type used to manage and manipulate RTEMS event sets with the Event - Manager. +.. _InterfaceRtemsEventSet: + +rtems_event_set +--------------- + +This integer type represents a bit field which can hold exactly 32 individual +events. + +.. Generated from spec:/rtems/fatal/if/exception-frame + +.. index:: rtems_exception_frame + +.. _InterfaceRtemsExceptionFrame: + +rtems_exception_frame +--------------------- + +This structure represents an architecture-dependent exception frame. + +.. Generated from spec:/rtems/userext/if/table + +.. index:: rtems_extensions_table + +.. _InterfaceRtemsExtensionsTable: + +rtems_extensions_table +---------------------- + +The extensions table contains a set of extensions which may be registered in +the system through the :ref:`CONFIGURE_INITIAL_EXTENSIONS` application +configuration option or the :ref:`InterfaceRtemsExtensionCreate` directive. + +.. Generated from spec:/rtems/userext/if/fatal-code + +.. index:: rtems_fatal_code + +.. _InterfaceRtemsFatalCode: + +rtems_fatal_code +---------------- -.. index:: rtems_extension +This integer type represents system termination codes. -``rtems_extension`` - The return type for RTEMS user extension routines. +.. rubric:: DESCRIPTION: + +This integer type is large enough to store a 32-bit integer or a pointer. + +.. rubric:: NOTES: + +The interpretation of a system termination code depends on the system +termination source, see :ref:`InterfaceRtemsFatalSource`. + +.. Generated from spec:/rtems/userext/if/fatal .. index:: rtems_fatal_extension -``rtems_fatal_extension`` - The entry point for a fatal error user extension handler routine. +.. _InterfaceRtemsFatalExtension: + +rtems_fatal_extension +--------------------- + +Fatal extensions are invoked when the system should terminate. + +.. rubric:: NOTES: + +The fatal extensions are invoked in :term:`extension forward order`. + +The fatal extension should be extremely careful with respect to the RTEMS +directives it calls. Depending on the system termination source, the system +may be in an undefined and corrupt state. + +It is recommended to register fatal extensions through :term:`initial extension +sets`, see :ref:`CONFIGURE_INITIAL_EXTENSIONS`. + +.. Generated from spec:/rtems/userext/if/fatal-source + +.. index:: rtems_fatal_source + +.. _InterfaceRtemsFatalSource: + +rtems_fatal_source +------------------ + +This enumeration represents system termination sources. + +.. rubric:: NOTES: + +The system termination code may provide additional information depending on the +system termination source, see :ref:`InterfaceRtemsFatalCode`. + +.. Generated from spec:/rtems/type/if/id .. index:: rtems_id -``rtems_id`` - The data type used to manage and manipulate RTEMS object IDs. +.. _InterfaceRtemsId: + +rtems_id +-------- + +This type represents RTEMS object identifiers. + +.. Generated from spec:/rtems/task/if/initialization-table + +.. index:: rtems_initialization_tasks_table + +.. _InterfaceRtemsInitializationTasksTable: + +rtems_initialization_tasks_table +-------------------------------- + +This structure defines the properties of the Classic API user initialization +task. + +.. rubric:: MEMBERS: + +name + This member defines the task name. + +stack_size + This member defines the task stack size in bytes. + +initial_priority + This member defines the initial task priority. + +attribute_set + This member defines the attribute set of the task. + +entry_point + This member defines the entry point of the task. + +mode_set + This member defines the initial modes of the task. + +argument + This member defines the entry point argument of the task. + +.. Generated from spec:/rtems/intr/if/attributes + +.. index:: rtems_interrupt_attributes -.. index:: rtems_interrupt_frame +.. _InterfaceRtemsInterruptAttributes: -``rtems_interrupt_frame`` - The data structure that defines the format of the interrupt stack frame as it - appears to a user ISR. This data structure is only defined on architectures - that pass the frame pointer to the ISR handler. +rtems_interrupt_attributes +-------------------------- + +This structure provides the attributes of an interrupt vector. + +.. rubric:: MEMBERS: + +is_maskable + This member is true, if the interrupt vector is maskable by + :ref:`InterfaceRtemsInterruptLocalDisable`, otherwise it is false. + Interrupt vectors which are not maskable by + :ref:`InterfaceRtemsInterruptLocalDisable` should be used with care since + they cannot use most operating system services. + +can_enable + This member is true, if the interrupt vector can be enabled by + :ref:`InterfaceRtemsInterruptVectorEnable`, otherwise it is false. When an + interrupt vector can be enabled, this means that the enabled state can + always be changed from disabled to enabled. For an interrupt vector which + can be enabled it follows that it may be enabled. + +maybe_enable + This member is true, if the interrupt vector may be enabled by + :ref:`InterfaceRtemsInterruptVectorEnable`, otherwise it is false. When an + interrupt vector may be enabled, this means that the enabled state may be + changed from disabled to enabled. The requested enabled state change + should be checked by :ref:`InterfaceRtemsInterruptVectorIsEnabled`. Some + interrupt vectors may be optionally available and cannot be enabled on a + particular :term:`target`. + +can_disable + This member is true, if the interrupt vector can be disabled by + :ref:`InterfaceRtemsInterruptVectorDisable`, otherwise it is false. When an + interrupt vector can be disabled, this means that the enabled state can be + changed from enabled to disabled. For an interrupt vector which can be + disabled it follows that it may be disabled. + +maybe_disable + This member is true, if the interrupt vector may be disabled by + :ref:`InterfaceRtemsInterruptVectorDisable`, otherwise it is false. When an + interrupt vector may be disabled, this means that the enabled state may be + changed from enabled to disabled. The requested enabled state change + should be checked by :ref:`InterfaceRtemsInterruptVectorIsEnabled`. Some + interrupt vectors may be always enabled and cannot be disabled on a + particular :term:`target`. + +can_raise + This member is true, if the interrupt vector can be raised by + :ref:`InterfaceRtemsInterruptRaise`, otherwise it is false. + +can_raise_on + This member is true, if the interrupt vector can be raised on a processor + by :ref:`InterfaceRtemsInterruptRaiseOn`, otherwise it is false. + +can_clear + This member is true, if the interrupt vector can be cleared by + :ref:`InterfaceRtemsInterruptClear`, otherwise it is false. + +cleared_by_acknowledge + This member is true, if the pending status of the interrupt associated with + the interrupt vector is cleared by an interrupt acknowledge from the + processor, otherwise it is false. + +can_get_affinity + This member is true, if the affinity set of the interrupt vector can be + obtained by :ref:`InterfaceRtemsInterruptGetAffinity`, otherwise it is + false. + +can_set_affinity + This member is true, if the affinity set of the interrupt vector can be set + by :ref:`InterfaceRtemsInterruptSetAffinity`, otherwise it is false. + +can_be_triggered_by_message + This member is true, if the interrupt associated with the interrupt vector + can be triggered by a message. Interrupts may be also triggered by signals, + :ref:`InterfaceRtemsInterruptRaise`, or + :ref:`InterfaceRtemsInterruptRaiseOn`. Examples for message triggered + interrupts are the PCIe MSI/MSI-X and the ARM GICv3 Locality-specific + Peripheral Interrupts (LPI). + +trigger_signal + This member describes the trigger signal of the interrupt associated with + the interrupt vector. Interrupts are normally triggered by signals which + indicate an interrupt request from a peripheral. Interrupts may be also + triggered by messages, :ref:`InterfaceRtemsInterruptRaise`, or + :ref:`InterfaceRtemsInterruptRaiseOn`. + +.. rubric:: DESCRIPTION: + +The :ref:`InterfaceRtemsInterruptGetAttributes` directive may be used to obtain +the attributes of an interrupt vector. + +.. Generated from spec:/rtems/intr/if/entry + +.. index:: rtems_interrupt_entry + +.. _InterfaceRtemsInterruptEntry: + +rtems_interrupt_entry +--------------------- + +This structure represents an interrupt entry. + +.. rubric:: MEMBERS: + +Members of the type shall not be accessed directly by the application. + +.. rubric:: NOTES: + +This structure shall be treated as an opaque data type from the :term:`API` +point of view. Members shall not be accessed directly. An entry may be +initialized by :ref:`InterfaceRTEMSINTERRUPTENTRYINITIALIZER` or +:ref:`InterfaceRtemsInterruptEntryInitialize`. It may be installed for an +interrupt vector with :ref:`InterfaceRtemsInterruptEntryInstall` and removed +from an interrupt vector by :ref:`InterfaceRtemsInterruptEntryRemove`. + +.. Generated from spec:/rtems/intr/if/handler + +.. index:: rtems_interrupt_handler + +.. _InterfaceRtemsInterruptHandler: + +rtems_interrupt_handler +----------------------- + +Interrupt handler routines shall have this type. + +.. Generated from spec:/rtems/intr/if/level .. index:: rtems_interrupt_level -``rtems_interrupt_level`` - The data structure used with the ``rtems_interrupt_disable``, - ``rtems_interrupt_enable``, and ``rtems_interrupt_flash`` routines. This - data type is CPU dependent and usually corresponds to the contents of the - processor register containing the interrupt mask level. +.. _InterfaceRtemsInterruptLevel: + +rtems_interrupt_level +--------------------- + +This integer type represents interrupt levels. + +.. Generated from spec:/rtems/intr/if/lock + +.. index:: rtems_interrupt_lock + +.. _InterfaceRtemsInterruptLock: + +rtems_interrupt_lock +-------------------- + +This structure represents an ISR lock. + +.. Generated from spec:/rtems/intr/if/lock-context + +.. index:: rtems_interrupt_lock_context + +.. _InterfaceRtemsInterruptLockContext: + +rtems_interrupt_lock_context +---------------------------- + +This structure provides an ISR lock context for acquire and release pairs. + +.. Generated from spec:/rtems/intr/if/per-handler-routine + +.. index:: rtems_interrupt_per_handler_routine + +.. _InterfaceRtemsInterruptPerHandlerRoutine: + +rtems_interrupt_per_handler_routine +----------------------------------- + +Visitor routines invoked by :ref:`InterfaceRtemsInterruptHandlerIterate` shall +have this type. + +.. Generated from spec:/rtems/intr/if/server-action + +.. index:: rtems_interrupt_server_action + +.. _InterfaceRtemsInterruptServerAction: + +rtems_interrupt_server_action +----------------------------- + +This structure represents an interrupt server action. + +.. rubric:: MEMBERS: + +Members of the type shall not be accessed directly by the application. + +.. rubric:: NOTES: + +This structure shall be treated as an opaque data type from the :term:`API` +point of view. Members shall not be accessed directly. + +.. Generated from spec:/rtems/intr/if/server-config + +.. index:: rtems_interrupt_server_config + +.. _InterfaceRtemsInterruptServerConfig: + +rtems_interrupt_server_config +----------------------------- + +This structure defines an interrupt server configuration. + +.. rubric:: MEMBERS: + +Members of the type shall not be accessed directly by the application. + +.. rubric:: NOTES: + +See also :ref:`InterfaceRtemsInterruptServerCreate`. + +.. Generated from spec:/rtems/intr/if/server-control + +.. index:: rtems_interrupt_server_control + +.. _InterfaceRtemsInterruptServerControl: + +rtems_interrupt_server_control +------------------------------ + +This structure represents an interrupt server. + +.. rubric:: MEMBERS: + +Members of the type shall not be accessed directly by the application. + +.. rubric:: NOTES: + +This structure shall be treated as an opaque data type from the :term:`API` +point of view. Members shall not be accessed directly. The structure is +initialized by :ref:`InterfaceRtemsInterruptServerCreate` and maintained by the +interrupt server support. + +.. Generated from spec:/rtems/intr/if/server-entry + +.. index:: rtems_interrupt_server_entry + +.. _InterfaceRtemsInterruptServerEntry: + +rtems_interrupt_server_entry +---------------------------- + +This structure represents an interrupt server entry. + +.. rubric:: MEMBERS: + +Members of the type shall not be accessed directly by the application. + +.. rubric:: NOTES: + +This structure shall be treated as an opaque data type from the :term:`API` +point of view. Members shall not be accessed directly. An entry is +initialized by :ref:`InterfaceRtemsInterruptServerEntryInitialize` and +destroyed by :ref:`InterfaceRtemsInterruptServerEntryDestroy`. Interrupt +server actions can be prepended to the entry by +:ref:`InterfaceRtemsInterruptServerActionPrepend`. The entry is submitted to +be serviced by :ref:`InterfaceRtemsInterruptServerEntrySubmit`. + +.. Generated from spec:/rtems/intr/if/server-request + +.. index:: rtems_interrupt_server_request + +.. _InterfaceRtemsInterruptServerRequest: + +rtems_interrupt_server_request +------------------------------ + +This structure represents an interrupt server request. + +.. rubric:: MEMBERS: + +Members of the type shall not be accessed directly by the application. + +.. rubric:: NOTES: + +This structure shall be treated as an opaque data type from the :term:`API` +point of view. Members shall not be accessed directly. A request is +initialized by :ref:`InterfaceRtemsInterruptServerRequestInitialize` and +destroyed by :ref:`InterfaceRtemsInterruptServerRequestDestroy`. The interrupt +vector of the request can be set by +:ref:`InterfaceRtemsInterruptServerRequestSetVector`. The request is submitted +to be serviced by :ref:`InterfaceRtemsInterruptServerRequestSubmit`. + +.. Generated from spec:/rtems/intr/if/signal-variant + +.. index:: rtems_interrupt_signal_variant + +.. _InterfaceRtemsInterruptSignalVariant: + +rtems_interrupt_signal_variant +------------------------------ + +This enumeration provides interrupt trigger signal variants. + +.. rubric:: ENUMERATORS: + +RTEMS_INTERRUPT_UNSPECIFIED_SIGNAL + This interrupt signal variant indicates that the interrupt trigger signal + is unspecified. + +RTEMS_INTERRUPT_NO_SIGNAL + This interrupt signal variant indicates that the interrupt cannot be + triggered by a signal. + +RTEMS_INTERRUPT_SIGNAL_LEVEL_LOW + This interrupt signal variant indicates that the interrupt is triggered by + a low level signal. + +RTEMS_INTERRUPT_SIGNAL_LEVEL_HIGH + This interrupt signal variant indicates that the interrupt is triggered by + a high level signal. + +RTEMS_INTERRUPT_SIGNAL_EDGE_FALLING + This interrupt signal variant indicates that the interrupt is triggered by + a falling edge signal. + +RTEMS_INTERRUPT_SIGNAL_EDGE_RAISING + This interrupt signal variant indicates that the interrupt is triggered by + a raising edge signal. + +.. Generated from spec:/rtems/type/if/interval .. index:: rtems_interval -``rtems_interval`` - The data type used to manage and manipulate time intervals. Intervals are - non-negative integers used to measure the length of time in clock ticks. +.. _InterfaceRtemsInterval: + +rtems_interval +-------------- + +This type represents clock tick intervals. + +.. Generated from spec:/rtems/intr/if/isr .. index:: rtems_isr -``rtems_isr`` - The return type of a function implementing an RTEMS ISR. +.. _InterfaceRtemsIsr: + +rtems_isr +--------- + +This type defines the return type of interrupt service routines. + +.. rubric:: DESCRIPTION: + +This type can be used to document interrupt service routines in the source +code. + +.. Generated from spec:/rtems/intr/if/isr-entry .. index:: rtems_isr_entry -``rtems_isr_entry`` - The address of the entry point to an RTEMS ISR. It is equivalent to the - entry point of the function implementing the ISR. +.. _InterfaceRtemsIsrEntry: -.. index:: rtems_mp_packet_classes +rtems_isr_entry +--------------- + +Interrupt service routines installed by :ref:`InterfaceRtemsInterruptCatch` +shall have this type. + +.. Generated from spec:/rtems/message/if/config + +.. index:: rtems_message_queue_config + +.. _InterfaceRtemsMessageQueueConfig: + +rtems_message_queue_config +-------------------------- + +This structure defines the configuration of a message queue constructed by +:ref:`InterfaceRtemsMessageQueueConstruct`. + +.. rubric:: MEMBERS: + +name + This member defines the name of the message queue. -``rtems_mp_packet_classes`` - The enumerated type which specifies the categories of multiprocessing - messages. For example, one of the classes is for messages that must be - processed by the Task Manager. +maximum_pending_messages + This member defines the maximum number of pending messages supported by the + message queue. + +maximum_message_size + This member defines the maximum message size supported by the message + queue. + +storage_area + This member shall point to the message buffer storage area begin. The + message buffer storage area for the message queue shall be an array of the + type defined by :ref:`InterfaceRTEMSMESSAGEQUEUEBUFFER` with a maximum + message size equal to the maximum message size of this configuration. + +storage_size + This member defines size of the message buffer storage area in bytes. + +storage_free + This member defines the optional handler to free the message buffer storage + area. It is called when the message queue is deleted. It is called from + task context under protection of the object allocator lock. It is allowed + to call :c:func:`free` in this handler. If handler is `NULL + <https://en.cppreference.com/w/c/types/NULL>`_, then no action will be + performed. + +attributes + This member defines the attributes of the message queue. + +.. Generated from spec:/rtems/mode/if/mode .. index:: rtems_mode -``rtems_mode`` - The data type used to manage and dynamically manipulate the execution mode of - an RTEMS task. +.. _InterfaceRtemsMode: + +rtems_mode +---------- + +This type represents a Classic API task mode set. + +.. Generated from spec:/rtems/type/if/mp-packet-classes + +.. index:: rtems_mp_packet_classes + +.. _InterfaceRtemsMpPacketClasses: + +rtems_mp_packet_classes +----------------------- + +This enumeration defines the MPCI packet classes. + +.. Generated from spec:/rtems/type/if/mpci-entry .. index:: rtems_mpci_entry -``rtems_mpci_entry`` - The return type of an RTEMS MPCI routine. +.. _InterfaceRtemsMpciEntry: + +rtems_mpci_entry +---------------- + +MPCI handler routines shall have this return type. + +.. Generated from spec:/rtems/type/if/mpci-get-packet-entry .. index:: rtems_mpci_get_packet_entry -``rtems_mpci_get_packet_entry`` - The address of the entry point to the get packet routine for an MPCI - implementation. +.. _InterfaceRtemsMpciGetPacketEntry: + +rtems_mpci_get_packet_entry +--------------------------- + +MPCI get packet routines shall have this type. + +.. Generated from spec:/rtems/type/if/mpci-initialization-entry .. index:: rtems_mpci_initialization_entry -``rtems_mpci_initialization_entry`` - The address of the entry point to the initialization routine for an MPCI - implementation. +.. _InterfaceRtemsMpciInitializationEntry: + +rtems_mpci_initialization_entry +------------------------------- + +MPCI initialization routines shall have this type. + +.. Generated from spec:/rtems/type/if/mpci-receive-packet-entry .. index:: rtems_mpci_receive_packet_entry -``rtems_mpci_receive_packet_entry`` - The address of the entry point to the receive packet routine for an MPCI - implementation. +.. _InterfaceRtemsMpciReceivePacketEntry: + +rtems_mpci_receive_packet_entry +------------------------------- + +MPCI receive packet routines shall have this type. + +.. Generated from spec:/rtems/type/if/mpci-return-packet-entry .. index:: rtems_mpci_return_packet_entry -``rtems_mpci_return_packet_entry`` - The address of the entry point to the return packet routine for an MPCI - implementation. +.. _InterfaceRtemsMpciReturnPacketEntry: + +rtems_mpci_return_packet_entry +------------------------------ + +MPCI return packet routines shall have this type. + +.. Generated from spec:/rtems/type/if/mpci-send-packet-entry .. index:: rtems_mpci_send_packet_entry -``rtems_mpci_send_packet_entry`` - The address of the entry point to the send packet routine for an MPCI - implementation. +.. _InterfaceRtemsMpciSendPacketEntry: + +rtems_mpci_send_packet_entry +---------------------------- + +MPCI send packet routines shall have this type. + +.. Generated from spec:/rtems/type/if/mpci-table .. index:: rtems_mpci_table -``rtems_mpci_table`` - The data structure containing the configuration information for an MPCI. +.. _InterfaceRtemsMpciTable: + +rtems_mpci_table +---------------- + +This type represents the user-provided MPCI control. + +.. Generated from spec:/rtems/type/if/multiprocessing-table + +.. index:: rtems_multiprocessing_table + +.. _InterfaceRtemsMultiprocessingTable: + +rtems_multiprocessing_table +--------------------------- + +This type represents the user-provided MPCI configuration. + +.. Generated from spec:/rtems/type/if/name .. index:: rtems_name -``rtems_name`` - The data type used to contain the name of a Classic API object. It is an - unsigned thirty-two bit integer which can be treated as a numeric value or - initialized using ``rtems_build_name`` to contain four ASCII characters. +.. _InterfaceRtemsName: + +rtems_name +---------- + +This type represents Classic API object names. + +.. rubric:: DESCRIPTION: + +It is an unsigned 32-bit integer which can be treated as a numeric value or +initialized using :ref:`InterfaceRtemsBuildName` to encode four ASCII +characters. A value of zero may have a special meaning in some directives. + +.. Generated from spec:/rtems/object/if/api-class-information + +.. index:: rtems_object_api_class_information + +.. _InterfaceRtemsObjectApiClassInformation: + +rtems_object_api_class_information +---------------------------------- + +This structure is used to return information to the application about the +objects configured for a specific API/Class combination. + +.. rubric:: MEMBERS: + +minimum_id + This member contains the minimum valid object identifier for this class. + +maximum_id + This member contains the maximum valid object identifier for this class. + +maximum + This member contains the maximum number of active objects configured for + this class. + +auto_extend + This member is true, if this class is configured for automatic object + extension, otherwise it is false. + +unallocated + This member contains the number of currently inactive objects of this + class. + +.. Generated from spec:/rtems/option/if/option .. index:: rtems_option -``rtems_option`` - The data type used to specify which behavioral options the caller desires. - It is commonly used with potentially blocking directives to specify whether - the caller is willing to block or return immediately with an error indicating - that the resource was not available. +.. _InterfaceRtemsOption: + +rtems_option +------------ + +This type represents a Classic API directive option set. + +.. Generated from spec:/rtems/type/if/packet-prefix .. index:: rtems_packet_prefix -``rtems_packet_prefix`` - The data structure that defines the first bytes in every packet sent between - nodes in an RTEMS multiprocessor system. It contains routing information - that is expected to be used by the MPCI layer. +.. _InterfaceRtemsPacketPrefix: + +rtems_packet_prefix +------------------- + +This type represents the prefix found at the beginning of each MPCI packet sent +between nodes. + +.. Generated from spec:/rtems/ratemon/if/period-states + +.. index:: rtems_rate_monotonic_period_states + +.. _InterfaceRtemsRateMonotonicPeriodStates: + +rtems_rate_monotonic_period_states +---------------------------------- + +This enumeration defines the states in which a period may be. + +.. rubric:: ENUMERATORS: + +RATE_MONOTONIC_INACTIVE + This status indicates the period is off the watchdog chain, and has never + been initialized. + +RATE_MONOTONIC_ACTIVE + This status indicates the period is on the watchdog chain, and running. + The owner may be executing or blocked waiting on another object. + +RATE_MONOTONIC_EXPIRED + This status indicates the period is off the watchdog chain, and has + expired. The owner may still execute and has taken too much time to + complete this iteration of the period. + +.. Generated from spec:/rtems/ratemon/if/period-statistics + +.. index:: rtems_rate_monotonic_period_statistics + +.. _InterfaceRtemsRateMonotonicPeriodStatistics: + +rtems_rate_monotonic_period_statistics +-------------------------------------- + +This structure provides the statistics of a period. + +.. rubric:: MEMBERS: + +count + This member contains the number of periods executed. + +missed_count + This member contains the number of periods missed. + +min_cpu_time + This member contains the least amount of processor time used in a period. + +max_cpu_time + This member contains the highest amount of processor time used in a period. + +total_cpu_time + This member contains the total amount of processor time used in a period. + +min_wall_time + This member contains the least amount of :term:`CLOCK_MONOTONIC` time used + in a period. + +max_wall_time + This member contains the highest amount of :term:`CLOCK_MONOTONIC` time + used in a period. + +total_wall_time + This member contains the total amount of :term:`CLOCK_MONOTONIC` time used + in a period. + +.. Generated from spec:/rtems/ratemon/if/period-status + +.. index:: rtems_rate_monotonic_period_status + +.. _InterfaceRtemsRateMonotonicPeriodStatus: + +rtems_rate_monotonic_period_status +---------------------------------- + +This structure provides the detailed status of a period. + +.. rubric:: MEMBERS: + +owner + This member contains the identifier of the owner task of the period. + +state + This member contains the state of the period. + +since_last_period + This member contains the time elapsed since the last successful invocation + :ref:`InterfaceRtemsRateMonotonicPeriod` using :term:`CLOCK_MONOTONIC`. If + the period is expired or has not been initiated, then this value has no + meaning. + +executed_since_last_period + This member contains the processor time consumed by the owner task since + the last successful invocation :ref:`InterfaceRtemsRateMonotonicPeriod`. If + the period is expired or has not been initiated, then this value has no + meaning. + +postponed_jobs_count + This member contains the count of jobs which are not released yet. + +.. Handwritten + +.. index:: rtems_regulator_attributes + +.. _InterfaceRtemsRegulatorAttributes: + +rtems_regulator_attributes +-------------------------- + +This structure defines the configuration of a regulator created by +:ref:`InterfaceRtemsRegulatorCreate`. + +.. rubric:: MEMBERS: + +deliverer + This member contains a pointer to an application function invoked by + the Delivery thread to output a message to the destination. + +deliverer_context + This member contains a pointer to an application defined context which + is passed to delivery function. + +maximum_message_size + This member contains the maximum size message to process. + +maximum_messages + This member contains the maximum number of messages to be able to buffer. + +output_thread_priority + This member contains the priority of output thread. + +output_thread_stack_size + This member contains the Stack size of output thread. + +output_thread_period + This member contains the period (in ticks) of output thread. + +maximum_to_dequeue_per_period + This member contains the maximum number of messages the output thread + should dequeue and deliver per period. + +.. rubric:: NOTES: + +This type is passed as an argument to :ref:`InterfaceRtemsRegulatorCreate`. + +.. Handwritten + +.. index:: rtems_regulator_deliverer + +.. _InterfaceRtemsRegulatorDeliverer: + +rtems_regulator_deliverer +------------------------- + +This type represents the function signature used to specify a delivery +function for the RTEMS Regulator. + +.. rubric:: NOTES: + +This type is used in the :ref:`InterfaceRtemsRegulatorAttributes` +structure which is passed as an argument to +:ref:`InterfaceRtemsRegulatorCreate`. + +.. Handwritten + +.. index:: rtems_regulator_statistics + +.. _InterfaceRtemsRegulatorStatistics: + +rtems_regulator_statistics +-------------------------- + +This structure defines the statistics maintained by each Regulator instance. + +.. rubric:: MEMBERS: + +obtained + This member contains the number of successfully obtained buffers. + +released + This member contains the number of successfully released buffers. + +delivered + This member contains the number of successfully delivered buffers. + +period_statistics + This member contains the Rate Monotonic Period + statistics for the Delivery Thread. It is an instance of the + :ref:`InterfaceRtemsRateMonotonicPeriodStatistics` structure. + +.. rubric:: NOTES: + +This type is passed as an argument to +:ref:`InterfaceRtemsRegulatorGetStatistics`. + +.. Generated from spec:/rtems/signal/if/set .. index:: rtems_signal_set -``rtems_signal_set`` - The data type used to manage and manipulate RTEMS signal sets with the Signal - Manager. +.. _InterfaceRtemsSignalSet: + +rtems_signal_set +---------------- -.. index:: int8_t +This integer type represents a bit field which can hold exactly 32 individual +signals. -``int8_t`` - The C99 data type that corresponds to signed eight bit integers. This data - type is defined by RTEMS in a manner that ensures it is portable across - different target processors. +.. Generated from spec:/rtems/config/if/stack-allocate-hook -.. index:: int16_t +.. index:: rtems_stack_allocate_hook -``int16_t`` - The C99 data type that corresponds to signed sixteen bit integers. This data - type is defined by RTEMS in a manner that ensures it is portable across - different target processors. +.. _InterfaceRtemsStackAllocateHook: -.. index:: int32_t +rtems_stack_allocate_hook +------------------------- -``int32_t`` - The C99 data type that corresponds to signed thirty-two bit integers. This - data type is defined by RTEMS in a manner that ensures it is portable across - different target processors. +A thread stack allocator allocate handler shall have this type. -.. index:: int64_t +.. Generated from spec:/rtems/config/if/stack-allocate-init-hook -``int64_t`` - The C99 data type that corresponds to signed sixty-four bit integers. This - data type is defined by RTEMS in a manner that ensures it is portable across - different target processors. +.. index:: rtems_stack_allocate_init_hook -.. index:: rtems_single +.. _InterfaceRtemsStackAllocateInitHook: -``rtems_single`` - This type is deprecated will be removed in RTEMS 6.1. Use ``float`` instead. +rtems_stack_allocate_init_hook +------------------------------ + +A task stack allocator initialization handler shall have this type. + +.. Generated from spec:/rtems/config/if/stack-free-hook + +.. index:: rtems_stack_free_hook + +.. _InterfaceRtemsStackFreeHook: + +rtems_stack_free_hook +--------------------- + +A task stack allocator free handler shall have this type. + +.. Generated from spec:/rtems/status/if/code .. index:: rtems_status_code -``rtems_status_code`` - The return type for most RTEMS services. This is an enumerated type of - approximately twenty-five values. In general, when a service returns a - particular status code, it indicates that a very specific error condition has - occurred. +.. _InterfaceRtemsStatusCode: + +rtems_status_code +----------------- + +This enumeration provides status codes for directives of the Classic API. + +.. rubric:: ENUMERATORS: + +RTEMS_SUCCESSFUL + This status code indicates successful completion of a requested operation. + +RTEMS_TASK_EXITTED + This status code indicates that a thread exitted. + +RTEMS_MP_NOT_CONFIGURED + This status code indicates that multiprocessing was not configured. + +RTEMS_INVALID_NAME + This status code indicates that an object name was invalid. + +RTEMS_INVALID_ID + This status code indicates that an object identifier was invalid. + +RTEMS_TOO_MANY + This status code indicates you have attempted to create too many instances + of a particular object class. + +RTEMS_TIMEOUT + This status code indicates that a blocking directive timed out. + +RTEMS_OBJECT_WAS_DELETED + This status code indicates the object was deleted while the thread was + blocked waiting. + +RTEMS_INVALID_SIZE + This status code indicates that a specified size was invalid. + +RTEMS_INVALID_ADDRESS + This status code indicates that a specified address was invalid. + +RTEMS_INVALID_NUMBER + This status code indicates that a specified number was invalid. + +RTEMS_NOT_DEFINED + This status code indicates that the item has not been initialized. + +RTEMS_RESOURCE_IN_USE + This status code indicates that the object still had resources in use. + +RTEMS_UNSATISFIED + This status code indicates that the request was not satisfied. + +RTEMS_INCORRECT_STATE + This status code indicates that an object was in wrong state for the + requested operation. + +RTEMS_ALREADY_SUSPENDED + This status code indicates that the thread was already suspended. + +RTEMS_ILLEGAL_ON_SELF + This status code indicates that the operation was illegal on the calling + thread. + +RTEMS_ILLEGAL_ON_REMOTE_OBJECT + This status code indicates that the operation was illegal on a remote + object. + +RTEMS_CALLED_FROM_ISR + This status code indicates that the operation should not be called from + this execution environment. + +RTEMS_INVALID_PRIORITY + This status code indicates that an invalid thread priority was provided. + +RTEMS_INVALID_CLOCK + This status code indicates that a specified date or time was invalid. + +RTEMS_INVALID_NODE + This status code indicates that a specified node identifier was invalid. + +RTEMS_NOT_CONFIGURED + This status code indicates that the directive was not configured. + +RTEMS_NOT_OWNER_OF_RESOURCE + This status code indicates that the caller was not the owner of the + resource. + +RTEMS_NOT_IMPLEMENTED + This status code indicates the directive or requested portion of the + directive is not implemented. This is a hint that you have stumbled across + an opportunity to submit code to the RTEMS Project. + +RTEMS_INTERNAL_ERROR + This status code indicates that an internal RTEMS inconsistency was + detected. + +RTEMS_NO_MEMORY + This status code indicates that the directive attempted to allocate memory + but was unable to do so. + +RTEMS_IO_ERROR + This status code indicates a device driver IO error. + +RTEMS_INTERRUPTED + This status code is used internally by the implementation to indicate a + blocking device driver call has been interrupted and should be reflected to + the caller as interrupted. + +RTEMS_PROXY_BLOCKING + This status code is used internally by the implementation when performing + operations on behalf of remote tasks. This is referred to as proxying + operations and this status indicates that the operation could not be + completed immediately and the proxy is blocking. + +.. Generated from spec:/rtems/task/if/task .. index:: rtems_task -``rtems_task`` - The return type for an RTEMS Task. +.. _InterfaceRtemsTask: + +rtems_task +---------- + +This type defines the return type of task entry points. + +.. rubric:: DESCRIPTION: + +This type can be used to document task entry points in the source code. + +.. Generated from spec:/rtems/task/if/argument .. index:: rtems_task_argument -``rtems_task_argument`` - The data type for the argument passed to each RTEMS task. In RTEMS 4.7 and - older, this is an unsigned thirty-two bit integer. In RTEMS 4.8 and newer, - this is based upon the C99 type ``uintptr_t`` which is guaranteed to be an - integer large enough to hold a pointer on the target architecture. +.. _InterfaceRtemsTaskArgument: + +rtems_task_argument +------------------- + +This integer type represents task argument values. + +.. rubric:: NOTES: + +The type is an architecture-specific unsigned integer type which is large +enough to represent pointer values and 32-bit unsigned integers. + +.. Generated from spec:/rtems/userext/if/task-begin .. index:: rtems_task_begin_extension -``rtems_task_begin_extension`` - The entry point for a task beginning execution user extension handler - routine. +.. _InterfaceRtemsTaskBeginExtension: + +rtems_task_begin_extension +-------------------------- + +Task begin extensions are invoked when a task begins execution. + +.. rubric:: NOTES: + +The task begin extensions are invoked in :term:`extension forward order`. + +Task begin extensions are invoked with thread dispatching enabled. This allows +the use of dynamic memory allocation, creation of POSIX keys, and use of C++ +thread-local storage. Blocking synchronization primitives are allowed also. + +The task begin extensions are invoked before the global construction. + +The task begin extensions may be called as a result of a task restart through +:ref:`InterfaceRtemsTaskRestart`. + +.. Generated from spec:/rtems/task/if/config + +.. index:: rtems_task_config + +.. _InterfaceRtemsTaskConfig: + +rtems_task_config +----------------- + +This structure defines the configuration of a task constructed by +:ref:`InterfaceRtemsTaskConstruct`. + +.. rubric:: MEMBERS: + +name + This member defines the name of the task. + +initial_priority + This member defines the initial priority of the task. + +storage_area + This member shall point to the task storage area begin. The task storage + area will contain the task stack, the thread-local storage, and the + floating-point context on architectures with a separate floating-point + context. + + The task storage area begin address and size should be aligned by + :c:macro:`RTEMS_TASK_STORAGE_ALIGNMENT`. To avoid memory waste, use + :c:func:`RTEMS_ALIGNED` and :c:macro:`RTEMS_TASK_STORAGE_ALIGNMENT` to + enforce the recommended alignment of a statically allocated task storage + area. + +storage_size + This member defines size of the task storage area in bytes. Use the + :ref:`InterfaceRTEMSTASKSTORAGESIZE` macro to determine the recommended + task storage area size. + +maximum_thread_local_storage_size + This member defines the maximum thread-local storage size supported by the + task storage area. Use :c:func:`RTEMS_ALIGN_UP` and + :c:macro:`RTEMS_TASK_STORAGE_ALIGNMENT` to adjust the size to meet the + minimum alignment requirement of a thread-local storage area used to + construct a task. + + If the value is less than the actual thread-local storage size, then the + task construction by :ref:`InterfaceRtemsTaskConstruct` fails. + + If the is less than the task storage area size, then the task construction + by :ref:`InterfaceRtemsTaskConstruct` fails. + + The actual thread-local storage size is determined when the application + executable is linked. The ``rtems-exeinfo`` command line tool included in + the RTEMS Tools can be used to obtain the thread-local storage size and + alignment of an application executable. + + The application may configure the maximum thread-local storage size for all + threads explicitly through the + :ref:`CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE` configuration option. + +storage_free + This member defines the optional handler to free the task storage area. It + is called on exactly two mutually exclusive occasions. Firstly, when the + task construction aborts due to a failed task create extension, or + secondly, when the task is deleted. It is called from task context under + protection of the object allocator lock. It is allowed to call + :c:func:`free` in this handler. If handler is `NULL + <https://en.cppreference.com/w/c/types/NULL>`_, then no action will be + performed. + +initial_modes + This member defines the initial modes of the task. + +attributes + This member defines the attributes of the task. + +.. Generated from spec:/rtems/userext/if/task-create .. index:: rtems_task_create_extension -``rtems_task_create_extension`` - The entry point for a task creation execution user extension handler routine. +.. _InterfaceRtemsTaskCreateExtension: + +rtems_task_create_extension +--------------------------- + +Task create extensions are invoked when a task is created. + +.. rubric:: NOTES: + +The task create extensions are invoked in :term:`extension forward order`. + +The task create extensions are invoked after a new task has been completely +initialized, but before it is started. + +While normal tasks are created, the executing thread is the owner of the object +allocator mutex. The object allocator mutex allows nesting, so the normal +memory allocation routines can be used allocate memory for the created thread. + +If the task create extension returns :c:macro:`false`, then the task create +operation stops immediately and the entire task create operation will fail. In +this case, all task delete extensions are invoked, see +:ref:`InterfaceRtemsTaskDeleteExtension`. + +.. Generated from spec:/rtems/userext/if/task-delete .. index:: rtems_task_delete_extension -``rtems_task_delete_extension`` - The entry point for a task deletion user extension handler routine. +.. _InterfaceRtemsTaskDeleteExtension: + +rtems_task_delete_extension +--------------------------- + +Task delete extensions are invoked when a task is deleted. + +.. rubric:: NOTES: + +The task delete extensions are invoked in :term:`extension reverse order`. + +The task delete extensions are invoked by task create directives before an +attempt to allocate a :term:`TCB` is made. + +If a task create extension failed, then a task delete extension may be invoked +without a previous invocation of the corresponding task create extension of the +extension set. + +.. Generated from spec:/rtems/task/if/entry .. index:: rtems_task_entry -``rtems_task_entry`` - The address of the entry point to an RTEMS ASR. It is equivalent to the - entry point of the function implementing the ASR. +.. _InterfaceRtemsTaskEntry: + +rtems_task_entry +---------------- + +This type defines the :term:`task entry` point of an RTEMS task. + +.. Generated from spec:/rtems/userext/if/task-exitted .. index:: rtems_task_exitted_extension -``rtems_task_exitted_extension`` - The entry point for a task exitted user extension handler routine. +.. _InterfaceRtemsTaskExittedExtension: + +rtems_task_exitted_extension +---------------------------- + +Task exitted extensions are invoked when a task entry returns. + +.. rubric:: NOTES: + +The task exitted extensions are invoked in :term:`extension forward order`. + +.. Generated from spec:/rtems/type/if/priority .. index:: rtems_task_priority -``rtems_task_priority`` - The data type used to manage and manipulate task priorities. +.. _InterfaceRtemsTaskPriority: + +rtems_task_priority +------------------- + +This integer type represents task priorities of the Classic API. + +.. Generated from spec:/rtems/userext/if/task-restart .. index:: rtems_task_restart_extension -``rtems_task_restart_extension`` - The entry point for a task restart user extension handler routine. +.. _InterfaceRtemsTaskRestartExtension: + +rtems_task_restart_extension +---------------------------- + +Task restart extensions are invoked when a task restarts. + +.. rubric:: NOTES: + +The task restart extensions are invoked in :term:`extension forward order`. + +The task restart extensions are invoked in the context of the restarted thread +right before the execution context is reloaded. The thread stack reflects the +previous execution context. + +Thread restart and delete requests issued by restart extensions lead to +recursion. + +.. Generated from spec:/rtems/userext/if/task-start .. index:: rtems_task_start_extension -``rtems_task_start_extension`` - The entry point for a task start user extension handler routine. +.. _InterfaceRtemsTaskStartExtension: + +rtems_task_start_extension +-------------------------- + +Task start extensions are invoked when a task was made ready for the first +time. + +.. rubric:: NOTES: + +The task start extensions are invoked in :term:`extension forward order`. + +In SMP configurations, the thread may already run on another processor before +the task start extensions are actually invoked. Task switch and task begin +extensions may run before or in parallel with the thread start extension in SMP +configurations, see :ref:`InterfaceRtemsTaskSwitchExtension` and +:ref:`InterfaceRtemsTaskBeginExtension`. + +.. Generated from spec:/rtems/userext/if/task-switch .. index:: rtems_task_switch_extension -``rtems_task_switch_extension`` - The entry point for a task context switch user extension handler routine. +.. _InterfaceRtemsTaskSwitchExtension: + +rtems_task_switch_extension +--------------------------- + +Task switch extensions are invoked when a thread switch from an executing +thread to a heir thread takes place. + +.. rubric:: NOTES: + +The task switch extensions are invoked in :term:`extension forward order`. + +The invocation conditions of the task switch extensions depend on whether RTEMS +was built with SMP support enabled or disabled. A user must pay attention to +the differences to correctly implement a task switch extension. + +Where the system was built with SMP support disabled, the task switch +extensions are invoked before the context switch from the currently executing +thread to the heir thread. The executing is a pointer to the :term:`TCB` of +the currently executing thread. The heir is a pointer to the TCB of the heir +thread. The context switch initiated through the multitasking start is not +covered by the task switch extensions. + +Where the system was built with SMP support enabled, the task switch extensions +are invoked after the context switch to the heir thread. The executing is a +pointer to the TCB of the previously executing thread. Despite the name, this +is not the currently executing thread. The heir is a pointer to the TCB of the +newly executing thread. This is the currently executing thread. The context +switches initiated through the multitasking start are covered by the task +switch extensions. The reason for the differences to uniprocessor +configurations is that the context switch may update the heir thread of the +processor. The task switch extensions are invoked with maskable interrupts +disabled and with ownership of a processor-specific SMP lock. Task switch +extensions may run in parallel on multiple processors. It is recommended to +use thread-local or processor-specific data structures for task switch +extensions. A global SMP lock should be avoided for performance reasons, see +:ref:`InterfaceRtemsInterruptLockInitialize`. + +.. Generated from spec:/rtems/userext/if/task-terminate + +.. index:: rtems_task_terminate_extension + +.. _InterfaceRtemsTaskTerminateExtension: + +rtems_task_terminate_extension +------------------------------ + +Task terminate extensions are invoked when a task terminates. + +.. rubric:: NOTES: + +The task terminate extensions are invoked in :term:`extension reverse order`. + +The task terminate extensions are invoked in the context of the terminating +thread right before the thread dispatch to the heir thread should take place. +The thread stack reflects the previous execution context. The POSIX cleanup +and key destructors execute in this context. + +Thread restart and delete requests issued by terminate extensions lead to +recursion. + +.. Generated from spec:/rtems/task/if/visitor + +.. index:: rtems_task_visitor + +.. _InterfaceRtemsTaskVisitor: + +rtems_task_visitor +------------------ + +Visitor routines invoked by :ref:`InterfaceRtemsTaskIterate` shall have this +type. + +.. Generated from spec:/rtems/task/if/tcb .. index:: rtems_tcb -``rtems_tcb`` - The data structure associated with each task in an RTEMS system. +.. _InterfaceRtemsTcb: + +rtems_tcb +--------- + +This structure represents the :term:`TCB`. + +.. Generated from spec:/rtems/type/if/time-of-day .. index:: rtems_time_of_day -``rtems_time_of_day`` - The data structure used to manage and manipulate calendar time in RTEMS. +.. _InterfaceRtemsTimeOfDay: + +rtems_time_of_day +----------------- + +This type represents Classic API calendar times. + +.. rubric:: MEMBERS: + +year + This member contains the year A.D. + +month + This member contains the month of the year with values from 1 to 12. + +day + This member contains the day of the month with values from 1 to 31. + +hour + This member contains the hour of the day with values from 0 to 23. + +minute + This member contains the minute of the hour with values from 0 to 59. + +second + This member contains the second of the minute with values from 0 to 59. + +ticks + This member contains the clock tick of the second with values from 0 to + :ref:`InterfaceRtemsClockGetTicksPerSecond` minus one. + +.. Generated from spec:/rtems/timer/if/information + +.. index:: rtems_timer_information + +.. _InterfaceRtemsTimerInformation: + +rtems_timer_information +----------------------- + +The structure contains information about a timer. + +.. rubric:: MEMBERS: + +the_class + The timer class member indicates how the timer was most recently fired. + +initial + This member indicates the initial requested interval. + +start_time + This member indicates the time the timer was initially scheduled. The time + is in clock ticks since the clock driver initialization or the last clock + tick counter overflow. + +stop_time + This member indicates the time the timer was scheduled to fire. The time is + in clock ticks since the clock driver initialization or the last clock tick + counter overflow. + +.. Generated from spec:/rtems/timer/if/service-routine .. index:: rtems_timer_service_routine -``rtems_timer_service_routine`` - The return type for an RTEMS Timer Service Routine. +.. _InterfaceRtemsTimerServiceRoutine: -.. index:: rtems_timer_service_routine_entry +rtems_timer_service_routine +--------------------------- -``rtems_timer_service_routine_entry`` - The address of the entry point to an RTEMS TSR. It is equivalent to the - entry point of the function implementing the TSR. +This type defines the return type of routines which can be fired by directives +of the Timer Manager. -.. index:: rtems_vector_number +.. rubric:: DESCRIPTION: -``rtems_vector_number`` - The data type used to manage and manipulate interrupt vector numbers. +This type can be used to document timer service routines in the source code. -.. index:: uint8_t +.. Generated from spec:/rtems/timer/if/service-routine-entry -``uint8_t`` - The C99 data type that corresponds to unsigned eight bit integers. This data - type is defined by RTEMS in a manner that ensures it is portable across - different target processors. +.. index:: rtems_timer_service_routine_entry -.. index:: uint16_t +.. _InterfaceRtemsTimerServiceRoutineEntry: -``uint16_t`` - The C99 data type that corresponds to unsigned sixteen bit integers. This - data type is defined by RTEMS in a manner that ensures it is portable across - different target processors. +rtems_timer_service_routine_entry +--------------------------------- -.. index:: uint32_t +This type defines the prototype of routines which can be fired by directives of +the Timer Manager. -``uint32_t`` - The C99 data type that corresponds to unsigned thirty-two bit integers. This - data type is defined by RTEMS in a manner that ensures it is portable across - different target processors. +.. Generated from spec:/rtems/intr/if/vector-number -.. index:: uint64_t +.. index:: rtems_vector_number -``uint64_t`` - The C99 data type that corresponds to unsigned sixty-four bit integers. This - data type is defined by RTEMS in a manner that ensures it is portable across - different target processors. +.. _InterfaceRtemsVectorNumber: -.. index:: uintptr_t +rtems_vector_number +------------------- -``uintptr_t`` - The C99 data type that corresponds to the unsigned integer type that is of - sufficient size to represent addresses as unsigned integers. This data type - is defined by RTEMS in a manner that ensures it is portable across different - target processors. +This integer type represents interrupt vector numbers. diff --git a/c-user/scheduling-concepts/background.rst b/c-user/scheduling-concepts/background.rst new file mode 100644 index 0000000..38b77ee --- /dev/null +++ b/c-user/scheduling-concepts/background.rst @@ -0,0 +1,324 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2011 Petr Benes +.. Copyright (C) 2010 Gedare Bloom +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Background +========== + +.. index:: scheduling algorithms + +Scheduling Algorithms +--------------------- + +RTEMS provides a plugin framework that allows it to support multiple +scheduling algorithms. RTEMS includes multiple scheduling algorithms, and the +user can select which of these they wish to use in their application at +link-time. In addition, the user can implement their own scheduling algorithm +and configure RTEMS to use it. + +Supporting multiple scheduling algorithms gives the end user the option to +select the algorithm which is most appropriate to their use case. Most +real-time operating systems schedule tasks using a priority based algorithm, +possibly with preemption control. The classic RTEMS scheduling algorithm which +was the only algorithm available in RTEMS 4.10 and earlier, is a fixed-priority +scheduling algorithm. This scheduling algorithm is suitable for uniprocessor +(e.g., non-SMP) systems and is known as the *Deterministic Priority +Scheduler*. Unless the user configures another scheduling algorithm, RTEMS +will use this on uniprocessor systems. + +.. index:: priority scheduling + +Priority Scheduling +------------------- + +When using priority based scheduling, RTEMS allocates the processor using a +priority-based, preemptive algorithm augmented to provide round-robin +characteristics within individual priority groups. The goal of this algorithm +is to guarantee that the task which is executing on the processor at any point +in time is the one with the highest priority among all tasks in the ready +state. + +When a task is added to the ready chain, it is placed behind all other tasks of +the same priority. This rule provides a round-robin within a priority group +scheduling characteristic. This means that in a group of equal priority tasks, +tasks will execute in the order they become ready or FIFO order. Even though +there are ways to manipulate and adjust task priorities, the most important +rule to remember is: + +.. note:: + + Priority based scheduling algorithms will always select the highest priority + task that is ready to run when allocating the processor to a task. + +Priority scheduling is the most commonly used scheduling algorithm. It should +be used by applications in which multiple tasks contend for CPU time or other +resources, and there is a need to ensure certain tasks are given priority over +other tasks. + +There are a few common methods of accomplishing the mechanics of this +algorithm. These ways involve a list or chain of tasks in the ready state. + +- The least efficient method is to randomly place tasks in the ready chain + forcing the scheduler to scan the entire chain to determine which task + receives the processor. + +- A more efficient method is to schedule the task by placing it in the proper + place on the ready chain based on the designated scheduling criteria at the + time it enters the ready state. Thus, when the processor is free, the first + task on the ready chain is allocated the processor. + +- Another mechanism is to maintain a list of FIFOs per priority. When a task + is readied, it is placed on the rear of the FIFO for its priority. This + method is often used with a bitmap to assist in locating which FIFOs have + ready tasks on them. This data structure has :math:`O(1)` insert, extract + and find highest ready run-time complexities. + +- A red-black tree may be used for the ready queue with the priority as the + key. This data structure has :math:`O(log(n))` insert, extract and find + highest ready run-time complexities while :math:`n` is the count of tasks in + the ready queue. + +RTEMS currently includes multiple priority based scheduling algorithms as well +as other algorithms that incorporate deadline. Each algorithm is discussed in +the following sections. + +.. index:: scheduling mechanisms + +Scheduling Modification Mechanisms +---------------------------------- + +RTEMS provides four mechanisms which allow the user to alter the task +scheduling decisions: + +- user-selectable task priority level + +- task preemption control + +- task timeslicing control + +- manual round-robin selection + +Each of these methods provides a powerful capability to customize sets of tasks +to satisfy the unique and particular requirements encountered in custom +real-time applications. Although each mechanism operates independently, there +is a precedence relationship which governs the effects of scheduling +modifications. The evaluation order for scheduling characteristics is always +priority, preemption mode, and timeslicing. When reading the descriptions of +timeslicing and manual round-robin it is important to keep in mind that +preemption (if enabled) of a task by higher priority tasks will occur as +required, overriding the other factors presented in the description. + +.. index:: task priority + +Task Priority and Scheduling +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The most significant task scheduling modification mechanism is the ability for +the user to assign a priority level to each individual task when it is created +and to alter a task's priority at run-time, see :ref:`TaskPriority`. + +.. index:: preemption + +Preemption +^^^^^^^^^^ + +Another way the user can alter the basic scheduling algorithm is by +manipulating the preemption mode flag (``RTEMS_PREEMPT_MASK``) of individual +tasks. If preemption is disabled for a task (``RTEMS_NO_PREEMPT``), then the +task will not relinquish control of the processor until it terminates, blocks, +or re-enables preemption. Even tasks which become ready to run and possess +higher priority levels will not be allowed to execute. Note that the +preemption setting has no effect on the manner in which a task is scheduled. +It only applies once a task has control of the processor. + +.. index:: timeslicing +.. index:: round robin scheduling + +Timeslicing +^^^^^^^^^^^ + +Timeslicing or round-robin scheduling is an additional method which can be used +to alter the basic scheduling algorithm. Like preemption, timeslicing is +specified on a task by task basis using the timeslicing mode flag +(``RTEMS_TIMESLICE_MASK``). If timeslicing is enabled for a task +(``RTEMS_TIMESLICE``), then RTEMS will limit the amount of time the task can +execute before the processor is allocated to another task. Each tick of the +real-time clock reduces the currently running task's timeslice. When the +execution time equals the timeslice, RTEMS will dispatch another task of the +same priority to execute. If there are no other tasks of the same priority +ready to execute, then the current task is allocated an additional timeslice +and continues to run. Remember that a higher priority task will preempt the +task (unless preemption is disabled) as soon as it is ready to run, even if the +task has not used up its entire timeslice. + +.. index:: manual round robin + +Manual Round-Robin +^^^^^^^^^^^^^^^^^^ + +The final mechanism for altering the RTEMS scheduling algorithm is called +manual round-robin. Manual round-robin is invoked by using +the ``rtems_task_wake_after`` directive with a ``ticks`` parameter of +``RTEMS_YIELD_PROCESSOR``. This allows a task to give up the processor and be +immediately returned to the ready chain at the end of its priority group. If +no other tasks of the same priority are ready to run, then the task does not +lose control of the processor. + +.. index:: dispatching + +Dispatching Tasks +----------------- + +The dispatcher is the RTEMS component responsible for allocating the processor +to a ready task. In order to allocate the processor to one task, it must be +deallocated or retrieved from the task currently using it. This involves a +concept called a context switch. To perform a context switch, the dispatcher +saves the context of the current task and restores the context of the task +which has been allocated to the processor. Saving and restoring a task's +context is the storing/loading of all the essential information about a task to +enable it to continue execution without any effects of the interruption. For +example, the contents of a task's register set must be the same when it is +given the processor as they were when it was taken away. All of the +information that must be saved or restored for a context switch is located +either in the TCB or on the task's stacks. + +Tasks that utilize a numeric coprocessor and are created with the +``RTEMS_FLOATING_POINT`` attribute require additional operations during a +context switch. These additional operations are necessary to save and restore +the floating point context of ``RTEMS_FLOATING_POINT`` tasks. To avoid +unnecessary save and restore operations, the state of the numeric coprocessor +is only saved when a ``RTEMS_FLOATING_POINT`` task is dispatched and that task +was not the last task to utilize the coprocessor. + +.. index:: task state transitions + +Task State Transitions +---------------------- + +Tasks in an RTEMS system must always be in one of the five allowable task +states. These states are: executing, ready, blocked, dormant, and +non-existent. + +A task occupies the non-existent state before a ``rtems_task_create`` has been +issued on its behalf. A task enters the non-existent state from any other +state in the system when it is deleted with the ``rtems_task_delete`` +directive. While a task occupies this state it does not have a TCB or a task +ID assigned to it; therefore, no other tasks in the system may reference this +task. + +When a task is created via the ``rtems_task_create`` directive, it enters the +dormant state. This state is not entered through any other means. Although +the task exists in the system, it cannot actively compete for system resources. +It will remain in the dormant state until it is started via the +``rtems_task_start`` directive, at which time it enters the ready state. The +task is now permitted to be scheduled for the processor and to compete for +other system resources. + +.. figure:: ../../images/c_user/states.png + :width: 70% + :align: center + :alt: Task State Transitions + +A task occupies the blocked state whenever it is unable to be scheduled to run. +A running task may block itself or be blocked by other tasks in the system. +The running task blocks itself through voluntary operations that cause the task +to wait. The only way a task can block a task other than itself is with the +``rtems_task_suspend`` directive. A task enters the blocked state due to any +of the following conditions: + +- A task issues a ``rtems_task_suspend`` directive which blocks either itself + or another task in the system. + +- The running task issues a ``rtems_barrier_wait`` directive. + +- The running task issues a ``rtems_message_queue_receive`` directive with the + wait option, and the message queue is empty. + +- The running task issues a ``rtems_event_receive`` directive with the wait + option, and the currently pending events do not satisfy the request. + +- The running task issues a ``rtems_semaphore_obtain`` directive with the wait + option and the requested semaphore is unavailable. + +- The running task issues a ``rtems_task_wake_after`` directive which blocks + the task for the given count of ticks. If the count of ticks specified is + zero, the task yields the processor and remains in the ready state. + +- The running task issues a ``rtems_task_wake_when`` directive which blocks the + task until the requested date and time arrives. + +- The running task issues a ``rtems_rate_monotonic_period`` directive and must + wait for the specified rate monotonic period to conclude. + +- The running task issues a ``rtems_region_get_segment`` directive with the + wait option and there is not an available segment large enough to satisfy the + task's request. + +A blocked task may also be suspended. Therefore, both the suspension and the +blocking condition must be removed before the task becomes ready to run again. + +A task occupies the ready state when it is able to be scheduled to run, but +currently does not have control of the processor. Tasks of the same or higher +priority will yield the processor by either becoming blocked, completing their +timeslice, or being deleted. All tasks with the same priority will execute in +FIFO order. A task enters the ready state due to any of the following +conditions: + +- A running task issues a ``rtems_task_resume`` directive for a task that is + suspended and the task is not blocked waiting on any resource. + +- A running task issues a ``rtems_message_queue_send``, + ``rtems_message_queue_broadcast``, or a ``rtems_message_queue_urgent`` + directive which posts a message to the queue on which the blocked task is + waiting. + +- A running task issues an ``rtems_event_send`` directive which sends an event + condition to a task that is blocked waiting on that event condition. + +- A running task issues a ``rtems_semaphore_release`` directive which releases + the semaphore on which the blocked task is waiting. + +- The requested count of ticks has elapsed for a task which was blocked by a + call to the ``rtems_task_wake_after`` directive. + +- A timeout period expires for a task which blocked by a call to the + ``rtems_task_wake_when`` directive. + +- A running task issues a ``rtems_region_return_segment`` directive which + releases a segment to the region on which the blocked task is waiting and a + resulting segment is large enough to satisfy the task's request. + +- A rate monotonic period expires for a task which blocked by a call to the + ``rtems_rate_monotonic_period`` directive. + +- A timeout interval expires for a task which was blocked waiting on a message, + event, semaphore, or segment with a timeout specified. + +- A running task issues a directive which deletes a message queue, a semaphore, + or a region on which the blocked task is waiting. + +- A running task issues a ``rtems_task_restart`` directive for the blocked + task. + +- The running task, with its preemption mode enabled, may be made ready by + issuing any of the directives that may unblock a task with a higher priority. + This directive may be issued from the running task itself or from an ISR. A + ready task occupies the executing state when it has control of the CPU. A + task enters the executing state due to any of the following conditions: + +- The task is the highest priority ready task in the system. + +- The running task blocks and the task is next in the scheduling queue. The + task may be of equal priority as in round-robin scheduling or the task may + possess the highest priority of the remaining ready tasks. + +- The running task may reenable its preemption mode and a task exists in the + ready queue that has a higher priority than the running task. + +- The running task lowers its own priority and another task is of higher + priority as a result. + +- The running task raises the priority of a task above its own and the running + task is in preemption mode. diff --git a/c-user/scheduling-concepts/directives.rst b/c-user/scheduling-concepts/directives.rst new file mode 100644 index 0000000..115b4fa --- /dev/null +++ b/c-user/scheduling-concepts/directives.rst @@ -0,0 +1,707 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2013, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. _SchedulerManagerDirectives: + +Directives +========== + +This section details the directives of the Scheduler Manager. A subsection is +dedicated to each of this manager's directives and lists the calling sequence, +parameters, description, return values, and notes of the directive. + +.. Generated from spec:/rtems/scheduler/if/ident + +.. raw:: latex + + \clearpage + +.. index:: rtems_scheduler_ident() + +.. _InterfaceRtemsSchedulerIdent: + +rtems_scheduler_ident() +----------------------- + +Identifies a scheduler by the object name. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_scheduler_ident( rtems_name name, rtems_id *id ); + +.. rubric:: PARAMETERS: + +``name`` + This parameter is the scheduler name to look up. + +``id`` + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the identifier of the scheduler will be + stored in this object. + +.. rubric:: DESCRIPTION: + +This directive obtains a scheduler identifier associated with the scheduler +name specified in ``name``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_NAME` + There was no scheduler associated with the name. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``id`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +.. rubric:: NOTES: + +The scheduler name is determined by the scheduler configuration. + +The scheduler identifier is used with other scheduler related directives to +access the scheduler. + +.. 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/scheduler/if/ident-by-processor + +.. raw:: latex + + \clearpage + +.. index:: rtems_scheduler_ident_by_processor() + +.. _InterfaceRtemsSchedulerIdentByProcessor: + +rtems_scheduler_ident_by_processor() +------------------------------------ + +Identifies a scheduler by the processor index. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_scheduler_ident_by_processor( + uint32_t cpu_index, + rtems_id *id + ); + +.. rubric:: PARAMETERS: + +``cpu_index`` + This parameter is the processor index to identify the scheduler. + +``id`` + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the identifier of the scheduler will be + stored in this object. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``id`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_NAME` + The processor index was invalid. + +:c:macro:`RTEMS_INCORRECT_STATE` + The processor index was valid, however, the corresponding processor was not + owned by a scheduler. + +.. 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/scheduler/if/ident-by-processor-set + +.. raw:: latex + + \clearpage + +.. index:: rtems_scheduler_ident_by_processor_set() + +.. _InterfaceRtemsSchedulerIdentByProcessorSet: + +rtems_scheduler_ident_by_processor_set() +---------------------------------------- + +Identifies a scheduler by the processor set. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_scheduler_ident_by_processor_set( + size_t cpusetsize, + const cpu_set_t *cpuset, + rtems_id *id + ); + +.. rubric:: PARAMETERS: + +``cpusetsize`` + This parameter is the size of the processor set referenced by ``cpuset`` in + bytes. The size shall be positive. + +``cpuset`` + This parameter is the pointer to a :c:type:`cpu_set_t`. The referenced + processor set will be used to identify the scheduler. + +``id`` + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the identifier of the scheduler will be + stored in this object. + +.. rubric:: DESCRIPTION: + +The scheduler is selected according to the highest numbered online processor in +the specified processor set. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``id`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``cpuset`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_SIZE` + The processor set size was invalid. + +:c:macro:`RTEMS_INVALID_NAME` + The processor set contained no online processor. + +:c:macro:`RTEMS_INCORRECT_STATE` + The processor set was valid, however, the highest numbered online processor + in the processor set was not owned by a scheduler. + +.. 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/scheduler/if/get-maximum-priority + +.. raw:: latex + + \clearpage + +.. index:: rtems_scheduler_get_maximum_priority() + +.. _InterfaceRtemsSchedulerGetMaximumPriority: + +rtems_scheduler_get_maximum_priority() +-------------------------------------- + +Gets the maximum task priority of the scheduler. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_scheduler_get_maximum_priority( + rtems_id scheduler_id, + rtems_task_priority *priority + ); + +.. rubric:: PARAMETERS: + +``scheduler_id`` + This parameter is the scheduler identifier. + +``priority`` + This parameter is the pointer to an :ref:`InterfaceRtemsTaskPriority` + object. When the directive the maximum priority of the scheduler will be + stored in this object. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no scheduler associated with the identifier specified by + ``scheduler_id``. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``priority`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +.. 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/scheduler/if/map-priority-to-posix + +.. raw:: latex + + \clearpage + +.. index:: rtems_scheduler_map_priority_to_posix() + +.. _InterfaceRtemsSchedulerMapPriorityToPosix: + +rtems_scheduler_map_priority_to_posix() +--------------------------------------- + +Maps a Classic API task priority to the corresponding POSIX thread priority. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_scheduler_map_priority_to_posix( + rtems_id scheduler_id, + rtems_task_priority priority, + int *posix_priority + ); + +.. rubric:: PARAMETERS: + +``scheduler_id`` + This parameter is the scheduler identifier. + +``priority`` + This parameter is the Classic API task priority to map. + +``posix_priority`` + This parameter is the pointer to an ``int`` object. When the directive + call is successful, the POSIX thread priority value corresponding to the + specified Classic API task priority value will be stored in this object. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``posix_priority`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no scheduler associated with the identifier specified by + ``scheduler_id``. + +:c:macro:`RTEMS_INVALID_PRIORITY` + The Classic API task priority was invalid. + +.. 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/scheduler/if/map-priority-from-posix + +.. raw:: latex + + \clearpage + +.. index:: rtems_scheduler_map_priority_from_posix() + +.. _InterfaceRtemsSchedulerMapPriorityFromPosix: + +rtems_scheduler_map_priority_from_posix() +----------------------------------------- + +Maps a POSIX thread priority to the corresponding Classic API task priority. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_scheduler_map_priority_from_posix( + rtems_id scheduler_id, + int posix_priority, + rtems_task_priority *priority + ); + +.. rubric:: PARAMETERS: + +``scheduler_id`` + This parameter is the scheduler identifier. + +``posix_priority`` + This parameter is the POSIX thread priority to map. + +``priority`` + This parameter is the pointer to an :ref:`InterfaceRtemsTaskPriority` + object. When the directive call is successful, the Classic API task + priority value corresponding to the specified POSIX thread priority value + will be stored in this object. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``priority`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no scheduler associated with the identifier specified by + ``scheduler_id``. + +:c:macro:`RTEMS_INVALID_PRIORITY` + The POSIX thread priority was invalid. + +.. 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/scheduler/if/get-processor + +.. raw:: latex + + \clearpage + +.. index:: rtems_scheduler_get_processor() + +.. _InterfaceRtemsSchedulerGetProcessor: + +rtems_scheduler_get_processor() +------------------------------- + +Returns the index of the current processor. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_scheduler_get_processor( void ); + +.. rubric:: DESCRIPTION: + +Where the system was built with SMP support disabled, this directive evaluates +to a compile time constant of zero. + +Where the system was built with SMP support enabled, this directive returns the +index of the current processor. The set of processor indices is the range of +integers starting with zero up to +:ref:`InterfaceRtemsSchedulerGetProcessorMaximum` minus one. + +.. rubric:: RETURN VALUES: + +Returns the index of the current processor. + +.. rubric:: NOTES: + +Outside of sections with disabled thread dispatching the current processor +index may change after every instruction since the thread may migrate from one +processor to another. Sections with disabled interrupts are sections with +thread dispatching disabled. + +.. 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/scheduler/if/get-processor-maximum + +.. raw:: latex + + \clearpage + +.. index:: rtems_scheduler_get_processor_maximum() + +.. _InterfaceRtemsSchedulerGetProcessorMaximum: + +rtems_scheduler_get_processor_maximum() +--------------------------------------- + +Returns the processor maximum supported by the system. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_scheduler_get_processor_maximum( void ); + +.. rubric:: DESCRIPTION: + +Where the system was built with SMP support disabled, this directive evaluates +to a compile time constant of one. + +Where the system was built with SMP support enabled, this directive returns the +minimum of the processors (physically or virtually) available at the +:term:`target` and the configured processor maximum (see +:ref:`CONFIGURE_MAXIMUM_PROCESSORS`). Not all processors in the range from +processor index zero to the last processor index (which is the processor +maximum minus one) may be configured to be used by a scheduler or may be online +(online processors have a scheduler assigned). + +.. rubric:: RETURN VALUES: + +Returns the processor maximum supported by the system. + +.. 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/scheduler/if/get-processor-set + +.. raw:: latex + + \clearpage + +.. index:: rtems_scheduler_get_processor_set() + +.. _InterfaceRtemsSchedulerGetProcessorSet: + +rtems_scheduler_get_processor_set() +----------------------------------- + +Gets the set of processors owned by the scheduler. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_scheduler_get_processor_set( + rtems_id scheduler_id, + size_t cpusetsize, + cpu_set_t *cpuset + ); + +.. rubric:: PARAMETERS: + +``scheduler_id`` + This parameter is the scheduler identifier. + +``cpusetsize`` + This parameter is the size of the processor set referenced by ``cpuset`` in + bytes. + +``cpuset`` + This parameter is the pointer to a :c:type:`cpu_set_t` object. When the + directive call is successful, the processor set of the scheduler will be + stored in this object. A set bit in the processor set means that the + corresponding processor is owned by the scheduler, otherwise the bit is + cleared. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``cpuset`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no scheduler associated with the identifier specified by + ``scheduler_id``. + +:c:macro:`RTEMS_INVALID_SIZE` + The provided processor set was too small for the set of processors owned by + the scheduler. + +.. 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/scheduler/if/add-processor + +.. raw:: latex + + \clearpage + +.. index:: rtems_scheduler_add_processor() + +.. _InterfaceRtemsSchedulerAddProcessor: + +rtems_scheduler_add_processor() +------------------------------- + +Adds the processor to the set of processors owned by the scheduler. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_scheduler_add_processor( + rtems_id scheduler_id, + uint32_t cpu_index + ); + +.. rubric:: PARAMETERS: + +``scheduler_id`` + This parameter is the scheduler identifier. + +``cpu_index`` + This parameter is the index of the processor to add. + +.. rubric:: DESCRIPTION: + +This directive adds the processor specified by the ``cpu_index`` to the +scheduler specified by ``scheduler_id``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no scheduler associated with the identifier specified by + ``scheduler_id``. + +:c:macro:`RTEMS_NOT_CONFIGURED` + The processor was not configured to be used by the application. + +:c:macro:`RTEMS_INCORRECT_STATE` + The processor was configured to be used by the application, however, it was + not online. + +:c:macro:`RTEMS_RESOURCE_IN_USE` + The processor was already assigned to a scheduler. + +.. 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/scheduler/if/remove-processor + +.. raw:: latex + + \clearpage + +.. index:: rtems_scheduler_remove_processor() + +.. _InterfaceRtemsSchedulerRemoveProcessor: + +rtems_scheduler_remove_processor() +---------------------------------- + +Removes the processor from the set of processors owned by the scheduler. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_scheduler_remove_processor( + rtems_id scheduler_id, + uint32_t cpu_index + ); + +.. rubric:: PARAMETERS: + +``scheduler_id`` + This parameter is the scheduler identifier. + +``cpu_index`` + This parameter is the index of the processor to remove. + +.. rubric:: DESCRIPTION: + +This directive removes the processor specified by the ``cpu_index`` from the +scheduler specified by ``scheduler_id``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no scheduler associated with the identifier specified by + ``scheduler_id``. + +:c:macro:`RTEMS_INVALID_NUMBER` + The processor was not owned by the scheduler. + +:c:macro:`RTEMS_RESOURCE_IN_USE` + The processor was required by at least one non-idle task that used the + scheduler as its :term:`home scheduler`. + +:c:macro:`RTEMS_RESOURCE_IN_USE` + The processor was the last processor owned by the scheduler and there was + at least one task that used the scheduler as a :term:`helping scheduler`. + +.. rubric:: NOTES: + +Removing a processor from a scheduler is a complex operation that involves all +tasks of the system. + +.. 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. diff --git a/c-user/scheduling-concepts/index.rst b/c-user/scheduling-concepts/index.rst new file mode 100644 index 0000000..ee9aa26 --- /dev/null +++ b/c-user/scheduling-concepts/index.rst @@ -0,0 +1,19 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 embedded brains GmbH & Co. KG + +.. index:: scheduling +.. index:: task scheduling + +.. _RTEMSAPIClassicScheduler: + +Scheduling Concepts +******************* + +.. toctree:: + + introduction + background + uniprocessor-schedulers + smp-schedulers + directives diff --git a/c-user/scheduling-concepts/introduction.rst b/c-user/scheduling-concepts/introduction.rst new file mode 100644 index 0000000..527d103 --- /dev/null +++ b/c-user/scheduling-concepts/introduction.rst @@ -0,0 +1,86 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2013, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/rtems/scheduler/if/group + +.. _SchedulerManagerIntroduction: + +Introduction +============ + +.. The following list was generated from: +.. spec:/rtems/scheduler/if/ident +.. spec:/rtems/scheduler/if/ident-by-processor +.. spec:/rtems/scheduler/if/ident-by-processor-set +.. spec:/rtems/scheduler/if/get-maximum-priority +.. spec:/rtems/scheduler/if/map-priority-to-posix +.. spec:/rtems/scheduler/if/map-priority-from-posix +.. spec:/rtems/scheduler/if/get-processor +.. spec:/rtems/scheduler/if/get-processor-maximum +.. spec:/rtems/scheduler/if/get-processor-set +.. spec:/rtems/scheduler/if/add-processor +.. spec:/rtems/scheduler/if/remove-processor + +The scheduling concepts relate to the allocation of processing time for tasks. + +The concept of scheduling in real-time systems dictates the ability to provide +an immediate response to specific external events, particularly the necessity +of scheduling tasks to run within a specified time limit after the occurrence +of an event. For example, software embedded in life-support systems used to +monitor hospital patients must take instant action if a change in the patient’s +status is detected. + +The component of RTEMS responsible for providing this capability is +appropriately called the scheduler. The scheduler’s sole purpose is to allocate +the all important resource of processor time to the various tasks competing for +attention. The directives provided by the Scheduler Manager are: + +* :ref:`InterfaceRtemsSchedulerIdent` - Identifies a scheduler by the object + name. + +* :ref:`InterfaceRtemsSchedulerIdentByProcessor` - Identifies a scheduler by + the processor index. + +* :ref:`InterfaceRtemsSchedulerIdentByProcessorSet` - Identifies a scheduler by + the processor set. + +* :ref:`InterfaceRtemsSchedulerGetMaximumPriority` - Gets the maximum task + priority of the scheduler. + +* :ref:`InterfaceRtemsSchedulerMapPriorityToPosix` - Maps a Classic API task + priority to the corresponding POSIX thread priority. + +* :ref:`InterfaceRtemsSchedulerMapPriorityFromPosix` - Maps a POSIX thread + priority to the corresponding Classic API task priority. + +* :ref:`InterfaceRtemsSchedulerGetProcessor` - Returns the index of the current + processor. + +* :ref:`InterfaceRtemsSchedulerGetProcessorMaximum` - Returns the processor + maximum supported by the system. + +* :ref:`InterfaceRtemsSchedulerGetProcessorSet` - Gets the set of processors + owned by the scheduler. + +* :ref:`InterfaceRtemsSchedulerAddProcessor` - Adds the processor to the set of + processors owned by the scheduler. + +* :ref:`InterfaceRtemsSchedulerRemoveProcessor` - Removes the processor from + the set of processors owned by the scheduler. diff --git a/c-user/scheduling-concepts/smp-schedulers.rst b/c-user/scheduling-concepts/smp-schedulers.rst new file mode 100644 index 0000000..d6c1dc6 --- /dev/null +++ b/c-user/scheduling-concepts/smp-schedulers.rst @@ -0,0 +1,70 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2011 Petr Benes +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +SMP Schedulers +============== + +All SMP schedulers included in RTEMS are priority based. The processors +managed by a scheduler instance are allocated to the highest priority tasks +allowed to run. + +.. _SchedulerSMPEDF: + +Earliest Deadline First SMP Scheduler +------------------------------------- + +This is a job-level fixed-priority scheduler using the Earliest Deadline First +(EDF) method. By convention, the maximum priority level is +:math:`min(INT\_MAX, 2^{62} - 1)` for background tasks. Tasks without an +active deadline are background tasks. In case deadlines are not used, then the +EDF scheduler behaves exactly like a fixed-priority scheduler. The tasks with +an active deadline have a higher priority than the background tasks. This +scheduler supports :ref:`task processor affinities <rtems_task_set_affinity>` +of one-to-one and one-to-all, e.g., a task can execute on exactly one processor +or all processors managed by the scheduler instance. The processor affinity +set of a task must contain all online processors to select the one-to-all +affinity. This is to avoid pathological cases if processors are added/removed +to/from the scheduler instance at run-time. In case the processor affinity set +contains not all online processors, then a one-to-one affinity will be used +selecting the processor with the largest index within the set of processors +currently owned by the scheduler instance. This scheduler algorithm supports +:ref:`thread pinning <ThreadPinning>`. The ready queues use a red-black tree +with the task priority as the key. + +This scheduler algorithm is the default scheduler in SMP configurations if more +than one processor is configured (:ref:`CONFIGURE_MAXIMUM_PROCESSORS +<CONFIGURE_MAXIMUM_PROCESSORS>`). + +.. _SchedulerSMPPriority: + +Deterministic Priority SMP Scheduler +------------------------------------ + +A fixed-priority scheduler which uses a table of chains with one chain per +priority level for the ready tasks. The maximum priority level is +configurable. By default, the maximum priority level is 255 (256 priority +levels), see :ref:`CONFIGURE_MAXIMUM_PRIORITY`. + +.. _SchedulerSMPPrioritySimple: + +Simple Priority SMP Scheduler +----------------------------- + +A fixed-priority scheduler which uses a sorted chain for the ready tasks. By +convention, the maximum priority level is 255. The implementation limit is +actually :math:`2^{63} - 1`. + +.. _SchedulerSMPPriorityAffinity: + +Arbitrary Processor Affinity Priority SMP Scheduler +--------------------------------------------------- + +A fixed-priority scheduler which uses a table of chains with one chain per +priority level for the ready tasks. The maximum priority level is +configurable. By default, the maximum priority level is 255 (256 priority +levels), see :ref:`CONFIGURE_MAXIMUM_PRIORITY`. This scheduler supports +arbitrary task processor affinities. The worst-case run-time complexity of +some scheduler operations exceeds :math:`O(n)` while :math:`n` is the count of +ready tasks. diff --git a/c-user/scheduling-concepts/uniprocessor-schedulers.rst b/c-user/scheduling-concepts/uniprocessor-schedulers.rst new file mode 100644 index 0000000..34969bc --- /dev/null +++ b/c-user/scheduling-concepts/uniprocessor-schedulers.rst @@ -0,0 +1,113 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2011 Petr Benes +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Uniprocessor Schedulers +======================= + +All uniprocessor schedulers included in RTEMS are priority based. The +processor is allocated to the highest priority task allowed to run. + +.. _SchedulerPriority: + +Deterministic Priority Scheduler +-------------------------------- + +This is the scheduler implementation which has always been in RTEMS. After the +4.10 release series, it was factored into a pluggable scheduler selection. It +schedules tasks using a priority based algorithm which takes into account +preemption. It is implemented using an array of FIFOs with a FIFO per +priority. It maintains a bitmap which is used to track which priorities have +ready tasks. + +This algorithm is deterministic (e.g., predictable and fixed) in execution time. +This comes at the cost of using slightly over three (3) kilobytes of RAM on a +system configured to support 256 priority levels. + +This scheduler is only aware of a single core. + +.. _SchedulerPrioritySimple: + +Simple Priority Scheduler +------------------------- + +This scheduler implementation has the same behaviour as the Deterministic +Priority Scheduler but uses only one linked list to manage all ready tasks. +When a task is readied, a linear search of that linked list is performed to +determine where to insert the newly readied task. + +This algorithm uses much less RAM than the Deterministic Priority Scheduler but +is *O(n)* where *n* is the number of ready tasks. In a small system with a +small number of tasks, this will not be a performance issue. Reducing RAM +consumption is often critical in small systems that are incapable of +supporting a large number of tasks. + +This scheduler is only aware of a single core. + +.. index:: earliest deadline first scheduling + +.. _SchedulerEDF: + +Earliest Deadline First Scheduler +--------------------------------- + +This is an alternative scheduler in RTEMS for single-core applications. The +primary EDF advantage is high total CPU utilization (theoretically up to +100%). It assumes that tasks have priorities equal to deadlines. + +This EDF is initially preemptive, however, individual tasks may be declared +not-preemptive. Deadlines are declared using only Rate Monotonic manager whose +goal is to handle periodic behavior. Period is always equal to the deadline. All +ready tasks reside in a single ready queue implemented using a red-black tree. + +This implementation of EDF schedules two different types of task priority types +while each task may switch between the two types within its execution. If a +task does have a deadline declared using the Rate Monotonic manager, the task +is deadline-driven and its priority is equal to deadline. On the contrary, if a +task does not have any deadline or the deadline is cancelled using the Rate +Monotonic manager, the task is considered a background task with priority equal +to that assigned upon initialization in the same manner as for priority +scheduler. Each background task is of lower importance than each +deadline-driven one and is scheduled when no deadline-driven task and no higher +priority background task is ready to run. + +Every deadline-driven scheduling algorithm requires means for tasks to claim a +deadline. The Rate Monotonic Manager is responsible for handling periodic +execution. In RTEMS periods are equal to deadlines, thus if a task announces a +period, it has to be finished until the end of this period. The call of +``rtems_rate_monotonic_period`` passes the scheduler the length of an oncoming +deadline. Moreover, the ``rtems_rate_monotonic_cancel`` and +``rtems_rate_monotonic_delete`` calls clear the deadlines assigned to the task. + +.. index:: constant bandwidth server scheduling + +.. _SchedulerCBS: + +Constant Bandwidth Server Scheduling (CBS) +------------------------------------------ + +This is an alternative scheduler in RTEMS for single-core applications. The +CBS is a budget aware extension of EDF scheduler. The main goal of this +scheduler is to ensure temporal isolation of tasks meaning that a task's +execution in terms of meeting deadlines must not be influenced by other tasks +as if they were run on multiple independent processors. + +Each task can be assigned a server (current implementation supports only one +task per server). The server is characterized by period (deadline) and +computation time (budget). The ratio budget/period yields bandwidth, which is +the fraction of CPU to be reserved by the scheduler for each subsequent period. + +The CBS is equipped with a set of rules applied to tasks attached to servers +ensuring that deadline miss because of another task cannot occur. In case a +task breaks one of the rules, its priority is pulled to background until the +end of its period and then restored again. The rules are: + +- Task cannot exceed its registered budget, + +- Task cannot be unblocked when a ratio between remaining budget and remaining + deadline is higher than declared bandwidth. + +The CBS provides an extensive API. Unlike EDF, the +``rtems_rate_monotonic_period`` does not declare a deadline because it is +carried out using CBS API. This call only announces next period. diff --git a/c-user/scheduling_concepts.rst b/c-user/scheduling_concepts.rst deleted file mode 100644 index dac39a8..0000000 --- a/c-user/scheduling_concepts.rst +++ /dev/null @@ -1,968 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-4.0 - -.. Copyright (C) 2011 Petr Benes -.. Copyright (C) 2010 Gedare Bloom -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) - -.. index:: scheduling -.. index:: task scheduling - -.. _SchedulingConcepts: - -Scheduling Concepts -******************* - -Introduction -============ - -The concept of scheduling in real-time systems dictates the ability to provide -immediate response to specific external events, particularly the necessity of -scheduling tasks to run within a specified time limit after the occurrence of -an event. For example, software embedded in life-support systems used to -monitor hospital patients must take instant action if a change in the patient's -status is detected. - -The component of RTEMS responsible for providing this capability is -appropriately called the scheduler. The scheduler's sole purpose is to -allocate the all important resource of processor time to the various tasks -competing for attention. - -The directives provided by the scheduler manager are: - -- rtems_scheduler_ident_ - Get ID of a scheduler - -- rtems_scheduler_ident_by_processor_ - Get ID of a scheduler by processor - -- rtems_scheduler_ident_by_processor_set_ - Get ID of a scheduler by processor set - -- rtems_scheduler_get_maximum_priority_ - Get maximum task priority of a scheduler - -- rtems_scheduler_map_priority_to_posix_ - Map task priority to POSIX thread - prority - -- rtems_scheduler_map_priority_from_posix_ - Map POSIX thread priority to task - prority - -- rtems_scheduler_get_processor_ - Get current processor index - -- rtems_scheduler_get_processor_maximum_ - Get processor maximum - -- rtems_scheduler_get_processor_set_ - Get processor set of a scheduler - -- rtems_scheduler_add_processor_ - Add processor to a scheduler - -- rtems_scheduler_remove_processor_ - Remove processor from a scheduler - -.. index:: scheduling algorithms - -Scheduling Algorithms ---------------------- - -RTEMS provides a plugin framework which allows it to support multiple -scheduling algorithms. RTEMS includes multiple scheduling algorithms and the -user can select which of these they wish to use in their application at -link-time. In addition, the user can implement their own scheduling algorithm -and configure RTEMS to use it. - -Supporting multiple scheduling algorithms gives the end user the option to -select the algorithm which is most appropriate to their use case. Most -real-time operating systems schedule tasks using a priority based algorithm, -possibly with preemption control. The classic RTEMS scheduling algorithm which -was the only algorithm available in RTEMS 4.10 and earlier, is a fixed-priority -scheduling algorithm. This scheduling algoritm is suitable for uniprocessor -(e.g. non-SMP) systems and is known as the *Deterministic Priority -Scheduler*. Unless the user configures another scheduling algorithm, RTEMS -will use this on uniprocessor systems. - -.. index:: priority scheduling - -Priority Scheduling -------------------- - -When using priority based scheduling, RTEMS allocates the processor using a -priority-based, preemptive algorithm augmented to provide round-robin -characteristics within individual priority groups. The goal of this algorithm -is to guarantee that the task which is executing on the processor at any point -in time is the one with the highest priority among all tasks in the ready -state. - -When a task is added to the ready chain, it is placed behind all other tasks of -the same priority. This rule provides a round-robin within priority group -scheduling characteristic. This means that in a group of equal priority tasks, -tasks will execute in the order they become ready or FIFO order. Even though -there are ways to manipulate and adjust task priorities, the most important -rule to remember is: - -.. note:: - - Priority based scheduling algorithms will always select the highest priority - task that is ready to run when allocating the processor to a task. - -Priority scheduling is the most commonly used scheduling algorithm. It should -be used by applications in which multiple tasks contend for CPU time or other -resources and there is a need to ensure certain tasks are given priority over -other tasks. - -There are a few common methods of accomplishing the mechanics of this -algorithm. These ways involve a list or chain of tasks in the ready state. - -- The least efficient method is to randomly place tasks in the ready chain - forcing the scheduler to scan the entire chain to determine which task - receives the processor. - -- A more efficient method is to schedule the task by placing it in the proper - place on the ready chain based on the designated scheduling criteria at the - time it enters the ready state. Thus, when the processor is free, the first - task on the ready chain is allocated the processor. - -- Another mechanism is to maintain a list of FIFOs per priority. When a task - is readied, it is placed on the rear of the FIFO for its priority. This - method is often used with a bitmap to assist in locating which FIFOs have - ready tasks on them. This data structure has :math:`O(1)` insert, extract - and find highest ready run-time complexities. - -- A red-black tree may be used for the ready queue with the priority as the - key. This data structure has :math:`O(log(n))` insert, extract and find - highest ready run-time complexities while :math:`n` is the count of tasks in - the ready queue. - -RTEMS currently includes multiple priority based scheduling algorithms as well -as other algorithms which incorporate deadline. Each algorithm is discussed in -the following sections. - -Uniprocessor Schedulers -======================= - -All uniprocessor schedulers included in RTEMS are priority based. The -processor is allocated to the highest priority task allowed to run. - -.. _SchedulerPriority: - -Deterministic Priority Scheduler --------------------------------- - -This is the scheduler implementation which has always been in RTEMS. After the -4.10 release series, it was factored into pluggable scheduler selection. It -schedules tasks using a priority based algorithm which takes into account -preemption. It is implemented using an array of FIFOs with a FIFO per -priority. It maintains a bitmap which is used to track which priorities have -ready tasks. - -This algorithm is deterministic (e.g. predictable and fixed) in execution time. -This comes at the cost of using slightly over three (3) kilobytes of RAM on a -system configured to support 256 priority levels. - -This scheduler is only aware of a single core. - -.. _SchedulerPrioritySimple: - -Simple Priority Scheduler -------------------------- - -This scheduler implementation has the same behaviour as the Deterministic -Priority Scheduler but uses only one linked list to manage all ready tasks. -When a task is readied, a linear search of that linked list is performed to -determine where to insert the newly readied task. - -This algorithm uses much less RAM than the Deterministic Priority Scheduler but -is *O(n)* where *n* is the number of ready tasks. In a small system with a -small number of tasks, this will not be a performance issue. Reducing RAM -consumption is often critical in small systems which are incapable of -supporting a large number of tasks. - -This scheduler is only aware of a single core. - -.. index:: earliest deadline first scheduling - -.. _SchedulerEDF: - -Earliest Deadline First Scheduler ---------------------------------- - -This is an alternative scheduler in RTEMS for single core applications. The -primary EDF advantage is high total CPU utilization (theoretically up to -100%). It assumes that tasks have priorities equal to deadlines. - -This EDF is initially preemptive, however, individual tasks may be declared -not-preemptive. Deadlines are declared using only Rate Monotonic manager which -goal is to handle periodic behavior. Period is always equal to deadline. All -ready tasks reside in a single ready queue implemented using a red-black tree. - -This implementation of EDF schedules two different types of task priority types -while each task may switch between the two types within its execution. If a -task does have a deadline declared using the Rate Monotonic manager, the task -is deadline-driven and its priority is equal to deadline. On the contrary if a -task does not have any deadline or the deadline is cancelled using the Rate -Monotonic manager, the task is considered a background task with priority equal -to that assigned upon initialization in the same manner as for priority -scheduler. Each background task is of a lower importance than each -deadline-driven one and is scheduled when no deadline-driven task and no higher -priority background task is ready to run. - -Every deadline-driven scheduling algorithm requires means for tasks to claim a -deadline. The Rate Monotonic Manager is responsible for handling periodic -execution. In RTEMS periods are equal to deadlines, thus if a task announces a -period, it has to be finished until the end of this period. The call of -``rtems_rate_monotonic_period`` passes the scheduler the length of oncoming -deadline. Moreover, the ``rtems_rate_monotonic_cancel`` and -``rtems_rate_monotonic_delete`` calls clear the deadlines assigned to the task. - -.. index:: constant bandwidth server scheduling - -.. _SchedulerCBS: - -Constant Bandwidth Server Scheduling (CBS) ------------------------------------------- - -This is an alternative scheduler in RTEMS for single core applications. The -CBS is a budget aware extension of EDF scheduler. The main goal of this -scheduler is to ensure temporal isolation of tasks meaning that a task's -execution in terms of meeting deadlines must not be influenced by other tasks -as if they were run on multiple independent processors. - -Each task can be assigned a server (current implementation supports only one -task per server). The server is characterized by period (deadline) and -computation time (budget). The ratio budget/period yields bandwidth, which is -the fraction of CPU to be reserved by the scheduler for each subsequent period. - -The CBS is equipped with a set of rules applied to tasks attached to servers -ensuring that deadline miss because of another task cannot occur. In case a -task breaks one of the rules, its priority is pulled to background until the -end of its period and then restored again. The rules are: - -- Task cannot exceed its registered budget, - -- Task cannot be unblocked when a ratio between remaining budget and remaining - deadline is higher than declared bandwidth. - -The CBS provides an extensive API. Unlike EDF, the -``rtems_rate_monotonic_period`` does not declare a deadline because it is -carried out using CBS API. This call only announces next period. - -SMP Schedulers -============== - -All SMP schedulers included in RTEMS are priority based. The processors -managed by a scheduler instance are allocated to the highest priority tasks -allowed to run. - -.. _SchedulerSMPEDF: - -Earliest Deadline First SMP Scheduler -------------------------------------- - -This is a job-level fixed-priority scheduler using the Earliest Deadline First -(EDF) method. By convention, the maximum priority level is -:math:`min(INT\_MAX, 2^{62} - 1)` for background tasks. Tasks without an -active deadline are background tasks. In case deadlines are not used, then the -EDF scheduler behaves exactly like a fixed-priority scheduler. The tasks with -an active deadline have a higher priority than the background tasks. This -scheduler supports :ref:`task processor affinities <rtems_task_set_affinity>` -of one-to-one and one-to-all, e.g. a task can execute on exactly one processor -or all processors managed by the scheduler instance. The processor affinity -set of a task must contain all online processors to select the one-to-all -affinity. This is to avoid pathological cases if processors are added/removed -to/from the scheduler instance at run-time. In case the processor affinity set -contains not all online processors, then a one-to-one affinity will be used -selecting the processor with the largest index within the set of processors -currently owned by the scheduler instance. This scheduler algorithm supports -:ref:`thread pinning <ThreadPinning>`. The ready queues use a red-black tree -with the task priority as the key. - -This scheduler algorithm is the default scheduler in SMP configurations if more -than one processor is configured (:ref:`CONFIGURE_MAXIMUM_PROCESSORS -<CONFIGURE_MAXIMUM_PROCESSORS>`). - -.. _SchedulerSMPPriority: - -Deterministic Priority SMP Scheduler ------------------------------------- - -A fixed-priority scheduler which uses a table of chains with one chain per -priority level for the ready tasks. The maximum priority level is -configurable. By default, the maximum priority level is 255 (256 priority -levels). - -.. _SchedulerSMPPrioritySimple: - -Simple Priority SMP Scheduler ------------------------------ - -A fixed-priority scheduler which uses a sorted chain for the ready tasks. By -convention, the maximum priority level is 255. The implementation limit is -actually :math:`2^{63} - 1`. - -.. _SchedulerSMPPriorityAffinity: - -Arbitrary Processor Affinity Priority SMP Scheduler ---------------------------------------------------- - -A fixed-priority scheduler which uses a table of chains with one chain per -priority level for the ready tasks. The maximum priority level is -configurable. By default, the maximum priority level is 255 (256 priority -levels). This scheduler supports arbitrary task processor affinities. The -worst-case run-time complexity of some scheduler operations exceeds -:math:`O(n)` while :math:`n` is the count of ready tasks. - -.. index:: scheduling mechanisms - -Scheduling Modification Mechanisms -================================== - -RTEMS provides four mechanisms which allow the user to alter the task -scheduling decisions: - -- user-selectable task priority level - -- task preemption control - -- task timeslicing control - -- manual round-robin selection - -Each of these methods provides a powerful capability to customize sets of tasks -to satisfy the unique and particular requirements encountered in custom -real-time applications. Although each mechanism operates independently, there -is a precedence relationship which governs the effects of scheduling -modifications. The evaluation order for scheduling characteristics is always -priority, preemption mode, and timeslicing. When reading the descriptions of -timeslicing and manual round-robin it is important to keep in mind that -preemption (if enabled) of a task by higher priority tasks will occur as -required, overriding the other factors presented in the description. - -.. index:: task priority - -Task Priority and Scheduling ----------------------------- - -The most significant task scheduling modification mechanism is the ability for -the user to assign a priority level to each individual task when it is created -and to alter a task's priority at run-time. The maximum priority level depends -on the configured scheduler. A lower priority level means higher priority -(higher importance). The maximum priority level of the default uniprocessor -scheduler is 255. - -.. index:: preemption - -Preemption ----------- - -Another way the user can alter the basic scheduling algorithm is by -manipulating the preemption mode flag (``RTEMS_PREEMPT_MASK``) of individual -tasks. If preemption is disabled for a task (``RTEMS_NO_PREEMPT``), then the -task will not relinquish control of the processor until it terminates, blocks, -or re-enables preemption. Even tasks which become ready to run and possess -higher priority levels will not be allowed to execute. Note that the -preemption setting has no effect on the manner in which a task is scheduled. -It only applies once a task has control of the processor. - -.. index:: timeslicing -.. index:: round robin scheduling - -Timeslicing ------------ - -Timeslicing or round-robin scheduling is an additional method which can be used -to alter the basic scheduling algorithm. Like preemption, timeslicing is -specified on a task by task basis using the timeslicing mode flag -(``RTEMS_TIMESLICE_MASK``). If timeslicing is enabled for a task -(``RTEMS_TIMESLICE``), then RTEMS will limit the amount of time the task can -execute before the processor is allocated to another task. Each tick of the -real-time clock reduces the currently running task's timeslice. When the -execution time equals the timeslice, RTEMS will dispatch another task of the -same priority to execute. If there are no other tasks of the same priority -ready to execute, then the current task is allocated an additional timeslice -and continues to run. Remember that a higher priority task will preempt the -task (unless preemption is disabled) as soon as it is ready to run, even if the -task has not used up its entire timeslice. - -.. index:: manual round robin - -Manual Round-Robin ------------------- - -The final mechanism for altering the RTEMS scheduling algorithm is called -manual round-robin. Manual round-robin is invoked by using -the ``rtems_task_wake_after`` directive with a time interval of -``RTEMS_YIELD_PROCESSOR``. This allows a task to give up the processor and be -immediately returned to the ready chain at the end of its priority group. If -no other tasks of the same priority are ready to run, then the task does not -lose control of the processor. - -.. index:: dispatching - -Dispatching Tasks -================= - -The dispatcher is the RTEMS component responsible for allocating the processor -to a ready task. In order to allocate the processor to one task, it must be -deallocated or retrieved from the task currently using it. This involves a -concept called a context switch. To perform a context switch, the dispatcher -saves the context of the current task and restores the context of the task -which has been allocated to the processor. Saving and restoring a task's -context is the storing/loading of all the essential information about a task to -enable it to continue execution without any effects of the interruption. For -example, the contents of a task's register set must be the same when it is -given the processor as they were when it was taken away. All of the -information that must be saved or restored for a context switch is located -either in the TCB or on the task's stacks. - -Tasks that utilize a numeric coprocessor and are created with the -``RTEMS_FLOATING_POINT`` attribute require additional operations during a -context switch. These additional operations are necessary to save and restore -the floating point context of ``RTEMS_FLOATING_POINT`` tasks. To avoid -unnecessary save and restore operations, the state of the numeric coprocessor -is only saved when a ``RTEMS_FLOATING_POINT`` task is dispatched and that task -was not the last task to utilize the coprocessor. - -.. index:: task state transitions - -Task State Transitions -====================== - -Tasks in an RTEMS system must always be in one of the five allowable task -states. These states are: executing, ready, blocked, dormant, and -non-existent. - -A task occupies the non-existent state before a ``rtems_task_create`` has been -issued on its behalf. A task enters the non-existent state from any other -state in the system when it is deleted with the ``rtems_task_delete`` -directive. While a task occupies this state it does not have a TCB or a task -ID assigned to it; therefore, no other tasks in the system may reference this -task. - -When a task is created via the ``rtems_task_create`` directive it enters the -dormant state. This state is not entered through any other means. Although -the task exists in the system, it cannot actively compete for system resources. -It will remain in the dormant state until it is started via the -``rtems_task_start`` directive, at which time it enters the ready state. The -task is now permitted to be scheduled for the processor and to compete for -other system resources. - -.. figure:: ../images/c_user/states.png - :width: 70% - :align: center - :alt: Task State Transitions - -A task occupies the blocked state whenever it is unable to be scheduled to run. -A running task may block itself or be blocked by other tasks in the system. -The running task blocks itself through voluntary operations that cause the task -to wait. The only way a task can block a task other than itself is with the -``rtems_task_suspend`` directive. A task enters the blocked state due to any -of the following conditions: - -- A task issues a ``rtems_task_suspend`` directive which blocks either itself - or another task in the system. - -- The running task issues a ``rtems_barrier_wait`` directive. - -- The running task issues a ``rtems_message_queue_receive`` directive with the - wait option and the message queue is empty. - -- The running task issues an ``rtems_event_receive`` directive with the wait - option and the currently pending events do not satisfy the request. - -- The running task issues a ``rtems_semaphore_obtain`` directive with the wait - option and the requested semaphore is unavailable. - -- The running task issues a ``rtems_task_wake_after`` directive which blocks - the task for the given time interval. If the time interval specified is - zero, the task yields the processor and remains in the ready state. - -- The running task issues a ``rtems_task_wake_when`` directive which blocks the - task until the requested date and time arrives. - -- The running task issues a ``rtems_rate_monotonic_period`` directive and must - wait for the specified rate monotonic period to conclude. - -- The running task issues a ``rtems_region_get_segment`` directive with the - wait option and there is not an available segment large enough to satisfy the - task's request. - -A blocked task may also be suspended. Therefore, both the suspension and the -blocking condition must be removed before the task becomes ready to run again. - -A task occupies the ready state when it is able to be scheduled to run, but -currently does not have control of the processor. Tasks of the same or higher -priority will yield the processor by either becoming blocked, completing their -timeslice, or being deleted. All tasks with the same priority will execute in -FIFO order. A task enters the ready state due to any of the following -conditions: - -- A running task issues a ``rtems_task_resume`` directive for a task that is - suspended and the task is not blocked waiting on any resource. - -- A running task issues a ``rtems_message_queue_send``, - ``rtems_message_queue_broadcast``, or a ``rtems_message_queue_urgent`` - directive which posts a message to the queue on which the blocked task is - waiting. - -- A running task issues an ``rtems_event_send`` directive which sends an event - condition to a task which is blocked waiting on that event condition. - -- A running task issues a ``rtems_semaphore_release`` directive which releases - the semaphore on which the blocked task is waiting. - -- A timeout interval expires for a task which was blocked by a call to the - ``rtems_task_wake_after`` directive. - -- A timeout period expires for a task which blocked by a call to the - ``rtems_task_wake_when`` directive. - -- A running task issues a ``rtems_region_return_segment`` directive which - releases a segment to the region on which the blocked task is waiting and a - resulting segment is large enough to satisfy the task's request. - -- A rate monotonic period expires for a task which blocked by a call to the - ``rtems_rate_monotonic_period`` directive. - -- A timeout interval expires for a task which was blocked waiting on a message, - event, semaphore, or segment with a timeout specified. - -- A running task issues a directive which deletes a message queue, a semaphore, - or a region on which the blocked task is waiting. - -- A running task issues a ``rtems_task_restart`` directive for the blocked - task. - -- The running task, with its preemption mode enabled, may be made ready by - issuing any of the directives that may unblock a task with a higher priority. - This directive may be issued from the running task itself or from an ISR. A - ready task occupies the executing state when it has control of the CPU. A - task enters the executing state due to any of the following conditions: - -- The task is the highest priority ready task in the system. - -- The running task blocks and the task is next in the scheduling queue. The - task may be of equal priority as in round-robin scheduling or the task may - possess the highest priority of the remaining ready tasks. - -- The running task may reenable its preemption mode and a task exists in the - ready queue that has a higher priority than the running task. - -- The running task lowers its own priority and another task is of higher - priority as a result. - -- The running task raises the priority of a task above its own and the running - task is in preemption mode. - -Directives -========== - -This section details the scheduler manager. A subsection is dedicated to each -of these services and describes the calling sequence, related constants, usage, -and status codes. - -.. raw:: latex - - \clearpage - -.. _rtems_scheduler_ident: - -SCHEDULER_IDENT - Get ID of a scheduler ---------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_scheduler_ident( - rtems_name name, - rtems_id *id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - Successful operation. - * - ``RTEMS_INVALID_ADDRESS`` - - The ``id`` parameter is ``NULL``. - * - ``RTEMS_INVALID_NAME`` - - Invalid scheduler name. - -DESCRIPTION: - Identifies a scheduler by its name. The scheduler name is determined by - the scheduler configuration. See :ref:`ConfigurationSchedulerTable` - and :ref:`CONFIGURE_SCHEDULER_NAME`. - -NOTES: - None. - -.. raw:: latex - - \clearpage - -.. _rtems_scheduler_ident_by_processor: - -SCHEDULER_IDENT_BY_PROCESSOR - Get ID of a scheduler by processor ------------------------------------------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_scheduler_ident_by_processor( - uint32_t cpu_index, - rtems_id *id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - Successful operation. - * - ``RTEMS_INVALID_ADDRESS`` - - The ``id`` parameter is ``NULL``. - * - ``RTEMS_INVALID_NAME`` - - Invalid processor index. - * - ``RTEMS_INCORRECT_STATE`` - - The processor index is valid, however, this processor is not owned by - a scheduler. - -DESCRIPTION: - Identifies a scheduler by a processor. - -NOTES: - None. - -.. raw:: latex - - \clearpage - -.. _rtems_scheduler_ident_by_processor_set: - -SCHEDULER_IDENT_BY_PROCESSOR_SET - Get ID of a scheduler by processor set -------------------------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_scheduler_ident_by_processor_set( - size_t cpusetsize, - const cpu_set_t *cpuset, - rtems_id *id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - Successful operation. - * - ``RTEMS_INVALID_ADDRESS`` - - The ``id`` parameter is ``NULL``. - * - ``RTEMS_INVALID_SIZE`` - - Invalid processor set size. - * - ``RTEMS_INVALID_NAME`` - - The processor set contains no online processor. - * - ``RTEMS_INCORRECT_STATE`` - - The processor set is valid, however, the highest numbered online - processor in the specified processor set is not owned by a scheduler. - -DESCRIPTION: - Identifies a scheduler by a processor set. The scheduler is selected - according to the highest numbered online processor in the specified - processor set. - -NOTES: - None. - -.. raw:: latex - - \clearpage - -.. _rtems_scheduler_get_maximum_priority: - -SCHEDULER_GET_MAXIMUM_PRIORITY - Get maximum task priority of a scheduler -------------------------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_scheduler_get_maximum_priority( - rtems_id scheduler_id, - rtems_task_priority *priority - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - Successful operation. - * - ``RTEMS_INVALID_ID`` - - Invalid scheduler instance identifier. - * - ``RTEMS_INVALID_ADDRESS`` - - The ``priority`` parameter is ``NULL``. - -DESCRIPTION: - Returns the maximum task priority of the specified scheduler instance in - ``priority``. - -NOTES: - None. - -.. raw:: latex - - \clearpage - -.. _rtems_scheduler_map_priority_to_posix: - -SCHEDULER_MAP_PRIORITY_TO_POSIX - Map task priority to POSIX thread prority ---------------------------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_scheduler_map_priority_to_posix( - rtems_id scheduler_id, - rtems_task_priority priority, - int *posix_priority - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - Successful operation. - * - ``RTEMS_INVALID_ADDRESS`` - - The ``posix_priority`` parameter is ``NULL``. - * - ``RTEMS_INVALID_ID`` - - Invalid scheduler instance identifier. - * - ``RTEMS_INVALID_PRIORITY`` - - Invalid task priority. - -DESCRIPTION: - Maps a task priority to the corresponding POSIX thread priority. - -NOTES: - None. - -.. raw:: latex - - \clearpage - -.. _rtems_scheduler_map_priority_from_posix: - -SCHEDULER_MAP_PRIORITY_FROM_POSIX - Map POSIX thread prority to task priority ------------------------------------------------------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_scheduler_map_priority_from_posix( - rtems_id scheduler_id, - int posix_priority, - rtems_task_priority *priority - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - Successful operation. - * - ``RTEMS_INVALID_ADDRESS`` - - The ``priority`` parameter is ``NULL``. - * - ``RTEMS_INVALID_ID`` - - Invalid scheduler instance identifier. - * - ``RTEMS_INVALID_PRIORITY`` - - Invalid POSIX thread priority. - -DESCRIPTION: - Maps a POSIX thread priority to the corresponding task priority. - -NOTES: - None. - -.. raw:: latex - - \clearpage - -.. _rtems_scheduler_get_processor: - -SCHEDULER_GET_PROCESSOR - Get current processor index ------------------------------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - uint32_t rtems_scheduler_get_processor( void ); - -DIRECTIVE STATUS CODES: - This directive returns the index of the current processor. - -DESCRIPTION: - In uniprocessor configurations, a value of zero will be returned. - - In SMP configurations, an architecture specific method is used to obtain the - index of the current processor in the system. The set of processor indices - is the range of integers starting with zero up to the processor count minus - one. - - Outside of sections with disabled thread dispatching the current processor - index may change after every instruction since the thread may migrate from - one processor to another. Sections with disabled interrupts are sections - with thread dispatching disabled. - -NOTES: - None. - -.. raw:: latex - - \clearpage - -.. _rtems_scheduler_get_processor_maximum: - -SCHEDULER_GET_PROCESSOR_MAXIMUM - Get processor maximum -------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - uint32_t rtems_scheduler_get_processor_maximum( void ); - -DIRECTIVE STATUS CODES: - This directive returns the processor maximum supported by the system. - -DESCRIPTION: - In uniprocessor configurations, a value of one will be returned. - - In SMP configurations, this directive returns the minimum of the processors - (physically or virtually) available by the platform and the configured - processor maximum. Not all processors in the range from processor index - zero to the last processor index (which is the processor maximum minus one) - may be configured to be used by a scheduler or online (online processors - have a scheduler assigned). - -NOTES: - None. - -.. raw:: latex - - \clearpage - -.. _rtems_scheduler_get_processor_set: - -SCHEDULER_GET_PROCESSOR_SET - Get processor set of a scheduler --------------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_scheduler_get_processor_set( - rtems_id scheduler_id, - size_t cpusetsize, - cpu_set_t *cpuset - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - Successful operation. - * - ``RTEMS_INVALID_ID`` - - Invalid scheduler instance identifier. - * - ``RTEMS_INVALID_ADDRESS`` - - The ``cpuset`` parameter is ``NULL``. - * - ``RTEMS_INVALID_NUMBER`` - - The processor set buffer is too small for the set of processors owned - by the scheduler instance. - -DESCRIPTION: - Returns the processor set owned by the scheduler instance in ``cpuset``. A - set bit in the processor set means that this processor is owned by the - scheduler instance and a cleared bit means the opposite. - -NOTES: - None. - -.. raw:: latex - - \clearpage - -.. _rtems_scheduler_add_processor: - -SCHEDULER_ADD_PROCESSOR - Add processor to a scheduler ------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_scheduler_add_processor( - rtems_id scheduler_id, - uint32_t cpu_index - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - Successful operation. - * - ``RTEMS_INVALID_ID`` - - Invalid scheduler instance identifier. - * - ``RTEMS_NOT_CONFIGURED`` - - The processor is not configured to be used by the application. - * - ``RTEMS_INCORRECT_STATE`` - - The processor is configured to be used by the application, however, it - is not online. - * - ``RTEMS_RESOURCE_IN_USE`` - - The processor is already assigned to a scheduler instance. - -DESCRIPTION: - Adds a processor to the set of processors owned by the specified scheduler - instance. - -NOTES: - Must be called from task context. This operation obtains and releases the - objects allocator lock. - -.. raw:: latex - - \clearpage - -.. _rtems_scheduler_remove_processor: - -SCHEDULER_REMOVE_PROCESSOR - Remove processor from a scheduler --------------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_scheduler_remove_processor( - rtems_id scheduler_id, - uint32_t cpu_index - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - Successful operation. - * - ``RTEMS_INVALID_ID`` - - Invalid scheduler instance identifier. - * - ``RTEMS_INVALID_NUMBER`` - - The processor is not owned by the specified scheduler instance. - * - ``RTEMS_RESOURCE_IN_USE`` - - The set of processors owned by the specified scheduler instance would - be empty after the processor removal and there exists a non-idle task - that uses this scheduler instance as its home scheduler instance. - * - ``RTEMS_RESOURCE_IN_USE`` - - A task with a restricted processor affinity exists that uses this - scheduler instance as its home scheduler instance and it would be no - longer possible to allocate a processor for this task after the - removal of this processor. - -DESCRIPTION: - Removes a processor from set of processors owned by the specified scheduler - instance. - -NOTES: - Must be called from task context. This operation obtains and releases the - objects allocator lock. Removing a processor from a scheduler is a complex - operation that involves all tasks of the system. diff --git a/c-user/self_contained_objects.rst b/c-user/self_contained_objects.rst index 0be1423..2001ba3 100644 --- a/c-user/self_contained_objects.rst +++ b/c-user/self_contained_objects.rst @@ -1,7 +1,7 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 .. Copyright (C) 2014, 2017. -.. COMMENT: embedded brains GmbH. +.. COMMENT: embedded brains GmbH & Co. KG Self-Contained Objects ********************** @@ -132,6 +132,10 @@ copies of the object in calls to * :c:func:`rtems_recursive_mutex_lock`, +* :c:func:`rtems_mutex_try_lock`, + +* :c:func:`rtems_recursive_mutex_try_lock`, + * :c:func:`rtems_mutex_unlock`, * :c:func:`rtems_recursive_mutex_unlock`, @@ -262,6 +266,37 @@ NOTES: \clearpage +Try to lock the mutex +--------------------- + +CALLING SEQUENCE: + .. code-block:: c + + int rtems_mutex_try_lock( + rtems_mutex *mutex + ); + + int rtems_recursive_mutex_try_lock( + rtems_recursive_mutex *mutex + ); + +DESCRIPTION: + Tries to lock the ``mutex``. In case the mutex is not locked, it will be + locked and the function returns with a return value of ``0``. If the mutex + is already locked, the function will return with a value of ``EBUSY``. + +NOTES: + This function must be called from thread context with interrupts enabled. + + For recursively locking a mutex, please also see the notes for + :c:func:`rtems_mutex_lock` and :c:func:`rtems_recursive_mutex_lock`. + + Each mutex lock operation must have a corresponding unlock operation. + +.. raw:: latex + + \clearpage + Unlock the mutex ---------------- diff --git a/c-user/semaphore/background.rst b/c-user/semaphore/background.rst new file mode 100644 index 0000000..9d9b151 --- /dev/null +++ b/c-user/semaphore/background.rst @@ -0,0 +1,180 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Background +========== + +A semaphore can be viewed as a protected variable whose value can be modified +only with the ``rtems_semaphore_create``, ``rtems_semaphore_obtain``, and +``rtems_semaphore_release`` directives. RTEMS supports both binary and +counting semaphores. A binary semaphore is restricted to values of zero or one, +while a counting semaphore can assume any non-negative integer value. + +A binary semaphore (not a simple binary semaphore) can be used to control +access to a single resource. In particular, it can be used to enforce mutual +exclusion for a critical section in user code (mutex). In this instance, the +semaphore would be created with an initial count of one to indicate that no +task is executing the critical section of code. Upon entry to the critical +section, a task must issue the ``rtems_semaphore_obtain`` directive to prevent +other tasks from entering the critical section. Upon exit from the critical +section, the task that obtained the binary semaphore must issue the +``rtems_semaphore_release`` directive to allow another task to execute the +critical section. A binary semaphore must be released by the task that +obtained it. + +A counting semaphore can be used to control access to a pool of two or more +resources. For example, access to three printers could be administered by a +semaphore created with an initial count of three. When a task requires access +to one of the printers, it issues the ``rtems_semaphore_obtain`` directive to +obtain access to a printer. If a printer is not currently available, the task +can wait for a printer to become available or return immediately. When the +task has completed printing, it should issue the ``rtems_semaphore_release`` +directive to allow other tasks access to the printer. + +Task synchronization may be achieved by creating a semaphore with an initial +count of zero. One task waits for the arrival of another task by issuing a +``rtems_semaphore_obtain`` directive when it reaches a synchronization point. +The other task performs a corresponding ``rtems_semaphore_release`` operation +when it reaches its synchronization point, thus unblocking the pending task. + +.. _Nested Resource Access: + +Nested Resource Access +---------------------- + +Deadlock occurs when a task owning a binary semaphore attempts to acquire that +same semaphore and blocks as result. Since the semaphore is allocated to a +task, it cannot be deleted. Therefore, the task that currently holds the +semaphore and is also blocked waiting for that semaphore will never execute +again. + +RTEMS addresses this problem by allowing the task holding the binary semaphore +to obtain the same binary semaphore multiple times in a nested manner. Each +``rtems_semaphore_obtain`` must be accompanied with a +``rtems_semaphore_release``. The semaphore will only be made available for +acquisition by other tasks when the outermost ``rtems_semaphore_obtain`` is +matched with a ``rtems_semaphore_release``. + +Simple binary semaphores do not allow nested access and so can be used for task +synchronization. + +.. _Priority Inheritance: + +Priority Inheritance +-------------------- + +RTEMS supports :ref:`priority inheritance <PriorityInheritance>` for local, +binary semaphores that use the priority task wait queue blocking discipline. +In SMP configurations, the :ref:`OMIP` is used instead. + +.. _Priority Ceiling: + +Priority Ceiling +---------------- + +RTEMS supports :ref:`priority ceiling <PriorityCeiling>` for local, binary +semaphores that use the priority task wait queue blocking discipline. + +.. _Multiprocessor Resource Sharing Protocol: + +Multiprocessor Resource Sharing Protocol +---------------------------------------- + +RTEMS supports the :ref:`MrsP` for local, binary semaphores that use the +priority task wait queue blocking discipline. In uniprocessor configurations, +the :ref:`PriorityCeiling` is used instead. + +.. _Building a Semaphore Attribute Set: + +Building a Semaphore Attribute Set +---------------------------------- + +In general, an attribute set is built by a bitwise OR of the desired attribute +components. The following table lists the set of valid semaphore attributes: + +.. list-table:: + :class: rtems-table + + * - ``RTEMS_FIFO`` + - tasks wait by FIFO (default) + * - ``RTEMS_PRIORITY`` + - tasks wait by priority + * - ``RTEMS_BINARY_SEMAPHORE`` + - restrict values to 0 and 1 + * - ``RTEMS_COUNTING_SEMAPHORE`` + - no restriction on values (default) + * - ``RTEMS_SIMPLE_BINARY_SEMAPHORE`` + - restrict values to 0 and 1, do not allow nested access, allow deletion of + locked semaphore. + * - ``RTEMS_NO_INHERIT_PRIORITY`` + - do not use priority inheritance (default) + * - ``RTEMS_INHERIT_PRIORITY`` + - use priority inheritance + * - ``RTEMS_NO_PRIORITY_CEILING`` + - do not use priority ceiling (default) + * - ``RTEMS_PRIORITY_CEILING`` + - use priority ceiling + * - ``RTEMS_NO_MULTIPROCESSOR_RESOURCE_SHARING`` + - do not use Multiprocessor Resource Sharing Protocol (default) + * - ``RTEMS_MULTIPROCESSOR_RESOURCE_SHARING`` + - use Multiprocessor Resource Sharing Protocol + * - ``RTEMS_LOCAL`` + - local semaphore (default) + * - ``RTEMS_GLOBAL`` + - global semaphore + +Attribute values are specifically designed to be mutually exclusive, therefore +bitwise OR and addition operations are equivalent as long as each attribute +appears exactly once in the component list. An attribute listed as a default +is not required to appear in the attribute list, although it is a good +programming practice to specify default attributes. If all defaults are +desired, the attribute ``RTEMS_DEFAULT_ATTRIBUTES`` should be specified on this +call. + +This example demonstrates the attribute_set parameter needed to create a local +semaphore with the task priority waiting queue discipline. The attribute_set +parameter passed to the ``rtems_semaphore_create`` directive could be either +``RTEMS_PRIORITY`` or ``RTEMS_LOCAL | RTEMS_PRIORITY``. The attribute_set +parameter can be set to ``RTEMS_PRIORITY`` because ``RTEMS_LOCAL`` is the +default for all created tasks. If a similar semaphore were to be known +globally, then the attribute_set parameter would be ``RTEMS_GLOBAL | +RTEMS_PRIORITY``. + +Some combinatinos of these attributes are invalid. For example, priority +ordered blocking discipline must be applied to a binary semaphore in order to +use either the priority inheritance or priority ceiling functionality. The +following tree figure illustrates the valid combinations. + +.. figure:: ../../images/c_user/semaphore_attributes.png + :width: 90% + :align: center + :alt: Semaphore Attributes + +.. _Building a SEMAPHORE_OBTAIN Option Set: + +Building a SEMAPHORE_OBTAIN Option Set +-------------------------------------- + +In general, an option is built by a bitwise OR of the desired option +components. The set of valid options for the ``rtems_semaphore_obtain`` +directive are listed in the following table: + +.. list-table:: + :class: rtems-table + + * - ``RTEMS_WAIT`` + - task will wait for semaphore (default) + * - ``RTEMS_NO_WAIT`` + - task should not wait + +Option values are specifically designed to be mutually exclusive, therefore +bitwise OR and addition operations are equivalent as long as each attribute +appears exactly once in the component list. An option listed as a default is +not required to appear in the list, although it is a good programming practice +to specify default options. If all defaults are desired, the option +``RTEMS_DEFAULT_OPTIONS`` should be specified on this call. + +This example demonstrates the option parameter needed to poll for a semaphore. +The option parameter passed to the ``rtems_semaphore_obtain`` directive should +be ``RTEMS_NO_WAIT``. diff --git a/c-user/semaphore/directives.rst b/c-user/semaphore/directives.rst new file mode 100644 index 0000000..a0d12a6 --- /dev/null +++ b/c-user/semaphore/directives.rst @@ -0,0 +1,1024 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. _SemaphoreManagerDirectives: + +Directives +========== + +This section details the directives of the Semaphore Manager. A subsection is +dedicated to each of this manager's directives and lists the calling sequence, +parameters, description, return values, and notes of the directive. + +.. Generated from spec:/rtems/sem/if/create + +.. raw:: latex + + \clearpage + +.. index:: rtems_semaphore_create() +.. index:: create a semaphore + +.. _InterfaceRtemsSemaphoreCreate: + +rtems_semaphore_create() +------------------------ + +Creates a semaphore. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_semaphore_create( + rtems_name name, + uint32_t count, + rtems_attribute attribute_set, + rtems_task_priority priority_ceiling, + rtems_id *id + ); + +.. rubric:: PARAMETERS: + +``name`` + This parameter is the object name of the semaphore. + +``count`` + This parameter is the initial count of the semaphore. If the semaphore is + a binary semaphore, then a count of 0 will make the calling task the owner + of the binary semaphore and a count of 1 will create a binary semaphore + without an owner. + +``attribute_set`` + This parameter is the attribute set of the semaphore. + +``priority_ceiling`` + This parameter is the priority ceiling if the semaphore is a binary + semaphore with the priority ceiling or MrsP locking protocol as defined by + the attribute set. + +``id`` + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the identifier of the created semaphore + will be stored in this object. + +.. rubric:: DESCRIPTION: + +This directive creates a semaphore which resides on the local node. The +semaphore has the user-defined object name specified in ``name`` and the +initial count specified in ``count``. The assigned object identifier is +returned in ``id``. This identifier is used to access the semaphore with other +semaphore related directives. + +The **attribute set** specified in ``attribute_set`` is built through a +*bitwise or* of the attribute constants described below. Not all combinations +of attributes are allowed. Some attributes are mutually exclusive. If +mutually exclusive attributes are combined, the behaviour is undefined. +Attributes not mentioned below are not evaluated by this directive and have no +effect. Default attributes can be selected by using the +:c:macro:`RTEMS_DEFAULT_ATTRIBUTES` constant. The attribute set defines + +* the scope of the semaphore: :c:macro:`RTEMS_LOCAL` (default) or + :c:macro:`RTEMS_GLOBAL`, + +* the task wait queue discipline used by the semaphore: :c:macro:`RTEMS_FIFO` + (default) or :c:macro:`RTEMS_PRIORITY`, + +* the class of the semaphore: :c:macro:`RTEMS_COUNTING_SEMAPHORE` (default), + :c:macro:`RTEMS_BINARY_SEMAPHORE`, or + :c:macro:`RTEMS_SIMPLE_BINARY_SEMAPHORE`, and + +* the locking protocol of a binary semaphore: no locking protocol (default), + :c:macro:`RTEMS_INHERIT_PRIORITY`, :c:macro:`RTEMS_PRIORITY_CEILING`, or + :c:macro:`RTEMS_MULTIPROCESSOR_RESOURCE_SHARING`. + +The semaphore has a local or global **scope** in a multiprocessing network +(this attribute does not refer to SMP systems). The scope is selected by the +mutually exclusive :c:macro:`RTEMS_LOCAL` and :c:macro:`RTEMS_GLOBAL` +attributes. + +* A **local scope** is the default and can be emphasized through the use of the + :c:macro:`RTEMS_LOCAL` attribute. A local semaphore can be only used by the + node which created it. + +* A **global scope** is established if the :c:macro:`RTEMS_GLOBAL` attribute is + set. Setting the global attribute in a single node system has no effect. + +The **task wait queue discipline** is selected by the mutually exclusive +:c:macro:`RTEMS_FIFO` and :c:macro:`RTEMS_PRIORITY` attributes. + +* The **FIFO discipline** is the default and can be emphasized through use of + the :c:macro:`RTEMS_FIFO` attribute. + +* The **priority discipline** is selected by the :c:macro:`RTEMS_PRIORITY` + attribute. The locking protocols require the priority discipline. + +The **semaphore class** is selected by the mutually exclusive +:c:macro:`RTEMS_COUNTING_SEMAPHORE`, :c:macro:`RTEMS_BINARY_SEMAPHORE`, and +:c:macro:`RTEMS_SIMPLE_BINARY_SEMAPHORE` attributes. + +* The **counting semaphore class** is the default and can be emphasized through + use of the :c:macro:`RTEMS_COUNTING_SEMAPHORE` attribute. + +* The **binary semaphore class** is selected by the + :c:macro:`RTEMS_BINARY_SEMAPHORE` attribute. Binary semaphores are mutual + exclusion (mutex) synchronization primitives which may have an owner. The + count of a binary semaphore is restricted to 0 and 1 values. + +* The **simple binary semaphore class** is selected by the + :c:macro:`RTEMS_SIMPLE_BINARY_SEMAPHORE` attribute. Simple binary semaphores + have no owner. They may be used for task and interrupt synchronization. The + count of a simple binary semaphore is restricted to 0 and 1 values. + +Binary semaphores may use a **locking protocol**. If a locking protocol is +selected, then the scope shall be local and the priority task wait queue +discipline shall be selected. The locking protocol is selected by the mutually +exclusive :c:macro:`RTEMS_INHERIT_PRIORITY`, :c:macro:`RTEMS_PRIORITY_CEILING`, +and :c:macro:`RTEMS_MULTIPROCESSOR_RESOURCE_SHARING` attributes. + +* The default is **no locking protocol**. This can be emphasized through use + of the :c:macro:`RTEMS_NO_INHERIT_PRIORITY`, + :c:macro:`RTEMS_NO_MULTIPROCESSOR_RESOURCE_SHARING`, and + :c:macro:`RTEMS_NO_PRIORITY_CEILING` attributes. + +* The **priority inheritance locking protocol** is selected by the + :c:macro:`RTEMS_INHERIT_PRIORITY` attribute. + +* The **priority ceiling locking protocol** is selected by the + :c:macro:`RTEMS_PRIORITY_CEILING` attribute. For this locking protocol a + priority ceiling shall be specified in ``priority_ceiling``. + +* The **MrsP locking protocol** is selected by the + :c:macro:`RTEMS_MULTIPROCESSOR_RESOURCE_SHARING` attribute in SMP + configurations, otherwise this attribute selects the **priority ceiling + locking protocol**. For these locking protocols a priority ceiling shall be + specified in ``priority_ceiling``. This priority is used to set the priority + ceiling for all schedulers. This can be changed later with the + :ref:`InterfaceRtemsSemaphoreSetPriority` directive using the returned object + identifier. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_NAME` + The ``name`` parameter was invalid. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``id`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_NUMBER` + The ``count`` parameter was invalid. + +:c:macro:`RTEMS_NOT_DEFINED` + The ``attribute_set`` parameter was invalid. + +:c:macro:`RTEMS_TOO_MANY` + There was no inactive object available to create a semaphore. The number + of semaphores available to the application is configured through the + :ref:`CONFIGURE_MAXIMUM_SEMAPHORES` application configuration option. + +:c:macro:`RTEMS_TOO_MANY` + In multiprocessing configurations, there was no inactive global object + available to create a global semaphore. The number of global objects + available to the application is configured through the + :ref:`CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS` application configuration + option. + +:c:macro:`RTEMS_INVALID_PRIORITY` + The ``priority_ceiling`` parameter was invalid. + +.. rubric:: NOTES: + +For control and maintenance of the semaphore, RTEMS allocates a :term:`SMCB` +from the local SMCB free pool and initializes it. + +The SMCB for a global semaphore is allocated on the local node. Semaphores +should not be made global unless remote tasks must interact with the semaphore. +This is to avoid the system overhead incurred by the creation of a global +semaphore. When a global semaphore is created, the semaphore's name and +identifier must be transmitted to every node in the system for insertion in the +local copy of the global object table. + +.. 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. + +* When the directive operates on a global object, the directive sends a message + to remote nodes. This may preempt the calling task. + +* The number of semaphores available to the application is configured through + the :ref:`CONFIGURE_MAXIMUM_SEMAPHORES` application configuration option. + +* Where the object class corresponding to the directive is configured to use + unlimited objects, the directive may allocate memory from the RTEMS + Workspace. + +* The number of global objects available to the application is configured + through the :ref:`CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS` application + configuration option. + +.. Generated from spec:/rtems/sem/if/ident + +.. raw:: latex + + \clearpage + +.. index:: rtems_semaphore_ident() + +.. _InterfaceRtemsSemaphoreIdent: + +rtems_semaphore_ident() +----------------------- + +Identifies a semaphore by the object name. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_semaphore_ident( + rtems_name name, + uint32_t node, + rtems_id *id + ); + +.. rubric:: PARAMETERS: + +``name`` + This parameter is the object name to look up. + +``node`` + This parameter is the node or node set to search for a matching object. + +``id`` + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the object identifier of an object with + the specified name will be stored in this object. + +.. rubric:: DESCRIPTION: + +This directive obtains a semaphore identifier associated with the semaphore +name specified in ``name``. + +The node to search is specified in ``node``. It shall be + +* a valid node number, + +* the constant :c:macro:`RTEMS_SEARCH_ALL_NODES` to search in all nodes, + +* the constant :c:macro:`RTEMS_SEARCH_LOCAL_NODE` to search in the local node + only, or + +* the constant :c:macro:`RTEMS_SEARCH_OTHER_NODES` to search in all nodes + except the local node. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``id`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_NAME` + The ``name`` parameter was 0. + +:c:macro:`RTEMS_INVALID_NAME` + There was no object with the specified name on the specified nodes. + +:c:macro:`RTEMS_INVALID_NODE` + In multiprocessing configurations, the specified node was invalid. + +.. rubric:: NOTES: + +If the semaphore name is not unique, then the semaphore identifier will match +the first semaphore with that name in the search order. However, this +semaphore identifier is not guaranteed to correspond to the desired semaphore. + +The objects are searched from lowest to the highest index. If ``node`` is +:c:macro:`RTEMS_SEARCH_ALL_NODES`, all nodes are searched with the local node +being searched first. All other nodes are searched from lowest to the highest +node number. + +If node is a valid node number which does not represent the local node, then +only the semaphores exported by the designated node are searched. + +This directive does not generate activity on remote nodes. It accesses only +the local copy of the global object table. + +The semaphore identifier is used with other semaphore related directives to +access the semaphore. + +.. 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/sem/if/delete + +.. raw:: latex + + \clearpage + +.. index:: rtems_semaphore_delete() +.. index:: delete a semaphore + +.. _InterfaceRtemsSemaphoreDelete: + +rtems_semaphore_delete() +------------------------ + +Deletes the semaphore. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_semaphore_delete( rtems_id id ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the semaphore identifier. + +.. rubric:: DESCRIPTION: + +This directive deletes the semaphore specified by ``id``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no semaphore associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT` + The semaphore resided on a remote node. + +:c:macro:`RTEMS_RESOURCE_IN_USE` + The binary semaphore had an owner. + +.. rubric:: NOTES: + +Binary semaphores with an owner cannot be deleted. + +When a semaphore is deleted, all tasks blocked waiting to obtain the semaphore +will be readied and returned a status code which indicates that the semaphore +was deleted. + +The :term:`SMCB` for the deleted semaphore is reclaimed by RTEMS. + +When a global semaphore is deleted, the semaphore identifier must be +transmitted to every node in the system for deletion from the local copy of the +global object table. + +The semaphore must reside on the local node, even if the semaphore was created +with the :c:macro:`RTEMS_GLOBAL` attribute. + +Proxies, used to represent remote tasks, are reclaimed when the semaphore is +deleted. + +.. 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. + +* When the directive operates on a global object, the directive sends a message + to remote nodes. This may preempt the calling task. + +* The calling task does not have to be the task that created the object. Any + local task that knows the object identifier can delete the object. + +* Where the object class corresponding to the directive is configured to use + unlimited objects, the directive may free memory to the RTEMS Workspace. + +.. Generated from spec:/rtems/sem/if/obtain + +.. raw:: latex + + \clearpage + +.. index:: rtems_semaphore_obtain() +.. index:: obtain a semaphore +.. index:: lock a semaphore + +.. _InterfaceRtemsSemaphoreObtain: + +rtems_semaphore_obtain() +------------------------ + +Obtains the semaphore. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_semaphore_obtain( + rtems_id id, + rtems_option option_set, + rtems_interval timeout + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the semaphore identifier. + +``option_set`` + This parameter is the option set. + +``timeout`` + This parameter is the timeout in :term:`clock ticks <clock tick>` if the + :c:macro:`RTEMS_WAIT` option is set. Use :c:macro:`RTEMS_NO_TIMEOUT` to + wait potentially forever. + +.. rubric:: DESCRIPTION: + +This directive obtains the semaphore specified by ``id``. + +The **option set** specified in ``option_set`` is built through a *bitwise or* +of the option constants described below. Not all combinations of options are +allowed. Some options are mutually exclusive. If mutually exclusive options +are combined, the behaviour is undefined. Options not mentioned below are not +evaluated by this directive and have no effect. Default options can be selected +by using the :c:macro:`RTEMS_DEFAULT_OPTIONS` constant. + +The calling task can **wait** or **try to obtain** the semaphore according to +the mutually exclusive :c:macro:`RTEMS_WAIT` and :c:macro:`RTEMS_NO_WAIT` +options. + +* **Waiting to obtain** the semaphore is the default and can be emphasized + through the use of the :c:macro:`RTEMS_WAIT` option. The ``timeout`` + parameter defines how long the calling task is willing to wait. Use + :c:macro:`RTEMS_NO_TIMEOUT` to wait potentially forever, otherwise set a + timeout interval in clock ticks. + +* **Trying to obtain** the semaphore is selected by the + :c:macro:`RTEMS_NO_WAIT` option. If this option is defined, then the + ``timeout`` parameter is ignored. When the semaphore cannot be immediately + obtained, then the :c:macro:`RTEMS_UNSATISFIED` status is returned. + +With either :c:macro:`RTEMS_WAIT` or :c:macro:`RTEMS_NO_WAIT` if the current +semaphore count is positive, then it is decremented by one and the semaphore is +successfully obtained by returning immediately with the +:c:macro:`RTEMS_SUCCESSFUL` status code. + +If the calling task chooses to return immediately and the current semaphore +count is zero, then the :c:macro:`RTEMS_UNSATISFIED` status code is returned +indicating that the semaphore is not available. + +If the calling task chooses to wait for a semaphore and the current semaphore +count is zero, then the calling task is placed on the semaphore's wait queue +and blocked. If a local, binary semaphore was created with the +:c:macro:`RTEMS_INHERIT_PRIORITY` attribute, then the priority of the task +currently holding the binary semaphore will inherit the current priority set of +the blocking task. The priority inheritance is carried out recursively. This +means, that if the task currently holding the binary semaphore is blocked on +another local, binary semaphore using the priority inheritance locking +protocol, then the owner of this semaphore will inherit the current priority +sets of both tasks, and so on. A task has a current priority for each +scheduler. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no semaphore associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_NOT_DEFINED` + The semaphore uses a priority ceiling and there was no priority ceiling + defined for the :term:`home scheduler` of the calling task. + +:c:macro:`RTEMS_UNSATISFIED` + The semaphore could not be obtained immediately. + +:c:macro:`RTEMS_INVALID_PRIORITY` + The semaphore uses a priority ceiling and the calling task had a current + priority less than the priority ceiling. + +:c:macro:`RTEMS_INCORRECT_STATE` + Acquiring of the local, binary semaphore by the calling task would have + cased a deadlock. + +:c:macro:`RTEMS_INCORRECT_STATE` + The calling task attempted to recursively obtain a local, binary semaphore + using the MrsP locking protocol. + +:c:macro:`RTEMS_UNSATISFIED` + The semaphore was flushed while the calling task was waiting to obtain the + semaphore. + +:c:macro:`RTEMS_TIMEOUT` + The timeout happened while the calling task was waiting to obtain the + semaphore. + +:c:macro:`RTEMS_OBJECT_WAS_DELETED` + The semaphore was deleted while the calling task was waiting to obtain the + semaphore. + +.. rubric:: NOTES: + +If a local, binary semaphore was created with the +:c:macro:`RTEMS_PRIORITY_CEILING` or +:c:macro:`RTEMS_MULTIPROCESSOR_RESOURCE_SHARING` attribute, a task successfully +obtains the semaphore, and the priority of that task is greater than the +ceiling priority for this semaphore, then the priority of the task acquiring +the semaphore is elevated to that of the ceiling. + +Deadlock situations are detected for local, binary semaphores. If a deadlock +is detected, then the directive immediately returns the +:c:macro:`RTEMS_INCORRECT_STATE` status code. + +It is not allowed to recursively obtain (nested access) a local, binary +semaphore using the MrsP locking protocol and any attempt to do this will just +return the :c:macro:`RTEMS_INCORRECT_STATE` status code. This error can only +happen in SMP configurations. + +If the semaphore was created with the :c:macro:`RTEMS_PRIORITY` attribute, then +the calling task is inserted into the wait queue according to its priority. +However, if the semaphore was created with the :c:macro:`RTEMS_FIFO` attribute, +then the calling task is placed at the rear of the wait queue. + +Attempting to obtain a global semaphore which does not reside on the local node +will generate a request to the remote node to access the semaphore. If the +semaphore is not available and :c:macro:`RTEMS_NO_WAIT` was not specified, then +the task must be blocked until the semaphore is released. A proxy is allocated +on the remote node to represent the task until the semaphore is released. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* When a local, counting semaphore or a local, simple binary semaphore is + accessed and the :c:macro:`RTEMS_NO_WAIT` option is set, the directive may be + called from within interrupt context. + +* When a local semaphore is accessed and the request can be immediately + satisfied, the directive may be called from within device driver + initialization context. + +* The directive may be called from within task context. + +* When the request cannot be immediately satisfied and the + :c:macro:`RTEMS_WAIT` option is set, the calling task blocks at some point + during the directive call. + +* The timeout functionality of the directive requires a :term:`clock tick`. + +* When the directive operates on a remote object, the directive sends a message + to the remote node and waits for a reply. This will preempt the calling + task. + +.. Generated from spec:/rtems/sem/if/release + +.. raw:: latex + + \clearpage + +.. index:: rtems_semaphore_release() +.. index:: release a semaphore +.. index:: unlock a semaphore + +.. _InterfaceRtemsSemaphoreRelease: + +rtems_semaphore_release() +------------------------- + +Releases the semaphore. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_semaphore_release( rtems_id id ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the semaphore identifier. + +.. rubric:: DESCRIPTION: + +This directive releases the semaphore specified by ``id``. If the semaphore's +wait queue is not empty, then + +* the first task on the wait queue is removed and unblocked, the semaphore's + count is not changed, otherwise + +* the semaphore's count is incremented by one for counting semaphores and set + to one for binary and simple binary semaphores. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no semaphore associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_NOT_OWNER_OF_RESOURCE` + The calling task was not the owner of the semaphore. + +:c:macro:`RTEMS_UNSATISFIED` + The semaphore's count already had the maximum value of `UINT32_MAX + <https://en.cppreference.com/w/c/types/integer>`_. + +.. rubric:: NOTES: + +The calling task may be preempted if it causes a higher priority task to be +made ready for execution. + +The outermost release of a local, binary semaphore using the priority +inheritance, priority ceiling, or MrsP locking protocol may result in the +calling task having its priority lowered. This will occur if the highest +priority of the calling task was available due to the ownership of the released +semaphore. If a task was on the semaphore's wait queue, then the priority +associated with the semaphore will be transferred to the new owner. + +Releasing a global semaphore which does not reside on the local node will +generate a request telling the remote node to release the semaphore. + +If the task to be unblocked resides on a different node from the semaphore, +then the semaphore allocation is forwarded to the appropriate node, the waiting +task is unblocked, and the proxy used to represent the task is reclaimed. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* When a local, counting semaphore or a local, simple binary semaphore is + accessed, the directive may be called from within interrupt context. + +* When a local semaphore is accessed, the directive may be called from within + device driver initialization context. + +* The directive may be called from within task context. + +* The directive may unblock a task. This may cause the calling task to be + preempted. + +* When the directive operates on a remote object, the directive sends a message + to the remote node and waits for a reply. This will preempt the calling + task. + +.. Generated from spec:/rtems/sem/if/flush + +.. raw:: latex + + \clearpage + +.. index:: rtems_semaphore_flush() +.. index:: flush a semaphore +.. index:: unblock all tasks waiting on a semaphore + +.. _InterfaceRtemsSemaphoreFlush: + +rtems_semaphore_flush() +----------------------- + +Flushes the semaphore. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_semaphore_flush( rtems_id id ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the semaphore identifier. + +.. rubric:: DESCRIPTION: + +This directive unblocks all tasks waiting on the semaphore specified by ``id``. +The semaphore's count is not changed by this directive. Tasks which are +unblocked as the result of this directive will return from the +:ref:`InterfaceRtemsSemaphoreObtain` directive with a status code of +:c:macro:`RTEMS_UNSATISFIED` to indicate that the semaphore was not obtained. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no semaphore associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT` + The semaphore resided on a remote node. + +:c:macro:`RTEMS_NOT_DEFINED` + Flushing a semaphore using the MrsP locking protocol is undefined + behaviour. + +.. rubric:: NOTES: + +If the task to be unblocked resides on a different node from the semaphore, +then the waiting task is unblocked, and the proxy used to represent the task is +reclaimed. + +It is not allowed to flush a local, binary semaphore using the MrsP locking +protocol and any attempt to do this will just return the +:c:macro:`RTEMS_NOT_DEFINED` status code. This error can only happen in SMP +configurations. + +For barrier synchronization, the :ref:`RTEMSAPIClassicBarrier` offers a cleaner +alternative to using the semaphore flush directive. Unlike POSIX barriers, +they have a manual release option. + +Using the semaphore flush directive for condition synchronization in concert +with another semaphore may be subject to the lost wake-up problem. The +following attempt to implement a condition variable is broken. + +.. code-block:: c + :linenos: + + #include <rtems.h> + #include <assert.h> + + void cnd_wait( rtems_id cnd, rtems_id mtx ) + { + rtems_status_code sc; + + sc = rtems_semaphore_release( mtx ); + assert( sc == RTEMS_SUCCESSFUL ); + + // Here, a higher priority task may run and satisfy the condition. + // We may never wake up from the next semaphore obtain. + + sc = rtems_semaphore_obtain( cnd, RTEMS_WAIT, RTEMS_NO_TIMEOUT ); + assert( sc == RTEMS_UNSATISFIED ); + + sc = rtems_semaphore_obtain( mtx, RTEMS_WAIT, RTEMS_NO_TIMEOUT ); + assert( sc == RTEMS_SUCCESSFUL ); + } + + void cnd_broadcast( rtems_id cnd ) + { + rtems_status_code sc; + + sc = rtems_semaphore_flush( cnd ); + assert( sc == RTEMS_SUCCESSFUL ); + } + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* When a local, counting semaphore or a local, simple binary semaphore is + accessed, the directive may be called from within interrupt context. + +* When a local semaphore is accessed, the directive may be called from within + device driver initialization context. + +* The directive may be called from within task context. + +* The directive may unblock a task. This may cause the calling task to be + preempted. + +* When the directive operates on a remote object, the directive sends a message + to the remote node and waits for a reply. This will preempt the calling + task. + +.. Generated from spec:/rtems/sem/if/set-priority + +.. raw:: latex + + \clearpage + +.. index:: rtems_semaphore_set_priority() +.. index:: set priority by scheduler for a semaphore + +.. _InterfaceRtemsSemaphoreSetPriority: + +rtems_semaphore_set_priority() +------------------------------ + +Sets the priority by scheduler for the semaphore. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_semaphore_set_priority( + rtems_id semaphore_id, + rtems_id scheduler_id, + rtems_task_priority new_priority, + rtems_task_priority *old_priority + ); + +.. rubric:: PARAMETERS: + +``semaphore_id`` + This parameter is the semaphore identifier. + +``scheduler_id`` + This parameter is the identifier of the scheduler corresponding to the new + priority. + +``new_priority`` + This parameter is the new priority corresponding to the specified + scheduler. + +``old_priority`` + This parameter is the pointer to an :ref:`InterfaceRtemsTaskPriority` + object. When the directive call is successful, the old priority of the + semaphore corresponding to the specified scheduler will be stored in this + object. + +.. rubric:: DESCRIPTION: + +This directive sets the priority of the semaphore specified by +``semaphore_id``. The priority corresponds to the scheduler specified by +``scheduler_id``. + +The special priority value :c:macro:`RTEMS_CURRENT_PRIORITY` can be used to get +the current priority without changing it. + +The availability and use of a priority depends on the class and locking +protocol of the semaphore: + +* For local, binary semaphores using the MrsP locking protocol, the ceiling + priority for each scheduler can be set by this directive. + +* For local, binary semaphores using the priority ceiling protocol, the ceiling + priority can be set by this directive. + +* For other semaphore classes and locking protocols, setting a priority is + undefined behaviour. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``old_priority`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no scheduler associated with the identifier specified by + ``scheduler_id``. + +:c:macro:`RTEMS_INVALID_ID` + There was no semaphore associated with the identifier specified by + ``semaphore_id``. + +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT` + The semaphore resided on a remote node. + +:c:macro:`RTEMS_INVALID_PRIORITY` + The ``new_priority`` parameter was invalid. + +:c:macro:`RTEMS_NOT_DEFINED` + Setting a priority for the class or locking protocol of the semaphore is + undefined behaviour. + +.. rubric:: NOTES: + +Please have a look at the following example: + +.. code-block:: c + :linenos: + + #include <assert.h> + #include <rtems.h> + + #define SCHED_A rtems_build_name( ' ', ' ', ' ', 'A' ) + #define SCHED_B rtems_build_name( ' ', ' ', ' ', 'B' ) + + static void Init( rtems_task_argument arg ) + { + rtems_status_code sc; + rtems_id semaphore_id; + rtems_id scheduler_a_id; + rtems_id scheduler_b_id; + rtems_task_priority prio; + + (void) arg; + + // Get the scheduler identifiers + sc = rtems_scheduler_ident( SCHED_A, &scheduler_a_id ); + assert( sc == RTEMS_SUCCESSFUL ); + sc = rtems_scheduler_ident( SCHED_B, &scheduler_b_id ); + assert( sc == RTEMS_SUCCESSFUL ); + + // Create a local, binary semaphore using the MrsP locking protocol + sc = rtems_semaphore_create( + rtems_build_name( 'M', 'R', 'S', 'P' ), + 1, + RTEMS_BINARY_SEMAPHORE | RTEMS_PRIORITY | + RTEMS_MULTIPROCESSOR_RESOURCE_SHARING, + 1, + &semaphore_id + ); + assert( sc == RTEMS_SUCCESSFUL ); + + // The ceiling priority for each scheduler is equal to the priority + // specified for the semaphore creation. + prio = RTEMS_CURRENT_PRIORITY; + sc = rtems_semaphore_set_priority( semaphore_id, scheduler_a_id, prio, &prio ); + assert( sc == RTEMS_SUCCESSFUL ); + assert( prio == 1 ); + + // Check the old value and set a new ceiling priority for scheduler B + prio = 2; + sc = rtems_semaphore_set_priority( semaphore_id, scheduler_b_id, prio, &prio ); + assert( sc == RTEMS_SUCCESSFUL ); + assert( prio == 1 ); + + // Check the ceiling priority values + prio = RTEMS_CURRENT_PRIORITY; + sc = rtems_semaphore_set_priority( semaphore_id, scheduler_a_id, prio, &prio ); + assert( sc == RTEMS_SUCCESSFUL ); + assert( prio == 1 ); + prio = RTEMS_CURRENT_PRIORITY; + sc = rtems_semaphore_set_priority( semaphore_id, scheduler_b_id, prio, &prio ); + assert( sc == RTEMS_SUCCESSFUL ); + assert( prio == 2 ); + + sc = rtems_semaphore_delete( semaphore_id ); + assert( sc == RTEMS_SUCCESSFUL ); + + rtems_shutdown_executive( 0 ); + } + + #define CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER + #define CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER + #define CONFIGURE_MAXIMUM_TASKS 1 + #define CONFIGURE_MAXIMUM_SEMAPHORES 1 + #define CONFIGURE_MAXIMUM_PROCESSORS 2 + + #define CONFIGURE_SCHEDULER_SIMPLE_SMP + + #include <rtems/scheduler.h> + + RTEMS_SCHEDULER_CONTEXT_SIMPLE_SMP( a ); + RTEMS_SCHEDULER_CONTEXT_SIMPLE_SMP( b ); + + #define CONFIGURE_SCHEDULER_TABLE_ENTRIES \ + RTEMS_SCHEDULER_TABLE_SIMPLE_SMP( a, SCHED_A ), \ + RTEMS_SCHEDULER_TABLE_SIMPLE_SMP( b, SCHED_B ) + + #define CONFIGURE_SCHEDULER_ASSIGNMENTS \ + RTEMS_SCHEDULER_ASSIGN( 0, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY ), \ + RTEMS_SCHEDULER_ASSIGN( 1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY ) + + #define CONFIGURE_RTEMS_INIT_TASKS_TABLE + #define CONFIGURE_INIT + + #include <rtems/confdefs.h> + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may change the priority of a task. This may cause the calling + task to be preempted. diff --git a/c-user/semaphore/index.rst b/c-user/semaphore/index.rst new file mode 100644 index 0000000..369bccd --- /dev/null +++ b/c-user/semaphore/index.rst @@ -0,0 +1,20 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 embedded brains GmbH & Co. KG + +.. index:: semaphores +.. index:: binary semaphores +.. index:: counting semaphores +.. index:: mutual exclusion + +.. _RTEMSAPIClassicSem: + +Semaphore Manager +***************** + +.. toctree:: + + introduction + background + operations + directives diff --git a/c-user/semaphore/introduction.rst b/c-user/semaphore/introduction.rst new file mode 100644 index 0000000..ded0c3e --- /dev/null +++ b/c-user/semaphore/introduction.rst @@ -0,0 +1,55 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/rtems/sem/if/group + +.. _SemaphoreManagerIntroduction: + +Introduction +============ + +.. The following list was generated from: +.. spec:/rtems/sem/if/create +.. spec:/rtems/sem/if/ident +.. spec:/rtems/sem/if/delete +.. spec:/rtems/sem/if/obtain +.. spec:/rtems/sem/if/release +.. spec:/rtems/sem/if/flush +.. spec:/rtems/sem/if/set-priority + +The Semaphore Manager utilizes standard Dijkstra counting semaphores to provide +synchronization and mutual exclusion capabilities. The directives provided by +the Semaphore Manager are: + +* :ref:`InterfaceRtemsSemaphoreCreate` - Creates a semaphore. + +* :ref:`InterfaceRtemsSemaphoreIdent` - Identifies a semaphore by the object + name. + +* :ref:`InterfaceRtemsSemaphoreDelete` - Deletes the semaphore. + +* :ref:`InterfaceRtemsSemaphoreObtain` - Obtains the semaphore. + +* :ref:`InterfaceRtemsSemaphoreRelease` - Releases the semaphore. + +* :ref:`InterfaceRtemsSemaphoreFlush` - Flushes the semaphore. + +* :ref:`InterfaceRtemsSemaphoreSetPriority` - Sets the priority by scheduler + for the semaphore. diff --git a/c-user/semaphore/operations.rst b/c-user/semaphore/operations.rst new file mode 100644 index 0000000..19c4be2 --- /dev/null +++ b/c-user/semaphore/operations.rst @@ -0,0 +1,105 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Operations +========== + +.. _Creating a Semaphore: + +Creating a Semaphore +-------------------- + +The ``rtems_semaphore_create`` directive creates a binary or counting semaphore +with a user-specified name as well as an initial count. If a binary semaphore +is created with a count of zero (0) to indicate that it has been allocated, +then the task creating the semaphore is considered the current holder of the +semaphore. At create time the method for ordering waiting tasks in the +semaphore's task wait queue (by FIFO or task priority) is specified. +Additionally, the priority inheritance or priority ceiling algorithm may be +selected for local, binary semaphores that use the priority task wait queue +blocking discipline. If the priority ceiling algorithm is selected, then the +highest priority of any task which will attempt to obtain this semaphore must +be specified. RTEMS allocates a Semaphore Control Block (SMCB) from the SMCB +free list. This data structure is used by RTEMS to manage the newly created +semaphore. Also, a unique semaphore ID is generated and returned to the +calling task. + +.. _Obtaining Semaphore IDs: + +Obtaining Semaphore IDs +----------------------- + +When a semaphore is created, RTEMS generates a unique semaphore ID and assigns +it to the created semaphore until it is deleted. The semaphore ID may be +obtained by either of two methods. First, as the result of an invocation of +the ``rtems_semaphore_create`` directive, the semaphore ID is stored in a user +provided location. Second, the semaphore ID may be obtained later using the +``rtems_semaphore_ident`` directive. The semaphore ID is used by other +semaphore manager directives to access this semaphore. + +.. _Acquiring a Semaphore: + +Acquiring a Semaphore +--------------------- + +The ``rtems_semaphore_obtain`` directive is used to acquire the +specified semaphore. A simplified version of the ``rtems_semaphore_obtain`` +directive can be described as follows: + + If the semaphore's count is greater than zero then decrement the + semaphore's count else wait for release of semaphore then return + SUCCESSFUL. + +When the semaphore cannot be immediately acquired, one of the following +situations applies: + +- By default, the calling task will wait forever to acquire the semaphore. + +- Specifying ``RTEMS_NO_WAIT`` forces an immediate return with an error status + code. + +- Specifying a timeout limits the interval the task will wait before returning + with an error status code. + +If the task waits to acquire the semaphore, then it is placed in the +semaphore's task wait queue in either FIFO or task priority order. If the task +blocked waiting for a binary semaphore using priority inheritance and the +task's priority is greater than that of the task currently holding the +semaphore, then the holding task will inherit the priority of the blocking +task. All tasks waiting on a semaphore are returned an error code when the +semaphore is deleted. + +When a task successfully obtains a semaphore using priority ceiling and the +priority ceiling for this semaphore is greater than that of the holder, then +the holder's priority will be elevated. + +.. _Releasing a Semaphore: + +Releasing a Semaphore +--------------------- + +The ``rtems_semaphore_release`` directive is used to release the specified +semaphore. A simplified version of the ``rtems_semaphore_release`` directive +can be described as follows: + + If there are no tasks are waiting on this semaphore then increment the + semaphore's count else assign semaphore to a waiting task and return + SUCCESSFUL. + +If this is the outermost release of a binary semaphore that uses priority +inheritance or priority ceiling and the task does not currently hold any other +binary semaphores, then the task performing the ``rtems_semaphore_release`` +will have its priority restored to its normal value. + +.. _Deleting a Semaphore: + +Deleting a Semaphore +-------------------- + +The ``rtems_semaphore_delete`` directive removes a semaphore from the system +and frees its control block. A semaphore can be deleted by any local task that +knows the semaphore's ID. As a result of this directive, all tasks blocked +waiting to acquire the semaphore will be readied and returned a status code +which indicates that the semaphore was deleted. Any subsequent references to +the semaphore's name and ID are invalid. diff --git a/c-user/semaphore_manager.rst b/c-user/semaphore_manager.rst deleted file mode 100644 index 3e6008d..0000000 --- a/c-user/semaphore_manager.rst +++ /dev/null @@ -1,957 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-4.0 - -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) - -.. index:: semaphores -.. index:: binary semaphores -.. index:: counting semaphores -.. index:: mutual exclusion - -Semaphore Manager -***************** - -Introduction -============ - -The semaphore manager utilizes standard Dijkstra -counting semaphores to provide synchronization and mutual -exclusion capabilities. The directives provided by the -semaphore manager are: - -- rtems_semaphore_create_ - Create a semaphore - -- rtems_semaphore_ident_ - Get ID of a semaphore - -- rtems_semaphore_delete_ - Delete a semaphore - -- rtems_semaphore_obtain_ - Acquire a semaphore - -- rtems_semaphore_release_ - Release a semaphore - -- rtems_semaphore_flush_ - Unblock all tasks waiting on a semaphore - -- rtems_semaphore_set_priority_ - Set priority by scheduler for a semaphore - -Background -========== - -A semaphore can be viewed as a protected variable whose value can be modified -only with the ``rtems_semaphore_create``, ``rtems_semaphore_obtain``, and -``rtems_semaphore_release`` directives. RTEMS supports both binary and -counting semaphores. A binary semaphore is restricted to values of zero or one, -while a counting semaphore can assume any non-negative integer value. - -A binary semaphore (not a simple binary semaphore) can be used to control -access to a single resource. In particular, it can be used to enforce mutual -exclusion for a critical section in user code (mutex). In this instance, the -semaphore would be created with an initial count of one to indicate that no -task is executing the critical section of code. Upon entry to the critical -section, a task must issue the ``rtems_semaphore_obtain`` directive to prevent -other tasks from entering the critical section. Upon exit from the critical -section, the task that obtained the binary semaphore must issue the -``rtems_semaphore_release`` directive to allow another task to execute the -critical section. A binary semaphore must be released by the task that -obtained it. - -A counting semaphore can be used to control access to a pool of two or more -resources. For example, access to three printers could be administered by a -semaphore created with an initial count of three. When a task requires access -to one of the printers, it issues the ``rtems_semaphore_obtain`` directive to -obtain access to a printer. If a printer is not currently available, the task -can wait for a printer to become available or return immediately. When the -task has completed printing, it should issue the ``rtems_semaphore_release`` -directive to allow other tasks access to the printer. - -Task synchronization may be achieved by creating a semaphore with an initial -count of zero. One task waits for the arrival of another task by issuing a -``rtems_semaphore_obtain`` directive when it reaches a synchronization point. -The other task performs a corresponding ``rtems_semaphore_release`` operation -when it reaches its synchronization point, thus unblocking the pending task. - -.. _Nested Resource Access: - -Nested Resource Access ----------------------- - -Deadlock occurs when a task owning a binary semaphore attempts to acquire that -same semaphore and blocks as result. Since the semaphore is allocated to a -task, it cannot be deleted. Therefore, the task that currently holds the -semaphore and is also blocked waiting for that semaphore will never execute -again. - -RTEMS addresses this problem by allowing the task holding the binary semaphore -to obtain the same binary semaphore multiple times in a nested manner. Each -``rtems_semaphore_obtain`` must be accompanied with a -``rtems_semaphore_release``. The semaphore will only be made available for -acquisition by other tasks when the outermost ``rtems_semaphore_obtain`` is -matched with a ``rtems_semaphore_release``. - -Simple binary semaphores do not allow nested access and so can be used for task -synchronization. - -.. _Priority Inheritance: - -Priority Inheritance --------------------- - -RTEMS supports :ref:`priority inheritance <PriorityInheritance>` for local, -binary semaphores that use the priority task wait queue blocking discipline. -In SMP configurations, the :ref:`OMIP` is used instead. - -.. _Priority Ceiling: - -Priority Ceiling ----------------- - -RTEMS supports :ref:`priority ceiling <PriorityCeiling>` for local, binary -semaphores that use the priority task wait queue blocking discipline. - -.. _Multiprocessor Resource Sharing Protocol: - -Multiprocessor Resource Sharing Protocol ----------------------------------------- - -RTEMS supports the :ref:`MrsP` for local, binary semaphores that use the -priority task wait queue blocking discipline. In uniprocessor configurations, -the :ref:`PriorityCeiling` is used instead. - -.. _Building a Semaphore Attribute Set: - -Building a Semaphore Attribute Set ----------------------------------- - -In general, an attribute set is built by a bitwise OR of the desired attribute -components. The following table lists the set of valid semaphore attributes: - -.. list-table:: - :class: rtems-table - - * - ``RTEMS_FIFO`` - - tasks wait by FIFO (default) - * - ``RTEMS_PRIORITY`` - - tasks wait by priority - * - ``RTEMS_BINARY_SEMAPHORE`` - - restrict values to 0 and 1 - * - ``RTEMS_COUNTING_SEMAPHORE`` - - no restriction on values (default) - * - ``RTEMS_SIMPLE_BINARY_SEMAPHORE`` - - restrict values to 0 and 1, do not allow nested access, allow deletion of - locked semaphore. - * - ``RTEMS_NO_INHERIT_PRIORITY`` - - do not use priority inheritance (default) - * - ``RTEMS_INHERIT_PRIORITY`` - - use priority inheritance - * - ``RTEMS_NO_PRIORITY_CEILING`` - - do not use priority ceiling (default) - * - ``RTEMS_PRIORITY_CEILING`` - - use priority ceiling - * - ``RTEMS_NO_MULTIPROCESSOR_RESOURCE_SHARING`` - - do not use Multiprocessor Resource Sharing Protocol (default) - * - ``RTEMS_MULTIPROCESSOR_RESOURCE_SHARING`` - - use Multiprocessor Resource Sharing Protocol - * - ``RTEMS_LOCAL`` - - local semaphore (default) - * - ``RTEMS_GLOBAL`` - - global semaphore - -Attribute values are specifically designed to be mutually exclusive, therefore -bitwise OR and addition operations are equivalent as long as each attribute -appears exactly once in the component list. An attribute listed as a default -is not required to appear in the attribute list, although it is a good -programming practice to specify default attributes. If all defaults are -desired, the attribute ``RTEMS_DEFAULT_ATTRIBUTES`` should be specified on this -call. - -This example demonstrates the attribute_set parameter needed to create a local -semaphore with the task priority waiting queue discipline. The attribute_set -parameter passed to the ``rtems_semaphore_create`` directive could be either -``RTEMS_PRIORITY`` or ``RTEMS_LOCAL | RTEMS_PRIORITY``. The attribute_set -parameter can be set to ``RTEMS_PRIORITY`` because ``RTEMS_LOCAL`` is the -default for all created tasks. If a similar semaphore were to be known -globally, then the attribute_set parameter would be ``RTEMS_GLOBAL | -RTEMS_PRIORITY``. - -Some combinatinos of these attributes are invalid. For example, priority -ordered blocking discipline must be applied to a binary semaphore in order to -use either the priority inheritance or priority ceiling functionality. The -following tree figure illustrates the valid combinations. - -.. figure:: ../images/c_user/semaphore_attributes.png - :width: 90% - :align: center - :alt: Semaphore Attributes - -.. _Building a SEMAPHORE_OBTAIN Option Set: - -Building a SEMAPHORE_OBTAIN Option Set --------------------------------------- - -In general, an option is built by a bitwise OR of the desired option -components. The set of valid options for the ``rtems_semaphore_obtain`` -directive are listed in the following table: - -.. list-table:: - :class: rtems-table - - * - ``RTEMS_WAIT`` - - task will wait for semaphore (default) - * - ``RTEMS_NO_WAIT`` - - task should not wait - -Option values are specifically designed to be mutually exclusive, therefore -bitwise OR and addition operations are equivalent as long as each attribute -appears exactly once in the component list. An option listed as a default is -not required to appear in the list, although it is a good programming practice -to specify default options. If all defaults are desired, the option -``RTEMS_DEFAULT_OPTIONS`` should be specified on this call. - -This example demonstrates the option parameter needed to poll for a semaphore. -The option parameter passed to the ``rtems_semaphore_obtain`` directive should -be ``RTEMS_NO_WAIT``. - -Operations -========== - -.. _Creating a Semaphore: - -Creating a Semaphore --------------------- - -The ``rtems_semaphore_create`` directive creates a binary or counting semaphore -with a user-specified name as well as an initial count. If a binary semaphore -is created with a count of zero (0) to indicate that it has been allocated, -then the task creating the semaphore is considered the current holder of the -semaphore. At create time the method for ordering waiting tasks in the -semaphore's task wait queue (by FIFO or task priority) is specified. -Additionally, the priority inheritance or priority ceiling algorithm may be -selected for local, binary semaphores that use the priority task wait queue -blocking discipline. If the priority ceiling algorithm is selected, then the -highest priority of any task which will attempt to obtain this semaphore must -be specified. RTEMS allocates a Semaphore Control Block (SMCB) from the SMCB -free list. This data structure is used by RTEMS to manage the newly created -semaphore. Also, a unique semaphore ID is generated and returned to the -calling task. - -.. _Obtaining Semaphore IDs: - -Obtaining Semaphore IDs ------------------------ - -When a semaphore is created, RTEMS generates a unique semaphore ID and assigns -it to the created semaphore until it is deleted. The semaphore ID may be -obtained by either of two methods. First, as the result of an invocation of -the ``rtems_semaphore_create`` directive, the semaphore ID is stored in a user -provided location. Second, the semaphore ID may be obtained later using the -``rtems_semaphore_ident`` directive. The semaphore ID is used by other -semaphore manager directives to access this semaphore. - -.. _Acquiring a Semaphore: - -Acquiring a Semaphore ---------------------- - -The ``rtems_semaphore_obtain`` directive is used to acquire the -specified semaphore. A simplified version of the ``rtems_semaphore_obtain`` -directive can be described as follows: - - If the semaphore's count is greater than zero then decrement the - semaphore's count else wait for release of semaphore then return - SUCCESSFUL. - -When the semaphore cannot be immediately acquired, one of the following -situations applies: - -- By default, the calling task will wait forever to acquire the semaphore. - -- Specifying ``RTEMS_NO_WAIT`` forces an immediate return with an error status - code. - -- Specifying a timeout limits the interval the task will wait before returning - with an error status code. - -If the task waits to acquire the semaphore, then it is placed in the -semaphore's task wait queue in either FIFO or task priority order. If the task -blocked waiting for a binary semaphore using priority inheritance and the -task's priority is greater than that of the task currently holding the -semaphore, then the holding task will inherit the priority of the blocking -task. All tasks waiting on a semaphore are returned an error code when the -semaphore is deleted. - -When a task successfully obtains a semaphore using priority ceiling and the -priority ceiling for this semaphore is greater than that of the holder, then -the holder's priority will be elevated. - -.. _Releasing a Semaphore: - -Releasing a Semaphore ---------------------- - -The ``rtems_semaphore_release`` directive is used to release the specified -semaphore. A simplified version of the ``rtems_semaphore_release`` directive -can be described as follows: - - If there are no tasks are waiting on this semaphore then increment the - semaphore's count else assign semaphore to a waiting task and return - SUCCESSFUL. - -If this is the outermost release of a binary semaphore that uses priority -inheritance or priority ceiling and the task does not currently hold any other -binary semaphores, then the task performing the ``rtems_semaphore_release`` -will have its priority restored to its normal value. - -.. _Deleting a Semaphore: - -Deleting a Semaphore --------------------- - -The ``rtems_semaphore_delete`` directive removes a semaphore from the system -and frees its control block. A semaphore can be deleted by any local task that -knows the semaphore's ID. As a result of this directive, all tasks blocked -waiting to acquire the semaphore will be readied and returned a status code -which indicates that the semaphore was deleted. Any subsequent references to -the semaphore's name and ID are invalid. - -Directives -========== - -This section details the semaphore manager's directives. A subsection is -dedicated to each of this manager's directives and describes the calling -sequence, related constants, usage, and status codes. - -.. raw:: latex - - \clearpage - -.. index:: create a semaphore -.. index:: rtems_semaphore_create - -.. _rtems_semaphore_create: - -SEMAPHORE_CREATE - Create a semaphore -------------------------------------- - - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_semaphore_create( - rtems_name name, - uint32_t count, - rtems_attribute attribute_set, - rtems_task_priority priority_ceiling, - rtems_id *id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - semaphore created successfully - * - ``RTEMS_INVALID_NAME`` - - invalid semaphore name - * - ``RTEMS_INVALID_ADDRESS`` - - ``id`` is NULL - * - ``RTEMS_TOO_MANY`` - - too many semaphores created - * - ``RTEMS_NOT_DEFINED`` - - invalid attribute set - * - ``RTEMS_INVALID_NUMBER`` - - invalid starting count for binary semaphore - * - ``RTEMS_MP_NOT_CONFIGURED`` - - multiprocessing not configured - * - ``RTEMS_TOO_MANY`` - - too many global objects - -DESCRIPTION: - This directive creates a semaphore which resides on the local node. The - created semaphore has the user-defined name specified in name and the - initial count specified in count. For control and maintenance of the - semaphore, RTEMS allocates and initializes a SMCB. The RTEMS-assigned - semaphore id is returned in id. This semaphore id is used with other - semaphore related directives to access the semaphore. - - Specifying PRIORITY in attribute_set causes tasks waiting for a semaphore - to be serviced according to task priority. When FIFO is selected, tasks - are serviced in First In-First Out order. - -NOTES: - This directive will not cause the calling task to be preempted. - - The priority inheritance and priority ceiling algorithms are only supported - for local, binary semaphores that use the priority task wait queue blocking - discipline. - - The following semaphore attribute constants are defined by RTEMS: - - .. list-table:: - :class: rtems-table - - * - ``RTEMS_FIFO`` - - tasks wait by FIFO (default) - * - ``RTEMS_PRIORITY`` - - tasks wait by priority - * - ``RTEMS_BINARY_SEMAPHORE`` - - restrict values to 0 and 1 - * - ``RTEMS_COUNTING_SEMAPHORE`` - - no restriction on values (default) - * - ``RTEMS_SIMPLE_BINARY_SEMAPHORE`` - - restrict values to 0 and 1, block on nested access, allow deletion of locked semaphore. - * - ``RTEMS_NO_INHERIT_PRIORITY`` - - do not use priority inheritance (default) - * - ``RTEMS_INHERIT_PRIORITY`` - - use priority inheritance - * - ``RTEMS_NO_PRIORITY_CEILING`` - - do not use priority ceiling (default) - * - ``RTEMS_PRIORITY_CEILING`` - - use priority ceiling - * - ``RTEMS_NO_MULTIPROCESSOR_RESOURCE_SHARING`` - - do not use Multiprocessor Resource Sharing Protocol (default) - * - ``RTEMS_MULTIPROCESSOR_RESOURCE_SHARING`` - - use Multiprocessor Resource Sharing Protocol - * - ``RTEMS_LOCAL`` - - local semaphore (default) - * - ``RTEMS_GLOBAL`` - - global semaphore - - Semaphores should not be made global unless remote tasks must interact with - the created semaphore. This is to avoid the system overhead incurred by - the creation of a global semaphore. When a global semaphore is created, - the semaphore's name and id must be transmitted to every node in the system - for insertion in the local copy of the global object table. - - *Note*, some combinations of attributes are not valid. See the earlier - discussion on this. - - The total number of global objects, including semaphores, is limited by the - maximum_global_objects field in the Configuration Table. - - It is not allowed to create an initially locked MrsP semaphore and the - ``RTEMS_INVALID_NUMBER`` status code will be returned in SMP configurations - in this case. This prevents lock order reversal problems with the - allocator mutex. - -.. raw:: latex - - \clearpage - -.. index:: get ID of a semaphore -.. index:: obtain ID of a semaphore -.. index:: rtems_semaphore_ident - -.. _rtems_semaphore_ident: - -SEMAPHORE_IDENT - Get ID of a semaphore ---------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_semaphore_ident( - rtems_name name, - uint32_t node, - rtems_id *id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - semaphore identified successfully - * - ``RTEMS_INVALID_NAME`` - - semaphore name not found - * - ``RTEMS_INVALID_NODE`` - - invalid node id - -DESCRIPTION: - This directive obtains the semaphore id associated with the semaphore name. - If the semaphore name is not unique, then the semaphore id will match one - of the semaphores with that name. However, this semaphore id is not - guaranteed to correspond to the desired semaphore. The semaphore id is - used by other semaphore related directives to access the semaphore. - -NOTES: - This directive will not cause the running task to be preempted. - - If node is ``RTEMS_SEARCH_ALL_NODES``, all nodes are searched with the - local node being searched first. All other nodes are searched with the - lowest numbered node searched first. - - If node is a valid node number which does not represent the local node, - then only the semaphores exported by the designated node are searched. - - This directive does not generate activity on remote nodes. It accesses - only the local copy of the global object table. - -.. raw:: latex - - \clearpage - -.. index:: delete a semaphore -.. index:: rtems_semaphore_delete - -.. _rtems_semaphore_delete: - -SEMAPHORE_DELETE - Delete a semaphore -------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_semaphore_delete( - rtems_id id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - semaphore deleted successfully - * - ``RTEMS_INVALID_ID`` - - invalid semaphore id - * - ``RTEMS_RESOURCE_IN_USE`` - - binary semaphore is in use - * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - - cannot delete remote semaphore - -DESCRIPTION: - This directive deletes the semaphore specified by ``id``. All tasks - blocked waiting to acquire the semaphore will be readied and returned a - status code which indicates that the semaphore was deleted. The SMCB for - this semaphore is reclaimed by RTEMS. - -NOTES: - The calling task will be preempted if it is enabled by the task's execution - mode and a higher priority local task is waiting on the deleted semaphore. - The calling task will NOT be preempted if all of the tasks that are waiting - on the semaphore are remote tasks. - - The calling task does not have to be the task that created the semaphore. Any - local task that knows the semaphore id can delete the semaphore. - - When a global semaphore is deleted, the semaphore id must be transmitted to - every node in the system for deletion from the local copy of the global - object table. - - The semaphore must reside on the local node, even if the semaphore was - created with the ``RTEMS_GLOBAL`` option. - - Proxies, used to represent remote tasks, are reclaimed when the semaphore - is deleted. - -.. raw:: latex - - \clearpage - -.. index:: obtain a semaphore -.. index:: lock a semaphore -.. index:: rtems_semaphore_obtain - -.. _rtems_semaphore_obtain: - -SEMAPHORE_OBTAIN - Acquire a semaphore --------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_semaphore_obtain( - rtems_id id, - rtems_option option_set, - rtems_interval timeout - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - semaphore obtained successfully - * - ``RTEMS_UNSATISFIED`` - - semaphore not available - * - ``RTEMS_TIMEOUT`` - - timed out waiting for semaphore - * - ``RTEMS_OBJECT_WAS_DELETED`` - - semaphore deleted while waiting - * - ``RTEMS_INVALID_ID`` - - invalid semaphore id - -DESCRIPTION: - This directive acquires the semaphore specified by id. The ``RTEMS_WAIT`` - and ``RTEMS_NO_WAIT`` components of the options parameter indicate whether - the calling task wants to wait for the semaphore to become available or - return immediately if the semaphore is not currently available. With - either ``RTEMS_WAIT`` or ``RTEMS_NO_WAIT``, if the current semaphore count - is positive, then it is decremented by one and the semaphore is - successfully acquired by returning immediately with a successful return - code. - - If the calling task chooses to return immediately and the current semaphore - count is zero or negative, then a status code is returned indicating that - the semaphore is not available. If the calling task chooses to wait for a - semaphore and the current semaphore count is zero or negative, then it is - decremented by one and the calling task is placed on the semaphore's wait - queue and blocked. If the semaphore was created with the - ``RTEMS_PRIORITY`` attribute, then the calling task is inserted into the - queue according to its priority. However, if the semaphore was created - with the ``RTEMS_FIFO`` attribute, then the calling task is placed at the - rear of the wait queue. If the binary semaphore was created with the - ``RTEMS_INHERIT_PRIORITY`` attribute, then the priority of the task - currently holding the binary semaphore is guaranteed to be greater than or - equal to that of the blocking task. If the binary semaphore was created - with the ``RTEMS_PRIORITY_CEILING`` attribute, a task successfully obtains - the semaphore, and the priority of that task is greater than the ceiling - priority for this semaphore, then the priority of the task obtaining the - semaphore is elevated to that of the ceiling. - - The timeout parameter specifies the maximum interval the calling task is - willing to be blocked waiting for the semaphore. If it is set to - ``RTEMS_NO_TIMEOUT``, then the calling task will wait forever. If the - semaphore is available or the ``RTEMS_NO_WAIT`` option component is set, - then timeout is ignored. - - In case a semaphore is not available, then ``RTEMS_UNSATISFIED`` will be - returned. This happens immediately in case ``RTEMS_NO_WAIT`` is specified, - or as a result of another task invoking the ``rtems_semaphore_flush`` - directive in case ``RTEMS_WAIT`` is specified. - - Deadlock situations are detected for MrsP semaphores and the - ``RTEMS_UNSATISFIED`` status code will be returned in SMP configurations in - this case. - -NOTES: - The following semaphore acquisition option constants are defined by RTEMS: - - .. list-table:: - :class: rtems-table - - * - ``RTEMS_WAIT`` - - task will wait for semaphore (default) - * - ``RTEMS_NO_WAIT`` - - task should not wait - - Attempting to obtain a global semaphore which does not reside on the local - node will generate a request to the remote node to access the semaphore. - If the semaphore is not available and ``RTEMS_NO_WAIT`` was not specified, - then the task must be blocked until the semaphore is released. A proxy is - allocated on the remote node to represent the task until the semaphore is - released. - - A clock tick is required to support the timeout functionality of this - directive. - - It is not allowed to obtain a MrsP semaphore more than once by one task at - a time (nested access) and the ``RTEMS_UNSATISFIED`` status code will be - returned in SMP configurations in this case. - -.. raw:: latex - - \clearpage - -.. index:: release a semaphore -.. index:: unlock a semaphore -.. index:: rtems_semaphore_release - -.. _rtems_semaphore_release: - -SEMAPHORE_RELEASE - Release a semaphore ---------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_semaphore_release( - rtems_id id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - semaphore released successfully - * - ``RTEMS_INVALID_ID`` - - invalid semaphore id - * - ``RTEMS_NOT_OWNER_OF_RESOURCE`` - - calling task does not own semaphore - * - ``RTEMS_INCORRECT_STATE`` - - invalid unlock order - -DESCRIPTION: - This directive releases the semaphore specified by id. The semaphore count - is incremented by one. If the count is zero or negative, then the first - task on this semaphore's wait queue is removed and unblocked. The - unblocked task may preempt the running task if the running task's - preemption mode is enabled and the unblocked task has a higher priority - than the running task. - -NOTES: - The calling task may be preempted if it causes a higher priority task to be - made ready for execution. - - Releasing a global semaphore which does not reside on the local node will - generate a request telling the remote node to release the semaphore. - - If the task to be unblocked resides on a different node from the semaphore, - then the semaphore allocation is forwarded to the appropriate node, the - waiting task is unblocked, and the proxy used to represent the task is - reclaimed. - - The outermost release of a local, binary, priority inheritance or priority - ceiling semaphore may result in the calling task having its priority - lowered. This will occur if the calling task holds no other binary - semaphores and it has inherited a higher priority. - - The MrsP semaphores must be released in the reversed obtain order, - otherwise the ``RTEMS_INCORRECT_STATE`` status code will be returned in SMP - configurations in this case. - -.. raw:: latex - - \clearpage - -.. index:: flush a semaphore -.. index:: unblock all tasks waiting on a semaphore -.. index:: rtems_semaphore_flush - -.. _rtems_semaphore_flush: - -SEMAPHORE_FLUSH - Unblock all tasks waiting on a semaphore ----------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_semaphore_flush( - rtems_id id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - semaphore released successfully - * - ``RTEMS_INVALID_ID`` - - invalid semaphore id - * - ``RTEMS_NOT_DEFINED`` - - operation not defined for the protocol of the semaphore - * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - - not supported for remote semaphores - -DESCRIPTION: - This directive unblocks all tasks waiting on the semaphore specified by id. - Since there are tasks blocked on the semaphore, the semaphore's count is - not changed by this directive and thus is zero before and after this - directive is executed. Tasks which are unblocked as the result of this - directive will return from the ``rtems_semaphore_obtain`` directive with a - status code of ``RTEMS_UNSATISFIED`` to indicate that the semaphore was not - obtained. - - This directive may unblock any number of tasks. Any of the unblocked tasks - may preempt the running task if the running task's preemption mode is - enabled and an unblocked task has a higher priority than the running task. - -NOTES: - The calling task may be preempted if it causes a higher priority task to be - made ready for execution. - - If the task to be unblocked resides on a different node from the semaphore, - then the waiting task is unblocked, and the proxy used to represent the - task is reclaimed. - - It is not allowed to flush a MrsP semaphore and the ``RTEMS_NOT_DEFINED`` - status code will be returned in SMP configurations in this case. - - Using the ``rtems_semaphore_flush`` directive for condition synchronization - in concert with another semaphore may be subject to the lost wake-up - problem. The following attempt to implement a condition variable is - broken. - - .. code-block:: c - - #include <rtems.h> - #include <assert.h> - - void cnd_wait( rtems_id cnd, rtems_id mtx ) - { - rtems_status_code sc; - - sc = rtems_semaphore_release( mtx ); - assert( sc == RTEMS_SUCCESSFUL ); - - /* - * Here, a higher priority task may run and satisfy the condition. We - * may never wake up from the next semaphore obtain. - */ - - sc = rtems_semaphore_obtain( cnd, RTEMS_WAIT, RTEMS_NO_TIMEOUT ); - assert( sc == RTEMS_UNSATISFIED ); - - sc = rtems_semaphore_obtain( mtx, RTEMS_WAIT, RTEMS_NO_TIMEOUT ); - assert( sc == RTEMS_SUCCESSFUL ); - } - - void cnd_broadcast( rtems_id cnd ) - { - rtems_status_code sc; - - sc = rtems_semaphore_flush( cnd ); - assert( sc == RTEMS_SUCCESSFUL ); - } - - For barrier synchronization, the :ref:`barrier_manager` offers a cleaner - alternative to using the `rtems_semaphore_flush` directive. Unlike POSIX - barriers, they have a manual release option. - -.. raw:: latex - - \clearpage - -.. index:: set priority by scheduler for a semaphore -.. index:: rtems_semaphore_set_priority - -.. _rtems_semaphore_set_priority: - -SEMAPHORE_SET_PRIORITY - Set priority by scheduler for a semaphore ------------------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_semaphore_set_priority( - rtems_id semaphore_id, - rtems_id scheduler_id, - rtems_task_priority new_priority, - rtems_task_priority *old_priority - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - successful operation - * - ``RTEMS_INVALID_ID`` - - invalid semaphore or scheduler id - * - ``RTEMS_INVALID_ADDRESS`` - - ``old_priority`` is NULL - * - ``RTEMS_INVALID_PRIORITY`` - - invalid new priority value - * - ``RTEMS_NOT_DEFINED`` - - operation not defined for the protocol ofthe semaphore - * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - - not supported for remote semaphores - -DESCRIPTION: - This directive sets the priority value with respect to the specified - scheduler of a semaphore. - - The special priority value ``RTEMS_CURRENT_PRIORITY`` can be used to get - the current priority value without changing it. - - The interpretation of the priority value depends on the protocol of the - semaphore object. - - - The Multiprocessor Resource Sharing Protocol needs a ceiling priority per - scheduler instance. This operation can be used to specify these priority - values. - - - For the Priority Ceiling Protocol the ceiling priority is used with this - operation. - - - For other protocols this operation is not defined. - -EXAMPLE: - .. code-block:: c - :linenos: - - #include <assert.h> - #include <stdlib.h> - #include <rtems.h> - - #define SCHED_A rtems_build_name(' ', ' ', ' ', 'A') - #define SCHED_B rtems_build_name(' ', ' ', ' ', 'B') - - static void Init(rtems_task_argument arg) - { - rtems_status_code sc; - rtems_id semaphore_id; - rtems_id scheduler_a_id; - rtems_id scheduler_b_id; - rtems_task_priority prio; - - /* Get the scheduler identifiers */ - sc = rtems_scheduler_ident(SCHED_A, &scheduler_a_id); - assert(sc == RTEMS_SUCCESSFUL); - sc = rtems_scheduler_ident(SCHED_B, &scheduler_b_id); - assert(sc == RTEMS_SUCCESSFUL); - - /* Create a MrsP semaphore object */ - sc = rtems_semaphore_create( - rtems_build_name('M', 'R', 'S', 'P'), - 1, - RTEMS_MULTIPROCESSOR_RESOURCE_SHARING | RTEMS_BINARY_SEMAPHORE, - 1, - &semaphore_id - ); - assert(sc == RTEMS_SUCCESSFUL); - - /* - * The ceiling priority values per scheduler are equal to the value specified - * for object creation. - */ - prio = RTEMS_CURRENT_PRIORITY; - sc = rtems_semaphore_set_priority(semaphore_id, scheduler_a_id, prio, &prio); - assert(sc == RTEMS_SUCCESSFUL); - assert(prio == 1); - - /* Check the old value and set a new ceiling priority for scheduler B */ - prio = 2; - sc = rtems_semaphore_set_priority(semaphore_id, scheduler_b_id, prio, &prio); - assert(sc == RTEMS_SUCCESSFUL); - assert(prio == 1); - - /* Check the ceiling priority values */ - prio = RTEMS_CURRENT_PRIORITY; - sc = rtems_semaphore_set_priority(semaphore_id, scheduler_a_id, prio, &prio); - assert(sc == RTEMS_SUCCESSFUL); - assert(prio == 1); - prio = RTEMS_CURRENT_PRIORITY; - sc = rtems_semaphore_set_priority(semaphore_id, scheduler_b_id, prio, &prio); - assert(sc == RTEMS_SUCCESSFUL); - assert(prio == 2); - - sc = rtems_semaphore_delete(semaphore_id); - assert(sc == RTEMS_SUCCESSFUL); - - exit(0); - } - - #define CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER - #define CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER - #define CONFIGURE_MAXIMUM_TASKS 1 - #define CONFIGURE_MAXIMUM_SEMAPHORES 1 - #define CONFIGURE_MAXIMUM_PROCESSORS 2 - - #define CONFIGURE_SCHEDULER_SIMPLE_SMP - - #include <rtems/scheduler.h> - - RTEMS_SCHEDULER_CONTEXT_SIMPLE_SMP(a); - RTEMS_SCHEDULER_CONTEXT_SIMPLE_SMP(b); - - #define CONFIGURE_SCHEDULER_TABLE_ENTRIES \ - RTEMS_SCHEDULER_TABLE_SIMPLE_SMP(a, SCHED_A), \ - RTEMS_SCHEDULER_TABLE_SIMPLE_SMP(b, SCHED_B) - - #define CONFIGURE_SCHEDULER_ASSIGNMENTS \ - RTEMS_SCHEDULER_ASSIGN(0, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \ - RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY) - - #define CONFIGURE_RTEMS_INIT_TASKS_TABLE - #define CONFIGURE_INIT - - #include <rtems/confdefs.h> diff --git a/c-user/signal/background.rst b/c-user/signal/background.rst new file mode 100644 index 0000000..5ba5eeb --- /dev/null +++ b/c-user/signal/background.rst @@ -0,0 +1,112 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Background +========== + +.. index:: asynchronous signal routine +.. index:: ASR + +Signal Manager Definitions +-------------------------- + +The signal manager allows a task to optionally define an asynchronous signal +routine (ASR). An ASR is to a task what an ISR is to an application's set of +tasks. When the processor is interrupted, the execution of an application is +also interrupted and an ISR is given control. Similarly, when a signal is sent +to a task, that task's execution path will be "interrupted" by the ASR. +Sending a signal to a task has no effect on the receiving task's current +execution state. + +.. index:: rtems_signal_set + +A signal flag is used by a task (or ISR) to inform another task of the +occurrence of a significant situation. Thirty-two signal flags are associated +with each task. A collection of one or more signals is referred to as a signal +set. The data type ``rtems_signal_set`` is used to manipulate signal sets. + +A signal set is posted when it is directed (or sent) to a task. A pending +signal is a signal that has been sent to a task with a valid ASR, but has not +been processed by that task's ASR. + +.. index:: ASR vs. ISR +.. index:: ISR vs. ASR + +A Comparison of ASRs and ISRs +----------------------------- + +The format of an ASR is similar to that of an ISR with the following +exceptions: + +- ISRs are scheduled by the processor hardware. ASRs are scheduled by RTEMS. + +- ISRs do not execute in the context of a task and may invoke only a subset of + directives. ASRs execute in the context of a task and may execute any + directive. + +- When an ISR is invoked, it is passed the vector number as its argument. When + an ASR is invoked, it is passed the signal set as its argument. + +- An ASR has a task mode which can be different from that of the task. An ISR + does not execute as a task and, as a result, does not have a task mode. + +.. index:: signal set, building + +Building a Signal Set +--------------------- + +A signal set is built by a bitwise OR of the desired signals. The set of valid +signals is ``RTEMS_SIGNAL_0`` through ``RTEMS_SIGNAL_31``. If a signal is not +explicitly specified in the signal set, then it is not present. Signal values +are specifically designed to be mutually exclusive, therefore bitwise OR and +addition operations are equivalent as long as each signal appears exactly once +in the component list. + +This example demonstrates the signal parameter used when sending the signal set +consisting of ``RTEMS_SIGNAL_6``, ``RTEMS_SIGNAL_15``, and ``RTEMS_SIGNAL_31``. +The signal parameter provided to the ``rtems_signal_send`` directive should be +``RTEMS_SIGNAL_6 | RTEMS_SIGNAL_15 | RTEMS_SIGNAL_31``. + +.. index:: ASR mode, building + +Building an ASR Mode +-------------------- + +In general, an ASR's mode is built by a bitwise OR of the desired mode +components. The set of valid mode components is the same as those allowed with +the task_create and task_mode directives. A complete list of mode options is +provided in the following table: + +.. list-table:: + :class: rtems-table + + * - ``RTEMS_PREEMPT`` + - is masked by ``RTEMS_PREEMPT_MASK`` and enables preemption + * - ``RTEMS_NO_PREEMPT`` + - is masked by ``RTEMS_PREEMPT_MASK`` and disables preemption + * - ``RTEMS_NO_TIMESLICE`` + - is masked by ``RTEMS_TIMESLICE_MASK`` and disables timeslicing + * - ``RTEMS_TIMESLICE`` + - is masked by ``RTEMS_TIMESLICE_MASK`` and enables timeslicing + * - ``RTEMS_ASR`` + - is masked by ``RTEMS_ASR_MASK`` and enables ASR processing + * - ``RTEMS_NO_ASR`` + - is masked by ``RTEMS_ASR_MASK`` and disables ASR processing + * - ``RTEMS_INTERRUPT_LEVEL(0)`` + - is masked by ``RTEMS_INTERRUPT_MASK`` and enables all interrupts + * - ``RTEMS_INTERRUPT_LEVEL(n)`` + - is masked by ``RTEMS_INTERRUPT_MASK`` and sets interrupts level n + +Mode values are specifically designed to be mutually exclusive, therefore +bitwise OR and addition operations are equivalent as long as each mode appears +exactly once in the component list. A mode component listed as a default is +not required to appear in the mode list, although it is a good programming +practice to specify default components. If all defaults are desired, the mode +``DEFAULT_MODES`` should be specified on this call. + +This example demonstrates the mode parameter used with the +``rtems_signal_catch`` to establish an ASR which executes at interrupt level +three and is non-preemptible. The mode should be set to +``RTEMS_INTERRUPT_LEVEL(3) | RTEMS_NO_PREEMPT`` to indicate the desired +processor mode and interrupt level. diff --git a/c-user/signal/directives.rst b/c-user/signal/directives.rst new file mode 100644 index 0000000..9345132 --- /dev/null +++ b/c-user/signal/directives.rst @@ -0,0 +1,198 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. _SignalManagerDirectives: + +Directives +========== + +This section details the directives of the Signal Manager. A subsection is +dedicated to each of this manager's directives and lists the calling sequence, +parameters, description, return values, and notes of the directive. + +.. Generated from spec:/rtems/signal/if/catch + +.. raw:: latex + + \clearpage + +.. index:: rtems_signal_catch() +.. index:: establish an ASR +.. index:: install an ASR + +.. _InterfaceRtemsSignalCatch: + +rtems_signal_catch() +-------------------- + +Establishes an asynchronous signal routine (ASR) for the calling task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_signal_catch( + rtems_asr_entry asr_handler, + rtems_mode mode_set + ); + +.. rubric:: PARAMETERS: + +``asr_handler`` + This parameter is the handler to process an asynchronous signal set. + +``mode_set`` + This parameter is the task mode while an asynchronous signal set is + processed by the handler. See :ref:`InterfaceRtemsTaskMode`. + +.. rubric:: DESCRIPTION: + +This directive establishes an asynchronous signal routine (ASR) for the calling +task. The ``asr_handler`` parameter specifies the entry point of the ASR. A +task may have at most one handler installed at a time. The most recently +installed handler is used. When ``asr_handler`` is `NULL +<https://en.cppreference.com/w/c/types/NULL>`_, the ASR for the calling task is +invalidated and all pending signals are cleared. Any signals sent to a task +with an invalid ASR are discarded. The ``mode_set`` parameter specifies the +execution mode for the ASR. This execution mode supersedes the task's +execution mode while the ASR is executing. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_NOT_IMPLEMENTED` + The :c:macro:`RTEMS_NO_PREEMPT` was set in ``mode_set`` and the system + configuration had no implementation for this mode. + +:c:macro:`RTEMS_NOT_IMPLEMENTED` + The :c:func:`RTEMS_INTERRUPT_LEVEL` was set to a positive level in + ``mode_set`` and the system configuration had no implementation for this + mode. + +.. rubric:: NOTES: + +It is strongly recommended to disable ASR processing during ASR processing by +setting :c:macro:`RTEMS_NO_ASR` in ``mode_set``, otherwise a recursion may +happen during ASR processing. Uncontrolled recursion may lead to stack +overflows. + +Using the same mutex (in particular a recursive mutex) in normal task context +and during ASR processing may result in undefined behaviour. + +Asynchronous signal handlers can access thread-local storage (:term:`TLS`). +When thread-local storage is shared between normal task context and ASR +processing, it may be protected by disabled interrupts. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/signal/if/send + +.. raw:: latex + + \clearpage + +.. index:: rtems_signal_send() +.. index:: send signal set + +.. _InterfaceRtemsSignalSend: + +rtems_signal_send() +------------------- + +Sends the signal set to the task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_signal_send( + rtems_id id, + rtems_signal_set signal_set + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the identifier of the target task to receive the signal + set. + +``signal_set`` + This parameter is the signal set to send. + +.. rubric:: DESCRIPTION: + +This directive sends the signal set, ``signal_set``, to the target task +identified by ``id``. + +If a caller sends a signal set to a task with an invalid :term:`ASR`, then an +error code is returned to the caller. If a caller sends a signal set to a task +whose ASR is valid but disabled, then the signal set will be caught and left +pending for the ASR to process when it is enabled. If a caller sends a signal +set to a task with an ASR that is both valid and enabled, then the signal set +is caught and the ASR will execute the next time the task is dispatched to run. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_NUMBER` + The ``signal_set`` parameter was 0. + +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_NOT_DEFINED` + The target task had no valid ASR installed. + +.. rubric:: NOTES: + +Sending a signal set to a task has no effect on that task's state. If a signal +set is sent to a blocked task, then the task will remain blocked and the +signals will be processed when the task becomes the running task. + +Sending a signal set to a global task which does not reside on the local node +will generate a request telling the remote node to send the signal set to the +specified task. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* When the directive operates on a local object, the directive will not cause + the calling task to be preempted. + +* When the directive operates on a remote object, the directive sends a message + to the remote node and waits for a reply. This will preempt the calling + task. diff --git a/c-user/signal/index.rst b/c-user/signal/index.rst new file mode 100644 index 0000000..d52e098 --- /dev/null +++ b/c-user/signal/index.rst @@ -0,0 +1,17 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 embedded brains GmbH & Co. KG + +.. index:: signals + +.. _RTEMSAPIClassicSignal: + +Signal Manager +************** + +.. toctree:: + + introduction + background + operations + directives diff --git a/c-user/signal/introduction.rst b/c-user/signal/introduction.rst new file mode 100644 index 0000000..f6e0ded --- /dev/null +++ b/c-user/signal/introduction.rst @@ -0,0 +1,38 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/rtems/signal/if/group + +.. _SignalManagerIntroduction: + +Introduction +============ + +.. The following list was generated from: +.. spec:/rtems/signal/if/catch +.. spec:/rtems/signal/if/send + +The Signal Manager provides the capabilities required for asynchronous +communication. The directives provided by the Signal Manager are: + +* :ref:`InterfaceRtemsSignalCatch` - Establishes an asynchronous signal routine + (ASR) for the calling task. + +* :ref:`InterfaceRtemsSignalSend` - Sends the signal set to the task. diff --git a/c-user/signal/operations.rst b/c-user/signal/operations.rst new file mode 100644 index 0000000..967b35f --- /dev/null +++ b/c-user/signal/operations.rst @@ -0,0 +1,75 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Operations +========== + +Establishing an ASR +------------------- + +The ``rtems_signal_catch`` directive establishes an ASR for the calling task. +The address of the ASR and its execution mode are specified to this directive. +The ASR's mode is distinct from the task's mode. For example, the task may +allow preemption, while that task's ASR may have preemption disabled. Until a +task calls ``rtems_signal_catch`` the first time, its ASR is invalid, and no +signal sets can be sent to the task. + +A task may invalidate its ASR and discard all pending signals by calling +``rtems_signal_catch`` with a value of NULL for the ASR's address. When a +task's ASR is invalid, new signal sets sent to this task are discarded. + +A task may disable ASR processing (``RTEMS_NO_ASR``) via the task_mode +directive. When a task's ASR is disabled, the signals sent to it are left +pending to be processed later when the ASR is enabled. + +Any directive that can be called from a task can also be called from an ASR. A +task is only allowed one active ASR. Thus, each call to ``rtems_signal_catch`` +replaces the previous one. + +Normally, signal processing is disabled for the ASR's execution mode, but if +signal processing is enabled for the ASR, the ASR must be reentrant. + +Sending a Signal Set +-------------------- + +The ``rtems_signal_send`` directive allows both tasks and ISRs to send signals +to a target task. The target task and a set of signals are specified to the +``rtems_signal_send`` directive. The sending of a signal to a task has no +effect on the execution state of that task. If the task is not the currently +running task, then the signals are left pending and processed by the task's ASR +the next time the task is dispatched to run. The ASR is executed immediately +before the task is dispatched. If the currently running task sends a signal to +itself or is sent a signal from an ISR, its ASR is immediately dispatched to +run provided signal processing is enabled. + +If an ASR with signals enabled is preempted by another task or an ISR and a new +signal set is sent, then a new copy of the ASR will be invoked, nesting the +preempted ASR. Upon completion of processing the new signal set, control will +return to the preempted ASR. In this situation, the ASR must be reentrant. + +Like events, identical signals sent to a task are not queued. In other words, +sending the same signal multiple times to a task (without any intermediate +signal processing occurring for the task), has the same result as sending that +signal to that task once. + +.. index:: rtems_asr + +Processing an ASR +----------------- + +Asynchronous signals were designed to provide the capability to generate +software interrupts. The processing of software interrupts parallels that of +hardware interrupts. As a result, the differences between the formats of ASRs +and ISRs is limited to the meaning of the single argument passed to an ASR. +The ASR should have the following calling sequence and adhere to C calling +conventions: + +.. code-block:: c + + rtems_asr user_routine( + rtems_signal_set signals + ); + +When the ASR returns to RTEMS the mode and execution path of the interrupted +task (or ASR) is restored to the context prior to entering the ASR. diff --git a/c-user/signal_manager.rst b/c-user/signal_manager.rst deleted file mode 100644 index 8cf1101..0000000 --- a/c-user/signal_manager.rst +++ /dev/null @@ -1,322 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-4.0 - -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) - -.. index:: signals - -Signal Manager -************** - -Introduction -============ - -The signal manager provides the capabilities required for asynchronous -communication. The directives provided by the signal manager are: - -- rtems_signal_catch_ - Establish an ASR - -- rtems_signal_send_ - Send signal set to a task - -Background -========== - -.. index:: asynchronous signal routine -.. index:: ASR - -Signal Manager Definitions --------------------------- - -The signal manager allows a task to optionally define an asynchronous signal -routine (ASR). An ASR is to a task what an ISR is to an application's set of -tasks. When the processor is interrupted, the execution of an application is -also interrupted and an ISR is given control. Similarly, when a signal is sent -to a task, that task's execution path will be "interrupted" by the ASR. -Sending a signal to a task has no effect on the receiving task's current -execution state. - -.. index:: rtems_signal_set - -A signal flag is used by a task (or ISR) to inform another task of the -occurrence of a significant situation. Thirty-two signal flags are associated -with each task. A collection of one or more signals is referred to as a signal -set. The data type ``rtems_signal_set`` is used to manipulate signal sets. - -A signal set is posted when it is directed (or sent) to a task. A pending -signal is a signal that has been sent to a task with a valid ASR, but has not -been processed by that task's ASR. - -.. index:: ASR vs. ISR -.. index:: ISR vs. ASR - -A Comparison of ASRs and ISRs ------------------------------ - -The format of an ASR is similar to that of an ISR with the following -exceptions: - -- ISRs are scheduled by the processor hardware. ASRs are scheduled by RTEMS. - -- ISRs do not execute in the context of a task and may invoke only a subset of - directives. ASRs execute in the context of a task and may execute any - directive. - -- When an ISR is invoked, it is passed the vector number as its argument. When - an ASR is invoked, it is passed the signal set as its argument. - -- An ASR has a task mode which can be different from that of the task. An ISR - does not execute as a task and, as a result, does not have a task mode. - -.. index:: signal set, building - -Building a Signal Set ---------------------- - -A signal set is built by a bitwise OR of the desired signals. The set of valid -signals is ``RTEMS_SIGNAL_0`` through ``RTEMS_SIGNAL_31``. If a signal is not -explicitly specified in the signal set, then it is not present. Signal values -are specifically designed to be mutually exclusive, therefore bitwise OR and -addition operations are equivalent as long as each signal appears exactly once -in the component list. - -This example demonstrates the signal parameter used when sending the signal set -consisting of ``RTEMS_SIGNAL_6``, ``RTEMS_SIGNAL_15``, and ``RTEMS_SIGNAL_31``. -The signal parameter provided to the ``rtems_signal_send`` directive should be -``RTEMS_SIGNAL_6 | RTEMS_SIGNAL_15 | RTEMS_SIGNAL_31``. - -.. index:: ASR mode, building - -Building an ASR Mode --------------------- - -In general, an ASR's mode is built by a bitwise OR of the desired mode -components. The set of valid mode components is the same as those allowed with -the task_create and task_mode directives. A complete list of mode options is -provided in the following table: - -.. list-table:: - :class: rtems-table - - * - ``RTEMS_PREEMPT`` - - is masked by ``RTEMS_PREEMPT_MASK`` and enables preemption - * - ``RTEMS_NO_PREEMPT`` - - is masked by ``RTEMS_PREEMPT_MASK`` and disables preemption - * - ``RTEMS_NO_TIMESLICE`` - - is masked by ``RTEMS_TIMESLICE_MASK`` and disables timeslicing - * - ``RTEMS_TIMESLICE`` - - is masked by ``RTEMS_TIMESLICE_MASK`` and enables timeslicing - * - ``RTEMS_ASR`` - - is masked by ``RTEMS_ASR_MASK`` and enables ASR processing - * - ``RTEMS_NO_ASR`` - - is masked by ``RTEMS_ASR_MASK`` and disables ASR processing - * - ``RTEMS_INTERRUPT_LEVEL(0)`` - - is masked by ``RTEMS_INTERRUPT_MASK`` and enables all interrupts - * - ``RTEMS_INTERRUPT_LEVEL(n)`` - - is masked by ``RTEMS_INTERRUPT_MASK`` and sets interrupts level n - -Mode values are specifically designed to be mutually exclusive, therefore -bitwise OR and addition operations are equivalent as long as each mode appears -exactly once in the component list. A mode component listed as a default is -not required to appear in the mode list, although it is a good programming -practice to specify default components. If all defaults are desired, the mode -``DEFAULT_MODES`` should be specified on this call. - -This example demonstrates the mode parameter used with the -``rtems_signal_catch`` to establish an ASR which executes at interrupt level -three and is non-preemptible. The mode should be set to -``RTEMS_INTERRUPT_LEVEL(3) | RTEMS_NO_PREEMPT`` to indicate the desired -processor mode and interrupt level. - -Operations -========== - -Establishing an ASR -------------------- - -The ``rtems_signal_catch`` directive establishes an ASR for the calling task. -The address of the ASR and its execution mode are specified to this directive. -The ASR's mode is distinct from the task's mode. For example, the task may -allow preemption, while that task's ASR may have preemption disabled. Until a -task calls ``rtems_signal_catch`` the first time, its ASR is invalid, and no -signal sets can be sent to the task. - -A task may invalidate its ASR and discard all pending signals by calling -``rtems_signal_catch`` with a value of NULL for the ASR's address. When a -task's ASR is invalid, new signal sets sent to this task are discarded. - -A task may disable ASR processing (``RTEMS_NO_ASR``) via the task_mode -directive. When a task's ASR is disabled, the signals sent to it are left -pending to be processed later when the ASR is enabled. - -Any directive that can be called from a task can also be called from an ASR. A -task is only allowed one active ASR. Thus, each call to ``rtems_signal_catch`` -replaces the previous one. - -Normally, signal processing is disabled for the ASR's execution mode, but if -signal processing is enabled for the ASR, the ASR must be reentrant. - -Sending a Signal Set --------------------- - -The ``rtems_signal_send`` directive allows both tasks and ISRs to send signals -to a target task. The target task and a set of signals are specified to the -``rtems_signal_send`` directive. The sending of a signal to a task has no -effect on the execution state of that task. If the task is not the currently -running task, then the signals are left pending and processed by the task's ASR -the next time the task is dispatched to run. The ASR is executed immediately -before the task is dispatched. If the currently running task sends a signal to -itself or is sent a signal from an ISR, its ASR is immediately dispatched to -run provided signal processing is enabled. - -If an ASR with signals enabled is preempted by another task or an ISR and a new -signal set is sent, then a new copy of the ASR will be invoked, nesting the -preempted ASR. Upon completion of processing the new signal set, control will -return to the preempted ASR. In this situation, the ASR must be reentrant. - -Like events, identical signals sent to a task are not queued. In other words, -sending the same signal multiple times to a task (without any intermediate -signal processing occurring for the task), has the same result as sending that -signal to that task once. - -.. index:: rtems_asr - -Processing an ASR ------------------ - -Asynchronous signals were designed to provide the capability to generate -software interrupts. The processing of software interrupts parallels that of -hardware interrupts. As a result, the differences between the formats of ASRs -and ISRs is limited to the meaning of the single argument passed to an ASR. -The ASR should have the following calling sequence and adhere to C calling -conventions: - -.. code-block:: c - - rtems_asr user_routine( - rtems_signal_set signals - ); - -When the ASR returns to RTEMS the mode and execution path of the interrupted -task (or ASR) is restored to the context prior to entering the ASR. - -Directives -========== - -This section details the signal manager's directives. A subsection is -dedicated to each of this manager's directives and describes the calling -sequence, related constants, usage, and status codes. - -.. raw:: latex - - \clearpage - -.. index:: establish an ASR -.. index:: install an ASR -.. index:: rtems_signal_catch - -.. _rtems_signal_catch: - -SIGNAL_CATCH - Establish an ASR -------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_signal_catch( - rtems_asr_entry asr_handler, - rtems_mode mode - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - always successful - -DESCRIPTION: - This directive establishes an asynchronous signal routine (ASR) for the - calling task. The asr_handler parameter specifies the entry point of the - ASR. If asr_handler is NULL, the ASR for the calling task is invalidated - and all pending signals are cleared. Any signals sent to a task with an - invalid ASR are discarded. The mode parameter specifies the execution mode - for the ASR. This execution mode supersedes the task's execution mode - while the ASR is executing. - -NOTES: - This directive will not cause the calling task to be preempted. - - The following task mode constants are defined by RTEMS: - - .. list-table:: - :class: rtems-table - - * - ``RTEMS_PREEMPT`` - - is masked by ``RTEMS_PREEMPT_MASK`` and enables preemption - * - ``RTEMS_NO_PREEMPT`` - - is masked by ``RTEMS_PREEMPT_MASK`` and disables preemption - * - ``RTEMS_NO_TIMESLICE`` - - is masked by ``RTEMS_TIMESLICE_MASK`` and disables timeslicing - * - ``RTEMS_TIMESLICE`` - - is masked by ``RTEMS_TIMESLICE_MASK`` and enables timeslicing - * - ``RTEMS_ASR`` - - is masked by ``RTEMS_ASR_MASK`` and enables ASR processing - * - ``RTEMS_NO_ASR`` - - is masked by ``RTEMS_ASR_MASK`` and disables ASR processing - * - ``RTEMS_INTERRUPT_LEVEL(0)`` - - is masked by ``RTEMS_INTERRUPT_MASK`` and enables all interrupts - * - ``RTEMS_INTERRUPT_LEVEL(n)`` - - is masked by ``RTEMS_INTERRUPT_MASK`` and sets interrupts level n - -.. raw:: latex - - \clearpage - -.. index:: send signal set -.. index:: rtems_signal_send - -.. _rtems_signal_send: - -SIGNAL_SEND - Send signal set to a task ---------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_signal_send( - rtems_id id, - rtems_signal_set signal_set - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - signal sent successfully - * - ``RTEMS_INVALID_ID`` - - task id invalid - * - ``RTEMS_INVALID_NUMBER`` - - empty signal set - * - ``RTEMS_NOT_DEFINED`` - - ASR invalid - -DESCRIPTION: - This directive sends a signal set to the task specified in id. The - signal_set parameter contains the signal set to be sent to the task. - - If a caller sends a signal set to a task with an invalid ASR, then an error - code is returned to the caller. If a caller sends a signal set to a task - whose ASR is valid but disabled, then the signal set will be caught and - left pending for the ASR to process when it is enabled. If a caller sends a - signal set to a task with an ASR that is both valid and enabled, then the - signal set is caught and the ASR will execute the next time the task is - dispatched to run. - -NOTES: - Sending a signal set to a task has no effect on that task's state. If a - signal set is sent to a blocked task, then the task will remain blocked and - the signals will be processed when the task becomes the running task. - - Sending a signal set to a global task which does not reside on the local - node will generate a request telling the remote node to send the signal set - to the specified task. diff --git a/c-user/symmetric_multiprocessing_services.rst b/c-user/symmetric_multiprocessing_services.rst index acfee56..aeecece 100644 --- a/c-user/symmetric_multiprocessing_services.rst +++ b/c-user/symmetric_multiprocessing_services.rst @@ -2,7 +2,7 @@ .. Copyright (C) 2014. .. COMMENT: On-Line Applications Research Corporation (OAR). -.. Copyright (C) 2017 embedded brains GmbH. +.. Copyright (C) 2017 embedded brains GmbH & Co. KG .. index:: Symmetric Multiprocessing .. index:: SMP @@ -13,10 +13,19 @@ Symmetric Multiprocessing (SMP) Introduction ============ -The Symmetric Multiprocessing (SMP) support of the RTEMS is available on +RTEMS Symmetric Multiprocessing (SMP) support is available on a subset +of target architectures supported by RTEMS. Further on some target +architectures, it is only available on a subset of BSPs. The user is +advised to check the BSP specific documentation and RTEMS source code +to verify the status of SMP support for a specific BSP. The following +architectures have support for SMP: + +- AArch64, - ARMv7-A, +- i386, + - PowerPC, - RISC-V, and @@ -25,8 +34,8 @@ The Symmetric Multiprocessing (SMP) support of the RTEMS is available on .. warning:: - The SMP support is only available if RTEMS was built with the - ``--enable-smp`` build configuration option. + SMP support is only available if RTEMS was built with the + SMP build configuration option enabled. RTEMS is supposed to be a real-time operating system. What does this mean in the context of SMP? The RTEMS interpretation of real-time on SMP is the @@ -580,10 +589,10 @@ Profiling --------- To identify the bottlenecks in the system, support for profiling of low-level -synchronization is optionally available. The profiling support is a BSP build -time configuration option (``--enable-profiling``) and is implemented with an -acceptable overhead, even for production systems. A low-overhead counter for -short time intervals must be provided by the hardware. +synchronization is optionally available. The profiling support is +an RTEMS build time configuration option and is implemented with an +acceptable overhead, even for production systems. A low-overhead counter +for short time intervals must be provided by the hardware. Profiling reports are generated in XML for most test programs of the RTEMS testsuite (more than 500 test programs). This gives a good sample set for diff --git a/c-user/task/background.rst b/c-user/task/background.rst new file mode 100644 index 0000000..c7645b1 --- /dev/null +++ b/c-user/task/background.rst @@ -0,0 +1,448 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2022 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Background +========== + +.. index:: task, definition + +Task Definition +--------------- + +Many definitions of a task have been proposed in computer literature. +Unfortunately, none of these definitions encompasses all facets of the concept +in a manner which is operating system independent. Several of the more common +definitions are provided to enable each user to select a definition which best +matches their own experience and understanding of the task concept: + +- a "dispatchable" unit. + +- an entity to which the processor is allocated. + +- an atomic unit of a real-time, multiprocessor system. + +- single threads of execution which concurrently compete for resources. + +- a sequence of closely related computations which can execute concurrently + with other computational sequences. + +From RTEMS' perspective, a task is the smallest thread of execution which can +compete on its own for system resources. A task is manifested by the existence +of a task control block (TCB). + +.. _TaskControlBlock: + +Task Control Block +------------------ + +The Task Control Block (TCB) is an RTEMS defined data structure which contains +all the information that is pertinent to the execution of a task. During +system initialization, RTEMS reserves a TCB for each task configured. A TCB is +allocated upon creation of the task and is returned to the TCB free list upon +deletion of the task. + +The TCB's elements are modified as a result of system calls made by the +application in response to external and internal stimuli. TCBs are the only +RTEMS internal data structure that can be accessed by an application via user +extension routines. The TCB contains a task's name, ID, current priority, +current and starting states, execution mode, TCB user extension pointer, +scheduling control structures, as well as data required by a blocked task. + +A task's context is stored in the TCB when a task switch occurs. When the task +regains control of the processor, its context is restored from the TCB. When a +task is restarted, the initial state of the task is restored from the starting +context area in the task's TCB. + +.. index:: task memory + +Task Memory +----------- + +The system uses two separate memory areas to manage a task. One memory area is +the :ref:`TaskControlBlock`. The other memory area is allocated from the stack +space or provided by the user and contains + +* the task stack, + +* the thread-local storage (:term:`TLS`), and + +* an optional architecture-specific floating-point context. + +The size of the thread-local storage is determined at link time. A +user-provided task stack must take the size of the thread-local storage into +account. + +On architectures with a dedicated floating-point context, the application +configuration assumes that every task is a floating-point task, but whether or +not a task is actually floating-point is determined at runtime during task +creation (see :ref:`TaskFloatingPointConsiderations`). In highly memory +constrained systems this potential overestimate of the task stack space can be +mitigated through the :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE` configuration +option and aligned task stack sizes for the tasks. A user-provided task stack +must take the potential floating-point context into account. + +.. index:: task name + +Task Name +--------- + +By default, the task name is defined by the task object name given to +:ref:`rtems_task_create() <rtems_task_create>`. The task name can be obtained +with the `pthread_getname_np() +<http://man7.org/linux/man-pages/man3/pthread_setname_np.3.html>`_ function. +Optionally, a new task name may be set with the `pthread_setname_np() +<http://man7.org/linux/man-pages/man3/pthread_setname_np.3.html>`_ function. +The maximum size of a task name is defined by the application configuration +option :ref:`CONFIGURE_MAXIMUM_THREAD_NAME_SIZE +<CONFIGURE_MAXIMUM_THREAD_NAME_SIZE>`. + +.. index:: task states + +Task States +----------- + +A task may exist in one of the following five states: + +- *executing* - Currently scheduled to the CPU + +- *ready* - May be scheduled to the CPU + +- *blocked* - Unable to be scheduled to the CPU + +- *dormant* - Created task that is not started + +- *non-existent* - Uncreated or deleted task + +An active task may occupy the executing, ready, blocked or dormant state, +otherwise the task is considered non-existent. One or more tasks may be active +in the system simultaneously. Multiple tasks communicate, synchronize, and +compete for system resources with each other via system calls. The multiple +tasks appear to execute in parallel, but actually each is dispatched to the CPU +for periods of time determined by the RTEMS scheduling algorithm. The +scheduling of a task is based on its current state and priority. + +.. index:: task priority +.. index:: priority, task +.. index:: rtems_task_priority + +.. _TaskPriority: + +Task Priority +------------- + +A task's :term:`priority` determines its importance in relation to the other +tasks executing on the processor set owned by a :term:`scheduler`. Normally, +RTEMS supports 256 levels of priority ranging from 0 to 255. The priority +level 0 represents a special priority reserved for the operating system. The +data type :c:type:`rtems_task_priority` is used to store task priorities. The +maximum priority level depends on the configured scheduler, see +:ref:`CONFIGURE_MAXIMUM_PRIORITY`, :ref:`ConfigurationSchedulersClustered`, and +:ref:`RTEMSAPIClassicScheduler`. + +Tasks of numerically smaller priority values are more important tasks than +tasks of numerically larger priority values. For example, a task at priority +level 5 is of higher privilege than a task at priority level 10. There is no +limit to the number of tasks assigned to the same priority. + +Each task has a priority associated with it at all times. The initial value of +this priority is assigned at task creation time. The priority of a task may be +changed at any subsequent time. + +Priorities are used by the scheduler to determine which ready task will be +allowed to execute. In general, the higher the logical priority of a task, the +more likely it is to receive processor execution time. + +.. index:: task mode +.. index:: rtems_task_mode + +Task Mode +--------- + +A task's execution mode is a combination of the following four components: + +- preemption + +- ASR processing + +- timeslicing + +- interrupt level + +It is used to modify RTEMS' scheduling process and to alter the execution +environment of the task. The data type ``rtems_task_mode`` is used to manage +the task execution mode. + +.. index:: preemption + +The preemption component allows a task to determine when control of the +processor is relinquished. If preemption is disabled (``RTEMS_NO_PREEMPT``), +the task will retain control of the processor as long as it is in the executing +state - even if a higher priority task is made ready. If preemption is enabled +(``RTEMS_PREEMPT``) and a higher priority task is made ready, then the +processor will be taken away from the current task immediately and given to the +higher priority task. + +.. index:: timeslicing + +The timeslicing component is used by the RTEMS scheduler to determine how the +processor is allocated to tasks of equal priority. If timeslicing is enabled +(``RTEMS_TIMESLICE``), then RTEMS will limit the amount of time the task can +execute before the processor is allocated to another ready task of equal +priority. The length of the timeslice is application dependent and specified in +the Configuration Table. If timeslicing is disabled (``RTEMS_NO_TIMESLICE``), +then the task will be allowed to execute until a task of higher priority is +made ready. If ``RTEMS_NO_PREEMPT`` is selected, then the timeslicing component +is ignored by the scheduler. + +The asynchronous signal processing component is used to determine when received +signals are to be processed by the task. If signal processing is enabled +(``RTEMS_ASR``), then signals sent to the task will be processed the next time +the task executes. If signal processing is disabled (``RTEMS_NO_ASR``), then +all signals received by the task will remain posted until signal processing is +enabled. This component affects only tasks which have established a routine to +process asynchronous signals. + +.. index:: interrupt level, task + +The interrupt level component is used to determine which interrupts will be +enabled when the task is executing. ``RTEMS_INTERRUPT_LEVEL(n)`` specifies that +the task will execute at interrupt level n. + +.. list-table:: + :class: rtems-table + + * - ``RTEMS_PREEMPT`` + - enable preemption (default) + * - ``RTEMS_NO_PREEMPT`` + - disable preemption + * - ``RTEMS_NO_TIMESLICE`` + - disable timeslicing (default) + * - ``RTEMS_TIMESLICE`` + - enable timeslicing + * - ``RTEMS_ASR`` + - enable ASR processing (default) + * - ``RTEMS_NO_ASR`` + - disable ASR processing + * - ``RTEMS_INTERRUPT_LEVEL(0)`` + - enable all interrupts (default) + * - ``RTEMS_INTERRUPT_LEVEL(n)`` + - execute at interrupt level n + +The set of default modes may be selected by specifying the +``RTEMS_DEFAULT_MODES`` constant. + +.. index:: task life states + +Task Life States +---------------- + +Independent of the task state with respect to the scheduler, the task life is +determined by several orthogonal states: + +* *protected* or *unprotected* + +* *deferred life changes* or *no deferred life changes* + +* *restarting* or *not restarting* + +* *terminating* or *not terminating* + +* *detached* or *not detached* + +While the task life is *protected*, asynchronous task restart and termination +requests are blocked. A task may still restart or terminate itself. All tasks +are created with an unprotected task life. The task life protection is used by +the system to prevent system resources being affected by asynchronous task +restart and termination requests. The task life protection can be enabled +(``PTHREAD_CANCEL_DISABLE``) or disabled (``PTHREAD_CANCEL_ENABLE``) for the +calling task through the ``pthread_setcancelstate()`` directive. + +While *deferred life changes* are enabled, asynchronous task restart and +termination requests are delayed until the task performs a life change itself +or calls ``pthread_testcancel()``. Cancellation points are not implemented in +RTEMS. Deferred task life changes can be enabled (``PTHREAD_CANCEL_DEFERRED``) +or disabled (``PTHREAD_CANCEL_ASYNCHRONOUS``) for the calling task through the +``pthread_setcanceltype()`` directive. Classic API tasks are created with +deferred life changes disabled. POSIX threads are created with deferred life +changes enabled. + +A task is made *restarting* by issuing a task restart request through the +:ref:`InterfaceRtemsTaskRestart` directive. + +A task is made *terminating* by issuing a task termination request through the +:ref:`InterfaceRtemsTaskExit`, :ref:`InterfaceRtemsTaskDelete`, +``pthread_exit()``, and ``pthread_cancel()`` directives. + +When a *detached* task terminates, the termination procedure completes without +the need for another task to join with the terminated task. Classic API tasks +are created as not detached. The detached state of created POSIX threads is +determined by the thread attributes. They are created as not detached by +default. The calling task is made detached through the ``pthread_detach()`` +directive. The :ref:`InterfaceRtemsTaskExit` directive and self deletion +though :ref:`InterfaceRtemsTaskDelete` directive make the calling task +detached. In contrast, the ``pthread_exit()`` directive does not change the +detached state of the calling task. + +.. index:: task arguments +.. index:: task prototype + +Accessing Task Arguments +------------------------ + +All RTEMS tasks are invoked with a single argument which is specified when they +are started or restarted. The argument is commonly used to communicate startup +information to the task. The simplest manner in which to define a task which +accesses it argument is: + +.. index:: rtems_task + +.. code-block:: c + + rtems_task user_task( + rtems_task_argument argument + ); + +Application tasks requiring more information may view this single argument as +an index into an array of parameter blocks. + +.. index:: floating point + +.. _TaskFloatingPointConsiderations: + +Floating Point Considerations +----------------------------- + +Please consult the *RTEMS CPU Architecture Supplement* if this section is +relevant on your architecture. On some architectures the floating-point context +is contained in the normal task context and this section does not apply. + +Creating a task with the ``RTEMS_FLOATING_POINT`` attribute flag results in +additional memory being allocated for the task to store the state of the numeric +coprocessor during task switches. This additional memory is **not** allocated +for ``RTEMS_NO_FLOATING_POINT`` tasks. Saving and restoring the context of a +``RTEMS_FLOATING_POINT`` task takes longer than that of a +``RTEMS_NO_FLOATING_POINT`` task because of the relatively large amount of time +required for the numeric coprocessor to save or restore its computational state. + +Since RTEMS was designed specifically for embedded military applications which +are floating point intensive, the executive is optimized to avoid unnecessarily +saving and restoring the state of the numeric coprocessor. In uniprocessor +configurations, the state of the numeric coprocessor is only saved when a +``RTEMS_FLOATING_POINT`` task is dispatched and that task was not the last task +to utilize the coprocessor. In a uniprocessor system with only one +``RTEMS_FLOATING_POINT`` task, the state of the numeric coprocessor will never +be saved or restored. + +Although the overhead imposed by ``RTEMS_FLOATING_POINT`` tasks is minimal, +some applications may wish to completely avoid the overhead associated with +``RTEMS_FLOATING_POINT`` tasks and still utilize a numeric coprocessor. By +preventing a task from being preempted while performing a sequence of floating +point operations, a ``RTEMS_NO_FLOATING_POINT`` task can utilize the numeric +coprocessor without incurring the overhead of a ``RTEMS_FLOATING_POINT`` +context switch. This approach also avoids the allocation of a floating point +context area. However, if this approach is taken by the application designer, +**no** tasks should be created as ``RTEMS_FLOATING_POINT`` tasks. Otherwise, the +floating point context will not be correctly maintained because RTEMS assumes +that the state of the numeric coprocessor will not be altered by +``RTEMS_NO_FLOATING_POINT`` tasks. Some architectures with a dedicated +floating-point context raise a processor exception if a task with +``RTEMS_NO_FLOATING_POINT`` issues a floating-point instruction, so this +approach may not work at all. + +If the supported processor type does not have hardware floating capabilities or +a standard numeric coprocessor, RTEMS will not provide built-in support for +hardware floating point on that processor. In this case, all tasks are +considered ``RTEMS_NO_FLOATING_POINT`` whether created as +``RTEMS_FLOATING_POINT`` or ``RTEMS_NO_FLOATING_POINT`` tasks. A floating +point emulation software library must be utilized for floating point +operations. + +On some processors, it is possible to disable the floating point unit +dynamically. If this capability is supported by the target processor, then +RTEMS will utilize this capability to enable the floating point unit only for +tasks which are created with the ``RTEMS_FLOATING_POINT`` attribute. The +consequence of a ``RTEMS_NO_FLOATING_POINT`` task attempting to access the +floating point unit is CPU dependent but will generally result in an exception +condition. + +.. index:: task attributes, building + +Building a Task Attribute Set +----------------------------- + +In general, an attribute set is built by a bitwise OR of the desired +components. The set of valid task attribute components is listed below: + +.. list-table:: + :class: rtems-table + + * - ``RTEMS_NO_FLOATING_POINT`` + - does not use coprocessor (default) + * - ``RTEMS_FLOATING_POINT`` + - uses numeric coprocessor + * - ``RTEMS_LOCAL`` + - local task (default) + * - ``RTEMS_GLOBAL`` + - global task + +Attribute values are specifically designed to be mutually exclusive, therefore +bitwise OR and addition operations are equivalent as long as each attribute +appears exactly once in the component list. A component listed as a default is +not required to appear in the component list, although it is a good programming +practice to specify default components. If all defaults are desired, then +``RTEMS_DEFAULT_ATTRIBUTES`` should be used. + +This example demonstrates the attribute_set parameter needed to create a local +task which utilizes the numeric coprocessor. The attribute_set parameter could +be ``RTEMS_FLOATING_POINT`` or ``RTEMS_LOCAL | RTEMS_FLOATING_POINT``. The +attribute_set parameter can be set to ``RTEMS_FLOATING_POINT`` because +``RTEMS_LOCAL`` is the default for all created tasks. If the task were global +and used the numeric coprocessor, then the attribute_set parameter would be +``RTEMS_GLOBAL | RTEMS_FLOATING_POINT``. + +.. index:: task mode, building + +Building a Mode and Mask +------------------------ + +In general, a mode and its corresponding mask is built by a bitwise OR of the +desired components. The set of valid mode constants and each mode's +corresponding mask constant is listed below: + +.. list-table:: + :class: rtems-table + + * - ``RTEMS_PREEMPT`` + - is masked by ``RTEMS_PREEMPT_MASK`` and enables preemption + * - ``RTEMS_NO_PREEMPT`` + - is masked by ``RTEMS_PREEMPT_MASK`` and disables preemption + * - ``RTEMS_NO_TIMESLICE`` + - is masked by ``RTEMS_TIMESLICE_MASK`` and disables timeslicing + * - ``RTEMS_TIMESLICE`` + - is masked by ``RTEMS_TIMESLICE_MASK`` and enables timeslicing + * - ``RTEMS_ASR`` + - is masked by ``RTEMS_ASR_MASK`` and enables ASR processing + * - ``RTEMS_NO_ASR`` + - is masked by ``RTEMS_ASR_MASK`` and disables ASR processing + * - ``RTEMS_INTERRUPT_LEVEL(0)`` + - is masked by ``RTEMS_INTERRUPT_MASK`` and enables all interrupts + * - ``RTEMS_INTERRUPT_LEVEL(n)`` + - is masked by ``RTEMS_INTERRUPT_MASK`` and sets interrupts level n + +Mode values are specifically designed to be mutually exclusive, therefore +bitwise OR and addition operations are equivalent as long as each mode appears +exactly once in the component list. A mode component listed as a default is +not required to appear in the mode component list, although it is a good +programming practice to specify default components. If all defaults are +desired, the mode ``RTEMS_DEFAULT_MODES`` and the mask ``RTEMS_ALL_MODE_MASKS`` +should be used. + +The following example demonstrates the mode and mask parameters used with the +``rtems_task_mode`` directive to place a task at interrupt level 3 and make it +non-preemptible. The mode should be set to ``RTEMS_INTERRUPT_LEVEL(3) | +RTEMS_NO_PREEMPT`` to indicate the desired preemption mode and interrupt level, +while the mask parameter should be set to ``RTEMS_INTERRUPT_MASK | +RTEMS_NO_PREEMPT_MASK`` to indicate that the calling task's interrupt level and +preemption mode are being altered. diff --git a/c-user/task/deprecated-directives.rst b/c-user/task/deprecated-directives.rst new file mode 100644 index 0000000..949d499 --- /dev/null +++ b/c-user/task/deprecated-directives.rst @@ -0,0 +1,46 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Deprecated Directives +===================== + +.. raw:: latex + + \clearpage + +.. index:: rtems_iterate_over_all_threads() + +.. _rtems_iterate_over_all_threads: + +ITERATE_OVER_ALL_THREADS - Iterate Over Tasks +--------------------------------------------- + +.. warning:: + + This directive is deprecated. Its use is unsafe. Use + :ref:`rtems_task_iterate` instead. + +CALLING SEQUENCE: + .. code-block:: c + + typedef void (*rtems_per_thread_routine)(Thread_Control *the_thread); + void rtems_iterate_over_all_threads( + rtems_per_thread_routine routine + ); + +DIRECTIVE STATUS CODES: + NONE + +DESCRIPTION: + This directive iterates over all of the existant threads in the system and + invokes ``routine`` on each of them. The user should be careful in + accessing the contents of ``the_thread``. + + This routine is intended for use in diagnostic utilities and is not + intented for routine use in an operational system. + +NOTES: + There is **no protection** while this routine is called. The thread + control block may be in an inconsistent state or may change due to + interrupts or activity on other processors. diff --git a/c-user/task/directives.rst b/c-user/task/directives.rst new file mode 100644 index 0000000..d976905 --- /dev/null +++ b/c-user/task/directives.rst @@ -0,0 +1,2014 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2023 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. _TaskManagerDirectives: + +Directives +========== + +This section details the directives of the Task Manager. A subsection is +dedicated to each of this manager's directives and lists the calling sequence, +parameters, description, return values, and notes of the directive. + +.. Generated from spec:/rtems/task/if/create + +.. raw:: latex + + \clearpage + +.. index:: rtems_task_create() +.. index:: create a task + +.. _InterfaceRtemsTaskCreate: + +rtems_task_create() +------------------- + +Creates a task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_create( + rtems_name name, + rtems_task_priority initial_priority, + size_t stack_size, + rtems_mode initial_modes, + rtems_attribute attribute_set, + rtems_id *id + ); + +.. rubric:: PARAMETERS: + +``name`` + This parameter is the object name of the task. + +``initial_priority`` + This parameter is the initial task priority. + +``stack_size`` + This parameter is the task stack size in bytes. + +``initial_modes`` + This parameter is the initial mode set of the task. + +``attribute_set`` + This parameter is the attribute set of the task. + +``id`` + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the identifier of the created task will + be stored in this object. + +.. rubric:: DESCRIPTION: + +This directive creates a task which resides on the local node. The task has +the user-defined object name specified in ``name``. The assigned object +identifier is returned in ``id``. This identifier is used to access the task +with other task related directives. + +The **initial priority** of the task is specified in ``initial_priority``. The +:term:`home scheduler` of the created task is the home scheduler of the calling +task at some time point during the task creation. The initial task priority +specified in ``initial_priority`` shall be valid for this scheduler. + +The **stack size** of the task is specified in ``stack_size``. If the +requested stack size is less than the configured minimum stack size, then RTEMS +will use the configured minimum as the stack size for this task. The +configured minimum stack size is defined by the +:ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE` application configuration option. In +addition to being able to specify the task stack size as a integer, there are +two constants which may be specified: + +* The :c:macro:`RTEMS_MINIMUM_STACK_SIZE` constant can be specified to use the + **recommended minimum stack size** for the target processor. This value is + selected by the RTEMS maintainers conservatively to minimize the risk of + blown stacks for most user applications. Using this constant when specifying + the task stack size, indicates that the stack size will be at least + :c:macro:`RTEMS_MINIMUM_STACK_SIZE` bytes in size. If the user configured + minimum stack size is larger than the recommended minimum, then it will be + used. + +* The :c:macro:`RTEMS_CONFIGURED_MINIMUM_STACK_SIZE` constant can be specified + to use the minimum stack size that was configured by the application. If not + explicitly configured by the application, the default configured minimum + stack size is the target processor dependent value + :c:macro:`RTEMS_MINIMUM_STACK_SIZE`. Since this uses the configured minimum + stack size value, you may get a stack size that is smaller or larger than the + recommended minimum. This can be used to provide large stacks for all tasks + on complex applications or small stacks on applications that are trying to + conserve memory. + +The **initial mode set** specified in ``initial_modes`` is built through a +*bitwise or* of the mode constants described below. Not all combinations of +modes are allowed. Some modes are mutually exclusive. If mutually exclusive +modes are combined, the behaviour is undefined. Default task modes can be +selected by using the :c:macro:`RTEMS_DEFAULT_MODES` constant. The task mode +set defines + +* the preemption mode of the task: :c:macro:`RTEMS_PREEMPT` (default) or + :c:macro:`RTEMS_NO_PREEMPT`, + +* the timeslicing mode of the task: :c:macro:`RTEMS_TIMESLICE` or + :c:macro:`RTEMS_NO_TIMESLICE` (default), + +* the :term:`ASR` processing mode of the task: :c:macro:`RTEMS_ASR` (default) + or :c:macro:`RTEMS_NO_ASR`, + +* the interrupt level of the task: :c:func:`RTEMS_INTERRUPT_LEVEL` with a + default of ``RTEMS_INTERRUPT_LEVEL( 0 )`` which is associated with enabled + interrupts. + +The **initial preemption mode** of the task is enabled or disabled. + +* An **enabled preemption** is the default and can be emphasized through the + use of the :c:macro:`RTEMS_PREEMPT` mode constant. + +* A **disabled preemption** is set by the :c:macro:`RTEMS_NO_PREEMPT` mode + constant. + +The **initial timeslicing mode** of the task is enabled or disabled. + +* A **disabled timeslicing** is the default and can be emphasized through the + use of the :c:macro:`RTEMS_NO_TIMESLICE` mode constant. + +* An **enabled timeslicing** is set by the :c:macro:`RTEMS_TIMESLICE` mode + constant. + +The **initial ASR processing mode** of the task is enabled or disabled. + +* An **enabled ASR processing** is the default and can be emphasized through + the use of the :c:macro:`RTEMS_ASR` mode constant. + +* A **disabled ASR processing** is set by the :c:macro:`RTEMS_NO_ASR` mode + constant. + +The **initial interrupt level mode** of the task is defined by +:c:func:`RTEMS_INTERRUPT_LEVEL`. + +* Task execution with **interrupts enabled** the default and can be emphasized + through the use of the :c:func:`RTEMS_INTERRUPT_LEVEL` mode macro with a + value of zero (0) for the parameter. An interrupt level of zero is + associated with enabled interrupts on all target processors. + +* Task execution at a **non-zero interrupt level** can be specified by the + :c:func:`RTEMS_INTERRUPT_LEVEL` mode macro with a non-zero value for the + parameter. The interrupt level portion of the task mode supports a maximum + of 256 interrupt levels. These levels are mapped onto the interrupt levels + actually supported by the target processor in a processor dependent fashion. + +The **attribute set** specified in ``attribute_set`` is built through a +*bitwise or* of the attribute constants described below. Not all combinations +of attributes are allowed. Some attributes are mutually exclusive. If +mutually exclusive attributes are combined, the behaviour is undefined. +Attributes not mentioned below are not evaluated by this directive and have no +effect. Default attributes can be selected by using the +:c:macro:`RTEMS_DEFAULT_ATTRIBUTES` constant. The attribute set defines + +* the scope of the task: :c:macro:`RTEMS_LOCAL` (default) or + :c:macro:`RTEMS_GLOBAL` and + +* the floating-point unit use of the task: :c:macro:`RTEMS_FLOATING_POINT` or + :c:macro:`RTEMS_NO_FLOATING_POINT` (default). + +The task has a local or global **scope** in a multiprocessing network (this +attribute does not refer to SMP systems). The scope is selected by the +mutually exclusive :c:macro:`RTEMS_LOCAL` and :c:macro:`RTEMS_GLOBAL` +attributes. + +* A **local scope** is the default and can be emphasized through the use of the + :c:macro:`RTEMS_LOCAL` attribute. A local task can be only used by the node + which created it. + +* A **global scope** is established if the :c:macro:`RTEMS_GLOBAL` attribute is + set. Setting the global attribute in a single node system has no effect.the + +The **use of the floating-point unit** is selected by the mutually exclusive +:c:macro:`RTEMS_FLOATING_POINT` and :c:macro:`RTEMS_NO_FLOATING_POINT` +attributes. On some target processors, the use of the floating-point unit can +be enabled or disabled for each task. Other target processors may have no +hardware floating-point unit or enable the use of the floating-point unit for +all tasks. Consult the *RTEMS CPU Architecture Supplement* for the details. + +* A **disabled floating-point unit** is the default and can be emphasized + through use of the :c:macro:`RTEMS_NO_FLOATING_POINT` attribute. For + performance reasons, it is recommended that tasks not using the + floating-point unit should specify this attribute. + +* An **enabled floating-point unit** is selected by the + :c:macro:`RTEMS_FLOATING_POINT` attribute. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_NAME` + The ``name`` parameter was invalid. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``id`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_PRIORITY` + The ``initial_priority`` was invalid. + +:c:macro:`RTEMS_TOO_MANY` + There was no inactive object available to create a task. The number of + tasks available to the application is configured through the + :ref:`CONFIGURE_MAXIMUM_TASKS` application configuration option. + +:c:macro:`RTEMS_TOO_MANY` + In multiprocessing configurations, there was no inactive global object + available to create a global task. The number of global objects available + to the application is configured through the + :ref:`CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS` application configuration + option. + +:c:macro:`RTEMS_UNSATISFIED` + There was not enough memory to allocate the task storage area. The task + storage area contains the task stack, the thread-local storage, and the + floating point context. + +:c:macro:`RTEMS_UNSATISFIED` + One of the task create extensions failed to create the task. + +:c:macro:`RTEMS_UNSATISFIED` + In SMP configurations, the non-preemption mode was not supported. + +:c:macro:`RTEMS_UNSATISFIED` + In SMP configurations, the interrupt level mode was not supported. + +.. rubric:: NOTES: + +The task processor affinity is initialized to the set of online processors. + +When created, a task is placed in the dormant state and can only be made ready +to execute using the directive :ref:`InterfaceRtemsTaskStart`. + +Application developers should consider the stack usage of the device drivers +when calculating the stack size required for tasks which utilize the driver. +The task stack size shall account for an target processor dependent interrupt +stack frame which may be placed on the stack of the interrupted task while +servicing an interrupt. The stack checker may be used to monitor the stack +usage, see :ref:`CONFIGURE_STACK_CHECKER_ENABLED`. + +For control and maintenance of the task, RTEMS allocates a :term:`TCB` from the +local TCB free pool and initializes it. + +The TCB for a global task is allocated on the local node. Task should not be +made global unless remote tasks must interact with the task. This is to avoid +the system overhead incurred by the creation of a global task. When a global +task is created, the task's name and identifier must be transmitted to every +node in the system for insertion in the local copy of the global object table. + +.. 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. + +* When the directive operates on a global object, the directive sends a message + to remote nodes. This may preempt the calling task. + +* The number of tasks available to the application is configured through the + :ref:`CONFIGURE_MAXIMUM_TASKS` application configuration option. + +* Where the object class corresponding to the directive is configured to use + unlimited objects, the directive may allocate memory from the RTEMS + Workspace. + +* The number of global objects available to the application is configured + through the :ref:`CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS` application + configuration option. + +.. Generated from spec:/rtems/task/if/construct + +.. raw:: latex + + \clearpage + +.. index:: rtems_task_construct() + +.. _InterfaceRtemsTaskConstruct: + +rtems_task_construct() +---------------------- + +Constructs a task from the specified task configuration. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_construct( + const rtems_task_config *config, + rtems_id *id + ); + +.. rubric:: PARAMETERS: + +``config`` + This parameter is the pointer to an :ref:`InterfaceRtemsTaskConfig` object. + It configures the task. + +``id`` + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the identifier of the constructed task + will be stored in this object. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``config`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_NAME` + The task name was invalid. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``id`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_PRIORITY` + The initial task priority was invalid. + +:c:macro:`RTEMS_INVALID_SIZE` + The thread-local storage size is greater than the maximum thread-local + storage size specified in the task configuration. The thread-local storage + size is determined by the thread-local variables used by the application + and :ref:`CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE`. + +:c:macro:`RTEMS_INVALID_SIZE` + The task storage area was too small to provide a task stack of the + configured minimum size, see :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. The + task storage area contains the task stack, the thread-local storage, and + the floating-point context on architectures with a separate floating-point + context. + +:c:macro:`RTEMS_TOO_MANY` + There was no inactive task object available to construct a task. + +:c:macro:`RTEMS_TOO_MANY` + In multiprocessing configurations, there was no inactive global object + available to construct a global task. + +:c:macro:`RTEMS_UNSATISFIED` + One of the task create extensions failed during the task construction. + +:c:macro:`RTEMS_UNSATISFIED` + In SMP configurations, the non-preemption mode was not supported. + +:c:macro:`RTEMS_UNSATISFIED` + In SMP configurations, the interrupt level mode was not supported. + +.. rubric:: NOTES: + +In contrast to tasks created by :ref:`InterfaceRtemsTaskCreate`, the tasks +constructed by this directive use a user-provided task storage area. The task +storage area contains the task stack, the thread-local storage, and the +floating-point context on architectures with a separate floating-point context. + +This directive is intended for applications which do not want to use the RTEMS +Workspace and instead statically allocate all operating system resources. It +is not recommended to use :ref:`InterfaceRtemsTaskCreate` and +:ref:`InterfaceRtemsTaskConstruct` together in an application. It is also not +recommended to use :ref:`InterfaceRtemsTaskConstruct` for drivers or general +purpose libraries. The reason for these recommendations is that the task +configuration needs settings which can be only given with a through knowledge +of the application resources. + +An application based solely on static allocation can avoid any runtime memory +allocators. This can simplify the application architecture as well as any +analysis that may be required. + +The stack space estimate done by ``<rtems/confdefs.h>`` assumes that all tasks +are created by :ref:`InterfaceRtemsTaskCreate`. The estimate can be adjusted +to take user-provided task storage areas into account through the +:ref:`CONFIGURE_MINIMUM_TASKS_WITH_USER_PROVIDED_STORAGE` application +configuration option. + +The :ref:`CONFIGURE_MAXIMUM_TASKS` should include tasks constructed by +:ref:`InterfaceRtemsTaskConstruct`. + +.. 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. + +* When the directive operates on a global object, the directive sends a message + to remote nodes. This may preempt the calling task. + +* The number of tasks available to the application is configured through the + :ref:`CONFIGURE_MAXIMUM_TASKS` application configuration option. + +* Where the object class corresponding to the directive is configured to use + unlimited objects, the directive may allocate memory from the RTEMS + Workspace. + +* The number of global objects available to the application is configured + through the :ref:`CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS` application + configuration option. + +.. Generated from spec:/rtems/task/if/ident + +.. raw:: latex + + \clearpage + +.. index:: rtems_task_ident() + +.. _InterfaceRtemsTaskIdent: + +rtems_task_ident() +------------------ + +Identifies a task by the object name. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_ident( + rtems_name name, + uint32_t node, + rtems_id *id + ); + +.. rubric:: PARAMETERS: + +``name`` + This parameter is the object name to look up. + +``node`` + This parameter is the node or node set to search for a matching object. + +``id`` + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the object identifier of an object with + the specified name will be stored in this object. + +.. rubric:: DESCRIPTION: + +This directive obtains a task identifier associated with the task name +specified in ``name``. + +A task may obtain its own identifier by specifying :c:macro:`RTEMS_WHO_AM_I` +for the name. + +The node to search is specified in ``node``. It shall be + +* a valid node number, + +* the constant :c:macro:`RTEMS_SEARCH_ALL_NODES` to search in all nodes, + +* the constant :c:macro:`RTEMS_SEARCH_LOCAL_NODE` to search in the local node + only, or + +* the constant :c:macro:`RTEMS_SEARCH_OTHER_NODES` to search in all nodes + except the local node. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``id`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_NAME` + There was no object with the specified name on the specified nodes. + +:c:macro:`RTEMS_INVALID_NODE` + In multiprocessing configurations, the specified node was invalid. + +.. rubric:: NOTES: + +If the task name is not unique, then the task identifier will match the first +task with that name in the search order. However, this task identifier is not +guaranteed to correspond to the desired task. + +The objects are searched from lowest to the highest index. If ``node`` is +:c:macro:`RTEMS_SEARCH_ALL_NODES`, all nodes are searched with the local node +being searched first. All other nodes are searched from lowest to the highest +node number. + +If node is a valid node number which does not represent the local node, then +only the tasks exported by the designated node are searched. + +This directive does not generate activity on remote nodes. It accesses only +the local copy of the global object table. + +The task identifier is used with other task related directives to access the +task. + +.. 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/task/if/self + +.. raw:: latex + + \clearpage + +.. index:: rtems_task_self() +.. index:: obtain ID of caller + +.. _InterfaceRtemsTaskSelf: + +rtems_task_self() +----------------- + +Gets the task identifier of the calling task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_id rtems_task_self( void ); + +.. rubric:: DESCRIPTION: + +This directive returns the task identifier of the calling task. + +.. rubric:: RETURN VALUES: + +Returns the task identifier of the calling task. + +.. 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 will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/task/if/start + +.. raw:: latex + + \clearpage + +.. index:: rtems_task_start() +.. index:: starting a task + +.. _InterfaceRtemsTaskStart: + +rtems_task_start() +------------------ + +Starts the task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_start( + rtems_id id, + rtems_task_entry entry_point, + rtems_task_argument argument + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF` + may be used to specify the calling task. + +``entry_point`` + This parameter is the task entry point. + +``argument`` + This parameter is the task entry point argument. + +.. rubric:: DESCRIPTION: + +This directive readies the task, specified by ``id``, for execution based on +the priority and execution mode specified when the task was created. The +:term:`task entry` point of the task is given in ``entry_point``. The task's +entry point argument is contained in ``argument``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``entry_point`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_INCORRECT_STATE` + The task was not in the dormant state. + +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT` + The task resided on a remote node. + +.. rubric:: NOTES: + +The type of the entry point argument is an unsigned integer type. However, the +integer type has the property that any valid pointer to ``void`` can be +converted to this type and then converted back to a pointer to ``void``. The +result will compare equal to the original pointer. The type can represent at +least 32 bits. Some applications use the entry point argument as an index into +a parameter table to get task-specific parameters. + +Any actions performed on a dormant task such as suspension or change of +priority are nullified when the task is initiated via the +:ref:`InterfaceRtemsTaskStart` directive. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may unblock a task. This may cause the calling task to be + preempted. + +.. Generated from spec:/rtems/task/if/restart + +.. raw:: latex + + \clearpage + +.. index:: rtems_task_restart() +.. index:: restarting a task + +.. _InterfaceRtemsTaskRestart: + +rtems_task_restart() +-------------------- + +Restarts the task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_restart( + rtems_id id, + rtems_task_argument argument + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF` + may be used to specify the calling task. + +``argument`` + This parameter is the task entry point argument. + +.. rubric:: DESCRIPTION: + +This directive resets the task specified by ``id`` to begin execution at its +original entry point. The task's priority and execution mode are set to the +original creation values. If the task is currently blocked, RTEMS +automatically makes the task ready. A task can be restarted from any state, +except the dormant state. The task's entry point argument is contained in +``argument``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_INCORRECT_STATE` + The task never started. + +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT` + The task resided on a remote node. + +.. rubric:: NOTES: + +The type of the entry point argument is an unsigned integer type. However, the +integer type has the property that any valid pointer to ``void`` can be +converted to this type and then converted back to a pointer to ``void``. The +result will compare equal to the original pointer. The type can represent at +least 32 bits. Some applications use the entry point argument as an index into +a parameter table to get task-specific parameters. + +A new entry point argument may be used to distinguish between the initial +:ref:`InterfaceRtemsTaskStart` of the task and any ensuing calls to +:ref:`InterfaceRtemsTaskRestart` of the task. This can be beneficial in +deleting a task. Instead of deleting a task using the +:ref:`InterfaceRtemsTaskDelete` directive, a task can delete another task by +restarting that task, and allowing that task to release resources back to RTEMS +and then delete itself. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may change the priority of a task. This may cause the calling + task to be preempted. + +* The directive may unblock a task. This may cause the calling task to be + preempted. + +.. Generated from spec:/rtems/task/if/delete + +.. raw:: latex + + \clearpage + +.. index:: rtems_task_delete() +.. index:: delete a task + +.. _InterfaceRtemsTaskDelete: + +rtems_task_delete() +------------------- + +Deletes the task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_delete( rtems_id id ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF` + may be used to specify the calling task. + +.. rubric:: DESCRIPTION: + +This directive deletes the task, either the calling task or another task, as +specified by ``id``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_CALLED_FROM_ISR` + The directive was called from within interrupt context. + +:c:macro:`RTEMS_INCORRECT_STATE` + The task termination procedure was started, however, waiting for the + terminating task would have resulted in a deadlock. + +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT` + The task resided on a remote node. + +.. rubric:: NOTES: + +The task deletion is done in several steps. Firstly, the task is marked as +terminating. While the task life of the terminating task is protected, it +executes normally until it disables the task life protection or it deletes +itself. A terminating task will eventually stop its normal execution and start +its termination procedure. The procedure executes in the context of the +terminating task. The task termination procedure involves the destruction of +POSIX key values and running the task termination user extensions. Once +complete the execution of the task is stopped and task-specific resources are +reclaimed by the system, such as the stack memory, any allocated delay or +timeout timers, the :term:`TCB`, and, if the task is +:c:macro:`RTEMS_FLOATING_POINT`, its floating point context area. RTEMS +explicitly does not reclaim the following resources: region segments, partition +buffers, semaphores, timers, or rate monotonic periods. + +A task is responsible for releasing its resources back to RTEMS before +deletion. To insure proper deallocation of resources, a task should not be +deleted unless it is unable to execute or does not hold any RTEMS resources. If +a task holds RTEMS resources, the task should be allowed to deallocate its +resources before deletion. A task can be directed to release its resources and +delete itself by restarting it with a special argument or by sending it a +message, an event, or a signal. + +Deletion of the calling task (:c:macro:`RTEMS_SELF`) will force RTEMS to select +another task to execute. + +When a task deletes another task, the calling task waits until the task +termination procedure of the task being deleted has completed. The terminating +task inherits the :term:`eligible priorities <eligible priority>` of the +calling task. + +When a global task is deleted, the task identifier must be transmitted to every +node in the system for deletion from the local copy of the global object table. + +The task must reside on the local node, even if the task was created with the +:c:macro:`RTEMS_GLOBAL` attribute. + +.. 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. + +* When the directive operates on a global object, the directive sends a message + to remote nodes. This may preempt the calling task. + +* The calling task does not have to be the task that created the object. Any + local task that knows the object identifier can delete the object. + +* Where the object class corresponding to the directive is configured to use + unlimited objects, the directive may free memory to the RTEMS Workspace. + +.. Generated from spec:/rtems/task/if/exit + +.. raw:: latex + + \clearpage + +.. index:: rtems_task_exit() +.. index:: deleting a task + +.. _InterfaceRtemsTaskExit: + +rtems_task_exit() +----------------- + +Deletes the calling task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_task_exit( void ); + +.. rubric:: DESCRIPTION: + +This directive deletes the calling task. + +.. rubric:: NOTES: + +The directive is an optimized variant of the following code sequences, see also +:ref:`InterfaceRtemsTaskDelete`: + +.. code-block:: c + + #include <pthread.h> + #include <rtems.h> + + void classic_delete_self( void ) + { + (void) rtems_task_delete( RTEMS_SELF ); + } + + void posix_delete_self( void ) + { + (void) pthread_detach( pthread_self() ); + (void) pthread_exit( NULL); + } + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within task context. + +* The directive will not return to the caller. + +* While thread dispatching is disabled, if the directive performs a thread + dispatch, then the fatal error with the fatal source + :ref:`INTERNAL_ERROR_CORE <FatalErrorSources>` and the fatal code + :ref:`INTERNAL_ERROR_BAD_THREAD_DISPATCH_DISABLE_LEVEL <internal_errors>` + will occur. + +.. Generated from spec:/rtems/task/if/suspend + +.. raw:: latex + + \clearpage + +.. index:: rtems_task_suspend() +.. index:: suspending a task + +.. _InterfaceRtemsTaskSuspend: + +rtems_task_suspend() +-------------------- + +Suspends the task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_suspend( rtems_id id ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF` + may be used to specify the calling task. + +.. rubric:: DESCRIPTION: + +This directive suspends the task specified by ``id`` from further execution by +placing it in the suspended state. This state is additive to any other blocked +state that the task may already be in. The task will not execute again until +another task issues the :ref:`InterfaceRtemsTaskResume` directive for this task +and any blocked state has been removed. The :ref:`InterfaceRtemsTaskRestart` +directive will also remove the suspended state. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_ALREADY_SUSPENDED` + The task was already suspended. + +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT` + The task resided on a remote node. + +.. rubric:: NOTES: + +The requesting task can suspend itself for example by specifying +:c:macro:`RTEMS_SELF` as ``id``. In this case, the task will be suspended and +a successful return code will be returned when the task is resumed. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* When the directive operates on a remote object, the directive sends a message + to the remote node and waits for a reply. This will preempt the calling + task. + +.. Generated from spec:/rtems/task/if/resume + +.. raw:: latex + + \clearpage + +.. index:: rtems_task_resume() +.. index:: resuming a task + +.. _InterfaceRtemsTaskResume: + +rtems_task_resume() +------------------- + +Resumes the task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_resume( rtems_id id ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the task identifier. + +.. rubric:: DESCRIPTION: + +This directive removes the task specified by ``id`` from the suspended state. +If the task is in the ready state after the suspension is removed, then it will +be scheduled to run. If the task is still in a blocked state after the +suspension is removed, then it will remain in that blocked state. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_INCORRECT_STATE` + The task was not suspended. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may unblock a task. This may cause the calling task to be + preempted. + +* When the directive operates on a remote object, the directive sends a message + to the remote node and waits for a reply. This will preempt the calling + task. + +.. Generated from spec:/rtems/task/if/is-suspended + +.. raw:: latex + + \clearpage + +.. index:: rtems_task_is_suspended() + +.. _InterfaceRtemsTaskIsSuspended: + +rtems_task_is_suspended() +------------------------- + +Checks if the task is suspended. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_is_suspended( rtems_id id ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF` + may be used to specify the calling task. + +.. rubric:: DESCRIPTION: + +This directive returns a status code indicating whether or not the task +specified by ``id`` is currently suspended. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The task was **not** suspended. + +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_ALREADY_SUSPENDED` + The task was suspended. + +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT` + The task resided on a remote node. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/task/if/set-priority + +.. raw:: latex + + \clearpage + +.. index:: rtems_task_set_priority() +.. index:: current task priority +.. index:: set task priority +.. index:: get task priority +.. index:: obtain task priority + +.. _InterfaceRtemsTaskSetPriority: + +rtems_task_set_priority() +------------------------- + +Sets the real priority or gets the current priority of the task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_set_priority( + rtems_id id, + rtems_task_priority new_priority, + rtems_task_priority *old_priority + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF` + may be used to specify the calling task. + +``new_priority`` + This parameter is the new real priority or + :c:macro:`RTEMS_CURRENT_PRIORITY` to get the current priority. + +``old_priority`` + This parameter is the pointer to an :ref:`InterfaceRtemsTaskPriority` + object. When the directive call is successful, the current or previous + priority of the task with respect to its :term:`home scheduler` will be + stored in this object. + +.. rubric:: DESCRIPTION: + +This directive manipulates the priority of the task specified by ``id``. When +``new_priority`` is not equal to :c:macro:`RTEMS_CURRENT_PRIORITY`, the +specified task's previous priority is returned in ``old_priority``. When +``new_priority`` is :c:macro:`RTEMS_CURRENT_PRIORITY`, the specified task's +current priority is returned in ``old_priority``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``old_priority`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_INVALID_PRIORITY` + The task priority specified in ``new_priority`` was invalid with respect to + the :term:`home scheduler` of the task. + +.. rubric:: NOTES: + +Valid priorities range from one to a maximum value which depends on the +configured scheduler. The lower the priority value the higher is the +importance of the task. + +If the task is currently holding any binary semaphores which use a locking +protocol, then the task's priority cannot be lowered immediately. If the +task's priority were lowered immediately, then this could violate properties of +the locking protocol and may result in priority inversion. The requested +lowering of the task's priority will occur when the task has released all +binary semaphores which make the task more important. The task's priority can +be increased regardless of the task's use of binary semaphores with locking +protocols. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may change the priority of a task. This may cause the calling + task to be preempted. + +* When the directive operates on a remote object, the directive sends a message + to the remote node and waits for a reply. This will preempt the calling + task. + +.. Generated from spec:/rtems/task/if/get-priority + +.. raw:: latex + + \clearpage + +.. index:: rtems_task_get_priority() +.. index:: current task priority +.. index:: get task priority +.. index:: obtain task priority + +.. _InterfaceRtemsTaskGetPriority: + +rtems_task_get_priority() +------------------------- + +Gets the current priority of the task with respect to the scheduler. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_get_priority( + rtems_id task_id, + rtems_id scheduler_id, + rtems_task_priority *priority + ); + +.. rubric:: PARAMETERS: + +``task_id`` + This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF` + may be used to specify the calling task. + +``scheduler_id`` + This parameter is the scheduler identifier. + +``priority`` + This parameter is the pointer to an :ref:`InterfaceRtemsTaskPriority` + object. When the directive call is successful, the current priority of the + task with respect to the specified scheduler will be stored in this object. + +.. rubric:: DESCRIPTION: + +This directive returns the current priority in ``priority`` of the task +specified by ``task_id`` with respect to the scheduler specified by +``scheduler_id``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``priority`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``task_id``. + +:c:macro:`RTEMS_INVALID_ID` + There was no scheduler associated with the identifier specified by + ``scheduler_id``. + +:c:macro:`RTEMS_NOT_DEFINED` + The task had no priority with respect to the scheduler. + +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT` + The task resided on a remote node. + +.. rubric:: NOTES: + +The current priority reflects temporary priority adjustments due to locking +protocols, the rate-monotonic period objects on some schedulers such as EDF, +and the POSIX sporadic server. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/task/if/mode + +.. raw:: latex + + \clearpage + +.. index:: rtems_task_mode() +.. index:: current task mode +.. index:: set task mode +.. index:: get task mode +.. index:: set task preemption mode +.. index:: get task preemption mode +.. index:: obtain task mode + +.. _InterfaceRtemsTaskMode: + +rtems_task_mode() +----------------- + +Gets and optionally sets the mode of the calling task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_mode( + rtems_mode mode_set, + rtems_mode mask, + rtems_mode *previous_mode_set + ); + +.. rubric:: PARAMETERS: + +``mode_set`` + This parameter is the mode set to apply to the calling task. When ``mask`` + is set to :c:macro:`RTEMS_CURRENT_MODE`, the value of this parameter is + ignored. Only modes requested by ``mask`` are applied to the calling task. + +``mask`` + This parameter is the mode mask which specifies which modes in ``mode_set`` + are applied to the calling task. When the value is + :c:macro:`RTEMS_CURRENT_MODE`, the mode of the calling task is not changed. + +``previous_mode_set`` + This parameter is the pointer to an :c:type:`rtems_mode` object. When the + directive call is successful, the mode of the task before any mode changes + done by the directive call will be stored in this object. + +.. rubric:: DESCRIPTION: + +This directive queries and optionally manipulates the execution mode of the +calling task. A task's execution mode enables and disables preemption, +timeslicing, asynchronous signal processing, as well as specifying the +interrupt level. To modify an execution mode, the mode class(es) to be changed +must be specified in the ``mask`` parameter and the desired mode(s) must be +specified in the ``mode_set`` parameter. + +A task can obtain its current execution mode, without modifying it, by calling +this directive with a ``mask`` value of :c:macro:`RTEMS_CURRENT_MODE`. + +The **mode set** specified in ``mode_set`` is built through a *bitwise or* of +the mode constants described below. Not all combinations of modes are allowed. +Some modes are mutually exclusive. If mutually exclusive modes are combined, +the behaviour is undefined. Default task modes can be selected by using the +:c:macro:`RTEMS_DEFAULT_MODES` constant. The task mode set defines + +* the preemption mode of the task: :c:macro:`RTEMS_PREEMPT` (default) or + :c:macro:`RTEMS_NO_PREEMPT`, + +* the timeslicing mode of the task: :c:macro:`RTEMS_TIMESLICE` or + :c:macro:`RTEMS_NO_TIMESLICE` (default), + +* the :term:`ASR` processing mode of the task: :c:macro:`RTEMS_ASR` (default) + or :c:macro:`RTEMS_NO_ASR`, + +* the interrupt level of the task: :c:func:`RTEMS_INTERRUPT_LEVEL` with a + default of ``RTEMS_INTERRUPT_LEVEL( 0 )`` which is associated with enabled + interrupts. + +The **mode mask** specified in ``mask`` is built through a *bitwise or* of the +mode mask constants described below. + +When the :c:macro:`RTEMS_PREEMPT_MASK` is set in ``mask``, the **preemption +mode** of the calling task is + +* enabled by using the :c:macro:`RTEMS_PREEMPT` mode constant in ``mode_set`` + and + +* disabled by using the :c:macro:`RTEMS_NO_PREEMPT` mode constant in + ``mode_set``. + +When the :c:macro:`RTEMS_TIMESLICE_MASK` is set in ``mask``, the **timeslicing +mode** of the calling task is + +* enabled by using the :c:macro:`RTEMS_TIMESLICE` mode constant in ``mode_set`` + and + +* disabled by using the :c:macro:`RTEMS_NO_TIMESLICE` mode constant in + ``mode_set``. + +Enabling timeslicing has no effect if preemption is disabled. For a task to be +timesliced, that task must have both preemption and timeslicing enabled. + +When the :c:macro:`RTEMS_ASR_MASK` is set in ``mask``, the **ASR processing +mode** of the calling task is + +* enabled by using the :c:macro:`RTEMS_ASR` mode constant in ``mode_set`` and + +* disabled by using the :c:macro:`RTEMS_NO_ASR` mode constant in ``mode_set``. + +When the :c:macro:`RTEMS_INTERRUPT_MASK` is set in ``mask``, **interrupts** of +the calling task are + +* enabled by using the :c:func:`RTEMS_INTERRUPT_LEVEL` mode macro with a value + of zero (0) in ``mode_set`` and + +* disabled up to the specified level by using the + :c:func:`RTEMS_INTERRUPT_LEVEL` mode macro with a positive value in + ``mode_set``. + +An interrupt level of zero is associated with enabled interrupts on all target +processors. The interrupt level portion of the task mode supports a maximum of +256 interrupt levels. These levels are mapped onto the interrupt levels +actually supported by the target processor in a processor dependent fashion. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_NOT_IMPLEMENTED` + The :c:macro:`RTEMS_NO_PREEMPT` was set in ``mode_set`` and setting the + preemption mode was requested by :c:macro:`RTEMS_PREEMPT_MASK` in ``mask`` + and the system configuration had no implementation for this mode. + +:c:macro:`RTEMS_NOT_IMPLEMENTED` + The :c:func:`RTEMS_INTERRUPT_LEVEL` was set to a positive level in + ``mode_set`` and setting the interrupt level was requested by + :c:macro:`RTEMS_INTERRUPT_MASK` in ``mask`` and the system configuration + had no implementation for this mode. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within task context. + +* When the directive enables preemption for the calling task, another task may + preempt the calling task. + +* While thread dispatching is disabled, if the directive performs a thread + dispatch, then the fatal error with the fatal source + :ref:`INTERNAL_ERROR_CORE <FatalErrorSources>` and the fatal code + :ref:`INTERNAL_ERROR_BAD_THREAD_DISPATCH_DISABLE_LEVEL <internal_errors>` + will occur. + +.. Generated from spec:/rtems/task/if/wake-after + +.. raw:: latex + + \clearpage + +.. index:: rtems_task_wake_after() +.. index:: delay a task for a count of clock ticks +.. index:: wake up after a count of clock ticks + +.. _InterfaceRtemsTaskWakeAfter: + +rtems_task_wake_after() +----------------------- + +Wakes up after a count of :term:`clock ticks <clock tick>` have occurred or +yields the processor. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_wake_after( rtems_interval ticks ); + +.. rubric:: PARAMETERS: + +``ticks`` + This parameter is the count of :term:`clock ticks <clock tick>` to delay + the task or :c:macro:`RTEMS_YIELD_PROCESSOR` to yield the processor. + +.. rubric:: DESCRIPTION: + +This directive blocks the calling task for the specified ``ticks`` count of +clock ticks if the value is not equal to :c:macro:`RTEMS_YIELD_PROCESSOR`. When +the requested count of ticks have occurred, the task is made ready. The clock +tick directives automatically update the delay period. The calling task may +give up the processor and remain in the ready state by specifying a value of +:c:macro:`RTEMS_YIELD_PROCESSOR` in ``ticks``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +.. rubric:: NOTES: + +Setting the system date and time with the :ref:`InterfaceRtemsClockSet` +directive and similar directives which set :term:`CLOCK_REALTIME` have no +effect on a :ref:`InterfaceRtemsTaskWakeAfter` blocked task. The delay until +first clock tick will never be a whole clock tick interval since this directive +will never execute exactly on a clock tick. Applications requiring use of a +clock (:term:`CLOCK_REALTIME` or :term:`CLOCK_MONOTONIC`) instead of clock +ticks should make use of `clock_nanosleep() +<https://pubs.opengroup.org/onlinepubs/9699919799/functions/clock_nanosleep.html>`_. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within task context. + +* The directive requires a :term:`Clock Driver`. + +* While thread dispatching is disabled, if the directive performs a thread + dispatch, then the fatal error with the fatal source + :ref:`INTERNAL_ERROR_CORE <FatalErrorSources>` and the fatal code + :ref:`INTERNAL_ERROR_BAD_THREAD_DISPATCH_DISABLE_LEVEL <internal_errors>` + will occur. + +.. Generated from spec:/rtems/task/if/wake-when + +.. raw:: latex + + \clearpage + +.. index:: rtems_task_wake_when() +.. index:: delay a task until a wall time +.. index:: wake up at a wall time + +.. _InterfaceRtemsTaskWakeWhen: + +rtems_task_wake_when() +---------------------- + +Wakes up when specified. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_wake_when( const rtems_time_of_day *time_buffer ); + +.. rubric:: PARAMETERS: + +``time_buffer`` + This parameter is the date and time to wake up. + +.. rubric:: DESCRIPTION: + +This directive blocks a task until the date and time specified in +``time_buffer``. At the requested date and time, the calling task will be +unblocked and made ready to execute. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_NOT_DEFINED` + The system date and time was not set. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``time_buffer`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_CLOCK` + The time of day was invalid. + +.. rubric:: NOTES: + +The ticks portion of ``time_buffer`` structure is ignored. The timing +granularity of this directive is a second. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within task context. + +* The directive requires a :term:`Clock Driver`. + +* While thread dispatching is disabled, if the directive performs a thread + dispatch, then the fatal error with the fatal source + :ref:`INTERNAL_ERROR_CORE <FatalErrorSources>` and the fatal code + :ref:`INTERNAL_ERROR_BAD_THREAD_DISPATCH_DISABLE_LEVEL <internal_errors>` + will occur. + +.. Generated from spec:/rtems/task/if/get-scheduler + +.. raw:: latex + + \clearpage + +.. index:: rtems_task_get_scheduler() + +.. _InterfaceRtemsTaskGetScheduler: + +rtems_task_get_scheduler() +-------------------------- + +Gets the home scheduler of the task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_get_scheduler( + rtems_id task_id, + rtems_id *scheduler_id + ); + +.. rubric:: PARAMETERS: + +``task_id`` + This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF` + may be used to specify the calling task. + +``scheduler_id`` + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the identifier of the :term:`home + scheduler` of the task will be stored in this object. + +.. rubric:: DESCRIPTION: + +This directive returns the identifier of the :term:`home scheduler` of the task +specified by ``task_id`` in ``scheduler_id``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``scheduler_id`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``task_id``. + +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT` + The task resided on a remote node. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/task/if/set-scheduler + +.. raw:: latex + + \clearpage + +.. index:: rtems_task_set_scheduler() + +.. _InterfaceRtemsTaskSetScheduler: + +rtems_task_set_scheduler() +-------------------------- + +Sets the home scheduler for the task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_set_scheduler( + rtems_id task_id, + rtems_id scheduler_id, + rtems_task_priority priority + ); + +.. rubric:: PARAMETERS: + +``task_id`` + This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF` + may be used to specify the calling task. + +``scheduler_id`` + This parameter is the scheduler identifier of the new :term:`home + scheduler` for the task specified by ``task_id``. + +``priority`` + This parameter is the new real priority for the task with respect to the + scheduler specified by ``scheduler_id``. + +.. rubric:: DESCRIPTION: + +This directive sets the :term:`home scheduler` to the scheduler specified by +``scheduler_id`` for the task specified by ``task_id``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no scheduler associated with the identifier specified by + ``scheduler_id``. + +:c:macro:`RTEMS_INVALID_PRIORITY` + The :term:`task priority` specified by ``priority`` was invalid with + respect to the scheduler specified by ``scheduler_id``. + +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``task_id``. + +:c:macro:`RTEMS_RESOURCE_IN_USE` + The task specified by ``task_id`` was enqueued on a :term:`wait queue`. + +:c:macro:`RTEMS_RESOURCE_IN_USE` + The task specified by ``task_id`` had a :term:`current priority` which + consisted of more than the :term:`real priority`. + +:c:macro:`RTEMS_RESOURCE_IN_USE` + The task specified by ``task_id`` had a :term:`helping scheduler`. + +:c:macro:`RTEMS_RESOURCE_IN_USE` + The task specified by ``task_id`` was pinned. + +:c:macro:`RTEMS_UNSATISFIED` + The scheduler specified by ``scheduler_id`` owned no processor. + +:c:macro:`RTEMS_UNSATISFIED` + The scheduler specified by ``scheduler_id`` did not support the affinity + set of the task specified by ``task_id``. + +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT` + The task resided on a remote node. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may change the priority of a task. This may cause the calling + task to be preempted. + +.. Generated from spec:/rtems/task/if/get-affinity + +.. raw:: latex + + \clearpage + +.. index:: rtems_task_get_affinity() + +.. _InterfaceRtemsTaskGetAffinity: + +rtems_task_get_affinity() +------------------------- + +Gets the processor affinity of the task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_get_affinity( + rtems_id id, + size_t cpusetsize, + cpu_set_t *cpuset + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF` + may be used to specify the calling task. + +``cpusetsize`` + This parameter is the size of the processor set referenced by ``cpuset`` in + bytes. + +``cpuset`` + This parameter is the pointer to a :c:type:`cpu_set_t` object. When the + directive call is successful, the processor affinity set of the task will + be stored in this object. A set bit in the processor set means that the + corresponding processor is in the processor affinity set of the task, + otherwise the bit is cleared. + +.. rubric:: DESCRIPTION: + +This directive returns the processor affinity of the task in ``cpuset`` of the +task specified by ``id``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``cpuset`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_INVALID_SIZE` + The size specified by ``cpusetsize`` of the processor set was too small for + the processor affinity set of the task. + +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT` + The task resided on a remote node. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/task/if/set-affinity + +.. raw:: latex + + \clearpage + +.. index:: rtems_task_set_affinity() + +.. _InterfaceRtemsTaskSetAffinity: + +rtems_task_set_affinity() +------------------------- + +Sets the processor affinity of the task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_set_affinity( + rtems_id id, + size_t cpusetsize, + const cpu_set_t *cpuset + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF` + may be used to specify the calling task. + +``cpusetsize`` + This parameter is the size of the processor set referenced by ``cpuset`` in + bytes. + +``cpuset`` + This parameter is the pointer to a :c:type:`cpu_set_t` object. The + processor set defines the new processor affinity set of the task. A set + bit in the processor set means that the corresponding processor shall be in + the processor affinity set of the task, otherwise the bit shall be cleared. + +.. rubric:: DESCRIPTION: + +This directive sets the processor affinity of the task specified by ``id``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``cpuset`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_INVALID_NUMBER` + The referenced processor set was not a valid new processor affinity set for + the task. + +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT` + The task resided on a remote node. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may change the processor affinity of a task. This may cause + the calling task to be preempted. + +.. Generated from spec:/rtems/task/if/iterate + +.. raw:: latex + + \clearpage + +.. index:: rtems_task_iterate() + +.. _InterfaceRtemsTaskIterate: + +rtems_task_iterate() +-------------------- + +Iterates over all tasks and invokes the visitor routine for each task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_task_iterate( rtems_task_visitor visitor, void *arg ); + +.. rubric:: PARAMETERS: + +``visitor`` + This parameter is the visitor routine invoked for each task. + +``arg`` + This parameter is the argument passed to each visitor routine invocation + during the iteration. + +.. rubric:: DESCRIPTION: + +This directive iterates over all tasks in the system. This operation covers +all tasks of all APIs. The user should be careful in accessing the contents of +the :term:`TCB`. The visitor argument ``arg`` is passed to all invocations of +``visitor`` in addition to the TCB. The iteration stops immediately in case the +visitor routine returns true. + +.. rubric:: NOTES: + +The visitor routine is invoked while owning the objects allocator lock. It is +allowed to perform blocking operations in the visitor routine, however, care +must be taken so that no deadlocks via the object allocator lock can occur. + +.. 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/task/if/storage-size + +.. raw:: latex + + \clearpage + +.. index:: RTEMS_TASK_STORAGE_SIZE() + +.. _InterfaceRTEMSTASKSTORAGESIZE: + +RTEMS_TASK_STORAGE_SIZE() +------------------------- + +Gets the recommended task storage area size for the size and task attributes. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + size_t RTEMS_TASK_STORAGE_SIZE( size_t size, rtems_attribute attributes ); + +.. rubric:: PARAMETERS: + +``size`` + This parameter is the size dedicated to the task stack and thread-local + storage in bytes. + +``attributes`` + This parameter is the attribute set of the task using the storage area. + +.. rubric:: RETURN VALUES: + +Returns the recommended task storage area size calculated from the input +parameters. diff --git a/c-user/task/index.rst b/c-user/task/index.rst new file mode 100644 index 0000000..f5e8a64 --- /dev/null +++ b/c-user/task/index.rst @@ -0,0 +1,19 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 embedded brains GmbH & Co. KG + +.. index:: tasks + +.. _RTEMSAPIClassicTasks: + +Task Manager +************ + +.. toctree:: + + introduction + background + operations + directives + deprecated-directives + removed-directives diff --git a/c-user/task/introduction.rst b/c-user/task/introduction.rst new file mode 100644 index 0000000..f174b42 --- /dev/null +++ b/c-user/task/introduction.rst @@ -0,0 +1,106 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2023 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/rtems/task/if/group + +.. _TaskManagerIntroduction: + +Introduction +============ + +.. The following list was generated from: +.. spec:/rtems/task/if/create +.. spec:/rtems/task/if/construct +.. spec:/rtems/task/if/ident +.. spec:/rtems/task/if/self +.. spec:/rtems/task/if/start +.. spec:/rtems/task/if/restart +.. spec:/rtems/task/if/delete +.. spec:/rtems/task/if/exit +.. spec:/rtems/task/if/suspend +.. spec:/rtems/task/if/resume +.. spec:/rtems/task/if/is-suspended +.. spec:/rtems/task/if/set-priority +.. spec:/rtems/task/if/get-priority +.. spec:/rtems/task/if/mode +.. spec:/rtems/task/if/wake-after +.. spec:/rtems/task/if/wake-when +.. spec:/rtems/task/if/get-scheduler +.. spec:/rtems/task/if/set-scheduler +.. spec:/rtems/task/if/get-affinity +.. spec:/rtems/task/if/set-affinity +.. spec:/rtems/task/if/iterate +.. spec:/rtems/task/if/storage-size + +The Task Manager provides a comprehensive set of directives to create, delete, +and administer tasks. The directives provided by the Task Manager are: + +* :ref:`InterfaceRtemsTaskCreate` - Creates a task. + +* :ref:`InterfaceRtemsTaskConstruct` - Constructs a task from the specified + task configuration. + +* :ref:`InterfaceRtemsTaskIdent` - Identifies a task by the object name. + +* :ref:`InterfaceRtemsTaskSelf` - Gets the task identifier of the calling task. + +* :ref:`InterfaceRtemsTaskStart` - Starts the task. + +* :ref:`InterfaceRtemsTaskRestart` - Restarts the task. + +* :ref:`InterfaceRtemsTaskDelete` - Deletes the task. + +* :ref:`InterfaceRtemsTaskExit` - Deletes the calling task. + +* :ref:`InterfaceRtemsTaskSuspend` - Suspends the task. + +* :ref:`InterfaceRtemsTaskResume` - Resumes the task. + +* :ref:`InterfaceRtemsTaskIsSuspended` - Checks if the task is suspended. + +* :ref:`InterfaceRtemsTaskSetPriority` - Sets the real priority or gets the + current priority of the task. + +* :ref:`InterfaceRtemsTaskGetPriority` - Gets the current priority of the task + with respect to the scheduler. + +* :ref:`InterfaceRtemsTaskMode` - Gets and optionally sets the mode of the + calling task. + +* :ref:`InterfaceRtemsTaskWakeAfter` - Wakes up after a count of :term:`clock + ticks <clock tick>` have occurred or yields the processor. + +* :ref:`InterfaceRtemsTaskWakeWhen` - Wakes up when specified. + +* :ref:`InterfaceRtemsTaskGetScheduler` - Gets the home scheduler of the task. + +* :ref:`InterfaceRtemsTaskSetScheduler` - Sets the home scheduler for the task. + +* :ref:`InterfaceRtemsTaskGetAffinity` - Gets the processor affinity of the + task. + +* :ref:`InterfaceRtemsTaskSetAffinity` - Sets the processor affinity of the + task. + +* :ref:`InterfaceRtemsTaskIterate` - Iterates over all tasks and invokes the + visitor routine for each task. + +* :ref:`InterfaceRTEMSTASKSTORAGESIZE` - Gets the recommended task storage area + size for the size and task attributes. diff --git a/c-user/task/operations.rst b/c-user/task/operations.rst new file mode 100644 index 0000000..438eea5 --- /dev/null +++ b/c-user/task/operations.rst @@ -0,0 +1,192 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Operations +========== + +Creating Tasks +-------------- + +The ``rtems_task_create`` directive creates a task by allocating a task control +block, assigning the task a user-specified name, allocating it a stack and +floating point context area, setting a user-specified initial priority, setting +a user-specified initial mode, and assigning it a task ID. Newly created tasks +are initially placed in the dormant state. All RTEMS tasks execute in the most +privileged mode of the processor. + +Obtaining Task IDs +------------------ + +When a task is created, RTEMS generates a unique task ID and assigns it to the +created task until it is deleted. The task ID may be obtained by either of two +methods. First, as the result of an invocation of the ``rtems_task_create`` +directive, the task ID is stored in a user provided location. Second, the task +ID may be obtained later using the ``rtems_task_ident`` directive. The task ID +is used by other directives to manipulate this task. + +Starting and Restarting Tasks +----------------------------- + +The ``rtems_task_start`` directive is used to place a dormant task in the ready +state. This enables the task to compete, based on its current priority, for +the processor and other system resources. Any actions, such as suspension or +change of priority, performed on a task prior to starting it are nullified when +the task is started. + +With the ``rtems_task_start`` directive the user specifies the task's starting +address and argument. The argument is used to communicate some startup +information to the task. As part of this directive, RTEMS initializes the +task's stack based upon the task's initial execution mode and start address. +The starting argument is passed to the task in accordance with the target +processor's calling convention. + +The ``rtems_task_restart`` directive restarts a task at its initial starting +address with its original priority and execution mode, but with a possibly +different argument. The new argument may be used to distinguish between the +original invocation of the task and subsequent invocations. The task's stack +and control block are modified to reflect their original creation values. +Although references to resources that have been requested are cleared, +resources allocated by the task are NOT automatically returned to RTEMS. A +task cannot be restarted unless it has previously been started (i.e. dormant +tasks cannot be restarted). All restarted tasks are placed in the ready state. + +Suspending and Resuming Tasks +----------------------------- + +The ``rtems_task_suspend`` directive is used to place either the caller or +another task into a suspended state. The task remains suspended until a +``rtems_task_resume`` directive is issued. This implies that a task may be +suspended as well as blocked waiting either to acquire a resource or for the +expiration of a timer. + +The ``rtems_task_resume`` directive is used to remove another task from the +suspended state. If the task is not also blocked, resuming it will place it in +the ready state, allowing it to once again compete for the processor and +resources. If the task was blocked as well as suspended, this directive clears +the suspension and leaves the task in the blocked state. + +Suspending a task which is already suspended or resuming a task which is not +suspended is considered an error. The ``rtems_task_is_suspended`` can be used +to determine if a task is currently suspended. + +Delaying the Currently Executing Task +------------------------------------- + +The ``rtems_task_wake_after`` directive creates a sleep timer which allows a +task to go to sleep for a specified count of clock ticks. The task is blocked +until the count of clock ticks has elapsed, at which time the task is unblocked. +A task calling the ``rtems_task_wake_after`` directive with a delay of +``RTEMS_YIELD_PROCESSOR`` ticks will yield the processor to any other ready +task of equal or greater priority and remain ready to execute. + +The ``rtems_task_wake_when`` directive creates a sleep timer which allows a +task to go to sleep until a specified date and time. The calling task is +blocked until the specified date and time has occurred, at which time the task +is unblocked. + +Changing Task Priority +---------------------- + +The ``rtems_task_set_priority`` directive is used to obtain or change the +current priority of either the calling task or another task. If the new +priority requested is ``RTEMS_CURRENT_PRIORITY`` or the task's actual priority, +then the current priority will be returned and the task's priority will remain +unchanged. If the task's priority is altered, then the task will be scheduled +according to its new priority. + +The ``rtems_task_restart`` directive resets the priority of a task to its +original value. + +Changing Task Mode +------------------ + +The ``rtems_task_mode`` directive is used to obtain or change the current +execution mode of the calling task. A task's execution mode is used to enable +preemption, timeslicing, ASR processing, and to set the task's interrupt level. + +The ``rtems_task_restart`` directive resets the mode of a task to its original +value. + +Task Deletion +------------- + +RTEMS provides the ``rtems_task_delete`` directive to allow a task to delete +itself or any other task. This directive removes all RTEMS references to the +task, frees the task's control block, removes it from resource wait queues, and +deallocates its stack as well as the optional floating point context. The +task's name and ID become inactive at this time, and any subsequent references +to either of them is invalid. In fact, RTEMS may reuse the task ID for another +task which is created later in the application. A specialization of +``rtems_task_delete`` is ``rtems_task_exit`` which deletes the calling task. + +Unexpired delay timers (i.e. those used by ``rtems_task_wake_after`` and +``rtems_task_wake_when``) and timeout timers associated with the task are +automatically deleted, however, other resources dynamically allocated by the +task are NOT automatically returned to RTEMS. Therefore, before a task is +deleted, all of its dynamically allocated resources should be deallocated by +the user. This may be accomplished by instructing the task to delete itself +rather than directly deleting the task. Other tasks may instruct a task to +delete itself by sending a "delete self" message, event, or signal, or by +restarting the task with special arguments which instruct the task to delete +itself. + +Setting Affinity to a Single Processor +-------------------------------------- + +On some embedded applications targeting SMP systems, it may be beneficial to +lock individual tasks to specific processors. In this way, one can designate a +processor for I/O tasks, another for computation, etc.. The following +illustrates the code sequence necessary to assign a task an affinity for +processor with index ``processor_index``. + +.. code-block:: c + + #include <rtems.h> + #include <assert.h> + + void pin_to_processor(rtems_id task_id, int processor_index) + { + rtems_status_code sc; + cpu_set_t cpuset; + CPU_ZERO(&cpuset); + CPU_SET(processor_index, &cpuset); + sc = rtems_task_set_affinity(task_id, sizeof(cpuset), &cpuset); + assert(sc == RTEMS_SUCCESSFUL); + } + +It is important to note that the ``cpuset`` is not validated until the +``rtems_task_set_affinity`` call is made. At that point, it is validated +against the current system configuration. + +.. index:: rtems_task_get_note() +.. index:: rtems_task_set_note() + +Transition Advice for Removed Notepads +--------------------------------------- + +Task notepads and the associated directives :ref:`rtems_task_get_note` and +:ref:`rtems_task_set_note` were removed in RTEMS 5.1. These were never +thread-safe to access and subject to conflicting use of the notepad index by +libraries which were designed independently. + +It is recommended that applications be modified to use services which are +thread safe and not subject to issues with multiple applications conflicting +over the key (e.g. notepad index) selection. For most applications, POSIX Keys +should be used. These are available in all RTEMS build configurations. It is +also possible that thread-local storage (TLS) is an option for some use cases. + +.. index:: rtems_task_variable_add() +.. index:: rtems_task_variable_get() +.. index:: rtems_task_variable_delete() + +Transition Advice for Removed Task Variables +--------------------------------------------- + +Task notepads and the associated directives :ref:`rtems_task_variable_add`, +:ref:`rtems_task_variable_get` and :ref:`rtems_task_variable_delete` were +removed in RTEMS 5.1. Task variables must be replaced by POSIX Keys or +thread-local storage (TLS). POSIX Keys are available in all configurations and +support value destructors. For the TLS support consult the :title:`RTEMS CPU +Architecture Supplement`. diff --git a/c-user/task/removed-directives.rst b/c-user/task/removed-directives.rst new file mode 100644 index 0000000..677e810 --- /dev/null +++ b/c-user/task/removed-directives.rst @@ -0,0 +1,283 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Removed Directives +================== + +.. raw:: latex + + \clearpage + +.. index:: get task notepad entry +.. index:: rtems_task_get_note() + +.. _rtems_task_get_note: + +TASK_GET_NOTE - Get task notepad entry +-------------------------------------- + +.. warning:: + + This directive was removed in RTEMS 5.1. + +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_task_get_note( + rtems_id id, + uint32_t notepad, + uint32_t *note + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - note value obtained successfully + * - ``RTEMS_INVALID_ADDRESS`` + - ``note`` parameter is NULL + * - ``RTEMS_INVALID_ID`` + - invalid task id + * - ``RTEMS_INVALID_NUMBER`` + - invalid notepad location + +DESCRIPTION: + This directive returns the note contained in the notepad location of the + task specified by id. + +NOTES: + This directive will not cause the running task to be preempted. + + If id is set to ``RTEMS_SELF``, the calling task accesses its own notepad. + + The sixteen notepad locations can be accessed using the constants + ``RTEMS_NOTEPAD_0`` through ``RTEMS_NOTEPAD_15``. + + Getting a note of a global task which does not reside on the local node + will generate a request to the remote node to obtain the notepad entry of + the specified task. + +.. raw:: latex + + \clearpage + +.. index:: set task notepad entry +.. index:: rtems_task_set_note() + +.. _rtems_task_set_note: + +TASK_SET_NOTE - Set task notepad entry +-------------------------------------- + +.. warning:: + + This directive was removed in RTEMS 5.1. + +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_task_set_note( + rtems_id id, + uint32_t notepad, + uint32_t note + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - note set successfully + * - ``RTEMS_INVALID_ID`` + - invalid task id + * - ``RTEMS_INVALID_NUMBER`` + - invalid notepad location + +DESCRIPTION: + This directive sets the notepad entry for the task specified by id to the + value note. + +NOTES: + If ``id`` is set to ``RTEMS_SELF``, the calling task accesses its own + notepad. + + This directive will not cause the running task to be preempted. + + The sixteen notepad locations can be accessed using the constants + ``RTEMS_NOTEPAD_0`` through ``RTEMS_NOTEPAD_15``. + + Setting a note of a global task which does not reside on the local node + will generate a request to the remote node to set the notepad entry of the + specified task. + +.. raw:: latex + + \clearpage + +.. index:: per-task variable +.. index:: task private variable +.. index:: task private data +.. index:: rtems_task_variable_add() + +.. _rtems_task_variable_add: + +TASK_VARIABLE_ADD - Associate per task variable +----------------------------------------------- + +.. warning:: + + This directive was removed in RTEMS 5.1. + +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_task_variable_add( + rtems_id tid, + void **task_variable, + void (*dtor)(void *) + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - per task variable added successfully + * - ``RTEMS_INVALID_ADDRESS`` + - ``task_variable`` is NULL + * - ``RTEMS_INVALID_ID`` + - invalid task id + * - ``RTEMS_NO_MEMORY`` + - invalid task id + * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` + - not supported on remote tasks + +DESCRIPTION: + This directive adds the memory location specified by the ptr argument to + the context of the given task. The variable will then be private to the + task. The task can access and modify the variable, but the modifications + will not appear to other tasks, and other tasks' modifications to that + variable will not affect the value seen by the task. This is accomplished + by saving and restoring the variable's value each time a task switch occurs + to or from the calling task. If the dtor argument is non-NULL it specifies + the address of a 'destructor' function which will be called when the task + is deleted. The argument passed to the destructor function is the task's + value of the variable. + +NOTES: + Task variables increase the context switch time to and from the tasks that + own them so it is desirable to minimize the number of task variables. One + efficient method is to have a single task variable that is a pointer to a + dynamically allocated structure containing the task's private 'global' + data. In this case the destructor function could be 'free'. + + Per-task variables are disabled in SMP configurations and this service is + not available. + +.. raw:: latex + + \clearpage + +.. index:: get per-task variable +.. index:: obtain per-task variable +.. index:: rtems_task_variable_get() + +.. _rtems_task_variable_get: + +TASK_VARIABLE_GET - Obtain value of a per task variable +------------------------------------------------------- + +.. warning:: + + This directive was removed in RTEMS 5.1. + +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_task_variable_get( + rtems_id tid, + void **task_variable, + void **task_variable_value + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - per task variable obtained successfully + * - ``RTEMS_INVALID_ADDRESS`` + - ``task_variable`` is NULL + * - ``RTEMS_INVALID_ADDRESS`` + - ``task_variable_value`` is NULL + * - ``RTEMS_INVALID_ADDRESS`` + - ``task_variable`` is not found + * - ``RTEMS_NO_MEMORY`` + - invalid task id + * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` + - not supported on remote tasks + +DESCRIPTION: + This directive looks up the private value of a task variable for a + specified task and stores that value in the location pointed to by the + result argument. The specified task is usually not the calling task, which + can get its private value by directly accessing the variable. + +NOTES: + If you change memory which ``task_variable_value`` points to, remember to + declare that memory as volatile, so that the compiler will optimize it + correctly. In this case both the pointer ``task_variable_value`` and data + referenced by ``task_variable_value`` should be considered volatile. + + Per-task variables are disabled in SMP configurations and this service is + not available. + +.. raw:: latex + + \clearpage + +.. index:: per-task variable +.. index:: task private variable +.. index:: task private data +.. index:: rtems_task_variable_delete() + +.. _rtems_task_variable_delete: + +TASK_VARIABLE_DELETE - Remove per task variable +----------------------------------------------- + +.. warning:: + + This directive was removed in RTEMS 5.1. + +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_task_variable_delete( + rtems_id id, + void **task_variable + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - per task variable deleted successfully + * - ``RTEMS_INVALID_ID`` + - invalid task id + * - ``RTEMS_NO_MEMORY`` + - invalid task id + * - ``RTEMS_INVALID_ADDRESS`` + - ``task_variable`` is NULL + * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` + - not supported on remote tasks + +DESCRIPTION: + This directive removes the given location from a task's context. + +NOTES: + Per-task variables are disabled in SMP configurations and this service is + not available. diff --git a/c-user/task_manager.rst b/c-user/task_manager.rst deleted file mode 100644 index c3919f4..0000000 --- a/c-user/task_manager.rst +++ /dev/null @@ -1,2081 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-4.0 - -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) - -.. index:: tasks - -Task Manager -************ - -Introduction -============ - -The task manager provides a comprehensive set of directives to create, delete, -and administer tasks. The directives provided by the task manager are: - -- rtems_task_create_ - Create a task - -- rtems_task_ident_ - Get ID of a task - -- rtems_task_self_ - Obtain ID of caller - -- rtems_task_start_ - Start a task - -- rtems_task_restart_ - Restart a task - -- rtems_task_delete_ - Delete a task - -- rtems_task_exit_ - Delete the calling task - -- rtems_task_suspend_ - Suspend a task - -- rtems_task_resume_ - Resume a task - -- rtems_task_is_suspended_ - Determine if a task is suspended - -- rtems_task_set_priority_ - Set task priority - -- rtems_task_get_priority_ - Get task priority - -- rtems_task_mode_ - Change current task's mode - -- rtems_task_wake_after_ - Wake up after interval - -- rtems_task_wake_when_ - Wake up when specified - -- rtems_task_get_scheduler_ - Get scheduler of a task - -- rtems_task_set_scheduler_ - Set scheduler of a task - -- rtems_task_get_affinity_ - Get task processor affinity - -- rtems_task_set_affinity_ - Set task processor affinity - -- rtems_task_iterate_ - Iterate Over Tasks - -Background -========== - -.. index:: task, definition - -Task Definition ---------------- - -Many definitions of a task have been proposed in computer literature. -Unfortunately, none of these definitions encompasses all facets of the concept -in a manner which is operating system independent. Several of the more common -definitions are provided to enable each user to select a definition which best -matches their own experience and understanding of the task concept: - -- a "dispatchable" unit. - -- an entity to which the processor is allocated. - -- an atomic unit of a real-time, multiprocessor system. - -- single threads of execution which concurrently compete for resources. - -- a sequence of closely related computations which can execute concurrently - with other computational sequences. - -From RTEMS' perspective, a task is the smallest thread of execution which can -compete on its own for system resources. A task is manifested by the existence -of a task control block (TCB). - -.. _TaskControlBlock: - -Task Control Block ------------------- - -The Task Control Block (TCB) is an RTEMS defined data structure which contains -all the information that is pertinent to the execution of a task. During -system initialization, RTEMS reserves a TCB for each task configured. A TCB is -allocated upon creation of the task and is returned to the TCB free list upon -deletion of the task. - -The TCB's elements are modified as a result of system calls made by the -application in response to external and internal stimuli. TCBs are the only -RTEMS internal data structure that can be accessed by an application via user -extension routines. The TCB contains a task's name, ID, current priority, -current and starting states, execution mode, TCB user extension pointer, -scheduling control structures, as well as data required by a blocked task. - -A task's context is stored in the TCB when a task switch occurs. When the task -regains control of the processor, its context is restored from the TCB. When a -task is restarted, the initial state of the task is restored from the starting -context area in the task's TCB. - -.. index:: task memory - -Task Memory ------------ - -The system uses two separate memory areas to manage a task. One memory area is -the :ref:`TaskControlBlock`. The other memory area is allocated from the stack -space or provided by the user and contains - -* the task stack, - -* the thread-local storage (:term:`TLS`), and - -* an optional architecture-specific floating-point context. - -The size of the thread-local storage is determined at link time. A -user-provided task stack must take the size of the thread-local storage into -account. - -On architectures with a dedicated floating-point context, the application -configuration assumes that every task is a floating-point task, but whether or -not a task is actually floating-point is determined at runtime during task -creation (see :ref:`TaskFloatingPointConsiderations`). In highly memory -constrained systems this potential overestimate of the task stack space can be -mitigated through the :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE` configuration -option and aligned task stack sizes for the tasks. A user-provided task stack -must take the potential floating-point context into account. - -.. index:: task name - -Task Name ---------- - -By default, the task name is defined by the task object name given to -:ref:`rtems_task_create() <rtems_task_create>`. The task name can be obtained -with the `pthread_getname_np() -<http://man7.org/linux/man-pages/man3/pthread_setname_np.3.html>`_ function. -Optionally, a new task name may be set with the `pthread_setname_np() -<http://man7.org/linux/man-pages/man3/pthread_setname_np.3.html>`_ function. -The maximum size of a task name is defined by the application configuration -option :ref:`CONFIGURE_MAXIMUM_THREAD_NAME_SIZE -<CONFIGURE_MAXIMUM_THREAD_NAME_SIZE>`. - -.. index:: task states - -Task States ------------ - -A task may exist in one of the following five states: - -- *executing* - Currently scheduled to the CPU - -- *ready* - May be scheduled to the CPU - -- *blocked* - Unable to be scheduled to the CPU - -- *dormant* - Created task that is not started - -- *non-existent* - Uncreated or deleted task - -An active task may occupy the executing, ready, blocked or dormant state, -otherwise the task is considered non-existent. One or more tasks may be active -in the system simultaneously. Multiple tasks communicate, synchronize, and -compete for system resources with each other via system calls. The multiple -tasks appear to execute in parallel, but actually each is dispatched to the CPU -for periods of time determined by the RTEMS scheduling algorithm. The -scheduling of a task is based on its current state and priority. - -.. index:: task priority -.. index:: priority, task -.. index:: rtems_task_priority - -Task Priority -------------- - -A task's priority determines its importance in relation to the other tasks -executing on the same processor. RTEMS supports 255 levels of priority ranging -from 1 to 255. The data type ``rtems_task_priority`` is used to store task -priorities. - -Tasks of numerically smaller priority values are more important tasks than -tasks of numerically larger priority values. For example, a task at priority -level 5 is of higher privilege than a task at priority level 10. There is no -limit to the number of tasks assigned to the same priority. - -Each task has a priority associated with it at all times. The initial value of -this priority is assigned at task creation time. The priority of a task may be -changed at any subsequent time. - -Priorities are used by the scheduler to determine which ready task will be -allowed to execute. In general, the higher the logical priority of a task, the -more likely it is to receive processor execution time. - -.. index:: task mode -.. index:: rtems_task_mode - -Task Mode ---------- - -A task's execution mode is a combination of the following four components: - -- preemption - -- ASR processing - -- timeslicing - -- interrupt level - -It is used to modify RTEMS' scheduling process and to alter the execution -environment of the task. The data type ``rtems_task_mode`` is used to manage -the task execution mode. - -.. index:: preemption - -The preemption component allows a task to determine when control of the -processor is relinquished. If preemption is disabled (``RTEMS_NO_PREEMPT``), -the task will retain control of the processor as long as it is in the executing -state - even if a higher priority task is made ready. If preemption is enabled -(``RTEMS_PREEMPT``) and a higher priority task is made ready, then the -processor will be taken away from the current task immediately and given to the -higher priority task. - -.. index:: timeslicing - -The timeslicing component is used by the RTEMS scheduler to determine how the -processor is allocated to tasks of equal priority. If timeslicing is enabled -(``RTEMS_TIMESLICE``), then RTEMS will limit the amount of time the task can -execute before the processor is allocated to another ready task of equal -priority. The length of the timeslice is application dependent and specified in -the Configuration Table. If timeslicing is disabled (``RTEMS_NO_TIMESLICE``), -then the task will be allowed to execute until a task of higher priority is -made ready. If ``RTEMS_NO_PREEMPT`` is selected, then the timeslicing component -is ignored by the scheduler. - -The asynchronous signal processing component is used to determine when received -signals are to be processed by the task. If signal processing is enabled -(``RTEMS_ASR``), then signals sent to the task will be processed the next time -the task executes. If signal processing is disabled (``RTEMS_NO_ASR``), then -all signals received by the task will remain posted until signal processing is -enabled. This component affects only tasks which have established a routine to -process asynchronous signals. - -.. index:: interrupt level, task - -The interrupt level component is used to determine which interrupts will be -enabled when the task is executing. ``RTEMS_INTERRUPT_LEVEL(n)`` specifies that -the task will execute at interrupt level n. - -.. list-table:: - :class: rtems-table - - * - ``RTEMS_PREEMPT`` - - enable preemption (default) - * - ``RTEMS_NO_PREEMPT`` - - disable preemption - * - ``RTEMS_NO_TIMESLICE`` - - disable timeslicing (default) - * - ``RTEMS_TIMESLICE`` - - enable timeslicing - * - ``RTEMS_ASR`` - - enable ASR processing (default) - * - ``RTEMS_NO_ASR`` - - disable ASR processing - * - ``RTEMS_INTERRUPT_LEVEL(0)`` - - enable all interrupts (default) - * - ``RTEMS_INTERRUPT_LEVEL(n)`` - - execute at interrupt level n - -The set of default modes may be selected by specifying the -``RTEMS_DEFAULT_MODES`` constant. - -.. index:: task arguments -.. index:: task prototype - -Accessing Task Arguments ------------------------- - -All RTEMS tasks are invoked with a single argument which is specified when they -are started or restarted. The argument is commonly used to communicate startup -information to the task. The simplest manner in which to define a task which -accesses it argument is: - -.. index:: rtems_task - -.. code-block:: c - - rtems_task user_task( - rtems_task_argument argument - ); - -Application tasks requiring more information may view this single argument as -an index into an array of parameter blocks. - -.. index:: floating point - -.. _TaskFloatingPointConsiderations: - -Floating Point Considerations ------------------------------ - -Please consult the *RTEMS CPU Architecture Supplement* if this section is -relevant on your architecture. On some architectures the floating-point context -is contained in the normal task context and this section does not apply. - -Creating a task with the ``RTEMS_FLOATING_POINT`` attribute flag results in -additional memory being allocated for the task to store the state of the numeric -coprocessor during task switches. This additional memory is **not** allocated -for ``RTEMS_NO_FLOATING_POINT`` tasks. Saving and restoring the context of a -``RTEMS_FLOATING_POINT`` task takes longer than that of a -``RTEMS_NO_FLOATING_POINT`` task because of the relatively large amount of time -required for the numeric coprocessor to save or restore its computational state. - -Since RTEMS was designed specifically for embedded military applications which -are floating point intensive, the executive is optimized to avoid unnecessarily -saving and restoring the state of the numeric coprocessor. In uniprocessor -configurations, the state of the numeric coprocessor is only saved when a -``RTEMS_FLOATING_POINT`` task is dispatched and that task was not the last task -to utilize the coprocessor. In a uniprocessor system with only one -``RTEMS_FLOATING_POINT`` task, the state of the numeric coprocessor will never -be saved or restored. - -Although the overhead imposed by ``RTEMS_FLOATING_POINT`` tasks is minimal, -some applications may wish to completely avoid the overhead associated with -``RTEMS_FLOATING_POINT`` tasks and still utilize a numeric coprocessor. By -preventing a task from being preempted while performing a sequence of floating -point operations, a ``RTEMS_NO_FLOATING_POINT`` task can utilize the numeric -coprocessor without incurring the overhead of a ``RTEMS_FLOATING_POINT`` -context switch. This approach also avoids the allocation of a floating point -context area. However, if this approach is taken by the application designer, -**no** tasks should be created as ``RTEMS_FLOATING_POINT`` tasks. Otherwise, the -floating point context will not be correctly maintained because RTEMS assumes -that the state of the numeric coprocessor will not be altered by -``RTEMS_NO_FLOATING_POINT`` tasks. Some architectures with a dedicated -floating-point context raise a processor exception if a task with -``RTEMS_NO_FLOATING_POINT`` issues a floating-point instruction, so this -approach may not work at all. - -If the supported processor type does not have hardware floating capabilities or -a standard numeric coprocessor, RTEMS will not provide built-in support for -hardware floating point on that processor. In this case, all tasks are -considered ``RTEMS_NO_FLOATING_POINT`` whether created as -``RTEMS_FLOATING_POINT`` or ``RTEMS_NO_FLOATING_POINT`` tasks. A floating -point emulation software library must be utilized for floating point -operations. - -On some processors, it is possible to disable the floating point unit -dynamically. If this capability is supported by the target processor, then -RTEMS will utilize this capability to enable the floating point unit only for -tasks which are created with the ``RTEMS_FLOATING_POINT`` attribute. The -consequence of a ``RTEMS_NO_FLOATING_POINT`` task attempting to access the -floating point unit is CPU dependent but will generally result in an exception -condition. - -.. index:: task attributes, building - -Building a Task Attribute Set ------------------------------ - -In general, an attribute set is built by a bitwise OR of the desired -components. The set of valid task attribute components is listed below: - -.. list-table:: - :class: rtems-table - - * - ``RTEMS_NO_FLOATING_POINT`` - - does not use coprocessor (default) - * - ``RTEMS_FLOATING_POINT`` - - uses numeric coprocessor - * - ``RTEMS_LOCAL`` - - local task (default) - * - ``RTEMS_GLOBAL`` - - global task - -Attribute values are specifically designed to be mutually exclusive, therefore -bitwise OR and addition operations are equivalent as long as each attribute -appears exactly once in the component list. A component listed as a default is -not required to appear in the component list, although it is a good programming -practice to specify default components. If all defaults are desired, then -``RTEMS_DEFAULT_ATTRIBUTES`` should be used. - -This example demonstrates the attribute_set parameter needed to create a local -task which utilizes the numeric coprocessor. The attribute_set parameter could -be ``RTEMS_FLOATING_POINT`` or ``RTEMS_LOCAL | RTEMS_FLOATING_POINT``. The -attribute_set parameter can be set to ``RTEMS_FLOATING_POINT`` because -``RTEMS_LOCAL`` is the default for all created tasks. If the task were global -and used the numeric coprocessor, then the attribute_set parameter would be -``RTEMS_GLOBAL | RTEMS_FLOATING_POINT``. - -.. index:: task mode, building - -Building a Mode and Mask ------------------------- - -In general, a mode and its corresponding mask is built by a bitwise OR of the -desired components. The set of valid mode constants and each mode's -corresponding mask constant is listed below: - -.. list-table:: - :class: rtems-table - - * - ``RTEMS_PREEMPT`` - - is masked by ``RTEMS_PREEMPT_MASK`` and enables preemption - * - ``RTEMS_NO_PREEMPT`` - - is masked by ``RTEMS_PREEMPT_MASK`` and disables preemption - * - ``RTEMS_NO_TIMESLICE`` - - is masked by ``RTEMS_TIMESLICE_MASK`` and disables timeslicing - * - ``RTEMS_TIMESLICE`` - - is masked by ``RTEMS_TIMESLICE_MASK`` and enables timeslicing - * - ``RTEMS_ASR`` - - is masked by ``RTEMS_ASR_MASK`` and enables ASR processing - * - ``RTEMS_NO_ASR`` - - is masked by ``RTEMS_ASR_MASK`` and disables ASR processing - * - ``RTEMS_INTERRUPT_LEVEL(0)`` - - is masked by ``RTEMS_INTERRUPT_MASK`` and enables all interrupts - * - ``RTEMS_INTERRUPT_LEVEL(n)`` - - is masked by ``RTEMS_INTERRUPT_MASK`` and sets interrupts level n - -Mode values are specifically designed to be mutually exclusive, therefore -bitwise OR and addition operations are equivalent as long as each mode appears -exactly once in the component list. A mode component listed as a default is -not required to appear in the mode component list, although it is a good -programming practice to specify default components. If all defaults are -desired, the mode ``RTEMS_DEFAULT_MODES`` and the mask ``RTEMS_ALL_MODE_MASKS`` -should be used. - -The following example demonstrates the mode and mask parameters used with the -``rtems_task_mode`` directive to place a task at interrupt level 3 and make it -non-preemptible. The mode should be set to ``RTEMS_INTERRUPT_LEVEL(3) | -RTEMS_NO_PREEMPT`` to indicate the desired preemption mode and interrupt level, -while the mask parameter should be set to ``RTEMS_INTERRUPT_MASK | -RTEMS_NO_PREEMPT_MASK`` to indicate that the calling task's interrupt level and -preemption mode are being altered. - -Operations -========== - -Creating Tasks --------------- - -The ``rtems_task_create`` directive creates a task by allocating a task control -block, assigning the task a user-specified name, allocating it a stack and -floating point context area, setting a user-specified initial priority, setting -a user-specified initial mode, and assigning it a task ID. Newly created tasks -are initially placed in the dormant state. All RTEMS tasks execute in the most -privileged mode of the processor. - -Obtaining Task IDs ------------------- - -When a task is created, RTEMS generates a unique task ID and assigns it to the -created task until it is deleted. The task ID may be obtained by either of two -methods. First, as the result of an invocation of the ``rtems_task_create`` -directive, the task ID is stored in a user provided location. Second, the task -ID may be obtained later using the ``rtems_task_ident`` directive. The task ID -is used by other directives to manipulate this task. - -Starting and Restarting Tasks ------------------------------ - -The ``rtems_task_start`` directive is used to place a dormant task in the ready -state. This enables the task to compete, based on its current priority, for -the processor and other system resources. Any actions, such as suspension or -change of priority, performed on a task prior to starting it are nullified when -the task is started. - -With the ``rtems_task_start`` directive the user specifies the task's starting -address and argument. The argument is used to communicate some startup -information to the task. As part of this directive, RTEMS initializes the -task's stack based upon the task's initial execution mode and start address. -The starting argument is passed to the task in accordance with the target -processor's calling convention. - -The ``rtems_task_restart`` directive restarts a task at its initial starting -address with its original priority and execution mode, but with a possibly -different argument. The new argument may be used to distinguish between the -original invocation of the task and subsequent invocations. The task's stack -and control block are modified to reflect their original creation values. -Although references to resources that have been requested are cleared, -resources allocated by the task are NOT automatically returned to RTEMS. A -task cannot be restarted unless it has previously been started (i.e. dormant -tasks cannot be restarted). All restarted tasks are placed in the ready state. - -Suspending and Resuming Tasks ------------------------------ - -The ``rtems_task_suspend`` directive is used to place either the caller or -another task into a suspended state. The task remains suspended until a -``rtems_task_resume`` directive is issued. This implies that a task may be -suspended as well as blocked waiting either to acquire a resource or for the -expiration of a timer. - -The ``rtems_task_resume`` directive is used to remove another task from the -suspended state. If the task is not also blocked, resuming it will place it in -the ready state, allowing it to once again compete for the processor and -resources. If the task was blocked as well as suspended, this directive clears -the suspension and leaves the task in the blocked state. - -Suspending a task which is already suspended or resuming a task which is not -suspended is considered an error. The ``rtems_task_is_suspended`` can be used -to determine if a task is currently suspended. - -Delaying the Currently Executing Task -------------------------------------- - -The ``rtems_task_wake_after`` directive creates a sleep timer which allows a -task to go to sleep for a specified interval. The task is blocked until the -delay interval has elapsed, at which time the task is unblocked. A task -calling the ``rtems_task_wake_after`` directive with a delay interval of -``RTEMS_YIELD_PROCESSOR`` ticks will yield the processor to any other ready -task of equal or greater priority and remain ready to execute. - -The ``rtems_task_wake_when`` directive creates a sleep timer which allows a -task to go to sleep until a specified date and time. The calling task is -blocked until the specified date and time has occurred, at which time the task -is unblocked. - -Changing Task Priority ----------------------- - -The ``rtems_task_set_priority`` directive is used to obtain or change the -current priority of either the calling task or another task. If the new -priority requested is ``RTEMS_CURRENT_PRIORITY`` or the task's actual priority, -then the current priority will be returned and the task's priority will remain -unchanged. If the task's priority is altered, then the task will be scheduled -according to its new priority. - -The ``rtems_task_restart`` directive resets the priority of a task to its -original value. - -Changing Task Mode ------------------- - -The ``rtems_task_mode`` directive is used to obtain or change the current -execution mode of the calling task. A task's execution mode is used to enable -preemption, timeslicing, ASR processing, and to set the task's interrupt level. - -The ``rtems_task_restart`` directive resets the mode of a task to its original -value. - -Task Deletion -------------- - -RTEMS provides the ``rtems_task_delete`` directive to allow a task to delete -itself or any other task. This directive removes all RTEMS references to the -task, frees the task's control block, removes it from resource wait queues, and -deallocates its stack as well as the optional floating point context. The -task's name and ID become inactive at this time, and any subsequent references -to either of them is invalid. In fact, RTEMS may reuse the task ID for another -task which is created later in the application. A specialization of -``rtems_task_delete`` is ``rtems_task_exit`` which deletes the calling task. - -Unexpired delay timers (i.e. those used by ``rtems_task_wake_after`` and -``rtems_task_wake_when``) and timeout timers associated with the task are -automatically deleted, however, other resources dynamically allocated by the -task are NOT automatically returned to RTEMS. Therefore, before a task is -deleted, all of its dynamically allocated resources should be deallocated by -the user. This may be accomplished by instructing the task to delete itself -rather than directly deleting the task. Other tasks may instruct a task to -delete itself by sending a "delete self" message, event, or signal, or by -restarting the task with special arguments which instruct the task to delete -itself. - -Setting Affinity to a Single Processor --------------------------------------- - -On some embedded applications targeting SMP systems, it may be beneficial to -lock individual tasks to specific processors. In this way, one can designate a -processor for I/O tasks, another for computation, etc.. The following -illustrates the code sequence necessary to assign a task an affinity for -processor with index ``processor_index``. - -.. code-block:: c - - #include <rtems.h> - #include <assert.h> - - void pin_to_processor(rtems_id task_id, int processor_index) - { - rtems_status_code sc; - cpu_set_t cpuset; - CPU_ZERO(&cpuset); - CPU_SET(processor_index, &cpuset); - sc = rtems_task_set_affinity(task_id, sizeof(cpuset), &cpuset); - assert(sc == RTEMS_SUCCESSFUL); - } - -It is important to note that the ``cpuset`` is not validated until the -``rtems_task_set_affinity`` call is made. At that point, it is validated -against the current system configuration. - -.. index:: rtems_task_get_note -.. index:: rtems_task_set_note - -Transition Advice for Removed Notepads ---------------------------------------- - -Task notepads and the associated directives :ref:`rtems_task_get_note` and -:ref:`rtems_task_set_note` were removed in RTEMS 5.1. These were never -thread-safe to access and subject to conflicting use of the notepad index by -libraries which were designed independently. - -It is recommended that applications be modified to use services which are -thread safe and not subject to issues with multiple applications conflicting -over the key (e.g. notepad index) selection. For most applications, POSIX Keys -should be used. These are available in all RTEMS build configurations. It is -also possible that thread-local storage (TLS) is an option for some use cases. - -.. index:: rtems_task_variable_add -.. index:: rtems_task_variable_get -.. index:: rtems_task_variable_delete - -Transition Advice for Removed Task Variables ---------------------------------------------- - -Task notepads and the associated directives :ref:`rtems_task_variable_add`, -:ref:`rtems_task_variable_get` and :ref:`rtems_task_variable_delete` were -removed in RTEMS 5.1. Task variables must be replaced by POSIX Keys or -thread-local storage (TLS). POSIX Keys are available in all configurations and -support value destructors. For the TLS support consult the :title:`RTEMS CPU -Architecture Supplement`. - -Directives -========== - -This section details the task manager's directives. A subsection is dedicated -to each of this manager's directives and describes the calling sequence, -related constants, usage, and status codes. - -.. raw:: latex - - \clearpage - -.. index:: create a task -.. index:: rtems_task_create - -.. _rtems_task_create: - -TASK_CREATE - Create a task ---------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_create( - rtems_name name, - rtems_task_priority initial_priority, - size_t stack_size, - rtems_mode initial_modes, - rtems_attribute attribute_set, - rtems_id *id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - task created successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``id`` is NULL - * - ``RTEMS_INVALID_NAME`` - - invalid task name - * - ``RTEMS_INVALID_PRIORITY`` - - invalid task priority - * - ``RTEMS_MP_NOT_CONFIGURED`` - - multiprocessing not configured - * - ``RTEMS_TOO_MANY`` - - too many tasks created - * - ``RTEMS_UNSATISFIED`` - - not enough memory for stack/FP context - * - ``RTEMS_UNSATISFIED`` - - non-preemption mode not supported on SMP system - * - ``RTEMS_UNSATISFIED`` - - interrupt level mode not supported on SMP system - * - ``RTEMS_TOO_MANY`` - - too many global objects - -DESCRIPTION: - This directive creates a task which resides on the local node. It - allocates and initializes a TCB, a stack, and an optional floating point - context area. The mode parameter contains values which sets the task's - initial execution mode. The ``RTEMS_FLOATING_POINT`` attribute should be - specified if the created task is to use a numeric coprocessor. For - performance reasons, it is recommended that tasks not using the numeric - coprocessor should specify the ``RTEMS_NO_FLOATING_POINT`` attribute. If - the ``RTEMS_GLOBAL`` attribute is specified, the task can be accessed from - remote nodes. The task id, returned in id, is used in other task related - directives to access the task. When created, a task is placed in the - dormant state and can only be made ready to execute using the directive - ``rtems_task_start``. - -NOTES: - This directive may cause the calling task to be preempted. - - The scheduler of the new task is the scheduler of the executing task at - some point during the task creation. The specified task priority must be - valid for the selected scheduler. - - The task processor affinity is initialized to the set of online processors. - - If the requested stack size is less than the configured minimum stack size, - then RTEMS will use the configured minimum as the stack size for this task. - In addition to being able to specify the task stack size as a integer, - there are two constants which may be specified: - - ``RTEMS_MINIMUM_STACK_SIZE`` - The minimum stack size *RECOMMENDED* for use on this processor. This - value is selected by the RTEMS developers conservatively to minimize the - risk of blown stacks for most user applications. Using this constant - when specifying the task stack size, indicates that the stack size will - be at least ``RTEMS_MINIMUM_STACK_SIZE`` bytes in size. If the user - configured minimum stack size is larger than the recommended minimum, - then it will be used. - - ``RTEMS_CONFIGURED_MINIMUM_STACK_SIZE`` - Indicates this task is to be created with a stack size of the minimum - stack size that was configured by the application. If not explicitly - configured by the application, the default configured minimum stack size - is the processor dependent value ``RTEMS_MINIMUM_STACK_SIZE``. Since - this uses the configured minimum stack size value, you may get a stack - size that is smaller or larger than the recommended minimum. This can be - used to provide large stacks for all tasks on complex applications or - small stacks on applications that are trying to conserve memory. - - Application developers should consider the stack usage of the device - drivers when calculating the stack size required for tasks which utilize - the driver. - - The following task attribute constants are defined by RTEMS: - - .. list-table:: - :class: rtems-table - - * - ``RTEMS_NO_FLOATING_POINT`` - - does not use coprocessor (default) - * - ``RTEMS_FLOATING_POINT`` - - uses numeric coprocessor - * - ``RTEMS_LOCAL`` - - local task (default) - * - ``RTEMS_GLOBAL`` - - global task - - The following task mode constants are defined by RTEMS: - - .. list-table:: - :class: rtems-table - - * - ``RTEMS_PREEMPT`` - - enable preemption (default) - * - ``RTEMS_NO_PREEMPT`` - - disable preemption - * - ``RTEMS_NO_TIMESLICE`` - - disable timeslicing (default) - * - ``RTEMS_TIMESLICE`` - - enable timeslicing - * - ``RTEMS_ASR`` - - enable ASR processing (default) - * - ``RTEMS_NO_ASR`` - - disable ASR processing - * - ``RTEMS_INTERRUPT_LEVEL(0)`` - - enable all interrupts (default) - * - ``RTEMS_INTERRUPT_LEVEL(n)`` - - execute at interrupt level ``n`` - - The interrupt level portion of the task execution mode supports a maximum - of 256 interrupt levels. These levels are mapped onto the interrupt - levels actually supported by the target processor in a processor dependent - fashion. - - Tasks should not be made global unless remote tasks must interact with - them. This avoids the system overhead incurred by the creation of a - global task. When a global task is created, the task's name and id must - be transmitted to every node in the system for insertion in the local copy - of the global object table. - - The total number of global objects, including tasks, is limited by the - maximum_global_objects field in the Configuration Table. - -.. raw:: latex - - \clearpage - -.. index:: get ID of a task -.. index:: rtems_task_ident - -.. _rtems_task_ident: - -TASK_IDENT - Get ID of a task ------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_ident( - rtems_name name, - uint32_t node, - rtems_id *id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - task identified successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``id`` is NULL - * - ``RTEMS_INVALID_NAME`` - - invalid task name - * - ``RTEMS_INVALID_NODE`` - - invalid node id - -DESCRIPTION: - This directive obtains the task id associated with the task name specified - in name. A task may obtain its own id by specifying ``RTEMS_SELF`` or its - own task name in name. If the task name is not unique, then the task id - returned will match one of the tasks with that name. However, this task id - is not guaranteed to correspond to the desired task. The task id, returned - in id, is used in other task related directives to access the task. - -NOTES: - This directive will not cause the running task to be preempted. - - If node is ``RTEMS_SEARCH_ALL_NODES``, all nodes are searched with the - local node being searched first. All other nodes are searched with the - lowest numbered node searched first. - - If node is a valid node number which does not represent the local node, - then only the tasks exported by the designated node are searched. - - This directive does not generate activity on remote nodes. It accesses - only the local copy of the global object table. - -.. raw:: latex - - \clearpage - -.. index:: obtain ID of caller -.. index:: rtems_task_self - -.. _rtems_task_self: - -TASK_SELF - Obtain ID of caller -------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_id rtems_task_self(void); - -DIRECTIVE STATUS CODES: - Returns the object Id of the calling task. - -DESCRIPTION: - This directive returns the Id of the calling task. - -NOTES: - If called from an interrupt service routine, this directive will return the - Id of the interrupted task. - -.. raw:: latex - - \clearpage - -.. index:: starting a task -.. index:: rtems_task_start - -.. _rtems_task_start: - -TASK_START - Start a task -------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_start( - rtems_id id, - rtems_task_entry entry_point, - rtems_task_argument argument - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - ask started successfully - * - ``RTEMS_INVALID_ADDRESS`` - - invalid task entry point - * - ``RTEMS_INVALID_ID`` - - invalid task id - * - ``RTEMS_INCORRECT_STATE`` - - task not in the dormant state - * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - - cannot start remote task - -DESCRIPTION: - This directive readies the task, specified by ``id``, for execution based - on the priority and execution mode specified when the task was created. - The starting address of the task is given in ``entry_point``. The task's - starting argument is contained in argument. This argument can be a single - value or used as an index into an array of parameter blocks. The type of - this numeric argument is an unsigned integer type with the property that - any valid pointer to void can be converted to this type and then converted - back to a pointer to void. The result will compare equal to the original - pointer. - -NOTES: - The calling task will be preempted if its preemption mode is enabled and - the task being started has a higher priority. - - Any actions performed on a dormant task such as suspension or change of - priority are nullified when the task is initiated via the - ``rtems_task_start`` directive. - -.. raw:: latex - - \clearpage - -.. index:: restarting a task -.. index:: rtems_task_restart - -.. _rtems_task_restart: - -TASK_RESTART - Restart a task ------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_restart( - rtems_id id, - rtems_task_argument argument - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - task restarted successfully - * - ``RTEMS_INVALID_ID`` - - task id invalid - * - ``RTEMS_INCORRECT_STATE`` - - task never started - * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - - cannot restart remote task - -DESCRIPTION: - This directive resets the task specified by id to begin execution at its - original starting address. The task's priority and execution mode are set - to the original creation values. If the task is currently blocked, RTEMS - automatically makes the task ready. A task can be restarted from any - state, except the dormant state. - - The task's starting argument is contained in argument. This argument can - be a single value or an index into an array of parameter blocks. The type - of this numeric argument is an unsigned integer type with the property that - any valid pointer to void can be converted to this type and then converted - back to a pointer to void. The result will compare equal to the original - pointer. This new argument may be used to distinguish between the initial - ``rtems_task_start`` of the task and any ensuing calls to - ``rtems_task_restart`` of the task. This can be beneficial in deleting a - task. Instead of deleting a task using the ``rtems_task_delete`` - directive, a task can delete another task by restarting that task, and - allowing that task to release resources back to RTEMS and then delete - itself. - -NOTES: - If id is ``RTEMS_SELF``, the calling task will be restarted and will not - return from this directive. - - The calling task will be preempted if its preemption mode is enabled and - the task being restarted has a higher priority. - - The task must reside on the local node, even if the task was created with - the ``RTEMS_GLOBAL`` option. - -.. raw:: latex - - \clearpage - -.. index:: deleting a task -.. index:: rtems_task_delete - -.. _rtems_task_delete: - -TASK_DELETE - Delete a task ---------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_delete( - rtems_id id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - task deleted successfully - * - ``RTEMS_INVALID_ID`` - - task id invalid - * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - - cannot restart remote task - -DESCRIPTION: - This directive deletes a task, either the calling task or another task, as - specified by id. RTEMS stops the execution of the task and reclaims the - stack memory, any allocated delay or timeout timers, the TCB, and, if the - task is ``RTEMS_FLOATING_POINT``, its floating point context area. RTEMS - does not reclaim the following resources: region segments, partition - buffers, semaphores, timers, or rate monotonic periods. - -NOTES: - A task is responsible for releasing its resources back to RTEMS before - deletion. To insure proper deallocation of resources, a task should not be - deleted unless it is unable to execute or does not hold any RTEMS - resources. If a task holds RTEMS resources, the task should be allowed to - deallocate its resources before deletion. A task can be directed to - release its resources and delete itself by restarting it with a special - argument or by sending it a message, an event, or a signal. - - Deletion of the current task (``RTEMS_SELF``) will force RTEMS to select - another task to execute. - - When a global task is deleted, the task id must be transmitted to every - node in the system for deletion from the local copy of the global object - table. - - The task must reside on the local node, even if the task was created with - the ``RTEMS_GLOBAL`` option. - -.. raw:: latex - - \clearpage - -.. index:: deleting a task -.. index:: rtems_task_exit - -.. _rtems_task_exit: - -TASK_EXIT - Delete the calling task ------------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - void rtems_task_exit( void ) RTEMS_NO_RETURN; - -DIRECTIVE STATUS CODES: - NONE - This function will not return to the caller. - -DESCRIPTION: - This directive deletes the calling task. - -NOTES: - This directive must be called from a regular task context with enabled - interrupts, otherwise one of the fatal errors - - * :ref:`INTERNAL_ERROR_BAD_THREAD_DISPATCH_DISABLE_LEVEL <internal_errors>`, or - * :ref:`INTERNAL_ERROR_BAD_THREAD_DISPATCH_ENVIRONMENT <internal_errors>` - - will occur. - - The ``rtems_task_exit()`` call is equivalent to the following code - sequence: - - .. code-block:: c - - pthread_detach(pthread_self()); - pthread_exit(NULL); - - See also :ref:`rtems_task_delete() <rtems_task_delete>`. - -.. raw:: latex - - \clearpage - -.. index:: suspending a task -.. index:: rtems_task_suspend - -.. _rtems_task_suspend: - -TASK_SUSPEND - Suspend a task ------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_suspend( - rtems_id id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - task suspended successfully - * - ``RTEMS_INVALID_ID`` - - task id invalid - * - ``RTEMS_ALREADY_SUSPENDED`` - - task already suspended - -DESCRIPTION: - This directive suspends the task specified by id from further execution by - placing it in the suspended state. This state is additive to any other - blocked state that the task may already be in. The task will not execute - again until another task issues the ``rtems_task_resume`` directive for - this task and any blocked state has been removed. - -NOTES: - The requesting task can suspend itself by specifying ``RTEMS_SELF`` as id. - In this case, the task will be suspended and a successful return code will - be returned when the task is resumed. - - Suspending a global task which does not reside on the local node will - generate a request to the remote node to suspend the specified task. - - If the task specified by id is already suspended, then the - ``RTEMS_ALREADY_SUSPENDED`` status code is returned. - -.. raw:: latex - - \clearpage - -.. index:: resuming a task -.. index:: rtems_task_resume - -.. _rtems_task_resume: - -TASK_RESUME - Resume a task ---------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_resume( - rtems_id id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - task resumed successfully - * - ``RTEMS_INVALID_ID`` - - task id invalid - * - ``RTEMS_INCORRECT_STATE`` - - task not suspended - -DESCRIPTION: - This directive removes the task specified by id from the suspended state. - If the task is in the ready state after the suspension is removed, then it - will be scheduled to run. If the task is still in a blocked state after - the suspension is removed, then it will remain in that blocked state. - -NOTES: - The running task may be preempted if its preemption mode is enabled and the - local task being resumed has a higher priority. - - Resuming a global task which does not reside on the local node will - generate a request to the remote node to resume the specified task. - - If the task specified by id is not suspended, then the - ``RTEMS_INCORRECT_STATE`` status code is returned. - -.. raw:: latex - - \clearpage - -.. index:: is task suspended -.. index:: rtems_task_is_suspended - -.. _rtems_task_is_suspended: - -TASK_IS_SUSPENDED - Determine if a task is Suspended ----------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_is_suspended( - rtems_id id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - task is NOT suspended - * - ``RTEMS_ALREADY_SUSPENDED`` - - task is currently suspended - * - ``RTEMS_INVALID_ID`` - - task id invalid - * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - - not supported on remote tasks - -DESCRIPTION: - This directive returns a status code indicating whether or not the - specified task is currently suspended. - -NOTES: - This operation is not currently supported on remote tasks. - -.. raw:: latex - - \clearpage - -.. index:: rtems_task_set_priority -.. index:: current task priority -.. index:: set task priority -.. index:: get task priority -.. index:: obtain task priority - -.. _rtems_task_set_priority: - -TASK_SET_PRIORITY - Set task priority -------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_set_priority( - rtems_id id, - rtems_task_priority new_priority, - rtems_task_priority *old_priority - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - task priority set successfully - * - ``RTEMS_INVALID_ID`` - - invalid task id - * - ``RTEMS_INVALID_ADDRESS`` - - invalid return argument pointer - * - ``RTEMS_INVALID_PRIORITY`` - - invalid task priority - -DESCRIPTION: - This directive manipulates the priority of the task specified by id. An id - of ``RTEMS_SELF`` is used to indicate the calling task. When new_priority - is not equal to ``RTEMS_CURRENT_PRIORITY``, the specified task's previous - priority is returned in old_priority. When new_priority is - ``RTEMS_CURRENT_PRIORITY``, the specified task's current priority is - returned in old_priority. Valid priorities range from a high of 1 to a low - of 255. - -NOTES: - The calling task may be preempted if its preemption mode is enabled and it - lowers its own priority or raises another task's priority. - - In case the new priority equals the current priority of the task, then - nothing happens. - - Setting the priority of a global task which does not reside on the local - node will generate a request to the remote node to change the priority of - the specified task. - - If the task specified by id is currently holding any binary semaphores - which use the priority inheritance algorithm, then the task's priority - cannot be lowered immediately. If the task's priority were lowered - immediately, then priority inversion results. The requested lowering of - the task's priority will occur when the task has released all priority - inheritance binary semaphores. The task's priority can be increased - regardless of the task's use of priority inheritance binary semaphores. - -.. raw:: latex - - \clearpage - -.. index:: rtems_task_get_priority -.. index:: current task priority -.. index:: get task priority -.. index:: obtain task priority - -.. _rtems_task_get_priority: - -TASK_GET_PRIORITY - Get task priority -------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_get_priority( - rtems_id task_id, - rtems_id scheduler_id, - rtems_task_priority *priority - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - Successful operation. - * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - - Directive is illegal on remote tasks. - * - ``RTEMS_INVALID_ADDRESS`` - - The priority parameter is NULL. - * - ``RTEMS_INVALID_ID`` - - Invalid task or scheduler identifier. - * - ``RTEMS_NOT_DEFINED`` - - The task has no priority within the specified scheduler instance. - This error is only possible in SMP configurations. - -DESCRIPTION: - This directive returns the current priority of the task specified by - :c:data:`task_id` with respect to the scheduler instance specified by - :c:data:`scheduler_id`. A task id of :c:macro:`RTEMS_SELF` is used to - indicate the calling task. - -NOTES: - The current priority reflects temporary priority adjustments due to locking - protocols, the rate-monotonic period objects on some schedulers and other - mechanisms. - -.. raw:: latex - - \clearpage - -.. index:: current task mode -.. index:: set task mode -.. index:: get task mode -.. index:: set task preemption mode -.. index:: get task preemption mode -.. index:: obtain task mode -.. index:: rtems_task_mode - -.. _rtems_task_mode: - -TASK_MODE - Change the current task mode ----------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_mode( - rtems_mode mode_set, - rtems_mode mask, - rtems_mode *previous_mode_set - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - task mode set successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``previous_mode_set`` is NULL - - not enough memory for stack/FP context - * - ``RTEMS_NOT_IMPLEMENTED`` - - non-preemption mode not supported on SMP system - * - ``RTEMS_NOT_IMPLEMENTED`` - -DESCRIPTION: - This directive manipulates the execution mode of the calling task. A - task's execution mode enables and disables preemption, timeslicing, - asynchronous signal processing, as well as specifying the current interrupt - level. To modify an execution mode, the mode class(es) to be changed must - be specified in the mask parameter and the desired mode(s) must be - specified in the mode parameter. - -NOTES: - The calling task will be preempted if it enables preemption and a higher - priority task is ready to run. - - Enabling timeslicing has no effect if preemption is disabled. For a task - to be timesliced, that task must have both preemption and timeslicing - enabled. - - A task can obtain its current execution mode, without modifying it, by - calling this directive with a mask value of ``RTEMS_CURRENT_MODE``. - - To temporarily disable the processing of a valid ASR, a task should call - this directive with the ``RTEMS_NO_ASR`` indicator specified in mode. - - The set of task mode constants and each mode's corresponding mask constant - is provided in the following table: - - .. list-table:: - :class: rtems-table - - * - ``RTEMS_PREEMPT`` - - is masked by ``RTEMS_PREEMPT_MASK`` and enables preemption - * - ``RTEMS_NO_PREEMPT`` - - is masked by ``RTEMS_PREEMPT_MASK`` and disables preemption - * - ``RTEMS_NO_TIMESLICE`` - - is masked by ``RTEMS_TIMESLICE_MASK`` and disables timeslicing - * - ``RTEMS_TIMESLICE`` - - is masked by ``RTEMS_TIMESLICE_MASK`` and enables timeslicing - * - ``RTEMS_ASR`` - - is masked by ``RTEMS_ASR_MASK`` and enables ASR processing - * - ``RTEMS_NO_ASR`` - - is masked by ``RTEMS_ASR_MASK`` and disables ASR processing - * - ``RTEMS_INTERRUPT_LEVEL(0)`` - - is masked by ``RTEMS_INTERRUPT_MASK`` and enables all interrupts - * - ``RTEMS_INTERRUPT_LEVEL(n)`` - - is masked by ``RTEMS_INTERRUPT_MASK`` and sets interrupts level n - -.. raw:: latex - - \clearpage - -.. index:: delay a task for an interval -.. index:: wake up after an interval -.. index:: rtems_task_wake_after - -.. _rtems_task_wake_after: - -TASK_WAKE_AFTER - Wake up after interval ----------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_wake_after( - rtems_interval ticks - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - always successful - -DESCRIPTION: - This directive blocks the calling task for the specified number of system - clock ticks. When the requested interval has elapsed, the task is made - ready. The clock tick directives automatically updates the delay period. - -NOTES: - Setting the system date and time with the ``rtems_clock_set`` directive has - no effect on a ``rtems_task_wake_after`` blocked task. - - A task may give up the processor and remain in the ready state by - specifying a value of ``RTEMS_YIELD_PROCESSOR`` in ticks. - - The maximum timer interval that can be specified is the maximum value which - can be represented by the uint32_t type. - - A clock tick is required to support the functionality of this directive. - -.. raw:: latex - - \clearpage - -.. index:: delay a task until a wall time -.. index:: wake up at a wall time -.. index:: rtems_task_wake_when - -.. _rtems_task_wake_when: - -TASK_WAKE_WHEN - Wake up when specified ---------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_wake_when( - rtems_time_of_day *time_buffer - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - awakened at date/time successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``time_buffer`` is NULL - * - ``RTEMS_INVALID_TIME_OF_DAY`` - - invalid time buffer - * - ``RTEMS_NOT_DEFINED`` - - system date and time is not set - -DESCRIPTION: - This directive blocks a task until the date and time specified in - time_buffer. At the requested date and time, the calling task will be - unblocked and made ready to execute. - -NOTES: - The ticks portion of time_buffer structure is ignored. The timing - granularity of this directive is a second. - - A clock tick is required to support the functionality of this directive. - -.. raw:: latex - - \clearpage - -.. _rtems_task_get_scheduler: - -TASK_GET_SCHEDULER - Get scheduler of a task --------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_get_scheduler( - rtems_id task_id, - rtems_id *scheduler_id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - successful operation - * - ``RTEMS_INVALID_ADDRESS`` - - ``scheduler_id`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid task id - -DESCRIPTION: - Returns the scheduler identifier of a task identified by ``task_id`` in - ``scheduler_id``. - -NOTES: - None. - -.. raw:: latex - - \clearpage - -.. _rtems_task_set_scheduler: -.. _TASK_SET_SCHEDULER - Set scheduler of a task: - -TASK_SET_SCHEDULER - Set scheduler of a task --------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_set_scheduler( - rtems_id task_id, - rtems_id scheduler_id, - rtems_task_priority priority - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - successful operation - * - ``RTEMS_INVALID_ID`` - - invalid task or scheduler id - * - ``RTEMS_INVALID_PRIORITY`` - - invalid task priority - * - ``RTEMS_RESOURCE_IN_USE`` - - the task is in the wrong state to perform a scheduler change - * - ``RTEMS_UNSATISFIED`` - - the processor set of the scheduler is empty - * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - - not supported on remote tasks - -DESCRIPTION: - Sets the scheduler of a task identified by ``task_id`` to the scheduler - identified by ``scheduler_id``. The scheduler of a task is initialized to - the scheduler of the task that created it. The priority of the task is set - to ``priority``. - -NOTES: - It is recommended to set the scheduler of a task before it is started or in - case it is guaranteed that the task owns no resources. Otherwise, sporadic - ``RTEMS_RESOURCE_IN_USE`` errors may occur. - -EXAMPLE: - .. code-block:: c - :linenos: - - #include <rtems.h> - #include <assert.h> - - rtems_task task( rtems_task_argument arg ); - - void example( void ) - { - rtems_status_code sc; - rtems_id task_id; - rtems_id scheduler_id; - rtems_name scheduler_name; - - scheduler_name = rtems_build_name( 'W', 'O', 'R', 'K' ); - - sc = rtems_scheduler_ident( scheduler_name, &scheduler_id ); - assert( sc == RTEMS_SUCCESSFUL ); - - sc = rtems_task_create( - rtems_build_name( 'T', 'A', 'S', 'K' ), - 1, - RTEMS_MINIMUM_STACK_SIZE, - RTEMS_DEFAULT_MODES, - RTEMS_DEFAULT_ATTRIBUTES, - &task_id - ); - assert( sc == RTEMS_SUCCESSFUL ); - - sc = rtems_task_set_scheduler( task_id, scheduler_id, 2 ); - assert( sc == RTEMS_SUCCESSFUL ); - - sc = rtems_task_start( task_id, task, 0 ); - assert( sc == RTEMS_SUCCESSFUL ); - } - -.. raw:: latex - - \clearpage - -.. _rtems_task_get_affinity: - -TASK_GET_AFFINITY - Get task processor affinity ------------------------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_get_affinity( - rtems_id id, - size_t cpusetsize, - cpu_set_t *cpuset - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - successful operation - * - ``RTEMS_INVALID_ADDRESS`` - - ``cpuset`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid task id - * - ``RTEMS_INVALID_NUMBER`` - - the affinity set buffer is too small for the current processor affinity - set of the task - -DESCRIPTION: - Returns the current processor affinity set of the task in ``cpuset``. A - set bit in the affinity set means that the task can execute on this - processor and a cleared bit means the opposite. - -NOTES: - The task processor affinity is initialized to the set of online processors. - -.. raw:: latex - - \clearpage - -.. _rtems_task_set_affinity: - -TASK_SET_AFFINITY - Set task processor affinity ------------------------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_set_affinity( - rtems_id id, - size_t cpusetsize, - const cpu_set_t *cpuset - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - successful operation - * - ``RTEMS_INVALID_ADDRESS`` - - ``cpuset`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid task id - * - ``RTEMS_INVALID_NUMBER`` - - invalid processor affinity set - -DESCRIPTION: - Sets the processor affinity set for the task specified by ``cpuset``. A - set bit in the affinity set means that the task can execute on this - processor and a cleared bit means the opposite. - -NOTES: - This function will not change the scheduler of the task. The intersection - of the processor affinity set and the set of processors owned by the - scheduler of the task must be non-empty. It is not an error if the - processor affinity set contains processors that are not part of the set of - processors owned by the scheduler instance of the task. A task will simply - not run under normal circumstances on these processors since the scheduler - ignores them. Some locking protocols may temporarily use processors that - are not included in the processor affinity set of the task. It is also not - an error if the processor affinity set contains processors that are not - part of the system. - - In case a scheduler without support for task affinites is used for the - task, then the task processor affinity set must contain all online - processors of the system. This prevents odd corner cases if processors are - added/removed at run-time to/from scheduler instances. - -.. raw:: latex - - \clearpage - -.. index:: iterate over all threads -.. index:: rtems_task_iterate - -.. _rtems_task_iterate: - -TASK_ITERATE - Iterate Over Tasks ---------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - typedef bool ( *rtems_task_visitor )( rtems_tcb *tcb, void *arg ); - - void rtems_task_iterate( - rtems_task_visitor visitor, - void *arg - ); - -DIRECTIVE STATUS CODES: - NONE - -DESCRIPTION: - Iterates over all tasks in the system. This operation covers all tasks of - all APIs. The user should be careful in accessing the contents of the - thread control block :c:data:`tcb`. The visitor argument :c:data:`arg` is - passed to all invocations of :c:data:`visitor` in addition to the thread - control block. The iteration stops immediately in case the visitor - function returns true. - -NOTES: - Must be called from task context. This operation obtains and releases the - objects allocator lock. The task visitor is called while owning the objects - allocator lock. It is possible to perform blocking operations in the task - visitor, however, take care that no deadlocks via the object allocator lock - can occur. - -Deprecated Directives -===================== - -.. raw:: latex - - \clearpage - -.. index:: rtems_iterate_over_all_threads - -.. _rtems_iterate_over_all_threads: - -ITERATE_OVER_ALL_THREADS - Iterate Over Tasks ---------------------------------------------- - -.. warning:: - - This directive is deprecated. Its use is unsafe. Use - :ref:`rtems_task_iterate` instead. - -CALLING SEQUENCE: - .. code-block:: c - - typedef void (*rtems_per_thread_routine)(Thread_Control *the_thread); - void rtems_iterate_over_all_threads( - rtems_per_thread_routine routine - ); - -DIRECTIVE STATUS CODES: - NONE - -DESCRIPTION: - This directive iterates over all of the existant threads in the system and - invokes ``routine`` on each of them. The user should be careful in - accessing the contents of ``the_thread``. - - This routine is intended for use in diagnostic utilities and is not - intented for routine use in an operational system. - -NOTES: - There is **no protection** while this routine is called. The thread - control block may be in an inconsistent state or may change due to - interrupts or activity on other processors. - -Removed Directives -================== - -.. raw:: latex - - \clearpage - -.. index:: get task notepad entry -.. index:: rtems_task_get_note - -.. _rtems_task_get_note: - -TASK_GET_NOTE - Get task notepad entry --------------------------------------- - -.. warning:: - - This directive was removed in RTEMS 5.1. - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_get_note( - rtems_id id, - uint32_t notepad, - uint32_t *note - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - note value obtained successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``note`` parameter is NULL - * - ``RTEMS_INVALID_ID`` - - invalid task id - * - ``RTEMS_INVALID_NUMBER`` - - invalid notepad location - -DESCRIPTION: - This directive returns the note contained in the notepad location of the - task specified by id. - -NOTES: - This directive will not cause the running task to be preempted. - - If id is set to ``RTEMS_SELF``, the calling task accesses its own notepad. - - The sixteen notepad locations can be accessed using the constants - ``RTEMS_NOTEPAD_0`` through ``RTEMS_NOTEPAD_15``. - - Getting a note of a global task which does not reside on the local node - will generate a request to the remote node to obtain the notepad entry of - the specified task. - -.. raw:: latex - - \clearpage - -.. index:: set task notepad entry -.. index:: rtems_task_set_note - -.. _rtems_task_set_note: - -TASK_SET_NOTE - Set task notepad entry --------------------------------------- - -.. warning:: - - This directive was removed in RTEMS 5.1. - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_set_note( - rtems_id id, - uint32_t notepad, - uint32_t note - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - note set successfully - * - ``RTEMS_INVALID_ID`` - - invalid task id - * - ``RTEMS_INVALID_NUMBER`` - - invalid notepad location - -DESCRIPTION: - This directive sets the notepad entry for the task specified by id to the - value note. - -NOTES: - If ``id`` is set to ``RTEMS_SELF``, the calling task accesses its own - notepad. - - This directive will not cause the running task to be preempted. - - The sixteen notepad locations can be accessed using the constants - ``RTEMS_NOTEPAD_0`` through ``RTEMS_NOTEPAD_15``. - - Setting a note of a global task which does not reside on the local node - will generate a request to the remote node to set the notepad entry of the - specified task. - -.. raw:: latex - - \clearpage - -.. index:: per-task variable -.. index:: task private variable -.. index:: task private data -.. index:: rtems_task_variable_add - -.. _rtems_task_variable_add: - -TASK_VARIABLE_ADD - Associate per task variable ------------------------------------------------ - -.. warning:: - - This directive was removed in RTEMS 5.1. - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_variable_add( - rtems_id tid, - void **task_variable, - void (*dtor)(void *) - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - per task variable added successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``task_variable`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid task id - * - ``RTEMS_NO_MEMORY`` - - invalid task id - * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - - not supported on remote tasks - -DESCRIPTION: - This directive adds the memory location specified by the ptr argument to - the context of the given task. The variable will then be private to the - task. The task can access and modify the variable, but the modifications - will not appear to other tasks, and other tasks' modifications to that - variable will not affect the value seen by the task. This is accomplished - by saving and restoring the variable's value each time a task switch occurs - to or from the calling task. If the dtor argument is non-NULL it specifies - the address of a 'destructor' function which will be called when the task - is deleted. The argument passed to the destructor function is the task's - value of the variable. - -NOTES: - Task variables increase the context switch time to and from the tasks that - own them so it is desirable to minimize the number of task variables. One - efficient method is to have a single task variable that is a pointer to a - dynamically allocated structure containing the task's private 'global' - data. In this case the destructor function could be 'free'. - - Per-task variables are disabled in SMP configurations and this service is - not available. - -.. raw:: latex - - \clearpage - -.. index:: get per-task variable -.. index:: obtain per-task variable -.. index:: rtems_task_variable_get - -.. _rtems_task_variable_get: - -TASK_VARIABLE_GET - Obtain value of a per task variable -------------------------------------------------------- - -.. warning:: - - This directive was removed in RTEMS 5.1. - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_variable_get( - rtems_id tid, - void **task_variable, - void **task_variable_value - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - per task variable obtained successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``task_variable`` is NULL - * - ``RTEMS_INVALID_ADDRESS`` - - ``task_variable_value`` is NULL - * - ``RTEMS_INVALID_ADDRESS`` - - ``task_variable`` is not found - * - ``RTEMS_NO_MEMORY`` - - invalid task id - * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - - not supported on remote tasks - -DESCRIPTION: - This directive looks up the private value of a task variable for a - specified task and stores that value in the location pointed to by the - result argument. The specified task is usually not the calling task, which - can get its private value by directly accessing the variable. - -NOTES: - If you change memory which ``task_variable_value`` points to, remember to - declare that memory as volatile, so that the compiler will optimize it - correctly. In this case both the pointer ``task_variable_value`` and data - referenced by ``task_variable_value`` should be considered volatile. - - Per-task variables are disabled in SMP configurations and this service is - not available. - -.. raw:: latex - - \clearpage - -.. index:: per-task variable -.. index:: task private variable -.. index:: task private data -.. index:: rtems_task_variable_delete - -.. _rtems_task_variable_delete: - -TASK_VARIABLE_DELETE - Remove per task variable ------------------------------------------------ - -.. warning:: - - This directive was removed in RTEMS 5.1. - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_variable_delete( - rtems_id id, - void **task_variable - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - per task variable deleted successfully - * - ``RTEMS_INVALID_ID`` - - invalid task id - * - ``RTEMS_NO_MEMORY`` - - invalid task id - * - ``RTEMS_INVALID_ADDRESS`` - - ``task_variable`` is NULL - * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - - not supported on remote tasks - -DESCRIPTION: - This directive removes the given location from a task's context. - -NOTES: - Per-task variables are disabled in SMP configurations and this service is - not available. diff --git a/c-user/timer/background.rst b/c-user/timer/background.rst new file mode 100644 index 0000000..20cf202 --- /dev/null +++ b/c-user/timer/background.rst @@ -0,0 +1,71 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Background +========== + +Required Support +---------------- + +A clock tick is required to support the functionality provided by this manager. + +Timers +------ + +A timer is an RTEMS object which allows the application to schedule operations +to occur at specific times in the future. User supplied timer service routines +are invoked by either a clock tick directive or a special Timer +Server task when the timer fires. Timer service routines may perform any +operations or directives which normally would be performed by the application +code which invoked a clock tick directive. + +The timer can be used to implement watchdog routines which only fire to denote +that an application error has occurred. The timer is reset at specific points +in the application to ensure that the watchdog does not fire. Thus, if the +application does not reset the watchdog timer, then the timer service routine +will fire to indicate that the application has failed to reach a reset point. +This use of a timer is sometimes referred to as a "keep alive" or a "deadman" +timer. + +Timer Server +------------ + +The Timer Server task is responsible for executing the timer service routines +associated with all task-based timers. This task executes at a priority +specified by :ref:`rtems_timer_initiate_server() <rtems_timer_initiate_server>` +and it may have a priority of zero (the highest priority). In uniprocessor +configurations, it is created non-preemptible. + +By providing a mechanism where timer service routines execute in task rather +than interrupt space, the application is allowed a bit more flexibility in what +operations a timer service routine can perform. For example, the Timer Server +can be configured to have a floating point context in which case it would be +safe to perform floating point operations from a task-based timer. Most of the +time, executing floating point instructions from an interrupt service routine +is not considered safe. The timer service routines invoked by the Timer Server +may block, however, since this blocks the Timer Server itself, other timer +service routines that are already pending do not run until the blocked timer +service routine finished its work. + +The Timer Server is designed to remain blocked until a task-based timer fires. +This reduces the execution overhead of the Timer Server. + +.. index:: rtems_timer_service_routine + +Timer Service Routines +---------------------- + +The timer service routine should adhere to C calling conventions and have a +prototype similar to the following: + +.. code-block:: c + + rtems_timer_service_routine user_routine( + rtems_id timer_id, + void *user_data + ); + +Where the timer_id parameter is the RTEMS object ID of the timer which is being +fired and user_data is a pointer to user-defined information which may be +utilized by the timer service routine. The argument user_data may be NULL. diff --git a/c-user/timer/directives.rst b/c-user/timer/directives.rst new file mode 100644 index 0000000..2237b30 --- /dev/null +++ b/c-user/timer/directives.rst @@ -0,0 +1,844 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. _TimerManagerDirectives: + +Directives +========== + +This section details the directives of the Timer Manager. A subsection is +dedicated to each of this manager's directives and lists the calling sequence, +parameters, description, return values, and notes of the directive. + +.. Generated from spec:/rtems/timer/if/create + +.. raw:: latex + + \clearpage + +.. index:: rtems_timer_create() +.. index:: create a timer + +.. _InterfaceRtemsTimerCreate: + +rtems_timer_create() +-------------------- + +Creates a timer. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_timer_create( rtems_name name, rtems_id *id ); + +.. rubric:: PARAMETERS: + +``name`` + This parameter is the object name of the timer. + +``id`` + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the identifier of the created timer will + be stored in this object. + +.. rubric:: DESCRIPTION: + +This directive creates a timer which resides on the local node. The timer has +the user-defined object name specified in ``name``. The assigned object +identifier is returned in ``id``. This identifier is used to access the timer +with other timer related directives. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_NAME` + The ``name`` parameter was invalid. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``id`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_TOO_MANY` + There was no inactive object available to create a timer. The number of + timers available to the application is configured through the + :ref:`CONFIGURE_MAXIMUM_TIMERS` application configuration option. + +.. rubric:: NOTES: + +The processor used to maintain the timer is the processor of the calling task +at some point during the timer creation. + +For control and maintenance of the timer, RTEMS allocates a :term:`TMCB` from +the local TMCB free pool and initializes it. + +.. 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. + +* The number of timers available to the application is configured through the + :ref:`CONFIGURE_MAXIMUM_TIMERS` application configuration option. + +* Where the object class corresponding to the directive is configured to use + unlimited objects, the directive may allocate memory from the RTEMS + Workspace. + +.. Generated from spec:/rtems/timer/if/ident + +.. raw:: latex + + \clearpage + +.. index:: rtems_timer_ident() +.. index:: obtain the ID of a timer + +.. _InterfaceRtemsTimerIdent: + +rtems_timer_ident() +------------------- + +Identifies a timer by the object name. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_timer_ident( rtems_name name, rtems_id *id ); + +.. rubric:: PARAMETERS: + +``name`` + This parameter is the object name to look up. + +``id`` + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the object identifier of an object with + the specified name will be stored in this object. + +.. rubric:: DESCRIPTION: + +This directive obtains a timer identifier associated with the timer name +specified in ``name``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``id`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_NAME` + The ``name`` parameter was 0. + +:c:macro:`RTEMS_INVALID_NAME` + There was no object with the specified name on the local node. + +.. rubric:: NOTES: + +If the timer name is not unique, then the timer identifier will match the first +timer with that name in the search order. However, this timer identifier is +not guaranteed to correspond to the desired timer. + +The objects are searched from lowest to the highest index. Only the local node +is searched. + +The timer identifier is used with other timer related directives to access the +timer. + +.. 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/timer/if/cancel + +.. raw:: latex + + \clearpage + +.. index:: rtems_timer_cancel() +.. index:: cancel a timer + +.. _InterfaceRtemsTimerCancel: + +rtems_timer_cancel() +-------------------- + +Cancels the timer. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_timer_cancel( rtems_id id ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the timer identifier. + +.. rubric:: DESCRIPTION: + +This directive cancels the timer specified by ``id``. This timer will be +reinitiated by the next invocation of :ref:`InterfaceRtemsTimerReset`, +:ref:`InterfaceRtemsTimerFireAfter`, :ref:`InterfaceRtemsTimerFireWhen`, +:ref:`InterfaceRtemsTimerServerFireAfter`, or +:ref:`InterfaceRtemsTimerServerFireWhen` with the same timer identifier. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no timer associated with the identifier specified by ``id``. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/timer/if/delete + +.. raw:: latex + + \clearpage + +.. index:: rtems_timer_delete() +.. index:: delete a timer + +.. _InterfaceRtemsTimerDelete: + +rtems_timer_delete() +-------------------- + +Deletes the timer. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_timer_delete( rtems_id id ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the timer identifier. + +.. rubric:: DESCRIPTION: + +This directive deletes the timer specified by ``id``. If the timer is running, +it is automatically canceled. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no timer associated with the identifier specified by ``id``. + +.. rubric:: NOTES: + +The :term:`TMCB` for the deleted timer is reclaimed by RTEMS. + +.. 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. + +* The calling task does not have to be the task that created the object. Any + local task that knows the object identifier can delete the object. + +* Where the object class corresponding to the directive is configured to use + unlimited objects, the directive may free memory to the RTEMS Workspace. + +.. Generated from spec:/rtems/timer/if/fire-after + +.. raw:: latex + + \clearpage + +.. index:: rtems_timer_fire_after() +.. index:: fire a timer after an interval + +.. _InterfaceRtemsTimerFireAfter: + +rtems_timer_fire_after() +------------------------ + +Fires the timer after the interval. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_timer_fire_after( + rtems_id id, + rtems_interval ticks, + rtems_timer_service_routine_entry routine, + void *user_data + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the timer identifier. + +``ticks`` + This parameter is the interval until the routine is fired in clock ticks. + +``routine`` + This parameter is the routine to schedule. + +``user_data`` + This parameter is the argument passed to the routine when it is fired. + +.. rubric:: DESCRIPTION: + +This directive initiates the timer specified by ``id``. If the timer is +running, it is automatically canceled before being initiated. The timer is +scheduled to fire after an interval of clock ticks has passed specified by +``ticks``. When the timer fires, the timer service routine ``routine`` will be +invoked with the argument ``user_data`` in the context of the clock tick +:term:`ISR`. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_NUMBER` + The ``ticks`` parameter was 0. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``routine`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no timer associated with the identifier specified by ``id``. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/timer/if/fire-when + +.. raw:: latex + + \clearpage + +.. index:: rtems_timer_fire_when() +.. index:: fire a timer at time of day + +.. _InterfaceRtemsTimerFireWhen: + +rtems_timer_fire_when() +----------------------- + +Fires the timer at the time of day. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_timer_fire_when( + rtems_id id, + const rtems_time_of_day *wall_time, + rtems_timer_service_routine_entry routine, + void *user_data + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the timer identifier. + +``wall_time`` + This parameter is the time of day when the routine is fired. + +``routine`` + This parameter is the routine to schedule. + +``user_data`` + This parameter is the argument passed to the routine when it is fired. + +.. rubric:: DESCRIPTION: + +This directive initiates the timer specified by ``id``. If the timer is +running, it is automatically canceled before being initiated. The timer is +scheduled to fire at the time of day specified by ``wall_time``. When the +timer fires, the timer service routine ``routine`` will be invoked with the +argument ``user_data`` in the context of the clock tick :term:`ISR`. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_NOT_DEFINED` + The system date and time was not set. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``routine`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``wall_time`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_CLOCK` + The time of day was invalid. + +:c:macro:`RTEMS_INVALID_ID` + There was no timer associated with the identifier specified by ``id``. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/timer/if/initiate-server + +.. raw:: latex + + \clearpage + +.. index:: rtems_timer_initiate_server() +.. index:: initiate the Timer Server + +.. _InterfaceRtemsTimerInitiateServer: + +rtems_timer_initiate_server() +----------------------------- + +Initiates the Timer Server. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_timer_initiate_server( + rtems_task_priority priority, + size_t stack_size, + rtems_attribute attribute_set + ); + +.. rubric:: PARAMETERS: + +``priority`` + This parameter is the task priority. + +``stack_size`` + This parameter is the task stack size in bytes. + +``attribute_set`` + This parameter is the task attribute set. + +.. rubric:: DESCRIPTION: + +This directive initiates the Timer Server task. This task is responsible for +executing all timers initiated via the +:ref:`InterfaceRtemsTimerServerFireAfter` or +:ref:`InterfaceRtemsTimerServerFireWhen` directives. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INCORRECT_STATE` + The Timer Server was already initiated. + +:c:macro:`RTEMS_INVALID_PRIORITY` + The task priority was invalid. + +:c:macro:`RTEMS_TOO_MANY` + There was no inactive task object available to create the Timer Server + task. + +:c:macro:`RTEMS_UNSATISFIED` + There was not enough memory to allocate the task storage area. The task + storage area contains the task stack, the thread-local storage, and the + floating point context. + +:c:macro:`RTEMS_UNSATISFIED` + One of the task create extensions failed to create the Timer Server task. + +.. rubric:: NOTES: + +The Timer Server task is created using the :ref:`InterfaceRtemsTaskCreate` +directive and must be accounted for when configuring the system. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The number of timers available to the application is configured through the + :ref:`CONFIGURE_MAXIMUM_TIMERS` application configuration option. + +* Where the object class corresponding to the directive is configured to use + unlimited objects, the directive may allocate memory from the RTEMS + Workspace. + +.. Generated from spec:/rtems/timer/if/server-fire-after + +.. raw:: latex + + \clearpage + +.. index:: rtems_timer_server_fire_after() +.. index:: fire task-based a timer after an interval + +.. _InterfaceRtemsTimerServerFireAfter: + +rtems_timer_server_fire_after() +------------------------------- + +Fires the timer after the interval using the Timer Server. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_timer_server_fire_after( + rtems_id id, + rtems_interval ticks, + rtems_timer_service_routine_entry routine, + void *user_data + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the timer identifier. + +``ticks`` + This parameter is the interval until the routine is fired in clock ticks. + +``routine`` + This parameter is the routine to schedule. + +``user_data`` + This parameter is the argument passed to the routine when it is fired. + +.. rubric:: DESCRIPTION: + +This directive initiates the timer specified by ``id``. If the timer is +running, it is automatically canceled before being initiated. The timer is +scheduled to fire after an interval of clock ticks has passed specified by +``ticks``. When the timer fires, the timer service routine ``routine`` will be +invoked with the argument ``user_data`` in the context of the Timer Server +task. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INCORRECT_STATE` + The Timer Server was not initiated. + +:c:macro:`RTEMS_INVALID_NUMBER` + The ``ticks`` parameter was 0. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``routine`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no timer associated with the identifier specified by ``id``. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/timer/if/server-fire-when + +.. raw:: latex + + \clearpage + +.. index:: rtems_timer_server_fire_when() +.. index:: fire a task-based timer at time of day + +.. _InterfaceRtemsTimerServerFireWhen: + +rtems_timer_server_fire_when() +------------------------------ + +Fires the timer at the time of day using the Timer Server. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_timer_server_fire_when( + rtems_id id, + const rtems_time_of_day *wall_time, + rtems_timer_service_routine_entry routine, + void *user_data + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the timer identifier. + +``wall_time`` + This parameter is the time of day when the routine is fired. + +``routine`` + This parameter is the routine to schedule. + +``user_data`` + This parameter is the argument passed to the routine when it is fired. + +.. rubric:: DESCRIPTION: + +This directive initiates the timer specified by ``id``. If the timer is +running, it is automatically canceled before being initiated. The timer is +scheduled to fire at the time of day specified by ``wall_time``. When the +timer fires, the timer service routine ``routine`` will be invoked with the +argument ``user_data`` in the context of the Timer Server task. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INCORRECT_STATE` + The Timer Server was not initiated. + +:c:macro:`RTEMS_NOT_DEFINED` + The system date and time was not set. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``routine`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``wall_time`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_CLOCK` + The time of day was invalid. + +:c:macro:`RTEMS_INVALID_ID` + There was no timer associated with the identifier specified by ``id``. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/timer/if/reset + +.. raw:: latex + + \clearpage + +.. index:: rtems_timer_reset() +.. index:: reset a timer + +.. _InterfaceRtemsTimerReset: + +rtems_timer_reset() +------------------- + +Resets the timer. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_timer_reset( rtems_id id ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the timer identifier. + +.. rubric:: DESCRIPTION: + +This directive resets the timer specified by ``id``. This timer must have been +previously initiated with either the :ref:`InterfaceRtemsTimerFireAfter` or +:ref:`InterfaceRtemsTimerServerFireAfter` directive. If active the timer is +canceled, after which the timer is reinitiated using the same interval and +timer service routine which the original :ref:`InterfaceRtemsTimerFireAfter` or +:ref:`InterfaceRtemsTimerServerFireAfter` directive used. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no timer associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_NOT_DEFINED` + The timer was not of the interval class. + +.. rubric:: NOTES: + +If the timer has not been used or the last usage of this timer was by a +:ref:`InterfaceRtemsTimerFireWhen` or :ref:`InterfaceRtemsTimerServerFireWhen` +directive, then the :c:macro:`RTEMS_NOT_DEFINED` error is returned. + +Restarting a cancelled after timer results in the timer being reinitiated with +its previous timer service routine and interval. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/timer/if/get-information + +.. raw:: latex + + \clearpage + +.. index:: rtems_timer_get_information() + +.. _InterfaceRtemsTimerGetInformation: + +rtems_timer_get_information() +----------------------------- + +Gets information about the timer. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_timer_get_information( + rtems_id id, + rtems_timer_information *the_info + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the timer identifier. + +``the_info`` + This parameter is the pointer to an :ref:`InterfaceRtemsTimerInformation` + object. When the directive call is successful, the information about the + timer will be stored in this object. + +.. rubric:: DESCRIPTION: + +This directive returns information about the timer. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``the_info`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no timer associated with the identifier specified by ``id``. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. diff --git a/c-user/timer/index.rst b/c-user/timer/index.rst new file mode 100644 index 0000000..b149f30 --- /dev/null +++ b/c-user/timer/index.rst @@ -0,0 +1,17 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 embedded brains GmbH & Co. KG + +.. index:: timers + +.. _RTEMSAPIClassicTimer: + +Timer Manager +************* + +.. toctree:: + + introduction + background + operations + directives diff --git a/c-user/timer/introduction.rst b/c-user/timer/introduction.rst new file mode 100644 index 0000000..4f35972 --- /dev/null +++ b/c-user/timer/introduction.rst @@ -0,0 +1,66 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/rtems/timer/if/group + +.. _TimerManagerIntroduction: + +Introduction +============ + +.. The following list was generated from: +.. spec:/rtems/timer/if/create +.. spec:/rtems/timer/if/ident +.. spec:/rtems/timer/if/cancel +.. spec:/rtems/timer/if/delete +.. spec:/rtems/timer/if/fire-after +.. spec:/rtems/timer/if/fire-when +.. spec:/rtems/timer/if/initiate-server +.. spec:/rtems/timer/if/server-fire-after +.. spec:/rtems/timer/if/server-fire-when +.. spec:/rtems/timer/if/reset +.. spec:/rtems/timer/if/get-information + +The Timer Manager provides support for timer facilities. The directives +provided by the Timer Manager are: + +* :ref:`InterfaceRtemsTimerCreate` - Creates a timer. + +* :ref:`InterfaceRtemsTimerIdent` - Identifies a timer by the object name. + +* :ref:`InterfaceRtemsTimerCancel` - Cancels the timer. + +* :ref:`InterfaceRtemsTimerDelete` - Deletes the timer. + +* :ref:`InterfaceRtemsTimerFireAfter` - Fires the timer after the interval. + +* :ref:`InterfaceRtemsTimerFireWhen` - Fires the timer at the time of day. + +* :ref:`InterfaceRtemsTimerInitiateServer` - Initiates the Timer Server. + +* :ref:`InterfaceRtemsTimerServerFireAfter` - Fires the timer after the + interval using the Timer Server. + +* :ref:`InterfaceRtemsTimerServerFireWhen` - Fires the timer at the time of day + using the Timer Server. + +* :ref:`InterfaceRtemsTimerReset` - Resets the timer. + +* :ref:`InterfaceRtemsTimerGetInformation` - Gets information about the timer. diff --git a/c-user/timer/operations.rst b/c-user/timer/operations.rst new file mode 100644 index 0000000..8a6404f --- /dev/null +++ b/c-user/timer/operations.rst @@ -0,0 +1,84 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Operations +========== + +Creating a Timer +---------------- + +The ``rtems_timer_create`` directive creates a timer by allocating a Timer +Control Block (TMCB), assigning the timer a user-specified name, and assigning +it a timer ID. Newly created timers do not have a timer service routine +associated with them and are not active. + +Obtaining Timer IDs +------------------- + +When a timer is created, RTEMS generates a unique timer ID and assigns it to +the created timer until it is deleted. The timer ID may be obtained by either +of two methods. First, as the result of an invocation of the +``rtems_timer_create`` directive, the timer ID is stored in a user provided +location. Second, the timer ID may be obtained later using the +``rtems_timer_ident`` directive. The timer ID is used by other directives to +manipulate this timer. + +Initiating an Interval Timer +---------------------------- + +The ``rtems_timer_fire_after`` and ``rtems_timer_server_fire_after`` directives +initiate a timer to fire a user provided timer service routine after the +specified number of clock ticks have elapsed. When the interval has elapsed, +the timer service routine will be invoked from a clock tick +directive if it was initiated by the ``rtems_timer_fire_after`` directive and +from the Timer Server task if initiated by the +``rtems_timer_server_fire_after`` directive. + +Initiating a Time of Day Timer +------------------------------ + +The ``rtems_timer_fire_when`` and ``rtems_timer_server_fire_when`` directive +initiate a timer to fire a user provided timer service routine when the +specified time of day has been reached. When the interval has elapsed, the +timer service routine will be invoked from a clock tick directive +by the ``rtems_timer_fire_when`` directive and from the Timer Server task if +initiated by the ``rtems_timer_server_fire_when`` directive. + +Canceling a Timer +----------------- + +The ``rtems_timer_cancel`` directive is used to halt the specified timer. Once +canceled, the timer service routine will not fire unless the timer is +reinitiated. The timer can be reinitiated using the ``rtems_timer_reset``, +``rtems_timer_fire_after``, and ``rtems_timer_fire_when`` directives. + +Resetting a Timer +----------------- + +The ``rtems_timer_reset`` directive is used to restore an interval timer +initiated by a previous invocation of ``rtems_timer_fire_after`` or +``rtems_timer_server_fire_after`` to its original interval length. If the +timer has not been used or the last usage of this timer was by the +``rtems_timer_fire_when`` or ``rtems_timer_server_fire_when`` directive, then +an error is returned. The timer service routine is not changed or fired by +this directive. + +Initiating the Timer Server +--------------------------- + +The ``rtems_timer_initiate_server`` directive is used to allocate and start the +execution of the Timer Server task. The application can specify both the stack +size and attributes of the Timer Server. The Timer Server executes at a +priority higher than any application task and thus the user can expect to be +preempted as the result of executing the ``rtems_timer_initiate_server`` +directive. + +Deleting a Timer +---------------- + +The ``rtems_timer_delete`` directive is used to delete a timer. If the timer +is running and has not expired, the timer is automatically canceled. The +timer's control block is returned to the TMCB free list when it is deleted. A +timer can be deleted by a task other than the task which created the timer. +Any subsequent references to the timer's name and ID are invalid. diff --git a/c-user/timer_manager.rst b/c-user/timer_manager.rst deleted file mode 100644 index fc5f79c..0000000 --- a/c-user/timer_manager.rst +++ /dev/null @@ -1,643 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-4.0 - -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) - -.. index:: timers - -Timer Manager -************* - -Introduction -============ - -The timer manager provides support for timer -facilities. The directives provided by the timer manager are: - -- rtems_timer_create_ - Create a timer - -- rtems_timer_ident_ - Get ID of a timer - -- rtems_timer_cancel_ - Cancel a timer - -- rtems_timer_delete_ - Delete a timer - -- rtems_timer_fire_after_ - Fire timer after interval - -- rtems_timer_fire_when_ - Fire timer when specified - -- rtems_timer_initiate_server_ - Initiate server for task-based timers - -- rtems_timer_server_fire_after_ - Fire task-based timer after interval - -- rtems_timer_server_fire_when_ - Fire task-based timer when specified - -- rtems_timer_reset_ - Reset an interval timer - -Background -========== - -Required Support ----------------- - -A clock tick is required to support the functionality provided by this manager. - -Timers ------- - -A timer is an RTEMS object which allows the application to schedule operations -to occur at specific times in the future. User supplied timer service routines -are invoked by either a clock tick directive or a special Timer -Server task when the timer fires. Timer service routines may perform any -operations or directives which normally would be performed by the application -code which invoked a clock tick directive. - -The timer can be used to implement watchdog routines which only fire to denote -that an application error has occurred. The timer is reset at specific points -in the application to ensure that the watchdog does not fire. Thus, if the -application does not reset the watchdog timer, then the timer service routine -will fire to indicate that the application has failed to reach a reset point. -This use of a timer is sometimes referred to as a "keep alive" or a "deadman" -timer. - -Timer Server ------------- - -The Timer Server task is responsible for executing the timer service routines -associated with all task-based timers. This task executes at a priority -specified by :ref:`rtems_timer_initiate_server() <rtems_timer_initiate_server>` -and it may have a priority of zero (the highest priority). In uniprocessor -configurations, it is created non-preemptible. - -By providing a mechanism where timer service routines execute in task rather -than interrupt space, the application is allowed a bit more flexibility in what -operations a timer service routine can perform. For example, the Timer Server -can be configured to have a floating point context in which case it would be -safe to perform floating point operations from a task-based timer. Most of the -time, executing floating point instructions from an interrupt service routine -is not considered safe. The timer service routines invoked by the Timer Server -may block, however, since this blocks the Timer Server itself, other timer -service routines that are already pending do not run until the blocked timer -service routine finished its work. - -The Timer Server is designed to remain blocked until a task-based timer fires. -This reduces the execution overhead of the Timer Server. - -.. index:: rtems_timer_service_routine - -Timer Service Routines ----------------------- - -The timer service routine should adhere to C calling conventions and have a -prototype similar to the following: - -.. code-block:: c - - rtems_timer_service_routine user_routine( - rtems_id timer_id, - void *user_data - ); - -Where the timer_id parameter is the RTEMS object ID of the timer which is being -fired and user_data is a pointer to user-defined information which may be -utilized by the timer service routine. The argument user_data may be NULL. - -Operations -========== - -Creating a Timer ----------------- - -The ``rtems_timer_create`` directive creates a timer by allocating a Timer -Control Block (TMCB), assigning the timer a user-specified name, and assigning -it a timer ID. Newly created timers do not have a timer service routine -associated with them and are not active. - -Obtaining Timer IDs -------------------- - -When a timer is created, RTEMS generates a unique timer ID and assigns it to -the created timer until it is deleted. The timer ID may be obtained by either -of two methods. First, as the result of an invocation of the -``rtems_timer_create`` directive, the timer ID is stored in a user provided -location. Second, the timer ID may be obtained later using the -``rtems_timer_ident`` directive. The timer ID is used by other directives to -manipulate this timer. - -Initiating an Interval Timer ----------------------------- - -The ``rtems_timer_fire_after`` and ``rtems_timer_server_fire_after`` directives -initiate a timer to fire a user provided timer service routine after the -specified number of clock ticks have elapsed. When the interval has elapsed, -the timer service routine will be invoked from a clock tick -directive if it was initiated by the ``rtems_timer_fire_after`` directive and -from the Timer Server task if initiated by the -``rtems_timer_server_fire_after`` directive. - -Initiating a Time of Day Timer ------------------------------- - -The ``rtems_timer_fire_when`` and ``rtems_timer_server_fire_when`` directive -initiate a timer to fire a user provided timer service routine when the -specified time of day has been reached. When the interval has elapsed, the -timer service routine will be invoked from a clock tick directive -by the ``rtems_timer_fire_when`` directive and from the Timer Server task if -initiated by the ``rtems_timer_server_fire_when`` directive. - -Canceling a Timer ------------------ - -The ``rtems_timer_cancel`` directive is used to halt the specified timer. Once -canceled, the timer service routine will not fire unless the timer is -reinitiated. The timer can be reinitiated using the ``rtems_timer_reset``, -``rtems_timer_fire_after``, and ``rtems_timer_fire_when`` directives. - -Resetting a Timer ------------------ - -The ``rtems_timer_reset`` directive is used to restore an interval timer -initiated by a previous invocation of ``rtems_timer_fire_after`` or -``rtems_timer_server_fire_after`` to its original interval length. If the -timer has not been used or the last usage of this timer was by the -``rtems_timer_fire_when`` or ``rtems_timer_server_fire_when`` directive, then -an error is returned. The timer service routine is not changed or fired by -this directive. - -Initiating the Timer Server ---------------------------- - -The ``rtems_timer_initiate_server`` directive is used to allocate and start the -execution of the Timer Server task. The application can specify both the stack -size and attributes of the Timer Server. The Timer Server executes at a -priority higher than any application task and thus the user can expect to be -preempted as the result of executing the ``rtems_timer_initiate_server`` -directive. - -Deleting a Timer ----------------- - -The ``rtems_timer_delete`` directive is used to delete a timer. If the timer -is running and has not expired, the timer is automatically canceled. The -timer's control block is returned to the TMCB free list when it is deleted. A -timer can be deleted by a task other than the task which created the timer. -Any subsequent references to the timer's name and ID are invalid. - -Directives -========== - -This section details the timer manager's directives. A subsection is dedicated -to each of this manager's directives and describes the calling sequence, -related constants, usage, and status codes. - -.. raw:: latex - - \clearpage -.. index:: create a timer -.. index:: rtems_timer_create - -.. _rtems_timer_create: - -TIMER_CREATE - Create a timer ------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_timer_create( - rtems_name name, - rtems_id *id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - timer created successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``id`` is NULL - * - ``RTEMS_INVALID_NAME`` - - invalid timer name - * - ``RTEMS_TOO_MANY`` - - too many timers created - -DESCRIPTION: - This directive creates a timer. The assigned timer id is returned in id. - This id is used to access the timer with other timer manager directives. - For control and maintenance of the timer, RTEMS allocates a TMCB from the - local TMCB free pool and initializes it. - -NOTES: - This directive will obtain the allocator mutex and may cause the calling - task to be preempted. - - In SMP configurations, the processor of the currently executing thread - determines the processor used for the created timer. During the life-time - of the timer this processor is used to manage the timer internally. - -.. raw:: latex - - \clearpage - -.. index:: obtain the ID of a timer -.. index:: rtems_timer_ident - -.. _rtems_timer_ident: - -TIMER_IDENT - Get ID of a timer -------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_timer_ident( - rtems_name name, - rtems_id *id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - timer identified successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``id`` is NULL - * - ``RTEMS_INVALID_NAME`` - - timer name not found - -DESCRIPTION: - This directive obtains the timer id associated with the timer name to be - acquired. If the timer name is not unique, then the timer id will match - one of the timers with that name. However, this timer id is not guaranteed - to correspond to the desired timer. The timer id is used to access this - timer in other timer related directives. - -NOTES: - This directive will not cause the running task to be preempted. - -.. raw:: latex - - \clearpage - -.. index:: cancel a timer -.. index:: rtems_timer_cancel - -.. _rtems_timer_cancel: - -TIMER_CANCEL - Cancel a timer ------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_timer_cancel( - rtems_id id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - timer canceled successfully - * - ``RTEMS_INVALID_ID`` - - invalid timer id - -DESCRIPTION: - This directive cancels the timer id. This timer will be reinitiated by the - next invocation of ``rtems_timer_reset``, ``rtems_timer_fire_after``, or - ``rtems_timer_fire_when`` with this id. - -NOTES: - This directive will not cause the running task to be preempted. - -.. raw:: latex - - \clearpage - -.. index:: delete a timer -.. index:: rtems_timer_delete - -.. _rtems_timer_delete: - -TIMER_DELETE - Delete a timer ------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_timer_delete( - rtems_id id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - timer deleted successfully - * - ``RTEMS_INVALID_ID`` - - invalid timer id - -DESCRIPTION: - This directive deletes the timer specified by id. If the timer is running, - it is automatically canceled. The TMCB for the deleted timer is reclaimed - by RTEMS. - -NOTES: - This directive will obtain the allocator mutex and may cause the calling - task to be preempted. - - A timer can be deleted by a task other than the task which created the - timer. - -.. raw:: latex - - \clearpage - -.. index:: fire a timer after an interval -.. index:: rtems_timer_fire_after - -.. _rtems_timer_fire_after: - -TIMER_FIRE_AFTER - Fire timer after interval --------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_timer_fire_after( - rtems_id id, - rtems_interval ticks, - rtems_timer_service_routine_entry routine, - void *user_data - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - timer initiated successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``routine`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid timer id - * - ``RTEMS_INVALID_NUMBER`` - - invalid interval - -DESCRIPTION: - This directive initiates the timer specified by id. If the timer is - running, it is automatically canceled before being initiated. The timer is - scheduled to fire after an interval ticks clock ticks has passed. When the - timer fires, the timer service routine routine will be invoked with the - argument user_data. - -NOTES: - This directive will not cause the running task to be preempted. - -.. raw:: latex - - \clearpage - -.. index:: fire a timer at wall time -.. index:: rtems_timer_fire_when - -.. _rtems_timer_fire_when: - -TIMER_FIRE_WHEN - Fire timer when specified -------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_timer_fire_when( - rtems_id id, - rtems_time_of_day *wall_time, - rtems_timer_service_routine_entry routine, - void *user_data - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - timer initiated successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``routine`` is NULL - * - ``RTEMS_INVALID_ADDRESS`` - - ``wall_time`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid timer id - * - ``RTEMS_NOT_DEFINED`` - - system date and time is not set - * - ``RTEMS_INVALID_CLOCK`` - - invalid time of day - -DESCRIPTION: - This directive initiates the timer specified by id. If the timer is - running, it is automatically canceled before being initiated. The timer is - scheduled to fire at the time of day specified by wall_time. When the - timer fires, the timer service routine routine will be invoked with the - argument user_data. - -NOTES: - This directive will not cause the running task to be preempted. - -.. raw:: latex - - \clearpage - -.. index:: initiate the Timer Server -.. index:: rtems_timer_initiate_server - -.. _rtems_timer_initiate_server: - -TIMER_INITIATE_SERVER - Initiate server for task-based timers -------------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_timer_initiate_server( - uint32_t priority, - uint32_t stack_size, - rtems_attribute attribute_set - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - Timer Server initiated successfully - * - ``RTEMS_TOO_MANY`` - - too many tasks created - -DESCRIPTION: - This directive initiates the Timer Server task. This task is responsible - for executing all timers initiated via the - ``rtems_timer_server_fire_after`` or ``rtems_timer_server_fire_when`` - directives. - -NOTES: - This directive could cause the calling task to be preempted. - - The Timer Server task is created using the ``rtems_task_create`` service - and must be accounted for when configuring the system. - - Even through this directive invokes the ``rtems_task_create`` and - ``rtems_task_start`` directives, it should only fail due to resource - allocation problems. - -.. raw:: latex - - \clearpage - -.. index:: fire task-based a timer after an interval -.. index:: rtems_timer_server_fire_after - -.. _rtems_timer_server_fire_after: - -TIMER_SERVER_FIRE_AFTER - Fire task-based timer after interval --------------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_timer_server_fire_after( - rtems_id id, - rtems_interval ticks, - rtems_timer_service_routine_entry routine, - void *user_data - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - timer initiated successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``routine`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid timer id - * - ``RTEMS_INVALID_NUMBER`` - - invalid interval - * - ``RTEMS_INCORRECT_STATE`` - - Timer Server not initiated - -DESCRIPTION: - This directive initiates the timer specified by id and specifies that when - it fires it will be executed by the Timer Server. - - If the timer is running, it is automatically canceled before being - initiated. The timer is scheduled to fire after an interval ticks clock - ticks has passed. When the timer fires, the timer service routine routine - will be invoked with the argument user_data. - -NOTES: - This directive will not cause the running task to be preempted. - -.. raw:: latex - - \clearpage - -.. index:: fire a task-based timer at wall time -.. index:: rtems_timer_server_fire_when - -.. _rtems_timer_server_fire_when: - -TIMER_SERVER_FIRE_WHEN - Fire task-based timer when specified -------------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_timer_server_fire_when( - rtems_id id, - rtems_time_of_day *wall_time, - rtems_timer_service_routine_entry routine, - void *user_data - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - timer initiated successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``routine`` is NULL - * - ``RTEMS_INVALID_ADDRESS`` - - ``wall_time`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid timer id - * - ``RTEMS_NOT_DEFINED`` - - system date and time is not set - * - ``RTEMS_INVALID_CLOCK`` - - invalid time of day - * - ``RTEMS_INCORRECT_STATE`` - - Timer Server not initiated - -DESCRIPTION: - This directive initiates the timer specified by id and specifies that when - it fires it will be executed by the Timer Server. - - If the timer is running, it is automatically canceled before being - initiated. The timer is scheduled to fire at the time of day specified by - wall_time. When the timer fires, the timer service routine routine will be - invoked with the argument user_data. - -NOTES: - This directive will not cause the running task to be preempted. - -.. raw:: latex - - \clearpage - -.. index:: reset a timer -.. index:: rtems_timer_reset - -.. _rtems_timer_reset: - -TIMER_RESET - Reset an interval timer -------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_timer_reset( - rtems_id id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - timer reset successfully - * - ``RTEMS_INVALID_ID`` - - invalid timer id - * - ``RTEMS_NOT_DEFINED`` - - attempted to reset a when or newly created timer - -DESCRIPTION: - This directive resets the timer associated with id. This timer must have - been previously initiated with either the ``rtems_timer_fire_after`` or - ``rtems_timer_server_fire_after`` directive. If active the timer is - canceled, after which the timer is reinitiated using the same interval and - timer service routine which the original ``rtems_timer_fire_after`` or - ``rtems_timer_server_fire_after`` directive used. - -NOTES: - If the timer has not been used or the last usage of this timer was by a - ``rtems_timer_fire_when`` or ``rtems_timer_server_fire_when`` directive, - then the ``RTEMS_NOT_DEFINED`` error is returned. - - Restarting a cancelled after timer results in the timer being reinitiated - with its previous timer service routine and interval. - - This directive will not cause the running task to be preempted. diff --git a/c-user/timespec_helpers.rst b/c-user/timespec_helpers.rst index f2ef5cd..bc39630 100644 --- a/c-user/timespec_helpers.rst +++ b/c-user/timespec_helpers.rst @@ -125,7 +125,7 @@ sequence, related constants, usage, and status codes. \clearpage .. index:: set struct timespec instance -.. index:: rtems_timespec_set +.. index:: rtems_timespec_set() .. _rtems_timespec_set: @@ -156,7 +156,7 @@ NOTES: \clearpage -.. index:: rtems_timespec_zero +.. index:: rtems_timespec_zero() .. _rtems_timespec_zero: @@ -184,7 +184,7 @@ NOTES: \clearpage -.. index:: rtems_timespec_is_valid +.. index:: rtems_timespec_is_valid() .. _rtems_timespec_is_valid: @@ -214,7 +214,7 @@ NOTES: \clearpage -.. index:: rtems_timespec_add_to +.. index:: rtems_timespec_add_to() .. _rtems_timespec_add_to: @@ -244,7 +244,7 @@ NOTES: \clearpage -.. index:: rtems_timespec_subtract +.. index:: rtems_timespec_subtract() .. _rtems_timespec_subtract: @@ -279,7 +279,7 @@ NOTES: \clearpage -.. index:: rtems_timespec_divide +.. index:: rtems_timespec_divide() .. _rtems_timespec_divide: @@ -320,7 +320,7 @@ NOTES: \clearpage -.. index:: rtems_timespec_divide_by_integer +.. index:: rtems_timespec_divide_by_integer() .. _rtems_timespec_divide_by_integer: @@ -352,7 +352,7 @@ NOTES: \clearpage -.. index:: rtems_timespec_less_than +.. index:: rtems_timespec_less_than() .. _rtems_timespec_less_than: @@ -383,7 +383,7 @@ NOTES: \clearpage -.. index:: rtems_timespec_greater_than +.. index:: rtems_timespec_greater_than() .. _rtems_timespec_greater_than: @@ -412,7 +412,7 @@ NOTES: \clearpage -.. index:: rtems_timespec_equal_to +.. index:: rtems_timespec_equal_to() .. _rtems_timespec_equal_to: @@ -441,7 +441,7 @@ NOTES: \clearpage -.. index:: rtems_timespec_get_seconds +.. index:: rtems_timespec_get_seconds() .. _rtems_timespec_get_seconds: @@ -470,7 +470,7 @@ NOTES: \clearpage -.. index:: rtems_timespec_get_nanoseconds +.. index:: rtems_timespec_get_nanoseconds() .. _rtems_timespec_get_nanoseconds: @@ -499,7 +499,7 @@ NOTES: \clearpage -.. index:: rtems_timespec_to_ticks +.. index:: rtems_timespec_to_ticks() .. _rtems_timespec_to_ticks: @@ -527,7 +527,7 @@ NOTES: \clearpage -.. index:: rtems_timespec_from_ticks +.. index:: rtems_timespec_from_ticks() .. _rtems_timespec_from_ticks: diff --git a/c-user/user_extensions.rst b/c-user/user-extensions/background.rst index 89b86fd..c1430a9 100644 --- a/c-user/user_extensions.rst +++ b/c-user/user-extensions/background.rst @@ -2,27 +2,6 @@ .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) -.. index:: user extensions - -.. _User Extensions Manager: - -User Extensions Manager -*********************** - -Introduction -============ - -The user extensions manager allows the application developer to augment the -executive by allowing them to supply extension routines which are invoked at -critical system events. The directives provided by the user extensions manager -are: - -- rtems_extension_create_ - Create an extension set - -- rtems_extension_ident_ - Get ID of an extension set - -- rtems_extension_delete_ - Delete an extension set - Background ========== @@ -130,15 +109,10 @@ and release the extension buffers. Order of Invocation ------------------- -The user extensions are invoked in either `forward` or `reverse` order. In -forward order, the user extensions of initial extension sets are invoked before -the user extensions of the dynamic extension sets. The forward order of -initial extension sets is defined by the initial extension sets table index. -The forward order of dynamic extension sets is defined by the order in which -the dynamic extension sets were created. The reverse order is defined -accordingly. By invoking the user extensions in this order, extensions can be -built upon one another. At the following system events, the user extensions -are invoked in `forward` order +The user extensions are invoked in either :term:`extension forward order` or +:term:`extension reverse order`. By invoking the user extensions in these +orders, extensions can be built upon one another. At the following system +events, the user extensions are invoked in `forward` order - thread creation, @@ -169,7 +143,7 @@ installed after the Standard C Library will operate correctly even if they utilize the C Library because the C Library's thread delete extension is invoked after that of the other thread delete extensions. -.. index:: rtems_task_create_extension +.. index:: rtems_task_create_extension() Thread Create Extension ----------------------- @@ -431,142 +405,3 @@ It is strongly advised to use initial extension sets to install a fatal error extension. Usually, the initial extension set of board support package provides a fatal error extension which resets the board. In this case, the dynamic fatal error extensions are not invoked. - -Directives -========== - -This section details the user extension manager's directives. A subsection is -dedicated to each of this manager's directives and describes the calling -sequence, related constants, usage, and status codes. - -.. raw:: latex - - \clearpage - -.. index:: create an extension set -.. index:: rtems_extension_create - -.. _rtems_extension_create: - -EXTENSION_CREATE - Create a extension set ------------------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_extension_create( - rtems_name name, - const rtems_extensions_table *table, - rtems_id *id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - extension set created successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``table`` or ``id`` are NULL - * - ``RTEMS_INVALID_NAME`` - - invalid extension set name - * - ``RTEMS_TOO_MANY`` - - too many extension sets created - -DESCRIPTION: - - This directive creates an extension set object and initializes it using the - specified extension set table. The assigned extension set identifier is - returned in :c:data:`id`. This identifier is used to access the extension - set with other user extension manager directives. For control and - maintenance of the extension set, RTEMS allocates an Extension Set Control - Block (ESCB) from the local ESCB free pool and initializes it. The - user-specified :c:data:`name` is assigned to the ESCB and may be used to - identify the extension set via - :ref:`rtems_extension_ident() <rtems_extension_ident>`. The extension set - specified by :c:data:`table` is copied to the ESCB. - -NOTES: - - This directive will not cause the calling task to be preempted. - -.. raw:: latex - - \clearpage - -.. index:: get ID of an extension set -.. index:: obtain ID of an extension set -.. index:: rtems_extension_ident - -.. _rtems_extension_ident: - -EXTENSION_IDENT - Get ID of a extension set -------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_extension_ident( - rtems_name name, - rtems_id *id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - extension set identified successfully - * - ``RTEMS_INVALID_NAME`` - - extension set name not found - -DESCRIPTION: - This directive obtains the extension set identifier associated with the - extension set :c:data:`name` to be acquired and returns it in :c:data:`id`. - If the extension set name is not unique, then the extension set identifier - will match one of the extension sets with that name. However, this - extension set identifier is not guaranteed to correspond to the desired - extension set. The extension set identifier is used to access this - extension set in other extension set related directives. - -NOTES: - This directive will not cause the running task to be preempted. - -.. raw:: latex - - \clearpage - -.. index:: delete an extension set -.. index:: rtems_extension_delete - -.. _rtems_extension_delete: - -EXTENSION_DELETE - Delete a extension set ------------------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_extension_delete( - rtems_id id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - extension set deleted successfully - * - ``RTEMS_INVALID_ID`` - - invalid extension set id - -DESCRIPTION: - This directive deletes the extension set specified by :c:data:`id`. If the - extension set is running, it is automatically canceled. The ESCB for the - deleted extension set is reclaimed by RTEMS. - -NOTES: - This directive will not cause the running task to be preempted. - - A extension set can be deleted by a task other than the task which created - the extension set. diff --git a/c-user/user-extensions/directives.rst b/c-user/user-extensions/directives.rst new file mode 100644 index 0000000..2c5648b --- /dev/null +++ b/c-user/user-extensions/directives.rst @@ -0,0 +1,265 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. _UserExtensionsManagerDirectives: + +Directives +========== + +This section details the directives of the User Extensions Manager. A +subsection is dedicated to each of this manager's directives and lists the +calling sequence, parameters, description, return values, and notes of the +directive. + +.. Generated from spec:/rtems/userext/if/create + +.. raw:: latex + + \clearpage + +.. index:: rtems_extension_create() +.. index:: create an extension set + +.. _InterfaceRtemsExtensionCreate: + +rtems_extension_create() +------------------------ + +Creates an extension set. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_extension_create( + rtems_name name, + const rtems_extensions_table *extension_table, + rtems_id *id + ); + +.. rubric:: PARAMETERS: + +``name`` + This parameter is the object name of the extension set. + +``extension_table`` + This parameter is the table with the extensions to be used by the extension + set. + +``id`` + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the identifier of the created extension + set will be stored in this object. + +.. rubric:: DESCRIPTION: + +This directive creates an extension set which resides on the local node. The +extension set has the user-defined object name specified in ``name``. The +assigned object identifier is returned in ``id``. This identifier is used to +access the extension set with other extension set related directives. + +The extension set is initialized using the extension table specified in +``extension_table``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_NAME` + The ``name`` parameter was invalid. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``extension_table`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``id`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_TOO_MANY` + There was no inactive object available to create an extension set. The + number of extension sets available to the application is configured through + the :ref:`CONFIGURE_MAXIMUM_USER_EXTENSIONS` application configuration + option. + +.. rubric:: NOTES: + +The user-provided extension table is not used after the return of the +directive. + +Each extension of the extension table is optional and may be `NULL +<https://en.cppreference.com/w/c/types/NULL>`_. All extensions except the task +switch extension of the extension table are atomically and immediately +installed. A task switch extension is separately installed after the other +extensions. The extensions of the extension table are invoked upon the next +system event supporting an extension. + +An alternative to dynamically created extension sets are initial extensions, +see :ref:`CONFIGURE_INITIAL_EXTENSIONS`. Initial extensions are recommended +for extension sets which provide a fatal error extension. + +For control and maintenance of the extension set, RTEMS allocates a +:term:`ESCB` from the local ESCB free pool and initializes it. + +.. 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. + +* The number of extension sets available to the application is configured + through the :ref:`CONFIGURE_MAXIMUM_USER_EXTENSIONS` application + configuration option. + +.. Generated from spec:/rtems/userext/if/delete + +.. raw:: latex + + \clearpage + +.. index:: rtems_extension_delete() +.. index:: delete an extension set + +.. _InterfaceRtemsExtensionDelete: + +rtems_extension_delete() +------------------------ + +Deletes the extension set. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_extension_delete( rtems_id id ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the extension set identifier. + +.. rubric:: DESCRIPTION: + +This directive deletes the extension set specified by ``id``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no extension set associated with the identifier specified by + ``id``. + +.. rubric:: NOTES: + +The :term:`ESCB` for the deleted extension set is reclaimed by RTEMS. + +.. 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. + +* The calling task does not have to be the task that created the object. Any + local task that knows the object identifier can delete the object. + +.. Generated from spec:/rtems/userext/if/ident + +.. raw:: latex + + \clearpage + +.. index:: rtems_extension_ident() + +.. _InterfaceRtemsExtensionIdent: + +rtems_extension_ident() +----------------------- + +Identifies an extension set by the object name. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_extension_ident( rtems_name name, rtems_id *id ); + +.. rubric:: PARAMETERS: + +``name`` + This parameter is the object name to look up. + +``id`` + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the object identifier of an object with + the specified name will be stored in this object. + +.. rubric:: DESCRIPTION: + +This directive obtains an extension set identifier associated with the +extension set name specified in ``name``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``id`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_NAME` + The ``name`` parameter was 0. + +:c:macro:`RTEMS_INVALID_NAME` + There was no object with the specified name on the local node. + +.. rubric:: NOTES: + +If the extension set name is not unique, then the extension set identifier will +match the first extension set with that name in the search order. However, this +extension set identifier is not guaranteed to correspond to the desired +extension set. + +The objects are searched from lowest to the highest index. Only the local node +is searched. + +The extension set identifier is used with other extension related directives to +access the extension set. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within device driver initialization context. + +* The directive will not cause the calling task to be preempted. diff --git a/c-user/user-extensions/index.rst b/c-user/user-extensions/index.rst new file mode 100644 index 0000000..54b0649 --- /dev/null +++ b/c-user/user-extensions/index.rst @@ -0,0 +1,16 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 embedded brains GmbH & Co. KG + +.. index:: user extensions + +.. _RTEMSAPIClassicUserext: + +User Extensions Manager +*********************** + +.. toctree:: + + introduction + background + directives diff --git a/c-user/user-extensions/introduction.rst b/c-user/user-extensions/introduction.rst new file mode 100644 index 0000000..fab79e7 --- /dev/null +++ b/c-user/user-extensions/introduction.rst @@ -0,0 +1,43 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/rtems/userext/if/group + +.. _UserExtensionsManagerIntroduction: + +Introduction +============ + +.. The following list was generated from: +.. spec:/rtems/userext/if/create +.. spec:/rtems/userext/if/delete +.. spec:/rtems/userext/if/ident + +The User Extensions Manager allows the application developer to augment the +executive by allowing them to supply extension routines which are invoked at +critical system events. The directives provided by the User Extensions Manager +are: + +* :ref:`InterfaceRtemsExtensionCreate` - Creates an extension set. + +* :ref:`InterfaceRtemsExtensionDelete` - Deletes the extension set. + +* :ref:`InterfaceRtemsExtensionIdent` - Identifies an extension set by the + object name. |