diff options
Diffstat (limited to 'c-user')
113 files changed, 10591 insertions, 3893 deletions
diff --git a/c-user/barrier/directives.rst b/c-user/barrier/directives.rst index 59abc51..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 :c:type:`rtems_id` object. When the - directive call is successful, the identifier of the created barrier will be - stored in this object. + 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 :c:type:`rtems_id` object. When the - directive call is successful, the object identifier of an object with the - specified name will be stored in this object. + 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/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 index 98349db..a97654e 100644 --- a/c-user/cache/directives.rst +++ b/c-user/cache/directives.rst @@ -1,7 +1,7 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 .. Copyright (C) 2016 Pavel Pisa -.. Copyright (C) 2014, 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. 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 diff --git a/c-user/cache/index.rst b/c-user/cache/index.rst index c8f7263..57c124f 100644 --- a/c-user/cache/index.rst +++ b/c-user/cache/index.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2021 embedded brains GmbH & Co. KG .. index:: cache diff --git a/c-user/cache/introduction.rst b/c-user/cache/introduction.rst index 6cae4b2..a632c9c 100644 --- a/c-user/cache/introduction.rst +++ b/c-user/cache/introduction.rst @@ -1,7 +1,7 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 .. Copyright (C) 2016 Pavel Pisa -.. Copyright (C) 2014, 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. 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 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 1a65abf..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 @@ -137,7 +137,7 @@ Gets the time of day associated with the current :term:`CLOCK_REALTIME`. .. rubric:: PARAMETERS: ``time_of_day`` - This parameter is the pointer to an :c:type:`rtems_time_of_day` object. + This parameter is the pointer to an :ref:`InterfaceRtemsTimeOfDay` object. When the directive call is successful, the time of day associated with the :term:`CLOCK_REALTIME` at some point during the directive call will be stored in this object. @@ -220,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 @@ -247,8 +1086,8 @@ 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 :c:type:`rtems_interval` object. When - the directive call is successful, the seconds elapsed since the + 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. @@ -383,12 +1222,11 @@ system initialization using :term:`CLOCK_MONOTONIC`. .. rubric:: PARAMETERS: ``uptime`` - 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 nanoseconds - elapsed since some time point during the system initialization and some - point during the directive call using :term:`CLOCK_MONOTONIC` will be - stored in this object. + This parameter is the pointer to a `struct timespec + <https://en.cppreference.com/w/c/chrono/timespec>`_ object. When the + directive call is successful, the seconds and nanoseconds elapsed since + some time point during the system initialization and some point during the + directive call using :term:`CLOCK_MONOTONIC` will be stored in this object. .. rubric:: RETURN VALUES: 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 c5381e1..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, 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 @@ -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,33 +76,38 @@ NOTES: CONFIGURE_BDBUF_BUFFER_MAX_SIZE ------------------------------- -CONSTANT: - ``CONFIGURE_BDBUF_BUFFER_MAX_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_BDBUF_BUFFER_MAX_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 4096. +.. rubric:: DEFAULT VALUE: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The default value is 4096. - * It shall be greater than or equal to zero. +.. rubric:: DESCRIPTION: - * It shall be an integral multiple of - :ref:`CONFIGURE_BDBUF_BUFFER_MIN_SIZE`. +The value of this configuration option defines the maximum size of a buffer +in bytes. -DESCRIPTION: - The value of this configuration option defines the maximum size of a buffer - in bytes. +.. rubric:: CONSTRAINTS: -NOTES: - None. +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be 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: @@ -97,33 +115,38 @@ NOTES: CONFIGURE_BDBUF_BUFFER_MIN_SIZE ------------------------------- -CONSTANT: - ``CONFIGURE_BDBUF_BUFFER_MIN_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_BDBUF_BUFFER_MIN_SIZE`` -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: OPTION TYPE: -DEFAULT VALUE: - The default value is 512. +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 zero. +The default value is 512. - * It shall be 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: @@ -131,33 +154,38 @@ NOTES: CONFIGURE_BDBUF_CACHE_MEMORY_SIZE --------------------------------- -CONSTANT: - ``CONFIGURE_BDBUF_CACHE_MEMORY_SIZE`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is an integer define. +``CONFIGURE_BDBUF_CACHE_MEMORY_SIZE`` -DEFAULT VALUE: - The default value is 32768. +.. 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 zero. +.. 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 32768. -DESCRIPTION: - The value of this configuration option defines the size of the cache memory - in bytes. +.. rubric:: DESCRIPTION: -NOTES: - None. +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: @@ -165,35 +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: -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 blocks per +read-ahead request. - * It shall be greater than or equal to zero. +.. rubric:: NOTES: - * It shall be less than or equal to `UINT32_MAX - <https://en.cppreference.com/w/c/types/integer>`_. +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. -DESCRIPTION: - The value of this configuration option defines the maximum blocks per - read-ahead request. +.. rubric:: CONSTRAINTS: -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. +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: @@ -201,33 +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 satisfy all of the following - constraints: +.. rubric:: DEFAULT VALUE: - * It shall be greater than or equal to zero. +The default value is 16. - * It shall be 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 blocks per write - request. +The value of this configuration option defines the maximum blocks per write +request. -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-read-ahead-task-priority +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY .. _CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY: @@ -235,28 +277,34 @@ NOTES: CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY ---------------------------------------- -CONSTANT: - ``CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is an integer define. +``CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY`` -DEFAULT VALUE: - The default value is 15. +.. rubric:: OPTION TYPE: -VALUE CONSTRAINTS: - The value of this configuration option shall be a valid Classic API task - priority. The set of valid task priorities depends on the scheduler - configuration. +This configuration option is an integer define. -DESCRIPTION: - The value of this configuration option defines the read-ahead task priority. +.. rubric:: DEFAULT VALUE: -NOTES: - None. +The default value is 15. + +.. rubric:: DESCRIPTION: + +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: @@ -264,39 +312,45 @@ NOTES: CONFIGURE_BDBUF_TASK_STACK_SIZE ------------------------------- -CONSTANT: - ``CONFIGURE_BDBUF_TASK_STACK_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_BDBUF_TASK_STACK_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: -OPTION TYPE: - This configuration option is an integer define. +The default value is :c:macro:`RTEMS_MINIMUM_STACK_SIZE`. -DEFAULT VALUE: - The default value is :c:macro:`RTEMS_MINIMUM_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 task stack size of the +Block Device Cache tasks in bytes. - * It shall be greater than or equal to - :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. +.. rubric:: CONSTRAINTS: - * It shall be less than or equal to a BSP-specific and application-specific - value which depends on the size of the memory available to the - application. +The following constraints apply to this configuration option: - * 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>`_. +* The value of the configuration option shall be greater than or equal to + :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. -DESCRIPTION: - The value of this configuration option defines the task stack size of the - Block Device Cache tasks in bytes. +* The value of the configuration option shall be 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: - None. +* 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: @@ -304,33 +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. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DEFAULT VALUE: -DEFAULT VALUE: - The default value is 1000. +The default value is 1000. -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 zero. +The value of this configuration option defines the swapout task maximum block +hold time in milliseconds. - * It shall be 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: @@ -338,33 +397,38 @@ NOTES: CONFIGURE_SWAPOUT_SWAP_PERIOD ----------------------------- -CONSTANT: - ``CONFIGURE_SWAPOUT_SWAP_PERIOD`` +.. rubric:: CONSTANT: + +``CONFIGURE_SWAPOUT_SWAP_PERIOD`` + +.. 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 250. +.. rubric:: DEFAULT VALUE: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The default value is 250. - * It shall be greater than or equal to zero. +.. rubric:: DESCRIPTION: - * It shall be less than or equal to `UINT32_MAX - <https://en.cppreference.com/w/c/types/integer>`_. +The value of this configuration option defines the swapout task swap period +in milliseconds. -DESCRIPTION: - The value of this configuration option defines the swapout task swap period - in milliseconds. +.. rubric:: CONSTRAINTS: -NOTES: - None. +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. .. Generated from spec:/acfg/if/bdbuf-swapout-task-priority +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_SWAPOUT_TASK_PRIORITY .. _CONFIGURE_SWAPOUT_TASK_PRIORITY: @@ -372,28 +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 depends on the scheduler - configuration. +.. 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: @@ -401,32 +471,37 @@ NOTES: CONFIGURE_SWAPOUT_WORKER_TASKS ------------------------------ -CONSTANT: - ``CONFIGURE_SWAPOUT_WORKER_TASKS`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is an integer define. +``CONFIGURE_SWAPOUT_WORKER_TASKS`` -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 zero. +.. rubric:: DEFAULT VALUE: - * It shall be less than or equal to `UINT32_MAX - <https://en.cppreference.com/w/c/types/integer>`_. +The default value is 0. -DESCRIPTION: - The value of this configuration option defines the swapout worker task count. +.. rubric:: DESCRIPTION: -NOTES: - None. +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: @@ -434,23 +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 depends on the scheduler - configuration. +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 45f31a8..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, 2021 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 add BSP-provided - prerequisite drivers to the Device Driver Table. - -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 4643572..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, 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 @@ -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 zero. +.. 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 the object class, if the value passed to - :c:func:`rtems_resource_unlimited` satisfies all other constraints of the - 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 zero. +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 the object class, if the value passed to - :c:func:`rtems_resource_unlimited` satisfies all other constraints of the - 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. -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 zero. +The value of this configuration option defines the maximum number of Classic +API Partitions 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 the object class, if the value passed to - :c:func:`rtems_resource_unlimited` satisfies all other constraints of the - configuration option. +.. rubric:: CONSTRAINTS: -DESCRIPTION: - The value of this configuration option defines the maximum number of Classic - API Partitions 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-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: + +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 Periods that can be concurrently active. -DEFAULT VALUE: - The default value is 0. +.. rubric:: NOTES: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. - * It shall be greater than or equal to zero. +.. rubric:: CONSTRAINTS: - * It shall be less than or equal to 65535. +The following constraints apply to this configuration option: - * It shall be less than or equal to a BSP-specific and application-specific - value which depends on the size of the memory available to the - application. +* The value of the configuration option shall be greater than or equal to zero. - * It may be defined through :c:func:`rtems_resource_unlimited` the enable - unlimited objects for the object class, if the value passed to - :c:func:`rtems_resource_unlimited` satisfies all other constraints of the - configuration option. +* The value of the configuration option shall be less than or equal to 65535. -DESCRIPTION: - The value of this configuration option defines the maximum number of Classic - API Periods that can be concurrently active. +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. +* The value of the configuration option may be defined through + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` + satisfies all other constraints of the configuration option. .. Generated from spec:/acfg/if/max-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. -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 zero. +The value of this configuration option defines the maximum number of Classic +API Ports that can be concurrently active. - * It shall be less than or equal to 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 the object class, if the value passed to - :c:func:`rtems_resource_unlimited` satisfies all other constraints of the - configuration option. +.. rubric:: CONSTRAINTS: -DESCRIPTION: - The value of this configuration option defines the maximum number of Classic - API Ports 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-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: -OPTION TYPE: - This configuration option is an integer define. +``CONFIGURE_MAXIMUM_REGIONS`` -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 zero. +.. 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 the object class, if the value passed to - :c:func:`rtems_resource_unlimited` satisfies all other constraints of the - configuration option. +The value of this configuration option defines the maximum number of Classic +API Regions that can be concurrently active. -DESCRIPTION: - The value of this configuration option defines the maximum number of Classic - API Regions 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`. + +.. 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,159 +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 zero. +.. 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 the object class, if the value passed to - :c:func:`rtems_resource_unlimited` satisfies all other constraints of the - 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 zero. + \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 the object class, if the value passed to - :c:func:`rtems_resource_unlimited` satisfies all other constraints of the - 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 zero. +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 @@ -455,42 +478,51 @@ NOTES: CONFIGURE_MAXIMUM_TIMERS ------------------------ -CONSTANT: - ``CONFIGURE_MAXIMUM_TIMERS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_TIMERS`` -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 zero. +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 Timers that can be concurrently active. - * It may be defined through :c:func:`rtems_resource_unlimited` the enable - unlimited objects for the object class, if the value passed to - :c:func:`rtems_resource_unlimited` satisfies all other constraints of the - configuration option. +.. rubric:: NOTES: -DESCRIPTION: - The value of this configuration option defines the maximum number of Classic - API Timers 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-user-extensions +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MAXIMUM_USER_EXTENSIONS .. _CONFIGURE_MAXIMUM_USER_EXTENSIONS: @@ -498,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: -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 User Extensions that can be concurrently active. - * It shall be greater than or equal to zero. +.. rubric:: NOTES: - * It shall be less than or equal to 65535. +This object class cannot be configured in unlimited allocation mode. - * 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: -DESCRIPTION: - The value of this configuration option defines the maximum number of Classic - API User Extensions that can be concurrently active. +The following constraints apply to this configuration option: -NOTES: - This object class cannot be configured in unlimited allocation mode. +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. .. Generated from spec:/acfg/if/min-tasks-with-user-provided-storage +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MINIMUM_TASKS_WITH_USER_PROVIDED_STORAGE .. _CONFIGURE_MINIMUM_TASKS_WITH_USER_PROVIDED_STORAGE: @@ -535,31 +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: -OPTION TYPE: - This configuration option is an integer define. +The value of this configuration option defines the minimum count of Classic +API Tasks which are constructed by :ref:`InterfaceRtemsTaskConstruct`. -DEFAULT VALUE: - The default value is 0. +.. rubric:: NOTES: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +By default, the calculation for the required memory in the RTEMS Workspace +for tasks assumes that all Classic API Tasks are created by +:ref:`InterfaceRtemsTaskCreate`. This configuration option can be used to +reduce the required memory for the system-provided task storage areas since +tasks constructed by :ref:`InterfaceRtemsTaskConstruct` use a user-provided +task storage area. - * It shall be greater than or equal to zero. +.. rubric:: CONSTRAINTS: - * It shall be 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 9c0435b..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, 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 @@ -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 convertible to an 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 convertible to an 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,29 +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 depends on the scheduler - configuration. +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: @@ -271,41 +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: @@ -313,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 22002f9..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, 2021 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,29 +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 depends on the scheduler - configuration. +.. _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: @@ -613,69 +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 fa1d011..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, 2021 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,35 +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 05ca826..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, 2021 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 equal to 16, 32, 64, 128, - 256, or 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 1a43b03..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, 2021 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,40 +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 zero. +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 @@ -138,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 -OPTION TYPE: - This configuration option is an integer define. +.. raw:: latex -DEFAULT VALUE: - The default value is 0. + \clearpage -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. index:: CONFIGURE_INIT - * It shall be greater than or equal to zero. +.. _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>`_. +CONFIGURE_INIT +-------------- -DESCRIPTION: - The value of this configuration option defines the number of bytes the - applications wishes to add to the task stack requirements calculated by - ``<rtems/confdefs.h>``. +.. rubric:: CONSTANT: -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>``. +``CONFIGURE_INIT`` + +.. 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: @@ -176,30 +302,40 @@ NOTES: CONFIGURE_INITIAL_EXTENSIONS ---------------------------- -CONSTANT: - ``CONFIGURE_INITIAL_EXTENSIONS`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is an initializer define. +``CONFIGURE_INITIAL_EXTENSIONS`` -DEFAULT VALUE: - The default value is the empty list. +.. rubric:: OPTION TYPE: -VALUE CONSTRAINTS: - The value of this configuration option shall be a list of initializers for - structures of type :c:type:`rtems_extensions_table`. +This configuration option is an initializer define. -DESCRIPTION: - The value of this configuration option is used to initialize the table of - initial user extensions. +.. rubric:: DEFAULT VALUE: -NOTES: - The value of this configuration option is placed before the entries of - :ref:`BSP_INITIAL_EXTENSION` and after the entries of all other initial - user extensions. +The default value is the empty list. + +.. 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 @@ -208,54 +344,67 @@ NOTES: CONFIGURE_INTERRUPT_STACK_SIZE ------------------------------ -CONSTANT: - ``CONFIGURE_INTERRUPT_STACK_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_INTERRUPT_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_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`. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is an integer define. +The value of this configuration option defines the size of an interrupt stack +in bytes. -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:: NOTES: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +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. - * It shall be greater than or equal to a BSP-specific and - application-specific minimum value. +Some BSPs use the interrupt stack as the initialization stack which is used +to perform the sequential system initialization before the multithreading +is started. - * 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>`_. +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. - * It shall be aligned according to - :c:macro:`CPU_INTERRUPT_STACK_ALIGNMENT`. +In releases before RTEMS 5.1 the default value was +:ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE` instead of +:c:macro:`CPU_STACK_MINIMUM_SIZE`. -DESCRIPTION: - The value of this configuration option defines the size of an interrupt stack - in bytes. +.. rubric:: CONSTRAINTS: -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. +The following constraints apply to this configuration option: - Some BSPs use the interrupt stack as the initialization stack which is used - to perform the sequential system initialization before the multithreading - is started. +* The value of the configuration option shall be greater than or equal to a + BSP-specific and application-specific minimum value. - 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. +* 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>`_. - 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 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: @@ -263,29 +412,38 @@ NOTES: CONFIGURE_MALLOC_DIRTY ---------------------- -CONSTANT: - ``CONFIGURE_MALLOC_DIRTY`` +.. rubric:: CONSTANT: + +``CONFIGURE_MALLOC_DIRTY`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. -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 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. -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: -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. +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 @@ -294,38 +452,47 @@ NOTES: CONFIGURE_MAXIMUM_FILE_DESCRIPTORS ---------------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_FILE_DESCRIPTORS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_FILE_DESCRIPTORS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 3. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is an integer define. +The value of this configuration option defines the maximum number of file +like objects that can be concurrently open. -DEFAULT VALUE: - The default value is 3. +.. rubric:: NOTES: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The default value of three file descriptors allows RTEMS to support standard +input, output, and error I/O streams on :file:`/dev/console`. - * It shall be greater than or equal to zero. +.. 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 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 file - like objects that can be concurrently open. +* The value of the configuration option shall be less than or equal to + `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_. -NOTES: - The default value of three file descriptors allows RTEMS to support standard - input, output, and error I/O streams on :file:`/dev/console`. +* 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: @@ -333,40 +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: -OPTION TYPE: - This configuration option is an integer define. +CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE +------------------------------------------- -DEFAULT VALUE: - The default value is 1. +.. rubric:: CONSTANT: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +``CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE`` - * It shall be greater than or equal to one. +.. rubric:: OPTION TYPE: - * It shall be 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 @@ -375,43 +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 zero. +.. 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() <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: @@ -419,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 zero. +.. 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 @@ -466,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 zero. - - * It shall be less than or equal to a BSP-specific and application-specific - value which depends on the size of the memory available to the - application. - - * 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 @@ -551,55 +820,64 @@ NOTES: CONFIGURE_MICROSECONDS_PER_TICK ------------------------------- -CONSTANT: - ``CONFIGURE_MICROSECONDS_PER_TICK`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is an integer define. +``CONFIGURE_MICROSECONDS_PER_TICK`` -DEFAULT VALUE: - The default value is 10000. +.. 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 value defined by the :term:`Clock - Driver`. +.. rubric:: DEFAULT VALUE: - * It shall be less than or equal to a value defined by the :term:`Clock - Driver`. +The default value is 10000. - * The resulting clock ticks per second should be an integer. +.. rubric:: DESCRIPTION: -DESCRIPTION: - The value of this configuration option defines the length of time in - microseconds between clock ticks (clock tick quantum). +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. -NOTES: - This configuration option has no impact if the Clock Driver is not - configured, see :ref:`CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`. +.. rubric:: NOTES: - There may be Clock Driver specific limits on the resolution or maximum value - of a clock tick quantum. +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. + +.. 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 @@ -608,54 +886,64 @@ NOTES: CONFIGURE_MINIMUM_TASK_STACK_SIZE --------------------------------- -CONSTANT: - ``CONFIGURE_MINIMUM_TASK_STACK_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_MINIMUM_TASK_STACK_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 :c:macro:`CPU_STACK_MINIMUM_SIZE`. +The default value is :c:macro:`CPU_STACK_MINIMUM_SIZE`. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: DESCRIPTION: - * 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>`_. +The value of this configuration option defines the minimum stack size in +bytes for every user task or thread in the system. - * It shall be greater than or equal to a BSP-specific and - application-specific minimum value. +.. rubric:: NOTES: -DESCRIPTION: - The value of this configuration option defines the minimum stack size in - bytes for every user task or thread in the system. +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`). -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`). +This parameter can be used to lower the minimum from that recommended. This +can be used in low memory systems to reduce memory consumption for +stacks. However, this shall be done with caution as it could increase the +possibility of a blown task stack. - This parameter can be used to lower the minimum from that recommended. This - can be used in low memory systems to reduce memory consumption for - stacks. However, this shall be done with caution as it could increase the - possibility of a blown task stack. +This parameter can be used to increase the minimum from that +recommended. This can be used in higher memory systems to reduce the risk +of stack overflow without performing analysis on actual consumption. - This parameter can be used to increase the minimum from that - recommended. This can be used in higher memory systems to reduce the risk - of stack overflow without performing analysis on actual consumption. +By default, this configuration parameter defines also the minimum stack +size of POSIX threads. This can be changed with the +:ref:`CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE` +configuration option. - By default, this configuration parameter defines also the minimum stack - size of POSIX threads. This can be changed with the - :ref:`CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE` - configuration option. +In releases before RTEMS 5.1 the ``CONFIGURE_MINIMUM_TASK_STACK_SIZE`` was +used to define the default value of :ref:`CONFIGURE_INTERRUPT_STACK_SIZE`. - In releases before RTEMS 5.1 the ``CONFIGURE_MINIMUM_TASK_STACK_SIZE`` was - used to define the default value of :ref:`CONFIGURE_INTERRUPT_STACK_SIZE`. +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be small enough so that the task + stack space calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. + +* The value of the configuration option shall be greater than or equal to a + BSP-specific and application-specific minimum value. .. Generated from spec:/acfg/if/stack-checker-enabled +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_STACK_CHECKER_ENABLED .. _CONFIGURE_STACK_CHECKER_ENABLED: @@ -663,29 +951,38 @@ NOTES: CONFIGURE_STACK_CHECKER_ENABLED ------------------------------- -CONSTANT: - ``CONFIGURE_STACK_CHECKER_ENABLED`` +.. rubric:: CONSTANT: + +``CONFIGURE_STACK_CHECKER_ENABLED`` + +.. 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 stack checker is - enabled. +.. rubric:: DESCRIPTION: -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 case this configuration option is defined, then the stack checker is +enabled. - In 4.9 and older, this configuration option was named ``STACK_CHECKER_ON``. +.. 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 @@ -694,34 +991,43 @@ NOTES: CONFIGURE_TICKS_PER_TIMESLICE ----------------------------- -CONSTANT: - ``CONFIGURE_TICKS_PER_TIMESLICE`` +.. rubric:: CONSTANT: + +``CONFIGURE_TICKS_PER_TIMESLICE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 50. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is an integer define. +The value of this configuration option defines the length of the timeslice +quantum in ticks for each task. -DEFAULT VALUE: - The default value is 50. +.. rubric:: NOTES: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +This configuration option has no impact if the Clock Driver is not +configured, see :ref:`CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`. - * It shall be greater than or equal to zero. +.. 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: -DESCRIPTION: - The value of this configuration option defines the length of the timeslice - quantum in ticks for each task. +* The value of the configuration option shall be greater than or equal to one. -NOTES: - This configuration option has no impact if the Clock Driver is not - configured, see :ref:`CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`. +* 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 @@ -733,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: @@ -767,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: @@ -802,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: @@ -835,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 @@ -866,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 1234f42..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, 2021 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 800aa30..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, 2021 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. -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 number of bytes the +applications wishes to add to the MPCI task stack on top of +:ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: NOTES: - * It shall be greater than or equal to zero. +This configuration option is only evaluated if +:ref:`CONFIGURE_MP_APPLICATION` is defined. - * It shall be less than or equal to `UINT32_MAX - <https://en.cppreference.com/w/c/types/integer>`_. +.. rubric:: CONSTRAINTS: - * 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 following constraints apply to this configuration option: -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 greater than or equal to zero. -NOTES: - 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>`_. + +* 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: + +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 multiprocessing services +are not initialized. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the multiprocessing services - are not initialized. +.. rubric:: DESCRIPTION: -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. +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. -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:: 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,37 +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: -OPTION TYPE: - This configuration option is an integer define. +The default value is 32. -DEFAULT VALUE: - The default value is 32. +.. 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 +concurrently active global objects in a multiprocessor system. - * It shall be greater than or equal to zero. +.. rubric:: NOTES: - * It shall be less than or equal to `UINT32_MAX - <https://en.cppreference.com/w/c/types/integer>`_. +This value corresponds to the total number of objects which can be created +with the :c:macro:`RTEMS_GLOBAL` attribute. -DESCRIPTION: - The value of this configuration option defines the maximum number of - concurrently active global objects in a multiprocessor system. +This configuration option is only evaluated if +:ref:`CONFIGURE_MP_APPLICATION` is defined. -NOTES: - This value corresponds to the total number of objects which can be created - with the :c:macro:`RTEMS_GLOBAL` attribute. +.. rubric:: CONSTRAINTS: - This configuration option is only evaluated if - :ref:`CONFIGURE_MP_APPLICATION` 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 + `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: @@ -147,34 +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. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DEFAULT VALUE: -DEFAULT VALUE: - The default value is 2. +The default value is 2. -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 zero. +The value of this configuration option defines the maximum number of nodes in +a multiprocessor system. - * It shall be 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: @@ -182,40 +224,49 @@ NOTES: CONFIGURE_MP_MAXIMUM_PROXIES ---------------------------- -CONSTANT: - ``CONFIGURE_MP_MAXIMUM_PROXIES`` +.. rubric:: CONSTANT: + +``CONFIGURE_MP_MAXIMUM_PROXIES`` + +.. 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 32. +.. rubric:: DEFAULT VALUE: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The default value is 32. - * It shall be greater than or equal to zero. +.. rubric:: DESCRIPTION: - * It shall be less than or equal to `UINT32_MAX - <https://en.cppreference.com/w/c/types/integer>`_. +The value of this configuration option defines the maximum number of +concurrently active thread/task proxies on this node in a multiprocessor +system. -DESCRIPTION: - The value of this configuration option defines the maximum number of - concurrently active thread/task proxies on this node in a multiprocessor - system. +.. rubric:: NOTES: -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`. +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. +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: @@ -223,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: @@ -257,33 +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: -OPTION TYPE: - This configuration option is an integer define. +The value of this configuration option defines the node number of this node +in a multiprocessor system. -DEFAULT VALUE: - The default value is ``NODE_NUMBER``. +.. rubric:: NOTES: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +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. - * It shall be greater than or equal to zero. +This configuration option is only evaluated if +:ref:`CONFIGURE_MP_APPLICATION` is defined. - * It shall be 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 3c2c8a2..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, 2021 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 zero. +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 the object class, if the value passed to - :c:func:`rtems_resource_unlimited` satisfies all other constraints of the - 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 zero. +.. 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 the object class, if the value passed to - :c:func:`rtems_resource_unlimited` satisfies all other constraints of the - 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 zero. +.. 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 the object class, if the value passed to - :c:func:`rtems_resource_unlimited` satisfies all other constraints of the - 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,45 +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 zero. +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 ``RTEMS_POSIX_API = True`` 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: @@ -224,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 zero. +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 the object class, if the value passed to - :c:func:`rtems_resource_unlimited` satisfies all other constraints of the - 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: @@ -276,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 zero. +.. 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 the object class, if the value passed to - :c:func:`rtems_resource_unlimited` satisfies all other constraints of the - 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: @@ -323,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 zero. +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: @@ -375,49 +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 zero. +.. 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 the object class, if the value passed to - :c:func:`rtems_resource_unlimited` satisfies all other constraints of the - configuration option. +.. rubric:: CONSTRAINTS: - * It 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. +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 @@ -426,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 8623f2c..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, 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 @@ -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,35 +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: @@ -101,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 d78b14a..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, 2021 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,38 +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 zero. +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 @@ -97,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 equal to 3, 7, 31, 63, 127, - or 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: @@ -155,41 +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 the - :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 the - :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 the - :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 convertible to an 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 the - :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 the - :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 the - :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 the - :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,33 +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 the - :ref:`SchedulerSMPPrioritySimple` - 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: + +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: @@ -524,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 the 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: @@ -556,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 3f779ff..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, 2021 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 869fd4b..b96e3c7 100644 --- a/c-user/dual-ported-memory/directives.rst +++ b/c-user/dual-ported-memory/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 @@ -71,9 +71,9 @@ Creates a port. This parameter is the length in bytes of the memory area. ``id`` - This parameter is the pointer to an :c:type:`rtems_id` object. When the - directive call is successful, the identifier of the created port will be - stored in this object. + 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: @@ -158,9 +158,9 @@ Identifies a port by the object name. This parameter is the object name to look up. ``id`` - This parameter is the pointer to an :c:type:`rtems_id` object. When the - directive call is successful, the object identifier of an object with the - specified name will be stored in this object. + 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/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 fd7cc8e..515a1f1 100644 --- a/c-user/dual-ported-memory/introduction.rst +++ b/c-user/dual-ported-memory/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/event/directives.rst b/c-user/event/directives.rst index bf8f74c..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 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/background.rst b/c-user/fatal-error/background.rst index 6932846..e3d7320 100644 --- a/c-user/fatal-error/background.rst +++ b/c-user/fatal-error/background.rst @@ -316,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) @@ -356,3 +356,25 @@ INTERNAL_ERROR_TOO_LARGE_TLS_SIZE (41) :ref:`CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE <CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE>`. You can get the thread-local storage size of an application using the RTEMS tool ``rtems-execinfo``. + +INTERNAL_ERROR_RTEMS_INIT_TASK_CONSTRUCT_FAILED (42) + The construction of the RTEMS initialization task failed. This fatal error + may occur during system initialization. It is an application configuration + error. + +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 index 6aa4b20..434172f 100644 --- a/c-user/fatal-error/directives.rst +++ b/c-user/fatal-error/directives.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2015, 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. 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 diff --git a/c-user/fatal-error/index.rst b/c-user/fatal-error/index.rst index 89cbe30..40eca3b 100644 --- a/c-user/fatal-error/index.rst +++ b/c-user/fatal-error/index.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2021 embedded brains GmbH & Co. KG .. index:: fatal errors diff --git a/c-user/fatal-error/introduction.rst b/c-user/fatal-error/introduction.rst index ff86922..fc310f4 100644 --- a/c-user/fatal-error/introduction.rst +++ b/c-user/fatal-error/introduction.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2015, 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. 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 diff --git a/c-user/glossary.rst b/c-user/glossary.rst index 9274cf3..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 @@ -244,12 +260,15 @@ Glossary 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 :c:func:`rtems_extension_create`. See also + 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>`_. @@ -342,9 +361,21 @@ Glossary 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/>`_. @@ -352,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`. @@ -359,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 @@ -402,7 +461,7 @@ Glossary 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. @@ -472,6 +531,10 @@ Glossary 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. @@ -481,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 @@ -502,6 +571,9 @@ Glossary 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. @@ -543,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. @@ -590,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 @@ -600,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. @@ -689,7 +777,8 @@ Glossary 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 @@ -739,8 +828,8 @@ Glossary 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 - :c:func:`rtems_task_set_priority` and - :c:func:`rtems_task_set_scheduler`. The real priority is the foundation + :ref:`InterfaceRtemsTaskSetPriority` and + :ref:`InterfaceRtemsTaskSetScheduler`. The real priority is the foundation of the :term:`current priority`. real-time @@ -753,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. @@ -765,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. @@ -812,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. @@ -848,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. @@ -868,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`. @@ -945,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 @@ -982,6 +1098,15 @@ 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. @@ -1012,6 +1137,15 @@ 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. diff --git a/c-user/index.rst b/c-user/index.rst index 385ea95..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 @@ -51,6 +51,7 @@ RTEMS Classic API Guide (|version|). user-extensions/index config/index self_contained_objects + regulator/index multiprocessing/index symmetric_multiprocessing_services pci_library diff --git a/c-user/initialization/directives.rst b/c-user/initialization/directives.rst index ca5c9c2..bb3fa95 100644 --- a/c-user/initialization/directives.rst +++ b/c-user/initialization/directives.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2015, 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. 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 diff --git a/c-user/initialization/index.rst b/c-user/initialization/index.rst index b41fcdd..cbca400 100644 --- a/c-user/initialization/index.rst +++ b/c-user/initialization/index.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2021 embedded brains GmbH & Co. KG .. _RTEMSAPIClassicInit: diff --git a/c-user/initialization/introduction.rst b/c-user/initialization/introduction.rst index 173e60f..15722f6 100644 --- a/c-user/initialization/introduction.rst +++ b/c-user/initialization/introduction.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2015, 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. 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 diff --git a/c-user/initialization/operations.rst b/c-user/initialization/operations.rst index db5c94b..e7d310c 100644 --- a/c-user/initialization/operations.rst +++ b/c-user/initialization/operations.rst @@ -285,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 diff --git a/c-user/interrupt/directives.rst b/c-user/interrupt/directives.rst index 2d7dccf..80eddfd 100644 --- a/c-user/interrupt/directives.rst +++ b/c-user/interrupt/directives.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2008, 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. 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 @@ -63,9 +63,10 @@ Establishes an interrupt service routine. This parameter is the interrupt vector number. ``old_isr_handler`` - This parameter is the pointer to an :c:type:`rtems_isr_entry` object. When - the directive call is successful, the previous interrupt service routine - established for this interrupt vector will be stored in this object. + 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: @@ -128,13 +129,13 @@ Disables the maskable interrupts on the current processor. .. code-block:: c - #define rtems_interrupt_disable( isr_cookie ) + void rtems_interrupt_disable( rtems_interrupt_level isr_cookie ); .. rubric:: PARAMETERS: ``isr_cookie`` - This parameter is a variable of type :c:type:`rtems_interrupt_level` which - will be used to save the previous interrupt level. + This parameter is a variable of type :ref:`InterfaceRtemsInterruptLevel` + which will be used to save the previous interrupt level. .. rubric:: DESCRIPTION: @@ -218,7 +219,7 @@ Restores the previous interrupt level on the current processor. .. code-block:: c - #define rtems_interrupt_enable( isr_cookie ) + void rtems_interrupt_enable( rtems_interrupt_level isr_cookie ); .. rubric:: PARAMETERS: @@ -280,7 +281,7 @@ Flashes interrupts on the current processor. .. code-block:: c - #define rtems_interrupt_flash( isr_cookie ) + void rtems_interrupt_flash( rtems_interrupt_level isr_cookie ); .. rubric:: PARAMETERS: @@ -338,13 +339,13 @@ Disables the maskable interrupts on the current processor. .. code-block:: c - #define rtems_interrupt_local_disable( isr_cookie ) + void rtems_interrupt_local_disable( rtems_interrupt_level isr_cookie ); .. rubric:: PARAMETERS: ``isr_cookie`` - This parameter is a variable of type :c:type:`rtems_interrupt_level` which - will be used to save the previous interrupt level. + This parameter is a variable of type :ref:`InterfaceRtemsInterruptLevel` + which will be used to save the previous interrupt level. .. rubric:: DESCRIPTION: @@ -428,7 +429,7 @@ Restores the previous interrupt level on the current processor. .. code-block:: c - #define rtems_interrupt_local_enable( isr_cookie ) + void rtems_interrupt_local_enable( rtems_interrupt_level isr_cookie ); .. rubric:: PARAMETERS: @@ -484,7 +485,7 @@ Checks if an ISR is in progress on the current processor. .. code-block:: c - #define rtems_interrupt_is_in_progress() + bool rtems_interrupt_is_in_progress( void ); .. rubric:: DESCRIPTION: @@ -525,7 +526,10 @@ Initializes the ISR lock. .. code-block:: c - #define rtems_interrupt_lock_initialize( lock, name ) + void rtems_interrupt_lock_initialize( + rtems_interrupt_lock *lock, + const char *name + ); .. rubric:: PARAMETERS: @@ -561,7 +565,7 @@ Destroys the ISR lock. .. code-block:: c - #define rtems_interrupt_lock_destroy( lock ) + void rtems_interrupt_lock_destroy( rtems_interrupt_lock *lock ); .. rubric:: PARAMETERS: @@ -605,7 +609,10 @@ Acquires the ISR lock. .. code-block:: c - #define rtems_interrupt_lock_acquire( lock, lock_context ) + void rtems_interrupt_lock_acquire( + rtems_interrupt_lock *lock, + rtems_interrupt_lock_context *lock_context + ); .. rubric:: PARAMETERS: @@ -679,7 +686,7 @@ Releases the ISR lock. .. code-block:: c - #define rtems_interrupt_lock_release( lock, lock_context ) + void rtems_interrupt_lock_release( rtems_interrupt_lock_context *lock ); .. rubric:: PARAMETERS: @@ -737,7 +744,10 @@ Acquires the ISR lock from within an ISR. .. code-block:: c - #define rtems_interrupt_lock_acquire_isr( lock, lock_context ) + void rtems_interrupt_lock_acquire_isr( + rtems_interrupt_lock *lock, + rtems_interrupt_lock_context *lock_context + ); .. rubric:: PARAMETERS: @@ -800,7 +810,10 @@ Releases the ISR lock from within an ISR. .. code-block:: c - #define rtems_interrupt_lock_release_isr( lock, lock_context ) + void rtems_interrupt_lock_release_isr( + rtems_interrupt_lock *lock, + rtems_interrupt_lock_context *lock_context + ); .. rubric:: PARAMETERS: @@ -853,7 +866,9 @@ Disables maskable interrupts on the current processor. .. code-block:: c - #define rtems_interrupt_lock_interrupt_disable( lock_context ) + void rtems_interrupt_lock_interrupt_disable( + rtems_interrupt_lock_context *lock_context + ); .. rubric:: PARAMETERS: @@ -892,7 +907,7 @@ Declares an ISR lock object. .. code-block:: c - #define RTEMS_INTERRUPT_LOCK_DECLARE( specifier, designator ) + RTEMS_INTERRUPT_LOCK_DECLARE( specifier, designator ); .. rubric:: PARAMETERS: @@ -926,7 +941,7 @@ Defines an ISR lock object. .. code-block:: c - #define RTEMS_INTERRUPT_LOCK_DEFINE( specifier, designator, name ) + RTEMS_INTERRUPT_LOCK_DEFINE( specifier, designator, const char *name ); .. rubric:: PARAMETERS: @@ -968,7 +983,7 @@ Statically initializes an ISR lock object. .. code-block:: c - #define RTEMS_INTERRUPT_LOCK_INITIALIZER( name ) + RTEMS_INTERRUPT_LOCK_INITIALIZER( const char *name ); .. rubric:: PARAMETERS: @@ -1001,7 +1016,7 @@ Defines an ISR lock member. .. code-block:: c - #define RTEMS_INTERRUPT_LOCK_MEMBER( designator ) + RTEMS_INTERRUPT_LOCK_MEMBER( designator ); .. rubric:: PARAMETERS: @@ -1031,7 +1046,7 @@ Defines an ISR lock object reference. .. code-block:: c - #define RTEMS_INTERRUPT_LOCK_REFERENCE( designator, target ) + RTEMS_INTERRUPT_LOCK_REFERENCE( designator, rtems_interrupt_lock *target ); .. rubric:: PARAMETERS: @@ -1064,7 +1079,11 @@ Statically initializes an interrupt entry object. .. code-block:: c - #define RTEMS_INTERRUPT_ENTRY_INITIALIZER( routine, arg, info ) + RTEMS_INTERRUPT_ENTRY_INITIALIZER( + rtems_interrupt_handler routine, + void *arg, + const char *info + ); .. rubric:: PARAMETERS: @@ -2123,6 +2142,11 @@ Sets the processor affinity set of the interrupt vector. 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: @@ -2165,9 +2189,10 @@ Gets the attributes of the interrupt vector. This parameter is the interrupt vector number. ``attributes`` - This parameter is the pointer to an :c:type:`rtems_interrupt_attributes` - object. When the directive call is successful, the attributes of the - interrupt vector will be stored in this object. + 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: @@ -2395,9 +2420,9 @@ Creates an interrupt server. ``control`` This parameter is the pointer to an - :c:type:`rtems_interrupt_server_control` 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. + :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. 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 7987b54..14ea275 100644 --- a/c-user/interrupt/introduction.rst +++ b/c-user/interrupt/introduction.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2008, 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. 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 diff --git a/c-user/io/directives.rst b/c-user/io/directives.rst index d308944..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,7 +64,7 @@ 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 an :c:type:`rtems_device_major_number` + 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. 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 index f13010e..e0476fe 100644 --- a/c-user/kernel-character-io/directives.rst +++ b/c-user/kernel-character-io/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) 2015 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/index.rst b/c-user/kernel-character-io/index.rst index c6a9b6b..2d1d13b 100644 --- a/c-user/kernel-character-io/index.rst +++ b/c-user/kernel-character-io/index.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2021 embedded brains GmbH & Co. KG .. index:: Kernel Character I/O Support diff --git a/c-user/kernel-character-io/introduction.rst b/c-user/kernel-character-io/introduction.rst index ef3512b..dc3ac26 100644 --- a/c-user/kernel-character-io/introduction.rst +++ b/c-user/kernel-character-io/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) 2015 On-Line Applications Research Corporation (OAR) .. This file is part of the RTEMS quality process and was automatically 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 7317eb4..7039b2e 100644 --- a/c-user/message/directives.rst +++ b/c-user/message/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 @@ -72,9 +72,9 @@ Creates a message queue. This parameter is the attribute set of the message queue. ``id`` - This parameter is the pointer to an :c:type:`rtems_id` object. When the - directive call is successful, the identifier of the created message queue - will be stored in this object. + 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: @@ -230,11 +230,12 @@ Constructs a message queue from the specified the message queue configuration. .. rubric:: PARAMETERS: ``config`` - This parameter is the message queue configuration. + This parameter is the pointer to an :ref:`InterfaceRtemsMessageQueueConfig` + object. It configures the message queue. ``id`` - This parameter is the pointer to an :c:type:`rtems_id` object. When the - directive call is successful, the identifier of the constructed message + 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: @@ -361,9 +362,9 @@ Identifies a message queue 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 :c:type:`rtems_id` object. When the - directive call is successful, the object identifier of an object with the - specified name will be stored in this object. + 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: @@ -727,7 +728,7 @@ Broadcasts the messages to the tasks waiting at the queue. 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 +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``. @@ -1014,8 +1015,8 @@ Flushes all messages on the queue. ``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. + directive call is successful, the number of pending messages removed from + the queue will be stored in this object. .. rubric:: DESCRIPTION: @@ -1072,7 +1073,7 @@ the specified maximum size. .. code-block:: c - #define RTEMS_MESSAGE_QUEUE_BUFFER( maximum_message_size ) + RTEMS_MESSAGE_QUEUE_BUFFER( size_t maximum_message_size ); .. rubric:: PARAMETERS: 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 89fbfca..989cd33 100644 --- a/c-user/message/introduction.rst +++ b/c-user/message/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/multiprocessing/directives.rst b/c-user/multiprocessing/directives.rst index fc10640..a12599c 100644 --- a/c-user/multiprocessing/directives.rst +++ b/c-user/multiprocessing/directives.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. 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 diff --git a/c-user/multiprocessing/index.rst b/c-user/multiprocessing/index.rst index 4ec4433..351105d 100644 --- a/c-user/multiprocessing/index.rst +++ b/c-user/multiprocessing/index.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2021 embedded brains GmbH & Co. KG .. index:: multiprocessing diff --git a/c-user/multiprocessing/introduction.rst b/c-user/multiprocessing/introduction.rst index 742a034..45c90bd 100644 --- a/c-user/multiprocessing/introduction.rst +++ b/c-user/multiprocessing/introduction.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. 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 diff --git a/c-user/object-services/directives.rst b/c-user/object-services/directives.rst index c975c75..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 :c:type:`rtems_name` object. When the - directive call is successful, the object name associated with the object - identifier will be stored in this object. + 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: @@ -802,7 +802,7 @@ Gets the object class information of the object class of the object API. ``info`` This parameter is the pointer to an - :c:type:`rtems_object_api_class_information` object. When the directive + :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. @@ -879,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 534cfb4..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 :c:type:`rtems_id` object. When the - directive call is successful, the identifier of the created partition will - be stored in this object. + 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 :c:type:`rtems_id` object. When the - directive call is successful, the object identifier of an object with the - specified name will be stored in this object. + 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/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 c81af4e..af54591 100644 --- a/c-user/rate-monotonic/background.rst +++ b/c-user/rate-monotonic/background.rst @@ -222,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. @@ -290,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 2e48aac..f0467d1 100644 --- a/c-user/rate-monotonic/directives.rst +++ b/c-user/rate-monotonic/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) 2017 Kuan-Hsun Chen .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) @@ -56,9 +56,9 @@ Creates a period. This parameter is the object name of the period. ``id`` - This parameter is the pointer to an :c:type:`rtems_id` object. When the - directive call is successful, the identifier of the created period will be - stored in this object. + 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: @@ -133,9 +133,9 @@ Identifies a period by the object name. This parameter is the object name to look up. ``id`` - This parameter is the pointer to an :c:type:`rtems_id` object. When the - directive call is successful, the object identifier of an object with the - specified name will be stored in this object. + 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: @@ -366,6 +366,11 @@ length of the period. :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: @@ -408,7 +413,7 @@ Gets the detailed status of the period. ``status`` This parameter is the pointer to an - :c:type:`rtems_rate_monotonic_period_status` object. When the directive + :ref:`InterfaceRtemsRateMonotonicPeriodStatus` object. When the directive call is successful, the detailed period status will be stored in this object. @@ -448,10 +453,6 @@ members of the period status object referenced by ``status``: The ``status`` parameter was `NULL <https://en.cppreference.com/w/c/types/NULL>`_. -:c:macro:`RTEMS_NOT_DEFINED` - There was no status available due to a reset of the processor time usage of - the owner task of the period. - .. rubric:: CONSTRAINTS: The following constraints apply to this directive: @@ -495,7 +496,7 @@ Gets the statistics of the period. ``status`` This parameter is the pointer to an - :c:type:`rtems_rate_monotonic_period_statistics` object. When the + :ref:`InterfaceRtemsRateMonotonicPeriodStatistics` object. When the directive call is successful, the period statistics will be stored in this object. 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 9e3c6f0..b33b0b8 100644 --- a/c-user/rate-monotonic/introduction.rst +++ b/c-user/rate-monotonic/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) 2017 Kuan-Hsun Chen .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) diff --git a/c-user/region/directives.rst b/c-user/region/directives.rst index 5a03e6a..557b89e 100644 --- a/c-user/region/directives.rst +++ b/c-user/region/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 @@ -77,9 +77,9 @@ Creates a region. This parameter is the attribute set of the region. ``id`` - This parameter is the pointer to an :c:type:`rtems_id` object. When the - directive call is successful, the identifier of the created region will be - stored in this object. + 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: @@ -193,9 +193,9 @@ Identifies a region by the object name. This parameter is the object name to look up. ``id`` - This parameter is the pointer to an :c:type:`rtems_id` object. When the - directive call is successful, the object identifier of an object with the - specified name will be stored in this object. + 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: @@ -713,9 +713,9 @@ Gets the region information. This parameter is the region identifier. ``the_info`` - This parameter is the pointer to a Heap_Information_block object. When the - directive call is successful, the information of the region will be stored - in this object. + 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: @@ -788,9 +788,9 @@ Gets the region free information. This parameter is the region identifier. ``the_info`` - This parameter is the pointer to a Heap_Information_block object. When the - directive call is successful, the free information of the region will be - stored in this object. + 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: 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 8075a84..ec44d2e 100644 --- a/c-user/region/introduction.rst +++ b/c-user/region/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/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 1fe7089..38b77ee 100644 --- a/c-user/scheduling-concepts/background.rst +++ b/c-user/scheduling-concepts/background.rst @@ -160,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 @@ -243,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 @@ -280,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 aa0300e..115b4fa 100644 --- a/c-user/scheduling-concepts/directives.rst +++ b/c-user/scheduling-concepts/directives.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2013, 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. 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 @@ -54,8 +54,8 @@ Identifies a scheduler by the object name. This parameter is the scheduler name to look up. ``id`` - This parameter is the pointer to an :c:type:`rtems_id` object. When the - directive call is successful, the identifier of the scheduler will be + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the identifier of the scheduler will be stored in this object. .. rubric:: DESCRIPTION: @@ -120,8 +120,8 @@ Identifies a scheduler by the processor index. This parameter is the processor index to identify the scheduler. ``id`` - This parameter is the pointer to an :c:type:`rtems_id` object. When the - directive call is successful, the identifier of the scheduler will be + 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: @@ -184,8 +184,8 @@ Identifies a scheduler by the processor set. processor set will be used to identify the scheduler. ``id`` - This parameter is the pointer to an :c:type:`rtems_id` object. When the - directive call is successful, the identifier of the scheduler will be + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the identifier of the scheduler will be stored in this object. .. rubric:: DESCRIPTION: @@ -254,9 +254,9 @@ Gets the maximum task priority of the scheduler. This parameter is the scheduler identifier. ``priority`` - This parameter is the pointer to an :c:type:`rtems_task_priority` object. - When the directive the maximum priority of the scheduler will be stored in - this object. + This parameter is the pointer to an :ref:`InterfaceRtemsTaskPriority` + object. When the directive the maximum priority of the scheduler will be + stored in this object. .. rubric:: RETURN VALUES: @@ -375,10 +375,10 @@ Maps a POSIX thread priority to the corresponding Classic API task priority. This parameter is the POSIX thread priority to map. ``priority`` - This parameter is the pointer to an :c:type:`rtems_task_priority` 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. + This parameter is the pointer to an :ref:`InterfaceRtemsTaskPriority` + object. When the directive call is successful, the Classic API task + priority value corresponding to the specified POSIX thread priority value + will be stored in this object. .. rubric:: RETURN VALUES: @@ -683,9 +683,12 @@ scheduler specified by ``scheduler_id``. The processor was not owned by the scheduler. :c:macro:`RTEMS_RESOURCE_IN_USE` - The set of processors owned by the scheduler would have been empty after - the processor removal and there was at least one non-idle task that used - this scheduler as its :term:`home scheduler`. + 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: 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 31de1c1..527d103 100644 --- a/c-user/scheduling-concepts/introduction.rst +++ b/c-user/scheduling-concepts/introduction.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2013, 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. 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 diff --git a/c-user/self_contained_objects.rst b/c-user/self_contained_objects.rst index 10d2b91..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 ********************** diff --git a/c-user/semaphore/directives.rst b/c-user/semaphore/directives.rst index 5a66ac1..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 :c:type:`rtems_id` object. When the - directive call is successful, the identifier of the created semaphore will - be stored in this object. + 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 :c:type:`rtems_id` object. When the - directive call is successful, the object identifier of an object with the - specified name will be stored in this object. + 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: @@ -862,9 +862,10 @@ Sets the priority by scheduler for the semaphore. scheduler. ``old_priority`` - This parameter is the pointer to an :c:type:`rtems_task_priority` object. - When the directive call is successful, the old priority of the semaphore - corresponding to the specified scheduler will be stored in this object. + 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: 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 da6cabf..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 @@ -233,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 e544525..d976905 100644 --- a/c-user/task/directives.rst +++ b/c-user/task/directives.rst @@ -1,7 +1,7 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) -.. Copyright (C) 1988, 2017 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 @@ -74,9 +74,9 @@ Creates a task. This parameter is the attribute set of the task. ``id`` - This parameter is the pointer to an :c:type:`rtems_id` object. When the - directive call is successful, the identifier of the created task will be - stored in this object. + 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: @@ -86,9 +86,9 @@ 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 -scheduler of the created task is the scheduler of the calling task at some -point during the task creation. The initial task priority specified in -``initial_priority`` shall be valid for this scheduler. +: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 @@ -332,12 +332,13 @@ Constructs a task from the specified task configuration. .. rubric:: PARAMETERS: ``config`` - This parameter is the task configuration. + This parameter is the pointer to an :ref:`InterfaceRtemsTaskConfig` object. + It configures the task. ``id`` - This parameter is the pointer to an :c:type:`rtems_id` object. When the - directive call is successful, the identifier of the constructed task will - be stored in this object. + 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: @@ -407,9 +408,9 @@ 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 +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. @@ -475,17 +476,17 @@ Identifies a task 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 :c:type:`rtems_id` object. When the - directive call is successful, the object identifier of an object with the - specified name will be stored in this object. + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the object identifier of an object with + the specified name will be stored in this object. .. rubric:: DESCRIPTION: This directive obtains a task identifier associated with the task name specified in ``name``. -A task may obtain its own identifier by specifying :c:macro:`RTEMS_SELF` for -the name. +A task may obtain its own identifier by specifying :c:macro:`RTEMS_WHO_AM_I` +for the name. The node to search is specified in ``node``. It shall be @@ -623,9 +624,9 @@ Starts the task. .. 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 entry -point of the task is given in ``entry_point``. The task's entry point argument -is contained in ``argument``. +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: @@ -805,14 +806,26 @@ 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: -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 -:c:macro:`RTEMS_FLOATING_POINT`, its floating point context area. RTEMS +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. @@ -824,10 +837,13 @@ 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 (:c:macro:`RTEMS_SELF`) will force RTEMS to select +Deletion of the calling task (:c:macro:`RTEMS_SELF`) will force RTEMS to select another task to execute. -The :term:`TCB` for the deleted task is reclaimed by RTEMS. +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. @@ -1147,10 +1163,10 @@ Sets the real priority or gets the current priority of the task. :c:macro:`RTEMS_CURRENT_PRIORITY` to get the current priority. ``old_priority`` - This parameter is the pointer to an :c:type:`rtems_task_priority` 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. + 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: @@ -1246,9 +1262,9 @@ Gets the current priority of the task with respect to the scheduler. This parameter is the scheduler identifier. ``priority`` - This parameter is the pointer to an :c:type:`rtems_task_priority` 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. + 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: @@ -1459,16 +1475,16 @@ The following constraints apply to this directive: \clearpage .. index:: rtems_task_wake_after() -.. index:: delay a task for an interval -.. index:: wake up after an interval +.. 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 an interval in :term:`clock ticks <clock tick>` or yields the -processor. +Wakes up after a count of :term:`clock ticks <clock tick>` have occurred or +yields the processor. .. rubric:: CALLING SEQUENCE: @@ -1479,16 +1495,16 @@ processor. .. rubric:: PARAMETERS: ``ticks`` - This parameter is the interval in :term:`clock ticks <clock tick>` to delay + This parameter is the count of :term:`clock ticks <clock tick>` to delay the task or :c:macro:`RTEMS_YIELD_PROCESSOR` to yield the processor. .. rubric:: DESCRIPTION: -This directive blocks the calling task for the specified ``ticks`` of clock -ticks if the value is not equal to :c:macro:`RTEMS_YIELD_PROCESSOR`. When the -requested interval has elapsed, the task is made ready. The clock tick -directives automatically updates the delay period. The calling task may give -up the processor and remain in the ready state by specifying a value of +This directive blocks the calling task for the specified ``ticks`` count of +clock ticks if the value is not equal to :c:macro:`RTEMS_YIELD_PROCESSOR`. When +the requested count of ticks have occurred, the task is made ready. The clock +tick directives automatically update the delay period. The calling task may +give up the processor and remain in the ready state by specifying a value of :c:macro:`RTEMS_YIELD_PROCESSOR` in ``ticks``. .. rubric:: RETURN VALUES: @@ -1500,7 +1516,12 @@ up the processor and remain in the ready state by specifying a value of 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. +effect on a :ref:`InterfaceRtemsTaskWakeAfter` blocked task. The delay until +first clock tick will never be a whole clock tick interval since this directive +will never execute exactly on a clock tick. Applications requiring use of a +clock (:term:`CLOCK_REALTIME` or :term:`CLOCK_MONOTONIC`) instead of clock +ticks should make use of `clock_nanosleep() +<https://pubs.opengroup.org/onlinepubs/9699919799/functions/clock_nanosleep.html>`_. .. rubric:: CONSTRAINTS: @@ -1615,9 +1636,9 @@ Gets the home scheduler of the task. may be used to specify the calling task. ``scheduler_id`` - This parameter is the pointer to an :c:type:`rtems_id` object. When the - directive call is successful, the identifier of the :term:`home scheduler` - of the task will be stored in this object. + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the identifier of the :term:`home + scheduler` of the task will be stored in this object. .. rubric:: DESCRIPTION: @@ -1976,7 +1997,7 @@ Gets the recommended task storage area size for the size and task attributes. .. code-block:: c - #define RTEMS_TASK_STORAGE_SIZE( size, attributes ) + size_t RTEMS_TASK_STORAGE_SIZE( size_t size, rtems_attribute attributes ); .. rubric:: 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 5d6eba4..f174b42 100644 --- a/c-user/task/introduction.rst +++ b/c-user/task/introduction.rst @@ -1,7 +1,7 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) -.. Copyright (C) 1988, 2017 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 @@ -84,8 +84,8 @@ and administer tasks. The directives provided by the Task Manager are: * :ref:`InterfaceRtemsTaskMode` - Gets and optionally sets the mode of the calling task. -* :ref:`InterfaceRtemsTaskWakeAfter` - Wakes up after an interval in - :term:`clock ticks <clock tick>` or yields the processor. +* :ref:`InterfaceRtemsTaskWakeAfter` - Wakes up after a count of :term:`clock + ticks <clock tick>` have occurred or yields the processor. * :ref:`InterfaceRtemsTaskWakeWhen` - Wakes up when specified. 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 f020de4..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 :c:type:`rtems_id` object. When the - directive call is successful, the identifier of the created timer will be - stored in this object. + 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 :c:type:`rtems_id` object. When the - directive call is successful, the object identifier of an object with the - specified name will be stored in this object. + 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: @@ -811,7 +811,7 @@ Gets information about the timer. This parameter is the timer identifier. ``the_info`` - This parameter is the pointer to an :c:type:`rtems_timer_information` + 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. 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 5aa747b..c1430a9 100644 --- a/c-user/user-extensions/background.rst +++ b/c-user/user-extensions/background.rst @@ -143,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 ac04cdd..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 :c:type:`rtems_id` object. When the - directive call is successful, the identifier of the created extension set - will be stored in this object. + 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: @@ -219,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 :c:type:`rtems_id` object. When the - directive call is successful, the object identifier of an object with the - specified name will be stored in this object. + 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 |