diff options
Diffstat (limited to 'c-user')
118 files changed, 21772 insertions, 7567 deletions
diff --git a/c-user/barrier/directives.rst b/c-user/barrier/directives.rst index 84dacc4..4eded62 100644 --- a/c-user/barrier/directives.rst +++ b/c-user/barrier/directives.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) .. This file is part of the RTEMS quality process and was automatically @@ -67,9 +67,9 @@ Creates a barrier. barrier. ``id`` - This parameter is the pointer to an object identifier variable. When the - directive call is successful, the identifier of the created barrier will be - stored in this variable. + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the identifier of the created barrier + will be stored in this object. .. rubric:: DESCRIPTION: @@ -175,9 +175,9 @@ Identifies a barrier by the object name. This parameter is the object name to look up. ``id`` - This parameter is the pointer to an object identifier variable. When the - directive call is successful, the object identifier of an object with the - specified name will be stored in this variable. + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the object identifier of an object with + the specified name will be stored in this object. .. rubric:: DESCRIPTION: @@ -380,9 +380,10 @@ Releases the barrier. This parameter is the barrier identifier. ``released`` - This parameter is the pointer to an integer variable. When the directive - call is successful, the number of released tasks will be stored in this - variable. + This parameter is the pointer to an `uint32_t + <https://en.cppreference.com/w/c/types/integer>`_ object. When the + directive call is successful, the number of released tasks will be stored + in this object. .. rubric:: DESCRIPTION: @@ -410,4 +411,5 @@ The following constraints apply to this directive: * The directive may be called from within task context. -* The directive may unblock another task which may preempt the calling task. +* The directive may unblock a task. This may cause the calling task to be + preempted. diff --git a/c-user/barrier/index.rst b/c-user/barrier/index.rst index ddf0b56..e924c83 100644 --- a/c-user/barrier/index.rst +++ b/c-user/barrier/index.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020 embedded brains GmbH & Co. KG .. index:: barrier diff --git a/c-user/barrier/introduction.rst b/c-user/barrier/introduction.rst index 11013bf..e1c957f 100644 --- a/c-user/barrier/introduction.rst +++ b/c-user/barrier/introduction.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) .. This file is part of the RTEMS quality process and was automatically diff --git a/c-user/cache/directives.rst b/c-user/cache/directives.rst new file mode 100644 index 0000000..a97654e --- /dev/null +++ b/c-user/cache/directives.rst @@ -0,0 +1,665 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2016 Pavel Pisa +.. Copyright (C) 2014, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 2000, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. _CacheManagerDirectives: + +Directives +========== + +This section details the directives of the Cache Manager. A subsection is +dedicated to each of this manager's directives and lists the calling sequence, +parameters, description, return values, and notes of the directive. + +.. Generated from spec:/rtems/cache/if/flush-multiple-data-lines + +.. raw:: latex + + \clearpage + +.. index:: rtems_cache_flush_multiple_data_lines() + +.. _InterfaceRtemsCacheFlushMultipleDataLines: + +rtems_cache_flush_multiple_data_lines() +--------------------------------------- + +Flushes the data cache lines covering the memory area. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_cache_flush_multiple_data_lines( const void *begin, size_t size ); + +.. rubric:: PARAMETERS: + +``begin`` + This parameter is the begin address of the memory area to flush. + +``size`` + This parameter is the size in bytes of the memory area to flush. + +.. rubric:: DESCRIPTION: + +Dirty data cache lines covering the area are transfered to memory. Depending +on the cache implementation this may mark the lines as invalid. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/cache/if/invalidate-multiple-data-lines + +.. raw:: latex + + \clearpage + +.. index:: rtems_cache_invalidate_multiple_data_lines() + +.. _InterfaceRtemsCacheInvalidateMultipleDataLines: + +rtems_cache_invalidate_multiple_data_lines() +-------------------------------------------- + +Invalidates the data cache lines covering the memory area. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_cache_invalidate_multiple_data_lines( + const void *begin, + size_t size + ); + +.. rubric:: PARAMETERS: + +``begin`` + This parameter is the begin address of the memory area to invalidate. + +``size`` + This parameter is the size in bytes of the memory area to invalidate. + +.. rubric:: DESCRIPTION: + +The cache lines covering the area are marked as invalid. A later read access +in the area will load the data from memory. + +.. rubric:: NOTES: + +In case the area is not aligned on cache line boundaries, then this operation +may destroy unrelated data. + +On some systems, the cache lines may be flushed before they are invalidated. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/cache/if/invalidate-multiple-instruction-lines + +.. raw:: latex + + \clearpage + +.. index:: rtems_cache_invalidate_multiple_instruction_lines() + +.. _InterfaceRtemsCacheInvalidateMultipleInstructionLines: + +rtems_cache_invalidate_multiple_instruction_lines() +--------------------------------------------------- + +Invalidates the instruction cache lines covering the memory area. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_cache_invalidate_multiple_instruction_lines( + const void *begin, + size_t size + ); + +.. rubric:: PARAMETERS: + +``begin`` + This parameter is the begin address of the memory area to invalidate. + +``size`` + This parameter is the size in bytes of the memory area to invalidate. + +.. rubric:: DESCRIPTION: + +The cache lines covering the area are marked as invalid. A later instruction +fetch from the area will result in a load from memory. + +.. rubric:: NOTES: + +In SMP configurations, on processors without instruction cache snooping, this +operation will invalidate the instruction cache lines on all processors. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/cache/if/instruction-sync-after-code-change + +.. raw:: latex + + \clearpage + +.. index:: rtems_cache_instruction_sync_after_code_change() + +.. _InterfaceRtemsCacheInstructionSyncAfterCodeChange: + +rtems_cache_instruction_sync_after_code_change() +------------------------------------------------ + +Ensures necessary synchronization required after code changes. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_cache_instruction_sync_after_code_change( + const void *begin, + size_t size + ); + +.. rubric:: PARAMETERS: + +``begin`` + This parameter is the begin address of the code area to synchronize. + +``size`` + This parameter is the size in bytes of the code area to synchronize. + +.. rubric:: NOTES: + +When code is loaded or modified, then most systems require synchronization +instructions to update the instruction caches so that the loaded or modified +code is fetched. For example, systems with separate data and instruction +caches or systems without instruction cache snooping. The directives should be +used by run time loader for example. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/cache/if/get-maximal-line-size + +.. raw:: latex + + \clearpage + +.. index:: rtems_cache_get_maximal_line_size() + +.. _InterfaceRtemsCacheGetMaximalLineSize: + +rtems_cache_get_maximal_line_size() +----------------------------------- + +Gets the maximal cache line size in bytes of all caches (data, instruction, or +unified). + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + size_t rtems_cache_get_maximal_line_size( void ); + +.. rubric:: RETURN VALUES: + +``0`` + There is no cache present. + +Returns the maximal cache line size in bytes of all caches (data, instruction, +or unified). + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/cache/if/get-data-line-size + +.. raw:: latex + + \clearpage + +.. index:: rtems_cache_get_data_line_size() + +.. _InterfaceRtemsCacheGetDataLineSize: + +rtems_cache_get_data_line_size() +-------------------------------- + +Gets the data cache line size in bytes. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + size_t rtems_cache_get_data_line_size( void ); + +.. rubric:: RETURN VALUES: + +``0`` + There is no data cache present. + +Returns the data cache line size in bytes. For multi-level caches this is the +maximum of the cache line sizes of all levels. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/cache/if/get-instruction-line-size + +.. raw:: latex + + \clearpage + +.. index:: rtems_cache_get_instruction_line_size() + +.. _InterfaceRtemsCacheGetInstructionLineSize: + +rtems_cache_get_instruction_line_size() +--------------------------------------- + +Gets the instruction cache line size in bytes. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + size_t rtems_cache_get_instruction_line_size( void ); + +.. rubric:: RETURN VALUES: + +``0`` + There is no instruction cache present. + +Returns the instruction cache line size in bytes. For multi-level caches this +is the maximum of the cache line sizes of all levels. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/cache/if/get-data-size + +.. raw:: latex + + \clearpage + +.. index:: rtems_cache_get_data_cache_size() + +.. _InterfaceRtemsCacheGetDataCacheSize: + +rtems_cache_get_data_cache_size() +--------------------------------- + +Gets the data cache size in bytes for the cache level. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + size_t rtems_cache_get_data_cache_size( uint32_t level ); + +.. rubric:: PARAMETERS: + +``level`` + This parameter is the requested data cache level. The cache level zero + specifies the entire data cache. + +.. rubric:: RETURN VALUES: + +``0`` + There is no data cache present at the requested cache level. + +Returns the data cache size in bytes of the requested cache level. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/cache/if/get-instruction-size + +.. raw:: latex + + \clearpage + +.. index:: rtems_cache_get_instruction_cache_size() + +.. _InterfaceRtemsCacheGetInstructionCacheSize: + +rtems_cache_get_instruction_cache_size() +---------------------------------------- + +Gets the instruction cache size in bytes for the cache level. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + size_t rtems_cache_get_instruction_cache_size( uint32_t level ); + +.. rubric:: PARAMETERS: + +``level`` + This parameter is the requested instruction cache level. The cache level + zero specifies the entire instruction cache. + +.. rubric:: RETURN VALUES: + +``0`` + There is no instruction cache present at the requested cache level. + +Returns the instruction cache size in bytes of the requested cache level. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/cache/if/flush-entire-data + +.. raw:: latex + + \clearpage + +.. index:: rtems_cache_flush_entire_data() + +.. _InterfaceRtemsCacheFlushEntireData: + +rtems_cache_flush_entire_data() +------------------------------- + +Flushes the entire data cache. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_cache_flush_entire_data( void ); + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/cache/if/invalidate-entire-data + +.. raw:: latex + + \clearpage + +.. index:: rtems_cache_invalidate_entire_data() + +.. _InterfaceRtemsCacheInvalidateEntireData: + +rtems_cache_invalidate_entire_data() +------------------------------------ + +Invalidates the entire data cache. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_cache_invalidate_entire_data( void ); + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/cache/if/invalidate-entire-instruction + +.. raw:: latex + + \clearpage + +.. index:: rtems_cache_invalidate_entire_instruction() + +.. _InterfaceRtemsCacheInvalidateEntireInstruction: + +rtems_cache_invalidate_entire_instruction() +------------------------------------------- + +Invalidates the entire instruction cache. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_cache_invalidate_entire_instruction( void ); + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/cache/if/enable-data + +.. raw:: latex + + \clearpage + +.. index:: rtems_cache_enable_data() + +.. _InterfaceRtemsCacheEnableData: + +rtems_cache_enable_data() +------------------------- + +Enables the data cache. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_cache_enable_data( void ); + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/cache/if/disable-data + +.. raw:: latex + + \clearpage + +.. index:: rtems_cache_disable_data() + +.. _InterfaceRtemsCacheDisableData: + +rtems_cache_disable_data() +-------------------------- + +Disables the data cache. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_cache_disable_data( void ); + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/cache/if/enable-instruction + +.. raw:: latex + + \clearpage + +.. index:: rtems_cache_enable_instruction() + +.. _InterfaceRtemsCacheEnableInstruction: + +rtems_cache_enable_instruction() +-------------------------------- + +Enables the instruction cache. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_cache_enable_instruction( void ); + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/cache/if/disable-instruction + +.. raw:: latex + + \clearpage + +.. index:: rtems_cache_disable_instruction() + +.. _InterfaceRtemsCacheDisableInstruction: + +rtems_cache_disable_instruction() +--------------------------------- + +Disables the instruction cache. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_cache_disable_instruction( void ); + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/cache/if/aligned-malloc + +.. raw:: latex + + \clearpage + +.. index:: rtems_cache_aligned_malloc() + +.. _InterfaceRtemsCacheAlignedMalloc: + +rtems_cache_aligned_malloc() +---------------------------- + +Allocates memory from the C Program Heap which begins at a cache line boundary. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void *rtems_cache_aligned_malloc( size_t size ); + +.. rubric:: PARAMETERS: + +``size`` + This parameter is the size in bytes of the memory area to allocate. + +.. rubric:: RETURN VALUES: + +`NULL <https://en.cppreference.com/w/c/types/NULL>`_ + There is not enough memory available to satisfy the allocation request. + +Returns the begin address of the allocated memory. The begin address is on a +cache line boundary. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. diff --git a/c-user/cache/index.rst b/c-user/cache/index.rst new file mode 100644 index 0000000..57c124f --- /dev/null +++ b/c-user/cache/index.rst @@ -0,0 +1,15 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2021 embedded brains GmbH & Co. KG + +.. index:: cache + +.. _RTEMSAPIClassicCache: + +Cache Manager +************* + +.. toctree:: + + introduction + directives diff --git a/c-user/cache/introduction.rst b/c-user/cache/introduction.rst new file mode 100644 index 0000000..a632c9c --- /dev/null +++ b/c-user/cache/introduction.rst @@ -0,0 +1,101 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2016 Pavel Pisa +.. Copyright (C) 2014, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 2000, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/rtems/cache/if/group + +.. _CacheManagerIntroduction: + +Introduction +============ + +.. The following list was generated from: +.. spec:/rtems/cache/if/flush-multiple-data-lines +.. spec:/rtems/cache/if/invalidate-multiple-data-lines +.. spec:/rtems/cache/if/invalidate-multiple-instruction-lines +.. spec:/rtems/cache/if/instruction-sync-after-code-change +.. spec:/rtems/cache/if/get-maximal-line-size +.. spec:/rtems/cache/if/get-data-line-size +.. spec:/rtems/cache/if/get-instruction-line-size +.. spec:/rtems/cache/if/get-data-size +.. spec:/rtems/cache/if/get-instruction-size +.. spec:/rtems/cache/if/flush-entire-data +.. spec:/rtems/cache/if/invalidate-entire-data +.. spec:/rtems/cache/if/invalidate-entire-instruction +.. spec:/rtems/cache/if/enable-data +.. spec:/rtems/cache/if/disable-data +.. spec:/rtems/cache/if/enable-instruction +.. spec:/rtems/cache/if/disable-instruction +.. spec:/rtems/cache/if/aligned-malloc + +The Cache Manager provides functions to perform maintenance operations for data +and instruction caches. + +The actual actions of the Cache Manager operations depend on the hardware and +the implementation provided by the CPU architecture port or a board support +package. Cache implementations tend to be highly hardware dependent. The +directives provided by the Cache Manager are: + +* :ref:`InterfaceRtemsCacheFlushMultipleDataLines` - Flushes the data cache + lines covering the memory area. + +* :ref:`InterfaceRtemsCacheInvalidateMultipleDataLines` - Invalidates the data + cache lines covering the memory area. + +* :ref:`InterfaceRtemsCacheInvalidateMultipleInstructionLines` - Invalidates + the instruction cache lines covering the memory area. + +* :ref:`InterfaceRtemsCacheInstructionSyncAfterCodeChange` - Ensures necessary + synchronization required after code changes. + +* :ref:`InterfaceRtemsCacheGetMaximalLineSize` - Gets the maximal cache line + size in bytes of all caches (data, instruction, or unified). + +* :ref:`InterfaceRtemsCacheGetDataLineSize` - Gets the data cache line size in + bytes. + +* :ref:`InterfaceRtemsCacheGetInstructionLineSize` - Gets the instruction cache + line size in bytes. + +* :ref:`InterfaceRtemsCacheGetDataCacheSize` - Gets the data cache size in + bytes for the cache level. + +* :ref:`InterfaceRtemsCacheGetInstructionCacheSize` - Gets the instruction + cache size in bytes for the cache level. + +* :ref:`InterfaceRtemsCacheFlushEntireData` - Flushes the entire data cache. + +* :ref:`InterfaceRtemsCacheInvalidateEntireData` - Invalidates the entire data + cache. + +* :ref:`InterfaceRtemsCacheInvalidateEntireInstruction` - Invalidates the + entire instruction cache. + +* :ref:`InterfaceRtemsCacheEnableData` - Enables the data cache. + +* :ref:`InterfaceRtemsCacheDisableData` - Disables the data cache. + +* :ref:`InterfaceRtemsCacheEnableInstruction` - Enables the instruction cache. + +* :ref:`InterfaceRtemsCacheDisableInstruction` - Disables the instruction + cache. + +* :ref:`InterfaceRtemsCacheAlignedMalloc` - Allocates memory from the C Program + Heap which begins at a cache line boundary. diff --git a/c-user/chains.rst b/c-user/chains.rst index 0dce1d9..ca80b4b 100644 --- a/c-user/chains.rst +++ b/c-user/chains.rst @@ -192,11 +192,12 @@ placed on another chain: rtems_chain_initialize_empty (out); - node = rtems_chain_head (chain); + node = rtems_chain_first (chain); + while (!rtems_chain_is_tail (chain, node)) { bar = (foo*) node; - rtems_chain_node* next_node = node->next; + rtems_chain_node* next_node = rtems_chain_next(node); if (strcmp (match, bar->data) == 0) { rtems_chain_extract (node); @@ -220,7 +221,7 @@ The section details the Chains directives. .. _rtems_chain_initialize: .. index:: chain initialize -.. index:: rtems_chain_initialize +.. index:: rtems_chain_initialize() Initialize Chain With Nodes --------------------------- @@ -258,7 +259,7 @@ NOTES: .. _rtems_chain_initialize_empty: .. index:: chain initialize empty -.. index:: rtems_chain_initialize_empty +.. index:: rtems_chain_initialize_empty() Initialize Empty ---------------- @@ -287,7 +288,7 @@ NOTES: .. _rtems_chain_is_null_node: .. index:: chain is node null -.. index:: rtems_chain_is_null_node +.. index:: rtems_chain_is_null_node() Is Null Node ? -------------- @@ -313,7 +314,7 @@ DESCRIPTION: .. _rtems_chain_head: .. index:: chain get head -.. index:: rtems_chain_head +.. index:: rtems_chain_head() Head ---- @@ -338,7 +339,7 @@ DESCRIPTION: .. _rtems_chain_tail: .. index:: chain get tail -.. index:: rtems_chain_tail +.. index:: rtems_chain_tail() Tail ---- @@ -363,7 +364,7 @@ DESCRIPTION: .. _rtems_chain_are_nodes_equal: .. index:: chare are nodes equal -.. index:: rtems_chain_are_nodes_equal +.. index:: rtems_chain_are_nodes_equal() Are Two Nodes Equal ? --------------------- @@ -391,7 +392,7 @@ DESCRIPTION: .. _rtems_chain_is_empty: .. index:: chain is chain empty -.. index:: rtems_chain_is_empty +.. index:: rtems_chain_is_empty() Is the Chain Empty ------------------ @@ -418,7 +419,7 @@ DESCRIPTION: .. _rtems_chain_is_first: .. index:: chain is node the first -.. index:: rtems_chain_is_first +.. index:: rtems_chain_is_first() Is this the First Node on the Chain ? ------------------------------------- @@ -445,7 +446,7 @@ DESCRIPTION: .. _rtems_chain_is_last: .. index:: chain is node the last -.. index:: rtems_chain_is_last +.. index:: rtems_chain_is_last() Is this the Last Node on the Chain ? ------------------------------------ @@ -472,7 +473,7 @@ DESCRIPTION: .. _rtems_chain_has_only_one_node: .. index:: chain only one node -.. index:: rtems_chain_has_only_one_node +.. index:: rtems_chain_has_only_one_node() Does this Chain have only One Node ? ------------------------------------ @@ -499,7 +500,7 @@ DESCRIPTION: .. _rtems_chain_node_count_unprotected: .. index:: chain only one node -.. index:: rtems_chain_node_count_unprotected +.. index:: rtems_chain_node_count_unprotected() Returns the node count of the chain (unprotected) ------------------------------------------------- @@ -524,7 +525,7 @@ DESCRIPTION: .. _rtems_chain_is_head: .. index:: chain is node the head -.. index:: rtems_chain_is_head +.. index:: rtems_chain_is_head() Is this Node the Chain Head ? ----------------------------- @@ -552,7 +553,7 @@ DESCRIPTION: .. _rtems_chain_is_tail: .. index:: chain is node the tail -.. index:: rtems_chain_is_tail +.. index:: rtems_chain_is_tail() Is this Node the Chain Tail ? ----------------------------- @@ -580,7 +581,7 @@ DESCRIPTION: .. _rtems_chain_extract: .. index:: chain extract a node -.. index:: rtems_chain_extract +.. index:: rtems_chain_extract() Extract a Node -------------- @@ -611,7 +612,7 @@ NOTES: .. _rtems_chain_extract_unprotected: .. index:: chain extract a node unprotected -.. index:: rtems_chain_extract_unprotected +.. index:: rtems_chain_extract_unprotected() Extract a Node (unprotected) ---------------------------- @@ -639,7 +640,7 @@ NOTES: .. _rtems_chain_get: .. index:: chain get first node -.. index:: rtems_chain_get +.. index:: rtems_chain_get() Get the First Node ------------------ @@ -672,7 +673,7 @@ NOTES: .. _rtems_chain_get_unprotected: .. index:: chain get first node -.. index:: rtems_chain_get_unprotected +.. index:: rtems_chain_get_unprotected() Get the First Node (unprotected) -------------------------------- @@ -701,7 +702,7 @@ NOTES: .. _rtems_chain_insert: .. index:: chain insert a node -.. index:: rtems_chain_insert +.. index:: rtems_chain_insert() Insert a Node ------------- @@ -734,7 +735,7 @@ NOTES: .. _rtems_chain_insert_unprotected: .. index:: chain insert a node unprotected -.. index:: rtems_chain_insert_unprotected +.. index:: rtems_chain_insert_unprotected() Insert a Node (unprotected) --------------------------- @@ -764,7 +765,7 @@ NOTES: .. _rtems_chain_append: .. index:: chain append a node -.. index:: rtems_chain_append +.. index:: rtems_chain_append() Append a Node ------------- @@ -796,7 +797,7 @@ NOTES: .. _rtems_chain_append_unprotected: .. index:: chain append a node unprotected -.. index:: rtems_chain_append_unprotected +.. index:: rtems_chain_append_unprotected() Append a Node (unprotected) --------------------------- @@ -825,7 +826,7 @@ NOTES: .. _rtems_chain_prepend: .. index:: prepend node -.. index:: rtems_chain_prepend +.. index:: rtems_chain_prepend() Prepend a Node -------------- @@ -857,7 +858,7 @@ NOTES: .. _rtems_chain_prepend_unprotected: .. index:: prepend node unprotected -.. index:: rtems_chain_prepend_unprotected +.. index:: rtems_chain_prepend_unprotected() Prepend a Node (unprotected) ---------------------------- diff --git a/c-user/clock/background.rst b/c-user/clock/background.rst index 64e8311..11a3cb5 100644 --- a/c-user/clock/background.rst +++ b/c-user/clock/background.rst @@ -1,5 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 +.. Copyright (C) 2021 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) Background @@ -8,20 +9,28 @@ Background Required Support ---------------- -For the features provided by the clock manager to be utilized, periodic timer -interrupts are required. Therefore, a real-time clock or hardware timer is -necessary to create the timer interrupts. The clock tick directive -is normally called by the timer ISR to announce to RTEMS that a system clock -tick has occurred. Elapsed time is measured in ticks. A tick is defined to be -an integral number of microseconds which is specified by the user in the -Configuration Table. +For the features provided by the Clock Manager to be utilized, a :term:`Clock +Driver` is required. The Clock Driver usually provides a clock interrupt which +is serviced on each configured processor at each :term:`clock tick`. In +addition, the Clock Driver provides three clock sources: + +* clock tick + +* :term:`CLOCK_REALTIME` + +* :term:`CLOCK_MONOTONIC` + +The time of these clock sources advances at each clock tick. This yields the +time of the clock sources in a coarse resolution. To get the time of the +``CLOCK_REALTIME`` or ``CLOCK_MONOTONIC`` clock sources in a higher resolution, +the Clock Driver may use a clock device to get the time between clock ticks. .. _Time and Date Data Structures: Time and Date Data Structures ----------------------------- -The clock facilities of the clock manager operate upon calendar time. These +The clock facilities of the Clock Manager operate upon calendar time. These directives utilize the following date and time structure for the native time and date format: @@ -29,7 +38,7 @@ and date format: .. code-block:: c - struct rtems_tod_control { + typedef struct { uint32_t year; /* greater than 1987 */ uint32_t month; /* 1 - 12 */ uint32_t day; /* 1 - 31 */ @@ -37,20 +46,34 @@ and date format: uint32_t minute; /* 0 - 59 */ uint32_t second; /* 0 - 59 */ uint32_t ticks; /* elapsed between seconds */ - }; - typedef struct rtems_tod_control rtems_time_of_day; + } rtems_time_of_day; The native date and time format is the only format supported when setting the -system date and time using the ``rtems_clock_set`` directive. Some +system date and time using the :ref:`InterfaceRtemsClockSet` directive. Some applications expect to operate on a *UNIX-style* date and time data structure. -The ``rtems_clock_get_tod_timeval`` always returns the date and time in -``struct timeval`` format. - -The ``struct timeval`` data structure has two fields: ``tv_sec`` and -``tv_usec`` which are seconds and microseconds, respectively. The ``tv_sec`` -field in this data structure is the number of seconds since the POSIX epoch of -*January 1, 1970* but will never be prior to the RTEMS epoch of *January 1, -1988*. +For example, the :ref:`InterfaceRtemsClockGetTodTimeval` returns the date and +time in ``struct timeval`` format. + +.. index:: struct timeval +.. index:: struct timespec + +Some directives use data structures defined by :term:`POSIX`. The ``struct +timeval`` data structure has two members: ``tv_sec`` and ``tv_usec`` which are +seconds and microseconds, respectively. The ``struct timespec`` data structure +has two members: ``tv_sec`` and ``tv_nsec`` which are seconds and nanoseconds, +respectively. For :term:`CLOCK_REALTIME` time points, the ``tv_sec`` member in +these data structures is the number of seconds since the :term:`Unix epoch` but +will never be prior to the :term:`RTEMS epoch`. + +.. index:: struct bintime +.. index:: sbintime_t + +The ``struct bintime`` and ``sbintime_t`` time formats used by some directives +originate in FreeBSD. The ``struct bintime`` data structure which represents +time in a binary time format has two members: ``sec`` and ``frac`` which are +seconds and fractions of a second in units of :math:`1 / 2^{64}` seconds, +respectively. The ``sbintime_t`` type is a signed 64-bit integer type used to +represent time in units of :math:`1 / 2^{32}` seconds. .. index:: timeslicing @@ -64,8 +87,9 @@ scheduling algorithm. The length of time allocated to each task is known as the quantum or timeslice. The system's timeslice is defined as an integral number of ticks, and is -specified in the Configuration Table. The timeslice is defined for the entire -system of tasks, but timeslicing is enabled and disabled on a per task basis. +specified by the :ref:`CONFIGURE_TICKS_PER_TIMESLICE` application configuration +option. The timeslice is defined for the entire system of tasks, but +timeslicing is enabled and disabled on a per task basis. The clock tick directives implement timeslicing by decrementing the running task's time-remaining counter when both timeslicing and preemption are @@ -79,10 +103,10 @@ Delays A sleep timer allows a task to delay for a given interval or up until a given time, and then wake and continue execution. This type of timer is created -automatically by the ``rtems_task_wake_after`` and ``rtems_task_wake_when`` -directives and, as a result, does not have an RTEMS ID. Once activated, a -sleep timer cannot be explicitly deleted. Each task may activate one and only -one sleep timer at a time. +automatically by the :ref:`InterfaceRtemsTaskWakeAfter` and +:ref:`InterfaceRtemsTaskWakeWhen` directives and, as a result, does not have an +object identifier. Once activated, a sleep timer cannot be explicitly deleted. +Each task may activate one and only one sleep timer at a time. .. index:: timeouts @@ -90,7 +114,8 @@ Timeouts -------- Timeouts are a special type of timer automatically created when the timeout -option is used on the ``rtems_message_queue_receive``, ``rtems_event_receive``, -``rtems_semaphore_obtain`` and ``rtems_region_get_segment`` directives. Each -task may have one and only one timeout active at a time. When a timeout -expires, it unblocks the task with a timeout status code. +option is used on the :ref:`InterfaceRtemsBarrierWait`, +:ref:`InterfaceRtemsEventReceive`, :ref:`InterfaceRtemsMessageQueueReceive`, +:ref:`InterfaceRtemsRegionGetSegment`, and :ref:`InterfaceRtemsSemaphoreObtain` +directives. Each task may have one and only one timeout active at a time. +When a timeout expires, it unblocks the task with a timeout status code. diff --git a/c-user/clock/directives.rst b/c-user/clock/directives.rst index a13b5ef..a6e00ca 100644 --- a/c-user/clock/directives.rst +++ b/c-user/clock/directives.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2014, 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2014, 2021 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) .. This file is part of the RTEMS quality process and was automatically @@ -70,10 +70,15 @@ Sets the :term:`CLOCK_REALTIME` to the time of day. The date, time, and ticks specified by ``time_of_day`` are all range-checked, and an error is returned if any one is out of its valid range. -RTEMS can represent time points of this clock in nanoseconds ranging from -1988-01-01T00:00:00.000000000Z to 2514-05-31T01:53:03.999999999Z. The future -uptime of the system shall be in this range, otherwise the system behaviour is -undefined. +RTEMS can represent time points of the :term:`CLOCK_REALTIME` clock in +nanoseconds ranging from 1988-01-01T00:00:00.000000000Z to +2514-05-31T01:53:03.999999999Z. The future uptime of the system shall be in +this range, otherwise the system behaviour is undefined. Due to implementation +constraints, the time of day set by the directive shall be before +2100-01-01:00:00.000000000Z. The latest valid time of day accepted by the +POSIX `clock_settime() +<https://pubs.opengroup.org/onlinepubs/9699919799/functions/clock_settime.html>`_ +is 2400-01-01T00:00:00.999999999Z. The specified time is based on the configured :term:`clock tick` rate, see the :ref:`CONFIGURE_MICROSECONDS_PER_TICK` application configuration option. @@ -96,10 +101,17 @@ The following constraints apply to this directive: * The directive may be called from within any runtime context. -* The directive may change the priority of another task which may preempt the - calling task. +* The directive may change the priority of a task. This may cause the calling + task to be preempted. -* The directive may unblock another task which may preempt the calling task. +* The directive may unblock a task. This may cause the calling task to be + preempted. + +* The time of day set by the directive shall be 1988-01-01T00:00:00.000000000Z + or later. + +* The time of day set by the directive shall be before + 2100-01-01T00:00:00.000000000Z. .. Generated from spec:/rtems/clock/if/get-tod @@ -125,10 +137,10 @@ Gets the time of day associated with the current :term:`CLOCK_REALTIME`. .. rubric:: PARAMETERS: ``time_of_day`` - This parameter is the pointer to a RTEMS time of day variable. When the - directive call is successful, the time of day associated with the + This parameter is the pointer to an :ref:`InterfaceRtemsTimeOfDay` object. + When the directive call is successful, the time of day associated with the :term:`CLOCK_REALTIME` at some point during the directive call will be - stored in this variable. + stored in this object. .. rubric:: RETURN VALUES: @@ -178,10 +190,12 @@ current :term:`CLOCK_REALTIME`. .. rubric:: PARAMETERS: ``time_of_day`` - This parameter is the pointer to a timeval structure variable. When the - directive call is successful, the seconds and microseconds elapsed since - the :term:`Unix epoch` and the :term:`CLOCK_REALTIME` at some point during - the directive call will be stored in this variable. + This parameter is the pointer to a `struct timeval + <https://pubs.opengroup.org/onlinepubs/009695399/basedefs/sys/time.h.html>`_ + object. When the directive call is successful, the seconds and + microseconds elapsed since the :term:`Unix epoch` and the + :term:`CLOCK_REALTIME` at some point during the directive call will be + stored in this object. .. rubric:: RETURN VALUES: @@ -206,6 +220,845 @@ The following constraints apply to this directive: * The directive requires a :term:`Clock Driver`. +.. Generated from spec:/rtems/clock/if/get-realtime + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_realtime() + +.. _InterfaceRtemsClockGetRealtime: + +rtems_clock_get_realtime() +-------------------------- + +Gets the time elapsed since the :term:`Unix epoch` measured using +:term:`CLOCK_REALTIME` in seconds and nanoseconds format. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_clock_get_realtime( struct timespec *time_snapshot ); + +.. rubric:: PARAMETERS: + +``time_snapshot`` + This parameter is the pointer to a `struct timespec + <https://en.cppreference.com/w/c/chrono/timespec>`_ object. The time + elapsed since the :term:`Unix epoch` measured using the + :term:`CLOCK_REALTIME` at some time point during the directive call will be + stored in this object. Calling the directive with a pointer equal to `NULL + <https://en.cppreference.com/w/c/types/NULL>`_ is undefined behaviour. + +.. rubric:: NOTES: + +The directive accesses a device provided by the :term:`Clock Driver` to get the +time in the highest resolution available to the system. Alternatively, the +:ref:`InterfaceRtemsClockGetRealtimeCoarse` directive may be used to get the +time in a lower resolution and with less runtime overhead. + +See :ref:`InterfaceRtemsClockGetRealtimeBintime` and +:ref:`InterfaceRtemsClockGetRealtimeTimeval` to get the time in alternative +formats. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +* The directive requires a :term:`Clock Driver`. + +.. Generated from spec:/rtems/clock/if/get-realtime-bintime + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_realtime_bintime() + +.. _InterfaceRtemsClockGetRealtimeBintime: + +rtems_clock_get_realtime_bintime() +---------------------------------- + +Gets the time elapsed since the :term:`Unix epoch` measured using +:term:`CLOCK_REALTIME` in binary time format. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_clock_get_realtime_bintime( struct bintime *time_snapshot ); + +.. rubric:: PARAMETERS: + +``time_snapshot`` + This parameter is the pointer to a ``struct bintime`` object. The time + elapsed since the :term:`Unix epoch` measured using the + :term:`CLOCK_REALTIME` at some time point during the directive call will be + stored in this object. Calling the directive with a pointer equal to `NULL + <https://en.cppreference.com/w/c/types/NULL>`_ is undefined behaviour. + +.. rubric:: NOTES: + +The directive accesses a device provided by the :term:`Clock Driver` to get the +time in the highest resolution available to the system. Alternatively, the +:ref:`InterfaceRtemsClockGetRealtimeCoarseBintime` directive may be used to get +the time in a lower resolution and with less runtime overhead. + +See :ref:`InterfaceRtemsClockGetRealtime` and +:ref:`InterfaceRtemsClockGetRealtimeTimeval` to get the time in alternative +formats. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +* The directive requires a :term:`Clock Driver`. + +.. Generated from spec:/rtems/clock/if/get-realtime-timeval + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_realtime_timeval() + +.. _InterfaceRtemsClockGetRealtimeTimeval: + +rtems_clock_get_realtime_timeval() +---------------------------------- + +Gets the time elapsed since the :term:`Unix epoch` measured using +:term:`CLOCK_REALTIME` in seconds and microseconds format. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_clock_get_realtime_timeval( struct timeval *time_snapshot ); + +.. rubric:: PARAMETERS: + +``time_snapshot`` + This parameter is the pointer to a `struct timeval + <https://pubs.opengroup.org/onlinepubs/009695399/basedefs/sys/time.h.html>`_ + object. The time elapsed since the :term:`Unix epoch` measured using the + :term:`CLOCK_REALTIME` at some time point during the directive call will be + stored in this object. Calling the directive with a pointer equal to `NULL + <https://en.cppreference.com/w/c/types/NULL>`_ is undefined behaviour. + +.. rubric:: NOTES: + +The directive accesses a device provided by the :term:`Clock Driver` to get the +time in the highest resolution available to the system. Alternatively, the +:ref:`InterfaceRtemsClockGetRealtimeCoarseTimeval` directive may be used to get +the time in a lower resolution and with less runtime overhead. + +See :ref:`InterfaceRtemsClockGetRealtime` and +:ref:`InterfaceRtemsClockGetRealtimeBintime` to get the time in alternative +formats. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +* The directive requires a :term:`Clock Driver`. + +.. Generated from spec:/rtems/clock/if/get-realtime-coarse + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_realtime_coarse() + +.. _InterfaceRtemsClockGetRealtimeCoarse: + +rtems_clock_get_realtime_coarse() +--------------------------------- + +Gets the time elapsed since the :term:`Unix epoch` measured using +:term:`CLOCK_REALTIME` in coarse resolution in seconds and nanoseconds format. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_clock_get_realtime_coarse( struct timespec *time_snapshot ); + +.. rubric:: PARAMETERS: + +``time_snapshot`` + This parameter is the pointer to a `struct timespec + <https://en.cppreference.com/w/c/chrono/timespec>`_ object. The time + elapsed since the :term:`Unix epoch` measured using the + :term:`CLOCK_REALTIME` at some time point close to the directive call will + be stored in this object. Calling the directive with a pointer equal to + `NULL <https://en.cppreference.com/w/c/types/NULL>`_ is undefined + behaviour. + +.. rubric:: NOTES: + +The directive does not access a device to get the time. It uses a recent +snapshot provided by the :term:`Clock Driver`. Alternatively, the +:ref:`InterfaceRtemsClockGetRealtime` directive may be used to get the time in +a higher resolution and with a higher runtime overhead. + +See :ref:`InterfaceRtemsClockGetRealtimeCoarseBintime` and +:ref:`InterfaceRtemsClockGetRealtimeCoarseTimeval` to get the time in +alternative formats. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +* The directive requires a :term:`Clock Driver`. + +.. Generated from spec:/rtems/clock/if/get-realtime-coarse-bintime + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_realtime_coarse_bintime() + +.. _InterfaceRtemsClockGetRealtimeCoarseBintime: + +rtems_clock_get_realtime_coarse_bintime() +----------------------------------------- + +Gets the time elapsed since the :term:`Unix epoch` measured using +:term:`CLOCK_REALTIME` in coarse resolution in binary time format. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_clock_get_realtime_coarse_bintime( struct bintime *time_snapshot ); + +.. rubric:: PARAMETERS: + +``time_snapshot`` + This parameter is the pointer to a ``struct bintime`` object. The time + elapsed since the :term:`Unix epoch` measured using the + :term:`CLOCK_REALTIME` at some time point close to the directive call will + be stored in this object. Calling the directive with a pointer equal to + `NULL <https://en.cppreference.com/w/c/types/NULL>`_ is undefined + behaviour. + +.. rubric:: NOTES: + +The directive does not access a device to get the time. It uses a recent +snapshot provided by the :term:`Clock Driver`. Alternatively, the +:ref:`InterfaceRtemsClockGetRealtimeBintime` directive may be used to get the +time in a higher resolution and with a higher runtime overhead. + +See :ref:`InterfaceRtemsClockGetRealtimeCoarse` and +:ref:`InterfaceRtemsClockGetRealtimeCoarseTimeval` to get the time in +alternative formats. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +* The directive requires a :term:`Clock Driver`. + +.. Generated from spec:/rtems/clock/if/get-realtime-coarse-timeval + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_realtime_coarse_timeval() + +.. _InterfaceRtemsClockGetRealtimeCoarseTimeval: + +rtems_clock_get_realtime_coarse_timeval() +----------------------------------------- + +Gets the time elapsed since the :term:`Unix epoch` measured using +:term:`CLOCK_REALTIME` in coarse resolution in seconds and microseconds format. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_clock_get_realtime_coarse_timeval( struct timeval *time_snapshot ); + +.. rubric:: PARAMETERS: + +``time_snapshot`` + This parameter is the pointer to a `struct timeval + <https://pubs.opengroup.org/onlinepubs/009695399/basedefs/sys/time.h.html>`_ + object. The time elapsed since the :term:`Unix epoch` measured using the + :term:`CLOCK_REALTIME` at some time point close to the directive call will + be stored in this object. Calling the directive with a pointer equal to + `NULL <https://en.cppreference.com/w/c/types/NULL>`_ is undefined + behaviour. + +.. rubric:: NOTES: + +The directive does not access a device to get the time. It uses a recent +snapshot provided by the :term:`Clock Driver`. Alternatively, the +:ref:`InterfaceRtemsClockGetRealtimeTimeval` directive may be used to get the +time in a higher resolution and with a higher runtime overhead. + +See :ref:`InterfaceRtemsClockGetRealtimeCoarse` and +:ref:`InterfaceRtemsClockGetRealtimeCoarseTimeval` to get the time in +alternative formats. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +* The directive requires a :term:`Clock Driver`. + +.. Generated from spec:/rtems/clock/if/get-monotonic + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_monotonic() + +.. _InterfaceRtemsClockGetMonotonic: + +rtems_clock_get_monotonic() +--------------------------- + +Gets the time elapsed since some fixed time point in the past measured using +the :term:`CLOCK_MONOTONIC` in seconds and nanoseconds format. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_clock_get_monotonic( struct timespec *time_snapshot ); + +.. rubric:: PARAMETERS: + +``time_snapshot`` + This parameter is the pointer to a `struct timespec + <https://en.cppreference.com/w/c/chrono/timespec>`_ object. The time + elapsed since some fixed time point in the past measured using the + :term:`CLOCK_MONOTONIC` at some time point during the directive call will + be stored in this object. Calling the directive with a pointer equal to + `NULL <https://en.cppreference.com/w/c/types/NULL>`_ is undefined + behaviour. + +.. rubric:: NOTES: + +The directive accesses a device provided by the :term:`Clock Driver` to get the +time in the highest resolution available to the system. Alternatively, the +:ref:`InterfaceRtemsClockGetMonotonicCoarse` directive may be used to get the +time with in a lower resolution and with less runtime overhead. + +See :ref:`InterfaceRtemsClockGetMonotonicBintime`, +:ref:`InterfaceRtemsClockGetMonotonicSbintime`, and +:ref:`InterfaceRtemsClockGetMonotonicTimeval` to get the time in alternative +formats. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +* The directive requires a :term:`Clock Driver`. + +.. Generated from spec:/rtems/clock/if/get-monotonic-bintime + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_monotonic_bintime() + +.. _InterfaceRtemsClockGetMonotonicBintime: + +rtems_clock_get_monotonic_bintime() +----------------------------------- + +Gets the time elapsed since some fixed time point in the past measured using +the :term:`CLOCK_MONOTONIC` in binary time format. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_clock_get_monotonic_bintime( struct bintime *time_snapshot ); + +.. rubric:: PARAMETERS: + +``time_snapshot`` + This parameter is the pointer to a ``struct bintime`` object. The time + elapsed since some fixed time point in the past measured using the + :term:`CLOCK_MONOTONIC` at some time point during the directive call will + be stored in this object. Calling the directive with a pointer equal to + `NULL <https://en.cppreference.com/w/c/types/NULL>`_ is undefined + behaviour. + +.. rubric:: NOTES: + +The directive accesses a device provided by the :term:`Clock Driver` to get the +time in the highest resolution available to the system. Alternatively, the +:ref:`InterfaceRtemsClockGetMonotonicCoarseBintime` directive may be used to +get the time in a lower resolution and with less runtime overhead. + +See :ref:`InterfaceRtemsClockGetMonotonic`, +:ref:`InterfaceRtemsClockGetMonotonicSbintime`, and +:ref:`InterfaceRtemsClockGetMonotonicTimeval` to get the time in alternative +formats. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +* The directive requires a :term:`Clock Driver`. + +.. Generated from spec:/rtems/clock/if/get-monotonic-sbintime + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_monotonic_sbintime() + +.. _InterfaceRtemsClockGetMonotonicSbintime: + +rtems_clock_get_monotonic_sbintime() +------------------------------------ + +Gets the time elapsed since some fixed time point in the past measured using +the :term:`CLOCK_MONOTONIC` in signed binary time format. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + int64_t rtems_clock_get_monotonic_sbintime( void ); + +.. rubric:: RETURN VALUES: + +Returns the time elapsed since some fixed time point in the past measured using +the :term:`CLOCK_MONOTONIC` at some time point during the directive call. + +.. rubric:: NOTES: + +The directive accesses a device provided by the :term:`Clock Driver` to get the +time in the highest resolution available to the system. + +See :ref:`InterfaceRtemsClockGetMonotonic`, +:ref:`InterfaceRtemsClockGetMonotonicBintime`, and +:ref:`InterfaceRtemsClockGetMonotonicTimeval` to get the time in alternative +formats. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +* The directive requires a :term:`Clock Driver`. + +.. Generated from spec:/rtems/clock/if/get-monotonic-timeval + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_monotonic_timeval() + +.. _InterfaceRtemsClockGetMonotonicTimeval: + +rtems_clock_get_monotonic_timeval() +----------------------------------- + +Gets the time elapsed since some fixed time point in the past measured using +the :term:`CLOCK_MONOTONIC` in seconds and microseconds format. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_clock_get_monotonic_timeval( struct timeval *time_snapshot ); + +.. rubric:: PARAMETERS: + +``time_snapshot`` + This parameter is the pointer to a `struct timeval + <https://pubs.opengroup.org/onlinepubs/009695399/basedefs/sys/time.h.html>`_ + object. The time elapsed since some fixed time point in the past measured + using the :term:`CLOCK_MONOTONIC` at some time point during the directive + call will be stored in this object. Calling the directive with a pointer + equal to `NULL <https://en.cppreference.com/w/c/types/NULL>`_ is undefined + behaviour. + +.. rubric:: NOTES: + +The directive accesses a device provided by the :term:`Clock Driver` to get the +time in the highest resolution available to the system. Alternatively, the +:ref:`InterfaceRtemsClockGetMonotonicCoarseTimeval` directive may be used to +get the time in a lower resolution and with less runtime overhead. + +See :ref:`InterfaceRtemsClockGetMonotonic`, +:ref:`InterfaceRtemsClockGetMonotonicBintime`, and +:ref:`InterfaceRtemsClockGetMonotonicSbintime` to get the time in alternative +formats. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +* The directive requires a :term:`Clock Driver`. + +.. Generated from spec:/rtems/clock/if/get-monotonic-coarse + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_monotonic_coarse() + +.. _InterfaceRtemsClockGetMonotonicCoarse: + +rtems_clock_get_monotonic_coarse() +---------------------------------- + +Gets the time elapsed since some fixed time point in the past measured using +the :term:`CLOCK_MONOTONIC` in coarse resolution in seconds and nanoseconds +format. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_clock_get_monotonic_coarse( struct timespec *time_snapshot ); + +.. rubric:: PARAMETERS: + +``time_snapshot`` + This parameter is the pointer to a `struct timespec + <https://en.cppreference.com/w/c/chrono/timespec>`_ object. The time + elapsed since some fixed time point in the past measured using the + :term:`CLOCK_MONOTONIC` at some time point close to the directive call will + be stored in this object. Calling the directive with a pointer equal to + `NULL <https://en.cppreference.com/w/c/types/NULL>`_ is undefined + behaviour. + +.. rubric:: NOTES: + +The directive does not access a device to get the time. It uses a recent +snapshot provided by the :term:`Clock Driver`. Alternatively, the +:ref:`InterfaceRtemsClockGetMonotonic` directive may be used to get the time in +a higher resolution and with a higher runtime overhead. + +See :ref:`InterfaceRtemsClockGetMonotonicCoarseBintime` and +:ref:`InterfaceRtemsClockGetMonotonicCoarseTimeval` to get the time in +alternative formats. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +* The directive requires a :term:`Clock Driver`. + +.. Generated from spec:/rtems/clock/if/get-monotonic-coarse-bintime + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_monotonic_coarse_bintime() + +.. _InterfaceRtemsClockGetMonotonicCoarseBintime: + +rtems_clock_get_monotonic_coarse_bintime() +------------------------------------------ + +Gets the time elapsed since some fixed time point in the past measured using +the :term:`CLOCK_MONOTONIC` in coarse resolution in binary time format. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_clock_get_monotonic_coarse_bintime( struct bintime *time_snapshot ); + +.. rubric:: PARAMETERS: + +``time_snapshot`` + This parameter is the pointer to a ``struct bintime`` object. The time + elapsed since some fixed time point in the past measured using the + :term:`CLOCK_MONOTONIC` at some time point close to the directive call will + be stored in this object. Calling the directive with a pointer equal to + `NULL <https://en.cppreference.com/w/c/types/NULL>`_ is undefined + behaviour. + +.. rubric:: NOTES: + +The directive does not access a device to get the time. It uses a recent +snapshot provided by the :term:`Clock Driver`. Alternatively, the +:ref:`InterfaceRtemsClockGetMonotonicBintime` directive may be used to get the +time in a higher resolution and with a higher runtime overhead. + +See :ref:`InterfaceRtemsClockGetMonotonicCoarse` and +:ref:`InterfaceRtemsClockGetMonotonicCoarseTimeval` to get the time in +alternative formats. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +* The directive requires a :term:`Clock Driver`. + +.. Generated from spec:/rtems/clock/if/get-monotonic-coarse-timeval + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_monotonic_coarse_timeval() + +.. _InterfaceRtemsClockGetMonotonicCoarseTimeval: + +rtems_clock_get_monotonic_coarse_timeval() +------------------------------------------ + +Gets the time elapsed since some fixed time point in the past measured using +the :term:`CLOCK_MONOTONIC` in coarse resolution in seconds and microseconds +format. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_clock_get_monotonic_coarse_timeval( struct timeval *time_snapshot ); + +.. rubric:: PARAMETERS: + +``time_snapshot`` + This parameter is the pointer to a `struct timeval + <https://pubs.opengroup.org/onlinepubs/009695399/basedefs/sys/time.h.html>`_ + object. The time elapsed since some fixed time point in the past measured + using the :term:`CLOCK_MONOTONIC` at some time point close to the directive + call will be stored in this object. Calling the directive with a pointer + equal to `NULL <https://en.cppreference.com/w/c/types/NULL>`_ is undefined + behaviour. + +.. rubric:: NOTES: + +The directive does not access a device to get the time. It uses a recent +snapshot provided by the :term:`Clock Driver`. Alternatively, the +:ref:`InterfaceRtemsClockGetMonotonicTimeval` directive may be used to get the +time in a higher resolution and with a higher runtime overhead. + +See :ref:`InterfaceRtemsClockGetMonotonicCoarse` and +:ref:`InterfaceRtemsClockGetMonotonicCoarseBintime` to get the time in +alternative formats. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +* The directive requires a :term:`Clock Driver`. + +.. Generated from spec:/rtems/clock/if/get-boot-time + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_boot_time() + +.. _InterfaceRtemsClockGetBootTime: + +rtems_clock_get_boot_time() +--------------------------- + +Gets the time elapsed since the :term:`Unix epoch` at some time point during +system initialization in seconds and nanoseconds format. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_clock_get_boot_time( struct timespec *boot_time ); + +.. rubric:: PARAMETERS: + +``boot_time`` + This parameter is the pointer to a `struct timespec + <https://en.cppreference.com/w/c/chrono/timespec>`_ object. The time + elapsed since the :term:`Unix epoch` at some time point during system + initialization call will be stored in this object. Calling the directive + with a pointer equal to `NULL + <https://en.cppreference.com/w/c/types/NULL>`_ is undefined behaviour. + +.. rubric:: NOTES: + +See :ref:`InterfaceRtemsClockGetBootTimeBintime` and +:ref:`InterfaceRtemsClockGetBootTimeTimeval` to get the boot time in +alternative formats. Setting the :term:`CLOCK_REALTIME` will also set the boot +time. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +* The directive requires a :term:`Clock Driver`. + +.. Generated from spec:/rtems/clock/if/get-boot-time-bintime + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_boot_time_bintime() + +.. _InterfaceRtemsClockGetBootTimeBintime: + +rtems_clock_get_boot_time_bintime() +----------------------------------- + +Gets the time elapsed since the :term:`Unix epoch` at some time point during +system initialization in binary time format. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_clock_get_boot_time_bintime( struct bintime *boot_time ); + +.. rubric:: PARAMETERS: + +``boot_time`` + This parameter is the pointer to a ``struct bintime`` object. The time + elapsed since the :term:`Unix epoch` at some time point during system + initialization call will be stored in this object. Calling the directive + with a pointer equal to `NULL + <https://en.cppreference.com/w/c/types/NULL>`_ is undefined behaviour. + +.. rubric:: NOTES: + +See :ref:`InterfaceRtemsClockGetBootTime` and +:ref:`InterfaceRtemsClockGetBootTimeTimeval` to get the boot time in +alternative formats. Setting the :term:`CLOCK_REALTIME` will also set the boot +time. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +* The directive requires a :term:`Clock Driver`. + +.. Generated from spec:/rtems/clock/if/get-boot-time-timeval + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_boot_time_timeval() + +.. _InterfaceRtemsClockGetBootTimeTimeval: + +rtems_clock_get_boot_time_timeval() +----------------------------------- + +Gets the time elapsed since the :term:`Unix epoch` at some time point during +system initialization in seconds and microseconds format. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_clock_get_boot_time_timeval( struct timeval *boot_time ); + +.. rubric:: PARAMETERS: + +``boot_time`` + This parameter is the pointer to a `struct timeval + <https://pubs.opengroup.org/onlinepubs/009695399/basedefs/sys/time.h.html>`_ + object. The time elapsed since the :term:`Unix epoch` at some time point + during system initialization call will be stored in this object. Calling + the directive with a pointer equal to `NULL + <https://en.cppreference.com/w/c/types/NULL>`_ is undefined behaviour. + +.. rubric:: NOTES: + +See :ref:`InterfaceRtemsClockGetBootTime` and +:ref:`InterfaceRtemsClockGetBootTimeBintime` to get the boot time in +alternative formats. Setting the :term:`CLOCK_REALTIME` will also set the boot +time. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +* The directive requires a :term:`Clock Driver`. + .. Generated from spec:/rtems/clock/if/get-seconds-since-epoch .. raw:: latex @@ -233,10 +1086,10 @@ Gets the seconds elapsed since the :term:`RTEMS epoch` and the current .. rubric:: PARAMETERS: ``seconds_since_rtems_epoch`` - This parameter is the pointer to an interval variable. When the directive - call is successful, the seconds elapsed since the :term:`RTEMS epoch` and - the :term:`CLOCK_REALTIME` at some point during the directive call will be - stored in this variable. + This parameter is the pointer to an :ref:`InterfaceRtemsInterval` object. + When the directive call is successful, the seconds elapsed since the + :term:`RTEMS epoch` and the :term:`CLOCK_REALTIME` at some point during the + directive call will be stored in this object. .. rubric:: RETURN VALUES: @@ -369,11 +1222,11 @@ system initialization using :term:`CLOCK_MONOTONIC`. .. rubric:: PARAMETERS: ``uptime`` - This parameter is the pointer to a timeval structure variable. When the + This parameter is the pointer to a `struct timespec + <https://en.cppreference.com/w/c/chrono/timespec>`_ object. When the directive call is successful, the seconds and nanoseconds elapsed since some time point during the system initialization and some point during the - directive call using :term:`CLOCK_MONOTONIC` will be stored in this - variable. + directive call using :term:`CLOCK_MONOTONIC` will be stored in this object. .. rubric:: RETURN VALUES: @@ -419,10 +1272,11 @@ system initialization using :term:`CLOCK_MONOTONIC`. .. rubric:: PARAMETERS: ``uptime`` - This parameter is the pointer to a timeval structure variable. The seconds - and microseconds elapsed since some time point during the system - initialization and some point during the directive call using - :term:`CLOCK_MONOTONIC` will be stored in this variable. The pointer shall + This parameter is the pointer to a `struct timeval + <https://pubs.opengroup.org/onlinepubs/009695399/basedefs/sys/time.h.html>`_ + object. The seconds and microseconds elapsed since some time point during + the system initialization and some point during the directive call using + :term:`CLOCK_MONOTONIC` will be stored in this object. The pointer shall be valid, otherwise the behaviour is undefined. .. rubric:: CONSTRAINTS: diff --git a/c-user/clock/index.rst b/c-user/clock/index.rst index d84a37a..cf41998 100644 --- a/c-user/clock/index.rst +++ b/c-user/clock/index.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020 embedded brains GmbH & Co. KG .. index:: clock diff --git a/c-user/clock/introduction.rst b/c-user/clock/introduction.rst index ad4b14c..6ba814b 100644 --- a/c-user/clock/introduction.rst +++ b/c-user/clock/introduction.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2014, 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2014, 2021 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) .. This file is part of the RTEMS quality process and was automatically @@ -29,6 +29,22 @@ Introduction .. spec:/rtems/clock/if/set .. spec:/rtems/clock/if/get-tod .. spec:/rtems/clock/if/get-tod-timeval +.. spec:/rtems/clock/if/get-realtime +.. spec:/rtems/clock/if/get-realtime-bintime +.. spec:/rtems/clock/if/get-realtime-timeval +.. spec:/rtems/clock/if/get-realtime-coarse +.. spec:/rtems/clock/if/get-realtime-coarse-bintime +.. spec:/rtems/clock/if/get-realtime-coarse-timeval +.. spec:/rtems/clock/if/get-monotonic +.. spec:/rtems/clock/if/get-monotonic-bintime +.. spec:/rtems/clock/if/get-monotonic-sbintime +.. spec:/rtems/clock/if/get-monotonic-timeval +.. spec:/rtems/clock/if/get-monotonic-coarse +.. spec:/rtems/clock/if/get-monotonic-coarse-bintime +.. spec:/rtems/clock/if/get-monotonic-coarse-timeval +.. spec:/rtems/clock/if/get-boot-time +.. spec:/rtems/clock/if/get-boot-time-bintime +.. spec:/rtems/clock/if/get-boot-time-timeval .. spec:/rtems/clock/if/get-seconds-since-epoch .. spec:/rtems/clock/if/get-ticks-per-second .. spec:/rtems/clock/if/get-ticks-since-boot @@ -52,6 +68,71 @@ capabilities. The directives provided by the Clock Manager are: * :ref:`InterfaceRtemsClockGetTodTimeval` - Gets the seconds and microseconds elapsed since the :term:`Unix epoch` and the current :term:`CLOCK_REALTIME`. +* :ref:`InterfaceRtemsClockGetRealtime` - Gets the time elapsed since the + :term:`Unix epoch` measured using :term:`CLOCK_REALTIME` in seconds and + nanoseconds format. + +* :ref:`InterfaceRtemsClockGetRealtimeBintime` - Gets the time elapsed since + the :term:`Unix epoch` measured using :term:`CLOCK_REALTIME` in binary time + format. + +* :ref:`InterfaceRtemsClockGetRealtimeTimeval` - Gets the time elapsed since + the :term:`Unix epoch` measured using :term:`CLOCK_REALTIME` in seconds and + microseconds format. + +* :ref:`InterfaceRtemsClockGetRealtimeCoarse` - Gets the time elapsed since the + :term:`Unix epoch` measured using :term:`CLOCK_REALTIME` in coarse resolution + in seconds and nanoseconds format. + +* :ref:`InterfaceRtemsClockGetRealtimeCoarseBintime` - Gets the time elapsed + since the :term:`Unix epoch` measured using :term:`CLOCK_REALTIME` in coarse + resolution in binary time format. + +* :ref:`InterfaceRtemsClockGetRealtimeCoarseTimeval` - Gets the time elapsed + since the :term:`Unix epoch` measured using :term:`CLOCK_REALTIME` in coarse + resolution in seconds and microseconds format. + +* :ref:`InterfaceRtemsClockGetMonotonic` - Gets the time elapsed since some + fixed time point in the past measured using the :term:`CLOCK_MONOTONIC` in + seconds and nanoseconds format. + +* :ref:`InterfaceRtemsClockGetMonotonicBintime` - Gets the time elapsed since + some fixed time point in the past measured using the :term:`CLOCK_MONOTONIC` + in binary time format. + +* :ref:`InterfaceRtemsClockGetMonotonicSbintime` - Gets the time elapsed since + some fixed time point in the past measured using the :term:`CLOCK_MONOTONIC` + in signed binary time format. + +* :ref:`InterfaceRtemsClockGetMonotonicTimeval` - Gets the time elapsed since + some fixed time point in the past measured using the :term:`CLOCK_MONOTONIC` + in seconds and microseconds format. + +* :ref:`InterfaceRtemsClockGetMonotonicCoarse` - Gets the time elapsed since + some fixed time point in the past measured using the :term:`CLOCK_MONOTONIC` + in coarse resolution in seconds and nanoseconds format. + +* :ref:`InterfaceRtemsClockGetMonotonicCoarseBintime` - Gets the time elapsed + since some fixed time point in the past measured using the + :term:`CLOCK_MONOTONIC` in coarse resolution in binary time format. + +* :ref:`InterfaceRtemsClockGetMonotonicCoarseTimeval` - Gets the time elapsed + since some fixed time point in the past measured using the + :term:`CLOCK_MONOTONIC` in coarse resolution in seconds and microseconds + format. + +* :ref:`InterfaceRtemsClockGetBootTime` - Gets the time elapsed since the + :term:`Unix epoch` at some time point during system initialization in seconds + and nanoseconds format. + +* :ref:`InterfaceRtemsClockGetBootTimeBintime` - Gets the time elapsed since + the :term:`Unix epoch` at some time point during system initialization in + binary time format. + +* :ref:`InterfaceRtemsClockGetBootTimeTimeval` - Gets the time elapsed since + the :term:`Unix epoch` at some time point during system initialization in + seconds and microseconds format. + * :ref:`InterfaceRtemsClockGetSecondsSinceEpoch` - Gets the seconds elapsed since the :term:`RTEMS epoch` and the current :term:`CLOCK_REALTIME`. diff --git a/c-user/clock/removed-directives.rst b/c-user/clock/removed-directives.rst index d7fd775..66be74e 100644 --- a/c-user/clock/removed-directives.rst +++ b/c-user/clock/removed-directives.rst @@ -14,7 +14,7 @@ Removed Directives CLOCK_GET - Get date and time information ----------------------------------------- .. index:: obtain the time of day -.. index:: rtems_clock_get +.. index:: rtems_clock_get() .. warning:: diff --git a/c-user/config/bdbuf.rst b/c-user/config/bdbuf.rst index 7377bee..2d27d54 100644 --- a/c-user/config/bdbuf.rst +++ b/c-user/config/bdbuf.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) .. This file is part of the RTEMS quality process and was automatically @@ -28,6 +28,10 @@ This section describes configuration options related to the Block Device Cache .. Generated from spec:/acfg/if/appl-needs-libblock +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_APPLICATION_NEEDS_LIBBLOCK .. _CONFIGURE_APPLICATION_NEEDS_LIBBLOCK: @@ -35,27 +39,36 @@ This section describes configuration options related to the Block Device Cache CONFIGURE_APPLICATION_NEEDS_LIBBLOCK ------------------------------------ -CONSTANT: - ``CONFIGURE_APPLICATION_NEEDS_LIBBLOCK`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_LIBBLOCK`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: -OPTION TYPE: - This configuration option is a boolean feature define. +If this configuration option is undefined, then the described feature is not +enabled. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DESCRIPTION: -DESCRIPTION: - In case this configuration option is defined, then the Block Device Cache is - initialized during system initialization. +In case this configuration option is defined, then the Block Device Cache is +initialized during system initialization. -NOTES: - Each option of the Block Device Cache (bdbuf) configuration can be explicitly - set by the user with the configuration options below. The Block Device Cache - is used for example by the RFS and DOSFS filesystems. +.. rubric:: NOTES: + +Each option of the Block Device Cache (bdbuf) configuration can be explicitly +set by the user with the configuration options below. The Block Device Cache +is used for example by the RFS and DOSFS filesystems. .. Generated from spec:/acfg/if/bdbuf-buffer-max-size +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_BDBUF_BUFFER_MAX_SIZE .. _CONFIGURE_BDBUF_BUFFER_MAX_SIZE: @@ -63,32 +76,38 @@ NOTES: CONFIGURE_BDBUF_BUFFER_MAX_SIZE ------------------------------- -CONSTANT: - ``CONFIGURE_BDBUF_BUFFER_MAX_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_BDBUF_BUFFER_MAX_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DEFAULT VALUE: -DEFAULT VALUE: - The default value is 4096. +The default value is 4096. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: DESCRIPTION: - * It shall be greater than or equal to 0. +The value of this configuration option defines the maximum size of a buffer +in bytes. - * It shall be an integral multiple of :ref:`CONFIGURE_BDBUF_BUFFER_MIN_SIZE`. +.. rubric:: CONSTRAINTS: -DESCRIPTION: - The value of this configuration option defines the maximum size of a buffer - in bytes. +The following constraints apply to this configuration option: -NOTES: - None. +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be an integral multiple of + :ref:`CONFIGURE_BDBUF_BUFFER_MIN_SIZE`. .. Generated from spec:/acfg/if/bdbuf-buffer-min-size +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_BDBUF_BUFFER_MIN_SIZE .. _CONFIGURE_BDBUF_BUFFER_MIN_SIZE: @@ -96,28 +115,38 @@ NOTES: CONFIGURE_BDBUF_BUFFER_MIN_SIZE ------------------------------- -CONSTANT: - ``CONFIGURE_BDBUF_BUFFER_MIN_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_BDBUF_BUFFER_MIN_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DEFAULT VALUE: -DEFAULT VALUE: - The default value is 512. +The default value is 512. -VALUE CONSTRAINTS: - The value of this configuration option shall be greater than or equal to 0 - and less than or equal to `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. +.. rubric:: DESCRIPTION: -DESCRIPTION: - The value of this configuration option defines the minimum size of a buffer - in bytes. +The value of this configuration option defines the minimum size of a buffer +in bytes. -NOTES: - None. +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. .. Generated from spec:/acfg/if/bdbuf-cache-memory-size +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_BDBUF_CACHE_MEMORY_SIZE .. _CONFIGURE_BDBUF_CACHE_MEMORY_SIZE: @@ -125,28 +154,38 @@ NOTES: CONFIGURE_BDBUF_CACHE_MEMORY_SIZE --------------------------------- -CONSTANT: - ``CONFIGURE_BDBUF_CACHE_MEMORY_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_BDBUF_CACHE_MEMORY_SIZE`` -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: OPTION TYPE: -DEFAULT VALUE: - The default value is 32768. +This configuration option is an integer define. -VALUE CONSTRAINTS: - The value of this configuration option shall be greater than or equal to 0 - and less than or equal to `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_. +.. rubric:: DEFAULT VALUE: -DESCRIPTION: - The value of this configuration option defines the size of the cache memory - in bytes. +The default value is 32768. -NOTES: - None. +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the size of the cache memory +in bytes. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_. .. Generated from spec:/acfg/if/bdbuf-max-read-ahead-blocks +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_BDBUF_MAX_READ_AHEAD_BLOCKS .. _CONFIGURE_BDBUF_MAX_READ_AHEAD_BLOCKS: @@ -154,30 +193,44 @@ NOTES: CONFIGURE_BDBUF_MAX_READ_AHEAD_BLOCKS ------------------------------------- -CONSTANT: - ``CONFIGURE_BDBUF_MAX_READ_AHEAD_BLOCKS`` +.. rubric:: CONSTANT: + +``CONFIGURE_BDBUF_MAX_READ_AHEAD_BLOCKS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DESCRIPTION: -DEFAULT VALUE: - The default value is 0. +The value of this configuration option defines the maximum blocks per +read-ahead request. -VALUE CONSTRAINTS: - The value of this configuration option shall be greater than or equal to 0 - and less than or equal to `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. +.. rubric:: NOTES: -DESCRIPTION: - The value of this configuration option defines the maximum blocks per - read-ahead request. +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. +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. .. Generated from spec:/acfg/if/bdbuf-max-write-blocks +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_BDBUF_MAX_WRITE_BLOCKS .. _CONFIGURE_BDBUF_MAX_WRITE_BLOCKS: @@ -185,28 +238,38 @@ NOTES: CONFIGURE_BDBUF_MAX_WRITE_BLOCKS -------------------------------- -CONSTANT: - ``CONFIGURE_BDBUF_MAX_WRITE_BLOCKS`` +.. rubric:: CONSTANT: + +``CONFIGURE_BDBUF_MAX_WRITE_BLOCKS`` -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: OPTION TYPE: -DEFAULT VALUE: - The default value is 16. +This configuration option is an integer define. -VALUE CONSTRAINTS: - The value of this configuration option shall be greater than or equal to 0 - and less than or equal to `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. +.. rubric:: DEFAULT VALUE: -DESCRIPTION: - The value of this configuration option defines the maximum blocks per write - request. +The default value is 16. -NOTES: - None. +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the maximum blocks per write +request. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. .. Generated from spec:/acfg/if/bdbuf-read-ahead-task-priority +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY .. _CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY: @@ -214,27 +277,34 @@ NOTES: CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY ---------------------------------------- -CONSTANT: - ``CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY`` +.. rubric:: CONSTANT: + +``CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is an integer define. +This configuration option is an integer define. -DEFAULT VALUE: - The default value is 15. +.. rubric:: DEFAULT VALUE: -VALUE CONSTRAINTS: - The value of this configuration option shall be a valid Classic API task - priority. The set of valid task priorities is scheduler-specific. +The default value is 15. -DESCRIPTION: - The value of this configuration option defines the read-ahead task priority. +.. rubric:: DESCRIPTION: -NOTES: - None. +The value of this configuration option defines the read-ahead task priority. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be a valid Classic API task +priority. The set of valid task priorities depends on the scheduler +configuration. .. Generated from spec:/acfg/if/bdbuf-task-stack-size +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_BDBUF_TASK_STACK_SIZE .. _CONFIGURE_BDBUF_TASK_STACK_SIZE: @@ -242,38 +312,45 @@ NOTES: CONFIGURE_BDBUF_TASK_STACK_SIZE ------------------------------- -CONSTANT: - ``CONFIGURE_BDBUF_TASK_STACK_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_BDBUF_TASK_STACK_SIZE`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is an integer define. +This configuration option is an integer define. -DEFAULT VALUE: - The default value is :c:macro:`RTEMS_MINIMUM_STACK_SIZE`. +.. rubric:: DEFAULT VALUE: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The default value is :c:macro:`RTEMS_MINIMUM_STACK_SIZE`. - * It shall be greater than or equal to :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. +.. rubric:: DESCRIPTION: - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +The value of this configuration option defines the task stack size of the +Block Device Cache tasks in bytes. - * It shall be small enough so that the task - stack space calculation carried out by ``<rtems/confdefs.h>`` does not - overflow an integer of type `uintptr_t <https://en.cppreference.com/w/c/types/integer>`_. +.. rubric:: CONSTRAINTS: -DESCRIPTION: - The value of this configuration option defines the task stack size of the - Block Device Cache tasks in bytes. +The following constraints apply to this configuration option: -NOTES: - None. +* The value of the configuration option shall be greater than or equal to + :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +* The value of the configuration option shall be small enough so that the task + stack space calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. .. Generated from spec:/acfg/if/bdbuf-swapout-block-hold +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_SWAPOUT_BLOCK_HOLD .. _CONFIGURE_SWAPOUT_BLOCK_HOLD: @@ -281,28 +358,38 @@ NOTES: CONFIGURE_SWAPOUT_BLOCK_HOLD ---------------------------- -CONSTANT: - ``CONFIGURE_SWAPOUT_BLOCK_HOLD`` +.. rubric:: CONSTANT: + +``CONFIGURE_SWAPOUT_BLOCK_HOLD`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 1000. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DESCRIPTION: -DEFAULT VALUE: - The default value is 1000. +The value of this configuration option defines the swapout task maximum block +hold time in milliseconds. -VALUE CONSTRAINTS: - The value of this configuration option shall be greater than or equal to 0 - and less than or equal to `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. +.. rubric:: CONSTRAINTS: -DESCRIPTION: - The value of this configuration option defines the swapout task maximum block - hold time in milliseconds. +The following constraints apply to this configuration option: -NOTES: - None. +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. .. Generated from spec:/acfg/if/bdbuf-swapout-swap-period +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_SWAPOUT_SWAP_PERIOD .. _CONFIGURE_SWAPOUT_SWAP_PERIOD: @@ -310,28 +397,38 @@ NOTES: CONFIGURE_SWAPOUT_SWAP_PERIOD ----------------------------- -CONSTANT: - ``CONFIGURE_SWAPOUT_SWAP_PERIOD`` +.. rubric:: CONSTANT: + +``CONFIGURE_SWAPOUT_SWAP_PERIOD`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DEFAULT VALUE: -DEFAULT VALUE: - The default value is 250. +The default value is 250. -VALUE CONSTRAINTS: - The value of this configuration option shall be greater than or equal to 0 - and less than or equal to `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. +.. rubric:: DESCRIPTION: -DESCRIPTION: - The value of this configuration option defines the swapout task swap period - in milliseconds. +The value of this configuration option defines the swapout task swap period +in milliseconds. -NOTES: - None. +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. .. Generated from spec:/acfg/if/bdbuf-swapout-task-priority +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_SWAPOUT_TASK_PRIORITY .. _CONFIGURE_SWAPOUT_TASK_PRIORITY: @@ -339,27 +436,34 @@ NOTES: CONFIGURE_SWAPOUT_TASK_PRIORITY ------------------------------- -CONSTANT: - ``CONFIGURE_SWAPOUT_TASK_PRIORITY`` +.. rubric:: CONSTANT: + +``CONFIGURE_SWAPOUT_TASK_PRIORITY`` -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: OPTION TYPE: -DEFAULT VALUE: - The default value is 15. +This configuration option is an integer define. -VALUE CONSTRAINTS: - The value of this configuration option shall be a valid Classic API task - priority. The set of valid task priorities is scheduler-specific. +.. rubric:: DEFAULT VALUE: -DESCRIPTION: - The value of this configuration option defines the swapout task priority. +The default value is 15. -NOTES: - None. +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the swapout task priority. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be a valid Classic API task +priority. The set of valid task priorities depends on the scheduler +configuration. .. Generated from spec:/acfg/if/bdbuf-swapout-worker-tasks +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_SWAPOUT_WORKER_TASKS .. _CONFIGURE_SWAPOUT_WORKER_TASKS: @@ -367,27 +471,37 @@ NOTES: CONFIGURE_SWAPOUT_WORKER_TASKS ------------------------------ -CONSTANT: - ``CONFIGURE_SWAPOUT_WORKER_TASKS`` +.. rubric:: CONSTANT: + +``CONFIGURE_SWAPOUT_WORKER_TASKS`` -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: OPTION TYPE: -DEFAULT VALUE: - The default value is 0. +This configuration option is an integer define. -VALUE CONSTRAINTS: - The value of this configuration option shall be greater than or equal to 0 - and less than or equal to `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. +.. rubric:: DEFAULT VALUE: -DESCRIPTION: - The value of this configuration option defines the swapout worker task count. +The default value is 0. -NOTES: - None. +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the swapout worker task count. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. .. Generated from spec:/acfg/if/bdbuf-swapout-worker-taskp-riority +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY .. _CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY: @@ -395,22 +509,25 @@ NOTES: CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY -------------------------------------- -CONSTANT: - ``CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY`` +.. rubric:: CONSTANT: + +``CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: -OPTION TYPE: - This configuration option is an integer define. +The default value is 15. -DEFAULT VALUE: - The default value is 15. +.. rubric:: DESCRIPTION: -VALUE CONSTRAINTS: - The value of this configuration option shall be a valid Classic API task - priority. The set of valid task priorities is scheduler-specific. +The value of this configuration option defines the swapout worker task +priority. -DESCRIPTION: - The value of this configuration option defines the swapout worker task - priority. +.. rubric:: CONSTRAINTS: -NOTES: - None. +The value of the configuration option shall be a valid Classic API task +priority. The set of valid task priorities depends on the scheduler +configuration. diff --git a/c-user/config/bsp-related.rst b/c-user/config/bsp-related.rst deleted file mode 100644 index e56cee4..0000000 --- a/c-user/config/bsp-related.rst +++ /dev/null @@ -1,299 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-4.0 - -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) - -.. This file is part of the RTEMS quality process and was automatically -.. generated. If you find something that needs to be fixed or -.. worded better please post a report or patch to an RTEMS mailing list -.. or raise a bug report: -.. -.. https://www.rtems.org/bugs.html -.. -.. For information on updating and regenerating please refer to the How-To -.. section in the Software Requirements Engineering chapter of the -.. RTEMS Software Engineering manual. The manual is provided as a part of -.. a release. For development sources please refer to the online -.. documentation at: -.. -.. https://docs.rtems.org - -.. Generated from spec:/acfg/if/group-bsp - -BSP Related Configuration Options -================================= - -This section describes configuration options related to the BSP. Some -configuration options may have a BSP-specific setting which is defined by -``<bsp.h>``. The BSP-specific settings can be disabled by the -:ref:`CONFIGURE_DISABLE_BSP_SETTINGS` configuration option. - -.. Generated from spec:/acfg/if/bsp-idle-task-body - -.. index:: BSP_IDLE_TASK_BODY - -.. _BSP_IDLE_TASK_BODY: - -BSP_IDLE_TASK_BODY ------------------- - -CONSTANT: - ``BSP_IDLE_TASK_BODY`` - -OPTION TYPE: - This configuration option is an initializer define. - -DEFAULT VALUE: - The default value is BSP-specific. - -VALUE CONSTRAINTS: - The value of this configuration option shall be defined to a valid function - pointer of the type ``void *( *idle_body )( uintptr_t )``. - -DESCRIPTION: - If - - * this configuration option is defined by the BSP - - * and :ref:`CONFIGURE_DISABLE_BSP_SETTINGS` is undefined, - - then the value of this configuration option defines the default value of - :ref:`CONFIGURE_IDLE_TASK_BODY`. - -NOTES: - As it has knowledge of the specific CPU model, system controller logic, and - peripheral buses, a BSP-specific IDLE task may be capable of turning - components off to save power during extended periods of no task activity. - -.. Generated from spec:/acfg/if/bsp-idle-task-stack-size - -.. index:: BSP_IDLE_TASK_STACK_SIZE - -.. _BSP_IDLE_TASK_STACK_SIZE: - -BSP_IDLE_TASK_STACK_SIZE ------------------------- - -CONSTANT: - ``BSP_IDLE_TASK_STACK_SIZE`` - -OPTION TYPE: - This configuration option is an integer define. - -DEFAULT VALUE: - The default value is BSP-specific. - -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: - - * It shall be greater than or equal to a - BSP-specific and application-specific minimum value. - - * It shall be small enough so that the IDLE - task stack area calculation carried out by ``<rtems/confdefs.h>`` does not - overflow an integer of type `size_t <https://en.cppreference.com/w/c/types/size_t>`_. - -DESCRIPTION: - If - - * this configuration option is defined by the BSP - - * and :ref:`CONFIGURE_DISABLE_BSP_SETTINGS` is undefined, - - then the value of this configuration option defines the default value of - :ref:`CONFIGURE_IDLE_TASK_STACK_SIZE`. - -NOTES: - None. - -.. Generated from spec:/acfg/if/bsp-initial-extension - -.. index:: BSP_INITIAL_EXTENSION - -.. _BSP_INITIAL_EXTENSION: - -BSP_INITIAL_EXTENSION ---------------------- - -CONSTANT: - ``BSP_INITIAL_EXTENSION`` - -OPTION TYPE: - This configuration option is an initializer define. - -DEFAULT VALUE: - The default value is BSP-specific. - -VALUE CONSTRAINTS: - The value of this configuration option shall be a list of initializers for - structures of type :c:type:`rtems_extensions_table`. - -DESCRIPTION: - If - - * this configuration option is defined by the BSP - - * and :ref:`CONFIGURE_DISABLE_BSP_SETTINGS` is undefined, - - then the value of this configuration option is used to initialize the table - of initial user extensions. - -NOTES: - The value of this configuration option is placed after the entries of all - other initial user extensions. - -.. Generated from spec:/acfg/if/bsp-interrupt-stack-size - -.. index:: BSP_INTERRUPT_STACK_SIZE - -.. _BSP_INTERRUPT_STACK_SIZE: - -BSP_INTERRUPT_STACK_SIZE ------------------------- - -CONSTANT: - ``BSP_INTERRUPT_STACK_SIZE`` - -OPTION TYPE: - This configuration option is an integer define. - -DEFAULT VALUE: - The default value is BSP-specific. - -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: - - * It shall be greater than or equal to a - BSP-specific and application-specific minimum value. - - * It shall be small enough so that the - interrupt stack area calculation carried out by ``<rtems/confdefs.h>`` does - not overflow an integer of type `size_t <https://en.cppreference.com/w/c/types/size_t>`_. - - * It shall be aligned according to - :c:macro:`CPU_INTERRUPT_STACK_ALIGNMENT`. - -DESCRIPTION: - If - - * this configuration option is defined by the BSP - - * and :ref:`CONFIGURE_DISABLE_BSP_SETTINGS` is undefined, - - then the value of this configuration option defines the default value of - :ref:`CONFIGURE_INTERRUPT_STACK_SIZE`. - -NOTES: - None. - -.. Generated from spec:/acfg/if/bsp-prerequisite-drivers - -.. index:: CONFIGURE_BSP_PREREQUISITE_DRIVERS - -.. _CONFIGURE_BSP_PREREQUISITE_DRIVERS: - -CONFIGURE_BSP_PREREQUISITE_DRIVERS ----------------------------------- - -CONSTANT: - ``CONFIGURE_BSP_PREREQUISITE_DRIVERS`` - -OPTION TYPE: - This configuration option is an initializer define. - -DEFAULT VALUE: - The default value is BSP-specific. - -VALUE CONSTRAINTS: - The value of this configuration option shall be a list of initializers for - structures of type :c:type:`rtems_extensions_table`. - -DESCRIPTION: - If - - * this configuration option is defined by the BSP - - * and :ref:`CONFIGURE_DISABLE_BSP_SETTINGS` is undefined, - - then the value of this configuration option is used to initialize the table - of initial user extensions. - -NOTES: - The value of this configuration option is placed before the entries of all - other initial user extensions (including - :ref:`CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS`). - -.. Generated from spec:/acfg/if/disable-bsp-settings - -.. index:: CONFIGURE_DISABLE_BSP_SETTINGS - -.. _CONFIGURE_DISABLE_BSP_SETTINGS: - -CONFIGURE_DISABLE_BSP_SETTINGS ------------------------------- - -CONSTANT: - ``CONFIGURE_DISABLE_BSP_SETTINGS`` - -OPTION TYPE: - This configuration option is a boolean feature define. - -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. - -DESCRIPTION: - In case this configuration option is defined, then the following BSP related - configuration options are undefined: - - * :ref:`BSP_IDLE_TASK_BODY` - - * :ref:`BSP_IDLE_TASK_STACK_SIZE` - - * :ref:`BSP_INITIAL_EXTENSION` - - * :ref:`BSP_INTERRUPT_STACK_SIZE` - - * :ref:`CONFIGURE_BSP_PREREQUISITE_DRIVERS` - - * :ref:`CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK` - -NOTES: - None. - -.. Generated from spec:/acfg/if/malloc-bsp-supports-sbrk - -.. index:: CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK - -.. _CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK: - -CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK ----------------------------------- - -CONSTANT: - ``CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK`` - -OPTION TYPE: - This configuration option is a boolean feature define. - -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. - -DESCRIPTION: - If - - * this configuration option is defined by the BSP - - * and :ref:`CONFIGURE_DISABLE_BSP_SETTINGS` is undefined, - - then not all memory is made available to the C Program Heap immediately at - system initialization time. When :c:func:`malloc` or other standard - memory allocation functions are unable to allocate memory, they will call the - BSP supplied :c:func:`sbrk` function to obtain more memory. - -NOTES: - This option should not be defined by the application. Only the BSP knows how - it allocates memory to the C Program Heap. diff --git a/c-user/config/classic-api.rst b/c-user/config/classic-api.rst index 74a8257..212f666 100644 --- a/c-user/config/classic-api.rst +++ b/c-user/config/classic-api.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) .. This file is part of the RTEMS quality process and was automatically @@ -27,6 +27,10 @@ This section describes configuration options related to the Classic API. .. Generated from spec:/acfg/if/max-barriers +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MAXIMUM_BARRIERS .. _CONFIGURE_MAXIMUM_BARRIERS: @@ -34,42 +38,51 @@ This section describes configuration options related to the Classic API. CONFIGURE_MAXIMUM_BARRIERS -------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_BARRIERS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_BARRIERS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: -OPTION TYPE: - This configuration option is an integer define. +The default value is 0. -DEFAULT VALUE: - The default value is 0. +.. rubric:: DESCRIPTION: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The value of this configuration option defines the maximum number of Classic +API Barriers that can be concurrently active. - * It shall be greater than or equal to 0. +.. rubric:: NOTES: - * It shall be less than or equal to 65535. +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +.. rubric:: CONSTRAINTS: - * It may be defined through - :c:func:`rtems_resource_unlimited` the enable unlimited objects for this - object class, if the value passed to :c:func:`rtems_resource_unlimited` - satisfies all other constraints of this configuration option. +The following constraints apply to this configuration option: -DESCRIPTION: - The value of this configuration option defines the maximum number of Classic - API Barriers that can be concurrently active. +* The value of the configuration option shall be greater than or equal to zero. -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +* The value of the configuration option may be defined through + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` + satisfies all other constraints of the configuration option. .. Generated from spec:/acfg/if/max-message-queues +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MAXIMUM_MESSAGE_QUEUES .. _CONFIGURE_MAXIMUM_MESSAGE_QUEUES: @@ -77,44 +90,53 @@ NOTES: CONFIGURE_MAXIMUM_MESSAGE_QUEUES -------------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_MESSAGE_QUEUES`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_MESSAGE_QUEUES`` -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: OPTION TYPE: -DEFAULT VALUE: - The default value is 0. +This configuration option is an integer define. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: DEFAULT VALUE: - * It shall be greater than or equal to 0. +The default value is 0. - * It shall be less than or equal to 65535. +.. rubric:: DESCRIPTION: - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +The value of this configuration option defines the maximum number of Classic +API Message Queues that can be concurrently active. - * It may be defined through - :c:func:`rtems_resource_unlimited` the enable unlimited objects for this - object class, if the value passed to :c:func:`rtems_resource_unlimited` - satisfies all other constraints of this configuration option. +.. rubric:: NOTES: -DESCRIPTION: - The value of this configuration option defines the maximum number of Classic - API Message Queues that can be concurrently active. +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. You have to account for the memory used to +store the messages of each message queue, see +:ref:`CONFIGURE_MESSAGE_BUFFER_MEMORY`. -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. You have to account for the memory used to - store the messages of each message queue, see - :ref:`CONFIGURE_MESSAGE_BUFFER_MEMORY`. +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +* The value of the configuration option may be defined through + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` + satisfies all other constraints of the configuration option. .. Generated from spec:/acfg/if/max-partitions +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MAXIMUM_PARTITIONS .. _CONFIGURE_MAXIMUM_PARTITIONS: @@ -122,42 +144,51 @@ NOTES: CONFIGURE_MAXIMUM_PARTITIONS ---------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_PARTITIONS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_PARTITIONS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: -OPTION TYPE: - This configuration option is an integer define. +The default value is 0. -DEFAULT VALUE: - The default value is 0. +.. rubric:: DESCRIPTION: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The value of this configuration option defines the maximum number of Classic +API Partitions that can be concurrently active. - * It shall be greater than or equal to 0. +.. rubric:: NOTES: - * It shall be less than or equal to 65535. +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +.. rubric:: CONSTRAINTS: - * It may be defined through - :c:func:`rtems_resource_unlimited` the enable unlimited objects for this - object class, if the value passed to :c:func:`rtems_resource_unlimited` - satisfies all other constraints of this configuration option. +The following constraints apply to this configuration option: -DESCRIPTION: - The value of this configuration option defines the maximum number of Classic - API Partitions that can be concurrently active. +* The value of the configuration option shall be greater than or equal to zero. -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +* The value of the configuration option may be defined through + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` + satisfies all other constraints of the configuration option. .. Generated from spec:/acfg/if/max-periods +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MAXIMUM_PERIODS .. _CONFIGURE_MAXIMUM_PERIODS: @@ -165,42 +196,51 @@ NOTES: CONFIGURE_MAXIMUM_PERIODS ------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_PERIODS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_PERIODS`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is an integer define. +This configuration option is an integer define. -DEFAULT VALUE: - The default value is 0. +.. rubric:: DEFAULT VALUE: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The default value is 0. - * It shall be greater than or equal to 0. +.. rubric:: DESCRIPTION: - * It shall be less than or equal to 65535. +The value of this configuration option defines the maximum number of Classic +API Periods that can be concurrently active. - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +.. rubric:: NOTES: - * It may be defined through - :c:func:`rtems_resource_unlimited` the enable unlimited objects for this - object class, if the value passed to :c:func:`rtems_resource_unlimited` - satisfies all other constraints of this configuration option. +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. -DESCRIPTION: - The value of this configuration option defines the maximum number of Classic - API Periods that can be concurrently active. +.. rubric:: CONSTRAINTS: -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +* The value of the configuration option may be defined through + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` + satisfies all other constraints of the configuration option. .. Generated from spec:/acfg/if/max-ports +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MAXIMUM_PORTS .. _CONFIGURE_MAXIMUM_PORTS: @@ -208,42 +248,51 @@ NOTES: CONFIGURE_MAXIMUM_PORTS ----------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_PORTS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_PORTS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: -OPTION TYPE: - This configuration option is an integer define. +The default value is 0. -DEFAULT VALUE: - The default value is 0. +.. rubric:: DESCRIPTION: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The value of this configuration option defines the maximum number of Classic +API Ports that can be concurrently active. - * It shall be greater than or equal to 0. +.. rubric:: NOTES: - * It shall be less than or equal to 65535. +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +.. rubric:: CONSTRAINTS: - * It may be defined through - :c:func:`rtems_resource_unlimited` the enable unlimited objects for this - object class, if the value passed to :c:func:`rtems_resource_unlimited` - satisfies all other constraints of this configuration option. +The following constraints apply to this configuration option: -DESCRIPTION: - The value of this configuration option defines the maximum number of Classic - API Ports that can be concurrently active. +* The value of the configuration option shall be greater than or equal to zero. -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +* The value of the configuration option may be defined through + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` + satisfies all other constraints of the configuration option. .. Generated from spec:/acfg/if/max-regions +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MAXIMUM_REGIONS .. _CONFIGURE_MAXIMUM_REGIONS: @@ -251,42 +300,51 @@ NOTES: CONFIGURE_MAXIMUM_REGIONS ------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_REGIONS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_REGIONS`` -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: OPTION TYPE: -DEFAULT VALUE: - The default value is 0. +This configuration option is an integer define. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: DEFAULT VALUE: - * It shall be greater than or equal to 0. +The default value is 0. - * It shall be less than or equal to 65535. +.. rubric:: DESCRIPTION: - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +The value of this configuration option defines the maximum number of Classic +API Regions that can be concurrently active. - * It may be defined through - :c:func:`rtems_resource_unlimited` the enable unlimited objects for this - object class, if the value passed to :c:func:`rtems_resource_unlimited` - satisfies all other constraints of this configuration option. +.. rubric:: NOTES: -DESCRIPTION: - The value of this configuration option defines the maximum number of Classic - API Regions that can be concurrently active. +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +* The value of the configuration option may be defined through + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` + satisfies all other constraints of the configuration option. .. Generated from spec:/acfg/if/max-semaphores +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MAXIMUM_SEMAPHORES .. _CONFIGURE_MAXIMUM_SEMAPHORES: @@ -294,157 +352,124 @@ NOTES: CONFIGURE_MAXIMUM_SEMAPHORES ---------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_SEMAPHORES`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is an integer define. +``CONFIGURE_MAXIMUM_SEMAPHORES`` -DEFAULT VALUE: - The default value is 0. +.. rubric:: OPTION TYPE: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +This configuration option is an integer define. - * It shall be greater than or equal to 0. +.. rubric:: DEFAULT VALUE: - * It shall be less than or equal to 65535. +The default value is 0. - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +.. rubric:: DESCRIPTION: - * It may be defined through - :c:func:`rtems_resource_unlimited` the enable unlimited objects for this - object class, if the value passed to :c:func:`rtems_resource_unlimited` - satisfies all other constraints of this configuration option. +The value of this configuration option defines the maximum number of Classic +API Semaphore that can be concurrently active. -DESCRIPTION: - The value of this configuration option defines the maximum number of Classic - API Semaphore that can be concurrently active. +.. rubric:: NOTES: -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. - In SMP configurations, the size of a Semaphore Control Block depends on the - scheduler count (see :ref:`ConfigurationSchedulerTable`). The semaphores - using the :ref:`MrsP` need a ceiling priority per scheduler. +In SMP configurations, the size of a Semaphore Control Block depends on the +scheduler count (see :ref:`ConfigurationSchedulerTable`). The semaphores +using the :ref:`MrsP` need a ceiling priority per scheduler. -.. Generated from spec:/acfg/if/max-tasks +.. rubric:: CONSTRAINTS: -.. index:: CONFIGURE_MAXIMUM_TASKS +The following constraints apply to this configuration option: -.. _CONFIGURE_MAXIMUM_TASKS: +* The value of the configuration option shall be greater than or equal to zero. -CONFIGURE_MAXIMUM_TASKS ------------------------ +* The value of the configuration option shall be less than or equal to 65535. -CONSTANT: - ``CONFIGURE_MAXIMUM_TASKS`` +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. -OPTION TYPE: - This configuration option is an integer define. +* The value of the configuration option may be defined through + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` + satisfies all other constraints of the configuration option. -DEFAULT VALUE: - The default value is 0. +.. Generated from spec:/acfg/if/max-tasks -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. raw:: latex - * It shall be greater than or equal to 0. + \clearpage - * It shall be less than or equal to 65535. +.. index:: CONFIGURE_MAXIMUM_TASKS - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +.. _CONFIGURE_MAXIMUM_TASKS: - * It shall be small enough so that the task - stack space calculation carried out by ``<rtems/confdefs.h>`` does not - overflow an integer of type `uintptr_t <https://en.cppreference.com/w/c/types/integer>`_. +CONFIGURE_MAXIMUM_TASKS +----------------------- - * It may be defined through - :c:func:`rtems_resource_unlimited` the enable unlimited objects for this - object class, if the value passed to :c:func:`rtems_resource_unlimited` - satisfies all other constraints of this configuration option. +.. rubric:: CONSTANT: -DESCRIPTION: - The value of this configuration option defines the maximum number of Classic - API Tasks that can be concurrently active. +``CONFIGURE_MAXIMUM_TASKS`` -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. +.. rubric:: OPTION TYPE: - The calculations for the required memory in the RTEMS Workspace for tasks - assume that each task has a minimum stack size and has floating point - support enabled. The configuration option :ref:`CONFIGURE_EXTRA_TASK_STACKS` is used - to specify task stack requirements *above* the minimum size required. +This configuration option is an integer define. - The maximum number of POSIX threads is specified by - :ref:`CONFIGURE_MAXIMUM_POSIX_THREADS`. +.. rubric:: DEFAULT VALUE: - A future enhancement to ``<rtems/confdefs.h>`` could be to eliminate the - assumption that all tasks have floating point enabled. This would require - the addition of a new configuration parameter to specify the number of - tasks which enable floating point support. +The default value is 0. -.. Generated from spec:/acfg/if/max-thread-local-storage-size +.. rubric:: DESCRIPTION: -.. index:: CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE +The value of this configuration option defines the maximum number of Classic +API Tasks that can be concurrently active. -.. _CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE: +.. rubric:: NOTES: -CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE -------------------------------------------- +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. -CONSTANT: - ``CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE`` +The calculations for the required memory in the RTEMS Workspace for tasks +assume that each task has a minimum stack size and has floating point +support enabled. The configuration option :ref:`CONFIGURE_EXTRA_TASK_STACKS` is used +to specify task stack requirements *above* the minimum size required. -OPTION TYPE: - This configuration option is an integer define. +The maximum number of POSIX threads is specified by +:ref:`CONFIGURE_MAXIMUM_POSIX_THREADS`. -DEFAULT VALUE: - The default value is 0. +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. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: CONSTRAINTS: - * It shall be greater than or equal to 0. +The following constraints apply to this configuration option: - * It shall be less than or equal to `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_. +* The value of the configuration option shall be greater than or equal to zero. - * It shall be an integral multiple of :c:macro:`RTEMS_TASK_STORAGE_ALIGNMENT`. +* The value of the configuration option shall be less than or equal to 65535. -DESCRIPTION: - If the value of this configuration option is greater than zero, then it - defines the maximum thread-local storage size, otherwise the thread-local - storage size is defined by the linker depending on the thread-local storage - objects used by the application in the statically-linked executable. +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. -NOTES: - This configuration option can be used to reserve space for the dynamic linking - of modules with thread-local storage objects. +* The value of the configuration option shall be small enough so that the task + stack space calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. - If the thread-local storage size defined by the thread-local storage - objects used by the application in the statically-linked executable is greater - than a non-zero value of this configuration option, then a fatal error will - occur during system initialization. +* The value of the configuration option may be defined through + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` + satisfies all other constraints of the configuration option. - Use :c:func:`RTEMS_ALIGN_UP` and - :c:macro:`RTEMS_TASK_STORAGE_ALIGNMENT` to adjust the size to meet the - minimum alignment requirement of a thread-local storage area. +.. Generated from spec:/acfg/if/max-timers - The actual thread-local storage size is determined when the application - executable is linked. The ``rtems-exeinfo`` command line tool included in - the RTEMS Tools can be used to obtain the thread-local storage size and - alignment of an application executable. +.. raw:: latex -.. Generated from spec:/acfg/if/max-timers + \clearpage .. index:: CONFIGURE_MAXIMUM_TIMERS @@ -453,42 +478,51 @@ NOTES: CONFIGURE_MAXIMUM_TIMERS ------------------------ -CONSTANT: - ``CONFIGURE_MAXIMUM_TIMERS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_TIMERS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DEFAULT VALUE: -DEFAULT VALUE: - The default value is 0. +The default value is 0. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: DESCRIPTION: - * It shall be greater than or equal to 0. +The value of this configuration option defines the maximum number of Classic +API Timers that can be concurrently active. - * It shall be less than or equal to 65535. +.. rubric:: NOTES: - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. - * It may be defined through - :c:func:`rtems_resource_unlimited` the enable unlimited objects for this - object class, if the value passed to :c:func:`rtems_resource_unlimited` - satisfies all other constraints of this configuration option. +.. rubric:: CONSTRAINTS: -DESCRIPTION: - The value of this configuration option defines the maximum number of Classic - API Timers that can be concurrently active. +The following constraints apply to this configuration option: -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +* The value of the configuration option may be defined through + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` + satisfies all other constraints of the configuration option. .. Generated from spec:/acfg/if/max-user-extensions +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MAXIMUM_USER_EXTENSIONS .. _CONFIGURE_MAXIMUM_USER_EXTENSIONS: @@ -496,36 +530,45 @@ NOTES: CONFIGURE_MAXIMUM_USER_EXTENSIONS --------------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_USER_EXTENSIONS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_USER_EXTENSIONS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is an integer define. +The value of this configuration option defines the maximum number of Classic +API User Extensions that can be concurrently active. -DEFAULT VALUE: - The default value is 0. +.. rubric:: NOTES: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +This object class cannot be configured in unlimited allocation mode. - * It shall be greater than or equal to 0. +.. rubric:: CONSTRAINTS: - * It shall be less than or equal to 65535. +The following constraints apply to this configuration option: - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +* The value of the configuration option shall be greater than or equal to zero. -DESCRIPTION: - The value of this configuration option defines the maximum number of Classic - API User Extensions that can be concurrently active. +* The value of the configuration option shall be less than or equal to 65535. -NOTES: - This object class cannot be configured in unlimited allocation mode. +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. .. Generated from spec:/acfg/if/min-tasks-with-user-provided-storage +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MINIMUM_TASKS_WITH_USER_PROVIDED_STORAGE .. _CONFIGURE_MINIMUM_TASKS_WITH_USER_PROVIDED_STORAGE: @@ -533,27 +576,37 @@ NOTES: CONFIGURE_MINIMUM_TASKS_WITH_USER_PROVIDED_STORAGE -------------------------------------------------- -CONSTANT: - ``CONFIGURE_MINIMUM_TASKS_WITH_USER_PROVIDED_STORAGE`` +.. rubric:: CONSTANT: + +``CONFIGURE_MINIMUM_TASKS_WITH_USER_PROVIDED_STORAGE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the minimum count of Classic +API Tasks which are constructed by :ref:`InterfaceRtemsTaskConstruct`. + +.. rubric:: NOTES: -OPTION TYPE: - This configuration option is an integer define. +By default, the calculation for the required memory in the RTEMS Workspace +for tasks assumes that all Classic API Tasks are created by +:ref:`InterfaceRtemsTaskCreate`. This configuration option can be used to +reduce the required memory for the system-provided task storage areas since +tasks constructed by :ref:`InterfaceRtemsTaskConstruct` use a user-provided +task storage area. -DEFAULT VALUE: - The default value is 0. +.. rubric:: CONSTRAINTS: -VALUE CONSTRAINTS: - The value of this configuration option shall be greater than or equal to 0 - and less than or equal to :ref:`CONFIGURE_MAXIMUM_TASKS`. +The following constraints apply to this configuration option: -DESCRIPTION: - The value of this configuration option defines the minimum count of Classic - API Tasks which are constructed by :c:func:`rtems_task_construct`. +* The value of the configuration option shall be greater than or equal to zero. -NOTES: - By default, the calculation for the required memory in the RTEMS Workspace - for tasks assumes that all Classic API Tasks are created by - :c:func:`rtems_task_create`. This configuration option can be used to - reduce the required memory for the system-provided task storage areas since - tasks constructed by :c:func:`rtems_task_construct` use a user-provided - task storage area. +* The value of the configuration option shall be less than or equal to + :ref:`CONFIGURE_MAXIMUM_TASKS`. diff --git a/c-user/config/classic-init-task.rst b/c-user/config/classic-init-task.rst index 0743929..f65bb8a 100644 --- a/c-user/config/classic-init-task.rst +++ b/c-user/config/classic-init-task.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) .. This file is part of the RTEMS quality process and was automatically @@ -28,6 +28,10 @@ initialization task. .. Generated from spec:/acfg/if/init-task-arguments +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_INIT_TASK_ARGUMENTS .. _CONFIGURE_INIT_TASK_ARGUMENTS: @@ -35,28 +39,34 @@ initialization task. CONFIGURE_INIT_TASK_ARGUMENTS ----------------------------- -CONSTANT: - ``CONFIGURE_INIT_TASK_ARGUMENTS`` +.. rubric:: CONSTANT: + +``CONFIGURE_INIT_TASK_ARGUMENTS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DEFAULT VALUE: -DEFAULT VALUE: - The default value is 0. +The default value is 0. -VALUE CONSTRAINTS: - The value of this configuration option shall be a valid integer of type - :c:type:`rtems_task_argument`. +.. rubric:: DESCRIPTION: -DESCRIPTION: - The value of this configuration option defines task argument of the Classic - API initialization task. +The value of this configuration option defines task argument of the Classic +API initialization task. -NOTES: - None. +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be convertible to an integer of +type :ref:`InterfaceRtemsTaskArgument`. .. Generated from spec:/acfg/if/init-task-attributes +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_INIT_TASK_ATTRIBUTES .. _CONFIGURE_INIT_TASK_ATTRIBUTES: @@ -64,27 +74,33 @@ NOTES: CONFIGURE_INIT_TASK_ATTRIBUTES ------------------------------ -CONSTANT: - ``CONFIGURE_INIT_TASK_ATTRIBUTES`` +.. rubric:: CONSTANT: + +``CONFIGURE_INIT_TASK_ATTRIBUTES`` -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: OPTION TYPE: -DEFAULT VALUE: - The default value is :c:macro:`RTEMS_DEFAULT_ATTRIBUTES`. +This configuration option is an integer define. -VALUE CONSTRAINTS: - The value of this configuration option shall be a valid task attribute set. +.. rubric:: DEFAULT VALUE: -DESCRIPTION: - The value of this configuration option defines the task attributes of the - Classic API initialization task. +The default value is :c:macro:`RTEMS_DEFAULT_ATTRIBUTES`. -NOTES: - None. +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the task attributes of the +Classic API initialization task. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be a valid task attribute set. .. Generated from spec:/acfg/if/init-task-construct-storage-size +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_INIT_TASK_CONSTRUCT_STORAGE_SIZE .. _CONFIGURE_INIT_TASK_CONSTRUCT_STORAGE_SIZE: @@ -92,60 +108,70 @@ NOTES: CONFIGURE_INIT_TASK_CONSTRUCT_STORAGE_SIZE ------------------------------------------ -CONSTANT: - ``CONFIGURE_INIT_TASK_CONSTRUCT_STORAGE_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_INIT_TASK_CONSTRUCT_STORAGE_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DEFAULT VALUE: -DEFAULT VALUE: - This configuration option has no default value. If it is not specified, then - the Classic API initialization task will be created with the stack size - defined by the :ref:`CONFIGURE_INIT_TASK_STACK_SIZE` configuration option. +This configuration option has no default value. If it is not specified, then +the Classic API initialization task will be created with the stack size +defined by the :ref:`CONFIGURE_INIT_TASK_STACK_SIZE` configuration option. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: DESCRIPTION: - * It shall be greater than or equal to :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. +The value of this configuration option defines the task storage size of the +Classic API initialization task. - * It shall be defined using - :c:func:`RTEMS_TASK_STORAGE_SIZE`. +.. rubric:: NOTES: -DESCRIPTION: - The value of this configuration option defines the task storage size of the - Classic API initialization task. +If this configuration option is specified, then -NOTES: - If this configuration option is specified, then +* a task storage area of the specified size is statically allocated by + ``<rtems/confdefs.h>`` for the Classic API initialization task, - * a task storage area of the specified size is statically allocated by - ``<rtems/confdefs.h>`` for the Classic API initialization task, +* the Classic API initialization task is constructed by + :ref:`InterfaceRtemsTaskConstruct` instead of using + :ref:`InterfaceRtemsTaskCreate`, - * the Classic API initialization task is constructed by - :c:func:`rtems_task_construct` instead of using - :c:func:`rtems_task_create`, +* the maximum thread-local storage size defined by + :ref:`CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE` is used for the Classic API + initialization task, - * the maximum thread-local storage size defined by - :ref:`CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE` is used for the Classic API - initialization task, +* the Classic API initialization task should be accounted for in + :ref:`CONFIGURE_MINIMUM_TASKS_WITH_USER_PROVIDED_STORAGE`, and - * the Classic API initialization task should be accounted for in - :ref:`CONFIGURE_MINIMUM_TASKS_WITH_USER_PROVIDED_STORAGE`, and +* the task storage area used for the Classic API initialization task is not + reclaimed by the system if the task is deleted. - * the task storage area used for the Classic API initialization task is not - reclaimed by the system if the task is deleted. +The - The +* :ref:`CONFIGURE_INIT_TASK_STACK_SIZE` and - * :ref:`CONFIGURE_INIT_TASK_STACK_SIZE` and +* ``CONFIGURE_INIT_TASK_CONSTRUCT_STORAGE_SIZE`` - * ``CONFIGURE_INIT_TASK_CONSTRUCT_STORAGE_SIZE`` +configuration options are mutually exclusive. - configuration options are mutually exclusive. +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to + :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. + +* The value of the configuration option shall be defined using + :ref:`InterfaceRTEMSTASKSTORAGESIZE`. .. Generated from spec:/acfg/if/init-task-entrypoint +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_INIT_TASK_ENTRY_POINT .. _CONFIGURE_INIT_TASK_ENTRY_POINT: @@ -153,29 +179,39 @@ NOTES: CONFIGURE_INIT_TASK_ENTRY_POINT ------------------------------- -CONSTANT: - ``CONFIGURE_INIT_TASK_ENTRY_POINT`` +.. rubric:: CONSTANT: + +``CONFIGURE_INIT_TASK_ENTRY_POINT`` + +.. rubric:: OPTION TYPE: + +This configuration option is an initializer define. -OPTION TYPE: - This configuration option is an initializer define. +.. rubric:: DEFAULT VALUE: -DEFAULT VALUE: - The default value is ``Init``. +The default value is ``Init``. -VALUE CONSTRAINTS: - The value of this configuration option shall be defined to a valid function - pointer of the type ``void ( *entry_point )( rtems_task_argument )``. +.. rubric:: DESCRIPTION: -DESCRIPTION: - The value of this configuration option initializes the entry point of the - Classic API initialization task. +The value of this configuration option initializes the entry point of the +Classic API initialization task. -NOTES: - The application shall provide the function referenced by this configuration - option. +.. rubric:: NOTES: + +The application shall provide the function referenced by this configuration +option. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be defined to a valid function +pointer of the type ``void ( *entry_point )( rtems_task_argument )``. .. Generated from spec:/acfg/if/init-task-initial-modes +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_INIT_TASK_INITIAL_MODES .. _CONFIGURE_INIT_TASK_INITIAL_MODES: @@ -183,28 +219,34 @@ NOTES: CONFIGURE_INIT_TASK_INITIAL_MODES --------------------------------- -CONSTANT: - ``CONFIGURE_INIT_TASK_INITIAL_MODES`` +.. rubric:: CONSTANT: + +``CONFIGURE_INIT_TASK_INITIAL_MODES`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DEFAULT VALUE: -DEFAULT VALUE: - In SMP configurations, the default value is :c:macro:`RTEMS_DEFAULT_MODES` - otherwise the default value is :c:macro:`RTEMS_NO_PREEMPT`. +In SMP configurations, the default value is :c:macro:`RTEMS_DEFAULT_MODES` +otherwise the default value is :c:macro:`RTEMS_NO_PREEMPT`. -VALUE CONSTRAINTS: - The value of this configuration option shall be a valid task mode set. +.. rubric:: DESCRIPTION: -DESCRIPTION: - The value of this configuration option defines the initial execution mode of - the Classic API initialization task. +The value of this configuration option defines the initial execution mode of +the Classic API initialization task. -NOTES: - None. +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be a valid task mode set. .. Generated from spec:/acfg/if/init-task-name +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_INIT_TASK_NAME .. _CONFIGURE_INIT_TASK_NAME: @@ -212,28 +254,38 @@ NOTES: CONFIGURE_INIT_TASK_NAME ------------------------ -CONSTANT: - ``CONFIGURE_INIT_TASK_NAME`` +.. rubric:: CONSTANT: + +``CONFIGURE_INIT_TASK_NAME`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is ``rtems_build_name( 'U', 'I', '1', ' ' )``. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DESCRIPTION: -DEFAULT VALUE: - The default value is ``rtems_build_name( 'U', 'I', '1', ' ' )``. +The value of this configuration option defines the name of the Classic API +initialization task. + +.. rubric:: NOTES: -VALUE CONSTRAINTS: - The value of this configuration option shall be a valid integer of type - :c:type:`rtems_name`. +Use :ref:`InterfaceRtemsBuildName` to define the task name. -DESCRIPTION: - The value of this configuration option defines the name of the Classic API - initialization task. +.. rubric:: CONSTRAINTS: -NOTES: - Use :c:func:`rtems_build_name` to define the task name. +The value of the configuration option shall be convertible to an integer of +type :c:type:`rtems_name`. .. Generated from spec:/acfg/if/init-task-priority +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_INIT_TASK_PRIORITY .. _CONFIGURE_INIT_TASK_PRIORITY: @@ -241,28 +293,35 @@ NOTES: CONFIGURE_INIT_TASK_PRIORITY ---------------------------- -CONSTANT: - ``CONFIGURE_INIT_TASK_PRIORITY`` +.. rubric:: CONSTANT: + +``CONFIGURE_INIT_TASK_PRIORITY`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: -OPTION TYPE: - This configuration option is an integer define. +The default value is 1. -DEFAULT VALUE: - The default value is 1. +.. rubric:: DESCRIPTION: -VALUE CONSTRAINTS: - The value of this configuration option shall be a valid Classic API task - priority. The set of valid task priorities is scheduler-specific. +The value of this configuration option defines the initial priority of the +Classic API initialization task. -DESCRIPTION: - The value of this configuration option defines the initial priority of the - Classic API initialization task. +.. rubric:: CONSTRAINTS: -NOTES: - None. +The value of the configuration option shall be a valid Classic API task +priority. The set of valid task priorities depends on the scheduler +configuration. .. Generated from spec:/acfg/if/init-task-stack-size +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_INIT_TASK_STACK_SIZE .. _CONFIGURE_INIT_TASK_STACK_SIZE: @@ -270,40 +329,51 @@ NOTES: CONFIGURE_INIT_TASK_STACK_SIZE ------------------------------ -CONSTANT: - ``CONFIGURE_INIT_TASK_STACK_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_INIT_TASK_STACK_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is an integer define. +The value of this configuration option defines the task stack size of the +Classic API initialization task. -DEFAULT VALUE: - The default value is :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. +.. rubric:: NOTES: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The - * It shall be greater than or equal to :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. +* ``CONFIGURE_INIT_TASK_STACK_SIZE`` and - * It shall be small enough so that the task - stack space calculation carried out by ``<rtems/confdefs.h>`` does not - overflow an integer of type `uintptr_t <https://en.cppreference.com/w/c/types/integer>`_. +* :ref:`CONFIGURE_INIT_TASK_CONSTRUCT_STORAGE_SIZE` -DESCRIPTION: - The value of this configuration option defines the task stack size of the - Classic API initialization task. +configuration options are mutually exclusive. -NOTES: - The +.. rubric:: CONSTRAINTS: - * ``CONFIGURE_INIT_TASK_STACK_SIZE`` and +The following constraints apply to this configuration option: - * :ref:`CONFIGURE_INIT_TASK_CONSTRUCT_STORAGE_SIZE` +* The value of the configuration option shall be greater than or equal to + :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. - configuration options are mutually exclusive. +* The value of the configuration option shall be small enough so that the task + stack space calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. .. Generated from spec:/acfg/if/rtems-init-tasks-table +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_RTEMS_INIT_TASKS_TABLE .. _CONFIGURE_RTEMS_INIT_TASKS_TABLE: @@ -311,28 +381,36 @@ NOTES: CONFIGURE_RTEMS_INIT_TASKS_TABLE -------------------------------- -CONSTANT: - ``CONFIGURE_RTEMS_INIT_TASKS_TABLE`` +.. rubric:: CONSTANT: + +``CONFIGURE_RTEMS_INIT_TASKS_TABLE`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is a boolean feature define. +In case this configuration option is defined, then exactly one Classic API +initialization task is configured. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: NOTES: -DESCRIPTION: - In case this configuration option is defined, then exactly one Classic API - initialization task is configured. +The application shall define at least one of the following configuration +options -NOTES: - The application shall define exactly one of the following configuration - options +* ``CONFIGURE_RTEMS_INIT_TASKS_TABLE``, - * ``CONFIGURE_RTEMS_INIT_TASKS_TABLE``, +* :ref:`CONFIGURE_POSIX_INIT_THREAD_TABLE`, or - * :ref:`CONFIGURE_POSIX_INIT_THREAD_TABLE`, or +* :ref:`CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION` - * :ref:`CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION` +otherwise a compile time error in the configuration file will occur. - otherwise a compile time error in the configuration file will occur. +The Classic API initialization task performs the +:ref:`GlobalConstruction`. diff --git a/c-user/config/device-driver.rst b/c-user/config/device-driver.rst index 05ae08a..1e31575 100644 --- a/c-user/config/device-driver.rst +++ b/c-user/config/device-driver.rst @@ -1,7 +1,7 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2021 On-Line Applications Research Corporation (OAR) .. This file is part of the RTEMS quality process and was automatically .. generated. If you find something that needs to be fixed or @@ -28,6 +28,10 @@ Note that network device drivers are not covered by the following options. .. Generated from spec:/acfg/if/appl-does-not-need-clock-driver +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER .. _CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER: @@ -35,37 +39,46 @@ Note that network device drivers are not covered by the following options. CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER ------------------------------------------------ -CONSTANT: - ``CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DEFAULT CONFIGURATION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then a Clock Driver may be - initialized during system initialization. +If this configuration option is undefined, then a Clock Driver may be +initialized during system initialization. -DESCRIPTION: - In case this configuration option is defined, then **no** Clock Driver is - initialized during system initialization. +.. rubric:: DESCRIPTION: -NOTES: - This configuration parameter is intended to prevent the common user error - of using the Hello World example as the baseline for an application and - leaving out a clock tick source. +In case this configuration option is defined, then **no** Clock Driver is +initialized during system initialization. - The application shall define exactly one of the following configuration options +.. rubric:: NOTES: - * :ref:`CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER`, +This configuration parameter is intended to prevent the common user error +of using the Hello World example as the baseline for an application and +leaving out a clock tick source. - * ``CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER``, or +The application shall define exactly one of the following configuration options - * :ref:`CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER`, +* :ref:`CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER`, - otherwise a compile time error in the configuration file will occur. +* ``CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER``, or + +* :ref:`CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER`, + +otherwise a compile time error in the configuration file will occur. .. Generated from spec:/acfg/if/appl-extra-drivers +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_APPLICATION_EXTRA_DRIVERS .. _CONFIGURE_APPLICATION_EXTRA_DRIVERS: @@ -73,32 +86,42 @@ NOTES: CONFIGURE_APPLICATION_EXTRA_DRIVERS ----------------------------------- -CONSTANT: - ``CONFIGURE_APPLICATION_EXTRA_DRIVERS`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_EXTRA_DRIVERS`` -OPTION TYPE: - This configuration option is an initializer define. +.. rubric:: OPTION TYPE: -DEFAULT VALUE: - The default value is the empty list. +This configuration option is an initializer define. -VALUE CONSTRAINTS: - The value of this configuration option shall be a list of initializers for - structures of type :c:type:`rtems_driver_address_table`. +.. rubric:: DEFAULT VALUE: -DESCRIPTION: - The value of this configuration option is used to initialize the Device - Driver Table. +The default value is the empty list. -NOTES: - The value of this configuration option is placed after the entries of other - device driver configuration options. +.. rubric:: DESCRIPTION: - See :ref:`CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS` for an alternative - placement of application device driver initializers. +The value of this configuration option is used to initialize the Device +Driver Table. + +.. rubric:: NOTES: + +The value of this configuration option is placed after the entries of other +device driver configuration options. + +See :ref:`CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS` for an alternative +placement of application device driver initializers. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be a list of initializers for +structures of type :ref:`InterfaceRtemsDriverAddressTable`. .. Generated from spec:/acfg/if/appl-needs-ata-driver +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_APPLICATION_NEEDS_ATA_DRIVER .. _CONFIGURE_APPLICATION_NEEDS_ATA_DRIVER: @@ -106,28 +129,37 @@ NOTES: CONFIGURE_APPLICATION_NEEDS_ATA_DRIVER -------------------------------------- -CONSTANT: - ``CONFIGURE_APPLICATION_NEEDS_ATA_DRIVER`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_ATA_DRIVER`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then the ATA Driver is - initialized during system initialization. +If this configuration option is undefined, then the described feature is not +enabled. -NOTES: - Most BSPs do not include support for an ATA Driver. +.. rubric:: DESCRIPTION: - If this option is defined and the BSP does not have this device driver, then - the user will get a link time error for an undefined symbol. +In case this configuration option is defined, then the ATA Driver is +initialized during system initialization. + +.. rubric:: NOTES: + +Most BSPs do not include support for an ATA Driver. + +If this option is defined and the BSP does not have this device driver, then +the user will get a link time error for an undefined symbol. .. Generated from spec:/acfg/if/appl-needs-clock-driver +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER .. _CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER: @@ -135,36 +167,45 @@ NOTES: CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER ---------------------------------------- -CONSTANT: - ``CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: -OPTION TYPE: - This configuration option is a boolean feature define. +If this configuration option is undefined, then the described feature is not +enabled. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DESCRIPTION: -DESCRIPTION: - In case this configuration option is defined, then the Clock Driver is - initialized during system initialization. +In case this configuration option is defined, then the Clock Driver is +initialized during system initialization. -NOTES: - The Clock Driver is responsible for providing a regular interrupt - which invokes a clock tick directive. +.. rubric:: NOTES: - The application shall define exactly one of the following configuration options +The Clock Driver is responsible for providing a regular interrupt +which invokes a clock tick directive. - * ``CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER``, +The application shall define exactly one of the following configuration options - * :ref:`CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`, or +* ``CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER``, - * :ref:`CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER`, +* :ref:`CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`, or - otherwise a compile time error in the configuration file will occur. +* :ref:`CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER`, + +otherwise a compile time error in the configuration file will occur. .. Generated from spec:/acfg/if/appl-needs-console-driver +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER .. _CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER: @@ -172,40 +213,49 @@ NOTES: CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER ------------------------------------------ -CONSTANT: - ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then the Console Driver is - initialized during system initialization. +If this configuration option is undefined, then the described feature is not +enabled. -NOTES: - The Console Driver is responsible for providing the :file:`/dev/console` - device file. This device is used to initialize the standard input, output, - and error file descriptors. +.. rubric:: DESCRIPTION: - BSPs should be constructed in a manner that allows :c:func:`printk` to work - properly without the need for the Console Driver to be configured. +In case this configuration option is defined, then the Console Driver is +initialized during system initialization. - The +.. rubric:: NOTES: - * ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER``, +The Console Driver is responsible for providing the :file:`/dev/console` +device file. This device is used to initialize the standard input, output, +and error file descriptors. - * :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER`, and +BSPs should be constructed in a manner that allows :ref:`InterfacePrintk` to work +properly without the need for the Console Driver to be configured. - * :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER` +The - configuration options are mutually exclusive. +* ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER``, + +* :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER`, and + +* :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER` + +configuration options are mutually exclusive. .. Generated from spec:/acfg/if/appl-needs-framebuffer-driver +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER .. _CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER: @@ -213,29 +263,38 @@ NOTES: CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER ----------------------------------------------- -CONSTANT: - ``CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: -OPTION TYPE: - This configuration option is a boolean feature define. +If this configuration option is undefined, then the described feature is not +enabled. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DESCRIPTION: -DESCRIPTION: - In case this configuration option is defined, then the Frame Buffer Driver is - initialized during system initialization. +In case this configuration option is defined, then the Frame Buffer Driver is +initialized during system initialization. -NOTES: - Most BSPs do not include support for a Frame Buffer Driver. This is - because many boards do not include the required hardware. +.. rubric:: NOTES: - If this option is defined and the BSP does not have this device driver, then - the user will get a link time error for an undefined symbol. +Most BSPs do not include support for a Frame Buffer Driver. This is +because many boards do not include the required hardware. + +If this option is defined and the BSP does not have this device driver, then +the user will get a link time error for an undefined symbol. .. Generated from spec:/acfg/if/appl-needs-ide-driver +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_APPLICATION_NEEDS_IDE_DRIVER .. _CONFIGURE_APPLICATION_NEEDS_IDE_DRIVER: @@ -243,28 +302,37 @@ NOTES: CONFIGURE_APPLICATION_NEEDS_IDE_DRIVER -------------------------------------- -CONSTANT: - ``CONFIGURE_APPLICATION_NEEDS_IDE_DRIVER`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_IDE_DRIVER`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then the IDE Driver is - initialized during system initialization. +If this configuration option is undefined, then the described feature is not +enabled. -NOTES: - Most BSPs do not include support for an IDE Driver. +.. rubric:: DESCRIPTION: - If this option is defined and the BSP does not have this device driver, then - the user will get a link time error for an undefined symbol. +In case this configuration option is defined, then the IDE Driver is +initialized during system initialization. + +.. rubric:: NOTES: + +Most BSPs do not include support for an IDE Driver. + +If this option is defined and the BSP does not have this device driver, then +the user will get a link time error for an undefined symbol. .. Generated from spec:/acfg/if/appl-needs-null-driver +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER .. index:: /dev/null @@ -273,25 +341,34 @@ NOTES: CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER --------------------------------------- -CONSTANT: - ``CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: -OPTION TYPE: - This configuration option is a boolean feature define. +If this configuration option is undefined, then the described feature is not +enabled. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DESCRIPTION: -DESCRIPTION: - In case this configuration option is defined, then the :file:`/dev/null` - Driver is initialized during system initialization. +In case this configuration option is defined, then the :file:`/dev/null` +Driver is initialized during system initialization. -NOTES: - This device driver is supported by all BSPs. +.. rubric:: NOTES: + +This device driver is supported by all BSPs. .. Generated from spec:/acfg/if/appl-needs-rtc-driver +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER .. _CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER: @@ -299,29 +376,38 @@ NOTES: CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER -------------------------------------- -CONSTANT: - ``CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then the Real-Time Clock Driver - is initialized during system initialization. +If this configuration option is undefined, then the described feature is not +enabled. -NOTES: - Most BSPs do not include support for a real-time clock (RTC). This is because - many boards do not include the required hardware. +.. rubric:: DESCRIPTION: - 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. +In case this configuration option is defined, then the Real-Time Clock Driver +is initialized during system initialization. + +.. rubric:: NOTES: + +Most BSPs do not include support for a real-time clock (RTC). This is because +many boards do not include the required hardware. + +If this is defined and the BSP does not have this device driver, then the +user will get a link time error for an undefined symbol. .. Generated from spec:/acfg/if/appl-needs-simple-console-driver +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER .. _CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER: @@ -329,44 +415,53 @@ NOTES: CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER ------------------------------------------------- -CONSTANT: - ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: -OPTION TYPE: - This configuration option is a boolean feature define. +If this configuration option is undefined, then the described feature is not +enabled. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DESCRIPTION: -DESCRIPTION: - In case this configuration option is defined, then the Simple Console Driver - is initialized during system initialization. +In case this configuration option is defined, then the Simple Console Driver +is initialized during system initialization. -NOTES: - This device driver is responsible for providing the :file:`/dev/console` - device file. This device is used to initialize the standard input, output, - and error file descriptors. +.. rubric:: NOTES: - This device driver reads via :c:func:`getchark`. +This device driver is responsible for providing the :file:`/dev/console` +device file. This device is used to initialize the standard input, output, +and error file descriptors. - This device driver writes via :c:func:`rtems_putc`. +This device driver reads via :ref:`InterfaceGetchark`. - The Termios framework is not used. There is no support to change device - settings, e.g. baud, stop bits, parity, etc. +This device driver writes via :ref:`InterfaceRtemsPutc`. - The +The Termios framework is not used. There is no support to change device +settings, e.g. baud, stop bits, parity, etc. - * :ref:`CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`, +The - * ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER``, and +* :ref:`CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`, - * :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER` +* ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER``, and - configuration options are mutually exclusive. +* :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER` + +configuration options are mutually exclusive. .. Generated from spec:/acfg/if/appl-needs-simple-task-console-driver +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER .. _CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER: @@ -374,53 +469,62 @@ NOTES: CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER ------------------------------------------------------ -CONSTANT: - ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER`` -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: OPTION TYPE: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +This configuration option is a boolean feature define. -DESCRIPTION: - In case this configuration option is defined, then the Simple Task Console - Driver is initialized during system initialization. +.. rubric:: DEFAULT CONFIGURATION: -NOTES: - This device driver is responsible for providing the :file:`/dev/console` - device file. This device is used to initialize the standard input, output, - and error file descriptors. +If this configuration option is undefined, then the described feature is not +enabled. - This device driver reads via :c:func:`getchark`. +.. rubric:: DESCRIPTION: - This device driver writes into a write buffer. The count of characters - written into the write buffer is returned. It might be less than the - requested count, in case the write buffer is full. The write is - non-blocking and may be called from interrupt context. A dedicated task - reads from the write buffer and outputs the characters via - :c:func:`rtems_putc`. This task runs with the least important priority. - The write buffer size is 2047 characters and it is not configurable. +In case this configuration option is defined, then the Simple Task Console +Driver is initialized during system initialization. - Use ``fsync( STDOUT_FILENO )`` or ``fdatasync( STDOUT_FILENO )`` to drain the - write buffer. +.. rubric:: NOTES: - The Termios framework is not used. There is no support to change device - settings, e.g. baud, stop bits, parity, etc. +This device driver is responsible for providing the :file:`/dev/console` +device file. This device is used to initialize the standard input, output, +and error file descriptors. - The +This device driver reads via :ref:`InterfaceGetchark`. - * :ref:`CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`, +This device driver writes into a write buffer. The count of characters +written into the write buffer is returned. It might be less than the +requested count, in case the write buffer is full. The write is +non-blocking and may be called from interrupt context. A dedicated task +reads from the write buffer and outputs the characters via +:ref:`InterfaceRtemsPutc`. This task runs with the least important priority. +The write buffer size is 2047 characters and it is not configurable. - * :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER`, and +Use ``fsync( STDOUT_FILENO )`` or ``fdatasync( STDOUT_FILENO )`` to drain the +write buffer. - * ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER`` +The Termios framework is not used. There is no support to change device +settings, e.g. baud, stop bits, parity, etc. - configuration options are mutually exclusive. +The + +* :ref:`CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`, + +* :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER`, and + +* ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER`` + +configuration options are mutually exclusive. .. Generated from spec:/acfg/if/appl-needs-stub-driver +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER .. _CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER: @@ -428,26 +532,35 @@ NOTES: CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER --------------------------------------- -CONSTANT: - ``CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: -OPTION TYPE: - This configuration option is a boolean feature define. +If this configuration option is undefined, then the described feature is not +enabled. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DESCRIPTION: -DESCRIPTION: - In case this configuration option is defined, then the Stub Driver is - initialized during system initialization. +In case this configuration option is defined, then the Stub Driver is +initialized during system initialization. -NOTES: - This device driver simply provides entry points that return successful and - is primarily a test fixture. It is supported by all BSPs. +.. rubric:: NOTES: + +This device driver simply provides entry points that return successful and +is primarily a test fixture. It is supported by all BSPs. .. Generated from spec:/acfg/if/appl-needs-timer-driver +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER .. _CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER: @@ -455,36 +568,45 @@ NOTES: CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER ---------------------------------------- -CONSTANT: - ``CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then the Benchmark Timer Driver is - initialized during system initialization. +If this configuration option is undefined, then the described feature is not +enabled. -NOTES: - The Benchmark Timer Driver is intended for the benchmark tests of the RTEMS - Testsuite. Applications should not use this driver. +.. rubric:: DESCRIPTION: - The application shall define exactly one of the following configuration options +In case this configuration option is defined, then the Benchmark Timer Driver is +initialized during system initialization. - * :ref:`CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER`, +.. rubric:: NOTES: - * :ref:`CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`, or +The Benchmark Timer Driver is intended for the benchmark tests of the RTEMS +Testsuite. Applications should not use this driver. - * ``CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER``, +The application shall define exactly one of the following configuration options - otherwise a compile time error will occur. +* :ref:`CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER`, + +* :ref:`CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`, or + +* ``CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER``, + +otherwise a compile time error will occur. .. Generated from spec:/acfg/if/appl-needs-watchdog-driver +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER .. _CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER: @@ -492,29 +614,38 @@ NOTES: CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER ------------------------------------------- -CONSTANT: - ``CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: -OPTION TYPE: - This configuration option is a boolean feature define. +If this configuration option is undefined, then the described feature is not +enabled. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DESCRIPTION: -DESCRIPTION: - In case this configuration option is defined, then the Watchdog Driver is - initialized during system initialization. +In case this configuration option is defined, then the Watchdog Driver is +initialized during system initialization. -NOTES: - Most BSPs do not include support for a watchdog device driver. This is - because many boards do not include the required hardware. +.. rubric:: NOTES: - 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. +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. .. Generated from spec:/acfg/if/appl-needs-zero-driver +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER .. index:: /dev/zero @@ -523,25 +654,34 @@ NOTES: CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER --------------------------------------- -CONSTANT: - ``CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER`` -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: OPTION TYPE: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +This configuration option is a boolean feature define. -DESCRIPTION: - In case this configuration option is defined, then the :file:`/dev/zero` - Driver is initialized during system initialization. +.. rubric:: DEFAULT CONFIGURATION: -NOTES: - This device driver is supported by all BSPs. +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the :file:`/dev/zero` +Driver is initialized during system initialization. + +.. rubric:: NOTES: + +This device driver is supported by all BSPs. .. Generated from spec:/acfg/if/appl-prerequisite-drivers +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS .. _CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS: @@ -549,33 +689,43 @@ NOTES: CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS ------------------------------------------ -CONSTANT: - ``CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an initializer define. -OPTION TYPE: - This configuration option is an initializer define. +.. rubric:: DEFAULT VALUE: -DEFAULT VALUE: - The default value is the empty list. +The default value is the empty list. -VALUE CONSTRAINTS: - The value of this configuration option shall be a list of initializers for - structures of type :c:type:`rtems_driver_address_table`. +.. rubric:: DESCRIPTION: -DESCRIPTION: - The value of this configuration option is used to initialize the Device - Driver Table. +The value of this configuration option is used to initialize the Device +Driver Table. -NOTES: - The value of this configuration option is placed after the entries defined by - :ref:`CONFIGURE_BSP_PREREQUISITE_DRIVERS` and before all other device driver - configuration options. +.. rubric:: NOTES: - See :ref:`CONFIGURE_APPLICATION_EXTRA_DRIVERS` for an alternative placement - of application device driver initializers. +The value of this configuration option is placed after the entries defined by +:c:macro:`CONFIGURE_BSP_PREREQUISITE_DRIVERS` and before all other device driver +configuration options. + +See :ref:`CONFIGURE_APPLICATION_EXTRA_DRIVERS` for an alternative placement +of application device driver initializers. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be a list of initializers for +structures of type :ref:`InterfaceRtemsDriverAddressTable`. .. Generated from spec:/acfg/if/ata-driver-task-priority +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_ATA_DRIVER_TASK_PRIORITY .. _CONFIGURE_ATA_DRIVER_TASK_PRIORITY: @@ -583,28 +733,78 @@ NOTES: CONFIGURE_ATA_DRIVER_TASK_PRIORITY ---------------------------------- -CONSTANT: - ``CONFIGURE_ATA_DRIVER_TASK_PRIORITY`` +.. rubric:: CONSTANT: + +``CONFIGURE_ATA_DRIVER_TASK_PRIORITY`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 140. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the ATA task priority. + +.. rubric:: NOTES: + +This configuration option is only evaluated if the configuration option +:ref:`CONFIGURE_APPLICATION_NEEDS_ATA_DRIVER` is defined. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be a valid Classic API task +priority. The set of valid task priorities depends on the scheduler +configuration. + +.. Generated from spec:/acfg/if/exception-to-signal-mapping + +.. raw:: latex -OPTION TYPE: - This configuration option is an integer define. + \clearpage -DEFAULT VALUE: - The default value is 140. +.. index:: CONFIGURE_EXCEPTION_TO_SIGNAL_MAPPING -VALUE CONSTRAINTS: - The value of this configuration option shall be a valid Classic API task - priority. The set of valid task priorities is scheduler-specific. +.. _CONFIGURE_EXCEPTION_TO_SIGNAL_MAPPING: -DESCRIPTION: - The value of this configuration option defines the ATA task priority. +CONFIGURE_EXCEPTION_TO_SIGNAL_MAPPING +------------------------------------- -NOTES: - This configuration option is only evaluated if the configuration option - :ref:`CONFIGURE_APPLICATION_NEEDS_ATA_DRIVER` is defined. +.. rubric:: CONSTANT: + +``CONFIGURE_EXCEPTION_TO_SIGNAL_MAPPING`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the machine exception to +POSIX signal mapping is configured during system initialization. + +.. rubric:: NOTES: + +This device driver is responsible for setting up a mapping from machine +exceptions to POSIX signals so that applications may consume them and alter +task execution as necessary. + +This is especially useful for applications written in Ada or C++. .. Generated from spec:/acfg/if/max-drivers +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MAXIMUM_DRIVERS .. _CONFIGURE_MAXIMUM_DRIVERS: @@ -612,68 +812,77 @@ NOTES: CONFIGURE_MAXIMUM_DRIVERS ------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_DRIVERS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_DRIVERS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +This is computed by default, and is set to the number of statically +configured device drivers configured using the following configuration +options: + +* :ref:`CONFIGURE_APPLICATION_EXTRA_DRIVERS` -OPTION TYPE: - This configuration option is an integer define. +* :ref:`CONFIGURE_APPLICATION_NEEDS_ATA_DRIVER` -DEFAULT VALUE: - This is computed by default, and is set to the number of statically - configured device drivers configured using the following configuration - options: +* :ref:`CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER` - * :ref:`CONFIGURE_APPLICATION_EXTRA_DRIVERS` +* :ref:`CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER` - * :ref:`CONFIGURE_APPLICATION_NEEDS_ATA_DRIVER` +* :ref:`CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER` - * :ref:`CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER` +* :ref:`CONFIGURE_APPLICATION_NEEDS_IDE_DRIVER` - * :ref:`CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER` +* :ref:`CONFIGURE_APPLICATION_NEEDS_LIBBLOCK` - * :ref:`CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER` +* :ref:`CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER` - * :ref:`CONFIGURE_APPLICATION_NEEDS_IDE_DRIVER` +* :ref:`CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER` - * :ref:`CONFIGURE_APPLICATION_NEEDS_LIBBLOCK` +* :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER` - * :ref:`CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER` +* :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER` - * :ref:`CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER` +* :ref:`CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER` - * :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER` +* :ref:`CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER` - * :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER` +* :ref:`CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER` - * :ref:`CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER` +* :ref:`CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER` - * :ref:`CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER` +* :ref:`CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS` - * :ref:`CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER` +If the :ref:`CONFIGURE_DISABLE_BSP_SETTINGS` configuration option is not defined and +the :term:`BSP` provides +:c:macro:`CONFIGURE_BSP_PREREQUISITE_DRIVERS`, then the BSP-provided +prerequisite device drivers are also taken into account. - * :ref:`CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER` +.. rubric:: DESCRIPTION: - * :ref:`CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS` +The value of this configuration option defines the number of device drivers. - * :ref:`CONFIGURE_BSP_PREREQUISITE_DRIVERS` +.. rubric:: NOTES: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +If the application will dynamically install device drivers, then the +configuration option value shall be larger than the number of statically +configured device drivers. - * It shall be less than or equal to `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_. +.. rubric:: CONSTRAINTS: - * It shall be greater than or equal than the number of statically configured - device drivers. +The following constraints apply to this configuration option: - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +* The value of the configuration option shall be less than or equal to + `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_. -DESCRIPTION: - The value of this configuration option defines the number of device drivers. +* The value of the configuration option shall be greater than or equal than the + number of statically configured device drivers. -NOTES: - If the application will dynamically install device drivers, then the - configuration option value shall be larger than the number of statically - configured device drivers. +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. diff --git a/c-user/config/directives.rst b/c-user/config/directives.rst new file mode 100644 index 0000000..25351e9 --- /dev/null +++ b/c-user/config/directives.rst @@ -0,0 +1,1550 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2009, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2021 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. _ApplicationConfigurationInformationDirectives: + +Directives +========== + +This section details the directives of the Application Configuration +Information. A subsection is dedicated to each of this manager's directives and +lists the calling sequence, parameters, description, return values, and notes +of the directive. + +.. Generated from spec:/rtems/config/if/get-build-label + +.. raw:: latex + + \clearpage + +.. index:: rtems_get_build_label() + +.. _InterfaceRtemsGetBuildLabel: + +rtems_get_build_label() +----------------------- + +Gets the RTEMS build label. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + const char *rtems_get_build_label( void ); + +.. rubric:: DESCRIPTION: + +The build label is a user-provided string defined by the build configuration +through the ``RTEMS_BUILD_LABEL`` build option. The format of the string is +completely user-defined. + +.. rubric:: RETURN VALUES: + +Returns a pointer to the RTEMS build label. + +.. rubric:: NOTES: + +The build label can be used to distinguish test suite results obtained from +different build configurations. A use case is to record test results with +performance data to track performance regressions. For this a database of +performance limits is required. The build label and the target hash obtained +from :ref:`InterfaceRtemsGetTargetHash` can be used as a key to obtain +performance limits. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-copyright-notice + +.. raw:: latex + + \clearpage + +.. index:: rtems_get_copyright_notice() + +.. _InterfaceRtemsGetCopyrightNotice: + +rtems_get_copyright_notice() +---------------------------- + +Gets the RTEMS copyright notice. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + const char *rtems_get_copyright_notice( void ); + +.. rubric:: RETURN VALUES: + +Returns a pointer to the RTEMS copyright notice. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-target-hash + +.. raw:: latex + + \clearpage + +.. index:: rtems_get_target_hash() + +.. _InterfaceRtemsGetTargetHash: + +rtems_get_target_hash() +----------------------- + +Gets the RTEMS target hash. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + const char *rtems_get_target_hash( void ); + +.. rubric:: DESCRIPTION: + +The target hash is calculated from BSP-specific values which characterize a +target system. The target hash is encoded as a base64url string. The target +hash algorithm is unspecified. + +.. rubric:: RETURN VALUES: + +Returns a pointer to the RTEMS target hash. + +.. rubric:: NOTES: + +For example, the device tree, settings of the memory controller, processor and +bus frequencies, a serial number of a chip may be used to calculate the target +hash. + +The target hash can be used to distinguish test suite results obtained from +different target systems. See also :ref:`InterfaceRtemsGetBuildLabel`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-version-string + +.. raw:: latex + + \clearpage + +.. index:: rtems_get_version_string() + +.. _InterfaceRtemsGetVersionString: + +rtems_get_version_string() +-------------------------- + +Gets the RTEMS version string. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + const char *rtems_get_version_string( void ); + +.. rubric:: RETURN VALUES: + +Returns a pointer to the RTEMS version string. + +.. rubric:: NOTES: + +The version string has no particular format. Parsing the string may break +across RTEMS releases. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-do-zero-of-workspace + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_do_zero_of_workspace() + +.. _InterfaceRtemsConfigurationGetDoZeroOfWorkspace: + +rtems_configuration_get_do_zero_of_workspace() +---------------------------------------------- + +Indicates if the RTEMS Workspace is configured to be zeroed during system +initialization for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + bool rtems_configuration_get_do_zero_of_workspace( void ); + +.. rubric:: RETURN VALUES: + +Returns true, if the RTEMS Workspace is configured to be zeroed during system +initialization for this application, otherwise false. + +.. rubric:: NOTES: + +The setting is defined by the :ref:`CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY` +application configuration option. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-idle-task-stack-size + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_idle_task_stack_size() + +.. _InterfaceRtemsConfigurationGetIdleTaskStackSize: + +rtems_configuration_get_idle_task_stack_size() +---------------------------------------------- + +Gets the IDLE task stack size in bytes of this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + size_t rtems_configuration_get_idle_task_stack_size( void ); + +.. rubric:: RETURN VALUES: + +Returns the IDLE task stack size in bytes of this application. + +.. rubric:: NOTES: + +The IDLE task stack size is defined by the +:ref:`CONFIGURE_IDLE_TASK_STACK_SIZE` application configuration option. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-idle-task + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_idle_task() + +.. _InterfaceRtemsConfigurationGetIdleTask: + +rtems_configuration_get_idle_task() +----------------------------------- + +Gets the IDLE task body of this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void *( * )( uintptr_t ) rtems_configuration_get_idle_task( void ); + +.. rubric:: RETURN VALUES: + +Returns the IDLE task body of this application. + +.. rubric:: NOTES: + +The IDLE task body is defined by the :ref:`CONFIGURE_IDLE_TASK_BODY` +application configuration option. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-interrupt-stack-size + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_interrupt_stack_size() + +.. _InterfaceRtemsConfigurationGetInterruptStackSize: + +rtems_configuration_get_interrupt_stack_size() +---------------------------------------------- + +Gets the interrupt stack size in bytes of this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + size_t rtems_configuration_get_interrupt_stack_size( void ); + +.. rubric:: RETURN VALUES: + +Returns the interrupt stack size in bytes of this application. + +.. rubric:: NOTES: + +The interrupt stack size is defined by the +:ref:`CONFIGURE_INTERRUPT_STACK_SIZE` application configuration option. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-maximum-barriers + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_maximum_barriers() + +.. _InterfaceRtemsConfigurationGetMaximumBarriers: + +rtems_configuration_get_maximum_barriers() +------------------------------------------ + +Gets the resource number of :ref:`RTEMSAPIClassicBarrier` objects configured +for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_maximum_barriers( void ); + +.. rubric:: RETURN VALUES: + +Returns the resource number of :ref:`RTEMSAPIClassicBarrier` objects configured +for this application. + +.. rubric:: NOTES: + +The resource number is defined by the :ref:`CONFIGURE_MAXIMUM_BARRIERS` +application configuration option. See also +:ref:`InterfaceRtemsResourceIsUnlimited` and +:ref:`InterfaceRtemsResourceMaximumPerAllocation`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-maximum-extensions + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_maximum_extensions() + +.. _InterfaceRtemsConfigurationGetMaximumExtensions: + +rtems_configuration_get_maximum_extensions() +-------------------------------------------- + +Gets the resource number of :ref:`RTEMSAPIClassicUserExt` objects configured +for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_maximum_extensions( void ); + +.. rubric:: RETURN VALUES: + +Returns the resource number of :ref:`RTEMSAPIClassicUserExt` objects configured +for this application. + +.. rubric:: NOTES: + +The resource number is defined by the :ref:`CONFIGURE_MAXIMUM_USER_EXTENSIONS` +application configuration option. See also +:ref:`InterfaceRtemsResourceIsUnlimited` and +:ref:`InterfaceRtemsResourceMaximumPerAllocation`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-maximum-message-queues + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_maximum_message_queues() + +.. _InterfaceRtemsConfigurationGetMaximumMessageQueues: + +rtems_configuration_get_maximum_message_queues() +------------------------------------------------ + +Gets the resource number of :ref:`RTEMSAPIClassicMessage` objects configured +for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_maximum_message_queues( void ); + +.. rubric:: RETURN VALUES: + +Returns the resource number of :ref:`RTEMSAPIClassicMessage` objects configured +for this application. + +.. rubric:: NOTES: + +The resource number is defined by the :ref:`CONFIGURE_MAXIMUM_MESSAGE_QUEUES` +application configuration option. See also +:ref:`InterfaceRtemsResourceIsUnlimited` and +:ref:`InterfaceRtemsResourceMaximumPerAllocation`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-maximum-partitions + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_maximum_partitions() + +.. _InterfaceRtemsConfigurationGetMaximumPartitions: + +rtems_configuration_get_maximum_partitions() +-------------------------------------------- + +Gets the resource number of :ref:`RTEMSAPIClassicPart` objects configured for +this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_maximum_partitions( void ); + +.. rubric:: RETURN VALUES: + +Returns the resource number of :ref:`RTEMSAPIClassicPart` objects configured +for this application. + +.. rubric:: NOTES: + +The resource number is defined by the :ref:`CONFIGURE_MAXIMUM_PARTITIONS` +application configuration option. See also +:ref:`InterfaceRtemsResourceIsUnlimited` and +:ref:`InterfaceRtemsResourceMaximumPerAllocation`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-maximum-periods + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_maximum_periods() + +.. _InterfaceRtemsConfigurationGetMaximumPeriods: + +rtems_configuration_get_maximum_periods() +----------------------------------------- + +Gets the resource number of :ref:`RTEMSAPIClassicRatemon` objects configured +for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_maximum_periods( void ); + +.. rubric:: RETURN VALUES: + +Returns the resource number of :ref:`RTEMSAPIClassicRatemon` objects configured +for this application. + +.. rubric:: NOTES: + +The resource number is defined by the :ref:`CONFIGURE_MAXIMUM_PERIODS` +application configuration option. See also +:ref:`InterfaceRtemsResourceIsUnlimited` and +:ref:`InterfaceRtemsResourceMaximumPerAllocation`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-maximum-ports + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_maximum_ports() + +.. _InterfaceRtemsConfigurationGetMaximumPorts: + +rtems_configuration_get_maximum_ports() +--------------------------------------- + +Gets the resource number of :ref:`RTEMSAPIClassicDPMem` objects configured for +this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_maximum_ports( void ); + +.. rubric:: RETURN VALUES: + +Returns the resource number of :ref:`RTEMSAPIClassicDPMem` objects configured +for this application. + +.. rubric:: NOTES: + +The resource number is defined by the :ref:`CONFIGURE_MAXIMUM_PORTS` +application configuration option. See also +:ref:`InterfaceRtemsResourceIsUnlimited` and +:ref:`InterfaceRtemsResourceMaximumPerAllocation`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-maximum-processors + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_maximum_processors() + +.. _InterfaceRtemsConfigurationGetMaximumProcessors: + +rtems_configuration_get_maximum_processors() +-------------------------------------------- + +Gets the maximum number of processors configured for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_maximum_processors( void ); + +.. rubric:: RETURN VALUES: + +Returns the maximum number of processors configured for this application. + +.. rubric:: NOTES: + +The actual number of processors available to the application is returned by +:ref:`InterfaceRtemsSchedulerGetProcessorMaximum` which less than or equal to +the configured maximum number of processors +(:ref:`CONFIGURE_MAXIMUM_PROCESSORS`). + +In uniprocessor configurations, this macro is a compile time constant which +evaluates to one. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-maximum-regions + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_maximum_regions() + +.. _InterfaceRtemsConfigurationGetMaximumRegions: + +rtems_configuration_get_maximum_regions() +----------------------------------------- + +Gets the resource number of :ref:`RTEMSAPIClassicRegion` objects configured for +this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_maximum_regions( void ); + +.. rubric:: RETURN VALUES: + +Returns the resource number of :ref:`RTEMSAPIClassicRegion` objects configured +for this application. + +.. rubric:: NOTES: + +The resource number is defined by the :ref:`CONFIGURE_MAXIMUM_REGIONS` +application configuration option. See also +:ref:`InterfaceRtemsResourceIsUnlimited` and +:ref:`InterfaceRtemsResourceMaximumPerAllocation`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-maximum-semaphores + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_maximum_semaphores() + +.. _InterfaceRtemsConfigurationGetMaximumSemaphores: + +rtems_configuration_get_maximum_semaphores() +-------------------------------------------- + +Gets the resource number of :ref:`RTEMSAPIClassicSem` objects configured for +this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_maximum_semaphores( void ); + +.. rubric:: RETURN VALUES: + +Returns the resource number of :ref:`RTEMSAPIClassicSem` objects configured for +this application. + +.. rubric:: NOTES: + +The resource number is defined by the :ref:`CONFIGURE_MAXIMUM_SEMAPHORES` +application configuration option. See also +:ref:`InterfaceRtemsResourceIsUnlimited` and +:ref:`InterfaceRtemsResourceMaximumPerAllocation`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-maximum-tasks + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_maximum_tasks() + +.. _InterfaceRtemsConfigurationGetMaximumTasks: + +rtems_configuration_get_maximum_tasks() +--------------------------------------- + +Gets the resource number of :ref:`RTEMSAPIClassicTasks` objects configured for +this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_maximum_tasks( void ); + +.. rubric:: RETURN VALUES: + +Returns the resource number of :ref:`RTEMSAPIClassicTasks` objects configured +for this application. + +.. rubric:: NOTES: + +The resource number is defined by the :ref:`CONFIGURE_MAXIMUM_TASKS` +application configuration option. See also +:ref:`InterfaceRtemsResourceIsUnlimited` and +:ref:`InterfaceRtemsResourceMaximumPerAllocation`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-maximum-timers + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_maximum_timers() + +.. _InterfaceRtemsConfigurationGetMaximumTimers: + +rtems_configuration_get_maximum_timers() +---------------------------------------- + +Gets the resource number of :ref:`RTEMSAPIClassicTimer` objects configured for +this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_maximum_timers( void ); + +.. rubric:: RETURN VALUES: + +Returns the resource number of :ref:`RTEMSAPIClassicTimer` objects configured +for this application. + +.. rubric:: NOTES: + +The resource number is defined by the :ref:`CONFIGURE_MAXIMUM_TIMERS` +application configuration option. See also +:ref:`InterfaceRtemsResourceIsUnlimited` and +:ref:`InterfaceRtemsResourceMaximumPerAllocation`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-microseconds-per-tick + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_microseconds_per_tick() + +.. _InterfaceRtemsConfigurationGetMicrosecondsPerTick: + +rtems_configuration_get_microseconds_per_tick() +----------------------------------------------- + +Gets the number of microseconds per clock tick configured for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_microseconds_per_tick( void ); + +.. rubric:: RETURN VALUES: + +Returns the number of microseconds per clock tick configured for this +application. + +.. rubric:: NOTES: + +The number of microseconds per :term:`clock tick` is defined by the +:ref:`CONFIGURE_MICROSECONDS_PER_TICK` application configuration option. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-milliseconds-per-tick + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_milliseconds_per_tick() + +.. _InterfaceRtemsConfigurationGetMillisecondsPerTick: + +rtems_configuration_get_milliseconds_per_tick() +----------------------------------------------- + +Gets the number of milliseconds per clock tick configured for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_milliseconds_per_tick( void ); + +.. rubric:: RETURN VALUES: + +Returns the number of milliseconds per clock tick configured for this +application. + +.. rubric:: NOTES: + +The number of milliseconds per :term:`clock tick` is defined by the +:ref:`CONFIGURE_MICROSECONDS_PER_TICK` application configuration option. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-nanoseconds-per-tick + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_nanoseconds_per_tick() + +.. _InterfaceRtemsConfigurationGetNanosecondsPerTick: + +rtems_configuration_get_nanoseconds_per_tick() +---------------------------------------------- + +Gets the number of microseconds per clock tick configured for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_nanoseconds_per_tick( void ); + +.. rubric:: RETURN VALUES: + +Returns the number of microseconds per clock tick configured for this +application. + +.. rubric:: NOTES: + +The number of nanoseconds per :term:`clock tick` is defined by the +:ref:`CONFIGURE_MICROSECONDS_PER_TICK` application configuration option. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-number-of-initial-extensions + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_number_of_initial_extensions() + +.. _InterfaceRtemsConfigurationGetNumberOfInitialExtensions: + +rtems_configuration_get_number_of_initial_extensions() +------------------------------------------------------ + +Gets the number of initial extensions configured for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_number_of_initial_extensions( void ); + +.. rubric:: RETURN VALUES: + +Returns the number of initial extensions configured for this application. + +.. rubric:: NOTES: + +The number of initial extensions is defined by the +:ref:`CONFIGURE_INITIAL_EXTENSIONS` application configuration option and +related options. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-stack-allocate-for-idle-hook + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_stack_allocate_for_idle_hook() + +.. _InterfaceRtemsConfigurationGetStackAllocateForIdleHook: + +rtems_configuration_get_stack_allocate_for_idle_hook() +------------------------------------------------------ + +Gets the task stack allocator allocate hook used to allocate the stack of each +:term:`IDLE task` configured for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void *( * )( uint32_t, size_t * ) + rtems_configuration_get_stack_allocate_for_idle_hook( void ); + +.. rubric:: RETURN VALUES: + +Returns the task stack allocator allocate hook used to allocate the stack of +each :term:`IDLE task` configured for this application. + +.. rubric:: NOTES: + +The task stack allocator allocate hook for idle tasks is defined by the +:ref:`CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE` application configuration +option. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-stack-allocate-hook + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_stack_allocate_hook() + +.. _InterfaceRtemsConfigurationGetStackAllocateHook: + +rtems_configuration_get_stack_allocate_hook() +--------------------------------------------- + +Gets the task stack allocator allocate hook configured for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void *( * )( size_t ) rtems_configuration_get_stack_allocate_hook( void ); + +.. rubric:: RETURN VALUES: + +Returns the task stack allocator allocate hook configured for this application. + +.. rubric:: NOTES: + +The task stack allocator allocate hook is defined by the +:ref:`CONFIGURE_TASK_STACK_ALLOCATOR` application configuration option. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-stack-allocate-init-hook + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_stack_allocate_init_hook() + +.. _InterfaceRtemsConfigurationGetStackAllocateInitHook: + +rtems_configuration_get_stack_allocate_init_hook() +-------------------------------------------------- + +Gets the task stack allocator initialization hook configured for this +application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void ( * )( size_t ) rtems_configuration_get_stack_allocate_init_hook( void ); + +.. rubric:: RETURN VALUES: + +Returns the task stack allocator initialization hook configured for this +application. + +.. rubric:: NOTES: + +The task stack allocator initialization hook is defined by the +:ref:`CONFIGURE_TASK_STACK_ALLOCATOR_INIT` application configuration option. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-stack-allocator-avoids-work-space + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_stack_allocator_avoids_work_space() + +.. _InterfaceRtemsConfigurationGetStackAllocatorAvoidsWorkSpace: + +rtems_configuration_get_stack_allocator_avoids_work_space() +----------------------------------------------------------- + +Indicates if the task stack allocator is configured to avoid the RTEMS +Workspace for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + bool rtems_configuration_get_stack_allocator_avoids_work_space( void ); + +.. rubric:: RETURN VALUES: + +Returns true, if the task stack allocator is configured to avoid the RTEMS +Workspace for this application, otherwise false. + +.. rubric:: NOTES: + +The setting is defined by the +:ref:`CONFIGURE_TASK_STACK_ALLOCATOR_AVOIDS_WORK_SPACE` application +configuration option. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-stack-free-hook + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_stack_free_hook() + +.. _InterfaceRtemsConfigurationGetStackFreeHook: + +rtems_configuration_get_stack_free_hook() +----------------------------------------- + +Gets the task stack allocator free hook configured for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void ( * )( void * ) rtems_configuration_get_stack_free_hook( void ); + +.. rubric:: RETURN VALUES: + +Returns the task stack allocator free hook configured for this application. + +.. rubric:: NOTES: + +The task stack allocator free hook is defined by the +:ref:`CONFIGURE_TASK_STACK_DEALLOCATOR` application configuration option. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-stack-space-size + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_stack_space_size() + +.. _InterfaceRtemsConfigurationGetStackSpaceSize: + +rtems_configuration_get_stack_space_size() +------------------------------------------ + +Gets the configured size in bytes of the memory space used to allocate thread +stacks for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uintptr_t rtems_configuration_get_stack_space_size( void ); + +.. rubric:: RETURN VALUES: + +Returns the configured size in bytes of the memory space used to allocate +thread stacks for this application. + +.. rubric:: NOTES: + +The size takes only threads and tasks into account with are known at the +application configuration time. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-ticks-per-timeslice + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_ticks_per_timeslice() + +.. _InterfaceRtemsConfigurationGetTicksPerTimeslice: + +rtems_configuration_get_ticks_per_timeslice() +--------------------------------------------- + +Gets the clock ticks per timeslice configured for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_ticks_per_timeslice( void ); + +.. rubric:: RETURN VALUES: + +Returns the clock ticks per timeslice configured for this application. + +.. rubric:: NOTES: + +The :term:`clock ticks <clock tick>` per timeslice is defined by the +:ref:`CONFIGURE_TICKS_PER_TIMESLICE` application configuration option. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-unified-work-area + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_unified_work_area() + +.. _InterfaceRtemsConfigurationGetUnifiedWorkArea: + +rtems_configuration_get_unified_work_area() +------------------------------------------- + +Indicates if the RTEMS Workspace and C Program Heap are configured to be +unified for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + bool rtems_configuration_get_unified_work_area( void ); + +.. rubric:: RETURN VALUES: + +Returns true, if the RTEMS Workspace and C Program Heap are configured to be +unified for this application, otherwise false. + +.. rubric:: NOTES: + +The setting is defined by the :ref:`CONFIGURE_UNIFIED_WORK_AREAS` application +configuration option. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-user-extension-table + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_user_extension_table() + +.. _InterfaceRtemsConfigurationGetUserExtensionTable: + +rtems_configuration_get_user_extension_table() +---------------------------------------------- + +Gets the initial extensions table configured for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + const rtems_extensions_table *rtems_configuration_get_user_extension_table( + void + ); + +.. rubric:: RETURN VALUES: + +Returns a pointer to the initial extensions table configured for this +application. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-user-multiprocessing-table + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_user_multiprocessing_table() + +.. _InterfaceRtemsConfigurationGetUserMultiprocessingTable: + +rtems_configuration_get_user_multiprocessing_table() +---------------------------------------------------- + +Gets the MPCI configuration table configured for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + const MPCI_Configuration *rtems_configuration_get_user_multiprocessing_table( + void + ); + +.. rubric:: RETURN VALUES: + +Returns a pointer to the MPCI configuration table configured for this +application. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-work-space-size + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_work_space_size() + +.. _InterfaceRtemsConfigurationGetWorkSpaceSize: + +rtems_configuration_get_work_space_size() +----------------------------------------- + +Gets the RTEMS Workspace size in bytes configured for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uintptr_t rtems_configuration_get_work_space_size( void ); + +.. rubric:: RETURN VALUES: + +Returns the RTEMS Workspace size in bytes configured for this application. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-api-configuration + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_rtems_api_configuration() + +.. _InterfaceRtemsConfigurationGetRtemsApiConfiguration: + +rtems_configuration_get_rtems_api_configuration() +------------------------------------------------- + +Gets the Classic API Configuration Table of this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + const rtems_api_configuration_table * + rtems_configuration_get_rtems_api_configuration( void ); + +.. rubric:: RETURN VALUES: + +Returns a pointer to the Classic API Configuration Table of this application. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/resource-is-unlimited + +.. raw:: latex + + \clearpage + +.. index:: rtems_resource_is_unlimited() + +.. _InterfaceRtemsResourceIsUnlimited: + +rtems_resource_is_unlimited() +----------------------------- + +Indicates if the resource is unlimited. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + bool rtems_resource_is_unlimited( uint32_t resource ); + +.. rubric:: PARAMETERS: + +``resource`` + This parameter is the resource number. + +.. rubric:: RETURN VALUES: + +Returns true, if the resource is unlimited, otherwise false. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive is implemented by a macro and may be called from within C/C++ + constant expressions. In addition, a function implementation of the + directive exists for bindings to other programming languages. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/resource-maximum-per-allocation + +.. raw:: latex + + \clearpage + +.. index:: rtems_resource_maximum_per_allocation() + +.. _InterfaceRtemsResourceMaximumPerAllocation: + +rtems_resource_maximum_per_allocation() +--------------------------------------- + +Gets the maximum number per allocation of a resource number. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_resource_maximum_per_allocation( uint32_t resource ); + +.. rubric:: PARAMETERS: + +``resource`` + This parameter is the resource number. + +.. rubric:: RETURN VALUES: + +Returns the maximum number per allocation of a resource number. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive is implemented by a macro and may be called from within C/C++ + constant expressions. In addition, a function implementation of the + directive exists for bindings to other programming languages. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/resource-unlimited + +.. raw:: latex + + \clearpage + +.. index:: rtems_resource_unlimited() + +.. _InterfaceRtemsResourceUnlimited: + +rtems_resource_unlimited() +-------------------------- + +Augments the resource number so that it indicates an unlimited resource. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_resource_unlimited( uint32_t resource ); + +.. rubric:: PARAMETERS: + +``resource`` + This parameter is the resource number to augment. + +.. rubric:: RETURN VALUES: + +Returns the resource number augmented to indicate an unlimited resource. + +.. rubric:: NOTES: + +This directive should be used to configure unlimited objects, see +:ref:`ConfigUnlimitedObjects`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive is implemented by a macro and may be called from within C/C++ + constant expressions. In addition, a function implementation of the + directive exists for bindings to other programming languages. + +* The directive will not cause the calling task to be preempted. diff --git a/c-user/config/event-record.rst b/c-user/config/event-record.rst index cbe02e3..1e5c52a 100644 --- a/c-user/config/event-record.rst +++ b/c-user/config/event-record.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2019, 2020 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2019, 2022 embedded brains GmbH & Co. KG .. This file is part of the RTEMS quality process and was automatically .. generated. If you find something that needs to be fixed or @@ -26,6 +26,10 @@ This section describes configuration options related to the event recording. .. Generated from spec:/acfg/if/record-extensions-enabled +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_RECORD_EXTENSIONS_ENABLED .. _CONFIGURE_RECORD_EXTENSIONS_ENABLED: @@ -33,31 +37,40 @@ This section describes configuration options related to the event recording. CONFIGURE_RECORD_EXTENSIONS_ENABLED ----------------------------------- -CONSTANT: - ``CONFIGURE_RECORD_EXTENSIONS_ENABLED`` +.. rubric:: CONSTANT: + +``CONFIGURE_RECORD_EXTENSIONS_ENABLED`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DESCRIPTION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +In case -DESCRIPTION: - In case +* this configuration option is defined - * this configuration option is defined +* and :ref:`CONFIGURE_RECORD_PER_PROCESSOR_ITEMS` is properly defined, - * and :ref:`CONFIGURE_RECORD_PER_PROCESSOR_ITEMS` is properly defined, +then the event record extensions are enabled. - then the event record extensions are enabled. +.. rubric:: NOTES: -NOTES: - The record extensions capture thread create, start, restart, delete, switch, - begin, exitted and terminate events. +The record extensions capture thread create, start, restart, delete, switch, +begin, exitted and terminate events. .. Generated from spec:/acfg/if/record-fatal-dump-base64 +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_RECORD_FATAL_DUMP_BASE64 .. _CONFIGURE_RECORD_FATAL_DUMP_BASE64: @@ -65,33 +78,42 @@ NOTES: CONFIGURE_RECORD_FATAL_DUMP_BASE64 ---------------------------------- -CONSTANT: - ``CONFIGURE_RECORD_FATAL_DUMP_BASE64`` +.. rubric:: CONSTANT: + +``CONFIGURE_RECORD_FATAL_DUMP_BASE64`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: -OPTION TYPE: - This configuration option is a boolean feature define. +If this configuration option is undefined, then the described feature is not +enabled. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DESCRIPTION: -DESCRIPTION: - In case +In case - * this configuration option is defined +* this configuration option is defined - * and :ref:`CONFIGURE_RECORD_PER_PROCESSOR_ITEMS` is properly defined, +* and :ref:`CONFIGURE_RECORD_PER_PROCESSOR_ITEMS` is properly defined, - * and :ref:`CONFIGURE_RECORD_FATAL_DUMP_BASE64_ZLIB` is undefined, +* and :ref:`CONFIGURE_RECORD_FATAL_DUMP_BASE64_ZLIB` is undefined, - then the event records are dumped in Base64 encoding in a fatal error - extension (see :ref:`Terminate`). +then the event records are dumped in Base64 encoding in a fatal error +extension (see :ref:`Terminate`). -NOTES: - This extension can be used to produce crash dumps. +.. rubric:: NOTES: + +This extension can be used to produce crash dumps. .. Generated from spec:/acfg/if/record-fatal-dump-base64-zlib +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_RECORD_FATAL_DUMP_BASE64_ZLIB .. _CONFIGURE_RECORD_FATAL_DUMP_BASE64_ZLIB: @@ -99,32 +121,82 @@ NOTES: CONFIGURE_RECORD_FATAL_DUMP_BASE64_ZLIB --------------------------------------- -CONSTANT: - ``CONFIGURE_RECORD_FATAL_DUMP_BASE64_ZLIB`` +.. rubric:: CONSTANT: + +``CONFIGURE_RECORD_FATAL_DUMP_BASE64_ZLIB`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case + +* this configuration option is defined + +* and :ref:`CONFIGURE_RECORD_PER_PROCESSOR_ITEMS` is properly defined, -OPTION TYPE: - This configuration option is a boolean feature define. +then the event records are compressed by zlib and dumped in Base64 encoding +in a fatal error extension (see :ref:`Terminate`). -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: NOTES: -DESCRIPTION: - In case +The zlib compression needs about 512KiB of RAM. This extension can be used +to produce crash dumps. - * this configuration option is defined +.. Generated from spec:/acfg/if/record-interrupts-enabled - * and :ref:`CONFIGURE_RECORD_PER_PROCESSOR_ITEMS` is properly defined, +.. raw:: latex - then the event records are compressed by zlib and dumped in Base64 encoding - in a fatal error extension (see :ref:`Terminate`). + \clearpage -NOTES: - The zlib compression needs about 512KiB of RAM. This extension can be used - to produce crash dumps. +.. index:: CONFIGURE_RECORD_INTERRUPTS_ENABLED + +.. _CONFIGURE_RECORD_INTERRUPTS_ENABLED: + +CONFIGURE_RECORD_INTERRUPTS_ENABLED +----------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_RECORD_INTERRUPTS_ENABLED`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case + +* this configuration option is defined + +* and :ref:`CONFIGURE_RECORD_PER_PROCESSOR_ITEMS` is properly defined, + +then the interrupt event recording is enabled. + +.. rubric:: NOTES: + +The interrupt event recording generates interrupt entry and exit events when +interrupt entries are dispatched. .. Generated from spec:/acfg/if/record-per-processor-items +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_RECORD_PER_PROCESSOR_ITEMS .. _CONFIGURE_RECORD_PER_PROCESSOR_ITEMS: @@ -132,34 +204,40 @@ NOTES: CONFIGURE_RECORD_PER_PROCESSOR_ITEMS ------------------------------------ -CONSTANT: - ``CONFIGURE_RECORD_PER_PROCESSOR_ITEMS`` +.. rubric:: CONSTANT: + +``CONFIGURE_RECORD_PER_PROCESSOR_ITEMS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is an integer define. +The value of this configuration option defines the event record item count +per processor. -DEFAULT VALUE: - The default value is 0. +.. rubric:: NOTES: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The event record buffers are statically allocated for each configured +processor (:ref:`CONFIGURE_MAXIMUM_PROCESSORS`). If the value of this +configuration option is zero, then nothing is allocated. - * It shall be greater than or equal to 16. +.. rubric:: CONSTRAINTS: - * It shall be less than or equal to `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_. +The following constraints apply to this configuration option: - * It shall be a power of two. +* The value of the configuration option shall be greater than or equal to 16. - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +* The value of the configuration option shall be less than or equal to + `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_. -DESCRIPTION: - The value of this configuration option defines the event record item count - per processor. +* The value of the configuration option shall be a power of two. -NOTES: - The event record buffers are statically allocated for each configured - processor (:ref:`CONFIGURE_MAXIMUM_PROCESSORS`). If the value of this - configuration option is zero, then nothing is allocated. +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. diff --git a/c-user/config/face-technical-standard.rst b/c-user/config/face-technical-standard.rst new file mode 100644 index 0000000..8772773 --- /dev/null +++ b/c-user/config/face-technical-standard.rst @@ -0,0 +1,76 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2022 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/acfg/if/group-face + +FACE Technical Standard Related Configuration +============================================= + +This section describes configuration options related to adapting +RTEMS behavior to be aligned with the FACE Technical Standard. +The FACE Technical Standard is a product of the FACE Consortium +which operates under the Open Group. The FACE Consortium was founded +by avionics organizations to improve the portability of cockpit software +across various platforms. It addresses technical and business concerns. + +Most important from an RTEMS perspective, the FACE Technical Standard +defines four POSIX profiles: Security, Safety Base, Safety Extended, and +the General Purpose Profile. Each has an increasingly larger subset of +POSIX APIs. In the Security and Safety profiles, ARINC 653 is required. +It is optional in the General Purpose Profile. + +The RTEMS Project has been tracking alignment with the FACE POSIX profiles +and they are included in the "RTEMS POSIX 1003.1 Compliance Guide." + +.. Generated from spec:/acfg/if/posix-timer-face-behavior + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_POSIX_TIMERS_FACE_BEHAVIOR + +.. _CONFIGURE_POSIX_TIMERS_FACE_BEHAVIOR: + +CONFIGURE_POSIX_TIMERS_FACE_BEHAVIOR +------------------------------------ + +.. rubric:: CONSTANT: + +``CONFIGURE_POSIX_TIMERS_FACE_BEHAVIOR`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +If this configuration option is defined, then POSIX timers may not be created +to use the :term:`CLOCK_REALTIME`. Per POSIX, this is allowed +behavior but per the FACE Technical Standard, it is not. Using POSIX timers +based on CLOCK_REALTIME (e.g., time of day) is unsafe for real-time safety +systems as setting CLOCK_REALTIME will perturb any active timers. + +If this option is not defined, POSIX timers may be created to use the +CLOCK_REALTIME in compliance with the POSIX specification. diff --git a/c-user/config/filesystem.rst b/c-user/config/filesystem.rst index 5b1b414..c565f4c 100644 --- a/c-user/config/filesystem.rst +++ b/c-user/config/filesystem.rst @@ -1,7 +1,7 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2023 On-Line Applications Research Corporation (OAR) .. This file is part of the RTEMS quality process and was automatically .. generated. If you find something that needs to be fixed or @@ -67,6 +67,10 @@ configuration options: .. Generated from spec:/acfg/if/appl-disable-filesystem +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_APPLICATION_DISABLE_FILESYSTEM .. _CONFIGURE_APPLICATION_DISABLE_FILESYSTEM: @@ -74,28 +78,37 @@ configuration options: CONFIGURE_APPLICATION_DISABLE_FILESYSTEM ---------------------------------------- -CONSTANT: - ``CONFIGURE_APPLICATION_DISABLE_FILESYSTEM`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_DISABLE_FILESYSTEM`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: -OPTION TYPE: - This configuration option is a boolean feature define. +If this configuration option is undefined, then a base filesystem and the +configured filesystems are initialized during system initialization. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then a base filesystem and the - configured filesystems are initialized during system initialization. +.. rubric:: DESCRIPTION: -DESCRIPTION: - In case this configuration option is defined, then **no base filesystem** is - initialized during system initialization and **no filesystems** are - configured. +In case this configuration option is defined, then **no base filesystem** is +initialized during system initialization and **no filesystems** are +configured. -NOTES: - Filesystems shall be initialized to support file descriptor based device - drivers and basic input/output functions such as :c:func:`printf`. - Filesystems can be disabled to reduce the memory footprint of an application. +.. rubric:: NOTES: + +Filesystems shall be initialized to support file descriptor based device +drivers and basic input/output functions such as :c:func:`printf`. +Filesystems can be disabled to reduce the memory footprint of an application. .. Generated from spec:/acfg/if/filesystem-all +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_FILESYSTEM_ALL .. _CONFIGURE_FILESYSTEM_ALL: @@ -103,39 +116,44 @@ NOTES: CONFIGURE_FILESYSTEM_ALL ------------------------ -CONSTANT: - ``CONFIGURE_FILESYSTEM_ALL`` +.. rubric:: CONSTANT: + +``CONFIGURE_FILESYSTEM_ALL`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then the following - configuration options will be defined as well +If this configuration option is undefined, then the described feature is not +enabled. - * :ref:`CONFIGURE_FILESYSTEM_DOSFS`, +.. rubric:: DESCRIPTION: - * :ref:`CONFIGURE_FILESYSTEM_FTPFS`, +In case this configuration option is defined, then the following +configuration options will be defined as well - * :ref:`CONFIGURE_FILESYSTEM_IMFS`, +* :ref:`CONFIGURE_FILESYSTEM_DOSFS`, - * :ref:`CONFIGURE_FILESYSTEM_JFFS2`, +* :ref:`CONFIGURE_FILESYSTEM_FTPFS`, - * :ref:`CONFIGURE_FILESYSTEM_NFS`, +* :ref:`CONFIGURE_FILESYSTEM_IMFS`, - * :ref:`CONFIGURE_FILESYSTEM_RFS`, and +* :ref:`CONFIGURE_FILESYSTEM_JFFS2`, - * :ref:`CONFIGURE_FILESYSTEM_TFTPFS`. +* :ref:`CONFIGURE_FILESYSTEM_NFS`, -NOTES: - None. +* :ref:`CONFIGURE_FILESYSTEM_RFS`, and + +* :ref:`CONFIGURE_FILESYSTEM_TFTPFS`. .. Generated from spec:/acfg/if/filesystem-dosfs +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_FILESYSTEM_DOSFS .. _CONFIGURE_FILESYSTEM_DOSFS: @@ -143,27 +161,36 @@ NOTES: CONFIGURE_FILESYSTEM_DOSFS -------------------------- -CONSTANT: - ``CONFIGURE_FILESYSTEM_DOSFS`` +.. rubric:: CONSTANT: + +``CONFIGURE_FILESYSTEM_DOSFS`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then the DOS (FAT) filesystem - is registered, so that instances of this filesystem can be mounted by the - application. +If this configuration option is undefined, then the described feature is not +enabled. -NOTES: - This filesystem requires a Block Device Cache configuration, see - :ref:`CONFIGURE_APPLICATION_NEEDS_LIBBLOCK`. +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the DOS (FAT) filesystem +is registered, so that instances of this filesystem can be mounted by the +application. + +.. rubric:: NOTES: + +This filesystem requires a Block Device Cache configuration, see +:ref:`CONFIGURE_APPLICATION_NEEDS_LIBBLOCK`. .. Generated from spec:/acfg/if/filesystem-ftpfs +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_FILESYSTEM_FTPFS .. _CONFIGURE_FILESYSTEM_FTPFS: @@ -171,26 +198,31 @@ NOTES: CONFIGURE_FILESYSTEM_FTPFS -------------------------- -CONSTANT: - ``CONFIGURE_FILESYSTEM_FTPFS`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is a boolean feature define. +``CONFIGURE_FILESYSTEM_FTPFS`` -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: OPTION TYPE: -DESCRIPTION: - In case this configuration option is defined, then the FTP filesystem (FTP - client) is registered, so that instances of this filesystem - can be mounted by the application. +This configuration option is a boolean feature define. -NOTES: - None. +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the FTP filesystem (FTP +client) is registered, so that instances of this filesystem +can be mounted by the application. .. Generated from spec:/acfg/if/filesystem-imfs +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_FILESYSTEM_IMFS .. _CONFIGURE_FILESYSTEM_IMFS: @@ -198,28 +230,37 @@ NOTES: CONFIGURE_FILESYSTEM_IMFS ------------------------- -CONSTANT: - ``CONFIGURE_FILESYSTEM_IMFS`` +.. rubric:: CONSTANT: + +``CONFIGURE_FILESYSTEM_IMFS`` -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: OPTION TYPE: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +This configuration option is a boolean feature define. -DESCRIPTION: - In case this configuration option is defined, then the In-Memory Filesystem - (IMFS) is registered, so that instances of this filesystem can be mounted by - the application. +.. rubric:: DEFAULT CONFIGURATION: -NOTES: - Applications will rarely need this configuration option. This configuration - option is intended for test programs. You do not need to define this - configuration option for the base filesystem (also known as root filesystem). +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the In-Memory Filesystem +(IMFS) is registered, so that instances of this filesystem can be mounted by +the application. + +.. rubric:: NOTES: + +Applications will rarely need this configuration option. This configuration +option is intended for test programs. You do not need to define this +configuration option for the base filesystem (also known as root filesystem). .. Generated from spec:/acfg/if/filesystem-jffs2 +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_FILESYSTEM_JFFS2 .. _CONFIGURE_FILESYSTEM_JFFS2: @@ -227,26 +268,31 @@ NOTES: CONFIGURE_FILESYSTEM_JFFS2 -------------------------- -CONSTANT: - ``CONFIGURE_FILESYSTEM_JFFS2`` +.. rubric:: CONSTANT: + +``CONFIGURE_FILESYSTEM_JFFS2`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then the JFFS2 filesystem - is registered, so that instances of this filesystem can be mounted by the - application. +If this configuration option is undefined, then the described feature is not +enabled. -NOTES: - None. +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the JFFS2 filesystem +is registered, so that instances of this filesystem can be mounted by the +application. .. Generated from spec:/acfg/if/filesystem-nfs +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_FILESYSTEM_NFS .. _CONFIGURE_FILESYSTEM_NFS: @@ -254,26 +300,31 @@ NOTES: CONFIGURE_FILESYSTEM_NFS ------------------------ -CONSTANT: - ``CONFIGURE_FILESYSTEM_NFS`` +.. rubric:: CONSTANT: + +``CONFIGURE_FILESYSTEM_NFS`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then the Network Filesystem - (NFS) client is registered, so that instances of this filesystem can be - mounted by the application. +If this configuration option is undefined, then the described feature is not +enabled. -NOTES: - None. +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the Network Filesystem +(NFS) client is registered, so that instances of this filesystem can be +mounted by the application. .. Generated from spec:/acfg/if/filesystem-rfs +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_FILESYSTEM_RFS .. _CONFIGURE_FILESYSTEM_RFS: @@ -281,27 +332,36 @@ NOTES: CONFIGURE_FILESYSTEM_RFS ------------------------ -CONSTANT: - ``CONFIGURE_FILESYSTEM_RFS`` +.. rubric:: CONSTANT: + +``CONFIGURE_FILESYSTEM_RFS`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DESCRIPTION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +In case this configuration option is defined, then the RTEMS Filesystem (RFS) +is registered, so that instances of this filesystem can be mounted by the +application. -DESCRIPTION: - In case this configuration option is defined, then the RTEMS Filesystem (RFS) - is registered, so that instances of this filesystem can be mounted by the - application. +.. rubric:: NOTES: -NOTES: - This filesystem requires a Block Device Cache configuration, see - :ref:`CONFIGURE_APPLICATION_NEEDS_LIBBLOCK`. +This filesystem requires a Block Device Cache configuration, see +:ref:`CONFIGURE_APPLICATION_NEEDS_LIBBLOCK`. .. Generated from spec:/acfg/if/filesystem-tftpfs +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_FILESYSTEM_TFTPFS .. _CONFIGURE_FILESYSTEM_TFTPFS: @@ -309,26 +369,31 @@ NOTES: CONFIGURE_FILESYSTEM_TFTPFS --------------------------- -CONSTANT: - ``CONFIGURE_FILESYSTEM_TFTPFS`` +.. rubric:: CONSTANT: + +``CONFIGURE_FILESYSTEM_TFTPFS`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DEFAULT CONFIGURATION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +If this configuration option is undefined, then the described feature is not +enabled. -DESCRIPTION: - In case this configuration option is defined, then the TFTP filesystem (TFTP - client) is registered, so that instances of this filesystem can be mounted by - the application. +.. rubric:: DESCRIPTION: -NOTES: - None. +In case this configuration option is defined, then the TFTP filesystem (TFTP +client) is registered, so that instances of this filesystem can be mounted by +the application. .. Generated from spec:/acfg/if/imfs-disable-chmod +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_IMFS_DISABLE_CHMOD .. _CONFIGURE_IMFS_DISABLE_CHMOD: @@ -336,25 +401,30 @@ NOTES: CONFIGURE_IMFS_DISABLE_CHMOD ---------------------------- -CONSTANT: - ``CONFIGURE_IMFS_DISABLE_CHMOD`` +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_CHMOD`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DEFAULT CONFIGURATION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the root IMFS supports - changing the mode of files. +If this configuration option is undefined, then the root IMFS supports +changing the mode of files. -DESCRIPTION: - In case this configuration option is defined, then the root IMFS does not - support changing the mode of files (no support for :c:func:`chmod`). +.. rubric:: DESCRIPTION: -NOTES: - None. +In case this configuration option is defined, then the root IMFS does not +support changing the mode of files (no support for :c:func:`chmod`). .. Generated from spec:/acfg/if/imfs-disable-chown +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_IMFS_DISABLE_CHOWN .. _CONFIGURE_IMFS_DISABLE_CHOWN: @@ -362,25 +432,30 @@ NOTES: CONFIGURE_IMFS_DISABLE_CHOWN ---------------------------- -CONSTANT: - ``CONFIGURE_IMFS_DISABLE_CHOWN`` +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_CHOWN`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DEFAULT CONFIGURATION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the root IMFS supports - changing the ownership of files. +If this configuration option is undefined, then the root IMFS supports +changing the ownership of files. -DESCRIPTION: - In case this configuration option is defined, then the root IMFS does not - support changing the ownership of files (no support for :c:func:`chown`). +.. rubric:: DESCRIPTION: -NOTES: - None. +In case this configuration option is defined, then the root IMFS does not +support changing the ownership of files (no support for :c:func:`chown`). .. Generated from spec:/acfg/if/imfs-disable-link +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_IMFS_DISABLE_LINK .. _CONFIGURE_IMFS_DISABLE_LINK: @@ -388,25 +463,30 @@ NOTES: CONFIGURE_IMFS_DISABLE_LINK --------------------------- -CONSTANT: - ``CONFIGURE_IMFS_DISABLE_LINK`` +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_LINK`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DEFAULT CONFIGURATION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the root IMFS supports hard - links. +If this configuration option is undefined, then the root IMFS supports hard +links. -DESCRIPTION: - In case this configuration option is defined, then the root IMFS does not - support hard links (no support for :c:func:`link`). +.. rubric:: DESCRIPTION: -NOTES: - None. +In case this configuration option is defined, then the root IMFS does not +support hard links (no support for :c:func:`link`). .. Generated from spec:/acfg/if/imfs-disable-mknod +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_IMFS_DISABLE_MKNOD .. _CONFIGURE_IMFS_DISABLE_MKNOD: @@ -414,25 +494,30 @@ NOTES: CONFIGURE_IMFS_DISABLE_MKNOD ---------------------------- -CONSTANT: - ``CONFIGURE_IMFS_DISABLE_MKNOD`` +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_MKNOD`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DEFAULT CONFIGURATION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the root IMFS supports making - files. +If this configuration option is undefined, then the root IMFS supports making +files. -DESCRIPTION: - In case this configuration option is defined, then the root IMFS does not - support making files (no support for :c:func:`mknod`). +.. rubric:: DESCRIPTION: -NOTES: - None. +In case this configuration option is defined, then the root IMFS does not +support making files (no support for :c:func:`mknod`). .. Generated from spec:/acfg/if/imfs-disable-mknod-device +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_IMFS_DISABLE_MKNOD_DEVICE .. _CONFIGURE_IMFS_DISABLE_MKNOD_DEVICE: @@ -440,25 +525,30 @@ NOTES: CONFIGURE_IMFS_DISABLE_MKNOD_DEVICE ----------------------------------- -CONSTANT: - ``CONFIGURE_IMFS_DISABLE_MKNOD_DEVICE`` +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_MKNOD_DEVICE`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DEFAULT CONFIGURATION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the root IMFS supports making - device files. +If this configuration option is undefined, then the root IMFS supports making +device files. -DESCRIPTION: - In case this configuration option is defined, then the root IMFS does not - support making device files. +.. rubric:: DESCRIPTION: -NOTES: - None. +In case this configuration option is defined, then the root IMFS does not +support making device files. .. Generated from spec:/acfg/if/imfs-disable-mknod-file +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_IMFS_DISABLE_MKNOD_FILE .. _CONFIGURE_IMFS_DISABLE_MKNOD_FILE: @@ -466,25 +556,30 @@ NOTES: CONFIGURE_IMFS_DISABLE_MKNOD_FILE --------------------------------- -CONSTANT: - ``CONFIGURE_IMFS_DISABLE_MKNOD_FILE`` +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_MKNOD_FILE`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DEFAULT CONFIGURATION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the root IMFS supports making - regular files. +If this configuration option is undefined, then the root IMFS supports making +regular files. -DESCRIPTION: - In case this configuration option is defined, then the root IMFS does not - support making regular files. +.. rubric:: DESCRIPTION: -NOTES: - None. +In case this configuration option is defined, then the root IMFS does not +support making regular files. .. Generated from spec:/acfg/if/imfs-disable-mount +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_IMFS_DISABLE_MOUNT .. _CONFIGURE_IMFS_DISABLE_MOUNT: @@ -492,26 +587,31 @@ NOTES: CONFIGURE_IMFS_DISABLE_MOUNT ---------------------------- -CONSTANT: - ``CONFIGURE_IMFS_DISABLE_MOUNT`` +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_MOUNT`` -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: OPTION TYPE: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the root IMFS supports - mounting other filesystems. +This configuration option is a boolean feature define. -DESCRIPTION: - In case this configuration option is defined, then the root IMFS does not - support mounting other filesystems (no support for - :c:func:`mount`). +.. rubric:: DEFAULT CONFIGURATION: -NOTES: - None. +If this configuration option is undefined, then the root IMFS supports +mounting other filesystems. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the root IMFS does not +support mounting other filesystems (no support for +:c:func:`mount`). .. Generated from spec:/acfg/if/imfs-disable-readdir +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_IMFS_DISABLE_READDIR .. _CONFIGURE_IMFS_DISABLE_READDIR: @@ -519,26 +619,31 @@ NOTES: CONFIGURE_IMFS_DISABLE_READDIR ------------------------------ -CONSTANT: - ``CONFIGURE_IMFS_DISABLE_READDIR`` +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_READDIR`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the root IMFS supports - reading directories. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then the root IMFS does not - support reading directories (no support for :c:func:`readdir`). It is - still possible to open files in a directory. +If this configuration option is undefined, then the root IMFS supports +reading directories. -NOTES: - None. +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the root IMFS does not +support reading directories (no support for :c:func:`readdir`). It is +still possible to open files in a directory. .. Generated from spec:/acfg/if/imfs-disable-readlink +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_IMFS_DISABLE_READLINK .. _CONFIGURE_IMFS_DISABLE_READLINK: @@ -546,25 +651,30 @@ NOTES: CONFIGURE_IMFS_DISABLE_READLINK ------------------------------- -CONSTANT: - ``CONFIGURE_IMFS_DISABLE_READLINK`` +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_READLINK`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the root IMFS supports - reading symbolic links. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then the root IMFS does not - support reading symbolic links (no support for :c:func:`readlink`). +If this configuration option is undefined, then the root IMFS supports +reading symbolic links. -NOTES: - None. +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the root IMFS does not +support reading symbolic links (no support for :c:func:`readlink`). .. Generated from spec:/acfg/if/imfs-disable-rename +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_IMFS_DISABLE_RENAME .. _CONFIGURE_IMFS_DISABLE_RENAME: @@ -572,25 +682,30 @@ NOTES: CONFIGURE_IMFS_DISABLE_RENAME ----------------------------- -CONSTANT: - ``CONFIGURE_IMFS_DISABLE_RENAME`` +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_RENAME`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the root IMFS supports - renaming files. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then the root IMFS does not - support renaming files (no support for :c:func:`rename`). +If this configuration option is undefined, then the root IMFS supports +renaming files. -NOTES: - None. +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the root IMFS does not +support renaming files (no support for :c:func:`rename`). .. Generated from spec:/acfg/if/imfs-disable-rmnod +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_IMFS_DISABLE_RMNOD .. _CONFIGURE_IMFS_DISABLE_RMNOD: @@ -598,25 +713,30 @@ NOTES: CONFIGURE_IMFS_DISABLE_RMNOD ---------------------------- -CONSTANT: - ``CONFIGURE_IMFS_DISABLE_RMNOD`` +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_RMNOD`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the root IMFS supports - removing files. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then the root IMFS does not - support removing files (no support for :c:func:`rmnod`). +If this configuration option is undefined, then the root IMFS supports +removing files. -NOTES: - None. +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the root IMFS does not +support removing files (no support for :c:func:`rmnod`). .. Generated from spec:/acfg/if/imfs-disable-symlink +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_IMFS_DISABLE_SYMLINK .. _CONFIGURE_IMFS_DISABLE_SYMLINK: @@ -624,25 +744,30 @@ NOTES: CONFIGURE_IMFS_DISABLE_SYMLINK ------------------------------ -CONSTANT: - ``CONFIGURE_IMFS_DISABLE_SYMLINK`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is a boolean feature define. +``CONFIGURE_IMFS_DISABLE_SYMLINK`` -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the root IMFS supports - creating symbolic links. +.. rubric:: OPTION TYPE: -DESCRIPTION: - In case this configuration option is defined, then the root IMFS does not - support creating symbolic links (no support for :c:func:`symlink`). +This configuration option is a boolean feature define. -NOTES: - None. +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the root IMFS supports +creating symbolic links. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the root IMFS does not +support creating symbolic links (no support for :c:func:`symlink`). .. Generated from spec:/acfg/if/imfs-disable-unmount +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_IMFS_DISABLE_UNMOUNT .. _CONFIGURE_IMFS_DISABLE_UNMOUNT: @@ -650,26 +775,31 @@ NOTES: CONFIGURE_IMFS_DISABLE_UNMOUNT ------------------------------ -CONSTANT: - ``CONFIGURE_IMFS_DISABLE_UNMOUNT`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is a boolean feature define. +``CONFIGURE_IMFS_DISABLE_UNMOUNT`` -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the root IMFS supports - unmounting other filesystems. +.. rubric:: OPTION TYPE: -DESCRIPTION: - In case this configuration option is defined, then the root IMFS does not - support unmounting other filesystems (no support for - :c:func:`unmount`). +This configuration option is a boolean feature define. -NOTES: - None. +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the root IMFS supports +unmounting other filesystems. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the root IMFS does not +support unmounting other filesystems (no support for +:c:func:`unmount`). .. Generated from spec:/acfg/if/imfs-disable-utime +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_IMFS_DISABLE_UTIME .. _CONFIGURE_IMFS_DISABLE_UTIME: @@ -677,25 +807,30 @@ NOTES: CONFIGURE_IMFS_DISABLE_UTIME ---------------------------- -CONSTANT: - ``CONFIGURE_IMFS_DISABLE_UTIME`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is a boolean feature define. +``CONFIGURE_IMFS_DISABLE_UTIME`` -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the root IMFS supports - changing file times. +.. rubric:: OPTION TYPE: -DESCRIPTION: - In case this configuration option is defined, then the root IMFS does not - support changing file times (no support for :c:func:`utime`). +This configuration option is a boolean feature define. -NOTES: - None. +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the root IMFS supports +changing file times. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the root IMFS does not +support changing file times (no support for :c:func:`utime`). .. Generated from spec:/acfg/if/imfs-enable-mkfifo +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_IMFS_ENABLE_MKFIFO .. _CONFIGURE_IMFS_ENABLE_MKFIFO: @@ -703,25 +838,30 @@ NOTES: CONFIGURE_IMFS_ENABLE_MKFIFO ---------------------------- -CONSTANT: - ``CONFIGURE_IMFS_ENABLE_MKFIFO`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is a boolean feature define. +``CONFIGURE_IMFS_ENABLE_MKFIFO`` -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the root IMFS does not - support making FIFOs (no support for :c:func:`mkfifo`). +.. rubric:: OPTION TYPE: -DESCRIPTION: - In case this configuration option is defined, then the root IMFS supports - making FIFOs. +This configuration option is a boolean feature define. -NOTES: - None. +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the root IMFS does not +support making FIFOs (no support for :c:func:`mkfifo`). + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the root IMFS supports +making FIFOs. .. Generated from spec:/acfg/if/imfs-memfile-bytes-per-block +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_IMFS_MEMFILE_BYTES_PER_BLOCK .. _CONFIGURE_IMFS_MEMFILE_BYTES_PER_BLOCK: @@ -729,52 +869,97 @@ NOTES: CONFIGURE_IMFS_MEMFILE_BYTES_PER_BLOCK -------------------------------------- -CONSTANT: - ``CONFIGURE_IMFS_MEMFILE_BYTES_PER_BLOCK`` +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_MEMFILE_BYTES_PER_BLOCK`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 128. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the block size for in-memory +files managed by the IMFS. + +.. rubric:: NOTES: + +The configured block size has two impacts. The first is the average amount of +unused memory in the last block of each file. For example, when the block +size is 512, on average one-half of the last block of each file will remain +unused and the memory is wasted. In contrast, when the block size is 16, the +average unused memory per file is only 8 bytes. However, it requires more +allocations for the same size file and thus more overhead per block for the +dynamic memory management. + +Second, the block size has an impact on the maximum size file that can be +stored in the IMFS. With smaller block size, the maximum file size is +correspondingly smaller. The following shows the maximum file size possible +based on the configured block size: + +* when the block size is 16 bytes, the maximum file size is 1,328 bytes. + +* when the block size is 32 bytes, the maximum file size is 18,656 bytes. + +* when the block size is 64 bytes, the maximum file size is 279,488 bytes. + +* when the block size is 128 bytes, the maximum file size is 4,329,344 bytes. + +* 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. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: CONSTRAINTS: -DEFAULT VALUE: - The default value is 128. +The value of the configuration option shall be equal to 16, 32, 64, 128, 256, +or 512. -VALUE CONSTRAINTS: - The value of this configuration option shall be - an element of {16, 32, 64, 128, 256, 512}. +.. Generated from spec:/acfg/if/jffs2-delayed-write-task-priority -DESCRIPTION: - The value of this configuration option defines the block size for in-memory - files managed by the IMFS. +.. raw:: latex -NOTES: - The configured block size has two impacts. The first is the average amount of - unused memory in the last block of each file. For example, when the block - size is 512, on average one-half of the last block of each file will remain - unused and the memory is wasted. In contrast, when the block size is 16, the - average unused memory per file is only 8 bytes. However, it requires more - allocations for the same size file and thus more overhead per block for the - dynamic memory management. + \clearpage - 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: +.. index:: CONFIGURE_JFFS2_DELAYED_WRITE_TASK_PRIORITY - * when the block size is 16 bytes, the maximum file size is 1,328 bytes. +.. _CONFIGURE_JFFS2_DELAYED_WRITE_TASK_PRIORITY: - * when the block size is 32 bytes, the maximum file size is 18,656 bytes. +CONFIGURE_JFFS2_DELAYED_WRITE_TASK_PRIORITY +------------------------------------------- - * when the block size is 64 bytes, the maximum file size is 279,488 bytes. +.. rubric:: CONSTANT: - * when the block size is 128 bytes, the maximum file size is 4,329,344 bytes. +``CONFIGURE_JFFS2_DELAYED_WRITE_TASK_PRIORITY`` - * when the block size is 256 bytes, the maximum file size is 68,173,568 bytes. +.. rubric:: OPTION TYPE: - * when the block size is 512 bytes, the maximum file size is 1,082,195,456 - bytes. +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 15. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the JFFS2 delayed write task priority. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be a valid Classic API task +priority. The set of valid task priorities depends on the scheduler +configuration. .. Generated from spec:/acfg/if/use-devfs-as-base-filesystem +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM .. _CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM: @@ -782,57 +967,66 @@ NOTES: CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM -------------------------------------- -CONSTANT: - ``CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM`` +.. rubric:: CONSTANT: + +``CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then an IMFS with a reduced - feature set will be the base filesystem (also known as root filesystem). +If this configuration option is undefined, then the described feature is not +enabled. -NOTES: - In case this configuration option is defined, then the following - configuration options will be defined as well +.. rubric:: DESCRIPTION: - * :ref:`CONFIGURE_IMFS_DISABLE_CHMOD`, +In case this configuration option is defined, then an IMFS with a reduced +feature set will be the base filesystem (also known as root filesystem). - * :ref:`CONFIGURE_IMFS_DISABLE_CHOWN`, +.. rubric:: NOTES: - * :ref:`CONFIGURE_IMFS_DISABLE_LINK`, +In case this configuration option is defined, then the following +configuration options will be defined as well - * :ref:`CONFIGURE_IMFS_DISABLE_MKNOD_FILE`, +* :ref:`CONFIGURE_IMFS_DISABLE_CHMOD`, - * :ref:`CONFIGURE_IMFS_DISABLE_MOUNT`, +* :ref:`CONFIGURE_IMFS_DISABLE_CHOWN`, - * :ref:`CONFIGURE_IMFS_DISABLE_READDIR`, +* :ref:`CONFIGURE_IMFS_DISABLE_LINK`, - * :ref:`CONFIGURE_IMFS_DISABLE_READLINK`, +* :ref:`CONFIGURE_IMFS_DISABLE_MKNOD_FILE`, - * :ref:`CONFIGURE_IMFS_DISABLE_RENAME`, +* :ref:`CONFIGURE_IMFS_DISABLE_MOUNT`, - * :ref:`CONFIGURE_IMFS_DISABLE_RMNOD`, +* :ref:`CONFIGURE_IMFS_DISABLE_READDIR`, - * :ref:`CONFIGURE_IMFS_DISABLE_SYMLINK`, +* :ref:`CONFIGURE_IMFS_DISABLE_READLINK`, - * :ref:`CONFIGURE_IMFS_DISABLE_UTIME`, and +* :ref:`CONFIGURE_IMFS_DISABLE_RENAME`, - * :ref:`CONFIGURE_IMFS_DISABLE_UNMOUNT`. +* :ref:`CONFIGURE_IMFS_DISABLE_RMNOD`, - In addition, a simplified path evaluation is enabled. It allows only a look - up of absolute paths. +* :ref:`CONFIGURE_IMFS_DISABLE_SYMLINK`, - This configuration of the IMFS is basically a device-only filesystem. It is - comparable in functionality to the pseudo-filesystem name space provided - before RTEMS release 4.5.0. +* :ref:`CONFIGURE_IMFS_DISABLE_UTIME`, and + +* :ref:`CONFIGURE_IMFS_DISABLE_UNMOUNT`. + +In addition, a simplified path evaluation is enabled. It allows only a look +up of absolute paths. + +This configuration of the IMFS is basically a device-only filesystem. It is +comparable in functionality to the pseudo-filesystem name space provided +before RTEMS release 4.5.0. .. Generated from spec:/acfg/if/use-miniimfs-as-base-filesystem +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_USE_MINIIMFS_AS_BASE_FILESYSTEM .. _CONFIGURE_USE_MINIIMFS_AS_BASE_FILESYSTEM: @@ -840,36 +1034,41 @@ NOTES: CONFIGURE_USE_MINIIMFS_AS_BASE_FILESYSTEM ----------------------------------------- -CONSTANT: - ``CONFIGURE_USE_MINIIMFS_AS_BASE_FILESYSTEM`` +.. rubric:: CONSTANT: + +``CONFIGURE_USE_MINIIMFS_AS_BASE_FILESYSTEM`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DESCRIPTION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +In case this configuration option is defined, then an IMFS with a reduced +feature set will be the base filesystem (also known as root filesystem). -DESCRIPTION: - In case this configuration option is defined, then an IMFS with a reduced - feature set will be the base filesystem (also known as root filesystem). +.. rubric:: NOTES: -NOTES: - In case this configuration option is defined, then the following - configuration options will be defined as well +In case this configuration option is defined, then the following +configuration options will be defined as well - * :ref:`CONFIGURE_IMFS_DISABLE_CHMOD`, +* :ref:`CONFIGURE_IMFS_DISABLE_CHMOD`, - * :ref:`CONFIGURE_IMFS_DISABLE_CHOWN`, +* :ref:`CONFIGURE_IMFS_DISABLE_CHOWN`, - * :ref:`CONFIGURE_IMFS_DISABLE_LINK`, +* :ref:`CONFIGURE_IMFS_DISABLE_LINK`, - * :ref:`CONFIGURE_IMFS_DISABLE_READLINK`, +* :ref:`CONFIGURE_IMFS_DISABLE_READLINK`, - * :ref:`CONFIGURE_IMFS_DISABLE_RENAME`, +* :ref:`CONFIGURE_IMFS_DISABLE_RENAME`, - * :ref:`CONFIGURE_IMFS_DISABLE_SYMLINK`, +* :ref:`CONFIGURE_IMFS_DISABLE_SYMLINK`, - * :ref:`CONFIGURE_IMFS_DISABLE_UTIME`, and +* :ref:`CONFIGURE_IMFS_DISABLE_UTIME`, and - * :ref:`CONFIGURE_IMFS_DISABLE_UNMOUNT`. +* :ref:`CONFIGURE_IMFS_DISABLE_UNMOUNT`. diff --git a/c-user/config/general.rst b/c-user/config/general.rst index 024b5c4..61bfa1e 100644 --- a/c-user/config/general.rst +++ b/c-user/config/general.rst @@ -1,7 +1,7 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +.. Copyright (C) 2020, 2023 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2022 On-Line Applications Research Corporation (OAR) .. This file is part of the RTEMS quality process and was automatically .. generated. If you find something that needs to be fixed or @@ -27,6 +27,10 @@ This section describes general system configuration options. .. Generated from spec:/acfg/if/dirty-memory +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_DIRTY_MEMORY .. _CONFIGURE_DIRTY_MEMORY: @@ -34,32 +38,90 @@ This section describes general system configuration options. CONFIGURE_DIRTY_MEMORY ---------------------- -CONSTANT: - ``CONFIGURE_DIRTY_MEMORY`` +.. rubric:: CONSTANT: + +``CONFIGURE_DIRTY_MEMORY`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the memory areas used for +the RTEMS Workspace and the C Program Heap are dirtied with a ``0xCF`` byte +pattern during system initialization. + +.. rubric:: NOTES: + +Dirtying memory can add significantly to system initialization time. It may +assist in finding code that incorrectly assumes the contents of free memory +areas is cleared to zero during system initialization. In case +:ref:`CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY` is also defined, then the +memory is first dirtied and then zeroed. + +See also :ref:`CONFIGURE_MALLOC_DIRTY`. + +.. Generated from spec:/acfg/if/disable-bsp-settings + +.. raw:: latex + + \clearpage -OPTION TYPE: - This configuration option is a boolean feature define. +.. index:: CONFIGURE_DISABLE_BSP_SETTINGS -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. _CONFIGURE_DISABLE_BSP_SETTINGS: -DESCRIPTION: - In case this configuration option is defined, then the memory areas used for - the RTEMS Workspace and the C Program Heap are dirtied with a ``0xCF`` byte - pattern during system initialization. +CONFIGURE_DISABLE_BSP_SETTINGS +------------------------------ + +.. rubric:: CONSTANT: + +``CONFIGURE_DISABLE_BSP_SETTINGS`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: -NOTES: - Dirtying memory can add significantly to system initialization time. It may - assist in finding code that incorrectly assumes the contents of free memory - areas is cleared to zero during system initialization. In case - :ref:`CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY` is also defined, then the - memory is first dirtied and then zeroed. +In case this configuration option is defined, then the optional BSP provided +settings listed below are disabled. - See also :ref:`CONFIGURE_MALLOC_DIRTY`. +The optional BSP provided default values for the following application +configuration options are disabled: + +* :ref:`CONFIGURE_IDLE_TASK_BODY` + +* :ref:`CONFIGURE_IDLE_TASK_STACK_SIZE` + +* :ref:`CONFIGURE_INTERRUPT_STACK_SIZE` + +The optional BSP provided initial extension set is disabled (see +:term:`initial extension sets`). The optional BSP provided +prerequisite IO device drivers are disabled (see +Device Driver Configuration). The optional BSP provided support for +:c:func:`sbrk` is disabled. + +This configuration option provides an all or nothing choice with respect to +the optional BSP provided settings. .. Generated from spec:/acfg/if/disable-newlib-reentrancy +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_DISABLE_NEWLIB_REENTRANCY .. _CONFIGURE_DISABLE_NEWLIB_REENTRANCY: @@ -67,28 +129,37 @@ NOTES: CONFIGURE_DISABLE_NEWLIB_REENTRANCY ----------------------------------- -CONSTANT: - ``CONFIGURE_DISABLE_NEWLIB_REENTRANCY`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is a boolean feature define. +``CONFIGURE_DISABLE_NEWLIB_REENTRANCY`` -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: OPTION TYPE: -DESCRIPTION: - In case this configuration option is defined, then the Newlib reentrancy - support per thread is disabled and a global reentrancy structure is used. +This configuration option is a boolean feature define. -NOTES: - You can enable this option to reduce the size of the :term:`TCB`. Use this - option with care, since it can lead to race conditions and undefined system - behaviour. For example, :c:macro:`errno` is no longer a thread-local - variable if this option is enabled. +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the Newlib reentrancy +support per thread is disabled and a global reentrancy structure is used. + +.. rubric:: NOTES: + +You can enable this option to reduce the size of the :term:`TCB`. Use this +option with care, since it can lead to race conditions and undefined system +behaviour. For example, :c:macro:`errno` is no longer a thread-local +variable if this option is enabled. .. Generated from spec:/acfg/if/executive-ram-size +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_EXECUTIVE_RAM_SIZE .. _CONFIGURE_EXECUTIVE_RAM_SIZE: @@ -96,39 +167,49 @@ NOTES: CONFIGURE_EXECUTIVE_RAM_SIZE ---------------------------- -CONSTANT: - ``CONFIGURE_EXECUTIVE_RAM_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_EXECUTIVE_RAM_SIZE`` -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: OPTION TYPE: -DEFAULT VALUE: - If this configuration option is undefined, then the RTEMS Workspace and task - stack space size is calculated by ``<rtems/confdefs.h>`` based on the values - configuration options. +This configuration option is an integer define. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: DEFAULT VALUE: - * It shall be greater than or equal to 0. +If this configuration option is undefined, then the RTEMS Workspace and task +stack space size is calculated by ``<rtems/confdefs.h>`` based on the +values configuration options. - * It shall be less than or equal to `UINTPTR_MAX <https://en.cppreference.com/w/c/types/integer>`_. +.. rubric:: DESCRIPTION: - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +The value of this configuration option defines the RTEMS Workspace size in +bytes. -DESCRIPTION: - The value of this configuration option defines the RTEMS Workspace size in - bytes. +.. rubric:: NOTES: -NOTES: - This is an advanced configuration option. Use it only if you know exactly - what you are doing. +This is an advanced configuration option. Use it only if you know exactly +what you are doing. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `UINTPTR_MAX <https://en.cppreference.com/w/c/types/integer>`_. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. .. Generated from spec:/acfg/if/extra-task-stacks +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_EXTRA_TASK_STACKS .. index:: memory for task tasks @@ -137,37 +218,83 @@ NOTES: CONFIGURE_EXTRA_TASK_STACKS --------------------------- -CONSTANT: - ``CONFIGURE_EXTRA_TASK_STACKS`` +.. rubric:: CONSTANT: + +``CONFIGURE_EXTRA_TASK_STACKS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the number of bytes the +applications wishes to add to the task stack requirements calculated by +``<rtems/confdefs.h>``. + +.. rubric:: NOTES: + +This parameter is very important. If the application creates tasks with +stacks larger then the minimum, then that memory is **not** accounted for by +``<rtems/confdefs.h>``. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be small enough so that the task + stack space calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. + +.. Generated from spec:/acfg/if/init + +.. raw:: latex -OPTION TYPE: - This configuration option is an integer define. + \clearpage -DEFAULT VALUE: - The default value is 0. +.. index:: CONFIGURE_INIT -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. _CONFIGURE_INIT: - * It shall be greater than or equal to 0. +CONFIGURE_INIT +-------------- - * It shall be small enough so that the task - stack space calculation carried out by ``<rtems/confdefs.h>`` does not - overflow an integer of type `uintptr_t <https://en.cppreference.com/w/c/types/integer>`_. +.. rubric:: CONSTANT: -DESCRIPTION: - The value of this configuration option defines the number of bytes the - applications wishes to add to the task stack requirements calculated by - ``<rtems/confdefs.h>``. +``CONFIGURE_INIT`` -NOTES: - This parameter is very important. If the application creates tasks with - stacks larger then the minimum, then that memory is **not** accounted for by - ``<rtems/confdefs.h>``. +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +There is no default configuration associated with this configuration option. +If ``<rtems/confdefs.h>`` is included and this configuration option is not +defined, then only white space is included. + +.. rubric:: DESCRIPTION: + +While this configuration option is defined, when the ``<rtems/confdefs.h>`` +is included, the system settings defined by present application configuration +options are statically allocated and initialized. All user provided +application configuration options defined before the include of +``<rtems/confdefs.h>`` are evaluated. They define the actual system +settings. .. Generated from spec:/acfg/if/initial-extensions +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_INITIAL_EXTENSIONS .. _CONFIGURE_INITIAL_EXTENSIONS: @@ -175,30 +302,40 @@ NOTES: CONFIGURE_INITIAL_EXTENSIONS ---------------------------- -CONSTANT: - ``CONFIGURE_INITIAL_EXTENSIONS`` +.. rubric:: CONSTANT: + +``CONFIGURE_INITIAL_EXTENSIONS`` -OPTION TYPE: - This configuration option is an initializer define. +.. rubric:: OPTION TYPE: -DEFAULT VALUE: - The default value is the empty list. +This configuration option is an initializer define. -VALUE CONSTRAINTS: - The value of this configuration option shall be a list of initializers for - structures of type :c:type:`rtems_extensions_table`. +.. rubric:: DEFAULT VALUE: -DESCRIPTION: - The value of this configuration option is used to initialize the table of - initial user extensions. +The default value is the empty list. -NOTES: - The value of this configuration option is placed before the entries of - :ref:`BSP_INITIAL_EXTENSION` and after the entries of all other initial - user extensions. +.. rubric:: DESCRIPTION: + +The value of this configuration option is used to initialize the table of +initial user extensions. + +.. rubric:: NOTES: + +The value of this configuration option is placed before the entries of +:c:macro:`BSP_INITIAL_EXTENSION` and after the entries of all other +initial user extensions. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be a list of initializers for +structures of type :ref:`InterfaceRtemsExtensionsTable`. .. Generated from spec:/acfg/if/interrupt-stack-size +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_INTERRUPT_STACK_SIZE .. index:: interrupt stack size @@ -207,54 +344,67 @@ NOTES: CONFIGURE_INTERRUPT_STACK_SIZE ------------------------------ -CONSTANT: - ``CONFIGURE_INTERRUPT_STACK_SIZE`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is an integer define. +``CONFIGURE_INTERRUPT_STACK_SIZE`` -DEFAULT VALUE: - The default value is :ref:`BSP_INTERRUPT_STACK_SIZE` in case it is defined, - otherwise the default value is :c:macro:`CPU_STACK_MINIMUM_SIZE`. +.. rubric:: OPTION TYPE: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +This configuration option is an integer define. - * It shall be greater than or equal to a - BSP-specific and application-specific minimum value. +.. rubric:: DEFAULT VALUE: - * It shall be small enough so that the - interrupt stack area calculation carried out by ``<rtems/confdefs.h>`` does - not overflow an integer of type `size_t <https://en.cppreference.com/w/c/types/size_t>`_. +If the :ref:`CONFIGURE_DISABLE_BSP_SETTINGS` configuration option is not defined and +:c:macro:`BSP_INTERRUPT_STACK_SIZE` is provided by the +:term:`BSP`, then the default value is defined by +:c:macro:`BSP_INTERRUPT_STACK_SIZE`, otherwise the default value is +:c:macro:`CPU_STACK_MINIMUM_SIZE`. - * It shall be aligned according to - :c:macro:`CPU_INTERRUPT_STACK_ALIGNMENT`. +.. rubric:: DESCRIPTION: -DESCRIPTION: - The value of this configuration option defines the size of an interrupt stack - in bytes. +The value of this configuration option defines the size of an interrupt stack +in bytes. -NOTES: - There is one interrupt stack available for each configured processor - (:ref:`CONFIGURE_MAXIMUM_PROCESSORS`). The interrupt stack areas are - statically allocated in a special linker section (``.rtemsstack.interrupt``). - The placement of this linker section is BSP-specific. +.. rubric:: NOTES: - Some BSPs use the interrupt stack as the initialization stack which is used - to perform the sequential system initialization before the multithreading - is started. +There is one interrupt stack available for each configured processor +(:ref:`CONFIGURE_MAXIMUM_PROCESSORS`). The interrupt stack areas are +statically allocated in a special linker section (``.rtemsstack.interrupt``). +The placement of this linker section is BSP-specific. - The interrupt stacks are covered by the stack checker, see - :ref:`CONFIGURE_STACK_CHECKER_ENABLED`. However, using a too small interrupt stack - size may still result in undefined behaviour. +Some BSPs use the interrupt stack as the initialization stack which is used +to perform the sequential system initialization before the multithreading +is started. - In releases before RTEMS 5.1 the default value was - :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE` instead of - :c:macro:`CPU_STACK_MINIMUM_SIZE`. +The interrupt stacks are covered by the stack checker, see +:ref:`CONFIGURE_STACK_CHECKER_ENABLED`. However, using a too small interrupt stack +size may still result in undefined behaviour. + +In releases before RTEMS 5.1 the default value was +:ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE` instead of +:c:macro:`CPU_STACK_MINIMUM_SIZE`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to a + BSP-specific and application-specific minimum value. + +* The value of the configuration option shall be small enough so that the + interrupt stack area calculation carried out by ``<rtems/confdefs.h>`` does + not overflow an integer of type `size_t + <https://en.cppreference.com/w/c/types/size_t>`_. + +* The value of the configuration option shall be aligned according to + :c:macro:`CPU_INTERRUPT_STACK_ALIGNMENT`. .. Generated from spec:/acfg/if/malloc-dirty +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MALLOC_DIRTY .. _CONFIGURE_MALLOC_DIRTY: @@ -262,29 +412,38 @@ NOTES: CONFIGURE_MALLOC_DIRTY ---------------------- -CONSTANT: - ``CONFIGURE_MALLOC_DIRTY`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is a boolean feature define. +``CONFIGURE_MALLOC_DIRTY`` -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: OPTION TYPE: -DESCRIPTION: - In case this configuration option is defined, then each memory area returned - by C Program Heap allocator functions such as :c:func:`malloc` is dirtied - with a ``0xCF`` byte pattern before it is handed over to the application. +This configuration option is a boolean feature define. -NOTES: - The dirtying performed by this option is carried out for each successful - memory allocation from the C Program Heap in contrast to - :ref:`CONFIGURE_DIRTY_MEMORY` which dirties the memory only once during the - system initialization. +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then each memory area returned +by C Program Heap allocator functions such as :c:func:`malloc` is dirtied +with a ``0xCF`` byte pattern before it is handed over to the application. + +.. rubric:: NOTES: + +The dirtying performed by this option is carried out for each successful +memory allocation from the C Program Heap in contrast to +:ref:`CONFIGURE_DIRTY_MEMORY` which dirties the memory only once during the +system initialization. .. Generated from spec:/acfg/if/max-file-descriptors +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MAXIMUM_FILE_DESCRIPTORS .. index:: maximum file descriptors @@ -293,37 +452,47 @@ NOTES: CONFIGURE_MAXIMUM_FILE_DESCRIPTORS ---------------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_FILE_DESCRIPTORS`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is an integer define. +``CONFIGURE_MAXIMUM_FILE_DESCRIPTORS`` -DEFAULT VALUE: - The default value is 3. +.. rubric:: OPTION TYPE: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +This configuration option is an integer define. - * It shall be greater than or equal to 0. +.. rubric:: DEFAULT VALUE: - * It shall be less than or equal to `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_. +The default value is 3. - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +.. rubric:: DESCRIPTION: -DESCRIPTION: - The value of this configuration option defines the maximum number of file - like objects that can be concurrently open. +The value of this configuration option defines the maximum number of file +like objects that can be concurrently open. -NOTES: - The default value of three file descriptors allows RTEMS to support standard - input, output, and error I/O streams on :file:`/dev/console`. +.. rubric:: NOTES: + +The default value of three file descriptors allows RTEMS to support standard +input, output, and error I/O streams on :file:`/dev/console`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. .. Generated from spec:/acfg/if/max-processors +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MAXIMUM_PROCESSORS .. _CONFIGURE_MAXIMUM_PROCESSORS: @@ -331,36 +500,113 @@ NOTES: CONFIGURE_MAXIMUM_PROCESSORS ---------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_PROCESSORS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_PROCESSORS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 1. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the maximum number of +processors an application intends to use. The number of actually available +processors depends on the hardware and may be less. It is recommended to use +the smallest value suitable for the application in order to save memory. +Each processor needs an IDLE task stack and interrupt stack for example. + +.. rubric:: NOTES: + +If there are more processors available than configured, the rest will be +ignored. + +This configuration option is only evaluated in SMP configurations of RTEMS +(e.g. RTEMS was built with the SMP build configuration option enabled). +In all other configurations it has no effect. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to one. + +* The value of the configuration option shall be less than or equal to + :c:macro:`CPU_MAXIMUM_PROCESSORS`. + +.. Generated from spec:/acfg/if/max-thread-local-storage-size + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE + +.. _CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE: + +CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE +------------------------------------------- + +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is an integer define. +``CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE`` -DEFAULT VALUE: - The default value is 1. +.. rubric:: OPTION TYPE: -VALUE CONSTRAINTS: - The value of this configuration option shall be greater than or equal to 1 - and less than or equal to :c:macro:`CPU_MAXIMUM_PROCESSORS`. +This configuration option is an integer define. -DESCRIPTION: - The value of this configuration option defines the maximum number of - processors an application intends to use. The number of actually available - processors depends on the hardware and may be less. It is recommended to use - the smallest value suitable for the application in order to save memory. - Each processor needs an IDLE task stack and interrupt stack for example. +.. rubric:: DEFAULT VALUE: -NOTES: - If there are more processors available than configured, the rest will be - ignored. +The default value is 0. - This configuration option is only evaluated in SMP configurations (e.g. RTEMS - was built with the ``--enable-smp`` build configuration option). In all - other configurations it has no effect. +.. rubric:: DESCRIPTION: + +If the value of this configuration option is greater than zero, then it +defines the maximum thread-local storage size, otherwise the thread-local +storage size is defined by the linker depending on the thread-local storage +objects used by the application in the statically-linked executable. + +.. rubric:: NOTES: + +This configuration option can be used to reserve space for the dynamic linking +of modules with thread-local storage objects. + +If the thread-local storage size defined by the thread-local storage +objects used by the application in the statically-linked executable is greater +than a non-zero value of this configuration option, then a fatal error will +occur during system initialization. + +Use :c:func:`RTEMS_ALIGN_UP` and +:c:macro:`RTEMS_TASK_STORAGE_ALIGNMENT` to adjust the size to meet the +minimum alignment requirement of a thread-local storage area. + +The actual thread-local storage size is determined when the application +executable is linked. The ``rtems-exeinfo`` command line tool included in +the RTEMS Tools can be used to obtain the thread-local storage size and +alignment of an application executable. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_. + +* The value of the configuration option shall be an integral multiple of + :c:macro:`RTEMS_TASK_STORAGE_ALIGNMENT`. .. Generated from spec:/acfg/if/max-thread-name-size +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MAXIMUM_THREAD_NAME_SIZE .. index:: maximum thread name size @@ -369,42 +615,52 @@ NOTES: CONFIGURE_MAXIMUM_THREAD_NAME_SIZE ---------------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_THREAD_NAME_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_THREAD_NAME_SIZE`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is an integer define. +This configuration option is an integer define. -DEFAULT VALUE: - The default value is 16. +.. rubric:: DEFAULT VALUE: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The default value is 16. - * It shall be greater than or equal to 0. +.. rubric:: DESCRIPTION: - * It shall be less than or equal to `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_. +The value of this configuration option defines the maximum thread name size +including the terminating ``NUL`` character. - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +.. rubric:: NOTES: -DESCRIPTION: - The value of this configuration option defines the maximum thread name size - including the terminating ``NUL`` character. +The default value was chosen for Linux compatibility, see +`pthread_setname_np() <http://man7.org/linux/man-pages/man3/pthread_setname_np.3.html>`_. -NOTES: - The default value was chosen for Linux compatibility, see - `PTHREAD_SETNAME_NP(3) <http://man7.org/linux/man-pages/man3/pthread_setname_np.3.html>`_. +The size of the thread control block is increased by the maximum thread name +size. - The size of the thread control block is increased by the maximum thread name - size. +This configuration option is available since RTEMS 5.1. - This configuration option is available since RTEMS 5.1. +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. .. Generated from spec:/acfg/if/memory-overhead +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MEMORY_OVERHEAD .. _CONFIGURE_MEMORY_OVERHEAD: @@ -412,43 +668,53 @@ NOTES: CONFIGURE_MEMORY_OVERHEAD ------------------------- -CONSTANT: - ``CONFIGURE_MEMORY_OVERHEAD`` +.. rubric:: CONSTANT: + +``CONFIGURE_MEMORY_OVERHEAD`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is an integer define. +This configuration option is an integer define. -DEFAULT VALUE: - The default value is 0. +.. rubric:: DEFAULT VALUE: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The default value is 0. - * It shall be greater than or equal to 0. +.. rubric:: DESCRIPTION: - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +The value of this configuration option defines the number of kilobytes the +application wishes to add to the RTEMS Workspace size calculated by +``<rtems/confdefs.h>``. - * It shall be small enough so that the - RTEMS Workspace size calculation carried out by ``<rtems/confdefs.h>`` does - not overflow an integer of type `uintptr_t <https://en.cppreference.com/w/c/types/integer>`_. +.. rubric:: NOTES: -DESCRIPTION: - The value of this configuration option defines the number of kilobytes the - application wishes to add to the RTEMS Workspace size calculated by - ``<rtems/confdefs.h>``. +This configuration option should only be used when it is suspected that a bug +in ``<rtems/confdefs.h>`` has resulted in an underestimation. Typically the +memory allocation will be too low when an application does not account for +all message queue buffers or task stacks, see +:ref:`CONFIGURE_MESSAGE_BUFFER_MEMORY`. -NOTES: - This configuration option should only be used when it is suspected that a bug - in ``<rtems/confdefs.h>`` has resulted in an underestimation. Typically the - memory allocation will be too low when an application does not account for - all message queue buffers or task stacks, see - :ref:`CONFIGURE_MESSAGE_BUFFER_MEMORY`. +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +* The value of the configuration option shall be small enough so that the RTEMS + Workspace size calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. .. Generated from spec:/acfg/if/message-buffer-memory +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MESSAGE_BUFFER_MEMORY .. index:: configure message queue buffer memory .. index:: CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE @@ -459,82 +725,92 @@ NOTES: CONFIGURE_MESSAGE_BUFFER_MEMORY ------------------------------- -CONSTANT: - ``CONFIGURE_MESSAGE_BUFFER_MEMORY`` - -OPTION TYPE: - This configuration option is an integer define. - -DEFAULT VALUE: - The default value is 0. - -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: - - * It shall be greater than or equal to 0. - - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. - - * It shall be small enough so that the - RTEMS Workspace size calculation carried out by ``<rtems/confdefs.h>`` does - not overflow an integer of type `uintptr_t <https://en.cppreference.com/w/c/types/integer>`_. - -DESCRIPTION: - The value of this configuration option defines the number of bytes reserved - for message queue buffers in the RTEMS Workspace. - -NOTES: - The configuration options :ref:`CONFIGURE_MAXIMUM_MESSAGE_QUEUES` and - :ref:`CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES` define only how many message - queues can be created by the application. The memory for the message - buffers is configured by this option. For each message queue you have to - reserve some memory for the message buffers. The size depends on the - maximum number of pending messages and the maximum size of the messages of - a message queue. Use the ``CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE()`` macro - to specify the message buffer memory for each message queue and sum them up - to define the value for ``CONFIGURE_MAXIMUM_MESSAGE_QUEUES``. - - The interface for the ``CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE()`` help - macro is as follows: - - .. code-block:: c - - CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE( max_messages, max_msg_size ) - - Where ``max_messages`` is the maximum number of pending messages and - ``max_msg_size`` is the maximum size in bytes of the messages of the - corresponding message queue. Both parameters shall be compile time - constants. Not using this help macro (e.g. just using - ``max_messages * max_msg_size``) may result in an underestimate of the - RTEMS Workspace size. - - The following example illustrates how the - ``CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE()`` help macro can be used to assist in - calculating the message buffer memory required. In this example, there are - two message queues used in this application. The first message queue has a - maximum of 24 pending messages with the message structure defined by the - type ``one_message_type``. The other message queue has a maximum of 500 - pending messages with the message structure defined by the type - ``other_message_type``. - - .. code-block:: c - - #define CONFIGURE_MESSAGE_BUFFER_MEMORY ( \ - CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE( \ - 24, \ - sizeof( one_message_type ) \ - ) \ - + CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE( \ - 500, \ - sizeof( other_message_type ) \ - ) \ - ) +.. rubric:: CONSTANT: + +``CONFIGURE_MESSAGE_BUFFER_MEMORY`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the number of bytes reserved +for message queue buffers in the RTEMS Workspace. + +.. rubric:: NOTES: + +The configuration options :ref:`CONFIGURE_MAXIMUM_MESSAGE_QUEUES` and +:ref:`CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES` define only how many message +queues can be created by the application. The memory for the message +buffers is configured by this option. For each message queue you have to +reserve some memory for the message buffers. The size depends on the +maximum number of pending messages and the maximum size of the messages of +a message queue. Use the ``CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE()`` macro +to specify the message buffer memory for each message queue and sum them up +to define the value for ``CONFIGURE_MAXIMUM_MESSAGE_QUEUES``. + +The interface for the ``CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE()`` help +macro is as follows: + +.. code-block:: c + + CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE( max_messages, max_msg_size ) + +Where ``max_messages`` is the maximum number of pending messages and +``max_msg_size`` is the maximum size in bytes of the messages of the +corresponding message queue. Both parameters shall be compile time +constants. Not using this help macro (e.g. just using +``max_messages * max_msg_size``) may result in an underestimate of the +RTEMS Workspace size. + +The following example illustrates how the +``CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE()`` help macro can be used to assist in +calculating the message buffer memory required. In this example, there are +two message queues used in this application. The first message queue has a +maximum of 24 pending messages with the message structure defined by the +type ``one_message_type``. The other message queue has a maximum of 500 +pending messages with the message structure defined by the type +``other_message_type``. + +.. code-block:: c + + #define CONFIGURE_MESSAGE_BUFFER_MEMORY ( \ + CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE( \ + 24, \ + sizeof( one_message_type ) \ + ) \ + + CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE( \ + 500, \ + sizeof( other_message_type ) \ + ) \ + ) + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +* The value of the configuration option shall be small enough so that the RTEMS + Workspace size calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. .. Generated from spec:/acfg/if/microseconds-per-tick +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MICROSECONDS_PER_TICK .. index:: clock tick quantum .. index:: tick quantum @@ -544,53 +820,64 @@ NOTES: CONFIGURE_MICROSECONDS_PER_TICK ------------------------------- -CONSTANT: - ``CONFIGURE_MICROSECONDS_PER_TICK`` +.. rubric:: CONSTANT: + +``CONFIGURE_MICROSECONDS_PER_TICK`` -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: OPTION TYPE: -DEFAULT VALUE: - The default value is 10000. +This configuration option is an integer define. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: DEFAULT VALUE: - * It shall be greater than or equal to a Clock Driver specific value. +The default value is 10000. - * It shall be less than or equal to a Clock Driver specific value. +.. rubric:: DESCRIPTION: - * The resulting clock ticks per second should be an integer. +The value of this configuration option defines the length of time in +microseconds between clock ticks (clock tick quantum). -DESCRIPTION: - The value of this configuration option defines the length of time in - microseconds between clock ticks (clock tick quantum). +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. - 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 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. - 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. +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 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. +.. rubric:: NOTES: -NOTES: - This configuration option has no impact if the Clock Driver is not - configured, see :ref:`CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`. +This configuration option has no impact if the Clock Driver is not +configured, see :ref:`CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`. - There may be Clock Driver specific limits on the resolution or maximum value - of a clock tick quantum. +There may be Clock Driver specific limits on the resolution or maximum value +of a clock tick quantum. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to a + value defined by the :term:`Clock Driver`. + +* The value of the configuration option shall be less than or equal to a value + defined by the :term:`Clock Driver`. + +* The resulting clock ticks per second should be an integer. .. Generated from spec:/acfg/if/min-task-stack-size +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MINIMUM_TASK_STACK_SIZE .. index:: minimum task stack size @@ -599,54 +886,64 @@ NOTES: CONFIGURE_MINIMUM_TASK_STACK_SIZE --------------------------------- -CONSTANT: - ``CONFIGURE_MINIMUM_TASK_STACK_SIZE`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is an integer define. +``CONFIGURE_MINIMUM_TASK_STACK_SIZE`` -DEFAULT VALUE: - The default value is :c:macro:`CPU_STACK_MINIMUM_SIZE`. +.. rubric:: OPTION TYPE: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +This configuration option is an integer define. - * It shall be small enough so that the task - stack space calculation carried out by ``<rtems/confdefs.h>`` does not - overflow an integer of type `uintptr_t <https://en.cppreference.com/w/c/types/integer>`_. +.. rubric:: DEFAULT VALUE: - * It shall be greater than or equal to a - BSP-specific and application-specific minimum value. +The default value is :c:macro:`CPU_STACK_MINIMUM_SIZE`. -DESCRIPTION: - The value of this configuration option defines the minimum stack size in - bytes for every user task or thread in the system. +.. rubric:: DESCRIPTION: -NOTES: - Adjusting this parameter should be done with caution. Examining the actual - stack usage using the stack checker usage reporting facility is recommended - (see also :ref:`CONFIGURE_STACK_CHECKER_ENABLED`). +The value of this configuration option defines the minimum stack size in +bytes for every user task or thread in the system. - This parameter can be used to lower the minimum from that recommended. This - can be used in low memory systems to reduce memory consumption for - stacks. However, this shall be done with caution as it could increase the - possibility of a blown task stack. +.. rubric:: NOTES: - 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. +Adjusting this parameter should be done with caution. Examining the actual +stack usage using the stack checker usage reporting facility is recommended +(see also :ref:`CONFIGURE_STACK_CHECKER_ENABLED`). - By default, this configuration parameter defines also the minimum stack - size of POSIX threads. This can be changed with the - :ref:`CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE` - configuration option. +This parameter can be used to lower the minimum from that recommended. This +can be used in low memory systems to reduce memory consumption for +stacks. However, this shall be done with caution as it could increase the +possibility of a blown task stack. - In releases before RTEMS 5.1 the ``CONFIGURE_MINIMUM_TASK_STACK_SIZE`` was - used to define the default value of :ref:`CONFIGURE_INTERRUPT_STACK_SIZE`. +This parameter can be used to increase the minimum from that +recommended. This can be used in higher memory systems to reduce the risk +of stack overflow without performing analysis on actual consumption. + +By default, this configuration parameter defines also the minimum stack +size of POSIX threads. This can be changed with the +:ref:`CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE` +configuration option. + +In releases before RTEMS 5.1 the ``CONFIGURE_MINIMUM_TASK_STACK_SIZE`` was +used to define the default value of :ref:`CONFIGURE_INTERRUPT_STACK_SIZE`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be small enough so that the task + stack space calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. + +* The value of the configuration option shall be greater than or equal to a + BSP-specific and application-specific minimum value. .. Generated from spec:/acfg/if/stack-checker-enabled +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_STACK_CHECKER_ENABLED .. _CONFIGURE_STACK_CHECKER_ENABLED: @@ -654,29 +951,38 @@ NOTES: CONFIGURE_STACK_CHECKER_ENABLED ------------------------------- -CONSTANT: - ``CONFIGURE_STACK_CHECKER_ENABLED`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is a boolean feature define. +``CONFIGURE_STACK_CHECKER_ENABLED`` -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: OPTION TYPE: -DESCRIPTION: - In case this configuration option is defined, then the stack checker is - enabled. +This configuration option is a boolean feature define. -NOTES: - The stack checker performs run-time stack bounds checking. This increases - the time required to create tasks as well as adding overhead to each context - switch. +.. rubric:: DEFAULT CONFIGURATION: - In 4.9 and older, this configuration option was named ``STACK_CHECKER_ON``. +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the stack checker is +enabled. + +.. rubric:: NOTES: + +The stack checker performs run-time stack bounds checking. This increases +the time required to create tasks as well as adding overhead to each context +switch. + +In 4.9 and older, this configuration option was named ``STACK_CHECKER_ON``. .. Generated from spec:/acfg/if/ticks-per-time-slice +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_TICKS_PER_TIMESLICE .. index:: ticks per timeslice @@ -685,29 +991,43 @@ NOTES: CONFIGURE_TICKS_PER_TIMESLICE ----------------------------- -CONSTANT: - ``CONFIGURE_TICKS_PER_TIMESLICE`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is an integer define. +``CONFIGURE_TICKS_PER_TIMESLICE`` -DEFAULT VALUE: - The default value is 50. +.. rubric:: OPTION TYPE: -VALUE CONSTRAINTS: - The value of this configuration option shall be greater than or equal to 0 - and less than or equal to `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. +This configuration option is an integer define. -DESCRIPTION: - The value of this configuration option defines the length of the timeslice - quantum in ticks for each task. +.. rubric:: DEFAULT VALUE: -NOTES: - This configuration option has no impact if the Clock Driver is not - configured, see :ref:`CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`. +The default value is 50. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the length of the timeslice +quantum in ticks for each task. + +.. rubric:: NOTES: + +This configuration option has no impact if the Clock Driver is not +configured, see :ref:`CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to one. + +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. .. Generated from spec:/acfg/if/unified-work-areas +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_UNIFIED_WORK_AREAS .. index:: unified work areas .. index:: separate work areas @@ -719,33 +1039,42 @@ NOTES: CONFIGURE_UNIFIED_WORK_AREAS ---------------------------- -CONSTANT: - ``CONFIGURE_UNIFIED_WORK_AREAS`` +.. rubric:: CONSTANT: + +``CONFIGURE_UNIFIED_WORK_AREAS`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then there will be separate memory +pools for the RTEMS Workspace and C Program Heap. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DESCRIPTION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then there will be separate memory - pools for the RTEMS Workspace and C Program Heap. +In case this configuration option is defined, then the RTEMS Workspace and +the C Program Heap will be one pool of memory. -DESCRIPTION: - In case this configuration option is defined, then the RTEMS Workspace and - the C Program Heap will be one pool of memory. +.. rubric:: NOTES: -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. +Having separate pools does have some advantages in the event a task blows a +stack or writes outside its memory area. However, in low memory systems the +overhead of the two pools plus the potential for unused memory in either +pool is very undesirable. - In high memory environments, this is desirable when you want to use the - :ref:`ConfigUnlimitedObjects` option. You will be able to create objects - until you run out of all available memory rather then just until you run out - of RTEMS Workspace. +In high memory environments, this is desirable when you want to use the +:ref:`ConfigUnlimitedObjects` option. You will be able to create objects +until you run out of all available memory rather then just until you run out +of RTEMS Workspace. .. Generated from spec:/acfg/if/unlimited-allocation-size +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_UNLIMITED_ALLOCATION_SIZE .. _CONFIGURE_UNLIMITED_ALLOCATION_SIZE: @@ -753,34 +1082,44 @@ NOTES: CONFIGURE_UNLIMITED_ALLOCATION_SIZE ----------------------------------- -CONSTANT: - ``CONFIGURE_UNLIMITED_ALLOCATION_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_UNLIMITED_ALLOCATION_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 8. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is an integer define. +If :ref:`CONFIGURE_UNLIMITED_OBJECTS` is defined, then the value of this +configuration option defines the default objects maximum of all object +classes supporting :ref:`ConfigUnlimitedObjects` to +``rtems_resource_unlimited( CONFIGURE_UNLIMITED_ALLOCATION_SIZE )``. -DEFAULT VALUE: - The default value is 8. +.. rubric:: NOTES: -VALUE CONSTRAINTS: - The value of this configuration option shall meet the constraints of all - object classes to which it is applied. +By allowing users to declare all resources as being unlimited the user can +avoid identifying and limiting the resources used. -DESCRIPTION: - If :ref:`CONFIGURE_UNLIMITED_OBJECTS` is defined, then the value of this - configuration option defines the default objects maximum of all object - classes supporting :ref:`ConfigUnlimitedObjects` to - ``rtems_resource_unlimited( CONFIGURE_UNLIMITED_ALLOCATION_SIZE )``. +The object maximum of each class can be configured also individually using +the :ref:`InterfaceRtemsResourceUnlimited` macro. -NOTES: - By allowing users to declare all resources as being unlimited the user can - avoid identifying and limiting the resources used. +.. rubric:: CONSTRAINTS: - The object maximum of each class can be configured also individually using - the :c:func:`rtems_resource_unlimited` macro. +The value of the configuration option shall meet the constraints of all object +classes to which it is applied. .. Generated from spec:/acfg/if/unlimited-objects +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_UNLIMITED_OBJECTS .. _CONFIGURE_UNLIMITED_OBJECTS: @@ -788,32 +1127,41 @@ NOTES: CONFIGURE_UNLIMITED_OBJECTS --------------------------- -CONSTANT: - ``CONFIGURE_UNLIMITED_OBJECTS`` +.. rubric:: CONSTANT: + +``CONFIGURE_UNLIMITED_OBJECTS`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DESCRIPTION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +In case this configuration option is defined, then unlimited objects are used +by default. -DESCRIPTION: - In case this configuration option is defined, then unlimited objects are used - by default. +.. rubric:: NOTES: -NOTES: - When using unlimited objects, it is common practice to also specify - :ref:`CONFIGURE_UNIFIED_WORK_AREAS` so the system operates with a single pool - of memory for both RTEMS Workspace and C Program Heap. +When using unlimited objects, it is common practice to also specify +:ref:`CONFIGURE_UNIFIED_WORK_AREAS` so the system operates with a single pool +of memory for both RTEMS Workspace and C Program Heap. - This option does not override an explicit configuration for a particular - object class by the user. +This option does not override an explicit configuration for a particular +object class by the user. - See also :ref:`CONFIGURE_UNLIMITED_ALLOCATION_SIZE`. +See also :ref:`CONFIGURE_UNLIMITED_ALLOCATION_SIZE`. .. Generated from spec:/acfg/if/verbose-system-init +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_VERBOSE_SYSTEM_INITIALIZATION .. _CONFIGURE_VERBOSE_SYSTEM_INITIALIZATION: @@ -821,26 +1169,35 @@ NOTES: CONFIGURE_VERBOSE_SYSTEM_INITIALIZATION --------------------------------------- -CONSTANT: - ``CONFIGURE_VERBOSE_SYSTEM_INITIALIZATION`` +.. rubric:: CONSTANT: + +``CONFIGURE_VERBOSE_SYSTEM_INITIALIZATION`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DESCRIPTION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +In case this configuration option is defined, then the system initialization +is verbose. -DESCRIPTION: - In case this configuration option is defined, then the system initialization - is verbose. +.. rubric:: NOTES: -NOTES: - You may use this feature to debug system initialization issues. The - :c:func:`printk` function is used to print the information. +You may use this feature to debug system initialization issues. The +:ref:`InterfacePrintk` function is used to print the information. .. Generated from spec:/acfg/if/zero-workspace-automatically +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY .. index:: clear C Program Heap .. index:: clear RTEMS Workspace @@ -852,23 +1209,28 @@ NOTES: CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY -------------------------------------- -CONSTANT: - ``CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY`` +.. rubric:: CONSTANT: + +``CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DESCRIPTION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +In case this configuration option is defined, then the memory areas used for +the RTEMS Workspace and the C Program Heap are zeroed with a ``0x00`` byte +pattern during system initialization. -DESCRIPTION: - In case this configuration option is defined, then the memory areas used for - the RTEMS Workspace and the C Program Heap are zeroed with a ``0x00`` byte - pattern during system initialization. +.. rubric:: NOTES: -NOTES: - Zeroing memory can add significantly to the system initialization time. It is - not necessary for RTEMS but is often assumed by support libraries. In case - :ref:`CONFIGURE_DIRTY_MEMORY` is also defined, then the memory is first - dirtied and then zeroed. +Zeroing memory can add significantly to the system initialization time. It is +not necessary for RTEMS but is often assumed by support libraries. In case +:ref:`CONFIGURE_DIRTY_MEMORY` is also defined, then the memory is first +dirtied and then zeroed. diff --git a/c-user/config/idle-task.rst b/c-user/config/idle-task.rst index 9330672..793fb5c 100644 --- a/c-user/config/idle-task.rst +++ b/c-user/config/idle-task.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020, 2022 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) .. This file is part of the RTEMS quality process and was automatically @@ -27,6 +27,10 @@ This section describes configuration options related to the idle tasks. .. Generated from spec:/acfg/if/idle-task-body +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_IDLE_TASK_BODY .. _CONFIGURE_IDLE_TASK_BODY: @@ -34,33 +38,51 @@ This section describes configuration options related to the idle tasks. CONFIGURE_IDLE_TASK_BODY ------------------------ -CONSTANT: - ``CONFIGURE_IDLE_TASK_BODY`` +.. rubric:: CONSTANT: + +``CONFIGURE_IDLE_TASK_BODY`` + +.. rubric:: OPTION TYPE: + +This configuration option is an initializer define. + +.. rubric:: DEFAULT VALUE: -OPTION TYPE: - This configuration option is an initializer define. +If the :ref:`CONFIGURE_DISABLE_BSP_SETTINGS` configuration option is not defined and +:c:macro:`BSP_IDLE_TASK_BODY` is provided by the +:term:`BSP`, then the default value is defined by +:c:macro:`BSP_IDLE_TASK_BODY`, otherwise the default value is +``_CPU_Thread_Idle_body``. -DEFAULT VALUE: - If :ref:`BSP_IDLE_TASK_BODY` is defined, then this will be the default value, - otherwise the default value is ``_CPU_Thread_Idle_body``. +.. rubric:: DESCRIPTION: -VALUE CONSTRAINTS: - The value of this configuration option shall be defined to a valid function - pointer of the type ``void *( *idle_body )( uintptr_t )``. +The value of this configuration option initializes the IDLE thread body. -DESCRIPTION: - The value of this configuration option initializes the IDLE thread body. +.. rubric:: NOTES: -NOTES: - IDLE threads shall not block. A blocking IDLE thread results in undefined - system behaviour because the scheduler assume that at least one ready thread - exists. +IDLE threads shall not block. A blocking IDLE thread results in undefined +system behaviour because the scheduler assume that at least one ready thread +exists. - IDLE threads can be used to initialize the application, see configuration - option :ref:`CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION`. +IDLE threads can be used to initialize the application, see configuration +option :ref:`CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION`. + +The BSP may have knowledge of the specific CPU model, system controller +logic, and peripheral buses, so a BSP-specific IDLE task may be capable of +turning components off to save power during extended periods of no task +activity. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be defined to a valid function +pointer of the type ``void *( *idle_body )( uintptr_t )``. .. Generated from spec:/acfg/if/idle-task-init-appl +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION .. _CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION: @@ -68,47 +90,59 @@ NOTES: CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION ------------------------------------------- -CONSTANT: - ``CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION`` +.. rubric:: CONSTANT: + +``CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION`` -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: OPTION TYPE: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the user is assumed to - provide one or more initialization tasks. +This configuration option is a boolean feature define. -DESCRIPTION: - This configuration option is defined to indicate that the user has configured - **no** user initialization tasks or threads and that the user provided IDLE - task will perform application initialization and then transform itself into - an IDLE task. +.. rubric:: DEFAULT CONFIGURATION: -NOTES: - If you use this option be careful, the user IDLE task **cannot** block at all - during the initialization sequence. Further, once application - initialization is complete, it shall make itself preemptible and enter an idle - body loop. +If this configuration option is undefined, then the user is assumed to +provide one or more initialization tasks. - The IDLE task shall run at the lowest priority of all tasks in the system. +.. rubric:: DESCRIPTION: - If this configuration option is defined, then it is mandatory to configure a - user IDLE task with the :ref:`CONFIGURE_IDLE_TASK_BODY` configuration option, - otherwise a compile time error in the configuration file will occur. +This configuration option is defined to indicate that the user has configured +**no** user initialization tasks or threads and that the user provided IDLE +task will perform application initialization and then transform itself into +an IDLE task. - The application shall define exactly one of the following configuration - options +.. rubric:: NOTES: - * :ref:`CONFIGURE_RTEMS_INIT_TASKS_TABLE`, +If you use this option be careful, the user IDLE task **cannot** block at all +during the initialization sequence. Further, once application +initialization is complete, it shall make itself preemptible and enter an idle +body loop. - * :ref:`CONFIGURE_POSIX_INIT_THREAD_TABLE`, or +The IDLE task shall run at the lowest priority of all tasks in the system. - * ``CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION`` +If this configuration option is defined, then it is mandatory to configure a +user IDLE task with the :ref:`CONFIGURE_IDLE_TASK_BODY` configuration option, +otherwise a compile time error in the configuration file will occur. - otherwise a compile time error in the configuration file will occur. +The application shall define at least one of the following configuration +options + +* :ref:`CONFIGURE_RTEMS_INIT_TASKS_TABLE`, + +* :ref:`CONFIGURE_POSIX_INIT_THREAD_TABLE`, or + +* ``CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION`` + +otherwise a compile time error in the configuration file will occur. + +If no Classic API initialization task and no POSIX API initialization thread +is configured, then no :ref:`GlobalConstruction` is performed. .. Generated from spec:/acfg/if/idle-task-stack-size +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_IDLE_TASK_STACK_SIZE .. _CONFIGURE_IDLE_TASK_STACK_SIZE: @@ -116,30 +150,111 @@ NOTES: CONFIGURE_IDLE_TASK_STACK_SIZE ------------------------------ -CONSTANT: - ``CONFIGURE_IDLE_TASK_STACK_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_IDLE_TASK_STACK_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +If the :ref:`CONFIGURE_DISABLE_BSP_SETTINGS` configuration option is not defined and +:c:macro:`BSP_IDLE_TASK_STACK_SIZE` is provided by the +:term:`BSP`, then the default value is defined by +:c:macro:`BSP_IDLE_TASK_STACK_SIZE`, otherwise the default value is +defined by the :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE` configuration option. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the task stack size for an +IDLE task. + +.. rubric:: NOTES: + +In SMP configurations, there is one IDLE task per configured processor, see +:ref:`CONFIGURE_MAXIMUM_PROCESSORS`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to a + BSP-specific and application-specific minimum value. + +* The value of the configuration option shall be small enough so that the IDLE + task stack area calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `size_t + <https://en.cppreference.com/w/c/types/size_t>`_. + +.. Generated from spec:/acfg/if/idle-task-storage-size + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_IDLE_TASK_STORAGE_SIZE +.. index:: IDLE task storage size + +.. _CONFIGURE_IDLE_TASK_STORAGE_SIZE: + +CONFIGURE_IDLE_TASK_STORAGE_SIZE +-------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_IDLE_TASK_STORAGE_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +This configuration option has no default value. If it is not specified, then +the task storage area for each :term:`IDLE task` will allocated +from the RTEMS Workspace or through a custom IDLE task stack allocator. + +.. rubric:: DESCRIPTION: + +If this configuration option is specified, then the task storage areas for +the :term:`IDLE tasks <IDLE task>` are statically allocated by +``<rtems/confdefs.h>``. The value of this configuration option defines the +size in bytes of the task storage area of each IDLE task in the system. + +.. rubric:: NOTES: + +By default, the IDLE task storage areas are allocated from the RTEMS +Workspace. Applications which do not want to use a heap allocator can use +this configuration option to use statically allocated memory for the IDLE +task storage areas. The task storage area contains the task stack, the +thread-local storage, and the floating-point context on architectures with a +separate floating-point context. The size of the thread-local storage area +is defined at link time or by the :ref:`CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE` +configuration option. You have to estimate the actual thread-local storage +size if you want to use this configuration option. If the IDLE task stack +size would be less than the value defined by the +:ref:`CONFIGURE_IDLE_TASK_STACK_SIZE` configuration option, for example because the +thread-local storage size is larger than expected, then the system terminates +with the :ref:`INTERNAL_ERROR_CORE <FatalErrorSources>` fatal source and the +:ref:`INTERNAL_ERROR_IDLE_THREAD_STACK_TOO_SMALL <internal_errors>` fatal code during +system initialization. -OPTION TYPE: - This configuration option is an integer define. +The value of this configuration option is passed to +:ref:`InterfaceRTEMSTASKSTORAGESIZE` by ``<rtems/confdefs.h>`` to determine +the actual size of the statically allocated area to take +architecture-specific overheads into account. -DEFAULT VALUE: - The default value is :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. +The -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +* ``CONFIGURE_IDLE_TASK_STORAGE_SIZE``, and - * It shall be greater than or equal to a - BSP-specific and application-specific minimum value. +* :ref:`CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE` - * It shall be small enough so that the IDLE - task stack area calculation carried out by ``<rtems/confdefs.h>`` does not - overflow an integer of type `size_t <https://en.cppreference.com/w/c/types/size_t>`_. +configuration options are mutually exclusive. -DESCRIPTION: - The value of this configuration option defines the task stack size for an - IDLE task. +.. rubric:: CONSTRAINTS: -NOTES: - In SMP configurations, there is one IDLE task per configured processor, see - :ref:`CONFIGURE_MAXIMUM_PROCESSORS`. +The value of the configuration option shall be greater than or equal to +:ref:`CONFIGURE_IDLE_TASK_STACK_SIZE`. diff --git a/c-user/config/index.rst b/c-user/config/index.rst index b0e21a4..b669ea2 100644 --- a/c-user/config/index.rst +++ b/c-user/config/index.rst @@ -10,6 +10,7 @@ Configuring a System .. toctree:: + introduction intro general device-driver @@ -24,8 +25,9 @@ Configuring a System idle-task scheduler-general scheduler-clustered - bsp-related + face-technical-standard mpci libpci ada + directives obsolete diff --git a/c-user/config/intro.rst b/c-user/config/intro.rst index 4c2f715..eb9c4c1 100644 --- a/c-user/config/intro.rst +++ b/c-user/config/intro.rst @@ -3,49 +3,6 @@ .. Copyright (C) 2012 Gedare Bloom .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) -Introduction -============ - -RTEMS must be configured for an application. This configuration encompasses a -variety of information including the length of each clock tick, the maximum -number of each information RTEMS object that can be created, the application -initialization tasks, the task scheduling algorithm to be used, and the device -drivers in the application. - -Although this information is contained in data structures that are used by -RTEMS at system initialization time, the data structures themselves must not be -generated by hand. RTEMS provides a set of macros system which provides a -simple standard mechanism to automate the generation of these structures. - -.. index:: confdefs.h -.. index:: <rtems/confdefs.h> - -The RTEMS header file ``<rtems/confdefs.h>`` is at the core of the automatic -generation of system configuration. It is based on the idea of setting macros -which define configuration parameters of interest to the application and -defaulting or calculating all others. This variety of macros can automatically -produce all of the configuration data required for an RTEMS application. - -.. sidebar: Trivia: - - The term ``confdefs`` is shorthand for a *Configuration Defaults*. - -As a general rule, application developers only specify values for the -configuration parameters of interest to them. They define what resources or -features they require. In most cases, when a parameter is not specified, it -defaults to zero (0) instances, a standards compliant value, or disabled as -appropriate. For example, by default there will be 256 task priority levels but -this can be lowered by the application. This number of priority levels is -required to be compliant with the RTEID/ORKID standards upon which the Classic -API is based. There are similar cases where the default is selected to be -compliant with the POSIX standard. - -For each configuration parameter in the configuration tables, the macro -corresponding to that field is discussed. The RTEMS Maintainers expect that all -systems can be easily configured using the ``<rtems/confdefs.h>`` mechanism and -that using this mechanism will avoid internal RTEMS configuration changes -impacting applications. - Default Value Selection Philosophy ================================== @@ -71,9 +28,9 @@ automatically. It assumes that all tasks are floating point and that all will be allocated the minimum stack space. This calculation includes the amount of memory that will be allocated for internal use by RTEMS. The automatic calculation may underestimate the workspace size truly needed by the -application, in which case one can use the ``CONFIGURE_MEMORY_OVERHEAD`` macro -to add a value to the estimate. See :ref:`Specify Memory Overhead` for more -details. +application, in which case one can use the :ref:`CONFIGURE_MEMORY_OVERHEAD` +macro to add a value to the estimate. See :ref:`Specify Memory Overhead` for +more details. The memory area for the RTEMS Workspace is determined by the BSP. In case the RTEMS Workspace is too large for the available memory, then a fatal run-time @@ -83,8 +40,8 @@ The file ``<rtems/confdefs.h>`` will calculate the value of the ``work_space_size`` parameter of the Configuration Table. There are many parameters the application developer can specify to help ``<rtems/confdefs.h>`` in its calculations. Correctly specifying the application requirements via -parameters such as ``CONFIGURE_EXTRA_TASK_STACKS`` and -``CONFIGURE_MAXIMUM_TASKS`` is critical for production software. +parameters such as :ref:`CONFIGURE_EXTRA_TASK_STACKS` and +:ref:`CONFIGURE_MAXIMUM_TASKS` is critical for production software. For each class of objects, the allocation can operate in one of two ways. The default way has an ceiling on the maximum number of object instances which can @@ -176,44 +133,45 @@ milliseconds is as follows: In this example, only a few configuration parameters are specified. The impact of these are as follows: -- The example specified ``CONFIGURE_RTEMS_INIT_TASK_TABLE`` but did not specify - any additional parameters. This results in a configuration of an application - which will begin execution of a single initialization task named ``Init`` - which is non-preemptible and at priority one (1). - -- By specifying ``CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER``, this application - is configured to have a clock tick device driver. Without a clock tick device - driver, RTEMS has no way to know that time is passing and will be unable to - support delays and wall time. Further configuration details about time are - provided. Per ``CONFIGURE_MICROSECONDS_PER_TICK`` and - ``CONFIGURE_TICKS_PER_TIMESLICE``, the user specified they wanted a clock +- The example specified :ref:`CONFIGURE_RTEMS_INIT_TASKS_TABLE` but did not + specify any additional parameters. This results in a configuration of an + application which will begin execution of a single initialization task named + ``Init`` which is non-preemptible and at priority one (1). + +- By specifying :ref:`CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER`, this + application is configured to have a clock tick device driver. Without a clock + tick device driver, RTEMS has no way to know that time is passing and will be + unable to support delays and wall time. Further configuration details about + time are provided. Per :ref:`CONFIGURE_MICROSECONDS_PER_TICK` and + :ref:`CONFIGURE_TICKS_PER_TIMESLICE`, the user specified they wanted a clock tick to occur each millisecond, and that the length of a timeslice would be fifty (50) milliseconds. -- By specifying ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER``, the application - will include a console device driver. Although the console device driver may - support a combination of multiple serial ports and display and keyboard - combinations, it is only required to provide a single device named +- By specifying :ref:`CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`, the + application will include a console device driver. Although the console device + driver may support a combination of multiple serial ports and display and + keyboard combinations, it is only required to provide a single device named ``/dev/console``. This device will be used for Standard Input, Output and - Error I/O Streams. Thus when ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`` - is specified, implicitly three (3) file descriptors are reserved for the - Standard I/O Streams and those file descriptors are associated with - ``/dev/console`` during initialization. All console devices are expected to - support the POSIX*termios* interface. - -- The example above specifies via ``CONFIGURE_MAXIMUM_TASKS`` that the + Error I/O Streams. Thus when + :ref:`CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER` is specified, implicitly + three (3) file descriptors are reserved for the Standard I/O Streams and + those file descriptors are associated with ``/dev/console`` during + initialization. All console devices are expected to support the + POSIX*termios* interface. + +- The example above specifies via :ref:`CONFIGURE_MAXIMUM_TASKS` that the application requires a maximum of four (4) simultaneously existing Classic - API tasks. Similarly, by specifying ``CONFIGURE_MAXIMUM_MESSAGE_QUEUES``, + API tasks. Similarly, by specifying :ref:`CONFIGURE_MAXIMUM_MESSAGE_QUEUES`, there may be a maximum of only one (1) concurrently existent Classic API message queues. - The most surprising configuration parameter in this example is the use of - ``CONFIGURE_MESSAGE_BUFFER_MEMORY``. Message buffer memory is allocated from - the RTEMS Workspace and must be accounted for. In this example, the single - message queue will have up to twenty (20) messages of type ``struct + :ref:`CONFIGURE_MESSAGE_BUFFER_MEMORY`. Message buffer memory is allocated + from the RTEMS Workspace and must be accounted for. In this example, the + single message queue will have up to twenty (20) messages of type ``struct USER_MESSAGE``. -- The ``CONFIGURE_INIT`` constant must be defined in order to make +- The :ref:`CONFIGURE_INIT` constant must be defined in order to make ``<rtems/confdefs.h>`` instantiate the configuration data structures. This can only be defined in one source file per application that includes ``<rtems/confdefs.h>`` or the symbol table will be instantiated multiple @@ -321,8 +279,6 @@ generally considered a safer embedded systems programming practice to know the system limits rather than experience an out of memory error at an arbitrary and largely unpredictable time in the field. -.. index:: rtems_resource_unlimited - .. _ConfigUnlimitedObjectsClass: Unlimited Objects by Class @@ -330,7 +286,7 @@ Unlimited Objects by Class When the number of objects is not known ahead of time, RTEMS provides an auto-extending mode that can be enabled individually for each object type by -using the macro ``rtems_resource_unlimited``. This takes a value as a +using the macro :ref:`InterfaceRtemsResourceUnlimited`. This takes a value as a parameter, and is used to set the object maximum number field in an API Configuration table. The value is an allocation unit size. When RTEMS is required to grow the object table it is grown by this size. The kernel will @@ -338,18 +294,15 @@ return the object memory back to the RTEMS Workspace when an object is destroyed. The kernel will only return an allocated block of objects to the RTEMS Workspace if at least half the allocation size of free objects remain allocated. RTEMS always keeps one allocation block of objects allocated. Here -is an example of using ``rtems_resource_unlimited``: +is an example of using :c:func:`rtems_resource_unlimited`: .. code-block:: c - #define CONFIGURE_MAXIMUM_TASKS rtems_resource_unlimited(5) - -.. index:: rtems_resource_is_unlimited -.. index:: rtems_resource_maximum_per_allocation + #define CONFIGURE_MAXIMUM_TASKS rtems_resource_unlimited( 5 ) Object maximum specifications can be evaluated with the -``rtems_resource_is_unlimited`` and``rtems_resource_maximum_per_allocation`` -macros. +:ref:`InterfaceRtemsResourceIsUnlimited` and +:ref:`InterfaceRtemsResourceMaximumPerAllocation` macros. .. _ConfigUnlimitedObjectsDefault: diff --git a/c-user/config/introduction.rst b/c-user/config/introduction.rst new file mode 100644 index 0000000..8852a24 --- /dev/null +++ b/c-user/config/introduction.rst @@ -0,0 +1,227 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2009, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2021 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/rtems/config/if/group + +.. _ApplicationConfigurationInformationIntroduction: + +Introduction +============ + +.. The following list was generated from: +.. spec:/rtems/config/if/get-build-label +.. spec:/rtems/config/if/get-copyright-notice +.. spec:/rtems/config/if/get-target-hash +.. spec:/rtems/config/if/get-version-string +.. spec:/rtems/config/if/get-do-zero-of-workspace +.. spec:/rtems/config/if/get-idle-task-stack-size +.. spec:/rtems/config/if/get-idle-task +.. spec:/rtems/config/if/get-interrupt-stack-size +.. spec:/rtems/config/if/get-maximum-barriers +.. spec:/rtems/config/if/get-maximum-extensions +.. spec:/rtems/config/if/get-maximum-message-queues +.. spec:/rtems/config/if/get-maximum-partitions +.. spec:/rtems/config/if/get-maximum-periods +.. spec:/rtems/config/if/get-maximum-ports +.. spec:/rtems/config/if/get-maximum-processors +.. spec:/rtems/config/if/get-maximum-regions +.. spec:/rtems/config/if/get-maximum-semaphores +.. spec:/rtems/config/if/get-maximum-tasks +.. spec:/rtems/config/if/get-maximum-timers +.. spec:/rtems/config/if/get-microseconds-per-tick +.. spec:/rtems/config/if/get-milliseconds-per-tick +.. spec:/rtems/config/if/get-nanoseconds-per-tick +.. spec:/rtems/config/if/get-number-of-initial-extensions +.. spec:/rtems/config/if/get-stack-allocate-for-idle-hook +.. spec:/rtems/config/if/get-stack-allocate-hook +.. spec:/rtems/config/if/get-stack-allocate-init-hook +.. spec:/rtems/config/if/get-stack-allocator-avoids-work-space +.. spec:/rtems/config/if/get-stack-free-hook +.. spec:/rtems/config/if/get-stack-space-size +.. spec:/rtems/config/if/get-ticks-per-timeslice +.. spec:/rtems/config/if/get-unified-work-area +.. spec:/rtems/config/if/get-user-extension-table +.. spec:/rtems/config/if/get-user-multiprocessing-table +.. spec:/rtems/config/if/get-work-space-size +.. spec:/rtems/config/if/get-api-configuration +.. spec:/rtems/config/if/resource-is-unlimited +.. spec:/rtems/config/if/resource-maximum-per-allocation +.. spec:/rtems/config/if/resource-unlimited + +The application configuration information group provides an API to get the +configuration of an application. + +RTEMS must be configured for an application. This configuration encompasses a +variety of information including the length of each clock tick, the maximum +number of each information RTEMS object that can be created, the application +initialization tasks, the task scheduling algorithm to be used, and the device +drivers in the application. + +Although this information is contained in data structures that are used by +RTEMS at system initialization time, the data structures themselves must not be +generated by hand. RTEMS provides a set of macros system which provides a +simple standard mechanism to automate the generation of these structures. + +The RTEMS header file ``<rtems/confdefs.h>`` is at the core of the automatic +generation of system configuration. It is based on the idea of setting macros +which define configuration parameters of interest to the application and +defaulting or calculating all others. This variety of macros can automatically +produce all of the configuration data required for an RTEMS application. The +term ``confdefs`` is shorthand for a *Configuration Defaults*. + +As a general rule, application developers only specify values for the +configuration parameters of interest to them. They define what resources or +features they require. In most cases, when a parameter is not specified, it +defaults to zero (0) instances, a standards compliant value, or disabled as +appropriate. For example, by default there will be 256 task priority levels but +this can be lowered by the application. This number of priority levels is +required to be compliant with the RTEID/ORKID standards upon which the Classic +API is based. There are similar cases where the default is selected to be +compliant with the POSIX standard. + +For each configuration parameter in the configuration tables, the macro +corresponding to that field is discussed. The RTEMS Maintainers expect that all +systems can be easily configured using the ``<rtems/confdefs.h>`` mechanism and +that using this mechanism will avoid internal RTEMS configuration changes +impacting applications. + +Some application configuration settings and other system parameters can be +queried by the application. The directives provided by the Application +Configuration Information are: + +* :ref:`InterfaceRtemsGetBuildLabel` - Gets the RTEMS build label. + +* :ref:`InterfaceRtemsGetCopyrightNotice` - Gets the RTEMS copyright notice. + +* :ref:`InterfaceRtemsGetTargetHash` - Gets the RTEMS target hash. + +* :ref:`InterfaceRtemsGetVersionString` - Gets the RTEMS version string. + +* :ref:`InterfaceRtemsConfigurationGetDoZeroOfWorkspace` - Indicates if the + RTEMS Workspace is configured to be zeroed during system initialization for + this application. + +* :ref:`InterfaceRtemsConfigurationGetIdleTaskStackSize` - Gets the IDLE task + stack size in bytes of this application. + +* :ref:`InterfaceRtemsConfigurationGetIdleTask` - Gets the IDLE task body of + this application. + +* :ref:`InterfaceRtemsConfigurationGetInterruptStackSize` - Gets the interrupt + stack size in bytes of this application. + +* :ref:`InterfaceRtemsConfigurationGetMaximumBarriers` - Gets the resource + number of :ref:`RTEMSAPIClassicBarrier` objects configured for this + application. + +* :ref:`InterfaceRtemsConfigurationGetMaximumExtensions` - Gets the resource + number of :ref:`RTEMSAPIClassicUserExt` objects configured for this + application. + +* :ref:`InterfaceRtemsConfigurationGetMaximumMessageQueues` - Gets the resource + number of :ref:`RTEMSAPIClassicMessage` objects configured for this + application. + +* :ref:`InterfaceRtemsConfigurationGetMaximumPartitions` - Gets the resource + number of :ref:`RTEMSAPIClassicPart` objects configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetMaximumPeriods` - Gets the resource + number of :ref:`RTEMSAPIClassicRatemon` objects configured for this + application. + +* :ref:`InterfaceRtemsConfigurationGetMaximumPorts` - Gets the resource number + of :ref:`RTEMSAPIClassicDPMem` objects configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetMaximumProcessors` - Gets the maximum + number of processors configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetMaximumRegions` - Gets the resource + number of :ref:`RTEMSAPIClassicRegion` objects configured for this + application. + +* :ref:`InterfaceRtemsConfigurationGetMaximumSemaphores` - Gets the resource + number of :ref:`RTEMSAPIClassicSem` objects configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetMaximumTasks` - Gets the resource number + of :ref:`RTEMSAPIClassicTasks` objects configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetMaximumTimers` - Gets the resource number + of :ref:`RTEMSAPIClassicTimer` objects configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetMicrosecondsPerTick` - Gets the number of + microseconds per clock tick configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetMillisecondsPerTick` - Gets the number of + milliseconds per clock tick configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetNanosecondsPerTick` - Gets the number of + microseconds per clock tick configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetNumberOfInitialExtensions` - Gets the + number of initial extensions configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetStackAllocateForIdleHook` - Gets the task + stack allocator allocate hook used to allocate the stack of each :term:`IDLE + task` configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetStackAllocateHook` - Gets the task stack + allocator allocate hook configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetStackAllocateInitHook` - Gets the task + stack allocator initialization hook configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetStackAllocatorAvoidsWorkSpace` - + Indicates if the task stack allocator is configured to avoid the RTEMS + Workspace for this application. + +* :ref:`InterfaceRtemsConfigurationGetStackFreeHook` - Gets the task stack + allocator free hook configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetStackSpaceSize` - Gets the configured + size in bytes of the memory space used to allocate thread stacks for this + application. + +* :ref:`InterfaceRtemsConfigurationGetTicksPerTimeslice` - Gets the clock ticks + per timeslice configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetUnifiedWorkArea` - Indicates if the RTEMS + Workspace and C Program Heap are configured to be unified for this + application. + +* :ref:`InterfaceRtemsConfigurationGetUserExtensionTable` - Gets the initial + extensions table configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetUserMultiprocessingTable` - Gets the MPCI + configuration table configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetWorkSpaceSize` - Gets the RTEMS Workspace + size in bytes configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetRtemsApiConfiguration` - Gets the Classic + API Configuration Table of this application. + +* :ref:`InterfaceRtemsResourceIsUnlimited` - Indicates if the resource is + unlimited. + +* :ref:`InterfaceRtemsResourceMaximumPerAllocation` - Gets the maximum number + per allocation of a resource number. + +* :ref:`InterfaceRtemsResourceUnlimited` - Augments the resource number so that + it indicates an unlimited resource. diff --git a/c-user/config/mpci.rst b/c-user/config/mpci.rst index 0c967c6..ab9d568 100644 --- a/c-user/config/mpci.rst +++ b/c-user/config/mpci.rst @@ -1,7 +1,7 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2022 On-Line Applications Research Corporation (OAR) .. This file is part of the RTEMS quality process and was automatically .. generated. If you find something that needs to be fixed or @@ -23,15 +23,20 @@ Multiprocessing Configuration ============================= -This section describes multiprocessing related configuration options. The -options are only used if RTEMS was built with the ``--enable-multiprocessing`` -build configuration option. Additionally, this class of configuration options -are only applicable if the configuration option :ref:`CONFIGURE_MP_APPLICATION` -is defined. The multiprocessing (MPCI) support must not be confused with the -SMP support. +This section describes multiprocessing related configuration options. +The options are only used if RTEMS was built when the multiprocessing +build configuration option is enabled. The multiprocessing configuration +is distinct from the SMP configuration. Additionally, this class of +configuration options are only applicable if the configuration option +:ref:`CONFIGURE_MP_APPLICATION` is defined. The multiprocessing (MPCI) +support must not be confused with the SMP support. .. Generated from spec:/acfg/if/mp-extra-server-stack +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_EXTRA_MPCI_RECEIVE_SERVER_STACK .. _CONFIGURE_EXTRA_MPCI_RECEIVE_SERVER_STACK: @@ -39,39 +44,49 @@ SMP support. CONFIGURE_EXTRA_MPCI_RECEIVE_SERVER_STACK ----------------------------------------- -CONSTANT: - ``CONFIGURE_EXTRA_MPCI_RECEIVE_SERVER_STACK`` +.. rubric:: CONSTANT: + +``CONFIGURE_EXTRA_MPCI_RECEIVE_SERVER_STACK`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is an integer define. +The value of this configuration option defines the number of bytes the +applications wishes to add to the MPCI task stack on top of +:ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. -DEFAULT VALUE: - The default value is 0. +.. rubric:: NOTES: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +This configuration option is only evaluated if +:ref:`CONFIGURE_MP_APPLICATION` is defined. - * It shall be greater than or equal to 0. +.. rubric:: CONSTRAINTS: - * It shall be less than or equal to `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. +The following constraints apply to this configuration option: - * It shall be small enough so that the - MPCI receive server stack area calculation carried out by - ``<rtems/confdefs.h>`` does not overflow an integer of type - `size_t <https://en.cppreference.com/w/c/types/size_t>`_. +* The value of the configuration option shall be greater than or equal to zero. -DESCRIPTION: - The value of this configuration option defines the number of bytes the - applications wishes to add to the MPCI task stack on top of - :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. -NOTES: - This configuration option is only evaluated if - :ref:`CONFIGURE_MP_APPLICATION` is defined. +* The value of the configuration option shall be small enough so that the MPCI + receive server stack area calculation carried out by ``<rtems/confdefs.h>`` + does not overflow an integer of type `size_t + <https://en.cppreference.com/w/c/types/size_t>`_. .. Generated from spec:/acfg/if/mp-appl +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MP_APPLICATION .. _CONFIGURE_MP_APPLICATION: @@ -79,29 +94,38 @@ NOTES: CONFIGURE_MP_APPLICATION ------------------------ -CONSTANT: - ``CONFIGURE_MP_APPLICATION`` +.. rubric:: CONSTANT: + +``CONFIGURE_MP_APPLICATION`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the multiprocessing services - are not initialized. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - This configuration option is defined to indicate that the application intends - to be part of a multiprocessing configuration. Additional configuration - options are assumed to be provided. +If this configuration option is undefined, then the multiprocessing services +are not initialized. -NOTES: - This configuration option shall be undefined if the multiprocessing support - is not enabled (e.g. RTEMS was built without the ``--enable-multiprocessing`` - build configuration option). Otherwise a compile time error in the - configuration file will occur. +.. rubric:: DESCRIPTION: + +This configuration option is defined to indicate that the application intends +to be part of a multiprocessing configuration. Additional configuration +options are assumed to be provided. + +.. rubric:: NOTES: + +This configuration option shall be undefined if the multiprocessing support +is not enabled (e.g. RTEMS was built without the multiprocessing build +configuration option enabled). Otherwise a compile time error in the +configuration file will occur. .. Generated from spec:/acfg/if/mp-max-global-objects +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS .. _CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS: @@ -109,32 +133,46 @@ NOTES: CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS ----------------------------------- -CONSTANT: - ``CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 32. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the maximum number of +concurrently active global objects in a multiprocessor system. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: NOTES: -DEFAULT VALUE: - The default value is 32. +This value corresponds to the total number of objects which can be created +with the :c:macro:`RTEMS_GLOBAL` attribute. -VALUE CONSTRAINTS: - The value of this configuration option shall be greater than or equal to 0 - and less than or equal to `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. +This configuration option is only evaluated if +:ref:`CONFIGURE_MP_APPLICATION` is defined. -DESCRIPTION: - The value of this configuration option defines the maximum number of - concurrently active global objects in a multiprocessor system. +.. rubric:: CONSTRAINTS: -NOTES: - This value corresponds to the total number of objects which can be created - with the :c:macro:`RTEMS_GLOBAL` attribute. +The following constraints apply to this configuration option: - This configuration option is only evaluated if - :ref:`CONFIGURE_MP_APPLICATION` is defined. +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. .. Generated from spec:/acfg/if/mp-max-nodes +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MP_MAXIMUM_NODES .. _CONFIGURE_MP_MAXIMUM_NODES: @@ -142,29 +180,43 @@ NOTES: CONFIGURE_MP_MAXIMUM_NODES -------------------------- -CONSTANT: - ``CONFIGURE_MP_MAXIMUM_NODES`` +.. rubric:: CONSTANT: + +``CONFIGURE_MP_MAXIMUM_NODES`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 2. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DESCRIPTION: -DEFAULT VALUE: - The default value is 2. +The value of this configuration option defines the maximum number of nodes in +a multiprocessor system. -VALUE CONSTRAINTS: - The value of this configuration option shall be greater than or equal to 0 - and less than or equal to `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. +.. rubric:: NOTES: -DESCRIPTION: - The value of this configuration option defines the maximum number of nodes in - a multiprocessor system. +This configuration option is only evaluated if +:ref:`CONFIGURE_MP_APPLICATION` is defined. -NOTES: - This configuration option is only evaluated if - :ref:`CONFIGURE_MP_APPLICATION` is defined. +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. .. Generated from spec:/acfg/if/mp-max-proxies +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MP_MAXIMUM_PROXIES .. _CONFIGURE_MP_MAXIMUM_PROXIES: @@ -172,35 +224,49 @@ NOTES: CONFIGURE_MP_MAXIMUM_PROXIES ---------------------------- -CONSTANT: - ``CONFIGURE_MP_MAXIMUM_PROXIES`` +.. rubric:: CONSTANT: + +``CONFIGURE_MP_MAXIMUM_PROXIES`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DEFAULT VALUE: -DEFAULT VALUE: - The default value is 32. +The default value is 32. -VALUE CONSTRAINTS: - The value of this configuration option shall be greater than or equal to 0 - and less than or equal to `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. +.. rubric:: DESCRIPTION: -DESCRIPTION: - The value of this configuration option defines the maximum number of - concurrently active thread/task proxies on this node in a multiprocessor - system. +The value of this configuration option defines the maximum number of +concurrently active thread/task proxies on this node in a multiprocessor +system. -NOTES: - Since a proxy is used to represent a remote task/thread which is blocking - on this node. This configuration parameter reflects the maximum number of - remote tasks/threads which can be blocked on objects on this node, see - :ref:`MPCIProxies`. +.. rubric:: NOTES: - This configuration option is only evaluated if - :ref:`CONFIGURE_MP_APPLICATION` is defined. +Since a proxy is used to represent a remote task/thread which is blocking +on this node. This configuration parameter reflects the maximum number of +remote tasks/threads which can be blocked on objects on this node, see +:ref:`MPCIProxies`. + +This configuration option is only evaluated if +:ref:`CONFIGURE_MP_APPLICATION` is defined. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. .. Generated from spec:/acfg/if/mp-mpci-table-pointer +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MP_MPCI_TABLE_POINTER .. _CONFIGURE_MP_MPCI_TABLE_POINTER: @@ -208,33 +274,43 @@ NOTES: CONFIGURE_MP_MPCI_TABLE_POINTER ------------------------------- -CONSTANT: - ``CONFIGURE_MP_MPCI_TABLE_POINTER`` +.. rubric:: CONSTANT: + +``CONFIGURE_MP_MPCI_TABLE_POINTER`` -OPTION TYPE: - This configuration option is an initializer define. +.. rubric:: OPTION TYPE: -DEFAULT VALUE: - The default value is ``&MPCI_table``. +This configuration option is an initializer define. -VALUE CONSTRAINTS: - The value of this configuration option shall be a pointer to - :c:type:`rtems_mpci_table`. +.. rubric:: DEFAULT VALUE: -DESCRIPTION: - The value of this configuration option initializes the MPCI Configuration - Table. +The default value is ``&MPCI_table``. -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. +.. rubric:: DESCRIPTION: - This configuration option is only evaluated if - :ref:`CONFIGURE_MP_APPLICATION` is defined. +The value of this configuration option initializes the MPCI Configuration +Table. + +.. rubric:: 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. + +This configuration option is only evaluated if +:ref:`CONFIGURE_MP_APPLICATION` is defined. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be a pointer to +:c:type:`rtems_mpci_table`. .. Generated from spec:/acfg/if/mp-node-number +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MP_NODE_NUMBER .. _CONFIGURE_MP_NODE_NUMBER: @@ -242,28 +318,38 @@ NOTES: CONFIGURE_MP_NODE_NUMBER ------------------------ -CONSTANT: - ``CONFIGURE_MP_NODE_NUMBER`` +.. rubric:: CONSTANT: + +``CONFIGURE_MP_NODE_NUMBER`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is ``NODE_NUMBER``. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the node number of this node +in a multiprocessor system. + +.. rubric:: NOTES: -OPTION TYPE: - This configuration option is an integer define. +In the RTEMS Multiprocessing Test Suite, the node number is derived from +the Makefile variable ``NODE_NUMBER``. The same code is compiled with the +``NODE_NUMBER`` set to different values. The test programs behave +differently based upon their node number. -DEFAULT VALUE: - The default value is ``NODE_NUMBER``. +This configuration option is only evaluated if +:ref:`CONFIGURE_MP_APPLICATION` is defined. -VALUE CONSTRAINTS: - The value of this configuration option shall be greater than or equal to 0 - and less than or equal to `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. +.. rubric:: CONSTRAINTS: -DESCRIPTION: - The value of this configuration option defines the node number of this node - in a multiprocessor system. +The following constraints apply to this configuration option: -NOTES: - In the RTEMS Multiprocessing Test Suite, the node number is derived from - the Makefile variable ``NODE_NUMBER``. The same code is compiled with the - ``NODE_NUMBER`` set to different values. The test programs behave - differently based upon their node number. +* The value of the configuration option shall be greater than or equal to zero. - This configuration option is only evaluated if - :ref:`CONFIGURE_MP_APPLICATION` is defined. +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. diff --git a/c-user/config/posix-api.rst b/c-user/config/posix-api.rst index 592a1ce..f788c08 100644 --- a/c-user/config/posix-api.rst +++ b/c-user/config/posix-api.rst @@ -1,7 +1,7 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2022 On-Line Applications Research Corporation (OAR) .. This file is part of the RTEMS quality process and was automatically .. generated. If you find something that needs to be fixed or @@ -25,11 +25,15 @@ POSIX API Configuration This section describes configuration options related to the POSIX API. Most POSIX API objects are available by default since RTEMS 5.1. The queued signals -and timers are only available if RTEMS was built with the ``--enable-posix`` +and timers are only available if RTEMS was built with the enable POSIX build configuration option. .. Generated from spec:/acfg/if/max-posix-keys +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MAXIMUM_POSIX_KEYS .. _CONFIGURE_MAXIMUM_POSIX_KEYS: @@ -37,42 +41,51 @@ build configuration option. CONFIGURE_MAXIMUM_POSIX_KEYS ---------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_POSIX_KEYS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_POSIX_KEYS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DEFAULT VALUE: -DEFAULT VALUE: - The default value is 0. +The default value is 0. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: DESCRIPTION: - * It shall be greater than or equal to 0. +The value of this configuration option defines the maximum number of POSIX +API Keys that can be concurrently active. - * It shall be less than or equal to 65535. +.. rubric:: NOTES: - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. - * It may be defined through - :c:func:`rtems_resource_unlimited` the enable unlimited objects for this - object class, if the value passed to :c:func:`rtems_resource_unlimited` - satisfies all other constraints of this configuration option. +.. rubric:: CONSTRAINTS: -DESCRIPTION: - The value of this configuration option defines the maximum number of POSIX - API Keys that can be concurrently active. +The following constraints apply to this configuration option: -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +* The value of the configuration option may be defined through + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` + satisfies all other constraints of the configuration option. .. Generated from spec:/acfg/if/max-posix-key-value-pairs +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS .. _CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS: @@ -80,48 +93,57 @@ NOTES: CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS --------------------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: -OPTION TYPE: - This configuration option is an integer define. +The default value is +:ref:`CONFIGURE_MAXIMUM_POSIX_KEYS` * +( :ref:`CONFIGURE_MAXIMUM_TASKS` + +:ref:`CONFIGURE_MAXIMUM_POSIX_THREADS` ). -DEFAULT VALUE: - The default value is - :ref:`CONFIGURE_MAXIMUM_POSIX_KEYS` * - :ref:`CONFIGURE_MAXIMUM_TASKS` + - :ref:`CONFIGURE_MAXIMUM_POSIX_THREADS`. +.. rubric:: DESCRIPTION: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The value of this configuration option defines the maximum number of key +value pairs used by POSIX API Keys that can be concurrently active. - * It shall be greater than or equal to 0. +.. rubric:: NOTES: - * It shall be less than or equal to 65535. +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +A key value pair is created by :c:func:`pthread_setspecific` if the value +is not `NULL <https://en.cppreference.com/w/c/types/NULL>`_, otherwise it is deleted. - * It may be defined through - :c:func:`rtems_resource_unlimited` the enable unlimited objects for this - object class, if the value passed to :c:func:`rtems_resource_unlimited` - satisfies all other constraints of this configuration option. +.. rubric:: CONSTRAINTS: -DESCRIPTION: - The value of this configuration option defines the maximum number of key - value pairs used by POSIX API Keys that can be concurrently active. +The following constraints apply to this configuration option: -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. +* The value of the configuration option shall be greater than or equal to zero. - A key value pair is created by :c:func:`pthread_setspecific` if the value - is not `NULL <https://en.cppreference.com/w/c/types/NULL>`_, otherwise it is deleted. +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +* The value of the configuration option may be defined through + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` + satisfies all other constraints of the configuration option. .. Generated from spec:/acfg/if/max-posix-message-queues +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES .. _CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES: @@ -129,48 +151,58 @@ NOTES: CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES -------------------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is an integer define. +``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES`` -DEFAULT VALUE: - The default value is 0. +.. rubric:: OPTION TYPE: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +This configuration option is an integer define. - * It shall be greater than or equal to 0. +.. rubric:: DEFAULT VALUE: - * It shall be less than or equal to 65535. +The default value is 0. - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +.. rubric:: DESCRIPTION: - * It shall be small enough so that the - RTEMS Workspace size calculation carried out by ``<rtems/confdefs.h>`` does - not overflow an integer of type `uintptr_t <https://en.cppreference.com/w/c/types/integer>`_. +The value of this configuration option defines the maximum number of POSIX +API Message Queues that can be concurrently active. - * It may be defined through - :c:func:`rtems_resource_unlimited` the enable unlimited objects for this - object class, if the value passed to :c:func:`rtems_resource_unlimited` - satisfies all other constraints of this configuration option. +.. rubric:: NOTES: -DESCRIPTION: - The value of this configuration option defines the maximum number of POSIX - API Message Queues that can be concurrently active. +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. You have to account for the memory used to +store the messages of each message queue, see +:ref:`CONFIGURE_MESSAGE_BUFFER_MEMORY`. -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. You have to account for the memory used to - store the messages of each message queue, see - :ref:`CONFIGURE_MESSAGE_BUFFER_MEMORY`. +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +* The value of the configuration option shall be small enough so that the RTEMS + Workspace size calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. + +* The value of the configuration option may be defined through + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` + satisfies all other constraints of the configuration option. .. Generated from spec:/acfg/if/max-posix-queued-signals +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS .. _CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS: @@ -178,46 +210,56 @@ NOTES: CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS -------------------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS`` -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: OPTION TYPE: -DEFAULT VALUE: - The default value is 0. +This configuration option is an integer define. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: DEFAULT VALUE: - * It shall be greater than or equal to 0. +The default value is 0. - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +.. rubric:: DESCRIPTION: - * It shall be small enough so that the - RTEMS Workspace size calculation carried out by ``<rtems/confdefs.h>`` does - not overflow an integer of type `uintptr_t <https://en.cppreference.com/w/c/types/integer>`_. +The value of this configuration option defines the maximum number of POSIX +API Queued Signals that can be concurrently active. - * It shall be zero if the POSIX API is not - enabled (e.g. RTEMS was built without the ``--enable-posix`` build - configuration option). Otherwise a compile time error in the configuration - file will occur. +.. rubric:: NOTES: -DESCRIPTION: - The value of this configuration option defines the maximum number of POSIX - API Queued Signals that can be concurrently active. +Unlimited objects are not available for queued signals. -NOTES: - Unlimited objects are not available for queued signals. +Queued signals are only available if RTEMS was built with the POSIX API +build configuration option enabled. - Queued signals are only available if RTEMS was built with the - ``--enable-posix`` build configuration option. +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +* The value of the configuration option shall be small enough so that the RTEMS + Workspace size calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. + +* The value of the configuration option shall be zero if the POSIX API is not + enabled (e.g. RTEMS was built without the ``RTEMS_POSIX_API = True`` build + configuration option). Otherwise a compile time error in the configuration + file will occur. .. Generated from spec:/acfg/if/max-posix-semaphores +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MAXIMUM_POSIX_SEMAPHORES .. _CONFIGURE_MAXIMUM_POSIX_SEMAPHORES: @@ -225,51 +267,61 @@ NOTES: CONFIGURE_MAXIMUM_POSIX_SEMAPHORES ---------------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_POSIX_SEMAPHORES`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_POSIX_SEMAPHORES`` -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: OPTION TYPE: -DEFAULT VALUE: - The default value is 0. +This configuration option is an integer define. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: DEFAULT VALUE: - * It shall be greater than or equal to 0. +The default value is 0. - * It shall be less than or equal to 65535. +.. rubric:: DESCRIPTION: - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +The value of this configuration option defines the maximum number of POSIX +API Named Semaphores that can be concurrently active. - * It shall be small enough so that the - RTEMS Workspace size calculation carried out by ``<rtems/confdefs.h>`` does - not overflow an integer of type `uintptr_t <https://en.cppreference.com/w/c/types/integer>`_. +.. rubric:: NOTES: - * It may be defined through - :c:func:`rtems_resource_unlimited` the enable unlimited objects for this - object class, if the value passed to :c:func:`rtems_resource_unlimited` - satisfies all other constraints of this configuration option. +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. -DESCRIPTION: - The value of this configuration option defines the maximum number of POSIX - API Named Semaphores that can be concurrently active. +Named semaphores are created with :c:func:`sem_open`. Semaphores +initialized with :c:func:`sem_init` are not affected by this +configuration option since the storage space for these semaphores is +user-provided. -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. +.. rubric:: CONSTRAINTS: - Named semaphores are created with :c:func:`sem_open`. Semaphores - initialized with :c:func:`sem_init` are not affected by this - configuration option since the storage space for these semaphores is - user-provided. +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +* The value of the configuration option shall be small enough so that the RTEMS + Workspace size calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. + +* The value of the configuration option may be defined through + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` + satisfies all other constraints of the configuration option. .. Generated from spec:/acfg/if/max-posix-shms +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MAXIMUM_POSIX_SHMS .. _CONFIGURE_MAXIMUM_POSIX_SHMS: @@ -277,46 +329,56 @@ NOTES: CONFIGURE_MAXIMUM_POSIX_SHMS ---------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_POSIX_SHMS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_POSIX_SHMS`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is an integer define. +This configuration option is an integer define. -DEFAULT VALUE: - The default value is 0. +.. rubric:: DEFAULT VALUE: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The default value is 0. - * It shall be greater than or equal to 0. +.. rubric:: DESCRIPTION: - * It shall be less than or equal to 65535. +The value of this configuration option defines the maximum number of POSIX +API Shared Memory objects that can be concurrently active. - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +.. rubric:: NOTES: - * It shall be small enough so that the - RTEMS Workspace size calculation carried out by ``<rtems/confdefs.h>`` does - not overflow an integer of type `uintptr_t <https://en.cppreference.com/w/c/types/integer>`_. +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. - * It may be defined through - :c:func:`rtems_resource_unlimited` the enable unlimited objects for this - object class, if the value passed to :c:func:`rtems_resource_unlimited` - satisfies all other constraints of this configuration option. +.. rubric:: CONSTRAINTS: -DESCRIPTION: - The value of this configuration option defines the maximum number of POSIX - API Shared Memory objects that can be concurrently active. +The following constraints apply to this configuration option: -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +* The value of the configuration option shall be small enough so that the RTEMS + Workspace size calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. + +* The value of the configuration option may be defined through + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` + satisfies all other constraints of the configuration option. .. Generated from spec:/acfg/if/max-posix-threads +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MAXIMUM_POSIX_THREADS .. _CONFIGURE_MAXIMUM_POSIX_THREADS: @@ -324,51 +386,61 @@ NOTES: CONFIGURE_MAXIMUM_POSIX_THREADS ------------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_POSIX_THREADS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_POSIX_THREADS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DEFAULT VALUE: -DEFAULT VALUE: - The default value is 0. +The default value is 0. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: DESCRIPTION: - * It shall be greater than or equal to 0. +The value of this configuration option defines the maximum number of POSIX +API Threads that can be concurrently active. - * It shall be less than or equal to 65535. +.. rubric:: NOTES: - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. - * It shall be small enough so that the task - stack space calculation carried out by ``<rtems/confdefs.h>`` does not - overflow an integer of type `uintptr_t <https://en.cppreference.com/w/c/types/integer>`_. +This calculations for the required memory in the RTEMS Workspace for threads +assume that each thread has a minimum stack size and has floating point +support enabled. The configuration option :ref:`CONFIGURE_EXTRA_TASK_STACKS` is used +to specify thread stack requirements **above** the minimum size required. -DESCRIPTION: - The value of this configuration option defines the maximum number of POSIX - API Threads that can be concurrently active. +The maximum number of Classic API Tasks is specified by +:ref:`CONFIGURE_MAXIMUM_TASKS`. -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. +All POSIX threads have floating point enabled. - This calculations for the required memory in the RTEMS Workspace for threads - assume that each thread has a minimum stack size and has floating point - support enabled. The configuration option :ref:`CONFIGURE_EXTRA_TASK_STACKS` is used - to specify thread stack requirements **above** the minimum size required. +.. rubric:: CONSTRAINTS: - The maximum number of Classic API Tasks is specified by - :ref:`CONFIGURE_MAXIMUM_TASKS`. +The following constraints apply to this configuration option: - All POSIX threads have floating point enabled. +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +* The value of the configuration option shall be small enough so that the task + stack space calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. .. Generated from spec:/acfg/if/max-posix-timers +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MAXIMUM_POSIX_TIMERS .. _CONFIGURE_MAXIMUM_POSIX_TIMERS: @@ -376,50 +448,59 @@ NOTES: CONFIGURE_MAXIMUM_POSIX_TIMERS ------------------------------ -CONSTANT: - ``CONFIGURE_MAXIMUM_POSIX_TIMERS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_POSIX_TIMERS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: -OPTION TYPE: - This configuration option is an integer define. +The default value is 0. -DEFAULT VALUE: - The default value is 0. +.. rubric:: DESCRIPTION: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The value of this configuration option defines the maximum number of POSIX +API Timers that can be concurrently active. - * It shall be greater than or equal to 0. +.. rubric:: NOTES: - * It shall be less than or equal to 65535. +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +Timers are only available if RTEMS was built with the POSIX API build +configuration option enabled. - * It may be defined through - :c:func:`rtems_resource_unlimited` the enable unlimited objects for this - object class, if the value passed to :c:func:`rtems_resource_unlimited` - satisfies all other constraints of this configuration option. +.. rubric:: CONSTRAINTS: - * It shall be zero if the POSIX API is not - enabled (e.g. RTEMS was built without the ``--enable-posix`` build - configuration option). Otherwise a compile time error in the configuration - file will occur. +The following constraints apply to this configuration option: -DESCRIPTION: - The value of this configuration option defines the maximum number of POSIX - API Timers that can be concurrently active. +* The value of the configuration option shall be greater than or equal to zero. -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. +* The value of the configuration option shall be less than or equal to 65535. - Timers are only available if RTEMS was built with the - ``--enable-posix`` build configuration option. +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +* The value of the configuration option may be defined through + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` + satisfies all other constraints of the configuration option. + +* The value of the configuration option shall be zero if the POSIX API is not + enabled (e.g. RTEMS was built without the ``RTEMS_POSIX_API = True`` build + configuration option). Otherwise a compile time error in the configuration + file will occur. .. Generated from spec:/acfg/if/min-posix-thread-stack-size +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE .. index:: minimum POSIX thread stack size @@ -428,30 +509,32 @@ NOTES: CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE ----------------------------------------- -CONSTANT: - ``CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: -OPTION TYPE: - This configuration option is an integer define. +The default value is two times the value of +:ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. -DEFAULT VALUE: - The default value is two times the value of - :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. +.. rubric:: DESCRIPTION: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The value of this configuration option defines the minimum stack size in +bytes for every POSIX thread in the system. - * It shall be small enough so that the task - stack space calculation carried out by ``<rtems/confdefs.h>`` does not - overflow an integer of type `uintptr_t <https://en.cppreference.com/w/c/types/integer>`_. +.. rubric:: CONSTRAINTS: - * It shall be greater than or equal to a - BSP-specific and application-specific minimum value. +The following constraints apply to this configuration option: -DESCRIPTION: - The value of this configuration option defines the minimum stack size in - bytes for every POSIX thread in the system. +* The value of the configuration option shall be small enough so that the task + stack space calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. -NOTES: - None. +* The value of the configuration option shall be greater than or equal to a + BSP-specific and application-specific minimum value. diff --git a/c-user/config/posix-init-thread.rst b/c-user/config/posix-init-thread.rst index 42542e5..ee09ba0 100644 --- a/c-user/config/posix-init-thread.rst +++ b/c-user/config/posix-init-thread.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) .. This file is part of the RTEMS quality process and was automatically @@ -28,6 +28,10 @@ initialization thread. .. Generated from spec:/acfg/if/posix-init-thread-entry-point +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT .. _CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT: @@ -35,29 +39,39 @@ initialization thread. CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT --------------------------------------- -CONSTANT: - ``CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT`` +.. rubric:: CONSTANT: + +``CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT`` + +.. rubric:: OPTION TYPE: + +This configuration option is an initializer define. + +.. rubric:: DEFAULT VALUE: -OPTION TYPE: - This configuration option is an initializer define. +The default value is ``POSIX_Init``. -DEFAULT VALUE: - The default value is ``POSIX_Init``. +.. rubric:: DESCRIPTION: -VALUE CONSTRAINTS: - The value of this configuration option shall be defined to a valid function - pointer of the type ``void *( *entry_point )( void * )``. +The value of this configuration option initializes the entry point of the +POSIX API initialization thread. -DESCRIPTION: - The value of this configuration option initializes the entry point of the - POSIX API initialization thread. +.. rubric:: NOTES: -NOTES: - The application shall provide the function referenced by this configuration - option. +The application shall provide the function referenced by this configuration +option. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be defined to a valid function +pointer of the type ``void *( *entry_point )( void * )``. .. Generated from spec:/acfg/if/posix-init-thread-stack-size +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE .. _CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE: @@ -65,34 +79,41 @@ NOTES: CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE -------------------------------------- -CONSTANT: - ``CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE`` -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: OPTION TYPE: -DEFAULT VALUE: - The default value is :ref:`CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE`. +This configuration option is an integer define. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: DEFAULT VALUE: - * It shall be greater than or equal to :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. +The default value is :ref:`CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE`. - * It shall be small enough so that the task - stack space calculation carried out by ``<rtems/confdefs.h>`` does not - overflow an integer of type `uintptr_t <https://en.cppreference.com/w/c/types/integer>`_. +.. rubric:: DESCRIPTION: -DESCRIPTION: - The value of this configuration option defines the thread stack size of the - POSIX API initialization thread. +The value of this configuration option defines the thread stack size of the +POSIX API initialization thread. -NOTES: - None. +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to + :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. + +* The value of the configuration option shall be small enough so that the task + stack space calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. .. Generated from spec:/acfg/if/posix-init-thread-table +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_POSIX_INIT_THREAD_TABLE .. _CONFIGURE_POSIX_INIT_THREAD_TABLE: @@ -100,28 +121,36 @@ NOTES: CONFIGURE_POSIX_INIT_THREAD_TABLE --------------------------------- -CONSTANT: - ``CONFIGURE_POSIX_INIT_THREAD_TABLE`` +.. rubric:: CONSTANT: + +``CONFIGURE_POSIX_INIT_THREAD_TABLE`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is a boolean feature define. +In case this configuration option is defined, then exactly one POSIX +initialization thread is configured. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: NOTES: -DESCRIPTION: - In case this configuration option is defined, then exactly one POSIX - initialization thread is configured. +The application shall define at least one of the following configuration +options -NOTES: - The application shall define exactly one of the following configuration - options +* :ref:`CONFIGURE_RTEMS_INIT_TASKS_TABLE`, - * :ref:`CONFIGURE_RTEMS_INIT_TASKS_TABLE`, +* ``CONFIGURE_POSIX_INIT_THREAD_TABLE``, or - * ``CONFIGURE_POSIX_INIT_THREAD_TABLE``, or +* :ref:`CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION` - * :ref:`CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION` +otherwise a compile time error in the configuration file will occur. - otherwise a compile time error in the configuration file will occur. +If no Classic API initialization task is configured, then the POSIX API +initialization thread performs the :ref:`GlobalConstruction`. diff --git a/c-user/config/scheduler-general.rst b/c-user/config/scheduler-general.rst index cbdb145..d347d6b 100644 --- a/c-user/config/scheduler-general.rst +++ b/c-user/config/scheduler-general.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020, 2022 embedded brains GmbH & Co. KG .. Copyright (C) 2010 Gedare Bloom .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) @@ -49,6 +49,10 @@ configuration option. .. Generated from spec:/acfg/if/cbs-max-servers +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_CBS_MAXIMUM_SERVERS .. _CONFIGURE_CBS_MAXIMUM_SERVERS: @@ -56,37 +60,47 @@ configuration option. CONFIGURE_CBS_MAXIMUM_SERVERS ----------------------------- -CONSTANT: - ``CONFIGURE_CBS_MAXIMUM_SERVERS`` +.. rubric:: CONSTANT: + +``CONFIGURE_CBS_MAXIMUM_SERVERS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DEFAULT VALUE: -DEFAULT VALUE: - The default value is :ref:`CONFIGURE_MAXIMUM_TASKS`. +The default value is :ref:`CONFIGURE_MAXIMUM_TASKS`. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: DESCRIPTION: - * It shall be greater than or equal to 0. +The value of this configuration option defines the maximum number Constant +Bandwidth Servers that can be concurrently active. - * It shall be less than or equal to `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_. +.. rubric:: NOTES: - * It shall be less than or equal to a - BSP-specific and application-specific value which depends on the size of the - memory available to the application. +This configuration option is only evaluated if the configuration option +:ref:`CONFIGURE_SCHEDULER_CBS` is defined. -DESCRIPTION: - The value of this configuration option defines the maximum number Constant - Bandwidth Servers that can be concurrently active. +.. rubric:: CONSTRAINTS: -NOTES: - This configuration option is only evaluated if the configuration option - :ref:`CONFIGURE_SCHEDULER_CBS` is defined. +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. .. Generated from spec:/acfg/if/max-priority +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MAXIMUM_PRIORITY .. index:: maximum priority .. index:: number of priority levels @@ -96,57 +110,67 @@ NOTES: CONFIGURE_MAXIMUM_PRIORITY -------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_PRIORITY`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_PRIORITY`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: -OPTION TYPE: - This configuration option is an integer define. +The default value is 255. -DEFAULT VALUE: - The default value is 255. +.. rubric:: DESCRIPTION: -VALUE CONSTRAINTS: - The value of this configuration option shall be - an element of {3, 7, 31, 63, 127, 255}. +For the following schedulers -DESCRIPTION: - For the following schedulers +* :ref:`SchedulerPriority`, which is the default in uniprocessor + configurations and can be configured through the + :ref:`CONFIGURE_SCHEDULER_PRIORITY` configuration option, - * :ref:`SchedulerPriority`, which is the default in uniprocessor - configurations and can be configured through the - :ref:`CONFIGURE_SCHEDULER_PRIORITY` configuration option, +* :ref:`SchedulerSMPPriority` which can be configured through the + :ref:`CONFIGURE_SCHEDULER_PRIORITY_SMP` configuration option, and - * :ref:`SchedulerSMPPriority` which can be configured through the - :ref:`CONFIGURE_SCHEDULER_PRIORITY_SMP` configuration option, and +* :ref:`SchedulerSMPPriorityAffinity` which can be configured through the + :ref:`CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP` configuration option - * :ref:`SchedulerSMPPriorityAffinity` which can be configured through the - :ref:`CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP` configuration option +this configuration option specifies the maximum numeric priority of any task +for these schedulers and one less that the number of priority levels for +these schedulers. For all other schedulers provided by RTEMS, this +configuration option has no effect. - this configuration option specifies the maximum numeric priority of any task - for these schedulers and one less that the number of priority levels for - these schedulers. For all other schedulers provided by RTEMS, this - configuration option has no effect. +.. rubric:: NOTES: -NOTES: - The numerically greatest priority is the logically lowest priority in the - system and will thus be used by the IDLE task. +The numerically greatest priority is the logically lowest priority in the +system and will thus be used by the IDLE task. - Priority zero is reserved for internal use by RTEMS and is not available to - applications. +Priority zero is reserved for internal use by RTEMS and is not available to +applications. - Reducing the number of priorities through this configuration option reduces - the amount of memory allocated by the schedulers listed above. These - schedulers use a chain control structure per priority and this structure - consists of three pointers. On a 32-bit architecture, the allocated memory - is 12 bytes * (``CONFIGURE_MAXIMUM_PRIORITY`` + 1), e.g. 3072 bytes for 256 - priority levels (default), 48 bytes for 4 priority levels - (``CONFIGURE_MAXIMUM_PRIORITY == 3``). +Reducing the number of priorities through this configuration option reduces +the amount of memory allocated by the schedulers listed above. These +schedulers use a chain control structure per priority and this structure +consists of three pointers. On a 32-bit architecture, the allocated memory +is 12 bytes * (``CONFIGURE_MAXIMUM_PRIORITY`` + 1), e.g. 3072 bytes for 256 +priority levels (default), 48 bytes for 4 priority levels +(``CONFIGURE_MAXIMUM_PRIORITY == 3``). - The default value is 255, because RTEMS shall support 256 priority levels to - be compliant with various standards. These priorities range from 0 to 255. +The default value is 255, because RTEMS shall support 256 priority levels to +be compliant with various standards. These priorities range from 0 to 255. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be equal to 3, 7, 31, 63, 127, or +255. .. Generated from spec:/acfg/if/scheduler-assignments +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_SCHEDULER_ASSIGNMENTS .. _CONFIGURE_SCHEDULER_ASSIGNMENTS: @@ -154,42 +178,63 @@ NOTES: CONFIGURE_SCHEDULER_ASSIGNMENTS ------------------------------- -CONSTANT: - ``CONFIGURE_SCHEDULER_ASSIGNMENTS`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is an initializer define. +``CONFIGURE_SCHEDULER_ASSIGNMENTS`` -DEFAULT VALUE: - The default value of this configuration option is computed so that the - default scheduler is assigned to each configured processor (up to 32). +.. rubric:: OPTION TYPE: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +This configuration option is an initializer define. - * It shall be a list of the following - macros: +.. rubric:: DEFAULT VALUE: - * ``RTEMS_SCHEDULER_ASSIGN( processor_index, attributes )`` +The default value of this configuration option is computed so that the +default scheduler is assigned to each configured processor (up to 32). - * ``RTEMS_SCHEDULER_ASSIGN_NO_SCHEDULER`` +.. rubric:: DESCRIPTION: - * It shall be a list of exactly - :ref:`CONFIGURE_MAXIMUM_PROCESSORS` elements. +The value of this configuration option is used to initialize the initial +scheduler to processor assignments. -DESCRIPTION: - The value of this configuration option is used to initialize the initial - scheduler to processor assignments. +.. rubric:: NOTES: -NOTES: - This configuration option is only evaluated in SMP configurations. +Where the system was built with SMP support enabled, this configuration +option is evaluated, otherwise it is ignored. - This is an advanced configuration option, see - :ref:`ConfigurationSchedulersClustered`. +This is an advanced configuration option, see +:ref:`ConfigurationSchedulersClustered`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be a list of the following + macros: + + * ``RTEMS_SCHEDULER_ASSIGN( scheduler_index, attributes )`` + + * ``RTEMS_SCHEDULER_ASSIGN_NO_SCHEDULER`` + + The ``scheduler_index`` macro parameter shall be a valid index of the + scheduler table defined by the :ref:`CONFIGURE_SCHEDULER_TABLE_ENTRIES` + configuration option. + + The ``attributes`` macro parameter shall be set to exactly one of the + following constants: + + * ``RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY`` + + * ``RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL`` + +* The value of the configuration option shall be a list of exactly + :ref:`CONFIGURE_MAXIMUM_PROCESSORS` elements. .. Generated from spec:/acfg/if/scheduler-cbs +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_SCHEDULER_CBS .. _CONFIGURE_SCHEDULER_CBS: @@ -197,30 +242,39 @@ NOTES: CONFIGURE_SCHEDULER_CBS ----------------------- -CONSTANT: - ``CONFIGURE_SCHEDULER_CBS`` +.. rubric:: CONSTANT: + +``CONFIGURE_SCHEDULER_CBS`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DESCRIPTION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +In case this configuration option is defined, then the +:ref:`SchedulerCBS` +algorithm is made available to the application. -DESCRIPTION: - In case this configuration option is defined, then - :ref:`SchedulerCBS` - algorithm is made available to the application. +.. rubric:: NOTES: -NOTES: - This scheduler configuration option is an advanced configuration option. - Think twice before you use it. +This scheduler configuration option is an advanced configuration option. +Think twice before you use it. - In case no explicit :ref:`ConfigurationSchedulersClustered` - is present, then it is used as the scheduler for exactly one processor. +In case no explicit :ref:`ConfigurationSchedulersClustered` +is present, then it is used as the scheduler for exactly one processor. .. Generated from spec:/acfg/if/scheduler-edf +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_SCHEDULER_EDF .. _CONFIGURE_SCHEDULER_EDF: @@ -228,30 +282,39 @@ NOTES: CONFIGURE_SCHEDULER_EDF ----------------------- -CONSTANT: - ``CONFIGURE_SCHEDULER_EDF`` +.. rubric:: CONSTANT: + +``CONFIGURE_SCHEDULER_EDF`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DEFAULT CONFIGURATION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +If this configuration option is undefined, then the described feature is not +enabled. -DESCRIPTION: - In case this configuration option is defined, then - :ref:`SchedulerEDF` - algorithm is made available to the application. +.. rubric:: DESCRIPTION: -NOTES: - This scheduler configuration option is an advanced configuration option. - Think twice before you use it. +In case this configuration option is defined, then the +:ref:`SchedulerEDF` +algorithm is made available to the application. - In case no explicit :ref:`ConfigurationSchedulersClustered` - is present, then it is used as the scheduler for exactly one processor. +.. rubric:: NOTES: + +This scheduler configuration option is an advanced configuration option. +Think twice before you use it. + +In case no explicit :ref:`ConfigurationSchedulersClustered` +is present, then it is used as the scheduler for exactly one processor. .. Generated from spec:/acfg/if/scheduler-edf-smp +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_SCHEDULER_EDF_SMP .. _CONFIGURE_SCHEDULER_EDF_SMP: @@ -259,37 +322,46 @@ NOTES: CONFIGURE_SCHEDULER_EDF_SMP --------------------------- -CONSTANT: - ``CONFIGURE_SCHEDULER_EDF_SMP`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is a boolean feature define. +``CONFIGURE_SCHEDULER_EDF_SMP`` -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: OPTION TYPE: -DESCRIPTION: - In case this configuration option is defined, then - :ref:`SchedulerSMPEDF` - algorithm is made available to the application. +This configuration option is a boolean feature define. -NOTES: - This scheduler configuration option is an advanced configuration option. - Think twice before you use it. +.. rubric:: DEFAULT CONFIGURATION: - This scheduler algorithm is only available when RTEMS is built with SMP - support enabled. +If this configuration option is undefined, then the described feature is not +enabled. - In case no explicit :ref:`ConfigurationSchedulersClustered` - is present, then it is used as the scheduler for up to 32 processors. +.. rubric:: DESCRIPTION: - This scheduler algorithm is the default in SMP configurations if - :ref:`CONFIGURE_MAXIMUM_PROCESSORS` is - greater than one. +In case this configuration option is defined, then the +:ref:`SchedulerSMPEDF` +algorithm is made available to the application. + +.. rubric:: NOTES: + +This scheduler configuration option is an advanced configuration option. +Think twice before you use it. + +This scheduler algorithm is only available when RTEMS is built with SMP +support enabled. + +In case no explicit :ref:`ConfigurationSchedulersClustered` +is present, then it is used as the scheduler for up to 32 processors. + +This scheduler algorithm is the default in SMP configurations if +:ref:`CONFIGURE_MAXIMUM_PROCESSORS` is +greater than one. .. Generated from spec:/acfg/if/scheduler-name +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_SCHEDULER_NAME .. _CONFIGURE_SCHEDULER_NAME: @@ -297,49 +369,59 @@ NOTES: CONFIGURE_SCHEDULER_NAME ------------------------ -CONSTANT: - ``CONFIGURE_SCHEDULER_NAME`` +.. rubric:: CONSTANT: + +``CONFIGURE_SCHEDULER_NAME`` -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: OPTION TYPE: -DEFAULT VALUE: - The default value is +This configuration option is an integer define. - * ``"MEDF"`` for the :ref:`SchedulerSMPEDF`, +.. rubric:: DEFAULT VALUE: - * ``"MPA "`` for the :ref:`SchedulerSMPPriorityAffinity`, +The default value is - * ``"MPD "`` for the :ref:`SchedulerSMPPriority`, +* ``"MEDF"`` for the :ref:`SchedulerSMPEDF`, - * ``"MPS "`` for the :ref:`SchedulerSMPPrioritySimple`, +* ``"MPA "`` for the :ref:`SchedulerSMPPriorityAffinity`, - * ``"UCBS"`` for the :ref:`SchedulerCBS`, +* ``"MPD "`` for the :ref:`SchedulerSMPPriority`, - * ``"UEDF"`` for the :ref:`SchedulerEDF`, +* ``"MPS "`` for the :ref:`SchedulerSMPPrioritySimple`, - * ``"UPD "`` for the :ref:`SchedulerPriority`, and +* ``"UCBS"`` for the :ref:`SchedulerCBS`, - * ``"UPS "`` for the :ref:`SchedulerPrioritySimple`. +* ``"UEDF"`` for the :ref:`SchedulerEDF`, -VALUE CONSTRAINTS: - The value of this configuration option shall be a valid integer of type - :c:type:`rtems_name`. +* ``"UPD "`` for the :ref:`SchedulerPriority`, and -DESCRIPTION: - The value of this configuration option defines the name of the default - scheduler. +* ``"UPS "`` for the :ref:`SchedulerPrioritySimple`. -NOTES: - This scheduler configuration option is an advanced configuration option. - Think twice before you use it. +.. rubric:: DESCRIPTION: - Schedulers can be identified via :c:func:`rtems_scheduler_ident`. +The value of this configuration option defines the name of the default +scheduler. - Use :c:func:`rtems_build_name` to define the scheduler name. +.. rubric:: NOTES: + +This scheduler configuration option is an advanced configuration option. +Think twice before you use it. + +Schedulers can be identified via :ref:`InterfaceRtemsSchedulerIdent`. + +Use :ref:`InterfaceRtemsBuildName` to define the scheduler name. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be convertible to an integer of +type :c:type:`rtems_name`. .. Generated from spec:/acfg/if/scheduler-priority +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_SCHEDULER_PRIORITY .. _CONFIGURE_SCHEDULER_PRIORITY: @@ -347,37 +429,46 @@ NOTES: CONFIGURE_SCHEDULER_PRIORITY ---------------------------- -CONSTANT: - ``CONFIGURE_SCHEDULER_PRIORITY`` +.. rubric:: CONSTANT: + +``CONFIGURE_SCHEDULER_PRIORITY`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then - :ref:`SchedulerPriority` - algorithm is made available to the application. +If this configuration option is undefined, then the described feature is not +enabled. -NOTES: - This scheduler configuration option is an advanced configuration option. - Think twice before you use it. +.. rubric:: DESCRIPTION: - In case no explicit :ref:`ConfigurationSchedulersClustered` - is present, then it is used as the scheduler for exactly one processor. +In case this configuration option is defined, then the +:ref:`SchedulerPriority` +algorithm is made available to the application. - This scheduler algorithm is the default when - :ref:`CONFIGURE_MAXIMUM_PROCESSORS` is - exactly one. +.. rubric:: NOTES: - The memory allocated for this scheduler depends on the - :ref:`CONFIGURE_MAXIMUM_PRIORITY` configuration option. +This scheduler configuration option is an advanced configuration option. +Think twice before you use it. + +In case no explicit :ref:`ConfigurationSchedulersClustered` +is present, then it is used as the scheduler for exactly one processor. + +This scheduler algorithm is the default when +:ref:`CONFIGURE_MAXIMUM_PROCESSORS` is +exactly one. + +The memory allocated for this scheduler depends on the +:ref:`CONFIGURE_MAXIMUM_PRIORITY` configuration option. .. Generated from spec:/acfg/if/scheduler-priority-affinity-smp +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP .. _CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP: @@ -385,36 +476,45 @@ NOTES: CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP ----------------------------------------- -CONSTANT: - ``CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP`` +.. rubric:: CONSTANT: + +``CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DEFAULT CONFIGURATION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +If this configuration option is undefined, then the described feature is not +enabled. -DESCRIPTION: - In case this configuration option is defined, then - :ref:`SchedulerSMPPriorityAffinity` - algorithm is made available to the application. +.. rubric:: DESCRIPTION: -NOTES: - This scheduler configuration option is an advanced configuration option. - Think twice before you use it. +In case this configuration option is defined, then the +:ref:`SchedulerSMPPriorityAffinity` +algorithm is made available to the application. - This scheduler algorithm is only available when RTEMS is built with SMP - support enabled. +.. rubric:: NOTES: - In case no explicit :ref:`ConfigurationSchedulersClustered` - is present, then it is used as the scheduler for up to 32 processors. +This scheduler configuration option is an advanced configuration option. +Think twice before you use it. - The memory allocated for this scheduler depends on the - :ref:`CONFIGURE_MAXIMUM_PRIORITY` configuration option. +This scheduler algorithm is only available when RTEMS is built with SMP +support enabled. + +In case no explicit :ref:`ConfigurationSchedulersClustered` +is present, then it is used as the scheduler for up to 32 processors. + +The memory allocated for this scheduler depends on the +:ref:`CONFIGURE_MAXIMUM_PRIORITY` configuration option. .. Generated from spec:/acfg/if/scheduler-priority-smp +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_SCHEDULER_PRIORITY_SMP .. _CONFIGURE_SCHEDULER_PRIORITY_SMP: @@ -422,36 +522,45 @@ NOTES: CONFIGURE_SCHEDULER_PRIORITY_SMP -------------------------------- -CONSTANT: - ``CONFIGURE_SCHEDULER_PRIORITY_SMP`` +.. rubric:: CONSTANT: + +``CONFIGURE_SCHEDULER_PRIORITY_SMP`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DESCRIPTION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +In case this configuration option is defined, then the +:ref:`SchedulerSMPPriority` +algorithm is made available to the application. -DESCRIPTION: - In case this configuration option is defined, then - :ref:`SchedulerSMPPriority` - algorithm is made available to the application. +.. rubric:: NOTES: -NOTES: - This scheduler configuration option is an advanced configuration option. - Think twice before you use it. +This scheduler configuration option is an advanced configuration option. +Think twice before you use it. - This scheduler algorithm is only available when RTEMS is built with SMP - support enabled. +This scheduler algorithm is only available when RTEMS is built with SMP +support enabled. - In case no explicit :ref:`ConfigurationSchedulersClustered` - is present, then it is used as the scheduler for up to 32 processors. +In case no explicit :ref:`ConfigurationSchedulersClustered` +is present, then it is used as the scheduler for up to 32 processors. - The memory allocated for this scheduler depends on the - :ref:`CONFIGURE_MAXIMUM_PRIORITY` configuration option. +The memory allocated for this scheduler depends on the +:ref:`CONFIGURE_MAXIMUM_PRIORITY` configuration option. .. Generated from spec:/acfg/if/scheduler-simple +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_SCHEDULER_SIMPLE .. _CONFIGURE_SCHEDULER_SIMPLE: @@ -459,30 +568,39 @@ NOTES: CONFIGURE_SCHEDULER_SIMPLE -------------------------- -CONSTANT: - ``CONFIGURE_SCHEDULER_SIMPLE`` +.. rubric:: CONSTANT: + +``CONFIGURE_SCHEDULER_SIMPLE`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DEFAULT CONFIGURATION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +If this configuration option is undefined, then the described feature is not +enabled. -DESCRIPTION: - In case this configuration option is defined, then - :ref:`SchedulerPrioritySimple` - algorithm is made available to the application. +.. rubric:: DESCRIPTION: -NOTES: - This scheduler configuration option is an advanced configuration option. - Think twice before you use it. +In case this configuration option is defined, then the +:ref:`SchedulerPrioritySimple` +algorithm is made available to the application. - In case no explicit :ref:`ConfigurationSchedulersClustered` - is present, then it is used as the scheduler for exactly one processor. +.. rubric:: NOTES: + +This scheduler configuration option is an advanced configuration option. +Think twice before you use it. + +In case no explicit :ref:`ConfigurationSchedulersClustered` +is present, then it is used as the scheduler for exactly one processor. .. Generated from spec:/acfg/if/scheduler-simple-smp +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_SCHEDULER_SIMPLE_SMP .. _CONFIGURE_SCHEDULER_SIMPLE_SMP: @@ -490,34 +608,42 @@ NOTES: CONFIGURE_SCHEDULER_SIMPLE_SMP ------------------------------ -CONSTANT: - ``CONFIGURE_SCHEDULER_SIMPLE_SMP`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is a boolean feature define. +``CONFIGURE_SCHEDULER_SIMPLE_SMP`` -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: OPTION TYPE: -DESCRIPTION: - In case this configuration option is defined, then - :ref:`SchedulerSMPPrioritySimple` - algorithm is made available to the application. - application. +This configuration option is a boolean feature define. -NOTES: - This scheduler configuration option is an advanced configuration option. - Think twice before you use it. +.. rubric:: DEFAULT CONFIGURATION: - This scheduler algorithm is only available when RTEMS is built with SMP - support enabled. +If this configuration option is undefined, then the described feature is not +enabled. - In case no explicit :ref:`ConfigurationSchedulersClustered` - is present, then it is used as the scheduler for up to 32 processors. +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the +:ref:`SchedulerSMPPrioritySimple` +algorithm is made available to the application. + +.. rubric:: NOTES: + +This scheduler configuration option is an advanced configuration option. +Think twice before you use it. + +This scheduler algorithm is only available when RTEMS is built with SMP +support enabled. + +In case no explicit :ref:`ConfigurationSchedulersClustered` +is present, then it is used as the scheduler for up to 32 processors. .. Generated from spec:/acfg/if/scheduler-strong-apa +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_SCHEDULER_STRONG_APA .. _CONFIGURE_SCHEDULER_STRONG_APA: @@ -525,31 +651,115 @@ NOTES: CONFIGURE_SCHEDULER_STRONG_APA ------------------------------ -CONSTANT: - ``CONFIGURE_SCHEDULER_STRONG_APA`` +.. rubric:: CONSTANT: + +``CONFIGURE_SCHEDULER_STRONG_APA`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the Strong APA algorithm +is made available to the application. + +.. rubric:: NOTES: + +This scheduler configuration option is an advanced configuration option. +Think twice before you use it. + +This scheduler algorithm is only available when RTEMS is built with SMP +support enabled. -OPTION TYPE: - This configuration option is a boolean feature define. +This scheduler algorithm is not correctly implemented. Do not use it. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. Generated from spec:/acfg/if/scheduler-table-entries -DESCRIPTION: - In case this configuration option is defined, then Strong APA algorithm is - made available to the application. +.. raw:: latex -NOTES: - This scheduler configuration option is an advanced configuration option. - Think twice before you use it. + \clearpage - This scheduler algorithm is only available when RTEMS is built with SMP - support enabled. +.. index:: CONFIGURE_SCHEDULER_TABLE_ENTRIES - This scheduler algorithm is not correctly implemented. Do not use it. +.. _CONFIGURE_SCHEDULER_TABLE_ENTRIES: + +CONFIGURE_SCHEDULER_TABLE_ENTRIES +--------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_SCHEDULER_TABLE_ENTRIES`` + +.. rubric:: OPTION TYPE: + +This configuration option is an initializer define. + +.. rubric:: DEFAULT VALUE: + +The default value of this configuration option is the definition of exactly +one table entry for the configured scheduler. + +.. rubric:: DESCRIPTION: + +The value of this configuration option is used to initialize the table of +configured schedulers. + +.. rubric:: NOTES: + +Schedulers registered in the scheduler table by this configuration option are +available to the application. The scheduler table entry index defines the +index of the scheduler. + +This is an advanced configuration option, see +:ref:`ConfigurationSchedulersClustered`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be a list of the following + macros: + + * ``RTEMS_SCHEDULER_TABLE_CBS( name, obj_name )`` + + * ``RTEMS_SCHEDULER_TABLE_EDF( name, obj_name )`` + + * ``RTEMS_SCHEDULER_TABLE_EDF_SMP( name, obj_name )`` + + * ``RTEMS_SCHEDULER_TABLE_PRIORITY_AFFINITY_SMP( name, obj_name )`` + + * ``RTEMS_SCHEDULER_TABLE_PRIORITY( name, obj_name )`` + + * ``RTEMS_SCHEDULER_TABLE_PRIORITY_SMP( name, obj_name )`` + + * ``RTEMS_SCHEDULER_TABLE_SIMPLE( name, obj_name )`` + + * ``RTEMS_SCHEDULER_TABLE_SIMPLE_SMP( name, obj_name )`` + + * ``RTEMS_SCHEDULER_TABLE_STRONG_APA( name, obj_name )`` + + The ``name`` macro parameter shall be the name associated with the scheduler + data structures, see :ref:`ConfigurationSchedulersClustered`. + + The ``obj_name`` macro parameter shall be the scheduler object name. It is + recommended to define the scheduler object name through + :ref:`InterfaceRtemsBuildName`. + +* Where the system was build with SMP support enabled, the table shall have one + or more entries, otherwise it shall have exactly one entry. .. Generated from spec:/acfg/if/scheduler-user +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_SCHEDULER_USER .. _CONFIGURE_SCHEDULER_USER: @@ -557,42 +767,48 @@ NOTES: CONFIGURE_SCHEDULER_USER ------------------------ -CONSTANT: - ``CONFIGURE_SCHEDULER_USER`` +.. rubric:: CONSTANT: + +``CONFIGURE_SCHEDULER_USER`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DESCRIPTION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +In case this configuration option is defined, then the user shall provide a +scheduler algorithm to the application. -DESCRIPTION: - In case this configuration option is defined, then the user shall provide a - scheduler algorithm to the application. +.. rubric:: NOTES: -NOTES: - This scheduler configuration option is an advanced configuration option. - Think twice before you use it. +This scheduler configuration option is an advanced configuration option. +Think twice before you use it. - RTEMS allows the application to provide its own task/thread scheduling - algorithm. In order to do this, one shall define - ``CONFIGURE_SCHEDULER_USER`` to indicate the application provides its own - scheduling algorithm. If ``CONFIGURE_SCHEDULER_USER`` is defined then the - following additional macros shall be defined: +RTEMS allows the application to provide its own task/thread scheduling +algorithm. In order to do this, one shall define +``CONFIGURE_SCHEDULER_USER`` to indicate the application provides its own +scheduling algorithm. If ``CONFIGURE_SCHEDULER_USER`` is defined then the +following additional macros shall be defined: - * ``CONFIGURE_SCHEDULER`` shall be defined to a static definition of - the scheduler data structures of the user scheduler. +* ``CONFIGURE_SCHEDULER`` shall be defined to a static definition of + the scheduler data structures of the user scheduler. - * ``CONFIGURE_SCHEDULER_TABLE_ENTRIES`` shall be defined to a scheduler - table entry initializer for the user scheduler. +* ``CONFIGURE_SCHEDULER_TABLE_ENTRIES`` shall be defined to a scheduler + table entry initializer for the user scheduler. - * ``CONFIGURE_SCHEDULER_USER_PER_THREAD`` shall be defined to the type of - the per-thread information of the user scheduler. +* ``CONFIGURE_SCHEDULER_USER_PER_THREAD`` shall be defined to the type of + the per-thread information of the user scheduler. - At this time, the mechanics and requirements for writing a new scheduler - are evolving and not fully documented. It is recommended that you look at - the existing Deterministic Priority Scheduler in - ``cpukit/score/src/schedulerpriority*.c`` for guidance. For guidance on - the configuration macros, please examine ``cpukit/sapi/include/confdefs.h`` - for how these are defined for the Deterministic Priority Scheduler. +At this time, the mechanics and requirements for writing a new scheduler +are evolving and not fully documented. It is recommended that you look at +the existing Deterministic Priority Scheduler in +``cpukit/score/src/schedulerpriority*.c`` for guidance. For guidance on +the configuration macros, please examine +``cpukit/include/rtems/confdefs/scheduler.h`` for how these are defined for +the Deterministic Priority Scheduler. diff --git a/c-user/config/task-stack-alloc.rst b/c-user/config/task-stack-alloc.rst index cd174ed..c79833f 100644 --- a/c-user/config/task-stack-alloc.rst +++ b/c-user/config/task-stack-alloc.rst @@ -1,7 +1,7 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +.. Copyright (C) 2020, 2022 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2021 On-Line Applications Research Corporation (OAR) .. This file is part of the RTEMS quality process and was automatically .. generated. If you find something that needs to be fixed or @@ -31,6 +31,10 @@ overflows are detected in hardware. .. Generated from spec:/acfg/if/task-stack-allocator +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_TASK_STACK_ALLOCATOR .. index:: task stack allocator @@ -39,35 +43,45 @@ overflows are detected in hardware. CONFIGURE_TASK_STACK_ALLOCATOR ------------------------------ -CONSTANT: - ``CONFIGURE_TASK_STACK_ALLOCATOR`` +.. rubric:: CONSTANT: + +``CONFIGURE_TASK_STACK_ALLOCATOR`` + +.. rubric:: OPTION TYPE: + +This configuration option is an initializer define. -OPTION TYPE: - This configuration option is an initializer define. +.. rubric:: DEFAULT VALUE: -DEFAULT VALUE: - The default value is ``_Workspace_Allocate``, which indicates that task - stacks will be allocated from the RTEMS Workspace. +The default value is ``_Workspace_Allocate``, which indicates that task +stacks will be allocated from the RTEMS Workspace. -VALUE CONSTRAINTS: - The value of this configuration option shall be defined to a valid function - pointer of the type ``void *( *allocate )( size_t )``. +.. rubric:: DESCRIPTION: -DESCRIPTION: - The value of this configuration option initializes the stack allocator - allocate handler. +The value of this configuration option initializes the stack allocator +allocate handler. -NOTES: - A correctly configured system shall configure the following to be consistent: +.. rubric:: NOTES: - * :ref:`CONFIGURE_TASK_STACK_ALLOCATOR_INIT` +A correctly configured system shall configure the following to be consistent: - * ``CONFIGURE_TASK_STACK_ALLOCATOR`` +* :ref:`CONFIGURE_TASK_STACK_ALLOCATOR_INIT` - * :ref:`CONFIGURE_TASK_STACK_DEALLOCATOR` +* ``CONFIGURE_TASK_STACK_ALLOCATOR`` + +* :ref:`CONFIGURE_TASK_STACK_DEALLOCATOR` + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be defined to a valid function +pointer of the type ``void *( *allocate )( size_t )``. .. Generated from spec:/acfg/if/task-stack-no-workspace +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_TASK_STACK_ALLOCATOR_AVOIDS_WORK_SPACE .. _CONFIGURE_TASK_STACK_ALLOCATOR_AVOIDS_WORK_SPACE: @@ -75,26 +89,100 @@ NOTES: CONFIGURE_TASK_STACK_ALLOCATOR_AVOIDS_WORK_SPACE ------------------------------------------------ -CONSTANT: - ``CONFIGURE_TASK_STACK_ALLOCATOR_AVOIDS_WORK_SPACE`` +.. rubric:: CONSTANT: + +``CONFIGURE_TASK_STACK_ALLOCATOR_AVOIDS_WORK_SPACE`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the system is informed +that the task stack allocator does not use the RTEMS Workspace. + +.. rubric:: NOTES: + +This configuration option may be used if a custom task stack allocator is +configured, see :ref:`CONFIGURE_TASK_STACK_ALLOCATOR`. + +.. Generated from spec:/acfg/if/task-stack-allocator-for-idle + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE +.. index:: task stack allocator for IDLE tasks + +.. _CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE: + +CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE +--------------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an initializer define. + +.. rubric:: DEFAULT VALUE: + +By default, the IDLE task storage area will be allocated from the RTEMS +Workspace. + +.. rubric:: DESCRIPTION: + +The value of this configuration option is the address for the stack allocator +allocate handler used to allocate the task storage area of each +:term:`IDLE task`. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: NOTES: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +This configuration option is independent of the other thread stack allocator +configuration options. It is assumed that any memory allocated for the task +storage area of an :term:`IDLE task` will not be from the RTEMS +Workspace. -DESCRIPTION: - In case this configuration option is defined, then the system is informed - that the task stack allocator does not use the RTEMS Workspace. +The IDLE task stack allocator may increase the size of the allocated memory +area to account for the actually allocated memory area. -NOTES: - This configuration option may be used if a custom task stack allocator is - configured, see :ref:`CONFIGURE_TASK_STACK_ALLOCATOR`. +The + +* :ref:`CONFIGURE_IDLE_TASK_STORAGE_SIZE`, and + +* ``CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE`` + +configuration options are mutually exclusive. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be defined to a valid function + pointer of the type ``void *( *allocate )( uint32_t, size_t * )``. + +* The IDLE task stack allocator shall return a pointer to the allocated memory + area or terminate the system with a fatal error if the allocation request + cannot be satisfied. + +* The IDLE task stack allocator may increase the size of the allocated memory + area. .. Generated from spec:/acfg/if/task-stack-allocator-init +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_TASK_STACK_ALLOCATOR_INIT .. _CONFIGURE_TASK_STACK_ALLOCATOR_INIT: @@ -102,35 +190,45 @@ NOTES: CONFIGURE_TASK_STACK_ALLOCATOR_INIT ----------------------------------- -CONSTANT: - ``CONFIGURE_TASK_STACK_ALLOCATOR_INIT`` +.. rubric:: CONSTANT: + +``CONFIGURE_TASK_STACK_ALLOCATOR_INIT`` + +.. rubric:: OPTION TYPE: + +This configuration option is an initializer define. + +.. rubric:: DEFAULT VALUE: + +The default value is `NULL <https://en.cppreference.com/w/c/types/NULL>`_. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is an initializer define. +The value of this configuration option initializes the stack allocator +initialization handler. -DEFAULT VALUE: - The default value is `NULL <https://en.cppreference.com/w/c/types/NULL>`_. +.. rubric:: NOTES: -VALUE CONSTRAINTS: - The value of this configuration option shall be defined to a valid function - pointer of the type ``void ( *initialize )( size_t )`` or to - `NULL <https://en.cppreference.com/w/c/types/NULL>`_. +A correctly configured system shall configure the following to be consistent: -DESCRIPTION: - The value of this configuration option initializes the stack allocator - initialization handler. +* ``CONFIGURE_TASK_STACK_ALLOCATOR_INIT`` -NOTES: - A correctly configured system shall configure the following to be consistent: +* :ref:`CONFIGURE_TASK_STACK_ALLOCATOR` - * ``CONFIGURE_TASK_STACK_ALLOCATOR_INIT`` +* :ref:`CONFIGURE_TASK_STACK_DEALLOCATOR` - * :ref:`CONFIGURE_TASK_STACK_ALLOCATOR` +.. rubric:: CONSTRAINTS: - * :ref:`CONFIGURE_TASK_STACK_DEALLOCATOR` +The value of the configuration option shall be defined to a valid function +pointer of the type ``void ( *initialize )( size_t )`` or to `NULL +<https://en.cppreference.com/w/c/types/NULL>`_. .. Generated from spec:/acfg/if/task-stack-deallocator +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_TASK_STACK_DEALLOCATOR .. index:: task stack deallocator @@ -139,35 +237,45 @@ NOTES: CONFIGURE_TASK_STACK_DEALLOCATOR -------------------------------- -CONSTANT: - ``CONFIGURE_TASK_STACK_DEALLOCATOR`` +.. rubric:: CONSTANT: + +``CONFIGURE_TASK_STACK_DEALLOCATOR`` + +.. rubric:: OPTION TYPE: + +This configuration option is an initializer define. + +.. rubric:: DEFAULT VALUE: + +The default value is ``_Workspace_Free``, which indicates that task stacks +will be allocated from the RTEMS Workspace. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is an initializer define. +The value of this configuration option initializes the stack allocator +deallocate handler. -DEFAULT VALUE: - The default value is ``_Workspace_Free``, which indicates that task stacks - will be allocated from the RTEMS Workspace. +.. rubric:: NOTES: -VALUE CONSTRAINTS: - The value of this configuration option shall be defined to a valid function - pointer of the type ``void ( *deallocate )( void * )``. +A correctly configured system shall configure the following to be consistent: -DESCRIPTION: - The value of this configuration option initializes the stack allocator - deallocate handler. +* :ref:`CONFIGURE_TASK_STACK_ALLOCATOR_INIT` -NOTES: - A correctly configured system shall configure the following to be consistent: +* :ref:`CONFIGURE_TASK_STACK_ALLOCATOR` - * :ref:`CONFIGURE_TASK_STACK_ALLOCATOR_INIT` +* ``CONFIGURE_TASK_STACK_DEALLOCATOR`` - * :ref:`CONFIGURE_TASK_STACK_ALLOCATOR` +.. rubric:: CONSTRAINTS: - * ``CONFIGURE_TASK_STACK_DEALLOCATOR`` +The value of the configuration option shall be defined to a valid function +pointer of the type ``void ( *deallocate )( void * )``. .. Generated from spec:/acfg/if/task-stack-from-alloc +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_TASK_STACK_FROM_ALLOCATOR .. index:: task stack allocator @@ -176,26 +284,31 @@ NOTES: CONFIGURE_TASK_STACK_FROM_ALLOCATOR ----------------------------------- -CONSTANT: - ``CONFIGURE_TASK_STACK_FROM_ALLOCATOR`` +.. rubric:: CONSTANT: + +``CONFIGURE_TASK_STACK_FROM_ALLOCATOR`` + +.. rubric:: OPTION TYPE: + +This configuration option is an initializer define. + +.. rubric:: DEFAULT VALUE: + +The default value is a macro which supports the system heap allocator. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is an initializer define. +The value of this configuration option is used to calculate the task stack +space size. -DEFAULT VALUE: - The default value is a macro which supports the system heap allocator. +.. rubric:: NOTES: -VALUE CONSTRAINTS: - The value of this configuration option shall be defined to a macro which - accepts exactly one parameter and returns an unsigned integer. The - parameter will be an allocation size and the macro shall return this size - plus the overhead of the allocator to manage an allocation request for this - size. +This configuration option may be used if a custom task stack allocator is +configured, see :ref:`CONFIGURE_TASK_STACK_ALLOCATOR`. -DESCRIPTION: - The value of this configuration option is used to calculate the task stack - space size. +.. rubric:: CONSTRAINTS: -NOTES: - This configuration option may be used if a custom task stack allocator is - configured, see :ref:`CONFIGURE_TASK_STACK_ALLOCATOR`. +The value of the configuration option shall be defined to a macro which accepts +exactly one parameter and returns an unsigned integer. The parameter will be +an allocation size and the macro shall return this size plus the overhead of +the allocator to manage an allocation request for this size. diff --git a/c-user/constant_bandwidth_server.rst b/c-user/constant_bandwidth_server.rst index eddc89a..d610ad9 100644 --- a/c-user/constant_bandwidth_server.rst +++ b/c-user/constant_bandwidth_server.rst @@ -233,7 +233,7 @@ sequence, related constants, usage, and status codes. \clearpage .. index:: initialize the CBS library -.. index:: rtems_cbs_initialize +.. index:: rtems_cbs_initialize() .. _rtems_cbs_initialize: CBS_INITIALIZE - Initialize the CBS library @@ -271,7 +271,7 @@ NOTES: \clearpage .. index:: cleanup the CBS library -.. index:: rtems_cbs_cleanup +.. index:: rtems_cbs_cleanup() .. _rtems_cbs_cleanup: @@ -302,7 +302,7 @@ NOTES: \clearpage .. index:: create a new bandwidth server -.. index:: rtems_cbs_create_server +.. index:: rtems_cbs_create_server() .. _rtems_cbs_create_server: @@ -351,7 +351,7 @@ NOTES: \clearpage .. index:: attach a thread to server -.. index:: rtems_cbs_attach_thread +.. index:: rtems_cbs_attach_thread() .. _rtems_cbs_attach_thread: @@ -394,7 +394,7 @@ NOTES: \clearpage .. index:: detach a thread from server -.. index:: rtems_cbs_detach_thread +.. index:: rtems_cbs_detach_thread() .. _rtems_cbs_detach_thread: @@ -432,7 +432,7 @@ NOTES: \clearpage .. index:: destroy a bandwidth server -.. index:: rtems_cbs_destroy_server +.. index:: rtems_cbs_destroy_server() .. _rtems_cbs_destroy_server: @@ -470,7 +470,7 @@ NOTES: \clearpage .. index:: get an ID of a server -.. index:: rtems_cbs_get_server_id +.. index:: rtems_cbs_get_server_id() .. _rtems_cbs_get_server_id: @@ -502,7 +502,7 @@ DESCRIPTION: \clearpage .. index:: get scheduling parameters of a server -.. index:: rtems_cbs_get_parameters +.. index:: rtems_cbs_get_parameters() .. _rtems_cbs_get_parameters: @@ -540,7 +540,7 @@ NOTES: \clearpage .. index:: set scheduling parameters -.. index:: rtems_cbs_set_parameters +.. index:: rtems_cbs_set_parameters() .. _rtems_cbs_set_parameters: @@ -580,7 +580,7 @@ NOTES: \clearpage .. index:: get elapsed execution time -.. index:: rtems_cbs_get_execution_time +.. index:: rtems_cbs_get_execution_time() .. _rtems_cbs_get_execution_time: @@ -619,7 +619,7 @@ NOTES: \clearpage .. index:: get remaining execution time -.. index:: rtems_cbs_get_remaining_budget +.. index:: rtems_cbs_get_remaining_budget() .. _rtems_cbs_get_remaining_budget: @@ -658,7 +658,7 @@ NOTES: \clearpage .. index:: get scheduler approved execution time -.. index:: rtems_cbs_get_approved_budget +.. index:: rtems_cbs_get_approved_budget() .. _rtems_cbs_get_approved_budget: diff --git a/c-user/cpu_usage_statistics.rst b/c-user/cpu_usage_statistics.rst index 46d130c..4f98b75 100644 --- a/c-user/cpu_usage_statistics.rst +++ b/c-user/cpu_usage_statistics.rst @@ -108,7 +108,7 @@ calling sequence, related constants, usage, and status codes. \clearpage -.. index:: rtems_cpu_usage_report +.. index:: rtems_cpu_usage_report() .. _rtems_cpu_usage_report: @@ -134,7 +134,7 @@ NOTES: \clearpage -.. index:: rtems_cpu_usage_reset +.. index:: rtems_cpu_usage_reset() .. _rtems_cpu_usage_reset: diff --git a/c-user/directive_status_codes.rst b/c-user/directive_status_codes.rst index 1331076..0421af7 100644 --- a/c-user/directive_status_codes.rst +++ b/c-user/directive_status_codes.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2015 embedded brains GmbH +.. Copyright (C) 2015 embedded brains GmbH & Co. KG .. index:: Status Codes @@ -87,7 +87,7 @@ The directives are: \clearpage -.. index:: rtems_status_text +.. index:: rtems_status_text() .. _rtems_status_text: diff --git a/c-user/dual-ported-memory/directives.rst b/c-user/dual-ported-memory/directives.rst index fb21a4f..b96e3c7 100644 --- a/c-user/dual-ported-memory/directives.rst +++ b/c-user/dual-ported-memory/directives.rst @@ -1,229 +1,403 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. _DualPortedMemoryManagerDirectives: + Directives ========== -This section details the 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. +This section details the directives of the Dual-Ported Memory Manager. A +subsection is dedicated to each of this manager's directives and lists the +calling sequence, parameters, description, return values, and notes of the +directive. + +.. Generated from spec:/rtems/dpmem/if/create .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_port_create() .. index:: create a port -.. index:: rtems_port_create - -.. _rtems_port_create: - -PORT_CREATE - Create a port ---------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_port_create( - rtems_name name, - void *internal_start, - void *external_start, - uint32_t length, - rtems_id *id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - port created successfully - * - ``RTEMS_INVALID_NAME`` - - invalid port name - * - ``RTEMS_INVALID_ADDRESS`` - - address not on four byte boundary - * - ``RTEMS_INVALID_ADDRESS`` - - ``id`` is NULL - * - ``RTEMS_TOO_MANY`` - - too many DP memory areas created - -DESCRIPTION: - This directive creates a port which resides on the local node for the - specified DPMA. The assigned port id is returned in id. This port id is - used as an argument to other dual-ported memory manager directives to - convert addresses within this DPMA. - - For control and maintenance of the port, RTEMS allocates and initializes an - DPCB from the DPCB free pool. Thus memory from the dual-ported memory area - is not used to store the DPCB. - -NOTES: - This directive may cause the calling task to be preempted due to an - obtain and release of the object allocator mutex. - - The internal_address and external_address parameters must be on a four byte - boundary. + +.. _InterfaceRtemsPortCreate: + +rtems_port_create() +------------------- + +Creates a port. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_port_create( + rtems_name name, + void *internal_start, + void *external_start, + uint32_t length, + rtems_id *id + ); + +.. rubric:: PARAMETERS: + +``name`` + This parameter is the object name of the port. + +``internal_start`` + This parameter is the internal start address of the memory area. + +``external_start`` + This parameter is the external start address of the memory area. + +``length`` + This parameter is the length in bytes of the memory area. + +``id`` + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the identifier of the created port will + be stored in this object. + +.. rubric:: DESCRIPTION: + +This directive creates a port which resides on the local node. The port has +the user-defined object name specified in ``name``. The assigned object +identifier is returned in ``id``. This identifier is used to access the port +with other dual-ported memory port related directives. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_NAME` + The ``name`` parameter was invalid. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``id`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``internal_start`` parameter was not properly aligned. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``external_start`` parameter was not properly aligned. + +:c:macro:`RTEMS_TOO_MANY` + There was no inactive object available to create a port. The number of + port available to the application is configured through the + :ref:`CONFIGURE_MAXIMUM_PORTS` application configuration option. + +.. rubric:: NOTES: + +The ``internal_start`` and ``external_start`` parameters must be on a boundary +defined by the target processor architecture. + +For control and maintenance of the port, RTEMS allocates a :term:`DPCB` from +the local DPCB free pool and initializes it. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. + +* The number of ports available to the application is configured through the + :ref:`CONFIGURE_MAXIMUM_PORTS` application configuration option. + +* Where the object class corresponding to the directive is configured to use + unlimited objects, the directive may allocate memory from the RTEMS + Workspace. + +.. Generated from spec:/rtems/dpmem/if/ident .. raw:: latex - \clearpage + \clearpage + +.. index:: rtems_port_ident() + +.. _InterfaceRtemsPortIdent: + +rtems_port_ident() +------------------ + +Identifies a port by the object name. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_port_ident( rtems_name name, rtems_id *id ); + +.. rubric:: PARAMETERS: + +``name`` + This parameter is the object name to look up. + +``id`` + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the object identifier of an object with + the specified name will be stored in this object. + +.. rubric:: DESCRIPTION: + +This directive obtains a port identifier associated with the port name +specified in ``name``. -.. index:: get ID of a port -.. index:: obtain ID of a port -.. index:: rtems_port_ident +.. rubric:: RETURN VALUES: -.. _rtems_port_ident: +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. -PORT_IDENT - Get ID of a port ------------------------------ +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``id`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. -CALLING SEQUENCE: - .. code-block:: c +:c:macro:`RTEMS_INVALID_NAME` + The ``name`` parameter was 0. - rtems_status_code rtems_port_ident( - rtems_name name, - rtems_id *id - ); +:c:macro:`RTEMS_INVALID_NAME` + There was no object with the specified name on the local node. -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +.. rubric:: NOTES: - * - ``RTEMS_SUCCESSFUL`` - - port identified successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``id`` is NULL - * - ``RTEMS_INVALID_NAME`` - - port name not found +If the port name is not unique, then the port identifier will match the first +port with that name in the search order. However, this port identifier is not +guaranteed to correspond to the desired port. -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. +The objects are searched from lowest to the highest index. Only the local node +is searched. -NOTES: - This directive will not cause the running task to be preempted. +The port identifier is used with other dual-ported memory related directives to +access the port. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/dpmem/if/delete .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_port_delete() .. index:: delete a port -.. index:: rtems_port_delete -.. _rtems_port_delete: +.. _InterfaceRtemsPortDelete: + +rtems_port_delete() +------------------- + +Deletes the port. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_port_delete( rtems_id id ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the port identifier. -PORT_DELETE - Delete a port ---------------------------- +.. rubric:: DESCRIPTION: -CALLING SEQUENCE: - .. code-block:: c +This directive deletes the port specified by ``id``. - rtems_status_code rtems_port_delete( - rtems_id id - ); +.. rubric:: RETURN VALUES: -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. - * - ``RTEMS_SUCCESSFUL`` - - port deleted successfully - * - ``RTEMS_INVALID_ID`` - - invalid port id +:c:macro:`RTEMS_INVALID_ID` + There was no port associated with the identifier specified by ``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. +.. rubric:: NOTES: -NOTES: - This directive may cause the calling task to be preempted due to an - obtain and release of the object allocator mutex. +The :term:`DPCB` for the deleted port 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. +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. + +* The calling task does not have to be the task that created the object. Any + local task that knows the object identifier can delete the object. + +* Where the object class corresponding to the directive is configured to use + unlimited objects, the directive may free memory to the RTEMS Workspace. + +.. Generated from spec:/rtems/dpmem/if/external-to-internal .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_port_external_to_internal() .. index:: convert external to internal address -.. index:: rtems_port_external_to_internal -.. _rtems_port_external_to_internal: +.. _InterfaceRtemsPortExternalToInternal: + +rtems_port_external_to_internal() +--------------------------------- + +Converts the external address to the internal address. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c -PORT_EXTERNAL_TO_INTERNAL - Convert external to internal address ----------------------------------------------------------------- + rtems_status_code rtems_port_external_to_internal( + rtems_id id, + void *external, + void **internal + ); -CALLING SEQUENCE: - .. code-block:: c +.. rubric:: PARAMETERS: - rtems_status_code rtems_port_external_to_internal( - rtems_id id, - void *external, - void **internal - ); +``id`` + This parameter is the port identifier. -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +``external`` + This parameter is the external address to convert. - * - ``RTEMS_INVALID_ADDRESS`` - - ``internal`` is NULL - * - ``RTEMS_SUCCESSFUL`` - - successful conversion +``internal`` + This parameter is the pointer to a ``void`` pointer object. When the + directive call is successful, the external address associated with the + internal address will be stored in this object. -DESCRIPTION: - This directive converts a dual-ported memory address from external to - internal representation for the specified port. If the given external - address is invalid for the specified port, then the internal address is set - to the given external address. +.. rubric:: 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. +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_NAME` + The ``id`` parameter was invalid. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``internal`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/dpmem/if/internal-to-external .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_port_internal_to_external() .. index:: convert internal to external address -.. index:: rtems_port_internal_to_external -.. _rtems_port_internal_to_external: +.. _InterfaceRtemsPortInternalToExternal: + +rtems_port_internal_to_external() +--------------------------------- + +Converts the internal address to the external address. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_port_internal_to_external( + rtems_id id, + void *internal, + void **external + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the port identifier. + +``internal`` + This parameter is the internal address to convert. + +``external`` + This parameter is the pointer to a ``void`` pointer object. When the + directive call is successful, the external address associated with the + internal address will be stored in this object. + +.. rubric:: DESCRIPTION: + +This directive converts a dual-ported memory address from internal to external +representation so that it can be passed to owner of the DPMA represented by the +specified port. If the given internal address is an invalid dual-ported +address, then the external address is set to the given internal address. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. -PORT_INTERNAL_TO_EXTERNAL - Convert internal to external address ----------------------------------------------------------------- +:c:macro:`RTEMS_INVALID_NAME` + The ``id`` parameter was invalid. -CALLING SEQUENCE: - .. code-block:: c +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``external`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. - rtems_status_code rtems_port_internal_to_external( - rtems_id id, - void *internal, - void **external - ); +.. rubric:: CONSTRAINTS: -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +The following constraints apply to this directive: - * - ``RTEMS_INVALID_ADDRESS`` - - ``external`` is NULL - * - ``RTEMS_SUCCESSFUL`` - - successful conversion +* The directive may be called from within interrupt context. -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. +* The directive may be called from within device driver initialization context. -NOTES: - This directive is callable from an ISR. +* The directive may be called from within task context. - This directive will not cause the calling task to be preempted. +* The directive will not cause the calling task to be preempted. diff --git a/c-user/dual-ported-memory/index.rst b/c-user/dual-ported-memory/index.rst index cc114ac..98dd9fe 100644 --- a/c-user/dual-ported-memory/index.rst +++ b/c-user/dual-ported-memory/index.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020 embedded brains GmbH & Co. KG .. index:: ports .. index:: dual ported memory diff --git a/c-user/dual-ported-memory/introduction.rst b/c-user/dual-ported-memory/introduction.rst index 752a162..515a1f1 100644 --- a/c-user/dual-ported-memory/introduction.rst +++ b/c-user/dual-ported-memory/introduction.rst @@ -1,20 +1,49 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/rtems/dpmem/if/group + +.. _DualPortedMemoryManagerIntroduction: + Introduction ============ -The dual-ported memory manager provides a mechanism for converting addresses +.. The following list was generated from: +.. spec:/rtems/dpmem/if/create +.. spec:/rtems/dpmem/if/ident +.. spec:/rtems/dpmem/if/delete +.. spec:/rtems/dpmem/if/external-to-internal +.. spec:/rtems/dpmem/if/internal-to-external + +The Dual-Ported Memory Manager provides a mechanism for converting addresses between internal and external representations for multiple dual-ported memory -areas (DPMA). The directives provided by the dual-ported memory manager are: +areas (DPMA). The directives provided by the Dual-Ported Memory Manager are: -- :ref:`rtems_port_create` +* :ref:`InterfaceRtemsPortCreate` - Creates a port. -- :ref:`rtems_port_ident` +* :ref:`InterfaceRtemsPortIdent` - Identifies a port by the object name. -- :ref:`rtems_port_delete` +* :ref:`InterfaceRtemsPortDelete` - Deletes the port. -- :ref:`rtems_port_external_to_internal` +* :ref:`InterfaceRtemsPortExternalToInternal` - Converts the external address + to the internal address. -- :ref:`rtems_port_internal_to_external` +* :ref:`InterfaceRtemsPortInternalToExternal` - Converts the internal address + to the external address. diff --git a/c-user/event/directives.rst b/c-user/event/directives.rst index 9d9bfe4..04a2894 100644 --- a/c-user/event/directives.rst +++ b/c-user/event/directives.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) .. This file is part of the RTEMS quality process and was automatically @@ -115,7 +115,8 @@ The following constraints apply to this directive: * The directive may be called from within task context. -* The directive may unblock another task which may preempt the calling task. +* The directive may unblock a task. This may cause the calling task to be + preempted. .. Generated from spec:/rtems/event/if/receive diff --git a/c-user/event/index.rst b/c-user/event/index.rst index 17ccfbc..dd926e1 100644 --- a/c-user/event/index.rst +++ b/c-user/event/index.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020 embedded brains GmbH & Co. KG .. index:: events diff --git a/c-user/event/introduction.rst b/c-user/event/introduction.rst index 2876b2c..ebdec2d 100644 --- a/c-user/event/introduction.rst +++ b/c-user/event/introduction.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) .. This file is part of the RTEMS quality process and was automatically diff --git a/c-user/fatal_error.rst b/c-user/fatal-error/background.rst index 81cfa0c..e3d7320 100644 --- a/c-user/fatal_error.rst +++ b/c-user/fatal-error/background.rst @@ -2,35 +2,6 @@ .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) -.. index:: fatal errors - -.. _fatal_error_manager: - -Fatal Error Manager -******************* - -Introduction -============ - -The fatal error manager processes all fatal or irrecoverable errors and other -sources of system termination (for example after :c:func:`exit()`). Fatal -errors are identified by the (fatal source, error code) pair. The directives -provided by the fatal error manager are: - -- rtems_fatal_ - Invoke the fatal error handler - -- rtems_panic_ - Print a message and invoke the fatal error handler - -- rtems_shutdown_executive_ - Shutdown RTEMS - -- rtems_exception_frame_print_ - Print the CPU exception frame - -- rtems_fatal_source_text_ - Return the fatal source text - -- rtems_internal_error_text_ - Return the error code text - -- rtems_fatal_error_occurred_ - Invoke the fatal error handler (deprecated) - Background ========== @@ -73,6 +44,8 @@ a register), and halt the processor. The precise actions of the RTEMS fatal error are discussed in the Default Fatal Error Processing chapter of the Applications Supplement document for a specific target processor. +.. _FatalErrorSources: + Fatal Sources ------------- @@ -343,13 +316,13 @@ INTERNAL_ERROR_BAD_THREAD_DISPATCH_ENVIRONMENT (31) } INTERNAL_ERROR_RTEMS_INIT_TASK_CREATE_FAILED (32) - Creation of an RTEMS initialization task failed. This fatal error may + The creation of the RTEMS initialization task failed. This fatal error may occur during system initialization. It is an application configuration error. INTERNAL_ERROR_POSIX_INIT_THREAD_CREATE_FAILED (33) - Creation of a POSIX initialization thread failed. This fatal error may - occur during system initialization. It is an application configuration + The creation of the POSIX initialization thread failed. This fatal error + may occur during system initialization. It is an application configuration error. INTERNAL_ERROR_LIBIO_STDOUT_FD_OPEN_FAILED (36) @@ -384,273 +357,24 @@ INTERNAL_ERROR_TOO_LARGE_TLS_SIZE (41) You can get the thread-local storage size of an application using the RTEMS tool ``rtems-execinfo``. -Operations -========== - -.. index:: _Terminate - -.. _Terminate: - -Announcing a Fatal Error ------------------------- - -The :c:func:`_Terminate()` internal error handler is invoked when the -application or the executive itself determines that a fatal error has occurred -or a final system state is reached (for example after :c:func:`rtems_fatal()` -or :c:func:`exit()`). - -The first action of the internal error handler is to call the fatal extension of -the user extensions. For the initial extensions the following conditions are -required - -- a valid stack pointer and enough stack space, - -- a valid code memory, and - -- valid read-only data. - -For the initial extensions the read-write data (including .bss segment) is not -required on single processor configurations. In SMP configurations, however, -the read-write data must be initialized since this function must determine the -state of the other processors and request them to shut-down if necessary. - -Non-initial extensions require in addition valid read-write data. The board -support package (BSP) may install an initial extension that performs a system -reset. In this case the non-initial extensions will be not called. - -The fatal extensions are called with three parameters: - -- the fatal source, - -- a legacy parameter which is always false, and - -- an error code with a fatal source dependent content. - -Once all fatal extensions executed, the error information will be stored to -:c:data:`_Internal_errors_What_happened` and the system state is set to -:c:macro:`SYSTEM_STATE_TERMINATED`. - -The final step is to call the CPU port specific :c:func:`_CPU_Fatal_halt()`. - -Directives -========== - -This section details the fatal error manager's directives. A subsection is -dedicated to each of this manager's directives and describes the calling -sequence, related constants, usage, and status codes. - -.. raw:: latex - - \clearpage - -.. index:: announce fatal error -.. index:: fatal error, announce -.. index:: rtems_fatal - -.. _rtems_fatal: - -FATAL - Invoke the fatal error handler --------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - void rtems_fatal( - rtems_fatal_source fatal_source, - rtems_fatal_code error_code - ) RTEMS_NO_RETURN; - -DIRECTIVE STATUS CODES: - NONE - This function will not return to the caller. - -DESCRIPTION: - This directive terminates the system. - -NOTE: - Registered :c:func:`atexit()` or :c:func:`on_exit()` handlers are not - called. Use :c:func:`exit()` in case these handlers should be invoked. - -.. raw:: latex - - \clearpage - -.. index:: panic -.. index:: rtems_panic - -.. _rtems_panic: - -PANIC - Print a message and invoke the fatal error handler ----------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - void rtems_panic( - const char *fmt, - ... - ) RTEMS_NO_RETURN RTEMS_PRINTFLIKE( 1, 2 ); - -DIRECTIVE STATUS CODES: - NONE - This function will not return to the caller. - -DESCRIPTION: - This directive prints a message via :c:func:`printk` specified by the - format and optional parameters and then terminates the system with the - :c:macro:`RTEMS_FATAL_SOURCE_PANIC` fatal source. The fatal code is set to - the format string address. - -NOTE: - Registered :c:func:`atexit()` or :c:func:`on_exit()` handlers are not - called. Use :c:func:`exit()` in case these handlers should be invoked. - -.. raw:: latex - - \clearpage - -.. index:: shutdown RTEMS -.. index:: rtems_shutdown_executive - -.. _rtems_shutdown_executive: - -SHUTDOWN_EXECUTIVE - Shutdown RTEMS ------------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - void rtems_shutdown_executive( - uint32_t result - ); - -DIRECTIVE STATUS CODES: - NONE - This function will not return to the caller. - -DESCRIPTION: - This directive is called when the application wishes to shutdown RTEMS. - The system is terminated with a fatal source of ``RTEMS_FATAL_SOURCE_EXIT`` - and the specified ``result`` code. - -NOTES: - This directive *must* be the last RTEMS directive invoked by an application - and it *does not return* to the caller. - - This directive may be called any time. - -.. raw:: latex - - \clearpage - -.. index:: exception frame -.. index:: rtems_exception_frame_print - -.. _rtems_exception_frame_print: - -EXCEPTION_FRAME_PRINT - Prints the exception frame --------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - void rtems_exception_frame_print( - const rtems_exception_frame *frame - ); - -DIRECTIVE STATUS CODES: - NONE - -DESCRIPTION: - Prints the exception frame via ``printk()``. - -.. raw:: latex - - \clearpage - -.. index:: fatal error -.. index:: rtems_fatal_source_text - -.. _rtems_fatal_source_text: - -FATAL_SOURCE_TEXT - Returns a text for a fatal source ------------------------------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - const char *rtems_fatal_source_text( - rtems_fatal_source source - ); - -DIRECTIVE STATUS CODES: - The fatal source text or "?" in case the passed fatal source is invalid. - -DESCRIPTION: - Returns a text for a fatal source. The text for fatal source is the - enumerator constant. - -.. raw:: latex - - \clearpage - -.. index:: fatal error -.. index:: rtems_internal_error_text - -.. _rtems_internal_error_text: - -INTERNAL_ERROR_TEXT - Returns a text for an internal error code ---------------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - const char *rtems_internal_error_text( - rtems_fatal_code error - ); - -DIRECTIVE STATUS CODES: - The error code text or "?" in case the passed error code is invalid. - -DESCRIPTION: - Returns a text for an internal error code. The text for each internal - error code is the enumerator constant. - -.. raw:: latex - - \clearpage - -.. index:: announce fatal error -.. index:: fatal error, announce -.. index:: rtems_fatal_error_occurred - -.. _rtems_fatal_error_occurred: - -FATAL_ERROR_OCCURRED - Invoke the fatal error handler (deprecated) ------------------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - void rtems_fatal_error_occurred( - uint32_t the_error - ) RTEMS_NO_RETURN; - -DIRECTIVE STATUS CODES: - NONE - This function will not return to the caller. - -DESCRIPTION: - This directive processes fatal errors. If the FATAL error extension is - defined in the configuration table, then the user-defined error extension - is called. If configured and the provided FATAL error extension returns, - then the RTEMS default error handler is invoked. This directive can be - invoked by RTEMS or by the user's application code including initialization - tasks, other tasks, and ISRs. - -NOTES: - This directive is deprecated and should not be used in new code. - - This directive supports local operations only. - - Unless the user-defined error extension takes special actions such as - restarting the calling task, this directive WILL NOT RETURN to the caller. +INTERNAL_ERROR_RTEMS_INIT_TASK_CONSTRUCT_FAILED (42) + The construction of the RTEMS initialization task failed. This fatal error + may occur during system initialization. It is an application configuration + error. - The user-defined extension for this directive may wish to initiate a global - shutdown. +INTERNAL_ERROR_IDLE_THREAD_CREATE_FAILED (43) + The creation of an IDLE task failed. This fatal error may occur during + system initialization. It happens if a task create extension fails for an + IDLE task. + +INTERNAL_ERROR_NO_MEMORY_FOR_IDLE_TASK_STORAGE (44) + There was not enough memory available to allocate an IDLE task stack. This + fatal error may occur during system initialization. It is an application + configuration error. + +INTERNAL_ERROR_IDLE_THREAD_STACK_TOO_SMALL (45) + The task stack size of an IDLE task would have been less than the + configured stack size for IDLE tasks, see + :ref:`CONFIGURE_IDLE_TASK_STACK_SIZE <CONFIGURE_IDLE_TASK_STACK_SIZE>`. + This fatal error may occur during system initialization. It is an + application configuration error. diff --git a/c-user/fatal-error/directives.rst b/c-user/fatal-error/directives.rst new file mode 100644 index 0000000..434172f --- /dev/null +++ b/c-user/fatal-error/directives.rst @@ -0,0 +1,355 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2015, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. _FatalErrorManagerDirectives: + +Directives +========== + +This section details the directives of the Fatal Error Manager. A subsection is +dedicated to each of this manager's directives and lists the calling sequence, +parameters, description, return values, and notes of the directive. + +.. Generated from spec:/rtems/fatal/if/fatal + +.. raw:: latex + + \clearpage + +.. index:: rtems_fatal() +.. index:: announce fatal error +.. index:: fatal error, announce + +.. _InterfaceRtemsFatal: + +rtems_fatal() +------------- + +Invokes the fatal error handler. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_fatal( + rtems_fatal_source fatal_source, + rtems_fatal_code fatal_code + ); + +.. rubric:: PARAMETERS: + +``fatal_source`` + This parameter is the fatal source. + +``fatal_code`` + This parameter is the fatal code. + +.. rubric:: DESCRIPTION: + +This directive processes fatal errors. The fatal source is set to the value of +the ``fatal_source`` parameter. The fatal code is set to the value of the +``fatal_code`` parameter. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not return to the caller. + +* The directive invokes the fatal error extensions in :term:`extension forward + order`. + +* The directive does not invoke handlers registered by :c:func:`atexit` or + :c:func:`on_exit`. + +* The directive may terminate the system. + +.. Generated from spec:/rtems/fatal/if/panic + +.. raw:: latex + + \clearpage + +.. index:: rtems_panic() +.. index:: panic + +.. _InterfaceRtemsPanic: + +rtems_panic() +------------- + +Prints the message and invokes the fatal error handler. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_panic( const char *fmt, ... ); + +.. rubric:: PARAMETERS: + +``fmt`` + This parameter is the message format. + +``...`` + This parameter is a list of optional parameters required by the message + format. + +.. rubric:: DESCRIPTION: + +This directive prints a message via :ref:`InterfacePrintk` specified by the +``fmt`` parameter and optional parameters and then invokes the fatal error +handler. The fatal source is set to :c:macro:`RTEMS_FATAL_SOURCE_PANIC`. The +fatal code is set to the value of the ``fmt`` parameter value. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not return to the caller. + +* The directive invokes the fatal error extensions in :term:`extension forward + order`. + +* The directive does not invoke handlers registered by :c:func:`atexit` or + :c:func:`on_exit`. + +* The directive may terminate the system. + +.. Generated from spec:/rtems/fatal/if/shutdown-executive + +.. raw:: latex + + \clearpage + +.. index:: rtems_shutdown_executive() +.. index:: shutdown RTEMS + +.. _InterfaceRtemsShutdownExecutive: + +rtems_shutdown_executive() +-------------------------- + +Invokes the fatal error handler. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_shutdown_executive( uint32_t fatal_code ); + +.. rubric:: PARAMETERS: + +``fatal_code`` + This parameter is the fatal code. + +.. rubric:: DESCRIPTION: + +This directive processes fatal errors. The fatal source is set to +:c:macro:`RTEMS_FATAL_SOURCE_EXIT`. The fatal code is set to the value of the +``fatal_code`` parameter. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not return to the caller. + +* The directive invokes the fatal error extensions in :term:`extension forward + order`. + +* The directive does not invoke handlers registered by :c:func:`atexit` or + :c:func:`on_exit`. + +* The directive may terminate the system. + +.. Generated from spec:/rtems/fatal/if/exception-frame-print + +.. raw:: latex + + \clearpage + +.. index:: rtems_exception_frame_print() +.. index:: exception frame + +.. _InterfaceRtemsExceptionFramePrint: + +rtems_exception_frame_print() +----------------------------- + +Prints the exception frame. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_exception_frame_print( const rtems_exception_frame *frame ); + +.. rubric:: PARAMETERS: + +``frame`` + This parameter is the reference to the exception frame to print. + +.. rubric:: DESCRIPTION: + +The exception frame is printed in an architecture-dependent format using +:ref:`InterfacePrintk`. + +.. Generated from spec:/rtems/fatal/if/source-text + +.. raw:: latex + + \clearpage + +.. index:: rtems_fatal_source_text() +.. index:: fatal error + +.. _InterfaceRtemsFatalSourceText: + +rtems_fatal_source_text() +------------------------- + +Returns a descriptive text for the fatal source. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + const char *rtems_fatal_source_text( rtems_fatal_source fatal_source ); + +.. rubric:: PARAMETERS: + +``fatal_source`` + This parameter is the fatal source. + +.. rubric:: RETURN VALUES: + +"?" + The ``fatal_source`` parameter value was not a fatal source. + +Returns a descriptive text for the fatal source. The text for the fatal source +is the enumerator constant name. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +.. Generated from spec:/rtems/fatal/if/internal-error-text + +.. raw:: latex + + \clearpage + +.. index:: rtems_internal_error_text() +.. index:: fatal error + +.. _InterfaceRtemsInternalErrorText: + +rtems_internal_error_text() +--------------------------- + +Returns a descriptive text for the internal error code. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + const char *rtems_internal_error_text( rtems_fatal_code internal_error_code ); + +.. rubric:: PARAMETERS: + +``internal_error_code`` + This parameter is the internal error code. + +.. rubric:: RETURN VALUES: + +"?" + The ``internal_error_code`` parameter value was not an internal error code. + +Returns a descriptive text for the internal error code. The text for the +internal error code is the enumerator constant name. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +.. Generated from spec:/rtems/fatal/if/error-occurred + +.. raw:: latex + + \clearpage + +.. index:: rtems_fatal_error_occurred() + +.. _InterfaceRtemsFatalErrorOccurred: + +rtems_fatal_error_occurred() +---------------------------- + +Invokes the fatal error handler. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_fatal_error_occurred( uint32_t fatal_code ); + +.. rubric:: PARAMETERS: + +``fatal_code`` + This parameter is the fatal code. + +.. rubric:: DESCRIPTION: + +This directive processes fatal errors. The fatal source is set to +:c:macro:`INTERNAL_ERROR_RTEMS_API`. The fatal code is set to the value of the +``fatal_code`` parameter. + +.. rubric:: NOTES: + +This directive is deprecated and should not be used in new code. It is +recommended to not use this directive since error locations cannot be uniquely +identified. A recommended alternative directive is :ref:`InterfaceRtemsFatal`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not return to the caller. + +* The directive invokes the fatal error extensions in :term:`extension forward + order`. + +* The directive does not invoke handlers registered by :c:func:`atexit` or + :c:func:`on_exit`. + +* The directive may terminate the system. diff --git a/c-user/fatal-error/index.rst b/c-user/fatal-error/index.rst new file mode 100644 index 0000000..40eca3b --- /dev/null +++ b/c-user/fatal-error/index.rst @@ -0,0 +1,17 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2021 embedded brains GmbH & Co. KG + +.. index:: fatal errors + +.. _RTEMSAPIClassicFatal: + +Fatal Error Manager +******************* + +.. toctree:: + + introduction + background + operations + directives diff --git a/c-user/fatal-error/introduction.rst b/c-user/fatal-error/introduction.rst new file mode 100644 index 0000000..fc310f4 --- /dev/null +++ b/c-user/fatal-error/introduction.rst @@ -0,0 +1,57 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2015, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/rtems/fatal/if/group + +.. _FatalErrorManagerIntroduction: + +Introduction +============ + +.. The following list was generated from: +.. spec:/rtems/fatal/if/fatal +.. spec:/rtems/fatal/if/panic +.. spec:/rtems/fatal/if/shutdown-executive +.. spec:/rtems/fatal/if/exception-frame-print +.. spec:/rtems/fatal/if/source-text +.. spec:/rtems/fatal/if/internal-error-text +.. spec:/rtems/fatal/if/error-occurred + +The Fatal Error Manager processes all fatal or irrecoverable errors and other +sources of system termination (for example after :c:func:`exit`). Fatal errors +are identified by the fatal source and code pair. The directives provided by +the Fatal Error Manager are: + +* :ref:`InterfaceRtemsFatal` - Invokes the fatal error handler. + +* :ref:`InterfaceRtemsPanic` - Prints the message and invokes the fatal error + handler. + +* :ref:`InterfaceRtemsShutdownExecutive` - Invokes the fatal error handler. + +* :ref:`InterfaceRtemsExceptionFramePrint` - Prints the exception frame. + +* :ref:`InterfaceRtemsFatalSourceText` - Returns a descriptive text for the + fatal source. + +* :ref:`InterfaceRtemsInternalErrorText` - Returns a descriptive text for the + internal error code. + +* :ref:`InterfaceRtemsFatalErrorOccurred` - Invokes the fatal error handler. diff --git a/c-user/fatal-error/operations.rst b/c-user/fatal-error/operations.rst new file mode 100644 index 0000000..6d03a26 --- /dev/null +++ b/c-user/fatal-error/operations.rst @@ -0,0 +1,50 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Operations +========== + +.. index:: _Terminate + +.. _Terminate: + +Announcing a Fatal Error +------------------------ + +The :c:func:`_Terminate()` internal error handler is invoked when the +application or the executive itself determines that a fatal error has occurred +or a final system state is reached (for example after :c:func:`rtems_fatal()` +or :c:func:`exit()`). + +The first action of the internal error handler is to call the fatal extension of +the user extensions. For the initial extensions the following conditions are +required + +- a valid stack pointer and enough stack space, + +- a valid code memory, and + +- valid read-only data. + +For the initial extensions the read-write data (including .bss segment) is not +required on single processor configurations. In SMP configurations, however, +the read-write data must be initialized since this function must determine the +state of the other processors and request them to shut-down if necessary. + +Non-initial extensions require in addition valid read-write data. The board +support package (BSP) may install an initial extension that performs a system +reset. In this case the non-initial extensions will be not called. + +The fatal extensions are called with three parameters: + +- the fatal source, + +- a legacy parameter which is always set to :c:macro:`false`, and + +- an error code with a fatal source dependent content. + +Once all fatal extensions executed, the system state is set to +:c:macro:`SYSTEM_STATE_TERMINATED`. + +The final step is to call the CPU port specific :c:func:`_CPU_Fatal_halt()`. diff --git a/c-user/glossary.rst b/c-user/glossary.rst index 71a0242..2516e90 100644 --- a/c-user/glossary.rst +++ b/c-user/glossary.rst @@ -1,7 +1,8 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 +.. Copyright (C) 2022, 2023 Trinity College Dublin .. Copyright (C) 2020 Richi Dubey (richidubey@gmail.com) -.. Copyright (C) 2017, 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2015, 2023 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 1998 On-Line Applications Research Corporation (OAR) Glossary @@ -17,6 +18,9 @@ Glossary A term used to describe an object which has been created by an application. + AMP + This term is an acronym for Asymmetric Multiprocessing. + APA This term is an acronym for Arbitrary Processor Affinity. APA schedulers allow a thread to have an arbitrary affinity to a processor set, rather than @@ -101,9 +105,21 @@ Glossary C++11 The standard ISO/IEC 14882:2011. + C++14 + The standard ISO/IEC 14882:2014. + + C++17 + The standard ISO/IEC 14882:2017. + + C++20 + The standard ISO/IEC 14882:2020. + C11 The standard ISO/IEC 9899:2011. + C17 + The standard ISO/IEC 9899:2018. + calling convention The processor and compiler dependent rules which define the mechanism used to invoke subroutines in a high-level language. These rules define @@ -194,6 +210,14 @@ Glossary This term is an acronym for Cathode Ray Tube. Normally used in reference to the man-machine interface. + current priority + The current priority of a :term:`task` is the :term:`task priority` with + respect to the :term:`home scheduler` of the task. It is an aggregation of + the :term:`real priority` and temporary priority adjustments due to locking + protocols, the rate-monotonic period objects on some schedulers such as EDF, + and the :term:`POSIX` sporadic server. The current priority is an + :term:`eligible priority`. + deadline A fixed time limit by which a task must have completed a set of actions. Beyond this point, the results are of reduced value and may even be @@ -233,13 +257,28 @@ Glossary A term used to describe memory which can be accessed at two different addresses. + dynamic extension sets + The dynamic extension sets are a list of :term:`user extensions`. The list + is defined by the system services used by the application and directive calls + such as :ref:`InterfaceRtemsExtensionCreate`. See also + :term:`initial extension sets`. + EARS This term is an acronym for Easy Approach to Requirements Syntax. + EDF + This term is an acronym for Earliest Deadline First. + ELF This term is an acronym for `Executable and Linkable Format <https://en.wikipedia.org/wiki/Executable_and_Linkable_Format>`_. + eligible priority + An eligible priority of a :term:`task` is the :term:`task priority` with + respect to the corresponding :term:`eligible scheduler` of the task. An + eligible priority is either the :term:`current priority` or a + :term:`helping priority` of a task. + eligible scheduler An eligible scheduler of a :term:`task` is a :term:`scheduler` which can be used by the task to allocate a processor for the task. @@ -286,6 +325,26 @@ Glossary An object known by all nodes in a multiprocessor system. An object created with the GLOBAL attribute will be exported. + extension forward order + The :term:`user extensions` may be invoked in extension forward order. In + forward order, all user extensions of the :term:`initial extension sets` are + invoked before all user extensions of the :term:`dynamic extension sets`. + In the initial extension sets the order is defined by the table index. The + user extension with the lowest table index is invoked first. In the dynamic + extension sets the order is defined by the registration order. The first + registered user extension is invoked first. See also + :term:`extension reverse order`. + + extension reverse order + The :term:`user extensions` may be invoked in extension reverse order. In + reverse order, all user extensions of the :term:`dynamic extension sets` are + invoked before all user extensions of the :term:`initial extension sets`. + In the dynamic extension sets the order is defined by the registration order. + The last registered user extension is invoked first. In the initial + extension sets the order is defined by the table index. The user extension + with the highest table index is invoked first. See also + :term:`extension forward order`. + external address The address used to access dual-ported memory by all the nodes in a system which do not own the memory. @@ -294,16 +353,29 @@ Glossary This term is an acronym for :term:`First In First Out`. First In First Out - A discipline for manipulating entries in a data structure. + A discipline for manipulating entries in a data structure. See also + :term:`Last In First Out`. floating point coprocessor A component used in computer systems to enhance performance in mathematically intensive situations. It is typically viewed as a logical extension of the primary processor. + formal model + A model of a computing component (hardware or software) that has a + mathematically based :term:`semantics`. + freed A resource that has been released by the application to RTEMS. + Futex + This term is an abbreviation for + `Fast User-Space Locking <https://man7.org/linux/man-pages/man2/futex.2.html>`_. + The futex support in RTEMS is provided for the barriers of the + :term:`OpenMP` library provided by :term:`GCC`. It could be used to + implement high performance :term:`SMP` synchronization primitives which + offer random-fairness. + GCC This term is an acronym for `GNU Compiler Collection <https://gcc.gnu.org/>`_. @@ -311,6 +383,10 @@ Glossary An object that has been created with the GLOBAL attribute and exported to all nodes in a multiprocessor system. + global construction + In the global construction, the C++ global constructors and constructor + functions are invoked. See :ref:`GlobalConstruction`. + GNAT *GNAT* is the :term:`GNU` compiler for Ada, integrated into the :term:`GCC`. @@ -318,6 +394,30 @@ Glossary GNU This term is an acronym for `GNU's Not Unix <https://www.gnu.org/>`_. + GPL + This term is an acronym for + `GNU General Public License <https://www.gnu.org/licenses>`__. + + GPLv2 + This term is an acronym for + `GNU General Public License Version 2 <https://www.gnu.org/licenses/old-licenses/gpl-2.0.html>`__. + + GPLv3 + This term is an acronym for + `GNU General Public License Version 3 <https://www.gnu.org/licenses/gpl-3.0.html>`__. + + GR712RC + The + `GR712RC <https://www.gaisler.com/index.php/products/components/gr712rc>`_ + is a :term:`system-on-chip` containing two processors of the :term:`SPARC` + :term:`target architecture`. + + GR740 + The + `GR740 <https://www.gaisler.com/index.php/products/components/gr740>`_ + is a :term:`system-on-chip` containing four processors of the :term:`SPARC` + :term:`target architecture`. + handler The equivalent of a manager, except that it is internal to RTEMS and forms part of the core. A handler is a collection of routines which @@ -340,6 +440,11 @@ Glossary dispatch is marked as necessary, then the next thread dispatch will make the heir task the executing task. + helping priority + A helping priority of a :term:`task` is the :term:`task priority` with + respect to the corresponding :term:`helping scheduler` of the task. A + helping priority is an :term:`eligible priority`. + helping scheduler A helping scheduler of a :term:`task` is a :term:`scheduler` which is a :term:`eligible scheduler` and which is not the :term:`home scheduler` of @@ -348,11 +453,15 @@ Glossary heterogeneous A multiprocessor computer system composed of dissimilar processors. + higher priority + A :term:`task` ``H`` has a higher :term:`priority` than a task ``L``, if + task ``H`` is more important than task ``L``. + home scheduler - The home scheduler of a :term:`task` is a :term:`scheduler` which is a - :term:`eligible scheduler` and which is assigned to the task during the + The home scheduler of a :term:`task` is a :term:`scheduler` which is an + :term:`eligible scheduler` and which is assigned to the task during its initialization or explicitly via a directive call such as - :c:func:`rtems_task_set_scheduler`. + :ref:`InterfaceRtemsTaskSetScheduler`. homogeneous A multiprocessor computer system composed of a single type of processor. @@ -371,6 +480,13 @@ Glossary An ineligible scheduler of a :term:`task` is a :term:`scheduler` which is not an :term:`eligible scheduler`. + initial extension sets + The initial extension sets are a table of :term:`user extensions`. The table + is defined by the application configuration for example through the + :ref:`CONFIGURE_INITIAL_EXTENSIONS` application configuration option. The + initial extension sets cannot be altered during runtime through directive + calls. See also :term:`dynamic extension sets`. + interface A specification of the methodology used to connect multiple independent subsystems. @@ -408,6 +524,17 @@ Glossary kernel In this document, this term is used as a synonym for executive. + Last In First Out + A discipline for manipulating entries in a data structure. See also + :term:`First In First Out`. + + LIFO + This term is an acronym for :term:`Last In First Out`. + + Linear Temporal Logic + This is a logic that states properties about (possibly infinite) sequences of + states. + list A data structure which allows for dynamic addition and removal of entries. It is not statically limited to a particular size. @@ -417,6 +544,12 @@ Glossary are arranged such that the least significant byte is at the lowest address. + LLVM + This term is an acronym for + `Low Level Virtual Machine <https://www.llvm.org>`__. + The LLVM Project is a collection of modular and reusable compiler and + toolchain technologies. + local An object which was created with the LOCAL attribute and is accessible only on the node it was created and resides upon. In a single processor @@ -434,6 +567,13 @@ Glossary A multiprocessor configuration where shared memory is not used for communication. + lower priority + A :term:`task` ``L`` has a lower :term:`priority` than a task ``H``, if + task ``L`` is less important than task ``H``. + + LTL + This term is an acronym for :term:`Linear Temporal Logic`. + major number The index of a device driver in the Device Driver Table. @@ -475,6 +615,9 @@ Glossary This term is an acronym for :term:`Multiprocessor Communications Interface Layer`. + MrsP + This term is an acronym for Multiprocessor Resource-Sharing Protocol. + multiprocessing The simultaneous execution of two or more processes by a multiple processor computer system. @@ -522,6 +665,9 @@ Glossary mathematically intensive situations. It is typically viewed as a logical extension of the primary processor. + OBC + This term is an acronym for On-Board Computer. + object In this document, this term is used to refer collectively to tasks, timers, message queues, partitions, regions, semaphores, ports, and rate @@ -532,6 +678,16 @@ Glossary variety of entities. Object-oriented systems shield the application from implementation details. + OMIP + This term is an acronym for O(m) Independence-Preserving Protocol. OMIP is a + generalization of the :term:`priority inheritance` locking protocol to + clustered scheduling. The ``m`` denotes the number of processors in the + system. + + OpenMP + This term is an acronym for + `Open Multi-Processing <https://www.openmp.org/>`_. + operating system The software which controls all the computer's resources and provides the base upon which application programs can be written. @@ -599,15 +755,30 @@ Glossary another task. priority - A mechanism used to represent the relative importance of an element in a - set of items. RTEMS uses priority to determine which task should - execute. + The priority is a mechanism used to represent the relative importance of an + element in a set of items. + + For example, :term:`RTEMS` uses :term:`task priorities <task priority>` to determine which + :term:`task` should execute on a processor. In RTEMS, priorities are + represented by non-negative integers. + + For the Classic :term:`API`, if a numerical priority value ``A`` is greater + than a numerical priority value ``B``, then ``A`` expresses a + :term:`lower priority` than ``B``. If a numerical priority value ``C`` is + less than a numerical priority value ``D``, then ``C`` expresses a + :term:`higher priority` than ``D``. + + For the :term:`POSIX` API, if a numerical priority value ``R`` is less than + a numerical priority value ``S``, then ``R`` expresses a lower priority than + ``S``. If a numerical priority value ``T`` is greater than a numerical + priority value ``U``, then ``T`` expresses a higher priority than ``U``. priority boosting A simple approach to extend the priority inheritance protocol for clustered scheduling is priority boosting. In case a mutex is owned by a task of another cluster, then the priority of the owner task is raised to - an artificially high priority, the pseudo-interrupt priority. + an artificially high priority. This approach is not used in RTEMS, see also + :term:`OMIP`. priority inheritance An algorithm that calls for the lower priority task holding a resource to @@ -653,6 +824,14 @@ Glossary decided that other tasks are currently more important. A task that is ready to execute and has a processor assigned is called scheduled. + real priority + Each :term:`task` has exactly one real priority. The real priority is + always with respect to the :term:`home scheduler` of a task. It is defined + during task initialization. It may be changed by directives such as + :ref:`InterfaceRtemsTaskSetPriority` and + :ref:`InterfaceRtemsTaskSetScheduler`. The real priority is the foundation + of the :term:`current priority`. + real-time A term used to describe systems which are characterized by requiring deterministic response times to external stimuli. The external stimuli @@ -663,6 +842,10 @@ Glossary A term used to describe routines which do not modify themselves or global variables. + refinement + A *refinement* is a relationship between a specification and its + implementation as code. + region An RTEMS object which is used to allocate and deallocate variable size blocks of memory from a dynamically specified area of memory. @@ -675,6 +858,9 @@ Glossary Registers are locations physically located within a component, typically used for device control or general purpose storage. + reification + Another term used to denote :term:`refinement`. + remote Any object that does not reside on the local node. @@ -722,6 +908,12 @@ Glossary The state of a rate monotonic timer while it is being used to delineate a period. The timer exits this state by either expiring or being canceled. + scenario + In the context of formal verification, in a setting that involves many + concurrent tasks that interleave in arbitrary ways, a scenario describes a + single specific possible interleaving. One interpretation of the behaviour + of a concurrent system is the set of all its scenarios. + schedulable A set of tasks which can be guaranteed to meet their deadlines based upon a specific scheduling algorithm. @@ -758,6 +950,11 @@ Glossary segments Variable sized memory blocks allocated from a region. + semantics + This term refers to the meaning of text or utterances in some language. In a + software engineering context these will be programming, modelling or + specification languages. + semaphore An RTEMS object which is used to synchronize tasks and provide mutually exclusive access to resources. @@ -778,6 +975,10 @@ Glossary A thirty-two bit entity which is used to represent a task's collection of pending signals and the signals sent to a task. + SIS + This term is an acronym for Simple Instruction Simulator. The SIS is a + :term:`SPARC` V7/V8 and RISC-V RV32IMACFD :term:`target architecture` simulator. + SMCB This term is an acronym for :term:`Semaphore Control Block`. @@ -855,6 +1056,11 @@ Glossary software as it is originally written (i.e., typed into a computer) by a human in plain text (i.e., human readable alphanumeric characters)." + SPARC + This term is an acronym for + `Scalable Processor ARChitecture <https://en.wikipedia.org/wiki/SPARC>`_. + See also :term:`target architecture`. + sporadic task A task which executes at irregular intervals and must comply with a hard deadline. A minimum period of time between successive iterations of the @@ -892,9 +1098,23 @@ Glossary system call In this document, this is used as an alternate term for directive. + system-on-chip + This project uses the `system on a chip definition of Wikipedia + <https://en.wikipedia.org/wiki/System_on_a_chip>`_: "A system on a chip or + system-on-chip is an integrated circuit that integrates most or all + components of a computer or other electronic system." + + Systems on a chip are :term:`target` systems for applications using + :term:`RTEMS`. + target The system on which the application will ultimately execute. + target architecture + The target architecture is the instruction set architecture (ISA) of the + :term:`target`. Some RTEMS features depend on the target architecture. For + the details consult the *RTEMS CPU Architecture Supplement*. + TAS This term is an acronym for Test-And-Set. @@ -917,10 +1137,32 @@ Glossary A data structure associated with each task used by RTEMS to manage that task. + task entry + The task entry is invoked to execute the task's job. Before the task entry + is invoked, the thread begin :term:`user extensions` run in the context of + the task. After the return of the task entry, the thread exitted user + extensions run in the context of the task. The first user initialization + task performs the :term:`global construction` after running the thread begin + extensions and before the task entry is invoked. See also + :ref:`InterfaceRtemsTaskStart`. + task migration Task migration happens in case a task stops execution on one processor and resumes execution on another processor. + task priority + A task :term:`priority` of a :term:`task` determines its importance + relative to other tasks. + + The scheduler use task priorities to determine which :term:`ready task` gets + a processor allocated, see :term:`scheduled task`. The + :term:`eligible priorities <eligible priority>` of a task define the position of the task in a + :term:`wait queue` which uses the priority discipline. Each task has at + least the :term:`real priority`. + + Task priorities are used in :term:`wait queues <wait queue>` which use the priority + discipline to determine the dequeueing order of tasks. + task processor affinity The set of processors on which a task is allowed to execute. @@ -991,8 +1233,11 @@ Glossary A table which contains the entry points for each user extensions. user extensions - Software routines provided by the application to enhance the - functionality of RTEMS. + User extensions are software routines provided by the application to enhance + the functionality of RTEMS. An active user extension is either in the + :term:`initial extension sets` or the :term:`dynamic extension sets`. User + extensions are invoked in :term:`extension forward order` or + :term:`extension reverse order`. User Initialization Tasks Table A table which contains the information needed to create and start each of diff --git a/c-user/index.rst b/c-user/index.rst index 2f8109a..b4ad322 100644 --- a/c-user/index.rst +++ b/c-user/index.rst @@ -10,7 +10,7 @@ RTEMS Classic API Guide (|version|). | |copy| 2017 Chris Johns | |copy| 2017 Kuan-Hsun Chen - | |copy| 2015, 2020 embedded brains GmbH + | |copy| 2015, 2020 embedded brains GmbH & Co. KG | |copy| 2015, 2020 Sebastian Huber | |copy| 2011 Petr Benes | |copy| 2010 Gedare Bloom @@ -29,7 +29,7 @@ RTEMS Classic API Guide (|version|). key_concepts rtems_data_types scheduling-concepts/index - initialization + initialization/index task/index interrupt/index clock/index @@ -44,12 +44,15 @@ RTEMS Classic API Guide (|version|). region/index dual-ported-memory/index io/index - fatal_error + kernel-character-io/index + cache/index + fatal-error/index board_support_packages user-extensions/index config/index self_contained_objects - multiprocessing + regulator/index + multiprocessing/index symmetric_multiprocessing_services pci_library stack_bounds_checker diff --git a/c-user/initialization/background.rst b/c-user/initialization/background.rst new file mode 100644 index 0000000..36d8ebd --- /dev/null +++ b/c-user/initialization/background.rst @@ -0,0 +1,48 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Background +========== + +.. index:: initialization tasks + +Initialization Tasks +-------------------- + +Initialization task(s) are the mechanism by which RTEMS transfers initial +control to the user's application. Initialization tasks differ from other +application tasks in that they are defined in the User Initialization Tasks +Table and automatically created and started by RTEMS as part of its +initialization sequence. Since the initialization tasks are scheduled using +the same algorithm as all other RTEMS tasks, they must be configured at a +priority and mode which will ensure that they will complete execution before +other application tasks execute. Although there is no upper limit on the +number of initialization tasks, an application is required to define at least +one. + +A typical initialization task will create and start the static set of +application tasks. It may also create any other objects used by the +application. Initialization tasks which only perform initialization should +delete themselves upon completion to free resources for other tasks. +Initialization tasks may transform themselves into a "normal" application task. +This transformation typically involves changing priority and execution mode. +RTEMS does not automatically delete the initialization tasks. + +The Idle Task +------------- + +The Idle Task is the lowest priority task in a system and executes only when no +other task is ready to execute. The default implementation of this task +consists of an infinite loop. RTEMS allows the Idle Task body to be replaced by +a CPU specific implementation, a BSP specific implementation or an application +specific implementation. + +The Idle Task is preemptible and *WILL* be preempted when any other task is +made ready to execute. This characteristic is critical to the overall behavior +of any application. + +Initialization Manager Failure +------------------------------ + +System initialization errors are fatal. See :ref:`internal_errors`. diff --git a/c-user/initialization/directives.rst b/c-user/initialization/directives.rst new file mode 100644 index 0000000..bb3fa95 --- /dev/null +++ b/c-user/initialization/directives.rst @@ -0,0 +1,69 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2015, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. _InitializationManagerDirectives: + +Directives +========== + +This section details the directives of the Initialization Manager. A subsection +is dedicated to each of this manager's directives and lists the calling +sequence, parameters, description, return values, and notes of the directive. + +.. Generated from spec:/rtems/init/if/initialize-executive + +.. raw:: latex + + \clearpage + +.. index:: rtems_initialize_executive() +.. index:: initialize RTEMS +.. index:: start multitasking + +.. _InterfaceRtemsInitializeExecutive: + +rtems_initialize_executive() +---------------------------- + +Initializes the system and starts multitasking. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_initialize_executive( void ); + +.. rubric:: DESCRIPTION: + +Iterates through the system initialization linker set and invokes the +registered handlers. The final step is to start multitasking. + +.. rubric:: NOTES: + +Errors in the initialization sequence are usually fatal and lead to a system +termination. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive should be called by :c:func:`boot_card` only. + +* The directive will not return to the caller. diff --git a/c-user/initialization/index.rst b/c-user/initialization/index.rst new file mode 100644 index 0000000..cbca400 --- /dev/null +++ b/c-user/initialization/index.rst @@ -0,0 +1,15 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2021 embedded brains GmbH & Co. KG + +.. _RTEMSAPIClassicInit: + +Initialization Manager +********************** + +.. toctree:: + + introduction + background + operations + directives diff --git a/c-user/initialization/introduction.rst b/c-user/initialization/introduction.rst new file mode 100644 index 0000000..15722f6 --- /dev/null +++ b/c-user/initialization/introduction.rst @@ -0,0 +1,39 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2015, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/rtems/init/if/group + +.. _InitializationManagerIntroduction: + +Introduction +============ + +.. The following list was generated from: +.. spec:/rtems/init/if/initialize-executive + +The Initialization Manager is responsible for initializing the system. + +The system initialization includes the initialization of the Board Support +Package, RTEMS, device drivers, the root filesystem, and the application. The +:ref:`RTEMSAPIClassicFatal` is responsible for the system shutdown. The +directives provided by the Initialization Manager are: + +* :ref:`InterfaceRtemsInitializeExecutive` - Initializes the system and starts + multitasking. diff --git a/c-user/initialization.rst b/c-user/initialization/operations.rst index fa7afb5..e7d310c 100644 --- a/c-user/initialization.rst +++ b/c-user/initialization/operations.rst @@ -2,66 +2,6 @@ .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) -Initialization Manager -********************** - -Introduction -============ - -The Initialization Manager is responsible for initializing the Board Support -Package, RTEMS, device drivers, the root filesystem and the application. The -:ref:`Fatal Error Manager <fatal_error_manager>` is responsible for the system -shutdown. - -The Initialization Manager provides only one directive: - -- rtems_initialize_executive_ - Initialize RTEMS - -Background -========== - -.. index:: initialization tasks - -Initialization Tasks --------------------- - -Initialization task(s) are the mechanism by which RTEMS transfers initial -control to the user's application. Initialization tasks differ from other -application tasks in that they are defined in the User Initialization Tasks -Table and automatically created and started by RTEMS as part of its -initialization sequence. Since the initialization tasks are scheduled using -the same algorithm as all other RTEMS tasks, they must be configured at a -priority and mode which will ensure that they will complete execution before -other application tasks execute. Although there is no upper limit on the -number of initialization tasks, an application is required to define at least -one. - -A typical initialization task will create and start the static set of -application tasks. It may also create any other objects used by the -application. Initialization tasks which only perform initialization should -delete themselves upon completion to free resources for other tasks. -Initialization tasks may transform themselves into a "normal" application task. -This transformation typically involves changing priority and execution mode. -RTEMS does not automatically delete the initialization tasks. - -The Idle Task -------------- - -The Idle Task is the lowest priority task in a system and executes only when no -other task is ready to execute. The default implementation of this task -consists of an infinite loop. RTEMS allows the Idle Task body to be replaced by -a CPU specific implementation, a BSP specific implementation or an application -specific implementation. - -The Idle Task is preemptible and *WILL* be preempted when any other task is -made ready to execute. This characteristic is critical to the overall behavior -of any application. - -Initialization Manager Failure ------------------------------- - -System initialization errors are fatal. See :ref:`internal_errors`. - Operations ========== @@ -345,19 +285,24 @@ Many of RTEMS actions during initialization are based upon the contents of the Configuration Table. For more information regarding the format and contents of this table, please refer to the chapter :ref:`Configuring a System`. +.. index:: global construction + +.. _GlobalConstruction: + Global Construction ------------------- -The global construction is carried out by the first Classic API initialization -task (first is defined by index zero in the Classic API initialization task -configuration table). If no Classic API initialization task exists, then it is -carried out by the first POSIX API initialization thread. If no initialization -task or thread exists, then no global construction is performed, see for -example :ref:`Specify Idle Task Performs Application Initialization`. The -Classic API task or POSIX API thread which carries out global construction is -called the main thread. - -Global construction runs before the entry function of the main thread. The +The :term:`global construction` is carried out by the Classic API +initialization task. If no Classic API initialization task exists, then it is +carried out by the POSIX API initialization thread. If no initialization task +or thread exists, then no global construction is performed. The Classic API +task or POSIX API thread which carries out global construction is called the +main thread. For configuration options related to initialization tasks, see +:ref:`CONFIGURE_RTEMS_INIT_TASKS_TABLE`, +:ref:`CONFIGURE_POSIX_INIT_THREAD_TABLE`, and +:ref:`CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION`. + +Global construction runs before the :term:`task entry` of the main thread. The configuration of the main thread must take the global construction into account. In particular, the main thread stack size, priority, attributes and initial modes must be set accordingly. Thread-local objects and POSIX key @@ -418,41 +363,3 @@ should output: c() b() A:A() - -Directives -========== - -This section details the Initialization Manager's directives. A subsection is -dedicated to each of this manager's directives and describes the calling -sequence, related constants, usage, and status codes. - -.. raw:: latex - - \clearpage - -.. index:: initialize RTEMS -.. index:: start multitasking -.. index:: rtems_initialize_executive - -.. _rtems_initialize_executive: - -INITIALIZE_EXECUTIVE - Initialize RTEMS ---------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - void rtems_initialize_executive(void); - -DIRECTIVE STATUS CODES: - NONE - This function will not return to the caller. - -DESCRIPTION: - Iterates through the system initialization linker set and invokes the - registered handlers. The final step is to start multitasking. - -NOTES: - This directive should be called by :c:func:`boot_card()` only. - - This directive *does not return* to the caller. Errors in the - initialization sequence are usually fatal and lead to a system termination. diff --git a/c-user/interrupt/directives.rst b/c-user/interrupt/directives.rst index 95181db..80eddfd 100644 --- a/c-user/interrupt/directives.rst +++ b/c-user/interrupt/directives.rst @@ -1,521 +1,3646 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 +.. Copyright (C) 2008, 2022 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. _InterruptManagerDirectives: + Directives ========== -This section details the 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. +This section details the directives of the Interrupt Manager. A subsection is +dedicated to each of this manager's directives and lists the calling sequence, +parameters, description, return values, and notes of the directive. + +.. Generated from spec:/rtems/intr/if/catch .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_interrupt_catch() .. index:: establish an ISR .. index:: install an ISR -.. index:: rtems_interrupt_catch -.. _rtems_interrupt_catch: +.. _InterfaceRtemsInterruptCatch: -INTERRUPT_CATCH - Establish an ISR ----------------------------------- +rtems_interrupt_catch() +----------------------- + +Establishes an interrupt service routine. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_catch( + rtems_isr_entry new_isr_handler, + rtems_vector_number vector, + rtems_isr_entry *old_isr_handler + ); + +.. rubric:: PARAMETERS: + +``new_isr_handler`` + This parameter is the new interrupt service routine. + +``vector`` + This parameter is the interrupt vector number. + +``old_isr_handler`` + This parameter is the pointer to an :ref:`InterfaceRtemsIsrEntry` object. + When the directive call is successful, the previous interrupt service + routine established for this interrupt vector will be stored in this + object. + +.. rubric:: DESCRIPTION: + +This directive establishes an interrupt service routine (ISR) for the interrupt +specified by the ``vector`` number. The ``new_isr_handler`` parameter +specifies the entry point of the ISR. The entry point of the previous ISR for +the specified vector is returned in ``old_isr_handler``. + +To release an interrupt vector, pass the old handler's address obtained when +the vector was first capture. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_NUMBER` + The interrupt vector number was illegal. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``new_isr_handler`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``old_isr_handler`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +.. rubric:: CONSTRAINTS: -CALLING SEQUENCE: - .. code-block:: c +The following constraints apply to this directive: - rtems_status_code rtems_interrupt_catch( - rtems_isr_entry new_isr_handler, - rtems_vector_number vector, - rtems_isr_entry *old_isr_handler - ); +* The directive may be called from within interrupt context. -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-wrap +* The directive may be called from within device driver initialization context. - * - ``RTEMS_SUCCESSFUL`` - - ISR established successfully - * - ``RTEMS_INVALID_NUMBER`` - - illegal vector number - * - ``RTEMS_INVALID_ADDRESS`` - - illegal ISR entry point or invalid ``old_isr_handler`` +* The directive may be called from within task context. -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``. +* The directive will not cause the calling task to be preempted. - To release an interrupt vector, pass the old handler's address obtained - when the vector was first capture. +* The directive is only available where the :term:`target architecture` support + enabled simple vectored interrupts. -NOTES: - This directive will not cause the calling task to be preempted. +.. Generated from spec:/rtems/intr/if/disable .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_interrupt_disable() .. index:: disable interrupts -.. index:: rtems_interrupt_disable -.. _rtems_interrupt_disable: +.. _InterfaceRtemsInterruptDisable: -INTERRUPT_DISABLE - Disable Interrupts --------------------------------------- +rtems_interrupt_disable() +------------------------- + +Disables the maskable interrupts on the current processor. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_interrupt_disable( rtems_interrupt_level isr_cookie ); + +.. rubric:: PARAMETERS: + +``isr_cookie`` + This parameter is a variable of type :ref:`InterfaceRtemsInterruptLevel` + which will be used to save the previous interrupt level. + +.. rubric:: DESCRIPTION: + +This directive disables all maskable interrupts on the current processor and +returns the previous interrupt level in ``isr_cookie``. + +.. rubric:: NOTES: -CALLING SEQUENCE: - .. code-block:: c +A later invocation of the :ref:`InterfaceRtemsInterruptEnable` directive should +be used to restore the previous interrupt level. - void rtems_interrupt_disable( - rtems_interrupt_level level - ); +This directive is implemented as a macro which sets the ``isr_cookie`` +parameter. -DIRECTIVE STATUS CODES: - NONE +.. code-block:: c + :linenos: -DESCRIPTION: - This directive disables all maskable interrupts and returns the previous - interrupt level in ``level``. + #include <rtems.h> -NOTES: - A later invocation of the ``rtems_interrupt_enable`` directive should be - used to restore the interrupt level. + void local_critical_section( void ) + { + rtems_interrupt_level level; - This directive is implemented as a macro which sets the ``level`` - parameter. + // Please note that the rtems_interrupt_disable() is a macro. The + // previous interrupt level (before the maskable interrupts are + // disabled) is returned here in the level macro parameter. This + // would be wrong: + // + // rtems_interrupt_disable( &level ); + rtems_interrupt_disable( level ); - This directive will not cause the calling task to be preempted. + // Here is the critical section: maskable interrupts are disabled - This directive is only available in uniprocessor configurations. The - directive ``rtems_interrupt_local_disable`` is available in all - configurations. + { + rtems_interrupt_level nested_level; - .. code-block:: c + rtems_interrupt_disable( nested_level ); - void critical_section( void ) - { - rtems_interrupt_level level; + // Here is a nested critical section - /* - * Please note that the rtems_interrupt_disable() is a macro. The - * previous interrupt level (before the maskable interrupts are - * disabled) is returned here in the level macro parameter. This - * would be wrong: - * - * rtems_interrupt_disable( &level ); - */ - rtems_interrupt_disable( level ); + rtems_interrupt_enable( nested_level ); + } - /* Critical section, maskable interrupts are disabled */ + // Maskable interrupts are still disabled - { - rtems_interrupt_level level2; + rtems_interrupt_enable( level ); + } - rtems_interrupt_disable( level2 ); +.. rubric:: CONSTRAINTS: - /* Nested critical section */ +The following constraints apply to this directive: - rtems_interrupt_enable( level2 ); - } +* The directive may be called from within any runtime context. - /* Maskable interrupts are still disabled */ +* The directive will not cause the calling task to be preempted. - rtems_interrupt_enable( level ); - } +* Where the system was built with SMP support enabled, the directive is not + available. Its use will result in compiler warnings and linker errors. The + :ref:`InterfaceRtemsInterruptLocalDisable` and + :ref:`InterfaceRtemsInterruptLocalEnable` directives are available in all + build configurations. + +.. Generated from spec:/rtems/intr/if/enable .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_interrupt_enable() .. index:: enable interrupts .. index:: restore interrupt level -.. index:: rtems_interrupt_enable -.. _rtems_interrupt_enable: +.. _InterfaceRtemsInterruptEnable: + +rtems_interrupt_enable() +------------------------ + +Restores the previous interrupt level on the current processor. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_interrupt_enable( rtems_interrupt_level isr_cookie ); + +.. rubric:: PARAMETERS: + +``isr_cookie`` + This parameter is the previous interrupt level to restore. The value must + be obtained by a previous call to :ref:`InterfaceRtemsInterruptDisable` or + :ref:`InterfaceRtemsInterruptFlash`. + +.. rubric:: DESCRIPTION: -INTERRUPT_ENABLE - Restore Interrupt Level ------------------------------------------- +This directive restores the interrupt level specified by ``isr_cookie`` on the +current processor. -CALLING SEQUENCE: - .. code-block:: c +.. rubric:: NOTES: - void rtems_interrupt_enable( - rtems_interrupt_level level - ); +The ``isr_cookie`` parameter value must be obtained by a previous call to +:ref:`InterfaceRtemsInterruptDisable` or :ref:`InterfaceRtemsInterruptFlash`. +Using an otherwise obtained value is undefined behaviour. -DIRECTIVE STATUS CODES: - NONE +This directive is unsuitable to enable particular interrupt sources, for +example in an interrupt controller. -DESCRIPTION: - This directive restores the interrupt level specified by ``level``. +.. rubric:: CONSTRAINTS: -NOTES: - The ``level`` parameter value must be obtained by a previous call to - ``rtems_interrupt_disable`` or ``rtems_interrupt_flash``. Using an - otherwise obtained value is undefined behaviour. +The following constraints apply to this directive: - This directive is unsuitable to enable particular interrupt sources, for - example in an interrupt controller. +* The directive may be called from within any runtime context. - This directive will not cause the calling task to be preempted. +* The directive will not cause the calling task to be preempted. - This directive is only available in uniprocessor configurations. The - directive ``rtems_interrupt_local_enable`` is available in all - configurations. +* While at least one maskable interrupt is pending, when the directive enables + maskable interrupts, the pending interrupts are immediately serviced. The + interrupt service routines may unblock higher priority tasks which may + preempt the calling task. + +* Where the system was built with SMP support enabled, the directive is not + available. Its use will result in compiler warnings and linker errors. The + :ref:`InterfaceRtemsInterruptLocalDisable` and + :ref:`InterfaceRtemsInterruptLocalEnable` directives are available in all + build configurations. + +.. Generated from spec:/rtems/intr/if/flash .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_interrupt_flash() .. index:: flash interrupts -.. index:: rtems_interrupt_flash -.. _rtems_interrupt_flash: +.. _InterfaceRtemsInterruptFlash: -INTERRUPT_FLASH - Flash Interrupts ----------------------------------- +rtems_interrupt_flash() +----------------------- + +Flashes interrupts on the current processor. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_interrupt_flash( rtems_interrupt_level isr_cookie ); + +.. rubric:: PARAMETERS: + +``isr_cookie`` + This parameter is the previous interrupt level. + +.. rubric:: DESCRIPTION: -CALLING SEQUENCE: - .. code-block:: c +This directive is functionally equivalent to a calling +:ref:`InterfaceRtemsInterruptEnable` immediately followed by a +:ref:`InterfaceRtemsInterruptDisable`. On some architectures it is possible to +provide an optimized implementation for this sequence. - void rtems_interrupt_flash( - rtems_interrupt_level level - ); +.. rubric:: NOTES: -DIRECTIVE STATUS CODES: - NONE +The ``isr_cookie`` parameter value must be obtained by a previous call to +:ref:`InterfaceRtemsInterruptDisable` or :ref:`InterfaceRtemsInterruptFlash`. +Using an otherwise obtained value is undefined behaviour. -DESCRIPTION: - This directive is functionally equivalent to a - ``rtems_interrupt_enable( level )`` immediately followed by a - ``rtems_interrupt_disable( level )``. On some - architectures it is possible to provide an optimized implementation for - this sequence. +Historically, the interrupt flash directive was heavily used in the operating +system implementation. However, this is no longer the case. The interrupt +flash directive is provided for backward compatibility reasons. -NOTES: - The ``level`` parameter value must be obtained by a previous call to - ``rtems_interrupt_disable`` or ``rtems_interrupt_flash``. Using an - otherwise obtained value is undefined behaviour. +.. rubric:: CONSTRAINTS: - This directive will not cause the calling task to be preempted. +The following constraints apply to this directive: - This directive is only available in uniprocessor configurations. The - directives ``rtems_interrupt_local_disable`` and - ``rtems_interrupt_local_enable`` are available in all configurations. +* The directive may be called from within any runtime context. - Historically, the interrupt flash directive was heavily used in the - operating system implementation. However, this is no longer the case. The - interrupt flash directive is provided for backward compatibility reasons. +* The directive will not cause the calling task to be preempted. + +* Where the system was built with SMP support enabled, the directive is not + available. Its use will result in compiler warnings and linker errors. The + :ref:`InterfaceRtemsInterruptLocalDisable` and + :ref:`InterfaceRtemsInterruptLocalEnable` directives are available in all + build configurations. + +.. Generated from spec:/rtems/intr/if/local-disable .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_interrupt_local_disable() .. index:: disable interrupts -.. index:: rtems_interrupt_local_disable -.. _rtems_interrupt_local_disable: +.. _InterfaceRtemsInterruptLocalDisable: + +rtems_interrupt_local_disable() +------------------------------- + +Disables the maskable interrupts on the current processor. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_interrupt_local_disable( rtems_interrupt_level isr_cookie ); + +.. rubric:: PARAMETERS: + +``isr_cookie`` + This parameter is a variable of type :ref:`InterfaceRtemsInterruptLevel` + which will be used to save the previous interrupt level. + +.. rubric:: DESCRIPTION: -INTERRUPT_LOCAL_DISABLE - Disable Interrupts on Current Processor ------------------------------------------------------------------ +This directive disables all maskable interrupts on the current processor and +returns the previous interrupt level in ``isr_cookie``. -CALLING SEQUENCE: - .. code-block:: c +.. rubric:: NOTES: - void rtems_interrupt_local_disable( - rtems_interrupt_level level - ); +A later invocation of the :ref:`InterfaceRtemsInterruptLocalEnable` directive +should be used to restore the previous interrupt level. -DIRECTIVE STATUS CODES: - NONE +This directive is implemented as a macro which sets the ``isr_cookie`` +parameter. -DESCRIPTION: - This directive disables all maskable interrupts on the current processor - and returns the previous interrupt level in ``level``. +Where the system was built with SMP support enabled, this will not ensure +system wide mutual exclusion. Use interrupt locks instead, see +:ref:`InterfaceRtemsInterruptLockAcquire`. Interrupt disabled critical +sections may be used to access processor-specific data structures or disable +thread dispatching. -NOTES: - A later invocation of the ``rtems_interrupt_local_enable`` directive should - be used to restore the interrupt level. +.. code-block:: c + :linenos: - This directive is implemented as a macro which sets the ``level`` - parameter. + #include <rtems.h> - This directive will not cause the calling task to be preempted. + void local_critical_section( void ) + { + rtems_interrupt_level level; - In SMP configurations, this will not ensure system wide mutual exclusion. - Use interrupt locks instead. + // Please note that the rtems_interrupt_local_disable() is a macro. + // The previous interrupt level (before the maskable interrupts are + // disabled) is returned here in the level macro parameter. This would + // be wrong: + // + // rtems_interrupt_local_disable( &level ); + rtems_interrupt_local_disable( level ); - .. code-block:: c + // Here is the critical section: maskable interrupts are disabled - void local_critical_section( void ) - { - rtems_interrupt_level level; + { + rtems_interrupt_level nested_level; - /* - * Please note that the rtems_interrupt_local_disable() is a macro. - * The previous interrupt level (before the maskable interrupts are - * disabled) is returned here in the level macro parameter. This - * would be wrong: - * - * rtems_interrupt_local_disable( &level ); - */ - rtems_interrupt_local_disable( level ); + rtems_interrupt_local_disable( nested_level ); - /* - * Local critical section, maskable interrupts on the current - * processor are disabled. - */ + // Here is a nested critical section - { - rtems_interrupt_level level2; + rtems_interrupt_local_enable( nested_level ); + } - rtems_interrupt_local_disable( level2 ); + // Maskable interrupts are still disabled - /* Nested local critical section */ + rtems_interrupt_local_enable( level ); + } - rtems_interrupt_local_enable( level2 ); - } +.. rubric:: CONSTRAINTS: - /* Maskable interrupts are still disabled */ +The following constraints apply to this directive: - rtems_interrupt_local_enable( level ); - } +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/intr/if/local-enable .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_interrupt_local_enable() .. index:: enable interrupts .. index:: restore interrupt level -.. index:: rtems_interrupt_local_enable -.. _rtems_interrupt_local_enable: +.. _InterfaceRtemsInterruptLocalEnable: + +rtems_interrupt_local_enable() +------------------------------ + +Restores the previous interrupt level on the current processor. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_interrupt_local_enable( rtems_interrupt_level isr_cookie ); + +.. rubric:: PARAMETERS: + +``isr_cookie`` + This parameter is the previous interrupt level to restore. The value must + be obtained by a previous call to + :ref:`InterfaceRtemsInterruptLocalDisable`. + +.. rubric:: DESCRIPTION: + +This directive restores the interrupt level specified by ``isr_cookie`` on the +current processor. + +.. rubric:: NOTES: + +The ``isr_cookie`` parameter value must be obtained by a previous call to +:ref:`InterfaceRtemsInterruptLocalDisable`. Using an otherwise obtained value +is undefined behaviour. + +This directive is unsuitable to enable particular interrupt sources, for +example in an interrupt controller. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +* While at least one maskable interrupt is pending, when the directive enables + maskable interrupts, the pending interrupts are immediately serviced. The + interrupt service routines may unblock higher priority tasks which may + preempt the calling task. -INTERRUPT_LOCAL_ENABLE - Restore Interrupt Level on Current Processor ---------------------------------------------------------------------- +.. Generated from spec:/rtems/intr/if/is-in-progress -CALLING SEQUENCE: - .. code-block:: c +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_is_in_progress() +.. index:: is interrupt in progress + +.. _InterfaceRtemsInterruptIsInProgress: + +rtems_interrupt_is_in_progress() +-------------------------------- + +Checks if an ISR is in progress on the current processor. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + bool rtems_interrupt_is_in_progress( void ); - void rtems_interrupt_local_enable( - rtems_interrupt_level level - ); +.. rubric:: DESCRIPTION: -DIRECTIVE STATUS CODES: - NONE +This directive returns ``true``, if the current processor is currently +servicing an interrupt, and ``false`` otherwise. A return value of ``true`` +indicates that the caller is an interrupt service routine, **not** a task. The +directives available to an interrupt service routine are restricted. -DESCRIPTION: - This directive restores the interrupt level specified by ``level`` on the - current processor. +.. rubric:: RETURN VALUES: -NOTES: - The ``level`` parameter value must be obtained by a previous call to - ``rtems_interrupt_local_disable``. Using an otherwise obtained value is - undefined behaviour. +Returns true, if the current processor is currently servicing an interrupt, +otherwise false. - This directive is unsuitable to enable particular interrupt sources, for - example in an interrupt controller. +.. rubric:: CONSTRAINTS: - This directive will not cause the calling task to be preempted. +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/intr/if/lock-initialize .. raw:: latex - \clearpage + \clearpage + +.. index:: rtems_interrupt_lock_initialize() + +.. _InterfaceRtemsInterruptLockInitialize: -.. index:: rtems_interrupt_lock_initialize +rtems_interrupt_lock_initialize() +--------------------------------- -.. _rtems_interrupt_lock_initialize: +Initializes the ISR lock. -INTERRUPT_LOCK_INITIALIZE - Initialize an ISR Lock --------------------------------------------------- +.. rubric:: CALLING SEQUENCE: -CALLING SEQUENCE: - .. code-block:: c +.. code-block:: c - void rtems_interrupt_lock_initialize( - rtems_interrupt_lock *lock, - const char *name - ); + void rtems_interrupt_lock_initialize( + rtems_interrupt_lock *lock, + const char *name + ); -DIRECTIVE STATUS CODES: - NONE +.. rubric:: PARAMETERS: -DESCRIPTION: - Initializes an interrupt lock. The name must be persistent throughout the - lifetime of the lock. +``lock`` + This parameter is the ISR lock to initialize. -NOTES: - Concurrent initialization leads to unpredictable results. +``name`` + This parameter is the ISR lock name. It shall be a string. The name is + only used where the system was built with profiling support enabled. + +.. rubric:: NOTES: + +ISR locks may also be statically defined by +:ref:`InterfaceRTEMSINTERRUPTLOCKDEFINE` or statically initialized by +:ref:`InterfaceRTEMSINTERRUPTLOCKINITIALIZER`. + +.. Generated from spec:/rtems/intr/if/lock-destroy .. raw:: latex - \clearpage + \clearpage + +.. index:: rtems_interrupt_lock_destroy() + +.. _InterfaceRtemsInterruptLockDestroy: -.. index:: rtems_interrupt_lock_acquire +rtems_interrupt_lock_destroy() +------------------------------ -.. _rtems_interrupt_lock_acquire: +Destroys the ISR lock. -INTERRUPT_LOCK_ACQUIRE - Acquire an ISR Lock --------------------------------------------- +.. rubric:: CALLING SEQUENCE: -CALLING SEQUENCE: - .. code-block:: c +.. code-block:: c - void rtems_interrupt_lock_acquire( - rtems_interrupt_lock *lock, - rtems_interrupt_lock_context *lock_context - ); + void rtems_interrupt_lock_destroy( rtems_interrupt_lock *lock ); -DIRECTIVE STATUS CODES: - NONE +.. rubric:: PARAMETERS: -DESCRIPTION: - Maskable interrupts will be disabled. In SMP configurations, this - directive acquires an SMP lock. +``lock`` + This parameter is the ISR lock to destroy. -NOTES: - A separate lock context must be provided for each acquire/release pair, for - example an automatic variable. +.. rubric:: NOTES: - An attempt to recursively acquire the lock may result in an infinite loop - with maskable interrupts disabled. +The lock must have been dynamically initialized by +:ref:`InterfaceRtemsInterruptLockInitialize`, statically defined by +:ref:`InterfaceRTEMSINTERRUPTLOCKDEFINE`, or statically initialized by +:ref:`InterfaceRTEMSINTERRUPTLOCKINITIALIZER`. - This directive will not cause the calling thread to be preempted. This - directive can be used in thread and interrupt context. +Concurrent lock use during the destruction or concurrent destruction leads to +unpredictable results. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/intr/if/lock-acquire .. raw:: latex - \clearpage + \clearpage + +.. index:: rtems_interrupt_lock_acquire() + +.. _InterfaceRtemsInterruptLockAcquire: + +rtems_interrupt_lock_acquire() +------------------------------ + +Acquires the ISR lock. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_interrupt_lock_acquire( + rtems_interrupt_lock *lock, + rtems_interrupt_lock_context *lock_context + ); + +.. rubric:: PARAMETERS: + +``lock`` + This parameter is the ISR lock to acquire. + +``lock_context`` + This parameter is the ISR lock context. This lock context shall be used to + release the lock by calling :ref:`InterfaceRtemsInterruptLockRelease`. + +.. rubric:: DESCRIPTION: + +This directive acquires the ISR lock specified by ``lock`` using the lock +context provided by ``lock_context``. Maskable interrupts will be disabled on +the current processor. + +.. rubric:: NOTES: + +A caller-specific lock context shall be provided for each acquire/release pair, +for example an automatic variable. -.. index:: rtems_interrupt_lock_release +Where the system was built with SMP support enabled, this directive acquires an +SMP lock. An attempt to recursively acquire the lock may result in an infinite +loop with maskable interrupts disabled. -.. _rtems_interrupt_lock_release: +This directive establishes a non-preemptive critical section with system wide +mutual exclusion on the local node in all RTEMS build configurations. -INTERRUPT_LOCK_RELEASE - Release an ISR Lock --------------------------------------------- +.. code-block:: c + :linenos: -CALLING SEQUENCE: - .. code-block:: c + #include <rtems.h> - void rtems_interrupt_lock_release( - rtems_interrupt_lock *lock, - rtems_interrupt_lock_context *lock_context - ); + void critical_section( rtems_interrupt_lock *lock ) + { + rtems_interrupt_lock_context lock_context; -DIRECTIVE STATUS CODES: - NONE + rtems_interrupt_lock_acquire( lock, &lock_context ); -DESCRIPTION: - The interrupt level will be restored. In SMP configurations, this - directive releases an SMP lock. + // Here is the critical section. Maskable interrupts are disabled. + // Where the system was built with SMP support enabled, this section + // is protected by an SMP lock. -NOTES: - The lock context must be the one used to acquire the lock, otherwise the - result is unpredictable. + rtems_interrupt_lock_release( lock, &lock_context ); + } - This directive will not cause the calling thread to be preempted. This - directive can be used in thread and interrupt context. +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/intr/if/lock-release .. raw:: latex - \clearpage + \clearpage + +.. index:: rtems_interrupt_lock_release() + +.. _InterfaceRtemsInterruptLockRelease: + +rtems_interrupt_lock_release() +------------------------------ + +Releases the ISR lock. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c -.. index:: rtems_interrupt_lock_acquire_isr + void rtems_interrupt_lock_release( rtems_interrupt_lock_context *lock ); -.. _rtems_interrupt_lock_acquire_isr: +.. rubric:: PARAMETERS: -INTERRUPT_LOCK_ACQUIRE_ISR - Acquire an ISR Lock from ISR ---------------------------------------------------------- +``lock`` + This parameter is the ISR lock to release. -CALLING SEQUENCE: - .. code-block:: c +``lock_context`` + This parameter is the ISR lock context. This lock context shall have been + used to acquire the lock by calling + :ref:`InterfaceRtemsInterruptLockAcquire`. - void rtems_interrupt_lock_acquire_isr( - rtems_interrupt_lock *lock, - rtems_interrupt_lock_context *lock_context - ); +.. rubric:: DESCRIPTION: -DIRECTIVE STATUS CODES: - NONE +This directive releases the ISR lock specified by ``lock`` using the lock +context provided by ``lock_context``. The previous interrupt level will be +restored on the current processor. -DESCRIPTION: - The interrupt level will remain unchanged. In SMP configurations, this - directive acquires an SMP lock. +.. rubric:: NOTES: -NOTES: - A separate lock context must be provided for each acquire/release pair, for - example an automatic variable. +The lock context shall be the one used to acquire the lock, otherwise the +result is unpredictable. - An attempt to recursively acquire the lock may result in an infinite loop. +Where the system was built with SMP support enabled, this directive releases an +SMP lock. - This directive is intended for device drivers and should be called from the - corresponding interrupt service routine. +.. rubric:: CONSTRAINTS: - 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. +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +* While at least one maskable interrupt is pending, when the directive enables + maskable interrupts, the pending interrupts are immediately serviced. The + interrupt service routines may unblock higher priority tasks which may + preempt the calling task. + +.. Generated from spec:/rtems/intr/if/lock-acquire-isr .. raw:: latex - \clearpage + \clearpage + +.. index:: rtems_interrupt_lock_acquire_isr() + +.. _InterfaceRtemsInterruptLockAcquireIsr: + +rtems_interrupt_lock_acquire_isr() +---------------------------------- + +Acquires the ISR lock from within an ISR. + +.. rubric:: CALLING SEQUENCE: -.. index:: rtems_interrupt_lock_release_isr +.. code-block:: c -.. _rtems_interrupt_lock_release_isr: + void rtems_interrupt_lock_acquire_isr( + rtems_interrupt_lock *lock, + rtems_interrupt_lock_context *lock_context + ); -INTERRUPT_LOCK_RELEASE_ISR - Release an ISR Lock from ISR ---------------------------------------------------------- +.. rubric:: PARAMETERS: -CALLING SEQUENCE: - .. code-block:: c +``lock`` + This parameter is the ISR lock to acquire within an ISR. - void rtems_interrupt_lock_release_isr( - rtems_interrupt_lock *lock, - rtems_interrupt_lock_context *lock_context - ); +``lock_context`` + This parameter is the ISR lock context. This lock context shall be used to + release the lock by calling :ref:`InterfaceRtemsInterruptLockReleaseIsr`. -DIRECTIVE STATUS CODES: - NONE +.. rubric:: DESCRIPTION: -DESCRIPTION: - The interrupt level will remain unchanged. In SMP configurations, this - directive releases an SMP lock. +This directive acquires the ISR lock specified by ``lock`` using the lock +context provided by ``lock_context``. The interrupt level will remain +unchanged. -NOTES: - The lock context must be the one used to acquire the lock, otherwise the - result is unpredictable. +.. rubric:: NOTES: - This directive is intended for device drivers and should be called from the - corresponding interrupt service routine. +A caller-specific lock context shall be provided for each acquire/release pair, +for example an automatic variable. + +Where the system was built with SMP support enabled, this directive acquires an +SMP lock. An attempt to recursively acquire the lock may result in an infinite +loop. + +This directive is intended for device drivers and should be called from the +corresponding interrupt service routine. + +In case the corresponding interrupt service routine can be interrupted by +higher priority interrupts and these interrupts enter the critical section +protected by this lock, then the result is unpredictable. This directive may +be used under specific circumstances as an optimization. In doubt, use +:ref:`InterfaceRtemsInterruptLockAcquire` and +:ref:`InterfaceRtemsInterruptLockRelease`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/intr/if/lock-release-isr .. raw:: latex - \clearpage + \clearpage -.. index:: is interrupt in progress -.. index:: rtems_interrupt_is_in_progress +.. index:: rtems_interrupt_lock_release_isr() + +.. _InterfaceRtemsInterruptLockReleaseIsr: + +rtems_interrupt_lock_release_isr() +---------------------------------- + +Releases the ISR lock from within an ISR. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_interrupt_lock_release_isr( + rtems_interrupt_lock *lock, + rtems_interrupt_lock_context *lock_context + ); + +.. rubric:: PARAMETERS: + +``lock`` + This parameter is the ISR lock to release within an ISR. + +``lock_context`` + This parameter is the ISR lock context. This lock context shall have been + used to acquire the lock by calling + :ref:`InterfaceRtemsInterruptLockAcquireIsr`. + +.. rubric:: DESCRIPTION: + +This directive releases the ISR lock specified by ``lock`` using the lock +context provided by ``lock_context``. The interrupt level will remain +unchanged. + +.. rubric:: NOTES: + +The lock context shall be the one used to acquire the lock, otherwise the +result is unpredictable. + +Where the system was built with SMP support enabled, this directive releases an +SMP lock. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/intr/if/lock-isr-disable + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_lock_interrupt_disable() + +.. _InterfaceRtemsInterruptLockInterruptDisable: + +rtems_interrupt_lock_interrupt_disable() +---------------------------------------- + +Disables maskable interrupts on the current processor. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_interrupt_lock_interrupt_disable( + rtems_interrupt_lock_context *lock_context + ); + +.. rubric:: PARAMETERS: + +``lock_context`` + This parameter is the ISR lock context for an acquire and release pair. + +.. rubric:: DESCRIPTION: + +This directive disables maskable interrupts on the current processor and stores +the previous interrupt level in ``lock_context``. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/intr/if/lock-declare + +.. raw:: latex + + \clearpage + +.. index:: RTEMS_INTERRUPT_LOCK_DECLARE() + +.. _InterfaceRTEMSINTERRUPTLOCKDECLARE: + +RTEMS_INTERRUPT_LOCK_DECLARE() +------------------------------ + +Declares an ISR lock object. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + RTEMS_INTERRUPT_LOCK_DECLARE( specifier, designator ); + +.. rubric:: PARAMETERS: + +``specifier`` + This parameter is the storage-class specifier for the ISR lock to declare, + for example ``extern`` or ``static``. + +``designator`` + This parameter is the ISR lock object designator. + +.. rubric:: NOTES: + +Do not add a ";" after this macro. + +.. Generated from spec:/rtems/intr/if/lock-define + +.. raw:: latex + + \clearpage + +.. index:: RTEMS_INTERRUPT_LOCK_DEFINE() + +.. _InterfaceRTEMSINTERRUPTLOCKDEFINE: + +RTEMS_INTERRUPT_LOCK_DEFINE() +----------------------------- + +Defines an ISR lock object. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + RTEMS_INTERRUPT_LOCK_DEFINE( specifier, designator, const char *name ); + +.. rubric:: PARAMETERS: + +``specifier`` + This parameter is the storage-class specifier for the ISR lock to declare, + for example ``extern`` or ``static``. + +``designator`` + This parameter is the ISR lock object designator. + +``name`` + This parameter is the ISR lock name. It shall be a string. The name is + only used where the system was built with profiling support enabled. + +.. rubric:: NOTES: + +Do not add a ";" after this macro. + +ISR locks may also be dynamically initialized by +:ref:`InterfaceRtemsInterruptLockInitialize` or statically by +:ref:`InterfaceRTEMSINTERRUPTLOCKINITIALIZER`. + +.. Generated from spec:/rtems/intr/if/lock-initializer + +.. raw:: latex + + \clearpage + +.. index:: RTEMS_INTERRUPT_LOCK_INITIALIZER() + +.. _InterfaceRTEMSINTERRUPTLOCKINITIALIZER: + +RTEMS_INTERRUPT_LOCK_INITIALIZER() +---------------------------------- + +Statically initializes an ISR lock object. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + RTEMS_INTERRUPT_LOCK_INITIALIZER( const char *name ); + +.. rubric:: PARAMETERS: + +``name`` + This parameter is the ISR lock name. It shall be a string. The name is + only used where the system was built with profiling support enabled. + +.. rubric:: NOTES: + +ISR locks may also be dynamically initialized by +:ref:`InterfaceRtemsInterruptLockInitialize` or statically defined by +:ref:`InterfaceRTEMSINTERRUPTLOCKDEFINE`. + +.. Generated from spec:/rtems/intr/if/lock-member + +.. raw:: latex + + \clearpage + +.. index:: RTEMS_INTERRUPT_LOCK_MEMBER() + +.. _InterfaceRTEMSINTERRUPTLOCKMEMBER: + +RTEMS_INTERRUPT_LOCK_MEMBER() +----------------------------- + +Defines an ISR lock member. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + RTEMS_INTERRUPT_LOCK_MEMBER( designator ); + +.. rubric:: PARAMETERS: + +``designator`` + This parameter is the ISR lock member designator. + +.. rubric:: NOTES: + +Do not add a ";" after this macro. + +.. Generated from spec:/rtems/intr/if/lock-reference + +.. raw:: latex + + \clearpage + +.. index:: RTEMS_INTERRUPT_LOCK_REFERENCE() + +.. _InterfaceRTEMSINTERRUPTLOCKREFERENCE: + +RTEMS_INTERRUPT_LOCK_REFERENCE() +-------------------------------- + +Defines an ISR lock object reference. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + RTEMS_INTERRUPT_LOCK_REFERENCE( designator, rtems_interrupt_lock *target ); + +.. rubric:: PARAMETERS: + +``designator`` + This parameter is the ISR lock reference designator. + +``target`` + This parameter is the target object to reference. + +.. rubric:: NOTES: + +Do not add a ";" after this macro. + +.. Generated from spec:/rtems/intr/if/entry-initializer + +.. raw:: latex + + \clearpage + +.. index:: RTEMS_INTERRUPT_ENTRY_INITIALIZER() + +.. _InterfaceRTEMSINTERRUPTENTRYINITIALIZER: + +RTEMS_INTERRUPT_ENTRY_INITIALIZER() +----------------------------------- + +Statically initializes an interrupt entry object. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + RTEMS_INTERRUPT_ENTRY_INITIALIZER( + rtems_interrupt_handler routine, + void *arg, + const char *info + ); + +.. rubric:: PARAMETERS: + +``routine`` + This parameter is the interrupt handler routine for the entry. + +``arg`` + This parameter is the interrupt handler argument for the entry. + +``info`` + This parameter is the descriptive information for the entry. + +.. rubric:: NOTES: + +Alternatively, :ref:`InterfaceRtemsInterruptEntryInitialize` may be used to +dynamically initialize an interrupt entry. + +.. Generated from spec:/rtems/intr/if/entry-initialize + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_entry_initialize() + +.. _InterfaceRtemsInterruptEntryInitialize: + +rtems_interrupt_entry_initialize() +---------------------------------- + +Initializes the interrupt entry. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_interrupt_entry_initialize( + rtems_interrupt_entry *entry, + rtems_interrupt_handler routine, + void *arg, + const char *info + ); + +.. rubric:: PARAMETERS: + +``entry`` + This parameter is the interrupt entry to initialize. + +``routine`` + This parameter is the interrupt handler routine for the entry. + +``arg`` + This parameter is the interrupt handler argument for the entry. + +``info`` + This parameter is the descriptive information for the entry. + +.. rubric:: NOTES: + +Alternatively, :ref:`InterfaceRTEMSINTERRUPTENTRYINITIALIZER` may be used to +statically initialize an interrupt entry. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/intr/if/entry-install + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_entry_install() + +.. _InterfaceRtemsInterruptEntryInstall: + +rtems_interrupt_entry_install() +------------------------------- + +Installs the interrupt entry at the interrupt vector. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_entry_install( + rtems_vector_number vector, + rtems_option options, + rtems_interrupt_entry *entry + ); + +.. rubric:: PARAMETERS: + +``vector`` + This parameter is the interrupt vector number. + +``options`` + This parameter is the interrupt entry install option set. + +``entry`` + This parameter is the interrupt entry to install. + +.. rubric:: DESCRIPTION: + +One of the following mutually exclusive options + +* :c:macro:`RTEMS_INTERRUPT_UNIQUE`, and + +* :c:macro:`RTEMS_INTERRUPT_SHARED` + +shall be set in the ``options`` parameter. + +The handler routine of the entry specified by ``entry`` will be called with the +handler argument of the entry when dispatched. The order in which shared +interrupt handlers are dispatched for one vector is defined by the installation +order. The first installed handler is dispatched first. + +If the option :c:macro:`RTEMS_INTERRUPT_UNIQUE` is set, then it will be ensured +that the handler will be the only one for the interrupt vector. + +If the option :c:macro:`RTEMS_INTERRUPT_SHARED` is set, then multiple handlers +may be installed for the interrupt vector. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``entry`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INCORRECT_STATE` + The service was not initialized. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The handler routine of the entry was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt vector associated with the number specified by + ``vector``. + +:c:macro:`RTEMS_CALLED_FROM_ISR` + The directive was called from within interrupt context. + +:c:macro:`RTEMS_INVALID_NUMBER` + An option specified by ``options`` was not applicable. + +:c:macro:`RTEMS_RESOURCE_IN_USE` + The :c:macro:`RTEMS_INTERRUPT_UNIQUE` option was set in ``entry`` and the + interrupt vector was already occupied by a handler. + +:c:macro:`RTEMS_RESOURCE_IN_USE` + The :c:macro:`RTEMS_INTERRUPT_SHARED` option was set in ``entry`` and the + interrupt vector was already occupied by a unique handler. + +:c:macro:`RTEMS_TOO_MANY` + The handler routine of the entry specified by ``entry`` was already + installed for the interrupt vector specified by ``vector`` with an argument + equal to the handler argument of the entry. + +.. rubric:: NOTES: + +When the directive call was successful, the ownership of the interrupt entry +has been transferred from the caller to the interrupt service. An installed +interrupt entry may be removed from the interrupt service by calling +:ref:`InterfaceRtemsInterruptEntryRemove`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. + +* The interrupt entry shall have been initialized by + :ref:`InterfaceRtemsInterruptEntryInitialize` or + :ref:`InterfaceRTEMSINTERRUPTENTRYINITIALIZER`. + +.. Generated from spec:/rtems/intr/if/entry-remove + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_entry_remove() + +.. _InterfaceRtemsInterruptEntryRemove: + +rtems_interrupt_entry_remove() +------------------------------ + +Removes the interrupt entry from the interrupt vector. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_entry_remove( + rtems_vector_number vector, + rtems_interrupt_entry *entry + ); + +.. rubric:: PARAMETERS: + +``vector`` + This parameter is the interrupt vector number. + +``entry`` + This parameter is the interrupt entry to remove. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INCORRECT_STATE` + The service was not initialized. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``entry`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt vector associated with the number specified by + ``vector``. + +:c:macro:`RTEMS_CALLED_FROM_ISR` + The directive was called from within interrupt context. + +:c:macro:`RTEMS_UNSATISFIED` + The entry specified by ``entry`` was not installed at the interrupt vector + specified by ``vector``. + +.. rubric:: NOTES: + +When the directive call was successful, the ownership of the interrupt entry +has been transferred from the interrupt service to the caller. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. + +* The interrupt entry shall have been installed by + :ref:`InterfaceRtemsInterruptEntryInstall`. + +.. Generated from spec:/rtems/intr/if/handler-install + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_handler_install() + +.. _InterfaceRtemsInterruptHandlerInstall: + +rtems_interrupt_handler_install() +--------------------------------- + +Installs the interrupt handler routine and argument at the interrupt vector. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_handler_install( + rtems_vector_number vector, + const char *info, + rtems_option options, + rtems_interrupt_handler routine, + void *arg + ); + +.. rubric:: PARAMETERS: + +``vector`` + This parameter is the interrupt vector number. + +``info`` + This parameter is the descriptive information of the interrupt handler to + install. + +``options`` + This parameter is the interrupt handler install option set. + +``routine`` + This parameter is the interrupt handler routine to install. + +``arg`` + This parameter is the interrupt handler argument to install. + +.. rubric:: DESCRIPTION: + +One of the following mutually exclusive options + +* :c:macro:`RTEMS_INTERRUPT_UNIQUE`, + +* :c:macro:`RTEMS_INTERRUPT_SHARED`, and + +* :c:macro:`RTEMS_INTERRUPT_REPLACE` + +shall be set in the ``options`` parameter. + +The handler routine will be called with the argument specified by ``arg`` when +dispatched. The order in which shared interrupt handlers are dispatched for +one vector is defined by the installation order. The first installed handler +is dispatched first. + +If the option :c:macro:`RTEMS_INTERRUPT_UNIQUE` is set, then it will be ensured +that the handler will be the only one for the interrupt vector. + +If the option :c:macro:`RTEMS_INTERRUPT_SHARED` is set, then multiple handler +may be installed for the interrupt vector. + +If the option :c:macro:`RTEMS_INTERRUPT_REPLACE` is set, then the handler +specified by ``routine`` will replace the first handler with the same argument +for the interrupt vector if it exists, otherwise an error status will be +returned. A second handler with the same argument for the interrupt vector +will remain unchanged. The new handler will inherit the unique or shared +options from the replaced handler. + +An informative description may be provided in ``info``. It may be used for +system debugging and diagnostic tools. The referenced string has to be +persistent as long as the handler is installed. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INCORRECT_STATE` + The service was not initialized. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``routine`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt vector associated with the number specified by + ``vector``. + +:c:macro:`RTEMS_CALLED_FROM_ISR` + The directive was called from within interrupt context. + +:c:macro:`RTEMS_NO_MEMORY` + There was not enough memory available to allocate data structures to + install the handler. + +:c:macro:`RTEMS_RESOURCE_IN_USE` + The :c:macro:`RTEMS_INTERRUPT_UNIQUE` option was set in ``options`` and the + interrupt vector was already occupied by a handler. + +:c:macro:`RTEMS_RESOURCE_IN_USE` + The :c:macro:`RTEMS_INTERRUPT_SHARED` option was set in ``options`` and the + interrupt vector was already occupied by a unique handler. + +:c:macro:`RTEMS_TOO_MANY` + The handler specified by ``routine`` was already installed for the + interrupt vector specified by ``vector`` with an argument equal to the + argument specified by ``arg``. + +:c:macro:`RTEMS_UNSATISFIED` + The :c:macro:`RTEMS_INTERRUPT_REPLACE` option was set in ``options`` and no + handler to replace was installed. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. + +.. Generated from spec:/rtems/intr/if/handler-remove + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_handler_remove() + +.. _InterfaceRtemsInterruptHandlerRemove: + +rtems_interrupt_handler_remove() +-------------------------------- + +Removes the interrupt handler routine and argument from the interrupt vector. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_handler_remove( + rtems_vector_number vector, + rtems_interrupt_handler routine, + void *arg + ); + +.. rubric:: PARAMETERS: + +``vector`` + This parameter is the interrupt vector number. + +``routine`` + This parameter is the interrupt handler routine to remove. + +``arg`` + This parameter is the interrupt handler argument to remove. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INCORRECT_STATE` + The service was not initialized. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``routine`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt vector associated with the number specified by + ``vector``. + +:c:macro:`RTEMS_CALLED_FROM_ISR` + The directive was called from within interrupt context. + +:c:macro:`RTEMS_UNSATISFIED` + There was no handler routine and argument pair installed specified by + ``routine`` and ``arg``. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. + +.. Generated from spec:/rtems/intr/if/vector-is-enabled + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_vector_is_enabled() + +.. _InterfaceRtemsInterruptVectorIsEnabled: + +rtems_interrupt_vector_is_enabled() +----------------------------------- + +Checks if the interrupt vector is enabled. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_vector_is_enabled( + rtems_vector_number vector, + bool *enabled + ); + +.. rubric:: PARAMETERS: + +``vector`` + This parameter is the interrupt vector number. + +``enabled`` + This parameter is the pointer to a ``bool`` object. When the directive + call is successful, the enabled status of the interrupt associated with the + interrupt vector specified by ``vector`` will be stored in this object. + When the interrupt was enabled for the processor executing the directive + call at some time point during the call, the object value will be set to + :c:macro:`true`, otherwise to :c:macro:`false`. + +.. rubric:: DESCRIPTION: + +The directive checks if the interrupt associated with the interrupt vector +specified by ``vector`` was enabled for the processor executing the directive +call at some time point during the call. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``enabled`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt vector associated with the number specified by + ``vector``. + +.. rubric:: NOTES: + +Interrupt vectors may be enabled by :ref:`InterfaceRtemsInterruptVectorEnable` +and disabled by :ref:`InterfaceRtemsInterruptVectorDisable`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/intr/if/vector-enable + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_vector_enable() + +.. _InterfaceRtemsInterruptVectorEnable: + +rtems_interrupt_vector_enable() +------------------------------- + +Enables the interrupt vector. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_vector_enable( rtems_vector_number vector ); + +.. rubric:: PARAMETERS: + +``vector`` + This parameter is the number of the interrupt vector to enable. + +.. rubric:: DESCRIPTION: + +The directive enables the interrupt vector specified by ``vector``. This allows +that interrupt service requests are issued to the target processors of the +interrupt vector. Interrupt service requests for an interrupt vector may be +raised by :ref:`InterfaceRtemsInterruptRaise`, +:ref:`InterfaceRtemsInterruptRaiseOn`, external signals, or messages. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt vector associated with the number specified by + ``vector``. + +:c:macro:`RTEMS_UNSATISFIED` + The request to enable the interrupt vector has not been satisfied. + +.. rubric:: NOTES: + +The :ref:`InterfaceRtemsInterruptGetAttributes` directive may be used to check +if an interrupt vector can be enabled. Interrupt vectors may be disabled by +:ref:`InterfaceRtemsInterruptVectorDisable`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/intr/if/vector-disable + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_vector_disable() + +.. _InterfaceRtemsInterruptVectorDisable: + +rtems_interrupt_vector_disable() +-------------------------------- + +Disables the interrupt vector. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_vector_disable( rtems_vector_number vector ); + +.. rubric:: PARAMETERS: + +``vector`` + This parameter is the number of the interrupt vector to disable. + +.. rubric:: DESCRIPTION: + +The directive disables the interrupt vector specified by ``vector``. This +prevents that an interrupt service request is issued to the target processors +of the interrupt vector. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt vector associated with the number specified by + ``vector``. + +:c:macro:`RTEMS_UNSATISFIED` + The request to disable the interrupt vector has not been satisfied. + +.. rubric:: NOTES: + +The :ref:`InterfaceRtemsInterruptGetAttributes` directive may be used to check +if an interrupt vector can be disabled. Interrupt vectors may be enabled by +:ref:`InterfaceRtemsInterruptVectorEnable`. There may be targets on which some +interrupt vectors cannot be disabled, for example a hardware watchdog interrupt +or software generated interrupts. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/intr/if/is-pending + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_is_pending() + +.. _InterfaceRtemsInterruptIsPending: + +rtems_interrupt_is_pending() +---------------------------- + +Checks if the interrupt is pending. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_is_pending( + rtems_vector_number vector, + bool *pending + ); + +.. rubric:: PARAMETERS: + +``vector`` + This parameter is the interrupt vector number. + +``pending`` + This parameter is the pointer to a ``bool`` object. When the directive + call is successful, the pending status of the interrupt associated with the + interrupt vector specified by ``vector`` will be stored in this object. + When the interrupt was pending for the processor executing the directive + call at some time point during the call, the object value will be set to + :c:macro:`true`, otherwise to :c:macro:`false`. + +.. rubric:: DESCRIPTION: + +The directive checks if the interrupt associated with the interrupt vector +specified by ``vector`` was pending for the processor executing the directive +call at some time point during the call. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``pending`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt vector associated with the number specified by + ``vector``. + +:c:macro:`RTEMS_UNSATISFIED` + The request to get the pending status has not been satisfied. + +.. rubric:: NOTES: + +Interrupts may be made pending by calling the +:ref:`InterfaceRtemsInterruptRaise` or :ref:`InterfaceRtemsInterruptRaiseOn` +directives or due to external signals or messages. The pending state may be +cleared by :ref:`InterfaceRtemsInterruptClear`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/intr/if/raise + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_raise() + +.. _InterfaceRtemsInterruptRaise: + +rtems_interrupt_raise() +----------------------- + +Raises the interrupt vector. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_raise( rtems_vector_number vector ); + +.. rubric:: PARAMETERS: + +``vector`` + This parameter is the number of the interrupt vector to raise. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt vector associated with the number specified by + ``vector``. + +:c:macro:`RTEMS_UNSATISFIED` + The request to raise the interrupt vector has not been satisfied. + +.. rubric:: NOTES: + +The :ref:`InterfaceRtemsInterruptGetAttributes` directive may be used to check +if an interrupt vector can be raised. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/intr/if/raise-on + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_raise_on() + +.. _InterfaceRtemsInterruptRaiseOn: + +rtems_interrupt_raise_on() +-------------------------- + +Raises the interrupt vector on the processor. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_raise_on( + rtems_vector_number vector, + uint32_t cpu_index + ); + +.. rubric:: PARAMETERS: + +``vector`` + This parameter is the number of the interrupt vector to raise. + +``cpu_index`` + This parameter is the index of the target processor of the interrupt vector + to raise. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt vector associated with the number specified by + ``vector``. + +:c:macro:`RTEMS_NOT_CONFIGURED` + The processor specified by ``cpu_index`` was not configured to be used by + the application. + +:c:macro:`RTEMS_INCORRECT_STATE` + The processor specified by ``cpu_index`` was configured to be used by the + application, however, it was not online. + +:c:macro:`RTEMS_UNSATISFIED` + The request to raise the interrupt vector has not been satisfied. + +.. rubric:: NOTES: + +The :ref:`InterfaceRtemsInterruptGetAttributes` directive may be used to check +if an interrupt vector can be raised on a processor. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/intr/if/clear + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_clear() + +.. _InterfaceRtemsInterruptClear: + +rtems_interrupt_clear() +----------------------- + +Clears the interrupt vector. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_clear( rtems_vector_number vector ); + +.. rubric:: PARAMETERS: + +``vector`` + This parameter is the number of the interrupt vector to clear. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt vector associated with the number specified by + ``vector``. + +:c:macro:`RTEMS_UNSATISFIED` + The request to raise the interrupt vector has not been satisfied. + +.. rubric:: NOTES: + +The :ref:`InterfaceRtemsInterruptGetAttributes` directive may be used to check +if an interrupt vector can be cleared. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/intr/if/get-affinity + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_get_affinity() + +.. _InterfaceRtemsInterruptGetAffinity: + +rtems_interrupt_get_affinity() +------------------------------ + +Gets the processor affinity set of the interrupt vector. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_get_affinity( + rtems_vector_number vector, + size_t affinity_size, + cpu_set_t *affinity + ); + +.. rubric:: PARAMETERS: + +``vector`` + This parameter is the interrupt vector number. + +``affinity_size`` + This parameter is the size of the processor set referenced by ``affinity`` + in bytes. + +``affinity`` + This parameter is the pointer to a :c:type:`cpu_set_t` object. When the + directive call is successful, the processor affinity set of the interrupt + vector will be stored in this object. A set bit in the processor set means + that the corresponding processor is in the processor affinity set of the + interrupt vector, otherwise the bit is cleared. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``affinity`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt vector associated with the number specified by + ``vector``. + +:c:macro:`RTEMS_INVALID_SIZE` + The size specified by ``affinity_size`` of the processor set was too small + for the processor affinity set of the interrupt vector. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/intr/if/set-affinity + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_set_affinity() + +.. _InterfaceRtemsInterruptSetAffinity: + +rtems_interrupt_set_affinity() +------------------------------ + +Sets the processor affinity set of the interrupt vector. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_set_affinity( + rtems_vector_number vector, + size_t affinity_size, + const cpu_set_t *affinity + ); + +.. rubric:: PARAMETERS: + +``vector`` + This parameter is the interrupt vector number. + +``affinity_size`` + This parameter is the size of the processor set referenced by ``affinity`` + in bytes. + +``affinity`` + This parameter is the pointer to a :c:type:`cpu_set_t` object. The + processor set defines the new processor affinity set of the interrupt + vector. A set bit in the processor set means that the corresponding + processor shall be in the processor affinity set of the interrupt vector, + otherwise the bit shall be cleared. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``affinity`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt vector associated with the number specified by + ``vector``. + +:c:macro:`RTEMS_INVALID_NUMBER` + The referenced processor set was not a valid new processor affinity set for + the interrupt vector. + +:c:macro:`RTEMS_UNSATISFIED` + The request to set the processor affinity of the interrupt vector has not + been satisfied. + +.. rubric:: NOTES: + +The :ref:`InterfaceRtemsInterruptGetAttributes` directive may be used to check +if the processor affinity of an interrupt vector can be set. + +Only online processors of the affinity set specified by ``affinity_size`` and +``affinity`` are considered by the directive. Other processors of the set are +ignored. If the set contains no online processor, then the set is invalid and +an error status is returned. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/intr/if/get-attributes + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_get_attributes() + +.. _InterfaceRtemsInterruptGetAttributes: + +rtems_interrupt_get_attributes() +-------------------------------- + +Gets the attributes of the interrupt vector. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_get_attributes( + rtems_vector_number vector, + rtems_interrupt_attributes *attributes + ); + +.. rubric:: PARAMETERS: + +``vector`` + This parameter is the interrupt vector number. + +``attributes`` + This parameter is the pointer to an + :ref:`InterfaceRtemsInterruptAttributes` object. When the directive call + is successful, the attributes of the interrupt vector will be stored in + this object. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``attributes`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt vector associated with the number specified by + ``vector``. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/intr/if/handler-iterate + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_handler_iterate() + +.. _InterfaceRtemsInterruptHandlerIterate: + +rtems_interrupt_handler_iterate() +--------------------------------- + +Iterates over all interrupt handler installed at the interrupt vector. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_handler_iterate( + rtems_vector_number vector, + rtems_interrupt_per_handler_routine routine, + void *arg + ); + +.. rubric:: PARAMETERS: + +``vector`` + This parameter is the interrupt vector number. + +``routine`` + This parameter is the visitor routine. + +``arg`` + This parameter is the visitor argument. + +.. rubric:: DESCRIPTION: + +For each installed handler at the interrupt vector the visitor function +specified by ``routine`` will be called with the argument specified by ``arg`` +and the handler information, options, routine and argument. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INCORRECT_STATE` + The service was not initialized. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``routine`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt vector associated with the number specified by + ``vector``. + +:c:macro:`RTEMS_CALLED_FROM_ISR` + The directive was called from within interrupt context. + +.. rubric:: NOTES: + +The directive is intended for system information and diagnostics. + +Never install or remove an interrupt handler within the visitor function. This +may result in a deadlock. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. + +.. Generated from spec:/rtems/intr/if/server-initialize + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_server_initialize() + +.. _InterfaceRtemsInterruptServerInitialize: + +rtems_interrupt_server_initialize() +----------------------------------- + +Initializes the interrupt server tasks. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_server_initialize( + rtems_task_priority priority, + size_t stack_size, + rtems_mode modes, + rtems_attribute attributes, + uint32_t *server_count + ); + +.. rubric:: PARAMETERS: + +``priority`` + This parameter is the initial :term:`task priority` of the created + interrupt servers. + +``stack_size`` + This parameter is the task stack size of the created interrupt servers. + +``modes`` + This parameter is the initial mode set of the created interrupt servers. + +``attributes`` + This parameter is the attribute set of the created interrupt servers. + +``server_count`` + This parameter is the pointer to an `uint32_t + <https://en.cppreference.com/w/c/types/integer>`_ object or `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. When the pointer is not + equal to `NULL <https://en.cppreference.com/w/c/types/NULL>`_, the count of + successfully created interrupt servers is stored in this object regardless + of the return status. + +.. rubric:: DESCRIPTION: + +The directive tries to create an interrupt server task for each online +processor in the system. The tasks will have the initial priority specified by +``priority``, the stack size specified by ``stack_size``, the initial mode set +specified by ``modes``, and the attribute set specified by ``attributes``. The +count of successfully created server tasks will be returned in ``server_count`` +if the pointer is not equal to `NULL +<https://en.cppreference.com/w/c/types/NULL>`_. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INCORRECT_STATE` + The interrupt servers were already initialized. + +The directive uses :ref:`InterfaceRtemsTaskCreate`. If this directive fails, +then its error status will be returned. + +.. rubric:: NOTES: + +Interrupt handlers may be installed on an interrupt server with +:ref:`InterfaceRtemsInterruptServerHandlerInstall` and removed with +:ref:`InterfaceRtemsInterruptServerHandlerRemove` using a server index. In +case of an interrupt, the request will be forwarded to the interrupt server. +The handlers are executed within the interrupt server context. If one handler +blocks on something this may delay the processing of other handlers. + +Interrupt servers may be deleted by :ref:`InterfaceRtemsInterruptServerDelete`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. + +.. Generated from spec:/rtems/intr/if/server-create + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_server_create() + +.. _InterfaceRtemsInterruptServerCreate: + +rtems_interrupt_server_create() +------------------------------- + +Creates an interrupt server. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_server_create( + rtems_interrupt_server_control *control, + const rtems_interrupt_server_config *config, + uint32_t *server_index + ); + +.. rubric:: PARAMETERS: + +``control`` + This parameter is the pointer to an + :ref:`InterfaceRtemsInterruptServerControl` object. When the directive + call was successful, the ownership of the object was transferred from the + caller of the directive to the interrupt server management. + +``config`` + This parameter is the interrupt server configuration. + +``server_index`` + This parameter is the pointer to an `uint32_t + <https://en.cppreference.com/w/c/types/integer>`_ object. When the + directive call was successful, the index of the created interrupt server + will be stored in this object. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +The directive uses :ref:`InterfaceRtemsTaskCreate`. If this directive fails, +then its error status will be returned. + +.. rubric:: NOTES: + +See also :ref:`InterfaceRtemsInterruptServerInitialize` and +:ref:`InterfaceRtemsInterruptServerDelete`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. + +.. Generated from spec:/rtems/intr/if/server-handler-install + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_server_handler_install() + +.. _InterfaceRtemsInterruptServerHandlerInstall: + +rtems_interrupt_server_handler_install() +---------------------------------------- + +Installs the interrupt handler routine and argument at the interrupt vector on +the interrupt server. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_server_handler_install( + uint32_t server_index, + rtems_vector_number vector, + const char *info, + rtems_option options, + rtems_interrupt_handler routine, + void *arg + ); + +.. rubric:: PARAMETERS: + +``server_index`` + This parameter is the interrupt server index. The constant + :c:macro:`RTEMS_INTERRUPT_SERVER_DEFAULT` may be used to specify the + default interrupt server. + +``vector`` + This parameter is the interrupt vector number. + +``info`` + This parameter is the descriptive information of the interrupt handler to + install. + +``options`` + This parameter is the interrupt handler install option set. + +``routine`` + This parameter is the interrupt handler routine to install. + +``arg`` + This parameter is the interrupt handler argument to install. + +.. rubric:: DESCRIPTION: + +The handler routine specified by ``routine`` will be executed within the +context of the interrupt server task specified by ``server_index``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt server associated with the index specified by + ``server_index``. + +:c:macro:`RTEMS_CALLED_FROM_ISR` + The directive was called from within interrupt context. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``routine`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt vector associated with the number specified by + ``vector``. + +:c:macro:`RTEMS_INVALID_NUMBER` + An option specified by ``info`` was not applicable. + +:c:macro:`RTEMS_RESOURCE_IN_USE` + The :c:macro:`RTEMS_INTERRUPT_UNIQUE` option was set in ``info`` and the + interrupt vector was already occupied by a handler. + +:c:macro:`RTEMS_RESOURCE_IN_USE` + The :c:macro:`RTEMS_INTERRUPT_SHARED` option was set in ``info`` and the + interrupt vector was already occupied by a unique handler. + +:c:macro:`RTEMS_TOO_MANY` + The handler specified by ``routine`` was already installed for the + interrupt vector specified by ``vector`` with an argument equal to the + argument specified by ``arg``. + +:c:macro:`RTEMS_UNSATISFIED` + The :c:macro:`RTEMS_INTERRUPT_REPLACE` option was set in ``info`` and no + handler to replace was installed. + +.. rubric:: NOTES: + +See also :ref:`InterfaceRtemsInterruptHandlerInstall`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. + +.. Generated from spec:/rtems/intr/if/server-handler-remove + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_server_handler_remove() + +.. _InterfaceRtemsInterruptServerHandlerRemove: + +rtems_interrupt_server_handler_remove() +--------------------------------------- + +Removes the interrupt handler routine and argument from the interrupt vector +and the interrupt server. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_server_handler_remove( + uint32_t server_index, + rtems_vector_number vector, + rtems_interrupt_handler routine, + void *arg + ); + +.. rubric:: PARAMETERS: + +``server_index`` + This parameter is the interrupt server index. The constant + :c:macro:`RTEMS_INTERRUPT_SERVER_DEFAULT` may be used to specify the + default interrupt server. + +``vector`` + This parameter is the interrupt vector number. + +``routine`` + This parameter is the interrupt handler routine to remove. + +``arg`` + This parameter is the interrupt handler argument to remove. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt server associated with the index specified by + ``server_index``. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt vector associated with the number specified by + ``vector``. + +:c:macro:`RTEMS_UNSATISFIED` + There was no handler routine and argument pair installed specified by + ``routine`` and ``arg``. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within task context. + +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. + +* The directive sends a request to another task and waits for a response. This + may cause the calling task to be blocked and unblocked. + +* The directive shall not be called from within the context of an interrupt + server. Calling the directive from within the context of an interrupt server + is undefined behaviour. + +.. Generated from spec:/rtems/intr/if/server-set-affinity + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_server_set_affinity() + +.. _InterfaceRtemsInterruptServerSetAffinity: + +rtems_interrupt_server_set_affinity() +------------------------------------- + +Sets the processor affinity of the interrupt server. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_server_set_affinity( + uint32_t server_index, + size_t affinity_size, + const cpu_set_t *affinity, + rtems_task_priority priority + ); + +.. rubric:: PARAMETERS: + +``server_index`` + This parameter is the interrupt server index. The constant + :c:macro:`RTEMS_INTERRUPT_SERVER_DEFAULT` may be used to specify the + default interrupt server. + +``affinity_size`` + This parameter is the size of the processor set referenced by ``affinity`` + in bytes. + +``affinity`` + This parameter is the pointer to a :c:type:`cpu_set_t` object. The + processor set defines the new processor affinity set of the interrupt + server. A set bit in the processor set means that the corresponding + processor shall be in the processor affinity set of the task, otherwise the + bit shall be cleared. + +``priority`` + This parameter is the new :term:`real priority` for the interrupt server. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt server associated with the index specified by + ``server_index``. + +The directive uses :ref:`InterfaceRtemsSchedulerIdentByProcessorSet`, +:ref:`InterfaceRtemsTaskSetScheduler`, and +:ref:`InterfaceRtemsTaskSetAffinity`. If one of these directive fails, then +its error status will be returned. + +.. rubric:: NOTES: + +The scheduler is set determined by the highest numbered processor in the +affinity set specified by ``affinity``. + +This operation is only reliable in case the interrupt server was suspended via +:ref:`InterfaceRtemsInterruptServerSuspend`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may change the processor affinity of a task. This may cause + the calling task to be preempted. + +* The directive may change the priority of a task. This may cause the calling + task to be preempted. + +.. Generated from spec:/rtems/intr/if/server-delete + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_server_delete() + +.. _InterfaceRtemsInterruptServerDelete: + +rtems_interrupt_server_delete() +------------------------------- + +Deletes the interrupt server. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_server_delete( uint32_t server_index ); + +.. rubric:: PARAMETERS: + +``server_index`` + This parameter is the index of the interrupt server to delete. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt server associated with the server index specified by + ``server_index``. + +.. rubric:: NOTES: + +The interrupt server deletes itself, so after the return of the directive the +interrupt server may be still in the termination process depending on the task +priorities of the system. + +See also :ref:`InterfaceRtemsInterruptServerCreate`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within task context. + +* The directive shall not be called from within the context of an interrupt + server. Calling the directive from within the context of an interrupt server + is undefined behaviour. + +* The directive sends a request to another task and waits for a response. This + may cause the calling task to be blocked and unblocked. + +.. Generated from spec:/rtems/intr/if/server-suspend + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_server_suspend() + +.. _InterfaceRtemsInterruptServerSuspend: + +rtems_interrupt_server_suspend() +-------------------------------- + +Suspends the interrupt server. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_server_suspend( uint32_t server_index ); + +.. rubric:: PARAMETERS: + +``server_index`` + This parameter is the index of the interrupt server to suspend. The + constant :c:macro:`RTEMS_INTERRUPT_SERVER_DEFAULT` may be used to specify + the default interrupt server. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt server associated with the index specified by + ``server_index``. + +.. rubric:: NOTES: + +Interrupt server may be resumed by :ref:`InterfaceRtemsInterruptServerResume`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within task context. + +* The directive shall not be called from within the context of an interrupt + server. Calling the directive from within the context of an interrupt server + is undefined behaviour. + +* The directive sends a request to another task and waits for a response. This + may cause the calling task to be blocked and unblocked. + +.. Generated from spec:/rtems/intr/if/server-resume + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_server_resume() + +.. _InterfaceRtemsInterruptServerResume: + +rtems_interrupt_server_resume() +------------------------------- + +Resumes the interrupt server. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_server_resume( uint32_t server_index ); + +.. rubric:: PARAMETERS: + +``server_index`` + This parameter is the index of the interrupt server to resume. The + constant :c:macro:`RTEMS_INTERRUPT_SERVER_DEFAULT` may be used to specify + the default interrupt server. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt server associated with the index specified by + ``server_index``. + +.. rubric:: NOTES: + +Interrupt server may be suspended by +:ref:`InterfaceRtemsInterruptServerSuspend`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within task context. + +* The directive shall not be called from within the context of an interrupt + server. Calling the directive from within the context of an interrupt server + is undefined behaviour. + +* The directive sends a request to another task and waits for a response. This + may cause the calling task to be blocked and unblocked. + +.. Generated from spec:/rtems/intr/if/server-move + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_server_move() + +.. _InterfaceRtemsInterruptServerMove: + +rtems_interrupt_server_move() +----------------------------- + +Moves the interrupt handlers installed at the interrupt vector and the source +interrupt server to the destination interrupt server. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_server_move( + uint32_t source_server_index, + rtems_vector_number vector, + uint32_t destination_server_index + ); + +.. rubric:: PARAMETERS: + +``source_server_index`` + This parameter is the index of the source interrupt server. The constant + :c:macro:`RTEMS_INTERRUPT_SERVER_DEFAULT` may be used to specify the + default interrupt server. + +``vector`` + This parameter is the interrupt vector number. + +``destination_server_index`` + This parameter is the index of the destination interrupt server. The + constant :c:macro:`RTEMS_INTERRUPT_SERVER_DEFAULT` may be used to specify + the default interrupt server. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt server associated with the index specified by + ``source_server_index``. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt server associated with the index specified by + ``destination_server_index``. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt vector associated with the number specified by + ``vector``. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within task context. + +* The directive shall not be called from within the context of an interrupt + server. Calling the directive from within the context of an interrupt server + is undefined behaviour. + +* The directive sends a request to another task and waits for a response. This + may cause the calling task to be blocked and unblocked. + +.. Generated from spec:/rtems/intr/if/server-handler-iterate + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_server_handler_iterate() + +.. _InterfaceRtemsInterruptServerHandlerIterate: + +rtems_interrupt_server_handler_iterate() +---------------------------------------- + +Iterates over all interrupt handler installed at the interrupt vector and +interrupt server. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_server_handler_iterate( + uint32_t server_index, + rtems_vector_number vector, + rtems_interrupt_per_handler_routine routine, + void *arg + ); + +.. rubric:: PARAMETERS: + +``server_index`` + This parameter is the index of the interrupt server. + +``vector`` + This parameter is the interrupt vector number. + +``routine`` + This parameter is the visitor routine. + +``arg`` + This parameter is the visitor argument. + +.. rubric:: DESCRIPTION: + +For each installed handler at the interrupt vector and interrupt server the +visitor function specified by ``vector`` will be called with the argument +specified by ``routine`` and the handler information, options, routine and +argument. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt server associated with the index specified by + ``server_index``. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt vector associated with the number specified by + ``vector``. + +.. rubric:: NOTES: + +The directive is intended for system information and diagnostics. + +Never install or remove an interrupt handler within the visitor function. This +may result in a deadlock. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. + +.. Generated from spec:/rtems/intr/if/server-entry-initialize + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_server_entry_initialize() + +.. _InterfaceRtemsInterruptServerEntryInitialize: + +rtems_interrupt_server_entry_initialize() +----------------------------------------- + +Initializes the interrupt server entry. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_server_entry_initialize( + uint32_t server_index, + rtems_interrupt_server_entry *entry + ); + +.. rubric:: PARAMETERS: + +``server_index`` + This parameter is the interrupt server index. The constant + :c:macro:`RTEMS_INTERRUPT_SERVER_DEFAULT` may be used to specify the + default interrupt server. + +``entry`` + This parameter is the interrupt server entry to initialize. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt server associated with the index specified by + ``server_index``. + +.. rubric:: NOTES: + +After initialization, the list of actions of the interrupt server entry is +empty. Actions may be prepended by +:ref:`InterfaceRtemsInterruptServerActionPrepend`. Interrupt server entries may +be moved to another interrupt vector with +:ref:`InterfaceRtemsInterruptServerEntryMove`. Server entries may be submitted +to get serviced by the interrupt server with +:ref:`InterfaceRtemsInterruptServerEntrySubmit`. Server entries may be +destroyed by :ref:`InterfaceRtemsInterruptServerEntryDestroy`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. + +.. Generated from spec:/rtems/intr/if/server-action-prepend + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_server_action_prepend() + +.. _InterfaceRtemsInterruptServerActionPrepend: + +rtems_interrupt_server_action_prepend() +--------------------------------------- + +Prepends the interrupt server action to the list of actions of the interrupt +server entry. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_interrupt_server_action_prepend( + rtems_interrupt_server_entry *entry, + rtems_interrupt_server_action *action, + rtems_interrupt_handler routine, + void *arg + ); + +.. rubric:: PARAMETERS: + +``entry`` + This parameter is the interrupt server entry to prepend the interrupt + server action. It shall have been initialized via + :ref:`InterfaceRtemsInterruptServerEntryInitialize`. + +``action`` + This parameter is the interrupt server action to initialize and prepend to + the list of actions of the entry. + +``routine`` + This parameter is the interrupt handler routine to set in the action. + +``arg`` + This parameter is the interrupt handler argument to set in the action. + +.. rubric:: NOTES: + +No error checking is performed by the directive. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +* The interrupt server entry shall have been initialized by + :ref:`InterfaceRtemsInterruptServerEntryInitialize` and further optional + calls to :ref:`InterfaceRtemsInterruptServerActionPrepend`. + +* The directive shall not be called concurrently with + :ref:`InterfaceRtemsInterruptServerActionPrepend` with the same interrupt + server entry. Calling the directive under this condition is undefined + behaviour. + +* The directive shall not be called concurrently with + :ref:`InterfaceRtemsInterruptServerEntryMove` with the same interrupt server + entry. Calling the directive under this condition is undefined behaviour. + +* The directive shall not be called concurrently with + :ref:`InterfaceRtemsInterruptServerEntrySubmit` with the same interrupt + server entry. Calling the directive under this condition is undefined + behaviour. + +* The directive shall not be called while the interrupt server entry is pending + on or serviced by its current interrupt server. Calling the directive under + these conditions is undefined behaviour. + +.. Generated from spec:/rtems/intr/if/server-entry-destroy + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_server_entry_destroy() + +.. _InterfaceRtemsInterruptServerEntryDestroy: + +rtems_interrupt_server_entry_destroy() +-------------------------------------- + +Destroys the interrupt server entry. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_interrupt_server_entry_destroy( + rtems_interrupt_server_entry *entry + ); + +.. rubric:: PARAMETERS: + +``entry`` + This parameter is the interrupt server entry to destroy. + +.. rubric:: NOTES: + +No error checking is performed by the directive. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within task context. + +* The directive shall not be called from within the context of an interrupt + server. Calling the directive from within the context of an interrupt server + is undefined behaviour. + +* The directive sends a request to another task and waits for a response. This + may cause the calling task to be blocked and unblocked. + +* The interrupt server entry shall have been initialized by + :ref:`InterfaceRtemsInterruptServerEntryInitialize` and further optional + calls to :ref:`InterfaceRtemsInterruptServerActionPrepend`. + +.. Generated from spec:/rtems/intr/if/server-entry-submit + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_server_entry_submit() + +.. _InterfaceRtemsInterruptServerEntrySubmit: + +rtems_interrupt_server_entry_submit() +------------------------------------- + +Submits the interrupt server entry to be serviced by the interrupt server. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_interrupt_server_entry_submit( + rtems_interrupt_server_entry *entry + ); + +.. rubric:: PARAMETERS: + +``entry`` + This parameter is the interrupt server entry to submit. + +.. rubric:: DESCRIPTION: + +The directive appends the entry to the pending entries of the interrupt server. +The interrupt server is notified that a new entry is pending. Once the +interrupt server is scheduled it services the actions of all pending entries. + +.. rubric:: NOTES: + +This directive may be used to do a two-step interrupt processing. The first +step is done from within interrupt context by a call to this directive. The +second step is then done from within the context of the interrupt server. + +No error checking is performed by the directive. + +A submitted entry may be destroyed by +:ref:`InterfaceRtemsInterruptServerEntryDestroy`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may unblock a task. This may cause the calling task to be + preempted. + +* The interrupt server entry shall have been initialized by + :ref:`InterfaceRtemsInterruptServerEntryInitialize` and further optional + calls to :ref:`InterfaceRtemsInterruptServerActionPrepend`. + +* The directive shall not be called concurrently with + :ref:`InterfaceRtemsInterruptServerActionPrepend` with the same interrupt + server entry. Calling the directive under this condition is undefined + behaviour. + +* The directive shall not be called concurrently with + :ref:`InterfaceRtemsInterruptServerEntryMove` with the same interrupt server + entry. Calling the directive under this condition is undefined behaviour. + +.. Generated from spec:/rtems/intr/if/server-entry-move + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_server_entry_move() + +.. _InterfaceRtemsInterruptServerEntryMove: + +rtems_interrupt_server_entry_move() +----------------------------------- + +Moves the interrupt server entry to the interrupt server. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_server_entry_move( + rtems_interrupt_server_entry *entry, + uint32_t server_index + ); + +.. rubric:: PARAMETERS: + +``entry`` + This parameter is the interrupt server entry to move. + +``server_index`` + This parameter is the index of the destination interrupt server. The + constant :c:macro:`RTEMS_INTERRUPT_SERVER_DEFAULT` may be used to specify + the default interrupt server. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt server associated with the index specified by + ``server_index``. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. + +* The interrupt server entry shall have been initialized by + :ref:`InterfaceRtemsInterruptServerEntryInitialize` and further optional + calls to :ref:`InterfaceRtemsInterruptServerActionPrepend`. + +* The directive shall not be called concurrently with + :ref:`InterfaceRtemsInterruptServerActionPrepend` with the same interrupt + server entry. Calling the directive under this condition is undefined + behaviour. + +* The directive shall not be called concurrently with + :ref:`InterfaceRtemsInterruptServerEntryMove` with the same interrupt server + entry. Calling the directive under this condition is undefined behaviour. + +* The directive shall not be called concurrently with + :ref:`InterfaceRtemsInterruptServerEntrySubmit` with the same interrupt + server entry. Calling the directive under this condition is undefined + behaviour. + +* The directive shall not be called while the interrupt server entry is pending + on or serviced by its current interrupt server. Calling the directive under + these conditions is undefined behaviour. + +.. Generated from spec:/rtems/intr/if/server-request-initialize + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_server_request_initialize() + +.. _InterfaceRtemsInterruptServerRequestInitialize: + +rtems_interrupt_server_request_initialize() +------------------------------------------- + +Initializes the interrupt server request. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_server_request_initialize( + uint32_t server_index, + rtems_interrupt_server_request *request, + rtems_interrupt_handler routine, + void *arg + ); + +.. rubric:: PARAMETERS: + +``server_index`` + This parameter is the interrupt server index. The constant + :c:macro:`RTEMS_INTERRUPT_SERVER_DEFAULT` may be used to specify the + default interrupt server. + +``request`` + This parameter is the interrupt server request to initialize. + +``routine`` + This parameter is the interrupt handler routine for the request action. + +``arg`` + This parameter is the interrupt handler argument for the request action. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no interrupt server associated with the index specified by + ``server_index``. + +.. rubric:: NOTES: + +An interrupt server requests consists of an interrupt server entry and exactly +one interrupt server action. The interrupt vector of the request may be +changed with :ref:`InterfaceRtemsInterruptServerRequestSetVector`. Interrupt +server requests may be submitted to get serviced by the interrupt server with +:ref:`InterfaceRtemsInterruptServerRequestSubmit`. Requests may be destroyed +by :ref:`InterfaceRtemsInterruptServerRequestDestroy`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. + +.. Generated from spec:/rtems/intr/if/server-request-set-vector + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_server_request_set_vector() + +.. _InterfaceRtemsInterruptServerRequestSetVector: + +rtems_interrupt_server_request_set_vector() +------------------------------------------- + +Sets the interrupt vector in the interrupt server request. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_interrupt_server_request_set_vector( + rtems_interrupt_server_request *request, + rtems_vector_number vector + ); + +.. rubric:: PARAMETERS: + +``request`` + This parameter is the interrupt server request to change. + +``vector`` + This parameter is the interrupt vector number to be used by the request. + +.. rubric:: NOTES: + +By default, the interrupt vector of an interrupt server request is set to a +special value which is outside the range of vectors supported by the interrupt +controller hardware. + +Calls to :ref:`InterfaceRtemsInterruptServerRequestSubmit` will disable the +interrupt vector of the request. After processing of the request by the +interrupt server the interrupt vector will be enabled again. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +* The interrupt server request shall have been initialized by + :ref:`InterfaceRtemsInterruptServerRequestInitialize`. + +* The directive shall not be called concurrently with + :ref:`InterfaceRtemsInterruptServerRequestSetVector` with the same interrupt + server request. Calling the directive under this condition is undefined + behaviour. + +* The directive shall not be called concurrently with + :ref:`InterfaceRtemsInterruptServerRequestSubmit` with the same interrupt + server request. Calling the directive under this condition is undefined + behaviour. + +* The directive shall not be called while the interrupt server entry is pending + on or serviced by its current interrupt server. Calling the directive under + these conditions is undefined behaviour. + +.. Generated from spec:/rtems/intr/if/server-request-destroy + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_server_request_destroy() + +.. _InterfaceRtemsInterruptServerRequestDestroy: + +rtems_interrupt_server_request_destroy() +---------------------------------------- + +Destroys the interrupt server request. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_interrupt_server_request_destroy( + rtems_interrupt_server_request *request + ); + +.. rubric:: PARAMETERS: + +``request`` + This parameter is the interrupt server request to destroy. + +.. rubric:: NOTES: + +No error checking is performed by the directive. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within task context. + +* The directive shall not be called from within the context of an interrupt + server. Calling the directive from within the context of an interrupt server + is undefined behaviour. + +* The directive sends a request to another task and waits for a response. This + may cause the calling task to be blocked and unblocked. + +* The interrupt server request shall have been initialized by + :ref:`InterfaceRtemsInterruptServerRequestInitialize`. + +.. Generated from spec:/rtems/intr/if/server-request-submit + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_server_request_submit() + +.. _InterfaceRtemsInterruptServerRequestSubmit: + +rtems_interrupt_server_request_submit() +--------------------------------------- + +Submits the interrupt server request to be serviced by the interrupt server. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_interrupt_server_request_submit( + rtems_interrupt_server_request *request + ); + +.. rubric:: PARAMETERS: + +``request`` + This parameter is the interrupt server request to submit. + +.. rubric:: DESCRIPTION: + +The directive appends the interrupt server entry of the request to the pending +entries of the interrupt server. The interrupt server is notified that a new +entry is pending. Once the interrupt server is scheduled it services the +actions of all pending entries. + +.. rubric:: NOTES: + +This directive may be used to do a two-step interrupt processing. The first +step is done from within interrupt context by a call to this directive. The +second step is then done from within the context of the interrupt server. + +No error checking is performed by the directive. + +A submitted request may be destroyed by +:ref:`InterfaceRtemsInterruptServerRequestDestroy`. + +.. rubric:: CONSTRAINTS: -.. _rtems_interrupt_is_in_progress: +The following constraints apply to this directive: -INTERRUPT_IS_IN_PROGRESS - Is an ISR in Progress ------------------------------------------------- +* The directive may be called from within interrupt context. -CALLING SEQUENCE: - .. code-block:: c +* The directive may be called from within device driver initialization context. - bool rtems_interrupt_is_in_progress( void ); +* The directive may be called from within task context. -DIRECTIVE STATUS CODES: - NONE +* The directive may unblock a task. This may cause the calling task to be + preempted. -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. +* The interrupt server request shall have been initialized by + :ref:`InterfaceRtemsInterruptServerRequestInitialize`. -NOTES: - This directive will not cause the calling task to be preempted. +* The directive shall not be called concurrently with + :ref:`InterfaceRtemsInterruptServerRequestSetVector` with the same interrupt + server request. Calling the directive under this condition is undefined + behaviour. diff --git a/c-user/interrupt/index.rst b/c-user/interrupt/index.rst index d3e4429..92d332d 100644 --- a/c-user/interrupt/index.rst +++ b/c-user/interrupt/index.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020 embedded brains GmbH & Co. KG .. index:: interrupts diff --git a/c-user/interrupt/introduction.rst b/c-user/interrupt/introduction.rst index 272eba2..14ea275 100644 --- a/c-user/interrupt/introduction.rst +++ b/c-user/interrupt/introduction.rst @@ -1,37 +1,241 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 +.. Copyright (C) 2008, 2022 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/rtems/intr/if/group + +.. _InterruptManagerIntroduction: + Introduction ============ +.. The following list was generated from: +.. spec:/rtems/intr/if/catch +.. spec:/rtems/intr/if/disable +.. spec:/rtems/intr/if/enable +.. spec:/rtems/intr/if/flash +.. spec:/rtems/intr/if/local-disable +.. spec:/rtems/intr/if/local-enable +.. spec:/rtems/intr/if/is-in-progress +.. spec:/rtems/intr/if/lock-initialize +.. spec:/rtems/intr/if/lock-destroy +.. spec:/rtems/intr/if/lock-acquire +.. spec:/rtems/intr/if/lock-release +.. spec:/rtems/intr/if/lock-acquire-isr +.. spec:/rtems/intr/if/lock-release-isr +.. spec:/rtems/intr/if/lock-isr-disable +.. spec:/rtems/intr/if/lock-declare +.. spec:/rtems/intr/if/lock-define +.. spec:/rtems/intr/if/lock-initializer +.. spec:/rtems/intr/if/lock-member +.. spec:/rtems/intr/if/lock-reference +.. spec:/rtems/intr/if/entry-initializer +.. spec:/rtems/intr/if/entry-initialize +.. spec:/rtems/intr/if/entry-install +.. spec:/rtems/intr/if/entry-remove +.. spec:/rtems/intr/if/handler-install +.. spec:/rtems/intr/if/handler-remove +.. spec:/rtems/intr/if/vector-is-enabled +.. spec:/rtems/intr/if/vector-enable +.. spec:/rtems/intr/if/vector-disable +.. spec:/rtems/intr/if/is-pending +.. spec:/rtems/intr/if/raise +.. spec:/rtems/intr/if/raise-on +.. spec:/rtems/intr/if/clear +.. spec:/rtems/intr/if/get-affinity +.. spec:/rtems/intr/if/set-affinity +.. spec:/rtems/intr/if/get-attributes +.. spec:/rtems/intr/if/handler-iterate +.. spec:/rtems/intr/if/server-initialize +.. spec:/rtems/intr/if/server-create +.. spec:/rtems/intr/if/server-handler-install +.. spec:/rtems/intr/if/server-handler-remove +.. spec:/rtems/intr/if/server-set-affinity +.. spec:/rtems/intr/if/server-delete +.. spec:/rtems/intr/if/server-suspend +.. spec:/rtems/intr/if/server-resume +.. spec:/rtems/intr/if/server-move +.. spec:/rtems/intr/if/server-handler-iterate +.. spec:/rtems/intr/if/server-entry-initialize +.. spec:/rtems/intr/if/server-action-prepend +.. spec:/rtems/intr/if/server-entry-destroy +.. spec:/rtems/intr/if/server-entry-submit +.. spec:/rtems/intr/if/server-entry-move +.. spec:/rtems/intr/if/server-request-initialize +.. spec:/rtems/intr/if/server-request-set-vector +.. spec:/rtems/intr/if/server-request-destroy +.. spec:/rtems/intr/if/server-request-submit + Any real-time executive must provide a mechanism for quick response to externally generated interrupts to satisfy the critical time constraints of the -application. The interrupt manager provides this mechanism for RTEMS. This +application. The Interrupt Manager provides this mechanism for RTEMS. This manager permits quick interrupt response times by providing the critical ability to alter task execution which allows a task to be preempted upon exit -from an ISR. The interrupt manager includes the following directive: +from an ISR. The directives provided by the Interrupt Manager are: + +* :ref:`InterfaceRtemsInterruptCatch` - Establishes an interrupt service + routine. + +* :ref:`InterfaceRtemsInterruptDisable` - Disables the maskable interrupts on + the current processor. + +* :ref:`InterfaceRtemsInterruptEnable` - Restores the previous interrupt level + on the current processor. + +* :ref:`InterfaceRtemsInterruptFlash` - Flashes interrupts on the current + processor. + +* :ref:`InterfaceRtemsInterruptLocalDisable` - Disables the maskable interrupts + on the current processor. + +* :ref:`InterfaceRtemsInterruptLocalEnable` - Restores the previous interrupt + level on the current processor. + +* :ref:`InterfaceRtemsInterruptIsInProgress` - Checks if an ISR is in progress + on the current processor. + +* :ref:`InterfaceRtemsInterruptLockInitialize` - Initializes the ISR lock. + +* :ref:`InterfaceRtemsInterruptLockDestroy` - Destroys the ISR lock. + +* :ref:`InterfaceRtemsInterruptLockAcquire` - Acquires the ISR lock. + +* :ref:`InterfaceRtemsInterruptLockRelease` - Releases the ISR lock. + +* :ref:`InterfaceRtemsInterruptLockAcquireIsr` - Acquires the ISR lock from + within an ISR. + +* :ref:`InterfaceRtemsInterruptLockReleaseIsr` - Releases the ISR lock from + within an ISR. + +* :ref:`InterfaceRtemsInterruptLockInterruptDisable` - Disables maskable + interrupts on the current processor. + +* :ref:`InterfaceRTEMSINTERRUPTLOCKDECLARE` - Declares an ISR lock object. + +* :ref:`InterfaceRTEMSINTERRUPTLOCKDEFINE` - Defines an ISR lock object. + +* :ref:`InterfaceRTEMSINTERRUPTLOCKINITIALIZER` - Statically initializes an ISR + lock object. + +* :ref:`InterfaceRTEMSINTERRUPTLOCKMEMBER` - Defines an ISR lock member. + +* :ref:`InterfaceRTEMSINTERRUPTLOCKREFERENCE` - Defines an ISR lock object + reference. + +* :ref:`InterfaceRTEMSINTERRUPTENTRYINITIALIZER` - Statically initializes an + interrupt entry object. + +* :ref:`InterfaceRtemsInterruptEntryInitialize` - Initializes the interrupt + entry. + +* :ref:`InterfaceRtemsInterruptEntryInstall` - Installs the interrupt entry at + the interrupt vector. + +* :ref:`InterfaceRtemsInterruptEntryRemove` - Removes the interrupt entry from + the interrupt vector. + +* :ref:`InterfaceRtemsInterruptHandlerInstall` - Installs the interrupt handler + routine and argument at the interrupt vector. + +* :ref:`InterfaceRtemsInterruptHandlerRemove` - Removes the interrupt handler + routine and argument from the interrupt vector. + +* :ref:`InterfaceRtemsInterruptVectorIsEnabled` - Checks if the interrupt + vector is enabled. + +* :ref:`InterfaceRtemsInterruptVectorEnable` - Enables the interrupt vector. + +* :ref:`InterfaceRtemsInterruptVectorDisable` - Disables the interrupt vector. + +* :ref:`InterfaceRtemsInterruptIsPending` - Checks if the interrupt is pending. + +* :ref:`InterfaceRtemsInterruptRaise` - Raises the interrupt vector. + +* :ref:`InterfaceRtemsInterruptRaiseOn` - Raises the interrupt vector on the + processor. + +* :ref:`InterfaceRtemsInterruptClear` - Clears the interrupt vector. + +* :ref:`InterfaceRtemsInterruptGetAffinity` - Gets the processor affinity set + of the interrupt vector. + +* :ref:`InterfaceRtemsInterruptSetAffinity` - Sets the processor affinity set + of the interrupt vector. + +* :ref:`InterfaceRtemsInterruptGetAttributes` - Gets the attributes of the + interrupt vector. + +* :ref:`InterfaceRtemsInterruptHandlerIterate` - Iterates over all interrupt + handler installed at the interrupt vector. + +* :ref:`InterfaceRtemsInterruptServerInitialize` - Initializes the interrupt + server tasks. + +* :ref:`InterfaceRtemsInterruptServerCreate` - Creates an interrupt server. + +* :ref:`InterfaceRtemsInterruptServerHandlerInstall` - Installs the interrupt + handler routine and argument at the interrupt vector on the interrupt server. + +* :ref:`InterfaceRtemsInterruptServerHandlerRemove` - Removes the interrupt + handler routine and argument from the interrupt vector and the interrupt + server. + +* :ref:`InterfaceRtemsInterruptServerSetAffinity` - Sets the processor affinity + of the interrupt server. + +* :ref:`InterfaceRtemsInterruptServerDelete` - Deletes the interrupt server. + +* :ref:`InterfaceRtemsInterruptServerSuspend` - Suspends the interrupt server. -- :ref:`rtems_interrupt_catch` +* :ref:`InterfaceRtemsInterruptServerResume` - Resumes the interrupt server. -- :ref:`rtems_interrupt_disable` +* :ref:`InterfaceRtemsInterruptServerMove` - Moves the interrupt handlers + installed at the interrupt vector and the source interrupt server to the + destination interrupt server. -- :ref:`rtems_interrupt_enable` +* :ref:`InterfaceRtemsInterruptServerHandlerIterate` - Iterates over all + interrupt handler installed at the interrupt vector and interrupt server. -- :ref:`rtems_interrupt_flash` +* :ref:`InterfaceRtemsInterruptServerEntryInitialize` - Initializes the + interrupt server entry. -- :ref:`rtems_interrupt_local_disable` +* :ref:`InterfaceRtemsInterruptServerActionPrepend` - Prepends the interrupt + server action to the list of actions of the interrupt server entry. -- :ref:`rtems_interrupt_local_enable` +* :ref:`InterfaceRtemsInterruptServerEntryDestroy` - Destroys the interrupt + server entry. -- :ref:`rtems_interrupt_lock_initialize` +* :ref:`InterfaceRtemsInterruptServerEntrySubmit` - Submits the interrupt + server entry to be serviced by the interrupt server. -- :ref:`rtems_interrupt_lock_acquire` +* :ref:`InterfaceRtemsInterruptServerEntryMove` - Moves the interrupt server + entry to the interrupt server. -- :ref:`rtems_interrupt_lock_release` +* :ref:`InterfaceRtemsInterruptServerRequestInitialize` - Initializes the + interrupt server request. -- :ref:`rtems_interrupt_lock_acquire_isr` +* :ref:`InterfaceRtemsInterruptServerRequestSetVector` - Sets the interrupt + vector in the interrupt server request. -- :ref:`rtems_interrupt_lock_release_isr` +* :ref:`InterfaceRtemsInterruptServerRequestDestroy` - Destroys the interrupt + server request. -- :ref:`rtems_interrupt_is_in_progress` +* :ref:`InterfaceRtemsInterruptServerRequestSubmit` - Submits the interrupt + server request to be serviced by the interrupt server. diff --git a/c-user/io/directives.rst b/c-user/io/directives.rst index 0683c4c..7def56a 100644 --- a/c-user/io/directives.rst +++ b/c-user/io/directives.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) .. This file is part of the RTEMS quality process and was automatically @@ -64,9 +64,9 @@ table and device major number in the Device Driver Table. This parameter is the device driver address table. ``registered_major`` - This parameter is the pointer to a device major number variable. When the - directive call is successful, the device major number of the registered - device will be stored in this variable. + This parameter is the pointer to an :ref:`InterfaceRtemsDeviceMajorNumber` + object. When the directive call is successful, the device major number of + the registered device will be stored in this object. .. rubric:: RETURN VALUES: diff --git a/c-user/io/index.rst b/c-user/io/index.rst index 424c776..b1147a9 100644 --- a/c-user/io/index.rst +++ b/c-user/io/index.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020 embedded brains GmbH & Co. KG .. index:: device drivers .. index:: IO Manager diff --git a/c-user/io/introduction.rst b/c-user/io/introduction.rst index 7d2c35d..95a5942 100644 --- a/c-user/io/introduction.rst +++ b/c-user/io/introduction.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) .. This file is part of the RTEMS quality process and was automatically diff --git a/c-user/kernel-character-io/directives.rst b/c-user/kernel-character-io/directives.rst new file mode 100644 index 0000000..e0476fe --- /dev/null +++ b/c-user/kernel-character-io/directives.rst @@ -0,0 +1,372 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 2015 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. _KernelCharacterIOSupportDirectives: + +Directives +========== + +This section details the directives of the Kernel Character I/O Support. A +subsection is dedicated to each of this manager's directives and lists the +calling sequence, parameters, description, return values, and notes of the +directive. + +.. Generated from spec:/rtems/io/if/putc + +.. raw:: latex + + \clearpage + +.. index:: rtems_putc() + +.. _InterfaceRtemsPutc: + +rtems_putc() +------------ + +Outputs the character to the kernel character output device. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_putc( char c ); + +.. rubric:: PARAMETERS: + +``c`` + This parameter is the character to output. + +.. rubric:: DESCRIPTION: + +The directive outputs the character specified by ``c`` to the kernel character +output device using the polled character output implementation provided by +BSP_output_char. The directive performs a character translation from ``NL`` to +``CR`` followed by ``NR``. + +If the kernel character output device is concurrently accessed, then +interleaved output may occur. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/io/if/put-char + +.. raw:: latex + + \clearpage + +.. index:: rtems_put_char() + +.. _InterfaceRtemsPutChar: + +rtems_put_char() +---------------- + +Puts the character using :ref:`InterfaceRtemsPutc` + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_put_char( int c, void *unused ); + +.. rubric:: PARAMETERS: + +``c`` + This parameter is the character to output. + +``unused`` + This parameter is an unused argument. + +.. rubric:: NOTES: + +The directive is provided to support the RTEMS Testing Framework. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/io/if/putk + +.. raw:: latex + + \clearpage + +.. index:: putk() + +.. _InterfacePutk: + +putk() +------ + +Outputs the characters of the string and a newline character to the kernel +character output device. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + int putk( const char *s ); + +.. rubric:: PARAMETERS: + +``s`` + This parameter is the string to output. + +.. rubric:: RETURN VALUES: + +Returns the number of characters output to the kernel character output device. + +.. rubric:: NOTES: + +The directive may be used to print debug and test information. It uses +:ref:`InterfaceRtemsPutc` to output the characters. This directive performs a +character translation from ``NL`` to ``CR`` followed by ``NR``. + +If the kernel character output device is concurrently accessed, then +interleaved output may occur. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/io/if/printk + +.. raw:: latex + + \clearpage + +.. index:: printk() + +.. _InterfacePrintk: + +printk() +-------- + +Outputs the characters defined by the format string and the arguments to the +kernel character output device. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + int printk( const char *fmt, ... ); + +.. rubric:: PARAMETERS: + +``fmt`` + This parameter is a printf()-style format string. + +``...`` + This parameter is a list of optional parameters required by the format + string. + +.. rubric:: RETURN VALUES: + +Returns the number of characters output to the kernel character output device. + +.. rubric:: NOTES: + +The directive may be used to print debug and test information. It uses +:ref:`InterfaceRtemsPutc` to output the characters. This directive performs a +character translation from ``NL`` to ``CR`` followed by ``NR``. + +If the kernel character output device is concurrently accessed, then +interleaved output may occur. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +* Formatting of floating point numbers is not supported. + +.. Generated from spec:/rtems/io/if/vprintk + +.. raw:: latex + + \clearpage + +.. index:: vprintk() + +.. _InterfaceVprintk: + +vprintk() +--------- + +Outputs the characters defined by the format string and the variable argument +list to the kernel character output device. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + int vprintk( const char *fmt, va_list ap ); + +.. rubric:: PARAMETERS: + +``fmt`` + This parameter is a printf()-style format string. + +``ap`` + This parameter is the variable argument list required by the format string. + +.. rubric:: RETURN VALUES: + +Returns the number of characters output to the kernel character output device. + +.. rubric:: NOTES: + +The directive may be used to print debug and test information. It uses +:ref:`InterfaceRtemsPutc` to output the characters. This directive performs a +character translation from ``NL`` to ``CR`` followed by ``NR``. + +If the kernel character output device is concurrently accessed, then +interleaved output may occur. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +* Formatting of floating point numbers is not supported. + +.. Generated from spec:/rtems/io/if/printk-printer + +.. raw:: latex + + \clearpage + +.. index:: rtems_printk_printer() + +.. _InterfaceRtemsPrintkPrinter: + +rtems_printk_printer() +---------------------- + +Outputs the characters defined by the format string and the variable argument +list to the kernel character output device. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + int rtems_printk_printer( void *unused, const char *fmt, va_list ap ); + +.. rubric:: PARAMETERS: + +``unused`` + This parameter is an unused argument. + +``fmt`` + This parameter is a printf()-style format string. + +``ap`` + This parameter is the variable argument list required by the format string. + +.. rubric:: RETURN VALUES: + +Returns the number of characters output to the kernel character output device. + +.. rubric:: NOTES: + +The directive may be used to print debug and test information. It uses +:ref:`InterfaceRtemsPutc` to output the characters. This directive performs a +character translation from ``NL`` to ``CR`` followed by ``NR``. + +If the kernel character output device is concurrently accessed, then +interleaved output may occur. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +* Formatting of floating point numbers is not supported. + +.. Generated from spec:/rtems/io/if/getchark + +.. raw:: latex + + \clearpage + +.. index:: getchark() + +.. _InterfaceGetchark: + +getchark() +---------- + +Tries to dequeue a character from the kernel character input device. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + int getchark( void ); + +.. rubric:: DESCRIPTION: + +The directive tries to dequeue a character from the kernel character input +device using the polled character input implementation referenced by +BSP_poll_char if it is available. + +.. rubric:: RETURN VALUES: + +``-1`` + The BSP_poll_char pointer was equal to `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +``-1`` + There was no character enqueued on the kernel character input device. + +Returns the character least recently enqueued on the kernel character input +device as an unsigned character value. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. diff --git a/c-user/kernel-character-io/index.rst b/c-user/kernel-character-io/index.rst new file mode 100644 index 0000000..2d1d13b --- /dev/null +++ b/c-user/kernel-character-io/index.rst @@ -0,0 +1,15 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2021 embedded brains GmbH & Co. KG + +.. index:: Kernel Character I/O Support + +.. _RTEMSAPIKernelCharIO: + +Kernel Character I/O Support +**************************** + +.. toctree:: + + introduction + directives diff --git a/c-user/kernel-character-io/introduction.rst b/c-user/kernel-character-io/introduction.rst new file mode 100644 index 0000000..dc3ac26 --- /dev/null +++ b/c-user/kernel-character-io/introduction.rst @@ -0,0 +1,69 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 2015 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/rtems/io/if/group-3 + +.. _KernelCharacterIOSupportIntroduction: + +Introduction +============ + +.. The following list was generated from: +.. spec:/rtems/io/if/putc +.. spec:/rtems/io/if/put-char +.. spec:/rtems/io/if/putk +.. spec:/rtems/io/if/printk +.. spec:/rtems/io/if/vprintk +.. spec:/rtems/io/if/printk-printer +.. spec:/rtems/io/if/getchark + +The kernel character input/output support is an extension of the +:ref:`RTEMSAPIClassicIO` to output characters to the kernel character output +device and receive characters from the kernel character input device using a +polled and non-blocking implementation. + +The directives may be used to print debug and test information. The kernel +character input/output support should work even if no Console Driver is +configured, see :ref:`CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`. The kernel +character input and output device is provided by the :term:`BSP`. Applications +may change the device. The directives provided by the Kernel Character I/O +Support are: + +* :ref:`InterfaceRtemsPutc` - Outputs the character to the kernel character + output device. + +* :ref:`InterfaceRtemsPutChar` - Puts the character using + :ref:`InterfaceRtemsPutc` + +* :ref:`InterfacePutk` - Outputs the characters of the string and a newline + character to the kernel character output device. + +* :ref:`InterfacePrintk` - Outputs the characters defined by the format string + and the arguments to the kernel character output device. + +* :ref:`InterfaceVprintk` - Outputs the characters defined by the format string + and the variable argument list to the kernel character output device. + +* :ref:`InterfaceRtemsPrintkPrinter` - Outputs the characters defined by the + format string and the variable argument list to the kernel character output + device. + +* :ref:`InterfaceGetchark` - Tries to dequeue a character from the kernel + character input device. diff --git a/c-user/key_concepts.rst b/c-user/key_concepts.rst index 6bc1c3e..fe8e90e 100644 --- a/c-user/key_concepts.rst +++ b/c-user/key_concepts.rst @@ -45,7 +45,7 @@ An object name is an unsigned thirty-two bit entity associated with the object by the user. The data type ``rtems_name`` is used to store object names. -.. index:: rtems_build_name +.. index:: rtems_build_name() Although not required by RTEMS, object names are often composed of four ASCII characters which help identify that object. For example, a task which causes a @@ -64,7 +64,7 @@ would be difficult to assign meaningful ASCII names to each task. A more convenient approach would be to name them the binary values one through one-hundred, respectively. -.. index:: rtems_object_get_name +.. index:: rtems_object_get_name() RTEMS provides a helper routine, ``rtems_object_get_name``, which can be used to obtain the name of any RTEMS object using just its ID. This routine @@ -85,18 +85,75 @@ name: printk( "ID=0x%08x name=%s\n", id, ((result) ? result : "no name") ); } -.. index:: object ID -.. index:: object ID composition +.. index:: object id +.. index:: object id composition .. index:: rtems_id -Object IDs +Object Ids ---------- -An object ID is a unique 32-bit unsigned integer value which uniquely -identifies an object instance. Object IDs are passed as arguments to many -directives in RTEMS and RTEMS translates the ID to an internal object pointer. -The efficient manipulation of object IDs is critical to the performance of some -RTEMS services. +an object id is a unique 32-bit unsigned integer value which uniquely +identifies an object instance. object ids are passed as arguments to many +directives in rtems and rtems translates the id to an internal object pointer. +the efficient manipulation of object ids is critical to the performance of some +rtems services. + +.. index:: rtems_extension_ident() +.. index:: rtems_barrier_ident() +.. index:: rtems_port_ident() +.. index:: rtems_message_queue_ident() +.. index:: rtems_partition_ident() +.. index:: rtems_region_ident() +.. index:: rtems_semaphore_ident() +.. index:: rtems_task_ident() +.. index:: rtems_timer_ident() + +There are multiple directives with names of the form +``rtems_@CLASS@_ident`` that take a name as argument and return the associated +id if the name is found. The following is the set of name to id services: +which can look up an object + +* ``rtems_extension_ident()`` +* ``rtems_barrier_ident()`` +* ``rtems_port_ident()`` +* ``rtems_message_queue_ident()`` +* ``rtems_partition_ident()`` +* ``rtems_region_ident()`` +* ``rtems_semaphore_ident()`` +* ``rtems_task_ident()`` +* ``rtems_timer_ident()`` + +Local and Global Scope +---------------------- + +.. index:: uniprocesor +.. index:: multiprocessing +.. index:: distributed multiprocessing +.. index:: symmetric multiprocessing (SMP) +.. index:: local scope +.. index:: global scope +.. index:: RTEMS_GLOBAL +.. index:: RTEMS_LOCAL +.. index:: RTEMS_GLOBAL + +RTEMS supports uniprocessing, distributed multiprocessing, and Symmetric +Multiprocessing (SMP) configurations. A uniprocessor system includes only +a single processor in a single node. Distributed multiprocessor systems +include multiple nodes, each of which is a single processor and is usually +referred to as just multiprocessor mode for historical reasons. SMP +systems consist of multiple processors cores in a single node. + +In distributed multiprocessing configurations, there are multiple nodes in +the system and object instances may be visible on just the creating node +or to all nodes. If visible only to the creating node, this is referred to +as **local scope** and corresponds to the RTEMS_LOCAL attribute setting +which is the default. If RTEMS GLOBAL is specified as part of the object +attributes, then the object instance has **global scope** and the object +id can be used anywhere in the system to identify that object instance. + +In uniprocessing and SMP configurations, there is only one node in +the system and object instances are locally scoped to that node. Any +attempt to create with the RTEMS_GLOBAL attribute is an error. Object ID Format ~~~~~~~~~~~~~~~~ @@ -122,6 +179,9 @@ sixteen bits form an identifier within a particular object type. This identifier, called the object index, ranges in value from 1 to the maximum number of objects configured for this object type. +None of the fields in an object id may be zero except for the special +case of RTEMS_SELF to indicate the currently running thread. + Object ID Description --------------------- @@ -150,10 +210,10 @@ prototyped as follows: .. index:: get class from object ID .. index:: get node from object ID .. index:: get index from object ID -.. index:: rtems_object_id_get_api -.. index:: rtems_object_id_get_class -.. index:: rtems_object_id_get_node -.. index:: rtems_object_id_get_index +.. index:: rtems_object_id_get_api() +.. index:: rtems_object_id_get_class() +.. index:: rtems_object_id_get_node() +.. index:: rtems_object_id_get_index() .. code-block:: c @@ -330,7 +390,7 @@ O(m) Independence-Preserving Protocol (OMIP) The :math:`O(m)` Independence-Preserving Protocol (OMIP) is a generalization of the priority inheritance protocol to clustered scheduling which avoids the -non-preemptive sections present with priority boosting +non-preemptive sections present with :term:`priority boosting` :cite:`Brandenburg:2013:OMIP`. The :math:`m` denotes the number of processors in the system. Similar to the uniprocessor priority inheritance protocol, the OMIP mutexes do not need any external configuration data, e.g. a ceiling diff --git a/c-user/linker_sets.rst b/c-user/linker_sets.rst index 8ad4846..74fc957 100644 --- a/c-user/linker_sets.rst +++ b/c-user/linker_sets.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2015, 2020 embedded brains GmbH +.. Copyright (C) 2015, 2020 embedded brains GmbH & Co. KG .. Copyright (C) 2015, 2020 Sebastian Huber .. index:: linkersets diff --git a/c-user/message/directives.rst b/c-user/message/directives.rst index 4d9bdc7..7039b2e 100644 --- a/c-user/message/directives.rst +++ b/c-user/message/directives.rst @@ -1,559 +1,1086 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. _MessageManagerDirectives: + Directives ========== -This section details the 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. +This section details the directives of the Message Manager. A subsection is +dedicated to each of this manager's directives and lists the calling sequence, +parameters, description, return values, and notes of the directive. + +.. Generated from spec:/rtems/message/if/create .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_message_queue_create() .. index:: create a message queue -.. index:: rtems_message_queue_create - -.. _rtems_message_queue_create: - -MESSAGE_QUEUE_CREATE - Create a queue -------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_message_queue_create( - rtems_name name, - uint32_t count, - size_t max_message_size, - rtems_attribute attribute_set, - rtems_id *id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - queue created successfully - * - ``RTEMS_INVALID_NAME`` - - invalid queue name - * - ``RTEMS_INVALID_ADDRESS`` - - ``id`` is NULL - * - ``RTEMS_INVALID_NUMBER`` - - invalid message count - * - ``RTEMS_INVALID_SIZE`` - - invalid message size - * - ``RTEMS_TOO_MANY`` - - too many queues created - * - ``RTEMS_UNSATISFIED`` - - unable to allocate message buffers - * - ``RTEMS_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 may cause the calling task to be preempted due to an - obtain and release of the object allocator mutex. - - 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. + +.. _InterfaceRtemsMessageQueueCreate: + +rtems_message_queue_create() +---------------------------- + +Creates a message queue. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_message_queue_create( + rtems_name name, + uint32_t count, + size_t max_message_size, + rtems_attribute attribute_set, + rtems_id *id + ); + +.. rubric:: PARAMETERS: + +``name`` + This parameter is the object name of the message queue. + +``count`` + This parameter is the maximum count of pending messages supported by the + message queue. + +``max_message_size`` + This parameter is the maximum size in bytes of a message supported by the + message queue. + +``attribute_set`` + This parameter is the attribute set of the message queue. + +``id`` + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the identifier of the created message + queue will be stored in this object. + +.. rubric:: DESCRIPTION: + +This directive creates a message queue which resides on the local node. The +message queue has the user-defined object name specified in ``name``. Memory +is allocated from the RTEMS Workspace for the count of messages specified in +``count``, each of ``max_message_size`` bytes in length. The assigned object +identifier is returned in ``id``. This identifier is used to access the +message queue with other message queue related directives. + +The **attribute set** specified in ``attribute_set`` is built through a +*bitwise or* of the attribute constants described below. Not all combinations +of attributes are allowed. Some attributes are mutually exclusive. If +mutually exclusive attributes are combined, the behaviour is undefined. +Attributes not mentioned below are not evaluated by this directive and have no +effect. Default attributes can be selected by using the +:c:macro:`RTEMS_DEFAULT_ATTRIBUTES` constant. The attribute set defines + +* the scope of the message queue: :c:macro:`RTEMS_LOCAL` (default) or + :c:macro:`RTEMS_GLOBAL` and + +* the task wait queue discipline used by the message queue: + :c:macro:`RTEMS_FIFO` (default) or :c:macro:`RTEMS_PRIORITY`. + +The message queue has a local or global **scope** in a multiprocessing network +(this attribute does not refer to SMP systems). The scope is selected by the +mutually exclusive :c:macro:`RTEMS_LOCAL` and :c:macro:`RTEMS_GLOBAL` +attributes. + +* A **local scope** is the default and can be emphasized through the use of the + :c:macro:`RTEMS_LOCAL` attribute. A local message queue can be only used by + the node which created it. + +* A **global scope** is established if the :c:macro:`RTEMS_GLOBAL` attribute is + set. Setting the global attribute in a single node system has no effect. + +The **task wait queue discipline** is selected by the mutually exclusive +:c:macro:`RTEMS_FIFO` and :c:macro:`RTEMS_PRIORITY` attributes. The discipline +defines the order in which tasks wait for a message to receive on a currently +empty message queue. + +* The **FIFO discipline** is the default and can be emphasized through use of + the :c:macro:`RTEMS_FIFO` attribute. + +* The **priority discipline** is selected by the :c:macro:`RTEMS_PRIORITY` + attribute. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_NAME` + The ``name`` parameter was invalid. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``id`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_NUMBER` + The ``count`` parameter was invalid. + +:c:macro:`RTEMS_INVALID_SIZE` + The ``max_message_size`` parameter was invalid. + +:c:macro:`RTEMS_TOO_MANY` + There was no inactive object available to create a message queue. The + number of message queue available to the application is configured through + the :ref:`CONFIGURE_MAXIMUM_MESSAGE_QUEUES` application configuration + option. + +:c:macro:`RTEMS_TOO_MANY` + In multiprocessing configurations, there was no inactive global object + available to create a global message queue. The number of global objects + available to the application is configured through the + :ref:`CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS` application configuration + option. + +:c:macro:`RTEMS_INVALID_NUMBER` + The product of ``count`` and ``max_message_size`` is greater than the + maximum storage size. + +:c:macro:`RTEMS_UNSATISFIED` + There was not enough memory available in the RTEMS Workspace to allocate + the message buffers for the message queue. + +.. rubric:: NOTES: + +For message queues with a global scope, the maximum message size is effectively +limited to the longest message which the :term:`MPCI` is capable of +transmitting. + +For control and maintenance of the message queue, RTEMS allocates a :term:`QCB` +from the local QCB free pool and initializes it. + +The QCB for a global message queue is allocated on the local node. Message +queues should not be made global unless remote tasks must interact with the +message queue. This is to avoid the system overhead incurred by the creation +of a global message queue. When a global message queue is created, the message +queue's name and identifier must be transmitted to every node in the system for +insertion in the local copy of the global object table. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. + +* When the directive operates on a global object, the directive sends a message + to remote nodes. This may preempt the calling task. + +* The number of message queues available to the application is configured + through the :ref:`CONFIGURE_MAXIMUM_MESSAGE_QUEUES` application configuration + option. + +* Where the object class corresponding to the directive is configured to use + unlimited objects, the directive may allocate memory from the RTEMS + Workspace. + +* The number of global objects available to the application is configured + through the :ref:`CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS` application + configuration option. + +.. Generated from spec:/rtems/message/if/construct + +.. raw:: latex + + \clearpage + +.. index:: rtems_message_queue_construct() + +.. _InterfaceRtemsMessageQueueConstruct: + +rtems_message_queue_construct() +------------------------------- + +Constructs a message queue from the specified the message queue configuration. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_message_queue_construct( + const rtems_message_queue_config *config, + rtems_id *id + ); + +.. rubric:: PARAMETERS: + +``config`` + This parameter is the pointer to an :ref:`InterfaceRtemsMessageQueueConfig` + object. It configures the message queue. + +``id`` + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the identifier of the constructed message + queue will be stored in this object. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``config`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_NAME` + The message queue name in the configuration was invalid. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``id`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_NUMBER` + The maximum number of pending messages in the configuration was zero. + +:c:macro:`RTEMS_INVALID_SIZE` + The maximum message size in the configuration was zero. + +:c:macro:`RTEMS_TOO_MANY` + There was no inactive message queue object available to construct a message + queue. + +:c:macro:`RTEMS_TOO_MANY` + In multiprocessing configurations, there was no inactive global object + available to construct a global message queue. + +:c:macro:`RTEMS_INVALID_SIZE` + The maximum message size in the configuration was too big and resulted in + integer overflows in calculations carried out to determine the size of the + message buffer area. + +:c:macro:`RTEMS_INVALID_NUMBER` + The maximum number of pending messages in the configuration was too big and + resulted in integer overflows in calculations carried out to determine the + size of the message buffer area. + +:c:macro:`RTEMS_UNSATISFIED` + The message queue storage area begin pointer in the configuration was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_UNSATISFIED` + The message queue storage area size in the configuration was not equal to + the size calculated from the maximum number of pending messages and the + maximum message size. + +.. rubric:: NOTES: + +In contrast to message queues created by +:ref:`InterfaceRtemsMessageQueueCreate`, the message queues constructed by this +directive use a user-provided message buffer storage area. + +This directive is intended for applications which do not want to use the RTEMS +Workspace and instead statically allocate all operating system resources. An +application based solely on static allocation can avoid any runtime memory +allocators. This can simplify the application architecture as well as any +analysis that may be required. + +The value for :ref:`CONFIGURE_MESSAGE_BUFFER_MEMORY` should not include memory +for message queues constructed by :ref:`InterfaceRtemsMessageQueueConstruct`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. + +* When the directive operates on a global object, the directive sends a message + to remote nodes. This may preempt the calling task. + +* The number of message queues available to the application is configured + through the :ref:`CONFIGURE_MAXIMUM_MESSAGE_QUEUES` application configuration + option. + +* Where the object class corresponding to the directive is configured to use + unlimited objects, the directive may allocate memory from the RTEMS + Workspace. + +* The number of global objects available to the application is configured + through the :ref:`CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS` application + configuration option. + +.. Generated from spec:/rtems/message/if/ident .. raw:: latex - \clearpage + \clearpage + +.. index:: rtems_message_queue_ident() + +.. _InterfaceRtemsMessageQueueIdent: + +rtems_message_queue_ident() +--------------------------- + +Identifies a message queue by the object name. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_message_queue_ident( + rtems_name name, + uint32_t node, + rtems_id *id + ); + +.. rubric:: PARAMETERS: + +``name`` + This parameter is the object name to look up. + +``node`` + This parameter is the node or node set to search for a matching object. + +``id`` + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the object identifier of an object with + the specified name will be stored in this object. + +.. rubric:: DESCRIPTION: + +This directive obtains a message queue identifier associated with the message +queue name specified in ``name``. + +The node to search is specified in ``node``. It shall be + +* a valid node number, + +* the constant :c:macro:`RTEMS_SEARCH_ALL_NODES` to search in all nodes, + +* the constant :c:macro:`RTEMS_SEARCH_LOCAL_NODE` to search in the local node + only, or -.. index:: get ID of a message queue -.. index:: rtems_message_queue_ident +* the constant :c:macro:`RTEMS_SEARCH_OTHER_NODES` to search in all nodes + except the local node. -.. _rtems_message_queue_ident: +.. rubric:: RETURN VALUES: -MESSAGE_QUEUE_IDENT - Get ID of a queue ---------------------------------------- +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. -CALLING SEQUENCE: - .. code-block:: c +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``id`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. - rtems_status_code rtems_message_queue_ident( - rtems_name name, - uint32_t node, - rtems_id *id - ); +:c:macro:`RTEMS_INVALID_NAME` + The ``name`` parameter was 0. -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +:c:macro:`RTEMS_INVALID_NAME` + There was no object with the specified name on the specified nodes. - * - ``RTEMS_SUCCESSFUL`` - - queue identified successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``id`` is NULL - * - ``RTEMS_INVALID_NAME`` - - queue name not found - * - ``RTEMS_INVALID_NODE`` - - invalid node id +:c:macro:`RTEMS_INVALID_NODE` + In multiprocessing configurations, the specified node was invalid. -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. +.. rubric:: NOTES: -NOTES: - This directive will not cause the running task to be preempted. +If the message queue name is not unique, then the message queue identifier will +match the first message queue with that name in the search order. However, this +message queue identifier is not guaranteed to correspond to the desired message +queue. - 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. +The objects are searched from lowest to the highest index. If ``node`` is +:c:macro:`RTEMS_SEARCH_ALL_NODES`, all nodes are searched with the local node +being searched first. All other nodes are searched from lowest to the highest +node number. - If node is a valid node number which does not represent the local node, - then only the message queues exported by the designated node are searched. +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. +This directive does not generate activity on remote nodes. It accesses only +the local copy of the global object table. + +The message queue identifier is used with other message related directives to +access the message queue. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/message/if/delete .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_message_queue_delete() .. index:: delete a message queue -.. index:: rtems_message_queue_delete -.. _rtems_message_queue_delete: +.. _InterfaceRtemsMessageQueueDelete: + +rtems_message_queue_delete() +---------------------------- + +Deletes the message queue. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_message_queue_delete( rtems_id id ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the message queue identifier. + +.. rubric:: DESCRIPTION: + +This directive deletes the message queue specified by ``id``. As a result of +this directive, all tasks blocked waiting to receive a message from this queue +will be readied and returned a status code which indicates that the message +queue was deleted. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no message queue associated with the identifier specified by + ``id``. -MESSAGE_QUEUE_DELETE - Delete a queue -------------------------------------- +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT` + The message queue resided on a remote node. -CALLING SEQUENCE: - .. code-block:: c +.. rubric:: NOTES: - rtems_status_code rtems_message_queue_delete( - rtems_id id - ); +When the message queue is deleted, any messages in the queue are returned to +the free message buffer pool. Any information stored in those messages is +lost. The message buffers allocated for the message queue are reclaimed. -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +The :term:`QCB` for the deleted message queue is reclaimed by RTEMS. - * - ``RTEMS_SUCCESSFUL`` - - queue deleted successfully - * - ``RTEMS_INVALID_ID`` - - invalid queue id - * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - - cannot delete remote queue +When a global message queue is deleted, the message queue identifier must be +transmitted to every node in the system for deletion from the local copy of the +global object table. -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. +The message queue must reside on the local node, even if the message queue was +created with the :c:macro:`RTEMS_GLOBAL` attribute. -NOTES: - This directive may cause the calling task to be preempted due to an - obtain and release of the object allocator mutex. +Proxies, used to represent remote tasks, are reclaimed when the message queue +is deleted. - 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. +.. rubric:: CONSTRAINTS: - 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 following constraints apply to this directive: - 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 directive may be called from within device driver initialization context. - 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. +* The directive may be called from within task context. - Proxies, used to represent remote tasks, are reclaimed when the message - queue is deleted. +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. + +* When the directive operates on a global object, the directive sends a message + to remote nodes. This may preempt the calling task. + +* The calling task does not have to be the task that created the object. Any + local task that knows the object identifier can delete the object. + +* Where the object class corresponding to the directive is configured to use + unlimited objects, the directive may free memory to the RTEMS Workspace. + +.. Generated from spec:/rtems/message/if/send .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_message_queue_send() .. index:: send message to a queue -.. index:: rtems_message_queue_send - -.. _rtems_message_queue_send: - -MESSAGE_QUEUE_SEND - Put message at rear of a queue ---------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_message_queue_send( - rtems_id id, - const void *buffer, - size_t size - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - message sent successfully - * - ``RTEMS_INVALID_ID`` - - invalid queue id - * - ``RTEMS_INVALID_SIZE`` - - invalid message size - * - ``RTEMS_INVALID_ADDRESS`` - - ``buffer`` is NULL - * - ``RTEMS_UNSATISFIED`` - - out of message buffers - * - ``RTEMS_TOO_MANY`` - - queue's limit has been reached - -DESCRIPTION: - This directive sends the message buffer of size bytes in length to the - queue specified by id. If a task is waiting at the queue, then the message - is copied to the waiting task's buffer and the task is unblocked. If no - tasks are waiting at the queue, then the message is copied to a message - buffer which is obtained from this message queue's message buffer pool. - The message buffer is then placed at the rear of the queue. - -NOTES: - The calling task will be preempted if it has preemption enabled and a - higher priority task is unblocked as the result of this directive. - - Sending a message to a global message queue which does not reside on the - local node will generate a request to the remote node to post the message - on the specified message queue. - - If the task to be unblocked resides on a different node from the message - queue, then the message is forwarded to the appropriate node, the waiting - task is unblocked, and the proxy used to represent the task is reclaimed. + +.. _InterfaceRtemsMessageQueueSend: + +rtems_message_queue_send() +-------------------------- + +Puts the message at the rear of the queue. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_message_queue_send( + rtems_id id, + const void *buffer, + size_t size + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the queue identifier. + +``buffer`` + This parameter is the begin address of the message buffer to send. + +``size`` + This parameter is the size in bytes of the message buffer to send. + +.. rubric:: DESCRIPTION: + +This directive sends the message ``buffer`` of ``size`` bytes in length to the +queue specified by ``id``. If a task is waiting at the queue, then the message +is copied to the waiting task's buffer and the task is unblocked. If no tasks +are waiting at the queue, then the message is copied to a message buffer which +is obtained from this message queue's message buffer pool. The message buffer +is then placed at the rear of the queue. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no queue associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``buffer`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_SIZE` + The size of the message exceeded the maximum message size of the queue as + defined by :ref:`InterfaceRtemsMessageQueueCreate` or + :ref:`InterfaceRtemsMessageQueueConstruct`. + +:c:macro:`RTEMS_TOO_MANY` + The maximum number of pending messages supported by the queue as defined by + :ref:`InterfaceRtemsMessageQueueCreate` or + :ref:`InterfaceRtemsMessageQueueConstruct` has been reached. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within task context. + +* The directive may be called from within interrupt context. + +* The directive may unblock a task. This may cause the calling task to be + preempted. + +* When the directive operates on a remote object, the directive sends a message + to the remote node and waits for a reply. This will preempt the calling + task. + +.. Generated from spec:/rtems/message/if/urgent .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_message_queue_urgent() .. index:: put message at front of queue -.. index:: rtems_message_queue_urgent - -.. _rtems_message_queue_urgent: - -MESSAGE_QUEUE_URGENT - Put message at front of a queue ------------------------------------------------------- - -**CALLING SEQUENCE:** - .. code-block:: c - - rtems_status_code rtems_message_queue_urgent( - rtems_id id, - const void *buffer, - size_t size - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - message sent successfully - * - ``RTEMS_INVALID_ID`` - - invalid queue id - * - ``RTEMS_INVALID_SIZE`` - - invalid message size - * - ``RTEMS_INVALID_ADDRESS`` - - ``buffer`` is NULL - * - ``RTEMS_UNSATISFIED`` - - out of message buffers - * - ``RTEMS_TOO_MANY`` - - queue's limit has been reached - -DESCRIPTION: - This directive sends the message buffer of size bytes in length to the - queue specified by id. If a task is waiting on the queue, then the message - is copied to the task's buffer and the task is unblocked. If no tasks are - waiting on the queue, then the message is copied to a message buffer which - is obtained from this message queue's message buffer pool. The message - buffer is then placed at the front of the queue. - -NOTES: - The calling task will be preempted if it has preemption enabled and a - higher priority task is unblocked as the result of this directive. - - Sending a message to a global message queue which does not reside on the - local node will generate a request telling the remote node to post the - message on the specified message queue. - - If the task to be unblocked resides on a different node from the message - queue, then the message is forwarded to the appropriate node, the waiting - task is unblocked, and the proxy used to represent the task is reclaimed. + +.. _InterfaceRtemsMessageQueueUrgent: + +rtems_message_queue_urgent() +---------------------------- + +Puts the message at the front of the queue. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_message_queue_urgent( + rtems_id id, + const void *buffer, + size_t size + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the queue identifier. + +``buffer`` + This parameter is the begin address of the message buffer to send urgently. + +``size`` + This parameter is the size in bytes of the message buffer to send urgently. + +.. rubric:: DESCRIPTION: + +This directive sends the message ``buffer`` of ``size`` bytes in length to the +queue specified by ``id``. If a task is waiting at the queue, then the message +is copied to the waiting task's buffer and the task is unblocked. If no tasks +are waiting at the queue, then the message is copied to a message buffer which +is obtained from this message queue's message buffer pool. The message buffer +is then placed at the front of the queue. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no queue associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``buffer`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_SIZE` + The size of the message exceeded the maximum message size of the queue as + defined by :ref:`InterfaceRtemsMessageQueueCreate` or + :ref:`InterfaceRtemsMessageQueueConstruct`. + +:c:macro:`RTEMS_TOO_MANY` + The maximum number of pending messages supported by the queue as defined by + :ref:`InterfaceRtemsMessageQueueCreate` or + :ref:`InterfaceRtemsMessageQueueConstruct` has been reached. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within task context. + +* The directive may be called from within interrupt context. + +* The directive may unblock a task. This may cause the calling task to be + preempted. + +* When the directive operates on a remote object, the directive sends a message + to the remote node and waits for a reply. This will preempt the calling + task. + +.. Generated from spec:/rtems/message/if/broadcast .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_message_queue_broadcast() .. index:: broadcast message to a queue -.. index:: rtems_message_queue_broadcast - -.. _rtems_message_queue_broadcast: - -MESSAGE_QUEUE_BROADCAST - Broadcast N messages to a queue ---------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_message_queue_broadcast( - rtems_id id, - const void *buffer, - size_t size, - uint32_t *count - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - message broadcasted successfully - * - ``RTEMS_INVALID_ID`` - - invalid queue id - * - ``RTEMS_INVALID_ADDRESS`` - - ``buffer`` is NULL - * - ``RTEMS_INVALID_ADDRESS`` - - ``count`` is NULL - * - ``RTEMS_INVALID_SIZE`` - - invalid message size - -DESCRIPTION: - This directive causes all tasks that are waiting at the queue specified by - id to be unblocked and sent the message contained in buffer. Before a task - is unblocked, the message buffer of size byes in length is copied to that - task's message buffer. The number of tasks that were unblocked is returned - in count. - -NOTES: - The calling task will be preempted if it has preemption enabled and a - higher priority task is unblocked as the result of this directive. - - The execution time of this directive is directly related to the number of - tasks waiting on the message queue, although it is more efficient than the - equivalent number of invocations of ``rtems_message_queue_send``. - - Broadcasting a message to a global message queue which does not reside on - the local node will generate a request telling the remote node to broadcast - the message to the specified message queue. - - When a task is unblocked which resides on a different node from the message - queue, a copy of the message is forwarded to the appropriate node, the - waiting task is unblocked, and the proxy used to represent the task is - reclaimed. + +.. _InterfaceRtemsMessageQueueBroadcast: + +rtems_message_queue_broadcast() +------------------------------- + +Broadcasts the messages to the tasks waiting at the queue. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_message_queue_broadcast( + rtems_id id, + const void *buffer, + size_t size, + uint32_t *count + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the queue identifier. + +``buffer`` + This parameter is the begin address of the message buffer to broadcast. + +``size`` + This parameter is the size in bytes of the message buffer to broadcast. + +``count`` + This parameter is the pointer to an `uint32_t + <https://en.cppreference.com/w/c/types/integer>`_ object. When the + directive call is successful, the number of unblocked tasks will be stored + in this object. + +.. rubric:: DESCRIPTION: + +This directive causes all tasks that are waiting at the queue specified by +``id`` to be unblocked and sent the message contained in ``buffer``. Before a +task is unblocked, the message ``buffer`` of ``size`` bytes in length is copied +to that task's message buffer. The number of tasks that were unblocked is +returned in ``count``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no queue associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``buffer`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``count`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_SIZE` + The size of the message exceeded the maximum message size of the queue as + defined by :ref:`InterfaceRtemsMessageQueueCreate` or + :ref:`InterfaceRtemsMessageQueueConstruct`. + +.. rubric:: NOTES: + +The execution time of this directive is directly related to the number of tasks +waiting on the message queue, although it is more efficient than the equivalent +number of invocations of :ref:`InterfaceRtemsMessageQueueSend`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within task context. + +* The directive may be called from within interrupt context. + +* The directive may unblock a task. This may cause the calling task to be + preempted. + +* When the directive operates on a remote object, the directive sends a message + to the remote node and waits for a reply. This will preempt the calling + task. + +.. Generated from spec:/rtems/message/if/receive .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_message_queue_receive() .. index:: receive message from a queue -.. index:: rtems_message_queue_receive - -.. _rtems_message_queue_receive: - -MESSAGE_QUEUE_RECEIVE - Receive message from a queue ----------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_message_queue_receive( - rtems_id id, - void *buffer, - size_t *size, - rtems_option option_set, - rtems_interval timeout - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - message received successfully - * - ``RTEMS_INVALID_ID`` - - invalid queue id - * - ``RTEMS_INVALID_ADDRESS`` - - ``buffer`` is NULL - * - ``RTEMS_INVALID_ADDRESS`` - - ``size`` is NULL - * - ``RTEMS_UNSATISFIED`` - - queue is empty - * - ``RTEMS_TIMEOUT`` - - timed out waiting for message - * - ``RTEMS_OBJECT_WAS_DELETED`` - - queue deleted while waiting - -DESCRIPTION: - This directive receives a message from the message queue specified in id. - The ``RTEMS_WAIT`` and ``RTEMS_NO_WAIT`` options of the options parameter - allow the calling task to specify whether to wait for a message to become - available or return immediately. For either option, if there is at least - one message in the queue, then it is copied to buffer, size is set to - return the length of the message in bytes, and this directive returns - immediately with a successful return code. The buffer has to be big enough - to receive a message of the maximum length with respect to this message - queue. - If the calling task chooses to return immediately and the queue is empty, - then a status code indicating this condition is returned. If the calling - task chooses to wait at the message queue and the queue is empty, then the - calling task is placed on the message wait queue and blocked. If the queue - was created with the ``RTEMS_PRIORITY`` option specified, then the calling - task is inserted into the wait queue according to its priority. But, if - the queue was created with the ``RTEMS_FIFO`` option specified, then the - calling task is placed at the rear of the wait queue. - - A task choosing to wait at the queue can optionally specify a timeout value - in the timeout parameter. The timeout parameter specifies the maximum - interval to wait before the calling task desires to be unblocked. If it is - set to ``RTEMS_NO_TIMEOUT``, then the calling task will wait forever. - -NOTES: - The following message receive option constants are defined by RTEMS: - - .. list-table:: - :class: rtems-table - - * - ``RTEMS_WAIT`` - - task will wait for a message (default) - * - ``RTEMS_NO_WAIT`` - - task should not wait - - Receiving a message from a global message queue which does not reside on - the local node will generate a request to the remote node to obtain a - message from the specified message queue. If no message is available and - ``RTEMS_WAIT`` was specified, then the task must be blocked until a message - is posted. A proxy is allocated on the remote node to represent the task - until the message is posted. - - A clock tick is required to support the timeout functionality of this - directive. +.. _InterfaceRtemsMessageQueueReceive: + +rtems_message_queue_receive() +----------------------------- + +Receives a message from the queue. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_message_queue_receive( + rtems_id id, + void *buffer, + size_t *size, + rtems_option option_set, + rtems_interval timeout + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the queue identifier. + +``buffer`` + This parameter is the begin address of the buffer to receive the message. + The buffer shall be large enough to receive a message of the maximum length + of the queue as defined by :ref:`InterfaceRtemsMessageQueueCreate` or + :ref:`InterfaceRtemsMessageQueueConstruct`. The ``size`` parameter cannot + be used to specify the size of the buffer. + +``size`` + This parameter is the pointer to a `size_t + <https://en.cppreference.com/w/c/types/size_t>`_ object. When the + directive call is successful, the size in bytes of the received messages + will be stored in this object. This parameter cannot be used to specify + the size of the buffer. + +``option_set`` + This parameter is the option set. + +``timeout`` + This parameter is the timeout in :term:`clock ticks <clock tick>` if the + :c:macro:`RTEMS_WAIT` option is set. Use :c:macro:`RTEMS_NO_TIMEOUT` to + wait potentially forever. + +.. rubric:: DESCRIPTION: + +This directive receives a message from the queue specified by ``id``. + +The **option set** specified in ``option_set`` is built through a *bitwise or* +of the option constants described below. Not all combinations of options are +allowed. Some options are mutually exclusive. If mutually exclusive options +are combined, the behaviour is undefined. Options not mentioned below are not +evaluated by this directive and have no effect. Default options can be selected +by using the :c:macro:`RTEMS_DEFAULT_OPTIONS` constant. + +The calling task can **wait** or **try to receive** a message from the queue +according to the mutually exclusive :c:macro:`RTEMS_WAIT` and +:c:macro:`RTEMS_NO_WAIT` options. + +* **Waiting to receive** a message from the queue is the default and can be + emphasized through the use of the :c:macro:`RTEMS_WAIT` option. The + ``timeout`` parameter defines how long the calling task is willing to wait. + Use :c:macro:`RTEMS_NO_TIMEOUT` to wait potentially forever, otherwise set a + timeout interval in clock ticks. + +* **Trying to receive** a message from the queue is selected by the + :c:macro:`RTEMS_NO_WAIT` option. If this option is defined, then the + ``timeout`` parameter is ignored. When a message from the queue cannot be + immediately received, then the :c:macro:`RTEMS_UNSATISFIED` status is + returned. + +With either :c:macro:`RTEMS_WAIT` or :c:macro:`RTEMS_NO_WAIT` if there is at +least one message in the queue, then it is copied to the buffer, the size is +set to return the length of the message in bytes, and this directive returns +immediately with the :c:macro:`RTEMS_SUCCESSFUL` status code. The buffer has +to be big enough to receive a message of the maximum length with respect to +this message queue. + +If the calling task chooses to return immediately and the queue is empty, then +the directive returns immediately with the :c:macro:`RTEMS_UNSATISFIED` status +code. If the calling task chooses to wait at the message queue and the queue +is empty, then the calling task is placed on the message wait queue and +blocked. If the queue was created with the :c:macro:`RTEMS_PRIORITY` option +specified, then the calling task is inserted into the wait queue according to +its priority. But, if the queue was created with the :c:macro:`RTEMS_FIFO` +option specified, then the calling task is placed at the rear of the wait +queue. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no queue associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``buffer`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``size`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_UNSATISFIED` + The queue was empty. + +:c:macro:`RTEMS_TIMEOUT` + The timeout happened while the calling task was waiting to receive a + message + +:c:macro:`RTEMS_OBJECT_WAS_DELETED` + The queue was deleted while the calling task was waiting to receive a + message. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* When a local queue is accessed and the :c:macro:`RTEMS_NO_WAIT` option is + set, the directive may be called from within interrupt context. + +* The directive may be called from within task context. + +* When the request cannot be immediately satisfied and the + :c:macro:`RTEMS_WAIT` option is set, the calling task blocks at some point + during the directive call. + +* The timeout functionality of the directive requires a :term:`clock tick`. + +* When the directive operates on a remote object, the directive sends a message + to the remote node and waits for a reply. This will preempt the calling + task. + +.. Generated from spec:/rtems/message/if/get-number-pending .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_message_queue_get_number_pending() .. index:: get number of pending messages -.. index:: rtems_message_queue_get_number_pending -.. _rtems_message_queue_get_number_pending: +.. _InterfaceRtemsMessageQueueGetNumberPending: + +rtems_message_queue_get_number_pending() +---------------------------------------- + +Gets the number of messages pending on the queue. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_message_queue_get_number_pending( + rtems_id id, + uint32_t *count + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the queue identifier. + +``count`` + This parameter is the pointer to an `uint32_t + <https://en.cppreference.com/w/c/types/integer>`_ object. When the + directive call is successful, the number of pending messages will be stored + in this object. -MESSAGE_QUEUE_GET_NUMBER_PENDING - Get number of messages pending on a queue ----------------------------------------------------------------------------- +.. rubric:: DESCRIPTION: -CALLING SEQUENCE: - .. code-block:: c +This directive returns the number of messages pending on the queue specified by +``id`` in ``count``. If no messages are present on the queue, count is set to +zero. - rtems_status_code rtems_message_queue_get_number_pending( - rtems_id id, - uint32_t *count - ); +.. rubric:: RETURN VALUES: -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. - * - ``RTEMS_SUCCESSFUL`` - - number of messages pending returned successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``count`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid queue id +:c:macro:`RTEMS_INVALID_ID` + There was no queue associated with the identifier specified by ``id``. -DESCRIPTION: - This directive returns the number of messages pending on this message queue - in count. If no messages are present on the queue, count is set to zero. +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``count`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. -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. +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within task context. + +* The directive may be called from within interrupt context. + +* When the directive operates on a remote object, the directive sends a message + to the remote node and waits for a reply. This will preempt the calling + task. + +.. Generated from spec:/rtems/message/if/flush .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_message_queue_flush() .. index:: flush messages on a queue -.. index:: rtems_message_queue_flush -.. _rtems_message_queue_flush: +.. _InterfaceRtemsMessageQueueFlush: + +rtems_message_queue_flush() +--------------------------- + +Flushes all messages on the queue. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_message_queue_flush( rtems_id id, uint32_t *count ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the queue identifier. + +``count`` + This parameter is the pointer to an `uint32_t + <https://en.cppreference.com/w/c/types/integer>`_ object. When the + directive call is successful, the number of pending messages removed from + the queue will be stored in this object. + +.. rubric:: DESCRIPTION: + +This directive removes all pending messages from the queue specified by ``id``. +The number of messages removed is returned in ``count``. If no messages are +present on the queue, count is set to zero. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no queue associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``count`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +.. rubric:: NOTES: + +The directive does not flush tasks waiting to receive a message from the +:term:`wait queue` of the message queue. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/message/if/buffer + +.. raw:: latex + + \clearpage + +.. index:: RTEMS_MESSAGE_QUEUE_BUFFER() + +.. _InterfaceRTEMSMESSAGEQUEUEBUFFER: + +RTEMS_MESSAGE_QUEUE_BUFFER() +---------------------------- + +Defines a structure which can be used as a message queue buffer for messages of +the specified maximum size. -MESSAGE_QUEUE_FLUSH - Flush all messages on a queue ---------------------------------------------------- +.. rubric:: CALLING SEQUENCE: -CALLING SEQUENCE: - .. code-block:: c +.. code-block:: c - rtems_status_code rtems_message_queue_flush( - rtems_id id, - uint32_t *count - ); + RTEMS_MESSAGE_QUEUE_BUFFER( size_t maximum_message_size ); -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +.. rubric:: PARAMETERS: - * - ``RTEMS_SUCCESSFUL`` - - message queue flushed successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``count`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid queue id +``maximum_message_size`` + This parameter is the maximum message size in bytes. -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. +.. rubric:: NOTES: -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. +Use this macro to define the message buffer storage area for +:ref:`InterfaceRtemsMessageQueueConstruct`. diff --git a/c-user/message/index.rst b/c-user/message/index.rst index 92ebdae..b797cd1 100644 --- a/c-user/message/index.rst +++ b/c-user/message/index.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020 embedded brains GmbH & Co. KG .. index:: messages .. index:: message queues diff --git a/c-user/message/introduction.rst b/c-user/message/introduction.rst index b10e06c..989cd33 100644 --- a/c-user/message/introduction.rst +++ b/c-user/message/introduction.rst @@ -1,28 +1,71 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/rtems/message/if/group + +.. _MessageManagerIntroduction: + Introduction ============ -The message manager provides communication and synchronization capabilities -using RTEMS message queues. The directives provided by the message manager -are: +.. The following list was generated from: +.. spec:/rtems/message/if/create +.. spec:/rtems/message/if/construct +.. spec:/rtems/message/if/ident +.. spec:/rtems/message/if/delete +.. spec:/rtems/message/if/send +.. spec:/rtems/message/if/urgent +.. spec:/rtems/message/if/broadcast +.. spec:/rtems/message/if/receive +.. spec:/rtems/message/if/get-number-pending +.. spec:/rtems/message/if/flush +.. spec:/rtems/message/if/buffer + +The Message Manager provides communication and synchronization capabilities +using RTEMS message queues. The directives provided by the Message Manager are: + +* :ref:`InterfaceRtemsMessageQueueCreate` - Creates a message queue. + +* :ref:`InterfaceRtemsMessageQueueConstruct` - Constructs a message queue from + the specified the message queue configuration. -- :ref:`rtems_message_queue_create` +* :ref:`InterfaceRtemsMessageQueueIdent` - Identifies a message queue by the + object name. -- :ref:`rtems_message_queue_ident` +* :ref:`InterfaceRtemsMessageQueueDelete` - Deletes the message queue. -- :ref:`rtems_message_queue_delete` +* :ref:`InterfaceRtemsMessageQueueSend` - Puts the message at the rear of the + queue. -- :ref:`rtems_message_queue_send` +* :ref:`InterfaceRtemsMessageQueueUrgent` - Puts the message at the front of + the queue. -- :ref:`rtems_message_queue_urgent` +* :ref:`InterfaceRtemsMessageQueueBroadcast` - Broadcasts the messages to the + tasks waiting at the queue. -- :ref:`rtems_message_queue_broadcast` +* :ref:`InterfaceRtemsMessageQueueReceive` - Receives a message from the queue. -- :ref:`rtems_message_queue_receive` +* :ref:`InterfaceRtemsMessageQueueGetNumberPending` - Gets the number of + messages pending on the queue. -- :ref:`rtems_message_queue_get_number_pending` +* :ref:`InterfaceRtemsMessageQueueFlush` - Flushes all messages on the queue. -- :ref:`rtems_message_queue_flush` +* :ref:`InterfaceRTEMSMESSAGEQUEUEBUFFER` - Defines a structure which can be + used as a message queue buffer for messages of the specified maximum size. diff --git a/c-user/multiprocessing.rst b/c-user/multiprocessing/background.rst index f207106..2aaae6e 100644 --- a/c-user/multiprocessing.rst +++ b/c-user/multiprocessing/background.rst @@ -2,44 +2,6 @@ .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) -.. index:: multiprocessing - -Multiprocessing Manager -*********************** - -Introduction -============ - -In multiprocessor real-time systems, new requirements, such as sharing data and -global resources between processors, are introduced. This requires an -efficient and reliable communications vehicle which allows all processors to -communicate with each other as necessary. In addition, the ramifications of -multiple processors affect each and every characteristic of a real-time system, -almost always making them more complicated. - -RTEMS addresses these issues by providing simple and flexible real-time -multiprocessing capabilities. The executive easily lends itself to both -tightly-coupled and loosely-coupled configurations of the target system -hardware. In addition, RTEMS supports systems composed of both homogeneous and -heterogeneous mixtures of processors and target boards. - -A major design goal of the RTEMS executive was to transcend the physical -boundaries of the target hardware configuration. This goal is achieved by -presenting the application software with a logical view of the target system -where the boundaries between processor nodes are transparent. As a result, the -application developer may designate objects such as tasks, queues, events, -signals, semaphores, and memory blocks as global objects. These global objects -may then be accessed by any task regardless of the physical location of the -object and the accessing task. RTEMS automatically determines that the object -being accessed resides on another processor and performs the actions required -to access the desired object. Simply stated, RTEMS allows the entire system, -both hardware and software, to be viewed logically as a single system. - -The directives provided by the Manager are: - -- rtems_multiprocessing_announce_ - A multiprocessing communications packet has - arrived - .. index:: multiprocessing topologies Background @@ -455,54 +417,3 @@ of the following: - RTEMS makes no assumptions regarding the application data component of the packet. - -Operations -========== - -Announcing a Packet -------------------- - -The ``rtems_multiprocessing_announce`` directive is called by the MPCI layer to -inform RTEMS that a packet has arrived from another node. This directive can -be called from an interrupt service routine or from within a polling routine. - -Directives -========== - -This section details the additional directives required to support RTEMS in a -multiprocessor configuration. A subsection is dedicated to each of this -manager's directives and describes the calling sequence, related constants, -usage, and status codes. - -.. raw:: latex - - \clearpage - -.. index:: announce arrival of package -.. index:: rtems_multiprocessing_announce - -.. _rtems_multiprocessing_announce: - -MULTIPROCESSING_ANNOUNCE - Announce the arrival of a packet ------------------------------------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - void rtems_multiprocessing_announce( void ); - -DIRECTIVE STATUS CODES: - NONE - -DESCRIPTION: - This directive informs RTEMS that a multiprocessing communications packet - has arrived from another node. This directive is called by the - user-provided MPCI, and is only used in multiprocessor configurations. - -NOTES: - This directive is typically called from an ISR. - - This directive will almost certainly cause the calling task to be - preempted. - - This directive does not generate activity on remote nodes. diff --git a/c-user/multiprocessing/directives.rst b/c-user/multiprocessing/directives.rst new file mode 100644 index 0000000..a12599c --- /dev/null +++ b/c-user/multiprocessing/directives.rst @@ -0,0 +1,75 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. _MultiprocessingManagerDirectives: + +Directives +========== + +This section details the directives of the Multiprocessing Manager. A +subsection is dedicated to each of this manager's directives and lists the +calling sequence, parameters, description, return values, and notes of the +directive. + +.. Generated from spec:/rtems/mp/if/announce + +.. raw:: latex + + \clearpage + +.. index:: rtems_multiprocessing_announce() + +.. _InterfaceRtemsMultiprocessingAnnounce: + +rtems_multiprocessing_announce() +-------------------------------- + +Announces the arrival of a packet. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_multiprocessing_announce( void ); + +.. rubric:: DESCRIPTION: + +This directive informs RTEMS that a multiprocessing communications packet has +arrived from another node. This directive is called by the user-provided MPCI, +and is only used in multiprocessing configurations. + +.. rubric:: NOTES: + +This directive is typically called from an :term:`ISR`. + +This directive does not generate activity on remote nodes. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may unblock a task. This may cause the calling task to be + preempted. diff --git a/c-user/multiprocessing/index.rst b/c-user/multiprocessing/index.rst new file mode 100644 index 0000000..351105d --- /dev/null +++ b/c-user/multiprocessing/index.rst @@ -0,0 +1,17 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2021 embedded brains GmbH & Co. KG + +.. index:: multiprocessing + +.. _RTEMSAPIClassicMP: + +Multiprocessing Manager +*********************** + +.. toctree:: + + introduction + background + operations + directives diff --git a/c-user/multiprocessing/introduction.rst b/c-user/multiprocessing/introduction.rst new file mode 100644 index 0000000..45c90bd --- /dev/null +++ b/c-user/multiprocessing/introduction.rst @@ -0,0 +1,61 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/rtems/mp/if/group + +.. _MultiprocessingManagerIntroduction: + +Introduction +============ + +.. The following list was generated from: +.. spec:/rtems/mp/if/announce + +The Multiprocessing Manager provides support for heterogeneous multiprocessing +systems based on message passing in a network of multiprocessing nodes. + +In multiprocessor real-time systems, new requirements, such as sharing data and +global resources between processors, are introduced. This requires an +efficient and reliable communications vehicle which allows all processors to +communicate with each other as necessary. In addition, the ramifications of +multiple processors affect each and every characteristic of a real-time system, +almost always making them more complicated. + +RTEMS addresses these issues by providing simple and flexible real-time +multiprocessing capabilities. The executive easily lends itself to both +tightly-coupled and loosely-coupled configurations of the target system +hardware. In addition, RTEMS supports systems composed of both homogeneous and +heterogeneous mixtures of processors and target boards. + +A major design goal of the RTEMS executive was to transcend the physical +boundaries of the target hardware configuration. This goal is achieved by +presenting the application software with a logical view of the target system +where the boundaries between processor nodes are transparent. As a result, the +application developer may designate objects such as tasks, queues, events, +signals, semaphores, and memory blocks as global objects. These global objects +may then be accessed by any task regardless of the physical location of the +object and the accessing task. RTEMS automatically determines that the object +being accessed resides on another processor and performs the actions required +to access the desired object. Simply stated, RTEMS allows the entire system, +both hardware and software, to be viewed logically as a single system. The +directives provided by the Multiprocessing Manager are: + +* :ref:`InterfaceRtemsMultiprocessingAnnounce` - Announces the arrival of a + packet. diff --git a/c-user/multiprocessing/operations.rst b/c-user/multiprocessing/operations.rst new file mode 100644 index 0000000..08dcded --- /dev/null +++ b/c-user/multiprocessing/operations.rst @@ -0,0 +1,13 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Operations +========== + +Announcing a Packet +------------------- + +The ``rtems_multiprocessing_announce`` directive is called by the MPCI layer to +inform RTEMS that a packet has arrived from another node. This directive can +be called from an interrupt service routine or from within a polling routine. diff --git a/c-user/object-services/directives.rst b/c-user/object-services/directives.rst index 54f234f..c692168 100644 --- a/c-user/object-services/directives.rst +++ b/c-user/object-services/directives.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2009 On-Line Applications Research Corporation (OAR) .. This file is part of the RTEMS quality process and was automatically @@ -168,9 +168,9 @@ Gets the object name associated with the object identifier. This parameter is the object identifier to get the name. ``name`` - This parameter is the pointer to an object name variable. When the - directive call is successful, the object name associated with the object - identifier will be stored in this variable. + This parameter is the pointer to an :ref:`InterfaceRtemsName` object. When + the directive call is successful, the object name associated with the + object identifier will be stored in this object. .. rubric:: RETURN VALUES: @@ -801,9 +801,10 @@ Gets the object class information of the object class of the object API. information. ``info`` - This parameter is the pointer to an object class information variable. - When the directive call is successful, the object class information of the - class of the API will be stored in this variable. + This parameter is the pointer to an + :ref:`InterfaceRtemsObjectApiClassInformation` object. When the directive + call is successful, the object class information of the class of the API + will be stored in this object. .. rubric:: RETURN VALUES: @@ -878,7 +879,11 @@ MPCI node components. .. code-block:: c - #define RTEMS_OBJECT_ID_INITIAL( api, class, node ) + rtems_id RTEMS_OBJECT_ID_INITIAL( + uint32_t api, + uint32_t class, + uint32_t node + ); .. rubric:: PARAMETERS: diff --git a/c-user/object-services/index.rst b/c-user/object-services/index.rst index 43a2c10..3218551 100644 --- a/c-user/object-services/index.rst +++ b/c-user/object-services/index.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020 embedded brains GmbH & Co. KG .. index:: object manipulation diff --git a/c-user/object-services/introduction.rst b/c-user/object-services/introduction.rst index d5a33a4..adff786 100644 --- a/c-user/object-services/introduction.rst +++ b/c-user/object-services/introduction.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2009 On-Line Applications Research Corporation (OAR) .. This file is part of the RTEMS quality process and was automatically diff --git a/c-user/partition/directives.rst b/c-user/partition/directives.rst index 98c0eb1..da5983c 100644 --- a/c-user/partition/directives.rst +++ b/c-user/partition/directives.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) .. This file is part of the RTEMS quality process and was automatically @@ -76,9 +76,9 @@ Creates a partition. This parameter is the attribute set of the partition. ``id`` - This parameter is the pointer to an object identifier variable. When the - directive call is successful, the identifier of the created partition will - be stored in this variable. + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the identifier of the created partition + will be stored in this object. .. rubric:: DESCRIPTION: @@ -241,9 +241,9 @@ Identifies a partition by the object name. This parameter is the node or node set to search for a matching object. ``id`` - This parameter is the pointer to an object identifier variable. When the - directive call is successful, the object identifier of an object with the - specified name will be stored in this variable. + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the object identifier of an object with + the specified name will be stored in this object. .. rubric:: DESCRIPTION: @@ -415,9 +415,9 @@ Tries to get a buffer from the partition. This parameter is the partition identifier. ``buffer`` - This parameter is the pointer to a buffer pointer variable. When the + This parameter is the pointer to a ``void`` pointer object. When the directive call is successful, the pointer to the allocated buffer will be - stored in this variable. + stored in this object. .. rubric:: DESCRIPTION: diff --git a/c-user/partition/index.rst b/c-user/partition/index.rst index 1396e5c..652fdfa 100644 --- a/c-user/partition/index.rst +++ b/c-user/partition/index.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020 embedded brains GmbH & Co. KG .. index:: partitions diff --git a/c-user/partition/introduction.rst b/c-user/partition/introduction.rst index 2798658..ca26de9 100644 --- a/c-user/partition/introduction.rst +++ b/c-user/partition/introduction.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) .. This file is part of the RTEMS quality process and was automatically diff --git a/c-user/rate-monotonic/background.rst b/c-user/rate-monotonic/background.rst index 9ca7dff..af54591 100644 --- a/c-user/rate-monotonic/background.rst +++ b/c-user/rate-monotonic/background.rst @@ -112,7 +112,9 @@ less than its period. For example, a periodic task's requirements may state that it should execute for 10 milliseconds every 100 milliseconds. Although the execution time may be the average, worst, or best case, the worst-case execution time is more appropriate for use when analyzing system behavior under -transient overload conditions... index:: aperiodic task, definition +transient overload conditions. + +.. index:: aperiodic task, definition In contrast, an aperiodic task executes at irregular intervals and has only a soft deadline. In other words, the deadlines for aperiodic tasks are not @@ -220,8 +222,9 @@ assumptions: - The execution time for each task without preemption or interruption is constant and does not vary. -- Any non-periodic tasks in the system are special. These tasks displace - periodic tasks while executing and do not have hard, critical deadlines. +- Any non-periodic tasks in the system are special. These tasks should not + displace periodic tasks while executing and do not have hard, critical + deadlines. Once the basic schedulability analysis is understood, some of the above assumptions can be relaxed and the side-effects accounted for. @@ -288,9 +291,9 @@ by the Processor Utilization Rule, they can still be guaranteed to meet all their deadlines by application of the First Deadline Rule. This rule can be stated as follows: -For a given set of independent periodic tasks, if each task meets its first -deadline when all tasks are started at the same time, then the deadlines will -always be met for any combination of start times. + For a given set of independent periodic tasks, if each task meets its first + deadline when all tasks are started at the same time, then the + deadlines will always be met for any combination of start times. A key point with this rule is that ALL periodic tasks are assumed to start at the exact same instant in time. Although this assumption may seem to be diff --git a/c-user/rate-monotonic/directives.rst b/c-user/rate-monotonic/directives.rst index d100c81..f0467d1 100644 --- a/c-user/rate-monotonic/directives.rst +++ b/c-user/rate-monotonic/directives.rst @@ -1,474 +1,720 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 2017 Kuan-Hsun Chen .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) -.. Copyright (C) 2017 Kuan-Hsun Chen. + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. _RateMonotonicManagerDirectives: Directives ========== -This section details the 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. +This section details the directives of the Rate-Monotonic Manager. A subsection +is dedicated to each of this manager's directives and lists the calling +sequence, parameters, description, return values, and notes of the directive. + +.. Generated from spec:/rtems/ratemon/if/create .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_rate_monotonic_create() .. index:: create a period -.. index:: rtems_rate_monotonic_create -.. _rtems_rate_monotonic_create: +.. _InterfaceRtemsRateMonotonicCreate: + +rtems_rate_monotonic_create() +----------------------------- + +Creates a period. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_rate_monotonic_create( rtems_name name, rtems_id *id ); + +.. rubric:: PARAMETERS: + +``name`` + This parameter is the object name of the period. + +``id`` + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the identifier of the created period will + be stored in this object. + +.. rubric:: DESCRIPTION: + +This directive creates a period which resides on the local node. The period +has the user-defined object name specified in ``name`` The assigned object +identifier is returned in ``id``. This identifier is used to access the period +with other rate monotonic related directives. -RATE_MONOTONIC_CREATE - Create a rate monotonic period ------------------------------------------------------- +.. rubric:: RETURN VALUES: -CALLING SEQUENCE: - .. code-block:: c +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. - rtems_status_code rtems_rate_monotonic_create( - rtems_name name, - rtems_id *id - ); +:c:macro:`RTEMS_INVALID_NAME` + The ``name`` parameter was invalid. -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +:c:macro:`RTEMS_TOO_MANY` + There was no inactive object available to create a period. The number of + periods available to the application is configured through the + :ref:`CONFIGURE_MAXIMUM_PERIODS` application configuration option. - * - ``RTEMS_SUCCESSFUL`` - - rate monotonic period created successfully - * - ``RTEMS_INVALID_NAME`` - - invalid period name - * - ``RTEMS_TOO_MANY`` - - too many periods created +.. rubric:: NOTES: -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. +The calling task is registered as the owner of the created period. Some +directives can be only used by this task for the created period. -NOTES: - This directive may cause the calling task to be preempted due to an - obtain and release of the object allocator mutex. +For control and maintenance of the period, RTEMS allocates a :term:`PCB` from +the local PCB free pool and initializes it. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. + +* The number of periods available to the application is configured through the + :ref:`CONFIGURE_MAXIMUM_PERIODS` application configuration option. + +* Where the object class corresponding to the directive is configured to use + unlimited objects, the directive may allocate memory from the RTEMS + Workspace. + +.. Generated from spec:/rtems/ratemon/if/ident .. raw:: latex - \clearpage + \clearpage + +.. index:: rtems_rate_monotonic_ident() + +.. _InterfaceRtemsRateMonotonicIdent: + +rtems_rate_monotonic_ident() +---------------------------- -.. index:: get ID of a period -.. index:: obtain ID of a period -.. index:: rtems_rate_monotonic_ident +Identifies a period by the object name. -.. _rtems_rate_monotonic_ident: +.. rubric:: CALLING SEQUENCE: -RATE_MONOTONIC_IDENT - Get ID of a period ------------------------------------------ +.. 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 - ); +.. rubric:: PARAMETERS: -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +``name`` + This parameter is the object name to look up. - * - ``RTEMS_SUCCESSFUL`` - - period identified successfully - * - ``RTEMS_INVALID_NAME`` - - period name not found +``id`` + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the object identifier of an object with + the specified name will be stored in this object. -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. +.. rubric:: DESCRIPTION: -NOTES: - This directive will not cause the running task to be preempted. +This directive obtains a period identifier associated with the period name +specified in ``name``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``id`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_NAME` + The ``name`` parameter was 0. + +:c:macro:`RTEMS_INVALID_NAME` + There was no object with the specified name on the local node. + +.. rubric:: NOTES: + +If the period name is not unique, then the period identifier will match the +first period with that name in the search order. However, this period +identifier is not guaranteed to correspond to the desired period. + +The objects are searched from lowest to the highest index. Only the local node +is searched. + +The period identifier is used with other rate monotonic related directives to +access the period. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/ratemon/if/cancel .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_rate_monotonic_cancel() .. index:: cancel a period -.. index:: rtems_rate_monotonic_cancel -.. _rtems_rate_monotonic_cancel: +.. _InterfaceRtemsRateMonotonicCancel: -RATE_MONOTONIC_CANCEL - Cancel a period ---------------------------------------- +rtems_rate_monotonic_cancel() +----------------------------- + +Cancels the period. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_rate_monotonic_cancel( rtems_id id ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the rate monotonic period identifier. + +.. rubric:: DESCRIPTION: + +This directive cancels the rate monotonic period specified by ``id``. This +period may be reinitiated by the next invocation of +:ref:`InterfaceRtemsRateMonotonicPeriod`. -CALLING SEQUENCE: - .. code-block:: c +.. rubric:: RETURN VALUES: - rtems_status_code rtems_rate_monotonic_cancel( - rtems_id id - ); +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +:c:macro:`RTEMS_INVALID_ID` + There was no rate monotonic period associated with the identifier specified + by ``id``. - * - ``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 +:c:macro:`RTEMS_NOT_OWNER_OF_RESOURCE` + The rate monotonic period was not created by the calling task. -DESCRIPTION: +.. rubric:: CONSTRAINTS: - This directive cancels the rate monotonic period id. This period will be - reinitiated by the next invocation of ``rtems_rate_monotonic_period`` - with id. +The following constraints apply to this directive: -NOTES: - This directive will not cause the running task to be preempted. +* The directive may be called from within task context. - The rate monotonic period specified by id must have been created by the - calling task. +* The directive will not cause the calling task to be preempted. + +* The directive may be used exclusively by the task which created the + associated object. + +.. Generated from spec:/rtems/ratemon/if/delete .. raw:: latex - \clearpage + \clearpage -.. index:: rtems_rate_monotonic_delete +.. index:: rtems_rate_monotonic_delete() .. index:: delete a period -.. _rtems_rate_monotonic_delete: +.. _InterfaceRtemsRateMonotonicDelete: + +rtems_rate_monotonic_delete() +----------------------------- + +Deletes the period. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_rate_monotonic_delete( rtems_id id ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the period identifier. + +.. rubric:: DESCRIPTION: + +This directive deletes the period specified by ``id``. If the period is +running, it is automatically canceled. + +.. rubric:: RETURN VALUES: -RATE_MONOTONIC_DELETE - Delete a rate monotonic period ------------------------------------------------------- +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. -CALLING SEQUENCE: - .. code-block:: c +:c:macro:`RTEMS_INVALID_ID` + There was no period associated with the identifier specified by ``id``. - rtems_status_code rtems_rate_monotonic_delete( - rtems_id id - ); +.. rubric:: NOTES: -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +The :term:`PCB` for the deleted period is reclaimed by RTEMS. - * - ``RTEMS_SUCCESSFUL`` - - period deleted successfully - * - ``RTEMS_INVALID_ID`` - - invalid rate monotonic period id +.. rubric:: CONSTRAINTS: -DESCRIPTION: +The following constraints apply to this directive: - 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. +* The directive may be called from within device driver initialization context. -NOTES: - This directive may cause the calling task to be preempted due to an - obtain and release of the object allocator mutex. +* The directive may be called from within task context. - A rate monotonic period can be deleted by a task other than the task which - created the period. +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. + +* The calling task does not have to be the task that created the object. Any + local task that knows the object identifier can delete the object. + +* Where the object class corresponding to the directive is configured to use + unlimited objects, the directive may free memory to the RTEMS Workspace. + +.. Generated from spec:/rtems/ratemon/if/period .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_rate_monotonic_period() .. index:: conclude current period .. index:: start current period .. index:: period initiation -.. index:: rtems_rate_monotonic_period - -.. _rtems_rate_monotonic_period: - -RATE_MONOTONIC_PERIOD - Conclude current/Start next period ----------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_rate_monotonic_period( - rtems_id id, - rtems_interval length - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - period initiated successfully - * - ``RTEMS_INVALID_ID`` - - invalid rate monotonic period id - * - ``RTEMS_NOT_OWNER_OF_RESOURCE`` - - period not created by calling task - * - ``RTEMS_NOT_DEFINED`` - - period has never been initiated (only possible when period is set to PERIOD_STATUS) - * - ``RTEMS_TIMEOUT`` - - period has expired - -DESCRIPTION: - This directive initiates the rate monotonic period id with a length of - period ticks. If id is running, then the calling task will block for the - remainder of the period before reinitiating the period with the specified - period. If id was not running (either expired or never initiated), the - period is immediately initiated and the directive returns immediately. - If id has expired its period, the postponed job will be released immediately - and the following calls of this directive will release postponed - jobs until there is no more deadline miss. - - If invoked with a period of ``RTEMS_PERIOD_STATUS`` ticks, the current - state of id will be returned. The directive status indicates the current - state of the period. This does not alter the state or period of the - period. - -NOTES: - This directive will not cause the running task to be preempted. + +.. _InterfaceRtemsRateMonotonicPeriod: + +rtems_rate_monotonic_period() +----------------------------- + +Concludes the current period and start the next period, or gets the period +status. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_rate_monotonic_period( + rtems_id id, + rtems_interval length + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the rate monotonic period identifier. + +``length`` + This parameter is the period length in :term:`clock ticks <clock tick>` or + :c:macro:`RTEMS_PERIOD_STATUS` to get the period status. + +.. rubric:: DESCRIPTION: + +This directive initiates the rate monotonic period specified by ``id`` with a +length of period ticks specified by ``length``. If the period is running, then +the calling task will block for the remainder of the period before reinitiating +the period with the specified period length. If the period was not running +(either expired or never initiated), the period is immediately initiated and +the directive returns immediately. If the period has expired, the postponed +job will be released immediately and the following calls of this directive will +release postponed jobs until there is no more deadline miss. + +If invoked with a period length of :c:macro:`RTEMS_PERIOD_STATUS` ticks, the +current state of the period will be returned. The directive status indicates +the current state of the period. This does not alter the state or period +length of the period. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no rate monotonic period associated with the identifier specified + by ``id``. + +:c:macro:`RTEMS_NOT_OWNER_OF_RESOURCE` + The rate monotonic period was not created by the calling task. + +:c:macro:`RTEMS_NOT_DEFINED` + The rate monotonic period has never been initiated (only possible when the + ``length`` parameter was equal to :c:macro:`RTEMS_PERIOD_STATUS`). + +:c:macro:`RTEMS_TIMEOUT` + The rate monotonic period has expired. + +.. rubric:: NOTES: + +Resetting the processor usage time of tasks has no impact on the period status +and statistics. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within task context. + +* The directive may be used exclusively by the task which created the + associated object. + +.. Generated from spec:/rtems/ratemon/if/get-status .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_rate_monotonic_get_status() .. index:: get status of period .. index:: obtain status of period -.. index:: rtems_rate_monotonic_get_status - -.. _rtems_rate_monotonic_get_status: - -RATE_MONOTONIC_GET_STATUS - Obtain status from a period -------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_rate_monotonic_get_status( - rtems_id id, - rtems_rate_monotonic_period_status *status - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - period status retrieved successfully - * - ``RTEMS_INVALID_ID`` - - invalid rate monotonic period id - * - ``RTEMS_INVALID_ADDRESS`` - - invalid address of status - * - ``RTEMS_NOT_DEFINED`` - - no status is available due to the cpu usage of the task having been - reset since the period initiated - -*DESCRIPTION: - This directive returns status information associated with the rate - monotonic period id in the following data structure: - - .. index:: rtems_rate_monotonic_period_status - - .. code-block:: c - - typedef struct { - rtems_id owner; - rtems_rate_monotonic_period_states state; - rtems_rate_monotonic_period_time_t since_last_period; - rtems_thread_cpu_usage_t executed_since_last_period; - uint32_t postponed_jobs_count; - } rtems_rate_monotonic_period_status; - - .. COMMENT: RATE_MONOTONIC_INACTIVE does not have RTEMS in front of it. - - A configure time option can be used to select whether the time information - is given in ticks or seconds and nanoseconds. The default is seconds and - nanoseconds. If the period's state is ``RATE_MONOTONIC_INACTIVE``, both - time values will be set to 0. Otherwise, both time values will contain - time information since the last invocation of the - ``rtems_rate_monotonic_period`` directive. More specifically, the - since_last_period value contains the elapsed time which has occurred since - the last invocation of the ``rtems_rate_monotonic_period`` directive and - the ``executed_since_last_period`` contains how much processor time the - owning task has consumed since the invocation of the - ``rtems_rate_monotonic_period`` directive. In addition, the - ``postponed_jobs_count value`` contains the count of jobs which are not - released yet. - -NOTES: - This directive will not cause the running task to be preempted. + +.. _InterfaceRtemsRateMonotonicGetStatus: + +rtems_rate_monotonic_get_status() +--------------------------------- + +Gets the detailed status of the period. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_rate_monotonic_get_status( + rtems_id id, + rtems_rate_monotonic_period_status *status + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the rate monotonic period identifier. + +``status`` + This parameter is the pointer to an + :ref:`InterfaceRtemsRateMonotonicPeriodStatus` object. When the directive + call is successful, the detailed period status will be stored in this + object. + +.. rubric:: DESCRIPTION: + +This directive returns the detailed status of the rate monotonic period +specified by ``id``. The detailed status of the period will be returned in the +members of the period status object referenced by ``status``: + +* The ``owner`` member is set to the identifier of the owner task of the + period. + +* The ``state`` member is set to the current state of the period. + +* The ``postponed_jobs_count`` member is set to the count of jobs which are not + released yet. + +* If the current state of the period is :c:macro:`RATE_MONOTONIC_INACTIVE`, the + ``since_last_period`` and ``executed_since_last_period`` members will be set + to zero. Otherwise, both members will contain time information since the + last successful invocation of the :ref:`InterfaceRtemsRateMonotonicPeriod` + directive by the owner task. More specifically, the ``since_last_period`` + member will be set to the time elapsed since the last successful invocation. + The ``executed_since_last_period`` member will be set to the processor time + consumed by the owner task since the last successful invocation. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no rate monotonic period associated with the identifier specified + by ``id``. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``status`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within task context. + +* The directive may be called from within interrupt context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/ratemon/if/get-statistics .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_rate_monotonic_get_statistics() .. index:: get statistics of period .. index:: obtain statistics of period -.. index:: rtems_rate_monotonic_get_statistics - -.. _rtems_rate_monotonic_get_statistics: - -RATE_MONOTONIC_GET_STATISTICS - Obtain statistics from a period ---------------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_rate_monotonic_get_statistics( - rtems_id id, - rtems_rate_monotonic_period_statistics *statistics - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - period statistics retrieved successfully - * - ``RTEMS_INVALID_ID`` - - invalid rate monotonic period id - * - ``RTEMS_INVALID_ADDRESS`` - - invalid address of statistics - -DESCRIPTION: - This directive returns statistics information associated with the rate - monotonic period id in the following data structure: - - .. index:: rtems_rate_monotonic_period_statistics - - .. code-block:: c - - typedef struct { - uint32_t count; - uint32_t missed_count; - #ifdef RTEMS_ENABLE_NANOSECOND_CPU_USAGE_STATISTICS - struct timespec min_cpu_time; - struct timespec max_cpu_time; - struct timespec total_cpu_time; - #else - uint32_t min_cpu_time; - uint32_t max_cpu_time; - uint32_t total_cpu_time; - #endif - #ifdef RTEMS_ENABLE_NANOSECOND_RATE_MONOTONIC_STATISTICS - struct timespec min_wall_time; - struct timespec max_wall_time; - struct timespec total_wall_time; - #else - uint32_t min_wall_time; - uint32_t max_wall_time; - uint32_t total_wall_time; - #endif - } rtems_rate_monotonic_period_statistics; - - This directive returns the current statistics information for the period - instance assocaited with ``id``. The information returned is indicated by - the structure above. - -NOTES: - This directive will not cause the running task to be preempted. + +.. _InterfaceRtemsRateMonotonicGetStatistics: + +rtems_rate_monotonic_get_statistics() +------------------------------------- + +Gets the statistics of the period. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_rate_monotonic_get_statistics( + rtems_id id, + rtems_rate_monotonic_period_statistics *status + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the rate monotonic period identifier. + +``status`` + This parameter is the pointer to an + :ref:`InterfaceRtemsRateMonotonicPeriodStatistics` object. When the + directive call is successful, the period statistics will be stored in this + object. + +.. rubric:: DESCRIPTION: + +This directive returns the statistics of the rate monotonic period specified by +``id``. The statistics of the period will be returned in the members of the +period statistics object referenced by ``status``: + +* The ``count`` member is set to the number of periods executed. + +* The ``missed_count`` member is set to the number of periods missed. + +* The ``min_cpu_time`` member is set to the least amount of processor time used + in the period. + +* The ``max_cpu_time`` member is set to the highest amount of processor time + used in the period. + +* The ``total_cpu_time`` member is set to the total amount of processor time + used in the period. + +* The ``min_wall_time`` member is set to the least amount of + :term:`CLOCK_MONOTONIC` time used in the period. + +* The ``max_wall_time`` member is set to the highest amount of + :term:`CLOCK_MONOTONIC` time used in the period. + +* The ``total_wall_time`` member is set to the total amount of + :term:`CLOCK_MONOTONIC` time used in the period. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no rate monotonic period associated with the identifier specified + by ``id``. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``status`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within task context. + +* The directive may be called from within interrupt context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/ratemon/if/reset-statistics .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_rate_monotonic_reset_statistics() .. index:: reset statistics of period -.. index:: rtems_rate_monotonic_reset_statistics -.. _rtems_rate_monotonic_reset_statistics: +.. _InterfaceRtemsRateMonotonicResetStatistics: + +rtems_rate_monotonic_reset_statistics() +--------------------------------------- + +Resets the statistics of the period. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_rate_monotonic_reset_statistics( rtems_id id ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the rate monotonic period identifier. -RATE_MONOTONIC_RESET_STATISTICS - Reset statistics for a period ---------------------------------------------------------------- +.. rubric:: DESCRIPTION: -CALLING SEQUENCE: - .. code-block:: c +This directive resets the statistics of the rate monotonic period specified by +``id``. - rtems_status_code rtems_rate_monotonic_reset_statistics( - rtems_id id - ); +.. rubric:: RETURN VALUES: -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. - * - ``RTEMS_SUCCESSFUL`` - - period initiated successfully - * - ``RTEMS_INVALID_ID`` - - invalid rate monotonic period id +:c:macro:`RTEMS_INVALID_ID` + There was no rate monotonic period associated with the identifier specified + by ``id``. -DESCRIPTION: - This directive resets the statistics information associated with this rate - monotonic period instance. +.. rubric:: CONSTRAINTS: -NOTES: - This directive will not cause the running task to be preempted. +The following constraints apply to this directive: + +* The directive may be called from within task context. + +* The directive may be called from within interrupt context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/ratemon/if/reset-all-statistics .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_rate_monotonic_reset_all_statistics() .. index:: reset statistics of all periods -.. index:: rtems_rate_monotonic_reset_all_statistics -.. _rtems_rate_monotonic_reset_all_statistics: +.. _InterfaceRtemsRateMonotonicResetAllStatistics: + +rtems_rate_monotonic_reset_all_statistics() +------------------------------------------- + +Resets the statistics of all periods. -RATE_MONOTONIC_RESET_ALL_STATISTICS - Reset statistics for all periods ----------------------------------------------------------------------- +.. rubric:: CALLING SEQUENCE: -CALLING SEQUENCE: - .. code-block:: c +.. code-block:: c - void rtems_rate_monotonic_reset_all_statistics(void); + void rtems_rate_monotonic_reset_all_statistics( void ); -DIRECTIVE STATUS CODES: - NONE +.. rubric:: 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. +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within task context. + +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. + +.. Generated from spec:/rtems/ratemon/if/report-statistics .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_rate_monotonic_report_statistics() .. index:: print period statistics report .. index:: period statistics report -.. index:: rtems_rate_monotonic_report_statistics -.. _rtems_rate_monotonic_report_statistics: +.. _InterfaceRtemsRateMonotonicReportStatistics: + +rtems_rate_monotonic_report_statistics() +---------------------------------------- + +Reports the period statistics using the :ref:`InterfacePrintk` printer. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_rate_monotonic_report_statistics( void ); + +.. rubric:: DESCRIPTION: + +This directive prints a report on all active periods which have executed at +least one period using the :ref:`InterfacePrintk` printer. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within task context. + +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. + +.. Generated from spec:/rtems/ratemon/if/report-statistics-with-plugin + +.. raw:: latex + + \clearpage + +.. index:: rtems_rate_monotonic_report_statistics_with_plugin() +.. index:: print period statistics report +.. index:: period statistics report + +.. _InterfaceRtemsRateMonotonicReportStatisticsWithPlugin: + +rtems_rate_monotonic_report_statistics_with_plugin() +---------------------------------------------------- + +Reports the period statistics using the printer plugin. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c -RATE_MONOTONIC_REPORT_STATISTICS - Print period statistics report ------------------------------------------------------------------ + void rtems_rate_monotonic_report_statistics_with_plugin( + const struct rtems_printer *printer + ); -CALLING SEQUENCE: - .. code-block:: c +.. rubric:: PARAMETERS: - void rtems_rate_monotonic_report_statistics(void); +``printer`` + This parameter is the printer plugin to output the report. -DIRECTIVE STATUS CODES: - NONE +.. rubric:: DESCRIPTION: -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. +This directive prints a report on all active periods which have executed at +least one period using the printer plugin specified by ``printer``. - .. index:: rtems_rate_monotonic_period_statistics +.. rubric:: CONSTRAINTS: - .. code-block:: c +The following constraints apply to this directive: - 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 +* The directive may be called from within task context. -NOTES: - This directive will not cause the running task to be preempted. +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. diff --git a/c-user/rate-monotonic/index.rst b/c-user/rate-monotonic/index.rst index a703ca0..9c5b4b6 100644 --- a/c-user/rate-monotonic/index.rst +++ b/c-user/rate-monotonic/index.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020 embedded brains GmbH & Co. KG .. index:: rate mononitonic tasks .. index:: periodic tasks diff --git a/c-user/rate-monotonic/introduction.rst b/c-user/rate-monotonic/introduction.rst index cb09898..b33b0b8 100644 --- a/c-user/rate-monotonic/introduction.rst +++ b/c-user/rate-monotonic/introduction.rst @@ -1,33 +1,76 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 2017 Kuan-Hsun Chen .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) -.. Copyright (C) 2017 Kuan-Hsun Chen. + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/rtems/ratemon/if/group + +.. _RateMonotonicManagerIntroduction: Introduction ============ -The rate monotonic manager provides facilities to implement tasks which execute +.. The following list was generated from: +.. spec:/rtems/ratemon/if/create +.. spec:/rtems/ratemon/if/ident +.. spec:/rtems/ratemon/if/cancel +.. spec:/rtems/ratemon/if/delete +.. spec:/rtems/ratemon/if/period +.. spec:/rtems/ratemon/if/get-status +.. spec:/rtems/ratemon/if/get-statistics +.. spec:/rtems/ratemon/if/reset-statistics +.. spec:/rtems/ratemon/if/reset-all-statistics +.. spec:/rtems/ratemon/if/report-statistics +.. spec:/rtems/ratemon/if/report-statistics-with-plugin + +The Rate-Monotonic Manager provides facilities to implement tasks which execute in a periodic fashion. Critically, it also gathers information about the execution of those periods and can provide important statistics to the user -which can be used to analyze and tune the application. The directives provided -by the rate monotonic manager are: +which can be used to analyze and tune the application. The directives provided +by the Rate-Monotonic Manager are: + +* :ref:`InterfaceRtemsRateMonotonicCreate` - Creates a period. -- :ref:`rtems_rate_monotonic_create` +* :ref:`InterfaceRtemsRateMonotonicIdent` - Identifies a period by the object + name. -- :ref:`rtems_rate_monotonic_ident` +* :ref:`InterfaceRtemsRateMonotonicCancel` - Cancels the period. -- :ref:`rtems_rate_monotonic_cancel` +* :ref:`InterfaceRtemsRateMonotonicDelete` - Deletes the period. -- :ref:`rtems_rate_monotonic_delete` +* :ref:`InterfaceRtemsRateMonotonicPeriod` - Concludes the current period and + start the next period, or gets the period status. -- :ref:`rtems_rate_monotonic_period` +* :ref:`InterfaceRtemsRateMonotonicGetStatus` - Gets the detailed status of the + period. -- :ref:`rtems_rate_monotonic_get_status` +* :ref:`InterfaceRtemsRateMonotonicGetStatistics` - Gets the statistics of the + period. -- :ref:`rtems_rate_monotonic_get_statistics` +* :ref:`InterfaceRtemsRateMonotonicResetStatistics` - Resets the statistics of + the period. -- :ref:`rtems_rate_monotonic_reset_statistics` +* :ref:`InterfaceRtemsRateMonotonicResetAllStatistics` - Resets the statistics + of all periods. -- :ref:`rtems_rate_monotonic_reset_all_statistics` +* :ref:`InterfaceRtemsRateMonotonicReportStatistics` - Reports the period + statistics using the :ref:`InterfacePrintk` printer. -- :ref:`rtems_rate_monotonic_report_statistics` +* :ref:`InterfaceRtemsRateMonotonicReportStatisticsWithPlugin` - Reports the + period statistics using the printer plugin. diff --git a/c-user/region/directives.rst b/c-user/region/directives.rst index be994f6..557b89e 100644 --- a/c-user/region/directives.rst +++ b/c-user/region/directives.rst @@ -1,561 +1,916 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. _RegionManagerDirectives: + Directives ========== -This section details the 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. +This section details the directives of the Region Manager. A subsection is +dedicated to each of this manager's directives and lists the calling sequence, +parameters, description, return values, and notes of the directive. + +.. Generated from spec:/rtems/region/if/create .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_region_create() .. index:: create a region -.. _rtems_region_create: +.. _InterfaceRtemsRegionCreate: -REGION_CREATE - Create a region -------------------------------- +rtems_region_create() +--------------------- + +Creates a region. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_region_create( + rtems_name name, + void *starting_address, + uintptr_t length, + uintptr_t page_size, + rtems_attribute attribute_set, + rtems_id *id + ); + +.. rubric:: PARAMETERS: + +``name`` + This parameter is the object name of the region. + +``starting_address`` + This parameter is the starting address of the memory area managed by the + region. + +``length`` + This parameter is the length in bytes of the memory area managed by the + region. + +``page_size`` + This parameter is the alignment of the starting address and length of each + allocated segment of the region. + +``attribute_set`` + This parameter is the attribute set of the region. + +``id`` + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the identifier of the created region will + be stored in this object. + +.. rubric:: DESCRIPTION: + +This directive creates a region which resides on the local node. The region +has the user-defined object name specified in ``name``. The assigned object +identifier is returned in ``id``. This identifier is used to access the region +with other region related directives. + +The region manages the **contiguous memory area** which starts at +``starting_address`` and is ``length`` bytes long. The memory area shall be +large enough to contain some internal region administration data. + +The **starting address** and **length of segments** allocated from the region +will be an integral multiple of ``page_size``. The specified page size will be +aligned to an implementation-dependent minimum alignment if necessary. + +The **attribute set** specified in ``attribute_set`` is built through a +*bitwise or* of the attribute constants described below. Not all combinations +of attributes are allowed. Some attributes are mutually exclusive. If +mutually exclusive attributes are combined, the behaviour is undefined. +Attributes not mentioned below are not evaluated by this directive and have no +effect. Default attributes can be selected by using the +:c:macro:`RTEMS_DEFAULT_ATTRIBUTES` constant. + +The **task wait queue discipline** is selected by the mutually exclusive +:c:macro:`RTEMS_FIFO` and :c:macro:`RTEMS_PRIORITY` attributes. The discipline +defines the order in which tasks wait for allocatable segments on a currently +empty region. + +* The **FIFO discipline** is the default and can be emphasized through use of + the :c:macro:`RTEMS_FIFO` attribute. + +* The **priority discipline** is selected by the :c:macro:`RTEMS_PRIORITY` + attribute. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_NAME` + The ``name`` parameter was invalid. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``id`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``starting_address`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_TOO_MANY` + There was no inactive object available to create a region. The number of + regions available to the application is configured through the + :ref:`CONFIGURE_MAXIMUM_REGIONS` application configuration option. + +:c:macro:`RTEMS_INVALID_SIZE` + The ``page_size`` parameter was invalid. + +:c:macro:`RTEMS_INVALID_SIZE` + The memory area specified in ``starting_address`` and ``length`` was too + small. -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_region_create( - rtems_name name, - void *starting_address, - uintptr_t length, - uintptr_t page_size, - rtems_attribute attribute_set, - rtems_id *id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - region created successfully - * - ``RTEMS_INVALID_NAME`` - - invalid region name - * - ``RTEMS_INVALID_ADDRESS`` - - ``id`` is NULL - * - ``RTEMS_INVALID_ADDRESS`` - - ``starting_address`` is NULL - * - ``RTEMS_TOO_MANY`` - - too many regions created - * - ``RTEMS_INVALID_SIZE`` - - invalid page size - * - ``RTEMS_INVALID_SIZE`` - - the memory area defined by the starting address and the length - parameters is too small - -DESCRIPTION: - This directive creates a region from a contiguous memory area - which starts at starting_address and is length bytes long. The memory area - must be large enough to contain some internal region administration data. - Segments allocated from the region will be a multiple of page_size bytes in - length. The specified page size will be aligned to an - architecture-specific minimum alignment if necessary. - - The assigned region id is returned in id. This region id is used as an - argument to other region related directives to access the region. - - For control and maintenance of the region, RTEMS allocates and initializes - an RNCB from the RNCB free pool. Thus memory from the region is not used - to store the RNCB. However, some overhead within the region is required by - RTEMS each time a segment is constructed in the region. - - Specifying ``RTEMS_PRIORITY`` in attribute_set causes tasks waiting for a - segment to be serviced according to task priority. Specifying - ``RTEMS_FIFO`` in attribute_set or selecting ``RTEMS_DEFAULT_ATTRIBUTES`` - will cause waiting tasks to be serviced in First In-First Out order. - -NOTES: - This directive will obtain the allocator mutex and may cause the calling - task to be preempted. - - The following region attribute constants are defined by RTEMS: - - .. list-table:: - :class: rtems-table - - * - ``RTEMS_FIFO`` - - tasks wait by FIFO (default) - * - ``RTEMS_PRIORITY`` - - tasks wait by priority +.. rubric:: NOTES: + +For control and maintenance of the region, RTEMS allocates a :term:`RNCB` from +the local RNCB free pool and initializes it. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. + +* The number of regions available to the application is configured through the + :ref:`CONFIGURE_MAXIMUM_REGIONS` application configuration option. + +* Where the object class corresponding to the directive is configured to use + unlimited objects, the directive may allocate memory from the RTEMS + Workspace. + +.. Generated from spec:/rtems/region/if/ident .. raw:: latex - \clearpage + \clearpage + +.. index:: rtems_region_ident() + +.. _InterfaceRtemsRegionIdent: + +rtems_region_ident() +-------------------- + +Identifies a region by the object name. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c -.. index:: get ID of a region -.. index:: obtain ID of a region -.. index:: rtems_region_ident + rtems_status_code rtems_region_ident( rtems_name name, rtems_id *id ); -.. _rtems_region_ident: +.. rubric:: PARAMETERS: -REGION_IDENT - Get ID of a region ---------------------------------- +``name`` + This parameter is the object name to look up. -CALLING SEQUENCE: - .. code-block:: c +``id`` + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the object identifier of an object with + the specified name will be stored in this object. - rtems_status_code rtems_region_ident( - rtems_name name, - rtems_id *id - ); +.. rubric:: DESCRIPTION: -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +This directive obtains a region identifier associated with the region name +specified in ``name``. - * - ``RTEMS_SUCCESSFUL`` - - region identified successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``id`` is NULL - * - ``RTEMS_INVALID_NAME`` - - region name not found +.. rubric:: RETURN VALUES: -DESCRIPTION: +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. - 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. +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``id`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. -NOTES: - This directive will not cause the running task to be preempted. +:c:macro:`RTEMS_INVALID_NAME` + The ``name`` parameter was 0. + +:c:macro:`RTEMS_INVALID_NAME` + There was no object with the specified name on the local node. + +.. rubric:: NOTES: + +If the region name is not unique, then the region identifier will match the +first region with that name in the search order. However, this region +identifier is not guaranteed to correspond to the desired region. + +The objects are searched from lowest to the highest index. Only the local node +is searched. + +The region identifier is used with other region related directives to access +the region. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/region/if/delete .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_region_delete() .. index:: delete a region -.. index:: rtems_region_delete -.. _rtems_region_delete: +.. _InterfaceRtemsRegionDelete: -REGION_DELETE - Delete a region -------------------------------- +rtems_region_delete() +--------------------- + +Deletes the region. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_region_delete( rtems_id id ); -CALLING SEQUENCE: - .. code-block:: c +.. rubric:: PARAMETERS: - rtems_status_code rtems_region_delete( - rtems_id id - ); +``id`` + This parameter is the region identifier. -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +.. rubric:: DESCRIPTION: - * - ``RTEMS_SUCCESSFUL`` - - region deleted successfully - * - ``RTEMS_INVALID_ID`` - - invalid region id - * - ``RTEMS_RESOURCE_IN_USE`` - - segments still in use +This directive deletes the region specified by ``id``. -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. +.. rubric:: RETURN VALUES: -NOTES: - This directive will obtain the allocator mutex and may cause the calling - task to be preempted. +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. - 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. +:c:macro:`RTEMS_INVALID_ID` + There was no region associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_RESOURCE_IN_USE` + There were segments of the region still in use. + +.. rubric:: NOTES: + +The region cannot be deleted if any of its segments are still allocated. + +The :term:`RNCB` for the deleted region is reclaimed by RTEMS. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. + +* The calling task does not have to be the task that created the object. Any + local task that knows the object identifier can delete the object. + +* Where the object class corresponding to the directive is configured to use + unlimited objects, the directive may free memory to the RTEMS Workspace. + +.. Generated from spec:/rtems/region/if/extend .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_region_extend() .. index:: add memory to a region .. index:: region, add memory -.. index:: rtems_region_extend - -.. _rtems_region_extend: - -REGION_EXTEND - Add memory to a region --------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_region_extend( - rtems_id id, - void *starting_address, - uintptr_t length - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - region extended successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``starting_address`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid region id - * - ``RTEMS_INVALID_ADDRESS`` - - invalid address of area to add - -DESCRIPTION: - This directive adds the memory area which starts at - :c:data:`starting_address` for :c:data:`length` bytes to the region - specified by :c:data:`id`. - - There are no alignment requirements for the memory area. The memory area - must be big enough to contain some maintenance blocks. It must not overlap - parts of the current heap memory areas. Disconnected memory areas added to - the heap will lead to used blocks which cover the gaps. Extending with an - inappropriate memory area will corrupt the heap resulting in undefined - behaviour. - -NOTES: - This directive will obtain the allocator mutex and may cause the calling - task to be preempted. - - The calling task does not have to be the task that created the region. Any - local task that knows the region identifier can extend the region. + +.. _InterfaceRtemsRegionExtend: + +rtems_region_extend() +--------------------- + +Extends the region. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_region_extend( + rtems_id id, + void *starting_address, + uintptr_t length + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the region identifier. + +``starting_address`` + This parameter is the starting address of the memory area to extend the + region. + +``length`` + This parameter is the length in bytes of the memory area to extend the + region. + +.. rubric:: DESCRIPTION: + +This directive adds the memory area which starts at ``starting_address`` for +``length`` bytes to the region specified by ``id``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``starting_address`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no region associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The memory area specified by ``starting_address`` and ``length`` was + insufficient to extend the heap. + +.. rubric:: NOTES: + +There are no alignment requirements for the memory area. The memory area must +be big enough to contain some maintenance blocks. It must not overlap parts of +the current heap memory areas. Disconnected memory areas added to the heap +will lead to used blocks which cover the gaps. Extending with an inappropriate +memory area will corrupt the heap resulting in undefined behaviour. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. + +.. Generated from spec:/rtems/region/if/get-segment .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_region_get_segment() .. index:: get segment from region -.. index:: rtems_region_get_segment - -.. _rtems_region_get_segment: - -REGION_GET_SEGMENT - Get segment from a region ----------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_region_get_segment( - rtems_id id, - uintptr_t size, - rtems_option option_set, - rtems_interval timeout, - void **segment - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - segment obtained successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``segment`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid region id - * - ``RTEMS_INVALID_SIZE`` - - request is for zero bytes or exceeds the size of maximum segment which is - possible for this region - * - ``RTEMS_UNSATISFIED`` - - segment of requested size not available - * - ``RTEMS_TIMEOUT`` - - timed out waiting for segment - * - ``RTEMS_OBJECT_WAS_DELETED`` - - region deleted while waiting - -DESCRIPTION: - This directive obtains a variable size segment from the region specified by - ``id``. The address of the allocated segment is returned in segment. The - ``RTEMS_WAIT`` and ``RTEMS_NO_WAIT`` components of the options parameter - are used to specify whether the calling tasks wish to wait for a segment to - become available or return immediately if no segment is available. For - either option, if a sufficiently sized segment is available, then the - segment is successfully acquired by returning immediately with the - ``RTEMS_SUCCESSFUL`` status code. - - If the calling task chooses to return immediately and a segment large - enough is not available, then an error code indicating this fact is - returned. If the calling task chooses to wait for the segment and a - segment large enough is not available, then the calling task is placed on - the region's segment wait queue and blocked. If the region was created - with the ``RTEMS_PRIORITY`` option, then the calling task is inserted into - the wait queue according to its priority. However, if the region was - created with the ``RTEMS_FIFO`` option, then the calling task is placed at - the rear of the wait queue. - - The timeout parameter specifies the maximum interval that a task is willing - to wait to obtain a segment. If timeout is set to ``RTEMS_NO_TIMEOUT``, - then the calling task will wait forever. - -NOTES: - This directive will obtain the allocator mutex and may cause the calling - task to be preempted. - - The actual length of the allocated segment may be larger than the requested - size because a segment size is always a multiple of the region's page size. - - The following segment acquisition option constants are defined by RTEMS: - - .. list-table:: - :class: rtems-table - - * - ``RTEMS_WAIT`` - - task will wait for segment (default) - * - ``RTEMS_NO_WAIT`` - - task should not wait - - A clock tick is required to support the timeout functionality of this - directive. + +.. _InterfaceRtemsRegionGetSegment: + +rtems_region_get_segment() +-------------------------- + +Gets a segment from the region. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_region_get_segment( + rtems_id id, + uintptr_t size, + rtems_option option_set, + rtems_interval timeout, + void **segment + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the region identifier. + +``size`` + This parameter is the size in bytes of the segment to allocate. + +``option_set`` + This parameter is the option set. + +``timeout`` + This parameter is the timeout in :term:`clock ticks <clock tick>` if the + :c:macro:`RTEMS_WAIT` option is set. Use :c:macro:`RTEMS_NO_TIMEOUT` to + wait potentially forever. + +``segment`` + This parameter is the pointer to a ``void`` pointer object. When the + directive call is successful, the begin address of the allocated segment + will be stored in this object. + +.. rubric:: DESCRIPTION: + +This directive gets a segment from the region specified by ``id``. + +The **option set** specified in ``option_set`` is built through a *bitwise or* +of the option constants described below. Not all combinations of options are +allowed. Some options are mutually exclusive. If mutually exclusive options +are combined, the behaviour is undefined. Options not mentioned below are not +evaluated by this directive and have no effect. Default options can be selected +by using the :c:macro:`RTEMS_DEFAULT_OPTIONS` constant. + +The calling task can **wait** or **try to get** a segment from the region +according to the mutually exclusive :c:macro:`RTEMS_WAIT` and +:c:macro:`RTEMS_NO_WAIT` options. + +* **Waiting to get** a segment from the region is the default and can be + emphasized through the use of the :c:macro:`RTEMS_WAIT` option. The + ``timeout`` parameter defines how long the calling task is willing to wait. + Use :c:macro:`RTEMS_NO_TIMEOUT` to wait potentially forever, otherwise set a + timeout interval in clock ticks. + +* **Trying to get** a segment from the region is selected by the + :c:macro:`RTEMS_NO_WAIT` option. If this option is defined, then the + ``timeout`` parameter is ignored. When a segment from the region cannot be + immediately allocated, then the :c:macro:`RTEMS_UNSATISFIED` status is + returned. + +With either :c:macro:`RTEMS_WAIT` or :c:macro:`RTEMS_NO_WAIT` if there is a +segment of the requested size is available, then it is returned in ``segment`` +and this directive returns immediately with the :c:macro:`RTEMS_SUCCESSFUL` +status code. + +If the calling task chooses to return immediately and the region has no segment +of the requested size available, then the directive returns immediately with +the :c:macro:`RTEMS_UNSATISFIED` status code. If the calling task chooses to +wait for a segment, then the calling task is placed on the region wait queue +and blocked. If the region was created with the :c:macro:`RTEMS_PRIORITY` +option specified, then the calling task is inserted into the wait queue +according to its priority. But, if the region was created with the +:c:macro:`RTEMS_FIFO` option specified, then the calling task is placed at the +rear of the wait queue. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``segment`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_SIZE` + The ``size`` parameter was zero. + +:c:macro:`RTEMS_INVALID_ID` + There was no region associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_INVALID_SIZE` + The ``size`` parameter exceeded the maximum segment size which is possible + for the region. + +:c:macro:`RTEMS_UNSATISFIED` + The region had no segment of the requested size immediately available. + +:c:macro:`RTEMS_TIMEOUT` + The timeout happened while the calling task was waiting to get a segment + from the region. + +.. rubric:: NOTES: + +The actual length of the allocated segment may be larger than the requested +size because a segment size is always a multiple of the region's page size. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. + +* When the request cannot be immediately satisfied and the + :c:macro:`RTEMS_WAIT` option is set, the calling task blocks at some point + during the directive call. + +* The timeout functionality of the directive requires a :term:`clock tick`. + +.. Generated from spec:/rtems/region/if/return-segment .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_region_return_segment() .. index:: return segment to region -.. index:: rtems_region_return_segment -.. _rtems_region_return_segment: +.. _InterfaceRtemsRegionReturnSegment: -REGION_RETURN_SEGMENT - Return segment to a region --------------------------------------------------- +rtems_region_return_segment() +----------------------------- -CALLING SEQUENCE: - .. code-block:: c +Returns the segment to the region. - rtems_status_code rtems_region_return_segment( - rtems_id id, - void *segment - ); +.. rubric:: CALLING SEQUENCE: -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +.. code-block:: c - * - ``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_status_code rtems_region_return_segment( rtems_id id, void *segment ); -DESCRIPTION: - This directive returns the segment specified by segment to the region - specified by id. The returned segment is merged with its neighbors to form - the largest possible segment. The first task on the wait queue is examined - to determine if its segment request can now be satisfied. If so, it is - given a segment and unblocked. This process is repeated until the first - task's segment request cannot be satisfied. +.. rubric:: PARAMETERS: -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: +``id`` + This parameter is the region identifier. - - a waiting task has a higher priority than the calling task +``segment`` + This parameter is the begin address of the segment to return. - - the size of the segment required by the waiting task is less than or - equal to the size of the segment returned. +.. rubric:: DESCRIPTION: -.. raw:: latex +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. - \clearpage +.. rubric:: RETURN VALUES: -.. index:: get size of segment -.. index:: rtems_region_get_segment_size +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no region associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The segment was not within the region. -.. _rtems_region_get_segment_size: +.. rubric:: NOTES: -REGION_GET_SEGMENT_SIZE - Obtain size of a segment --------------------------------------------------- +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: -CALLING SEQUENCE: - .. code-block:: c +* A waiting task has a higher priority than the calling task. - rtems_status_code rtems_region_get_segment_size( - rtems_id id, - void *segment, - uintptr_t *size - ); +* The size of the segment required by the waiting task is less than or equal to + the size of the segment returned. -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +.. rubric:: CONSTRAINTS: - * - ``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 +The following constraints apply to this directive: -DESCRIPTION: - This directive obtains the size in bytes of the specified segment. +* The directive may be called from within device driver initialization context. -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 directive may be called from within task context. + +* The directive may unblock a task. This may cause the calling task to be + preempted. + +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. + +.. Generated from spec:/rtems/region/if/resize-segment .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_region_resize_segment() .. index:: resize segment -.. index:: rtems_region_resize_segment - -.. _rtems_region_resize_segment: - -REGION_RESIZE_SEGMENT - Change size of a segment ------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_region_resize_segment( - rtems_id id, - void *segment, - uintptr_t new_size, - uintptr_t *old_size - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - segment obtained successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``segment`` is NULL - * - ``RTEMS_INVALID_ADDRESS`` - - ``old_size`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid region id - * - ``RTEMS_INVALID_ADDRESS`` - - segment address not in region - * - ``RTEMS_UNSATISFIED`` - - unable to make segment larger - -DESCRIPTION: - This directive is used to increase or decrease the size of a segment. When - increasing the size of a segment, it is possible that there is not memory - available contiguous to the segment. In this case, the request is - unsatisfied. - -NOTES: - This directive will obtain the allocator mutex and may cause the calling - task to be preempted. - - If an attempt to increase the size of a segment fails, then the application - may want to allocate a new segment of the desired size, copy the contents - of the original segment to the new, larger segment and then return the - original segment. + +.. _InterfaceRtemsRegionResizeSegment: + +rtems_region_resize_segment() +----------------------------- + +Changes the size of the segment. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_region_resize_segment( + rtems_id id, + void *segment, + uintptr_t size, + uintptr_t *old_size + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the region identifier. + +``segment`` + This parameter is the begin address of the segment to resize. + +``size`` + This parameter is the requested new size of the segment. + +``old_size`` + This parameter is the pointer to an `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_ object. When the + directive call is successful, the old size of the segment will be stored in + this object. + +.. rubric:: DESCRIPTION: + +This directive is used to increase or decrease the size of the ``segment`` of +the region specified by ``id``. When increasing the size of a segment, it is +possible that there is no memory available contiguous to the segment. In this +case, the request is unsatisfied. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``old_size`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no region associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The segment was not within the region. + +:c:macro:`RTEMS_UNSATISFIED` + The region was unable to resize the segment. + +.. rubric:: NOTES: + +If an attempt to increase the size of a segment fails, then the application may +want to allocate a new segment of the desired size, copy the contents of the +original segment to the new, larger segment and then return the original +segment. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. + +.. Generated from spec:/rtems/region/if/get-information .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_region_get_information() .. index:: obtain region information -.. index:: rtems_region_get_information -.. _rtems_region_get_information: +.. _InterfaceRtemsRegionGetInformation: + +rtems_region_get_information() +------------------------------ + +Gets the region information. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_region_get_information( + rtems_id id, + Heap_Information_block *the_info + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the region identifier. + +``the_info`` + This parameter is the pointer to a :c:type:`Heap_Information_block` object. + When the directive call is successful, the information of the region will + be stored in this object. + +.. rubric:: DESCRIPTION: + +This directive is used to obtain information about the used and free memory in +the region specified by ``id``. This is a snapshot at the time of the call. The +information will be returned in the structure pointed to by ``the_info``. + +.. rubric:: RETURN VALUES: -REGION_GET_INFORMATION - Get region information ------------------------------------------------ +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. -CALLING SEQUENCE: - .. code-block:: c +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``the_info`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. - rtems_status_code rtems_region_get_information( - rtems_id id, - Heap_Information_block *the_info - ); +:c:macro:`RTEMS_INVALID_ID` + There was no region associated with the identifier specified by ``id``. -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +.. rubric:: NOTES: - * - ``RTEMS_SUCCESSFUL`` - - information obtained successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``the_info`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid region id +This is primarily intended as a mechanism to obtain a diagnostic information. +This method forms am O(n) scan of the free and an O(n) scan of the used blocks +in the region to calculate the information provided. Given that the execution +time is driven by the number of used and free blocks, it can take a +non-deterministic time to execute. -DESCRIPTION: - This directive is used to obtain information about the used and free memory - in the region specified by ``id``. This is a snapshot at the time - of the call. The information will be returned in the structure pointed to - by ``the_info``. +To get only the free information of the region use +:ref:`InterfaceRtemsRegionGetFreeInformation`. -NOTES: - This directive will obtain the allocator mutex and may cause the calling - task to be preempted. +.. rubric:: CONSTRAINTS: - This is primarily intended as a mechanism to obtain a diagnostic information. - This method forms am O(n) scan of the free and an O(n) scan of the - used blocks in the region to calculate the information provided. Given that - the execution time is driven by the number of used and free blocks, it can - take a non-deterministic time to execute. +The following constraints apply to this directive: + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. + +.. Generated from spec:/rtems/region/if/get-free-information .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_region_get_free_information() .. index:: obtain region information on free blocks -.. index:: rtems_region_get_free_information - -.. _rtems_region_get_free_information: - -REGION_GET_FREE_INFORMATION - Get region free information ---------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_region_get_free_information( - rtems_id id, - Heap_Information_block *the_info - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - information obtained successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``the_info`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid region id - -DESCRIPTION: - This directive is used to obtain information about the free memory - in the region specified by ``id``. This is a snapshot at the time - of the call. The information will be returned in the structure pointed to - by ``the_info``. - -NOTES: - This directive will obtain the allocator mutex and may cause the calling - task to be preempted. - - This uses the same structure to return information as the - ``rtems_region_get_information`` directive but does not fill in the - used information. - - This is primarily intended as a mechanism to obtain a diagnostic information. - This method forms am O(n) scan of the free in the region to calculate - the information provided. Given that the execution time is driven by - the number of used and free blocks, it can take a non-deterministic - time to execute. Typically, there are many used blocks and a much smaller - number of used blocks making a call to this directive less expensive than - a call to ``rtems_region_get_information``. + +.. _InterfaceRtemsRegionGetFreeInformation: + +rtems_region_get_free_information() +----------------------------------- + +Gets the region free information. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_region_get_free_information( + rtems_id id, + Heap_Information_block *the_info + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the region identifier. + +``the_info`` + This parameter is the pointer to a :c:type:`Heap_Information_block` object. + When the directive call is successful, the free information of the region + will be stored in this object. + +.. rubric:: DESCRIPTION: + +This directive is used to obtain information about the free memory in the +region specified by ``id``. This is a snapshot at the time of the call. The +information will be returned in the structure pointed to by ``the_info``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``the_info`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no region associated with the identifier specified by ``id``. + +.. rubric:: NOTES: + +This directive uses the same structure to return information as the +:ref:`InterfaceRtemsRegionGetInformation` directive but does not fill in the +used information. + +This is primarily intended as a mechanism to obtain a diagnostic information. +This method forms am O(n) scan of the free in the region to calculate the +information provided. Given that the execution time is driven by the number of +used and free blocks, it can take a non-deterministic time to execute. +Typically, there are many used blocks and a much smaller number of used blocks +making a call to this directive less expensive than a call to +:ref:`InterfaceRtemsRegionGetInformation`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. + +.. Generated from spec:/rtems/region/if/get-segment-size + +.. raw:: latex + + \clearpage + +.. index:: rtems_region_get_segment_size() +.. index:: get size of segment + +.. _InterfaceRtemsRegionGetSegmentSize: + +rtems_region_get_segment_size() +------------------------------- + +Gets the size of the region segment. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_region_get_segment_size( + rtems_id id, + void *segment, + uintptr_t *size + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the region identifier. + +``segment`` + This parameter is the begin address of the segment. + +``size`` + This parameter is the pointer to a `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_ object. When the + directive call is successful, the size of the segment in bytes will be + stored in this object. + +.. rubric:: DESCRIPTION: + +This directive obtains the size in bytes of the segment specified by +``segment`` of the region specified by ``id`` in ``size``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``segment`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``size`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no region associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The segment was not within the region. + +.. rubric:: NOTES: + +The actual length of the allocated segment may be larger than the requested +size because a segment size is always a multiple of the region's page size. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. diff --git a/c-user/region/index.rst b/c-user/region/index.rst index f0be2f7..2fb01ec 100644 --- a/c-user/region/index.rst +++ b/c-user/region/index.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020 embedded brains GmbH & Co. KG .. index:: regions diff --git a/c-user/region/introduction.rst b/c-user/region/introduction.rst index 418e397..ec44d2e 100644 --- a/c-user/region/introduction.rst +++ b/c-user/region/introduction.rst @@ -1,29 +1,63 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/rtems/region/if/group + +.. _RegionManagerIntroduction: + Introduction ============ -The region manager provides facilities to dynamically allocate memory in -variable sized units. The directives provided by the region manager are: +.. The following list was generated from: +.. spec:/rtems/region/if/create +.. spec:/rtems/region/if/ident +.. spec:/rtems/region/if/delete +.. spec:/rtems/region/if/extend +.. spec:/rtems/region/if/get-segment +.. spec:/rtems/region/if/return-segment +.. spec:/rtems/region/if/resize-segment +.. spec:/rtems/region/if/get-information +.. spec:/rtems/region/if/get-free-information +.. spec:/rtems/region/if/get-segment-size + +The Region Manager provides facilities to dynamically allocate memory in +variable sized units. The directives provided by the Region Manager are: -- :ref:`rtems_region_create` +* :ref:`InterfaceRtemsRegionCreate` - Creates a region. -- :ref:`rtems_region_ident` +* :ref:`InterfaceRtemsRegionIdent` - Identifies a region by the object name. -- :ref:`rtems_region_delete` +* :ref:`InterfaceRtemsRegionDelete` - Deletes the region. -- :ref:`rtems_region_extend` +* :ref:`InterfaceRtemsRegionExtend` - Extends the region. -- :ref:`rtems_region_get_segment` +* :ref:`InterfaceRtemsRegionGetSegment` - Gets a segment from the region. -- :ref:`rtems_region_return_segment` +* :ref:`InterfaceRtemsRegionReturnSegment` - Returns the segment to the region. -- :ref:`rtems_region_get_segment_size` +* :ref:`InterfaceRtemsRegionResizeSegment` - Changes the size of the segment. -- :ref:`rtems_region_resize_segment` +* :ref:`InterfaceRtemsRegionGetInformation` - Gets the region information. -- :ref:`rtems_region_get_information` +* :ref:`InterfaceRtemsRegionGetFreeInformation` - Gets the region free + information. -- :ref:`rtems_region_get_free_information` +* :ref:`InterfaceRtemsRegionGetSegmentSize` - Gets the size of the region + segment. diff --git a/c-user/regulator/background.rst b/c-user/regulator/background.rst new file mode 100644 index 0000000..f6a6bff --- /dev/null +++ b/c-user/regulator/background.rst @@ -0,0 +1,90 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2023 On-Line Applications Research Corporation (OAR) + +.. _RegulatorManagerBackground: + +Background +========== +The regulator provides facilities to accept bursty input and buffer it +as needed before delivering it at a pre-defined periodic rate. The input +is referred to as the Source, with the output referred to as the +Destination. Messages are accepted from the Source and delivered to +the Destination by a user-provided Delivery function. + +The Regulator implementation uses the RTEMS Classic API Partition Manager +to manage the buffer pool and the RTEMS Classic API Message Queue +Manager to send the buffer to the Delivery thread. The Delivery thread +invokes a user-provided delivery function to get the message to the +Destination. + +Regulator Buffering +------------------- +The regulator is designed to sit logically between two entities -- a +source and a destination, where it limits the traffic sent to the +destination to prevent it from being flooded with messages from the +source. This can be used to accommodate bursts of input from a source +and meter it out to a destination. The maximum number of messages +which can be buffered in the regulator is specified by the +``maximum_messages`` field in the :ref:`InterfaceRtemsRegulatorAttributes` +structure passed as an argument to :ref:`InterfaceRtemsRegulatorCreate`. + +The regulator library accepts an input stream of messages from a +source and delivers them to a destination. The regulator assumes that the +input stream from the source contains sporadic bursts of data which can +exceed the acceptable rate of the destination. By limiting the message rate, +the regulator prevents an overflow of messages. + +The regulator can be configured for the input buffering required to manage +the maximum burst and for the metering rate for the delivery. The delivery +rate is in messages per second. If the sender produces data too fast, +the regulator will buffer the configured number of messages. + +A configuration capability is provided to allow for adaptation to different +message streams. The regulator can also support running multiple instances, +which could be used on independent message streams. + +It is assumed that the application has a design limit on the number of +messages which may be buffered. All messages accepted by the regulator, +assuming no overflow on input, will eventually be output by the Delivery +thread. + +Message Delivery Rate +--------------------- + +The Source sends buffers to the Regulator instance. The Regulator +then sends the buffer via a message queue which delivers them to the +Delivery thread. The Delivery thread executes periodically at a rate +specified by the ``delivery_thread_period`` field in the +:ref:`InterfaceRtemsRegulatorAttributes` structure passed as an argument +to :ref:`InterfaceRtemsRegulatorCreate`. + +During each period, the Delivery thread attempts to receive +up to ``maximum_to_dequeue_per_period`` number of buffers and +invoke the Delivery function to deliver each of them to the +Destination. The ``maximum_to_dequeue_per_period`` field in the +:ref:`InterfaceRtemsRegulatorAttributes` structure passed as an argument +to :ref:`InterfaceRtemsRegulatorCreate`. + +For example, consider a Source that may produce a burst of up to seven +messages every five seconds. But the Destination cannot handle a burst +of seven and either drops messages or gives an error. This can be +accommodated by a Regulator instance configured as follows: + +* ``maximum_messages`` - 7 +* ``delivery_thread_period`` - one second +* ``maximum_to_dequeue_per_period`` - 3 + +In this scenario, the application will use the Delivery thread +:ref:`InterfaceRtemsRegulatorSend` to enqueue the seven messages when they +arrive. The Delivery thread will deliver three messages per second. The +following illustrates this sequence: + +* Time 0: Source sends seven messages +* Time 1: Delivery of messages 1 to 3 +* Time 3: Delivery of messages 4 to 6 +* Time 3: Delivery of message 7 +* Time 4: No messages to deliver + +This configuration of the regulator ensures that the Destination does +not overflow. diff --git a/c-user/regulator/directives.rst b/c-user/regulator/directives.rst new file mode 100644 index 0000000..eea3fff --- /dev/null +++ b/c-user/regulator/directives.rst @@ -0,0 +1,549 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2023 On-Line Applications Research Corporation (OAR) + +.. _RegulatorManagerDirectives: + +Directives +========== + +This section details the directives of the Regulator Manager. A subsection is +dedicated to each of this manager's directives and lists the calling sequence, +parameters, description, return values, and notes of the directive. + +.. *** START of rtems_regulator_create() + +.. raw:: latex + + \clearpage + +.. index:: rtems_regulator_create() +.. index:: create a regulator + +.. _InterfaceRtemsRegulatorCreate: + +rtems_regulator_create() +------------------------ + +Creates a regulator. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_regulator_create( + rtems_regulator_attributes *attributes, + rtems_regulator_instance **regulator + ); + +.. rubric:: PARAMETERS: + +``attributes`` + This parameter is the attributes associated with the regulator + being created. + +``regulator`` + This parameter is the pointer to a regulator instance. When the + directive call is successful, a pointer to the created regulator + will be stored in this object. + +.. rubric:: DESCRIPTION: + +This function creates an instance of a regulator. It uses the provided +``attributes`` to create the instance return in ``regulator``. This instance +will allocate the buffers associated with the regulator instance as well +as the Delivery Thread. + +The ``attributes`` parameter points to an instance of +:ref:`InterfaceRtemsRegulatorAttributes` which is filled in to reflect +the desired configuration of the regulator instance. It defines multiple +characteristics of the the Delivery thread dedicated to this regulator +instance including the priority and stack size. It also defines the +period of the Delivery thread and the maximum number of messages that may +be delivered per period via invocation of the delivery function. + +For each regulator instance, the following resources are allocated: + +* A memory area for the regulator control block using ``malloc()``. + +* A RTEMS Classic API Message Queue is constructed with message + buffer memory allocated using ``malloc()``. Each message consists + of a pointer to the contents and a length field. + +* A RTEMS Classic API Partition. + +* A RTEMS Classic API Rate Monotonic Period. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``attributes`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``regulator`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``deliverer`` field in the structure pointed to by the + ``attributes`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_SIZE` + The ``maximum_messages`` field in the structure pointed to by the + ``attributes`` parameter was 0. + +:c:macro:`RTEMS_INVALID_NUMBER` + The ``maximum_to_dequeue_per_period`` field in the structure pointed + to by the ``attributes`` parameter was 0. + +:c:macro:`RTEMS_NO_MEMORY` + The allocation of memory for the regulator instance failed. + +:c:macro:`RTEMS_NO_MEMORY` + The allocation of memory for the buffers failed. + +:c:macro:`RTEMS_NO_MEMORY` + The allocation of memory for the internal message queue failed. + +.. rubric:: NOTES: + +:ref:`InterfaceRtemsRegulatorCreate` uses +:ref:`InterfaceRtemsPartitionCreate`, +:ref:`InterfaceRtemsMessageQueueConstruct`, +:ref:`InterfaceRtemsTaskCreate`, and :ref:`InterfaceRtemsTaskStart`. If +any of those directives return a status indicating failure, it will be +returned to the caller. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. + +* The number of tasks available to the application is configured through the + :ref:`CONFIGURE_MAXIMUM_TASKS` application configuration option. + +* Where the object class corresponding to the directive is configured to use + unlimited objects, the directive may allocate memory from the RTEMS + Workspace. + +.. *** START of rtems_regulator_delete() + +.. raw:: latex + + \clearpage + +.. index:: rtems_regulator_delete() +.. index:: delete a regulator + +.. _InterfaceRtemsRegulatorDelete: + +rtems_regulator_delete() +------------------------ + +Deletes the regulator. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_regulator_delete( + rtems_regulator_instance *regulator, + rtems_interval ticks + ); + +.. rubric:: PARAMETERS: + +``regulator`` + This parameter points to the regulator instance. + +``ticks`` + This parameter specifies the maximum length of time to wait. + +.. rubric:: DESCRIPTION: + +This directive is used to delete the specified ``regulator`` +instance. It will deallocate the resources that were allocated by the +:ref:`InterfaceRtemsRegulatorCreate` directive. + + +This directive ensures that no buffers are outstanding either because the +Source is holding one of more buffers or because they are being held by +the regulator instance pending delivery. + +If the Delivery Thread has been created and is running, this directive will +request the thread to voluntarily exit. This call will wait up to ``ticks`` for the thread to exit. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``regulator`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INCORRECT_STATE` + The ``regulator`` instance was not initialized. + +:c:macro:`RTEMS_RESOURCE_IN_USE` + The ``regulator`` instance has buffers outstanding. + +:c:macro:`RTEMS_TIMEOUT` + The ``regulator`` instance was not able to be deleted within the + specific number of ``ticks``. + +.. rubric:: NOTES: + +It is the responsibility of the user to ensure that any resources +such as sockets or open file descriptors used by the Source or delivery +function are also deleted if necessary. It is likely safer to delete those +delivery resources after deleting the regulator instance rather than before. + + +It is the responsibility of the user to ensure that all buffers associated +with this regulator instance have been released and that none are in +the process of being delivered. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within task context. + +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. + +* The calling task does not have to be the task that created the object. Any + local task that knows the object identifier can delete the object. + +* Where the object class corresponding to the directive is configured to use + unlimited objects, the directive may free memory to the RTEMS Workspace. + +.. *** START of rtems_regulator_obtain_buffer() + +.. raw:: latex + + \clearpage + +.. index:: rtems_regulator_obtain_buffer() +.. index:: obtain buffer from regulator + +.. _InterfaceRtemsRegulatorObtainBuffer: + +rtems_regulator_obtain_buffer() +------------------------------- + +Obtain buffer from regulator. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_regulator_obtain_buffer( + rtems_regulator_instance *regulator, + void **buffer + ); + +.. rubric:: PARAMETERS: + +``regulator`` + This parameter is the regulator instance to operate upon. + +``buffer`` + This parameter will point to the buffer allocated. + +.. rubric:: DESCRIPTION: + +This function is used to obtain a buffer from the regulator's pool. The +``buffer`` returned is assumed to be filled in with contents and used +in a subsequent call to :ref:`InterfaceRtemsRegulatorSend`. + +When the ``buffer`` is delivered, it is expected to be released. If the +``buffer`` is not successfully accepted by this method, then it should +be returned using :ref:`InterfaceRtemsRegulatorReleaseBuffer` or used +to send another message. + +The ``buffer`` returned is of the maximum_message_size specified in the +attributes passed in to :ref:`InterfaceRtemsRegulatorCreate`. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``regulator`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INCORRECT_STATE` + The ``regulator`` instance was not initialized. + +.. rubric:: NOTES: + +:ref:`InterfaceRtemsRegulatorObtainBuffer` uses +:ref:`InterfaceRtemsPartitionGetBuffer` and if it returns a status +indicating failure, it will be returned to the caller. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +.. *** START of rtems_regulator_release_buffer() + +.. raw:: latex + + \clearpage + +.. index:: rtems_regulator_release_buffer() +.. index:: release buffer back to regulator + +.. _InterfaceRtemsRegulatorReleaseBuffer: + +rtems_regulator_release_buffer() +-------------------------------- + +Release buffer to regulator. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_regulator_release_buffer( + rtems_regulator_instance *regulator, + void *buffer + ); + +.. rubric:: PARAMETERS: + +``regulator`` + This parameter is the regulator instance to operate upon. + +``buffer`` + This parameter will point to the buffer to be released. + +.. rubric:: DESCRIPTION: + +This function is used to release a buffer to the regulator's pool. It is +assumed that the ``buffer`` returned will not be used by the application +anymore. + +The ``buffer`` must have previously been allocated by +:ref:`InterfaceRtemsRegulatorObtainBuffer` and NOT yet passed to +:ref:`InterfaceRtemsRegulatorSend`, or it has been sent and delivery +has been completed by the delivery function. + +If a subsequent :ref:`InterfaceRtemsRegulatorSend` using this ``buffer`` +is successful, the ``buffer`` will eventually be processed by the delivery +thread and released. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``regulator`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INCORRECT_STATE` + The ``regulator`` instance was not initialized. + +.. rubric:: NOTES: + +:ref:`InterfaceRtemsRegulatorReleaseBuffer` uses +:ref:`InterfaceRtemsPartitionReturnBuffer` and if it returns a status +indicating failure, it will be returned to the caller. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +.. *** START of rtems_regulator_send() + +.. raw:: latex + + \clearpage + +.. index:: rtems_regulator_send() +.. index:: send buffer to regulator for delivery + +.. _InterfaceRtemsRegulatorSend: + +rtems_regulator_send() +---------------------- + +Send buffer to regulator. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_regulator_send( + rtems_regulator_instance *regulator, + void *message, + size_t length + ); + +.. rubric:: PARAMETERS: + +``regulator`` + This parameter is the regulator instance to operate upon. + +``message`` + This parameter points to the buffer to send. + +``length`` + This parameter specifies the number of bytes in the ``message``. + +.. rubric:: DESCRIPTION: + +This method is used by the producer to send a ``message`` to the +``regulator`` for later delivery by the delivery thread. The message is +contained in the memory pointed to by ``message`` and is ``length`` +bytes in length. + +It is required that the message buffer was obtained via +:ref:`InterfaceRtemsRegulatorObtainBuffer`. + +It is assumed that the ``message`` buffer has been filled in with +application content to deliver. + +If the :ref:`InterfaceRtemsRegulatorSend` is successful, the ``message`` +buffer is enqueued inside the regulator instance for subsequent delivery. +After the ``message`` is delivered, it may be released by either delivery +function or other application code depending on the implementation. + +The status ``RTEMS_TOO_MANY`` is returned if the regulator's +internal queue is full. This indicates that the configured +maximum number of messages was insufficient. It is the +responsibility of the caller to decide whether to hold messages, +drop them, or print a message that the maximum number of messages +should be increased + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``regulator`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INCORRECT_STATE` + The ``regulator`` instance was not initialized. + +.. rubric:: NOTES: + +:ref:`InterfaceRtemsRegulatorSend` uses +:ref:`InterfaceRtemsMessageQueueSend` and if it returns a status +indicating failure, it will be returned to the caller. + + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +.. *** START of rtems_regulator_get_statistics() + +.. raw:: latex + + \clearpage + +.. index:: rtems_regulator_get_statistics() +.. index:: obtain statistics from regulator + +.. _InterfaceRtemsRegulatorGetStatistics: + +rtems_regulator_get_statistics() +-------------------------------- + +Obtain statistics from regulator. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_regulator_get_statistics( + rtems_regulator_instance *regulator, + rtems_regulator_statistics *statistics + ); + +.. rubric:: PARAMETERS: + +``regulator`` + This parameter is the regulator instance to operate upon. + +``statistics`` + This parameter points to the statistics structure to be filled in. + +.. rubric:: DESCRIPTION: + +This method is used by the application to obtain the current +``statistics`` for this ``regulator``. The statistics information +provided includes: + +* the number of buffers obtained via + :ref:`InterfaceRtemsRegulatorObtainBuffer` +* the number of buffers released via + :ref:`InterfaceRtemsRegulatorReleaseBuffer` +* the number of buffers delivered by the Delivery + Thread via the ``deliverer`` function specified in the + :ref:`InterfaceRtemsRegulatorAttributes` structure provided to + :ref:`InterfaceRtemsRegulatorCreate`` via the ``attibutes`` parameter. +* the ``period_statistics`` for the Delivery Thread. For more details on + period statistics, see :ref:`InterfaceRtemsRateMonotonicPeriodStatistics`. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``regulator`` or ``statistics`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INCORRECT_STATE` + The ``regulator`` instance was not initialized. + +.. rubric:: NOTES: + +The number of buffers outstanding is ``released`` minus +``obtained``. The regulator instance cannot be deleted using +:ref:`InterfaceRtemsRegulatorDelete` until all buffers are released. + +The ``obtained`` and ``released`` values are cumulative over +the life of the Regulator instance and are likely to larger than the +``maximum_messages`` value in the ``attributes`` structure +(:ref:`InterfaceRtemsRegulatorAttributes` +provided to :ref:`InterfaceRtemsRegulatorCreate`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + diff --git a/c-user/regulator/index.rst b/c-user/regulator/index.rst new file mode 100644 index 0000000..4731b7b --- /dev/null +++ b/c-user/regulator/index.rst @@ -0,0 +1,19 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2023 OAR Corporation + +.. index:: regulator + +.. _RTEMSAPIRegulator + +Regulator Manager +***************** + +.. toctree:: + + introduction + background + operations + directives +.. deprecated-directives +.. removed-directives diff --git a/c-user/regulator/introduction.rst b/c-user/regulator/introduction.rst new file mode 100644 index 0000000..3ad90d3 --- /dev/null +++ b/c-user/regulator/introduction.rst @@ -0,0 +1,25 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2023 On-Line Applications Research Corporation (OAR) + +.. _RegulatorManagerIntroduction: + +Introduction +============ + +The Regulator Manager provides a set of directives to manage a data flow +from a source to a destination. The focus is on regulating the bursty +input so that it is delivered to the destination at a regular rate. +The directives provided by the Regulator Manager are: + +* :ref:`InterfaceRtemsRegulatorCreate` - Creates a regulator. + +* :ref:`InterfaceRtemsRegulatorDelete` - Deletes the regulator. + +* :ref:`InterfaceRtemsRegulatorObtainBuffer` - Obtain buffer from a regulator. + +* :ref:`InterfaceRtemsRegulatorReleaseBuffer` - Release buffer to a regulator. + +* :ref:`InterfaceRtemsRegulatorSend` - Send buffer to a regulator. + +* :ref:`InterfaceRtemsRegulatorGetStatistics` - Obtain statistics for a regulator. diff --git a/c-user/regulator/operations.rst b/c-user/regulator/operations.rst new file mode 100644 index 0000000..a9e5a44 --- /dev/null +++ b/c-user/regulator/operations.rst @@ -0,0 +1,67 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2023 On-Line Applications Research Corporation (OAR) + +.. _RegulatorManagerOperations: + +Operations +========== + +Application Sourcing Data +------------------------- + +The application interacting with the Source will obtain buffers from +the regulator instance, fill them with information, and send them to +the regulator instance. This allows the regulator to buffer bursty input. + +A regulator instance is used as follows from the Source side: + +.. code-block:: c + + while (1) { + use rtems_regulator_obtain_buffer to obtain a buffer + // Perform some input operation to fetch data into the buffer + rtems_regulator_send(buffer, size of message) + } + +The delivery of message buffers to the Destination and subsequent release is +performed in the context of the delivery thread by either the delivery +function or delivery thread. Details are below. + +The sequence diagram below shows the interaction between a message Source, +a Regulator instance, and RTEMS, given the usage described in the above +paragraphs. + +.. _fig-regulator_input_sequence: + +.. figure:: ../../images/c_user/regulator_input_sequence.png + :width: 90% + :alt: Regulator Application Input Source Usage + :figclass: align-center + +As illustrated in the preceding sequence diagram, the Source usually +corresponds to application software reading a system input. The Source +obtains a buffer from the Regulator instance and fills it with incoming +data. The application explicitly obtaining a buffer and filling it in +allows for zero copy operations on the Source side. + +After the Source has sent the message to the Regulator instance, +the Source is free to process another input and the Regulator +instance will ensure that the buffer is delivered to the Delivery +function and Destination. + +Delivery Function +----------------- +The Delivery function is provided by the application for a specific +Regulator instance. Depending on the Destination, it may use a function which +copies the buffer contents (e.g., write()) or which operates directly +on the buffer contents (e.g. DMA from buffer). In the case of a +Destination which copies the buffer contents, the buffer can be released +via :ref:`InterfaceRtemsRegulatorReleaseBuffer` as soon as the function +or copying completes. In the case where the delivery uses the buffer +and returns, the call to :ref:`InterfaceRtemsRegulatorReleaseBuffer` +will occur when the use of the buffer is complete (e.g. completion +of DMA transfer). This explicit and deliberate exposure of buffering +provides the application with the ability to avoid copying the contents. + + diff --git a/c-user/rtems_data_types.rst b/c-user/rtems_data_types.rst index 121d37e..0a5461c 100644 --- a/c-user/rtems_data_types.rst +++ b/c-user/rtems_data_types.rst @@ -1,6 +1,22 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +.. Copyright (C) 2008, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org .. index:: RTEMS Data Types .. index:: data types @@ -8,6 +24,8 @@ RTEMS Data Types **************** +.. _Introduction: + Introduction ============ @@ -16,368 +34,1849 @@ alphabetical order. This is intended to be an overview and the user is encouraged to look at the appropriate chapters in the manual for more information about the usage of the various data types. +.. _ListOfDataTypes: + List of Data Types ================== The following is a complete list of the RTEMS primitive data types in alphabetical order: -.. index:: rtems_address +.. Generated from spec:/rtems/io/if/bsp-output-char-function-type + +.. index:: BSP_output_char_function_type + +.. _InterfaceBSPOutputCharFunctionType: + +BSP_output_char_function_type +----------------------------- + +Polled character output functions shall have this type. + +.. Generated from spec:/rtems/io/if/bsp-polling-getchar-function-type + +.. index:: BSP_polling_getchar_function_type + +.. _InterfaceBSPPollingGetcharFunctionType: + +BSP_polling_getchar_function_type +--------------------------------- + +Polled character input functions shall have this type. + +.. Generated from spec:/rtems/timer/if/classes + +.. index:: Timer_Classes + +.. _InterfaceTimerClasses: + +Timer_Classes +------------- + +The timer class indicates how the timer was most recently fired. + +.. rubric:: ENUMERATORS: + +TIMER_DORMANT + This timer class indicates that the timer was never in use. + +TIMER_INTERVAL + This timer class indicates that the timer is currently in use as an + interval timer which will fire in the context of the clock tick + :term:`ISR`. + +TIMER_INTERVAL_ON_TASK + This timer class indicates that the timer is currently in use as an + interval timer which will fire in the context of the Timer Server task. + +TIMER_TIME_OF_DAY + This timer class indicates that the timer is currently in use as an time of + day timer which will fire in the context of the clock tick :term:`ISR`. + +TIMER_TIME_OF_DAY_ON_TASK + This timer class indicates that the timer is currently in use as an time of + day timer which will fire in the context of the Timer Server task. + +.. Generated from spec:/rtems/config/if/api-table + +.. index:: rtems_api_configuration_table + +.. _InterfaceRtemsApiConfigurationTable: + +rtems_api_configuration_table +----------------------------- + +This structure contains a summary of the Classic API configuration. + +.. rubric:: MEMBERS: + +maximum_tasks + This member contains the maximum number of Classic API Tasks configured for + this application. See :ref:`CONFIGURE_MAXIMUM_TASKS`. + +notepads_enabled + This member is true, if the Classic API Notepads are enabled, otherwise it + is false. + +maximum_timers + This member contains the maximum number of Classic API Timers configured + for this application. See :ref:`CONFIGURE_MAXIMUM_TIMERS`. + +maximum_semaphores + This member contains the maximum number of Classic API Semaphores + configured for this application. See :ref:`CONFIGURE_MAXIMUM_SEMAPHORES`. + +maximum_message_queues + This member contains the maximum number of Classic API Message Queues + configured for this application. See + :ref:`CONFIGURE_MAXIMUM_MESSAGE_QUEUES`. + +maximum_partitions + This member contains the maximum number of Classic API Partitions + configured for this application. See :ref:`CONFIGURE_MAXIMUM_PARTITIONS`. + +maximum_regions + This member contains the maximum number of Classic API Regions configured + for this application. See :ref:`CONFIGURE_MAXIMUM_REGIONS`. + +maximum_ports + This member contains the maximum number of Classic API Dual-Ported Memories + configured for this application. See :ref:`CONFIGURE_MAXIMUM_PORTS`. -``rtems_address`` - The data type used to manage addresses. It is equivalent to a ``void *`` - pointer. +maximum_periods + This member contains the maximum number of Classic API Rate Monotonic + Periods configured for this application. See + :ref:`CONFIGURE_MAXIMUM_PERIODS`. + +maximum_barriers + This member contains the maximum number of Classic API Barriers configured + for this application. See :ref:`CONFIGURE_MAXIMUM_BARRIERS`. + +number_of_initialization_tasks + This member contains the number of Classic API Initialization Tasks + configured for this application. See + :ref:`CONFIGURE_RTEMS_INIT_TASKS_TABLE`. + +User_initialization_tasks_table + This member contains the pointer to Classic API Initialization Tasks Table + of this application. See :ref:`CONFIGURE_RTEMS_INIT_TASKS_TABLE`. + +.. rubric:: DESCRIPTION: + +Use :ref:`InterfaceRtemsConfigurationGetRtemsApiConfiguration` to get the +configuration table. + +.. Generated from spec:/rtems/signal/if/asr .. index:: rtems_asr -``rtems_asr`` - The return type for an RTEMS ASR. +.. _InterfaceRtemsAsr: + +rtems_asr +--------- + +This type defines the return type of routines which are used to process +asynchronous signals. + +.. rubric:: NOTES: + +This type can be used to document asynchronous signal routines in the source +code. + +.. Generated from spec:/rtems/signal/if/asr-entry .. index:: rtems_asr_entry -``rtems_asr_entry`` - The address of the entry point to an RTEMS ASR. +.. _InterfaceRtemsAsrEntry: -.. index:: rtems_attribute +rtems_asr_entry +--------------- + +This type defines the prototype of routines which are used to process +asynchronous signals. + +.. Generated from spec:/rtems/fatal/if/assert-context -``rtems_attribute`` - The data type used to manage the attributes for RTEMS objects. It is - primarily used as an argument to object create routines to specify - characteristics of the new object. +.. index:: rtems_assert_context -.. index:: rtems_boolean +.. _InterfaceRtemsAssertContext: -``rtems_boolean`` - This type is deprecated will be removed in RTEMS 6.1. Use ``bool`` instead. +rtems_assert_context +-------------------- -.. index:: rtems_context +This structure provides the context in which an assertion failed. -``rtems_context`` - This type is deprecated will be removed in RTEMS 6.1. +.. rubric:: MEMBERS: -.. index:: rtems_context_fp +file + This member provides the file name of the source code file containing the + failed assertion statement. -``rtems_context_fp`` - This type is deprecated will be removed in RTEMS 6.1. +line + This member provides the line number in the source code file containing the + failed assertion statement. + +function + This member provides the function name containing the failed assertion + statement. + +failed_expression + This member provides the expression of the failed assertion statement. + +.. Generated from spec:/rtems/attr/if/attribute + +.. index:: rtems_attribute + +.. _InterfaceRtemsAttribute: + +rtems_attribute +--------------- + +This type represents Classic API attributes. + +.. rubric:: NOTES: + +Attributes are primarily used when creating objects. + +.. Generated from spec:/rtems/io/if/device-driver .. index:: rtems_device_driver -``rtems_device_driver`` - The return type for a RTEMS device driver routine. +.. _InterfaceRtemsDeviceDriver: + +rtems_device_driver +------------------- + +This type shall be used in device driver entry declarations and definitions. + +.. rubric:: NOTES: + +Device driver entries return an :c:type:`rtems_status_code` status code. This +type definition helps to document device driver entries in the source code. + +.. Generated from spec:/rtems/io/if/device-driver-entry .. index:: rtems_device_driver_entry -``rtems_device_driver_entry`` - The entry point to a RTEMS device driver routine. +.. _InterfaceRtemsDeviceDriverEntry: + +rtems_device_driver_entry +------------------------- + +Device driver entries shall have this type. + +.. Generated from spec:/rtems/io/if/device-major-number .. index:: rtems_device_major_number -``rtems_device_major_number`` - The data type used to manage device major numbers. +.. _InterfaceRtemsDeviceMajorNumber: + +rtems_device_major_number +------------------------- + +This integer type represents the major number of devices. + +.. rubric:: NOTES: + +The major number of a device is determined by +:ref:`InterfaceRtemsIoRegisterDriver` and the application configuration (see +:ref:`CONFIGURE_MAXIMUM_DRIVERS`) . + +.. Generated from spec:/rtems/io/if/device-minor-number .. index:: rtems_device_minor_number -``rtems_device_minor_number`` - The data type used to manage device minor numbers. +.. _InterfaceRtemsDeviceMinorNumber: + +rtems_device_minor_number +------------------------- + +This integer type represents the minor number of devices. + +.. rubric:: NOTES: + +The minor number of devices is managed by the device driver. + +.. Generated from spec:/rtems/io/if/driver-address-table + +.. index:: rtems_driver_address_table + +.. _InterfaceRtemsDriverAddressTable: + +rtems_driver_address_table +-------------------------- + +This structure contains the device driver entries. + +.. rubric:: MEMBERS: + +initialization_entry + This member is the device driver initialization entry. This entry is called + by :ref:`InterfaceRtemsIoInitialize`. + +open_entry + This member is the device driver open entry. This entry is called by + :ref:`InterfaceRtemsIoOpen`. + +close_entry + This member is the device driver close entry. This entry is called by + :ref:`InterfaceRtemsIoClose`. + +read_entry + This member is the device driver read entry. This entry is called by + :ref:`InterfaceRtemsIoRead`. + +write_entry + This member is the device driver write entry. This entry is called by + :ref:`InterfaceRtemsIoWrite`. -.. index:: rtems_double +control_entry + This member is the device driver control entry. This entry is called by + :ref:`InterfaceRtemsIoControl`. -``rtems_double`` - This type is deprecated will be removed in RTEMS 6.1. Use ``double`` instead. +.. rubric:: DESCRIPTION: + +This structure is used to register a device driver via +:ref:`InterfaceRtemsIoRegisterDriver`. + +.. Generated from spec:/rtems/event/if/set .. index:: rtems_event_set -``rtems_event_set`` - The data type used to manage and manipulate RTEMS event sets with the Event - Manager. +.. _InterfaceRtemsEventSet: + +rtems_event_set +--------------- + +This integer type represents a bit field which can hold exactly 32 individual +events. + +.. Generated from spec:/rtems/fatal/if/exception-frame + +.. index:: rtems_exception_frame + +.. _InterfaceRtemsExceptionFrame: + +rtems_exception_frame +--------------------- + +This structure represents an architecture-dependent exception frame. + +.. Generated from spec:/rtems/userext/if/table + +.. index:: rtems_extensions_table + +.. _InterfaceRtemsExtensionsTable: + +rtems_extensions_table +---------------------- + +The extensions table contains a set of extensions which may be registered in +the system through the :ref:`CONFIGURE_INITIAL_EXTENSIONS` application +configuration option or the :ref:`InterfaceRtemsExtensionCreate` directive. + +.. Generated from spec:/rtems/userext/if/fatal-code + +.. index:: rtems_fatal_code + +.. _InterfaceRtemsFatalCode: + +rtems_fatal_code +---------------- -.. index:: rtems_extension +This integer type represents system termination codes. -``rtems_extension`` - The return type for RTEMS user extension routines. +.. rubric:: DESCRIPTION: + +This integer type is large enough to store a 32-bit integer or a pointer. + +.. rubric:: NOTES: + +The interpretation of a system termination code depends on the system +termination source, see :ref:`InterfaceRtemsFatalSource`. + +.. Generated from spec:/rtems/userext/if/fatal .. index:: rtems_fatal_extension -``rtems_fatal_extension`` - The entry point for a fatal error user extension handler routine. +.. _InterfaceRtemsFatalExtension: + +rtems_fatal_extension +--------------------- + +Fatal extensions are invoked when the system should terminate. + +.. rubric:: NOTES: + +The fatal extensions are invoked in :term:`extension forward order`. + +The fatal extension should be extremely careful with respect to the RTEMS +directives it calls. Depending on the system termination source, the system +may be in an undefined and corrupt state. + +It is recommended to register fatal extensions through :term:`initial extension +sets`, see :ref:`CONFIGURE_INITIAL_EXTENSIONS`. + +.. Generated from spec:/rtems/userext/if/fatal-source + +.. index:: rtems_fatal_source + +.. _InterfaceRtemsFatalSource: + +rtems_fatal_source +------------------ + +This enumeration represents system termination sources. + +.. rubric:: NOTES: + +The system termination code may provide additional information depending on the +system termination source, see :ref:`InterfaceRtemsFatalCode`. + +.. Generated from spec:/rtems/type/if/id .. index:: rtems_id -``rtems_id`` - The data type used to manage and manipulate RTEMS object IDs. +.. _InterfaceRtemsId: + +rtems_id +-------- + +This type represents RTEMS object identifiers. + +.. Generated from spec:/rtems/task/if/initialization-table + +.. index:: rtems_initialization_tasks_table + +.. _InterfaceRtemsInitializationTasksTable: + +rtems_initialization_tasks_table +-------------------------------- + +This structure defines the properties of the Classic API user initialization +task. + +.. rubric:: MEMBERS: + +name + This member defines the task name. + +stack_size + This member defines the task stack size in bytes. + +initial_priority + This member defines the initial task priority. + +attribute_set + This member defines the attribute set of the task. + +entry_point + This member defines the entry point of the task. + +mode_set + This member defines the initial modes of the task. + +argument + This member defines the entry point argument of the task. + +.. Generated from spec:/rtems/intr/if/attributes + +.. index:: rtems_interrupt_attributes -.. index:: rtems_interrupt_frame +.. _InterfaceRtemsInterruptAttributes: -``rtems_interrupt_frame`` - The data structure that defines the format of the interrupt stack frame as it - appears to a user ISR. This data structure is only defined on architectures - that pass the frame pointer to the ISR handler. +rtems_interrupt_attributes +-------------------------- + +This structure provides the attributes of an interrupt vector. + +.. rubric:: MEMBERS: + +is_maskable + This member is true, if the interrupt vector is maskable by + :ref:`InterfaceRtemsInterruptLocalDisable`, otherwise it is false. + Interrupt vectors which are not maskable by + :ref:`InterfaceRtemsInterruptLocalDisable` should be used with care since + they cannot use most operating system services. + +can_enable + This member is true, if the interrupt vector can be enabled by + :ref:`InterfaceRtemsInterruptVectorEnable`, otherwise it is false. When an + interrupt vector can be enabled, this means that the enabled state can + always be changed from disabled to enabled. For an interrupt vector which + can be enabled it follows that it may be enabled. + +maybe_enable + This member is true, if the interrupt vector may be enabled by + :ref:`InterfaceRtemsInterruptVectorEnable`, otherwise it is false. When an + interrupt vector may be enabled, this means that the enabled state may be + changed from disabled to enabled. The requested enabled state change + should be checked by :ref:`InterfaceRtemsInterruptVectorIsEnabled`. Some + interrupt vectors may be optionally available and cannot be enabled on a + particular :term:`target`. + +can_disable + This member is true, if the interrupt vector can be disabled by + :ref:`InterfaceRtemsInterruptVectorDisable`, otherwise it is false. When an + interrupt vector can be disabled, this means that the enabled state can be + changed from enabled to disabled. For an interrupt vector which can be + disabled it follows that it may be disabled. + +maybe_disable + This member is true, if the interrupt vector may be disabled by + :ref:`InterfaceRtemsInterruptVectorDisable`, otherwise it is false. When an + interrupt vector may be disabled, this means that the enabled state may be + changed from enabled to disabled. The requested enabled state change + should be checked by :ref:`InterfaceRtemsInterruptVectorIsEnabled`. Some + interrupt vectors may be always enabled and cannot be disabled on a + particular :term:`target`. + +can_raise + This member is true, if the interrupt vector can be raised by + :ref:`InterfaceRtemsInterruptRaise`, otherwise it is false. + +can_raise_on + This member is true, if the interrupt vector can be raised on a processor + by :ref:`InterfaceRtemsInterruptRaiseOn`, otherwise it is false. + +can_clear + This member is true, if the interrupt vector can be cleared by + :ref:`InterfaceRtemsInterruptClear`, otherwise it is false. + +cleared_by_acknowledge + This member is true, if the pending status of the interrupt associated with + the interrupt vector is cleared by an interrupt acknowledge from the + processor, otherwise it is false. + +can_get_affinity + This member is true, if the affinity set of the interrupt vector can be + obtained by :ref:`InterfaceRtemsInterruptGetAffinity`, otherwise it is + false. + +can_set_affinity + This member is true, if the affinity set of the interrupt vector can be set + by :ref:`InterfaceRtemsInterruptSetAffinity`, otherwise it is false. + +can_be_triggered_by_message + This member is true, if the interrupt associated with the interrupt vector + can be triggered by a message. Interrupts may be also triggered by signals, + :ref:`InterfaceRtemsInterruptRaise`, or + :ref:`InterfaceRtemsInterruptRaiseOn`. Examples for message triggered + interrupts are the PCIe MSI/MSI-X and the ARM GICv3 Locality-specific + Peripheral Interrupts (LPI). + +trigger_signal + This member describes the trigger signal of the interrupt associated with + the interrupt vector. Interrupts are normally triggered by signals which + indicate an interrupt request from a peripheral. Interrupts may be also + triggered by messages, :ref:`InterfaceRtemsInterruptRaise`, or + :ref:`InterfaceRtemsInterruptRaiseOn`. + +.. rubric:: DESCRIPTION: + +The :ref:`InterfaceRtemsInterruptGetAttributes` directive may be used to obtain +the attributes of an interrupt vector. + +.. Generated from spec:/rtems/intr/if/entry + +.. index:: rtems_interrupt_entry + +.. _InterfaceRtemsInterruptEntry: + +rtems_interrupt_entry +--------------------- + +This structure represents an interrupt entry. + +.. rubric:: MEMBERS: + +Members of the type shall not be accessed directly by the application. + +.. rubric:: NOTES: + +This structure shall be treated as an opaque data type from the :term:`API` +point of view. Members shall not be accessed directly. An entry may be +initialized by :ref:`InterfaceRTEMSINTERRUPTENTRYINITIALIZER` or +:ref:`InterfaceRtemsInterruptEntryInitialize`. It may be installed for an +interrupt vector with :ref:`InterfaceRtemsInterruptEntryInstall` and removed +from an interrupt vector by :ref:`InterfaceRtemsInterruptEntryRemove`. + +.. Generated from spec:/rtems/intr/if/handler + +.. index:: rtems_interrupt_handler + +.. _InterfaceRtemsInterruptHandler: + +rtems_interrupt_handler +----------------------- + +Interrupt handler routines shall have this type. + +.. Generated from spec:/rtems/intr/if/level .. index:: rtems_interrupt_level -``rtems_interrupt_level`` - The data structure used with the ``rtems_interrupt_disable``, - ``rtems_interrupt_enable``, and ``rtems_interrupt_flash`` routines. This - data type is CPU dependent and usually corresponds to the contents of the - processor register containing the interrupt mask level. +.. _InterfaceRtemsInterruptLevel: + +rtems_interrupt_level +--------------------- + +This integer type represents interrupt levels. + +.. Generated from spec:/rtems/intr/if/lock + +.. index:: rtems_interrupt_lock + +.. _InterfaceRtemsInterruptLock: + +rtems_interrupt_lock +-------------------- + +This structure represents an ISR lock. + +.. Generated from spec:/rtems/intr/if/lock-context + +.. index:: rtems_interrupt_lock_context + +.. _InterfaceRtemsInterruptLockContext: + +rtems_interrupt_lock_context +---------------------------- + +This structure provides an ISR lock context for acquire and release pairs. + +.. Generated from spec:/rtems/intr/if/per-handler-routine + +.. index:: rtems_interrupt_per_handler_routine + +.. _InterfaceRtemsInterruptPerHandlerRoutine: + +rtems_interrupt_per_handler_routine +----------------------------------- + +Visitor routines invoked by :ref:`InterfaceRtemsInterruptHandlerIterate` shall +have this type. + +.. Generated from spec:/rtems/intr/if/server-action + +.. index:: rtems_interrupt_server_action + +.. _InterfaceRtemsInterruptServerAction: + +rtems_interrupt_server_action +----------------------------- + +This structure represents an interrupt server action. + +.. rubric:: MEMBERS: + +Members of the type shall not be accessed directly by the application. + +.. rubric:: NOTES: + +This structure shall be treated as an opaque data type from the :term:`API` +point of view. Members shall not be accessed directly. + +.. Generated from spec:/rtems/intr/if/server-config + +.. index:: rtems_interrupt_server_config + +.. _InterfaceRtemsInterruptServerConfig: + +rtems_interrupt_server_config +----------------------------- + +This structure defines an interrupt server configuration. + +.. rubric:: MEMBERS: + +Members of the type shall not be accessed directly by the application. + +.. rubric:: NOTES: + +See also :ref:`InterfaceRtemsInterruptServerCreate`. + +.. Generated from spec:/rtems/intr/if/server-control + +.. index:: rtems_interrupt_server_control + +.. _InterfaceRtemsInterruptServerControl: + +rtems_interrupt_server_control +------------------------------ + +This structure represents an interrupt server. + +.. rubric:: MEMBERS: + +Members of the type shall not be accessed directly by the application. + +.. rubric:: NOTES: + +This structure shall be treated as an opaque data type from the :term:`API` +point of view. Members shall not be accessed directly. The structure is +initialized by :ref:`InterfaceRtemsInterruptServerCreate` and maintained by the +interrupt server support. + +.. Generated from spec:/rtems/intr/if/server-entry + +.. index:: rtems_interrupt_server_entry + +.. _InterfaceRtemsInterruptServerEntry: + +rtems_interrupt_server_entry +---------------------------- + +This structure represents an interrupt server entry. + +.. rubric:: MEMBERS: + +Members of the type shall not be accessed directly by the application. + +.. rubric:: NOTES: + +This structure shall be treated as an opaque data type from the :term:`API` +point of view. Members shall not be accessed directly. An entry is +initialized by :ref:`InterfaceRtemsInterruptServerEntryInitialize` and +destroyed by :ref:`InterfaceRtemsInterruptServerEntryDestroy`. Interrupt +server actions can be prepended to the entry by +:ref:`InterfaceRtemsInterruptServerActionPrepend`. The entry is submitted to +be serviced by :ref:`InterfaceRtemsInterruptServerEntrySubmit`. + +.. Generated from spec:/rtems/intr/if/server-request + +.. index:: rtems_interrupt_server_request + +.. _InterfaceRtemsInterruptServerRequest: + +rtems_interrupt_server_request +------------------------------ + +This structure represents an interrupt server request. + +.. rubric:: MEMBERS: + +Members of the type shall not be accessed directly by the application. + +.. rubric:: NOTES: + +This structure shall be treated as an opaque data type from the :term:`API` +point of view. Members shall not be accessed directly. A request is +initialized by :ref:`InterfaceRtemsInterruptServerRequestInitialize` and +destroyed by :ref:`InterfaceRtemsInterruptServerRequestDestroy`. The interrupt +vector of the request can be set by +:ref:`InterfaceRtemsInterruptServerRequestSetVector`. The request is submitted +to be serviced by :ref:`InterfaceRtemsInterruptServerRequestSubmit`. + +.. Generated from spec:/rtems/intr/if/signal-variant + +.. index:: rtems_interrupt_signal_variant + +.. _InterfaceRtemsInterruptSignalVariant: + +rtems_interrupt_signal_variant +------------------------------ + +This enumeration provides interrupt trigger signal variants. + +.. rubric:: ENUMERATORS: + +RTEMS_INTERRUPT_UNSPECIFIED_SIGNAL + This interrupt signal variant indicates that the interrupt trigger signal + is unspecified. + +RTEMS_INTERRUPT_NO_SIGNAL + This interrupt signal variant indicates that the interrupt cannot be + triggered by a signal. + +RTEMS_INTERRUPT_SIGNAL_LEVEL_LOW + This interrupt signal variant indicates that the interrupt is triggered by + a low level signal. + +RTEMS_INTERRUPT_SIGNAL_LEVEL_HIGH + This interrupt signal variant indicates that the interrupt is triggered by + a high level signal. + +RTEMS_INTERRUPT_SIGNAL_EDGE_FALLING + This interrupt signal variant indicates that the interrupt is triggered by + a falling edge signal. + +RTEMS_INTERRUPT_SIGNAL_EDGE_RAISING + This interrupt signal variant indicates that the interrupt is triggered by + a raising edge signal. + +.. Generated from spec:/rtems/type/if/interval .. index:: rtems_interval -``rtems_interval`` - The data type used to manage and manipulate time intervals. Intervals are - non-negative integers used to measure the length of time in clock ticks. +.. _InterfaceRtemsInterval: + +rtems_interval +-------------- + +This type represents clock tick intervals. + +.. Generated from spec:/rtems/intr/if/isr .. index:: rtems_isr -``rtems_isr`` - The return type of a function implementing an RTEMS ISR. +.. _InterfaceRtemsIsr: + +rtems_isr +--------- + +This type defines the return type of interrupt service routines. + +.. rubric:: DESCRIPTION: + +This type can be used to document interrupt service routines in the source +code. + +.. Generated from spec:/rtems/intr/if/isr-entry .. index:: rtems_isr_entry -``rtems_isr_entry`` - The address of the entry point to an RTEMS ISR. It is equivalent to the - entry point of the function implementing the ISR. +.. _InterfaceRtemsIsrEntry: -.. index:: rtems_mp_packet_classes +rtems_isr_entry +--------------- + +Interrupt service routines installed by :ref:`InterfaceRtemsInterruptCatch` +shall have this type. + +.. Generated from spec:/rtems/message/if/config + +.. index:: rtems_message_queue_config + +.. _InterfaceRtemsMessageQueueConfig: + +rtems_message_queue_config +-------------------------- + +This structure defines the configuration of a message queue constructed by +:ref:`InterfaceRtemsMessageQueueConstruct`. + +.. rubric:: MEMBERS: + +name + This member defines the name of the message queue. -``rtems_mp_packet_classes`` - The enumerated type which specifies the categories of multiprocessing - messages. For example, one of the classes is for messages that must be - processed by the Task Manager. +maximum_pending_messages + This member defines the maximum number of pending messages supported by the + message queue. + +maximum_message_size + This member defines the maximum message size supported by the message + queue. + +storage_area + This member shall point to the message buffer storage area begin. The + message buffer storage area for the message queue shall be an array of the + type defined by :ref:`InterfaceRTEMSMESSAGEQUEUEBUFFER` with a maximum + message size equal to the maximum message size of this configuration. + +storage_size + This member defines size of the message buffer storage area in bytes. + +storage_free + This member defines the optional handler to free the message buffer storage + area. It is called when the message queue is deleted. It is called from + task context under protection of the object allocator lock. It is allowed + to call :c:func:`free` in this handler. If handler is `NULL + <https://en.cppreference.com/w/c/types/NULL>`_, then no action will be + performed. + +attributes + This member defines the attributes of the message queue. + +.. Generated from spec:/rtems/mode/if/mode .. index:: rtems_mode -``rtems_mode`` - The data type used to manage and dynamically manipulate the execution mode of - an RTEMS task. +.. _InterfaceRtemsMode: + +rtems_mode +---------- + +This type represents a Classic API task mode set. + +.. Generated from spec:/rtems/type/if/mp-packet-classes + +.. index:: rtems_mp_packet_classes + +.. _InterfaceRtemsMpPacketClasses: + +rtems_mp_packet_classes +----------------------- + +This enumeration defines the MPCI packet classes. + +.. Generated from spec:/rtems/type/if/mpci-entry .. index:: rtems_mpci_entry -``rtems_mpci_entry`` - The return type of an RTEMS MPCI routine. +.. _InterfaceRtemsMpciEntry: + +rtems_mpci_entry +---------------- + +MPCI handler routines shall have this return type. + +.. Generated from spec:/rtems/type/if/mpci-get-packet-entry .. index:: rtems_mpci_get_packet_entry -``rtems_mpci_get_packet_entry`` - The address of the entry point to the get packet routine for an MPCI - implementation. +.. _InterfaceRtemsMpciGetPacketEntry: + +rtems_mpci_get_packet_entry +--------------------------- + +MPCI get packet routines shall have this type. + +.. Generated from spec:/rtems/type/if/mpci-initialization-entry .. index:: rtems_mpci_initialization_entry -``rtems_mpci_initialization_entry`` - The address of the entry point to the initialization routine for an MPCI - implementation. +.. _InterfaceRtemsMpciInitializationEntry: + +rtems_mpci_initialization_entry +------------------------------- + +MPCI initialization routines shall have this type. + +.. Generated from spec:/rtems/type/if/mpci-receive-packet-entry .. index:: rtems_mpci_receive_packet_entry -``rtems_mpci_receive_packet_entry`` - The address of the entry point to the receive packet routine for an MPCI - implementation. +.. _InterfaceRtemsMpciReceivePacketEntry: + +rtems_mpci_receive_packet_entry +------------------------------- + +MPCI receive packet routines shall have this type. + +.. Generated from spec:/rtems/type/if/mpci-return-packet-entry .. index:: rtems_mpci_return_packet_entry -``rtems_mpci_return_packet_entry`` - The address of the entry point to the return packet routine for an MPCI - implementation. +.. _InterfaceRtemsMpciReturnPacketEntry: + +rtems_mpci_return_packet_entry +------------------------------ + +MPCI return packet routines shall have this type. + +.. Generated from spec:/rtems/type/if/mpci-send-packet-entry .. index:: rtems_mpci_send_packet_entry -``rtems_mpci_send_packet_entry`` - The address of the entry point to the send packet routine for an MPCI - implementation. +.. _InterfaceRtemsMpciSendPacketEntry: + +rtems_mpci_send_packet_entry +---------------------------- + +MPCI send packet routines shall have this type. + +.. Generated from spec:/rtems/type/if/mpci-table .. index:: rtems_mpci_table -``rtems_mpci_table`` - The data structure containing the configuration information for an MPCI. +.. _InterfaceRtemsMpciTable: + +rtems_mpci_table +---------------- + +This type represents the user-provided MPCI control. + +.. Generated from spec:/rtems/type/if/multiprocessing-table + +.. index:: rtems_multiprocessing_table + +.. _InterfaceRtemsMultiprocessingTable: + +rtems_multiprocessing_table +--------------------------- + +This type represents the user-provided MPCI configuration. + +.. Generated from spec:/rtems/type/if/name .. index:: rtems_name -``rtems_name`` - The data type used to contain the name of a Classic API object. It is an - unsigned thirty-two bit integer which can be treated as a numeric value or - initialized using ``rtems_build_name`` to contain four ASCII characters. +.. _InterfaceRtemsName: + +rtems_name +---------- + +This type represents Classic API object names. + +.. rubric:: DESCRIPTION: + +It is an unsigned 32-bit integer which can be treated as a numeric value or +initialized using :ref:`InterfaceRtemsBuildName` to encode four ASCII +characters. A value of zero may have a special meaning in some directives. + +.. Generated from spec:/rtems/object/if/api-class-information + +.. index:: rtems_object_api_class_information + +.. _InterfaceRtemsObjectApiClassInformation: + +rtems_object_api_class_information +---------------------------------- + +This structure is used to return information to the application about the +objects configured for a specific API/Class combination. + +.. rubric:: MEMBERS: + +minimum_id + This member contains the minimum valid object identifier for this class. + +maximum_id + This member contains the maximum valid object identifier for this class. + +maximum + This member contains the maximum number of active objects configured for + this class. + +auto_extend + This member is true, if this class is configured for automatic object + extension, otherwise it is false. + +unallocated + This member contains the number of currently inactive objects of this + class. + +.. Generated from spec:/rtems/option/if/option .. index:: rtems_option -``rtems_option`` - The data type used to specify which behavioral options the caller desires. - It is commonly used with potentially blocking directives to specify whether - the caller is willing to block or return immediately with an error indicating - that the resource was not available. +.. _InterfaceRtemsOption: + +rtems_option +------------ + +This type represents a Classic API directive option set. + +.. Generated from spec:/rtems/type/if/packet-prefix .. index:: rtems_packet_prefix -``rtems_packet_prefix`` - The data structure that defines the first bytes in every packet sent between - nodes in an RTEMS multiprocessor system. It contains routing information - that is expected to be used by the MPCI layer. +.. _InterfaceRtemsPacketPrefix: + +rtems_packet_prefix +------------------- + +This type represents the prefix found at the beginning of each MPCI packet sent +between nodes. + +.. Generated from spec:/rtems/ratemon/if/period-states + +.. index:: rtems_rate_monotonic_period_states + +.. _InterfaceRtemsRateMonotonicPeriodStates: + +rtems_rate_monotonic_period_states +---------------------------------- + +This enumeration defines the states in which a period may be. + +.. rubric:: ENUMERATORS: + +RATE_MONOTONIC_INACTIVE + This status indicates the period is off the watchdog chain, and has never + been initialized. + +RATE_MONOTONIC_ACTIVE + This status indicates the period is on the watchdog chain, and running. + The owner may be executing or blocked waiting on another object. + +RATE_MONOTONIC_EXPIRED + This status indicates the period is off the watchdog chain, and has + expired. The owner may still execute and has taken too much time to + complete this iteration of the period. + +.. Generated from spec:/rtems/ratemon/if/period-statistics + +.. index:: rtems_rate_monotonic_period_statistics + +.. _InterfaceRtemsRateMonotonicPeriodStatistics: + +rtems_rate_monotonic_period_statistics +-------------------------------------- + +This structure provides the statistics of a period. + +.. rubric:: MEMBERS: + +count + This member contains the number of periods executed. + +missed_count + This member contains the number of periods missed. + +min_cpu_time + This member contains the least amount of processor time used in a period. + +max_cpu_time + This member contains the highest amount of processor time used in a period. + +total_cpu_time + This member contains the total amount of processor time used in a period. + +min_wall_time + This member contains the least amount of :term:`CLOCK_MONOTONIC` time used + in a period. + +max_wall_time + This member contains the highest amount of :term:`CLOCK_MONOTONIC` time + used in a period. + +total_wall_time + This member contains the total amount of :term:`CLOCK_MONOTONIC` time used + in a period. + +.. Generated from spec:/rtems/ratemon/if/period-status + +.. index:: rtems_rate_monotonic_period_status + +.. _InterfaceRtemsRateMonotonicPeriodStatus: + +rtems_rate_monotonic_period_status +---------------------------------- + +This structure provides the detailed status of a period. + +.. rubric:: MEMBERS: + +owner + This member contains the identifier of the owner task of the period. + +state + This member contains the state of the period. + +since_last_period + This member contains the time elapsed since the last successful invocation + :ref:`InterfaceRtemsRateMonotonicPeriod` using :term:`CLOCK_MONOTONIC`. If + the period is expired or has not been initiated, then this value has no + meaning. + +executed_since_last_period + This member contains the processor time consumed by the owner task since + the last successful invocation :ref:`InterfaceRtemsRateMonotonicPeriod`. If + the period is expired or has not been initiated, then this value has no + meaning. + +postponed_jobs_count + This member contains the count of jobs which are not released yet. + +.. Handwritten + +.. index:: rtems_regulator_attributes + +.. _InterfaceRtemsRegulatorAttributes: + +rtems_regulator_attributes +-------------------------- + +This structure defines the configuration of a regulator created by +:ref:`InterfaceRtemsRegulatorCreate`. + +.. rubric:: MEMBERS: + +deliverer + This member contains a pointer to an application function invoked by + the Delivery thread to output a message to the destination. + +deliverer_context + This member contains a pointer to an application defined context which + is passed to delivery function. + +maximum_message_size + This member contains the maximum size message to process. + +maximum_messages + This member contains the maximum number of messages to be able to buffer. + +output_thread_priority + This member contains the priority of output thread. + +output_thread_stack_size + This member contains the Stack size of output thread. + +output_thread_period + This member contains the period (in ticks) of output thread. + +maximum_to_dequeue_per_period + This member contains the maximum number of messages the output thread + should dequeue and deliver per period. + +.. rubric:: NOTES: + +This type is passed as an argument to :ref:`InterfaceRtemsRegulatorCreate`. + +.. Handwritten + +.. index:: rtems_regulator_deliverer + +.. _InterfaceRtemsRegulatorDeliverer: + +rtems_regulator_deliverer +------------------------- + +This type represents the function signature used to specify a delivery +function for the RTEMS Regulator. + +.. rubric:: NOTES: + +This type is used in the :ref:`InterfaceRtemsRegulatorAttributes` +structure which is passed as an argument to +:ref:`InterfaceRtemsRegulatorCreate`. + +.. Handwritten + +.. index:: rtems_regulator_statistics + +.. _InterfaceRtemsRegulatorStatistics: + +rtems_regulator_statistics +-------------------------- + +This structure defines the statistics maintained by each Regulator instance. + +.. rubric:: MEMBERS: + +obtained + This member contains the number of successfully obtained buffers. + +released + This member contains the number of successfully released buffers. + +delivered + This member contains the number of successfully delivered buffers. + +period_statistics + This member contains the Rate Monotonic Period + statistics for the Delivery Thread. It is an instance of the + :ref:`InterfaceRtemsRateMonotonicPeriodStatistics` structure. + +.. rubric:: NOTES: + +This type is passed as an argument to +:ref:`InterfaceRtemsRegulatorGetStatistics`. + +.. Generated from spec:/rtems/signal/if/set .. index:: rtems_signal_set -``rtems_signal_set`` - The data type used to manage and manipulate RTEMS signal sets with the Signal - Manager. +.. _InterfaceRtemsSignalSet: + +rtems_signal_set +---------------- -.. index:: int8_t +This integer type represents a bit field which can hold exactly 32 individual +signals. -``int8_t`` - The C99 data type that corresponds to signed eight bit integers. This data - type is defined by RTEMS in a manner that ensures it is portable across - different target processors. +.. Generated from spec:/rtems/config/if/stack-allocate-hook -.. index:: int16_t +.. index:: rtems_stack_allocate_hook -``int16_t`` - The C99 data type that corresponds to signed sixteen bit integers. This data - type is defined by RTEMS in a manner that ensures it is portable across - different target processors. +.. _InterfaceRtemsStackAllocateHook: -.. index:: int32_t +rtems_stack_allocate_hook +------------------------- -``int32_t`` - The C99 data type that corresponds to signed thirty-two bit integers. This - data type is defined by RTEMS in a manner that ensures it is portable across - different target processors. +A thread stack allocator allocate handler shall have this type. -.. index:: int64_t +.. Generated from spec:/rtems/config/if/stack-allocate-init-hook -``int64_t`` - The C99 data type that corresponds to signed sixty-four bit integers. This - data type is defined by RTEMS in a manner that ensures it is portable across - different target processors. +.. index:: rtems_stack_allocate_init_hook -.. index:: rtems_single +.. _InterfaceRtemsStackAllocateInitHook: -``rtems_single`` - This type is deprecated will be removed in RTEMS 6.1. Use ``float`` instead. +rtems_stack_allocate_init_hook +------------------------------ + +A task stack allocator initialization handler shall have this type. + +.. Generated from spec:/rtems/config/if/stack-free-hook + +.. index:: rtems_stack_free_hook + +.. _InterfaceRtemsStackFreeHook: + +rtems_stack_free_hook +--------------------- + +A task stack allocator free handler shall have this type. + +.. Generated from spec:/rtems/status/if/code .. index:: rtems_status_code -``rtems_status_code`` - The return type for most RTEMS services. This is an enumerated type of - approximately twenty-five values. In general, when a service returns a - particular status code, it indicates that a very specific error condition has - occurred. +.. _InterfaceRtemsStatusCode: + +rtems_status_code +----------------- + +This enumeration provides status codes for directives of the Classic API. + +.. rubric:: ENUMERATORS: + +RTEMS_SUCCESSFUL + This status code indicates successful completion of a requested operation. + +RTEMS_TASK_EXITTED + This status code indicates that a thread exitted. + +RTEMS_MP_NOT_CONFIGURED + This status code indicates that multiprocessing was not configured. + +RTEMS_INVALID_NAME + This status code indicates that an object name was invalid. + +RTEMS_INVALID_ID + This status code indicates that an object identifier was invalid. + +RTEMS_TOO_MANY + This status code indicates you have attempted to create too many instances + of a particular object class. + +RTEMS_TIMEOUT + This status code indicates that a blocking directive timed out. + +RTEMS_OBJECT_WAS_DELETED + This status code indicates the object was deleted while the thread was + blocked waiting. + +RTEMS_INVALID_SIZE + This status code indicates that a specified size was invalid. + +RTEMS_INVALID_ADDRESS + This status code indicates that a specified address was invalid. + +RTEMS_INVALID_NUMBER + This status code indicates that a specified number was invalid. + +RTEMS_NOT_DEFINED + This status code indicates that the item has not been initialized. + +RTEMS_RESOURCE_IN_USE + This status code indicates that the object still had resources in use. + +RTEMS_UNSATISFIED + This status code indicates that the request was not satisfied. + +RTEMS_INCORRECT_STATE + This status code indicates that an object was in wrong state for the + requested operation. + +RTEMS_ALREADY_SUSPENDED + This status code indicates that the thread was already suspended. + +RTEMS_ILLEGAL_ON_SELF + This status code indicates that the operation was illegal on the calling + thread. + +RTEMS_ILLEGAL_ON_REMOTE_OBJECT + This status code indicates that the operation was illegal on a remote + object. + +RTEMS_CALLED_FROM_ISR + This status code indicates that the operation should not be called from + this execution environment. + +RTEMS_INVALID_PRIORITY + This status code indicates that an invalid thread priority was provided. + +RTEMS_INVALID_CLOCK + This status code indicates that a specified date or time was invalid. + +RTEMS_INVALID_NODE + This status code indicates that a specified node identifier was invalid. + +RTEMS_NOT_CONFIGURED + This status code indicates that the directive was not configured. + +RTEMS_NOT_OWNER_OF_RESOURCE + This status code indicates that the caller was not the owner of the + resource. + +RTEMS_NOT_IMPLEMENTED + This status code indicates the directive or requested portion of the + directive is not implemented. This is a hint that you have stumbled across + an opportunity to submit code to the RTEMS Project. + +RTEMS_INTERNAL_ERROR + This status code indicates that an internal RTEMS inconsistency was + detected. + +RTEMS_NO_MEMORY + This status code indicates that the directive attempted to allocate memory + but was unable to do so. + +RTEMS_IO_ERROR + This status code indicates a device driver IO error. + +RTEMS_INTERRUPTED + This status code is used internally by the implementation to indicate a + blocking device driver call has been interrupted and should be reflected to + the caller as interrupted. + +RTEMS_PROXY_BLOCKING + This status code is used internally by the implementation when performing + operations on behalf of remote tasks. This is referred to as proxying + operations and this status indicates that the operation could not be + completed immediately and the proxy is blocking. + +.. Generated from spec:/rtems/task/if/task .. index:: rtems_task -``rtems_task`` - The return type for an RTEMS Task. +.. _InterfaceRtemsTask: + +rtems_task +---------- + +This type defines the return type of task entry points. + +.. rubric:: DESCRIPTION: + +This type can be used to document task entry points in the source code. + +.. Generated from spec:/rtems/task/if/argument .. index:: rtems_task_argument -``rtems_task_argument`` - The data type for the argument passed to each RTEMS task. In RTEMS 4.7 and - older, this is an unsigned thirty-two bit integer. In RTEMS 4.8 and newer, - this is based upon the C99 type ``uintptr_t`` which is guaranteed to be an - integer large enough to hold a pointer on the target architecture. +.. _InterfaceRtemsTaskArgument: + +rtems_task_argument +------------------- + +This integer type represents task argument values. + +.. rubric:: NOTES: + +The type is an architecture-specific unsigned integer type which is large +enough to represent pointer values and 32-bit unsigned integers. + +.. Generated from spec:/rtems/userext/if/task-begin .. index:: rtems_task_begin_extension -``rtems_task_begin_extension`` - The entry point for a task beginning execution user extension handler - routine. +.. _InterfaceRtemsTaskBeginExtension: + +rtems_task_begin_extension +-------------------------- + +Task begin extensions are invoked when a task begins execution. + +.. rubric:: NOTES: + +The task begin extensions are invoked in :term:`extension forward order`. + +Task begin extensions are invoked with thread dispatching enabled. This allows +the use of dynamic memory allocation, creation of POSIX keys, and use of C++ +thread-local storage. Blocking synchronization primitives are allowed also. + +The task begin extensions are invoked before the global construction. + +The task begin extensions may be called as a result of a task restart through +:ref:`InterfaceRtemsTaskRestart`. + +.. Generated from spec:/rtems/task/if/config + +.. index:: rtems_task_config + +.. _InterfaceRtemsTaskConfig: + +rtems_task_config +----------------- + +This structure defines the configuration of a task constructed by +:ref:`InterfaceRtemsTaskConstruct`. + +.. rubric:: MEMBERS: + +name + This member defines the name of the task. + +initial_priority + This member defines the initial priority of the task. + +storage_area + This member shall point to the task storage area begin. The task storage + area will contain the task stack, the thread-local storage, and the + floating-point context on architectures with a separate floating-point + context. + + The task storage area begin address and size should be aligned by + :c:macro:`RTEMS_TASK_STORAGE_ALIGNMENT`. To avoid memory waste, use + :c:func:`RTEMS_ALIGNED` and :c:macro:`RTEMS_TASK_STORAGE_ALIGNMENT` to + enforce the recommended alignment of a statically allocated task storage + area. + +storage_size + This member defines size of the task storage area in bytes. Use the + :ref:`InterfaceRTEMSTASKSTORAGESIZE` macro to determine the recommended + task storage area size. + +maximum_thread_local_storage_size + This member defines the maximum thread-local storage size supported by the + task storage area. Use :c:func:`RTEMS_ALIGN_UP` and + :c:macro:`RTEMS_TASK_STORAGE_ALIGNMENT` to adjust the size to meet the + minimum alignment requirement of a thread-local storage area used to + construct a task. + + If the value is less than the actual thread-local storage size, then the + task construction by :ref:`InterfaceRtemsTaskConstruct` fails. + + If the is less than the task storage area size, then the task construction + by :ref:`InterfaceRtemsTaskConstruct` fails. + + The actual thread-local storage size is determined when the application + executable is linked. The ``rtems-exeinfo`` command line tool included in + the RTEMS Tools can be used to obtain the thread-local storage size and + alignment of an application executable. + + The application may configure the maximum thread-local storage size for all + threads explicitly through the + :ref:`CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE` configuration option. + +storage_free + This member defines the optional handler to free the task storage area. It + is called on exactly two mutually exclusive occasions. Firstly, when the + task construction aborts due to a failed task create extension, or + secondly, when the task is deleted. It is called from task context under + protection of the object allocator lock. It is allowed to call + :c:func:`free` in this handler. If handler is `NULL + <https://en.cppreference.com/w/c/types/NULL>`_, then no action will be + performed. + +initial_modes + This member defines the initial modes of the task. + +attributes + This member defines the attributes of the task. + +.. Generated from spec:/rtems/userext/if/task-create .. index:: rtems_task_create_extension -``rtems_task_create_extension`` - The entry point for a task creation execution user extension handler routine. +.. _InterfaceRtemsTaskCreateExtension: + +rtems_task_create_extension +--------------------------- + +Task create extensions are invoked when a task is created. + +.. rubric:: NOTES: + +The task create extensions are invoked in :term:`extension forward order`. + +The task create extensions are invoked after a new task has been completely +initialized, but before it is started. + +While normal tasks are created, the executing thread is the owner of the object +allocator mutex. The object allocator mutex allows nesting, so the normal +memory allocation routines can be used allocate memory for the created thread. + +If the task create extension returns :c:macro:`false`, then the task create +operation stops immediately and the entire task create operation will fail. In +this case, all task delete extensions are invoked, see +:ref:`InterfaceRtemsTaskDeleteExtension`. + +.. Generated from spec:/rtems/userext/if/task-delete .. index:: rtems_task_delete_extension -``rtems_task_delete_extension`` - The entry point for a task deletion user extension handler routine. +.. _InterfaceRtemsTaskDeleteExtension: + +rtems_task_delete_extension +--------------------------- + +Task delete extensions are invoked when a task is deleted. + +.. rubric:: NOTES: + +The task delete extensions are invoked in :term:`extension reverse order`. + +The task delete extensions are invoked by task create directives before an +attempt to allocate a :term:`TCB` is made. + +If a task create extension failed, then a task delete extension may be invoked +without a previous invocation of the corresponding task create extension of the +extension set. + +.. Generated from spec:/rtems/task/if/entry .. index:: rtems_task_entry -``rtems_task_entry`` - The address of the entry point to an RTEMS ASR. It is equivalent to the - entry point of the function implementing the ASR. +.. _InterfaceRtemsTaskEntry: + +rtems_task_entry +---------------- + +This type defines the :term:`task entry` point of an RTEMS task. + +.. Generated from spec:/rtems/userext/if/task-exitted .. index:: rtems_task_exitted_extension -``rtems_task_exitted_extension`` - The entry point for a task exitted user extension handler routine. +.. _InterfaceRtemsTaskExittedExtension: + +rtems_task_exitted_extension +---------------------------- + +Task exitted extensions are invoked when a task entry returns. + +.. rubric:: NOTES: + +The task exitted extensions are invoked in :term:`extension forward order`. + +.. Generated from spec:/rtems/type/if/priority .. index:: rtems_task_priority -``rtems_task_priority`` - The data type used to manage and manipulate task priorities. +.. _InterfaceRtemsTaskPriority: + +rtems_task_priority +------------------- + +This integer type represents task priorities of the Classic API. + +.. Generated from spec:/rtems/userext/if/task-restart .. index:: rtems_task_restart_extension -``rtems_task_restart_extension`` - The entry point for a task restart user extension handler routine. +.. _InterfaceRtemsTaskRestartExtension: + +rtems_task_restart_extension +---------------------------- + +Task restart extensions are invoked when a task restarts. + +.. rubric:: NOTES: + +The task restart extensions are invoked in :term:`extension forward order`. + +The task restart extensions are invoked in the context of the restarted thread +right before the execution context is reloaded. The thread stack reflects the +previous execution context. + +Thread restart and delete requests issued by restart extensions lead to +recursion. + +.. Generated from spec:/rtems/userext/if/task-start .. index:: rtems_task_start_extension -``rtems_task_start_extension`` - The entry point for a task start user extension handler routine. +.. _InterfaceRtemsTaskStartExtension: + +rtems_task_start_extension +-------------------------- + +Task start extensions are invoked when a task was made ready for the first +time. + +.. rubric:: NOTES: + +The task start extensions are invoked in :term:`extension forward order`. + +In SMP configurations, the thread may already run on another processor before +the task start extensions are actually invoked. Task switch and task begin +extensions may run before or in parallel with the thread start extension in SMP +configurations, see :ref:`InterfaceRtemsTaskSwitchExtension` and +:ref:`InterfaceRtemsTaskBeginExtension`. + +.. Generated from spec:/rtems/userext/if/task-switch .. index:: rtems_task_switch_extension -``rtems_task_switch_extension`` - The entry point for a task context switch user extension handler routine. +.. _InterfaceRtemsTaskSwitchExtension: + +rtems_task_switch_extension +--------------------------- + +Task switch extensions are invoked when a thread switch from an executing +thread to a heir thread takes place. + +.. rubric:: NOTES: + +The task switch extensions are invoked in :term:`extension forward order`. + +The invocation conditions of the task switch extensions depend on whether RTEMS +was built with SMP support enabled or disabled. A user must pay attention to +the differences to correctly implement a task switch extension. + +Where the system was built with SMP support disabled, the task switch +extensions are invoked before the context switch from the currently executing +thread to the heir thread. The executing is a pointer to the :term:`TCB` of +the currently executing thread. The heir is a pointer to the TCB of the heir +thread. The context switch initiated through the multitasking start is not +covered by the task switch extensions. + +Where the system was built with SMP support enabled, the task switch extensions +are invoked after the context switch to the heir thread. The executing is a +pointer to the TCB of the previously executing thread. Despite the name, this +is not the currently executing thread. The heir is a pointer to the TCB of the +newly executing thread. This is the currently executing thread. The context +switches initiated through the multitasking start are covered by the task +switch extensions. The reason for the differences to uniprocessor +configurations is that the context switch may update the heir thread of the +processor. The task switch extensions are invoked with maskable interrupts +disabled and with ownership of a processor-specific SMP lock. Task switch +extensions may run in parallel on multiple processors. It is recommended to +use thread-local or processor-specific data structures for task switch +extensions. A global SMP lock should be avoided for performance reasons, see +:ref:`InterfaceRtemsInterruptLockInitialize`. + +.. Generated from spec:/rtems/userext/if/task-terminate + +.. index:: rtems_task_terminate_extension + +.. _InterfaceRtemsTaskTerminateExtension: + +rtems_task_terminate_extension +------------------------------ + +Task terminate extensions are invoked when a task terminates. + +.. rubric:: NOTES: + +The task terminate extensions are invoked in :term:`extension reverse order`. + +The task terminate extensions are invoked in the context of the terminating +thread right before the thread dispatch to the heir thread should take place. +The thread stack reflects the previous execution context. The POSIX cleanup +and key destructors execute in this context. + +Thread restart and delete requests issued by terminate extensions lead to +recursion. + +.. Generated from spec:/rtems/task/if/visitor + +.. index:: rtems_task_visitor + +.. _InterfaceRtemsTaskVisitor: + +rtems_task_visitor +------------------ + +Visitor routines invoked by :ref:`InterfaceRtemsTaskIterate` shall have this +type. + +.. Generated from spec:/rtems/task/if/tcb .. index:: rtems_tcb -``rtems_tcb`` - The data structure associated with each task in an RTEMS system. +.. _InterfaceRtemsTcb: + +rtems_tcb +--------- + +This structure represents the :term:`TCB`. + +.. Generated from spec:/rtems/type/if/time-of-day .. index:: rtems_time_of_day -``rtems_time_of_day`` - The data structure used to manage and manipulate calendar time in RTEMS. +.. _InterfaceRtemsTimeOfDay: + +rtems_time_of_day +----------------- + +This type represents Classic API calendar times. + +.. rubric:: MEMBERS: + +year + This member contains the year A.D. + +month + This member contains the month of the year with values from 1 to 12. + +day + This member contains the day of the month with values from 1 to 31. + +hour + This member contains the hour of the day with values from 0 to 23. + +minute + This member contains the minute of the hour with values from 0 to 59. + +second + This member contains the second of the minute with values from 0 to 59. + +ticks + This member contains the clock tick of the second with values from 0 to + :ref:`InterfaceRtemsClockGetTicksPerSecond` minus one. + +.. Generated from spec:/rtems/timer/if/information + +.. index:: rtems_timer_information + +.. _InterfaceRtemsTimerInformation: + +rtems_timer_information +----------------------- + +The structure contains information about a timer. + +.. rubric:: MEMBERS: + +the_class + The timer class member indicates how the timer was most recently fired. + +initial + This member indicates the initial requested interval. + +start_time + This member indicates the time the timer was initially scheduled. The time + is in clock ticks since the clock driver initialization or the last clock + tick counter overflow. + +stop_time + This member indicates the time the timer was scheduled to fire. The time is + in clock ticks since the clock driver initialization or the last clock tick + counter overflow. + +.. Generated from spec:/rtems/timer/if/service-routine .. index:: rtems_timer_service_routine -``rtems_timer_service_routine`` - The return type for an RTEMS Timer Service Routine. +.. _InterfaceRtemsTimerServiceRoutine: -.. index:: rtems_timer_service_routine_entry +rtems_timer_service_routine +--------------------------- -``rtems_timer_service_routine_entry`` - The address of the entry point to an RTEMS TSR. It is equivalent to the - entry point of the function implementing the TSR. +This type defines the return type of routines which can be fired by directives +of the Timer Manager. -.. index:: rtems_vector_number +.. rubric:: DESCRIPTION: -``rtems_vector_number`` - The data type used to manage and manipulate interrupt vector numbers. +This type can be used to document timer service routines in the source code. -.. index:: uint8_t +.. Generated from spec:/rtems/timer/if/service-routine-entry -``uint8_t`` - The C99 data type that corresponds to unsigned eight bit integers. This data - type is defined by RTEMS in a manner that ensures it is portable across - different target processors. +.. index:: rtems_timer_service_routine_entry -.. index:: uint16_t +.. _InterfaceRtemsTimerServiceRoutineEntry: -``uint16_t`` - The C99 data type that corresponds to unsigned sixteen bit integers. This - data type is defined by RTEMS in a manner that ensures it is portable across - different target processors. +rtems_timer_service_routine_entry +--------------------------------- -.. index:: uint32_t +This type defines the prototype of routines which can be fired by directives of +the Timer Manager. -``uint32_t`` - The C99 data type that corresponds to unsigned thirty-two bit integers. This - data type is defined by RTEMS in a manner that ensures it is portable across - different target processors. +.. Generated from spec:/rtems/intr/if/vector-number -.. index:: uint64_t +.. index:: rtems_vector_number -``uint64_t`` - The C99 data type that corresponds to unsigned sixty-four bit integers. This - data type is defined by RTEMS in a manner that ensures it is portable across - different target processors. +.. _InterfaceRtemsVectorNumber: -.. index:: uintptr_t +rtems_vector_number +------------------- -``uintptr_t`` - The C99 data type that corresponds to the unsigned integer type that is of - sufficient size to represent addresses as unsigned integers. This data type - is defined by RTEMS in a manner that ensures it is portable across different - target processors. +This integer type represents interrupt vector numbers. diff --git a/c-user/scheduling-concepts/background.rst b/c-user/scheduling-concepts/background.rst index 7f8a63d..38b77ee 100644 --- a/c-user/scheduling-concepts/background.rst +++ b/c-user/scheduling-concepts/background.rst @@ -117,10 +117,7 @@ Task Priority and Scheduling The most significant task scheduling modification mechanism is the ability for the user to assign a priority level to each individual task when it is created -and to alter a task's priority at run-time. The maximum priority level depends -on the configured scheduler. A lower priority level means higher priority -(higher importance). The maximum priority level of the default uniprocessor -scheduler is 255. +and to alter a task's priority at run-time, see :ref:`TaskPriority`. .. index:: preemption @@ -163,7 +160,7 @@ Manual Round-Robin The final mechanism for altering the RTEMS scheduling algorithm is called manual round-robin. Manual round-robin is invoked by using -the ``rtems_task_wake_after`` directive with a time interval of +the ``rtems_task_wake_after`` directive with a ``ticks`` parameter of ``RTEMS_YIELD_PROCESSOR``. This allows a task to give up the processor and be immediately returned to the ready chain at the end of its priority group. If no other tasks of the same priority are ready to run, then the task does not @@ -246,7 +243,7 @@ of the following conditions: option and the requested semaphore is unavailable. - The running task issues a ``rtems_task_wake_after`` directive which blocks - the task for the given time interval. If the time interval specified is + the task for the given count of ticks. If the count of ticks specified is zero, the task yields the processor and remains in the ready state. - The running task issues a ``rtems_task_wake_when`` directive which blocks the @@ -283,8 +280,8 @@ conditions: - A running task issues a ``rtems_semaphore_release`` directive which releases the semaphore on which the blocked task is waiting. -- A timeout interval expires for a task which was blocked by a call to the - ``rtems_task_wake_after`` directive. +- The requested count of ticks has elapsed for a task which was blocked by a + call to the ``rtems_task_wake_after`` directive. - A timeout period expires for a task which blocked by a call to the ``rtems_task_wake_when`` directive. diff --git a/c-user/scheduling-concepts/directives.rst b/c-user/scheduling-concepts/directives.rst index 5b1246f..115b4fa 100644 --- a/c-user/scheduling-concepts/directives.rst +++ b/c-user/scheduling-concepts/directives.rst @@ -1,424 +1,707 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +.. Copyright (C) 2013, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. _SchedulerManagerDirectives: Directives ========== -This section details the scheduler manager. A subsection is dedicated to each -of these services and describes the calling sequence, related constants, usage, -and status codes. +This section details the directives of the Scheduler Manager. A subsection is +dedicated to each of this manager's directives and lists the calling sequence, +parameters, description, return values, and notes of the directive. + +.. Generated from spec:/rtems/scheduler/if/ident .. raw:: latex - \clearpage + \clearpage -.. _rtems_scheduler_ident: +.. index:: rtems_scheduler_ident() -SCHEDULER_IDENT - Get ID of a scheduler ---------------------------------------- +.. _InterfaceRtemsSchedulerIdent: + +rtems_scheduler_ident() +----------------------- + +Identifies a scheduler by the object name. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_scheduler_ident( rtems_name name, rtems_id *id ); + +.. rubric:: PARAMETERS: + +``name`` + This parameter is the scheduler name to look up. + +``id`` + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the identifier of the scheduler will be + stored in this object. -CALLING SEQUENCE: - .. code-block:: c +.. rubric:: DESCRIPTION: - rtems_status_code rtems_scheduler_ident( - rtems_name name, - rtems_id *id - ); +This directive obtains a scheduler identifier associated with the scheduler +name specified in ``name``. -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +.. rubric:: RETURN VALUES: - * - ``RTEMS_SUCCESSFUL`` - - Successful operation. - * - ``RTEMS_INVALID_ADDRESS`` - - The ``id`` parameter is ``NULL``. - * - ``RTEMS_INVALID_NAME`` - - Invalid scheduler name. +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. -DESCRIPTION: - Identifies a scheduler by its name. The scheduler name is determined by - the scheduler configuration. See :ref:`ConfigurationSchedulerTable` - and :ref:`CONFIGURE_SCHEDULER_NAME`. +:c:macro:`RTEMS_INVALID_NAME` + There was no scheduler associated with the name. -NOTES: - None. +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``id`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +.. rubric:: NOTES: + +The scheduler name is determined by the scheduler configuration. + +The scheduler identifier is used with other scheduler related directives to +access the scheduler. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/scheduler/if/ident-by-processor .. raw:: latex - \clearpage + \clearpage + +.. index:: rtems_scheduler_ident_by_processor() + +.. _InterfaceRtemsSchedulerIdentByProcessor: -.. _rtems_scheduler_ident_by_processor: +rtems_scheduler_ident_by_processor() +------------------------------------ -SCHEDULER_IDENT_BY_PROCESSOR - Get ID of a scheduler by processor ------------------------------------------------------------------ +Identifies a scheduler by the processor index. -CALLING SEQUENCE: - .. code-block:: c +.. rubric:: CALLING SEQUENCE: - rtems_status_code rtems_scheduler_ident_by_processor( - uint32_t cpu_index, - rtems_id *id - ); +.. code-block:: c -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table + rtems_status_code rtems_scheduler_ident_by_processor( + uint32_t cpu_index, + rtems_id *id + ); - * - ``RTEMS_SUCCESSFUL`` - - Successful operation. - * - ``RTEMS_INVALID_ADDRESS`` - - The ``id`` parameter is ``NULL``. - * - ``RTEMS_INVALID_NAME`` - - Invalid processor index. - * - ``RTEMS_INCORRECT_STATE`` - - The processor index is valid, however, this processor is not owned by - a scheduler. +.. rubric:: PARAMETERS: -DESCRIPTION: - Identifies a scheduler by a processor. +``cpu_index`` + This parameter is the processor index to identify the scheduler. -NOTES: - None. +``id`` + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the identifier of the scheduler will be + stored in this object. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``id`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_NAME` + The processor index was invalid. + +:c:macro:`RTEMS_INCORRECT_STATE` + The processor index was valid, however, the corresponding processor was not + owned by a scheduler. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/scheduler/if/ident-by-processor-set .. raw:: latex - \clearpage + \clearpage + +.. index:: rtems_scheduler_ident_by_processor_set() + +.. _InterfaceRtemsSchedulerIdentByProcessorSet: + +rtems_scheduler_ident_by_processor_set() +---------------------------------------- + +Identifies a scheduler by the processor set. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_scheduler_ident_by_processor_set( + size_t cpusetsize, + const cpu_set_t *cpuset, + rtems_id *id + ); + +.. rubric:: PARAMETERS: + +``cpusetsize`` + This parameter is the size of the processor set referenced by ``cpuset`` in + bytes. The size shall be positive. + +``cpuset`` + This parameter is the pointer to a :c:type:`cpu_set_t`. The referenced + processor set will be used to identify the scheduler. -.. _rtems_scheduler_ident_by_processor_set: +``id`` + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the identifier of the scheduler will be + stored in this object. -SCHEDULER_IDENT_BY_PROCESSOR_SET - Get ID of a scheduler by processor set -------------------------------------------------------------------------- +.. rubric:: DESCRIPTION: -CALLING SEQUENCE: - .. code-block:: c +The scheduler is selected according to the highest numbered online processor in +the specified processor set. - rtems_status_code rtems_scheduler_ident_by_processor_set( - size_t cpusetsize, - const cpu_set_t *cpuset, - rtems_id *id - ); +.. rubric:: RETURN VALUES: -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. - * - ``RTEMS_SUCCESSFUL`` - - Successful operation. - * - ``RTEMS_INVALID_ADDRESS`` - - The ``id`` parameter is ``NULL``. - * - ``RTEMS_INVALID_SIZE`` - - Invalid processor set size. - * - ``RTEMS_INVALID_NAME`` - - The processor set contains no online processor. - * - ``RTEMS_INCORRECT_STATE`` - - The processor set is valid, however, the highest numbered online - processor in the specified processor set is not owned by a scheduler. +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``id`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. -DESCRIPTION: - Identifies a scheduler by a processor set. The scheduler is selected - according to the highest numbered online processor in the specified - processor set. +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``cpuset`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. -NOTES: - None. +:c:macro:`RTEMS_INVALID_SIZE` + The processor set size was invalid. + +:c:macro:`RTEMS_INVALID_NAME` + The processor set contained no online processor. + +:c:macro:`RTEMS_INCORRECT_STATE` + The processor set was valid, however, the highest numbered online processor + in the processor set was not owned by a scheduler. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/scheduler/if/get-maximum-priority .. raw:: latex - \clearpage + \clearpage + +.. index:: rtems_scheduler_get_maximum_priority() + +.. _InterfaceRtemsSchedulerGetMaximumPriority: + +rtems_scheduler_get_maximum_priority() +-------------------------------------- -.. _rtems_scheduler_get_maximum_priority: +Gets the maximum task priority of the scheduler. -SCHEDULER_GET_MAXIMUM_PRIORITY - Get maximum task priority of a scheduler -------------------------------------------------------------------------- +.. rubric:: CALLING SEQUENCE: -CALLING SEQUENCE: - .. code-block:: c +.. code-block:: c - rtems_status_code rtems_scheduler_get_maximum_priority( - rtems_id scheduler_id, - rtems_task_priority *priority - ); + rtems_status_code rtems_scheduler_get_maximum_priority( + rtems_id scheduler_id, + rtems_task_priority *priority + ); -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +.. rubric:: PARAMETERS: - * - ``RTEMS_SUCCESSFUL`` - - Successful operation. - * - ``RTEMS_INVALID_ID`` - - Invalid scheduler instance identifier. - * - ``RTEMS_INVALID_ADDRESS`` - - The ``priority`` parameter is ``NULL``. +``scheduler_id`` + This parameter is the scheduler identifier. -DESCRIPTION: - Returns the maximum task priority of the specified scheduler instance in - ``priority``. +``priority`` + This parameter is the pointer to an :ref:`InterfaceRtemsTaskPriority` + object. When the directive the maximum priority of the scheduler will be + stored in this object. -NOTES: - None. +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no scheduler associated with the identifier specified by + ``scheduler_id``. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``priority`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/scheduler/if/map-priority-to-posix .. raw:: latex - \clearpage + \clearpage + +.. index:: rtems_scheduler_map_priority_to_posix() + +.. _InterfaceRtemsSchedulerMapPriorityToPosix: -.. _rtems_scheduler_map_priority_to_posix: +rtems_scheduler_map_priority_to_posix() +--------------------------------------- + +Maps a Classic API task priority to the corresponding POSIX thread priority. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_scheduler_map_priority_to_posix( + rtems_id scheduler_id, + rtems_task_priority priority, + int *posix_priority + ); + +.. rubric:: PARAMETERS: + +``scheduler_id`` + This parameter is the scheduler identifier. + +``priority`` + This parameter is the Classic API task priority to map. + +``posix_priority`` + This parameter is the pointer to an ``int`` object. When the directive + call is successful, the POSIX thread priority value corresponding to the + specified Classic API task priority value will be stored in this object. + +.. rubric:: RETURN VALUES: -SCHEDULER_MAP_PRIORITY_TO_POSIX - Map task priority to POSIX thread prority ---------------------------------------------------------------------------- +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. -CALLING SEQUENCE: - .. code-block:: c +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``posix_priority`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. - rtems_status_code rtems_scheduler_map_priority_to_posix( - rtems_id scheduler_id, - rtems_task_priority priority, - int *posix_priority - ); +:c:macro:`RTEMS_INVALID_ID` + There was no scheduler associated with the identifier specified by + ``scheduler_id``. -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +:c:macro:`RTEMS_INVALID_PRIORITY` + The Classic API task priority was invalid. - * - ``RTEMS_SUCCESSFUL`` - - Successful operation. - * - ``RTEMS_INVALID_ADDRESS`` - - The ``posix_priority`` parameter is ``NULL``. - * - ``RTEMS_INVALID_ID`` - - Invalid scheduler instance identifier. - * - ``RTEMS_INVALID_PRIORITY`` - - Invalid task priority. +.. rubric:: CONSTRAINTS: -DESCRIPTION: - Maps a task priority to the corresponding POSIX thread priority. +The following constraints apply to this directive: -NOTES: - None. +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/scheduler/if/map-priority-from-posix .. raw:: latex - \clearpage + \clearpage + +.. index:: rtems_scheduler_map_priority_from_posix() + +.. _InterfaceRtemsSchedulerMapPriorityFromPosix: + +rtems_scheduler_map_priority_from_posix() +----------------------------------------- + +Maps a POSIX thread priority to the corresponding Classic API task priority. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_scheduler_map_priority_from_posix( + rtems_id scheduler_id, + int posix_priority, + rtems_task_priority *priority + ); + +.. rubric:: PARAMETERS: -.. _rtems_scheduler_map_priority_from_posix: +``scheduler_id`` + This parameter is the scheduler identifier. -SCHEDULER_MAP_PRIORITY_FROM_POSIX - Map POSIX thread prority to task priority ------------------------------------------------------------------------------ +``posix_priority`` + This parameter is the POSIX thread priority to map. -CALLING SEQUENCE: - .. code-block:: c +``priority`` + This parameter is the pointer to an :ref:`InterfaceRtemsTaskPriority` + object. When the directive call is successful, the Classic API task + priority value corresponding to the specified POSIX thread priority value + will be stored in this object. - rtems_status_code rtems_scheduler_map_priority_from_posix( - rtems_id scheduler_id, - int posix_priority, - rtems_task_priority *priority - ); +.. rubric:: RETURN VALUES: -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. - * - ``RTEMS_SUCCESSFUL`` - - Successful operation. - * - ``RTEMS_INVALID_ADDRESS`` - - The ``priority`` parameter is ``NULL``. - * - ``RTEMS_INVALID_ID`` - - Invalid scheduler instance identifier. - * - ``RTEMS_INVALID_PRIORITY`` - - Invalid POSIX thread priority. +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``priority`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. -DESCRIPTION: - Maps a POSIX thread priority to the corresponding task priority. +:c:macro:`RTEMS_INVALID_ID` + There was no scheduler associated with the identifier specified by + ``scheduler_id``. -NOTES: - None. +:c:macro:`RTEMS_INVALID_PRIORITY` + The POSIX thread priority was invalid. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/scheduler/if/get-processor .. raw:: latex - \clearpage + \clearpage + +.. index:: rtems_scheduler_get_processor() + +.. _InterfaceRtemsSchedulerGetProcessor: + +rtems_scheduler_get_processor() +------------------------------- + +Returns the index of the current processor. + +.. rubric:: CALLING SEQUENCE: -.. _rtems_scheduler_get_processor: +.. code-block:: c -SCHEDULER_GET_PROCESSOR - Get current processor index ------------------------------------------------------ + uint32_t rtems_scheduler_get_processor( void ); -CALLING SEQUENCE: - .. code-block:: c +.. rubric:: DESCRIPTION: - uint32_t rtems_scheduler_get_processor( void ); +Where the system was built with SMP support disabled, this directive evaluates +to a compile time constant of zero. -DIRECTIVE STATUS CODES: - This directive returns the index of the current processor. +Where the system was built with SMP support enabled, this directive returns the +index of the current processor. The set of processor indices is the range of +integers starting with zero up to +:ref:`InterfaceRtemsSchedulerGetProcessorMaximum` minus one. -DESCRIPTION: - In uniprocessor configurations, a value of zero will be returned. +.. rubric:: RETURN VALUES: - In SMP configurations, an architecture specific method is used to obtain the - index of the current processor in the system. The set of processor indices - is the range of integers starting with zero up to the processor count minus - one. +Returns the index of the current processor. - Outside of sections with disabled thread dispatching the current processor - index may change after every instruction since the thread may migrate from - one processor to another. Sections with disabled interrupts are sections - with thread dispatching disabled. +.. rubric:: NOTES: -NOTES: - None. +Outside of sections with disabled thread dispatching the current processor +index may change after every instruction since the thread may migrate from one +processor to another. Sections with disabled interrupts are sections with +thread dispatching disabled. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/scheduler/if/get-processor-maximum .. raw:: latex - \clearpage + \clearpage + +.. index:: rtems_scheduler_get_processor_maximum() + +.. _InterfaceRtemsSchedulerGetProcessorMaximum: + +rtems_scheduler_get_processor_maximum() +--------------------------------------- + +Returns the processor maximum supported by the system. -.. _rtems_scheduler_get_processor_maximum: +.. rubric:: CALLING SEQUENCE: -SCHEDULER_GET_PROCESSOR_MAXIMUM - Get processor maximum -------------------------------------------------------- +.. code-block:: c -CALLING SEQUENCE: - .. code-block:: c + uint32_t rtems_scheduler_get_processor_maximum( void ); - uint32_t rtems_scheduler_get_processor_maximum( void ); +.. rubric:: DESCRIPTION: -DIRECTIVE STATUS CODES: - This directive returns the processor maximum supported by the system. +Where the system was built with SMP support disabled, this directive evaluates +to a compile time constant of one. -DESCRIPTION: - In uniprocessor configurations, a value of one will be returned. +Where the system was built with SMP support enabled, this directive returns the +minimum of the processors (physically or virtually) available at the +:term:`target` and the configured processor maximum (see +:ref:`CONFIGURE_MAXIMUM_PROCESSORS`). Not all processors in the range from +processor index zero to the last processor index (which is the processor +maximum minus one) may be configured to be used by a scheduler or may be online +(online processors have a scheduler assigned). - In SMP configurations, this directive returns the minimum of the processors - (physically or virtually) available by the platform and the configured - processor maximum. Not all processors in the range from processor index - zero to the last processor index (which is the processor maximum minus one) - may be configured to be used by a scheduler or online (online processors - have a scheduler assigned). +.. rubric:: RETURN VALUES: -NOTES: - None. +Returns the processor maximum supported by the system. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/scheduler/if/get-processor-set .. raw:: latex - \clearpage + \clearpage + +.. index:: rtems_scheduler_get_processor_set() + +.. _InterfaceRtemsSchedulerGetProcessorSet: + +rtems_scheduler_get_processor_set() +----------------------------------- + +Gets the set of processors owned by the scheduler. + +.. rubric:: CALLING SEQUENCE: -.. _rtems_scheduler_get_processor_set: +.. code-block:: c -SCHEDULER_GET_PROCESSOR_SET - Get processor set of a scheduler --------------------------------------------------------------- + rtems_status_code rtems_scheduler_get_processor_set( + rtems_id scheduler_id, + size_t cpusetsize, + cpu_set_t *cpuset + ); -CALLING SEQUENCE: - .. code-block:: c +.. rubric:: PARAMETERS: - rtems_status_code rtems_scheduler_get_processor_set( - rtems_id scheduler_id, - size_t cpusetsize, - cpu_set_t *cpuset - ); +``scheduler_id`` + This parameter is the scheduler identifier. -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +``cpusetsize`` + This parameter is the size of the processor set referenced by ``cpuset`` in + bytes. - * - ``RTEMS_SUCCESSFUL`` - - Successful operation. - * - ``RTEMS_INVALID_ID`` - - Invalid scheduler instance identifier. - * - ``RTEMS_INVALID_ADDRESS`` - - The ``cpuset`` parameter is ``NULL``. - * - ``RTEMS_INVALID_NUMBER`` - - The processor set buffer is too small for the set of processors owned - by the scheduler instance. +``cpuset`` + This parameter is the pointer to a :c:type:`cpu_set_t` object. When the + directive call is successful, the processor set of the scheduler will be + stored in this object. A set bit in the processor set means that the + corresponding processor is owned by the scheduler, otherwise the bit is + cleared. -DESCRIPTION: - Returns the processor set owned by the scheduler instance in ``cpuset``. A - set bit in the processor set means that this processor is owned by the - scheduler instance and a cleared bit means the opposite. +.. rubric:: RETURN VALUES: -NOTES: - None. +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``cpuset`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no scheduler associated with the identifier specified by + ``scheduler_id``. + +:c:macro:`RTEMS_INVALID_SIZE` + The provided processor set was too small for the set of processors owned by + the scheduler. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/scheduler/if/add-processor .. raw:: latex - \clearpage + \clearpage + +.. index:: rtems_scheduler_add_processor() + +.. _InterfaceRtemsSchedulerAddProcessor: -.. _rtems_scheduler_add_processor: +rtems_scheduler_add_processor() +------------------------------- -SCHEDULER_ADD_PROCESSOR - Add processor to a scheduler ------------------------------------------------------- +Adds the processor to the set of processors owned by the scheduler. -CALLING SEQUENCE: - .. code-block:: c +.. rubric:: CALLING SEQUENCE: - rtems_status_code rtems_scheduler_add_processor( - rtems_id scheduler_id, - uint32_t cpu_index - ); +.. code-block:: c -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table + rtems_status_code rtems_scheduler_add_processor( + rtems_id scheduler_id, + uint32_t cpu_index + ); - * - ``RTEMS_SUCCESSFUL`` - - Successful operation. - * - ``RTEMS_INVALID_ID`` - - Invalid scheduler instance identifier. - * - ``RTEMS_NOT_CONFIGURED`` - - The processor is not configured to be used by the application. - * - ``RTEMS_INCORRECT_STATE`` - - The processor is configured to be used by the application, however, it - is not online. - * - ``RTEMS_RESOURCE_IN_USE`` - - The processor is already assigned to a scheduler instance. +.. rubric:: PARAMETERS: -DESCRIPTION: - Adds a processor to the set of processors owned by the specified scheduler - instance. +``scheduler_id`` + This parameter is the scheduler identifier. -NOTES: - Must be called from task context. This operation obtains and releases the - objects allocator lock. +``cpu_index`` + This parameter is the index of the processor to add. + +.. rubric:: DESCRIPTION: + +This directive adds the processor specified by the ``cpu_index`` to the +scheduler specified by ``scheduler_id``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no scheduler associated with the identifier specified by + ``scheduler_id``. + +:c:macro:`RTEMS_NOT_CONFIGURED` + The processor was not configured to be used by the application. + +:c:macro:`RTEMS_INCORRECT_STATE` + The processor was configured to be used by the application, however, it was + not online. + +:c:macro:`RTEMS_RESOURCE_IN_USE` + The processor was already assigned to a scheduler. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. + +.. Generated from spec:/rtems/scheduler/if/remove-processor .. raw:: latex - \clearpage - -.. _rtems_scheduler_remove_processor: - -SCHEDULER_REMOVE_PROCESSOR - Remove processor from a scheduler --------------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_scheduler_remove_processor( - rtems_id scheduler_id, - uint32_t cpu_index - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - Successful operation. - * - ``RTEMS_INVALID_ID`` - - Invalid scheduler instance identifier. - * - ``RTEMS_INVALID_NUMBER`` - - The processor is not owned by the specified scheduler instance. - * - ``RTEMS_RESOURCE_IN_USE`` - - The set of processors owned by the specified scheduler instance would - be empty after the processor removal and there exists a non-idle task - that uses this scheduler instance as its home scheduler instance. - * - ``RTEMS_RESOURCE_IN_USE`` - - A task with a restricted processor affinity exists that uses this - scheduler instance as its home scheduler instance and it would be no - longer possible to allocate a processor for this task after the - removal of this processor. - -DESCRIPTION: - Removes a processor from set of processors owned by the specified scheduler - instance. - -NOTES: - Must be called from task context. This operation obtains and releases the - objects allocator lock. Removing a processor from a scheduler is a complex - operation that involves all tasks of the system. + \clearpage + +.. index:: rtems_scheduler_remove_processor() + +.. _InterfaceRtemsSchedulerRemoveProcessor: + +rtems_scheduler_remove_processor() +---------------------------------- + +Removes the processor from the set of processors owned by the scheduler. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_scheduler_remove_processor( + rtems_id scheduler_id, + uint32_t cpu_index + ); + +.. rubric:: PARAMETERS: + +``scheduler_id`` + This parameter is the scheduler identifier. + +``cpu_index`` + This parameter is the index of the processor to remove. + +.. rubric:: DESCRIPTION: + +This directive removes the processor specified by the ``cpu_index`` from the +scheduler specified by ``scheduler_id``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no scheduler associated with the identifier specified by + ``scheduler_id``. + +:c:macro:`RTEMS_INVALID_NUMBER` + The processor was not owned by the scheduler. + +:c:macro:`RTEMS_RESOURCE_IN_USE` + The processor was required by at least one non-idle task that used the + scheduler as its :term:`home scheduler`. + +:c:macro:`RTEMS_RESOURCE_IN_USE` + The processor was the last processor owned by the scheduler and there was + at least one task that used the scheduler as a :term:`helping scheduler`. + +.. rubric:: NOTES: + +Removing a processor from a scheduler is a complex operation that involves all +tasks of the system. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. diff --git a/c-user/scheduling-concepts/index.rst b/c-user/scheduling-concepts/index.rst index 6b16f1b..ee9aa26 100644 --- a/c-user/scheduling-concepts/index.rst +++ b/c-user/scheduling-concepts/index.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020 embedded brains GmbH & Co. KG .. index:: scheduling .. index:: task scheduling diff --git a/c-user/scheduling-concepts/introduction.rst b/c-user/scheduling-concepts/introduction.rst index 92da6de..527d103 100644 --- a/c-user/scheduling-concepts/introduction.rst +++ b/c-user/scheduling-concepts/introduction.rst @@ -1,42 +1,86 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +.. Copyright (C) 2013, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/rtems/scheduler/if/group + +.. _SchedulerManagerIntroduction: Introduction ============ +.. The following list was generated from: +.. spec:/rtems/scheduler/if/ident +.. spec:/rtems/scheduler/if/ident-by-processor +.. spec:/rtems/scheduler/if/ident-by-processor-set +.. spec:/rtems/scheduler/if/get-maximum-priority +.. spec:/rtems/scheduler/if/map-priority-to-posix +.. spec:/rtems/scheduler/if/map-priority-from-posix +.. spec:/rtems/scheduler/if/get-processor +.. spec:/rtems/scheduler/if/get-processor-maximum +.. spec:/rtems/scheduler/if/get-processor-set +.. spec:/rtems/scheduler/if/add-processor +.. spec:/rtems/scheduler/if/remove-processor + +The scheduling concepts relate to the allocation of processing time for tasks. + The concept of scheduling in real-time systems dictates the ability to provide -an immediate response to specific external events, particularly the necessity of -scheduling tasks to run within a specified time limit after the occurrence of -an event. For example, software embedded in life-support systems used to -monitor hospital patients must take instant action if a change in the patient's +an immediate response to specific external events, particularly the necessity +of scheduling tasks to run within a specified time limit after the occurrence +of an event. For example, software embedded in life-support systems used to +monitor hospital patients must take instant action if a change in the patient’s status is detected. The component of RTEMS responsible for providing this capability is -appropriately called the scheduler. The scheduler's sole purpose is to -allocate the all important resource of processor time to the various tasks -competing for attention. - -The directives provided by the scheduler manager are: +appropriately called the scheduler. The scheduler’s sole purpose is to allocate +the all important resource of processor time to the various tasks competing for +attention. The directives provided by the Scheduler Manager are: -- :ref:`rtems_scheduler_ident` +* :ref:`InterfaceRtemsSchedulerIdent` - Identifies a scheduler by the object + name. -- :ref:`rtems_scheduler_ident_by_processor` +* :ref:`InterfaceRtemsSchedulerIdentByProcessor` - Identifies a scheduler by + the processor index. -- :ref:`rtems_scheduler_ident_by_processor_set` +* :ref:`InterfaceRtemsSchedulerIdentByProcessorSet` - Identifies a scheduler by + the processor set. -- :ref:`rtems_scheduler_get_maximum_priority` +* :ref:`InterfaceRtemsSchedulerGetMaximumPriority` - Gets the maximum task + priority of the scheduler. -- :ref:`rtems_scheduler_map_priority_to_posix` +* :ref:`InterfaceRtemsSchedulerMapPriorityToPosix` - Maps a Classic API task + priority to the corresponding POSIX thread priority. -- :ref:`rtems_scheduler_map_priority_from_posix` +* :ref:`InterfaceRtemsSchedulerMapPriorityFromPosix` - Maps a POSIX thread + priority to the corresponding Classic API task priority. -- :ref:`rtems_scheduler_get_processor` +* :ref:`InterfaceRtemsSchedulerGetProcessor` - Returns the index of the current + processor. -- :ref:`rtems_scheduler_get_processor_maximum` +* :ref:`InterfaceRtemsSchedulerGetProcessorMaximum` - Returns the processor + maximum supported by the system. -- :ref:`rtems_scheduler_get_processor_set` +* :ref:`InterfaceRtemsSchedulerGetProcessorSet` - Gets the set of processors + owned by the scheduler. -- :ref:`rtems_scheduler_add_processor` +* :ref:`InterfaceRtemsSchedulerAddProcessor` - Adds the processor to the set of + processors owned by the scheduler. -- :ref:`rtems_scheduler_remove_processor` +* :ref:`InterfaceRtemsSchedulerRemoveProcessor` - Removes the processor from + the set of processors owned by the scheduler. diff --git a/c-user/scheduling-concepts/smp-schedulers.rst b/c-user/scheduling-concepts/smp-schedulers.rst index cfab04f..d6c1dc6 100644 --- a/c-user/scheduling-concepts/smp-schedulers.rst +++ b/c-user/scheduling-concepts/smp-schedulers.rst @@ -45,7 +45,7 @@ Deterministic Priority SMP Scheduler A fixed-priority scheduler which uses a table of chains with one chain per priority level for the ready tasks. The maximum priority level is configurable. By default, the maximum priority level is 255 (256 priority -levels). +levels), see :ref:`CONFIGURE_MAXIMUM_PRIORITY`. .. _SchedulerSMPPrioritySimple: @@ -64,6 +64,7 @@ Arbitrary Processor Affinity Priority SMP Scheduler A fixed-priority scheduler which uses a table of chains with one chain per priority level for the ready tasks. The maximum priority level is configurable. By default, the maximum priority level is 255 (256 priority -levels). This scheduler supports arbitrary task processor affinities. The -worst-case run-time complexity of some scheduler operations exceeds -:math:`O(n)` while :math:`n` is the count of ready tasks. +levels), see :ref:`CONFIGURE_MAXIMUM_PRIORITY`. This scheduler supports +arbitrary task processor affinities. The worst-case run-time complexity of +some scheduler operations exceeds :math:`O(n)` while :math:`n` is the count of +ready tasks. diff --git a/c-user/self_contained_objects.rst b/c-user/self_contained_objects.rst index 0be1423..2001ba3 100644 --- a/c-user/self_contained_objects.rst +++ b/c-user/self_contained_objects.rst @@ -1,7 +1,7 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 .. Copyright (C) 2014, 2017. -.. COMMENT: embedded brains GmbH. +.. COMMENT: embedded brains GmbH & Co. KG Self-Contained Objects ********************** @@ -132,6 +132,10 @@ copies of the object in calls to * :c:func:`rtems_recursive_mutex_lock`, +* :c:func:`rtems_mutex_try_lock`, + +* :c:func:`rtems_recursive_mutex_try_lock`, + * :c:func:`rtems_mutex_unlock`, * :c:func:`rtems_recursive_mutex_unlock`, @@ -262,6 +266,37 @@ NOTES: \clearpage +Try to lock the mutex +--------------------- + +CALLING SEQUENCE: + .. code-block:: c + + int rtems_mutex_try_lock( + rtems_mutex *mutex + ); + + int rtems_recursive_mutex_try_lock( + rtems_recursive_mutex *mutex + ); + +DESCRIPTION: + Tries to lock the ``mutex``. In case the mutex is not locked, it will be + locked and the function returns with a return value of ``0``. If the mutex + is already locked, the function will return with a value of ``EBUSY``. + +NOTES: + This function must be called from thread context with interrupts enabled. + + For recursively locking a mutex, please also see the notes for + :c:func:`rtems_mutex_lock` and :c:func:`rtems_recursive_mutex_lock`. + + Each mutex lock operation must have a corresponding unlock operation. + +.. raw:: latex + + \clearpage + Unlock the mutex ---------------- diff --git a/c-user/semaphore/directives.rst b/c-user/semaphore/directives.rst index 54f40a4..a0d12a6 100644 --- a/c-user/semaphore/directives.rst +++ b/c-user/semaphore/directives.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) .. This file is part of the RTEMS quality process and was automatically @@ -75,9 +75,9 @@ Creates a semaphore. the attribute set. ``id`` - This parameter is the pointer to an object identifier variable. When the - directive call is successful, the identifier of the created semaphore will - be stored in this variable. + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the identifier of the created semaphore + will be stored in this object. .. rubric:: DESCRIPTION: @@ -278,9 +278,9 @@ Identifies a semaphore by the object name. This parameter is the node or node set to search for a matching object. ``id`` - This parameter is the pointer to an object identifier variable. When the - directive call is successful, the object identifier of an object with the - specified name will be stored in this variable. + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the object identifier of an object with + the specified name will be stored in this object. .. rubric:: DESCRIPTION: @@ -466,9 +466,9 @@ Obtains the semaphore. This parameter is the option set. ``timeout`` - This parameter is the timeout in clock ticks if the :c:macro:`RTEMS_WAIT` - option is set. Use :c:macro:`RTEMS_NO_TIMEOUT` to wait potentially - forever. + This parameter is the timeout in :term:`clock ticks <clock tick>` if the + :c:macro:`RTEMS_WAIT` option is set. Use :c:macro:`RTEMS_NO_TIMEOUT` to + wait potentially forever. .. rubric:: DESCRIPTION: @@ -525,9 +525,17 @@ scheduler. :c:macro:`RTEMS_INVALID_ID` There was no semaphore associated with the identifier specified by ``id``. +:c:macro:`RTEMS_NOT_DEFINED` + The semaphore uses a priority ceiling and there was no priority ceiling + defined for the :term:`home scheduler` of the calling task. + :c:macro:`RTEMS_UNSATISFIED` The semaphore could not be obtained immediately. +:c:macro:`RTEMS_INVALID_PRIORITY` + The semaphore uses a priority ceiling and the calling task had a current + priority less than the priority ceiling. + :c:macro:`RTEMS_INCORRECT_STATE` Acquiring of the local, binary semaphore by the calling task would have cased a deadlock. @@ -686,7 +694,8 @@ The following constraints apply to this directive: * The directive may be called from within task context. -* The directive may unblock another task which may preempt the calling task. +* The directive may unblock a task. This may cause the calling task to be + preempted. * When the directive operates on a remote object, the directive sends a message to the remote node and waits for a reply. This will preempt the calling @@ -805,7 +814,8 @@ The following constraints apply to this directive: * The directive may be called from within task context. -* The directive may unblock another task which may preempt the calling task. +* The directive may unblock a task. This may cause the calling task to be + preempted. * When the directive operates on a remote object, the directive sends a message to the remote node and waits for a reply. This will preempt the calling @@ -852,9 +862,10 @@ Sets the priority by scheduler for the semaphore. scheduler. ``old_priority`` - This parameter is the pointer to a task priority variable. When the - directive call is successful, the old priority of the semaphore - corresponding to the specified scheduler will be stored in this variable. + This parameter is the pointer to an :ref:`InterfaceRtemsTaskPriority` + object. When the directive call is successful, the old priority of the + semaphore corresponding to the specified scheduler will be stored in this + object. .. rubric:: DESCRIPTION: @@ -1009,5 +1020,5 @@ The following constraints apply to this directive: * The directive may be called from within task context. -* The directive may change the priority of another task which may preempt the - calling task. +* The directive may change the priority of a task. This may cause the calling + task to be preempted. diff --git a/c-user/semaphore/index.rst b/c-user/semaphore/index.rst index c281104..369bccd 100644 --- a/c-user/semaphore/index.rst +++ b/c-user/semaphore/index.rst @@ -1,13 +1,13 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020 embedded brains GmbH & Co. KG .. index:: semaphores .. index:: binary semaphores .. index:: counting semaphores .. index:: mutual exclusion -.. _RTEMSAPIClassicSemaphore: +.. _RTEMSAPIClassicSem: Semaphore Manager ***************** diff --git a/c-user/semaphore/introduction.rst b/c-user/semaphore/introduction.rst index 9c36834..ded0c3e 100644 --- a/c-user/semaphore/introduction.rst +++ b/c-user/semaphore/introduction.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) .. This file is part of the RTEMS quality process and was automatically diff --git a/c-user/signal/directives.rst b/c-user/signal/directives.rst index b883b0a..9345132 100644 --- a/c-user/signal/directives.rst +++ b/c-user/signal/directives.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) .. This file is part of the RTEMS quality process and was automatically diff --git a/c-user/signal/index.rst b/c-user/signal/index.rst index e418491..d52e098 100644 --- a/c-user/signal/index.rst +++ b/c-user/signal/index.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020 embedded brains GmbH & Co. KG .. index:: signals diff --git a/c-user/signal/introduction.rst b/c-user/signal/introduction.rst index 449022a..f6e0ded 100644 --- a/c-user/signal/introduction.rst +++ b/c-user/signal/introduction.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) .. This file is part of the RTEMS quality process and was automatically diff --git a/c-user/symmetric_multiprocessing_services.rst b/c-user/symmetric_multiprocessing_services.rst index acfee56..aeecece 100644 --- a/c-user/symmetric_multiprocessing_services.rst +++ b/c-user/symmetric_multiprocessing_services.rst @@ -2,7 +2,7 @@ .. Copyright (C) 2014. .. COMMENT: On-Line Applications Research Corporation (OAR). -.. Copyright (C) 2017 embedded brains GmbH. +.. Copyright (C) 2017 embedded brains GmbH & Co. KG .. index:: Symmetric Multiprocessing .. index:: SMP @@ -13,10 +13,19 @@ Symmetric Multiprocessing (SMP) Introduction ============ -The Symmetric Multiprocessing (SMP) support of the RTEMS is available on +RTEMS Symmetric Multiprocessing (SMP) support is available on a subset +of target architectures supported by RTEMS. Further on some target +architectures, it is only available on a subset of BSPs. The user is +advised to check the BSP specific documentation and RTEMS source code +to verify the status of SMP support for a specific BSP. The following +architectures have support for SMP: + +- AArch64, - ARMv7-A, +- i386, + - PowerPC, - RISC-V, and @@ -25,8 +34,8 @@ The Symmetric Multiprocessing (SMP) support of the RTEMS is available on .. warning:: - The SMP support is only available if RTEMS was built with the - ``--enable-smp`` build configuration option. + SMP support is only available if RTEMS was built with the + SMP build configuration option enabled. RTEMS is supposed to be a real-time operating system. What does this mean in the context of SMP? The RTEMS interpretation of real-time on SMP is the @@ -580,10 +589,10 @@ Profiling --------- To identify the bottlenecks in the system, support for profiling of low-level -synchronization is optionally available. The profiling support is a BSP build -time configuration option (``--enable-profiling``) and is implemented with an -acceptable overhead, even for production systems. A low-overhead counter for -short time intervals must be provided by the hardware. +synchronization is optionally available. The profiling support is +an RTEMS build time configuration option and is implemented with an +acceptable overhead, even for production systems. A low-overhead counter +for short time intervals must be provided by the hardware. Profiling reports are generated in XML for most test programs of the RTEMS testsuite (more than 500 test programs). This gives a good sample set for diff --git a/c-user/task/background.rst b/c-user/task/background.rst index a55f743..c7645b1 100644 --- a/c-user/task/background.rst +++ b/c-user/task/background.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020, 2022 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) Background @@ -127,13 +127,19 @@ scheduling of a task is based on its current state and priority. .. index:: priority, task .. index:: rtems_task_priority +.. _TaskPriority: + Task Priority ------------- -A task's priority determines its importance in relation to the other tasks -executing on the same processor. RTEMS supports 255 levels of priority ranging -from 1 to 255. The data type ``rtems_task_priority`` is used to store task -priorities. +A task's :term:`priority` determines its importance in relation to the other +tasks executing on the processor set owned by a :term:`scheduler`. Normally, +RTEMS supports 256 levels of priority ranging from 0 to 255. The priority +level 0 represents a special priority reserved for the operating system. The +data type :c:type:`rtems_task_priority` is used to store task priorities. The +maximum priority level depends on the configured scheduler, see +:ref:`CONFIGURE_MAXIMUM_PRIORITY`, :ref:`ConfigurationSchedulersClustered`, and +:ref:`RTEMSAPIClassicScheduler`. Tasks of numerically smaller priority values are more important tasks than tasks of numerically larger priority values. For example, a task at priority @@ -227,6 +233,58 @@ the task will execute at interrupt level n. The set of default modes may be selected by specifying the ``RTEMS_DEFAULT_MODES`` constant. +.. index:: task life states + +Task Life States +---------------- + +Independent of the task state with respect to the scheduler, the task life is +determined by several orthogonal states: + +* *protected* or *unprotected* + +* *deferred life changes* or *no deferred life changes* + +* *restarting* or *not restarting* + +* *terminating* or *not terminating* + +* *detached* or *not detached* + +While the task life is *protected*, asynchronous task restart and termination +requests are blocked. A task may still restart or terminate itself. All tasks +are created with an unprotected task life. The task life protection is used by +the system to prevent system resources being affected by asynchronous task +restart and termination requests. The task life protection can be enabled +(``PTHREAD_CANCEL_DISABLE``) or disabled (``PTHREAD_CANCEL_ENABLE``) for the +calling task through the ``pthread_setcancelstate()`` directive. + +While *deferred life changes* are enabled, asynchronous task restart and +termination requests are delayed until the task performs a life change itself +or calls ``pthread_testcancel()``. Cancellation points are not implemented in +RTEMS. Deferred task life changes can be enabled (``PTHREAD_CANCEL_DEFERRED``) +or disabled (``PTHREAD_CANCEL_ASYNCHRONOUS``) for the calling task through the +``pthread_setcanceltype()`` directive. Classic API tasks are created with +deferred life changes disabled. POSIX threads are created with deferred life +changes enabled. + +A task is made *restarting* by issuing a task restart request through the +:ref:`InterfaceRtemsTaskRestart` directive. + +A task is made *terminating* by issuing a task termination request through the +:ref:`InterfaceRtemsTaskExit`, :ref:`InterfaceRtemsTaskDelete`, +``pthread_exit()``, and ``pthread_cancel()`` directives. + +When a *detached* task terminates, the termination procedure completes without +the need for another task to join with the terminated task. Classic API tasks +are created as not detached. The detached state of created POSIX threads is +determined by the thread attributes. They are created as not detached by +default. The calling task is made detached through the ``pthread_detach()`` +directive. The :ref:`InterfaceRtemsTaskExit` directive and self deletion +though :ref:`InterfaceRtemsTaskDelete` directive make the calling task +detached. In contrast, the ``pthread_exit()`` directive does not change the +detached state of the calling task. + .. index:: task arguments .. index:: task prototype diff --git a/c-user/task/deprecated-directives.rst b/c-user/task/deprecated-directives.rst index 107c5e0..949d499 100644 --- a/c-user/task/deprecated-directives.rst +++ b/c-user/task/deprecated-directives.rst @@ -9,7 +9,7 @@ Deprecated Directives \clearpage -.. index:: rtems_iterate_over_all_threads +.. index:: rtems_iterate_over_all_threads() .. _rtems_iterate_over_all_threads: diff --git a/c-user/task/directives.rst b/c-user/task/directives.rst index b5574e9..d976905 100644 --- a/c-user/task/directives.rst +++ b/c-user/task/directives.rst @@ -1,1454 +1,2014 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2023 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. _TaskManagerDirectives: Directives ========== -This section details the task manager's directives. A subsection is dedicated -to each of this manager's directives and describes the calling sequence, -related constants, usage, and status codes. +This section details the directives of the Task Manager. A subsection is +dedicated to each of this manager's directives and lists the calling sequence, +parameters, description, return values, and notes of the directive. + +.. Generated from spec:/rtems/task/if/create .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_task_create() .. index:: create a task -.. index:: rtems_task_create - -.. _rtems_task_create: - -TASK_CREATE - Create a task ---------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_create( - rtems_name name, - rtems_task_priority initial_priority, - size_t stack_size, - rtems_mode initial_modes, - rtems_attribute attribute_set, - rtems_id *id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - task created successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``id`` is NULL - * - ``RTEMS_INVALID_NAME`` - - invalid task name - * - ``RTEMS_INVALID_PRIORITY`` - - invalid task priority - * - ``RTEMS_TOO_MANY`` - - too many tasks created - * - ``RTEMS_UNSATISFIED`` - - not enough memory for stack/FP context - * - ``RTEMS_UNSATISFIED`` - - non-preemption mode not supported on SMP system - * - ``RTEMS_UNSATISFIED`` - - interrupt level mode not supported on SMP system - * - ``RTEMS_TOO_MANY`` - - too many global objects - -DESCRIPTION: - This directive creates a task which resides on the local node. It - allocates and initializes a TCB, a stack, and an optional floating point - context area. The mode parameter contains values which sets the task's - initial execution mode. The ``RTEMS_FLOATING_POINT`` attribute should be - specified if the created task is to use a numeric coprocessor. For - performance reasons, it is recommended that tasks not using the numeric - coprocessor should specify the ``RTEMS_NO_FLOATING_POINT`` attribute. If - the ``RTEMS_GLOBAL`` attribute is specified, the task can be accessed from - remote nodes. The task id, returned in id, is used in other task related - directives to access the task. When created, a task is placed in the - dormant state and can only be made ready to execute using the directive - ``rtems_task_start``. - -NOTES: - This directive may cause the calling task to be preempted. - - The scheduler of the new task is the scheduler of the executing task at - some point during the task creation. The specified task priority must be - valid for the selected scheduler. - - The task processor affinity is initialized to the set of online processors. - - If the requested stack size is less than the configured minimum stack size, - then RTEMS will use the configured minimum as the stack size for this task. - In addition to being able to specify the task stack size as a integer, - there are two constants which may be specified: - - ``RTEMS_MINIMUM_STACK_SIZE`` - The minimum stack size *RECOMMENDED* for use on this processor. This - value is selected by the RTEMS developers conservatively to minimize the - risk of blown stacks for most user applications. Using this constant - when specifying the task stack size, indicates that the stack size will - be at least ``RTEMS_MINIMUM_STACK_SIZE`` bytes in size. If the user - configured minimum stack size is larger than the recommended minimum, - then it will be used. - - ``RTEMS_CONFIGURED_MINIMUM_STACK_SIZE`` - Indicates this task is to be created with a stack size of the minimum - stack size that was configured by the application. If not explicitly - configured by the application, the default configured minimum stack size - is the processor dependent value ``RTEMS_MINIMUM_STACK_SIZE``. Since - this uses the configured minimum stack size value, you may get a stack - size that is smaller or larger than the recommended minimum. This can be - used to provide large stacks for all tasks on complex applications or - small stacks on applications that are trying to conserve memory. - - Application developers should consider the stack usage of the device - drivers when calculating the stack size required for tasks which utilize - the driver. - - The following task attribute constants are defined by RTEMS: - - .. list-table:: - :class: rtems-table - - * - ``RTEMS_NO_FLOATING_POINT`` - - does not use coprocessor (default) - * - ``RTEMS_FLOATING_POINT`` - - uses numeric coprocessor - * - ``RTEMS_LOCAL`` - - local task (default) - * - ``RTEMS_GLOBAL`` - - global task - - The following task mode constants are defined by RTEMS: - - .. list-table:: - :class: rtems-table - - * - ``RTEMS_PREEMPT`` - - enable preemption (default) - * - ``RTEMS_NO_PREEMPT`` - - disable preemption - * - ``RTEMS_NO_TIMESLICE`` - - disable timeslicing (default) - * - ``RTEMS_TIMESLICE`` - - enable timeslicing - * - ``RTEMS_ASR`` - - enable ASR processing (default) - * - ``RTEMS_NO_ASR`` - - disable ASR processing - * - ``RTEMS_INTERRUPT_LEVEL(0)`` - - enable all interrupts (default) - * - ``RTEMS_INTERRUPT_LEVEL(n)`` - - execute at interrupt level ``n`` - - The interrupt level portion of the task execution mode supports a maximum - of 256 interrupt levels. These levels are mapped onto the interrupt - levels actually supported by the target processor in a processor dependent - fashion. - - Tasks should not be made global unless remote tasks must interact with - them. This avoids the system overhead incurred by the creation of a - global task. When a global task is created, the task's name and id must - be transmitted to every node in the system for insertion in the local copy - of the global object table. - - The total number of global objects, including tasks, is limited by the - maximum_global_objects field in the Configuration Table. + +.. _InterfaceRtemsTaskCreate: + +rtems_task_create() +------------------- + +Creates a task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_create( + rtems_name name, + rtems_task_priority initial_priority, + size_t stack_size, + rtems_mode initial_modes, + rtems_attribute attribute_set, + rtems_id *id + ); + +.. rubric:: PARAMETERS: + +``name`` + This parameter is the object name of the task. + +``initial_priority`` + This parameter is the initial task priority. + +``stack_size`` + This parameter is the task stack size in bytes. + +``initial_modes`` + This parameter is the initial mode set of the task. + +``attribute_set`` + This parameter is the attribute set of the task. + +``id`` + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the identifier of the created task will + be stored in this object. + +.. rubric:: DESCRIPTION: + +This directive creates a task which resides on the local node. The task has +the user-defined object name specified in ``name``. The assigned object +identifier is returned in ``id``. This identifier is used to access the task +with other task related directives. + +The **initial priority** of the task is specified in ``initial_priority``. The +:term:`home scheduler` of the created task is the home scheduler of the calling +task at some time point during the task creation. The initial task priority +specified in ``initial_priority`` shall be valid for this scheduler. + +The **stack size** of the task is specified in ``stack_size``. If the +requested stack size is less than the configured minimum stack size, then RTEMS +will use the configured minimum as the stack size for this task. The +configured minimum stack size is defined by the +:ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE` application configuration option. In +addition to being able to specify the task stack size as a integer, there are +two constants which may be specified: + +* The :c:macro:`RTEMS_MINIMUM_STACK_SIZE` constant can be specified to use the + **recommended minimum stack size** for the target processor. This value is + selected by the RTEMS maintainers conservatively to minimize the risk of + blown stacks for most user applications. Using this constant when specifying + the task stack size, indicates that the stack size will be at least + :c:macro:`RTEMS_MINIMUM_STACK_SIZE` bytes in size. If the user configured + minimum stack size is larger than the recommended minimum, then it will be + used. + +* The :c:macro:`RTEMS_CONFIGURED_MINIMUM_STACK_SIZE` constant can be specified + to use the minimum stack size that was configured by the application. If not + explicitly configured by the application, the default configured minimum + stack size is the target processor dependent value + :c:macro:`RTEMS_MINIMUM_STACK_SIZE`. Since this uses the configured minimum + stack size value, you may get a stack size that is smaller or larger than the + recommended minimum. This can be used to provide large stacks for all tasks + on complex applications or small stacks on applications that are trying to + conserve memory. + +The **initial mode set** specified in ``initial_modes`` is built through a +*bitwise or* of the mode constants described below. Not all combinations of +modes are allowed. Some modes are mutually exclusive. If mutually exclusive +modes are combined, the behaviour is undefined. Default task modes can be +selected by using the :c:macro:`RTEMS_DEFAULT_MODES` constant. The task mode +set defines + +* the preemption mode of the task: :c:macro:`RTEMS_PREEMPT` (default) or + :c:macro:`RTEMS_NO_PREEMPT`, + +* the timeslicing mode of the task: :c:macro:`RTEMS_TIMESLICE` or + :c:macro:`RTEMS_NO_TIMESLICE` (default), + +* the :term:`ASR` processing mode of the task: :c:macro:`RTEMS_ASR` (default) + or :c:macro:`RTEMS_NO_ASR`, + +* the interrupt level of the task: :c:func:`RTEMS_INTERRUPT_LEVEL` with a + default of ``RTEMS_INTERRUPT_LEVEL( 0 )`` which is associated with enabled + interrupts. + +The **initial preemption mode** of the task is enabled or disabled. + +* An **enabled preemption** is the default and can be emphasized through the + use of the :c:macro:`RTEMS_PREEMPT` mode constant. + +* A **disabled preemption** is set by the :c:macro:`RTEMS_NO_PREEMPT` mode + constant. + +The **initial timeslicing mode** of the task is enabled or disabled. + +* A **disabled timeslicing** is the default and can be emphasized through the + use of the :c:macro:`RTEMS_NO_TIMESLICE` mode constant. + +* An **enabled timeslicing** is set by the :c:macro:`RTEMS_TIMESLICE` mode + constant. + +The **initial ASR processing mode** of the task is enabled or disabled. + +* An **enabled ASR processing** is the default and can be emphasized through + the use of the :c:macro:`RTEMS_ASR` mode constant. + +* A **disabled ASR processing** is set by the :c:macro:`RTEMS_NO_ASR` mode + constant. + +The **initial interrupt level mode** of the task is defined by +:c:func:`RTEMS_INTERRUPT_LEVEL`. + +* Task execution with **interrupts enabled** the default and can be emphasized + through the use of the :c:func:`RTEMS_INTERRUPT_LEVEL` mode macro with a + value of zero (0) for the parameter. An interrupt level of zero is + associated with enabled interrupts on all target processors. + +* Task execution at a **non-zero interrupt level** can be specified by the + :c:func:`RTEMS_INTERRUPT_LEVEL` mode macro with a non-zero value for the + parameter. The interrupt level portion of the task mode supports a maximum + of 256 interrupt levels. These levels are mapped onto the interrupt levels + actually supported by the target processor in a processor dependent fashion. + +The **attribute set** specified in ``attribute_set`` is built through a +*bitwise or* of the attribute constants described below. Not all combinations +of attributes are allowed. Some attributes are mutually exclusive. If +mutually exclusive attributes are combined, the behaviour is undefined. +Attributes not mentioned below are not evaluated by this directive and have no +effect. Default attributes can be selected by using the +:c:macro:`RTEMS_DEFAULT_ATTRIBUTES` constant. The attribute set defines + +* the scope of the task: :c:macro:`RTEMS_LOCAL` (default) or + :c:macro:`RTEMS_GLOBAL` and + +* the floating-point unit use of the task: :c:macro:`RTEMS_FLOATING_POINT` or + :c:macro:`RTEMS_NO_FLOATING_POINT` (default). + +The task has a local or global **scope** in a multiprocessing network (this +attribute does not refer to SMP systems). The scope is selected by the +mutually exclusive :c:macro:`RTEMS_LOCAL` and :c:macro:`RTEMS_GLOBAL` +attributes. + +* A **local scope** is the default and can be emphasized through the use of the + :c:macro:`RTEMS_LOCAL` attribute. A local task can be only used by the node + which created it. + +* A **global scope** is established if the :c:macro:`RTEMS_GLOBAL` attribute is + set. Setting the global attribute in a single node system has no effect.the + +The **use of the floating-point unit** is selected by the mutually exclusive +:c:macro:`RTEMS_FLOATING_POINT` and :c:macro:`RTEMS_NO_FLOATING_POINT` +attributes. On some target processors, the use of the floating-point unit can +be enabled or disabled for each task. Other target processors may have no +hardware floating-point unit or enable the use of the floating-point unit for +all tasks. Consult the *RTEMS CPU Architecture Supplement* for the details. + +* A **disabled floating-point unit** is the default and can be emphasized + through use of the :c:macro:`RTEMS_NO_FLOATING_POINT` attribute. For + performance reasons, it is recommended that tasks not using the + floating-point unit should specify this attribute. + +* An **enabled floating-point unit** is selected by the + :c:macro:`RTEMS_FLOATING_POINT` attribute. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_NAME` + The ``name`` parameter was invalid. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``id`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_PRIORITY` + The ``initial_priority`` was invalid. + +:c:macro:`RTEMS_TOO_MANY` + There was no inactive object available to create a task. The number of + tasks available to the application is configured through the + :ref:`CONFIGURE_MAXIMUM_TASKS` application configuration option. + +:c:macro:`RTEMS_TOO_MANY` + In multiprocessing configurations, there was no inactive global object + available to create a global task. The number of global objects available + to the application is configured through the + :ref:`CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS` application configuration + option. + +:c:macro:`RTEMS_UNSATISFIED` + There was not enough memory to allocate the task storage area. The task + storage area contains the task stack, the thread-local storage, and the + floating point context. + +:c:macro:`RTEMS_UNSATISFIED` + One of the task create extensions failed to create the task. + +:c:macro:`RTEMS_UNSATISFIED` + In SMP configurations, the non-preemption mode was not supported. + +:c:macro:`RTEMS_UNSATISFIED` + In SMP configurations, the interrupt level mode was not supported. + +.. rubric:: NOTES: + +The task processor affinity is initialized to the set of online processors. + +When created, a task is placed in the dormant state and can only be made ready +to execute using the directive :ref:`InterfaceRtemsTaskStart`. + +Application developers should consider the stack usage of the device drivers +when calculating the stack size required for tasks which utilize the driver. +The task stack size shall account for an target processor dependent interrupt +stack frame which may be placed on the stack of the interrupted task while +servicing an interrupt. The stack checker may be used to monitor the stack +usage, see :ref:`CONFIGURE_STACK_CHECKER_ENABLED`. + +For control and maintenance of the task, RTEMS allocates a :term:`TCB` from the +local TCB free pool and initializes it. + +The TCB for a global task is allocated on the local node. Task should not be +made global unless remote tasks must interact with the task. This is to avoid +the system overhead incurred by the creation of a global task. When a global +task is created, the task's name and identifier must be transmitted to every +node in the system for insertion in the local copy of the global object table. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. + +* When the directive operates on a global object, the directive sends a message + to remote nodes. This may preempt the calling task. + +* The number of tasks available to the application is configured through the + :ref:`CONFIGURE_MAXIMUM_TASKS` application configuration option. + +* Where the object class corresponding to the directive is configured to use + unlimited objects, the directive may allocate memory from the RTEMS + Workspace. + +* The number of global objects available to the application is configured + through the :ref:`CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS` application + configuration option. + +.. Generated from spec:/rtems/task/if/construct + +.. raw:: latex + + \clearpage + +.. index:: rtems_task_construct() + +.. _InterfaceRtemsTaskConstruct: + +rtems_task_construct() +---------------------- + +Constructs a task from the specified task configuration. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_construct( + const rtems_task_config *config, + rtems_id *id + ); + +.. rubric:: PARAMETERS: + +``config`` + This parameter is the pointer to an :ref:`InterfaceRtemsTaskConfig` object. + It configures the task. + +``id`` + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the identifier of the constructed task + will be stored in this object. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``config`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_NAME` + The task name was invalid. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``id`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_PRIORITY` + The initial task priority was invalid. + +:c:macro:`RTEMS_INVALID_SIZE` + The thread-local storage size is greater than the maximum thread-local + storage size specified in the task configuration. The thread-local storage + size is determined by the thread-local variables used by the application + and :ref:`CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE`. + +:c:macro:`RTEMS_INVALID_SIZE` + The task storage area was too small to provide a task stack of the + configured minimum size, see :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. The + task storage area contains the task stack, the thread-local storage, and + the floating-point context on architectures with a separate floating-point + context. + +:c:macro:`RTEMS_TOO_MANY` + There was no inactive task object available to construct a task. + +:c:macro:`RTEMS_TOO_MANY` + In multiprocessing configurations, there was no inactive global object + available to construct a global task. + +:c:macro:`RTEMS_UNSATISFIED` + One of the task create extensions failed during the task construction. + +:c:macro:`RTEMS_UNSATISFIED` + In SMP configurations, the non-preemption mode was not supported. + +:c:macro:`RTEMS_UNSATISFIED` + In SMP configurations, the interrupt level mode was not supported. + +.. rubric:: NOTES: + +In contrast to tasks created by :ref:`InterfaceRtemsTaskCreate`, the tasks +constructed by this directive use a user-provided task storage area. The task +storage area contains the task stack, the thread-local storage, and the +floating-point context on architectures with a separate floating-point context. + +This directive is intended for applications which do not want to use the RTEMS +Workspace and instead statically allocate all operating system resources. It +is not recommended to use :ref:`InterfaceRtemsTaskCreate` and +:ref:`InterfaceRtemsTaskConstruct` together in an application. It is also not +recommended to use :ref:`InterfaceRtemsTaskConstruct` for drivers or general +purpose libraries. The reason for these recommendations is that the task +configuration needs settings which can be only given with a through knowledge +of the application resources. + +An application based solely on static allocation can avoid any runtime memory +allocators. This can simplify the application architecture as well as any +analysis that may be required. + +The stack space estimate done by ``<rtems/confdefs.h>`` assumes that all tasks +are created by :ref:`InterfaceRtemsTaskCreate`. The estimate can be adjusted +to take user-provided task storage areas into account through the +:ref:`CONFIGURE_MINIMUM_TASKS_WITH_USER_PROVIDED_STORAGE` application +configuration option. + +The :ref:`CONFIGURE_MAXIMUM_TASKS` should include tasks constructed by +:ref:`InterfaceRtemsTaskConstruct`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. + +* When the directive operates on a global object, the directive sends a message + to remote nodes. This may preempt the calling task. + +* The number of tasks available to the application is configured through the + :ref:`CONFIGURE_MAXIMUM_TASKS` application configuration option. + +* Where the object class corresponding to the directive is configured to use + unlimited objects, the directive may allocate memory from the RTEMS + Workspace. + +* The number of global objects available to the application is configured + through the :ref:`CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS` application + configuration option. + +.. Generated from spec:/rtems/task/if/ident .. raw:: latex - \clearpage + \clearpage + +.. index:: rtems_task_ident() + +.. _InterfaceRtemsTaskIdent: + +rtems_task_ident() +------------------ + +Identifies a task by the object name. + +.. rubric:: CALLING SEQUENCE: -.. index:: get ID of a task -.. index:: rtems_task_ident +.. code-block:: c -.. _rtems_task_ident: + rtems_status_code rtems_task_ident( + rtems_name name, + uint32_t node, + rtems_id *id + ); -TASK_IDENT - Get ID of a task ------------------------------ +.. rubric:: PARAMETERS: -CALLING SEQUENCE: - .. code-block:: c +``name`` + This parameter is the object name to look up. - rtems_status_code rtems_task_ident( - rtems_name name, - uint32_t node, - rtems_id *id - ); +``node`` + This parameter is the node or node set to search for a matching object. -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +``id`` + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the object identifier of an object with + the specified name will be stored in this object. - * - ``RTEMS_SUCCESSFUL`` - - task identified successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``id`` is NULL - * - ``RTEMS_INVALID_NAME`` - - invalid task name - * - ``RTEMS_INVALID_NODE`` - - invalid node id +.. rubric:: 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 a task identifier associated with the task name +specified in ``name``. -NOTES: - This directive will not cause the running task to be preempted. +A task may obtain its own identifier by specifying :c:macro:`RTEMS_WHO_AM_I` +for the name. - 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. +The node to search is specified in ``node``. It shall be - 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. +* a valid node number, - This directive does not generate activity on remote nodes. It accesses - only the local copy of the global object table. +* the constant :c:macro:`RTEMS_SEARCH_ALL_NODES` to search in all nodes, + +* the constant :c:macro:`RTEMS_SEARCH_LOCAL_NODE` to search in the local node + only, or + +* the constant :c:macro:`RTEMS_SEARCH_OTHER_NODES` to search in all nodes + except the local node. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``id`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_NAME` + There was no object with the specified name on the specified nodes. + +:c:macro:`RTEMS_INVALID_NODE` + In multiprocessing configurations, the specified node was invalid. + +.. rubric:: NOTES: + +If the task name is not unique, then the task identifier will match the first +task with that name in the search order. However, this task identifier is not +guaranteed to correspond to the desired task. + +The objects are searched from lowest to the highest index. If ``node`` is +:c:macro:`RTEMS_SEARCH_ALL_NODES`, all nodes are searched with the local node +being searched first. All other nodes are searched from lowest to the highest +node number. + +If node is a valid node number which does not represent the local node, then +only the tasks exported by the designated node are searched. + +This directive does not generate activity on remote nodes. It accesses only +the local copy of the global object table. + +The task identifier is used with other task related directives to access the +task. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/task/if/self .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_task_self() .. index:: obtain ID of caller -.. index:: rtems_task_self -.. _rtems_task_self: +.. _InterfaceRtemsTaskSelf: + +rtems_task_self() +----------------- + +Gets the task identifier of the calling task. + +.. rubric:: CALLING SEQUENCE: -TASK_SELF - Obtain ID of caller -------------------------------- +.. code-block:: c -CALLING SEQUENCE: - .. code-block:: c + rtems_id rtems_task_self( void ); - rtems_id rtems_task_self(void); +.. rubric:: DESCRIPTION: -DIRECTIVE STATUS CODES: - Returns the object Id of the calling task. +This directive returns the task identifier of the calling task. -DESCRIPTION: - This directive returns the Id of the calling task. +.. rubric:: RETURN VALUES: -NOTES: - If called from an interrupt service routine, this directive will return the - Id of the interrupted task. +Returns the task identifier of the calling task. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/task/if/start .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_task_start() .. index:: starting a task -.. index:: rtems_task_start -.. _rtems_task_start: +.. _InterfaceRtemsTaskStart: -TASK_START - Start a task -------------------------- +rtems_task_start() +------------------ -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. +Starts the task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_start( + rtems_id id, + rtems_task_entry entry_point, + rtems_task_argument argument + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF` + may be used to specify the calling task. + +``entry_point`` + This parameter is the task entry point. + +``argument`` + This parameter is the task entry point argument. + +.. rubric:: DESCRIPTION: + +This directive readies the task, specified by ``id``, for execution based on +the priority and execution mode specified when the task was created. The +:term:`task entry` point of the task is given in ``entry_point``. The task's +entry point argument is contained in ``argument``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``entry_point`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_INCORRECT_STATE` + The task was not in the dormant state. + +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT` + The task resided on a remote node. + +.. rubric:: NOTES: + +The type of the entry point argument is an unsigned integer type. However, the +integer type has the property that any valid pointer to ``void`` can be +converted to this type and then converted back to a pointer to ``void``. The +result will compare equal to the original pointer. The type can represent at +least 32 bits. Some applications use the entry point argument as an index into +a parameter table to get task-specific parameters. + +Any actions performed on a dormant task such as suspension or change of +priority are nullified when the task is initiated via the +:ref:`InterfaceRtemsTaskStart` directive. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may unblock a task. This may cause the calling task to be + preempted. + +.. Generated from spec:/rtems/task/if/restart .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_task_restart() .. index:: restarting a task -.. index:: rtems_task_restart - -.. _rtems_task_restart: - -TASK_RESTART - Restart a task ------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_restart( - rtems_id id, - rtems_task_argument argument - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - task restarted successfully - * - ``RTEMS_INVALID_ID`` - - task id invalid - * - ``RTEMS_INCORRECT_STATE`` - - task never started - * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - - cannot restart remote task - -DESCRIPTION: - This directive resets the task specified by id to begin execution at its - original starting address. The task's priority and execution mode are set - to the original creation values. If the task is currently blocked, RTEMS - automatically makes the task ready. A task can be restarted from any - state, except the dormant state. - - The task's starting argument is contained in argument. This argument can - be a single value or an index into an array of parameter blocks. The type - of this numeric argument is an unsigned integer type with the property that - any valid pointer to void can be converted to this type and then converted - back to a pointer to void. The result will compare equal to the original - pointer. This new argument may be used to distinguish between the initial - ``rtems_task_start`` of the task and any ensuing calls to - ``rtems_task_restart`` of the task. This can be beneficial in deleting a - task. Instead of deleting a task using the ``rtems_task_delete`` - directive, a task can delete another task by restarting that task, and - allowing that task to release resources back to RTEMS and then delete - itself. - -NOTES: - If id is ``RTEMS_SELF``, the calling task will be restarted and will not - return from this directive. - - The calling task will be preempted if its preemption mode is enabled and - the task being restarted has a higher priority. - - The task must reside on the local node, even if the task was created with - the ``RTEMS_GLOBAL`` option. + +.. _InterfaceRtemsTaskRestart: + +rtems_task_restart() +-------------------- + +Restarts the task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_restart( + rtems_id id, + rtems_task_argument argument + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF` + may be used to specify the calling task. + +``argument`` + This parameter is the task entry point argument. + +.. rubric:: DESCRIPTION: + +This directive resets the task specified by ``id`` to begin execution at its +original entry point. The task's priority and execution mode are set to the +original creation values. If the task is currently blocked, RTEMS +automatically makes the task ready. A task can be restarted from any state, +except the dormant state. The task's entry point argument is contained in +``argument``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_INCORRECT_STATE` + The task never started. + +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT` + The task resided on a remote node. + +.. rubric:: NOTES: + +The type of the entry point argument is an unsigned integer type. However, the +integer type has the property that any valid pointer to ``void`` can be +converted to this type and then converted back to a pointer to ``void``. The +result will compare equal to the original pointer. The type can represent at +least 32 bits. Some applications use the entry point argument as an index into +a parameter table to get task-specific parameters. + +A new entry point argument may be used to distinguish between the initial +:ref:`InterfaceRtemsTaskStart` of the task and any ensuing calls to +:ref:`InterfaceRtemsTaskRestart` of the task. This can be beneficial in +deleting a task. Instead of deleting a task using the +:ref:`InterfaceRtemsTaskDelete` directive, a task can delete another task by +restarting that task, and allowing that task to release resources back to RTEMS +and then delete itself. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may change the priority of a task. This may cause the calling + task to be preempted. + +* The directive may unblock a task. This may cause the calling task to be + preempted. + +.. Generated from spec:/rtems/task/if/delete .. raw:: latex - \clearpage + \clearpage -.. index:: deleting a task -.. index:: rtems_task_delete - -.. _rtems_task_delete: - -TASK_DELETE - Delete a task ---------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_delete( - rtems_id id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - task deleted successfully - * - ``RTEMS_INVALID_ID`` - - task id invalid - * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - - cannot restart remote task - -DESCRIPTION: - This directive deletes a task, either the calling task or another task, as - specified by id. RTEMS stops the execution of the task and reclaims the - stack memory, any allocated delay or timeout timers, the TCB, and, if the - task is ``RTEMS_FLOATING_POINT``, its floating point context area. RTEMS - does not reclaim the following resources: region segments, partition - buffers, semaphores, timers, or rate monotonic periods. - -NOTES: - A task is responsible for releasing its resources back to RTEMS before - deletion. To insure proper deallocation of resources, a task should not be - deleted unless it is unable to execute or does not hold any RTEMS - resources. If a task holds RTEMS resources, the task should be allowed to - deallocate its resources before deletion. A task can be directed to - release its resources and delete itself by restarting it with a special - argument or by sending it a message, an event, or a signal. - - Deletion of the current task (``RTEMS_SELF``) will force RTEMS to select - another task to execute. - - When a global task is deleted, the task id must be transmitted to every - node in the system for deletion from the local copy of the global object - table. - - The task must reside on the local node, even if the task was created with - the ``RTEMS_GLOBAL`` option. +.. index:: rtems_task_delete() +.. index:: delete a task + +.. _InterfaceRtemsTaskDelete: + +rtems_task_delete() +------------------- + +Deletes the task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_delete( rtems_id id ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF` + may be used to specify the calling task. + +.. rubric:: DESCRIPTION: + +This directive deletes the task, either the calling task or another task, as +specified by ``id``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_CALLED_FROM_ISR` + The directive was called from within interrupt context. + +:c:macro:`RTEMS_INCORRECT_STATE` + The task termination procedure was started, however, waiting for the + terminating task would have resulted in a deadlock. + +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT` + The task resided on a remote node. + +.. rubric:: NOTES: + +The task deletion is done in several steps. Firstly, the task is marked as +terminating. While the task life of the terminating task is protected, it +executes normally until it disables the task life protection or it deletes +itself. A terminating task will eventually stop its normal execution and start +its termination procedure. The procedure executes in the context of the +terminating task. The task termination procedure involves the destruction of +POSIX key values and running the task termination user extensions. Once +complete the execution of the task is stopped and task-specific resources are +reclaimed by the system, such as the stack memory, any allocated delay or +timeout timers, the :term:`TCB`, and, if the task is +:c:macro:`RTEMS_FLOATING_POINT`, its floating point context area. RTEMS +explicitly does not reclaim the following resources: region segments, partition +buffers, semaphores, timers, or rate monotonic periods. + +A task is responsible for releasing its resources back to RTEMS before +deletion. To insure proper deallocation of resources, a task should not be +deleted unless it is unable to execute or does not hold any RTEMS resources. If +a task holds RTEMS resources, the task should be allowed to deallocate its +resources before deletion. A task can be directed to release its resources and +delete itself by restarting it with a special argument or by sending it a +message, an event, or a signal. + +Deletion of the calling task (:c:macro:`RTEMS_SELF`) will force RTEMS to select +another task to execute. + +When a task deletes another task, the calling task waits until the task +termination procedure of the task being deleted has completed. The terminating +task inherits the :term:`eligible priorities <eligible priority>` of the +calling task. + +When a global task is deleted, the task identifier must be transmitted to every +node in the system for deletion from the local copy of the global object table. + +The task must reside on the local node, even if the task was created with the +:c:macro:`RTEMS_GLOBAL` attribute. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. + +* When the directive operates on a global object, the directive sends a message + to remote nodes. This may preempt the calling task. + +* The calling task does not have to be the task that created the object. Any + local task that knows the object identifier can delete the object. + +* Where the object class corresponding to the directive is configured to use + unlimited objects, the directive may free memory to the RTEMS Workspace. + +.. Generated from spec:/rtems/task/if/exit .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_task_exit() .. index:: deleting a task -.. index:: rtems_task_exit -.. _rtems_task_exit: +.. _InterfaceRtemsTaskExit: + +rtems_task_exit() +----------------- + +Deletes the calling task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_task_exit( void ); + +.. rubric:: DESCRIPTION: -TASK_EXIT - Delete the calling task ------------------------------------ +This directive deletes the calling task. -CALLING SEQUENCE: - .. code-block:: c +.. rubric:: NOTES: - void rtems_task_exit( void ) RTEMS_NO_RETURN; +The directive is an optimized variant of the following code sequences, see also +:ref:`InterfaceRtemsTaskDelete`: -DIRECTIVE STATUS CODES: - NONE - This function will not return to the caller. +.. code-block:: c -DESCRIPTION: - This directive deletes the calling task. + #include <pthread.h> + #include <rtems.h> -NOTES: - This directive must be called from a regular task context with enabled - interrupts, otherwise one of the fatal errors + void classic_delete_self( void ) + { + (void) rtems_task_delete( RTEMS_SELF ); + } - * :ref:`INTERNAL_ERROR_BAD_THREAD_DISPATCH_DISABLE_LEVEL <internal_errors>`, or - * :ref:`INTERNAL_ERROR_BAD_THREAD_DISPATCH_ENVIRONMENT <internal_errors>` + void posix_delete_self( void ) + { + (void) pthread_detach( pthread_self() ); + (void) pthread_exit( NULL); + } - will occur. +.. rubric:: CONSTRAINTS: - The ``rtems_task_exit()`` call is equivalent to the following code - sequence: +The following constraints apply to this directive: - .. code-block:: c +* The directive may be called from within task context. - pthread_detach(pthread_self()); - pthread_exit(NULL); +* The directive will not return to the caller. - See also :ref:`rtems_task_delete() <rtems_task_delete>`. +* While thread dispatching is disabled, if the directive performs a thread + dispatch, then the fatal error with the fatal source + :ref:`INTERNAL_ERROR_CORE <FatalErrorSources>` and the fatal code + :ref:`INTERNAL_ERROR_BAD_THREAD_DISPATCH_DISABLE_LEVEL <internal_errors>` + will occur. + +.. Generated from spec:/rtems/task/if/suspend .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_task_suspend() .. index:: suspending a task -.. index:: rtems_task_suspend -.. _rtems_task_suspend: +.. _InterfaceRtemsTaskSuspend: + +rtems_task_suspend() +-------------------- + +Suspends the task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_suspend( rtems_id id ); + +.. rubric:: PARAMETERS: -TASK_SUSPEND - Suspend a task ------------------------------ +``id`` + This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF` + may be used to specify the calling task. -CALLING SEQUENCE: - .. code-block:: c +.. rubric:: DESCRIPTION: - rtems_status_code rtems_task_suspend( - rtems_id id - ); +This directive suspends the task specified by ``id`` from further execution by +placing it in the suspended state. This state is additive to any other blocked +state that the task may already be in. The task will not execute again until +another task issues the :ref:`InterfaceRtemsTaskResume` directive for this task +and any blocked state has been removed. The :ref:`InterfaceRtemsTaskRestart` +directive will also remove the suspended state. -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +.. rubric:: RETURN VALUES: - * - ``RTEMS_SUCCESSFUL`` - - task suspended successfully - * - ``RTEMS_INVALID_ID`` - - task id invalid - * - ``RTEMS_ALREADY_SUSPENDED`` - - task already suspended +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. -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. +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``id``. -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. +:c:macro:`RTEMS_ALREADY_SUSPENDED` + The task was already suspended. - 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. +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT` + The task resided on a remote node. - If the task specified by id is already suspended, then the - ``RTEMS_ALREADY_SUSPENDED`` status code is returned. +.. rubric:: NOTES: + +The requesting task can suspend itself for example by specifying +:c:macro:`RTEMS_SELF` as ``id``. In this case, the task will be suspended and +a successful return code will be returned when the task is resumed. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* When the directive operates on a remote object, the directive sends a message + to the remote node and waits for a reply. This will preempt the calling + task. + +.. Generated from spec:/rtems/task/if/resume .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_task_resume() .. index:: resuming a task -.. index:: rtems_task_resume -.. _rtems_task_resume: +.. _InterfaceRtemsTaskResume: + +rtems_task_resume() +------------------- + +Resumes the task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_resume( rtems_id id ); + +.. rubric:: PARAMETERS: -TASK_RESUME - Resume a task ---------------------------- +``id`` + This parameter is the task identifier. -CALLING SEQUENCE: - .. code-block:: c +.. rubric:: DESCRIPTION: - rtems_status_code rtems_task_resume( - rtems_id id - ); +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. -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +.. rubric:: RETURN VALUES: - * - ``RTEMS_SUCCESSFUL`` - - task resumed successfully - * - ``RTEMS_INVALID_ID`` - - task id invalid - * - ``RTEMS_INCORRECT_STATE`` - - task not suspended +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. -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. +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``id``. -NOTES: - The running task may be preempted if its preemption mode is enabled and the - local task being resumed has a higher priority. +:c:macro:`RTEMS_INCORRECT_STATE` + The task was not suspended. - 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. +.. rubric:: CONSTRAINTS: - If the task specified by id is not suspended, then the - ``RTEMS_INCORRECT_STATE`` status code is returned. +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may unblock a task. This may cause the calling task to be + preempted. + +* When the directive operates on a remote object, the directive sends a message + to the remote node and waits for a reply. This will preempt the calling + task. + +.. Generated from spec:/rtems/task/if/is-suspended .. raw:: latex - \clearpage + \clearpage + +.. index:: rtems_task_is_suspended() + +.. _InterfaceRtemsTaskIsSuspended: + +rtems_task_is_suspended() +------------------------- + +Checks if the task is suspended. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_is_suspended( rtems_id id ); -.. index:: is task suspended -.. index:: rtems_task_is_suspended +.. rubric:: PARAMETERS: -.. _rtems_task_is_suspended: +``id`` + This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF` + may be used to specify the calling task. -TASK_IS_SUSPENDED - Determine if a task is Suspended ----------------------------------------------------- +.. rubric:: DESCRIPTION: -CALLING SEQUENCE: - .. code-block:: c +This directive returns a status code indicating whether or not the task +specified by ``id`` is currently suspended. - rtems_status_code rtems_task_is_suspended( - rtems_id id - ); +.. rubric:: RETURN VALUES: -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +:c:macro:`RTEMS_SUCCESSFUL` + The task was **not** suspended. - * - ``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 +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``id``. -DESCRIPTION: - This directive returns a status code indicating whether or not the - specified task is currently suspended. +:c:macro:`RTEMS_ALREADY_SUSPENDED` + The task was suspended. -NOTES: - This operation is not currently supported on remote tasks. +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT` + The task resided on a remote node. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/task/if/set-priority .. raw:: latex - \clearpage + \clearpage -.. index:: rtems_task_set_priority +.. index:: rtems_task_set_priority() .. index:: current task priority .. index:: set task priority .. index:: get task priority .. index:: obtain task priority -.. _rtems_task_set_priority: - -TASK_SET_PRIORITY - Set task priority -------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_set_priority( - rtems_id id, - rtems_task_priority new_priority, - rtems_task_priority *old_priority - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - task priority set successfully - * - ``RTEMS_INVALID_ID`` - - invalid task id - * - ``RTEMS_INVALID_ADDRESS`` - - invalid return argument pointer - * - ``RTEMS_INVALID_PRIORITY`` - - invalid task priority - -DESCRIPTION: - This directive manipulates the priority of the task specified by id. An id - of ``RTEMS_SELF`` is used to indicate the calling task. When new_priority - is not equal to ``RTEMS_CURRENT_PRIORITY``, the specified task's previous - priority is returned in old_priority. When new_priority is - ``RTEMS_CURRENT_PRIORITY``, the specified task's current priority is - returned in old_priority. Valid priorities range from a high of 1 to a low - of 255. - -NOTES: - The calling task may be preempted if its preemption mode is enabled and it - lowers its own priority or raises another task's priority. - - In case the new priority equals the current priority of the task, then - nothing happens. - - Setting the priority of a global task which does not reside on the local - node will generate a request to the remote node to change the priority of - the specified task. - - If the task specified by id is currently holding any binary semaphores - which use the priority inheritance algorithm, then the task's priority - cannot be lowered immediately. If the task's priority were lowered - immediately, then priority inversion results. The requested lowering of - the task's priority will occur when the task has released all priority - inheritance binary semaphores. The task's priority can be increased - regardless of the task's use of priority inheritance binary semaphores. +.. _InterfaceRtemsTaskSetPriority: + +rtems_task_set_priority() +------------------------- + +Sets the real priority or gets the current priority of the task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_set_priority( + rtems_id id, + rtems_task_priority new_priority, + rtems_task_priority *old_priority + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF` + may be used to specify the calling task. + +``new_priority`` + This parameter is the new real priority or + :c:macro:`RTEMS_CURRENT_PRIORITY` to get the current priority. + +``old_priority`` + This parameter is the pointer to an :ref:`InterfaceRtemsTaskPriority` + object. When the directive call is successful, the current or previous + priority of the task with respect to its :term:`home scheduler` will be + stored in this object. + +.. rubric:: DESCRIPTION: + +This directive manipulates the priority of the task specified by ``id``. When +``new_priority`` is not equal to :c:macro:`RTEMS_CURRENT_PRIORITY`, the +specified task's previous priority is returned in ``old_priority``. When +``new_priority`` is :c:macro:`RTEMS_CURRENT_PRIORITY`, the specified task's +current priority is returned in ``old_priority``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``old_priority`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_INVALID_PRIORITY` + The task priority specified in ``new_priority`` was invalid with respect to + the :term:`home scheduler` of the task. + +.. rubric:: NOTES: + +Valid priorities range from one to a maximum value which depends on the +configured scheduler. The lower the priority value the higher is the +importance of the task. + +If the task is currently holding any binary semaphores which use a locking +protocol, then the task's priority cannot be lowered immediately. If the +task's priority were lowered immediately, then this could violate properties of +the locking protocol and may result in priority inversion. The requested +lowering of the task's priority will occur when the task has released all +binary semaphores which make the task more important. The task's priority can +be increased regardless of the task's use of binary semaphores with locking +protocols. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may change the priority of a task. This may cause the calling + task to be preempted. + +* When the directive operates on a remote object, the directive sends a message + to the remote node and waits for a reply. This will preempt the calling + task. + +.. Generated from spec:/rtems/task/if/get-priority .. raw:: latex - \clearpage + \clearpage -.. index:: rtems_task_get_priority +.. index:: rtems_task_get_priority() .. index:: current task priority .. index:: get task priority .. index:: obtain task priority -.. _rtems_task_get_priority: - -TASK_GET_PRIORITY - Get task priority -------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_get_priority( - rtems_id task_id, - rtems_id scheduler_id, - rtems_task_priority *priority - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - Successful operation. - * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - - Directive is illegal on remote tasks. - * - ``RTEMS_INVALID_ADDRESS`` - - The priority parameter is NULL. - * - ``RTEMS_INVALID_ID`` - - Invalid task or scheduler identifier. - * - ``RTEMS_NOT_DEFINED`` - - The task has no priority within the specified scheduler instance. - This error is only possible in SMP configurations. - -DESCRIPTION: - This directive returns the current priority of the task specified by - :c:data:`task_id` with respect to the scheduler instance specified by - :c:data:`scheduler_id`. A task id of :c:macro:`RTEMS_SELF` is used to - indicate the calling task. - -NOTES: - The current priority reflects temporary priority adjustments due to locking - protocols, the rate-monotonic period objects on some schedulers and other - mechanisms. +.. _InterfaceRtemsTaskGetPriority: + +rtems_task_get_priority() +------------------------- + +Gets the current priority of the task with respect to the scheduler. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_get_priority( + rtems_id task_id, + rtems_id scheduler_id, + rtems_task_priority *priority + ); + +.. rubric:: PARAMETERS: + +``task_id`` + This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF` + may be used to specify the calling task. + +``scheduler_id`` + This parameter is the scheduler identifier. + +``priority`` + This parameter is the pointer to an :ref:`InterfaceRtemsTaskPriority` + object. When the directive call is successful, the current priority of the + task with respect to the specified scheduler will be stored in this object. + +.. rubric:: DESCRIPTION: + +This directive returns the current priority in ``priority`` of the task +specified by ``task_id`` with respect to the scheduler specified by +``scheduler_id``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``priority`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``task_id``. + +:c:macro:`RTEMS_INVALID_ID` + There was no scheduler associated with the identifier specified by + ``scheduler_id``. + +:c:macro:`RTEMS_NOT_DEFINED` + The task had no priority with respect to the scheduler. + +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT` + The task resided on a remote node. + +.. rubric:: NOTES: + +The current priority reflects temporary priority adjustments due to locking +protocols, the rate-monotonic period objects on some schedulers such as EDF, +and the POSIX sporadic server. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/task/if/mode .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_task_mode() .. index:: current task mode .. index:: set task mode .. index:: get task mode .. index:: set task preemption mode .. index:: get task preemption mode .. index:: obtain task mode -.. index:: rtems_task_mode - -.. _rtems_task_mode: - -TASK_MODE - Change the current task mode ----------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_mode( - rtems_mode mode_set, - rtems_mode mask, - rtems_mode *previous_mode_set - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - task mode set successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``previous_mode_set`` is NULL - - not enough memory for stack/FP context - * - ``RTEMS_NOT_IMPLEMENTED`` - - non-preemption mode not supported on SMP system - * - ``RTEMS_NOT_IMPLEMENTED`` - -DESCRIPTION: - This directive manipulates the execution mode of the calling task. A - task's execution mode enables and disables preemption, timeslicing, - asynchronous signal processing, as well as specifying the current interrupt - level. To modify an execution mode, the mode class(es) to be changed must - be specified in the mask parameter and the desired mode(s) must be - specified in the mode parameter. - -NOTES: - The calling task will be preempted if it enables preemption and a higher - priority task is ready to run. - - Enabling timeslicing has no effect if preemption is disabled. For a task - to be timesliced, that task must have both preemption and timeslicing - enabled. - - A task can obtain its current execution mode, without modifying it, by - calling this directive with a mask value of ``RTEMS_CURRENT_MODE``. - - To temporarily disable the processing of a valid ASR, a task should call - this directive with the ``RTEMS_NO_ASR`` indicator specified in mode. - - The set of task mode constants and each mode's corresponding mask constant - is provided in the following table: - - .. list-table:: - :class: rtems-table - - * - ``RTEMS_PREEMPT`` - - is masked by ``RTEMS_PREEMPT_MASK`` and enables preemption - * - ``RTEMS_NO_PREEMPT`` - - is masked by ``RTEMS_PREEMPT_MASK`` and disables preemption - * - ``RTEMS_NO_TIMESLICE`` - - is masked by ``RTEMS_TIMESLICE_MASK`` and disables timeslicing - * - ``RTEMS_TIMESLICE`` - - is masked by ``RTEMS_TIMESLICE_MASK`` and enables timeslicing - * - ``RTEMS_ASR`` - - is masked by ``RTEMS_ASR_MASK`` and enables ASR processing - * - ``RTEMS_NO_ASR`` - - is masked by ``RTEMS_ASR_MASK`` and disables ASR processing - * - ``RTEMS_INTERRUPT_LEVEL(0)`` - - is masked by ``RTEMS_INTERRUPT_MASK`` and enables all interrupts - * - ``RTEMS_INTERRUPT_LEVEL(n)`` - - is masked by ``RTEMS_INTERRUPT_MASK`` and sets interrupts level n + +.. _InterfaceRtemsTaskMode: + +rtems_task_mode() +----------------- + +Gets and optionally sets the mode of the calling task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_mode( + rtems_mode mode_set, + rtems_mode mask, + rtems_mode *previous_mode_set + ); + +.. rubric:: PARAMETERS: + +``mode_set`` + This parameter is the mode set to apply to the calling task. When ``mask`` + is set to :c:macro:`RTEMS_CURRENT_MODE`, the value of this parameter is + ignored. Only modes requested by ``mask`` are applied to the calling task. + +``mask`` + This parameter is the mode mask which specifies which modes in ``mode_set`` + are applied to the calling task. When the value is + :c:macro:`RTEMS_CURRENT_MODE`, the mode of the calling task is not changed. + +``previous_mode_set`` + This parameter is the pointer to an :c:type:`rtems_mode` object. When the + directive call is successful, the mode of the task before any mode changes + done by the directive call will be stored in this object. + +.. rubric:: DESCRIPTION: + +This directive queries and optionally manipulates the execution mode of the +calling task. A task's execution mode enables and disables preemption, +timeslicing, asynchronous signal processing, as well as specifying the +interrupt level. To modify an execution mode, the mode class(es) to be changed +must be specified in the ``mask`` parameter and the desired mode(s) must be +specified in the ``mode_set`` parameter. + +A task can obtain its current execution mode, without modifying it, by calling +this directive with a ``mask`` value of :c:macro:`RTEMS_CURRENT_MODE`. + +The **mode set** specified in ``mode_set`` is built through a *bitwise or* of +the mode constants described below. Not all combinations of modes are allowed. +Some modes are mutually exclusive. If mutually exclusive modes are combined, +the behaviour is undefined. Default task modes can be selected by using the +:c:macro:`RTEMS_DEFAULT_MODES` constant. The task mode set defines + +* the preemption mode of the task: :c:macro:`RTEMS_PREEMPT` (default) or + :c:macro:`RTEMS_NO_PREEMPT`, + +* the timeslicing mode of the task: :c:macro:`RTEMS_TIMESLICE` or + :c:macro:`RTEMS_NO_TIMESLICE` (default), + +* the :term:`ASR` processing mode of the task: :c:macro:`RTEMS_ASR` (default) + or :c:macro:`RTEMS_NO_ASR`, + +* the interrupt level of the task: :c:func:`RTEMS_INTERRUPT_LEVEL` with a + default of ``RTEMS_INTERRUPT_LEVEL( 0 )`` which is associated with enabled + interrupts. + +The **mode mask** specified in ``mask`` is built through a *bitwise or* of the +mode mask constants described below. + +When the :c:macro:`RTEMS_PREEMPT_MASK` is set in ``mask``, the **preemption +mode** of the calling task is + +* enabled by using the :c:macro:`RTEMS_PREEMPT` mode constant in ``mode_set`` + and + +* disabled by using the :c:macro:`RTEMS_NO_PREEMPT` mode constant in + ``mode_set``. + +When the :c:macro:`RTEMS_TIMESLICE_MASK` is set in ``mask``, the **timeslicing +mode** of the calling task is + +* enabled by using the :c:macro:`RTEMS_TIMESLICE` mode constant in ``mode_set`` + and + +* disabled by using the :c:macro:`RTEMS_NO_TIMESLICE` mode constant in + ``mode_set``. + +Enabling timeslicing has no effect if preemption is disabled. For a task to be +timesliced, that task must have both preemption and timeslicing enabled. + +When the :c:macro:`RTEMS_ASR_MASK` is set in ``mask``, the **ASR processing +mode** of the calling task is + +* enabled by using the :c:macro:`RTEMS_ASR` mode constant in ``mode_set`` and + +* disabled by using the :c:macro:`RTEMS_NO_ASR` mode constant in ``mode_set``. + +When the :c:macro:`RTEMS_INTERRUPT_MASK` is set in ``mask``, **interrupts** of +the calling task are + +* enabled by using the :c:func:`RTEMS_INTERRUPT_LEVEL` mode macro with a value + of zero (0) in ``mode_set`` and + +* disabled up to the specified level by using the + :c:func:`RTEMS_INTERRUPT_LEVEL` mode macro with a positive value in + ``mode_set``. + +An interrupt level of zero is associated with enabled interrupts on all target +processors. The interrupt level portion of the task mode supports a maximum of +256 interrupt levels. These levels are mapped onto the interrupt levels +actually supported by the target processor in a processor dependent fashion. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_NOT_IMPLEMENTED` + The :c:macro:`RTEMS_NO_PREEMPT` was set in ``mode_set`` and setting the + preemption mode was requested by :c:macro:`RTEMS_PREEMPT_MASK` in ``mask`` + and the system configuration had no implementation for this mode. + +:c:macro:`RTEMS_NOT_IMPLEMENTED` + The :c:func:`RTEMS_INTERRUPT_LEVEL` was set to a positive level in + ``mode_set`` and setting the interrupt level was requested by + :c:macro:`RTEMS_INTERRUPT_MASK` in ``mask`` and the system configuration + had no implementation for this mode. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within task context. + +* When the directive enables preemption for the calling task, another task may + preempt the calling task. + +* While thread dispatching is disabled, if the directive performs a thread + dispatch, then the fatal error with the fatal source + :ref:`INTERNAL_ERROR_CORE <FatalErrorSources>` and the fatal code + :ref:`INTERNAL_ERROR_BAD_THREAD_DISPATCH_DISABLE_LEVEL <internal_errors>` + will occur. + +.. Generated from spec:/rtems/task/if/wake-after .. raw:: latex - \clearpage + \clearpage + +.. index:: rtems_task_wake_after() +.. index:: delay a task for a count of clock ticks +.. index:: wake up after a count of clock ticks + +.. _InterfaceRtemsTaskWakeAfter: + +rtems_task_wake_after() +----------------------- + +Wakes up after a count of :term:`clock ticks <clock tick>` have occurred or +yields the processor. + +.. rubric:: CALLING SEQUENCE: -.. index:: delay a task for an interval -.. index:: wake up after an interval -.. index:: rtems_task_wake_after +.. code-block:: c -.. _rtems_task_wake_after: + rtems_status_code rtems_task_wake_after( rtems_interval ticks ); -TASK_WAKE_AFTER - Wake up after interval ----------------------------------------- +.. rubric:: PARAMETERS: -CALLING SEQUENCE: - .. code-block:: c +``ticks`` + This parameter is the count of :term:`clock ticks <clock tick>` to delay + the task or :c:macro:`RTEMS_YIELD_PROCESSOR` to yield the processor. - rtems_status_code rtems_task_wake_after( - rtems_interval ticks - ); +.. rubric:: DESCRIPTION: -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +This directive blocks the calling task for the specified ``ticks`` count of +clock ticks if the value is not equal to :c:macro:`RTEMS_YIELD_PROCESSOR`. When +the requested count of ticks have occurred, the task is made ready. The clock +tick directives automatically update the delay period. The calling task may +give up the processor and remain in the ready state by specifying a value of +:c:macro:`RTEMS_YIELD_PROCESSOR` in ``ticks``. - * - ``RTEMS_SUCCESSFUL`` - - always successful +.. rubric:: RETURN VALUES: -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. +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. -NOTES: - Setting the system date and time with the ``rtems_clock_set`` directive has - no effect on a ``rtems_task_wake_after`` blocked task. +.. rubric:: 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 :ref:`InterfaceRtemsClockSet` +directive and similar directives which set :term:`CLOCK_REALTIME` have no +effect on a :ref:`InterfaceRtemsTaskWakeAfter` blocked task. The delay until +first clock tick will never be a whole clock tick interval since this directive +will never execute exactly on a clock tick. Applications requiring use of a +clock (:term:`CLOCK_REALTIME` or :term:`CLOCK_MONOTONIC`) instead of clock +ticks should make use of `clock_nanosleep() +<https://pubs.opengroup.org/onlinepubs/9699919799/functions/clock_nanosleep.html>`_. - The maximum timer interval that can be specified is the maximum value which - can be represented by the uint32_t type. +.. rubric:: CONSTRAINTS: - A clock tick is required to support the functionality of this directive. +The following constraints apply to this directive: + +* The directive may be called from within task context. + +* The directive requires a :term:`Clock Driver`. + +* While thread dispatching is disabled, if the directive performs a thread + dispatch, then the fatal error with the fatal source + :ref:`INTERNAL_ERROR_CORE <FatalErrorSources>` and the fatal code + :ref:`INTERNAL_ERROR_BAD_THREAD_DISPATCH_DISABLE_LEVEL <internal_errors>` + will occur. + +.. Generated from spec:/rtems/task/if/wake-when .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_task_wake_when() .. index:: delay a task until a wall time .. index:: wake up at a wall time -.. index:: rtems_task_wake_when -.. _rtems_task_wake_when: +.. _InterfaceRtemsTaskWakeWhen: -TASK_WAKE_WHEN - Wake up when specified ---------------------------------------- +rtems_task_wake_when() +---------------------- -CALLING SEQUENCE: - .. code-block:: c +Wakes up when specified. - rtems_status_code rtems_task_wake_when( - rtems_time_of_day *time_buffer - ); +.. rubric:: CALLING SEQUENCE: -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +.. code-block:: c - * - ``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_status_code rtems_task_wake_when( const rtems_time_of_day *time_buffer ); -DESCRIPTION: - This directive blocks a task until the date and time specified in - time_buffer. At the requested date and time, the calling task will be - unblocked and made ready to execute. +.. rubric:: PARAMETERS: -NOTES: - The ticks portion of time_buffer structure is ignored. The timing - granularity of this directive is a second. +``time_buffer`` + This parameter is the date and time to wake up. - A clock tick is required to support the functionality of this directive. +.. rubric:: DESCRIPTION: -.. raw:: latex +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. - \clearpage +.. rubric:: RETURN VALUES: -.. _rtems_task_get_scheduler: +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. -TASK_GET_SCHEDULER - Get scheduler of a task --------------------------------------------- +:c:macro:`RTEMS_NOT_DEFINED` + The system date and time was not set. -CALLING SEQUENCE: - .. code-block:: c +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``time_buffer`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. - rtems_status_code rtems_task_get_scheduler( - rtems_id task_id, - rtems_id *scheduler_id - ); +:c:macro:`RTEMS_INVALID_CLOCK` + The time of day was invalid. -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +.. rubric:: NOTES: - * - ``RTEMS_SUCCESSFUL`` - - successful operation - * - ``RTEMS_INVALID_ADDRESS`` - - ``scheduler_id`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid task id +The ticks portion of ``time_buffer`` structure is ignored. The timing +granularity of this directive is a second. -DESCRIPTION: - Returns the scheduler identifier of a task identified by ``task_id`` in - ``scheduler_id``. +.. rubric:: CONSTRAINTS: -NOTES: - None. +The following constraints apply to this directive: -.. raw:: latex +* The directive may be called from within task context. - \clearpage - -.. _rtems_task_set_scheduler: -.. _TASK_SET_SCHEDULER - Set scheduler of a task: - -TASK_SET_SCHEDULER - Set scheduler of a task --------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_set_scheduler( - rtems_id task_id, - rtems_id scheduler_id, - rtems_task_priority priority - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - successful operation - * - ``RTEMS_INVALID_ID`` - - invalid task or scheduler id - * - ``RTEMS_INVALID_PRIORITY`` - - invalid task priority - * - ``RTEMS_RESOURCE_IN_USE`` - - the task is in the wrong state to perform a scheduler change - * - ``RTEMS_UNSATISFIED`` - - the processor set of the scheduler is empty - * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - - not supported on remote tasks - -DESCRIPTION: - Sets the scheduler of a task identified by ``task_id`` to the scheduler - identified by ``scheduler_id``. The scheduler of a task is initialized to - the scheduler of the task that created it. The priority of the task is set - to ``priority``. - -NOTES: - It is recommended to set the scheduler of a task before it is started or in - case it is guaranteed that the task owns no resources. Otherwise, sporadic - ``RTEMS_RESOURCE_IN_USE`` errors may occur. - -EXAMPLE: - .. code-block:: c - :linenos: - - #include <rtems.h> - #include <assert.h> - - rtems_task task( rtems_task_argument arg ); - - void example( void ) - { - rtems_status_code sc; - rtems_id task_id; - rtems_id scheduler_id; - rtems_name scheduler_name; - - scheduler_name = rtems_build_name( 'W', 'O', 'R', 'K' ); - - sc = rtems_scheduler_ident( scheduler_name, &scheduler_id ); - assert( sc == RTEMS_SUCCESSFUL ); - - sc = rtems_task_create( - rtems_build_name( 'T', 'A', 'S', 'K' ), - 1, - RTEMS_MINIMUM_STACK_SIZE, - RTEMS_DEFAULT_MODES, - RTEMS_DEFAULT_ATTRIBUTES, - &task_id - ); - assert( sc == RTEMS_SUCCESSFUL ); - - sc = rtems_task_set_scheduler( task_id, scheduler_id, 2 ); - assert( sc == RTEMS_SUCCESSFUL ); - - sc = rtems_task_start( task_id, task, 0 ); - assert( sc == RTEMS_SUCCESSFUL ); - } +* The directive requires a :term:`Clock Driver`. + +* While thread dispatching is disabled, if the directive performs a thread + dispatch, then the fatal error with the fatal source + :ref:`INTERNAL_ERROR_CORE <FatalErrorSources>` and the fatal code + :ref:`INTERNAL_ERROR_BAD_THREAD_DISPATCH_DISABLE_LEVEL <internal_errors>` + will occur. + +.. Generated from spec:/rtems/task/if/get-scheduler .. raw:: latex - \clearpage + \clearpage -.. _rtems_task_get_affinity: +.. index:: rtems_task_get_scheduler() -TASK_GET_AFFINITY - Get task processor affinity ------------------------------------------------ +.. _InterfaceRtemsTaskGetScheduler: -CALLING SEQUENCE: - .. code-block:: c +rtems_task_get_scheduler() +-------------------------- - rtems_status_code rtems_task_get_affinity( - rtems_id id, - size_t cpusetsize, - cpu_set_t *cpuset - ); +Gets the home scheduler of the task. -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +.. rubric:: CALLING SEQUENCE: - * - ``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 +.. code-block:: c -DESCRIPTION: - Returns the current processor affinity set of the task in ``cpuset``. A - set bit in the affinity set means that the task can execute on this - processor and a cleared bit means the opposite. + rtems_status_code rtems_task_get_scheduler( + rtems_id task_id, + rtems_id *scheduler_id + ); -NOTES: - The task processor affinity is initialized to the set of online processors. +.. rubric:: PARAMETERS: -.. raw:: latex +``task_id`` + This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF` + may be used to specify the calling task. - \clearpage - -.. _rtems_task_set_affinity: - -TASK_SET_AFFINITY - Set task processor affinity ------------------------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_set_affinity( - rtems_id id, - size_t cpusetsize, - const cpu_set_t *cpuset - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - successful operation - * - ``RTEMS_INVALID_ADDRESS`` - - ``cpuset`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid task id - * - ``RTEMS_INVALID_NUMBER`` - - invalid processor affinity set - -DESCRIPTION: - Sets the processor affinity set for the task specified by ``cpuset``. A - set bit in the affinity set means that the task can execute on this - processor and a cleared bit means the opposite. - -NOTES: - This function will not change the scheduler of the task. The intersection - of the processor affinity set and the set of processors owned by the - scheduler of the task must be non-empty. It is not an error if the - processor affinity set contains processors that are not part of the set of - processors owned by the scheduler instance of the task. A task will simply - not run under normal circumstances on these processors since the scheduler - ignores them. Some locking protocols may temporarily use processors that - are not included in the processor affinity set of the task. It is also not - an error if the processor affinity set contains processors that are not - part of the system. - - In case a scheduler without support for task affinites is used for the - task, then the task processor affinity set must contain all online - processors of the system. This prevents odd corner cases if processors are - added/removed at run-time to/from scheduler instances. +``scheduler_id`` + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the identifier of the :term:`home + scheduler` of the task will be stored in this object. -.. raw:: latex +.. rubric:: DESCRIPTION: - \clearpage +This directive returns the identifier of the :term:`home scheduler` of the task +specified by ``task_id`` in ``scheduler_id``. -.. index:: iterate over all threads -.. index:: rtems_task_iterate +.. rubric:: RETURN VALUES: -.. _rtems_task_iterate: +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. -TASK_ITERATE - Iterate Over Tasks ---------------------------------- +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``scheduler_id`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. -CALLING SEQUENCE: - .. code-block:: c +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``task_id``. - typedef bool ( *rtems_task_visitor )( rtems_tcb *tcb, void *arg ); +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT` + The task resided on a remote node. - void rtems_task_iterate( - rtems_task_visitor visitor, - void *arg - ); +.. rubric:: CONSTRAINTS: -DIRECTIVE STATUS CODES: - NONE +The following constraints apply to this directive: -DESCRIPTION: - Iterates over all tasks in the system. This operation covers all tasks of - all APIs. The user should be careful in accessing the contents of the - thread control block :c:data:`tcb`. The visitor argument :c:data:`arg` is - passed to all invocations of :c:data:`visitor` in addition to the thread - control block. The iteration stops immediately in case the visitor - function returns true. +* The directive may be called from within interrupt context. -NOTES: - Must be called from task context. This operation obtains and releases the - objects allocator lock. The task visitor is called while owning the objects - allocator lock. It is possible to perform blocking operations in the task - visitor, however, take care that no deadlocks via the object allocator lock - can occur. +* The directive may be called from within device driver initialization context. -Deprecated Directives -===================== +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/task/if/set-scheduler .. raw:: latex - \clearpage + \clearpage -.. index:: rtems_iterate_over_all_threads +.. index:: rtems_task_set_scheduler() -.. _rtems_iterate_over_all_threads: +.. _InterfaceRtemsTaskSetScheduler: -ITERATE_OVER_ALL_THREADS - Iterate Over Tasks ---------------------------------------------- +rtems_task_set_scheduler() +-------------------------- -.. warning:: +Sets the home scheduler for the task. - This directive is deprecated. Its use is unsafe. Use - :ref:`rtems_task_iterate` instead. +.. rubric:: CALLING SEQUENCE: -CALLING SEQUENCE: - .. code-block:: c +.. code-block:: c - typedef void (*rtems_per_thread_routine)(Thread_Control *the_thread); - void rtems_iterate_over_all_threads( - rtems_per_thread_routine routine - ); + rtems_status_code rtems_task_set_scheduler( + rtems_id task_id, + rtems_id scheduler_id, + rtems_task_priority priority + ); -DIRECTIVE STATUS CODES: - NONE +.. rubric:: PARAMETERS: -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``. +``task_id`` + This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF` + may be used to specify the calling task. - This routine is intended for use in diagnostic utilities and is not - intented for routine use in an operational system. +``scheduler_id`` + This parameter is the scheduler identifier of the new :term:`home + scheduler` for the task specified by ``task_id``. -NOTES: - There is **no protection** while this routine is called. The thread - control block may be in an inconsistent state or may change due to - interrupts or activity on other processors. +``priority`` + This parameter is the new real priority for the task with respect to the + scheduler specified by ``scheduler_id``. -Removed Directives -================== +.. rubric:: DESCRIPTION: -.. raw:: latex +This directive sets the :term:`home scheduler` to the scheduler specified by +``scheduler_id`` for the task specified by ``task_id``. - \clearpage +.. rubric:: RETURN VALUES: -.. index:: get task notepad entry -.. index:: rtems_task_get_note +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. -.. _rtems_task_get_note: +:c:macro:`RTEMS_INVALID_ID` + There was no scheduler associated with the identifier specified by + ``scheduler_id``. + +:c:macro:`RTEMS_INVALID_PRIORITY` + The :term:`task priority` specified by ``priority`` was invalid with + respect to the scheduler specified by ``scheduler_id``. + +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``task_id``. + +:c:macro:`RTEMS_RESOURCE_IN_USE` + The task specified by ``task_id`` was enqueued on a :term:`wait queue`. -TASK_GET_NOTE - Get task notepad entry --------------------------------------- +:c:macro:`RTEMS_RESOURCE_IN_USE` + The task specified by ``task_id`` had a :term:`current priority` which + consisted of more than the :term:`real priority`. -.. warning:: +:c:macro:`RTEMS_RESOURCE_IN_USE` + The task specified by ``task_id`` had a :term:`helping scheduler`. - This directive was removed in RTEMS 5.1. +:c:macro:`RTEMS_RESOURCE_IN_USE` + The task specified by ``task_id`` was pinned. -CALLING SEQUENCE: - .. code-block:: c +:c:macro:`RTEMS_UNSATISFIED` + The scheduler specified by ``scheduler_id`` owned no processor. - rtems_status_code rtems_task_get_note( - rtems_id id, - uint32_t notepad, - uint32_t *note - ); +:c:macro:`RTEMS_UNSATISFIED` + The scheduler specified by ``scheduler_id`` did not support the affinity + set of the task specified by ``task_id``. -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT` + The task resided on a remote node. - * - ``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 +.. rubric:: CONSTRAINTS: -DESCRIPTION: - This directive returns the note contained in the notepad location of the - task specified by id. +The following constraints apply to this directive: -NOTES: - This directive will not cause the running task to be preempted. +* The directive may be called from within interrupt context. - If id is set to ``RTEMS_SELF``, the calling task accesses its own notepad. +* The directive may be called from within device driver initialization context. - The sixteen notepad locations can be accessed using the constants - ``RTEMS_NOTEPAD_0`` through ``RTEMS_NOTEPAD_15``. +* The directive may be called from within task context. - 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 directive may change the priority of a task. This may cause the calling + task to be preempted. + +.. Generated from spec:/rtems/task/if/get-affinity .. raw:: latex - \clearpage + \clearpage + +.. index:: rtems_task_get_affinity() + +.. _InterfaceRtemsTaskGetAffinity: + +rtems_task_get_affinity() +------------------------- + +Gets the processor affinity of the task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_get_affinity( + rtems_id id, + size_t cpusetsize, + cpu_set_t *cpuset + ); + +.. rubric:: PARAMETERS: -.. index:: set task notepad entry -.. index:: rtems_task_set_note +``id`` + This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF` + may be used to specify the calling task. -.. _rtems_task_set_note: +``cpusetsize`` + This parameter is the size of the processor set referenced by ``cpuset`` in + bytes. -TASK_SET_NOTE - Set task notepad entry --------------------------------------- +``cpuset`` + This parameter is the pointer to a :c:type:`cpu_set_t` object. When the + directive call is successful, the processor affinity set of the task will + be stored in this object. A set bit in the processor set means that the + corresponding processor is in the processor affinity set of the task, + otherwise the bit is cleared. -.. warning:: +.. rubric:: DESCRIPTION: - This directive was removed in RTEMS 5.1. +This directive returns the processor affinity of the task in ``cpuset`` of the +task specified by ``id``. -CALLING SEQUENCE: - .. code-block:: c +.. rubric:: RETURN VALUES: - rtems_status_code rtems_task_set_note( - rtems_id id, - uint32_t notepad, - uint32_t note - ); +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``cpuset`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. - * - ``RTEMS_SUCCESSFUL`` - - note set successfully - * - ``RTEMS_INVALID_ID`` - - invalid task id - * - ``RTEMS_INVALID_NUMBER`` - - invalid notepad location +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``id``. -DESCRIPTION: - This directive sets the notepad entry for the task specified by id to the - value note. +:c:macro:`RTEMS_INVALID_SIZE` + The size specified by ``cpusetsize`` of the processor set was too small for + the processor affinity set of the task. -NOTES: - If ``id`` is set to ``RTEMS_SELF``, the calling task accesses its own - notepad. +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT` + The task resided on a remote node. - This directive will not cause the running task to be preempted. +.. rubric:: CONSTRAINTS: - The sixteen notepad locations can be accessed using the constants - ``RTEMS_NOTEPAD_0`` through ``RTEMS_NOTEPAD_15``. +The following constraints apply to this directive: - 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 directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/task/if/set-affinity .. raw:: latex - \clearpage - -.. index:: per-task variable -.. index:: task private variable -.. index:: task private data -.. index:: rtems_task_variable_add - -.. _rtems_task_variable_add: - -TASK_VARIABLE_ADD - Associate per task variable ------------------------------------------------ - -.. warning:: - - This directive was removed in RTEMS 5.1. - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_variable_add( - rtems_id tid, - void **task_variable, - void (*dtor)(void *) - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - per task variable added successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``task_variable`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid task id - * - ``RTEMS_NO_MEMORY`` - - invalid task id - * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - - not supported on remote tasks - -DESCRIPTION: - This directive adds the memory location specified by the ptr argument to - the context of the given task. The variable will then be private to the - task. The task can access and modify the variable, but the modifications - will not appear to other tasks, and other tasks' modifications to that - variable will not affect the value seen by the task. This is accomplished - by saving and restoring the variable's value each time a task switch occurs - to or from the calling task. If the dtor argument is non-NULL it specifies - the address of a 'destructor' function which will be called when the task - is deleted. The argument passed to the destructor function is the task's - value of the variable. - -NOTES: - Task variables increase the context switch time to and from the tasks that - own them so it is desirable to minimize the number of task variables. One - efficient method is to have a single task variable that is a pointer to a - dynamically allocated structure containing the task's private 'global' - data. In this case the destructor function could be 'free'. - - Per-task variables are disabled in SMP configurations and this service is - not available. + \clearpage + +.. index:: rtems_task_set_affinity() + +.. _InterfaceRtemsTaskSetAffinity: + +rtems_task_set_affinity() +------------------------- + +Sets the processor affinity of the task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_set_affinity( + rtems_id id, + size_t cpusetsize, + const cpu_set_t *cpuset + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF` + may be used to specify the calling task. + +``cpusetsize`` + This parameter is the size of the processor set referenced by ``cpuset`` in + bytes. + +``cpuset`` + This parameter is the pointer to a :c:type:`cpu_set_t` object. The + processor set defines the new processor affinity set of the task. A set + bit in the processor set means that the corresponding processor shall be in + the processor affinity set of the task, otherwise the bit shall be cleared. + +.. rubric:: DESCRIPTION: + +This directive sets the processor affinity of the task specified by ``id``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``cpuset`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_INVALID_NUMBER` + The referenced processor set was not a valid new processor affinity set for + the task. + +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT` + The task resided on a remote node. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may change the processor affinity of a task. This may cause + the calling task to be preempted. + +.. Generated from spec:/rtems/task/if/iterate .. raw:: latex - \clearpage + \clearpage + +.. index:: rtems_task_iterate() + +.. _InterfaceRtemsTaskIterate: + +rtems_task_iterate() +-------------------- + +Iterates over all tasks and invokes the visitor routine for each task. -.. index:: get per-task variable -.. index:: obtain per-task variable -.. index:: rtems_task_variable_get +.. rubric:: CALLING SEQUENCE: -.. _rtems_task_variable_get: +.. code-block:: c -TASK_VARIABLE_GET - Obtain value of a per task variable -------------------------------------------------------- + void rtems_task_iterate( rtems_task_visitor visitor, void *arg ); -.. warning:: +.. rubric:: PARAMETERS: - This directive was removed in RTEMS 5.1. +``visitor`` + This parameter is the visitor routine invoked for each task. -CALLING SEQUENCE: - .. code-block:: c +``arg`` + This parameter is the argument passed to each visitor routine invocation + during the iteration. - rtems_status_code rtems_task_variable_get( - rtems_id tid, - void **task_variable, - void **task_variable_value - ); +.. rubric:: DESCRIPTION: -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +This directive iterates over all tasks in the system. This operation covers +all tasks of all APIs. The user should be careful in accessing the contents of +the :term:`TCB`. The visitor argument ``arg`` is passed to all invocations of +``visitor`` in addition to the TCB. The iteration stops immediately in case the +visitor routine returns true. - * - ``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 +.. rubric:: NOTES: -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. +The visitor routine is invoked while owning the objects allocator lock. It is +allowed to perform blocking operations in the visitor routine, however, care +must be taken so that no deadlocks via the object allocator lock can occur. -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. +.. rubric:: CONSTRAINTS: - Per-task variables are disabled in SMP configurations and this service is - not available. +The following constraints apply to this directive: + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. + +.. Generated from spec:/rtems/task/if/storage-size .. raw:: latex - \clearpage + \clearpage + +.. index:: RTEMS_TASK_STORAGE_SIZE() -.. index:: per-task variable -.. index:: task private variable -.. index:: task private data -.. index:: rtems_task_variable_delete +.. _InterfaceRTEMSTASKSTORAGESIZE: -.. _rtems_task_variable_delete: +RTEMS_TASK_STORAGE_SIZE() +------------------------- -TASK_VARIABLE_DELETE - Remove per task variable ------------------------------------------------ +Gets the recommended task storage area size for the size and task attributes. -.. warning:: +.. rubric:: CALLING SEQUENCE: - This directive was removed in RTEMS 5.1. +.. code-block:: c -CALLING SEQUENCE: - .. code-block:: c + size_t RTEMS_TASK_STORAGE_SIZE( size_t size, rtems_attribute attributes ); - rtems_status_code rtems_task_variable_delete( - rtems_id id, - void **task_variable - ); +.. rubric:: PARAMETERS: -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +``size`` + This parameter is the size dedicated to the task stack and thread-local + storage in bytes. - * - ``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 +``attributes`` + This parameter is the attribute set of the task using the storage area. -DESCRIPTION: - This directive removes the given location from a task's context. +.. rubric:: RETURN VALUES: -NOTES: - Per-task variables are disabled in SMP configurations and this service is - not available. +Returns the recommended task storage area size calculated from the input +parameters. diff --git a/c-user/task/index.rst b/c-user/task/index.rst index afe8b76..f5e8a64 100644 --- a/c-user/task/index.rst +++ b/c-user/task/index.rst @@ -1,10 +1,10 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020 embedded brains GmbH & Co. KG .. index:: tasks -.. _RTEMSAPIClassicTask: +.. _RTEMSAPIClassicTasks: Task Manager ************ diff --git a/c-user/task/introduction.rst b/c-user/task/introduction.rst index 449b335..f174b42 100644 --- a/c-user/task/introduction.rst +++ b/c-user/task/introduction.rst @@ -1,50 +1,106 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2023 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/rtems/task/if/group + +.. _TaskManagerIntroduction: Introduction ============ -The task manager provides a comprehensive set of directives to create, delete, -and administer tasks. The directives provided by the task manager are: +.. The following list was generated from: +.. spec:/rtems/task/if/create +.. spec:/rtems/task/if/construct +.. spec:/rtems/task/if/ident +.. spec:/rtems/task/if/self +.. spec:/rtems/task/if/start +.. spec:/rtems/task/if/restart +.. spec:/rtems/task/if/delete +.. spec:/rtems/task/if/exit +.. spec:/rtems/task/if/suspend +.. spec:/rtems/task/if/resume +.. spec:/rtems/task/if/is-suspended +.. spec:/rtems/task/if/set-priority +.. spec:/rtems/task/if/get-priority +.. spec:/rtems/task/if/mode +.. spec:/rtems/task/if/wake-after +.. spec:/rtems/task/if/wake-when +.. spec:/rtems/task/if/get-scheduler +.. spec:/rtems/task/if/set-scheduler +.. spec:/rtems/task/if/get-affinity +.. spec:/rtems/task/if/set-affinity +.. spec:/rtems/task/if/iterate +.. spec:/rtems/task/if/storage-size -- :ref:`rtems_task_create` +The Task Manager provides a comprehensive set of directives to create, delete, +and administer tasks. The directives provided by the Task Manager are: -- :ref:`rtems_task_ident` +* :ref:`InterfaceRtemsTaskCreate` - Creates a task. -- :ref:`rtems_task_self` +* :ref:`InterfaceRtemsTaskConstruct` - Constructs a task from the specified + task configuration. -- :ref:`rtems_task_start` +* :ref:`InterfaceRtemsTaskIdent` - Identifies a task by the object name. -- :ref:`rtems_task_restart` +* :ref:`InterfaceRtemsTaskSelf` - Gets the task identifier of the calling task. -- :ref:`rtems_task_delete` +* :ref:`InterfaceRtemsTaskStart` - Starts the task. -- :ref:`rtems_task_exit` +* :ref:`InterfaceRtemsTaskRestart` - Restarts the task. -- :ref:`rtems_task_suspend` +* :ref:`InterfaceRtemsTaskDelete` - Deletes the task. -- :ref:`rtems_task_resume` +* :ref:`InterfaceRtemsTaskExit` - Deletes the calling task. -- :ref:`rtems_task_is_suspended` +* :ref:`InterfaceRtemsTaskSuspend` - Suspends the task. -- :ref:`rtems_task_set_priority` +* :ref:`InterfaceRtemsTaskResume` - Resumes the task. -- :ref:`rtems_task_get_priority` +* :ref:`InterfaceRtemsTaskIsSuspended` - Checks if the task is suspended. -- :ref:`rtems_task_mode` +* :ref:`InterfaceRtemsTaskSetPriority` - Sets the real priority or gets the + current priority of the task. -- :ref:`rtems_task_wake_after` +* :ref:`InterfaceRtemsTaskGetPriority` - Gets the current priority of the task + with respect to the scheduler. -- :ref:`rtems_task_wake_when` +* :ref:`InterfaceRtemsTaskMode` - Gets and optionally sets the mode of the + calling task. -- :ref:`rtems_task_get_scheduler` +* :ref:`InterfaceRtemsTaskWakeAfter` - Wakes up after a count of :term:`clock + ticks <clock tick>` have occurred or yields the processor. -- :ref:`rtems_task_set_scheduler` +* :ref:`InterfaceRtemsTaskWakeWhen` - Wakes up when specified. -- :ref:`rtems_task_get_affinity` +* :ref:`InterfaceRtemsTaskGetScheduler` - Gets the home scheduler of the task. -- :ref:`rtems_task_set_affinity` +* :ref:`InterfaceRtemsTaskSetScheduler` - Sets the home scheduler for the task. -- :ref:`rtems_task_iterate` +* :ref:`InterfaceRtemsTaskGetAffinity` - Gets the processor affinity of the + task. + +* :ref:`InterfaceRtemsTaskSetAffinity` - Sets the processor affinity of the + task. + +* :ref:`InterfaceRtemsTaskIterate` - Iterates over all tasks and invokes the + visitor routine for each task. + +* :ref:`InterfaceRTEMSTASKSTORAGESIZE` - Gets the recommended task storage area + size for the size and task attributes. diff --git a/c-user/task/operations.rst b/c-user/task/operations.rst index 58174d6..438eea5 100644 --- a/c-user/task/operations.rst +++ b/c-user/task/operations.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) Operations @@ -75,9 +75,9 @@ Delaying the Currently Executing Task ------------------------------------- The ``rtems_task_wake_after`` directive creates a sleep timer which allows a -task to go to sleep for a specified interval. The task is blocked until the -delay interval has elapsed, at which time the task is unblocked. A task -calling the ``rtems_task_wake_after`` directive with a delay interval of +task to go to sleep for a specified count of clock ticks. The task is blocked +until the count of clock ticks has elapsed, at which time the task is unblocked. +A task calling the ``rtems_task_wake_after`` directive with a delay of ``RTEMS_YIELD_PROCESSOR`` ticks will yield the processor to any other ready task of equal or greater priority and remain ready to execute. @@ -160,8 +160,8 @@ It is important to note that the ``cpuset`` is not validated until the ``rtems_task_set_affinity`` call is made. At that point, it is validated against the current system configuration. -.. index:: rtems_task_get_note -.. index:: rtems_task_set_note +.. index:: rtems_task_get_note() +.. index:: rtems_task_set_note() Transition Advice for Removed Notepads --------------------------------------- @@ -177,9 +177,9 @@ over the key (e.g. notepad index) selection. For most applications, POSIX Keys should be used. These are available in all RTEMS build configurations. It is also possible that thread-local storage (TLS) is an option for some use cases. -.. index:: rtems_task_variable_add -.. index:: rtems_task_variable_get -.. index:: rtems_task_variable_delete +.. index:: rtems_task_variable_add() +.. index:: rtems_task_variable_get() +.. index:: rtems_task_variable_delete() Transition Advice for Removed Task Variables --------------------------------------------- diff --git a/c-user/task/removed-directives.rst b/c-user/task/removed-directives.rst index 8c8aae9..677e810 100644 --- a/c-user/task/removed-directives.rst +++ b/c-user/task/removed-directives.rst @@ -10,7 +10,7 @@ Removed Directives \clearpage .. index:: get task notepad entry -.. index:: rtems_task_get_note +.. index:: rtems_task_get_note() .. _rtems_task_get_note: @@ -64,7 +64,7 @@ NOTES: \clearpage .. index:: set task notepad entry -.. index:: rtems_task_set_note +.. index:: rtems_task_set_note() .. _rtems_task_set_note: @@ -119,7 +119,7 @@ NOTES: .. index:: per-task variable .. index:: task private variable .. index:: task private data -.. index:: rtems_task_variable_add +.. index:: rtems_task_variable_add() .. _rtems_task_variable_add: @@ -182,7 +182,7 @@ NOTES: .. index:: get per-task variable .. index:: obtain per-task variable -.. index:: rtems_task_variable_get +.. index:: rtems_task_variable_get() .. _rtems_task_variable_get: @@ -241,7 +241,7 @@ NOTES: .. index:: per-task variable .. index:: task private variable .. index:: task private data -.. index:: rtems_task_variable_delete +.. index:: rtems_task_variable_delete() .. _rtems_task_variable_delete: diff --git a/c-user/timer/directives.rst b/c-user/timer/directives.rst index b5ec8f4..2237b30 100644 --- a/c-user/timer/directives.rst +++ b/c-user/timer/directives.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) .. This file is part of the RTEMS quality process and was automatically @@ -55,9 +55,9 @@ Creates a timer. This parameter is the object name of the timer. ``id`` - This parameter is the pointer to an object identifier variable. When the - directive call is successful, the identifier of the created timer will be - stored in this variable. + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the identifier of the created timer will + be stored in this object. .. rubric:: DESCRIPTION: @@ -137,9 +137,9 @@ Identifies a timer by the object name. This parameter is the object name to look up. ``id`` - This parameter is the pointer to an object identifier variable. When the - directive call is successful, the object identifier of an object with the - specified name will be stored in this variable. + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the object identifier of an object with + the specified name will be stored in this object. .. rubric:: DESCRIPTION: @@ -212,8 +212,9 @@ Cancels the timer. This directive cancels the timer specified by ``id``. This timer will be reinitiated by the next invocation of :ref:`InterfaceRtemsTimerReset`, -:ref:`InterfaceRtemsTimerFireAfter`, or :ref:`InterfaceRtemsTimerFireWhen` with -the same timer identifier. +:ref:`InterfaceRtemsTimerFireAfter`, :ref:`InterfaceRtemsTimerFireWhen`, +:ref:`InterfaceRtemsTimerServerFireAfter`, or +:ref:`InterfaceRtemsTimerServerFireWhen` with the same timer identifier. .. rubric:: RETURN VALUES: @@ -395,7 +396,7 @@ Fires the timer at the time of day. rtems_status_code rtems_timer_fire_when( rtems_id id, - rtems_time_of_day *wall_time, + const rtems_time_of_day *wall_time, rtems_timer_service_routine_entry routine, void *user_data ); @@ -648,7 +649,7 @@ Fires the timer at the time of day using the Timer Server. rtems_status_code rtems_timer_server_fire_when( rtems_id id, - rtems_time_of_day *wall_time, + const rtems_time_of_day *wall_time, rtems_timer_service_routine_entry routine, void *user_data ); @@ -810,9 +811,9 @@ Gets information about the timer. This parameter is the timer identifier. ``the_info`` - This parameter is the pointer to a timer information variable. When the - directive call is successful, the information about the timer will be - stored in this variable. + This parameter is the pointer to an :ref:`InterfaceRtemsTimerInformation` + object. When the directive call is successful, the information about the + timer will be stored in this object. .. rubric:: DESCRIPTION: diff --git a/c-user/timer/index.rst b/c-user/timer/index.rst index 6557668..b149f30 100644 --- a/c-user/timer/index.rst +++ b/c-user/timer/index.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020 embedded brains GmbH & Co. KG .. index:: timers diff --git a/c-user/timer/introduction.rst b/c-user/timer/introduction.rst index 76db7ff..4f35972 100644 --- a/c-user/timer/introduction.rst +++ b/c-user/timer/introduction.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) .. This file is part of the RTEMS quality process and was automatically diff --git a/c-user/timespec_helpers.rst b/c-user/timespec_helpers.rst index f2ef5cd..bc39630 100644 --- a/c-user/timespec_helpers.rst +++ b/c-user/timespec_helpers.rst @@ -125,7 +125,7 @@ sequence, related constants, usage, and status codes. \clearpage .. index:: set struct timespec instance -.. index:: rtems_timespec_set +.. index:: rtems_timespec_set() .. _rtems_timespec_set: @@ -156,7 +156,7 @@ NOTES: \clearpage -.. index:: rtems_timespec_zero +.. index:: rtems_timespec_zero() .. _rtems_timespec_zero: @@ -184,7 +184,7 @@ NOTES: \clearpage -.. index:: rtems_timespec_is_valid +.. index:: rtems_timespec_is_valid() .. _rtems_timespec_is_valid: @@ -214,7 +214,7 @@ NOTES: \clearpage -.. index:: rtems_timespec_add_to +.. index:: rtems_timespec_add_to() .. _rtems_timespec_add_to: @@ -244,7 +244,7 @@ NOTES: \clearpage -.. index:: rtems_timespec_subtract +.. index:: rtems_timespec_subtract() .. _rtems_timespec_subtract: @@ -279,7 +279,7 @@ NOTES: \clearpage -.. index:: rtems_timespec_divide +.. index:: rtems_timespec_divide() .. _rtems_timespec_divide: @@ -320,7 +320,7 @@ NOTES: \clearpage -.. index:: rtems_timespec_divide_by_integer +.. index:: rtems_timespec_divide_by_integer() .. _rtems_timespec_divide_by_integer: @@ -352,7 +352,7 @@ NOTES: \clearpage -.. index:: rtems_timespec_less_than +.. index:: rtems_timespec_less_than() .. _rtems_timespec_less_than: @@ -383,7 +383,7 @@ NOTES: \clearpage -.. index:: rtems_timespec_greater_than +.. index:: rtems_timespec_greater_than() .. _rtems_timespec_greater_than: @@ -412,7 +412,7 @@ NOTES: \clearpage -.. index:: rtems_timespec_equal_to +.. index:: rtems_timespec_equal_to() .. _rtems_timespec_equal_to: @@ -441,7 +441,7 @@ NOTES: \clearpage -.. index:: rtems_timespec_get_seconds +.. index:: rtems_timespec_get_seconds() .. _rtems_timespec_get_seconds: @@ -470,7 +470,7 @@ NOTES: \clearpage -.. index:: rtems_timespec_get_nanoseconds +.. index:: rtems_timespec_get_nanoseconds() .. _rtems_timespec_get_nanoseconds: @@ -499,7 +499,7 @@ NOTES: \clearpage -.. index:: rtems_timespec_to_ticks +.. index:: rtems_timespec_to_ticks() .. _rtems_timespec_to_ticks: @@ -527,7 +527,7 @@ NOTES: \clearpage -.. index:: rtems_timespec_from_ticks +.. index:: rtems_timespec_from_ticks() .. _rtems_timespec_from_ticks: diff --git a/c-user/user-extensions/background.rst b/c-user/user-extensions/background.rst index 2dc2577..c1430a9 100644 --- a/c-user/user-extensions/background.rst +++ b/c-user/user-extensions/background.rst @@ -109,15 +109,10 @@ and release the extension buffers. Order of Invocation ------------------- -The user extensions are invoked in either `forward` or `reverse` order. In -forward order, the user extensions of initial extension sets are invoked before -the user extensions of the dynamic extension sets. The forward order of -initial extension sets is defined by the initial extension sets table index. -The forward order of dynamic extension sets is defined by the order in which -the dynamic extension sets were created. The reverse order is defined -accordingly. By invoking the user extensions in this order, extensions can be -built upon one another. At the following system events, the user extensions -are invoked in `forward` order +The user extensions are invoked in either :term:`extension forward order` or +:term:`extension reverse order`. By invoking the user extensions in these +orders, extensions can be built upon one another. At the following system +events, the user extensions are invoked in `forward` order - thread creation, @@ -148,7 +143,7 @@ installed after the Standard C Library will operate correctly even if they utilize the C Library because the C Library's thread delete extension is invoked after that of the other thread delete extensions. -.. index:: rtems_task_create_extension +.. index:: rtems_task_create_extension() Thread Create Extension ----------------------- diff --git a/c-user/user-extensions/directives.rst b/c-user/user-extensions/directives.rst index 9aa1e9d..2c5648b 100644 --- a/c-user/user-extensions/directives.rst +++ b/c-user/user-extensions/directives.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) .. This file is part of the RTEMS quality process and was automatically @@ -64,9 +64,9 @@ Creates an extension set. set. ``id`` - This parameter is the pointer to an object identifier variable. When the - directive call is successful, the identifier of the created extension set - will be stored in this variable. + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the identifier of the created extension + set will be stored in this object. .. rubric:: DESCRIPTION: @@ -102,11 +102,15 @@ The extension set is initialized using the extension table specified in .. rubric:: NOTES: -The user-provided extension set table is not used after the return of the +The user-provided extension table is not used after the return of the directive. -Newly created extension sets are immediately installed and are invoked upon the -next system event supporting an extension. +Each extension of the extension table is optional and may be `NULL +<https://en.cppreference.com/w/c/types/NULL>`_. All extensions except the task +switch extension of the extension table are atomically and immediately +installed. A task switch extension is separately installed after the other +extensions. The extensions of the extension table are invoked upon the next +system event supporting an extension. An alternative to dynamically created extension sets are initial extensions, see :ref:`CONFIGURE_INITIAL_EXTENSIONS`. Initial extensions are recommended @@ -215,9 +219,9 @@ Identifies an extension set by the object name. This parameter is the object name to look up. ``id`` - This parameter is the pointer to an object identifier variable. When the - directive call is successful, the object identifier of an object with the - specified name will be stored in this variable. + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the object identifier of an object with + the specified name will be stored in this object. .. rubric:: DESCRIPTION: diff --git a/c-user/user-extensions/index.rst b/c-user/user-extensions/index.rst index 56aa9c4..54b0649 100644 --- a/c-user/user-extensions/index.rst +++ b/c-user/user-extensions/index.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020 embedded brains GmbH & Co. KG .. index:: user extensions diff --git a/c-user/user-extensions/introduction.rst b/c-user/user-extensions/introduction.rst index 6284242..fab79e7 100644 --- a/c-user/user-extensions/introduction.rst +++ b/c-user/user-extensions/introduction.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) .. This file is part of the RTEMS quality process and was automatically |