diff options
| author | Chris Johns <chrisj@rtems.org> | 2016-11-08 15:26:50 +1100 |
|---|---|---|
| committer | Chris Johns <chrisj@rtems.org> | 2016-11-08 15:28:32 +1100 |
| commit | 53bb72e99669750ecbd7a418047711a21e32ac40 (patch) | |
| tree | b0cd10cb72041c45696ae9540c406b83ed1e62cb /c-user | |
| parent | pdf: Format lists for directives to sit on the next line. (diff) | |
| download | rtems-docs-53bb72e99669750ecbd7a418047711a21e32ac40.tar.bz2 | |
c-user: Format the directives as descriptions.
This change combined with the element list change in latex generates
a much better looking PDF.
Add a page break before each directive to like th previous versions of the
manuals.
Diffstat (limited to 'c-user')
30 files changed, 7796 insertions, 8135 deletions
diff --git a/c-user/barrier_manager.rst b/c-user/barrier_manager.rst index 7e80879..653c98f 100644 --- a/c-user/barrier_manager.rst +++ b/c-user/barrier_manager.rst @@ -156,81 +156,84 @@ 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: BARRIER_CREATE - Create a barrier --------------------------------- .. index:: create a barrier - -**CALLING SEQUENCE:** - .. index:: rtems_barrier_create -.. 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) +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: @@ -238,84 +241,82 @@ BARRIER_IDENT - Get ID of a barrier ----------------------------------- .. index:: get ID of a barrier .. index:: obtain ID of a barrier - -**CALLING SEQUENCE:** - .. index:: rtems_barrier_ident -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_barrier_ident( - rtems_name name, - rtems_id *id - ); + rtems_status_code rtems_barrier_ident( + rtems_name name, + rtems_id *id + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. list-table:: - :class: rtems-table + * - ``RTEMS_SUCCESSFUL`` + - barrier identified successfully + * - ``RTEMS_INVALID_NAME`` + - barrier name not found + * - ``RTEMS_INVALID_NODE`` + - invalid node id - * - ``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. -**DESCRIPTION:** +NOTES: + This directive will not cause the running task to be preempted. -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. +.. raw:: latex -**NOTES:** - -This directive will not cause the running task to be preempted. + \clearpage .. _rtems_barrier_delete: BARRIER_DELETE - Delete a barrier --------------------------------- .. index:: delete a barrier - -**CALLING SEQUENCE:** - .. index:: rtems_barrier_delete -.. code-block:: c - - rtems_status_code rtems_barrier_delete( - rtems_id id - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_status_code rtems_barrier_delete( + rtems_id id + ); -.. list-table:: - :class: rtems-table +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table - * - ``RTEMS_SUCCESSFUL`` - - barrier deleted successfully - * - ``RTEMS_INVALID_ID`` - - invalid barrier id + * - ``RTEMS_SUCCESSFUL`` + - barrier deleted successfully + * - ``RTEMS_INVALID_ID`` + - invalid barrier id -**DESCRIPTION:** +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. -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. -**NOTES:** + 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. -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. +.. raw:: latex -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. + \clearpage .. _rtems_barrier_wait: @@ -323,71 +324,73 @@ BARRIER_OBTAIN - Acquire a barrier ---------------------------------- .. index:: obtain a barrier .. index:: lock a barrier - -**CALLING SEQUENCE:** - .. index:: rtems_barrier_wait -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_barrier_wait( - rtems_id id, - rtems_interval timeout - ); + rtems_status_code rtems_barrier_wait( + rtems_id id, + rtems_interval timeout + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. 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 - * - ``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: -**DESCRIPTION:** + This directive acquires the barrier 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 barrier to become + available or return immediately if the barrier is not currently available. + With either ``RTEMS_WAIT`` or ``RTEMS_NO_WAIT``, if the current barrier + count is positive, then it is decremented by one and the barrier is + successfully acquired by returning immediately with a successful return + code. -This directive acquires the barrier 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 barrier to become available or return -immediately if the barrier is not currently available. With either -``RTEMS_WAIT`` or ``RTEMS_NO_WAIT``, if the current barrier count is positive, -then it is decremented by one and the barrier is successfully acquired by -returning immediately with a successful return code. + 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. -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. + 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 forever. If the + barrier is available or the ``RTEMS_NO_WAIT`` option component is set, then + timeout is ignored. -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 forever. If the barrier -is available or the ``RTEMS_NO_WAIT`` option component is set, then timeout is -ignored. +NOTES: -**NOTES:** + The following barrier acquisition option constants are defined by RTEMS: -The following barrier acquisition option constants are defined by RTEMS: + .. list-table:: + :class: rtems-table -.. list-table:: - :class: rtems-table + * - ``RTEMS_WAIT`` + - task will wait for barrier (default) + * - ``RTEMS_NO_WAIT`` + - task should not wait - * - ``RTEMS_WAIT`` - - task will wait for barrier (default) - * - ``RTEMS_NO_WAIT`` - - task should not wait + A clock tick is required to support the timeout functionality of this + directive. -A clock tick is required to support the timeout functionality of this -directive. +.. raw:: latex + + \clearpage .. _rtems_barrier_release: @@ -395,35 +398,31 @@ BARRIER_RELEASE - Release a barrier ----------------------------------- .. index:: wait at a barrier .. index:: release a barrier - -**CALLING SEQUENCE:** - .. index:: rtems_barrier_release -.. code-block:: c - - rtems_status_code rtems_barrier_release( - rtems_id id, - uint32_t *released - ); - -**DIRECTIVE STATUS CODES:** - -.. list-table:: - :class: rtems-table +CALLING SEQUENCE: + .. code-block:: c - * - ``RTEMS_SUCCESSFUL`` - - barrier released successfully - * - ``RTEMS_INVALID_ID`` - - invalid barrier id + rtems_status_code rtems_barrier_release( + rtems_id id, + uint32_t *released + ); -**DESCRIPTION:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -This directive releases the barrier specified by id. All tasks waiting at the -barrier will be unblocked. If the running task's preemption mode is enabled -and one of the unblocked tasks has a higher priority than the running task. + * - ``RTEMS_SUCCESSFUL`` + - barrier released successfully + * - ``RTEMS_INVALID_ID`` + - invalid barrier id -**NOTES:** +DESCRIPTION: + This directive releases the barrier specified by id. All tasks waiting at + the barrier will be unblocked. If the running task's preemption mode is + enabled and one of the unblocked tasks has a higher priority than the + running task. -The calling task may be preempted if it causes a higher priority task to be -made ready for execution. +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/chains.rst b/c-user/chains.rst index caa3ffe..f427142 100644 --- a/c-user/chains.rst +++ b/c-user/chains.rst @@ -15,10 +15,6 @@ The Chains API is an interface to the Super Core (score) chain implementation. The Super Core uses chains for all list type functions. This includes wait queues and task queues. The Chains API provided by RTEMS is: -- ``rtems_chain_node`` - Chain node used in user objects - -- ``rtems_chain_control`` - Chain control node - - rtems_chain_initialize_ - initialize the chain with nodes - rtems_chain_initialize_empty_ - initialize the chain as empty @@ -217,657 +213,645 @@ The section details the Chains directives. .. COMMENT: Initialize this Chain With Nodes +.. raw:: latex + + \clearpage + .. _rtems_chain_initialize: Initialize Chain With Nodes --------------------------- .. index:: chain initialize - -**CALLING SEQUENCE:** - .. index:: rtems_chain_initialize -.. code-block:: c - - void rtems_chain_initialize( - rtems_chain_control *the_chain, - void *starting_address, - size_t number_nodes, - size_t node_size - ) +CALLING SEQUENCE: + .. code-block:: c -**RETURNS** + void rtems_chain_initialize( + rtems_chain_control *the_chain, + void *starting_address, + size_t number_nodes, + size_t node_size + ) -Returns nothing. +RETURNS: + Returns nothing. -**DESCRIPTION:** +DESCRIPTION: + This function take in a pointer to a chain control and initializes it to + contain a set of chain nodes. The chain will contain ``number_nodes`` + chain nodes from the memory pointed to by ``start_address``. Each node is + assumed to be ``node_size`` bytes. -This function take in a pointer to a chain control and initializes it to -contain a set of chain nodes. The chain will contain ``number_nodes`` chain -nodes from the memory pointed to by ``start_address``. Each node is assumed to -be ``node_size`` bytes. +NOTES: + This call will discard any nodes on the chain. -**NOTES:** + This call does NOT inititialize any user data on each node. -This call will discard any nodes on the chain. +.. COMMENT: Initialize this Chain as Empty -This call does NOT inititialize any user data on each node. +.. raw:: latex -.. COMMENT: Initialize this Chain as Empty + \clearpage .. _rtems_chain_initialize_empty: Initialize Empty ---------------- .. index:: chain initialize empty - -**CALLING SEQUENCE:** - .. index:: rtems_chain_initialize_empty -.. code-block:: c - - void rtems_chain_initialize_empty( - rtems_chain_control *the_chain - ); +CALLING SEQUENCE: + .. code-block:: c -**RETURNS** + void rtems_chain_initialize_empty( + rtems_chain_control *the_chain + ); -Returns nothing. +RETURNS: + Returns nothing. -**DESCRIPTION:** +DESCRIPTION: + This function take in a pointer to a chain control and initializes it to + empty. -This function take in a pointer to a chain control and initializes it to empty. +NOTES: + This call will discard any nodes on the chain. -**NOTES:** +.. raw:: latex -This call will discard any nodes on the chain. + \clearpage .. _rtems_chain_is_null_node: Is Null Node ? -------------- .. index:: chain is node null - -**CALLING SEQUENCE:** - .. index:: rtems_chain_is_null_node -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - bool rtems_chain_is_null_node( - const rtems_chain_node *the_node - ); + bool rtems_chain_is_null_node( + const rtems_chain_node *the_node + ); -**RETURNS** +RETURNS: + Returns ``true`` is the node point is NULL and ``false`` if the node is not + NULL. -Returns ``true`` is the node point is NULL and ``false`` if the node is not -NULL. +DESCRIPTION: + Tests the node to see if it is a NULL returning ``true`` if a null. -**DESCRIPTION:** +.. raw:: latex -Tests the node to see if it is a NULL returning ``true`` if a null. + \clearpage .. _rtems_chain_head: Head ---- .. index:: chain get head - -**CALLING SEQUENCE:** - .. index:: rtems_chain_head -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_chain_node *rtems_chain_head( - rtems_chain_control *the_chain - ) + rtems_chain_node *rtems_chain_head( + rtems_chain_control *the_chain + ) -**RETURNS** +RETURNS: + Returns the permanent head node of the chain. -Returns the permanent head node of the chain. +DESCRIPTION: + This function returns a pointer to the first node on the chain. -**DESCRIPTION:** +.. raw:: latex -This function returns a pointer to the first node on the chain. + \clearpage .. _rtems_chain_tail: Tail ---- .. index:: chain get tail - -**CALLING SEQUENCE:** - .. index:: rtems_chain_tail -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_chain_node *rtems_chain_tail( - rtems_chain_control *the_chain - ); + rtems_chain_node *rtems_chain_tail( + rtems_chain_control *the_chain + ); -**RETURNS** +RETURNS: + Returns the permanent tail node of the chain. -Returns the permanent tail node of the chain. +DESCRIPTION: + This function returns a pointer to the last node on the chain. -**DESCRIPTION:** +.. raw:: latex -This function returns a pointer to the last node on the chain. + \clearpage .. _rtems_chain_are_nodes_equal: Are Two Nodes Equal ? --------------------- .. index:: chare are nodes equal - -**CALLING SEQUENCE:** - .. index:: rtems_chain_are_nodes_equal -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - bool rtems_chain_are_nodes_equal( - const rtems_chain_node *left, - const rtems_chain_node *right - ); + bool rtems_chain_are_nodes_equal( + const rtems_chain_node *left, + const rtems_chain_node *right + ); -**RETURNS** +RETURNS: + This function returns ``true`` if the left node and the right node are + equal, and ``false`` otherwise. -This function returns ``true`` if the left node and the right node are equal, -and ``false`` otherwise. +DESCRIPTION: + This function returns ``true`` if the left node and the right node are + equal, and ``false`` otherwise. -**DESCRIPTION:** +.. raw:: latex -This function returns ``true`` if the left node and the right node are equal, -and ``false`` otherwise. + \clearpage .. _rtems_chain_is_empty: Is the Chain Empty ------------------ .. index:: chain is chain empty - -**CALLING SEQUENCE:** - .. index:: rtems_chain_is_empty -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - bool rtems_chain_is_empty( - rtems_chain_control *the_chain - ); + bool rtems_chain_is_empty( + rtems_chain_control *the_chain + ); -**RETURNS** +RETURNS: + This function returns ``true`` if there a no nodes on the chain and + ``false`` otherwise. -This function returns ``true`` if there a no nodes on the chain and ``false`` -otherwise. +DESCRIPTION: + This function returns ``true`` if there a no nodes on the chain and + ``false`` otherwise. -**DESCRIPTION:** +.. raw:: latex -This function returns ``true`` if there a no nodes on the chain and ``false`` -otherwise. + \clearpage .. _rtems_chain_is_first: Is this the First Node on the Chain ? ------------------------------------- .. index:: chain is node the first - -**CALLING SEQUENCE:** - .. index:: rtems_chain_is_first -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - bool rtems_chain_is_first( - const rtems_chain_node *the_node - ); + bool rtems_chain_is_first( + const rtems_chain_node *the_node + ); -**RETURNS** +RETURNS: + This function returns ``true`` if the node is the first node on a chain and + ``false`` otherwise. -This function returns ``true`` if the node is the first node on a chain and -``false`` otherwise. +DESCRIPTION: + This function returns ``true`` if the node is the first node on a chain and + ``false`` otherwise. -**DESCRIPTION:** +.. raw:: latex -This function returns ``true`` if the node is the first node on a chain and -``false`` otherwise. + \clearpage .. _rtems_chain_is_last: Is this the Last Node on the Chain ? ------------------------------------ .. index:: chain is node the last - -**CALLING SEQUENCE:** - .. index:: rtems_chain_is_last -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - bool rtems_chain_is_last( - const rtems_chain_node *the_node - ); + bool rtems_chain_is_last( + const rtems_chain_node *the_node + ); -**RETURNS** +RETURNS: + This function returns ``true`` if the node is the last node on a chain and + ``false`` otherwise. -This function returns ``true`` if the node is the last node on a chain and -``false`` otherwise. +DESCRIPTION: + This function returns ``true`` if the node is the last node on a chain and + ``false`` otherwise. -**DESCRIPTION:** +.. raw:: latex -This function returns ``true`` if the node is the last node on a chain and -``false`` otherwise. + \clearpage .. _rtems_chain_has_only_one_node: Does this Chain have only One Node ? ------------------------------------ .. index:: chain only one node - -**CALLING SEQUENCE:** - .. index:: rtems_chain_has_only_one_node -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - bool rtems_chain_has_only_one_node( - const rtems_chain_control *the_chain - ); + bool rtems_chain_has_only_one_node( + const rtems_chain_control *the_chain + ); -**RETURNS** +RETURNS: + This function returns ``true`` if there is only one node on the chain and + ``false`` otherwise. -This function returns ``true`` if there is only one node on the chain and -``false`` otherwise. +DESCRIPTION: + This function returns ``true`` if there is only one node on the chain and + ``false`` otherwise. -**DESCRIPTION:** +.. raw:: latex -This function returns ``true`` if there is only one node on the chain and -``false`` otherwise. + \clearpage .. _rtems_chain_node_count_unprotected: Returns the node count of the chain (unprotected) ------------------------------------------------- .. index:: chain only one node - -**CALLING SEQUENCE:** - .. index:: rtems_chain_node_count_unprotected -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - size_t rtems_chain_node_count_unprotected( - const rtems_chain_control *the_chain - ); + size_t rtems_chain_node_count_unprotected( + const rtems_chain_control *the_chain + ); -**RETURNS** +RETURNS: + This function returns the node count of the chain. -This function returns the node count of the chain. +DESCRIPTION: + This function returns the node count of the chain. -**DESCRIPTION:** +.. raw:: latex -This function returns the node count of the chain. + \clearpage .. _rtems_chain_is_head: Is this Node the Chain Head ? ----------------------------- .. index:: chain is node the head - -**CALLING SEQUENCE:** - .. index:: rtems_chain_is_head -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - bool rtems_chain_is_head( - rtems_chain_control *the_chain, - rtems_const chain_node *the_node - ); + bool rtems_chain_is_head( + rtems_chain_control *the_chain, + rtems_const chain_node *the_node + ); -**RETURNS** +RETURNS: + This function returns ``true`` if the node is the head of the chain and + ``false`` otherwise. -This function returns ``true`` if the node is the head of the chain and -``false`` otherwise. +DESCRIPTION: + This function returns ``true`` if the node is the head of the chain and + ``false`` otherwise. -**DESCRIPTION:** +.. raw:: latex -This function returns ``true`` if the node is the head of the chain and -``false`` otherwise. + \clearpage .. _rtems_chain_is_tail: Is this Node the Chain Tail ? ----------------------------- .. index:: chain is node the tail - -**CALLING SEQUENCE:** - .. index:: rtems_chain_is_tail -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - bool rtems_chain_is_tail( - rtems_chain_control *the_chain, - const rtems_chain_node *the_node - ) + bool rtems_chain_is_tail( + rtems_chain_control *the_chain, + const rtems_chain_node *the_node + ) -**RETURNS** +RETURNS: + This function returns ``true`` if the node is the tail of the chain and + ``false`` otherwise. -This function returns ``true`` if the node is the tail of the chain and -``false`` otherwise. +DESCRIPTION: + This function returns ``true`` if the node is the tail of the chain and + ``false`` otherwise. -**DESCRIPTION:** +.. raw:: latex -This function returns ``true`` if the node is the tail of the chain and -``false`` otherwise. + \clearpage .. _rtems_chain_extract: Extract a Node -------------- .. index:: chain extract a node - -**CALLING SEQUENCE:** - .. index:: rtems_chain_extract -.. code-block:: c - - void rtems_chain_extract( - rtems_chain_node *the_node - ); +CALLING SEQUENCE: + .. code-block:: c -**RETURNS** + void rtems_chain_extract( + rtems_chain_node *the_node + ); -Returns nothing. +RETURNS: + Returns nothing. -**DESCRIPTION:** +DESCRIPTION: + This routine extracts the node from the chain on which it resides. -This routine extracts the node from the chain on which it resides. +NOTES: + Interrupts are disabled while extracting the node to ensure the atomicity + of the operation. -**NOTES:** + Use ``rtems_chain_extract_unprotected`` to avoid disabling of interrupts. -Interrupts are disabled while extracting the node to ensure the atomicity of -the operation. +.. raw:: latex -Use rtems_chain_extract_unprotected_ to avoid disabling of interrupts. + \clearpage .. _rtems_chain_extract_unprotected: Extract a Node (unprotected) ---------------------------- .. index:: chain extract a node unprotected - -**CALLING SEQUENCE:** - .. index:: rtems_chain_extract_unprotected -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - void rtems_chain_extract_unprotected( - rtems_chain_node *the_node - ); + void rtems_chain_extract_unprotected( + rtems_chain_node *the_node + ); -**RETURNS** +RETURNS: + Returns nothing. -Returns nothing. +DESCRIPTION: + This routine extracts the node from the chain on which it resides. -**DESCRIPTION:** +NOTES: + The function does nothing to ensure the atomicity of the operation. -This routine extracts the node from the chain on which it resides. +.. raw:: latex -**NOTES:** - -The function does nothing to ensure the atomicity of the operation. + \clearpage .. _rtems_chain_get: Get the First Node ------------------ .. index:: chain get first node - -**CALLING SEQUENCE:** - .. index:: rtems_chain_get -.. code-block:: c - - rtems_chain_node *rtems_chain_get( - rtems_chain_control *the_chain - ); +CALLING SEQUENCE: + .. code-block:: c -**RETURNS** + rtems_chain_node *rtems_chain_get( + rtems_chain_control *the_chain + ); -Returns a pointer a node. If a node was removed, then a pointer to that node is -returned. If the chain was empty, then ``NULL`` is returned. +RETURNS: + Returns a pointer a node. If a node was removed, then a pointer to that + node is returned. If the chain was empty, then ``NULL`` is returned. -**DESCRIPTION:** +DESCRIPTION: + This function removes the first node from the chain and returns a pointer + to that node. If the chain is empty, then ``NULL`` is returned. -This function removes the first node from the chain and returns a pointer to -that node. If the chain is empty, then ``NULL`` is returned. +NOTES: + Interrupts are disabled while obtaining the node to ensure the atomicity of + the operation. -**NOTES:** + Use ``rtems_chain_get_unprotected()`` to avoid disabling of interrupts. -Interrupts are disabled while obtaining the node to ensure the atomicity of the -operation. +.. raw:: latex -Use ``rtems_chain_get_unprotected()`` to avoid disabling of interrupts. + \clearpage .. _rtems_chain_get_unprotected: Get the First Node (unprotected) -------------------------------- .. index:: chain get first node - -**CALLING SEQUENCE:** - .. index:: rtems_chain_get_unprotected -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_chain_node *rtems_chain_get_unprotected( - rtems_chain_control *the_chain - ); + rtems_chain_node *rtems_chain_get_unprotected( + rtems_chain_control *the_chain + ); -**RETURNS:** +RETURNS: + A pointer to the former first node is returned. -A pointer to the former first node is returned. +DESCRIPTION: + Removes the first node from the chain and returns a pointer to it. In case + the chain was empty, then the results are unpredictable. -**DESCRIPTION:** +NOTES: + The function does nothing to ensure the atomicity of the operation. -Removes the first node from the chain and returns a pointer to it. In case the -chain was empty, then the results are unpredictable. +.. raw:: latex -**NOTES:** - -The function does nothing to ensure the atomicity of the operation. + \clearpage .. _rtems_chain_insert: Insert a Node ------------- .. index:: chain insert a node - -**CALLING SEQUENCE:** - .. index:: rtems_chain_insert -.. code-block:: c - - void rtems_chain_insert( - rtems_chain_node *after_node, - rtems_chain_node *the_node - ); +CALLING SEQUENCE: + .. code-block:: c -**RETURNS** + void rtems_chain_insert( + rtems_chain_node *after_node, + rtems_chain_node *the_node + ); -Returns nothing. +RETURNS: + Returns nothing. -**DESCRIPTION:** +DESCRIPTION: + This routine inserts a node on a chain immediately following the specified + node. -This routine inserts a node on a chain immediately following the specified -node. +NOTES: + Interrupts are disabled during the insert to ensure the atomicity of the + operation. -**NOTES:** + Use ``rtems_chain_insert_unprotected()`` to avoid disabling of interrupts. -Interrupts are disabled during the insert to ensure the atomicity of the -operation. +.. raw:: latex -Use rtems_chain_insert_unprotected_ to avoid disabling of interrupts. + \clearpage .. _rtems_chain_insert_unprotected: Insert a Node (unprotected) --------------------------- .. index:: chain insert a node unprotected - -**CALLING SEQUENCE:** - .. index:: rtems_chain_insert_unprotected -.. code-block:: c - - void rtems_chain_insert_unprotected( - rtems_chain_node *after_node, - rtems_chain_node *the_node - ); +CALLING SEQUENCE: + .. code-block:: c -**RETURNS** + void rtems_chain_insert_unprotected( + rtems_chain_node *after_node, + rtems_chain_node *the_node + ); -Returns nothing. +RETURNS: + Returns nothing. -**DESCRIPTION:** +DESCRIPTION: + This routine inserts a node on a chain immediately following the specified + node. -This routine inserts a node on a chain immediately following the specified -node. +NOTES: + The function does nothing to ensure the atomicity of the operation. -**NOTES:** +.. raw:: latex -The function does nothing to ensure the atomicity of the operation. + \clearpage .. _rtems_chain_append: Append a Node ------------- .. index:: chain append a node - -**CALLING SEQUENCE:** - .. index:: rtems_chain_append -.. code-block:: c - - void rtems_chain_append( - rtems_chain_control *the_chain, - rtems_chain_node *the_node - ); +CALLING SEQUENCE: + .. code-block:: c -**RETURNS** + void rtems_chain_append( + rtems_chain_control *the_chain, + rtems_chain_node *the_node + ); -Returns nothing. +RETURNS: + Returns nothing. -**DESCRIPTION:** +DESCRIPTION: + This routine appends a node to the end of a chain. -This routine appends a node to the end of a chain. +NOTES: + Interrupts are disabled during the append to ensure the atomicity of the + operation. -**NOTES:** + Use ``rtems_chain_append_unprotected`` to avoid disabling of interrupts. -Interrupts are disabled during the append to ensure the atomicity of the -operation. +.. raw:: latex -Use rtems_chain_append_unprotected_ to avoid disabling of interrupts. + \clearpage .. _rtems_chain_append_unprotected: Append a Node (unprotected) --------------------------- .. index:: chain append a node unprotected - -**CALLING SEQUENCE:** - .. index:: rtems_chain_append_unprotected -.. code-block:: c - - void rtems_chain_append_unprotected( - rtems_chain_control *the_chain, - rtems_chain_node *the_node - ); +CALLING SEQUENCE: + .. code-block:: c -**RETURNS** + void rtems_chain_append_unprotected( + rtems_chain_control *the_chain, + rtems_chain_node *the_node + ); -Returns nothing. +RETURNS: + Returns nothing. -**DESCRIPTION:** +DESCRIPTION: + This routine appends a node to the end of a chain. -This routine appends a node to the end of a chain. +NOTES: + The function does nothing to ensure the atomicity of the operation. -**NOTES:** +.. raw:: latex -The function does nothing to ensure the atomicity of the operation. + \clearpage .. _rtems_chain_prepend: Prepend a Node -------------- .. index:: prepend node - -**CALLING SEQUENCE:** - .. index:: rtems_chain_prepend -.. code-block:: c - - void rtems_chain_prepend( - rtems_chain_control *the_chain, - rtems_chain_node *the_node - ); +CALLING SEQUENCE: + .. code-block:: c -**RETURNS** + void rtems_chain_prepend( + rtems_chain_control *the_chain, + rtems_chain_node *the_node + ); -Returns nothing. +RETURNS: + Returns nothing. -**DESCRIPTION:** +DESCRIPTION: + This routine prepends a node to the front of the chain. -This routine prepends a node to the front of the chain. +NOTES: + Interrupts are disabled during the prepend to ensure the atomicity of the + operation. -**NOTES:** + Use ``rtems_chain_prepend_unprotected`` to avoid disabling of interrupts. -Interrupts are disabled during the prepend to ensure the atomicity of the -operation. +.. raw:: latex -Use rtems_chain_prepend_unprotected_ to avoid disabling of -interrupts. + \clearpage .. _rtems_chain_prepend_unprotected: Prepend a Node (unprotected) ---------------------------- .. index:: prepend node unprotected - -**CALLING SEQUENCE:** - .. index:: rtems_chain_prepend_unprotected -.. code-block:: c - - void rtems_chain_prepend_unprotected( - rtems_chain_control *the_chain, - rtems_chain_node *the_node - ); - -**RETURNS** - -Returns nothing. +CALLING SEQUENCE: + .. code-block:: c -**DESCRIPTION:** + void rtems_chain_prepend_unprotected( + rtems_chain_control *the_chain, + rtems_chain_node *the_node + ); -This routine prepends a node to the front of the chain. +RETURNS: + Returns nothing. -**NOTES:** +DESCRIPTION: + This routine prepends a node to the front of the chain. -The function does nothing to ensure the atomicity of the operation. +NOTES: + The function does nothing to ensure the atomicity of the operation. diff --git a/c-user/clock_manager.rst b/c-user/clock_manager.rst index cd9140c..f27e66d 100644 --- a/c-user/clock_manager.rst +++ b/c-user/clock_manager.rst @@ -203,282 +203,290 @@ 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: CLOCK_SET - Set date and time ----------------------------- - -**CALLING SEQUENCE:** - .. index:: set the time of day - .. index:: rtems_clock_set -.. code-block:: c - - rtems_status_code rtems_clock_set( - rtems_time_of_day *time_buffer - ); - -**DIRECTIVE STATUS CODES:** +CALLING SEQUENCE: + .. code-block:: c -``RTEMS_SUCCESSFUL`` - date and time set successfully + rtems_status_code rtems_clock_set( + rtems_time_of_day *time_buffer + ); -``RTEMS_INVALID_ADDRESS`` - ``time_buffer`` is NULL +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -``RTEMS_INVALID_CLOCK`` - invalid time of day + * - ``RTEMS_SUCCESSFUL`` + - date and time set successfully + * - ``RTEMS_INVALID_ADDRESS`` + - ``time_buffer`` is NULL + * - ``RTEMS_INVALID_CLOCK`` + - invalid time of day -**DESCRIPTION:** +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. -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. -**NOTES:** + The system date and time are based on the configured tick rate (number of + microseconds in a tick). -Years before 1988 are invalid. + 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. -The system date and time are based on the configured tick rate (number of -microseconds in a 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. -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. +.. raw:: latex -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. + \clearpage .. _rtems_clock_get: CLOCK_GET - Get date and time information ----------------------------------------- .. index:: obtain the time of day +.. index:: rtems_clock_get .. warning:: This directive is deprecated and will be removed. -**CALLING SEQUENCE:** - -.. index:: rtems_clock_get - -.. code-block:: c - - rtems_status_code rtems_clock_get( - rtems_clock_get_options option, - void *time_buffer - ); - -**DIRECTIVE STATUS CODES:** - -``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. +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. + +.. raw:: latex + + \clearpage .. _rtems_clock_get_tod: CLOCK_GET_TOD - Get date and time in TOD format ----------------------------------------------- .. index:: obtain the time of day - -**CALLING SEQUENCE:** - .. index:: rtems_clock_get_tod -.. code-block:: c - - rtems_status_code rtems_clock_get_tod( - rtems_time_of_day *time_buffer - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_status_code rtems_clock_get_tod( + rtems_time_of_day *time_buffer + ); -``RTEMS_SUCCESSFUL`` - current time obtained successfully +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -``RTEMS_NOT_DEFINED`` - system date and time is not set + * - ``RTEMS_SUCCESSFUL`` + - current time obtained successfully + * - ``RTEMS_NOT_DEFINED`` + - system date and time is not set + * - ``RTEMS_INVALID_ADDRESS`` + - ``time_buffer`` is NULL -``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. -**DESCRIPTION:** +NOTES: + This directive is callable from an ISR. -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. + 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. -**NOTES:** +.. raw:: latex -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. + \clearpage .. _rtems_clock_get_tod_timeval: CLOCK_GET_TOD_TIMEVAL - Get date and time in timeval format ----------------------------------------------------------- .. index:: obtain the time of day - -**CALLING SEQUENCE:** - .. index:: rtems_clock_get_tod_timeval -.. code-block:: c - - rtems_status_code rtems_clock_get_tod_interval( - struct timeval *time - ); - -**DIRECTIVE STATUS CODES:** - -``RTEMS_SUCCESSFUL`` - current time obtained successfully +CALLING SEQUENCE: + .. code-block:: c -``RTEMS_NOT_DEFINED`` - system date and time is not set + rtems_status_code rtems_clock_get_tod_interval( + struct timeval *time + ); -``RTEMS_INVALID_ADDRESS`` - ``time`` is NULL +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:** +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. -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. -**NOTES:** + 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. -This directive is callable from an ISR. +.. raw:: latex -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. + \clearpage .. _rtems_clock_get_seconds_since_epoch: CLOCK_GET_SECONDS_SINCE_EPOCH - Get seconds since epoch ------------------------------------------------------- .. index:: obtain seconds since epoch - -**CALLING SEQUENCE:** - .. index:: rtems_clock_get_seconds_since_epoch -.. code-block:: c - - rtems_status_code rtems_clock_get_seconds_since_epoch( - rtems_interval *the_interval - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_status_code rtems_clock_get_seconds_since_epoch( + rtems_interval *the_interval + ); -``RTEMS_SUCCESSFUL`` - current time obtained successfully +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 -``RTEMS_NOT_DEFINED`` - system date and time is not set +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. -``RTEMS_INVALID_ADDRESS`` - ``the_interval`` is NULL +NOTES: + This directive is callable from an ISR. -**DESCRIPTION:** + 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. -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. +.. raw:: latex -**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. + \clearpage .. _rtems_clock_get_ticks_per_second: CLOCK_GET_TICKS_PER_SECOND - Get ticks per second ------------------------------------------------- .. index:: obtain seconds since epoch - -**CALLING SEQUENCE:** - .. index:: rtems_clock_get_ticks_per_second -.. code-block:: c - - rtems_interval rtems_clock_get_ticks_per_second(void); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_interval rtems_clock_get_ticks_per_second(void); -NONE +DIRECTIVE STATUS CODES: + NONE -**DESCRIPTION:** +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. -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. -**NOTES:** + This directive will not cause the running task to be preempted. -This directive is callable from an ISR. +.. raw:: latex -This directive will not cause the running task to be preempted. + \clearpage .. _rtems_clock_get_ticks_since_boot: @@ -486,123 +494,123 @@ CLOCK_GET_TICKS_SINCE_BOOT - Get current ticks counter value ------------------------------------------------------------ .. index:: obtain ticks since boot .. index:: get current ticks counter value - -**CALLING SEQUENCE:** - .. index:: rtems_clock_get_ticks_since_boot -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c + + rtems_interval rtems_clock_get_ticks_since_boot(void); - rtems_interval rtems_clock_get_ticks_since_boot(void); +DIRECTIVE STATUS CODES: + NONE -**DIRECTIVE STATUS CODES:** +DESCRIPTION: -NONE + 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. -**DESCRIPTION:** +NOTES: -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. + This directive is callable from an ISR. -**NOTES:** + This directive will not cause the running task to be preempted. -This directive is callable from an ISR. +.. raw:: latex -This directive will not cause the running task to be preempted. + \clearpage .. _rtems_clock_tick_later: CLOCK_TICK_LATER - Get tick value in the future ----------------------------------------------- - -**CALLING SEQUENCE:** - .. index:: rtems_clock_tick_later -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_interval rtems_clock_tick_later( - rtems_interval delta - ); + rtems_interval rtems_clock_tick_later( + rtems_interval delta + ); -**DESCRIPTION:** +DESCRIPTION: + Returns the ticks counter value delta ticks in the future. -Returns the ticks counter value delta ticks in the future. +NOTES: + This directive is callable from an ISR. -**NOTES:** + This directive will not cause the running task to be preempted. -This directive is callable from an ISR. +.. raw:: latex -This directive will not cause the running task to be preempted. + \clearpage .. _rtems_clock_tick_later_usec: CLOCK_TICK_LATER_USEC - Get tick value in the future in microseconds -------------------------------------------------------------------- - -**CALLING SEQUENCE:** - .. index:: rtems_clock_tick_later_usec -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_interval rtems_clock_tick_later_usec( - rtems_interval delta_in_usec - ); + rtems_interval rtems_clock_tick_later_usec( + rtems_interval delta_in_usec + ); -**DESCRIPTION:** +DESCRIPTION: + Returns the ticks counter value at least delta microseconds in the future. -Returns the ticks counter value at least delta microseconds in the future. +NOTES: + This directive is callable from an ISR. -**NOTES:** + This directive will not cause the running task to be preempted. -This directive is callable from an ISR. +.. raw:: latex -This directive will not cause the running task to be preempted. + \clearpage .. _rtems_clock_tick_before: CLOCK_TICK_BEFORE - Is tick value is before a point in time ----------------------------------------------------------- - -**CALLING SEQUENCE:** - .. index:: rtems_clock_tick_before -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_interval rtems_clock_tick_before( - rtems_interval tick - ); + rtems_interval rtems_clock_tick_before( + rtems_interval tick + ); -**DESCRIPTION:** +DESCRIPTION: + Returns true if the current ticks counter value indicates a time before the + time specified by the tick value and false otherwise. -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. -**NOTES:** + This directive will not cause the running task to be preempted. -This directive is callable from an ISR. +EXAMPLE: + .. code-block:: c -This directive will not cause the running task to be preempted. + 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; + } -**EXAMPLE:** +.. raw:: latex -.. 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; - } + \clearpage .. _rtems_clock_get_uptime: @@ -610,34 +618,34 @@ CLOCK_GET_UPTIME - Get the time since boot ------------------------------------------ .. index:: clock get uptime .. index:: uptime - -**CALLING SEQUENCE:** - .. index:: rtems_clock_get_uptime -.. code-block:: c - - rtems_status_code rtems_clock_get_uptime( - struct timespec *uptime - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_status_code rtems_clock_get_uptime( + struct timespec *uptime + ); -``RTEMS_SUCCESSFUL`` - clock tick processed successfully +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + * - ``RTEMS_SUCCESSFUL`` + - clock tick processed successfully + * - ``RTEMS_INVALID_ADDRESS`` + - ``time_buffer`` is ``NULL`` -``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. -**DESCRIPTION:** +NOTES: + This directive may be called from an ISR. -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. +.. raw:: latex -**NOTES:** - -This directive may be called from an ISR. + \clearpage .. _rtems_clock_get_uptime_timeval: @@ -645,30 +653,29 @@ CLOCK_GET_UPTIME_TIMEVAL - Get the time since boot in timeval format -------------------------------------------------------------------- .. index:: clock get uptime interval .. index:: uptime - -**CALLING SEQUENCE:** - .. index:: rtems_clock_get_uptime_timeval -.. code-block:: c - - void rtems_clock_get_uptime_timeval( - struct timeval *uptime - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + void rtems_clock_get_uptime_timeval( + struct timeval *uptime + ); -NONE +DIRECTIVE STATUS CODES: + NONE -**DESCRIPTION:** +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. -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. -**NOTES:** +.. raw:: latex -This directive may be called from an ISR. + \clearpage .. _rtems_clock_get_uptime_seconds: @@ -676,26 +683,26 @@ CLOCK_GET_UPTIME_SECONDS - Get the seconds since boot ----------------------------------------------------- .. index:: clock get uptime seconds .. index:: uptime - -**CALLING SEQUENCE:** - .. index:: rtems_clock_get_uptime_seconds -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - time_t rtems_clock_get_uptime_seconds(void); + time_t rtems_clock_get_uptime_seconds(void); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + The system uptime in seconds. -The system uptime in seconds. +DESCRIPTION: -**DESCRIPTION:** + This directive returns the seconds since the system was booted. -This directive returns the seconds since the system was booted. +NOTES: + This directive may be called from an ISR. -**NOTES:** +.. raw:: latex -This directive may be called from an ISR. + \clearpage .. _rtems_clock_get_uptime_nanoseconds: @@ -703,23 +710,18 @@ CLOCK_GET_UPTIME_NANOSECONDS - Get the nanoseconds since boot ------------------------------------------------------------- .. index:: clock get nanoseconds uptime .. index:: uptime - -**CALLING SEQUENCE:** - .. index:: rtems_clock_get_uptime_nanoseconds -.. code-block:: c - - uint64_t rtems_clock_get_uptime_nanoseconds(void); - -**DIRECTIVE STATUS CODES:** - -The system uptime in nanoseconds. +CALLING SEQUENCE: + .. code-block:: c -**DESCRIPTION:** + uint64_t rtems_clock_get_uptime_nanoseconds(void); -This directive returns the nanoseconds since the system was booted. +DIRECTIVE STATUS CODES: + The system uptime in nanoseconds. -**NOTES:** +DESCRIPTION: + This directive returns the nanoseconds since the system was booted. -This directive may be called from an ISR. +NOTES: + This directive may be called from an ISR. diff --git a/c-user/configuring_a_system.rst b/c-user/configuring_a_system.rst index 55673b1..16973d6 100644 --- a/c-user/configuring_a_system.rst +++ b/c-user/configuring_a_system.rst @@ -173,13 +173,13 @@ for its resources. Format to be followed for making changes in this file ===================================================== -*MACRO NAME:*: +MACRO NAME: Should be alphanumeric. Can have '_' (underscore). -*DATA TYPE:* +DATA TYPE: Please refer to all existing formats. -*RANGE:* +RANGE: The range depends on the Data Type of the macro. - If the data type is of type task priority, then its value should be an @@ -196,9 +196,9 @@ Format to be followed for making changes in this file be alphanumeric. - If the data type is RTEMS NAME then the value should be an integer>=0 or - RTEMS_BUILD_NAME( 'U', 'I', '1', ' ' ) + ``RTEMS_BUILD_NAME( 'U', 'I', '1', ' ' )`` -*DEFAULT VALUE:* +DEFAULT VALUE: The default value should be in the following formats- Please note that the '.' (full stop) is necessary. @@ -208,10 +208,10 @@ Format to be followed for making changes in this file - If the default value is BSP Specific then: This option is BSP specific. -*DESCRIPTION:* +DESCRIPTION: The description of the macro. (No specific format) -*NOTES:* +NOTES: Any further notes. (No specific format) .. COMMENT: === Configuration Example === @@ -303,7 +303,7 @@ things, the application implicitly used the following defaults: .. _Unlimited Objects: Unlimited Objects ------------------ +================= In real-time embedded systems the RAM is normally a limited, critical resource and dynamic allocation is avoided as much as possible to ensure predictable, @@ -450,29 +450,27 @@ Enable Unlimited Object Instances --------------------------------- .. index:: CONFIGURE_UNLIMITED_OBJECTS -*CONSTANT:* +CONSTANT: ``CONFIGURE_UNLIMITED_OBJECTS`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. -**DESCRIPTION:** +DESCRIPTION: + ``CONFIGURE_UNLIMITED_OBJECTS`` enables ``rtems_resource_unlimited`` mode + for Classic API and POSIX API objects that do not already have a specific + maximum limit defined. -``CONFIGURE_UNLIMITED_OBJECTS`` enables ``rtems_resource_unlimited`` mode for -Classic API and POSIX API objects that do not already have a specific maximum -limit defined. - -**NOTES:** - -When using unlimited objects, it is common practice to also specify -``CONFIGURE_UNIFIED_WORK_AREAS`` so the system operates with a single pool of -memory for both RTEMS and application memory allocations. +NOTES: + When using unlimited objects, it is common practice to also specify + ``CONFIGURE_UNIFIED_WORK_AREAS`` so the system operates with a single pool + of memory for both RTEMS and application memory allocations. .. COMMENT: === CONFIGURE_UNLIMITED_ALLOCATION_SIZE === @@ -481,30 +479,30 @@ memory for both RTEMS and application memory allocations. Specify Unlimited Objects Allocation Size ----------------------------------------- -*CONSTANT:* +CONSTANT: ``CONFIGURE_UNLIMITED_ALLOCATION_SIZE`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``uint32_t``). -*RANGE:* +RANGE: Positive. -*DEFAULT VALUE:* If not defined and ``CONFIGURE_UNLIMITED_OBJECTS`` is defined, - the default value is eight (8). - -**DESCRIPTION:** +DEFAULT VALUE: + If not defined and ``CONFIGURE_UNLIMITED_OBJECTS`` is defined, the default + value is eight (8). -``CONFIGURE_UNLIMITED_ALLOCATION_SIZE`` provides an allocation size to use for -``rtems_resource_unlimited`` when using ``CONFIGURE_UNLIMITED_OBJECTS``. +DESCRIPTION: + ``CONFIGURE_UNLIMITED_ALLOCATION_SIZE`` provides an allocation size to use + for ``rtems_resource_unlimited`` when using + ``CONFIGURE_UNLIMITED_OBJECTS``. -**NOTES:** - -By allowing users to declare all resources as being unlimited the user can -avoid identifying and limiting the resources -used. ``CONFIGURE_UNLIMITED_OBJECTS`` does not support varying the allocation -sizes for different objects; users who want that much control can define the -``rtems_resource_unlimited`` macros themselves. +NOTES: + By allowing users to declare all resources as being unlimited the user can + avoid identifying and limiting the resources + used. ``CONFIGURE_UNLIMITED_OBJECTS`` does not support varying the + allocation sizes for different objects; users who want that much control + can define the ``rtems_resource_unlimited`` macros themselves. .. code-block:: c @@ -527,44 +525,43 @@ Specify Maximum Classic API Tasks --------------------------------- .. index:: CONFIGURE_MAXIMUM_TASKS -*CONSTANT:* +CONSTANT: ``CONFIGURE_MAXIMUM_TASKS`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``uint32_t``). -*RANGE:* +RANGE: Zero or positive. -*DEFAULT VALUE:* - The default value is 0. - -**DESCRIPTION:** +DEFAULT VALUE: + The default value is ``0``. -``CONFIGURE_MAXIMUM_TASKS`` is the maximum number of Classic API Tasks that can -be concurrently active. +DESCRIPTION: + ``CONFIGURE_MAXIMUM_TASKS`` is the maximum number of Classic API Tasks that + can be concurrently active. -**NOTES:** +NOTES: + This object class can be configured in unlimited allocation mode. -This object class can be configured in unlimited allocation mode. + 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 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 maximum number of POSIX threads is specified by + ``CONFIGURE_MAXIMUM_POSIX_THREADS``. -The maximum number of POSIX threads is specified by -``CONFIGURE_MAXIMUM_POSIX_THREADS``. + 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. .. COMMENT: XXX - Add xref to CONFIGURE_MAXIMUM_POSIX_THREADS. -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. - .. COMMENT: === CONFIGURE_ENABLE_CLASSIC_API_NOTEPADS === .. _Specify Maximum Classic API Timers: @@ -573,27 +570,27 @@ Specify Maximum Classic API Timers ---------------------------------- .. index:: CONFIGURE_ENABLE_CLASSIC_API_NOTEPADS -*CONSTANT:* +CONSTANT: ``CONFIGURE_ENABLE_CLASSIC_API_NOTEPADS`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default, and Classic API Notepads are not supported. -**DESCRIPTION:** +DESCRIPTION: ``CONFIGURE_ENABLE_CLASSIC_API_NOTEPADS`` should be defined if the user wants to have support for Classic API Notepads in their application. -**NOTES:** +NOTES: Disabling Classic API Notepads saves the allocation of sixteen (16) thirty-two bit integers. This saves sixty-four bytes per task/thread plus the allocation overhead. Notepads are rarely used in applications - and this can save significant memory in a low RAM system. Classic API + and this can save significant memory in a low RAM system. Classic API Notepads are deprecated, and this option has been removed from post 4.11 versions of RTEMS. @@ -605,26 +602,24 @@ Specify Maximum Classic API Timers ---------------------------------- .. index:: CONFIGURE_MAXIMUM_TIMERS -*CONSTANT:* +CONSTANT: ``CONFIGURE_MAXIMUM_TIMERS`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``uint32_t``). -*RANGE:* +RANGE: Zero or positive. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is 0. -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_TIMERS`` is the maximum number of Classic API Timers that -can be concurrently active. +DESCRIPTION: + ``CONFIGURE_MAXIMUM_TIMERS`` is the maximum number of Classic API Timers + that can be concurrently active. -**NOTES:** - -This object class can be configured in unlimited allocation mode. +NOTES: + This object class can be configured in unlimited allocation mode. .. COMMENT: === CONFIGURE_MAXIMUM_SEMAPHORES === @@ -634,26 +629,24 @@ Specify Maximum Classic API Semaphores -------------------------------------- .. index:: CONFIGURE_MAXIMUM_SEMAPHORES -*CONSTANT:* +CONSTANT: ``CONFIGURE_MAXIMUM_SEMAPHORES`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``uint32_t``). -*RANGE:* +RANGE: Zero or positive. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is 0. -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_SEMAPHORES`` is the maximum number of Classic API -Semaphores that can be concurrently active. +DESCRIPTION: + ``CONFIGURE_MAXIMUM_SEMAPHORES`` is the maximum number of Classic API + Semaphores that can be concurrently active. -**NOTES:** - -This object class can be configured in unlimited allocation mode. +NOTES: + This object class can be configured in unlimited allocation mode. .. COMMENT: === CONFIGURE_MAXIMUM_MRSP_SEMAPHORES === @@ -663,29 +656,27 @@ Specify Maximum Classic API Semaphores usable with MrsP ------------------------------------------------------- .. index:: CONFIGURE_MAXIMUM_MRSP_SEMAPHORES -*CONSTANT:* +CONSTANT: ``CONFIGURE_MAXIMUM_MRSP_SEMAPHORES`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``uint32_t``). -*RANGE:* +RANGE: Zero or positive. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is 0. -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_MRSP_SEMAPHORES`` is the maximum number of Classic API -Semaphores using the Multiprocessor Resource Sharing Protocol (MrsP) that can -be concurrently active. - -**NOTES:** +DESCRIPTION: + ``CONFIGURE_MAXIMUM_MRSP_SEMAPHORES`` is the maximum number of Classic API + Semaphores using the Multiprocessor Resource Sharing Protocol (MrsP) that + can be concurrently active. -This configuration option is only used on SMP configurations. On uni-processor -configurations the Priority Ceiling Protocol is used for MrsP semaphores and -thus no extra memory is necessary. +NOTES: + This configuration option is only used on SMP configurations. On + uni-processor configurations the Priority Ceiling Protocol is used for MrsP + semaphores and thus no extra memory is necessary. .. COMMENT: === CONFIGURE_MAXIMUM_MESSAGE_QUEUES === @@ -695,26 +686,24 @@ Specify Maximum Classic API Message Queues ------------------------------------------ .. index:: CONFIGURE_MAXIMUM_MESSAGE_QUEUES -*CONSTANT:* +CONSTANT: ``CONFIGURE_MAXIMUM_MESSAGE_QUEUES`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``uint32_t``). -*RANGE:* +RANGE: Zero or positive. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is 0. -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_MESSAGE_QUEUES`` is the maximum number of Classic API -Message Queues that can be concurrently active. - -**NOTES:** +DESCRIPTION: + ``CONFIGURE_MAXIMUM_MESSAGE_QUEUES`` is the maximum number of Classic API + Message Queues that can be concurrently active. -This object class can be configured in unlimited allocation mode. +NOTES: + This object class can be configured in unlimited allocation mode. .. COMMENT: === CONFIGURE_MAXIMUM_BARRIERS === @@ -724,26 +713,24 @@ Specify Maximum Classic API Barriers ------------------------------------ .. index:: CONFIGURE_MAXIMUM_BARRIERS -*CONSTANT:* +CONSTANT: ``CONFIGURE_MAXIMUM_BARRIERS`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``uint32_t``). -*RANGE:* +RANGE: Zero or positive. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is 0. -**DESCRIPTION:** +DESCRIPTION: + ``CONFIGURE_MAXIMUM_BARRIERS`` is the maximum number of Classic API + Barriers that can be concurrently active. -``CONFIGURE_MAXIMUM_BARRIERS`` is the maximum number of Classic API Barriers -that can be concurrently active. - -**NOTES:** - -This object class can be configured in unlimited allocation mode. +NOTES: + This object class can be configured in unlimited allocation mode. .. COMMENT: === CONFIGURE_MAXIMUM_PERIODS === @@ -753,26 +740,24 @@ Specify Maximum Classic API Periods ----------------------------------- .. index:: CONFIGURE_MAXIMUM_PERIODS -*CONSTANT:* +CONSTANT: ``CONFIGURE_MAXIMUM_PERIODS`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``uint32_t``). -*RANGE:* +RANGE: Zero or positive. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is 0. -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_PERIODS`` is the maximum number of Classic API Periods that -can be concurrently active. +DESCRIPTION: + ``CONFIGURE_MAXIMUM_PERIODS`` is the maximum number of Classic API Periods + that can be concurrently active. -**NOTES:** - -This object class can be configured in unlimited allocation mode. +NOTES: + This object class can be configured in unlimited allocation mode. .. COMMENT: === CONFIGURE_MAXIMUM_PARTITIONS === @@ -782,26 +767,24 @@ Specify Maximum Classic API Partitions -------------------------------------- .. index:: CONFIGURE_MAXIMUM_PARTITIONS -*CONSTANT:* +CONSTANT: ``CONFIGURE_MAXIMUM_PARTITIONS`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``uint32_t``). -*RANGE:* +RANGE: Zero or positive. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is 0. -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_PARTITIONS`` is the maximum number of Classic API -Partitions that can be concurrently active. +DESCRIPTION: + ``CONFIGURE_MAXIMUM_PARTITIONS`` is the maximum number of Classic API + Partitions that can be concurrently active. -**NOTES:** - -This object class can be configured in unlimited allocation mode. +NOTES: + This object class can be configured in unlimited allocation mode. .. COMMENT: === CONFIGURE_MAXIMUM_REGIONS === @@ -811,26 +794,24 @@ Specify Maximum Classic API Regions ----------------------------------- .. index:: CONFIGURE_MAXIMUM_REGIONS -*CONSTANT:* +CONSTANT: ``CONFIGURE_MAXIMUM_REGIONS`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``uint32_t``). -*RANGE:* +RANGE: Zero or positive. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is 0. -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_REGIONS`` is the maximum number of Classic API Regions that -can be concurrently active. - -**NOTES:** +DESCRIPTION: + ``CONFIGURE_MAXIMUM_REGIONS`` is the maximum number of Classic API Regions + that can be concurrently active. -None. +NOTES: + None. .. COMMENT: === CONFIGURE_MAXIMUM_PORTS === @@ -840,26 +821,24 @@ Specify Maximum Classic API Ports --------------------------------- .. index:: CONFIGURE_MAXIMUM_PORTS -*CONSTANT:* +CONSTANT: ``CONFIGURE_MAXIMUM_PORTS`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``uint32_t``). -*RANGE:* +RANGE: Zero or positive. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is 0. -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_PORTS`` is the maximum number of Classic API Ports that can -be concurrently active. - -**NOTES:** +DESCRIPTION: + ``CONFIGURE_MAXIMUM_PORTS`` is the maximum number of Classic API Ports that + can be concurrently active. -This object class can be configured in unlimited allocation mode. +NOTES: + This object class can be configured in unlimited allocation mode. .. COMMENT: === CONFIGURE_MAXIMUM_USER_EXTENSIONS === @@ -869,26 +848,24 @@ Specify Maximum Classic API User Extensions ------------------------------------------- .. index:: CONFIGURE_MAXIMUM_USER_EXTENSIONS -*CONSTANT:* +CONSTANT: ``CONFIGURE_MAXIMUM_USER_EXTENSIONS`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``uint32_t``). -*RANGE:* +RANGE: Zero or positive. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is 0. -**DESCRIPTION:** +DESCRIPTION: + ``CONFIGURE_MAXIMUM_USER_EXTENSIONS`` is the maximum number of Classic API + User Extensions that can be concurrently active. -``CONFIGURE_MAXIMUM_USER_EXTENSIONS`` is the maximum number of Classic API User -Extensions that can be concurrently active. - -**NOTES:** - -This object class can be configured in unlimited allocation mode. +NOTES: + This object class can be configured in unlimited allocation mode. .. COMMENT: === Classic API Initialization Task Configuration === @@ -907,35 +884,34 @@ Instantiate Classic API Initialization Task Table ------------------------------------------------- .. index:: CONFIGURE_RTEMS_INIT_TASKS_TABLE -*CONSTANT:* +CONSTANT: ``CONFIGURE_RTEMS_INIT_TASKS_TABLE`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. -**DESCRIPTION:** - -``CONFIGURE_RTEMS_INIT_TASKS_TABLE`` is defined if the user wishes to use a -Classic RTEMS API Initialization Task Table. The table built by -``<rtems/confdefs.h>`` specifies the parameters for a single task. This is -sufficient for applications which initialization the system from a single task. +DESCRIPTION: + ``CONFIGURE_RTEMS_INIT_TASKS_TABLE`` is defined if the user wishes to use a + Classic RTEMS API Initialization Task Table. The table built by + ``<rtems/confdefs.h>`` specifies the parameters for a single task. This is + sufficient for applications which initialization the system from a single + task. -By default, this field is not defined as the user MUST select their own API for -initialization tasks. - -**NOTES:** + By default, this field is not defined as the user MUST select their own API + for initialization tasks. -The application may choose to use the initialization tasks or threads table -from another API. +NOTES: + The application may choose to use the initialization tasks or threads table + from another API. -A compile time error will be generated if the user does not configure any -initialization tasks or threads. + A compile time error will be generated if the user does not configure any + initialization tasks or threads. .. COMMENT: === CONFIGURE_INIT_TASK_ENTRY_POINT === @@ -945,28 +921,26 @@ Specifying Classic API Initialization Task Entry Point ------------------------------------------------------ .. index:: CONFIGURE_INIT_TASK_ENTRY_POINT -*CONSTANT:* +CONSTANT: ``CONFIGURE_INIT_TASK_ENTRY_POINT`` -*DATA TYPE:* +DATA TYPE: Task entry function pointer (``rtems_task_entry``). -*RANGE:* +RANGE: Valid task entry function pointer. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is ``Init``. -**DESCRIPTION:** +DESCRIPTION: + ``CONFIGURE_INIT_TASK_ENTRY_POINT`` is the entry point (a.k.a. function + name) of the single initialization task defined by the Classic API + Initialization Tasks Table. -``CONFIGURE_INIT_TASK_ENTRY_POINT`` is the entry point (a.k.a. function name) -of the single initialization task defined by the Classic API Initialization -Tasks Table. - -**NOTES:** - -The user must implement the function ``Init`` or the function name provided in -this configuration parameter. +NOTES: + The user must implement the function ``Init`` or the function name provided + in this configuration parameter. .. COMMENT: === CONFIGURE_INIT_TASK_NAME === @@ -976,26 +950,24 @@ Specifying Classic API Initialization Task Name ----------------------------------------------- .. index:: CONFIGURE_INIT_TASK_NAME -*CONSTANT:* +CONSTANT: ``CONFIGURE_INIT_TASK_NAME`` -*DATA TYPE:* +DATA TYPE: RTEMS Name (``rtems_name``). -*RANGE:* +RANGE: Any value. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is ``rtems_build_name( 'U', 'I', '1', ' ' )``. -**DESCRIPTION:** - -``CONFIGURE_INIT_TASK_NAME`` is the name of the single initialization task -defined by the Classic API Initialization Tasks Table. +DESCRIPTION: + ``CONFIGURE_INIT_TASK_NAME`` is the name of the single initialization task + defined by the Classic API Initialization Tasks Table. -**NOTES:** - -None. +NOTES: + None. .. COMMENT: === CONFIGURE_INIT_TASK_STACK_SIZE === @@ -1005,29 +977,27 @@ Specifying Classic API Initialization Task Stack Size ----------------------------------------------------- .. index:: CONFIGURE_INIT_TASK_STACK_SIZE -*CONSTANT:* +CONSTANT: ``CONFIGURE_INIT_TASK_STACK_SIZE`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``size_t``). -*RANGE:* +RANGE: Zero or positive. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is RTEMS_MINIMUM_STACK_SIZE. -**DESCRIPTION:** - -``CONFIGURE_INIT_TASK_STACK_SIZE`` is the stack size of the single -initialization task defined by the Classic API Initialization Tasks Table. +DESCRIPTION: + ``CONFIGURE_INIT_TASK_STACK_SIZE`` is the stack size of the single + initialization task defined by the Classic API Initialization Tasks Table. -**NOTES:** - -If the stack size specified is greater than the configured minimum, it must be -accounted for in ``CONFIGURE_EXTRA_TASK_STACKS``. See :ref:`Reserve -Task/Thread Stack Memory Above Minimum` for more information about -``CONFIGURE_EXTRA_TASK_STACKS``. +NOTES: + If the stack size specified is greater than the configured minimum, it must + be accounted for in ``CONFIGURE_EXTRA_TASK_STACKS``. See :ref:`Reserve + Task/Thread Stack Memory Above Minimum` for more information about + ``CONFIGURE_EXTRA_TASK_STACKS``. .. COMMENT: === CONFIGURE_INIT_TASK_PRIORITY === @@ -1037,27 +1007,24 @@ Specifying Classic API Initialization Task Priority --------------------------------------------------- .. index:: CONFIGURE_INIT_TASK_PRIORITY -*CONSTANT:* +CONSTANT: ``CONFIGURE_INIT_TASK_PRIORITY`` -*DATA TYPE:* +DATA TYPE: RTEMS Task Priority (``rtems_task_priority``). -*RANGE:* +RANGE: One (1) to CONFIGURE_MAXIMUM_PRIORITY. -*DEFAULT VALUE:* - The default value is 1, which is the highest priority in the - Classic API. - -**DESCRIPTION:** +DEFAULT VALUE: + The default value is 1, which is the highest priority in the Classic API. -``CONFIGURE_INIT_TASK_PRIORITY`` is the initial priority of the single -initialization task defined by the Classic API Initialization Tasks Table. +DESCRIPTION: + ``CONFIGURE_INIT_TASK_PRIORITY`` is the initial priority of the single + initialization task defined by the Classic API Initialization Tasks Table. -**NOTES:** - -None. +NOTES: + None. .. COMMENT: === CONFIGURE_INIT_TASK_ATTRIBUTES === @@ -1067,26 +1034,24 @@ Specifying Classic API Initialization Task Attributes ----------------------------------------------------- .. index:: CONFIGURE_INIT_TASK_ATTRIBUTES -*CONSTANT:* +CONSTANT: ``CONFIGURE_INIT_TASK_ATTRIBUTES`` -*DATA TYPE:* +DATA TYPE: RTEMS Attributes (``rtems_attribute``). -*RANGE:* +RANGE: Valid task attribute sets. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is ``RTEMS_DEFAULT_ATTRIBUTES``. -**DESCRIPTION:** - -``CONFIGURE_INIT_TASK_ATTRIBUTES`` is the task attributes of the single -initialization task defined by the Classic API Initialization Tasks Table. +DESCRIPTION: + ``CONFIGURE_INIT_TASK_ATTRIBUTES`` is the task attributes of the single + initialization task defined by the Classic API Initialization Tasks Table. -**NOTES:** - -None. +NOTES: + None. .. COMMENT: === CONFIGURE_INIT_TASK_INITIAL_MODES === @@ -1096,27 +1061,25 @@ Specifying Classic API Initialization Task Modes ------------------------------------------------ .. index:: CONFIGURE_INIT_TASK_INITIAL_MODES -*CONSTANT:* +CONSTANT: ``CONFIGURE_INIT_TASK_INITIAL_MODES`` -*DATA TYPE:* +DATA TYPE: RTEMS Mode (``rtems_mode``). -*RANGE:* +RANGE: Valid task mode sets. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is ``RTEMS_NO_PREEMPT``. -**DESCRIPTION:** - -``CONFIGURE_INIT_TASK_INITIAL_MODES`` is the initial execution mode of the -single initialization task defined by the Classic API Initialization Tasks -Table. - -**NOTES:** +DESCRIPTION: + ``CONFIGURE_INIT_TASK_INITIAL_MODES`` is the initial execution mode of the + single initialization task defined by the Classic API Initialization Tasks + Table. -None. +NOTES: + None. .. COMMENT: === CONFIGURE_INIT_TASK_ARGUMENTS === @@ -1126,26 +1089,24 @@ Specifying Classic API Initialization Task Arguments ---------------------------------------------------- .. index:: CONFIGURE_INIT_TASK_ARGUMENTS -*CONSTANT:* +CONSTANT: ``CONFIGURE_INIT_TASK_ARGUMENTS`` -*DATA TYPE:* +DATA TYPE: RTEMS Task Argument (``rtems_task_argument``). -*RANGE:* +RANGE: Complete range of the type. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is 0. -**DESCRIPTION:** - -``CONFIGURE_INIT_TASK_ARGUMENTS`` is the task argument of the single -initialization task defined by the Classic API Initialization Tasks Table. - -**NOTES:** +DESCRIPTION: + ``CONFIGURE_INIT_TASK_ARGUMENTS`` is the task argument of the single + initialization task defined by the Classic API Initialization Tasks Table. -None. +NOTES: + None. .. COMMENT: === CONFIGURE_HAS_OWN_INIT_TASK_TABLE === @@ -1155,28 +1116,26 @@ Not Using Generated Initialization Tasks Table ---------------------------------------------- .. index:: CONFIGURE_HAS_OWN_INIT_TASK_TABLE -*CONSTANT:* +CONSTANT: ``CONFIGURE_HAS_OWN_INIT_TASK_TABLE`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. -**DESCRIPTION:** +DESCRIPTION: + ``CONFIGURE_HAS_OWN_INIT_TASK_TABLE`` is defined if the user wishes to + define their own Classic API Initialization Tasks Table. This table should + be named ``Initialization_tasks``. -``CONFIGURE_HAS_OWN_INIT_TASK_TABLE`` is defined if the user wishes to define -their own Classic API Initialization Tasks Table. This table should be named -``Initialization_tasks``. - -**NOTES:** - -This is a seldom used configuration parameter. The most likely use case is when -an application desires to have more than one initialization task. +NOTES: + This is a seldom used configuration parameter. The most likely use case is + when an application desires to have more than one initialization task. .. COMMENT: === POSIX API Configuration === @@ -1195,38 +1154,37 @@ Specify Maximum POSIX API Threads --------------------------------- .. index:: CONFIGURE_MAXIMUM_POSIX_THREADS -*CONSTANT:* +CONSTANT: ``CONFIGURE_MAXIMUM_POSIX_THREADS`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``uint32_t``). -*RANGE:* +RANGE: Zero or positive. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is 0. -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_POSIX_THREADS`` is the maximum number of POSIX API -Threads that can be concurrently active. +DESCRIPTION: + ``CONFIGURE_MAXIMUM_POSIX_THREADS`` is the maximum number of POSIX API + Threads that can be concurrently active. -**NOTES:** +NOTES: + This object class can be configured in unlimited allocation mode. -This object class can be configured in unlimited allocation mode. + 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 parameter + ``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``. -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 parameter ``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``. + The maximum number of Classic API Tasks is specified by + ``CONFIGURE_MAXIMUM_TASKS``. -The maximum number of Classic API Tasks is specified by -``CONFIGURE_MAXIMUM_TASKS``. - -All POSIX threads have floating point enabled. + All POSIX threads have floating point enabled. .. COMMENT: XXX - Add xref to CONFIGURE_MAXIMUM_TASKS. @@ -1238,26 +1196,24 @@ Specify Maximum POSIX API Mutexes --------------------------------- .. index:: CONFIGURE_MAXIMUM_POSIX_MUTEXES -*CONSTANT:* +CONSTANT: ``CONFIGURE_MAXIMUM_POSIX_MUTEXES`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``uint32_t``). -*RANGE:* +RANGE: Zero or positive. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is 0. -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_POSIX_MUTEXES`` is the maximum number of POSIX API Mutexes -that can be concurrently active. +DESCRIPTION: + ``CONFIGURE_MAXIMUM_POSIX_MUTEXES`` is the maximum number of POSIX API + Mutexes that can be concurrently active. -**NOTES:** - -This object class can be configured in unlimited allocation mode. +NOTES: + This object class can be configured in unlimited allocation mode. .. COMMENT: === CONFIGURE_MAXIMUM_POSIX_CONDITION_VARIABLES === @@ -1267,26 +1223,24 @@ Specify Maximum POSIX API Condition Variables --------------------------------------------- .. index:: CONFIGURE_MAXIMUM_POSIX_CONDITION_VARIABLES -*CONSTANT:* +CONSTANT: ``CONFIGURE_MAXIMUM_POSIX_CONDITION_VARIABLES`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``uint32_t``). -*RANGE:* +RANGE: Zero or positive. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is 0. -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_POSIX_CONDITION_VARIABLES`` is the maximum number of POSIX -API Condition Variables that can be concurrently active. - -**NOTES:** +DESCRIPTION: + ``CONFIGURE_MAXIMUM_POSIX_CONDITION_VARIABLES`` is the maximum number of + POSIX API Condition Variables that can be concurrently active. -This object class can be configured in unlimited allocation mode. +NOTES: + This object class can be configured in unlimited allocation mode. .. COMMENT: === CONFIGURE_MAXIMUM_POSIX_KEYS === @@ -1296,26 +1250,24 @@ Specify Maximum POSIX API Keys ------------------------------ .. index:: CONFIGURE_MAXIMUM_POSIX_KEYS -*CONSTANT:* +CONSTANT: ``CONFIGURE_MAXIMUM_POSIX_KEYS`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``uint32_t``). -*RANGE:* +RANGE: Zero or positive. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is 0. -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_POSIX_KEYS`` is the maximum number of POSIX API Keys that -can be concurrently active. - -**NOTES:** +DESCRIPTION: + ``CONFIGURE_MAXIMUM_POSIX_KEYS`` is the maximum number of POSIX API Keys + that can be concurrently active. -This object class can be configured in unlimited allocation mode. +NOTES: + This object class can be configured in unlimited allocation mode. .. COMMENT: XXX - Key pairs @@ -1327,26 +1279,24 @@ Specify Maximum POSIX API Timers -------------------------------- .. index:: CONFIGURE_MAXIMUM_POSIX_TIMERS -*CONSTANT:* +CONSTANT: ``CONFIGURE_MAXIMUM_POSIX_TIMERS`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``uint32_t``). -*RANGE:* +RANGE: Zero or positive. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is 0. -**DESCRIPTION:** +DESCRIPTION: + ``CONFIGURE_MAXIMUM_POSIX_TIMERS`` is the maximum number of POSIX API + Timers that can be concurrently active. -``CONFIGURE_MAXIMUM_POSIX_TIMERS`` is the maximum number of POSIX API Timers -that can be concurrently active. - -**NOTES:** - -This object class can be configured in unlimited allocation mode. +NOTES: + This object class can be configured in unlimited allocation mode. .. COMMENT: === CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS === @@ -1356,26 +1306,24 @@ Specify Maximum POSIX API Queued Signals ---------------------------------------- .. index:: CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS -*CONSTANT:* +CONSTANT: ``CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``uint32_t``). -*RANGE:* +RANGE: Zero or positive. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is 0. -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS`` is the maximum number of POSIX API -Queued Signals that can be concurrently active. - -**NOTES:** +DESCRIPTION: + ``CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS`` is the maximum number of POSIX + API Queued Signals that can be concurrently active. -None. +NOTES: + None. .. COMMENT: === CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES === @@ -1385,26 +1333,24 @@ Specify Maximum POSIX API Message Queues ---------------------------------------- .. index:: CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES -*CONSTANT:* +CONSTANT: ``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``uint32_t``). -*RANGE:* +RANGE: Zero or positive. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is 0. -**DESCRIPTION:** +DESCRIPTION: + ``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES`` is the maximum number of POSIX + API Message Queues that can be concurrently active. -``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES`` is the maximum number of POSIX API -Message Queues that can be concurrently active. - -**NOTES:** - -This object class can be configured in unlimited allocation mode. +NOTES: + This object class can be configured in unlimited allocation mode. .. COMMENT: XXX - memory for buffers note @@ -1416,29 +1362,27 @@ Specify Maximum POSIX API Message Queue Descriptors --------------------------------------------------- .. index:: CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUE_DESCRIPTORS -*CONSTANT:* +CONSTANT: ``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUE_DESCRIPTORS`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``uint32_t``). -*RANGE:* +RANGE: greater than or equal to ``CONFIGURE_MAXIMUM_POSIX_MESSAGES_QUEUES`` -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is 0. -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUE_DESCRIPTORS`` is the maximum number of -POSIX API Message Queue Descriptors that can be concurrently active. +DESCRIPTION: + ``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUE_DESCRIPTORS`` is the maximum number + of POSIX API Message Queue Descriptors that can be concurrently active. -**NOTES:** +NOTES: + This object class can be configured in unlimited allocation mode. -This object class can be configured in unlimited allocation mode. - -``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUE_DESCRIPTORS`` should be greater than or -equal to ``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES``. + ``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUE_DESCRIPTORS`` should be greater + than or equal to ``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES``. .. COMMENT: === CONFIGURE_MAXIMUM_POSIX_SEMAPHORES === @@ -1448,26 +1392,24 @@ Specify Maximum POSIX API Semaphores ------------------------------------ .. index:: CONFIGURE_MAXIMUM_POSIX_SEMAPHORES -*CONSTANT:* +CONSTANT: ``CONFIGURE_MAXIMUM_POSIX_SEMAPHORES`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``uint32_t``). -*RANGE:* +RANGE: Zero or positive. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is 0. -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_POSIX_SEMAPHORES`` is the maximum number of POSIX API -Semaphores that can be concurrently active. +DESCRIPTION: + ``CONFIGURE_MAXIMUM_POSIX_SEMAPHORES`` is the maximum number of POSIX API + Semaphores that can be concurrently active. -**NOTES:** - -None. +NOTES: + None. .. COMMENT: === CONFIGURE_MAXIMUM_POSIX_BARRIERS === @@ -1477,26 +1419,24 @@ Specify Maximum POSIX API Barriers ---------------------------------- .. index:: CONFIGURE_MAXIMUM_POSIX_BARRIERS -*CONSTANT:* +CONSTANT: ``CONFIGURE_MAXIMUM_POSIX_BARRIERS`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``uint32_t``). -*RANGE:* +RANGE: Zero or positive. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is 0. -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_POSIX_BARRIERS`` is the maximum number of POSIX API -Barriers that can be concurrently active. - -**NOTES:** +DESCRIPTION: + ``CONFIGURE_MAXIMUM_POSIX_BARRIERS`` is the maximum number of POSIX API + Barriers that can be concurrently active. -This object class can be configured in unlimited allocation mode. +NOTES: + This object class can be configured in unlimited allocation mode. .. COMMENT: === CONFIGURE_MAXIMUM_POSIX_SPINLOCKS === @@ -1506,26 +1446,24 @@ Specify Maximum POSIX API Spinlocks ----------------------------------- .. index:: CONFIGURE_MAXIMUM_POSIX_SPINLOCKS -*CONSTANT:* +CONSTANT: ``CONFIGURE_MAXIMUM_POSIX_SPINLOCKS`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``uint32_t``). -*RANGE:* +RANGE: Zero or positive. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is 0. -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_POSIX_SPINLOCKS`` is the maximum number of POSIX API -Spinlocks that can be concurrently active. - -**NOTES:** +DESCRIPTION: + ``CONFIGURE_MAXIMUM_POSIX_SPINLOCKS`` is the maximum number of POSIX API + Spinlocks that can be concurrently active. -This object class can be configured in unlimited allocation mode. +NOTES: + This object class can be configured in unlimited allocation mode. .. COMMENT: === CONFIGURE_MAXIMUM_POSIX_RWLOCKS === @@ -1535,26 +1473,24 @@ Specify Maximum POSIX API Read/Write Locks ------------------------------------------ .. index:: CONFIGURE_MAXIMUM_POSIX_RWLOCKS -*CONSTANT:* +CONSTANT: ``CONFIGURE_MAXIMUM_POSIX_RWLOCKS`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``uint32_t``). -*RANGE:* +RANGE: Zero or positive. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is 0. -**DESCRIPTION:** +DESCRIPTION: + ``CONFIGURE_MAXIMUM_POSIX_RWLOCKS`` is the maximum number of POSIX API + Read/Write Locks that can be concurrently active. -``CONFIGURE_MAXIMUM_POSIX_RWLOCKS`` is the maximum number of POSIX API -Read/Write Locks that can be concurrently active. - -**NOTES:** - -This object class can be configured in unlimited allocation mode. +NOTES: + This object class can be configured in unlimited allocation mode. .. COMMENT: === POSIX Initialization Threads Table Configuration === @@ -1573,36 +1509,36 @@ Instantiate POSIX API Initialization Thread Table ------------------------------------------------- .. index:: CONFIGURE_POSIX_INIT_THREAD_TABLE -*CONSTANT:* - .. index:: CONFIGURE_POSIX_INIT_THREAD_TABLE +CONSTANT: + + ``CONFIGURE_POSIX_INIT_THREAD_TABLE`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This field is not defined by default, as the user MUST select their own API for initialization tasks. -**DESCRIPTION:** - -``CONFIGURE_POSIX_INIT_THREAD_TABLE`` is defined if the user wishes to use a -POSIX API Initialization Threads Table. The table built by -``<rtems/confdefs.h>`` specifies the parameters for a single thread. This is -sufficient for applications which initialization the system from a single task. - -By default, this field is not defined as the user MUST select their own API for -initialization tasks. +DESCRIPTION: + ``CONFIGURE_POSIX_INIT_THREAD_TABLE`` is defined if the user wishes to use + a POSIX API Initialization Threads Table. The table built by + ``<rtems/confdefs.h>`` specifies the parameters for a single thread. This + is sufficient for applications which initialization the system from a + single task. -**NOTES:** + By default, this field is not defined as the user MUST select their own API + for initialization tasks. -The application may choose to use the initialization tasks or threads table -from another API. +NOTES: + The application may choose to use the initialization tasks or threads table + from another API. -A compile time error will be generated if the user does not configure any -initialization tasks or threads. + A compile time error will be generated if the user does not configure any + initialization tasks or threads. .. COMMENT: === CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT === @@ -1612,28 +1548,26 @@ Specifying POSIX API Initialization Thread Entry Point ------------------------------------------------------ .. index:: CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT -*CONSTANT:* +CONSTANT: ``CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT`` -*DATA TYPE:* +DATA TYPE: POSIX thread function pointer (``void *(*entry_point)(void *)``). -*RANGE:* +RANGE: Undefined or a valid POSIX thread function pointer. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is ``POSIX_Init``. -**DESCRIPTION:** - -``CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT`` is the entry point (a.k.a. function -name) of the single initialization thread defined by the POSIX API -Initialization Threads Table. +DESCRIPTION: + ``CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT`` is the entry point + (a.k.a. function name) of the single initialization thread defined by the + POSIX API Initialization Threads Table. -**NOTES:** - -The user must implement the function ``POSIX_Init`` or the function name -provided in this configuration parameter. +NOTES: + The user must implement the function ``POSIX_Init`` or the function name + provided in this configuration parameter. .. COMMENT: === CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE === @@ -1643,29 +1577,28 @@ Specifying POSIX API Initialization Thread Stack Size ----------------------------------------------------- .. index:: CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE -*CONSTANT:* +CONSTANT: ``CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``size_t``). -*RANGE:* +RANGE: Zero or positive. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is 2 \* RTEMS_MINIMUM_STACK_SIZE. -**DESCRIPTION:** - -``CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE`` is the stack size of the single -initialization thread defined by the POSIX API Initialization Threads Table. +DESCRIPTION: + ``CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE`` is the stack size of the single + initialization thread defined by the POSIX API Initialization Threads + Table. -**NOTES:** - -If the stack size specified is greater than the configured minimum, it must be -accounted for in ``CONFIGURE_EXTRA_TASK_STACKS``. See :ref:`Reserve -Task/Thread Stack Memory Above Minimum` for more information about -``CONFIGURE_EXTRA_TASK_STACKS``. +NOTES: + If the stack size specified is greater than the configured minimum, it must + be accounted for in ``CONFIGURE_EXTRA_TASK_STACKS``. See :ref:`Reserve + Task/Thread Stack Memory Above Minimum` for more information about + ``CONFIGURE_EXTRA_TASK_STACKS``. .. COMMENT: === CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE === @@ -1675,28 +1608,26 @@ Not Using Generated POSIX Initialization Threads Table ------------------------------------------------------ .. index:: CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE -*CONSTANT:* +CONSTANT: ``CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. -**DESCRIPTION:** - -``CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE`` is defined if the user wishes to -define their own POSIX API Initialization Threads Table. This table should be -named ``POSIX_Initialization_threads``. - -**NOTES:** +DESCRIPTION: + ``CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE`` is defined if the user wishes + to define their own POSIX API Initialization Threads Table. This table + should be named ``POSIX_Initialization_threads``. -This is a seldom used configuration parameter. The most likely use case is when -an application desires to have more than one initialization task. +NOTES: + This is a seldom used configuration parameter. The most likely use case is + when an application desires to have more than one initialization task. .. COMMENT: === Basic System Information === @@ -1718,38 +1649,36 @@ Separate or Unified Work Areas .. index:: RTEMS Workspace .. index:: C Program Heap -*CONSTANT:* +CONSTANT: ``CONFIGURE_UNIFIED_WORK_AREAS`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default, which specifies that the C Program Heap and the RTEMS Workspace will be separate. -**DESCRIPTION:** - -When defined, the C Program Heap and the RTEMS Workspace will be one pool of -memory. - -When not defined, there will be separate memory pools for the RTEMS Workspace -and C Program Heap. +DESCRIPTION: + When defined, the C Program Heap and the RTEMS Workspace will be one pool + of memory. -**NOTES:** + When not defined, there will be separate memory pools for the RTEMS + Workspace and C Program Heap. -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 RTEMS -"unlimited" objects 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 + RTEMS "unlimited" objects 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. .. COMMENT: === CONFIGURE_MICROSECONDS_PER_TICK === @@ -1760,43 +1689,43 @@ Length of Each Clock Tick .. index:: CONFIGURE_MICROSECONDS_PER_TICK .. index:: tick quantum -*CONSTANT:* +CONSTANT: ``CONFIGURE_MICROSECONDS_PER_TICK`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``uint32_t``). -*RANGE:* +RANGE: Positive. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. When not defined, the clock tick quantum is configured to be 10,000 microseconds which is ten (10) milliseconds. -**DESCRIPTION:** - -This constant is used to specify the length of time between clock ticks. - -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. +DESCRIPTION: + This constant is used to specify the length of time between clock ticks. -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. + 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 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. + 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. -**NOTES:** + 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. -This configuration parameter has no impact if the Clock Tick Device driver is -not configured. +NOTES: + This configuration parameter has no impact if the Clock Tick Device driver + is not configured. -There may be BSP specific limits on the resolution or maximum value of a clock -tick quantum. + There may be BSP specific limits on the resolution or maximum value of a + clock tick quantum. .. COMMENT: === CONFIGURE_TICKS_PER_TIMESLICE === @@ -1807,27 +1736,25 @@ Specifying Timeslicing Quantum .. index:: CONFIGURE_TICKS_PER_TIMESLICE .. index:: ticks per timeslice -*CONSTANT:* +CONSTANT: ``CONFIGURE_TICKS_PER_TIMESLICE`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``uint32_t``). -*RANGE:* +RANGE: Positive. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is 50. -**DESCRIPTION:** - -This configuration parameter specifies the length of the timeslice quantum in -ticks for each task. - -**NOTES:** +DESCRIPTION: + This configuration parameter specifies the length of the timeslice quantum + in ticks for each task. -This configuration parameter has no impact if the Clock Tick Device driver is -not configured. +NOTES: + This configuration parameter has no impact if the Clock Tick Device driver + is not configured. .. COMMENT: === CONFIGURE_MAXIMUM_PRIORITY === @@ -1839,43 +1766,42 @@ Specifying the Number of Thread Priority Levels .. index:: maximum priority .. index:: number of priority levels -*CONSTANT:* +CONSTANT: ``CONFIGURE_MAXIMUM_PRIORITY`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``uint8_t``). -*RANGE:* +RANGE: Valid values for this configuration parameter must be one (1) less than than a power of two (2) between 4 and 256 inclusively. In other words, valid values are 3, 7, 31, 63, 127, and 255. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is 255, because RTEMS must support 256 priority levels to be compliant with various standards. These priorities range from zero (0) to 255. -**DESCRIPTION:** +DESCRIPTION: + This configuration parameter specified the maximum numeric priority of any + task in the system and one less that the number of priority levels in the + system. -This configuration parameter specified the maximum numeric priority of any task -in the system and one less that the number of priority levels in the system. + Reducing the number of priorities in the system reduces the amount of memory + allocated from the RTEMS Workspace. -Reducing the number of priorities in the system reduces the amount of memory -allocated from the RTEMS Workspace. +NOTES: + The numerically greatest priority is the logically lowest priority in the + system and will thus be used by the IDLE task. -**NOTES:** + Priority zero (0) is reserved for internal use by RTEMS and is not available + to applications. -The numerically greatest priority is the logically lowest priority in the -system and will thus be used by the IDLE task. - -Priority zero (0) is reserved for internal use by RTEMS and is not available to -applications. - -With some schedulers, reducing the number of priorities can reduce the amount -of memory used by the scheduler. For example, the Deterministic Priority -Scheduler (DPS) used by default uses three pointers of storage per priority -level. Reducing the number of priorities from 256 levels to sixteen (16) can -reduce memory usage by about three (3) kilobytes. + With some schedulers, reducing the number of priorities can reduce the + amount of memory used by the scheduler. For example, the Deterministic + Priority Scheduler (DPS) used by default uses three pointers of storage per + priority level. Reducing the number of priorities from 256 levels to + sixteen (16) can reduce memory usage by about three (3) kilobytes. .. COMMENT: === CONFIGURE_MINIMUM_TASK_STACK_SIZE === @@ -1886,37 +1812,35 @@ Specifying the Minimum Task Size .. index:: CONFIGURE_MINIMUM_TASK_STACK_SIZE .. index:: minimum task stack size -*CONSTANT:* +CONSTANT: ``CONFIGURE_MINIMUM_TASK_STACK_SIZE`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``uint32_t``). -*RANGE:* +RANGE: Positive. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default, which sets the executive to the recommended minimum stack size for this processor. -**DESCRIPTION:** - -The configuration parameter is set to the number of bytes the application wants -the minimum stack size to be for every task or thread in the system. +DESCRIPTION: + The configuration parameter is set to the number of bytes the application + wants the minimum stack size to be for every task or thread in the system. -Adjusting this parameter should be done with caution. Examining the actual -usage using the Stack Checker Usage Reporting facility is recommended. + Adjusting this parameter should be done with caution. Examining the actual + usage using the Stack Checker Usage Reporting facility is recommended. -**NOTES:** +NOTES: + 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 must 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 must 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. .. COMMENT: === CONFIGURE_INTERRUPT_STACK_SIZE === @@ -1927,33 +1851,31 @@ Configuring the Size of the Interrupt Stack .. index:: CONFIGURE_INTERRUPT_STACK_SIZE .. index:: interrupt stack size -*CONSTANT:* +CONSTANT: ``CONFIGURE_INTERRUPT_STACK_SIZE`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``uint32_t``). -*RANGE:* +RANGE: Positive. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is CONFIGURE_MINIMUM_TASK_STACK_SIZE, which is the minimum interrupt stack size. -**DESCRIPTION:** - -``CONFIGURE_INTERRUPT_STACK_SIZE`` is set to the size of the interrupt stack. -The interrupt stack size is often set by the BSP but since this memory may be -allocated from the RTEMS Workspace, it must be accounted for. +DESCRIPTION: + ``CONFIGURE_INTERRUPT_STACK_SIZE`` is set to the size of the interrupt + stack. The interrupt stack size is often set by the BSP but since this + memory may be allocated from the RTEMS Workspace, it must be accounted for. -**NOTES:** +NOTES: + In some BSPs, changing this constant does NOT change the size of the + interrupt stack, only the amount of memory reserved for it. -In some BSPs, changing this constant does NOT change the size of the interrupt -stack, only the amount of memory reserved for it. - -Patches which result in this constant only being used in memory calculations -when the interrupt stack is intended to be allocated from the RTEMS Workspace -would be welcomed by the RTEMS Project. + Patches which result in this constant only being used in memory + calculations when the interrupt stack is intended to be allocated from the + RTEMS Workspace would be welcomed by the RTEMS Project. .. COMMENT: === CONFIGURE_EXTRA_TASK_STACKS === @@ -1964,29 +1886,27 @@ Reserve Task/Thread Stack Memory Above Minimum .. index:: CONFIGURE_EXTRA_TASK_STACKS .. index:: memory for task tasks -*CONSTANT:* +CONSTANT: ``CONFIGURE_EXTRA_TASK_STACKS`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``size_t``). -*RANGE:* +RANGE: Undefined or positive. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is 0. -**DESCRIPTION:** - -This configuration parameter is set to the number of bytes the applications -wishes to add to the task stack requirements calculated by -``<rtems/confdefs.h>``. - -**NOTES:** +DESCRIPTION: + This configuration parameter is set to the number of bytes the applications + wishes to add to the task stack requirements calculated by + ``<rtems/confdefs.h>``. -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>``. +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>``. .. COMMENT: === CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY === @@ -2000,29 +1920,27 @@ Automatically Zeroing the RTEMS Workspace and C Program Heap .. index:: zero C Program Heap .. index:: zero RTEMS Workspace -*CONSTANT:* +CONSTANT: ``CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default, unless overridden by the BSP. The default is *NOT* to zero out the RTEMS Workspace or C Program Heap. -**DESCRIPTION:** - -This macro indicates whether RTEMS should zero the RTEMS Workspace and C -Program Heap as part of its initialization. If defined, the memory regions are -zeroed. Otherwise, they are not. - -**NOTES:** +DESCRIPTION: + This macro indicates whether RTEMS should zero the RTEMS Workspace and C + Program Heap as part of its initialization. If defined, the memory regions + are zeroed. Otherwise, they are not. -Zeroing memory can add significantly to system boot time. It is not necessary -for RTEMS but is often assumed by support libraries. +NOTES: + Zeroing memory can add significantly to system boot time. It is not + necessary for RTEMS but is often assumed by support libraries. .. COMMENT: === CONFIGURE_STACK_CHECKER_ENABLED === @@ -2032,29 +1950,27 @@ Enable The Task Stack Usage Checker ----------------------------------- .. index:: CONFIGURE_STACK_CHECKER_ENABLED -*CONSTANT:* +CONSTANT: ``CONFIGURE_STACK_CHECKER_ENABLED`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default, and thus stack checking is disabled. -**DESCRIPTION:** - -This configuration parameter is defined when the application wishes to enable -run-time stack bounds checking. - -**NOTES:** +DESCRIPTION: + This configuration parameter is defined when the application wishes to + enable run-time stack bounds checking. -In 4.9 and older, this configuration parameter was named ``STACK_CHECKER_ON``. +NOTES: + In 4.9 and older, this configuration parameter was named ``STACK_CHECKER_ON``. -This increases the time required to create tasks as well as adding overhead to -each context switch. + This increases the time required to create tasks as well as adding overhead + to each context switch. .. COMMENT: === CONFIGURE_INITIAL_EXTENSIONS === @@ -2064,27 +1980,25 @@ Specify Application Specific User Extensions -------------------------------------------- .. index:: CONFIGURE_INITIAL_EXTENSIONS -*CONSTANT:* +CONSTANT: ``CONFIGURE_INITIAL_EXTENSIONS`` -*DATA TYPE:* +DATA TYPE: List of user extension initializers (``rtems_extensions_table``). -*RANGE:* +RANGE: Undefined or a list of one or more user extensions. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. -**DESCRIPTION:** +DESCRIPTION: + If ``CONFIGURE_INITIAL_EXTENSIONS`` is defined by the application, then + this application specific set of initial extensions will be placed in the + initial extension table. -If ``CONFIGURE_INITIAL_EXTENSIONS`` is defined by the application, then this -application specific set of initial extensions will be placed in the initial -extension table. - -**NOTES:** - -None. +NOTES: + None. .. COMMENT: === Custom Stack Allocator === @@ -2104,27 +2018,26 @@ Custom Task Stack Allocator Initialization ------------------------------------------ .. index:: CONFIGURE_TASK_STACK_ALLOCATOR_INIT -*CONSTANT:* +CONSTANT: ``CONFIGURE_TASK_STACK_ALLOCATOR_INIT`` -*DATA TYPE:* +DATA TYPE: Function pointer. -*RANGE:* +RANGE: Undefined, NULL or valid function pointer. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is NULL, which indicates that task stacks will be allocated from the RTEMS Workspace. -**DESCRIPTION:** - -``CONFIGURE_TASK_STACK_ALLOCATOR_INIT`` configures the initialization method -for an application or BSP specific task stack allocation implementation. +DESCRIPTION: + ``CONFIGURE_TASK_STACK_ALLOCATOR_INIT`` configures the initialization + method for an application or BSP specific task stack allocation + implementation. -**NOTES:** - -A correctly configured system must configure the following to be consistent: +NOTES: + A correctly configured system must configure the following to be consistent: - ``CONFIGURE_TASK_STACK_ALLOCATOR_INIT`` @@ -2142,27 +2055,25 @@ Custom Task Stack Allocator .. index:: task stack allocator -*CONSTANT:* +CONSTANT: ``CONFIGURE_TASK_STACK_ALLOCATOR`` -*DATA TYPE:* +DATA TYPE: Function pointer. -*RANGE:* +RANGE: Undefined or valid function pointer. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is ``_Workspace_Allocate``, which indicates that task stacks will be allocated from the RTEMS Workspace. -**DESCRIPTION:** - -``CONFIGURE_TASK_STACK_ALLOCATOR`` may point to a user provided routine to -allocate task stacks. +DESCRIPTION: + ``CONFIGURE_TASK_STACK_ALLOCATOR`` may point to a user provided routine to + allocate task stacks. -**NOTES:** - -A correctly configured system must configure the following to be consistent: +NOTES: + A correctly configured system must configure the following to be consistent: - ``CONFIGURE_TASK_STACK_ALLOCATOR_INIT`` @@ -2179,27 +2090,25 @@ Custom Task Stack Deallocator .. index:: CONFIGURE_TASK_STACK_DEALLOCATOR .. index:: task stack deallocator -*CONSTANT:* +CONSTANT: ``CONFIGURE_TASK_STACK_DEALLOCATOR`` -*DATA TYPE:* +DATA TYPE: Function pointer. -*RANGE:* +RANGE: Undefined or valid function pointer. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is ``_Workspace_Free``, which indicates that task stacks will be allocated from the RTEMS Workspace. -**DESCRIPTION:** - -``CONFIGURE_TASK_STACK_DEALLOCATOR`` may point to a user provided routine to -free task stacks. - -**NOTES:** +DESCRIPTION: + ``CONFIGURE_TASK_STACK_DEALLOCATOR`` may point to a user provided routine + to free task stacks. -A correctly configured system must configure the following to be consistent: +NOTES: + A correctly configured system must configure the following to be consistent: - ``CONFIGURE_TASK_STACK_ALLOCATOR_INIT`` @@ -2224,36 +2133,36 @@ Calculate Memory for a Single Classic Message API Message Queue .. index:: CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE .. index:: memory for a single message queue's buffers -*CONSTANT:* +CONSTANT: ``CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE(max_messages, size_per)`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``size_t``). -*RANGE:* +RANGE: Positive. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is None. -**DESCRIPTION:** +DESCRIPTION: + This is a helper macro which is used to assist in computing the total + amount of memory required for message buffers. Each message queue will + have its own configuration with maximum message size and maximum number of + pending messages. -This is a helper macro which is used to assist in computing the total amount of -memory required for message buffers. Each message queue will have its own -configuration with maximum message size and maximum number of pending messages. + The interface for this macro is as follows: -The interface for this macro is as follows: - -.. code-block:: c + .. code-block:: c - CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE(max_messages, size_per) + CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE(max_messages, size_per) -Where ``max_messages`` is the maximum number of pending messages and -``size_per`` is the size in bytes of the user message. + Where ``max_messages`` is the maximum number of pending messages and + ``size_per`` is the size in bytes of the user message. -**NOTES:** +NOTES: -This macro is only used in support of ``CONFIGURE_MESSAGE_BUFFER_MEMORY``. + This macro is only used in support of ``CONFIGURE_MESSAGE_BUFFER_MEMORY``. .. COMMENT: === CONFIGURE_MESSAGE_BUFFER_MEMORY === @@ -2264,42 +2173,41 @@ Reserve Memory for All Classic Message API Message Queues .. index:: CONFIGURE_MESSAGE_BUFFER_MEMORY .. index:: configure message queue buffer memory -*CONSTANT:* +CONSTANT: ``CONFIGURE_MESSAGE_BUFFER_MEMORY`` -*DATA TYPE:* +DATA TYPE: integer summation macro -*RANGE:* +RANGE: undefined (zero) or calculation resulting in a positive integer -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default, and zero (0) memory is reserved. -**DESCRIPTION:** - -This macro is set to the number of bytes the application requires to be -reserved for pending Classic API Message Queue buffers. - -**NOTES:** - -The following illustrates how the help macro -``CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE`` 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 maximum of 24 -pending messages with the message structure defined by the type -``one_message_type``. The other message queue has 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) \ - ) +DESCRIPTION: + This macro is set to the number of bytes the application requires to be + reserved for pending Classic API Message Queue buffers. + +NOTES: + The following illustrates how the help macro + ``CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE`` 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 + maximum of 24 pending messages with the message structure defined by the + type ``one_message_type``. The other message queue has 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) \ + ) .. COMMENT: === Seldom Used Configuration Parameters === @@ -2319,29 +2227,27 @@ Specify Memory Overhead ----------------------- .. index:: CONFIGURE_MEMORY_OVERHEAD -*CONSTANT:* +CONSTANT: ``CONFIGURE_MEMORY_OVERHEAD`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``size_t``). -*RANGE:* +RANGE: Zero or positive. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is 0. -**DESCRIPTION:** - -Thie parameter is set to the number of kilobytes the application wishes to add -to the requirements calculated by ``<rtems/confdefs.h>``. - -**NOTES:** +DESCRIPTION: + This parameter is set to the number of kilobytes the application wishes to + add to the requirements calculated by ``<rtems/confdefs.h>``. -This configuration parameter 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. +NOTES: + This configuration parameter 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. .. COMMENT: === CONFIGURE_HAS_OWN_CONFIGURATION_TABLE === @@ -2351,26 +2257,24 @@ Do Not Generate Configuration Information ----------------------------------------- .. index:: CONFIGURE_HAS_OWN_CONFIGURATION_TABLE -*CONSTANT:* +CONSTANT: ``CONFIGURE_HAS_OWN_CONFIGURATION_TABLE`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. -**DESCRIPTION:** +DESCRIPTION: + This configuration parameter should only be defined if the application is + providing their own complete set of configuration tables. -This configuration parameter should only be defined if the application is -providing their own complete set of configuration tables. - -**NOTES:** - -None. +NOTES: + None. .. COMMENT: === C Library Support Configuration === @@ -2389,29 +2293,27 @@ Specify Maximum Number of File Descriptors .. index:: CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS .. index:: maximum file descriptors -*CONSTANT:* +CONSTANT: ``CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``uint32_t``). -*RANGE:* +RANGE: Zero or positive. -*DEFAULT VALUE:* +DEFAULT VALUE: If ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`` is defined, then the default value is 3, otherwise the default value is 0. Three file descriptors allows RTEMS to support standard input, output, and error I/O streams on ``/dev/console``. -**DESCRIPTION:** - -This configuration parameter is set to the maximum number of file like objects -that can be concurrently open. +DESCRIPTION: + This configuration parameter is set to the maximum number of file like + objects that can be concurrently open. -**NOTES:** - -None. +NOTES: + None. .. COMMENT: === CONFIGURE_TERMIOS_DISABLED === @@ -2421,28 +2323,27 @@ Disable POSIX Termios Support ----------------------------- .. index:: CONFIGURE_TERMIOS_DISABLED -*CONSTANT:* +CONSTANT: ``CONFIGURE_TERMIOS_DISABLED`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default, and resources are reserved for the termios functionality. -**DESCRIPTION:** - -This configuration parameter is defined if the software implementing POSIX -termios functionality is not going to be used by this application. +DESCRIPTION: + This configuration parameter is defined if the software implementing POSIX + termios functionality is not going to be used by this application. -**NOTES:** - -The termios support library should not be included in an application executable -unless it is directly referenced by the application or a device driver. +NOTES: + The termios support library should not be included in an application + executable unless it is directly referenced by the application or a device + driver. .. COMMENT: === CONFIGURE_NUMBER_OF_TERMIOS_PORTS === @@ -2452,28 +2353,28 @@ Specify Maximum Termios Ports ----------------------------- .. index:: CONFIGURE_NUMBER_OF_TERMIOS_PORTS -*CONSTANT:* +CONSTANT: ``CONFIGURE_NUMBER_OF_TERMIOS_PORTS`` -*DATA TYPE:* +DATA TYPE: Unsigned integer. -*RANGE:* +RANGE: Zero or positive. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is 1, so a console port can be used. -**DESCRIPTION:** - -This configuration parameter is set to the number of ports using the termios -functionality. Each concurrently active termios port requires resources. - -**NOTES:** +DESCRIPTION: + This configuration parameter is set to the number of ports using the + termios functionality. Each concurrently active termios port requires + resources. -If the application will be using serial ports including, but not limited to, -the Console Device (e.g. ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER``), then -it is highly likely that this configuration parameter should NOT be is defined. +NOTES: + If the application will be using serial ports including, but not limited + to, the Console Device + (e.g. ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER``), then it is highly + likely that this configuration parameter should NOT be is defined. .. COMMENT: === File System Configuration Parameters === @@ -2490,31 +2391,29 @@ Providing Application Specific Mount Table ------------------------------------------ .. index:: CONFIGURE_HAS_OWN_MOUNT_TABLE -*CONSTANT:* +CONSTANT: ``CONFIGURE_HAS_OWN_MOUNT_TABLE`` -*DATA TYPE:* +DATA TYPE: Undefined or an array of type ``rtems_filesystem_mount_table_t``. -*RANGE:* +RANGE: Undefined or an array of type ``rtems_filesystem_mount_table_t``. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. -**DESCRIPTION:** - -This configuration parameter is defined when the application provides their own -filesystem mount table. The mount table is an array of -``rtems_filesystem_mount_table_t`` entries pointed to by the global variable -``rtems_filesystem_mount_table``. The number of entries in this table is in an -integer variable named ``rtems_filesystem_mount_table_t``. +DESCRIPTION: + This configuration parameter is defined when the application provides their + own filesystem mount table. The mount table is an array of + ``rtems_filesystem_mount_table_t`` entries pointed to by the global + variable ``rtems_filesystem_mount_table``. The number of entries in this + table is in an integer variable named ``rtems_filesystem_mount_table_t``. .. COMMENT: XXX - is the variable name for the count right? -**NOTES:** - -None. +NOTES: + None. .. COMMENT: XXX - Please provide an example @@ -2526,31 +2425,29 @@ Configure devFS as Root File System ----------------------------------- .. index:: CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM -*CONSTANT:* +CONSTANT: ``CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. If no other root file system configuration parameters are specified, the IMFS will be used as the root file system. -**DESCRIPTION:** +DESCRIPTION: + This configuration parameter is defined if the application wishes to use + the device-only filesytem as the root file system. -This configuration parameter is defined if the application wishes to use the -device-only filesytem as the root file system. +NOTES: + The device-only filesystem supports only device nodes and is smaller in + executable code size than the full IMFS and miniIMFS. -**NOTES:** - -The device-only filesystem supports only device nodes and is smaller in -executable code size than the full IMFS and miniIMFS. - -The devFS is comparable in functionality to the pseudo-filesystem name space -provided before RTEMS release 4.5.0. + The devFS is comparable in functionality to the pseudo-filesystem name + space provided before RTEMS release 4.5.0. .. COMMENT: === CONFIGURE_MAXIMUM_DEVICES === @@ -2560,30 +2457,28 @@ Specifying Maximum Devices for devFS ------------------------------------ .. index:: CONFIGURE_MAXIMUM_DEVICES -*CONSTANT:* +CONSTANT: ``CONFIGURE_MAXIMUM_DEVICES`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``uint32_t``). -*RANGE:* +RANGE: Positive. -*DEFAULT VALUE:* +DEFAULT VALUE: If ``BSP_MAXIMUM_DEVICES`` is defined, then the default value is ``BSP_MAXIMUM_DEVICES``, otherwise the default value is 4. -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_DEVICES`` is defined to the number of individual devices -that may be registered in the device file system (devFS). - -**NOTES:** +DESCRIPTION: + ``CONFIGURE_MAXIMUM_DEVICES`` is defined to the number of individual + devices that may be registered in the device file system (devFS). -This option is specific to the device file system (devFS) and should not be -confused with the ``CONFIGURE_MAXIMUM_DRIVERS`` option. This parameter only -impacts the devFS and thus is only used by ``<rtems/confdefs.h>`` when -``CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM`` is specified. +NOTES: + This option is specific to the device file system (devFS) and should not be + confused with the ``CONFIGURE_MAXIMUM_DRIVERS`` option. This parameter + only impacts the devFS and thus is only used by ``<rtems/confdefs.h>`` when + ``CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM`` is specified. .. COMMENT: === CONFIGURE_APPLICATION_DISABLE_FILESYSTEM === @@ -2593,28 +2488,26 @@ Disable File System Support --------------------------- .. index:: CONFIGURE_APPLICATION_DISABLE_FILESYSTEM -*CONSTANT:* +CONSTANT: ``CONFIGURE_APPLICATION_DISABLE_FILESYSTEM`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. If no other root file system configuration parameters are specified, the IMFS will be used as the root file system. -**DESCRIPTION:** +DESCRIPTION: + This configuration parameter is defined if the application dose not intend + to use any kind of filesystem support. This include the device + infrastructure necessary to support ``printf()``. -This configuration parameter is defined if the application dose not intend to -use any kind of filesystem support. This include the device infrastructure -necessary to support ``printf()``. - -**NOTES:** - -None. +NOTES: + None. .. COMMENT: === CONFIGURE_USE_MINIIMFS_AS_BASE_FILESYSTEM === @@ -2624,38 +2517,37 @@ Use a Root IMFS with a Minimalistic Feature Set ----------------------------------------------- .. index:: CONFIGURE_USE_MINIIMFS_AS_BASE_FILESYSTEM -*CONSTANT:* +CONSTANT: ``CONFIGURE_USE_MINIIMFS_AS_BASE_FILESYSTEM`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. -**DESCRIPTION:** - -In case this configuration option is defined, then the following configuration -options will be defined as well +DESCRIPTION: + In case this configuration option is defined, then the following + configuration options will be defined as well -- ``CONFIGURE_IMFS_DISABLE_CHMOD``, + - ``CONFIGURE_IMFS_DISABLE_CHMOD``, -- ``CONFIGURE_IMFS_DISABLE_CHOWN``, + - ``CONFIGURE_IMFS_DISABLE_CHOWN``, -- ``CONFIGURE_IMFS_DISABLE_UTIME``, + - ``CONFIGURE_IMFS_DISABLE_UTIME``, -- ``CONFIGURE_IMFS_DISABLE_LINK``, + - ``CONFIGURE_IMFS_DISABLE_LINK``, -- ``CONFIGURE_IMFS_DISABLE_SYMLINK``, + - ``CONFIGURE_IMFS_DISABLE_SYMLINK``, -- ``CONFIGURE_IMFS_DISABLE_READLINK``, + - ``CONFIGURE_IMFS_DISABLE_READLINK``, -- ``CONFIGURE_IMFS_DISABLE_RENAME``, and + - ``CONFIGURE_IMFS_DISABLE_RENAME``, and -- ``CONFIGURE_IMFS_DISABLE_UNMOUNT``. + - ``CONFIGURE_IMFS_DISABLE_UNMOUNT``. .. COMMENT: === CONFIGURE_IMFS_MEMFILE_BYTES_PER_BLOCK === @@ -2665,48 +2557,47 @@ Specify Block Size for IMFS --------------------------- .. index:: CONFIGURE_IMFS_MEMFILE_BYTES_PER_BLOCK -*CONSTANT:* +CONSTANT: ``CONFIGURE_IMFS_MEMFILE_BYTES_PER_BLOCK`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Valid values for this configuration parameter are a power of two (2) between 16 and 512 inclusive. In other words, valid values are 16, 32, 64, 128, 256,and 512. -*DEFAULT VALUE:* +DEFAULT VALUE: The default IMFS block size is 128 bytes. -**DESCRIPTION:** +DESCRIPTION: + This configuration parameter specifies the block size for in-memory files + managed by the IMFS. 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. -This configuration parameter specifies the block size for in-memory files -managed by the IMFS. 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: -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 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 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 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. -- when the block size is 128 bytes, the maximum file size is 4,329,344 bytes. + - when the block size is 256 bytes, the maximum file size is 68,173,568 bytes. -- when the block size is 256 bytes, the maximum file size is 68,173,568 bytes. - -- when the block size is 512 bytes, the maximum file size is 1,082,195,456 - bytes. + - when the block size is 512 bytes, the maximum file size is 1,082,195,456 + bytes. .. COMMENT: === CONFIGURE_IMFS_DISABLE_CHOWN === @@ -2716,22 +2607,21 @@ Disable Change Owner Support of Root IMFS ----------------------------------------- .. index:: CONFIGURE_IMFS_DISABLE_CHOWN -*CONSTANT:* +CONSTANT: ``CONFIGURE_IMFS_DISABLE_CHOWN`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. -**DESCRIPTION:** - -In case this configuration option is defined, then the support to change the -owner is disabled in the root IMFS. +DESCRIPTION: + In case this configuration option is defined, then the support to change + the owner is disabled in the root IMFS. .. COMMENT: === CONFIGURE_IMFS_DISABLE_CHMOD === @@ -2741,22 +2631,21 @@ Disable Change Mode Support of Root IMFS ---------------------------------------- .. index:: CONFIGURE_IMFS_DISABLE_CHMOD -*CONSTANT:* +CONSTANT: ``CONFIGURE_IMFS_DISABLE_CHMOD`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. -**DESCRIPTION:** - -In case this configuration option is defined, then the support to change the -mode is disabled in the root IMFS. +DESCRIPTION: + In case this configuration option is defined, then the support to change + the mode is disabled in the root IMFS. .. COMMENT: === CONFIGURE_IMFS_DISABLE_UTIME === @@ -2766,22 +2655,21 @@ Disable Change Times Support of Root IMFS ----------------------------------------- .. index:: CONFIGURE_IMFS_DISABLE_UTIME -*CONSTANT:* +CONSTANT: ``CONFIGURE_IMFS_DISABLE_UTIME`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. -**DESCRIPTION:** - -In case this configuration option is defined, then the support to change times -is disabled in the root IMFS. +DESCRIPTION: + In case this configuration option is defined, then the support to change + times is disabled in the root IMFS. .. COMMENT: === CONFIGURE_IMFS_DISABLE_LINK === @@ -2791,22 +2679,21 @@ Disable Create Hard Link Support of Root IMFS --------------------------------------------- .. index:: CONFIGURE_IMFS_DISABLE_LINK -*CONSTANT:* +CONSTANT: ``CONFIGURE_IMFS_DISABLE_LINK`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. -**DESCRIPTION:** - -In case this configuration option is defined, then the support to create hard -links is disabled in the root IMFS. +DESCRIPTION: + In case this configuration option is defined, then the support to create + hard links is disabled in the root IMFS. .. COMMENT: === CONFIGURE_IMFS_DISABLE_SYMLINK === @@ -2816,22 +2703,21 @@ Disable Create Symbolic Link Support of Root IMFS ------------------------------------------------- .. index:: CONFIGURE_IMFS_DISABLE_SYMLINK -*CONSTANT:* +CONSTANT: ``CONFIGURE_IMFS_DISABLE_SYMLINK`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. -**DESCRIPTION:** - -In case this configuration option is defined, then the support to create -symbolic links is disabled in the root IMFS. +DESCRIPTION: + In case this configuration option is defined, then the support to create + symbolic links is disabled in the root IMFS. .. COMMENT: === CONFIGURE_IMFS_DISABLE_READLINK === @@ -2841,22 +2727,21 @@ Disable Read Symbolic Link Support of Root IMFS ----------------------------------------------- .. index:: CONFIGURE_IMFS_DISABLE_READLINK -*CONSTANT:* +CONSTANT: ``CONFIGURE_IMFS_DISABLE_READLINK`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. -**DESCRIPTION:** - -In case this configuration option is defined, then the support to read symbolic -links is disabled in the root IMFS. +DESCRIPTION: + In case this configuration option is defined, then the support to read + symbolic links is disabled in the root IMFS. .. COMMENT: === CONFIGURE_IMFS_DISABLE_RENAME === @@ -2866,22 +2751,21 @@ Disable Rename Support of Root IMFS ----------------------------------- .. index:: CONFIGURE_IMFS_DISABLE_RENAME -*CONSTANT:* +CONSTANT: ``CONFIGURE_IMFS_DISABLE_RENAME`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. -**DESCRIPTION:** - -In case this configuration option is defined, then the support to rename nodes -is disabled in the root IMFS. +DESCRIPTION: + In case this configuration option is defined, then the support to rename + nodes is disabled in the root IMFS. .. COMMENT: === CONFIGURE_IMFS_DISABLE_READDIR === @@ -2891,23 +2775,22 @@ Disable Directory Read Support of Root IMFS ------------------------------------------- .. index:: CONFIGURE_IMFS_DISABLE_READDIR -*CONSTANT:* +CONSTANT: ``CONFIGURE_IMFS_DISABLE_READDIR`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. -**DESCRIPTION:** - -In case this configuration option is defined, then the support to read a -directory is disabled in the root IMFS. It is still possible to open nodes in -a directory. +DESCRIPTION: + In case this configuration option is defined, then the support to read a + directory is disabled in the root IMFS. It is still possible to open nodes + in a directory. .. COMMENT: === CONFIGURE_IMFS_DISABLE_MOUNT === @@ -2917,22 +2800,21 @@ Disable Mount Support of Root IMFS ---------------------------------- .. index:: CONFIGURE_IMFS_DISABLE_MOUNT -*CONSTANT:* +CONSTANT: ``CONFIGURE_IMFS_DISABLE_MOUNT`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. -**DESCRIPTION:** - -In case this configuration option is defined, then the support to mount other -file systems is disabled in the root IMFS. +DESCRIPTION: + In case this configuration option is defined, then the support to mount + other file systems is disabled in the root IMFS. .. COMMENT: === CONFIGURE_IMFS_DISABLE_UNMOUNT === @@ -2942,22 +2824,21 @@ Disable Unmount Support of Root IMFS ------------------------------------ .. index:: CONFIGURE_IMFS_DISABLE_UNMOUNT -*CONSTANT:* +CONSTANT: ``CONFIGURE_IMFS_DISABLE_UNMOUNT`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. -**DESCRIPTION:** - -In case this configuration option is defined, then the support to unmount file -systems is disabled in the root IMFS. +DESCRIPTION: + In case this configuration option is defined, then the support to unmount + file systems is disabled in the root IMFS. .. COMMENT: === CONFIGURE_IMFS_DISABLE_MKNOD === @@ -2967,22 +2848,21 @@ Disable Make Nodes Support of Root IMFS --------------------------------------- .. index:: CONFIGURE_IMFS_DISABLE_MKNOD -*CONSTANT:* +CONSTANT: ``CONFIGURE_IMFS_DISABLE_MKNOD`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. -**DESCRIPTION:** - -In case this configuration option is defined, then the support to make -directories, devices, regular files and FIFOs is disabled in the root IMFS. +DESCRIPTION: + In case this configuration option is defined, then the support to make + directories, devices, regular files and FIFOs is disabled in the root IMFS. .. COMMENT: === CONFIGURE_IMFS_DISABLE_MKNOD_FILE === @@ -2992,22 +2872,21 @@ Disable Make Files Support of Root IMFS --------------------------------------- .. index:: CONFIGURE_IMFS_DISABLE_MKNOD_FILE -*CONSTANT:* +CONSTANT: ``CONFIGURE_IMFS_DISABLE_MKNOD_FILE`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. -**DESCRIPTION:** - -In case this configuration option is defined, then the support to make regular -files is disabled in the root IMFS. +DESCRIPTION: + In case this configuration option is defined, then the support to make + regular files is disabled in the root IMFS. .. COMMENT: === CONFIGURE_IMFS_DISABLE_RMNOD === @@ -3017,22 +2896,21 @@ Disable Remove Nodes Support of Root IMFS ----------------------------------------- .. index:: CONFIGURE_IMFS_DISABLE_RMNOD -*CONSTANT:* +CONSTANT: ``CONFIGURE_IMFS_DISABLE_RMNOD`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. -**DESCRIPTION:** - -In case this configuration option is defined, then the support to remove nodes -is disabled in the root IMFS. +DESCRIPTION: + In case this configuration option is defined, then the support to remove + nodes is disabled in the root IMFS. .. COMMENT: === Block Device Cache Configuration === @@ -3050,27 +2928,25 @@ Enable Block Device Cache ------------------------- .. index:: CONFIGURE_APPLICATION_NEEDS_LIBBLOCK -*CONSTANT:* +CONSTANT: ``CONFIGURE_APPLICATION_NEEDS_LIBBLOCK`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. -**DESCRIPTION:** - -Provides a Block Device Cache configuration. - -**NOTES:** +DESCRIPTION: + Provides a Block Device Cache configuration. -Each option of the Block Device Cache 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 file systems. +NOTES: + Each option of the Block Device Cache 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 file systems. .. COMMENT: === CONFIGURE_BDBUF_CACHE_MEMORY_SIZE === @@ -3080,25 +2956,23 @@ Size of the Cache Memory ------------------------ .. index:: CONFIGURE_BDBUF_CACHE_MEMORY_SIZE -*CONSTANT:* +CONSTANT: ``CONFIGURE_BDBUF_CACHE_MEMORY_SIZE`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``size_t``). -*RANGE:* +RANGE: Positive. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is 32768 bytes. -**DESCRIPTION:** +DESCRIPTION: + Size of the cache memory in bytes. -Size of the cache memory in bytes. - -**NOTES:** - -None. +NOTES: + None. .. COMMENT: === CONFIGURE_BDBUF_BUFFER_MIN_SIZE === @@ -3108,25 +2982,23 @@ Minimum Size of a Buffer ------------------------ .. index:: CONFIGURE_BDBUF_BUFFER_MIN_SIZE -*CONSTANT:* +CONSTANT: ``CONFIGURE_BDBUF_BUFFER_MIN_SIZE`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``uint32_t``). -*RANGE:* +RANGE: Positive. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is 512 bytes. -**DESCRIPTION:** - -Defines the minimum size of a buffer in bytes. +DESCRIPTION: + Defines the minimum size of a buffer in bytes. -**NOTES:** - -None. +NOTES: + None. .. COMMENT: === CONFIGURE_BDBUF_BUFFER_MAX_SIZE === @@ -3136,25 +3008,23 @@ Maximum Size of a Buffer ------------------------ .. index:: CONFIGURE_BDBUF_BUFFER_MAX_SIZE -*CONSTANT:* +CONSTANT: ``CONFIGURE_BDBUF_BUFFER_MAX_SIZE`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``uint32_t``). -*RANGE:* +RANGE: It must be positive and an integral multiple of the buffer minimum size. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is 4096 bytes. -**DESCRIPTION:** - -Defines the maximum size of a buffer in bytes. +DESCRIPTION: + Defines the maximum size of a buffer in bytes. -**NOTES:** - -None. +NOTES: + None. .. COMMENT: === CONFIGURE_SWAPOUT_SWAP_PERIOD === @@ -3164,25 +3034,23 @@ Swapout Task Swap Period ------------------------ .. index:: CONFIGURE_SWAPOUT_SWAP_PERIOD -*CONSTANT:* +CONSTANT: ``CONFIGURE_SWAPOUT_SWAP_PERIOD`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``uint32_t``). -*RANGE:* +RANGE: Positive. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is 250 milliseconds. -**DESCRIPTION:** - -Defines the swapout task swap period in milliseconds. - -**NOTES:** +DESCRIPTION: + Defines the swapout task swap period in milliseconds. -None. +NOTES: + None. .. COMMENT: === CONFIGURE_SWAPOUT_BLOCK_HOLD === @@ -3192,25 +3060,23 @@ Swapout Task Maximum Block Hold Time ------------------------------------ .. index:: CONFIGURE_SWAPOUT_BLOCK_HOLD -*CONSTANT:* +CONSTANT: ``CONFIGURE_SWAPOUT_BLOCK_HOLD`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``uint32_t``). -*RANGE:* +RANGE: Positive. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is 1000 milliseconds. -**DESCRIPTION:** - -Defines the swapout task maximum block hold time in milliseconds. - -**NOTES:** +DESCRIPTION: + Defines the swapout task maximum block hold time in milliseconds. -None. +NOTES: + None. .. COMMENT: === CONFIGURE_SWAPOUT_TASK_PRIORITY === @@ -3220,25 +3086,23 @@ Swapout Task Priority --------------------- .. index:: CONFIGURE_SWAPOUT_TASK_PRIORITY -*CONSTANT:* +CONSTANT: ``CONFIGURE_SWAPOUT_TASK_PRIORITY`` -*DATA TYPE:* +DATA TYPE: Task priority (``rtems_task_priority``). -*RANGE:* +RANGE: Valid task priority. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is 15. -**DESCRIPTION:** +DESCRIPTION: + Defines the swapout task priority. -Defines the swapout task priority. - -**NOTES:** - -None. +NOTES: + None. .. COMMENT: === CONFIGURE_BDBUF_MAX_READ_AHEAD_BLOCKS === @@ -3248,27 +3112,25 @@ Maximum Blocks per Read-Ahead Request ------------------------------------- .. index:: CONFIGURE_BDBUF_MAX_READ_AHEAD_BLOCKS -*CONSTANT:* +CONSTANT: ``CONFIGURE_BDBUF_MAX_READ_AHEAD_BLOCKS`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``uint32_t``). -*RANGE:* +RANGE: Positive. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is 0. -**DESCRIPTION:** - -Defines the maximum blocks per read-ahead request. +DESCRIPTION: + Defines the maximum blocks per read-ahead request. -**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. +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. .. COMMENT: === CONFIGURE_BDBUF_MAX_WRITE_BLOCKS === @@ -3278,25 +3140,23 @@ Maximum Blocks per Write Request -------------------------------- .. index:: CONFIGURE_BDBUF_MAX_WRITE_BLOCKS -*CONSTANT:* +CONSTANT: ``CONFIGURE_BDBUF_MAX_WRITE_BLOCKS`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``uint32_t``). -*RANGE:* +RANGE: Positive. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is 16. -**DESCRIPTION:** - -Defines the maximum blocks per write request. +DESCRIPTION: + Defines the maximum blocks per write request. -**NOTES:** - -None. +NOTES: + None. .. COMMENT: === CONFIGURE_BDBUF_TASK_STACK_SIZE === @@ -3306,25 +3166,23 @@ Task Stack Size of the Block Device Cache Tasks ----------------------------------------------- .. index:: CONFIGURE_BDBUF_TASK_STACK_SIZE -*CONSTANT:* +CONSTANT: ``CONFIGURE_BDBUF_TASK_STACK_SIZE`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``size_t``). -*RANGE:* +RANGE: Zero or positive. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is RTEMS_MINIMUM_STACK_SIZE. -**DESCRIPTION:** - -Defines the task stack size of the Block Device Cache tasks in bytes. - -**NOTES:** +DESCRIPTION: + Defines the task stack size of the Block Device Cache tasks in bytes. -None. +NOTES: + None. .. COMMENT: === CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY === @@ -3334,25 +3192,23 @@ Read-Ahead Task Priority ------------------------ .. index:: CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY -*CONSTANT:* +CONSTANT: ``CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY`` -*DATA TYPE:* +DATA TYPE: Task priority (``rtems_task_priority``). -*RANGE:* +RANGE: Valid task priority. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is 15. -**DESCRIPTION:** - -Defines the read-ahead task priority. - -**NOTES:** +DESCRIPTION: + Defines the read-ahead task priority. -None. +NOTES: + None. .. COMMENT: === CONFIGURE_SWAPOUT_WORKER_TASKS === @@ -3362,25 +3218,23 @@ Swapout Worker Task Count ------------------------- .. index:: CONFIGURE_SWAPOUT_WORKER_TASKS -*CONSTANT:* +CONSTANT: ``CONFIGURE_SWAPOUT_WORKER_TASKS`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``size_t``). -*RANGE:* +RANGE: Zero or positive. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is 0. -**DESCRIPTION:** +DESCRIPTION: + Defines the swapout worker task count. -Defines the swapout worker task count. - -**NOTES:** - -None. +NOTES: + None. .. COMMENT: === CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY === @@ -3390,25 +3244,23 @@ Swapout Worker Task Priority ---------------------------- .. index:: CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY -*CONSTANT:* +CONSTANT: ``CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY`` -*DATA TYPE:* +DATA TYPE: Task priority (``rtems_task_priority``). -*RANGE:* +RANGE: Valid task priority. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is 15. -**DESCRIPTION:** - -Defines the swapout worker task priority. +DESCRIPTION: + Defines the swapout worker task priority. -**NOTES:** - -None. +NOTES: + None. .. COMMENT: === BSP Specific Settings === @@ -3427,26 +3279,24 @@ Disable BSP Configuration Settings ---------------------------------- .. index:: CONFIGURE_DISABLE_BSP_SETTINGS -*CONSTANT:* +CONSTANT: ``CONFIGURE_DISABLE_BSP_SETTINGS`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. -**DESCRIPTION:** - -All BSP specific configuration settings can be disabled by the application with -the ``CONFIGURE_DISABLE_BSP_SETTINGS`` option. +DESCRIPTION: + All BSP specific configuration settings can be disabled by the application + with the ``CONFIGURE_DISABLE_BSP_SETTINGS`` option. -**NOTES:** - -None. +NOTES: + None. .. COMMENT: === CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK === @@ -3456,31 +3306,29 @@ Specify BSP Supports sbrk() --------------------------- .. index:: CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK -*CONSTANT:* +CONSTANT: ``CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This option is BSP specific. -**DESCRIPTION:** - -This configuration parameter is defined by a BSP to indicate that it does not -allocate all available memory to the C Program Heap used by the Malloc Family -of routines. - -If defined, when ``malloc()`` is unable to allocate memory, it will call the -BSP supplied ``sbrk()`` to obtain more memory. +DESCRIPTION: + This configuration parameter is defined by a BSP to indicate that it does + not allocate all available memory to the C Program Heap used by the Malloc + Family of routines. -**NOTES:** + If defined, when ``malloc()`` is unable to allocate memory, it will call + the BSP supplied ``sbrk()`` to obtain more memory. -This parameter should not be defined by the application. Only the BSP knows how -it allocates memory to the C Program Heap. +NOTES: + This parameter should not be defined by the application. Only the BSP knows + how it allocates memory to the C Program Heap. .. COMMENT: === BSP_IDLE_TASK_BODY === @@ -3490,29 +3338,27 @@ Specify BSP Specific Idle Task ------------------------------ .. index:: BSP_IDLE_TASK_BODY -*CONSTANT:* +CONSTANT: ``BSP_IDLE_TASK_BODY`` -*DATA TYPE:* +DATA TYPE: Function pointer. -*RANGE:* +RANGE: Undefined or valid function pointer. -*DEFAULT VALUE:* +DEFAULT VALUE: This option is BSP specific. -**DESCRIPTION:** - -If ``BSP_IDLE_TASK_BODY`` is defined by the BSP and -``CONFIGURE_IDLE_TASK_BODY`` is not defined by the application, then this BSP -specific idle task body will be used. - -**NOTES:** +DESCRIPTION: + If ``BSP_IDLE_TASK_BODY`` is defined by the BSP and + ``CONFIGURE_IDLE_TASK_BODY`` is not defined by the application, then this + BSP specific idle task body will be used. -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 +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 .. COMMENT: === BSP_IDLE_TASK_STACK_SIZE === @@ -3522,35 +3368,33 @@ Specify BSP Suggested Value for IDLE Task Stack Size ---------------------------------------------------- .. index:: BSP_IDLE_TASK_STACK_SIZE -*CONSTANT:* +CONSTANT: ``BSP_IDLE_TASK_STACK_SIZE`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``size_t``). -*RANGE:* +RANGE: Undefined or positive. -*DEFAULT VALUE:* +DEFAULT VALUE: This option is BSP specific. -**DESCRIPTION:** +DESCRIPTION: + If ``BSP_IDLE_TASK_STACK_SIZE`` is defined by the BSP and + ``CONFIGURE_IDLE_TASK_STACK_SIZE`` is not defined by the application, then + this BSP suggested idle task stack size will be used. -If ``BSP_IDLE_TASK_STACK_SIZE`` is defined by the BSP and -``CONFIGURE_IDLE_TASK_STACK_SIZE`` is not defined by the application, then this -BSP suggested idle task stack size will be used. +NOTES: + The order of precedence for configuring the IDLE task stack size is: -**NOTES:** + - RTEMS default minimum stack size. -The order of precedence for configuring the IDLE task stack size is: + - If defined, then ``CONFIGURE_MINIMUM_TASK_STACK_SIZE``. -- RTEMS default minimum stack size. + - If defined, then the BSP specific ``BSP_IDLE_TASK_SIZE``. -- If defined, then ``CONFIGURE_MINIMUM_TASK_STACK_SIZE``. - -- If defined, then the BSP specific ``BSP_IDLE_TASK_SIZE``. - -- If defined, then the application specified ``CONFIGURE_IDLE_TASK_SIZE``. + - If defined, then the application specified ``CONFIGURE_IDLE_TASK_SIZE``. .. COMMENT: XXX - add cross references to other related values. @@ -3562,27 +3406,25 @@ Specify BSP Specific User Extensions ------------------------------------ .. index:: BSP_INITIAL_EXTENSION -*CONSTANT:* +CONSTANT: ``BSP_INITIAL_EXTENSION`` -*DATA TYPE:* +DATA TYPE: List of user extension initializers (``rtems_extensions_table``). -*RANGE:* +RANGE: Undefined or a list of user extension initializers. -*DEFAULT VALUE:* +DEFAULT VALUE: This option is BSP specific. -**DESCRIPTION:** - -If ``BSP_INITIAL_EXTENSION`` is defined by the BSP, then this BSP specific -initial extension will be placed as the last entry in the initial extension -table. +DESCRIPTION: + If ``BSP_INITIAL_EXTENSION`` is defined by the BSP, then this BSP specific + initial extension will be placed as the last entry in the initial extension + table. -**NOTES:** - -None. +NOTES: + None. .. COMMENT: === BSP_INTERRUPT_STACK_SIZE === @@ -3592,27 +3434,25 @@ Specifying BSP Specific Interrupt Stack Size -------------------------------------------- .. index:: BSP_INTERRUPT_STACK_SIZE -*CONSTANT:* +CONSTANT: ``BSP_INTERRUPT_STACK_SIZE`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``size_t``). -*RANGE:* +RANGE: Undefined or positive. -*DEFAULT VALUE:* +DEFAULT VALUE: This option is BSP specific. -**DESCRIPTION:** - -If ``BSP_INTERRUPT_STACK_SIZE`` is defined by the BSP and -``CONFIGURE_INTERRUPT_STACK_SIZE`` is not defined by the application, then this -BSP specific interrupt stack size will be used. +DESCRIPTION: + If ``BSP_INTERRUPT_STACK_SIZE`` is defined by the BSP and + ``CONFIGURE_INTERRUPT_STACK_SIZE`` is not defined by the application, then + this BSP specific interrupt stack size will be used. -**NOTES:** - -None. +NOTES: + None. .. COMMENT: === BSP_MAXIMUM_DEVICES === @@ -3622,30 +3462,28 @@ Specifying BSP Specific Maximum Devices --------------------------------------- .. index:: BSP_MAXIMUM_DEVICES -*CONSTANT:* +CONSTANT: ``BSP_MAXIMUM_DEVICES`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``size_t``). -*RANGE:* +RANGE: Undefined or positive. -*DEFAULT VALUE:* +DEFAULT VALUE: This option is BSP specific. -**DESCRIPTION:** - -If ``BSP_MAXIMUM_DEVICES`` is defined by the BSP and -``CONFIGURE_MAXIMUM_DEVICES`` is not defined by the application, then this BSP -specific maximum device count will be used. +DESCRIPTION: + If ``BSP_MAXIMUM_DEVICES`` is defined by the BSP and + ``CONFIGURE_MAXIMUM_DEVICES`` is not defined by the application, then this + BSP specific maximum device count will be used. -**NOTES:** - -This option is specific to the device file system (devFS) and should not be -confused with the ``CONFIGURE_MAXIMUM_DRIVERS`` option. This parameter only -impacts the devFS and thus is only used by ``<rtems/confdefs.h>`` when -``CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM`` is specified. +NOTES: + This option is specific to the device file system (devFS) and should not be + confused with the ``CONFIGURE_MAXIMUM_DRIVERS`` option. This parameter + only impacts the devFS and thus is only used by ``<rtems/confdefs.h>`` when + ``CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM`` is specified. .. COMMENT: === BSP_ZERO_WORKSPACE_AUTOMATICALLY === @@ -3655,28 +3493,26 @@ BSP Recommends RTEMS Workspace be Cleared ----------------------------------------- .. index:: BSP_ZERO_WORKSPACE_AUTOMATICALLY -*CONSTANT:* +CONSTANT: ``BSP_ZERO_WORKSPACE_AUTOMATICALLY`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This option is BSP specific. -**DESCRIPTION:** - -If ``BSP_ZERO_WORKSPACE_AUTOMATICALLY`` is defined by the BSP and -``CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY`` is not defined by the application, -then the workspace will be zeroed automatically. +DESCRIPTION: + If ``BSP_ZERO_WORKSPACE_AUTOMATICALLY`` is defined by the BSP and + ``CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY`` is not defined by the + application, then the workspace will be zeroed automatically. -**NOTES:** - -Zeroing memory can add significantly to system boot time. It is not necessary -for RTEMS but is often assumed by support libraries. +NOTES: + Zeroing memory can add significantly to system boot time. It is not + necessary for RTEMS but is often assumed by support libraries. .. COMMENT: === CONFIGURE_BSP_PREREQUISITE_DRIVERS === @@ -3686,30 +3522,29 @@ Specify BSP Prerequisite Drivers -------------------------------- .. index:: CONFIGURE_BSP_PREREQUISITE_DRIVERS -*CONSTANT:* +CONSTANT: ``CONFIGURE_BSP_PREREQUISITE_DRIVERS`` -*DATA TYPE:* +DATA TYPE: List of device driver initializers (``rtems_driver_address_table``). -*RANGE:* +RANGE: Undefined or array of device drivers. -*DEFAULT VALUE:* +DEFAULT VALUE: This option is BSP specific. -**DESCRIPTION:** - -``CONFIGURE_BSP_PREREQUISITE_DRIVERS`` is defined if the BSP has device drivers -it needs to include in the Device Driver Table. This should be defined to the -set of device driver entries that will be placed in the table at the *FRONT* of -the Device Driver Table and initialized before any other drivers *INCLUDING* -any application prerequisite drivers. - -**NOTES:** +DESCRIPTION: + ``CONFIGURE_BSP_PREREQUISITE_DRIVERS`` is defined if the BSP has device + drivers it needs to include in the Device Driver Table. This should be + defined to the set of device driver entries that will be placed in the + table at the *FRONT* of the Device Driver Table and initialized before any + other drivers *INCLUDING* any application prerequisite drivers. -``CONFIGURE_BSP_PREREQUISITE_DRIVERS`` is typically used by BSPs to configure -common infrastructure such as bus controllers or probe for devices. +NOTES: + ``CONFIGURE_BSP_PREREQUISITE_DRIVERS`` is typically used by BSPs to + configure common infrastructure such as bus controllers or probe for + devices. .. COMMENT: === Idle Task Configuration === @@ -3727,27 +3562,25 @@ Specify Application Specific Idle Task Body ------------------------------------------- .. index:: CONFIGURE_IDLE_TASK_BODY -*CONSTANT:* +CONSTANT: ``CONFIGURE_IDLE_TASK_BODY`` -*DATA TYPE:* +DATA TYPE: Function pointer. -*RANGE:* +RANGE: Undefined or valid function pointer. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. -**DESCRIPTION:** - -``CONFIGURE_IDLE_TASK_BODY`` is set to the function name corresponding to the -application specific IDLE thread body. If not specified, the BSP or RTEMS -default IDLE thread body will be used. - -**NOTES:** +DESCRIPTION: + ``CONFIGURE_IDLE_TASK_BODY`` is set to the function name corresponding to + the application specific IDLE thread body. If not specified, the BSP or + RTEMS default IDLE thread body will be used. -None. +NOTES: + None. .. COMMENT: === CONFIGURE_IDLE_TASK_STACK_SIZE === @@ -3757,26 +3590,24 @@ Specify Idle Task Stack Size ---------------------------- .. index:: CONFIGURE_IDLE_TASK_STACK_SIZE -*CONSTANT:* +CONSTANT: ``CONFIGURE_IDLE_TASK_STACK_SIZE`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``size_t``). -*RANGE:* +RANGE: Undefined or positive. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is RTEMS_MINIMUM_STACK_SIZE. -**DESCRIPTION:** +DESCRIPTION: + ``CONFIGURE_IDLE_TASK_STACK_SIZE`` is set to the desired stack size for the + IDLE task. -``CONFIGURE_IDLE_TASK_STACK_SIZE`` is set to the -desired stack size for the IDLE task. - -**NOTES:** - -None. +NOTES: + None. .. COMMENT: === CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION === @@ -3786,33 +3617,32 @@ Specify Idle Task Performs Application Initialization ----------------------------------------------------- .. index:: CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION -*CONSTANT:* +CONSTANT: ``CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* - This is not defined by default, the user is assumed - to provide one or more initialization tasks. - -**DESCRIPTION:** +DEFAULT VALUE: + This is not defined by default, the user is assumed to provide one or more + initialization tasks. -``CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION`` is set 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. +DESCRIPTION: + ``CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION`` is set 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. -**NOTES:** +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 must make itself preemptible and enter an + IDLE body loop. -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 must make itself preemptible and enter an IDLE body loop. - -The IDLE task must run at the lowest priority of all tasks in the system. + The IDLE task must run at the lowest priority of all tasks in the system. .. COMMENT: === Scheduler Algorithm Configuration === @@ -3837,32 +3667,30 @@ Use Deterministic Priority Scheduler ------------------------------------ .. index:: CONFIGURE_SCHEDULER_PRIORITY -*CONSTANT:* +CONSTANT: ``CONFIGURE_SCHEDULER_PRIORITY`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is defined by default. This is the default scheduler and specifying this configuration parameter is redundant. -**DESCRIPTION:** - -The Deterministic Priority Scheduler is the default scheduler in RTEMS for -uni-processor applications and is designed for predictable performance under -the highest loads. It can block or unblock a thread in a constant amount of -time. This scheduler requires a variable amount of memory based upon the -number of priorities configured in the system. +DESCRIPTION: + The Deterministic Priority Scheduler is the default scheduler in RTEMS for + uni-processor applications and is designed for predictable performance + under the highest loads. It can block or unblock a thread in a constant + amount of time. This scheduler requires a variable amount of memory based + upon the number of priorities configured in the system. -**NOTES:** - -This scheduler may be explicitly selected by defining -``CONFIGURE_SCHEDULER_PRIORITY`` although this is equivalent to the default -behavior. +NOTES: + This scheduler may be explicitly selected by defining + ``CONFIGURE_SCHEDULER_PRIORITY`` although this is equivalent to the default + behavior. .. COMMENT: === CONFIGURE_SCHEDULER_SIMPLE === @@ -3872,34 +3700,32 @@ Use Simple Priority Scheduler ----------------------------- .. index:: CONFIGURE_SCHEDULER_SIMPLE -*CONSTANT:* +CONSTANT: ``CONFIGURE_SCHEDULER_SIMPLE`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. -**DESCRIPTION:** - -When defined, the Simple Priority Scheduler is used at the thread scheduling -algorithm. This is an alternative scheduler in RTEMS. It is designed to -provide the same task scheduling behaviour as the Deterministic Priority -Scheduler while being simpler in implementation and uses less memory for data -management. It maintains a single sorted list of all ready threads. Thus -blocking or unblocking a thread is not a constant time operation with this -scheduler. - -This scheduler may be explicitly selected by defining -``CONFIGURE_SCHEDULER_SIMPLE``. +DESCRIPTION: + When defined, the Simple Priority Scheduler is used at the thread + scheduling algorithm. This is an alternative scheduler in RTEMS. It is + designed to provide the same task scheduling behaviour as the Deterministic + Priority Scheduler while being simpler in implementation and uses less + memory for data management. It maintains a single sorted list of all ready + threads. Thus blocking or unblocking a thread is not a constant time + operation with this scheduler. -**NOTES:** + This scheduler may be explicitly selected by defining + ``CONFIGURE_SCHEDULER_SIMPLE``. -This scheduler is appropriate for use in small systems where RAM is limited. +NOTES: + This scheduler is appropriate for use in small systems where RAM is limited. .. COMMENT: === CONFIGURE_SCHEDULER_EDF === @@ -3909,36 +3735,34 @@ Use Earliest Deadline First Scheduler ------------------------------------- .. index:: CONFIGURE_SCHEDULER_EDF -*CONSTANT:* +CONSTANT: ``CONFIGURE_SCHEDULER_EDF`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. -**DESCRIPTION:** - -The Earliest Deadline First Scheduler (EDF) is an alternative scheduler in -RTEMS for uni-processor applications. The EDF schedules tasks with dynamic -priorities equal to deadlines. The deadlines are declared using only Rate -Monotonic manager which handles periodic behavior. Period is always equal to -deadline. If a task does not have any deadline declared or the deadline is -cancelled, the task is considered a background task which is scheduled in case -no deadline-driven tasks are ready to run. Moreover, multiple background tasks -are scheduled according their priority assigned upon initialization. All ready -tasks reside in a single ready queue. - -This scheduler may be explicitly selected by defining -``CONFIGURE_SCHEDULER_EDF``. +DESCRIPTION: + The Earliest Deadline First Scheduler (EDF) is an alternative scheduler in + RTEMS for uni-processor applications. The EDF schedules tasks with dynamic + priorities equal to deadlines. The deadlines are declared using only Rate + Monotonic manager which handles periodic behavior. Period is always equal + to deadline. If a task does not have any deadline declared or the deadline + is cancelled, the task is considered a background task which is scheduled + in case no deadline-driven tasks are ready to run. Moreover, multiple + background tasks are scheduled according their priority assigned upon + initialization. All ready tasks reside in a single ready queue. -**NOTES:** + This scheduler may be explicitly selected by defining + ``CONFIGURE_SCHEDULER_EDF``. -None. +NOTES: + None. .. COMMENT: === CONFIGURE_SCHEDULER_CBS === @@ -3948,34 +3772,32 @@ Use Constant Bandwidth Server Scheduler --------------------------------------- .. index:: CONFIGURE_SCHEDULER_CBS -*CONSTANT:* +CONSTANT: ``CONFIGURE_SCHEDULER_CBS`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. -**DESCRIPTION:** +DESCRIPTION: + The Constant Bandwidth Server Scheduler (CBS) is an alternative scheduler + in RTEMS for uni-processor applications. The CBS is a budget aware + extension of EDF scheduler. The goal of this scheduler is to ensure + temporal isolation of tasks. The CBS is equipped with a set of additional + rules and provides with an extensive API. -The Constant Bandwidth Server Scheduler (CBS) is an alternative scheduler in -RTEMS for uni-processor applications. The CBS is a budget aware extension of -EDF scheduler. The goal of this scheduler is to ensure temporal isolation of -tasks. The CBS is equipped with a set of additional rules and provides with an -extensive API. - -This scheduler may be explicitly selected by defining -``CONFIGURE_SCHEDULER_CBS``. + This scheduler may be explicitly selected by defining + ``CONFIGURE_SCHEDULER_CBS``. .. COMMENT: XXX - add cross reference to API chapter -**NOTES:** - -None. +NOTES: + None. .. COMMENT: === CONFIGURE_SCHEDULER_PRIORITY_SMP === @@ -3985,34 +3807,32 @@ Use Deterministic Priority SMP Scheduler ---------------------------------------- .. index:: CONFIGURE_SCHEDULER_PRIORITY_SMP -*CONSTANT:* +CONSTANT: ``CONFIGURE_SCHEDULER_PRIORITY_SMP`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. -**DESCRIPTION:** - -The Deterministic Priority SMP Scheduler is derived from the Deterministic -Priority Scheduler but is capable of scheduling threads across multiple -processors. - -In a configuration with SMP enabled at configure time, it may be explicitly -selected by defining ``CONFIGURE_SCHEDULER_PRIORITY_SMP``. +DESCRIPTION: + The Deterministic Priority SMP Scheduler is derived from the Deterministic + Priority Scheduler but is capable of scheduling threads across multiple + processors. -**NOTES:** + In a configuration with SMP enabled at configure time, it may be explicitly + selected by defining ``CONFIGURE_SCHEDULER_PRIORITY_SMP``. -This scheduler is only available when RTEMS is configured with SMP -support enabled. +NOTES: + This scheduler is only available when RTEMS is configured with SMP support + enabled. -This scheduler is currently the default in SMP configurations and is only -selected when ``CONFIGURE_SMP_APPLICATION`` is defined. + This scheduler is currently the default in SMP configurations and is only + selected when ``CONFIGURE_SMP_APPLICATION`` is defined. .. COMMENT: === CONFIGURE_SCHEDULER_SIMPLE_SMP === @@ -4022,40 +3842,38 @@ Use Simple SMP Priority Scheduler --------------------------------- .. index:: CONFIGURE_SCHEDULER_SIMPLE_SMP -*CONSTANT:* +CONSTANT: ``CONFIGURE_SCHEDULER_SIMPLE_SMP`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. -**DESCRIPTION:** +DESCRIPTION: + The Simple SMP Priority Scheduler is derived from the Simple Priority + Scheduler but is capable of scheduling threads across multiple processors. + It is designed to provide the same task scheduling behaviour as the + Deterministic Priority Scheduler while distributing threads across multiple + processors. Being based upon the Simple Priority Scheduler, it also + maintains a single sorted list of all ready threads. Thus blocking or + unblocking a thread is not a constant time operation with this scheduler. -The Simple SMP Priority Scheduler is derived from the Simple Priority Scheduler -but is capable of scheduling threads across multiple processors. It is -designed to provide the same task scheduling behaviour as the Deterministic -Priority Scheduler while distributing threads across multiple processors. -Being based upon the Simple Priority Scheduler, it also maintains a single -sorted list of all ready threads. Thus blocking or unblocking a thread is not -a constant time operation with this scheduler. + In addition, when allocating threads to processors, the algorithm is not + constant time. This algorithm was not designed with efficiency as a primary + design goal. Its primary design goal was to provide an SMP-aware + scheduling algorithm that is simple to understand. -In addition, when allocating threads to processors, the algorithm is not -constant time. This algorithm was not designed with efficiency as a primary -design goal. Its primary design goal was to provide an SMP-aware scheduling -algorithm that is simple to understand. + In a configuration with SMP enabled at configure time, it may be explicitly + selected by defining ``CONFIGURE_SCHEDULER_SIMPLE_SMP``. -In a configuration with SMP enabled at configure time, it may be explicitly -selected by defining ``CONFIGURE_SCHEDULER_SIMPLE_SMP``. - -**NOTES:** - -This scheduler is only available when RTEMS is configured with SMP support -enabled. +NOTES: + This scheduler is only available when RTEMS is configured with SMP support + enabled. .. COMMENT: === Configuring a Scheduler Name === @@ -4065,16 +3883,16 @@ Configuring a Scheduler Name ---------------------------- .. index:: CONFIGURE_SCHEDULER_NAME -*CONSTANT:* +CONSTANT: ``CONFIGURE_SCHEDULER_NAME`` -*DATA TYPE:* +DATA TYPE: RTEMS Name (``rtems_name``). -*RANGE:* +RANGE: Any value. -*DEFAULT VALUE:* +DEFAULT VALUE: The default name is - ``"UCBS"`` for the Uni-Processor CBS scheduler, - ``"UEDF"`` for the Uni-Processor EDF scheduler, @@ -4084,14 +3902,12 @@ Configuring a Scheduler Name - ``"MPD "`` for the Multi-Processor Deterministic Priority scheduler, and - ``"MPS "`` for the Multi-Processor Simple Priority scheduler. -**DESCRIPTION:** - -Schedulers can be identified via ``rtems_scheduler_ident``. The name of the -scheduler is determined by the configuration. +DESCRIPTION: + Schedulers can be identified via ``rtems_scheduler_ident``. The name of + the scheduler is determined by the configuration. -**NOTES:** - -None. +NOTES: + None. .. COMMENT: === Configuring a User Scheduler === @@ -4101,43 +3917,41 @@ Configuring a User Provided Scheduler ------------------------------------- .. index:: CONFIGURE_SCHEDULER_USER -*CONSTANT:* +CONSTANT: ``CONFIGURE_SCHEDULER_USER`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. -**DESCRIPTION:** - -RTEMS allows the application to provide its own task/thread scheduling -algorithm. In order to do this, one must define ``CONFIGURE_SCHEDULER_USER`` to -indicate the application provides its own scheduling algorithm. If -``CONFIGURE_SCHEDULER_USER`` is defined then the following additional macros -must be defined: +DESCRIPTION: + RTEMS allows the application to provide its own task/thread scheduling + algorithm. In order to do this, one must define + ``CONFIGURE_SCHEDULER_USER`` to indicate the application provides its own + scheduling algorithm. If ``CONFIGURE_SCHEDULER_USER`` is defined then the + following additional macros must be defined: -- ``CONFIGURE_SCHEDULER_CONTEXT`` must be defined to a static definition of the - scheduler context of the user scheduler. + - ``CONFIGURE_SCHEDULER_CONTEXT`` must be defined to a static definition of + the scheduler context of the user scheduler. -- ``CONFIGURE_SCHEDULER_CONTROLS`` must be defined to a scheduler control - initializer for the user scheduler. + - ``CONFIGURE_SCHEDULER_CONTROLS`` must be defined to a scheduler control + initializer for the user scheduler. -- ``CONFIGURE_SCHEDULER_USER_PER_THREAD`` must be defined to the type of the - per-thread information of the user scheduler. + - ``CONFIGURE_SCHEDULER_USER_PER_THREAD`` must be defined to the type of + the per-thread information of the user scheduler. -**NOTES:** - -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. +NOTES: + 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. .. COMMENT: === Configuring Clustered Schedulers === @@ -4163,145 +3977,146 @@ the application designer has to answer two questions. #. Which scheduler is used for which cluster? -**CONFIGURATION:** - -The schedulers in an SMP system are statically configured on RTEMS. Firstly -the application must select which scheduling algorithms are available with the -following defines - -- ``CONFIGURE_SCHEDULER_PRIORITY_SMP``, - -- ``CONFIGURE_SCHEDULER_SIMPLE_SMP``, and - -- ``CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP``. - -This is necessary to calculate the per-thread overhead introduced by the -schedulers. After these definitions the configuration file must ``#include -<rtems/scheduler.h>`` to have access to scheduler specific configuration -macros. Each scheduler needs a context to store state information at run-time. -To provide a context for each scheduler is the next step. Use the following -macros to create scheduler contexts - -- ``RTEMS_SCHEDULER_CONTEXT_PRIORITY_SMP(name, prio_count)``, - -- ``RTEMS_SCHEDULER_CONTEXT_SIMPLE_SMP(name)``, and - -- ``RTEMS_SCHEDULER_CONTEXT_PRIORITY_AFFINITY_SMP(name, prio_count)``. - -The ``name`` parameter is used as part of a designator for a global variable, -so the usual C/C++ designator rules apply. Additional parameters are scheduler -specific. The schedulers are registered in the system via the scheduler table. -To create the scheduler table define ``CONFIGURE_SCHEDULER_CONTROLS`` to a list -of the following scheduler control initializers - -- ``RTEMS_SCHEDULER_CONTROL_PRIORITY_SMP(name, obj_name)``, - -- ``RTEMS_SCHEDULER_CONTROL_SIMPLE_SMP(name, obj_name)``, and - -- ``RTEMS_SCHEDULER_CONTROL_PRIORITY_AFFINITY_SMP(name, obj_name)``. - -The ``name`` parameter must correspond to the parameter defining the scheduler -context. The ``obj_name`` determines the scheduler object name and can be used -in ``rtems_scheduler_ident()`` to get the scheduler object identifier. - -The last step is to define which processor uses which scheduler. For this -purpose a scheduler assignment table must be defined. The entry count of this -table must be equal to the configured maximum processors -(``CONFIGURE_SMP_MAXIMUM_PROCESSORS``). A processor assignment to a scheduler -can be optional or mandatory. The boot processor must have a scheduler -assigned. In case the system needs more mandatory processors than available -then a fatal run-time error will occur. To specify the scheduler assignments -define ``CONFIGURE_SMP_SCHEDULER_ASSIGNMENTS`` to a list of -``RTEMS_SCHEDULER_ASSIGN(index, attr)`` and -``RTEMS_SCHEDULER_ASSIGN_NO_SCHEDULER`` macros. The ``index`` parameter must -be a valid index into the scheduler table. The ``attr`` parameter defines the -scheduler assignment attributes. By default a scheduler assignment to a -processor is optional. For the scheduler assignment attribute use one of the -mutually exclusive variants - -- ``RTEMS_SCHEDULER_ASSIGN_DEFAULT``, - -- ``RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY``, and - -- ``RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL``. - -**ERRORS:** - -In case one of the scheduler indices in``CONFIGURE_SMP_SCHEDULER_ASSIGNMENTS`` -is invalid a link-time error will occur with an undefined reference to -``RTEMS_SCHEDULER_INVALID_INDEX``. - -Some fatal errors may occur in case of scheduler configuration inconsistencies -or a lack of processors on the system. The fatal source is -``RTEMS_FATAL_SOURCE_SMP``. None of the errors is internal. - -- ``SMP_FATAL_BOOT_PROCESSOR_NOT_ASSIGNED_TO_SCHEDULER`` - the boot processor - must have a scheduler assigned. - -- ``SMP_FATAL_MANDATORY_PROCESSOR_NOT_PRESENT`` - there exists a mandatory - processor beyond the range of physically or virtually available processors. - The processor demand must be reduced for this system. - -- ``SMP_FATAL_START_OF_MANDATORY_PROCESSOR_FAILED`` - the start of a mandatory - processor failed during system initialization. The system may not have this - processor at all or it could be a problem with a boot loader for example. - Check the ``CONFIGURE_SMP_SCHEDULER_ASSIGNMENTS`` definition. - -- ``SMP_FATAL_MULTITASKING_START_ON_UNASSIGNED_PROCESSOR`` - it is not allowed - to start multitasking on a processor with no scheduler assigned. - -**EXAMPLE:** - -The following example shows a scheduler configuration for a hypothetical -product using two chip variants. One variant has four processors which is used -for the normal product line and another provides eight processors for the -high-performance product line. The first processor performs hard-real time -control of actuators and sensors. The second processor is not used by RTEMS at -all and runs a Linux instance to provide a graphical user interface. The -additional processors are used for a worker thread pool to perform data -processing operations. - -The processors managed by RTEMS use two Deterministic Priority scheduler -instances capable of dealing with 256 priority levels. The scheduler with -index zero has the name ``"IO "``. The scheduler with index one has the name -``"WORK"``. The scheduler assignments of the first, third and fourth processor -are mandatory, so the system must have at least four processors, otherwise a -fatal run-time error will occur during system startup. The processor -assignments for the fifth up to the eighth processor are optional so that the -same application can be used for the normal and high-performance product lines. -The second processor has no scheduler assigned and runs Linux. A hypervisor -will ensure that the two systems cannot interfere in an undesirable way. - -.. code-block:: c - - #define CONFIGURE_SMP_MAXIMUM_PROCESSORS 8 - #define CONFIGURE_MAXIMUM_PRIORITY 255 - /* Make the scheduler algorithm available */ - #define CONFIGURE_SCHEDULER_PRIORITY_SMP - #include <rtems/scheduler.h> - /* Create contexts for the two scheduler instances */ - RTEMS_SCHEDULER_CONTEXT_PRIORITY_SMP(io, CONFIGURE_MAXIMUM_PRIORITY + 1); - RTEMS_SCHEDULER_CONTEXT_PRIORITY_SMP(work, CONFIGURE_MAXIMUM_PRIORITY + 1); - /* Define the scheduler table */ - #define CONFIGURE_SCHEDULER_CONTROLS \\ - RTEMS_SCHEDULER_CONTROL_PRIORITY_SMP( \ - io, \ - rtems_build_name('I', 'O', ' ', ' ') \ - ), \ - RTEMS_SCHEDULER_CONTROL_PRIORITY_SMP( \ - work, \ - rtems_build_name('W', 'O', 'R', 'K') \ - ) - /* Define the processor to scheduler assignments */ - #define CONFIGURE_SMP_SCHEDULER_ASSIGNMENTS \ - RTEMS_SCHEDULER_ASSIGN(0, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \ - RTEMS_SCHEDULER_ASSIGN_NO_SCHEDULER, \ - RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \ - RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \ - RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL), \ - RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL), \ - RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL), \ - RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL) +CONFIGURATION: + The schedulers in an SMP system are statically configured on RTEMS. + Firstly the application must select which scheduling algorithms are + available with the following defines + + - ``CONFIGURE_SCHEDULER_PRIORITY_SMP``, + + - ``CONFIGURE_SCHEDULER_SIMPLE_SMP``, and + + - ``CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP``. + + This is necessary to calculate the per-thread overhead introduced by the + schedulers. After these definitions the configuration file must ``#include + <rtems/scheduler.h>`` to have access to scheduler specific configuration + macros. Each scheduler needs a context to store state information at + run-time. To provide a context for each scheduler is the next step. Use + the following macros to create scheduler contexts + + - ``RTEMS_SCHEDULER_CONTEXT_PRIORITY_SMP(name, prio_count)``, + + - ``RTEMS_SCHEDULER_CONTEXT_SIMPLE_SMP(name)``, and + + - ``RTEMS_SCHEDULER_CONTEXT_PRIORITY_AFFINITY_SMP(name, prio_count)``. + + The ``name`` parameter is used as part of a designator for a global + variable, so the usual C/C++ designator rules apply. Additional parameters + are scheduler specific. The schedulers are registered in the system via + the scheduler table. To create the scheduler table define + ``CONFIGURE_SCHEDULER_CONTROLS`` to a list of the following scheduler + control initializers + + - ``RTEMS_SCHEDULER_CONTROL_PRIORITY_SMP(name, obj_name)``, + + - ``RTEMS_SCHEDULER_CONTROL_SIMPLE_SMP(name, obj_name)``, and + + - ``RTEMS_SCHEDULER_CONTROL_PRIORITY_AFFINITY_SMP(name, obj_name)``. + + The ``name`` parameter must correspond to the parameter defining the + scheduler context. The ``obj_name`` determines the scheduler object name + and can be used in ``rtems_scheduler_ident()`` to get the scheduler object + identifier. + + The last step is to define which processor uses which scheduler. For this + purpose a scheduler assignment table must be defined. The entry count of + this table must be equal to the configured maximum processors + (``CONFIGURE_SMP_MAXIMUM_PROCESSORS``). A processor assignment to a + scheduler can be optional or mandatory. The boot processor must have a + scheduler assigned. In case the system needs more mandatory processors + than available then a fatal run-time error will occur. To specify the + scheduler assignments define ``CONFIGURE_SMP_SCHEDULER_ASSIGNMENTS`` to a + list of ``RTEMS_SCHEDULER_ASSIGN(index, attr)`` and + ``RTEMS_SCHEDULER_ASSIGN_NO_SCHEDULER`` macros. The ``index`` parameter + must be a valid index into the scheduler table. The ``attr`` parameter + defines the scheduler assignment attributes. By default a scheduler + assignment to a processor is optional. For the scheduler assignment + attribute use one of the mutually exclusive variants + + - ``RTEMS_SCHEDULER_ASSIGN_DEFAULT``, + + - ``RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY``, and + + - ``RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL``. + +ERRORS: + In case one of the scheduler indices + in``CONFIGURE_SMP_SCHEDULER_ASSIGNMENTS`` is invalid a link-time error will + occur with an undefined reference to ``RTEMS_SCHEDULER_INVALID_INDEX``. + + Some fatal errors may occur in case of scheduler configuration + inconsistencies or a lack of processors on the system. The fatal source is + ``RTEMS_FATAL_SOURCE_SMP``. None of the errors is internal. + + - ``SMP_FATAL_BOOT_PROCESSOR_NOT_ASSIGNED_TO_SCHEDULER`` - the boot + processor must have a scheduler assigned. + + - ``SMP_FATAL_MANDATORY_PROCESSOR_NOT_PRESENT`` - there exists a mandatory + processor beyond the range of physically or virtually available + processors. The processor demand must be reduced for this system. + + - ``SMP_FATAL_START_OF_MANDATORY_PROCESSOR_FAILED`` - the start of a + mandatory processor failed during system initialization. The system may + not have this processor at all or it could be a problem with a boot + loader for example. Check the ``CONFIGURE_SMP_SCHEDULER_ASSIGNMENTS`` + definition. + + - ``SMP_FATAL_MULTITASKING_START_ON_UNASSIGNED_PROCESSOR`` - it is not + allowed to start multitasking on a processor with no scheduler assigned. + +EXAMPLE: + The following example shows a scheduler configuration for a hypothetical + product using two chip variants. One variant has four processors which is + used for the normal product line and another provides eight processors for + the high-performance product line. The first processor performs hard-real + time control of actuators and sensors. The second processor is not used by + RTEMS at all and runs a Linux instance to provide a graphical user + interface. The additional processors are used for a worker thread pool to + perform data processing operations. + + The processors managed by RTEMS use two Deterministic Priority scheduler + instances capable of dealing with 256 priority levels. The scheduler with + index zero has the name ``"IO "``. The scheduler with index one has the + name ``"WORK"``. The scheduler assignments of the first, third and fourth + processor are mandatory, so the system must have at least four processors, + otherwise a fatal run-time error will occur during system startup. The + processor assignments for the fifth up to the eighth processor are optional + so that the same application can be used for the normal and + high-performance product lines. The second processor has no scheduler + assigned and runs Linux. A hypervisor will ensure that the two systems + cannot interfere in an undesirable way. + + .. code-block:: c + + #define CONFIGURE_SMP_MAXIMUM_PROCESSORS 8 + #define CONFIGURE_MAXIMUM_PRIORITY 255 + /* Make the scheduler algorithm available */ + #define CONFIGURE_SCHEDULER_PRIORITY_SMP + #include <rtems/scheduler.h> + /* Create contexts for the two scheduler instances */ + RTEMS_SCHEDULER_CONTEXT_PRIORITY_SMP(io, CONFIGURE_MAXIMUM_PRIORITY + 1); + RTEMS_SCHEDULER_CONTEXT_PRIORITY_SMP(work, CONFIGURE_MAXIMUM_PRIORITY + 1); + /* Define the scheduler table */ + #define CONFIGURE_SCHEDULER_CONTROLS \\ + RTEMS_SCHEDULER_CONTROL_PRIORITY_SMP( \ + io, \ + rtems_build_name('I', 'O', ' ', ' ') \ + ), \ + RTEMS_SCHEDULER_CONTROL_PRIORITY_SMP( \ + work, \ + rtems_build_name('W', 'O', 'R', 'K') \ + ) + /* Define the processor to scheduler assignments */ + #define CONFIGURE_SMP_SCHEDULER_ASSIGNMENTS \ + RTEMS_SCHEDULER_ASSIGN(0, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \ + RTEMS_SCHEDULER_ASSIGN_NO_SCHEDULER, \ + RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \ + RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \ + RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL), \ + RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL), \ + RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL), \ + RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL) .. COMMENT: === SMP Specific Configuration Parameters === @@ -4321,27 +4136,26 @@ Enable SMP Support for Applications ----------------------------------- .. index:: CONFIGURE_SMP_APPLICATION -*CONSTANT:* +CONSTANT: ``CONFIGURE_SMP_APPLICATION`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. -**DESCRIPTION:** - -``CONFIGURE_SMP_APPLICATION`` must be defined to enable SMP support for the -application. - -**NOTES:** +DESCRIPTION: + ``CONFIGURE_SMP_APPLICATION`` must be defined to enable SMP support for the + application. -This define may go away in the future in case all RTEMS components are SMP -ready. This configuration define is ignored on uni-processor configurations. +NOTES: + This define may go away in the future in case all RTEMS components are SMP + ready. This configuration define is ignored on uni-processor + configurations. .. COMMENT: === CONFIGURE_SMP_MAXIMUM_PROCESSORS === @@ -4351,27 +4165,26 @@ Specify Maximum Processors in SMP System ---------------------------------------- .. index:: CONFIGURE_SMP_MAXIMUM_PROCESSORS -*CONSTANT:* +CONSTANT: ``CONFIGURE_SMP_MAXIMUM_PROCESSORS`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``uint32_t``). -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is 1, (if CONFIGURE_SMP_APPLICATION is defined). -**DESCRIPTION:** +DESCRIPTION: + ``CONFIGURE_SMP_MAXIMUM_PROCESSORS`` must be set to the number of + processors in the SMP configuration. -``CONFIGURE_SMP_MAXIMUM_PROCESSORS`` must be set to the number of processors in -the SMP configuration. - -**NOTES:** - -If there are more processors available than configured, the rest will be -ignored. This configuration define is ignored on uni-processor configurations. +NOTES: + If there are more processors available than configured, the rest will be + ignored. This configuration define is ignored on uni-processor + configurations. .. COMMENT: === Device Driver Table === @@ -4393,32 +4206,31 @@ Specifying the Maximum Number of Device Drivers ----------------------------------------------- .. index:: CONFIGURE_MAXIMUM_DRIVERS -*CONSTANT:* +CONSTANT: + ``CONFIGURE_MAXIMUM_DRIVERS`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``uint32_t``). -*RANGE:* +RANGE: Zero or positive. -*DEFAULT VALUE:* +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 parameters. -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_DRIVERS`` is defined as the number of device drivers per -node. - -**NOTES:** +DESCRIPTION: + ``CONFIGURE_MAXIMUM_DRIVERS`` is defined as the number of device drivers + per node. -If the application will dynamically install device drivers, then this -configuration parameter must be larger than the number of statically configured -device drivers. Drivers configured using the -``CONFIGURE_APPLICATIONS_NEEDS_XXX_DRIVER`` configuration parameters are -statically installed. +NOTES: + If the application will dynamically install device drivers, then this + configuration parameter must be larger than the number of statically + configured device drivers. Drivers configured using the + ``CONFIGURE_APPLICATIONS_NEEDS_XXX_DRIVER`` configuration parameters are + statically installed. .. COMMENT: === CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER === @@ -4428,30 +4240,28 @@ Enable Console Device Driver ---------------------------- .. index:: CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER -*CONSTANT:* +CONSTANT: ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. -**DESCRIPTION:** +DESCRIPTION: + ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`` is defined if the + application wishes to include the Console Device Driver. -``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`` is defined if the application -wishes to include the Console Device Driver. +NOTES: + This device driver is responsible for providing standard input and output + using */dev/console*. -**NOTES:** - -This device driver is responsible for providing standard input and output using -*/dev/console*. - -BSPs should be constructed in a manner that allows ``printk()`` to work -properly without the need for the console driver to be configured. + BSPs should be constructed in a manner that allows ``printk()`` to work + properly without the need for the console driver to be configured. .. COMMENT: === CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER === @@ -4461,31 +4271,30 @@ Enable Clock Driver ------------------- .. index:: CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER -*CONSTANT:* +CONSTANT: ``CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. -**DESCRIPTION:** - -``CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER`` is defined if the application -wishes to include the Clock Device Driver. +DESCRIPTION: + ``CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER`` is defined if the application + wishes to include the Clock Device Driver. -**NOTES:** +NOTES: + This device driver is responsible for providing a regular interrupt which + invokes a clock tick directive. -This device driver is responsible for providing a regular interrupt which -invokes a clock tick directive. - -If neither the Clock Driver not Benchmark Timer is enabled and the -configuration parameter ``CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`` is -not defined, then a compile time error will occur. + If neither the Clock Driver not Benchmark Timer is enabled and the + configuration parameter + ``CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`` is not defined, then a + compile time error will occur. .. COMMENT: === CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER === @@ -4495,29 +4304,28 @@ Enable the Benchmark Timer Driver --------------------------------- .. index:: CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER -*CONSTANT:* +CONSTANT: ``CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. -**DESCRIPTION:** - -``CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER`` is defined if the -application wishes to include the Timer Driver. This device driver is -used to benchmark execution times by the RTEMS Timing Test Suites. +DESCRIPTION: + ``CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER`` is defined if the application + wishes to include the Timer Driver. This device driver is used to + benchmark execution times by the RTEMS Timing Test Suites. -**NOTES:** - -If neither the Clock Driver not Benchmark Timer is enabled and the -configuration parameter ``CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`` is -not defined, then a compile time error will occur. +NOTES: + If neither the Clock Driver not Benchmark Timer is enabled and the + configuration parameter + ``CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`` is not defined, then a + compile time error will occur. .. COMMENT: === CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER === @@ -4527,30 +4335,28 @@ Specify Clock and Benchmark Timer Drivers Are Not Needed -------------------------------------------------------- .. index:: CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER -*CONSTANT:* +CONSTANT: ``CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. -**DESCRIPTION:** - -``CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`` is defined when the -application does *NOT* want the Clock Device Driver and is *NOT* using the -Timer Driver. The inclusion or exclusion of the Clock Driver must be explicit -in user applications. - -**NOTES:** +DESCRIPTION: + ``CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`` is defined when the + application does *NOT* want the Clock Device Driver and is *NOT* using the + Timer Driver. The inclusion or exclusion of the Clock Driver must be + explicit in user applications. -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. +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. .. COMMENT: === CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER === @@ -4560,30 +4366,28 @@ Enable Real-Time Clock Driver ----------------------------- .. index:: CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER -*CONSTANT:* +CONSTANT: ``CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. -**DESCRIPTION:** - -``CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER`` is defined if the application wishes -to include the Real-Time Clock Driver. - -**NOTES:** +DESCRIPTION: + ``CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER`` is defined if the application + wishes to include the Real-Time Clock Driver. -Most BSPs do not include support for a real-time clock. This is because many -boards do not include the required hardware. +NOTES: + Most BSPs do not include support for a real-time clock. 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. .. COMMENT: === CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER === @@ -4593,30 +4397,28 @@ Enable the Watchdog Device Driver --------------------------------- .. index:: CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER -*CONSTANT:* +CONSTANT: ``CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. -**DESCRIPTION:** +DESCRIPTION: + ``CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER`` is defined if the + application wishes to include the Watchdog Driver. -``CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER`` is defined if the application -wishes to include the Watchdog Driver. +NOTES: + 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. .. COMMENT: === CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER === @@ -4626,30 +4428,28 @@ Enable the Graphics Frame Buffer Device Driver ---------------------------------------------- .. index:: CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER -*CONSTANT:* +CONSTANT: ``CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. -**DESCRIPTION:** - -``CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER`` is defined if the -application wishes to include the BSP's Frame Buffer Device Driver. - -**NOTES:** +DESCRIPTION: + ``CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER`` is defined if the + application wishes to include the BSP's Frame Buffer Device Driver. -Most BSPs do not include support for a Frame Buffer Device Driver. This is -because many boards do not include the required hardware. +NOTES: + Most BSPs do not include support for a Frame Buffer 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. .. COMMENT: === CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER === @@ -4659,27 +4459,25 @@ Enable Stub Device Driver ------------------------- .. index:: CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER -*CONSTANT:* +CONSTANT: ``CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. -**DESCRIPTION:** +DESCRIPTION: + ``CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER`` is defined if the application + wishes to include the Stub Device Driver. -``CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER`` is defined if the application -wishes to include the Stub Device Driver. - -**NOTES:** - -This device driver simply provides entry points that return successful and is -primarily a test fixture. It is supported by all BSPs. +NOTES: + This device driver simply provides entry points that return successful and + is primarily a test fixture. It is supported by all BSPs. .. COMMENT: === CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS === @@ -4689,33 +4487,31 @@ Specify Application Prerequisite Device Drivers ----------------------------------------------- .. index:: CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS -*CONSTANT:* +CONSTANT: ``CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS`` -*DATA TYPE:* +DATA TYPE: device driver entry structures -*RANGE:* +RANGE: Undefined or set of device driver entry structures -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. -**DESCRIPTION:** - -``CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS`` is defined if the application -has device drivers it needs to include in the Device Driver Table. This should -be defined to the set of device driver entries that will be placed in the table -at the *FRONT* of the Device Driver Table and initialized before any other -drivers *EXCEPT* any BSP prerequisite drivers. +DESCRIPTION: + ``CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS`` is defined if the + application has device drivers it needs to include in the Device Driver + Table. This should be defined to the set of device driver entries that + will be placed in the table at the *FRONT* of the Device Driver Table and + initialized before any other drivers *EXCEPT* any BSP prerequisite drivers. -**NOTES:** - -In some cases, it is used by System On Chip BSPs to support peripheral buses -beyond those normally found on the System On Chip. For example, this is used by -one RTEMS system which has implemented a SPARC/ERC32 based board with -VMEBus. The VMEBus Controller initialization is performed by a device driver -configured via this configuration parameter. +NOTES: + In some cases, it is used by System On Chip BSPs to support peripheral + buses beyond those normally found on the System On Chip. For example, this + is used by one RTEMS system which has implemented a SPARC/ERC32 based board + with VMEBus. The VMEBus Controller initialization is performed by a device + driver configured via this configuration parameter. .. COMMENT: XXX Add example @@ -4727,28 +4523,26 @@ Specify Extra Application Device Drivers ---------------------------------------- .. index:: CONFIGURE_APPLICATION_EXTRA_DRIVERS -*CONSTANT:* +CONSTANT: ``CONFIGURE_APPLICATION_EXTRA_DRIVERS`` -*DATA TYPE:* +DATA TYPE: device driver entry structures -*RANGE:* +RANGE: Undefined or set of device driver entry structures -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. -**DESCRIPTION:** - -``CONFIGURE_APPLICATION_EXTRA_DRIVERS`` is defined if the application has -device drivers it needs to include in the Device Driver Table. This should be -defined to the set of device driver entries that will be placed in the table at -the *END* of the Device Driver Table. +DESCRIPTION: + ``CONFIGURE_APPLICATION_EXTRA_DRIVERS`` is defined if the application has + device drivers it needs to include in the Device Driver Table. This should + be defined to the set of device driver entries that will be placed in the + table at the *END* of the Device Driver Table. -**NOTES:** - -None. +NOTES: + None. .. COMMENT: === CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER === @@ -4759,25 +4553,23 @@ Enable /dev/null Device Driver .. index:: CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER .. index:: /dev/null -*CONSTANT:* +CONSTANT: ``CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. -**DESCRIPTION:** - -This configuration variable is specified to enable ``/dev/null`` device driver. - -**NOTES:** +DESCRIPTION: + This configuration variable is specified to enable ``/dev/null`` device driver. -This device driver is supported by all BSPs. +NOTES: + This device driver is supported by all BSPs. .. COMMENT: === CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER === @@ -4788,25 +4580,23 @@ Enable /dev/zero Device Driver .. index:: CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER .. index:: /dev/zero -*CONSTANT:* +CONSTANT: ``CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. -**DESCRIPTION:** - -This configuration variable is specified to enable ``/dev/zero`` device driver. - -**NOTES:** +DESCRIPTION: + This configuration variable is specified to enable ``/dev/zero`` device driver. -This device driver is supported by all BSPs. +NOTES: + This device driver is supported by all BSPs. .. COMMENT: === CONFIGURE_HAS_OWN_DEVICE_DRIVER_TABLE === @@ -4816,32 +4606,30 @@ Specifying Application Defined Device Driver Table -------------------------------------------------- .. index:: CONFIGURE_HAS_OWN_DEVICE_DRIVER_TABLE -*CONSTANT:* +CONSTANT: ``CONFIGURE_HAS_OWN_DEVICE_DRIVER_TABLE`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default, indicating the ``<rtems/confdefs.h>`` is providing the device driver table. -**DESCRIPTION:** +DESCRIPTION: + ``CONFIGURE_HAS_OWN_DEVICE_DRIVER_TABLE`` is defined if the application + wishes to provide their own Device Driver Table. -``CONFIGURE_HAS_OWN_DEVICE_DRIVER_TABLE`` is defined if the application wishes -to provide their own Device Driver Table. + The table must be an array of ``rtems_driver_address_table`` entries + named`` _IO_Driver_address_table``. The application must also provide a + const variable ``_IO_Number_of_drivers`` of type ``size_t`` indicating the + number of entries in the ``_IO_Driver_address_table``. -The table must be an array of ``rtems_driver_address_table`` entries named`` -_IO_Driver_address_table``. The application must also provide a const variable -``_IO_Number_of_drivers`` of type ``size_t`` indicating the number of entries -in the ``_IO_Driver_address_table``. - -**NOTES:** - -It is expected that there the application would only rarely need to do this. +NOTES: + It is expected that there the application would only rarely need to do this. .. COMMENT: === Multiprocessing Configuration === @@ -4864,28 +4652,27 @@ Specify Application Will Use Multiprocessing -------------------------------------------- .. index:: CONFIGURE_MP_APPLICATION -*CONSTANT:* +CONSTANT: ``CONFIGURE_MP_APPLICATION`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. -**DESCRIPTION:** - -This configuration parameter must be defined to indicate that the application -intends to be part of a multiprocessing configuration. Additional configuration -parameters are assumed to be provided. +DESCRIPTION: + This configuration parameter must be defined to indicate that the + application intends to be part of a multiprocessing + configuration. Additional configuration parameters are assumed to be + provided. -**NOTES:** - -This has no impact unless RTEMS was configured and built using the -``--enable-multiprocessing`` option. +NOTES: + This has no impact unless RTEMS was configured and built using the + ``--enable-multiprocessing`` option. .. COMMENT: === CONFIGURE_MP_NODE_NUMBER === @@ -4895,30 +4682,28 @@ Configure Node Number in Multiprocessor Configuration ----------------------------------------------------- .. index:: CONFIGURE_MP_NODE_NUMBER -*CONSTANT:* +CONSTANT: ``CONFIGURE_MP_NODE_NUMBER`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``uint32_t``). -*RANGE:* +RANGE: Positive. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is ``NODE_NUMBER``, which is assumed to be set by the compilation environment. -**DESCRIPTION:** - -``CONFIGURE_MP_NODE_NUMBER`` is the node number of this node in a -multiprocessor system. +DESCRIPTION: + ``CONFIGURE_MP_NODE_NUMBER`` is the node number of this node in a + multiprocessor system. -**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. +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. .. COMMENT: === CONFIGURE_MP_MAXIMUM_NODES === @@ -4928,26 +4713,24 @@ Configure Maximum Node in Multiprocessor Configuration ------------------------------------------------------ .. index:: CONFIGURE_MP_MAXIMUM_NODES -*CONSTANT:* +CONSTANT: ``CONFIGURE_MP_MAXIMUM_NODES`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``uint32_t``). -*RANGE:* +RANGE: Positive. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is 2. -**DESCRIPTION:** - -``CONFIGURE_MP_MAXIMUM_NODES`` is the maximum number of nodes in a -multiprocessor system. +DESCRIPTION: + ``CONFIGURE_MP_MAXIMUM_NODES`` is the maximum number of nodes in a + multiprocessor system. -**NOTES:** - -None. +NOTES: + None. .. COMMENT: === CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS === @@ -4957,27 +4740,25 @@ Configure Maximum Global Objects in Multiprocessor Configuration ---------------------------------------------------------------- .. index:: CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS -*CONSTANT:* +CONSTANT: ``CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``uint32_t``). -*RANGE:* +RANGE: Positive. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is 32. -**DESCRIPTION:** - -``CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS`` is the maximum number of concurrently -active global objects in a multiprocessor system. +DESCRIPTION: + ``CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS`` is the maximum number of + concurrently active global objects in a multiprocessor system. -**NOTES:** - -This value corresponds to the total number of objects which can be created with -the ``RTEMS_GLOBAL`` attribute. +NOTES: + This value corresponds to the total number of objects which can be created + with the ``RTEMS_GLOBAL`` attribute. .. COMMENT: === CONFIGURE_MP_MAXIMUM_PROXIES === @@ -4987,28 +4768,26 @@ Configure Maximum Proxies in Multiprocessor Configuration --------------------------------------------------------- .. index:: CONFIGURE_MP_MAXIMUM_PROXIES -*CONSTANT:* +CONSTANT: ``CONFIGURE_MP_MAXIMUM_PROXIES`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``uint32_t``). -*RANGE:* +RANGE: Undefined or positive. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is 32. -**DESCRIPTION:** - -``CONFIGURE_MP_MAXIMUM_PROXIES`` is the maximum number of concurrently -active thread/task proxies on this node in a multiprocessor system. - -**NOTES:** +DESCRIPTION: + ``CONFIGURE_MP_MAXIMUM_PROXIES`` is the maximum number of concurrently + active thread/task proxies on this node in a multiprocessor system. -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. +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. .. COMMENT: XXX - add xref to proxy discussion in MP chapter @@ -5020,28 +4799,26 @@ Configure MPCI in Multiprocessor Configuration ---------------------------------------------- .. index:: CONFIGURE_MP_MPCI_TABLE_POINTER -*CONSTANT:* +CONSTANT: ``CONFIGURE_MP_MPCI_TABLE_POINTER`` -*DATA TYPE:* +DATA TYPE: pointer to ``rtems_mpci_table`` -*RANGE:* +RANGE: undefined or valid pointer -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. -**DESCRIPTION:** - -``CONFIGURE_MP_MPCI_TABLE_POINTER`` is the pointer to the MPCI Configuration -Table. The default value of this field is``&MPCI_table``. - -**NOTES:** +DESCRIPTION: + ``CONFIGURE_MP_MPCI_TABLE_POINTER`` is the pointer to the MPCI + Configuration Table. The default value of this field 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. +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. .. COMMENT: === CONFIGURE_HAS_OWN_MULTIPROCESSING_TABLE === @@ -5051,29 +4828,27 @@ Do Not Generate Multiprocessor Configuration Table -------------------------------------------------- .. index:: CONFIGURE_HAS_OWN_MULTIPROCESSING_TABLE -*CONSTANT:* +CONSTANT: ``CONFIGURE_HAS_OWN_MULTIPROCESSING_TABLE`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. -**DESCRIPTION:** +DESCRIPTION: + ``CONFIGURE_HAS_OWN_MULTIPROCESSING_TABLE`` is defined if the application + wishes to provide their own Multiprocessing Configuration Table. The + generated table is named ``Multiprocessing_configuration``. -``CONFIGURE_HAS_OWN_MULTIPROCESSING_TABLE`` is defined if the application -wishes to provide their own Multiprocessing Configuration Table. The generated -table is named ``Multiprocessing_configuration``. - -**NOTES:** - -This is a configuration parameter which is very unlikely to be used by an -application. If you find yourself wanting to use it in an application, please -reconsider and discuss this on the RTEMS Users mailing list. +NOTES: + This is a configuration parameter which is very unlikely to be used by an + application. If you find yourself wanting to use it in an application, + please reconsider and discuss this on the RTEMS Users mailing list. .. COMMENT: === Ada Tasks === @@ -5100,28 +4875,26 @@ Specify Application Includes Ada Code ------------------------------------- .. index:: CONFIGURE_GNAT_RTEMS -*CONSTANT:* +CONSTANT: ``CONFIGURE_GNAT_RTEMS`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. -**DESCRIPTION:** - -``CONFIGURE_GNAT_RTEMS`` is defined to inform RTEMS that the GNAT Ada run-time -is to be used by the application. +DESCRIPTION: + ``CONFIGURE_GNAT_RTEMS`` is defined to inform RTEMS that the GNAT Ada + run-time is to be used by the application. -**NOTES:** - -This configuration parameter is critical as it makes``<rtems/confdefs.h>`` -configure the resources (POSIX API Threads, Mutexes, Condition Variables, and -Keys) used implicitly by the GNAT run-time. +NOTES: + This configuration parameter is critical as it makes``<rtems/confdefs.h>`` + configure the resources (POSIX API Threads, Mutexes, Condition Variables, + and Keys) used implicitly by the GNAT run-time. .. COMMENT: === CONFIGURE_MAXIMUM_ADA_TASKS === @@ -5131,27 +4904,25 @@ Specify the Maximum Number of Ada Tasks. ---------------------------------------- .. index:: CONFIGURE_MAXIMUM_ADA_TASKS -*CONSTANT:* +CONSTANT: ``CONFIGURE_MAXIMUM_ADA_TASKS`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``uint32_t``). -*RANGE:* +RANGE: Undefined or positive. -*DEFAULT VALUE:* +DEFAULT VALUE: If ``CONFIGURE_GNAT_RTEMS`` is defined, then the default value is 20, otherwise the default value is 0. -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_ADA_TASKS`` is the number of Ada tasks that can be -concurrently active in the system. +DESCRIPTION: + ``CONFIGURE_MAXIMUM_ADA_TASKS`` is the number of Ada tasks that can be + concurrently active in the system. -**NOTES:** - -None. +NOTES: + None. .. COMMENT: === CONFIGURE_MAXIMUM_FAKE_ADA_TASKS === @@ -5161,27 +4932,26 @@ Specify the Maximum Fake Ada Tasks ---------------------------------- .. index:: CONFIGURE_MAXIMUM_FAKE_ADA_TASKS -*CONSTANT:* +CONSTANT: .. index:: ``CONFIGURE_MAXIMUM_FAKE_ADA_TASKS`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``uint32_t``). -*RANGE:* +RANGE: Zero or positive. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is 0. -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_FAKE_ADA_TASKS`` is the number of *fake* Ada tasks that can -be concurrently active in the system. A *fake* Ada task is a non-Ada task that -makes calls back into Ada code and thus implicitly uses the Ada run-time. - -**NOTES:** +DESCRIPTION: + ``CONFIGURE_MAXIMUM_FAKE_ADA_TASKS`` is the number of *fake* Ada tasks that + can be concurrently active in the system. A *fake* Ada task is a non-Ada + task that makes calls back into Ada code and thus implicitly uses the Ada + run-time. -None. +NOTES: + None. .. COMMENT: === PCI Library === @@ -5250,26 +5020,24 @@ Specify Application Includes Go Code ------------------------------------ .. index:: CONFIGURE_ENABLE_GO -*CONSTANT:* +CONSTANT: ``CONFIGURE_ENABLE_GO`` -*DATA TYPE:* +DATA TYPE: Boolean feature macro. -*RANGE:* +RANGE: Defined or undefined. -*DEFAULT VALUE:* +DEFAULT VALUE: This is not defined by default. -**DESCRIPTION:** - -``CONFIGURE_ENABLE_GO`` is defined to inform RTEMS that the Go run-time is to -be used by the application. - -**NOTES:** +DESCRIPTION: + ``CONFIGURE_ENABLE_GO`` is defined to inform RTEMS that the Go run-time is + to be used by the application. -The Go language support is experimental +NOTES: + The Go language support is experimental .. COMMENT: === CONFIGURE_MAXIMUM_GOROUTINES === @@ -5279,26 +5047,24 @@ Specify the maximum number of Go routines ----------------------------------------- .. index:: CONFIGURE_MAXIMUM_GOROUTINES -*CONSTANT:* +CONSTANT: ``CONFIGURE_MAXIMUM_GOROUTINES`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``uint32_t``). -*RANGE:* +RANGE: Zero or positive. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is 400 -**DESCRIPTION:** +DESCRIPTION: + ``CONFIGURE_MAXIMUM_GOROUTINES`` is defined to specify the maximum number + of Go routines. -``CONFIGURE_MAXIMUM_GOROUTINES`` is defined to specify the maximum number of Go -routines. - -**NOTES:** - -The Go language support is experimental +NOTES: + The Go language support is experimental .. COMMENT: === CONFIGURE_MAXIMUM_GO_CHANNELS === @@ -5308,26 +5074,24 @@ Specify the maximum number of Go Channels ----------------------------------------- .. index:: CONFIGURE_MAXIMUM_GO_CHANNELS -*CONSTANT:* +CONSTANT: ``CONFIGURE_MAXIMUM_GO_CHANNELS`` -*DATA TYPE:* +DATA TYPE: Unsigned integer (``uint32_t``). -*RANGE:* +RANGE: Zero or positive. -*DEFAULT VALUE:* +DEFAULT VALUE: The default value is 500 -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_GO_CHANNELS`` is defined to specify the maximum number of -Go channels. - -**NOTES:** +DESCRIPTION: + ``CONFIGURE_MAXIMUM_GO_CHANNELS`` is defined to specify the maximum number + of Go channels. -The Go language support is experimental +NOTES: + The Go language support is experimental .. COMMENT: === Configuration Data Structures === diff --git a/c-user/constant_bandwidth_server.rst b/c-user/constant_bandwidth_server.rst index 135dfdb..7f45e26 100644 --- a/c-user/constant_bandwidth_server.rst +++ b/c-user/constant_bandwidth_server.rst @@ -229,458 +229,450 @@ This section details the Constant Bandwidth Server'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_cbs_initialize: CBS_INITIALIZE - Initialize the CBS library ------------------------------------------- .. index:: initialize the CBS library - -**CALLING SEQUENCE:** - .. index:: rtems_cbs_initialize -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - int rtems_cbs_initialize( void ); + int rtems_cbs_initialize( void ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. list-table:: - :class: rtems-table + * - ``RTEMS_CBS_OK`` + - successful initialization + * - ``RTEMS_CBS_ERROR_NO_MEMORY`` + - not enough memory for data - * - ``RTEMS_CBS_OK`` - - successful initialization - * - ``RTEMS_CBS_ERROR_NO_MEMORY`` - - not enough memory for data +DESCRIPTION: + This routine initializes the library in terms of allocating necessary + memory for the servers. In case not enough memory is available in the + system, ``RTEMS_CBS_ERROR_NO_MEMORY`` is returned, otherwise + ``RTEMS_CBS_OK``. -**DESCRIPTION:** +NOTES: + Additional memory per each server is allocated upon invocation of + ``rtems_cbs_create_server``. -This routine initializes the library in terms of allocating necessary memory -for the servers. In case not enough memory is available in the system, -``RTEMS_CBS_ERROR_NO_MEMORY`` is returned, otherwise ``RTEMS_CBS_OK``. + Tasks in the system are not influenced, they still keep executing with + their initial parameters. -**NOTES:** +.. raw:: latex -Additional memory per each server is allocated upon invocation of -``rtems_cbs_create_server``. - -Tasks in the system are not influenced, they still keep executing with their -initial parameters. + \clearpage .. _rtems_cbs_cleanup: CBS_CLEANUP - Cleanup the CBS library ------------------------------------- .. index:: cleanup the CBS library - -**CALLING SEQUENCE:** - .. index:: rtems_cbs_cleanup -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - int rtems_cbs_cleanup( void ); + int rtems_cbs_cleanup( void ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. list-table:: - :class: rtems-table + * - ``RTEMS_CBS_OK`` + - always successful - * - ``RTEMS_CBS_OK`` - - always successful +DESCRIPTION: + This routine detaches all tasks from their servers, destroys all servers + and returns memory back to the system. -**DESCRIPTION:** +NOTES: + All tasks continue executing with their initial priorities. -This routine detaches all tasks from their servers, destroys all servers and -returns memory back to the system. +.. raw:: latex -**NOTES:** - -All tasks continue executing with their initial priorities. + \clearpage .. _rtems_cbs_create_server: CBS_CREATE_SERVER - Create a new bandwidth server ------------------------------------------------- .. index:: create a new bandwidth server - -**CALLING SEQUENCE:** - .. index:: rtems_cbs_create_server -.. code-block:: c - - int rtems_cbs_create_server ( - rtems_cbs_parameters *params, - rtems_cbs_budget_overrun budget_overrun_callback, - rtems_cbs_server_id *server_id - ); - -**DIRECTIVE STATUS CODES:** - -.. list-table:: - :class: rtems-table - - * - ``RTEMS_CBS_OK`` - - successfully created - * - ``RTEMS_CBS_ERROR_NO_MEMORY`` - - not enough memory for data - * - ``RTEMS_CBS_ERROR_FULL`` - - maximum servers exceeded - * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER`` - - invalid input argument - -**DESCRIPTION:** - -This routine prepares an instance of a constant bandwidth server. The input -parameter ``rtems_cbs_parameters`` specifies scheduling parameters of the -server (period and budget). If these are not valid, -``RTEMS_CBS_ERROR_INVALID_PARAMETER`` is returned. The -``budget_overrun_callback`` is an optional callback function, which is invoked -in case the server's budget within one period is exceeded. Output parameter -``server_id`` becomes an id of the newly created server. If there is not -enough memory, the ``RTEMS_CBS_ERROR_NO_MEMORY`` is returned. If the maximum -server count in the system is exceeded, ``RTEMS_CBS_ERROR_FULL`` is returned. - -**NOTES:** - -No task execution is being influenced so far. +CALLING SEQUENCE: + .. code-block:: c + + int rtems_cbs_create_server ( + rtems_cbs_parameters *params, + rtems_cbs_budget_overrun budget_overrun_callback, + rtems_cbs_server_id *server_id + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_CBS_OK`` + - successfully created + * - ``RTEMS_CBS_ERROR_NO_MEMORY`` + - not enough memory for data + * - ``RTEMS_CBS_ERROR_FULL`` + - maximum servers exceeded + * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER`` + - invalid input argument + +DESCRIPTION: + This routine prepares an instance of a constant bandwidth server. The + input parameter ``rtems_cbs_parameters`` specifies scheduling parameters of + the server (period and budget). If these are not valid, + ``RTEMS_CBS_ERROR_INVALID_PARAMETER`` is returned. The + ``budget_overrun_callback`` is an optional callback function, which is + invoked in case the server's budget within one period is exceeded. Output + parameter ``server_id`` becomes an id of the newly created server. If + there is not enough memory, the ``RTEMS_CBS_ERROR_NO_MEMORY`` is + returned. If the maximum server count in the system is exceeded, + ``RTEMS_CBS_ERROR_FULL`` is returned. + +NOTES: + No task execution is being influenced so far. + +.. raw:: latex + + \clearpage .. _rtems_cbs_attach_thread: CBS_ATTACH_THREAD - Attach a thread to server --------------------------------------------- .. index:: attach a thread to server - -**CALLING SEQUENCE:** - .. index:: rtems_cbs_attach_thread -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - int rtems_cbs_attach_thread ( - rtems_cbs_server_id server_id, - rtems_id task_id - ); + int rtems_cbs_attach_thread ( + rtems_cbs_server_id server_id, + rtems_id task_id + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. list-table:: - :class: rtems-table + * - ``RTEMS_CBS_OK`` + - successfully attached + * - ``RTEMS_CBS_ERROR_FULL`` + - server maximum tasks exceeded + * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER`` + - invalid input argument + * - ``RTEMS_CBS_ERROR_NOSERVER`` + - server is not valid - * - ``RTEMS_CBS_OK`` - - successfully attached - * - ``RTEMS_CBS_ERROR_FULL`` - - server maximum tasks exceeded - * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER`` - - invalid input argument - * - ``RTEMS_CBS_ERROR_NOSERVER`` - - server is not valid +DESCRIPTION: + Attaches a task (``task_id``) to a server (``server_id``). The server has + to be previously created. Now, the task starts to be scheduled according to + the server parameters and not using initial priority. This implementation + allows only one task per server, if the user tries to bind another task to + the same server, ``RTEMS_CBS_ERROR_FULL`` is returned. -**DESCRIPTION:** +NOTES: + Tasks attached to servers become preemptible. -Attaches a task (``task_id``) to a server (``server_id``). The server has to -be previously created. Now, the task starts to be scheduled according to the -server parameters and not using initial priority. This implementation allows -only one task per server, if the user tries to bind another task to the same -server, ``RTEMS_CBS_ERROR_FULL`` is returned. +.. raw:: latex -**NOTES:** - -Tasks attached to servers become preemptible. + \clearpage .. _rtems_cbs_detach_thread: CBS_DETACH_THREAD - Detach a thread from server ----------------------------------------------- .. index:: detach a thread from server - -**CALLING SEQUENCE:** - .. index:: rtems_cbs_detach_thread -.. code-block:: c - - int rtems_cbs_detach_thread ( - rtems_cbs_server_id server_id, - rtems_id task_id - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + int rtems_cbs_detach_thread ( + rtems_cbs_server_id server_id, + rtems_id task_id + ); -.. list-table:: - :class: rtems-table +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table - * - ``RTEMS_CBS_OK`` - - successfully detached - * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER`` - - invalid input argument - * - ``RTEMS_CBS_ERROR_NOSERVER`` - - server is not valid + * - ``RTEMS_CBS_OK`` + - successfully detached + * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER`` + - invalid input argument + * - ``RTEMS_CBS_ERROR_NOSERVER`` + - server is not valid -**DESCRIPTION:** +DESCRIPTION: + This directive detaches a thread from server. The task continues its + execution with initial priority. -This directive detaches a thread from server. The task continues its execution -with initial priority. +NOTES: + The server can be reused for any other task. -**NOTES:** +.. raw:: latex -The server can be reused for any other task. + \clearpage .. _rtems_cbs_destroy_server: CBS_DESTROY_SERVER - Destroy a bandwidth server ----------------------------------------------- .. index:: destroy a bandwidth server - -**CALLING SEQUENCE:** - .. index:: rtems_cbs_destroy_server -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - int rtems_cbs_destroy_server ( - rtems_cbs_server_id server_id - ); + int rtems_cbs_destroy_server ( + rtems_cbs_server_id server_id + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. list-table:: - :class: rtems-table + * - ``RTEMS_CBS_OK`` + - successfully destroyed + * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER`` + - invalid input argument + * - ``RTEMS_CBS_ERROR_NOSERVER`` + - server is not valid - * - ``RTEMS_CBS_OK`` - - successfully destroyed - * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER`` - - invalid input argument - * - ``RTEMS_CBS_ERROR_NOSERVER`` - - server is not valid +DESCRIPTION: + This directive destroys a server. If any task was attached to the server, + the task is detached and continues its execution according to EDF rules + with initial properties. -**DESCRIPTION:** +NOTES: + This again enables one more task to be created. -This directive destroys a server. If any task was attached to the server, the -task is detached and continues its execution according to EDF rules with -initial properties. +.. raw:: latex -**NOTES:** - -This again enables one more task to be created. + \clearpage .. _rtems_cbs_get_server_id: CBS_GET_SERVER_ID - Get an ID of a server ----------------------------------------- .. index:: get an ID of a server - -**CALLING SEQUENCE:** - .. index:: rtems_cbs_get_server_id -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - int rtems_cbs_get_server_id ( - rtems_id task_id, - rtems_cbs_server_id *server_id - ); + int rtems_cbs_get_server_id ( + rtems_id task_id, + rtems_cbs_server_id *server_id + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. list-table:: - :class: rtems-table + * - ``RTEMS_CBS_OK`` + - successful + * - ``RTEMS_CBS_ERROR_NOSERVER`` + - server is not valid - * - ``RTEMS_CBS_OK`` - - successful - * - ``RTEMS_CBS_ERROR_NOSERVER`` - - server is not valid +DESCRIPTION: + This directive returns an id of server belonging to a given task. -**DESCRIPTION:** +.. raw:: latex -This directive returns an id of server belonging to a given task. + \clearpage .. _rtems_cbs_get_parameters: CBS_GET_PARAMETERS - Get scheduling parameters of a server ---------------------------------------------------------- .. index:: get scheduling parameters of a server - -**CALLING SEQUENCE:** - .. index:: rtems_cbs_get_parameters -.. code-block:: c - - rtems_cbs_get_parameters ( - rtems_cbs_server_id server_id, - rtems_cbs_parameters *params - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_cbs_get_parameters ( + rtems_cbs_server_id server_id, + rtems_cbs_parameters *params + ); -.. list-table:: - :class: rtems-table +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table - * - ``RTEMS_CBS_OK`` - - successful - * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER`` - - invalid input argument - * - ``RTEMS_CBS_ERROR_NOSERVER`` - - server is not valid + * - ``RTEMS_CBS_OK`` + - successful + * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER`` + - invalid input argument + * - ``RTEMS_CBS_ERROR_NOSERVER`` + - server is not valid -**DESCRIPTION:** +DESCRIPTION: + This directive returns a structure with current scheduling parameters of a + given server (period and execution time). -This directive returns a structure with current scheduling parameters -of a given server (period and execution time). +NOTES: + It makes no difference if any task is assigned or not. -**NOTES:** +.. raw:: latex -It makes no difference if any task is assigned or not. + \clearpage .. _rtems_cbs_set_parameters: CBS_SET_PARAMETERS - Set scheduling parameters ---------------------------------------------- .. index:: set scheduling parameters - -**CALLING SEQUENCE:** - .. index:: rtems_cbs_set_parameters -.. code-block:: c - - int rtems_cbs_set_parameters ( - rtems_cbs_server_id server_id, - rtems_cbs_parameters *params - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + int rtems_cbs_set_parameters ( + rtems_cbs_server_id server_id, + rtems_cbs_parameters *params + ); -.. list-table:: - :class: rtems-table +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table - * - ``RTEMS_CBS_OK`` - - successful - * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER`` - - invalid input argument - * - ``RTEMS_CBS_ERROR_NOSERVER`` - - server is not valid + * - ``RTEMS_CBS_OK`` + - successful + * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER`` + - invalid input argument + * - ``RTEMS_CBS_ERROR_NOSERVER`` + - server is not valid -**DESCRIPTION:** +DESCRIPTION: + This directive sets new scheduling parameters to the server. This operation + can be performed regardless of whether a task is assigned or not. If a + task is assigned, the parameters become effective imediately, therefore it + is recommended to apply the change between two subsequent periods. -This directive sets new scheduling parameters to the server. This operation can -be performed regardless of whether a task is assigned or not. If a task is -assigned, the parameters become effective imediately, therefore it is -recommended to apply the change between two subsequent periods. +NOTES: + There is an upper limit on both period and budget equal to (2^31)-1 ticks. -**NOTES:** +.. raw:: latex -There is an upper limit on both period and budget equal to (2^31)-1 ticks. + \clearpage .. _rtems_cbs_get_execution_time: CBS_GET_EXECUTION_TIME - Get elapsed execution time --------------------------------------------------- .. index:: get elapsed execution time - -**CALLING SEQUENCE:** - .. index:: rtems_cbs_get_execution_time -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - int rtems_cbs_get_execution_time ( - rtems_cbs_server_id server_id, - time_t *exec_time, - time_t *abs_time - ); + int rtems_cbs_get_execution_time ( + rtems_cbs_server_id server_id, + time_t *exec_time, + time_t *abs_time + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. list-table:: - :class: rtems-table + * - ``RTEMS_CBS_OK`` + - successful + * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER`` + - invalid input argument + * - ``RTEMS_CBS_ERROR_NOSERVER`` + - server is not valid - * - ``RTEMS_CBS_OK`` - - successful - * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER`` - - invalid input argument - * - ``RTEMS_CBS_ERROR_NOSERVER`` - - server is not valid +DESCRIPTION: + This routine returns consumed execution time (``exec_time``) of a server + during the current period. -**DESCRIPTION:** +NOTES: + Absolute time (``abs_time``) not supported now. -This routine returns consumed execution time (``exec_time``) of a server during -the current period. +.. raw:: latex -**NOTES:** - -Absolute time (``abs_time``) not supported now. + \clearpage .. _rtems_cbs_get_remaining_budget: CBS_GET_REMAINING_BUDGET - Get remaining execution time ------------------------------------------------------- .. index:: get remaining execution time - -**CALLING SEQUENCE:** - .. index:: rtems_cbs_get_remaining_budget -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - int rtems_cbs_get_remaining_budget ( - rtems_cbs_server_id server_id, - time_t *remaining_budget - ); - -**DIRECTIVE STATUS CODES:** + int rtems_cbs_get_remaining_budget ( + rtems_cbs_server_id server_id, + time_t *remaining_budget + ); -.. list-table:: - :class: rtems-table +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table - * - ``RTEMS_CBS_OK`` - - successful - * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER`` - - invalid input argument - * - ``RTEMS_CBS_ERROR_NOSERVER`` - - server is not valid + * - ``RTEMS_CBS_OK`` + - successful + * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER`` + - invalid input argument + * - ``RTEMS_CBS_ERROR_NOSERVER`` + - server is not valid -**DESCRIPTION:** +DESCRIPTION: + This directive returns remaining execution time of a given server for + current period. -This directive returns remaining execution time of a given server for current -period. +NOTES: + If the execution time approaches zero, the assigned task should finish + computations of the current period. -**NOTES:** +.. raw:: latex -If the execution time approaches zero, the assigned task should finish -computations of the current period. + \clearpage .. _rtems_cbs_get_approved_budget: CBS_GET_APPROVED_BUDGET - Get scheduler approved execution time --------------------------------------------------------------- .. index:: get scheduler approved execution time - -**CALLING SEQUENCE:** - .. index:: rtems_cbs_get_approved_budget -.. code-block:: c - - int rtems_cbs_get_approved_budget ( - rtems_cbs_server_id server_id, - time_t *appr_budget - ); - -**DIRECTIVE STATUS CODES:** +CALLING SEQUENCE: + .. code-block:: c -.. list-table:: - :class: rtems-table + int rtems_cbs_get_approved_budget ( + rtems_cbs_server_id server_id, + time_t *appr_budget + ); - * - ``RTEMS_CBS_OK`` - - successful - * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER`` - - invalid input argument - * - ``RTEMS_CBS_ERROR_NOSERVER`` - - server is not valid +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -**DESCRIPTION:** + * - ``RTEMS_CBS_OK`` + - successful + * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER`` + - invalid input argument + * - ``RTEMS_CBS_ERROR_NOSERVER`` + - server is not valid -This directive returns server's approved budget for subsequent periods. +DESCRIPTION: + This directive returns server's approved budget for subsequent periods. diff --git a/c-user/cpu_usage_statistics.rst b/c-user/cpu_usage_statistics.rst index 2fbe754..4705ca9 100644 --- a/c-user/cpu_usage_statistics.rst +++ b/c-user/cpu_usage_statistics.rst @@ -104,52 +104,52 @@ This section details the CPU usage statistics 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_cpu_usage_report: cpu_usage_report - Report CPU Usage Statistics ---------------------------------------------- -**CALLING SEQUENCE:** - -.. code-block:: c - - void rtems_cpu_usage_report( void ); +CALLING SEQUENCE: + .. code-block:: c -**STATUS CODES:** + void rtems_cpu_usage_report( void ); -NONE +STATUS CODES: + NONE -**DESCRIPTION:** +DESCRIPTION: + This routine prints out a table detailing the CPU usage statistics for all + tasks in the system. -This routine prints out a table detailing the CPU usage statistics for all -tasks in the system. +NOTES: + The table is printed using the ``printk`` routine. -**NOTES:** +.. raw:: latex -The table is printed using the ``printk`` routine. + \clearpage .. _rtems_cpu_usage_reset: cpu_usage_reset - Reset CPU Usage Statistics -------------------------------------------- -**CALLING SEQUENCE:** - -.. code-block:: c - - void rtems_cpu_usage_reset( void ); - -**STATUS CODES:** - -NONE +CALLING SEQUENCE: + .. code-block:: c -**DESCRIPTION:** + void rtems_cpu_usage_reset( void ); -This routine re-initializes the CPU usage statistics for all tasks in the -system to their initial state. The initial state is that a task has not -executed and thus has consumed no CPU time. default state which is when zero -period executions have occurred. +STATUS CODES: + NONE -**NOTES:** +DESCRIPTION: + This routine re-initializes the CPU usage statistics for all tasks in the + system to their initial state. The initial state is that a task has not + executed and thus has consumed no CPU time. default state which is when + zero period executions have occurred. -NONE +NOTES: + NONE diff --git a/c-user/directive_status_codes.rst b/c-user/directive_status_codes.rst index b4c7f3b..5106a81 100644 --- a/c-user/directive_status_codes.rst +++ b/c-user/directive_status_codes.rst @@ -76,25 +76,25 @@ The directives are: * - ``RTEMS_NO_MEMORY`` - could not get enough memory +.. raw:: latex + + \clearpage + .. _rtems_status_text: STATUS_TEXT - Returns the enumeration name for a status code ------------------------------------------------------------ - -**CALLING SEQUENCE:** - .. index:: rtems_status_text -.. code-block:: c - - const char *rtems_status_text( - rtems_status_code code - ); - -**DIRECTIVE STATUS CODES** +CALLING SEQUENCE: + .. code-block:: c -The status code enumeration name or "?" in case the status code is invalid. + const char *rtems_status_text( + rtems_status_code code + ); -**DESCRIPTION:** +DIRECTIVE STATUS CODES + The status code enumeration name or "?" in case the status code is invalid. -Returns the enumeration name for the specified status code. +DESCRIPTION: + Returns the enumeration name for the specified status code. diff --git a/c-user/dual_ports_memory_manager.rst b/c-user/dual_ports_memory_manager.rst index 0502e42..7af67c6 100644 --- a/c-user/dual_ports_memory_manager.rst +++ b/c-user/dual_ports_memory_manager.rst @@ -94,59 +94,62 @@ 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 + .. _rtems_port_create: PORT_CREATE - Create a port --------------------------- .. index:: create a port - -**CALLING SEQUENCE:** - .. index:: rtems_port_create -.. code-block:: c - - rtems_status_code rtems_port_create( - rtems_name name, - void *internal_start, - void *external_start, - uint32_t length, - rtems_id *id - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_status_code rtems_port_create( + rtems_name name, + void *internal_start, + void *external_start, + uint32_t length, + rtems_id *id + ); -.. list-table:: - :class: rtems-table +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 + * - ``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:** +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. -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. -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. -**NOTES:** + This directive will not cause the calling task to be preempted. -The internal_address and external_address parameters must be on a four byte -boundary. +.. raw:: latex -This directive will not cause the calling task to be preempted. + \clearpage .. _rtems_port_ident: @@ -154,158 +157,151 @@ PORT_IDENT - Get ID of a port ----------------------------- .. index:: get ID of a port .. index:: obtain ID of a port - -**CALLING SEQUENCE:** - .. index:: rtems_port_ident -.. code-block:: c - - rtems_status_code rtems_port_ident( - rtems_name name, - rtems_id *id - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_status_code rtems_port_ident( + rtems_name name, + rtems_id *id + ); -.. list-table:: - :class: rtems-table +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 + * - ``RTEMS_SUCCESSFUL`` + - port identified successfully + * - ``RTEMS_INVALID_ADDRESS`` + - ``id`` is NULL + * - ``RTEMS_INVALID_NAME`` + - port name not found -**DESCRIPTION:** +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. -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. -**NOTES:** +.. raw:: latex -This directive will not cause the running task to be preempted. + \clearpage .. _rtems_port_delete: PORT_DELETE - Delete a port --------------------------- .. index:: delete a port - -**CALLING SEQUENCE:** - .. index:: rtems_port_delete -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_port_delete( - rtems_id id - ); + rtems_status_code rtems_port_delete( + rtems_id id + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. list-table:: - :class: rtems-table + * - ``RTEMS_SUCCESSFUL`` + - port deleted successfully + * - ``RTEMS_INVALID_ID`` + - invalid port id - * - ``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. -**DESCRIPTION:** +NOTES: + This directive will not cause the calling task to be preempted. -This directive deletes the dual-ported memory area specified by id. The DPCB -for the deleted dual-ported memory area is reclaimed by RTEMS. + 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. -**NOTES:** +.. raw:: latex -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. + \clearpage .. _rtems_port_external_to_internal: PORT_EXTERNAL_TO_INTERNAL - Convert external to internal address ---------------------------------------------------------------- .. index:: convert external to internal address - -**CALLING SEQUENCE:** - .. index:: rtems_port_external_to_internal -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_port_external_to_internal( - rtems_id id, - void *external, - void **internal - ); + rtems_status_code rtems_port_external_to_internal( + rtems_id id, + void *external, + void **internal + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. list-table:: - :class: rtems-table + * - ``RTEMS_INVALID_ADDRESS`` + - ``internal`` is NULL + * - ``RTEMS_SUCCESSFUL`` + - successful conversion - * - ``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. -**DESCRIPTION:** +NOTES: + This directive is callable from an ISR. -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. + This directive will not cause the calling task to be preempted. -**NOTES:** +.. raw:: latex -This directive is callable from an ISR. - -This directive will not cause the calling task to be preempted. + \clearpage .. _rtems_port_internal_to_external: PORT_INTERNAL_TO_EXTERNAL - Convert internal to external address ---------------------------------------------------------------- .. index:: convert internal to external address - -**CALLING SEQUENCE:** - .. index:: rtems_port_internal_to_external -.. 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 +CALLING SEQUENCE: + .. code-block:: c - * - ``RTEMS_INVALID_ADDRESS`` - - ``external`` is NULL - * - ``RTEMS_SUCCESSFUL`` - - successful conversion + rtems_status_code rtems_port_internal_to_external( + rtems_id id, + void *internal, + void **external + ); -**DESCRIPTION:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -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. + * - ``RTEMS_INVALID_ADDRESS`` + - ``external`` is NULL + * - ``RTEMS_SUCCESSFUL`` + - successful conversion -**NOTES:** +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. -This directive is callable from an ISR. +NOTES: + This directive is callable from an ISR. -This directive will not cause the calling task to be preempted. + This directive will not cause the calling task to be preempted. diff --git a/c-user/event_manager.rst b/c-user/event_manager.rst index 724d138..4b12a9a 100644 --- a/c-user/event_manager.rst +++ b/c-user/event_manager.rst @@ -176,132 +176,132 @@ 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 + .. _rtems_event_send: EVENT_SEND - Send event set to a task ------------------------------------- .. index:: send event set to a task - -**CALLING SEQUENCE:** - .. index:: rtems_event_send -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_event_send ( - rtems_id id, - rtems_event_set event_in - ); + rtems_status_code rtems_event_send ( + rtems_id id, + rtems_event_set event_in + ); -**DIRECTIVE STATUS CODES:** - -.. list-table:: - :class: rtems-table +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table - * - ``RTEMS_SUCCESSFUL`` - - event set sent successfully - * - ``RTEMS_INVALID_ID`` - - invalid task id + * - ``RTEMS_SUCCESSFUL`` + - event set sent successfully + * - ``RTEMS_INVALID_ID`` + - invalid task id -**DESCRIPTION:** +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. -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. -**NOTES:** + 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. -Specifying ``RTEMS_SELF`` for id results in the event set being sent to the -calling task. + The calling task will be preempted if it has preemption enabled and a + higher priority task is unblocked as the result of this directive. -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. + 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. -The calling task will be preempted if it has preemption enabled and a higher -priority task is unblocked as the result of this directive. +.. raw:: latex -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. + \clearpage .. _rtems_event_receive: EVENT_RECEIVE - Receive event condition --------------------------------------- .. index:: receive event condition - -**CALLING SEQUENCE:** - .. index:: rtems_event_receive -.. 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. +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.rst index 6ffd43b..5d7456f 100644 --- a/c-user/fatal_error.rst +++ b/c-user/fatal_error.rst @@ -111,45 +111,48 @@ 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 + .. _rtems_fatal_error_occurred: FATAL_ERROR_OCCURRED - Invoke the fatal error handler ----------------------------------------------------- .. index:: announce fatal error .. index:: fatal error, announce - -**CALLING SEQUENCE:** - .. index:: rtems_fatal_error_occurred -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - void rtems_fatal_error_occurred( - uint32_t the_error - ); + void rtems_fatal_error_occurred( + uint32_t the_error + ); -**DIRECTIVE STATUS CODES** +DIRECTIVE STATUS CODES: + NONE -NONE +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. -**DESCRIPTION:** +NOTES: + This directive supports local operations only. -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. + Unless the user-defined error extension takes special actions such as + restarting the calling task, this directive WILL NOT RETURN to the caller. -**NOTES:** + The user-defined extension for this directive may wish to initiate a global + shutdown. -This directive supports local operations only. +.. raw:: latex -Unless the user-defined error extension takes special actions such as -restarting the calling task, this directive WILL NOT RETURN to the caller. - -The user-defined extension for this directive may wish to initiate a global -shutdown. + \clearpage .. _rtems_fatal: @@ -157,97 +160,93 @@ FATAL - Invoke the fatal error handler with error source -------------------------------------------------------- .. index:: announce fatal error .. index:: fatal error, announce - -**CALLING SEQUENCE:** - .. index:: rtems_fatal -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - void rtems_fatal( - rtems_fatal_source source, - rtems_fatal_code error - ); + void rtems_fatal( + rtems_fatal_source source, + rtems_fatal_code error + ); -**DIRECTIVE STATUS CODES** +DIRECTIVE STATUS CODES: + NONE -NONE +DESCRIPTION: + This directive invokes the internal error handler with is internal set to + false. See also ``rtems_fatal_error_occurred``. -**DESCRIPTION:** +.. raw:: latex -This directive invokes the internal error handler with is internal set to -false. See also ``rtems_fatal_error_occurred``. + \clearpage .. _rtems_exception_frame_print: EXCEPTION_FRAME_PRINT - Prints the exception frame -------------------------------------------------- .. index:: exception frame - -**CALLING SEQUENCE:** - .. index:: rtems_exception_frame_print -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - void rtems_exception_frame_print( - const rtems_exception_frame *frame - ); + void rtems_exception_frame_print( + const rtems_exception_frame *frame + ); -**DIRECTIVE STATUS CODES** +DIRECTIVE STATUS CODES: + NONE -NONE +DESCRIPTION: + Prints the exception frame via ``printk()``. -**DESCRIPTION:** +.. raw:: latex -Prints the exception frame via ``printk()``. + \clearpage .. _rtems_fatal_source_text: FATAL_SOURCE_TEXT - Returns a text for a fatal source ----------------------------------------------------- .. index:: fatal error - -**CALLING SEQUENCE:** - .. index:: rtems_fatal_source_text -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - const char *rtems_fatal_source_text( - rtems_fatal_source source - ); + const char *rtems_fatal_source_text( + rtems_fatal_source source + ); -**DIRECTIVE STATUS CODES** +DIRECTIVE STATUS CODES: + The fatal source text or "?" in case the passed fatal source is invalid. -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. -**DESCRIPTION:** +.. raw:: latex -Returns a text for a fatal source. The text for fatal source is the enumerator -constant. + \clearpage .. _rtems_internal_error_text: INTERNAL_ERROR_TEXT - Returns a text for an internal error code --------------------------------------------------------------- .. index:: fatal error - -**CALLING SEQUENCE:** - .. index:: rtems_internal_error_text -.. code-block:: c - - const char *rtems_internal_error_text( - rtems_fatal_code error - ); - -**DIRECTIVE STATUS CODES** +CALLING SEQUENCE: + .. code-block:: c -The error code text or "?" in case the passed error code is invalid. + const char *rtems_internal_error_text( + rtems_fatal_code error + ); -**DESCRIPTION:** +DIRECTIVE STATUS CODES: + The error code text or "?" in case the passed error code is invalid. -Returns a text for an internal error code. The text for each internal error -code is the enumerator constant. +DESCRIPTION: + Returns a text for an internal error code. The text for each internal + error code is the enumerator constant. diff --git a/c-user/index.rst b/c-user/index.rst index 3333551..e97ffbf 100644 --- a/c-user/index.rst +++ b/c-user/index.rst @@ -35,7 +35,7 @@ to the Community Project hosted at http://www.rtems.org/. ================ ============================= .. toctree:: - :maxdepth: 3 + :maxdepth: 5 :numbered: preface diff --git a/c-user/initialization.rst b/c-user/initialization.rst index 9df30f0..d808110 100644 --- a/c-user/initialization.rst +++ b/c-user/initialization.rst @@ -139,15 +139,15 @@ A list of all initialization steps follows. Some steps are optional depending on the requested feature set of the application. The initialization steps are execute in the order presented here. -`RTEMS_SYSINIT_BSP_WORK_AREAS` +``RTEMS_SYSINIT_BSP_WORK_AREAS`` The work areas consisting of C Program Heap and the RTEMS Workspace are initialized by the Board Support Package. This step is mandatory. -`RTEMS_SYSINIT_BSP_START` +``RTEMS_SYSINIT_BSP_START`` Basic initialization step provided by the Board Support Package. This step is mandatory. -`RTEMS_SYSINIT_DATA_STRUCTURES` +``RTEMS_SYSINIT_DATA_STRUCTURES`` This directive is called when the Board Support Package has completed its basic initialization and allows RTEMS to initialize the application environment based upon the information in the Configuration Table, User @@ -155,28 +155,28 @@ execute in the order presented here. Multiprocessor Configuration Table, and the Multiprocessor Communications Interface (MPCI) Table. -`RTEMS_SYSINIT_BSP_LIBC` +``RTEMS_SYSINIT_BSP_LIBC`` Depending on the application configuration the IO library and root filesystem is initialized. This step is mandatory. -`RTEMS_SYSINIT_BEFORE_DRIVERS` +``RTEMS_SYSINIT_BEFORE_DRIVERS`` This directive performs initialization that must occur between basis RTEMS data structure initialization and device driver initialization. In particular, in a multiprocessor configuration, this directive will create the MPCI Server Task. -`RTEMS_SYSINIT_BSP_PRE_DRIVERS` +``RTEMS_SYSINIT_BSP_PRE_DRIVERS`` Initialization step performed right before device drivers are initialized provided by the Board Support Package. This step is mandatory. -`RTEMS_SYSINIT_DEVICE_DRIVERS` +``RTEMS_SYSINIT_DEVICE_DRIVERS`` This step initializes all statically configured device drivers and performs all RTEMS initialization which requires device drivers to be initialized. This step is mandatory. In a multiprocessor configuration, this service will initialize the Multiprocessor Communications Interface (MPCI) and synchronize with the other nodes in the system. -`RTEMS_SYSINIT_BSP_POST_DRIVERS` +``RTEMS_SYSINIT_BSP_POST_DRIVERS`` Initialization step performed right after device drivers are initialized provided by the Board Support Package. This step is mandatory. @@ -207,6 +207,10 @@ 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 + .. _rtems_initialize_executive: INITIALIZE_EXECUTIVE - Initialize RTEMS @@ -214,29 +218,28 @@ INITIALIZE_EXECUTIVE - Initialize RTEMS .. index:: initialize RTEMS .. index:: start multitasking -**CALLING SEQUENCE:** - .. index:: rtems_initialize_executive +CALLING SEQUENCE: + .. code-block:: c -.. code-block:: c - - void rtems_initialize_executive(void); - -**DIRECTIVE STATUS CODES:** + void rtems_initialize_executive(void); -NONE +DIRECTIVE STATUS CODES: + NONE -**DESCRIPTION:** +DESCRIPTION: + Iterates through the system initialization linker set and invokes the + registered handlers. The final step is to start multitasking. -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 ``boot_card`` only. -**NOTES:** + This directive *does not return* to the caller. Errors in the + initialization sequence are usually fatal and lead to a system termination. -This directive should be called by ``boot_card`` only. +.. raw:: latex -This directive *does not return* to the caller. Errors in the initialization -sequence are usually fatal and lead to a system termination. + \clearpage .. _rtems_shutdown_executive: @@ -244,29 +247,24 @@ SHUTDOWN_EXECUTIVE - Shutdown RTEMS ----------------------------------- .. index:: shutdown RTEMS -**CALLING SEQUENCE:** - .. index:: rtems_shutdown_executive +CALLING SEQUENCE: + .. code-block:: c -.. code-block:: c - - void rtems_shutdown_executive( - uint32_t result - ); - -**DIRECTIVE STATUS CODES:** - -NONE - -**DESCRIPTION:** + void rtems_shutdown_executive( + uint32_t result + ); -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. +DIRECTIVE STATUS CODES: + NONE -**NOTES:** +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. -This directive *must* be the last RTEMS directive invoked by an application and -it *does not return* to the caller. +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. + This directive may be called any time. diff --git a/c-user/interrupt_manager.rst b/c-user/interrupt_manager.rst index 0ee6a39..8cd1332 100644 --- a/c-user/interrupt_manager.rst +++ b/c-user/interrupt_manager.rst @@ -260,406 +260,397 @@ 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 + .. _rtems_interrupt_catch: INTERRUPT_CATCH - Establish an ISR ---------------------------------- .. index:: establish an ISR .. index:: install an ISR - -**CALLING SEQUENCE:** - .. index:: rtems_interrupt_catch -.. code-block:: c +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:** + rtems_status_code rtems_interrupt_catch( + rtems_isr_entry new_isr_handler, + rtems_vector_number vector, + rtems_isr_entry *old_isr_handler + ); -.. list-table:: - :class: rtems-wrap +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`` + * - ``RTEMS_SUCCESSFUL`` + - ISR established successfully + * - ``RTEMS_INVALID_NUMBER`` + - illegal vector number + * - ``RTEMS_INVALID_ADDRESS`` + - illegal ISR entry point or invalid ``old_isr_handler`` -**DESCRIPTION:** +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``. -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. -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. -**NOTES:** +.. raw:: latex -This directive will not cause the calling task to be preempted. + \clearpage .. _rtems_interrupt_disable: INTERRUPT_DISABLE - Disable Interrupts -------------------------------------- .. index:: disable interrupts - -**CALLING SEQUENCE:** - .. index:: rtems_interrupt_disable -.. code-block:: c - - void rtems_interrupt_disable( - rtems_interrupt_level level - ); - -**DIRECTIVE STATUS CODES:** +CALLING SEQUENCE: + .. code-block:: c -NONE + void rtems_interrupt_disable( + rtems_interrupt_level level + ); -**DESCRIPTION:** +DIRECTIVE STATUS CODES: + NONE .. sidebar:: *Macro* This directive is implemented as a macro which modifies the ``level`` parameter. -This directive disables all maskable interrupts and returns the previous -``level``. A later invocation of the ``rtems_interrupt_enable`` directive -should be used to restore the interrupt level. +DESCRIPTION: + This directive disables all maskable interrupts and returns the previous + ``level``. A later invocation of the ``rtems_interrupt_enable`` directive + should be used to restore the interrupt level. -**NOTES:** +NOTES: + This directive will not cause the calling task to be preempted. -This directive will not cause the calling task to be preempted. + This directive is only available on uni-processor configurations. The + directive ``rtems_interrupt_local_disable`` is available on all + configurations. -This directive is only available on uni-processor configurations. The -directive ``rtems_interrupt_local_disable`` is available on all configurations. +.. raw:: latex + + \clearpage .. _rtems_interrupt_enable: INTERRUPT_ENABLE - Enable Interrupts ------------------------------------ .. index:: enable interrupts - -**CALLING SEQUENCE:** - .. index:: rtems_interrupt_enable -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - void rtems_interrupt_enable( - rtems_interrupt_level level - ); - -**DIRECTIVE STATUS CODES:** + void rtems_interrupt_enable( + rtems_interrupt_level level + ); -NONE +DIRECTIVE STATUS CODES: + NONE -**DESCRIPTION:** +DESCRIPTION: + This directive enables maskable interrupts to the ``level`` which was + returned by a previous call to ``rtems_interrupt_disable``. Immediately + prior to invoking this directive, maskable interrupts should be disabled by + a call to ``rtems_interrupt_disable`` and will be enabled when this + directive returns to the caller. -This directive enables maskable interrupts to the ``level`` which was returned -by a previous call to ``rtems_interrupt_disable``. Immediately prior to -invoking this directive, maskable interrupts should be disabled by a call to -``rtems_interrupt_disable`` and will be enabled when this directive returns to -the caller. +NOTES: + This directive will not cause the calling task to be preempted. -**NOTES:** + This directive is only available on uni-processor configurations. The + directive ``rtems_interrupt_local_enable`` is available on all + configurations. -This directive will not cause the calling task to be preempted. +.. raw:: latex -This directive is only available on uni-processor configurations. The -directive ``rtems_interrupt_local_enable`` is available on all configurations. + \clearpage .. _rtems_interrupt_flash: INTERRUPT_FLASH - Flash Interrupts ---------------------------------- .. index:: flash interrupts - -**CALLING SEQUENCE:** - .. index:: rtems_interrupt_flash -.. code-block:: c - - void rtems_interrupt_flash( - rtems_interrupt_level level - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + void rtems_interrupt_flash( + rtems_interrupt_level level + ); -NONE +DIRECTIVE STATUS CODES: + NONE -**DESCRIPTION:** +DESCRIPTION: + This directive temporarily enables maskable interrupts to the ``level`` + which was returned by a previous call to ``rtems_interrupt_disable``. + Immediately prior to invoking this directive, maskable interrupts should be + disabled by a call to ``rtems_interrupt_disable`` and will be redisabled + when this directive returns to the caller. -This directive temporarily enables maskable interrupts to the ``level`` which -was returned by a previous call to ``rtems_interrupt_disable``. Immediately -prior to invoking this directive, maskable interrupts should be disabled by a -call to ``rtems_interrupt_disable`` and will be redisabled when this directive -returns to the caller. +NOTES: + This directive will not cause the calling task to be preempted. -**NOTES:** + This directive is only available on uni-processor configurations. The + directives ``rtems_interrupt_local_disable`` and + ``rtems_interrupt_local_enable`` is available on all configurations. -This directive will not cause the calling task to be preempted. +.. raw:: latex -This directive is only available on uni-processor configurations. The -directives ``rtems_interrupt_local_disable`` and -``rtems_interrupt_local_enable`` is available on all configurations. + \clearpage .. _rtems_interrupt_local_disable: INTERRUPT_LOCAL_DISABLE - Disable Interrupts on Current Processor ----------------------------------------------------------------- .. index:: disable interrupts - -**CALLING SEQUENCE:** - .. index:: rtems_interrupt_local_disable -.. code-block:: c - - void rtems_interrupt_local_disable( - rtems_interrupt_level level - ); - -**DIRECTIVE STATUS CODES:** +CALLING SEQUENCE: + .. code-block:: c -NONE + void rtems_interrupt_local_disable( + rtems_interrupt_level level + ); -**DESCRIPTION:** +DIRECTIVE STATUS CODES: + NONE .. sidebar:: *Macro* This directive is implemented as a macro which modifies the ``level`` parameter. -This directive disables all maskable interrupts and returns the previous -``level``. A later invocation of the ``rtems_interrupt_local_enable`` directive -should be used to restore the interrupt level. +DESCRIPTION: + This directive disables all maskable interrupts and returns the previous + ``level``. A later invocation of the ``rtems_interrupt_local_enable`` + directive should be used to restore the interrupt level. + +NOTES: + This directive will not cause the calling task to be preempted. -**NOTES:** + On SMP configurations this will not ensure system wide mutual exclusion. + Use interrupt locks instead. -This directive will not cause the calling task to be preempted. +.. raw:: latex -On SMP configurations this will not ensure system wide mutual exclusion. Use -interrupt locks instead. + \clearpage .. _rtems_interrupt_local_enable: INTERRUPT_LOCAL_ENABLE - Enable Interrupts on Current Processor --------------------------------------------------------------- .. index:: enable interrupts - -**CALLING SEQUENCE:** - .. index:: rtems_interrupt_local_enable -.. code-block:: c - - void rtems_interrupt_local_enable( - rtems_interrupt_level level - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + void rtems_interrupt_local_enable( + rtems_interrupt_level level + ); -NONE +DIRECTIVE STATUS CODES: + NONE -**DESCRIPTION:** +DESCRIPTION: + This directive enables maskable interrupts to the ``level`` which was + returned by a previous call to ``rtems_interrupt_local_disable``. + Immediately prior to invoking this directive, maskable interrupts should be + disabled by a call to ``rtems_interrupt_local_disable`` and will be enabled + when this directive returns to the caller. -This directive enables maskable interrupts to the ``level`` which was returned -by a previous call to ``rtems_interrupt_local_disable``. Immediately prior to -invoking this directive, maskable interrupts should be disabled by a call to -``rtems_interrupt_local_disable`` and will be enabled when this directive -returns to the caller. +NOTES: + This directive will not cause the calling task to be preempted. -**NOTES:** +.. raw:: latex -This directive will not cause the calling task to be preempted. + \clearpage .. _rtems_interrupt_lock_initialize: INTERRUPT_LOCK_INITIALIZE - Initialize an ISR Lock -------------------------------------------------- - -**CALLING SEQUENCE:** - .. index:: rtems_interrupt_lock_initialize -.. code-block:: c - - void rtems_interrupt_lock_initialize( - rtems_interrupt_lock *lock - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + void rtems_interrupt_lock_initialize( + rtems_interrupt_lock *lock + ); -NONE +DIRECTIVE STATUS CODES: + NONE -**DESCRIPTION:** +DESCRIPTION: + Initializes an interrupt lock. -Initializes an interrupt lock. +NOTES: + Concurrent initialization leads to unpredictable results. -**NOTES:** +.. raw:: latex -Concurrent initialization leads to unpredictable results. + \clearpage .. _rtems_interrupt_lock_acquire: INTERRUPT_LOCK_ACQUIRE - Acquire an ISR Lock -------------------------------------------- - -**CALLING SEQUENCE:** - .. index:: rtems_interrupt_lock_acquire -.. code-block:: c - - void rtems_interrupt_lock_acquire( - rtems_interrupt_lock *lock, - rtems_interrupt_level level - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + void rtems_interrupt_lock_acquire( + rtems_interrupt_lock *lock, + rtems_interrupt_level level + ); -NONE +DIRECTIVE STATUS CODES: + NONE -**DESCRIPTION:** +DESCRIPTION: + Interrupts will be disabled. On SMP configurations this directive acquires + a SMP lock. -Interrupts will be disabled. On SMP configurations this directive acquires a -SMP lock. +NOTES: + This directive will not cause the calling thread to be preempted. This + directive can be used in thread and interrupt context. -**NOTES:** +.. raw:: latex -This directive will not cause the calling thread to be preempted. This -directive can be used in thread and interrupt context. + \clearpage .. _rtems_interrupt_lock_release: INTERRUPT_LOCK_RELEASE - Release an ISR Lock -------------------------------------------- - -**CALLING SEQUENCE:** - .. index:: rtems_interrupt_lock_release -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - void rtems_interrupt_lock_release( - rtems_interrupt_lock *lock, - rtems_interrupt_level level - ); + void rtems_interrupt_lock_release( + rtems_interrupt_lock *lock, + rtems_interrupt_level level + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + NONE -NONE +DESCRIPTION: + The interrupt status will be restored. On SMP configurations this + directive releases a SMP lock. -**DESCRIPTION:** +NOTES: + This directive will not cause the calling thread to be preempted. This + directive can be used in thread and interrupt context. -The interrupt status will be restored. On SMP configurations this directive -releases a SMP lock. +.. raw:: latex -**NOTES:** - -This directive will not cause the calling thread to be preempted. This -directive can be used in thread and interrupt context. + \clearpage .. _rtems_interrupt_lock_acquire_isr: INTERRUPT_LOCK_ACQUIRE_ISR - Acquire an ISR Lock from ISR --------------------------------------------------------- - -**CALLING SEQUENCE:** - .. index:: rtems_interrupt_lock_acquire_isr -.. code-block:: c - - void rtems_interrupt_lock_acquire_isr( - rtems_interrupt_lock *lock, - rtems_interrupt_level level - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + void rtems_interrupt_lock_acquire_isr( + rtems_interrupt_lock *lock, + rtems_interrupt_level level + ); -NONE +DIRECTIVE STATUS CODES: + NONE -**DESCRIPTION:** +DESCRIPTION: + The interrupt status will remain unchanged. On SMP configurations this + directive acquires a SMP lock. -The interrupt status will remain unchanged. On SMP configurations this -directive acquires a SMP lock. + 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. -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. +NOTES: + This directive should be called from the corresponding interrupt service + routine. -**NOTES:** +.. raw:: latex -This directive should be called from the corresponding interrupt service -routine. + \clearpage .. _rtems_interrupt_lock_release_isr: INTERRUPT_LOCK_RELEASE_ISR - Release an ISR Lock from ISR --------------------------------------------------------- - -**CALLING SEQUENCE:** - .. index:: rtems_interrupt_lock_release_isr -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - void rtems_interrupt_lock_release_isr( - rtems_interrupt_lock *lock, - rtems_interrupt_level level - ); + void rtems_interrupt_lock_release_isr( + rtems_interrupt_lock *lock, + rtems_interrupt_level level + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + NONE -NONE +DESCRIPTION: -**DESCRIPTION:** + The interrupt status will remain unchanged. On SMP configurations this + directive releases a SMP lock. -The interrupt status will remain unchanged. On SMP configurations this -directive releases a SMP lock. +NOTES: + This directive should be called from the corresponding interrupt service + routine. -**NOTES:** +.. raw:: latex -This directive should be called from the corresponding interrupt service -routine. + \clearpage .. _rtems_interrupt_is_in_progress: INTERRUPT_IS_IN_PROGRESS - Is an ISR in Progress ------------------------------------------------ .. index:: is interrupt in progress - -**CALLING SEQUENCE:** - .. index:: rtems_interrupt_is_in_progress -.. code-block:: c - - bool rtems_interrupt_is_in_progress(void); - -**DIRECTIVE STATUS CODES:** - -NONE +CALLING SEQUENCE: + .. code-block:: c -**DESCRIPTION:** + bool rtems_interrupt_is_in_progress(void); -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. +DIRECTIVE STATUS CODES: + NONE -**NOTES:** +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. -This directive will not cause the calling task to be preempted. +NOTES: + This directive will not cause the calling task to be preempted. diff --git a/c-user/io_manager.rst b/c-user/io_manager.rst index 50340c9..74ca5b1 100644 --- a/c-user/io_manager.rst +++ b/c-user/io_manager.rst @@ -221,371 +221,367 @@ 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 + .. _rtems_io_register_driver: IO_REGISTER_DRIVER - Register a device driver --------------------------------------------- .. index:: register a device driver - -**CALLING SEQUENCE:** - .. index:: rtems_io_register_driver -.. 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. +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 .. _rtems_io_unregister_driver: IO_UNREGISTER_DRIVER - Unregister a device driver ------------------------------------------------- .. index:: unregister a device driver - -**CALLING SEQUENCE:** - .. index:: rtems_io_unregister_driver -.. code-block:: c - - rtems_status_code rtems_io_unregister_driver( - rtems_device_major_number major - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_status_code rtems_io_unregister_driver( + rtems_device_major_number major + ); -.. list-table:: - :class: rtems-table +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table - * - ``RTEMS_SUCCESSFUL`` - - successfully registered - * - ``RTEMS_INVALID_NUMBER`` - - invalid major device number + * - ``RTEMS_SUCCESSFUL`` + - successfully registered + * - ``RTEMS_INVALID_NUMBER`` + - invalid major device number -**DESCRIPTION:** +DESCRIPTION: + This directive removes a device driver from the Device Driver Table. -This directive removes a device driver from the Device Driver Table. +NOTES: + Currently no specific checks are made and the driver is not closed. -**NOTES:** +.. raw:: latex -Currently no specific checks are made and the driver is not closed. + \clearpage .. _rtems_io_initialize: IO_INITIALIZE - Initialize a device driver ------------------------------------------ .. index:: initialize a device driver - -**CALLING SEQUENCE:** - .. index:: rtems_io_initialize -.. code-block:: c - - rtems_status_code rtems_io_initialize( - rtems_device_major_number major, - rtems_device_minor_number minor, - void *argument - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_status_code rtems_io_initialize( + rtems_device_major_number major, + rtems_device_minor_number minor, + void *argument + ); -.. list-table:: - :class: rtems-table +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table - * - ``RTEMS_SUCCESSFUL`` - - successfully initialized - * - ``RTEMS_INVALID_NUMBER`` - - invalid major device number + * - ``RTEMS_SUCCESSFUL`` + - successfully initialized + * - ``RTEMS_INVALID_NUMBER`` + - invalid major device number -**DESCRIPTION:** +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. -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. -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. -**NOTES:** +.. raw:: latex -This directive may or may not cause the calling task to be preempted. This is -dependent on the device driver being initialized. + \clearpage .. _rtems_io_register_name: IO_REGISTER_NAME - Register a device ------------------------------------ .. index:: register device - -**CALLING SEQUENCE:** - .. index:: rtems_io_register_name -.. code-block:: c - - rtems_status_code rtems_io_register_name( - const char *name, - rtems_device_major_number major, - rtems_device_minor_number minor - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_status_code rtems_io_register_name( + const char *name, + rtems_device_major_number major, + rtems_device_minor_number minor + ); -.. list-table:: - :class: rtems-table +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table - * - ``RTEMS_SUCCESSFUL`` - - successfully initialized - * - ``RTEMS_TOO_MANY`` - - too many devices registered + * - ``RTEMS_SUCCESSFUL`` + - successfully initialized + * - ``RTEMS_TOO_MANY`` + - too many devices registered -**DESCRIPTION:** +DESCRIPTION: + This directive associates name with the specified major/minor number pair. -This directive associates name with the specified major/minor number pair. +NOTES: + This directive will not cause the calling task to be preempted. -**NOTES:** +.. raw:: latex -This directive will not cause the calling task to be preempted. + \clearpage .. _rtems_io_lookup_name: IO_LOOKUP_NAME - Lookup a device -------------------------------- .. index:: lookup device major and minor number - -**CALLING SEQUENCE:** - .. index:: rtems_io_lookup_name -.. code-block:: c - - rtems_status_code rtems_io_lookup_name( - const char *name, - rtems_driver_name_t *device_info - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_status_code rtems_io_lookup_name( + const char *name, + rtems_driver_name_t *device_info + ); -.. list-table:: - :class: rtems-table +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table - * - ``RTEMS_SUCCESSFUL`` - - successfully initialized - * - ``RTEMS_UNSATISFIED`` - - name not registered + * - ``RTEMS_SUCCESSFUL`` + - successfully initialized + * - ``RTEMS_UNSATISFIED`` + - name not registered -**DESCRIPTION:** +DESCRIPTION: + This directive returns the major/minor number pair associated with the + given device name in ``device_info``. -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. -**NOTES:** +.. raw:: latex -This directive will not cause the calling task to be preempted. + \clearpage .. _rtems_io_open: IO_OPEN - Open a device ----------------------- .. index:: open a devive - -**CALLING SEQUENCE:** - .. index:: rtems_io_open -.. code-block:: c - - rtems_status_code rtems_io_open( - rtems_device_major_number major, - rtems_device_minor_number minor, - void *argument - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_status_code rtems_io_open( + rtems_device_major_number major, + rtems_device_minor_number minor, + void *argument + ); -.. list-table:: - :class: rtems-table +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table - * - ``RTEMS_SUCCESSFUL`` - - successfully initialized - * - ``RTEMS_INVALID_NUMBER`` - - invalid major device number + * - ``RTEMS_SUCCESSFUL`` + - successfully initialized + * - ``RTEMS_INVALID_NUMBER`` + - invalid major device number -**DESCRIPTION:** +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. -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. -**NOTES:** +.. raw:: latex -This directive may or may not cause the calling task to be preempted. This is -dependent on the device driver being invoked. + \clearpage .. _rtems_io_close: IO_CLOSE - Close a device ------------------------- .. index:: close a device - -**CALLING SEQUENCE:** - .. index:: rtems_io_close -.. code-block:: c - - rtems_status_code rtems_io_close( - rtems_device_major_number major, - rtems_device_minor_number minor, - void *argument - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_status_code rtems_io_close( + rtems_device_major_number major, + rtems_device_minor_number minor, + void *argument + ); -.. list-table:: - :class: rtems-table +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table - * - ``RTEMS_SUCCESSFUL`` - - successfully initialized - * - ``RTEMS_INVALID_NUMBER`` - - invalid major device number + * - ``RTEMS_SUCCESSFUL`` + - successfully initialized + * - ``RTEMS_INVALID_NUMBER`` + - invalid major device number -**DESCRIPTION:** +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. -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. -**NOTES:** +.. raw:: latex -This directive may or may not cause the calling task to be preempted. This is -dependent on the device driver being invoked. + \clearpage .. _rtems_io_read: IO_READ - Read from a device ---------------------------- .. index:: read from a device - -**CALLING SEQUENCE:** - .. index:: rtems_io_read -.. code-block:: c - - rtems_status_code rtems_io_read( - rtems_device_major_number major, - rtems_device_minor_number minor, - void *argument - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_status_code rtems_io_read( + rtems_device_major_number major, + rtems_device_minor_number minor, + void *argument + ); -.. list-table:: - :class: rtems-table +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table - * - ``RTEMS_SUCCESSFUL`` - - successfully initialized - * - ``RTEMS_INVALID_NUMBER`` - - invalid major device number + * - ``RTEMS_SUCCESSFUL`` + - successfully initialized + * - ``RTEMS_INVALID_NUMBER`` + - invalid major device number -**DESCRIPTION:** +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. -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. -**NOTES:** +.. raw:: latex -This directive may or may not cause the calling task to be preempted. This is -dependent on the device driver being invoked. + \clearpage .. _rtems_io_write: IO_WRITE - Write to a device ---------------------------- .. index:: write to a device - -**CALLING SEQUENCE:** - .. index:: rtems_io_write -.. code-block:: c - - rtems_status_code rtems_io_write( - rtems_device_major_number major, - rtems_device_minor_number minor, - void *argument - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_status_code rtems_io_write( + rtems_device_major_number major, + rtems_device_minor_number minor, + void *argument + ); -.. list-table:: - :class: rtems-table +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table - * - ``RTEMS_SUCCESSFUL`` - - successfully initialized - * - ``RTEMS_INVALID_NUMBER`` - - invalid major device number + * - ``RTEMS_SUCCESSFUL`` + - successfully initialized + * - ``RTEMS_INVALID_NUMBER`` + - invalid major device number -**DESCRIPTION:** +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. -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. -**NOTES:** +.. raw:: latex -This directive may or may not cause the calling task to be preempted. This is -dependent on the device driver being invoked. + \clearpage .. _rtems_io_control: @@ -593,40 +589,35 @@ IO_CONTROL - Special device services ------------------------------------ .. index:: special device services .. index:: IO Control - -**CALLING SEQUENCE:** - .. index:: rtems_io_control -.. 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. +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/linker_sets.rst b/c-user/linker_sets.rst index ad45fea..37f863e 100644 --- a/c-user/linker_sets.rst +++ b/c-user/linker_sets.rst @@ -113,408 +113,425 @@ For an example see test program :file:`sptests/splinkersets01`. Directives ========== +.. raw:: latex + + \clearpage + .. _RTEMS_LINKER_SET_BEGIN: RTEMS_LINKER_SET_BEGIN - Designator of the linker set begin marker ------------------------------------------------------------------ - -**CALLING SEQUENCE:** - .. index:: RTEMS_LINKER_SET_BEGIN -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - volatile type *begin = RTEMS_LINKER_SET_BEGIN( set ); + volatile type *begin = RTEMS_LINKER_SET_BEGIN( set ); -**DESCRIPTION:** +DESCRIPTION: + This macro generates the designator of the begin marker of the linker set + identified by ``set``. The item at the begin marker address is the first + member of the linker set if it exists, e.g. the linker set is not empty. A + linker set is empty, if and only if the begin and end markers have the same + address. -This macro generates the designator of the begin marker of the linker set -identified by ``set``. The item at the begin marker address is the first -member of the linker set if it exists, e.g. the linker set is not empty. A -linker set is empty, if and only if the begin and end markers have the same -address. + The ``set`` parameter itself must be a valid C designator on which no macro + expansion is performed. It uniquely identifies the linker set. -The ``set`` parameter itself must be a valid C designator on which no macro -expansion is performed. It uniquely identifies the linker set. +.. raw:: latex + + \clearpage .. _RTEMS_LINKER_SET_END: RTEMS_LINKER_SET_END - Designator of the linker set end marker -------------------------------------------------------------- - -**CALLING SEQUENCE:** - .. index:: RTEMS_LINKER_SET_END -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - volatile type *end = RTEMS_LINKER_SET_END( set ); + volatile type *end = RTEMS_LINKER_SET_END( set ); -**DESCRIPTION:** +DESCRIPTION: + This macro generates the designator of the end marker of the linker set + identified by ``set``. The item at the end marker address is not a member + of the linker set. The ``set`` parameter itself must be a valid C + designator on which no macro expansion is performed. It uniquely + identifies the linker set. -This macro generates the designator of the end marker of the linker set -identified by ``set``. The item at the end marker address is not a member of -the linker set. The ``set`` parameter itself must be a valid C designator on -which no macro expansion is performed. It uniquely identifies the linker set. +.. raw:: latex + + \clearpage .. _RTEMS_LINKER_SET_SIZE: RTEMS_LINKER_SET_SIZE - The linker set size in characters --------------------------------------------------------- - -**CALLING SEQUENCE:** - .. index:: RTEMS_LINKER_SET_SIZE -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c + + size_t size = RTEMS_LINKER_SET_SIZE( set ); - size_t size = RTEMS_LINKER_SET_SIZE( set ); +DESCRIPTION: + This macro returns the size of the linker set identified by ``set`` in + characters. The ``set`` parameter itself must be a valid C designator on + which no macro expansion is performed. It uniquely identifies the linker + set. -**DESCRIPTION:** +.. raw:: latex -This macro returns the size of the linker set identified by ``set`` in -characters. The ``set`` parameter itself must be a valid C designator on which -no macro expansion is performed. It uniquely identifies the linker set. + \clearpage .. _RTEMS_LINKER_ROSET_DECLARE: RTEMS_LINKER_ROSET_DECLARE - Declares a read-only linker set ------------------------------------------------------------ - -**CALLING SEQUENCE:** - .. index:: RTEMS_LINKER_ROSET_DECLARE -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c + + RTEMS_LINKER_ROSET_DECLARE( set, type ); - RTEMS_LINKER_ROSET_DECLARE( set, type ); +DESCRIPTION: + This macro generates declarations for the begin and end markers of a + read-only linker set identified by ``set``. The ``set`` parameter itself + must be a valid C designator on which no macro expansion is performed. It + uniquely identifies the linker set. The ``type`` parameter defines the type + of the linker set items. The type must be the same for all macro + invocations of a particular linker set. -**DESCRIPTION:** +.. raw:: latex -This macro generates declarations for the begin and end markers of a read-only -linker set identified by ``set``. The ``set`` parameter itself must be a valid -C designator on which no macro expansion is performed. It uniquely identifies -the linker set. The ``type`` parameter defines the type of the linker set -items. The type must be the same for all macro invocations of a particular -linker set. + \clearpage .. _RTEMS_LINKER_ROSET: RTEMS_LINKER_ROSET - Defines a read-only linker set --------------------------------------------------- - -**CALLING SEQUENCE:** - .. index:: RTEMS_LINKER_ROSET -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - RTEMS_LINKER_ROSET( set, type ); + RTEMS_LINKER_ROSET( set, type ); -**DESCRIPTION:** +DESCRIPTION: + This macro generates definitions for the begin and end markers of a + read-only linker set identified by ``set``. The ``set`` parameter itself + must be a valid C designator on which no macro expansion is performed. It + uniquely identifies the linker set. The ``type`` parameter defines the type + of the linker set items. The type must be the same for all macro + invocations of a particular linker set. -This macro generates definitions for the begin and end markers of a read-only -linker set identified by ``set``. The ``set`` parameter itself must be a valid -C designator on which no macro expansion is performed. It uniquely identifies -the linker set. The ``type`` parameter defines the type of the linker set -items. The type must be the same for all macro invocations of a particular -linker set. +.. raw:: latex + + \clearpage .. _RTEMS_LINKER_ROSET_ITEM_DECLARE: RTEMS_LINKER_ROSET_ITEM_DECLARE - Declares a read-only linker set item ---------------------------------------------------------------------- - -**CALLING SEQUENCE:** - .. index:: RTEMS_LINKER_ROSET_ITEM_DECLARE -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - RTEMS_LINKER_ROSET_ITEM_DECLARE( set, type, item ); + RTEMS_LINKER_ROSET_ITEM_DECLARE( set, type, item ); -**DESCRIPTION:** +DESCRIPTION: + This macro generates a declaration of an item contained in the read-only + linker set identified by ``set``. The ``set`` parameter itself must be a + valid C designator on which no macro expansion is performed. It uniquely + identifies the linker set. The ``type`` parameter defines the type of the + linker set items. The type must be the same for all macro invocations of a + particular linker set. The ``item`` parameter itself must be a valid C + designator on which no macro expansion is performed. It uniquely + identifies an item in the linker set. -This macro generates a declaration of an item contained in the read-only linker -set identified by ``set``. The ``set`` parameter itself must be a valid C -designator on which no macro expansion is performed. It uniquely identifies -the linker set. The ``type`` parameter defines the type of the linker set -items. The type must be the same for all macro invocations of a particular -linker set. The ``item`` parameter itself must be a valid C designator on which -no macro expansion is performed. It uniquely identifies an item in the linker -set. +.. raw:: latex + + \clearpage .. _RTEMS_LINKER_ROSET_ITEM_REFERENCE: RTEMS_LINKER_ROSET_ITEM_REFERENCE - References a read-only linker set item -------------------------------------------------------------------------- - -**CALLING SEQUENCE:** - .. index:: RTEMS_LINKER_ROSET_ITEM_REFERENCE -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - RTEMS_LINKER_ROSET_ITEM_REFERENCE( set, type, item ); + RTEMS_LINKER_ROSET_ITEM_REFERENCE( set, type, item ); -**DESCRIPTION:** +DESCRIPTION: + This macro generates a reference to an item contained in the read-only + linker set identified by ``set``. The ``set`` parameter itself must be a + valid C designator on which no macro expansion is performed. It uniquely + identifies the linker set. The ``type`` parameter defines the type of the + linker set items. The type must be the same for all macro invocations of a + particular linker set. The ``item`` parameter itself must be a valid C + designator on which no macro expansion is performed. It uniquely + identifies an item in the linker set. -This macro generates a reference to an item contained in the read-only linker -set identified by ``set``. The ``set`` parameter itself must be a valid C -designator on which no macro expansion is performed. It uniquely identifies -the linker set. The ``type`` parameter defines the type of the linker set -items. The type must be the same for all macro invocations of a particular -linker set. The ``item`` parameter itself must be a valid C designator on which -no macro expansion is performed. It uniquely identifies an item in the linker -set. +.. raw:: latex + + \clearpage .. _RTEMS_LINKER_ROSET_ITEM: RTEMS_LINKER_ROSET_ITEM - Defines a read-only linker set item ------------------------------------------------------------- - -**CALLING SEQUENCE:** - .. index:: RTEMS_LINKER_ROSET_ITEM -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - RTEMS_LINKER_ROSET_ITEM( set, type, item ); + RTEMS_LINKER_ROSET_ITEM( set, type, item ); -**DESCRIPTION:** +DESCRIPTION: + This macro generates a definition of an item contained in the read-only + linker set identified by ``set``. The ``set`` parameter itself must be a + valid C designator on which no macro expansion is performed. It uniquely + identifies the linker set. The ``type`` parameter defines the type of the + linker set items. The type must be the same for all macro invocations of a + particular linker set. The ``item`` parameter itself must be a valid C + designator on which no macro expansion is performed. It uniquely + identifies an item in the linker set. -This macro generates a definition of an item contained in the read-only linker -set identified by ``set``. The ``set`` parameter itself must be a valid C -designator on which no macro expansion is performed. It uniquely identifies -the linker set. The ``type`` parameter defines the type of the linker set -items. The type must be the same for all macro invocations of a particular -linker set. The ``item`` parameter itself must be a valid C designator on which -no macro expansion is performed. It uniquely identifies an item in the linker -set. +.. raw:: latex + + \clearpage .. _RTEMS_LINKER_ROSET_ITEM_ORDERED: RTEMS_LINKER_ROSET_ITEM_ORDERED - Defines an ordered read-only linker set item ------------------------------------------------------------------------------ - -**CALLING SEQUENCE:** - .. index:: RTEMS_LINKER_ROSET_ITEM_ORDERED -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - RTEMS_LINKER_ROSET_ITEM_ORDERED( set, type, item, order ); + RTEMS_LINKER_ROSET_ITEM_ORDERED( set, type, item, order ); -**DESCRIPTION:** +DESCRIPTION: + This macro generates a definition of an ordered item contained in the + read-only linker set identified by ``set``. The ``set`` parameter itself + must be a valid C designator on which no macro expansion is performed. It + uniquely identifies the linker set. The ``type`` parameter defines the type + of the linker set items. The type must be the same for all macro + invocations of a particular linker set. The ``item`` parameter itself must + be a valid C designator on which no macro expansion is performed. It + uniquely identifies an item in the linker set. The ``order`` parameter must + be a valid linker input section name part on which macro expansion is + performed. The items are lexicographically ordered according to the + ``order`` parameter within a linker set. Ordered items are placed before + unordered items in the linker set. -This macro generates a definition of an ordered item contained in the read-only -linker set identified by ``set``. The ``set`` parameter itself must be a valid -C designator on which no macro expansion is performed. It uniquely identifies -the linker set. The ``type`` parameter defines the type of the linker set -items. The type must be the same for all macro invocations of a particular -linker set. The ``item`` parameter itself must be a valid C designator on -which no macro expansion is performed. It uniquely identifies an item in the -linker set. The ``order`` parameter must be a valid linker input section name -part on which macro expansion is performed. The items are lexicographically -ordered according to the ``order`` parameter within a linker set. Ordered -items are placed before unordered items in the linker set. +NOTES: + To be resilient to typos in the order parameter, it is recommended to use + the following construct in macros defining items for a particular linker + set (see enum in ``XYZ_ITEM()``). -**NOTES:** + .. code-block:: c -To be resilient to typos in the order parameter, it is recommended to use the -following construct in macros defining items for a particular linker set (see -enum in ``XYZ_ITEM()``). + #include <rtems/linkersets.h> -.. code-block:: c + typedef struct { + int foo; + } xyz_item; - #include <rtems/linkersets.h> + /* The XYZ-order defines */ + #define XYZ_ORDER_FIRST 0x00001000 + #define XYZ_ORDER_AND_SO_ON 0x00002000 - typedef struct { - int foo; - } xyz_item; + /* Defines an ordered XYZ-item */ + #define XYZ_ITEM( item, order ) \ + enum { xyz_##item = order - order }; \ + RTEMS_LINKER_ROSET_ITEM_ORDERED( \ + xyz, const xyz_item *, item, order \ + ) = { &item } - /* The XYZ-order defines */ - #define XYZ_ORDER_FIRST 0x00001000 - #define XYZ_ORDER_AND_SO_ON 0x00002000 + /* Example item */ + static const xyz_item some_item = { 123 }; + XYZ_ITEM( some_item, XYZ_ORDER_FIRST ); - /* Defines an ordered XYZ-item */ - #define XYZ_ITEM( item, order ) \ - enum { xyz_##item = order - order }; \ - RTEMS_LINKER_ROSET_ITEM_ORDERED( \ - xyz, const xyz_item *, item, order \ - ) = { &item } +.. raw:: latex - /* Example item */ - static const xyz_item some_item = { 123 }; - XYZ_ITEM( some_item, XYZ_ORDER_FIRST ); + \clearpage .. _RTEMS_LINKER_RWSET_DECLARE: RTEMS_LINKER_RWSET_DECLARE - Declares a read-write linker set ------------------------------------------------------------- - -**CALLING SEQUENCE:** - .. index:: RTEMS_LINKER_RWSET_DECLARE -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c + + RTEMS_LINKER_RWSET_DECLARE( set, type ); - RTEMS_LINKER_RWSET_DECLARE( set, type ); +DESCRIPTION: + This macro generates declarations for the begin and end markers of a + read-write linker set identified by ``set``. The ``set`` parameter itself + must be a valid C designator on which no macro expansion is performed. It + uniquely identifies the linker set. The ``type`` parameter defines the type + of the linker set items. The type must be the same for all macro + invocations of a particular linker set. -**DESCRIPTION:** +.. raw:: latex -This macro generates declarations for the begin and end markers of a read-write -linker set identified by ``set``. The ``set`` parameter itself must be a valid -C designator on which no macro expansion is performed. It uniquely identifies -the linker set. The ``type`` parameter defines the type of the linker set -items. The type must be the same for all macro invocations of a particular -linker set. + \clearpage .. _RTEMS_LINKER_RWSET: RTEMS_LINKER_RWSET - Defines a read-write linker set ---------------------------------------------------- - -**CALLING SEQUENCE:** - .. index:: RTEMS_LINKER_RWSET -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c + + RTEMS_LINKER_RWSET( set, type ); - RTEMS_LINKER_RWSET( set, type ); +DESCRIPTION: + This macro generates definitions for the begin and end markers of a + read-write linker set identified by ``set``. The ``set`` parameter itself + must be a valid C designator on which no macro expansion is performed. It + uniquely identifies the linker set. The ``type`` parameter defines the type + of the linker set items. The type must be the same for all macro + invocations of a particular linker set. -**DESCRIPTION:** +.. raw:: latex -This macro generates definitions for the begin and end markers of a read-write -linker set identified by ``set``. The ``set`` parameter itself must be a valid -C designator on which no macro expansion is performed. It uniquely identifies -the linker set. The ``type`` parameter defines the type of the linker set -items. The type must be the same for all macro invocations of a particular -linker set. + \clearpage .. _RTEMS_LINKER_RWSET_ITEM_DECLARE: RTEMS_LINKER_RWSET_ITEM_DECLARE - Declares a read-write linker set item ----------------------------------------------------------------------- - -**CALLING SEQUENCE:** - .. index:: RTEMS_LINKER_RWSET_ITEM_DECLARE -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c + + RTEMS_LINKER_RWSET_ITEM_DECLARE( set, type, item ); - RTEMS_LINKER_RWSET_ITEM_DECLARE( set, type, item ); +DESCRIPTION: + This macro generates a declaration of an item contained in the read-write + linker set identified by ``set``. The ``set`` parameter itself must be a + valid C designator on which no macro expansion is performed. It uniquely + identifies the linker set. The ``type`` parameter defines the type of the + linker set items. The type must be the same for all macro invocations of a + particular linker set. The ``item`` parameter itself must be a valid C + designator on which no macro expansion is performed. It uniquely + identifies an item in the linker set. -**DESCRIPTION:** +.. raw:: latex -This macro generates a declaration of an item contained in the read-write -linker set identified by ``set``. The ``set`` parameter itself must be a valid -C designator on which no macro expansion is performed. It uniquely identifies -the linker set. The ``type`` parameter defines the type of the linker set -items. The type must be the same for all macro invocations of a particular -linker set. The ``item`` parameter itself must be a valid C designator on which -no macro expansion is performed. It uniquely identifies an item in the linker -set. + \clearpage .. _RTEMS_LINKER_RWSET_ITEM_REFERENCE: RTEMS_LINKER_RWSET_ITEM_REFERENCE - References a read-write linker set item --------------------------------------------------------------------------- - -**CALLING SEQUENCE:** - .. index:: RTEMS_LINKER_RWSET_ITEM_REFERENCE -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c + + RTEMS_LINKER_RWSET_ITEM_REFERENCE( set, type, item ); - RTEMS_LINKER_RWSET_ITEM_REFERENCE( set, type, item ); +DESCRIPTION: + This macro generates a reference to an item contained in the read-write + linker set identified by ``set``. The ``set`` parameter itself must be a + valid C designator on which no macro expansion is performed. It uniquely + identifies the linker set. The ``type`` parameter defines the type of the + linker set items. The type must be the same for all macro invocations of a + particular linker set. The ``item`` parameter itself must be a valid C + designator on which no macro expansion is performed. It uniquely + identifies an item in the linker set. -**DESCRIPTION:** +.. raw:: latex -This macro generates a reference to an item contained in the read-write linker -set identified by ``set``. The ``set`` parameter itself must be a valid C -designator on which no macro expansion is performed. It uniquely identifies -the linker set. The ``type`` parameter defines the type of the linker set -items. The type must be the same for all macro invocations of a particular -linker set. The ``item`` parameter itself must be a valid C designator on which -no macro expansion is performed. It uniquely identifies an item in the linker -set. + \clearpage .. _RTEMS_LINKER_RWSET_ITEM: RTEMS_LINKER_RWSET_ITEM - Defines a read-write linker set item -------------------------------------------------------------- - -**CALLING SEQUENCE:** - .. index:: RTEMS_LINKER_RWSET_ITEM -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - RTEMS_LINKER_RWSET_ITEM( set, type, item ); + RTEMS_LINKER_RWSET_ITEM( set, type, item ); -**DESCRIPTION:** +DESCRIPTION: + This macro generates a definition of an item contained in the read-write + linker set identified by ``set``. The ``set`` parameter itself must be a + valid C designator on which no macro expansion is performed. It uniquely + identifies the linker set. The ``type`` parameter defines the type of the + linker set items. The type must be the same for all macro invocations of a + particular linker set. The ``item`` parameter itself must be a valid C + designator on which no macro expansion is performed. It uniquely + identifies an item in the linker set. -This macro generates a definition of an item contained in the read-write linker -set identified by ``set``. The ``set`` parameter itself must be a valid C -designator on which no macro expansion is performed. It uniquely identifies -the linker set. The ``type`` parameter defines the type of the linker set -items. The type must be the same for all macro invocations of a particular -linker set. The ``item`` parameter itself must be a valid C designator on which -no macro expansion is performed. It uniquely identifies an item in the linker -set. +.. raw:: latex + + \clearpage .. _RTEMS_LINKER_RWSET_ITEM_ORDERED: RTEMS_LINKER_RWSET_ITEM_ORDERED - Defines an ordered read-write linker set item ------------------------------------------------------------------------------- - -**CALLING SEQUENCE:** - .. index:: RTEMS_LINKER_RWSET_ITEM_ORDERED -.. code-block:: c - - RTEMS_LINKER_RWSET_ITEM_ORDERED( set, type, item, order ); - -**DESCRIPTION:** - -This macro generates a definition of an ordered item contained in the -read-write linker set identified by ``set``. The ``set`` parameter itself must -be a valid C designator on which no macro expansion is performed. It uniquely -identifies the linker set. The ``type`` parameter defines the type of the -linker set items. The type must be the same for all macro invocations of a -particular linker set. The ``item`` parameter itself must be a valid C -designator on which no macro expansion is performed. It uniquely identifies an -item in the linker set. The ``order`` parameter must be a valid linker input -section name part on which macro expansion is performed. The items are -lexicographically ordered according to the ``order`` parameter within a linker -set. Ordered items are placed before unordered items in the linker set. - -**NOTES:** - -To be resilient to typos in the order parameter, it is recommended to use the -following construct in macros defining items for a particular linker set (see -enum in ``XYZ_ITEM()``). - -.. code-block:: c - - #include <rtems/linkersets.h> - - typedef struct { - int foo; - } xyz_item; - - /* The XYZ-order defines */ - #define XYZ_ORDER_FIRST 0x00001000 - #define XYZ_ORDER_AND_SO_ON 0x00002000 - - /* Defines an ordered XYZ-item */ - #define XYZ_ITEM( item, order ) \ - enum { xyz_##item = order - order }; \ - RTEMS_LINKER_RWSET_ITEM_ORDERED( \ - xyz, const xyz_item *, item, order \ - ) = { &item } - /* Example item */ - static const xyz_item some_item = { 123 }; - XYZ_ITEM( some_item, XYZ_ORDER_FIRST ); +CALLING SEQUENCE: + .. code-block:: c + + RTEMS_LINKER_RWSET_ITEM_ORDERED( set, type, item, order ); + +DESCRIPTION: + This macro generates a definition of an ordered item contained in the + read-write linker set identified by ``set``. The ``set`` parameter itself + must be a valid C designator on which no macro expansion is performed. It + uniquely identifies the linker set. The ``type`` parameter defines the type + of the linker set items. The type must be the same for all macro + invocations of a particular linker set. The ``item`` parameter itself must + be a valid C designator on which no macro expansion is performed. It + uniquely identifies an item in the linker set. The ``order`` parameter must + be a valid linker input section name part on which macro expansion is + performed. The items are lexicographically ordered according to the + ``order`` parameter within a linker set. Ordered items are placed before + unordered items in the linker set. + +NOTES: + To be resilient to typos in the order parameter, it is recommended to use + the following construct in macros defining items for a particular linker + set (see enum in ``XYZ_ITEM()``). + + .. code-block:: c + + #include <rtems/linkersets.h> + + typedef struct { + int foo; + } xyz_item; + + /* The XYZ-order defines */ + #define XYZ_ORDER_FIRST 0x00001000 + #define XYZ_ORDER_AND_SO_ON 0x00002000 + + /* Defines an ordered XYZ-item */ + #define XYZ_ITEM( item, order ) \ + enum { xyz_##item = order - order }; \ + RTEMS_LINKER_RWSET_ITEM_ORDERED( \ + xyz, const xyz_item *, item, order \ + ) = { &item } + /* Example item */ + static const xyz_item some_item = { 123 }; + XYZ_ITEM( some_item, XYZ_ORDER_FIRST ); diff --git a/c-user/message_manager.rst b/c-user/message_manager.rst index d622cef..5613da9 100644 --- a/c-user/message_manager.rst +++ b/c-user/message_manager.rst @@ -215,543 +215,540 @@ 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 + .. _rtems_message_queue_create: MESSAGE_QUEUE_CREATE - Create a queue ------------------------------------- .. index:: create a message queue - -**CALLING SEQUENCE:** - .. index:: rtems_message_queue_create -.. 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. +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 .. _rtems_message_queue_ident: MESSAGE_QUEUE_IDENT - Get ID of a queue --------------------------------------- .. index:: get ID of a message queue - -**CALLING SEQUENCE:** - .. index:: rtems_message_queue_ident -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_message_queue_ident( - rtems_name name, - uint32_t node, - rtems_id *id - ); + rtems_status_code rtems_message_queue_ident( + rtems_name name, + uint32_t node, + rtems_id *id + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. 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 - * - ``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. -**DESCRIPTION:** +NOTES: + This directive will not cause the running task to be preempted. -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. + 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. -**NOTES:** + 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 will not cause the running task to be preempted. + This directive does not generate activity on remote nodes. It accesses + only the local copy of the global object table. -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. +.. raw:: latex -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. + \clearpage .. _rtems_message_queue_delete: MESSAGE_QUEUE_DELETE - Delete a queue ------------------------------------- .. index:: delete a message queue - -**CALLING SEQUENCE:** - .. index:: rtems_message_queue_delete -.. code-block:: c - - rtems_status_code rtems_message_queue_delete( - rtems_id id - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_status_code rtems_message_queue_delete( + rtems_id id + ); -.. list-table:: - :class: rtems-table +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 + * - ``RTEMS_SUCCESSFUL`` + - queue deleted successfully + * - ``RTEMS_INVALID_ID`` + - invalid queue id + * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` + - cannot delete remote queue -**DESCRIPTION:** +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. -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. -**NOTES:** + 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. -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. + 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. -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 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. -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. + Proxies, used to represent remote tasks, are reclaimed when the message + queue is deleted. -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. +.. raw:: latex -Proxies, used to represent remote tasks, are reclaimed when the message queue -is deleted. + \clearpage .. _rtems_message_queue_send: MESSAGE_QUEUE_SEND - Put message at rear of a queue --------------------------------------------------- .. index:: send message to a queue - -**CALLING SEQUENCE:** - .. index:: rtems_message_queue_send -.. code-block:: c - - rtems_status_code rtems_message_queue_send( - rtems_id id, - cons 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. +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_message_queue_send( + rtems_id id, + cons 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 .. _rtems_message_queue_urgent: MESSAGE_QUEUE_URGENT - Put message at front of a queue ------------------------------------------------------ .. index:: put message at front of queue - -**CALLING SEQUENCE:** - .. index:: rtems_message_queue_urgent -.. 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. +**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 .. _rtems_message_queue_broadcast: MESSAGE_QUEUE_BROADCAST - Broadcast N messages to a queue --------------------------------------------------------- .. index:: broadcast message to a queue - -**CALLING SEQUENCE:** - .. index:: rtems_message_queue_broadcast -.. 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. +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 .. _rtems_message_queue_receive: MESSAGE_QUEUE_RECEIVE - Receive message from a queue ---------------------------------------------------- .. index:: receive message from a queue - -**CALLING SEQUENCE:** - .. index:: rtems_message_queue_receive -.. 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. +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 .. _rtems_message_queue_get_number_pending: MESSAGE_QUEUE_GET_NUMBER_PENDING - Get number of messages pending on a queue ---------------------------------------------------------------------------- .. index:: get number of pending messages - -**CALLING SEQUENCE:** - .. index:: rtems_message_queue_get_number_pending -.. code-block:: c - - rtems_status_code rtems_message_queue_get_number_pending( - rtems_id id, - uint32_t *count - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_status_code rtems_message_queue_get_number_pending( + rtems_id id, + uint32_t *count + ); -.. list-table:: - :class: rtems-table +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 + * - ``RTEMS_SUCCESSFUL`` + - number of messages pending returned successfully + * - ``RTEMS_INVALID_ADDRESS`` + - ``count`` is NULL + * - ``RTEMS_INVALID_ID`` + - invalid queue id -**DESCRIPTION:** +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. -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. -**NOTES:** +.. raw:: latex -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. + \clearpage .. _rtems_message_queue_flush: MESSAGE_QUEUE_FLUSH - Flush all messages on a queue --------------------------------------------------- .. index:: flush messages on a queue - -**CALLING SEQUENCE:** - .. index:: rtems_message_queue_flush -.. 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. +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.rst index 5270256..5323cfa 100644 --- a/c-user/multiprocessing.rst +++ b/c-user/multiprocessing.rst @@ -471,34 +471,34 @@ 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 + .. _rtems_multiprocessing_announce: MULTIPROCESSING_ANNOUNCE - Announce the arrival of a packet ----------------------------------------------------------- .. index:: announce arrival of package - -**CALLING SEQUENCE:** - .. index:: rtems_multiprocessing_announce -.. code-block:: c - - void rtems_multiprocessing_announce( void ); - -**DIRECTIVE STATUS CODES:** - -NONE +CALLING SEQUENCE: + .. code-block:: c -**DESCRIPTION:** + void rtems_multiprocessing_announce( void ); -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. +DIRECTIVE STATUS CODES: + NONE -**NOTES:** +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. -This directive is typically called from an ISR. +NOTES: + This directive is typically called from an ISR. -This directive will almost certainly cause the calling task to be preempted. + This directive will almost certainly cause the calling task to be + preempted. -This directive does not generate activity on remote nodes. + This directive does not generate activity on remote nodes. diff --git a/c-user/object_services.rst b/c-user/object_services.rst index f4b388a..e748de7 100644 --- a/c-user/object_services.rst +++ b/c-user/object_services.rst @@ -176,38 +176,41 @@ parts and "pretty-printed." Directives ========== +.. raw:: latex + + \clearpage + .. _rtems_build_name: BUILD_NAME - Build object name from characters ---------------------------------------------- .. index:: build object name - -**CALLING SEQUENCE:** - .. index:: rtems_build_name -.. code-block:: c - - rtems_name rtems_build_name( - uint8_t c1, - uint8_t c2, - uint8_t c3, - uint8_t c4 - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES** + rtems_name rtems_build_name( + uint8_t c1, + uint8_t c2, + uint8_t c3, + uint8_t c4 + ); -Returns a name constructed from the four characters. +DIRECTIVE STATUS CODES: + Returns a name constructed from the four characters. -**DESCRIPTION:** +DESCRIPTION: + This service takes the four characters provided as arguments and constructs + a thirty-two bit object name with ``c1`` in the most significant byte and + ``c4`` in the least significant byte. -This service takes the four characters provided as arguments and constructs a -thirty-two bit object name with ``c1`` in the most significant byte and ``c4`` -in the least significant byte. +NOTES: + This directive is strictly local and does not impact task scheduling. -**NOTES:** +.. raw:: latex -This directive is strictly local and does not impact task scheduling. + \clearpage .. _rtems_object_get_classic_name: @@ -215,38 +218,37 @@ OBJECT_GET_CLASSIC_NAME - Lookup name from id --------------------------------------------- .. index:: get name from id .. index:: obtain name from id - -**CALLING SEQUENCE:** - .. index:: rtems_object_get_classic_name -.. code-block:: c - - rtems_status_code rtems_object_get_classic_name( - rtems_id id, - rtems_name *name - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES** + rtems_status_code rtems_object_get_classic_name( + rtems_id id, + rtems_name *name + ); -.. list-table:: - :class: rtems-table +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 + * - ``RTEMS_SUCCESSFUL`` + - name looked up successfully + * - ``RTEMS_INVALID_ADDRESS`` + - invalid name pointer + * - ``RTEMS_INVALID_ID`` + - invalid object id -**DESCRIPTION:** +DESCRIPTION: + This service looks up the name for the object ``id`` specified and, if + found, places the result in ``*name``. -This service looks up the name for the object ``id`` specified and, if found, -places the result in ``*name``. +NOTES: + This directive is strictly local and does not impact task scheduling. -**NOTES:** +.. raw:: latex -This directive is strictly local and does not impact task scheduling. + \clearpage .. _rtems_object_get_name: @@ -254,535 +256,515 @@ OBJECT_GET_NAME - Obtain object name as string ---------------------------------------------- .. index:: get object name as string .. index:: obtain object name as string - -**CALLING SEQUENCE:** - .. index:: rtems_object_get_name -.. code-block:: c - - char* rtems_object_get_name( - rtems_id id, - size_t length, - char *name - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES** + char* rtems_object_get_name( + rtems_id id, + size_t length, + char *name + ); -Returns a pointer to the name if successful or ``NULL`` otherwise. +DIRECTIVE STATUS CODES: + Returns a pointer to the name if successful or ``NULL`` otherwise. -**DESCRIPTION:** +DESCRIPTION: + This service looks up the name of the object specified by ``id`` and places + it in the memory pointed to by ``name``. Every attempt is made to return + name as a printable string even if the object has the Classic API + thirty-two bit style name. -This service looks up the name of the object specified by ``id`` and places it -in the memory pointed to by ``name``. Every attempt is made to return name as -a printable string even if the object has the Classic API thirty-two bit style -name. +NOTES: + This directive is strictly local and does not impact task scheduling. -**NOTES:** +.. raw:: latex -This directive is strictly local and does not impact task scheduling. + \clearpage .. _rtems_object_set_name: OBJECT_SET_NAME - Set object name --------------------------------- .. index:: set object name - -**CALLING SEQUENCE:** - .. index:: rtems_object_set_name -.. code-block:: c - - rtems_status_code rtems_object_set_name( - rtems_id id, - const char *name - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES** + rtems_status_code rtems_object_set_name( + rtems_id id, + const char *name + ); -.. list-table:: - :class: rtems-table +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 + * - ``RTEMS_SUCCESSFUL`` + - name looked up successfully + * - ``RTEMS_INVALID_ADDRESS`` + - invalid name pointer + * - ``RTEMS_INVALID_ID`` + - invalid object id -**DESCRIPTION:** +DESCRIPTION: + This service sets the name of ``id`` to that specified by the string + located at ``name``. -This service sets the name of ``id`` to that specified by the string located at -``name``. +NOTES: + This directive is strictly local and does not impact task scheduling. -**NOTES:** + 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``. -This directive is strictly local and does not impact task scheduling. + 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 -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``. +.. raw:: latex -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 + \clearpage .. _rtems_object_id_get_api: OBJECT_ID_GET_API - Obtain API from Id -------------------------------------- .. index:: obtain API from id - -**CALLING SEQUENCE:** - .. index:: rtems_object_id_get_api -.. code-block:: c - - int rtems_object_id_get_api( - rtems_id id - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES** + int rtems_object_id_get_api( + rtems_id id + ); -Returns the API portion of the object Id. +DIRECTIVE STATUS CODES: + Returns the API portion of the object Id. -**DESCRIPTION:** +DESCRIPTION: + This directive returns the API portion of the provided object ``id``. -This directive returns the API portion of the provided object ``id``. +NOTES: + This directive is strictly local and does not impact task scheduling. -**NOTES:** + This directive does NOT validate the ``id`` provided. -This directive is strictly local and does not impact task scheduling. +.. raw:: latex -This directive does NOT validate the ``id`` provided. + \clearpage .. _rtems_object_id_get_class: OBJECT_ID_GET_CLASS - Obtain Class from Id ------------------------------------------ .. index:: obtain class from object id - -**CALLING SEQUENCE:** - .. index:: rtems_object_id_get_class -.. code-block:: c - - int rtems_object_id_get_class( - rtems_id id - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES** + int rtems_object_id_get_class( + rtems_id id + ); -Returns the class portion of the object Id. +DIRECTIVE STATUS CODES: + Returns the class portion of the object Id. -**DESCRIPTION:** +DESCRIPTION: + This directive returns the class portion of the provided object ``id``. -This directive returns the class portion of the provided object ``id``. +NOTES: + This directive is strictly local and does not impact task scheduling. -**NOTES:** + This directive does NOT validate the ``id`` provided. -This directive is strictly local and does not impact task scheduling. +.. raw:: latex -This directive does NOT validate the ``id`` provided. + \clearpage .. _rtems_object_id_get_node: OBJECT_ID_GET_NODE - Obtain Node from Id ---------------------------------------- .. index:: obtain node from object id - -**CALLING SEQUENCE:** - .. index:: rtems_object_id_get_node -.. code-block:: c - - int rtems_object_id_get_node( - rtems_id id - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES** + int rtems_object_id_get_node( + rtems_id id + ); -Returns the node portion of the object Id. +DIRECTIVE STATUS CODES: + Returns the node portion of the object Id. -**DESCRIPTION:** +DESCRIPTION: + This directive returns the node portion of the provided object ``id``. -This directive returns the node portion of the provided object ``id``. +NOTES: + This directive is strictly local and does not impact task scheduling. -**NOTES:** + This directive does NOT validate the ``id`` provided. -This directive is strictly local and does not impact task scheduling. +.. raw:: latex -This directive does NOT validate the ``id`` provided. + \clearpage .. _rtems_object_id_get_index: OBJECT_ID_GET_INDEX - Obtain Index from Id ------------------------------------------ .. index:: obtain index from object id - -**CALLING SEQUENCE:** - .. index:: rtems_object_id_get_index -.. code-block:: c - - int rtems_object_id_get_index( - rtems_id id - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES** + int rtems_object_id_get_index( + rtems_id id + ); -Returns the index portion of the object Id. +DIRECTIVE STATUS CODES: + Returns the index portion of the object Id. -**DESCRIPTION:** +DESCRIPTION: + This directive returns the index portion of the provided object ``id``. -This directive returns the index portion of the provided object ``id``. +NOTES: + This directive is strictly local and does not impact task scheduling. -**NOTES:** + This directive does NOT validate the ``id`` provided. -This directive is strictly local and does not impact task scheduling. +.. raw:: latex -This directive does NOT validate the ``id`` provided. + \clearpage .. _rtems_build_id: BUILD_ID - Build Object Id From Components ------------------------------------------ .. index:: build object id from components - -**CALLING SEQUENCE:** - .. index:: rtems_build_id -.. code-block:: c +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** + rtems_id rtems_build_id( + int the_api, + int the_class, + int the_node, + int the_index + ); -Returns an object Id constructed from the provided arguments. +DIRECTIVE STATUS CODES: + Returns an object Id constructed from the provided arguments. -**DESCRIPTION:** +DESCRIPTION: + This service constructs an object Id from the provided ``the_api``, + ``the_class``, ``the_node``, and ``the_index``. -This service constructs an object Id from the provided ``the_api``, -``the_class``, ``the_node``, and ``the_index``. +NOTES: + This directive is strictly local and does not impact task scheduling. -**NOTES:** + This directive does NOT validate the arguments provided or the Object id + returned. -This directive is strictly local and does not impact task scheduling. +.. raw:: latex -This directive does NOT validate the arguments provided or the Object id -returned. + \clearpage .. _rtems_object_id_api_minimum: OBJECT_ID_API_MINIMUM - Obtain Minimum API Value ------------------------------------------------ .. index:: obtain minimum API value - -**CALLING SEQUENCE:** - .. index:: rtems_object_id_api_minimum -.. code-block:: c - - int rtems_object_id_api_minimum(void); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES** + int rtems_object_id_api_minimum(void); -Returns the minimum valid for the API portion of an object Id. +DIRECTIVE STATUS CODES: + Returns the minimum valid for the API portion of an object Id. -**DESCRIPTION:** +DESCRIPTION: + This service returns the minimum valid for the API portion of an object Id. -This service returns the minimum valid for the API portion of an object Id. +NOTES: + This directive is strictly local and does not impact task scheduling. -**NOTES:** +.. raw:: latex -This directive is strictly local and does not impact task scheduling. + \clearpage .. _rtems_object_id_api_maximum: OBJECT_ID_API_MAXIMUM - Obtain Maximum API Value ------------------------------------------------ .. index:: obtain maximum API value - -**CALLING SEQUENCE:** - .. index:: rtems_object_id_api_maximum -.. code-block:: c - - int rtems_object_id_api_maximum(void); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES** + int rtems_object_id_api_maximum(void); -Returns the maximum valid for the API portion of an object Id. +DIRECTIVE STATUS CODES: + Returns the maximum valid for the API portion of an object Id. -**DESCRIPTION:** +DESCRIPTION: + This service returns the maximum valid for the API portion of an object Id. -This service returns the maximum valid for the API portion of an object Id. +NOTES: + This directive is strictly local and does not impact task scheduling. -**NOTES:** +.. raw:: latex -This directive is strictly local and does not impact task scheduling. + \clearpage .. _rtems_object_api_minimum_class: OBJECT_API_MINIMUM_CLASS - Obtain Minimum Class Value ----------------------------------------------------- .. index:: obtain minimum class value - -**CALLING SEQUENCE:** - .. index:: rtems_object_api_minimum_class -.. code-block:: c - - int rtems_object_api_minimum_class( - int api - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES** + int rtems_object_api_minimum_class( + int api + ); -If ``api`` is not valid, -1 is returned. +DIRECTIVE STATUS CODES: + If ``api`` is not valid, -1 is returned. -If successful, this service returns the minimum valid for the class portion of -an object Id for the specified ``api``. + If successful, this service returns the minimum valid for the class portion + of an object Id for the specified ``api``. -**DESCRIPTION:** +DESCRIPTION: + This service returns the minimum valid for the class portion of an object + Id for the specified ``api``. -This service returns the minimum valid for the class portion of an object Id -for the specified ``api``. +NOTES: + This directive is strictly local and does not impact task scheduling. -**NOTES:** +.. raw:: latex -This directive is strictly local and does not impact task scheduling. + \clearpage .. _rtems_object_api_maximum_class: OBJECT_API_MAXIMUM_CLASS - Obtain Maximum Class Value ----------------------------------------------------- .. index:: obtain maximum class value - -**CALLING SEQUENCE:** - .. index:: rtems_object_api_maximum_class -.. code-block:: c - - int rtems_object_api_maximum_class( - int api - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES** + int rtems_object_api_maximum_class( + int api + ); -If ``api`` is not valid, -1 is returned. +DIRECTIVE STATUS CODES: + If ``api`` is not valid, -1 is returned. -If successful, this service returns the maximum valid for the class portion of -an object Id for the specified ``api``. + If successful, this service returns the maximum valid for the class portion + of an object Id for the specified ``api``. -**DESCRIPTION:** +DESCRIPTION: + This service returns the maximum valid for the class portion of an object + Id for the specified ``api``. -This service returns the maximum valid for the class portion of an object Id -for the specified ``api``. +NOTES: + This directive is strictly local and does not impact task scheduling. -**NOTES:** +.. raw:: latex -This directive is strictly local and does not impact task scheduling. + \clearpage .. _rtems_object_id_api_minimum_class: OBJECT_ID_API_MINIMUM_CLASS - Obtain Minimum Class Value for an API ------------------------------------------------------------------- .. index:: obtain minimum class value for an API - -**CALLING SEQUENCE:** - .. index:: rtems_object_id_api_minimum_class -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - int rtems_object_get_id_api_minimum_class( - int api - ); - -**DIRECTIVE STATUS CODES** + int rtems_object_get_id_api_minimum_class( + int api + ); -If ``api`` is not valid, -1 is returned. +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``. + If successful, this service returns the index corresponding to the first + object class of the specified ``api``. -**DESCRIPTION:** +DESCRIPTION: + This service returns the index for the first object class associated with + the specified ``api``. -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. -**NOTES:** +.. raw:: latex -This directive is strictly local and does not impact task scheduling. + \clearpage .. _rtems_object_id_api_maximum_class: OBJECT_ID_API_MAXIMUM_CLASS - Obtain Maximum Class Value for an API ------------------------------------------------------------------- .. index:: obtain maximum class value for an API - -**CALLING SEQUENCE:** - .. index:: rtems_object_id_api_maximum_class -.. code-block:: c - - int rtems_object_get_api_maximum_class( - int api - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES** + int rtems_object_get_api_maximum_class( + int api + ); -If ``api`` is not valid, -1 is returned. +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``. + If successful, this service returns the index corresponding to the last + object class of the specified ``api``. -**DESCRIPTION:** +DESCRIPTION: + This service returns the index for the last object class associated with + the specified ``api``. -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. -**NOTES:** +.. raw:: latex -This directive is strictly local and does not impact task scheduling. + \clearpage .. _rtems_object_get_api_name: OBJECT_GET_API_NAME - Obtain API Name ------------------------------------- .. index:: obtain API name - -**CALLING SEQUENCE:** - .. index:: rtems_object_get_api_name -.. code-block:: c - - const char* rtems_object_get_api_name( - int api - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES** + const char* rtems_object_get_api_name( + int api + ); -If ``api`` is not valid, the string ``"BAD API"`` is returned. +DIRECTIVE STATUS CODES: + If ``api`` is not valid, the string ``"BAD API"`` is returned. -If successful, this service returns a pointer to a string containing the name -of the specified ``api``. + If successful, this service returns a pointer to a string containing the + name of the specified ``api``. -**DESCRIPTION:** +DESCRIPTION: + This service returns the name of the specified ``api``. -This service returns the name of the specified ``api``. +NOTES: + This directive is strictly local and does not impact task scheduling. -**NOTES:** + The string returned is from constant space. Do not modify or free it. -This directive is strictly local and does not impact task scheduling. +.. raw:: latex -The string returned is from constant space. Do not modify or free it. + \clearpage .. _rtems_object_get_api_class_name: OBJECT_GET_API_CLASS_NAME - Obtain Class Name --------------------------------------------- .. index:: obtain class name - -**CALLING SEQUENCE:** - .. index:: rtems_object_get_api_class_name -.. code-block:: c - - const char *rtems_object_get_api_class_name( - int the_api, - int the_class - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES** + const char *rtems_object_get_api_class_name( + int the_api, + int the_class + ); -If ``the_api`` is not valid, the string ``"BAD API"`` is returned. +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 ``the_class`` is not valid, the string ``"BAD CLASS"`` is returned. -If successful, this service returns a pointer to a string containing the name -of the specified ``the_api`` / ``the_class`` pair. + If successful, this service returns a pointer to a string containing the + name of the specified ``the_api`` / ``the_class`` pair. -**DESCRIPTION:** +DESCRIPTION: + This service returns the name of the object class indicated by the + specified ``the_api`` and ``the_class``. -This service returns the name of the object class indicated by the specified -``the_api`` and ``the_class``. +NOTES: + This directive is strictly local and does not impact task scheduling. -**NOTES:** + The string returned is from constant space. Do not modify or free it. -This directive is strictly local and does not impact task scheduling. +.. raw:: latex -The string returned is from constant space. Do not modify or free it. + \clearpage .. _rtems_object_get_class_information: OBJECT_GET_CLASS_INFORMATION - Obtain Class Information ------------------------------------------------------- .. index:: obtain class information - -**CALLING SEQUENCE:** - .. index:: rtems_object_get_class_information -.. code-block:: c +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`` + rtems_status_code rtems_object_get_class_information( + int the_api, + int the_class, + rtems_object_api_class_information *info + ); -If successful, the structure located at ``info`` will be filled in with -information about the specified ``api`` / ``the_class`` pairing. +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -**DESCRIPTION:** + * - ``RTEMS_SUCCESSFUL`` + - information obtained successfully + * - ``RTEMS_INVALID_ADDRESS`` + - ``info`` is NULL + * - ``RTEMS_INVALID_NUMBER`` + - invalid ``api`` or ``the_class`` -This service returns information about the object class indicated by the -specified ``api`` and ``the_class``. This structure is defined as follows: + If successful, the structure located at ``info`` will be filled in with + information about the specified ``api`` / ``the_class`` pairing. -.. code-block:: c +DESCRIPTION: + This service returns information about the object class indicated by the + specified ``api`` and ``the_class``. This structure is defined as follows: - typedef struct { - rtems_id minimum_id; - rtems_id maximum_id; - int maximum; - bool auto_extend; - int unallocated; - } rtems_object_api_class_information; + .. code-block:: c -**NOTES:** + typedef struct { + rtems_id minimum_id; + rtems_id maximum_id; + int maximum; + bool auto_extend; + int unallocated; + } rtems_object_api_class_information; -This directive is strictly local and does not impact task scheduling. +NOTES: + This directive is strictly local and does not impact task scheduling. diff --git a/c-user/partition_manager.rst b/c-user/partition_manager.rst index 1de5fc1..f3d0a92 100644 --- a/c-user/partition_manager.rst +++ b/c-user/partition_manager.rst @@ -129,99 +129,103 @@ 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 + .. _rtems_partition_create: PARTITION_CREATE - Create a partition ------------------------------------- .. index:: create a partition - -**CALLING SEQUENCE:** - .. index:: rtems_partition_create -.. code-block:: c - - rtems_status_code rtems_partition_create( - rtems_name name, - void *starting_address, - uint32_t length, - uint32_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`` - - address not on four byte 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 not a multiple of 4 - * - ``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 ``starting_address`` must be properly aligned for the target architecture. - -The ``buffer_size`` parameter must be a multiple of the CPU alignment factor. -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. +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_partition_create( + rtems_name name, + void *starting_address, + uint32_t length, + uint32_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`` + - address not on four byte 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 not a multiple of 4 + * - ``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 ``starting_address`` must be properly aligned for the target + architecture. + + The ``buffer_size`` parameter must be a multiple of the CPU alignment + factor. 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. + +.. raw:: latex + + \clearpage .. _rtems_partition_ident: @@ -229,104 +233,102 @@ PARTITION_IDENT - Get ID of a partition --------------------------------------- .. index:: get ID of a partition .. index:: obtain ID of a partition - -**CALLING SEQUENCE:** - .. index:: rtems_partition_ident -.. code-block:: c - - rtems_status_code rtems_partition_ident( - rtems_name name, - uint32_t node, - rtems_id *id - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_status_code rtems_partition_ident( + rtems_name name, + uint32_t node, + rtems_id *id + ); -.. list-table:: - :class: rtems-table +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 + * - ``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:** +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. -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. -**NOTES:** + 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. -This directive will not cause the running task to be preempted. + 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. -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. + This directive does not generate activity on remote nodes. It accesses + only the local copy of the global object table. -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. +.. raw:: latex -This directive does not generate activity on remote nodes. It accesses only -the local copy of the global object table. + \clearpage .. _rtems_partition_delete: PARTITION_DELETE - Delete a partition ------------------------------------- .. index:: delete a partition - -**CALLING SEQUENCE:** - .. index:: rtems_partition_delete -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_partition_delete( - rtems_id id - ); + rtems_status_code rtems_partition_delete( + rtems_id id + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. 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 + * - ``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:** +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. -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. -**NOTES:** + 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. -This directive will not cause the calling task to be preempted. + 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 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. + The partition must reside on the local node, even if the partition was + created with the ``RTEMS_GLOBAL`` option. -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. +.. raw:: latex -The partition must reside on the local node, even if the partition was created -with the ``RTEMS_GLOBAL`` option. + \clearpage .. _rtems_partition_get_buffer: @@ -334,92 +336,86 @@ PARTITION_GET_BUFFER - Get buffer from a partition -------------------------------------------------- .. index:: get buffer from partition .. index:: obtain buffer from partition - -**CALLING SEQUENCE:** - .. index:: rtems_partition_get_buffer -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_partition_get_buffer( - rtems_id id, - void **buffer - ); + rtems_status_code rtems_partition_get_buffer( + rtems_id id, + void **buffer + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. 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 + * - ``RTEMS_SUCCESSFUL`` + - buffer obtained successfully + * - ``RTEMS_INVALID_ADDRESS`` + - ``buffer`` is NULL + * - ``RTEMS_INVALID_ID`` + - invalid partition id + * - ``RTEMS_UNSATISFIED`` + - all buffers are allocated -**DESCRIPTION:** +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. -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. -**NOTES:** + All buffers begin on a four byte boundary. -This directive will not cause the running task to be preempted. + A task cannot wait on a buffer to become available. -All buffers begin on a four byte boundary. + 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. -A task cannot wait on a buffer to become available. +.. raw:: latex -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. + \clearpage .. _rtems_partition_return_buffer: PARTITION_RETURN_BUFFER - Return buffer to a partition ------------------------------------------------------ .. index:: return buffer to partitition - -**CALLING SEQUENCE:** - .. index:: rtems_partition_return_buffer -.. code-block:: c - - rtems_status_code rtems_partition_return_buffer( - rtems_id id, - void *buffer - ); - -**DIRECTIVE STATUS CODES:** - -.. list-table:: - :class: rtems-table +CALLING SEQUENCE: + .. code-block:: c - * - ``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 + rtems_status_code rtems_partition_return_buffer( + rtems_id id, + void *buffer + ); -**DESCRIPTION:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -This directive returns the buffer specified by buffer to the partition -specified by id. + * - ``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 -**NOTES:** +DESCRIPTION: + This directive returns the buffer specified by buffer to the partition + specified by id. -This directive will not cause the running task to be preempted. +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 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. + Returning a buffer multiple times is an error. It will corrupt the + internal state of the partition. diff --git a/c-user/rate_monotonic_manager.rst b/c-user/rate_monotonic_manager.rst index e0fc66b..c2ba1a5 100644 --- a/c-user/rate_monotonic_manager.rst +++ b/c-user/rate_monotonic_manager.rst @@ -639,46 +639,49 @@ 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 + .. _rtems_rate_monotonic_create: RATE_MONOTONIC_CREATE - Create a rate monotonic period ------------------------------------------------------ .. index:: create a period - -**CALLING SEQUENCE:** - .. index:: rtems_rate_monotonic_create -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_rate_monotonic_create( - rtems_name name, - rtems_id *id - ); + rtems_status_code rtems_rate_monotonic_create( + rtems_name name, + rtems_id *id + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. 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 + * - ``RTEMS_SUCCESSFUL`` + - rate monotonic period created successfully + * - ``RTEMS_INVALID_NAME`` + - invalid period name + * - ``RTEMS_TOO_MANY`` + - too many periods created -**DESCRIPTION:** +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. -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. -**NOTES:** +.. raw:: latex -This directive will not cause the calling task to be preempted. + \clearpage .. _rtems_rate_monotonic_ident: @@ -686,118 +689,118 @@ RATE_MONOTONIC_IDENT - Get ID of a period ----------------------------------------- .. index:: get ID of a period .. index:: obtain ID of a period - -**CALLING SEQUENCE:** - .. index:: rtems_rate_monotonic_ident -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_rate_monotonic_ident( - rtems_name name, - rtems_id *id - ); + rtems_status_code rtems_rate_monotonic_ident( + rtems_name name, + rtems_id *id + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - period identified successfully - * - ``RTEMS_INVALID_NAME`` - - period name not found + * - ``RTEMS_SUCCESSFUL`` + - period identified successfully + * - ``RTEMS_INVALID_NAME`` + - period name not found -**DESCRIPTION:** +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. -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. -**NOTES:** +.. raw:: latex -This directive will not cause the running task to be preempted. + \clearpage .. _rtems_rate_monotonic_cancel: RATE_MONOTONIC_CANCEL - Cancel a period --------------------------------------- .. index:: cancel a period - -**CALLING SEQUENCE:** - .. index:: rtems_rate_monotonic_cancel -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_rate_monotonic_cancel( - rtems_id id - ); + rtems_status_code rtems_rate_monotonic_cancel( + rtems_id id + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. 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 - * - ``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: -**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. -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. -**NOTES:** + The rate monotonic period specified by id must have been created by the + calling task. -This directive will not cause the running task to be preempted. +.. raw:: latex -The rate monotonic period specified by id must have been created by the calling -task. + \clearpage .. _rtems_rate_monotonic_delete: +.. index:: rtems_rate_monotonic_delete RATE_MONOTONIC_DELETE - Delete a rate monotonic period ------------------------------------------------------ .. index:: delete a period -**CALLING SEQUENCE:** +CALLING SEQUENCE: + .. code-block:: c -.. index:: rtems_rate_monotonic_delete + rtems_status_code rtems_rate_monotonic_delete( + rtems_id id + ); -.. code-block:: c +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table - rtems_status_code rtems_rate_monotonic_delete( - rtems_id id - ); + * - ``RTEMS_SUCCESSFUL`` + - period deleted successfully + * - ``RTEMS_INVALID_ID`` + - invalid rate monotonic period id -**DIRECTIVE STATUS CODES:** +DESCRIPTION: -.. list-table:: - :class: rtems-table + 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. - * - ``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. -**NOTES:** + A rate monotonic period can be deleted by a task other than the task which + created the period. -This directive will not cause the running task to be preempted. +.. raw:: latex -A rate monotonic period can be deleted by a task other than the task which -created the period. + \clearpage .. _rtems_rate_monotonic_period: @@ -806,49 +809,49 @@ RATE_MONOTONIC_PERIOD - Conclude current/Start next period .. index:: conclude current period .. index:: start current period .. index:: period initiation - -**CALLING SEQUENCE:** - .. index:: rtems_rate_monotonic_period -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_rate_monotonic_period( - rtems_id id, - rtems_interval length - ); + rtems_status_code rtems_rate_monotonic_period( + rtems_id id, + rtems_interval length + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. 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 + * - ``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:** +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. -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 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. -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. -**NOTES:** +.. raw:: latex -This directive will not cause the running task to be preempted. + \clearpage .. _rtems_rate_monotonic_get_status: @@ -856,63 +859,62 @@ RATE_MONOTONIC_GET_STATUS - Obtain status from a period ------------------------------------------------------- .. index:: get status of period .. index:: obtain status of period - -**CALLING SEQUENCE:** - .. index:: rtems_rate_monotonic_get_status -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_rate_monotonic_get_status( - rtems_id id, - rtems_rate_monotonic_period_status *status - ); + rtems_status_code rtems_rate_monotonic_get_status( + rtems_id id, + rtems_rate_monotonic_period_status *status + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. list-table:: - :class: rtems-table + * - ``RTEMS_SUCCESSFUL`` + - period initiated successfully + * - ``RTEMS_INVALID_ID`` + - invalid rate monotonic period id + * - ``RTEMS_INVALID_ADDRESS`` + - invalid address of status - * - ``RTEMS_SUCCESSFUL`` - - period initiated successfully - * - ``RTEMS_INVALID_ID`` - - invalid rate monotonic period id - * - ``RTEMS_INVALID_ADDRESS`` - - invalid address of status +*DESCRIPTION: + This directive returns status information associated with the rate + monotonic period id in the following data structure: -**DESCRIPTION:** + .. index:: rtems_rate_monotonic_period_status -This directive returns status information associated with the rate monotonic -period id in the following data structure: + .. code-block:: c -.. index:: rtems_rate_monotonic_period_status + 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; + } rtems_rate_monotonic_period_status; -.. code-block:: c + .. COMMENT: RATE_MONOTONIC_INACTIVE does not have RTEMS in front of it. - 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; - } 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 ticks_since_last_period value contains the -elapsed time which has occurred since the last invocation of the -``rtems_rate_monotonic_period`` directive and the -``ticks_executed_since_last_period`` contains how much processor time the -owning task has consumed since the invocation of the -``rtems_rate_monotonic_period`` directive. + 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 + ticks_since_last_period value contains the elapsed time which has occurred + since the last invocation of the ``rtems_rate_monotonic_period`` directive + and the ``ticks_executed_since_last_period`` contains how much processor + time the owning task has consumed since the invocation of the + ``rtems_rate_monotonic_period`` directive. -**NOTES:** +NOTES: + This directive will not cause the running task to be preempted. -This directive will not cause the running task to be preempted. +.. raw:: latex + + \clearpage .. _rtems_rate_monotonic_get_statistics: @@ -920,131 +922,128 @@ RATE_MONOTONIC_GET_STATISTICS - Obtain statistics from a period --------------------------------------------------------------- .. index:: get statistics of period .. index:: obtain statistics of period - -**CALLING SEQUENCE:** - .. index:: rtems_rate_monotonic_get_statistics -.. 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 initiated 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. +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 initiated 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 .. _rtems_rate_monotonic_reset_statistics: RATE_MONOTONIC_RESET_STATISTICS - Reset statistics for a period --------------------------------------------------------------- .. index:: reset statistics of period - -**CALLING SEQUENCE:** - .. index:: rtems_rate_monotonic_reset_statistics -.. code-block:: c - - rtems_status_code rtems_rate_monotonic_reset_statistics( - rtems_id id - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_status_code rtems_rate_monotonic_reset_statistics( + rtems_id id + ); -.. list-table:: - :class: rtems-table +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table - * - ``RTEMS_SUCCESSFUL`` - - period initiated successfully - * - ``RTEMS_INVALID_ID`` - - invalid rate monotonic period id + * - ``RTEMS_SUCCESSFUL`` + - period initiated successfully + * - ``RTEMS_INVALID_ID`` + - invalid rate monotonic period id -**DESCRIPTION:** +DESCRIPTION: + This directive resets the statistics information associated with this rate + monotonic period instance. -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. -**NOTES:** +.. raw:: latex -This directive will not cause the running task to be preempted. + \clearpage .. _rtems_rate_monotonic_reset_all_statistics: RATE_MONOTONIC_RESET_ALL_STATISTICS - Reset statistics for all periods ---------------------------------------------------------------------- .. index:: reset statistics of all periods - -**CALLING SEQUENCE:** - .. index:: rtems_rate_monotonic_reset_all_statistics -.. code-block:: c - - void rtems_rate_monotonic_reset_all_statistics(void); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + void rtems_rate_monotonic_reset_all_statistics(void); -NONE +DIRECTIVE STATUS CODES: + NONE -**DESCRIPTION:** +DESCRIPTION: + This directive resets the statistics information associated with all rate + monotonic period instances. -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. -**NOTES:** +.. raw:: latex -This directive will not cause the running task to be preempted. + \clearpage .. _rtems_rate_monotonic_report_statistics: @@ -1052,37 +1051,32 @@ RATE_MONOTONIC_REPORT_STATISTICS - Print period statistics report ----------------------------------------------------------------- .. index:: print period statistics report .. index:: period statistics report - -**CALLING SEQUENCE:** - .. index:: rtems_rate_monotonic_report_statistics -.. code-block:: c - - void rtems_rate_monotonic_report_statistics(void); - -**DIRECTIVE STATUS CODES:** +CALLING SEQUENCE: + .. code-block:: c -NONE + void rtems_rate_monotonic_report_statistics(void); -**DESCRIPTION:** +DIRECTIVE STATUS CODES: + NONE -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. +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 + .. index:: rtems_rate_monotonic_period_statistics - 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 + .. code-block:: c -**NOTES:** + 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 -This directive will not cause the running task to be preempted. +NOTES: + This directive will not cause the running task to be preempted. diff --git a/c-user/region_manager.rst b/c-user/region_manager.rst index 699a3a6..c5491cb 100644 --- a/c-user/region_manager.rst +++ b/c-user/region_manager.rst @@ -224,82 +224,83 @@ 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 + .. _rtems_region_create: REGION_CREATE - Create a region ------------------------------- .. index:: create a region - -**CALLING SEQUENCE:** - -.. index:: rtems_region_create - -.. code-block:: c - - rtems_status_code rtems_region_create( - rtems_name name, - void *starting_address, - intptr_t length, - uint32_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_INVALID_ADDRESS`` - - address not on four byte boundary - * - ``RTEMS_TOO_MANY`` - - too many regions created - * - ``RTEMS_INVALID_SIZE`` - - invalid page size - -**DESCRIPTION:** - -This directive creates a region from a physically contiguous memory space which -starts at starting_address and is length bytes long. Segments allocated from -the region will be a multiple of page_size bytes in length. 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. - -The ``starting_address`` parameter must be aligned on a four byte boundary. -The ``page_size`` parameter must be a multiple of four greater than or equal to -eight. - -**NOTES:** - -This directive will not 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 +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_region_create( + rtems_name name, + void *starting_address, + intptr_t length, + uint32_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_INVALID_ADDRESS`` + - address not on four byte boundary + * - ``RTEMS_TOO_MANY`` + - too many regions created + * - ``RTEMS_INVALID_SIZE`` + - invalid page size + +DESCRIPTION: + This directive creates a region from a physically contiguous memory space + which starts at starting_address and is length bytes long. Segments + allocated from the region will be a multiple of page_size bytes in length. + 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. + + The ``starting_address`` parameter must be aligned on a four byte boundary. + The ``page_size`` parameter must be a multiple of four greater than or + equal to eight. + +NOTES: + This directive will not 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 .. _rtems_region_ident: @@ -307,82 +308,81 @@ REGION_IDENT - Get ID of a region --------------------------------- .. index:: get ID of a region .. index:: obtain ID of a region - -**CALLING SEQUENCE:** - .. index:: rtems_region_ident -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_region_ident( - rtems_name name, - rtems_id *id - ); + rtems_status_code rtems_region_ident( + rtems_name name, + rtems_id *id + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. list-table:: - :class: rtems-table + * - ``RTEMS_SUCCESSFUL`` + - region identified successfully + * - ``RTEMS_INVALID_ADDRESS`` + - ``id`` is NULL + * - ``RTEMS_INVALID_NAME`` + - region name not found - * - ``RTEMS_SUCCESSFUL`` - - region identified successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``id`` is NULL - * - ``RTEMS_INVALID_NAME`` - - region name not found +DESCRIPTION: -**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. -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. -**NOTES:** +.. raw:: latex -This directive will not cause the running task to be preempted. + \clearpage .. _rtems_region_delete: REGION_DELETE - Delete a region ------------------------------- .. index:: delete a region - -**CALLING SEQUENCE:** - .. index:: rtems_region_delete -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_region_delete( - rtems_id id - ); + rtems_status_code rtems_region_delete( + rtems_id id + ); -**DIRECTIVE STATUS CODES:** - -.. list-table:: - :class: rtems-table +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 + * - ``RTEMS_SUCCESSFUL`` + - region deleted successfully + * - ``RTEMS_INVALID_ID`` + - invalid region id + * - ``RTEMS_RESOURCE_IN_USE`` + - segments still in use -**DESCRIPTION:** +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. -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 not cause the calling task to be preempted. -**NOTES:** + 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. -This directive will not cause the calling task to be preempted. +.. raw:: latex -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. + \clearpage .. _rtems_region_extend: @@ -390,266 +390,260 @@ REGION_EXTEND - Add memory to a region -------------------------------------- .. index:: add memory to a region .. index:: region, add memory - -**CALLING SEQUENCE:** - .. index:: rtems_region_extend -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_region_extend( - rtems_id id, - void *starting_address, - intptr_t length - ); + rtems_status_code rtems_region_extend( + rtems_id id, + void *starting_address, + intptr_t length + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. 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 - * - ``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 which starts at starting_address for length + bytes to the region specified by id. -**DESCRIPTION:** +NOTES: + This directive will not cause the calling task to be preempted. -This directive adds the memory which starts at starting_address for length -bytes to the region specified by id. + The calling task does not have to be the task that created the region. Any + local task that knows the region id can extend the region. -**NOTES:** +.. raw:: latex -This directive will not 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 extend the region. + \clearpage .. _rtems_region_get_segment: REGION_GET_SEGMENT - Get segment from a region ---------------------------------------------- .. index:: get segment from region - -**CALLING SEQUENCE:** - .. index:: rtems_region_get_segment -.. code-block:: c - - rtems_status_code rtems_region_get_segment( - rtems_id id, - intptr_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:** - -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. +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_region_get_segment( + rtems_id id, + intptr_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: + 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 .. _rtems_region_return_segment: REGION_RETURN_SEGMENT - Return segment to a region -------------------------------------------------- .. index:: return segment to region - -**CALLING SEQUENCE:** - .. index:: rtems_region_return_segment -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_region_return_segment( - rtems_id id, - void *segment - ); + rtems_status_code rtems_region_return_segment( + rtems_id id, + void *segment + ); -**DIRECTIVE STATUS CODES:** - -.. list-table:: - :class: rtems-table +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 + * - ``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:** +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. -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: -**NOTES:** + - a waiting task has a higher priority than the calling task -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: + - the size of the segment required by the waiting task is less than or + equal to the size of the segment returned. -- a waiting task has a higher priority than the calling task +.. raw:: latex -- the size of the segment required by the waiting task is less than or equal to - the size of the segment returned. + \clearpage .. _rtems_region_get_segment_size: REGION_GET_SEGMENT_SIZE - Obtain size of a segment -------------------------------------------------- .. index:: get size of segment - -**CALLING SEQUENCE:** - .. index:: rtems_region_get_segment_size -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_region_get_segment_size( - rtems_id id, - void *segment, - ssize_t *size - ); + rtems_status_code rtems_region_get_segment_size( + rtems_id id, + void *segment, + ssize_t *size + ); -**DIRECTIVE STATUS CODES:** - -.. list-table:: - :class: rtems-table +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 + * - ``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:** +DESCRIPTION: + This directive obtains the size in bytes of the specified segment. -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. -**NOTES:** +.. raw:: latex -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. + \clearpage .. _rtems_region_resize_segment: REGION_RESIZE_SEGMENT - Change size of a segment ------------------------------------------------ .. index:: resize segment - -**CALLING SEQUENCE:** - .. index:: rtems_region_resize_segment -.. code-block:: c - - rtems_status_code rtems_region_resize_segment( - rtems_id id, - void *segment, - ssize_t size, - ssize_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:** - -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. +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_region_resize_segment( + rtems_id id, + void *segment, + ssize_t size, + ssize_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: + 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. diff --git a/c-user/rtems_data_types.rst b/c-user/rtems_data_types.rst index 015901d..da23448 100644 --- a/c-user/rtems_data_types.rst +++ b/c-user/rtems_data_types.rst @@ -37,7 +37,7 @@ alphabetical order: ``rtems_asr_entry`` The address of the entry point to an RTEMS ASR. - .. index:: rtems_attribute +.. index:: rtems_attribute ``rtems_attribute`` The data type used to manage the attributes for RTEMS objects. It is diff --git a/c-user/semaphore_manager.rst b/c-user/semaphore_manager.rst index b328e00..13b5ff3 100644 --- a/c-user/semaphore_manager.rst +++ b/c-user/semaphore_manager.rst @@ -395,118 +395,121 @@ 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 + .. _rtems_semaphore_create: SEMAPHORE_CREATE - Create a semaphore ------------------------------------- .. index:: create a semaphore - -**CALLING SEQUENCE:** - .. index:: rtems_semaphore_create -.. 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 that some combinations of attributes are not valid. See the earlier -discussion on this. +CALLING SEQUENCE: + .. code-block:: c -The total number of global objects, including semaphores, is limited by the -maximum_global_objects field in the Configuration Table. + rtems_status_code rtems_semaphore_create( + rtems_name name, + uint32_t count, + rtems_attribute attribute_set, + rtems_task_priority priority_ceiling, + rtems_id *id + ); -It is not allowed to create an initially locked MrsP semaphore and the -``RTEMS_INVALID_NUMBER`` status code will be returned on SMP configurations in -this case. This prevents lock order reversal problems with the allocator -mutex. +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 on SMP configurations + in this case. This prevents lock order reversal problems with the + allocator mutex. + +.. raw:: latex + + \clearpage .. _rtems_semaphore_ident: @@ -515,108 +518,107 @@ SEMAPHORE_IDENT - Get ID of a semaphore .. index:: get ID of a semaphore .. index:: obtain ID of a semaphore -**CALLING SEQUENCE:** - .. index:: rtems_semaphore_ident -.. code-block:: c - - rtems_status_code rtems_semaphore_ident( - rtems_name name, - uint32_t node, - rtems_id *id - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_status_code rtems_semaphore_ident( + rtems_name name, + uint32_t node, + rtems_id *id + ); -.. list-table:: - :class: rtems-table +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 + * - ``RTEMS_SUCCESSFUL`` + - semaphore identified successfully + * - ``RTEMS_INVALID_NAME`` + - semaphore name not found + * - ``RTEMS_INVALID_NODE`` + - invalid node id -**DESCRIPTION:** +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. -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. -**NOTES:** + 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. -This directive will not cause the running task to be preempted. + 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. -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. + This directive does not generate activity on remote nodes. It accesses + only the local copy of the global object table. -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. +.. raw:: latex -This directive does not generate activity on remote nodes. It accesses only -the local copy of the global object table. + \clearpage .. _rtems_semaphore_delete: SEMAPHORE_DELETE - Delete a semaphore ------------------------------------- .. index:: delete a semaphore - -**CALLING SEQUENCE:** - .. index:: rtems_semaphore_delete -.. code-block:: c - - rtems_status_code rtems_semaphore_delete( - rtems_id id - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_status_code rtems_semaphore_delete( + rtems_id id + ); -.. list-table:: - :class: rtems-table +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 + * - ``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:** +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. -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. -**NOTES:** + 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. -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. + 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 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. + The semaphore must reside on the local node, even if the semaphore was + created with the ``RTEMS_GLOBAL`` option. -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. + Proxies, used to represent remote tasks, are reclaimed when the semaphore + is deleted. -The semaphore must reside on the local node, even if the semaphore was created -with the ``RTEMS_GLOBAL`` option. +.. raw:: latex -Proxies, used to represent remote tasks, are reclaimed when the semaphore is -deleted. + \clearpage .. _rtems_semaphore_obtain: @@ -624,96 +626,98 @@ SEMAPHORE_OBTAIN - Acquire a semaphore -------------------------------------- .. index:: obtain a semaphore .. index:: lock a semaphore - -**CALLING SEQUENCE:** - .. index:: rtems_semaphore_obtain -.. 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. - -Deadlock situations are detected for MrsP semaphores and the -``RTEMS_UNSATISFIED`` status code will be returned on 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 +CALLING SEQUENCE: + .. code-block:: c -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. + rtems_status_code rtems_semaphore_obtain( + rtems_id id, + rtems_option option_set, + rtems_interval timeout + ); -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 -on SMP configurations in this case. +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. + + Deadlock situations are detected for MrsP semaphores and the + ``RTEMS_UNSATISFIED`` status code will be returned on 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 on SMP configurations in this case. + +.. raw:: latex + + \clearpage .. _rtems_semaphore_release: @@ -721,59 +725,60 @@ SEMAPHORE_RELEASE - Release a semaphore --------------------------------------- .. index:: release a semaphore .. index:: unlock a semaphore - -**CALLING SEQUENCE:** - .. index:: rtems_semaphore_release -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_semaphore_release( - rtems_id id - ); + rtems_status_code rtems_semaphore_release( + rtems_id id + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. 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 + * - ``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:** +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. -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. -**NOTES:** + Releasing a global semaphore which does not reside on the local node will + generate a request telling the remote node to release the semaphore. -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 semaphore allocation is forwarded to the appropriate node, the + waiting task is unblocked, and the proxy used to represent the task is + reclaimed. -Releasing a global semaphore which does not reside on the local node will -generate a request telling the remote node to release the semaphore. + 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. -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 MrsP semaphores must be released in the reversed obtain order, + otherwise the ``RTEMS_INCORRECT_STATE`` status code will be returned on SMP + configurations in this case. -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. +.. raw:: latex -The MrsP semaphores must be released in the reversed obtain order, otherwise -the ``RTEMS_INCORRECT_STATE`` status code will be returned on SMP -configurations in this case. + \clearpage .. _rtems_semaphore_flush: @@ -781,198 +786,193 @@ SEMAPHORE_FLUSH - Unblock all tasks waiting on a semaphore ---------------------------------------------------------- .. index:: flush a semaphore .. index:: unblock all tasks waiting on a semaphore - -**CALLING SEQUENCE:** - .. index:: rtems_semaphore_flush -.. code-block:: c - - rtems_status_code rtems_semaphore_flush( - rtems_id id - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_status_code rtems_semaphore_flush( + rtems_id id + ); -.. list-table:: - :class: rtems-table +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 ofthe semaphore - * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - - not supported for remote semaphores + * - ``RTEMS_SUCCESSFUL`` + - semaphore released successfully + * - ``RTEMS_INVALID_ID`` + - invalid semaphore id + * - ``RTEMS_NOT_DEFINED`` + - operation not defined for the protocol ofthe semaphore + * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` + - not supported for remote semaphores -**DESCRIPTION:** +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 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. -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. -**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. -The calling task may be preempted if it causes a higher priority task to be -made ready for execution. + It is not allowed to flush a MrsP semaphore and the ``RTEMS_NOT_DEFINED`` + status code will be returned on SMP configurations in this case. -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. +.. raw:: latex -It is not allowed to flush a MrsP semaphore and the ``RTEMS_NOT_DEFINED`` -status code will be returned on SMP configurations in this case. + \clearpage .. _rtems_semaphore_set_priority: SEMAPHORE_SET_PRIORITY - Set priority by scheduler for a semaphore ------------------------------------------------------------------ .. index:: set priority by scheduler for a semaphore - -**CALLING SEQUENCE:** - .. index:: rtems_semaphore_set_priority -.. 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 - ); +CALLING SEQUENCE: + .. code-block:: c -**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 + 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 ); - 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_SMP_APPLICATION - #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_MRSP_SEMAPHORES 1 - #define CONFIGURE_SMP_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_CONTROLS \ - RTEMS_SCHEDULER_CONTROL_SIMPLE_SMP(a, SCHED_A), \ - RTEMS_SCHEDULER_CONTROL_SIMPLE_SMP(b, SCHED_B) - #define CONFIGURE_SMP_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> + +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_SMP_APPLICATION + #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_MRSP_SEMAPHORES 1 + #define CONFIGURE_SMP_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_CONTROLS \ + RTEMS_SCHEDULER_CONTROL_SIMPLE_SMP(a, SCHED_A), \ + RTEMS_SCHEDULER_CONTROL_SIMPLE_SMP(b, SCHED_B) + #define CONFIGURE_SMP_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_manager.rst b/c-user/signal_manager.rst index e9c1d6e..d6b253d 100644 --- a/c-user/signal_manager.rst +++ b/c-user/signal_manager.rst @@ -203,117 +203,116 @@ 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 + .. _rtems_signal_catch: SIGNAL_CATCH - Establish an ASR ------------------------------- .. index:: establish an ASR .. index:: install an ASR - -**CALLING SEQUENCE:** - .. index:: rtems_signal_catch -.. 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 +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 .. _rtems_signal_send: SIGNAL_SEND - Send signal set to a task --------------------------------------- .. index:: send signal set - -**CALLING SEQUENCE:** - .. index:: rtems_signal_send -.. 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. +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/stack_bounds_checker.rst b/c-user/stack_bounds_checker.rst index 0ce5a44..87c16f5 100644 --- a/c-user/stack_bounds_checker.rst +++ b/c-user/stack_bounds_checker.rst @@ -157,54 +157,46 @@ constants, usage, and status codes. STACK_CHECKER_IS_BLOWN - Has Current Task Blown Its Stack --------------------------------------------------------- -**CALLING SEQUENCE:** +CALLING SEQUENCE: + .. code-block:: c -.. code-block:: c - - bool rtems_stack_checker_is_blown( void ); - -**STATUS CODES:** - -.. list-table:: - :class: rtems-table - - * - ``TRUE`` - - Stack is operating within its stack limits - * - ``FALSE`` - - Current stack pointer is outside allocated area + bool rtems_stack_checker_is_blown( void ); -**DESCRIPTION:** +STATUS CODES: + .. list-table:: + :class: rtems-table -This method is used to determine if the current stack pointer of the currently -executing task is within bounds. + * - ``TRUE`` + - Stack is operating within its stack limits + * - ``FALSE`` + - Current stack pointer is outside allocated area -**NOTES:** +DESCRIPTION: + This method is used to determine if the current stack pointer of the + currently executing task is within bounds. -This method checks the current stack pointer against the high and low addresses -of the stack memory allocated when the task was created and it looks for damage -to the high water mark pattern for the worst case usage of the task being -called. +NOTES: + This method checks the current stack pointer against the high and low + addresses of the stack memory allocated when the task was created and it + looks for damage to the high water mark pattern for the worst case usage of + the task being called. .. _rtems_stack_checker_report_usage: STACK_CHECKER_REPORT_USAGE - Report Task Stack Usage ---------------------------------------------------- -**CALLING SEQUENCE:** - -.. code-block:: c - - void rtems_stack_checker_report_usage( void ); - -**STATUS CODES:** - -NONE +CALLING SEQUENCE: + .. code-block:: c -**DESCRIPTION:** + void rtems_stack_checker_report_usage( void ); -This routine prints a table with the peak stack usage and stack space -allocation of every task in the system. +STATUS CODES: + NONE -**NOTES:** +DESCRIPTION: + This routine prints a table with the peak stack usage and stack space + allocation of every task in the system. -NONE +NOTES: + NONE diff --git a/c-user/symmetric_multiprocessing_services.rst b/c-user/symmetric_multiprocessing_services.rst index ac9cb6b..4c72861 100644 --- a/c-user/symmetric_multiprocessing_services.rst +++ b/c-user/symmetric_multiprocessing_services.rst @@ -656,180 +656,184 @@ This section details the symmetric multiprocessing services. A subsection is dedicated to each of these services and describes the calling sequence, related constants, usage, and status codes. +.. raw:: latex + + \clearpage + .. _rtems_get_processor_count: GET_PROCESSOR_COUNT - Get processor count ----------------------------------------- -**CALLING SEQUENCE:** - -.. code-block:: c - - uint32_t rtems_get_processor_count(void); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + uint32_t rtems_get_processor_count(void); -The count of processors in the system. +DIRECTIVE STATUS CODES: + The count of processors in the system. -**DESCRIPTION:** +DESCRIPTION: + On uni-processor configurations a value of one will be returned. -On uni-processor configurations a value of one will be returned. + On SMP configurations this returns the value of a global variable set + during system initialization to indicate the count of utilized processors. + The processor count depends on the physically or virtually available + processors and application configuration. The value will always be less + than or equal to the maximum count of application configured processors. -On SMP configurations this returns the value of a global variable set during -system initialization to indicate the count of utilized processors. The -processor count depends on the physically or virtually available processors and -application configuration. The value will always be less than or equal to the -maximum count of application configured processors. +NOTES: + None. -**NOTES:** +.. raw:: latex -None. + \clearpage .. _rtems_get_current_processor: GET_CURRENT_PROCESSOR - Get current processor index --------------------------------------------------- -**CALLING SEQUENCE:** +CALLING SEQUENCE: + .. code-block:: c -.. code-block:: c - - uint32_t rtems_get_current_processor(void); - -**DIRECTIVE STATUS CODES:** + uint32_t rtems_get_current_processor(void); -The index of the current processor. +DIRECTIVE STATUS CODES: + The index of the current processor. -**DESCRIPTION:** +DESCRIPTION: + On uni-processor configurations a value of zero will be returned. -On uni-processor configurations a value of zero will be returned. + On 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. -On 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. -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. -**NOTES:** +.. raw:: latex -None. + \clearpage .. _rtems_scheduler_ident: -.. _SCHEDULER_IDENT - Get ID of a scheduler: SCHEDULER_IDENT - Get ID of a scheduler --------------------------------------- -**CALLING SEQUENCE:** - -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_scheduler_ident( - rtems_name name, - rtems_id *id - ); + rtems_status_code rtems_scheduler_ident( + rtems_name name, + rtems_id *id + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. list-table:: - :class: rtems-table + * - ``RTEMS_SUCCESSFUL`` + - successful operation + * - ``RTEMS_INVALID_ADDRESS`` + - ``id`` is NULL + * - ``RTEMS_INVALID_NAME`` + - invalid scheduler name + * - ``RTEMS_UNSATISFIED`` + - a scheduler with this name exists, but the processor set of this scheduler + is empty - * - ``RTEMS_SUCCESSFUL`` - - successful operation - * - ``RTEMS_INVALID_ADDRESS`` - - ``id`` is NULL - * - ``RTEMS_INVALID_NAME`` - - invalid scheduler name - * - ``RTEMS_UNSATISFIED`` - - a scheduler with this name exists, but the processor set of this scheduler - is empty +DESCRIPTION: + Identifies a scheduler by its name. The scheduler name is determined by + the scheduler configuration. See :ref:`Configuring a System`. -**DESCRIPTION:** +NOTES: + None. -Identifies a scheduler by its name. The scheduler name is determined by the -scheduler configuration. See :ref:`Configuring a System`. +.. raw:: latex -**NOTES:** - -None. + \clearpage .. _rtems_scheduler_get_processor_set: SCHEDULER_GET_PROCESSOR_SET - Get processor set of a scheduler -------------------------------------------------------------- -**CALLING SEQUENCE:** - -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_scheduler_get_processor_set( - rtems_id scheduler_id, - size_t cpusetsize, - cpu_set_t *cpuset - ); + rtems_status_code rtems_scheduler_get_processor_set( + rtems_id scheduler_id, + size_t cpusetsize, + cpu_set_t *cpuset + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. list-table:: - :class: rtems-table + * - ``RTEMS_SUCCESSFUL`` + - successful operation + * - ``RTEMS_INVALID_ADDRESS`` + - ``cpuset`` is NULL + * - ``RTEMS_INVALID_ID`` + - invalid scheduler id + * - ``RTEMS_INVALID_NUMBER`` + - the affinity set buffer is too small for set of processors owned by + the scheduler - * - ``RTEMS_SUCCESSFUL`` - - successful operation - * - ``RTEMS_INVALID_ADDRESS`` - - ``cpuset`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid scheduler id - * - ``RTEMS_INVALID_NUMBER`` - - the affinity set buffer is too small for set of processors owned by the - scheduler +DESCRIPTION: + Returns the processor set owned by the scheduler in ``cpuset``. A set bit + in the processor set means that this processor is owned by the scheduler + and a cleared bit means the opposite. -**DESCRIPTION:** +NOTES: + None. -Returns the processor set owned by the scheduler in ``cpuset``. A set bit in -the processor set means that this processor is owned by the scheduler and a -cleared bit means the opposite. +.. raw:: latex -**NOTES:** - -None. + \clearpage .. _rtems_task_get_scheduler: TASK_GET_SCHEDULER - Get scheduler of a task -------------------------------------------- -**CALLING SEQUENCE:** +CALLING SEQUENCE: + .. code-block:: c -.. code-block:: c + rtems_status_code rtems_task_get_scheduler( + rtems_id task_id, + rtems_id *scheduler_id + ); - rtems_status_code rtems_task_get_scheduler( - rtems_id task_id, - rtems_id *scheduler_id - ); +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -**DIRECTIVE STATUS CODES:** + * - ``RTEMS_SUCCESSFUL`` + - successful operation + * - ``RTEMS_INVALID_ADDRESS`` + - ``scheduler_id`` is NULL + * - ``RTEMS_INVALID_ID`` + - invalid task id -.. list-table:: - :class: rtems-table +DESCRIPTION: + Returns the scheduler identifier of a task identified by ``task_id`` in + ``scheduler_id``. - * - ``RTEMS_SUCCESSFUL`` - - successful operation - * - ``RTEMS_INVALID_ADDRESS`` - - ``scheduler_id`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid task id +NOTES: + None. -**DESCRIPTION:** +.. raw:: latex -Returns the scheduler identifier of a task identified by ``task_id`` in -``scheduler_id``. - -**NOTES:** - -None. + \clearpage .. _rtems_task_set_scheduler: .. _TASK_SET_SCHEDULER - Set scheduler of a task: @@ -837,159 +841,156 @@ None. TASK_SET_SCHEDULER - Set scheduler of a task -------------------------------------------- -**CALLING SEQUENCE:** +CALLING SEQUENCE: + .. code-block:: c -.. code-block:: c + rtems_status_code rtems_task_set_scheduler( + rtems_id task_id, + rtems_id scheduler_id + ); - rtems_status_code rtems_task_set_scheduler( - rtems_id task_id, - rtems_id scheduler_id - ); +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -**DIRECTIVE STATUS CODES:** + * - ``RTEMS_SUCCESSFUL`` + - successful operation + * - ``RTEMS_INVALID_ID`` + - invalid task or scheduler id + * - ``RTEMS_INCORRECT_STATE`` + - the task is in the wrong state to perform a scheduler change -.. list-table:: - :class: rtems-table +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. - * - ``RTEMS_SUCCESSFUL`` - - successful operation - * - ``RTEMS_INVALID_ID`` - - invalid task or scheduler id - * - ``RTEMS_INCORRECT_STATE`` - - the task is in the wrong state to perform a scheduler change +NOTES: + None. -**DESCRIPTION:** +EXAMPLE: + .. code-block:: c + :linenos: -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. + #include <rtems.h> + #include <assert.h> -**NOTES:** + void task(rtems_task_argument arg); -None. + void example(void) + { + rtems_status_code sc; + rtems_id task_id; + rtems_id scheduler_id; + rtems_name scheduler_name; -**EXAMPLE:** + scheduler_name = rtems_build_name('W', 'O', 'R', 'K'); -.. code-block:: c - :linenos: + sc = rtems_scheduler_ident(scheduler_name, &scheduler_id); + assert(sc == RTEMS_SUCCESSFUL); - #include <rtems.h> - #include <assert.h> + 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); - void 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_set_scheduler(task_id, 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_start(task_id, task, 0); + assert(sc == RTEMS_SUCCESSFUL); + } - sc = rtems_task_set_scheduler(task_id, scheduler_id); - assert(sc == RTEMS_SUCCESSFUL); +.. raw:: latex - sc = rtems_task_start(task_id, task, 0); - assert(sc == RTEMS_SUCCESSFUL); - } + \clearpage .. _rtems_task_get_affinity: TASK_GET_AFFINITY - Get task processor affinity ----------------------------------------------- -**CALLING SEQUENCE:** +CALLING SEQUENCE: + .. code-block:: c -.. code-block:: c + rtems_status_code rtems_task_get_affinity( + rtems_id id, + size_t cpusetsize, + cpu_set_t *cpuset + ); - 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 -**DIRECTIVE STATUS CODES:** + * - ``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 -.. list-table:: - :class: rtems-table +DESCRIPTION: - * - ``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 + 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. -**DESCRIPTION:** +NOTES: + None. -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. +.. raw:: latex -**NOTES:** - -None. + \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. +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. diff --git a/c-user/task_manager.rst b/c-user/task_manager.rst index f88e660..beaef3b 100644 --- a/c-user/task_manager.rst +++ b/c-user/task_manager.rst @@ -37,9 +37,9 @@ and administer tasks. The directives provided by the task manager are: - rtems_task_mode_ - Change current task's mode -- rtems_task_get_note_ - Get task notepad entry +- rtems_task_get_note_ - Get task notepad entry -- rtems_task_set_note_ - Set task notepad entry +- rtems_task_set_note_ - Set task notepad entry - rtems_task_wake_after_ - Wake up after interval @@ -590,530 +590,532 @@ 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 + .. _rtems_task_create: TASK_CREATE - Create a task --------------------------- .. index:: create a task - -**CALLING SEQUENCE:** - .. index:: rtems_task_create -.. 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_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 will not cause the calling task to be preempted. - -Valid task priorities range from a high of 1 to a low of 255. - -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. +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_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 will not cause the calling task to be preempted. + + Valid task priorities range from a high of 1 to a low of 255. + + 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 .. _rtems_task_ident: TASK_IDENT - Get ID of a task ----------------------------- .. index:: get ID of a task - -**CALLING SEQUENCE:** - .. index:: rtems_task_ident -.. code-block:: c - - rtems_status_code rtems_task_ident( - rtems_name name, - uint32_t node, - rtems_id *id - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_status_code rtems_task_ident( + rtems_name name, + uint32_t node, + rtems_id *id + ); -.. list-table:: - :class: rtems-table +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 + * - ``RTEMS_SUCCESSFUL`` + - task identified successfully + * - ``RTEMS_INVALID_ADDRESS`` + - ``id`` is NULL + * - ``RTEMS_INVALID_NAME`` + - invalid task name + * - ``RTEMS_INVALID_NODE`` + - invalid node id -**DESCRIPTION:** +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. -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. -**NOTES:** + 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. -This directive will not cause the running task to be preempted. + 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. -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. + This directive does not generate activity on remote nodes. It accesses + only the local copy of the global object table. -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. +.. raw:: latex -This directive does not generate activity on remote nodes. It accesses only -the local copy of the global object table. + \clearpage .. _rtems_task_self: TASK_SELF - Obtain ID of caller ------------------------------- .. index:: obtain ID of caller - -**CALLING SEQUENCE:** - .. index:: rtems_task_self -.. code-block:: c - - rtems_id rtems_task_self(void); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_id rtems_task_self(void); -Returns the object Id of the calling task. +DIRECTIVE STATUS CODES: + Returns the object Id of the calling task. -**DESCRIPTION:** +DESCRIPTION: + This directive returns the Id of the calling task. -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. -**NOTES:** +.. raw:: latex -If called from an interrupt service routine, this directive will return the Id -of the interrupted task. + \clearpage .. _rtems_task_start: TASK_START - Start a task ------------------------- .. index:: starting a task - -**CALLING SEQUENCE:** - .. index:: rtems_task_start -.. 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. +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 .. _rtems_task_restart: TASK_RESTART - Restart a task ----------------------------- .. index:: restarting a task - -**CALLING SEQUENCE:** - .. index:: rtems_task_restart -.. 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. +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 .. _rtems_task_delete: TASK_DELETE - Delete a task --------------------------- .. index:: deleting a task - -**CALLING SEQUENCE:** - .. index:: rtems_task_delete -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_task_delete( - rtems_id id - ); + rtems_status_code rtems_task_delete( + rtems_id id + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. 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 - * - ``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. -**DESCRIPTION:** +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. -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. + Deletion of the current task (``RTEMS_SELF``) will force RTEMS to select + another task to execute. -**NOTES:** + 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. -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. + The task must reside on the local node, even if the task was created with + the ``RTEMS_GLOBAL`` option. -Deletion of the current task (``RTEMS_SELF``) will force RTEMS to select -another task to execute. +.. raw:: latex -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. + \clearpage .. _rtems_task_suspend: TASK_SUSPEND - Suspend a task ----------------------------- .. index:: suspending a task - -**CALLING SEQUENCE:** - .. index:: rtems_task_suspend -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_task_suspend( - rtems_id id - ); + rtems_status_code rtems_task_suspend( + rtems_id id + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. list-table:: - :class: rtems-table + * - ``RTEMS_SUCCESSFUL`` + - task suspended successfully + * - ``RTEMS_INVALID_ID`` + - task id invalid + * - ``RTEMS_ALREADY_SUSPENDED`` + - task already suspended - * - ``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. -**DESCRIPTION:** +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. -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. + 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. -**NOTES:** + If the task specified by id is already suspended, then the + ``RTEMS_ALREADY_SUSPENDED`` status code is returned. -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. +.. raw:: latex -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. + \clearpage .. _rtems_task_resume: TASK_RESUME - Resume a task --------------------------- .. index:: resuming a task - -**CALLING SEQUENCE:** - .. index:: rtems_task_resume -.. code-block:: c - - rtems_status_code rtems_task_resume( - rtems_id id - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_status_code rtems_task_resume( + rtems_id id + ); -.. list-table:: - :class: rtems-table +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 + * - ``RTEMS_SUCCESSFUL`` + - task resumed successfully + * - ``RTEMS_INVALID_ID`` + - task id invalid + * - ``RTEMS_INCORRECT_STATE`` + - task not suspended -**DESCRIPTION:** +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. -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. -**NOTES:** + 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. -The running task may be preempted if its preemption mode is enabled and the -local task being resumed has a higher priority. + If the task specified by id is not suspended, then the + ``RTEMS_INCORRECT_STATE`` status code is returned. -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. +.. raw:: latex -If the task specified by id is not suspended, then the -``RTEMS_INCORRECT_STATE`` status code is returned. + \clearpage .. _rtems_task_is_suspended: TASK_IS_SUSPENDED - Determine if a task is Suspended ---------------------------------------------------- .. index:: is task suspended - -**CALLING SEQUENCE:** - .. index:: rtems_task_is_suspended -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_task_is_suspended( - rtems_id id - ); + rtems_status_code rtems_task_is_suspended( + rtems_id id + ); -**DIRECTIVE STATUS CODES:** - -.. list-table:: - :class: rtems-table +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 + * - ``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:** +DESCRIPTION: + This directive returns a status code indicating whether or not the + specified task is currently suspended. -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. -**NOTES:** +.. raw:: latex -This operation is not currently supported on remote tasks. + \clearpage .. _rtems_task_set_priority: @@ -1125,58 +1127,59 @@ TASK_SET_PRIORITY - Set task priority .. index:: get task priority .. index:: obtain 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. +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 .. _rtems_task_mode: @@ -1188,172 +1191,171 @@ TASK_MODE - Change the current task mode .. index:: set task preemption mode .. index:: get task preemption mode .. index:: obtain task mode - -**CALLING SEQUENCE:** - .. index:: rtems_task_mode -.. 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 - -**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 +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 + +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 .. _rtems_task_get_note: TASK_GET_NOTE - Get task notepad entry -------------------------------------- .. index:: get task notepad entry - -**CALLING SEQUENCE:** - .. index:: rtems_task_get_note -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_task_get_note( - rtems_id id, - uint32_t notepad, - uint32_t *note - ); + rtems_status_code rtems_task_get_note( + rtems_id id, + uint32_t notepad, + uint32_t *note + ); -**DIRECTIVE STATUS CODES:** - -.. list-table:: - :class: rtems-table +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 + * - ``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:** +DESCRIPTION: + This directive returns the note contained in the notepad location of the + task specified by id. -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. -**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``. -If id is set to ``RTEMS_SELF``, the calling task accesses its own notepad. + 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. -The sixteen notepad locations can be accessed using the constants -``RTEMS_NOTEPAD_0`` through ``RTEMS_NOTEPAD_15``. +.. raw:: latex -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. + \clearpage .. _rtems_task_set_note: TASK_SET_NOTE - Set task notepad entry -------------------------------------- .. index:: set task notepad entry - -**CALLING SEQUENCE:** - .. index:: rtems_task_set_note -.. code-block:: c - - rtems_status_code rtems_task_set_note( - rtems_id id, - uint32_t notepad, - uint32_t note - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_status_code rtems_task_set_note( + rtems_id id, + uint32_t notepad, + uint32_t note + ); -.. list-table:: - :class: rtems-table +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 + * - ``RTEMS_SUCCESSFUL`` + - note set successfully + * - ``RTEMS_INVALID_ID`` + - invalid task id + * - ``RTEMS_INVALID_NUMBER`` + - invalid notepad location -**DESCRIPTION:** +DESCRIPTION: + This directive sets the notepad entry for the task specified by id to the + value note. -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. -**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``. -This directive will not cause the running task to be preempted. + 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. -The sixteen notepad locations can be accessed using the constants -``RTEMS_NOTEPAD_0`` through ``RTEMS_NOTEPAD_15``. +.. raw:: latex -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. + \clearpage .. _rtems_task_wake_after: @@ -1361,43 +1363,42 @@ TASK_WAKE_AFTER - Wake up after interval ---------------------------------------- .. index:: delay a task for an interval .. index:: wake up after an interval - -**CALLING SEQUENCE:** - .. index:: rtems_task_wake_after -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_task_wake_after( - rtems_interval ticks - ); + rtems_status_code rtems_task_wake_after( + rtems_interval ticks + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - always successful + * - ``RTEMS_SUCCESSFUL`` + - always successful -**DESCRIPTION:** +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. -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. -**NOTES:** + A task may give up the processor and remain in the ready state by + specifying a value of ``RTEMS_YIELD_PROCESSOR`` in ticks. -Setting the system date and time with the ``rtems_clock_set`` directive has no -effect on a ``rtems_task_wake_after`` blocked task. + The maximum timer interval that can be specified is the maximum value which + can be represented by the uint32_t type. -A task may give up the processor and remain in the ready state by specifying a -value of ``RTEMS_YIELD_PROCESSOR`` in ticks. + A clock tick is required to support the functionality of this directive. -The maximum timer interval that can be specified is the maximum value which can -be represented by the uint32_t type. +.. raw:: latex -A clock tick is required to support the functionality of this directive. + \clearpage .. _rtems_task_wake_when: @@ -1405,80 +1406,78 @@ TASK_WAKE_WHEN - Wake up when specified --------------------------------------- .. index:: delay a task until a wall time .. index:: wake up at a wall time - -**CALLING SEQUENCE:** - .. index:: rtems_task_wake_when -.. code-block:: c - - rtems_status_code rtems_task_wake_when( - rtems_time_of_day *time_buffer - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_status_code rtems_task_wake_when( + rtems_time_of_day *time_buffer + ); -.. list-table:: - :class: rtems-table +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 + * - ``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:** +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. -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. -**NOTES:** + A clock tick is required to support the functionality of this directive. -The ticks portion of time_buffer structure is ignored. The timing granularity -of this directive is a second. +.. raw:: latex -A clock tick is required to support the functionality of this directive. + \clearpage .. _rtems_iterate_over_all_threads: ITERATE_OVER_ALL_THREADS - Iterate Over Tasks --------------------------------------------- .. index:: iterate over all threads - -**CALLING SEQUENCE:** - .. index:: rtems_iterate_over_all_threads -.. code-block:: c - - typedef void (*rtems_per_thread_routine)(Thread_Control *the_thread); - void rtems_iterate_over_all_threads( - rtems_per_thread_routine routine - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + typedef void (*rtems_per_thread_routine)(Thread_Control *the_thread); + void rtems_iterate_over_all_threads( + rtems_per_thread_routine routine + ); -NONE +DIRECTIVE STATUS CODES: + NONE -**DESCRIPTION:** +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 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. -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. Thus it is possible + that ``the_thread`` could be deleted while this is operating. By not + having protection, the user is free to invoke support routines from the C + Library which require semaphores for data structures. -**NOTES:** +.. raw:: latex -There is NO protection while this routine is called. Thus it is possible that -``the_thread`` could be deleted while this is operating. By not having -protection, the user is free to invoke support routines from the C Library -which require semaphores for data structures. + \clearpage .. _rtems_task_variable_add: @@ -1487,61 +1486,61 @@ TASK_VARIABLE_ADD - Associate per task variable .. index:: per-task variable .. index:: task private variable .. index:: task private data +.. index:: rtems_task_variable_add .. warning:: This directive is deprecated and task variables will be removed. -**CALLING SEQUENCE:** - -.. index:: rtems_task_variable_add - -.. 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. +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 .. _rtems_task_variable_get: @@ -1549,57 +1548,56 @@ TASK_VARIABLE_GET - Obtain value of a per task variable ------------------------------------------------------- .. index:: get per-task variable .. index:: obtain per-task variable +.. index:: rtems_task_variable_get .. warning:: This directive is deprecated and task variables will be removed. -**CALLING SEQUENCE:** - -.. index:: rtems_task_variable_get - -.. 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. +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 .. _rtems_task_variable_delete: @@ -1608,43 +1606,38 @@ TASK_VARIABLE_DELETE - Remove per task variable .. index:: per-task variable .. index:: task private variable .. index:: task private data +.. index:: rtems_task_variable_delete .. warning:: This directive is deprecated and task variables will be removed. -**CALLING SEQUENCE:** - -.. index:: rtems_task_variable_delete - -.. 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. +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_manager.rst b/c-user/timer_manager.rst index 088c1b3..d9ffd92 100644 --- a/c-user/timer_manager.rst +++ b/c-user/timer_manager.rst @@ -189,446 +189,439 @@ 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 .. _rtems_timer_create: TIMER_CREATE - Create a timer ----------------------------- .. index:: create a timer - -**CALLING SEQUENCE:** - .. index:: rtems_timer_create -.. code-block:: c - - rtems_status_code rtems_timer_create( - rtems_name name, - rtems_id *id - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_status_code rtems_timer_create( + rtems_name name, + rtems_id *id + ); -.. list-table:: - :class: rtems-table +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 + * - ``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:** +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. -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 not cause the calling task to be preempted. -**NOTES:** +.. raw:: latex -This directive will not cause the calling task to be preempted. + \clearpage .. _rtems_timer_ident: TIMER_IDENT - Get ID of a timer ------------------------------- .. index:: obtain the ID of a timer - -**CALLING SEQUENCE:** - .. index:: rtems_timer_ident -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_timer_ident( - rtems_name name, - rtems_id *id - ); + rtems_status_code rtems_timer_ident( + rtems_name name, + rtems_id *id + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. list-table:: - :class: rtems-table + * - ``RTEMS_SUCCESSFUL`` + - timer identified successfully + * - ``RTEMS_INVALID_ADDRESS`` + - ``id`` is NULL + * - ``RTEMS_INVALID_NAME`` + - timer name not found - * - ``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. -**DESCRIPTION:** +NOTES: + This directive will not cause the running task to be preempted. -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. +.. raw:: latex -**NOTES:** - -This directive will not cause the running task to be preempted. + \clearpage .. _rtems_timer_cancel: TIMER_CANCEL - Cancel a timer ----------------------------- .. index:: cancel a timer - -**CALLING SEQUENCE:** - .. index:: rtems_timer_cancel -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_timer_cancel( - rtems_id id - ); + rtems_status_code rtems_timer_cancel( + rtems_id id + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. list-table:: - :class: rtems-table + * - ``RTEMS_SUCCESSFUL`` + - timer canceled successfully + * - ``RTEMS_INVALID_ID`` + - invalid timer id - * - ``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. -**DESCRIPTION:** +NOTES: + This directive will not cause the running task to be preempted. -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. +.. raw:: latex -**NOTES:** - -This directive will not cause the running task to be preempted. + \clearpage .. _rtems_timer_delete: TIMER_DELETE - Delete a timer ----------------------------- .. index:: delete a timer - -**CALLING SEQUENCE:** - .. index:: rtems_timer_delete -.. code-block:: c - - rtems_status_code rtems_timer_delete( - rtems_id id - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_status_code rtems_timer_delete( + rtems_id id + ); -.. list-table:: - :class: rtems-table +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table - * - ``RTEMS_SUCCESSFUL`` - - timer deleted successfully - * - ``RTEMS_INVALID_ID`` - - invalid timer id + * - ``RTEMS_SUCCESSFUL`` + - timer deleted successfully + * - ``RTEMS_INVALID_ID`` + - invalid timer id -**DESCRIPTION:** +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. -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 not cause the running task to be preempted. -**NOTES:** + A timer can be deleted by a task other than the task which created the + timer. -This directive will not cause the running task to be preempted. +.. raw:: latex -A timer can be deleted by a task other than the task which created the timer. + \clearpage .. _rtems_timer_fire_after: TIMER_FIRE_AFTER - Fire timer after interval -------------------------------------------- .. index:: fire a timer after an interval - -**CALLING SEQUENCE:** - .. index:: rtems_timer_fire_after -.. 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 - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_status_code rtems_timer_fire_after( + rtems_id id, + rtems_interval ticks, + rtems_timer_service_routine_entry routine, + void *user_data + ); -.. list-table:: - :class: rtems-table +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_SUCCESSFUL`` + - timer initiated successfully + * - ``RTEMS_INVALID_ADDRESS`` + - ``routine`` is NULL + * - ``RTEMS_INVALID_ID`` + - invalid timer id + * - ``RTEMS_INVALID_NUMBER`` + - invalid interval -**DESCRIPTION:** +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. -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. -**NOTES:** +.. raw:: latex -This directive will not cause the running task to be preempted. + \clearpage .. _rtems_timer_fire_when: TIMER_FIRE_WHEN - Fire timer when specified ------------------------------------------- .. index:: fire a timer at wall time - -**CALLING SEQUENCE:** - .. index:: rtems_timer_fire_when -.. 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. +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 .. _rtems_timer_initiate_server: TIMER_INITIATE_SERVER - Initiate server for task-based timers ------------------------------------------------------------- .. index:: initiate the Timer Server - -**CALLING SEQUENCE:** - .. index:: rtems_timer_initiate_server -.. code-block:: c - - rtems_status_code rtems_timer_initiate_server( - uint32_t priority, - uint32_t stack_size, - rtems_attribute attribute_set - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_status_code rtems_timer_initiate_server( + uint32_t priority, + uint32_t stack_size, + rtems_attribute attribute_set + ); -.. list-table:: - :class: rtems-table +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table - * - ``RTEMS_SUCCESSFUL`` - - Timer Server initiated successfully - * - ``RTEMS_TOO_MANY`` - - too many tasks created + * - ``RTEMS_SUCCESSFUL`` + - Timer Server initiated successfully + * - ``RTEMS_TOO_MANY`` + - too many tasks created -**DESCRIPTION:** +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. -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. -**NOTES:** + The Timer Server task is created using the ``rtems_task_create`` service + and must be accounted for when configuring the system. -This directive could cause the calling task to be preempted. + Even through this directive invokes the ``rtems_task_create`` and + ``rtems_task_start`` directives, it should only fail due to resource + allocation problems. -The Timer Server task is created using the ``rtems_task_create`` service and -must be accounted for when configuring the system. +.. raw:: latex -Even through this directive invokes the ``rtems_task_create`` and -``rtems_task_start`` directives, it should only fail due to resource allocation -problems. + \clearpage .. _rtems_timer_server_fire_after: TIMER_SERVER_FIRE_AFTER - Fire task-based timer after interval -------------------------------------------------------------- .. index:: fire task-based a timer after an interval - -**CALLING SEQUENCE:** - .. index:: rtems_timer_server_fire_after -.. 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 - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_status_code rtems_timer_server_fire_after( + rtems_id id, + rtems_interval ticks, + rtems_timer_service_routine_entry routine, + void *user_data + ); -.. list-table:: - :class: rtems-table +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 + * - ``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:** +DESCRIPTION: + This directive initiates the timer specified by id and specifies that when + it fires it will be executed by the Timer Server. -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. -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. -**NOTES:** +.. raw:: latex -This directive will not cause the running task to be preempted. + \clearpage .. _rtems_timer_server_fire_when: TIMER_SERVER_FIRE_WHEN - Fire task-based timer when specified ------------------------------------------------------------- .. index:: fire a task-based timer at wall time - -**CALLING SEQUENCE:** - .. index:: rtems_timer_server_fire_when -.. 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. +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 .. _rtems_timer_reset: TIMER_RESET - Reset an interval timer ------------------------------------- .. index:: reset a timer - -**CALLING SEQUENCE:** - .. index:: rtems_timer_reset -.. 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. +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 b24a63d..c818651 100644 --- a/c-user/timespec_helpers.rst +++ b/c-user/timespec_helpers.rst @@ -119,430 +119,420 @@ This section details the Timespec Helpers 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_timespec_set: TIMESPEC_SET - Set struct timespec Instance ------------------------------------------- .. index:: set struct timespec instance - -**CALLING SEQUENCE:** - .. index:: rtems_timespec_set -.. code-block:: c - - void rtems_timespec_set( - struct timespec *time, - time_t seconds, - uint32_t nanoseconds - ); +CALLING SEQUENCE: + .. code-block:: c -**STATUS CODES:** + void rtems_timespec_set( + struct timespec *time, + time_t seconds, + uint32_t nanoseconds + ); -NONE +DIRECTIVE STATUS CODES: + NONE -**DESCRIPTION:** +DESCRIPTION: + This directive sets the ``struct timespec`` *time* to the desired + ``seconds`` and ``nanoseconds`` values. -This directive sets the ``struct timespec`` *time* to the desired ``seconds`` -and ``nanoseconds`` values. +NOTES: + This method does NOT check if ``nanoseconds`` is less than the maximum + number of nanoseconds in a second. -**NOTES:** +.. raw:: latex -This method does NOT check if ``nanoseconds`` is less than the maximum number -of nanoseconds in a second. + \clearpage .. _rtems_timespec_zero: TIMESPEC_ZERO - Zero struct timespec Instance --------------------------------------------- - -**CALLING SEQUENCE:** - .. index:: rtems_timespec_zero -.. code-block:: c - - void rtems_timespec_zero( - struct timespec *time - ); +CALLING SEQUENCE: + .. code-block:: c -**STATUS CODES:** + void rtems_timespec_zero( + struct timespec *time + ); -NONE +DIRECTIVE STATUS CODES: + NONE -**DESCRIPTION:** +DESCRIPTION: + This routine sets the contents of the ``struct timespec`` instance ``time`` to + zero. -This routine sets the contents of the ``struct timespec`` instance ``time`` to -zero. +NOTES: + NONE -**NOTES:** +.. raw:: latex -NONE + \clearpage .. _rtems_timespec_is_valid: TIMESPEC_IS_VALID - Check validity of a struct timespec instance ---------------------------------------------------------------- - -**CALLING SEQUENCE:** - .. index:: rtems_timespec_is_valid -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - bool rtems_timespec_is_valid( - const struct timespec *time - ); + bool rtems_timespec_is_valid( + const struct timespec *time + ); -**STATUS CODES:** +DIRECTIVE STATUS CODES: + This method returns ``true`` if the instance is valid, and ``false`` + otherwise. -This method returns ``true`` if the instance is valid, and ``false`` otherwise. +DESCRIPTION: + This routine check validity of a ``struct timespec`` instance. It checks if + the nanoseconds portion of the ``struct timespec`` instanceis in allowed + range (less than the maximum number of nanoseconds per second). -**DESCRIPTION:** +NOTES: + NONE -This routine check validity of a ``struct timespec`` instance. It checks if the -nanoseconds portion of the ``struct timespec`` instanceis in allowed range -(less than the maximum number of nanoseconds per second). +.. raw:: latex -**NOTES:** + \clearpage .. _rtems_timespec_add_to: TIMESPEC_ADD_TO - Add Two struct timespec Instances --------------------------------------------------- - -**CALLING SEQUENCE:** - .. index:: rtems_timespec_add_to -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - uint32_t rtems_timespec_add_to( - struct timespec *time, - const struct timespec *add - ); + uint32_t rtems_timespec_add_to( + struct timespec *time, + const struct timespec *add + ); -**STATUS CODES:** +DIRECTIVE STATUS CODES: + The method returns the number of seconds ``time`` increased by. -The method returns the number of seconds ``time`` increased by. +DESCRIPTION: + This routine adds two ``struct timespec`` instances. The second argument is + added to the first. The parameter ``time`` is the base time to which the + ``add`` parameter is added. -**DESCRIPTION:** +NOTES: + NONE -This routine adds two ``struct timespec`` instances. The second argument is -added to the first. The parameter ``time`` is the base time to which the -``add`` parameter is added. +.. raw:: latex -**NOTES:** - -NONE + \clearpage .. _rtems_timespec_subtract: TIMESPEC_SUBTRACT - Subtract Two struct timespec Instances ---------------------------------------------------------- - -**CALLING SEQUENCE:** - .. index:: rtems_timespec_subtract -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - void rtems_timespec_subtract( - const struct timespec *start, - const struct timespec *end, - struct timespec *result - ); + void rtems_timespec_subtract( + const struct timespec *start, + const struct timespec *end, + struct timespec *result + ); -**STATUS CODES:** +DIRECTIVE STATUS CODES: + NONE -NONE +DESCRIPTION: + This routine subtracts ``start`` from ``end`` saves the difference in + ``result``. The primary use of this directive is to calculate elapsed time. -**DESCRIPTION:** +NOTES: + It is possible to subtract when ``end`` is less than ``start`` and it + produce negative ``result``. When doing this you should be careful and + remember that only the seconds portion of a ``struct timespec`` instance is + signed, which means that nanoseconds portion is always increasing. Due to + that when your timespec has seconds = -1 and nanoseconds = 500,000,000 it + means that result is -0.5 second, NOT the expected -1.5! -This routine subtracts ``start`` from ``end`` saves the difference in -``result``. The primary use of this directive is to calculate elapsed time. +.. raw:: latex -**NOTES:** - -It is possible to subtract when ``end`` is less than ``start`` and it produce -negative ``result``. When doing this you should be careful and remember that -only the seconds portion of a ``struct timespec`` instance is signed, which -means that nanoseconds portion is always increasing. Due to that when your -timespec has seconds = -1 and nanoseconds = 500,000,000 it means that result is --0.5 second, NOT the expected -1.5! + \clearpage .. _rtems_timespec_divide: TIMESPEC_DIVIDE - Divide Two struct timespec Instances ------------------------------------------------------ - -**CALLING SEQUENCE:** - .. index:: rtems_timespec_divide -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - void rtems_timespec_divide( - const struct timespec *lhs, - const struct timespec *rhs, - uint32_t *ival_percentage, - uint32_t *fval_percentage - ); + void rtems_timespec_divide( + const struct timespec *lhs, + const struct timespec *rhs, + uint32_t *ival_percentage, + uint32_t *fval_percentage + ); -**STATUS CODES:** +DIRECTIVE STATUS CODES: + NONE -NONE +DESCRIPTION: + This routine divides the ``struct timespec`` instance ``lhs`` by the + ``struct timespec`` instance ``rhs``. The result is returned in the + ``ival_percentage`` and ``fval_percentage``, representing the integer and + fractional results of the division respectively. -**DESCRIPTION:** + The ``ival_percentage`` is integer value of calculated percentage and + ``fval_percentage`` is fractional part of calculated percentage. -This routine divides the ``struct timespec`` instance ``lhs`` by the ``struct -timespec`` instance ``rhs``. The result is returned in the ``ival_percentage`` -and ``fval_percentage``, representing the integer and fractional results of the -division respectively. +NOTES: + The intended use is calculating percentges to three decimal points. -The ``ival_percentage`` is integer value of calculated percentage and -``fval_percentage`` is fractional part of calculated percentage. + When dividing by zero, this routine return both ``ival_percentage`` and + ``fval_percentage`` equal zero. -**NOTES:** + The division is performed using exclusively integer operations. -The intended use is calculating percentges to three decimal points. +.. raw:: latex -When dividing by zero, this routine return both ``ival_percentage`` and -``fval_percentage`` equal zero. - -The division is performed using exclusively integer operations. + \clearpage .. _rtems_timespec_divide_by_integer: TIMESPEC_DIVIDE_BY_INTEGER - Divide a struct timespec Instance by an Integer ---------------------------------------------------------------------------- - -**CALLING SEQUENCE:** - .. index:: rtems_timespec_divide_by_integer -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - int rtems_timespec_divide_by_integer( - const struct timespec *time, - uint32_t iterations, - struct timespec *result - ); + int rtems_timespec_divide_by_integer( + const struct timespec *time, + uint32_t iterations, + struct timespec *result + ); -**STATUS CODES:** +DIRECTIVE STATUS CODES: + NONE -NONE +DESCRIPTION: + This routine divides the ``struct timespec`` instance ``time`` by the + integer value ``iterations``. The result is saved in ``result``. -**DESCRIPTION:** +NOTES: + The expected use is to assist in benchmark calculations where you typically + divide a duration (``time``) by a number of iterations what gives average + time. -This routine divides the ``struct timespec`` instance ``time`` by the integer -value ``iterations``. The result is saved in ``result``. +.. raw:: latex -**NOTES:** - -The expected use is to assist in benchmark calculations where you typically -divide a duration (``time``) by a number of iterations what gives average time. + \clearpage .. _rtems_timespec_less_than: TIMESPEC_LESS_THAN - Less than operator --------------------------------------- - -**CALLING SEQUENCE:** - .. index:: rtems_timespec_less_than -.. code-block:: c - - bool rtems_timespec_less_than( - const struct timespec *lhs, - const struct timespec *rhs - ); +CALLING SEQUENCE: + .. code-block:: c -**STATUS CODES:** + bool rtems_timespec_less_than( + const struct timespec *lhs, + const struct timespec *rhs + ); -This method returns ``struct true`` if ``lhs`` is less than ``rhs`` and -``struct false`` otherwise. +DIRECTIVE STATUS CODES: + This method returns ``struct true`` if ``lhs`` is less than ``rhs`` and + ``struct false`` otherwise. -**DESCRIPTION:** +DESCRIPTION: + This method is the less than operator for ``struct timespec`` + instances. The first parameter is the left hand side and the second is the + right hand side of the comparison. -This method is the less than operator for ``struct timespec`` instances. The -first parameter is the left hand side and the second is the right hand side of -the comparison. +NOTES: + NONE -**NOTES:** +.. raw:: latex -NONE + \clearpage .. _rtems_timespec_greater_than: TIMESPEC_GREATER_THAN - Greater than operator --------------------------------------------- - -**CALLING SEQUENCE:** - .. index:: rtems_timespec_greater_than -.. code-block:: c - - bool rtems_timespec_greater_than( - const struct timespec *_lhs, - const struct timespec *_rhs - ); +CALLING SEQUENCE: + .. code-block:: c -**STATUS CODES:** + bool rtems_timespec_greater_than( + const struct timespec *_lhs, + const struct timespec *_rhs + ); -This method returns ``struct true`` if ``lhs`` is greater than ``rhs`` and -``struct false`` otherwise. +DIRECTIVE STATUS CODES: + This method returns ``struct true`` if ``lhs`` is greater than ``rhs`` and + ``struct false`` otherwise. -**DESCRIPTION:** +DESCRIPTION: + This method is greater than operator for ``struct timespec`` instances. -This method is greater than operator for ``struct timespec`` instances. +NOTES: + NONE -**NOTES:** +.. raw:: latex -NONE + \clearpage .. _rtems_timespec_equal_to: TIMESPEC_EQUAL_TO - Check equality of timespecs ----------------------------------------------- - -**CALLING SEQUENCE:** - .. index:: rtems_timespec_equal_to -.. code-block:: c - - bool rtems_timespec_equal_to( - const struct timespec *lhs, - const struct timespec *rhs - ); +CALLING SEQUENCE: + .. code-block:: c -**STATUS CODES:** + bool rtems_timespec_equal_to( + const struct timespec *lhs, + const struct timespec *rhs + ); -This method returns ``struct true`` if ``lhs`` is equal to ``rhs`` and ``struct -false`` otherwise. +DIRECTIVE STATUS CODES: + This method returns ``struct true`` if ``lhs`` is equal to ``rhs`` and + ``struct false`` otherwise. -**DESCRIPTION:** +DESCRIPTION: + This method is equality operator for ``struct timespec`` instances. -This method is equality operator for ``struct timespec`` instances. +NOTES: + NONE -**NOTES:** +.. raw:: latex -NONE + \clearpage .. _rtems_timespec_get_seconds: TIMESPEC_GET_SECONDS - Get Seconds Portion of struct timespec Instance ---------------------------------------------------------------------- - -**CALLING SEQUENCE:** - .. index:: rtems_timespec_get_seconds -.. code-block:: c - - time_t rtems_timespec_get_seconds( - struct timespec *time - ); +CALLING SEQUENCE: + .. code-block:: c -**STATUS CODES:** + time_t rtems_timespec_get_seconds( + struct timespec *time + ); -This method returns the seconds portion of the specified ``struct timespec`` -instance. +DIRECTIVE STATUS CODES: + This method returns the seconds portion of the specified ``struct + timespec`` instance. -**DESCRIPTION:** +DESCRIPTION: + This method returns the seconds portion of the specified ``struct + timespec`` instance ``time``. -This method returns the seconds portion of the specified ``struct timespec`` -instance ``time``. +NOTES: + NONE -**NOTES:** +.. raw:: latex -NONE + \clearpage .. _rtems_timespec_get_nanoseconds: TIMESPEC_GET_NANOSECONDS - Get Nanoseconds Portion of the struct timespec Instance ---------------------------------------------------------------------------------- - -**CALLING SEQUENCE:** - .. index:: rtems_timespec_get_nanoseconds -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - uint32_t rtems_timespec_get_nanoseconds( - struct timespec *_time - ); + uint32_t rtems_timespec_get_nanoseconds( + struct timespec *_time + ); -**STATUS CODES:** +DIRECTIVE STATUS CODES: + This method returns the nanoseconds portion of the specified ``struct + timespec`` instance. -This method returns the nanoseconds portion of the specified ``struct -timespec`` instance. +DESCRIPTION: + This method returns the nanoseconds portion of the specified timespec which + is pointed by ``_time``. -**DESCRIPTION:** +NOTES: + NONE -This method returns the nanoseconds portion of the specified timespec which is -pointed by ``_time``. +.. raw:: latex -**NOTES:** + \clearpage .. _rtems_timespec_to_ticks: TIMESPEC_TO_TICKS - Convert struct timespec Instance to Ticks ------------------------------------------------------------- - -**CALLING SEQUENCE:** - .. index:: rtems_timespec_to_ticks -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - uint32_t rtems_timespec_to_ticks( - const struct timespec *time - ); + uint32_t rtems_timespec_to_ticks( + const struct timespec *time + ); -**STATUS CODES:** +DIRECTIVE STATUS CODES: + This directive returns the number of ticks computed. -This directive returns the number of ticks computed. +DESCRIPTION: + This directive converts the ``time`` timespec to the corresponding number + of clock ticks. -**DESCRIPTION:** +NOTES: + NONE -This directive converts the ``time`` timespec to the corresponding number of -clock ticks. +.. raw:: latex -**NOTES:** - -NONE + \clearpage .. _rtems_timespec_from_ticks: TIMESPEC_FROM_TICKS - Convert Ticks to struct timespec Representation --------------------------------------------------------------------- - -**CALLING SEQUENCE:** - .. index:: rtems_timespec_from_ticks -.. code-block:: c - - void rtems_timespec_from_ticks( - uint32_t ticks, - struct timespec *time - ); - -.. index:: rtems_timespec_from_ticks - -**STATUS CODES:** - -NONE +CALLING SEQUENCE: + .. code-block:: c -**DESCRIPTION:** + void rtems_timespec_from_ticks( + uint32_t ticks, + struct timespec *time + ); -This routine converts the ``ticks`` to the corresponding ``struct timespec`` -representation and stores it in ``time``. +DIRECTIVE STATUS CODES: + NONE -**NOTES:** +DESCRIPTION: + This routine converts the ``ticks`` to the corresponding ``struct + timespec`` representation and stores it in ``time``. -NONE +NOTES: + NONE diff --git a/c-user/user_extensions.rst b/c-user/user_extensions.rst index 664d70a..aba0d9b 100644 --- a/c-user/user_extensions.rst +++ b/c-user/user_extensions.rst @@ -436,47 +436,51 @@ 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 + .. _rtems_extension_create: EXTENSION_CREATE - Create a extension set ----------------------------------------- .. index:: create an extension set - -**CALLING SEQUENCE:** - .. index:: rtems_extension_create -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_extension_create( - rtems_name name, - rtems_extensions_table *table, - rtems_id *id - ); + rtems_status_code rtems_extension_create( + rtems_name name, + rtems_extensions_table *table, + rtems_id *id + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. list-table:: - :class: rtems-table + * - ``RTEMS_SUCCESSFUL`` + - extension set created successfully + * - ``RTEMS_INVALID_NAME`` + - invalid extension set name + * - ``RTEMS_TOO_MANY`` + - too many extension sets created - * - ``RTEMS_SUCCESSFUL`` - - extension set created successfully - * - ``RTEMS_INVALID_NAME`` - - invalid extension set name - * - ``RTEMS_TOO_MANY`` - - too many extension sets created +DESCRIPTION: + This directive creates a extension set. The assigned extension set id is + returned in id. This id is used to access the extension set with other + user extension manager directives. For control and maintenance of the + extension set, RTEMS allocates an ESCB from the local ESCB free pool and + initializes it. -**DESCRIPTION:** +NOTES: -This directive creates a extension set. The assigned extension set id is -returned in id. This id is used to access the extension set with other user -extension manager directives. For control and maintenance of the extension -set, RTEMS allocates an ESCB from the local ESCB free pool and initializes it. + This directive will not cause the calling task to be preempted. -**NOTES:** +.. raw:: latex -This directive will not cause the calling task to be -preempted. + \clearpage .. _rtems_extension_ident: @@ -484,80 +488,73 @@ EXTENSION_IDENT - Get ID of a extension set ------------------------------------------- .. index:: get ID of an extension set .. index:: obtain ID of an extension set - -**CALLING SEQUENCE:** - .. index:: rtems_extension_ident -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_extension_ident( - rtems_name name, - rtems_id *id - ); + rtems_status_code rtems_extension_ident( + rtems_name name, + rtems_id *id + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. list-table:: - :class: rtems-table + * - ``RTEMS_SUCCESSFUL`` + - extension set identified successfully + * - ``RTEMS_INVALID_NAME`` + - extension set name not found - * - ``RTEMS_SUCCESSFUL`` - - extension set identified successfully - * - ``RTEMS_INVALID_NAME`` - - extension set name not found +DESCRIPTION: + This directive obtains the extension set id associated with the extension + set name to be acquired. If the extension set name is not unique, then the + extension set id will match one of the extension sets with that name. + However, this extension set id is not guaranteed to correspond to the + desired extension set. The extension set id is used to access this + extension set in other extension set related directives. -**DESCRIPTION:** +NOTES: + This directive will not cause the running task to be preempted. -This directive obtains the extension set id associated with the extension set -name to be acquired. If the extension set name is not unique, then the -extension set id will match one of the extension sets with that name. However, -this extension set id is not guaranteed to correspond to the desired extension -set. The extension set id is used to access this extension set in other -extension set related directives. +.. raw:: latex -**NOTES:** - -This directive will not cause the running task to be preempted. + \clearpage .. _rtems_extension_delete: EXTENSION_DELETE - Delete a extension set ----------------------------------------- .. index:: delete an extension set - -**CALLING SEQUENCE:** - .. index:: rtems_extension_delete -.. 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 +CALLING SEQUENCE: + .. code-block:: c -**DESCRIPTION:** + rtems_status_code rtems_extension_delete( + rtems_id id + ); -This directive deletes the extension set specified by ``id``. If the extension -set is running, it is automatically canceled. The ESCB for the deleted -extension set is reclaimed by RTEMS. +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -**NOTES:** + * - ``RTEMS_SUCCESSFUL`` + - extension set deleted successfully + * - ``RTEMS_INVALID_ID`` + - invalid extension set id -This directive will not cause the running task to be preempted. +DESCRIPTION: + This directive deletes the extension set specified by ``id``. If the + extension set is running, it is automatically canceled. The ESCB for the + deleted extension set is reclaimed by RTEMS. -A extension set can be deleted by a task other than the task which created the -extension set. +NOTES: + This directive will not cause the running task to be preempted. -**NOTES:** + A extension set can be deleted by a task other than the task which created + the extension set. -This directive will not cause the running task to be preempted. +NOTES: + This directive will not cause the running task to be preempted. |