summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--bsp-howto/index.rst1
-rw-r--r--bsp-howto/target-hash.rst17
-rw-r--r--c-user/barrier/directives.rst3
-rw-r--r--c-user/clock/directives.rst7
-rw-r--r--c-user/config/bdbuf.rst94
-rw-r--r--c-user/config/bsp-related.rst26
-rw-r--r--c-user/config/classic-api.rst176
-rw-r--r--c-user/config/classic-init-task.rst28
-rw-r--r--c-user/config/device-driver.rst18
-rw-r--r--c-user/config/event-record.rst11
-rw-r--r--c-user/config/filesystem.rst6
-rw-r--r--c-user/config/general.rst116
-rw-r--r--c-user/config/idle-task.rst12
-rw-r--r--c-user/config/mpci.rst50
-rw-r--r--c-user/config/posix-api.rst168
-rw-r--r--c-user/config/posix-init-thread.rst11
-rw-r--r--c-user/config/scheduler-general.rst49
-rw-r--r--c-user/config/task-stack-alloc.rst6
-rw-r--r--c-user/dual-ported-memory/directives.rst500
-rw-r--r--c-user/dual-ported-memory/introduction.rst43
-rw-r--r--c-user/event/directives.rst3
-rw-r--r--c-user/fatal-error/background.rst (renamed from c-user/fatal_error.rst)302
-rw-r--r--c-user/fatal-error/directives.rst355
-rw-r--r--c-user/fatal-error/index.rst17
-rw-r--r--c-user/fatal-error/introduction.rst57
-rw-r--r--c-user/fatal-error/operations.rst51
-rw-r--r--c-user/glossary.rst49
-rw-r--r--c-user/index.rst6
-rw-r--r--c-user/initialization/background.rst48
-rw-r--r--c-user/initialization/directives.rst69
-rw-r--r--c-user/initialization/index.rst15
-rw-r--r--c-user/initialization/introduction.rst39
-rw-r--r--c-user/initialization/operations.rst (renamed from c-user/initialization.rst)98
-rw-r--r--c-user/interrupt/directives.rst1250
-rw-r--r--c-user/interrupt/introduction.rst101
-rw-r--r--c-user/message/directives.rst1459
-rw-r--r--c-user/message/introduction.rst67
-rw-r--r--c-user/multiprocessing/background.rst (renamed from c-user/multiprocessing.rst)89
-rw-r--r--c-user/multiprocessing/directives.rst75
-rw-r--r--c-user/multiprocessing/index.rst17
-rw-r--r--c-user/multiprocessing/introduction.rst61
-rw-r--r--c-user/multiprocessing/operations.rst13
-rw-r--r--c-user/rate-monotonic/background.rst4
-rw-r--r--c-user/rate-monotonic/directives.rst949
-rw-r--r--c-user/rate-monotonic/introduction.rst71
-rw-r--r--c-user/region/directives.rst1271
-rw-r--r--c-user/region/introduction.rst58
-rw-r--r--c-user/scheduling-concepts/directives.rst889
-rw-r--r--c-user/scheduling-concepts/introduction.rst86
-rw-r--r--c-user/semaphore/directives.rst24
-rw-r--r--c-user/task/directives.rst2842
-rw-r--r--c-user/task/introduction.rst104
-rw-r--r--c-user/timer/directives.rst9
-rw-r--r--c-user/user-extensions/background.rst13
-rw-r--r--eng/req/items.rst108
-rw-r--r--legacy-networking/index.rst1
-rw-r--r--legacy-networking/quick_start.rst33
-rw-r--r--user/bsps/arm/beagle.rst41
58 files changed, 7809 insertions, 4277 deletions
diff --git a/bsp-howto/index.rst b/bsp-howto/index.rst
index e95c1b8..d095fc7 100644
--- a/bsp-howto/index.rst
+++ b/bsp-howto/index.rst
@@ -28,6 +28,7 @@ RTEMS BSP and Driver Guide (|version|).
initilization_code
console
clock
+ target-hash
getentropy
i2c
spi
diff --git a/bsp-howto/target-hash.rst b/bsp-howto/target-hash.rst
new file mode 100644
index 0000000..bcb651b
--- /dev/null
+++ b/bsp-howto/target-hash.rst
@@ -0,0 +1,17 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2021 embedded brains GmbH <rtems@embedded-brains.de>
+
+Target Hash
+***********
+
+Each BSP must provide an implementation of the :c:func:`rtems_get_target_hash`
+directive. The
+`default implementation <https://git.rtems.org/rtems/tree/bsps/shared/start/gettargethash-default.c>`_
+is based on the CPU counter frequency. A BSP-specific implementation may be
+provided which covers also for example the device tree, settings of the memory
+controller, processor and bus frequencies, a serial number of a chip, etc. For
+a BSP-specific implementation start with the default implementation and add
+more values to the target hash using the functions :c:func:`_Hash_Add_data` and
+:c:func:`_Hash_Add_string`. The target hash can be used to distinguish test
+suite results obtained from different target systems.
diff --git a/c-user/barrier/directives.rst b/c-user/barrier/directives.rst
index 84dacc4..ec40844 100644
--- a/c-user/barrier/directives.rst
+++ b/c-user/barrier/directives.rst
@@ -410,4 +410,5 @@ The following constraints apply to this directive:
* The directive may be called from within task context.
-* The directive may unblock another task which may preempt the calling task.
+* The directive may unblock a task. This may cause the calling task to be
+ preempted.
diff --git a/c-user/clock/directives.rst b/c-user/clock/directives.rst
index a13b5ef..4ed1c58 100644
--- a/c-user/clock/directives.rst
+++ b/c-user/clock/directives.rst
@@ -96,10 +96,11 @@ The following constraints apply to this directive:
* The directive may be called from within any runtime context.
-* The directive may change the priority of another task which may preempt the
- calling task.
+* The directive may change the priority of a task. This may cause the calling
+ task to be preempted.
-* The directive may unblock another task which may preempt the calling task.
+* The directive may unblock a task. This may cause the calling task to be
+ preempted.
.. Generated from spec:/rtems/clock/if/get-tod
diff --git a/c-user/config/bdbuf.rst b/c-user/config/bdbuf.rst
index 7377bee..c5381e1 100644
--- a/c-user/config/bdbuf.rst
+++ b/c-user/config/bdbuf.rst
@@ -1,6 +1,6 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
-.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+.. Copyright (C) 2020, 2021 embedded brains GmbH (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
@@ -76,9 +76,10 @@ VALUE CONSTRAINTS:
The value of this configuration option shall satisfy all of the following
constraints:
- * It shall be greater than or equal to 0.
+ * It shall be greater than or equal to zero.
- * It shall be an integral multiple of :ref:`CONFIGURE_BDBUF_BUFFER_MIN_SIZE`.
+ * It shall be an integral multiple of
+ :ref:`CONFIGURE_BDBUF_BUFFER_MIN_SIZE`.
DESCRIPTION:
The value of this configuration option defines the maximum size of a buffer
@@ -106,8 +107,13 @@ DEFAULT VALUE:
The default value is 512.
VALUE CONSTRAINTS:
- The value of this configuration option shall be greater than or equal to 0
- and less than or equal to `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_.
+ 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 `UINT32_MAX
+ <https://en.cppreference.com/w/c/types/integer>`_.
DESCRIPTION:
The value of this configuration option defines the minimum size of a buffer
@@ -135,8 +141,13 @@ DEFAULT VALUE:
The default value is 32768.
VALUE CONSTRAINTS:
- The value of this configuration option shall be greater than or equal to 0
- and less than or equal to `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_.
+ 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 `SIZE_MAX
+ <https://en.cppreference.com/w/c/types/limits>`_.
DESCRIPTION:
The value of this configuration option defines the size of the cache memory
@@ -164,8 +175,13 @@ DEFAULT VALUE:
The default value is 0.
VALUE CONSTRAINTS:
- The value of this configuration option shall be greater than or equal to 0
- and less than or equal to `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_.
+ 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 `UINT32_MAX
+ <https://en.cppreference.com/w/c/types/integer>`_.
DESCRIPTION:
The value of this configuration option defines the maximum blocks per
@@ -195,8 +211,13 @@ DEFAULT VALUE:
The default value is 16.
VALUE CONSTRAINTS:
- The value of this configuration option shall be greater than or equal to 0
- and less than or equal to `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_.
+ 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 `UINT32_MAX
+ <https://en.cppreference.com/w/c/types/integer>`_.
DESCRIPTION:
The value of this configuration option defines the maximum blocks per write
@@ -225,7 +246,8 @@ DEFAULT VALUE:
VALUE CONSTRAINTS:
The value of this configuration option shall be a valid Classic API task
- priority. The set of valid task priorities is scheduler-specific.
+ priority. The set of valid task priorities depends on the scheduler
+ configuration.
DESCRIPTION:
The value of this configuration option defines the read-ahead task priority.
@@ -255,15 +277,16 @@ VALUE CONSTRAINTS:
The value of this configuration option shall satisfy all of the following
constraints:
- * It shall be greater than or equal to :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`.
+ * It shall be greater than or equal to
+ :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`.
- * It shall be less than or equal to a
- BSP-specific and application-specific value which depends on the size of the
- memory available to the application.
+ * 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 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>`_.
+ * 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>`_.
DESCRIPTION:
The value of this configuration option defines the task stack size of the
@@ -291,8 +314,13 @@ DEFAULT VALUE:
The default value is 1000.
VALUE CONSTRAINTS:
- The value of this configuration option shall be greater than or equal to 0
- and less than or equal to `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_.
+ 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 `UINT32_MAX
+ <https://en.cppreference.com/w/c/types/integer>`_.
DESCRIPTION:
The value of this configuration option defines the swapout task maximum block
@@ -320,8 +348,13 @@ DEFAULT VALUE:
The default value is 250.
VALUE CONSTRAINTS:
- The value of this configuration option shall be greater than or equal to 0
- and less than or equal to `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_.
+ 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 `UINT32_MAX
+ <https://en.cppreference.com/w/c/types/integer>`_.
DESCRIPTION:
The value of this configuration option defines the swapout task swap period
@@ -350,7 +383,8 @@ DEFAULT VALUE:
VALUE CONSTRAINTS:
The value of this configuration option shall be a valid Classic API task
- priority. The set of valid task priorities is scheduler-specific.
+ priority. The set of valid task priorities depends on the scheduler
+ configuration.
DESCRIPTION:
The value of this configuration option defines the swapout task priority.
@@ -377,8 +411,13 @@ DEFAULT VALUE:
The default value is 0.
VALUE CONSTRAINTS:
- The value of this configuration option shall be greater than or equal to 0
- and less than or equal to `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_.
+ 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 `UINT32_MAX
+ <https://en.cppreference.com/w/c/types/integer>`_.
DESCRIPTION:
The value of this configuration option defines the swapout worker task count.
@@ -406,7 +445,8 @@ DEFAULT VALUE:
VALUE CONSTRAINTS:
The value of this configuration option shall be a valid Classic API task
- priority. The set of valid task priorities is scheduler-specific.
+ priority. The set of valid task priorities depends on the scheduler
+ configuration.
DESCRIPTION:
The value of this configuration option defines the swapout worker task
diff --git a/c-user/config/bsp-related.rst b/c-user/config/bsp-related.rst
index e56cee4..45f31a8 100644
--- a/c-user/config/bsp-related.rst
+++ b/c-user/config/bsp-related.rst
@@ -1,6 +1,6 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
-.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+.. Copyright (C) 2020, 2021 embedded brains GmbH (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
@@ -87,12 +87,12 @@ 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 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>`_.
+ * 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
@@ -165,12 +165,12 @@ 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 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 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`.
@@ -217,8 +217,8 @@ DESCRIPTION:
* 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.
+ 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
diff --git a/c-user/config/classic-api.rst b/c-user/config/classic-api.rst
index 74a8257..4643572 100644
--- a/c-user/config/classic-api.rst
+++ b/c-user/config/classic-api.rst
@@ -1,6 +1,6 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
-.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+.. Copyright (C) 2020, 2021 embedded brains GmbH (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
@@ -47,18 +47,18 @@ VALUE CONSTRAINTS:
The value of this configuration option shall satisfy all of the following
constraints:
- * It shall be greater than or equal to 0.
+ * It shall be greater than or equal to zero.
* It shall be less than or equal to 65535.
- * It shall be less than or equal to a
- BSP-specific and application-specific value which depends on the size of the
- memory available to the application.
+ * 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 may be defined through
- :c:func:`rtems_resource_unlimited` the enable unlimited objects for this
- object class, if the value passed to :c:func:`rtems_resource_unlimited`
- satisfies all other constraints of this configuration option.
+ * 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.
DESCRIPTION:
The value of this configuration option defines the maximum number of Classic
@@ -90,18 +90,18 @@ VALUE CONSTRAINTS:
The value of this configuration option shall satisfy all of the following
constraints:
- * It shall be greater than or equal to 0.
+ * It shall be greater than or equal to zero.
* It shall be less than or equal to 65535.
- * It shall be less than or equal to a
- BSP-specific and application-specific value which depends on the size of the
- memory available to the application.
+ * 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 may be defined through
- :c:func:`rtems_resource_unlimited` the enable unlimited objects for this
- object class, if the value passed to :c:func:`rtems_resource_unlimited`
- satisfies all other constraints of this configuration option.
+ * 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.
DESCRIPTION:
The value of this configuration option defines the maximum number of Classic
@@ -135,18 +135,18 @@ VALUE CONSTRAINTS:
The value of this configuration option shall satisfy all of the following
constraints:
- * It shall be greater than or equal to 0.
+ * It shall be greater than or equal to zero.
* It shall be less than or equal to 65535.
- * It shall be less than or equal to a
- BSP-specific and application-specific value which depends on the size of the
- memory available to the application.
+ * 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 may be defined through
- :c:func:`rtems_resource_unlimited` the enable unlimited objects for this
- object class, if the value passed to :c:func:`rtems_resource_unlimited`
- satisfies all other constraints of this configuration option.
+ * 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.
DESCRIPTION:
The value of this configuration option defines the maximum number of Classic
@@ -178,18 +178,18 @@ VALUE CONSTRAINTS:
The value of this configuration option shall satisfy all of the following
constraints:
- * It shall be greater than or equal to 0.
+ * It shall be greater than or equal to zero.
* It shall be less than or equal to 65535.
- * It shall be less than or equal to a
- BSP-specific and application-specific value which depends on the size of the
- memory available to the application.
+ * 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 may be defined through
- :c:func:`rtems_resource_unlimited` the enable unlimited objects for this
- object class, if the value passed to :c:func:`rtems_resource_unlimited`
- satisfies all other constraints of this configuration option.
+ * 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.
DESCRIPTION:
The value of this configuration option defines the maximum number of Classic
@@ -221,18 +221,18 @@ VALUE CONSTRAINTS:
The value of this configuration option shall satisfy all of the following
constraints:
- * It shall be greater than or equal to 0.
+ * It shall be greater than or equal to zero.
* It shall be less than or equal to 65535.
- * It shall be less than or equal to a
- BSP-specific and application-specific value which depends on the size of the
- memory available to the application.
+ * 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 may be defined through
- :c:func:`rtems_resource_unlimited` the enable unlimited objects for this
- object class, if the value passed to :c:func:`rtems_resource_unlimited`
- satisfies all other constraints of this configuration option.
+ * 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.
DESCRIPTION:
The value of this configuration option defines the maximum number of Classic
@@ -264,18 +264,18 @@ VALUE CONSTRAINTS:
The value of this configuration option shall satisfy all of the following
constraints:
- * It shall be greater than or equal to 0.
+ * It shall be greater than or equal to zero.
* It shall be less than or equal to 65535.
- * It shall be less than or equal to a
- BSP-specific and application-specific value which depends on the size of the
- memory available to the application.
+ * 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 may be defined through
- :c:func:`rtems_resource_unlimited` the enable unlimited objects for this
- object class, if the value passed to :c:func:`rtems_resource_unlimited`
- satisfies all other constraints of this configuration option.
+ * 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.
DESCRIPTION:
The value of this configuration option defines the maximum number of Classic
@@ -307,18 +307,18 @@ VALUE CONSTRAINTS:
The value of this configuration option shall satisfy all of the following
constraints:
- * It shall be greater than or equal to 0.
+ * It shall be greater than or equal to zero.
* It shall be less than or equal to 65535.
- * It shall be less than or equal to a
- BSP-specific and application-specific value which depends on the size of the
- memory available to the application.
+ * 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 may be defined through
- :c:func:`rtems_resource_unlimited` the enable unlimited objects for this
- object class, if the value passed to :c:func:`rtems_resource_unlimited`
- satisfies all other constraints of this configuration option.
+ * 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.
DESCRIPTION:
The value of this configuration option defines the maximum number of Classic
@@ -354,22 +354,22 @@ VALUE CONSTRAINTS:
The value of this configuration option shall satisfy all of the following
constraints:
- * It shall be greater than or equal to 0.
+ * It shall be greater than or equal to zero.
* It shall be less than or equal to 65535.
- * It shall be less than or equal to a
- BSP-specific and application-specific value which depends on the size of the
- memory available to the application.
+ * 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 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>`_.
+ * 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>`_.
- * It may be defined through
- :c:func:`rtems_resource_unlimited` the enable unlimited objects for this
- object class, if the value passed to :c:func:`rtems_resource_unlimited`
- satisfies all other constraints of this configuration option.
+ * 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.
DESCRIPTION:
The value of this configuration option defines the maximum number of Classic
@@ -414,11 +414,13 @@ VALUE CONSTRAINTS:
The value of this configuration option shall satisfy all of the following
constraints:
- * It shall be greater than or equal to 0.
+ * It shall be greater than or equal to zero.
- * It shall be less than or equal to `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_.
+ * It shall be less than or equal to `SIZE_MAX
+ <https://en.cppreference.com/w/c/types/limits>`_.
- * It shall be an integral multiple of :c:macro:`RTEMS_TASK_STORAGE_ALIGNMENT`.
+ * It shall be an integral multiple of
+ :c:macro:`RTEMS_TASK_STORAGE_ALIGNMENT`.
DESCRIPTION:
If the value of this configuration option is greater than zero, then it
@@ -466,18 +468,18 @@ VALUE CONSTRAINTS:
The value of this configuration option shall satisfy all of the following
constraints:
- * It shall be greater than or equal to 0.
+ * It shall be greater than or equal to zero.
* It shall be less than or equal to 65535.
- * It shall be less than or equal to a
- BSP-specific and application-specific value which depends on the size of the
- memory available to the application.
+ * 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 may be defined through
- :c:func:`rtems_resource_unlimited` the enable unlimited objects for this
- object class, if the value passed to :c:func:`rtems_resource_unlimited`
- satisfies all other constraints of this configuration option.
+ * 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.
DESCRIPTION:
The value of this configuration option defines the maximum number of Classic
@@ -509,13 +511,13 @@ VALUE CONSTRAINTS:
The value of this configuration option shall satisfy all of the following
constraints:
- * It shall be greater than or equal to 0.
+ * It shall be greater than or equal to zero.
* It shall be less than or equal to 65535.
- * It shall be less than or equal to a
- BSP-specific and application-specific value which depends on the size of the
- memory available to the application.
+ * 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.
DESCRIPTION:
The value of this configuration option defines the maximum number of Classic
@@ -543,8 +545,12 @@ DEFAULT VALUE:
The default value is 0.
VALUE CONSTRAINTS:
- The value of this configuration option shall be greater than or equal to 0
- and less than or equal to :ref:`CONFIGURE_MAXIMUM_TASKS`.
+ The 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 :ref:`CONFIGURE_MAXIMUM_TASKS`.
DESCRIPTION:
The value of this configuration option defines the minimum count of Classic
diff --git a/c-user/config/classic-init-task.rst b/c-user/config/classic-init-task.rst
index 0743929..9c0435b 100644
--- a/c-user/config/classic-init-task.rst
+++ b/c-user/config/classic-init-task.rst
@@ -1,6 +1,6 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
-.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+.. Copyright (C) 2020, 2021 embedded brains GmbH (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
@@ -45,8 +45,8 @@ DEFAULT VALUE:
The default value is 0.
VALUE CONSTRAINTS:
- The value of this configuration option shall be a valid integer of type
- :c:type:`rtems_task_argument`.
+ The value of this configuration option shall be convertible to an integer
+ of type :c:type:`rtems_task_argument`.
DESCRIPTION:
The value of this configuration option defines task argument of the Classic
@@ -107,10 +107,10 @@ VALUE CONSTRAINTS:
The value of this configuration option shall satisfy all of the following
constraints:
- * It shall be greater than or equal to :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`.
+ * It shall be greater than or equal to
+ :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`.
- * It shall be defined using
- :c:func:`RTEMS_TASK_STORAGE_SIZE`.
+ * It shall be defined using :c:func:`RTEMS_TASK_STORAGE_SIZE`.
DESCRIPTION:
The value of this configuration option defines the task storage size of the
@@ -222,8 +222,8 @@ DEFAULT VALUE:
The default value is ``rtems_build_name( 'U', 'I', '1', ' ' )``.
VALUE CONSTRAINTS:
- The value of this configuration option shall be a valid integer of type
- :c:type:`rtems_name`.
+ The value of this configuration option shall be convertible to an integer
+ of type :c:type:`rtems_name`.
DESCRIPTION:
The value of this configuration option defines the name of the Classic API
@@ -252,7 +252,8 @@ DEFAULT VALUE:
VALUE CONSTRAINTS:
The value of this configuration option shall be a valid Classic API task
- priority. The set of valid task priorities is scheduler-specific.
+ priority. The set of valid task priorities depends on the scheduler
+ configuration.
DESCRIPTION:
The value of this configuration option defines the initial priority of the
@@ -283,11 +284,12 @@ VALUE CONSTRAINTS:
The value of this configuration option shall satisfy all of the following
constraints:
- * It shall be greater than or equal to :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`.
+ * It shall be greater than or equal to
+ :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`.
- * It shall be small enough so that the task
- stack space calculation carried out by ``<rtems/confdefs.h>`` does not
- overflow an integer of type `uintptr_t <https://en.cppreference.com/w/c/types/integer>`_.
+ * 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>`_.
DESCRIPTION:
The value of this configuration option defines the task stack size of the
diff --git a/c-user/config/device-driver.rst b/c-user/config/device-driver.rst
index 05ae08a..22002f9 100644
--- a/c-user/config/device-driver.rst
+++ b/c-user/config/device-driver.rst
@@ -1,6 +1,6 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
-.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+.. Copyright (C) 2020, 2021 embedded brains GmbH (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
@@ -594,7 +594,8 @@ DEFAULT VALUE:
VALUE CONSTRAINTS:
The value of this configuration option shall be a valid Classic API task
- priority. The set of valid task priorities is scheduler-specific.
+ priority. The set of valid task priorities depends on the scheduler
+ configuration.
DESCRIPTION:
The value of this configuration option defines the ATA task priority.
@@ -661,14 +662,15 @@ VALUE CONSTRAINTS:
The value of this configuration option shall satisfy all of the following
constraints:
- * It shall be less than or equal to `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_.
+ * It shall be less than or equal to `SIZE_MAX
+ <https://en.cppreference.com/w/c/types/limits>`_.
- * It shall be greater than or equal than the number of statically configured
- device drivers.
+ * It shall be greater than or equal than the number of statically
+ configured device drivers.
- * 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 less than or equal to a BSP-specific and application-specific
+ value which depends on the size of the memory available to the
+ application.
DESCRIPTION:
The value of this configuration option defines the number of device drivers.
diff --git a/c-user/config/event-record.rst b/c-user/config/event-record.rst
index cbe02e3..fa1d011 100644
--- a/c-user/config/event-record.rst
+++ b/c-user/config/event-record.rst
@@ -1,6 +1,6 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
-.. Copyright (C) 2019, 2020 embedded brains GmbH (http://www.embedded-brains.de)
+.. Copyright (C) 2019, 2021 embedded brains GmbH (http://www.embedded-brains.de)
.. This file is part of the RTEMS quality process and was automatically
.. generated. If you find something that needs to be fixed or
@@ -147,13 +147,14 @@ VALUE CONSTRAINTS:
* It shall be greater than or equal to 16.
- * It shall be less than or equal to `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_.
+ * It shall be less than or equal to `SIZE_MAX
+ <https://en.cppreference.com/w/c/types/limits>`_.
* It shall be a power of two.
- * 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 less than or equal to a BSP-specific and application-specific
+ value which depends on the size of the memory available to the
+ application.
DESCRIPTION:
The value of this configuration option defines the event record item count
diff --git a/c-user/config/filesystem.rst b/c-user/config/filesystem.rst
index 5b1b414..05ca826 100644
--- a/c-user/config/filesystem.rst
+++ b/c-user/config/filesystem.rst
@@ -1,6 +1,6 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
-.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+.. Copyright (C) 2020, 2021 embedded brains GmbH (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
@@ -739,8 +739,8 @@ DEFAULT VALUE:
The default value is 128.
VALUE CONSTRAINTS:
- The value of this configuration option shall be
- an element of {16, 32, 64, 128, 256, 512}.
+ The value of this configuration option shall be equal to 16, 32, 64, 128,
+ 256, or 512.
DESCRIPTION:
The value of this configuration option defines the block size for in-memory
diff --git a/c-user/config/general.rst b/c-user/config/general.rst
index 024b5c4..1a43b03 100644
--- a/c-user/config/general.rst
+++ b/c-user/config/general.rst
@@ -1,6 +1,6 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
-.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+.. Copyright (C) 2020, 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
@@ -111,13 +111,14 @@ VALUE CONSTRAINTS:
The value of this configuration option shall satisfy all of the following
constraints:
- * It shall be greater than or equal to 0.
+ * It shall be greater than or equal to zero.
- * It shall be less than or equal to `UINTPTR_MAX <https://en.cppreference.com/w/c/types/integer>`_.
+ * It shall be less than or equal to `UINTPTR_MAX
+ <https://en.cppreference.com/w/c/types/integer>`_.
- * 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 less than or equal to a BSP-specific and application-specific
+ value which depends on the size of the memory available to the
+ application.
DESCRIPTION:
The value of this configuration option defines the RTEMS Workspace size in
@@ -150,11 +151,11 @@ VALUE CONSTRAINTS:
The value of this configuration option shall satisfy all of the following
constraints:
- * It shall be greater than or equal to 0.
+ * It shall be greater than or equal to zero.
- * 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>`_.
+ * 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>`_.
DESCRIPTION:
The value of this configuration option defines the number of bytes the
@@ -221,12 +222,12 @@ 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 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 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`.
@@ -306,13 +307,14 @@ VALUE CONSTRAINTS:
The value of this configuration option shall satisfy all of the following
constraints:
- * It shall be greater than or equal to 0.
+ * It shall be greater than or equal to zero.
- * It shall be less than or equal to `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_.
+ * It shall be less than or equal to `SIZE_MAX
+ <https://en.cppreference.com/w/c/types/limits>`_.
- * 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 less than or equal to a BSP-specific and application-specific
+ value which depends on the size of the memory available to the
+ application.
DESCRIPTION:
The value of this configuration option defines the maximum number of file
@@ -341,8 +343,12 @@ DEFAULT VALUE:
The default value is 1.
VALUE CONSTRAINTS:
- The value of this configuration option shall be greater than or equal to 1
- and less than or equal to :c:macro:`CPU_MAXIMUM_PROCESSORS`.
+ The value of this configuration option shall satisfy all of the following
+ constraints:
+
+ * It shall be greater than or equal to one.
+
+ * It shall be less than or equal to :c:macro:`CPU_MAXIMUM_PROCESSORS`.
DESCRIPTION:
The value of this configuration option defines the maximum number of
@@ -382,13 +388,14 @@ VALUE CONSTRAINTS:
The value of this configuration option shall satisfy all of the following
constraints:
- * It shall be greater than or equal to 0.
+ * It shall be greater than or equal to zero.
- * It shall be less than or equal to `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_.
+ * It shall be less than or equal to `SIZE_MAX
+ <https://en.cppreference.com/w/c/types/limits>`_.
- * 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 less than or equal to a BSP-specific and application-specific
+ value which depends on the size of the memory available to the
+ application.
DESCRIPTION:
The value of this configuration option defines the maximum thread name size
@@ -396,7 +403,7 @@ DESCRIPTION:
NOTES:
The default value was chosen for Linux compatibility, see
- `PTHREAD_SETNAME_NP(3) <http://man7.org/linux/man-pages/man3/pthread_setname_np.3.html>`_.
+ `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.
@@ -425,15 +432,15 @@ VALUE CONSTRAINTS:
The value of this configuration option shall satisfy all of the following
constraints:
- * It shall be greater than or equal to 0.
+ * It shall be 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 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>`_.
+ * 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 kilobytes the
@@ -472,15 +479,15 @@ VALUE CONSTRAINTS:
The value of this configuration option shall satisfy all of the following
constraints:
- * It shall be greater than or equal to 0.
+ * It shall be 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 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>`_.
+ * 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
@@ -557,9 +564,11 @@ VALUE CONSTRAINTS:
The value of this configuration option shall satisfy all of the following
constraints:
- * It shall be greater than or equal to a Clock Driver specific value.
+ * It shall be greater than or equal to a value defined by the :term:`Clock
+ Driver`.
- * It shall be less than or equal to a Clock Driver specific value.
+ * It 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.
@@ -612,12 +621,12 @@ VALUE CONSTRAINTS:
The value of this configuration option shall satisfy all of the following
constraints:
- * 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>`_.
+ * 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>`_.
- * It shall be greater than or equal to a
- BSP-specific and application-specific minimum value.
+ * It shall be greater than or equal to a BSP-specific and
+ application-specific minimum value.
DESCRIPTION:
The value of this configuration option defines the minimum stack size in
@@ -695,8 +704,13 @@ DEFAULT VALUE:
The default value is 50.
VALUE CONSTRAINTS:
- The value of this configuration option shall be greater than or equal to 0
- and less than or equal to `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_.
+ 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 `UINT32_MAX
+ <https://en.cppreference.com/w/c/types/integer>`_.
DESCRIPTION:
The value of this configuration option defines the length of the timeslice
diff --git a/c-user/config/idle-task.rst b/c-user/config/idle-task.rst
index 9330672..1234f42 100644
--- a/c-user/config/idle-task.rst
+++ b/c-user/config/idle-task.rst
@@ -1,6 +1,6 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
-.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+.. Copyright (C) 2020, 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
@@ -129,12 +129,12 @@ 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 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>`_.
+ * 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:
The value of this configuration option defines the task stack size for an
diff --git a/c-user/config/mpci.rst b/c-user/config/mpci.rst
index 0c967c6..800aa30 100644
--- a/c-user/config/mpci.rst
+++ b/c-user/config/mpci.rst
@@ -1,6 +1,6 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
-.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+.. Copyright (C) 2020, 2021 embedded brains GmbH (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
@@ -52,14 +52,14 @@ VALUE CONSTRAINTS:
The value of this configuration option shall satisfy all of the following
constraints:
- * It shall be greater than or equal to 0.
+ * It shall be greater than or equal to zero.
- * It shall be less than or equal to `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_.
+ * It shall be less than or equal to `UINT32_MAX
+ <https://en.cppreference.com/w/c/types/integer>`_.
- * 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>`_.
+ * 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>`_.
DESCRIPTION:
The value of this configuration option defines the number of bytes the
@@ -119,8 +119,13 @@ DEFAULT VALUE:
The default value is 32.
VALUE CONSTRAINTS:
- The value of this configuration option shall be greater than or equal to 0
- and less than or equal to `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_.
+ 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 `UINT32_MAX
+ <https://en.cppreference.com/w/c/types/integer>`_.
DESCRIPTION:
The value of this configuration option defines the maximum number of
@@ -152,8 +157,13 @@ DEFAULT VALUE:
The default value is 2.
VALUE CONSTRAINTS:
- The value of this configuration option shall be greater than or equal to 0
- and less than or equal to `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_.
+ 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 `UINT32_MAX
+ <https://en.cppreference.com/w/c/types/integer>`_.
DESCRIPTION:
The value of this configuration option defines the maximum number of nodes in
@@ -182,8 +192,13 @@ DEFAULT VALUE:
The default value is 32.
VALUE CONSTRAINTS:
- The value of this configuration option shall be greater than or equal to 0
- and less than or equal to `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_.
+ 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 `UINT32_MAX
+ <https://en.cppreference.com/w/c/types/integer>`_.
DESCRIPTION:
The value of this configuration option defines the maximum number of
@@ -252,8 +267,13 @@ DEFAULT VALUE:
The default value is ``NODE_NUMBER``.
VALUE CONSTRAINTS:
- The value of this configuration option shall be greater than or equal to 0
- and less than or equal to `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_.
+ 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 `UINT32_MAX
+ <https://en.cppreference.com/w/c/types/integer>`_.
DESCRIPTION:
The value of this configuration option defines the node number of this node
diff --git a/c-user/config/posix-api.rst b/c-user/config/posix-api.rst
index 592a1ce..3c2c8a2 100644
--- a/c-user/config/posix-api.rst
+++ b/c-user/config/posix-api.rst
@@ -1,6 +1,6 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
-.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+.. Copyright (C) 2020, 2021 embedded brains GmbH (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
@@ -50,18 +50,18 @@ VALUE CONSTRAINTS:
The value of this configuration option shall satisfy all of the following
constraints:
- * It shall be greater than or equal to 0.
+ * It shall be greater than or equal to zero.
* It shall be less than or equal to 65535.
- * It shall be less than or equal to a
- BSP-specific and application-specific value which depends on the size of the
- memory available to the application.
+ * 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 may be defined through
- :c:func:`rtems_resource_unlimited` the enable unlimited objects for this
- object class, if the value passed to :c:func:`rtems_resource_unlimited`
- satisfies all other constraints of this configuration option.
+ * 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.
DESCRIPTION:
The value of this configuration option defines the maximum number of POSIX
@@ -96,18 +96,18 @@ VALUE CONSTRAINTS:
The value of this configuration option shall satisfy all of the following
constraints:
- * It shall be greater than or equal to 0.
+ * It shall be greater than or equal to zero.
* It shall be less than or equal to 65535.
- * It shall be less than or equal to a
- BSP-specific and application-specific value which depends on the size of the
- memory available to the application.
+ * 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 may be defined through
- :c:func:`rtems_resource_unlimited` the enable unlimited objects for this
- object class, if the value passed to :c:func:`rtems_resource_unlimited`
- satisfies all other constraints of this configuration option.
+ * 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.
DESCRIPTION:
The value of this configuration option defines the maximum number of key
@@ -142,22 +142,22 @@ VALUE CONSTRAINTS:
The value of this configuration option shall satisfy all of the following
constraints:
- * It shall be greater than or equal to 0.
+ * It shall be greater than or equal to zero.
* It shall be less than or equal to 65535.
- * It shall be less than or equal to a
- BSP-specific and application-specific value which depends on the size of the
- memory available to the application.
+ * 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>`_.
+ * 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>`_.
- * It may be defined through
- :c:func:`rtems_resource_unlimited` the enable unlimited objects for this
- object class, if the value passed to :c:func:`rtems_resource_unlimited`
- satisfies all other constraints of this configuration option.
+ * 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.
DESCRIPTION:
The value of this configuration option defines the maximum number of POSIX
@@ -191,20 +191,19 @@ VALUE CONSTRAINTS:
The value of this configuration option shall satisfy all of the following
constraints:
- * It shall be greater than or equal to 0.
+ * It shall be 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 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>`_.
+ * 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>`_.
- * It shall be zero if the POSIX API is not
- enabled (e.g. RTEMS was built without the ``--enable-posix`` build
- configuration option). Otherwise a compile time error in the configuration
- file will occur.
+ * 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.
DESCRIPTION:
The value of this configuration option defines the maximum number of POSIX
@@ -238,22 +237,22 @@ VALUE CONSTRAINTS:
The value of this configuration option shall satisfy all of the following
constraints:
- * It shall be greater than or equal to 0.
+ * It shall be greater than or equal to zero.
* It shall be less than or equal to 65535.
- * It shall be less than or equal to a
- BSP-specific and application-specific value which depends on the size of the
- memory available to the application.
+ * 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>`_.
+ * 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>`_.
- * It may be defined through
- :c:func:`rtems_resource_unlimited` the enable unlimited objects for this
- object class, if the value passed to :c:func:`rtems_resource_unlimited`
- satisfies all other constraints of this configuration option.
+ * 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.
DESCRIPTION:
The value of this configuration option defines the maximum number of POSIX
@@ -290,22 +289,22 @@ VALUE CONSTRAINTS:
The value of this configuration option shall satisfy all of the following
constraints:
- * It shall be greater than or equal to 0.
+ * It shall be greater than or equal to zero.
* It shall be less than or equal to 65535.
- * It shall be less than or equal to a
- BSP-specific and application-specific value which depends on the size of the
- memory available to the application.
+ * 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>`_.
+ * 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>`_.
- * It may be defined through
- :c:func:`rtems_resource_unlimited` the enable unlimited objects for this
- object class, if the value passed to :c:func:`rtems_resource_unlimited`
- satisfies all other constraints of this configuration option.
+ * 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.
DESCRIPTION:
The value of this configuration option defines the maximum number of POSIX
@@ -337,17 +336,17 @@ VALUE CONSTRAINTS:
The value of this configuration option shall satisfy all of the following
constraints:
- * It shall be greater than or equal to 0.
+ * It shall be greater than or equal to zero.
* It shall be less than or equal to 65535.
- * It shall be less than or equal to a
- BSP-specific and application-specific value which depends on the size of the
- memory available to the application.
+ * 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 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>`_.
+ * 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>`_.
DESCRIPTION:
The value of this configuration option defines the maximum number of POSIX
@@ -389,23 +388,22 @@ VALUE CONSTRAINTS:
The value of this configuration option shall satisfy all of the following
constraints:
- * It shall be greater than or equal to 0.
+ * It shall be greater than or equal to zero.
* It shall be less than or equal to 65535.
- * It shall be less than or equal to a
- BSP-specific and application-specific value which depends on the size of the
- memory available to the application.
+ * 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 may be defined through
- :c:func:`rtems_resource_unlimited` the enable unlimited objects for this
- object class, if the value passed to :c:func:`rtems_resource_unlimited`
- satisfies all other constraints of this configuration option.
+ * 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.
- * It shall be zero if the POSIX API is not
- enabled (e.g. RTEMS was built without the ``--enable-posix`` build
- configuration option). Otherwise a compile time error in the configuration
- file will occur.
+ * 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.
DESCRIPTION:
The value of this configuration option defines the maximum number of POSIX
@@ -442,12 +440,12 @@ VALUE CONSTRAINTS:
The value of this configuration option shall satisfy all of the following
constraints:
- * 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>`_.
+ * 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>`_.
- * It shall be greater than or equal to a
- BSP-specific and application-specific minimum value.
+ * It shall be greater than or equal to a BSP-specific and
+ application-specific minimum value.
DESCRIPTION:
The value of this configuration option defines the minimum stack size in
diff --git a/c-user/config/posix-init-thread.rst b/c-user/config/posix-init-thread.rst
index 42542e5..8623f2c 100644
--- a/c-user/config/posix-init-thread.rst
+++ b/c-user/config/posix-init-thread.rst
@@ -1,6 +1,6 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
-.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+.. Copyright (C) 2020, 2021 embedded brains GmbH (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
@@ -78,11 +78,12 @@ VALUE CONSTRAINTS:
The value of this configuration option shall satisfy all of the following
constraints:
- * It shall be greater than or equal to :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`.
+ * It shall be greater than or equal to
+ :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`.
- * It shall be small enough so that the task
- stack space calculation carried out by ``<rtems/confdefs.h>`` does not
- overflow an integer of type `uintptr_t <https://en.cppreference.com/w/c/types/integer>`_.
+ * 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>`_.
DESCRIPTION:
The value of this configuration option defines the thread stack size of the
diff --git a/c-user/config/scheduler-general.rst b/c-user/config/scheduler-general.rst
index cbdb145..d78b14a 100644
--- a/c-user/config/scheduler-general.rst
+++ b/c-user/config/scheduler-general.rst
@@ -1,6 +1,6 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
-.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de)
.. Copyright (C) 2010 Gedare Bloom
.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -69,13 +69,14 @@ VALUE CONSTRAINTS:
The value of this configuration option shall satisfy all of the following
constraints:
- * It shall be greater than or equal to 0.
+ * It shall be greater than or equal to zero.
- * It shall be less than or equal to `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_.
+ * It shall be less than or equal to `SIZE_MAX
+ <https://en.cppreference.com/w/c/types/limits>`_.
- * 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 less than or equal to a BSP-specific and application-specific
+ value which depends on the size of the memory available to the
+ application.
DESCRIPTION:
The value of this configuration option defines the maximum number Constant
@@ -106,8 +107,8 @@ DEFAULT VALUE:
The default value is 255.
VALUE CONSTRAINTS:
- The value of this configuration option shall be
- an element of {3, 7, 31, 63, 127, 255}.
+ The value of this configuration option shall be equal to 3, 7, 31, 63, 127,
+ or 255.
DESCRIPTION:
For the following schedulers
@@ -168,15 +169,14 @@ VALUE CONSTRAINTS:
The value of this configuration option shall satisfy all of the following
constraints:
- * It shall be a list of the following
- macros:
+ * It shall be a list of the following macros:
* ``RTEMS_SCHEDULER_ASSIGN( processor_index, attributes )``
* ``RTEMS_SCHEDULER_ASSIGN_NO_SCHEDULER``
- * It shall be a list of exactly
- :ref:`CONFIGURE_MAXIMUM_PROCESSORS` elements.
+ * It shall be a list of exactly :ref:`CONFIGURE_MAXIMUM_PROCESSORS`
+ elements.
DESCRIPTION:
The value of this configuration option is used to initialize the initial
@@ -208,7 +208,7 @@ DEFAULT CONFIGURATION:
enabled.
DESCRIPTION:
- In case this configuration option is defined, then
+ In case this configuration option is defined, then the
:ref:`SchedulerCBS`
algorithm is made available to the application.
@@ -239,7 +239,7 @@ DEFAULT CONFIGURATION:
enabled.
DESCRIPTION:
- In case this configuration option is defined, then
+ In case this configuration option is defined, then the
:ref:`SchedulerEDF`
algorithm is made available to the application.
@@ -270,7 +270,7 @@ DEFAULT CONFIGURATION:
enabled.
DESCRIPTION:
- In case this configuration option is defined, then
+ In case this configuration option is defined, then the
:ref:`SchedulerSMPEDF`
algorithm is made available to the application.
@@ -323,8 +323,8 @@ DEFAULT VALUE:
* ``"UPS "`` for the :ref:`SchedulerPrioritySimple`.
VALUE CONSTRAINTS:
- The value of this configuration option shall be a valid integer of type
- :c:type:`rtems_name`.
+ The value of this configuration option shall be convertible to an integer
+ of type :c:type:`rtems_name`.
DESCRIPTION:
The value of this configuration option defines the name of the default
@@ -358,7 +358,7 @@ DEFAULT CONFIGURATION:
enabled.
DESCRIPTION:
- In case this configuration option is defined, then
+ In case this configuration option is defined, then the
:ref:`SchedulerPriority`
algorithm is made available to the application.
@@ -396,7 +396,7 @@ DEFAULT CONFIGURATION:
enabled.
DESCRIPTION:
- In case this configuration option is defined, then
+ In case this configuration option is defined, then the
:ref:`SchedulerSMPPriorityAffinity`
algorithm is made available to the application.
@@ -433,7 +433,7 @@ DEFAULT CONFIGURATION:
enabled.
DESCRIPTION:
- In case this configuration option is defined, then
+ In case this configuration option is defined, then the
:ref:`SchedulerSMPPriority`
algorithm is made available to the application.
@@ -470,7 +470,7 @@ DEFAULT CONFIGURATION:
enabled.
DESCRIPTION:
- In case this configuration option is defined, then
+ In case this configuration option is defined, then the
:ref:`SchedulerPrioritySimple`
algorithm is made available to the application.
@@ -501,10 +501,9 @@ DEFAULT CONFIGURATION:
enabled.
DESCRIPTION:
- In case this configuration option is defined, then
+ In case this configuration option is defined, then the
:ref:`SchedulerSMPPrioritySimple`
algorithm is made available to the application.
- application.
NOTES:
This scheduler configuration option is an advanced configuration option.
@@ -536,8 +535,8 @@ DEFAULT CONFIGURATION:
enabled.
DESCRIPTION:
- In case this configuration option is defined, then Strong APA algorithm is
- made available to the application.
+ In case this configuration option is defined, then the Strong APA algorithm
+ is made available to the application.
NOTES:
This scheduler configuration option is an advanced configuration option.
diff --git a/c-user/config/task-stack-alloc.rst b/c-user/config/task-stack-alloc.rst
index cd174ed..3f779ff 100644
--- a/c-user/config/task-stack-alloc.rst
+++ b/c-user/config/task-stack-alloc.rst
@@ -1,6 +1,6 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
-.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+.. Copyright (C) 2020, 2021 embedded brains GmbH (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
@@ -113,8 +113,8 @@ DEFAULT VALUE:
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>`_.
+ pointer of the type ``void ( *initialize )( size_t )`` or to `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
DESCRIPTION:
The value of this configuration option initializes the stack allocator
diff --git a/c-user/dual-ported-memory/directives.rst b/c-user/dual-ported-memory/directives.rst
index fb21a4f..42cb875 100644
--- a/c-user/dual-ported-memory/directives.rst
+++ b/c-user/dual-ported-memory/directives.rst
@@ -1,229 +1,403 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
+.. Copyright (C) 2020, 2021 embedded brains GmbH (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
+
+.. _DualPortedMemoryManagerDirectives:
+
Directives
==========
-This section details the dual-ported memory manager's directives. A subsection
-is dedicated to each of this manager's directives and describes the calling
-sequence, related constants, usage, and status codes.
+This section details the directives of the Dual-Ported Memory Manager. A
+subsection is dedicated to each of this manager's directives and lists the
+calling sequence, parameters, description, return values, and notes of the
+directive.
+
+.. Generated from spec:/rtems/dpmem/if/create
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_port_create()
.. index:: create a port
-.. index:: rtems_port_create
-
-.. _rtems_port_create:
-
-PORT_CREATE - Create a port
----------------------------
-
-CALLING SEQUENCE:
- .. code-block:: c
-
- rtems_status_code rtems_port_create(
- rtems_name name,
- void *internal_start,
- void *external_start,
- uint32_t length,
- rtems_id *id
- );
-
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
-
- * - ``RTEMS_SUCCESSFUL``
- - port created successfully
- * - ``RTEMS_INVALID_NAME``
- - invalid port name
- * - ``RTEMS_INVALID_ADDRESS``
- - address not on four byte boundary
- * - ``RTEMS_INVALID_ADDRESS``
- - ``id`` is NULL
- * - ``RTEMS_TOO_MANY``
- - too many DP memory areas created
-
-DESCRIPTION:
- This directive creates a port which resides on the local node for the
- specified DPMA. The assigned port id is returned in id. This port id is
- used as an argument to other dual-ported memory manager directives to
- convert addresses within this DPMA.
-
- For control and maintenance of the port, RTEMS allocates and initializes an
- DPCB from the DPCB free pool. Thus memory from the dual-ported memory area
- is not used to store the DPCB.
-
-NOTES:
- This directive may cause the calling task to be preempted due to an
- obtain and release of the object allocator mutex.
-
- The internal_address and external_address parameters must be on a four byte
- boundary.
+
+.. _InterfaceRtemsPortCreate:
+
+rtems_port_create()
+-------------------
+
+Creates a port.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_port_create(
+ rtems_name name,
+ void *internal_start,
+ void *external_start,
+ uint32_t length,
+ rtems_id *id
+ );
+
+.. rubric:: PARAMETERS:
+
+``name``
+ This parameter is the object name of the port.
+
+``internal_start``
+ This parameter is the internal start address of the memory area.
+
+``external_start``
+ This parameter is the external start address of the memory area.
+
+``length``
+ This parameter is the length in bytes of the memory area.
+
+``id``
+ This parameter is the pointer to an object identifier variable. When the
+ directive call is successful, the identifier of the created port will be
+ stored in this variable.
+
+.. rubric:: DESCRIPTION:
+
+This directive creates a port which resides on the local node. The port has
+the user-defined object name specified in ``name``. The assigned object
+identifier is returned in ``id``. This identifier is used to access the port
+with other dual-ported memory port related directives.
+
+.. rubric:: RETURN VALUES:
+
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_NAME`
+ The ``name`` parameter was invalid.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``id`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``internal_start`` parameter was not properly aligned.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``external_start`` parameter was not properly aligned.
+
+:c:macro:`RTEMS_TOO_MANY`
+ There was no inactive object available to create a port. The number of
+ port available to the application is configured through the
+ :ref:`CONFIGURE_MAXIMUM_PORTS` application configuration option.
+
+.. rubric:: NOTES:
+
+The ``internal_start`` and ``external_start`` parameters must be on a boundary
+defined by the target processor architecture.
+
+For control and maintenance of the port, RTEMS allocates a :term:`DPCB` from
+the local DPCB free pool and initializes it.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive may obtain and release the object allocator mutex. This may
+ cause the calling task to be preempted.
+
+* The number of ports available to the application is configured through the
+ :ref:`CONFIGURE_MAXIMUM_PORTS` application configuration option.
+
+* Where the object class corresponding to the directive is configured to use
+ unlimited objects, the directive may allocate memory from the RTEMS
+ Workspace.
+
+.. Generated from spec:/rtems/dpmem/if/ident
.. raw:: latex
- \clearpage
+ \clearpage
+
+.. index:: rtems_port_ident()
+
+.. _InterfaceRtemsPortIdent:
+
+rtems_port_ident()
+------------------
+
+Identifies a port by the object name.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_port_ident( rtems_name name, rtems_id *id );
+
+.. rubric:: PARAMETERS:
+
+``name``
+ This parameter is the object name to look up.
+
+``id``
+ This parameter is the pointer to an object identifier variable. When the
+ directive call is successful, the object identifier of an object with the
+ specified name will be stored in this variable.
+
+.. rubric:: DESCRIPTION:
+
+This directive obtains a port identifier associated with the port name
+specified in ``name``.
-.. index:: get ID of a port
-.. index:: obtain ID of a port
-.. index:: rtems_port_ident
+.. rubric:: RETURN VALUES:
-.. _rtems_port_ident:
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
-PORT_IDENT - Get ID of a port
------------------------------
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``id`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
-CALLING SEQUENCE:
- .. code-block:: c
+:c:macro:`RTEMS_INVALID_NAME`
+ The ``name`` parameter was 0.
- rtems_status_code rtems_port_ident(
- rtems_name name,
- rtems_id *id
- );
+:c:macro:`RTEMS_INVALID_NAME`
+ There was no object with the specified name on the local node.
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+.. rubric:: NOTES:
- * - ``RTEMS_SUCCESSFUL``
- - port identified successfully
- * - ``RTEMS_INVALID_ADDRESS``
- - ``id`` is NULL
- * - ``RTEMS_INVALID_NAME``
- - port name not found
+If the port name is not unique, then the port identifier will match the first
+port with that name in the search order. However, this port identifier is not
+guaranteed to correspond to the desired port.
-DESCRIPTION:
- This directive obtains the port id associated with the specified name to be
- acquired. If the port name is not unique, then the port id will match one
- of the DPMAs with that name. However, this port id is not guaranteed to
- correspond to the desired DPMA. The port id is used to access this DPMA in
- other dual-ported memory area related directives.
+The objects are searched from lowest to the highest index. Only the local node
+is searched.
-NOTES:
- This directive will not cause the running task to be preempted.
+The port identifier is used with other dual-ported memory related directives to
+access the port.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/dpmem/if/delete
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_port_delete()
.. index:: delete a port
-.. index:: rtems_port_delete
-.. _rtems_port_delete:
+.. _InterfaceRtemsPortDelete:
+
+rtems_port_delete()
+-------------------
+
+Deletes the port.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_port_delete( rtems_id id );
+
+.. rubric:: PARAMETERS:
+
+``id``
+ This parameter is the port identifier.
-PORT_DELETE - Delete a port
----------------------------
+.. rubric:: DESCRIPTION:
-CALLING SEQUENCE:
- .. code-block:: c
+This directive deletes the port specified by ``id``.
- rtems_status_code rtems_port_delete(
- rtems_id id
- );
+.. rubric:: RETURN VALUES:
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
- * - ``RTEMS_SUCCESSFUL``
- - port deleted successfully
- * - ``RTEMS_INVALID_ID``
- - invalid port id
+:c:macro:`RTEMS_INVALID_ID`
+ There was no port associated with the identifier specified by ``id``.
-DESCRIPTION:
- This directive deletes the dual-ported memory area specified by id. The
- DPCB for the deleted dual-ported memory area is reclaimed by RTEMS.
+.. rubric:: NOTES:
-NOTES:
- This directive may cause the calling task to be preempted due to an
- obtain and release of the object allocator mutex.
+The :term:`DPCB` for the deleted port is reclaimed by RTEMS.
- The calling task does not have to be the task that created the port. Any
- local task that knows the port id can delete the port.
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive may obtain and release the object allocator mutex. This may
+ cause the calling task to be preempted.
+
+* The calling task does not have to be the task that created the object. Any
+ local task that knows the object identifier can delete the object.
+
+* Where the object class corresponding to the directive is configured to use
+ unlimited objects, the directive may free memory to the RTEMS Workspace.
+
+.. Generated from spec:/rtems/dpmem/if/external-to-internal
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_port_external_to_internal()
.. index:: convert external to internal address
-.. index:: rtems_port_external_to_internal
-.. _rtems_port_external_to_internal:
+.. _InterfaceRtemsPortExternalToInternal:
+
+rtems_port_external_to_internal()
+---------------------------------
+
+Converts the external address to the internal address.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
-PORT_EXTERNAL_TO_INTERNAL - Convert external to internal address
-----------------------------------------------------------------
+ rtems_status_code rtems_port_external_to_internal(
+ rtems_id id,
+ void *external,
+ void **internal
+ );
-CALLING SEQUENCE:
- .. code-block:: c
+.. rubric:: PARAMETERS:
- rtems_status_code rtems_port_external_to_internal(
- rtems_id id,
- void *external,
- void **internal
- );
+``id``
+ This parameter is the port identifier.
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+``external``
+ This parameter is the external address to convert.
- * - ``RTEMS_INVALID_ADDRESS``
- - ``internal`` is NULL
- * - ``RTEMS_SUCCESSFUL``
- - successful conversion
+``internal``
+ This parameter is the pointer to a pointer variable. When the directive
+ call is successful, the external address associated with the internal
+ address will be stored in this variable.
-DESCRIPTION:
- This directive converts a dual-ported memory address from external to
- internal representation for the specified port. If the given external
- address is invalid for the specified port, then the internal address is set
- to the given external address.
+.. rubric:: DESCRIPTION:
-NOTES:
- This directive is callable from an ISR.
+This directive converts a dual-ported memory address from external to internal
+representation for the specified port. If the given external address is
+invalid for the specified port, then the internal address is set to the given
+external address.
- This directive will not cause the calling task to be preempted.
+.. rubric:: RETURN VALUES:
+
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_NAME`
+ The ``id`` parameter was invalid.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``internal`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within interrupt context.
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/dpmem/if/internal-to-external
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_port_internal_to_external()
.. index:: convert internal to external address
-.. index:: rtems_port_internal_to_external
-.. _rtems_port_internal_to_external:
+.. _InterfaceRtemsPortInternalToExternal:
+
+rtems_port_internal_to_external()
+---------------------------------
+
+Converts the internal address to the external address.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_port_internal_to_external(
+ rtems_id id,
+ void *internal,
+ void **external
+ );
+
+.. rubric:: PARAMETERS:
+
+``id``
+ This parameter is the port identifier.
+
+``internal``
+ This parameter is the internal address to convert.
+
+``external``
+ This parameter is the pointer to a pointer variable. When the directive
+ call is successful, the external address associated with the internal
+ address will be stored in this variable.
+
+.. rubric:: DESCRIPTION:
+
+This directive converts a dual-ported memory address from internal to external
+representation so that it can be passed to owner of the DPMA represented by the
+specified port. If the given internal address is an invalid dual-ported
+address, then the external address is set to the given internal address.
+
+.. rubric:: RETURN VALUES:
+
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
-PORT_INTERNAL_TO_EXTERNAL - Convert internal to external address
-----------------------------------------------------------------
+:c:macro:`RTEMS_INVALID_NAME`
+ The ``id`` parameter was invalid.
-CALLING SEQUENCE:
- .. code-block:: c
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``external`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
- rtems_status_code rtems_port_internal_to_external(
- rtems_id id,
- void *internal,
- void **external
- );
+.. rubric:: CONSTRAINTS:
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+The following constraints apply to this directive:
- * - ``RTEMS_INVALID_ADDRESS``
- - ``external`` is NULL
- * - ``RTEMS_SUCCESSFUL``
- - successful conversion
+* The directive may be called from within interrupt context.
-DESCRIPTION:
- This directive converts a dual-ported memory address from internal to
- external representation so that it can be passed to owner of the DPMA
- represented by the specified port. If the given internal address is an
- invalid dual-ported address, then the external address is set to the given
- internal address.
+* The directive may be called from within device driver initialization context.
-NOTES:
- This directive is callable from an ISR.
+* The directive may be called from within task context.
- This directive will not cause the calling task to be preempted.
+* The directive will not cause the calling task to be preempted.
diff --git a/c-user/dual-ported-memory/introduction.rst b/c-user/dual-ported-memory/introduction.rst
index 752a162..fd7cc8e 100644
--- a/c-user/dual-ported-memory/introduction.rst
+++ b/c-user/dual-ported-memory/introduction.rst
@@ -1,20 +1,49 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
+.. Copyright (C) 2020, 2021 embedded brains GmbH (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:/rtems/dpmem/if/group
+
+.. _DualPortedMemoryManagerIntroduction:
+
Introduction
============
-The dual-ported memory manager provides a mechanism for converting addresses
+.. The following list was generated from:
+.. spec:/rtems/dpmem/if/create
+.. spec:/rtems/dpmem/if/ident
+.. spec:/rtems/dpmem/if/delete
+.. spec:/rtems/dpmem/if/external-to-internal
+.. spec:/rtems/dpmem/if/internal-to-external
+
+The Dual-Ported Memory Manager provides a mechanism for converting addresses
between internal and external representations for multiple dual-ported memory
-areas (DPMA). The directives provided by the dual-ported memory manager are:
+areas (DPMA). The directives provided by the Dual-Ported Memory Manager are:
-- :ref:`rtems_port_create`
+* :ref:`InterfaceRtemsPortCreate` - Creates a port.
-- :ref:`rtems_port_ident`
+* :ref:`InterfaceRtemsPortIdent` - Identifies a port by the object name.
-- :ref:`rtems_port_delete`
+* :ref:`InterfaceRtemsPortDelete` - Deletes the port.
-- :ref:`rtems_port_external_to_internal`
+* :ref:`InterfaceRtemsPortExternalToInternal` - Converts the external address
+ to the internal address.
-- :ref:`rtems_port_internal_to_external`
+* :ref:`InterfaceRtemsPortInternalToExternal` - Converts the internal address
+ to the external address.
diff --git a/c-user/event/directives.rst b/c-user/event/directives.rst
index 9d9bfe4..bf8f74c 100644
--- a/c-user/event/directives.rst
+++ b/c-user/event/directives.rst
@@ -115,7 +115,8 @@ The following constraints apply to this directive:
* The directive may be called from within task context.
-* The directive may unblock another task which may preempt the calling task.
+* The directive may unblock a task. This may cause the calling task to be
+ preempted.
.. Generated from spec:/rtems/event/if/receive
diff --git a/c-user/fatal_error.rst b/c-user/fatal-error/background.rst
index 81cfa0c..6932846 100644
--- a/c-user/fatal_error.rst
+++ b/c-user/fatal-error/background.rst
@@ -2,35 +2,6 @@
.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
-.. index:: fatal errors
-
-.. _fatal_error_manager:
-
-Fatal Error Manager
-*******************
-
-Introduction
-============
-
-The fatal error manager processes all fatal or irrecoverable errors and other
-sources of system termination (for example after :c:func:`exit()`). Fatal
-errors are identified by the (fatal source, error code) pair. The directives
-provided by the fatal error manager are:
-
-- rtems_fatal_ - Invoke the fatal error handler
-
-- rtems_panic_ - Print a message and invoke the fatal error handler
-
-- rtems_shutdown_executive_ - Shutdown RTEMS
-
-- rtems_exception_frame_print_ - Print the CPU exception frame
-
-- rtems_fatal_source_text_ - Return the fatal source text
-
-- rtems_internal_error_text_ - Return the error code text
-
-- rtems_fatal_error_occurred_ - Invoke the fatal error handler (deprecated)
-
Background
==========
@@ -73,6 +44,8 @@ a register), and halt the processor. The precise actions of the RTEMS fatal
error are discussed in the Default Fatal Error Processing chapter of the
Applications Supplement document for a specific target processor.
+.. _FatalErrorSources:
+
Fatal Sources
-------------
@@ -383,274 +356,3 @@ 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``.
-
-Operations
-==========
-
-.. index:: _Terminate
-
-.. _Terminate:
-
-Announcing a Fatal Error
-------------------------
-
-The :c:func:`_Terminate()` internal error handler is invoked when the
-application or the executive itself determines that a fatal error has occurred
-or a final system state is reached (for example after :c:func:`rtems_fatal()`
-or :c:func:`exit()`).
-
-The first action of the internal error handler is to call the fatal extension of
-the user extensions. For the initial extensions the following conditions are
-required
-
-- a valid stack pointer and enough stack space,
-
-- a valid code memory, and
-
-- valid read-only data.
-
-For the initial extensions the read-write data (including .bss segment) is not
-required on single processor configurations. In SMP configurations, however,
-the read-write data must be initialized since this function must determine the
-state of the other processors and request them to shut-down if necessary.
-
-Non-initial extensions require in addition valid read-write data. The board
-support package (BSP) may install an initial extension that performs a system
-reset. In this case the non-initial extensions will be not called.
-
-The fatal extensions are called with three parameters:
-
-- the fatal source,
-
-- a legacy parameter which is always false, and
-
-- an error code with a fatal source dependent content.
-
-Once all fatal extensions executed, the error information will be stored to
-:c:data:`_Internal_errors_What_happened` and the system state is set to
-:c:macro:`SYSTEM_STATE_TERMINATED`.
-
-The final step is to call the CPU port specific :c:func:`_CPU_Fatal_halt()`.
-
-Directives
-==========
-
-This section details the fatal error manager's directives. A subsection is
-dedicated to each of this manager's directives and describes the calling
-sequence, related constants, usage, and status codes.
-
-.. raw:: latex
-
- \clearpage
-
-.. index:: announce fatal error
-.. index:: fatal error, announce
-.. index:: rtems_fatal
-
-.. _rtems_fatal:
-
-FATAL - Invoke the fatal error handler
---------------------------------------
-
-CALLING SEQUENCE:
- .. code-block:: c
-
- void rtems_fatal(
- rtems_fatal_source fatal_source,
- rtems_fatal_code error_code
- ) RTEMS_NO_RETURN;
-
-DIRECTIVE STATUS CODES:
- NONE - This function will not return to the caller.
-
-DESCRIPTION:
- This directive terminates the system.
-
-NOTE:
- Registered :c:func:`atexit()` or :c:func:`on_exit()` handlers are not
- called. Use :c:func:`exit()` in case these handlers should be invoked.
-
-.. raw:: latex
-
- \clearpage
-
-.. index:: panic
-.. index:: rtems_panic
-
-.. _rtems_panic:
-
-PANIC - Print a message and invoke the fatal error handler
-----------------------------------------------------------
-
-CALLING SEQUENCE:
- .. code-block:: c
-
- void rtems_panic(
- const char *fmt,
- ...
- ) RTEMS_NO_RETURN RTEMS_PRINTFLIKE( 1, 2 );
-
-DIRECTIVE STATUS CODES:
- NONE - This function will not return to the caller.
-
-DESCRIPTION:
- This directive prints a message via :c:func:`printk` specified by the
- format and optional parameters and then terminates the system with the
- :c:macro:`RTEMS_FATAL_SOURCE_PANIC` fatal source. The fatal code is set to
- the format string address.
-
-NOTE:
- Registered :c:func:`atexit()` or :c:func:`on_exit()` handlers are not
- called. Use :c:func:`exit()` in case these handlers should be invoked.
-
-.. raw:: latex
-
- \clearpage
-
-.. index:: shutdown RTEMS
-.. index:: rtems_shutdown_executive
-
-.. _rtems_shutdown_executive:
-
-SHUTDOWN_EXECUTIVE - Shutdown RTEMS
------------------------------------
-
-CALLING SEQUENCE:
- .. code-block:: c
-
- void rtems_shutdown_executive(
- uint32_t result
- );
-
-DIRECTIVE STATUS CODES:
- NONE - This function will not return to the caller.
-
-DESCRIPTION:
- This directive is called when the application wishes to shutdown RTEMS.
- The system is terminated with a fatal source of ``RTEMS_FATAL_SOURCE_EXIT``
- and the specified ``result`` code.
-
-NOTES:
- This directive *must* be the last RTEMS directive invoked by an application
- and it *does not return* to the caller.
-
- This directive may be called any time.
-
-.. raw:: latex
-
- \clearpage
-
-.. index:: exception frame
-.. index:: rtems_exception_frame_print
-
-.. _rtems_exception_frame_print:
-
-EXCEPTION_FRAME_PRINT - Prints the exception frame
---------------------------------------------------
-
-CALLING SEQUENCE:
- .. code-block:: c
-
- void rtems_exception_frame_print(
- const rtems_exception_frame *frame
- );
-
-DIRECTIVE STATUS CODES:
- NONE
-
-DESCRIPTION:
- Prints the exception frame via ``printk()``.
-
-.. raw:: latex
-
- \clearpage
-
-.. index:: fatal error
-.. index:: rtems_fatal_source_text
-
-.. _rtems_fatal_source_text:
-
-FATAL_SOURCE_TEXT - Returns a text for a fatal source
------------------------------------------------------
-
-CALLING SEQUENCE:
- .. code-block:: c
-
- const char *rtems_fatal_source_text(
- rtems_fatal_source source
- );
-
-DIRECTIVE STATUS CODES:
- The fatal source text or "?" in case the passed fatal source is invalid.
-
-DESCRIPTION:
- Returns a text for a fatal source. The text for fatal source is the
- enumerator constant.
-
-.. raw:: latex
-
- \clearpage
-
-.. index:: fatal error
-.. index:: rtems_internal_error_text
-
-.. _rtems_internal_error_text:
-
-INTERNAL_ERROR_TEXT - Returns a text for an internal error code
----------------------------------------------------------------
-
-CALLING SEQUENCE:
- .. code-block:: c
-
- const char *rtems_internal_error_text(
- rtems_fatal_code error
- );
-
-DIRECTIVE STATUS CODES:
- The error code text or "?" in case the passed error code is invalid.
-
-DESCRIPTION:
- Returns a text for an internal error code. The text for each internal
- error code is the enumerator constant.
-
-.. raw:: latex
-
- \clearpage
-
-.. index:: announce fatal error
-.. index:: fatal error, announce
-.. index:: rtems_fatal_error_occurred
-
-.. _rtems_fatal_error_occurred:
-
-FATAL_ERROR_OCCURRED - Invoke the fatal error handler (deprecated)
-------------------------------------------------------------------
-
-CALLING SEQUENCE:
- .. code-block:: c
-
- void rtems_fatal_error_occurred(
- uint32_t the_error
- ) RTEMS_NO_RETURN;
-
-DIRECTIVE STATUS CODES:
- NONE - This function will not return to the caller.
-
-DESCRIPTION:
- This directive processes fatal errors. If the FATAL error extension is
- defined in the configuration table, then the user-defined error extension
- is called. If configured and the provided FATAL error extension returns,
- then the RTEMS default error handler is invoked. This directive can be
- invoked by RTEMS or by the user's application code including initialization
- tasks, other tasks, and ISRs.
-
-NOTES:
- This directive is deprecated and should not be used in new code.
-
- This directive supports local operations only.
-
- Unless the user-defined error extension takes special actions such as
- restarting the calling task, this directive WILL NOT RETURN to the caller.
-
- The user-defined extension for this directive may wish to initiate a global
- shutdown.
diff --git a/c-user/fatal-error/directives.rst b/c-user/fatal-error/directives.rst
new file mode 100644
index 0000000..98ce209
--- /dev/null
+++ b/c-user/fatal-error/directives.rst
@@ -0,0 +1,355 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2015, 2021 embedded brains GmbH (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
+
+.. _FatalErrorManagerDirectives:
+
+Directives
+==========
+
+This section details the directives of the Fatal Error Manager. A subsection is
+dedicated to each of this manager's directives and lists the calling sequence,
+parameters, description, return values, and notes of the directive.
+
+.. Generated from spec:/rtems/fatal/if/fatal
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: rtems_fatal()
+.. index:: announce fatal error
+.. index:: fatal error, announce
+
+.. _InterfaceRtemsFatal:
+
+rtems_fatal()
+-------------
+
+Invokes the fatal error handler.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ void rtems_fatal(
+ rtems_fatal_source fatal_source,
+ rtems_fatal_code fatal_code
+ );
+
+.. rubric:: PARAMETERS:
+
+``fatal_source``
+ This parameter is the fatal source.
+
+``fatal_code``
+ This parameter is the fatal code.
+
+.. rubric:: DESCRIPTION:
+
+This directive processes fatal errors. The fatal source is set to the value of
+the ``fatal_source`` parameter. The fatal code is set to the value of the
+``fatal_code`` parameter.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not return to the caller.
+
+* The directive invokes the fatal error extensions in :term:`extension forward
+ order`.
+
+* The directive does not invoke handlers registered by :c:func:`atexit` or
+ :c:func:`on_exit`.
+
+* The directive may terminate the system.
+
+.. Generated from spec:/rtems/fatal/if/panic
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: rtems_panic()
+.. index:: panic
+
+.. _InterfaceRtemsPanic:
+
+rtems_panic()
+-------------
+
+Prints the message and invokes the fatal error handler.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ void rtems_panic( const char *fmt, ... );
+
+.. rubric:: PARAMETERS:
+
+``fmt``
+ This parameter is the message format.
+
+``...``
+ This parameter is a list of optional parameters required by the message
+ format.
+
+.. rubric:: DESCRIPTION:
+
+This directive prints a message via :c:func:`printk` specified by the ``fmt``
+parameter and optional parameters and then invokes the fatal error handler.
+The fatal source is set to :c:macro:`RTEMS_FATAL_SOURCE_PANIC`. The fatal code
+is set to the value of the ``fmt`` parameter value.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not return to the caller.
+
+* The directive invokes the fatal error extensions in :term:`extension forward
+ order`.
+
+* The directive does not invoke handlers registered by :c:func:`atexit` or
+ :c:func:`on_exit`.
+
+* The directive may terminate the system.
+
+.. Generated from spec:/rtems/fatal/if/shutdown-executive
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: rtems_shutdown_executive()
+.. index:: shutdown RTEMS
+
+.. _InterfaceRtemsShutdownExecutive:
+
+rtems_shutdown_executive()
+--------------------------
+
+Invokes the fatal error handler.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ void rtems_shutdown_executive( uint32_t fatal_code );
+
+.. rubric:: PARAMETERS:
+
+``fatal_code``
+ This parameter is the fatal code.
+
+.. rubric:: DESCRIPTION:
+
+This directive processes fatal errors. The fatal source is set to
+:c:macro:`RTEMS_FATAL_SOURCE_EXIT`. The fatal code is set to the value of the
+``fatal_code`` parameter.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not return to the caller.
+
+* The directive invokes the fatal error extensions in :term:`extension forward
+ order`.
+
+* The directive does not invoke handlers registered by :c:func:`atexit` or
+ :c:func:`on_exit`.
+
+* The directive may terminate the system.
+
+.. Generated from spec:/rtems/fatal/if/exception-frame-print
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: rtems_exception_frame_print()
+.. index:: exception frame
+
+.. _InterfaceRtemsExceptionFramePrint:
+
+rtems_exception_frame_print()
+-----------------------------
+
+Prints the exception frame.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ void rtems_exception_frame_print( const rtems_exception_frame *frame );
+
+.. rubric:: PARAMETERS:
+
+``frame``
+ This parameter is the reference to the exception frame to print.
+
+.. rubric:: DESCRIPTION:
+
+The exception frame is printed in an architecture-dependent format using
+:c:func:`printk`.
+
+.. Generated from spec:/rtems/fatal/if/source-text
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: rtems_fatal_source_text()
+.. index:: fatal error
+
+.. _InterfaceRtemsFatalSourceText:
+
+rtems_fatal_source_text()
+-------------------------
+
+Returns a descriptive text for the fatal source.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ const char *rtems_fatal_source_text( rtems_fatal_source fatal_source );
+
+.. rubric:: PARAMETERS:
+
+``fatal_source``
+ This parameter is the fatal source.
+
+.. rubric:: RETURN VALUES:
+
+"?"
+ The ``fatal_source`` parameter value was not a fatal source.
+
+Returns a descriptive text for the fatal source. The text for the fatal source
+is the enumerator constant name.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+.. Generated from spec:/rtems/fatal/if/internal-error-text
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: rtems_internal_error_text()
+.. index:: fatal error
+
+.. _InterfaceRtemsInternalErrorText:
+
+rtems_internal_error_text()
+---------------------------
+
+Returns a descriptive text for the internal error code.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ const char *rtems_internal_error_text( rtems_fatal_code internal_error_code );
+
+.. rubric:: PARAMETERS:
+
+``internal_error_code``
+ This parameter is the internal error code.
+
+.. rubric:: RETURN VALUES:
+
+"?"
+ The ``internal_error_code`` parameter value was not an internal error code.
+
+Returns a descriptive text for the internal error code. The text for the
+internal error code is the enumerator constant name.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+.. Generated from spec:/rtems/fatal/if/error-occurred
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: rtems_fatal_error_occurred()
+
+.. _InterfaceRtemsFatalErrorOccurred:
+
+rtems_fatal_error_occurred()
+----------------------------
+
+Invokes the fatal error handler.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ void rtems_fatal_error_occurred( uint32_t fatal_code );
+
+.. rubric:: PARAMETERS:
+
+``fatal_code``
+ This parameter is the fatal code.
+
+.. rubric:: DESCRIPTION:
+
+This directive processes fatal errors. The fatal source is set to
+:c:macro:`INTERNAL_ERROR_RTEMS_API`. The fatal code is set to the value of the
+``fatal_code`` parameter.
+
+.. rubric:: NOTES:
+
+This directive is deprecated and should not be used in new code. It is
+recommended to not use this directive since error locations cannot be uniquely
+identified. A recommended alternative directive is :ref:`InterfaceRtemsFatal`.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not return to the caller.
+
+* The directive invokes the fatal error extensions in :term:`extension forward
+ order`.
+
+* The directive does not invoke handlers registered by :c:func:`atexit` or
+ :c:func:`on_exit`.
+
+* The directive may terminate the system.
diff --git a/c-user/fatal-error/index.rst b/c-user/fatal-error/index.rst
new file mode 100644
index 0000000..89cbe30
--- /dev/null
+++ b/c-user/fatal-error/index.rst
@@ -0,0 +1,17 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+
+.. index:: fatal errors
+
+.. _RTEMSAPIClassicFatal:
+
+Fatal Error Manager
+*******************
+
+.. toctree::
+
+ introduction
+ background
+ operations
+ directives
diff --git a/c-user/fatal-error/introduction.rst b/c-user/fatal-error/introduction.rst
new file mode 100644
index 0000000..ff86922
--- /dev/null
+++ b/c-user/fatal-error/introduction.rst
@@ -0,0 +1,57 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2015, 2021 embedded brains GmbH (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:/rtems/fatal/if/group
+
+.. _FatalErrorManagerIntroduction:
+
+Introduction
+============
+
+.. The following list was generated from:
+.. spec:/rtems/fatal/if/fatal
+.. spec:/rtems/fatal/if/panic
+.. spec:/rtems/fatal/if/shutdown-executive
+.. spec:/rtems/fatal/if/exception-frame-print
+.. spec:/rtems/fatal/if/source-text
+.. spec:/rtems/fatal/if/internal-error-text
+.. spec:/rtems/fatal/if/error-occurred
+
+The Fatal Error Manager processes all fatal or irrecoverable errors and other
+sources of system termination (for example after :c:func:`exit`). Fatal errors
+are identified by the fatal source and code pair. The directives provided by
+the Fatal Error Manager are:
+
+* :ref:`InterfaceRtemsFatal` - Invokes the fatal error handler.
+
+* :ref:`InterfaceRtemsPanic` - Prints the message and invokes the fatal error
+ handler.
+
+* :ref:`InterfaceRtemsShutdownExecutive` - Invokes the fatal error handler.
+
+* :ref:`InterfaceRtemsExceptionFramePrint` - Prints the exception frame.
+
+* :ref:`InterfaceRtemsFatalSourceText` - Returns a descriptive text for the
+ fatal source.
+
+* :ref:`InterfaceRtemsInternalErrorText` - Returns a descriptive text for the
+ internal error code.
+
+* :ref:`InterfaceRtemsFatalErrorOccurred` - Invokes the fatal error handler.
diff --git a/c-user/fatal-error/operations.rst b/c-user/fatal-error/operations.rst
new file mode 100644
index 0000000..77753d6
--- /dev/null
+++ b/c-user/fatal-error/operations.rst
@@ -0,0 +1,51 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+
+Operations
+==========
+
+.. index:: _Terminate
+
+.. _Terminate:
+
+Announcing a Fatal Error
+------------------------
+
+The :c:func:`_Terminate()` internal error handler is invoked when the
+application or the executive itself determines that a fatal error has occurred
+or a final system state is reached (for example after :c:func:`rtems_fatal()`
+or :c:func:`exit()`).
+
+The first action of the internal error handler is to call the fatal extension of
+the user extensions. For the initial extensions the following conditions are
+required
+
+- a valid stack pointer and enough stack space,
+
+- a valid code memory, and
+
+- valid read-only data.
+
+For the initial extensions the read-write data (including .bss segment) is not
+required on single processor configurations. In SMP configurations, however,
+the read-write data must be initialized since this function must determine the
+state of the other processors and request them to shut-down if necessary.
+
+Non-initial extensions require in addition valid read-write data. The board
+support package (BSP) may install an initial extension that performs a system
+reset. In this case the non-initial extensions will be not called.
+
+The fatal extensions are called with three parameters:
+
+- the fatal source,
+
+- a legacy parameter which is always false, and
+
+- an error code with a fatal source dependent content.
+
+Once all fatal extensions executed, the error information will be stored to
+:c:data:`_Internal_errors_What_happened` and the system state is set to
+:c:macro:`SYSTEM_STATE_TERMINATED`.
+
+The final step is to call the CPU port specific :c:func:`_CPU_Fatal_halt()`.
diff --git a/c-user/glossary.rst b/c-user/glossary.rst
index 71a0242..b3527a7 100644
--- a/c-user/glossary.rst
+++ b/c-user/glossary.rst
@@ -233,6 +233,12 @@ Glossary
A term used to describe memory which can be accessed at two different
addresses.
+ dynamic extension sets
+ The dynamic extension sets are a list of :term:`user extensions`. The list
+ is defined by the system services used by the application and directive calls
+ such as :c:func:`rtems_extension_create`. See also
+ :term:`initial extension sets`.
+
EARS
This term is an acronym for Easy Approach to Requirements Syntax.
@@ -286,6 +292,26 @@ Glossary
An object known by all nodes in a multiprocessor system. An object
created with the GLOBAL attribute will be exported.
+ extension forward order
+ The :term:`user extensions` may be invoked in extension forward order. In
+ forward order, all user extensions of the :term:`initial extension sets` are
+ invoked before all user extensions of the :term:`dynamic extension sets`.
+ In the initial extension sets the order is defined by the table index. The
+ user extension with the lowest table index is invoked first. In the dynamic
+ extension sets the order is defined by the registration order. The first
+ registered user extension is invoked first. See also
+ :term:`extension reverse order`.
+
+ extension reverse order
+ The :term:`user extensions` may be invoked in extension reverse order. In
+ reverse order, all user extensions of the :term:`dynamic extension sets` are
+ invoked before all user extensions of the :term:`initial extension sets`.
+ In the dynamic extension sets the order is defined by the registration order.
+ The last registered user extension is invoked first. In the initial
+ extension sets the order is defined by the table index. The user extension
+ with the highest table index is invoked first. See also
+ :term:`extension forward order`.
+
external address
The address used to access dual-ported memory by all the nodes in a
system which do not own the memory.
@@ -349,8 +375,8 @@ Glossary
A multiprocessor computer system composed of dissimilar processors.
home scheduler
- The home scheduler of a :term:`task` is a :term:`scheduler` which is a
- :term:`eligible scheduler` and which is assigned to the task during the
+ The home scheduler of a :term:`task` is a :term:`scheduler` which is an
+ :term:`eligible scheduler` and which is assigned to the task during its
initialization or explicitly via a directive call such as
:c:func:`rtems_task_set_scheduler`.
@@ -371,6 +397,13 @@ Glossary
An ineligible scheduler of a :term:`task` is a :term:`scheduler` which is
not an :term:`eligible scheduler`.
+ initial extension sets
+ The initial extension sets are a table of :term:`user extensions`. The table
+ is defined by the application configuration for example through the
+ :ref:`CONFIGURE_INITIAL_EXTENSIONS` application configuration option. The
+ initial extension sets cannot be altered during runtime through directive
+ calls. See also :term:`dynamic extension sets`.
+
interface
A specification of the methodology used to connect multiple independent
subsystems.
@@ -895,6 +928,11 @@ Glossary
target
The system on which the application will ultimately execute.
+ target architecture
+ The target architecture is the instruction set architecture (ISA) of the
+ :term:`target`. Some RTEMS features depend on the target architecture. For
+ the details consult the *RTEMS CPU Architecture Supplement*.
+
TAS
This term is an acronym for Test-And-Set.
@@ -991,8 +1029,11 @@ Glossary
A table which contains the entry points for each user extensions.
user extensions
- Software routines provided by the application to enhance the
- functionality of RTEMS.
+ User extensions are software routines provided by the application to enhance
+ the functionality of RTEMS. An active user extension is either in the
+ :term:`initial extension sets` or the :term:`dynamic extension sets`. User
+ extensions are invoked in :term:`extension forward order` or
+ :term:`extension reverse order`.
User Initialization Tasks Table
A table which contains the information needed to create and start each of
diff --git a/c-user/index.rst b/c-user/index.rst
index 2f8109a..5cd87af 100644
--- a/c-user/index.rst
+++ b/c-user/index.rst
@@ -29,7 +29,7 @@ RTEMS Classic API Guide (|version|).
key_concepts
rtems_data_types
scheduling-concepts/index
- initialization
+ initialization/index
task/index
interrupt/index
clock/index
@@ -44,12 +44,12 @@ RTEMS Classic API Guide (|version|).
region/index
dual-ported-memory/index
io/index
- fatal_error
+ fatal-error/index
board_support_packages
user-extensions/index
config/index
self_contained_objects
- multiprocessing
+ multiprocessing/index
symmetric_multiprocessing_services
pci_library
stack_bounds_checker
diff --git a/c-user/initialization/background.rst b/c-user/initialization/background.rst
new file mode 100644
index 0000000..36d8ebd
--- /dev/null
+++ b/c-user/initialization/background.rst
@@ -0,0 +1,48 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+
+Background
+==========
+
+.. index:: initialization tasks
+
+Initialization Tasks
+--------------------
+
+Initialization task(s) are the mechanism by which RTEMS transfers initial
+control to the user's application. Initialization tasks differ from other
+application tasks in that they are defined in the User Initialization Tasks
+Table and automatically created and started by RTEMS as part of its
+initialization sequence. Since the initialization tasks are scheduled using
+the same algorithm as all other RTEMS tasks, they must be configured at a
+priority and mode which will ensure that they will complete execution before
+other application tasks execute. Although there is no upper limit on the
+number of initialization tasks, an application is required to define at least
+one.
+
+A typical initialization task will create and start the static set of
+application tasks. It may also create any other objects used by the
+application. Initialization tasks which only perform initialization should
+delete themselves upon completion to free resources for other tasks.
+Initialization tasks may transform themselves into a "normal" application task.
+This transformation typically involves changing priority and execution mode.
+RTEMS does not automatically delete the initialization tasks.
+
+The Idle Task
+-------------
+
+The Idle Task is the lowest priority task in a system and executes only when no
+other task is ready to execute. The default implementation of this task
+consists of an infinite loop. RTEMS allows the Idle Task body to be replaced by
+a CPU specific implementation, a BSP specific implementation or an application
+specific implementation.
+
+The Idle Task is preemptible and *WILL* be preempted when any other task is
+made ready to execute. This characteristic is critical to the overall behavior
+of any application.
+
+Initialization Manager Failure
+------------------------------
+
+System initialization errors are fatal. See :ref:`internal_errors`.
diff --git a/c-user/initialization/directives.rst b/c-user/initialization/directives.rst
new file mode 100644
index 0000000..ca5c9c2
--- /dev/null
+++ b/c-user/initialization/directives.rst
@@ -0,0 +1,69 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2015, 2021 embedded brains GmbH (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
+
+.. _InitializationManagerDirectives:
+
+Directives
+==========
+
+This section details the directives of the Initialization Manager. A subsection
+is dedicated to each of this manager's directives and lists the calling
+sequence, parameters, description, return values, and notes of the directive.
+
+.. Generated from spec:/rtems/init/if/initialize-executive
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: rtems_initialize_executive()
+.. index:: initialize RTEMS
+.. index:: start multitasking
+
+.. _InterfaceRtemsInitializeExecutive:
+
+rtems_initialize_executive()
+----------------------------
+
+Initializes the system and starts multitasking.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ void rtems_initialize_executive( void );
+
+.. rubric:: DESCRIPTION:
+
+Iterates through the system initialization linker set and invokes the
+registered handlers. The final step is to start multitasking.
+
+.. rubric:: NOTES:
+
+Errors in the initialization sequence are usually fatal and lead to a system
+termination.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive should be called by :c:func:`boot_card` only.
+
+* The directive will not return to the caller.
diff --git a/c-user/initialization/index.rst b/c-user/initialization/index.rst
new file mode 100644
index 0000000..b41fcdd
--- /dev/null
+++ b/c-user/initialization/index.rst
@@ -0,0 +1,15 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+
+.. _RTEMSAPIClassicInit:
+
+Initialization Manager
+**********************
+
+.. toctree::
+
+ introduction
+ background
+ operations
+ directives
diff --git a/c-user/initialization/introduction.rst b/c-user/initialization/introduction.rst
new file mode 100644
index 0000000..173e60f
--- /dev/null
+++ b/c-user/initialization/introduction.rst
@@ -0,0 +1,39 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2015, 2021 embedded brains GmbH (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:/rtems/init/if/group
+
+.. _InitializationManagerIntroduction:
+
+Introduction
+============
+
+.. The following list was generated from:
+.. spec:/rtems/init/if/initialize-executive
+
+The Initialization Manager is responsible for initializing the system.
+
+The system initialization includes the initialization of the Board Support
+Package, RTEMS, device drivers, the root filesystem, and the application. The
+:ref:`RTEMSAPIClassicFatal` is responsible for the system shutdown. The
+directives provided by the Initialization Manager are:
+
+* :ref:`InterfaceRtemsInitializeExecutive` - Initializes the system and starts
+ multitasking.
diff --git a/c-user/initialization.rst b/c-user/initialization/operations.rst
index fa7afb5..db5c94b 100644
--- a/c-user/initialization.rst
+++ b/c-user/initialization/operations.rst
@@ -2,66 +2,6 @@
.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
-Initialization Manager
-**********************
-
-Introduction
-============
-
-The Initialization Manager is responsible for initializing the Board Support
-Package, RTEMS, device drivers, the root filesystem and the application. The
-:ref:`Fatal Error Manager <fatal_error_manager>` is responsible for the system
-shutdown.
-
-The Initialization Manager provides only one directive:
-
-- rtems_initialize_executive_ - Initialize RTEMS
-
-Background
-==========
-
-.. index:: initialization tasks
-
-Initialization Tasks
---------------------
-
-Initialization task(s) are the mechanism by which RTEMS transfers initial
-control to the user's application. Initialization tasks differ from other
-application tasks in that they are defined in the User Initialization Tasks
-Table and automatically created and started by RTEMS as part of its
-initialization sequence. Since the initialization tasks are scheduled using
-the same algorithm as all other RTEMS tasks, they must be configured at a
-priority and mode which will ensure that they will complete execution before
-other application tasks execute. Although there is no upper limit on the
-number of initialization tasks, an application is required to define at least
-one.
-
-A typical initialization task will create and start the static set of
-application tasks. It may also create any other objects used by the
-application. Initialization tasks which only perform initialization should
-delete themselves upon completion to free resources for other tasks.
-Initialization tasks may transform themselves into a "normal" application task.
-This transformation typically involves changing priority and execution mode.
-RTEMS does not automatically delete the initialization tasks.
-
-The Idle Task
--------------
-
-The Idle Task is the lowest priority task in a system and executes only when no
-other task is ready to execute. The default implementation of this task
-consists of an infinite loop. RTEMS allows the Idle Task body to be replaced by
-a CPU specific implementation, a BSP specific implementation or an application
-specific implementation.
-
-The Idle Task is preemptible and *WILL* be preempted when any other task is
-made ready to execute. This characteristic is critical to the overall behavior
-of any application.
-
-Initialization Manager Failure
-------------------------------
-
-System initialization errors are fatal. See :ref:`internal_errors`.
-
Operations
==========
@@ -418,41 +358,3 @@ should output:
c()
b()
A:A()
-
-Directives
-==========
-
-This section details the Initialization Manager's directives. A subsection is
-dedicated to each of this manager's directives and describes the calling
-sequence, related constants, usage, and status codes.
-
-.. raw:: latex
-
- \clearpage
-
-.. index:: initialize RTEMS
-.. index:: start multitasking
-.. index:: rtems_initialize_executive
-
-.. _rtems_initialize_executive:
-
-INITIALIZE_EXECUTIVE - Initialize RTEMS
----------------------------------------
-
-CALLING SEQUENCE:
- .. code-block:: c
-
- void rtems_initialize_executive(void);
-
-DIRECTIVE STATUS CODES:
- NONE - This function will not return to the caller.
-
-DESCRIPTION:
- Iterates through the system initialization linker set and invokes the
- registered handlers. The final step is to start multitasking.
-
-NOTES:
- This directive should be called by :c:func:`boot_card()` only.
-
- This directive *does not return* to the caller. Errors in the
- initialization sequence are usually fatal and lead to a system termination.
diff --git a/c-user/interrupt/directives.rst b/c-user/interrupt/directives.rst
index 95181db..2b15fd6 100644
--- a/c-user/interrupt/directives.rst
+++ b/c-user/interrupt/directives.rst
@@ -1,521 +1,1111 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
+.. Copyright (C) 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
+
+.. _InterruptManagerDirectives:
+
Directives
==========
-This section details the interrupt manager's directives. A subsection is
-dedicated to each of this manager's directives and describes the calling
-sequence, related constants, usage, and status codes.
+This section details the directives of the Interrupt Manager. A subsection is
+dedicated to each of this manager's directives and lists the calling sequence,
+parameters, description, return values, and notes of the directive.
+
+.. Generated from spec:/rtems/intr/if/catch
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_interrupt_catch()
.. index:: establish an ISR
.. index:: install an ISR
-.. index:: rtems_interrupt_catch
-.. _rtems_interrupt_catch:
+.. _InterfaceRtemsInterruptCatch:
-INTERRUPT_CATCH - Establish an ISR
-----------------------------------
+rtems_interrupt_catch()
+-----------------------
+
+Establishes an interrupt service routine.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_interrupt_catch(
+ rtems_isr_entry new_isr_handler,
+ rtems_vector_number vector,
+ rtems_isr_entry *old_isr_handler
+ );
+
+.. rubric:: PARAMETERS:
+
+``new_isr_handler``
+ This parameter is the new interrupt service routine.
+
+``vector``
+ This parameter is the interrupt vector number.
+
+``old_isr_handler``
+ This parameter is the pointer to an :c:type:`rtems_isr_entry` variable.
+ When the directive call is successful, the previous interrupt service
+ routine established for this interrupt vector will be stored in this
+ variable.
+
+.. rubric:: DESCRIPTION:
+
+This directive establishes an interrupt service routine (ISR) for the interrupt
+specified by the ``vector`` number. The ``new_isr_handler`` parameter
+specifies the entry point of the ISR. The entry point of the previous ISR for
+the specified vector is returned in ``old_isr_handler``.
+
+To release an interrupt vector, pass the old handler's address obtained when
+the vector was first capture.
+
+.. rubric:: RETURN VALUES:
+
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_NUMBER`
+ The interrupt vector number was illegal.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``new_isr_handler`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``old_isr_handler`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
-CALLING SEQUENCE:
- .. code-block:: c
+.. rubric:: CONSTRAINTS:
- rtems_status_code rtems_interrupt_catch(
- rtems_isr_entry new_isr_handler,
- rtems_vector_number vector,
- rtems_isr_entry *old_isr_handler
- );
+The following constraints apply to this directive:
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-wrap
+* The directive may be called from within interrupt context.
- * - ``RTEMS_SUCCESSFUL``
- - ISR established successfully
- * - ``RTEMS_INVALID_NUMBER``
- - illegal vector number
- * - ``RTEMS_INVALID_ADDRESS``
- - illegal ISR entry point or invalid ``old_isr_handler``
+* The directive may be called from within device driver initialization context.
-DESCRIPTION:
- This directive establishes an interrupt service routine (ISR) for the
- specified interrupt vector number. The ``new_isr_handler`` parameter
- specifies the entry point of the ISR. The entry point of the previous ISR
- for the specified vector is returned in ``old_isr_handler``.
+* The directive may be called from within task context.
- To release an interrupt vector, pass the old handler's address obtained
- when the vector was first capture.
+* The directive will not cause the calling task to be preempted.
-NOTES:
- This directive will not cause the calling task to be preempted.
+* The directive is only available where the :term:`target architecture` support
+ enabled simple vectored interrupts.
+
+.. Generated from spec:/rtems/intr/if/disable
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_interrupt_disable()
.. index:: disable interrupts
-.. index:: rtems_interrupt_disable
-.. _rtems_interrupt_disable:
+.. _InterfaceRtemsInterruptDisable:
+
+rtems_interrupt_disable()
+-------------------------
+
+Disables the maskable interrupts on the current processor.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ #define rtems_interrupt_disable( 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.
+
+.. rubric:: DESCRIPTION:
-INTERRUPT_DISABLE - Disable Interrupts
---------------------------------------
+This directive disables all maskable interrupts on the current processor and
+returns the previous interrupt level in ``isr_cookie``.
-CALLING SEQUENCE:
- .. code-block:: c
+.. rubric:: NOTES:
- void rtems_interrupt_disable(
- rtems_interrupt_level level
- );
+A later invocation of the :ref:`InterfaceRtemsInterruptEnable` directive should
+be used to restore the previous interrupt level.
-DIRECTIVE STATUS CODES:
- NONE
+This directive is implemented as a macro which sets the ``isr_cookie``
+parameter.
-DESCRIPTION:
- This directive disables all maskable interrupts and returns the previous
- interrupt level in ``level``.
+.. code-block:: c
+ :linenos:
-NOTES:
- A later invocation of the ``rtems_interrupt_enable`` directive should be
- used to restore the interrupt level.
+ #include <rtems.h>
- This directive is implemented as a macro which sets the ``level``
- parameter.
+ void local_critical_section( void )
+ {
+ rtems_interrupt_level level;
- This directive will not cause the calling task to be preempted.
+ // Please note that the rtems_interrupt_disable() is a macro. The
+ // previous interrupt level (before the maskable interrupts are
+ // disabled) is returned here in the level macro parameter. This
+ // would be wrong:
+ //
+ // rtems_interrupt_disable( &level );
+ rtems_interrupt_disable( level );
- This directive is only available in uniprocessor configurations. The
- directive ``rtems_interrupt_local_disable`` is available in all
- configurations.
+ // Here is the critical section: maskable interrupts are disabled
- .. code-block:: c
+ {
+ rtems_interrupt_level nested_level;
- void critical_section( void )
- {
- rtems_interrupt_level level;
+ rtems_interrupt_disable( nested_level );
- /*
- * Please note that the rtems_interrupt_disable() is a macro. The
- * previous interrupt level (before the maskable interrupts are
- * disabled) is returned here in the level macro parameter. This
- * would be wrong:
- *
- * rtems_interrupt_disable( &level );
- */
- rtems_interrupt_disable( level );
+ // Here is a nested critical section
- /* Critical section, maskable interrupts are disabled */
+ rtems_interrupt_enable( nested_level );
+ }
- {
- rtems_interrupt_level level2;
+ // Maskable interrupts are still disabled
- rtems_interrupt_disable( level2 );
+ rtems_interrupt_enable( level );
+ }
- /* Nested critical section */
+.. rubric:: CONSTRAINTS:
- rtems_interrupt_enable( level2 );
- }
+The following constraints apply to this directive:
- /* Maskable interrupts are still disabled */
+* The directive may be called from within any runtime context.
- rtems_interrupt_enable( level );
- }
+* The directive will not cause the calling task to be preempted.
+
+* Where the system was built with SMP support enabled, the directive is not
+ available. Its use will result in compiler warnings and linker errors. The
+ :ref:`InterfaceRtemsInterruptLocalDisable` and
+ :ref:`InterfaceRtemsInterruptLocalEnable` directives are available in all
+ build configurations.
+
+.. Generated from spec:/rtems/intr/if/enable
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_interrupt_enable()
.. index:: enable interrupts
.. index:: restore interrupt level
-.. index:: rtems_interrupt_enable
-.. _rtems_interrupt_enable:
+.. _InterfaceRtemsInterruptEnable:
+
+rtems_interrupt_enable()
+------------------------
+
+Restores the previous interrupt level on the current processor.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ #define rtems_interrupt_enable( isr_cookie )
+
+.. rubric:: PARAMETERS:
+
+``isr_cookie``
+ This parameter is the previous interrupt level to restore. The value must
+ be obtained by a previous call to :ref:`InterfaceRtemsInterruptDisable` or
+ :ref:`InterfaceRtemsInterruptFlash`.
-INTERRUPT_ENABLE - Restore Interrupt Level
-------------------------------------------
+.. rubric:: DESCRIPTION:
-CALLING SEQUENCE:
- .. code-block:: c
+This directive restores the interrupt level specified by ``isr_cookie`` on the
+current processor.
- void rtems_interrupt_enable(
- rtems_interrupt_level level
- );
+.. rubric:: NOTES:
-DIRECTIVE STATUS CODES:
- NONE
+The ``isr_cookie`` parameter value must be obtained by a previous call to
+:ref:`InterfaceRtemsInterruptDisable` or :ref:`InterfaceRtemsInterruptFlash`.
+Using an otherwise obtained value is undefined behaviour.
-DESCRIPTION:
- This directive restores the interrupt level specified by ``level``.
+This directive is unsuitable to enable particular interrupt sources, for
+example in an interrupt controller.
-NOTES:
- The ``level`` parameter value must be obtained by a previous call to
- ``rtems_interrupt_disable`` or ``rtems_interrupt_flash``. Using an
- otherwise obtained value is undefined behaviour.
+.. rubric:: CONSTRAINTS:
- This directive is unsuitable to enable particular interrupt sources, for
- example in an interrupt controller.
+The following constraints apply to this directive:
- This directive will not cause the calling task to be preempted.
+* The directive may be called from within any runtime context.
- This directive is only available in uniprocessor configurations. The
- directive ``rtems_interrupt_local_enable`` is available in all
- configurations.
+* The directive will not cause the calling task to be preempted.
+
+* While at least one maskable interrupt is pending, when the directive enables
+ maskable interrupts, the pending interrupts are immediately serviced. The
+ interrupt service routines may unblock higher priority tasks which may
+ preempt the calling task.
+
+* Where the system was built with SMP support enabled, the directive is not
+ available. Its use will result in compiler warnings and linker errors. The
+ :ref:`InterfaceRtemsInterruptLocalDisable` and
+ :ref:`InterfaceRtemsInterruptLocalEnable` directives are available in all
+ build configurations.
+
+.. Generated from spec:/rtems/intr/if/flash
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_interrupt_flash()
.. index:: flash interrupts
-.. index:: rtems_interrupt_flash
-.. _rtems_interrupt_flash:
+.. _InterfaceRtemsInterruptFlash:
-INTERRUPT_FLASH - Flash Interrupts
-----------------------------------
+rtems_interrupt_flash()
+-----------------------
+
+Flashes interrupts on the current processor.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ #define rtems_interrupt_flash( isr_cookie )
+
+.. rubric:: PARAMETERS:
-CALLING SEQUENCE:
- .. code-block:: c
+``isr_cookie``
+ This parameter is the previous interrupt level.
- void rtems_interrupt_flash(
- rtems_interrupt_level level
- );
+.. rubric:: DESCRIPTION:
-DIRECTIVE STATUS CODES:
- NONE
+This directive is functionally equivalent to a calling
+:ref:`InterfaceRtemsInterruptEnable` immediately followed by a
+:ref:`InterfaceRtemsInterruptDisable`. On some architectures it is possible to
+provide an optimized implementation for this sequence.
-DESCRIPTION:
- This directive is functionally equivalent to a
- ``rtems_interrupt_enable( level )`` immediately followed by a
- ``rtems_interrupt_disable( level )``. On some
- architectures it is possible to provide an optimized implementation for
- this sequence.
+.. rubric:: NOTES:
-NOTES:
- The ``level`` parameter value must be obtained by a previous call to
- ``rtems_interrupt_disable`` or ``rtems_interrupt_flash``. Using an
- otherwise obtained value is undefined behaviour.
+The ``isr_cookie`` parameter value must be obtained by a previous call to
+:ref:`InterfaceRtemsInterruptDisable` or :ref:`InterfaceRtemsInterruptFlash`.
+Using an otherwise obtained value is undefined behaviour.
- This directive will not cause the calling task to be preempted.
+Historically, the interrupt flash directive was heavily used in the operating
+system implementation. However, this is no longer the case. The interrupt
+flash directive is provided for backward compatibility reasons.
- This directive is only available in uniprocessor configurations. The
- directives ``rtems_interrupt_local_disable`` and
- ``rtems_interrupt_local_enable`` are available in all configurations.
+.. rubric:: CONSTRAINTS:
- Historically, the interrupt flash directive was heavily used in the
- operating system implementation. However, this is no longer the case. The
- interrupt flash directive is provided for backward compatibility reasons.
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+* Where the system was built with SMP support enabled, the directive is not
+ available. Its use will result in compiler warnings and linker errors. The
+ :ref:`InterfaceRtemsInterruptLocalDisable` and
+ :ref:`InterfaceRtemsInterruptLocalEnable` directives are available in all
+ build configurations.
+
+.. Generated from spec:/rtems/intr/if/local-disable
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_interrupt_local_disable()
.. index:: disable interrupts
-.. index:: rtems_interrupt_local_disable
-.. _rtems_interrupt_local_disable:
+.. _InterfaceRtemsInterruptLocalDisable:
+
+rtems_interrupt_local_disable()
+-------------------------------
+
+Disables the maskable interrupts on the current processor.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ #define rtems_interrupt_local_disable( isr_cookie )
-INTERRUPT_LOCAL_DISABLE - Disable Interrupts on Current Processor
------------------------------------------------------------------
+.. rubric:: PARAMETERS:
-CALLING SEQUENCE:
- .. code-block:: c
+``isr_cookie``
+ This parameter is a variable of type :c:type:`rtems_interrupt_level` which
+ will be used to save the previous interrupt level.
- void rtems_interrupt_local_disable(
- rtems_interrupt_level level
- );
+.. rubric:: DESCRIPTION:
-DIRECTIVE STATUS CODES:
- NONE
+This directive disables all maskable interrupts on the current processor and
+returns the previous interrupt level in ``isr_cookie``.
-DESCRIPTION:
- This directive disables all maskable interrupts on the current processor
- and returns the previous interrupt level in ``level``.
+.. rubric:: NOTES:
-NOTES:
- A later invocation of the ``rtems_interrupt_local_enable`` directive should
- be used to restore the interrupt level.
+A later invocation of the :ref:`InterfaceRtemsInterruptLocalEnable` directive
+should be used to restore the previous interrupt level.
- This directive is implemented as a macro which sets the ``level``
- parameter.
+This directive is implemented as a macro which sets the ``isr_cookie``
+parameter.
- This directive will not cause the calling task to be preempted.
+Where the system was built with SMP support enabled, this will not ensure
+system wide mutual exclusion. Use interrupt locks instead, see
+:ref:`InterfaceRtemsInterruptLockAcquire`. Interrupt disabled critical
+sections may be used to access processor-specific data structures or disable
+thread dispatching.
- In SMP configurations, this will not ensure system wide mutual exclusion.
- Use interrupt locks instead.
+.. code-block:: c
+ :linenos:
- .. code-block:: c
+ #include <rtems.h>
- void local_critical_section( void )
- {
- rtems_interrupt_level level;
+ void local_critical_section( void )
+ {
+ rtems_interrupt_level level;
- /*
- * Please note that the rtems_interrupt_local_disable() is a macro.
- * The previous interrupt level (before the maskable interrupts are
- * disabled) is returned here in the level macro parameter. This
- * would be wrong:
- *
- * rtems_interrupt_local_disable( &level );
- */
- rtems_interrupt_local_disable( level );
+ // Please note that the rtems_interrupt_local_disable() is a macro.
+ // The previous interrupt level (before the maskable interrupts are
+ // disabled) is returned here in the level macro parameter. This would
+ // be wrong:
+ //
+ // rtems_interrupt_local_disable( &level );
+ rtems_interrupt_local_disable( level );
- /*
- * Local critical section, maskable interrupts on the current
- * processor are disabled.
- */
+ // Here is the critical section: maskable interrupts are disabled
- {
- rtems_interrupt_level level2;
+ {
+ rtems_interrupt_level nested_level;
- rtems_interrupt_local_disable( level2 );
+ rtems_interrupt_local_disable( nested_level );
- /* Nested local critical section */
+ // Here is a nested critical section
- rtems_interrupt_local_enable( level2 );
- }
+ rtems_interrupt_local_enable( nested_level );
+ }
- /* Maskable interrupts are still disabled */
+ // Maskable interrupts are still disabled
- rtems_interrupt_local_enable( level );
- }
+ rtems_interrupt_local_enable( level );
+ }
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/intr/if/local-enable
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_interrupt_local_enable()
.. index:: enable interrupts
.. index:: restore interrupt level
-.. index:: rtems_interrupt_local_enable
-.. _rtems_interrupt_local_enable:
+.. _InterfaceRtemsInterruptLocalEnable:
+
+rtems_interrupt_local_enable()
+------------------------------
+
+Restores the previous interrupt level on the current processor.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
-INTERRUPT_LOCAL_ENABLE - Restore Interrupt Level on Current Processor
----------------------------------------------------------------------
+ #define rtems_interrupt_local_enable( isr_cookie )
-CALLING SEQUENCE:
- .. code-block:: c
+.. rubric:: PARAMETERS:
- void rtems_interrupt_local_enable(
- rtems_interrupt_level level
- );
+``isr_cookie``
+ This parameter is the previous interrupt level to restore. The value must
+ be obtained by a previous call to
+ :ref:`InterfaceRtemsInterruptLocalDisable`.
-DIRECTIVE STATUS CODES:
- NONE
+.. rubric:: DESCRIPTION:
-DESCRIPTION:
- This directive restores the interrupt level specified by ``level`` on the
- current processor.
+This directive restores the interrupt level specified by ``isr_cookie`` on the
+current processor.
-NOTES:
- The ``level`` parameter value must be obtained by a previous call to
- ``rtems_interrupt_local_disable``. Using an otherwise obtained value is
- undefined behaviour.
+.. rubric:: NOTES:
- This directive is unsuitable to enable particular interrupt sources, for
- example in an interrupt controller.
+The ``isr_cookie`` parameter value must be obtained by a previous call to
+:ref:`InterfaceRtemsInterruptLocalDisable`. Using an otherwise obtained value
+is undefined behaviour.
- This directive will not cause the calling task to be preempted.
+This directive is unsuitable to enable particular interrupt sources, for
+example in an interrupt controller.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+* While at least one maskable interrupt is pending, when the directive enables
+ maskable interrupts, the pending interrupts are immediately serviced. The
+ interrupt service routines may unblock higher priority tasks which may
+ preempt the calling task.
+
+.. Generated from spec:/rtems/intr/if/is-in-progress
.. raw:: latex
- \clearpage
+ \clearpage
+
+.. index:: rtems_interrupt_is_in_progress()
+.. index:: is interrupt in progress
+
+.. _InterfaceRtemsInterruptIsInProgress:
-.. index:: rtems_interrupt_lock_initialize
+rtems_interrupt_is_in_progress()
+--------------------------------
-.. _rtems_interrupt_lock_initialize:
+Checks if an ISR is in progress on the current processor.
-INTERRUPT_LOCK_INITIALIZE - Initialize an ISR Lock
---------------------------------------------------
+.. rubric:: CALLING SEQUENCE:
-CALLING SEQUENCE:
- .. code-block:: c
+.. code-block:: c
- void rtems_interrupt_lock_initialize(
- rtems_interrupt_lock *lock,
- const char *name
- );
+ #define rtems_interrupt_is_in_progress()
-DIRECTIVE STATUS CODES:
- NONE
+.. rubric:: DESCRIPTION:
-DESCRIPTION:
- Initializes an interrupt lock. The name must be persistent throughout the
- lifetime of the lock.
+This directive returns ``true``, if the current processor is currently
+servicing an interrupt, and ``false`` otherwise. A return value of ``true``
+indicates that the caller is an interrupt service routine, **not** a task. The
+directives available to an interrupt service routine are restricted.
-NOTES:
- Concurrent initialization leads to unpredictable results.
+.. rubric:: RETURN VALUES:
+
+Returns true, if the current processor is currently servicing an interrupt,
+otherwise false.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/intr/if/cause
.. raw:: latex
- \clearpage
+ \clearpage
+
+.. index:: rtems_interrupt_cause()
+
+.. _InterfaceRtemsInterruptCause:
+
+rtems_interrupt_cause()
+-----------------------
-.. index:: rtems_interrupt_lock_acquire
+Causes the interrupt.
-.. _rtems_interrupt_lock_acquire:
+.. rubric:: CALLING SEQUENCE:
-INTERRUPT_LOCK_ACQUIRE - Acquire an ISR Lock
---------------------------------------------
+.. code-block:: c
-CALLING SEQUENCE:
- .. code-block:: c
+ #define rtems_interrupt_cause( vector )
- void rtems_interrupt_lock_acquire(
- rtems_interrupt_lock *lock,
- rtems_interrupt_lock_context *lock_context
- );
+.. rubric:: PARAMETERS:
-DIRECTIVE STATUS CODES:
- NONE
+``vector``
+ This parameter is the vector number of the interrupt to cause.
-DESCRIPTION:
- Maskable interrupts will be disabled. In SMP configurations, this
- directive acquires an SMP lock.
+.. rubric:: CONSTRAINTS:
-NOTES:
- A separate lock context must be provided for each acquire/release pair, for
- example an automatic variable.
+The following constraints apply to this directive:
- An attempt to recursively acquire the lock may result in an infinite loop
- with maskable interrupts disabled.
+* The directive is not implemented.
- This directive will not cause the calling thread to be preempted. This
- directive can be used in thread and interrupt context.
+.. Generated from spec:/rtems/intr/if/clear
.. raw:: latex
- \clearpage
+ \clearpage
-.. index:: rtems_interrupt_lock_release
+.. index:: rtems_interrupt_clear()
-.. _rtems_interrupt_lock_release:
+.. _InterfaceRtemsInterruptClear:
-INTERRUPT_LOCK_RELEASE - Release an ISR Lock
---------------------------------------------
+rtems_interrupt_clear()
+-----------------------
-CALLING SEQUENCE:
- .. code-block:: c
+Clears the interrupt.
- void rtems_interrupt_lock_release(
- rtems_interrupt_lock *lock,
- rtems_interrupt_lock_context *lock_context
- );
+.. rubric:: CALLING SEQUENCE:
-DIRECTIVE STATUS CODES:
- NONE
+.. code-block:: c
-DESCRIPTION:
- The interrupt level will be restored. In SMP configurations, this
- directive releases an SMP lock.
+ #define rtems_interrupt_clear( vector )
-NOTES:
- The lock context must be the one used to acquire the lock, otherwise the
- result is unpredictable.
+.. rubric:: PARAMETERS:
- This directive will not cause the calling thread to be preempted. This
- directive can be used in thread and interrupt context.
+``vector``
+ This parameter is the vector number of the interrupt to clear.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive is not implemented.
+
+.. Generated from spec:/rtems/intr/if/lock-initialize
.. raw:: latex
- \clearpage
+ \clearpage
+
+.. index:: rtems_interrupt_lock_initialize()
-.. index:: rtems_interrupt_lock_acquire_isr
+.. _InterfaceRtemsInterruptLockInitialize:
-.. _rtems_interrupt_lock_acquire_isr:
+rtems_interrupt_lock_initialize()
+---------------------------------
-INTERRUPT_LOCK_ACQUIRE_ISR - Acquire an ISR Lock from ISR
----------------------------------------------------------
+Initializes the ISR lock.
-CALLING SEQUENCE:
- .. code-block:: c
+.. rubric:: CALLING SEQUENCE:
- void rtems_interrupt_lock_acquire_isr(
- rtems_interrupt_lock *lock,
- rtems_interrupt_lock_context *lock_context
- );
+.. code-block:: c
-DIRECTIVE STATUS CODES:
- NONE
+ #define rtems_interrupt_lock_initialize( lock, name )
-DESCRIPTION:
- The interrupt level will remain unchanged. In SMP configurations, this
- directive acquires an SMP lock.
+.. rubric:: PARAMETERS:
-NOTES:
- A separate lock context must be provided for each acquire/release pair, for
- example an automatic variable.
+``lock``
+ This parameter is the ISR lock to initialize.
- An attempt to recursively acquire the lock may result in an infinite loop.
+``name``
+ This parameter is the ISR lock name. It shall be a string. The name is
+ only used where the system was built with profiling support enabled.
- This directive is intended for device drivers and should be called from the
- corresponding interrupt service routine.
+.. rubric:: NOTES:
- In case the corresponding interrupt service routine can be interrupted by
- higher priority interrupts and these interrupts enter the critical section
- protected by this lock, then the result is unpredictable.
+ISR locks may also be statically defined by
+:ref:`InterfaceRTEMSINTERRUPTLOCKDEFINE` or statically initialized by
+:ref:`InterfaceRTEMSINTERRUPTLOCKINITIALIZER`.
+
+.. Generated from spec:/rtems/intr/if/lock-destroy
.. raw:: latex
- \clearpage
+ \clearpage
+
+.. index:: rtems_interrupt_lock_destroy()
+
+.. _InterfaceRtemsInterruptLockDestroy:
+
+rtems_interrupt_lock_destroy()
+------------------------------
-.. index:: rtems_interrupt_lock_release_isr
+Destroys the ISR lock.
-.. _rtems_interrupt_lock_release_isr:
+.. rubric:: CALLING SEQUENCE:
-INTERRUPT_LOCK_RELEASE_ISR - Release an ISR Lock from ISR
----------------------------------------------------------
+.. code-block:: c
-CALLING SEQUENCE:
- .. code-block:: c
+ #define rtems_interrupt_lock_destroy( lock )
- void rtems_interrupt_lock_release_isr(
- rtems_interrupt_lock *lock,
- rtems_interrupt_lock_context *lock_context
- );
+.. rubric:: PARAMETERS:
-DIRECTIVE STATUS CODES:
- NONE
+``lock``
+ This parameter is the ISR lock to destroy.
-DESCRIPTION:
- The interrupt level will remain unchanged. In SMP configurations, this
- directive releases an SMP lock.
+.. rubric:: NOTES:
-NOTES:
- The lock context must be the one used to acquire the lock, otherwise the
- result is unpredictable.
+The lock must have been dynamically initialized by
+:ref:`InterfaceRtemsInterruptLockInitialize`, statically defined by
+:ref:`InterfaceRTEMSINTERRUPTLOCKDEFINE`, or statically initialized by
+:ref:`InterfaceRTEMSINTERRUPTLOCKINITIALIZER`.
- This directive is intended for device drivers and should be called from the
- corresponding interrupt service routine.
+Concurrent lock use during the destruction or concurrent destruction leads to
+unpredictable results.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/intr/if/lock-acquire
.. raw:: latex
- \clearpage
+ \clearpage
-.. index:: is interrupt in progress
-.. index:: rtems_interrupt_is_in_progress
+.. index:: rtems_interrupt_lock_acquire()
+
+.. _InterfaceRtemsInterruptLockAcquire:
+
+rtems_interrupt_lock_acquire()
+------------------------------
+
+Acquires the ISR lock.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ #define rtems_interrupt_lock_acquire( lock, lock_context )
+
+.. rubric:: PARAMETERS:
+
+``lock``
+ This parameter is the ISR lock to acquire.
+
+``lock_context``
+ This parameter is the ISR lock context. This lock context shall be used to
+ release the lock by calling :ref:`InterfaceRtemsInterruptLockRelease`.
+
+.. rubric:: DESCRIPTION:
+
+This directive acquires the ISR lock specified by ``lock`` using the lock
+context provided by ``lock_context``. Maskable interrupts will be disabled on
+the current processor.
+
+.. rubric:: NOTES:
+
+A caller-specific lock context shall be provided for each acquire/release pair,
+for example an automatic variable.
+
+Where the system was built with SMP support enabled, this directive acquires an
+SMP lock. An attempt to recursively acquire the lock may result in an infinite
+loop with maskable interrupts disabled.
+
+This directive establishes a non-preemptive critical section with system wide
+mutual exclusion on the local node in all RTEMS build configurations.
+
+.. code-block:: c
+ :linenos:
+
+ #include <rtems.h>
+
+ void critical_section( rtems_interrupt_lock *lock )
+ {
+ rtems_interrupt_lock_context lock_context;
+
+ rtems_interrupt_lock_acquire( lock, &lock_context );
+
+ // Here is the critical section. Maskable interrupts are disabled.
+ // Where the system was built with SMP support enabled, this section
+ // is protected by an SMP lock.
+
+ rtems_interrupt_lock_release( lock, &lock_context );
+ }
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/intr/if/lock-release
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: rtems_interrupt_lock_release()
+
+.. _InterfaceRtemsInterruptLockRelease:
+
+rtems_interrupt_lock_release()
+------------------------------
+
+Releases the ISR lock.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ #define rtems_interrupt_lock_release( lock, lock_context )
+
+.. rubric:: PARAMETERS:
+
+``lock``
+ This parameter is the ISR lock to release.
+
+``lock_context``
+ This parameter is the ISR lock context. This lock context shall have been
+ used to acquire the lock by calling
+ :ref:`InterfaceRtemsInterruptLockAcquire`.
+
+.. rubric:: DESCRIPTION:
+
+This directive releases the ISR lock specified by ``lock`` using the lock
+context provided by ``lock_context``. The previous interrupt level will be
+restored on the current processor.
+
+.. rubric:: NOTES:
+
+The lock context shall be the one used to acquire the lock, otherwise the
+result is unpredictable.
+
+Where the system was built with SMP support enabled, this directive releases an
+SMP lock.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+* While at least one maskable interrupt is pending, when the directive enables
+ maskable interrupts, the pending interrupts are immediately serviced. The
+ interrupt service routines may unblock higher priority tasks which may
+ preempt the calling task.
+
+.. Generated from spec:/rtems/intr/if/lock-acquire-isr
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: rtems_interrupt_lock_acquire_isr()
+
+.. _InterfaceRtemsInterruptLockAcquireIsr:
+
+rtems_interrupt_lock_acquire_isr()
+----------------------------------
+
+Acquires the ISR lock from within an ISR.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ #define rtems_interrupt_lock_acquire_isr( lock, lock_context )
+
+.. rubric:: PARAMETERS:
+
+``lock``
+ This parameter is the ISR lock to acquire within an ISR.
+
+``lock_context``
+ This parameter is the ISR lock context. This lock context shall be used to
+ release the lock by calling :ref:`InterfaceRtemsInterruptLockReleaseIsr`.
+
+.. rubric:: DESCRIPTION:
+
+This directive acquires the ISR lock specified by ``lock`` using the lock
+context provided by ``lock_context``. The interrupt level will remain
+unchanged.
+
+.. rubric:: NOTES:
+
+A caller-specific lock context shall be provided for each acquire/release pair,
+for example an automatic variable.
+
+Where the system was built with SMP support enabled, this directive acquires an
+SMP lock. An attempt to recursively acquire the lock may result in an infinite
+loop.
+
+This directive is intended for device drivers and should be called from the
+corresponding interrupt service routine.
+
+In case the corresponding interrupt service routine can be interrupted by
+higher priority interrupts and these interrupts enter the critical section
+protected by this lock, then the result is unpredictable. This directive may
+be used under specific circumstances as an optimization. In doubt, use
+:ref:`InterfaceRtemsInterruptLockAcquire` and
+:ref:`InterfaceRtemsInterruptLockRelease`.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/intr/if/lock-release-isr
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: rtems_interrupt_lock_release_isr()
+
+.. _InterfaceRtemsInterruptLockReleaseIsr:
+
+rtems_interrupt_lock_release_isr()
+----------------------------------
+
+Releases the ISR lock from within an ISR.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ #define rtems_interrupt_lock_release_isr( lock, lock_context )
+
+.. rubric:: PARAMETERS:
+
+``lock``
+ This parameter is the ISR lock to release within an ISR.
+
+``lock_context``
+ This parameter is the ISR lock context. This lock context shall have been
+ used to acquire the lock by calling
+ :ref:`InterfaceRtemsInterruptLockAcquireIsr`.
+
+.. rubric:: DESCRIPTION:
+
+This directive releases the ISR lock specified by ``lock`` using the lock
+context provided by ``lock_context``. The interrupt level will remain
+unchanged.
+
+.. rubric:: NOTES:
+
+The lock context shall be the one used to acquire the lock, otherwise the
+result is unpredictable.
+
+Where the system was built with SMP support enabled, this directive releases an
+SMP lock.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/intr/if/lock-isr-disable
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: rtems_interrupt_lock_interrupt_disable()
+
+.. _InterfaceRtemsInterruptLockInterruptDisable:
+
+rtems_interrupt_lock_interrupt_disable()
+----------------------------------------
+
+Disables maskable interrupts on the current processor.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ #define rtems_interrupt_lock_interrupt_disable( lock_context )
+
+.. rubric:: PARAMETERS:
+
+``lock_context``
+ This parameter is the ISR lock context for an acquire and release pair.
+
+.. rubric:: DESCRIPTION:
+
+This directive disables maskable interrupts on the current processor and stores
+the previous interrupt level in ``lock_context``.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/intr/if/lock-declare
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: RTEMS_INTERRUPT_LOCK_DECLARE()
+
+.. _InterfaceRTEMSINTERRUPTLOCKDECLARE:
+
+RTEMS_INTERRUPT_LOCK_DECLARE()
+------------------------------
+
+Declares an ISR lock object.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ #define RTEMS_INTERRUPT_LOCK_DECLARE( specifier, designator )
+
+.. rubric:: PARAMETERS:
+
+``specifier``
+ This parameter is the storage-class specifier for the ISR lock to declare,
+ for example ``extern`` or ``static``.
+
+``designator``
+ This parameter is the ISR lock object designator.
+
+.. rubric:: NOTES:
+
+Do not add a ";" after this macro.
+
+.. Generated from spec:/rtems/intr/if/lock-define
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: RTEMS_INTERRUPT_LOCK_DEFINE()
+
+.. _InterfaceRTEMSINTERRUPTLOCKDEFINE:
+
+RTEMS_INTERRUPT_LOCK_DEFINE()
+-----------------------------
+
+Defines an ISR lock object.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ #define RTEMS_INTERRUPT_LOCK_DEFINE( specifier, designator, name )
+
+.. rubric:: PARAMETERS:
+
+``specifier``
+ This parameter is the storage-class specifier for the ISR lock to declare,
+ for example ``extern`` or ``static``.
+
+``designator``
+ This parameter is the ISR lock object designator.
+
+``name``
+ This parameter is the ISR lock name. It shall be a string. The name is
+ only used where the system was built with profiling support enabled.
+
+.. rubric:: NOTES:
+
+Do not add a ";" after this macro.
+
+ISR locks may also be dynamically initialized by
+:ref:`InterfaceRtemsInterruptLockInitialize` or statically by
+:ref:`InterfaceRTEMSINTERRUPTLOCKINITIALIZER`.
+
+.. Generated from spec:/rtems/intr/if/lock-initializer
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: RTEMS_INTERRUPT_LOCK_INITIALIZER()
+
+.. _InterfaceRTEMSINTERRUPTLOCKINITIALIZER:
+
+RTEMS_INTERRUPT_LOCK_INITIALIZER()
+----------------------------------
+
+Statically initializes an ISR lock object.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ #define RTEMS_INTERRUPT_LOCK_INITIALIZER( name )
+
+.. rubric:: PARAMETERS:
+
+``name``
+ This parameter is the ISR lock name. It shall be a string. The name is
+ only used where the system was built with profiling support enabled.
+
+.. rubric:: NOTES:
+
+ISR locks may also be dynamically initialized by
+:ref:`InterfaceRtemsInterruptLockInitialize` or statically defined by
+:ref:`InterfaceRTEMSINTERRUPTLOCKDEFINE`.
+
+.. Generated from spec:/rtems/intr/if/lock-member
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: RTEMS_INTERRUPT_LOCK_MEMBER()
+
+.. _InterfaceRTEMSINTERRUPTLOCKMEMBER:
+
+RTEMS_INTERRUPT_LOCK_MEMBER()
+-----------------------------
+
+Defines an ISR lock member.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ #define RTEMS_INTERRUPT_LOCK_MEMBER( designator )
+
+.. rubric:: PARAMETERS:
+
+``designator``
+ This parameter is the ISR lock member designator.
+
+.. rubric:: NOTES:
+
+Do not add a ";" after this macro.
+
+.. Generated from spec:/rtems/intr/if/lock-reference
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: RTEMS_INTERRUPT_LOCK_REFERENCE()
+
+.. _InterfaceRTEMSINTERRUPTLOCKREFERENCE:
+
+RTEMS_INTERRUPT_LOCK_REFERENCE()
+--------------------------------
+
+Defines an ISR lock object reference.
+
+.. rubric:: CALLING SEQUENCE:
-.. _rtems_interrupt_is_in_progress:
+.. code-block:: c
-INTERRUPT_IS_IN_PROGRESS - Is an ISR in Progress
-------------------------------------------------
+ #define RTEMS_INTERRUPT_LOCK_REFERENCE( designator, target )
-CALLING SEQUENCE:
- .. code-block:: c
+.. rubric:: PARAMETERS:
- bool rtems_interrupt_is_in_progress( void );
+``designator``
+ This parameter is the ISR lock reference designator.
-DIRECTIVE STATUS CODES:
- NONE
+``target``
+ This parameter is the target object to reference.
-DESCRIPTION:
- This directive returns ``TRUE`` if the processor is currently servicing an
- interrupt and ``FALSE`` otherwise. A return value of ``TRUE`` indicates
- that the caller is an interrupt service routine, *NOT* a task. The
- directives available to an interrupt service routine are restricted.
+.. rubric:: NOTES:
-NOTES:
- This directive will not cause the calling task to be preempted.
+Do not add a ";" after this macro.
diff --git a/c-user/interrupt/introduction.rst b/c-user/interrupt/introduction.rst
index 272eba2..3d5c71d 100644
--- a/c-user/interrupt/introduction.rst
+++ b/c-user/interrupt/introduction.rst
@@ -1,37 +1,110 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
+.. Copyright (C) 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:/rtems/intr/if/group
+
+.. _InterruptManagerIntroduction:
+
Introduction
============
+.. The following list was generated from:
+.. spec:/rtems/intr/if/catch
+.. spec:/rtems/intr/if/disable
+.. spec:/rtems/intr/if/enable
+.. spec:/rtems/intr/if/flash
+.. spec:/rtems/intr/if/local-disable
+.. spec:/rtems/intr/if/local-enable
+.. spec:/rtems/intr/if/is-in-progress
+.. spec:/rtems/intr/if/cause
+.. spec:/rtems/intr/if/clear
+.. spec:/rtems/intr/if/lock-initialize
+.. spec:/rtems/intr/if/lock-destroy
+.. spec:/rtems/intr/if/lock-acquire
+.. spec:/rtems/intr/if/lock-release
+.. spec:/rtems/intr/if/lock-acquire-isr
+.. spec:/rtems/intr/if/lock-release-isr
+.. spec:/rtems/intr/if/lock-isr-disable
+.. spec:/rtems/intr/if/lock-declare
+.. spec:/rtems/intr/if/lock-define
+.. spec:/rtems/intr/if/lock-initializer
+.. spec:/rtems/intr/if/lock-member
+.. spec:/rtems/intr/if/lock-reference
+
Any real-time executive must provide a mechanism for quick response to
externally generated interrupts to satisfy the critical time constraints of the
-application. The interrupt manager provides this mechanism for RTEMS. This
+application. The Interrupt Manager provides this mechanism for RTEMS. This
manager permits quick interrupt response times by providing the critical
ability to alter task execution which allows a task to be preempted upon exit
-from an ISR. The interrupt manager includes the following directive:
+from an ISR. The directives provided by the Interrupt Manager are:
+
+* :ref:`InterfaceRtemsInterruptCatch` - Establishes an interrupt service
+ routine.
+
+* :ref:`InterfaceRtemsInterruptDisable` - Disables the maskable interrupts on
+ the current processor.
+
+* :ref:`InterfaceRtemsInterruptEnable` - Restores the previous interrupt level
+ on the current processor.
+
+* :ref:`InterfaceRtemsInterruptFlash` - Flashes interrupts on the current
+ processor.
+
+* :ref:`InterfaceRtemsInterruptLocalDisable` - Disables the maskable interrupts
+ on the current processor.
+
+* :ref:`InterfaceRtemsInterruptLocalEnable` - Restores the previous interrupt
+ level on the current processor.
+
+* :ref:`InterfaceRtemsInterruptIsInProgress` - Checks if an ISR is in progress
+ on the current processor.
+
+* :ref:`InterfaceRtemsInterruptCause` - Causes the interrupt.
+
+* :ref:`InterfaceRtemsInterruptClear` - Clears the interrupt.
-- :ref:`rtems_interrupt_catch`
+* :ref:`InterfaceRtemsInterruptLockInitialize` - Initializes the ISR lock.
-- :ref:`rtems_interrupt_disable`
+* :ref:`InterfaceRtemsInterruptLockDestroy` - Destroys the ISR lock.
-- :ref:`rtems_interrupt_enable`
+* :ref:`InterfaceRtemsInterruptLockAcquire` - Acquires the ISR lock.
-- :ref:`rtems_interrupt_flash`
+* :ref:`InterfaceRtemsInterruptLockRelease` - Releases the ISR lock.
-- :ref:`rtems_interrupt_local_disable`
+* :ref:`InterfaceRtemsInterruptLockAcquireIsr` - Acquires the ISR lock from
+ within an ISR.
-- :ref:`rtems_interrupt_local_enable`
+* :ref:`InterfaceRtemsInterruptLockReleaseIsr` - Releases the ISR lock from
+ within an ISR.
-- :ref:`rtems_interrupt_lock_initialize`
+* :ref:`InterfaceRtemsInterruptLockInterruptDisable` - Disables maskable
+ interrupts on the current processor.
-- :ref:`rtems_interrupt_lock_acquire`
+* :ref:`InterfaceRTEMSINTERRUPTLOCKDECLARE` - Declares an ISR lock object.
-- :ref:`rtems_interrupt_lock_release`
+* :ref:`InterfaceRTEMSINTERRUPTLOCKDEFINE` - Defines an ISR lock object.
-- :ref:`rtems_interrupt_lock_acquire_isr`
+* :ref:`InterfaceRTEMSINTERRUPTLOCKINITIALIZER` - Statically initializes an ISR
+ lock object.
-- :ref:`rtems_interrupt_lock_release_isr`
+* :ref:`InterfaceRTEMSINTERRUPTLOCKMEMBER` - Defines an ISR lock member.
-- :ref:`rtems_interrupt_is_in_progress`
+* :ref:`InterfaceRTEMSINTERRUPTLOCKREFERENCE` - Defines an ISR lock object
+ reference.
diff --git a/c-user/message/directives.rst b/c-user/message/directives.rst
index 4d9bdc7..11ff105 100644
--- a/c-user/message/directives.rst
+++ b/c-user/message/directives.rst
@@ -1,559 +1,1084 @@
.. 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
+
+.. _MessageManagerDirectives:
+
Directives
==========
-This section details the message manager's directives. A subsection is
-dedicated to each of this manager's directives and describes the calling
-sequence, related constants, usage, and status codes.
+This section details the directives of the Message Manager. A subsection is
+dedicated to each of this manager's directives and lists the calling sequence,
+parameters, description, return values, and notes of the directive.
+
+.. Generated from spec:/rtems/message/if/create
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_message_queue_create()
.. index:: create a message queue
-.. index:: rtems_message_queue_create
-
-.. _rtems_message_queue_create:
-
-MESSAGE_QUEUE_CREATE - Create a queue
--------------------------------------
-
-CALLING SEQUENCE:
- .. code-block:: c
-
- rtems_status_code rtems_message_queue_create(
- rtems_name name,
- uint32_t count,
- size_t max_message_size,
- rtems_attribute attribute_set,
- rtems_id *id
- );
-
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
-
- * - ``RTEMS_SUCCESSFUL``
- - queue created successfully
- * - ``RTEMS_INVALID_NAME``
- - invalid queue name
- * - ``RTEMS_INVALID_ADDRESS``
- - ``id`` is NULL
- * - ``RTEMS_INVALID_NUMBER``
- - invalid message count
- * - ``RTEMS_INVALID_SIZE``
- - invalid message size
- * - ``RTEMS_TOO_MANY``
- - too many queues created
- * - ``RTEMS_UNSATISFIED``
- - unable to allocate message buffers
- * - ``RTEMS_TOO_MANY``
- - too many global objects
-
-DESCRIPTION:
- This directive creates a message queue which resides on the local node with
- the user-defined name specified in name. For control and maintenance of
- the queue, RTEMS allocates and initializes a QCB. Memory is allocated from
- the RTEMS Workspace for the specified count of messages, each of
- max_message_size bytes in length. The RTEMS-assigned queue id, returned in
- id, is used to access the message queue.
-
- Specifying ``RTEMS_PRIORITY`` in attribute_set causes tasks waiting for a
- message to be serviced according to task priority. When ``RTEMS_FIFO`` is
- specified, waiting tasks are serviced in First In-First Out order.
-
-NOTES:
- This directive may cause the calling task to be preempted due to an
- obtain and release of the object allocator mutex.
-
- The following message queue attribute constants are defined by RTEMS:
-
- .. list-table::
- :class: rtems-table
-
- * - ``RTEMS_FIFO``
- - tasks wait by FIFO (default)
- * - ``RTEMS_PRIORITY``
- - tasks wait by priority
- * - ``RTEMS_LOCAL``
- - local message queue (default)
- * - ``RTEMS_GLOBAL``
- - global message queue
-
- Message queues should not be made global unless remote tasks must interact
- with the created message queue. This is to avoid the system overhead
- incurred by the creation of a global message queue. When a global message
- queue is created, the message queue's name and id must be transmitted to
- every node in the system for insertion in the local copy of the global
- object table.
-
- For GLOBAL message queues, the maximum message size is effectively limited
- to the longest message which the MPCI is capable of transmitting.
-
- The total number of global objects, including message queues, is limited by
- the ``maximum_global_objects`` field in the configuration table.
+
+.. _InterfaceRtemsMessageQueueCreate:
+
+rtems_message_queue_create()
+----------------------------
+
+Creates a message queue.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_message_queue_create(
+ rtems_name name,
+ uint32_t count,
+ size_t max_message_size,
+ rtems_attribute attribute_set,
+ rtems_id *id
+ );
+
+.. rubric:: PARAMETERS:
+
+``name``
+ This parameter is the object name of the message queue.
+
+``count``
+ This parameter is the maximum count of pending messages supported by the
+ message queue.
+
+``max_message_size``
+ This parameter is the maximum size in bytes of a message supported by the
+ message queue.
+
+``attribute_set``
+ This parameter is the attribute set of the message queue.
+
+``id``
+ This parameter is the pointer to an object identifier variable. When the
+ directive call is successful, the identifier of the created message queue
+ will be stored in this variable.
+
+.. rubric:: DESCRIPTION:
+
+This directive creates a message queue which resides on the local node. The
+message queue has the user-defined object name specified in ``name``. Memory
+is allocated from the RTEMS Workspace for the count of messages specified in
+``count``, each of ``max_message_size`` bytes in length. The assigned object
+identifier is returned in ``id``. This identifier is used to access the
+message queue with other message queue related directives.
+
+The **attribute set** specified in ``attribute_set`` is built through a
+*bitwise or* of the attribute constants described below. Not all combinations
+of attributes are allowed. Some attributes are mutually exclusive. If
+mutually exclusive attributes are combined, the behaviour is undefined.
+Attributes not mentioned below are not evaluated by this directive and have no
+effect. Default attributes can be selected by using the
+:c:macro:`RTEMS_DEFAULT_ATTRIBUTES` constant. The attribute set defines
+
+* the scope of the message queue: :c:macro:`RTEMS_LOCAL` (default) or
+ :c:macro:`RTEMS_GLOBAL` and
+
+* the task wait queue discipline used by the message queue:
+ :c:macro:`RTEMS_FIFO` (default) or :c:macro:`RTEMS_PRIORITY`.
+
+The message queue has a local or global **scope** in a multiprocessing network
+(this attribute does not refer to SMP systems). The scope is selected by the
+mutually exclusive :c:macro:`RTEMS_LOCAL` and :c:macro:`RTEMS_GLOBAL`
+attributes.
+
+* A **local scope** is the default and can be emphasized through the use of the
+ :c:macro:`RTEMS_LOCAL` attribute. A local message queue can be only used by
+ the node which created it.
+
+* A **global scope** is established if the :c:macro:`RTEMS_GLOBAL` attribute is
+ set. Setting the global attribute in a single node system has no effect.
+
+The **task wait queue discipline** is selected by the mutually exclusive
+:c:macro:`RTEMS_FIFO` and :c:macro:`RTEMS_PRIORITY` attributes. The discipline
+defines the order in which tasks wait for a message to receive on a currently
+empty message queue.
+
+* The **FIFO discipline** is the default and can be emphasized through use of
+ the :c:macro:`RTEMS_FIFO` attribute.
+
+* The **priority discipline** is selected by the :c:macro:`RTEMS_PRIORITY`
+ attribute.
+
+.. rubric:: RETURN VALUES:
+
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_NAME`
+ The ``name`` parameter was invalid.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``id`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+:c:macro:`RTEMS_INVALID_NUMBER`
+ The ``count`` parameter was invalid.
+
+:c:macro:`RTEMS_INVALID_SIZE`
+ The ``max_message_size`` parameter was invalid.
+
+:c:macro:`RTEMS_TOO_MANY`
+ There was no inactive object available to create a message queue. The
+ number of message queue available to the application is configured through
+ the :ref:`CONFIGURE_MAXIMUM_MESSAGE_QUEUES` application configuration
+ option.
+
+:c:macro:`RTEMS_TOO_MANY`
+ In multiprocessing configurations, there was no inactive global object
+ available to create a global message queue. The number of global objects
+ available to the application is configured through the
+ :ref:`CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS` application configuration
+ option.
+
+:c:macro:`RTEMS_INVALID_NUMBER`
+ The product of ``count`` and ``max_message_size`` is greater than the
+ maximum storage size.
+
+:c:macro:`RTEMS_UNSATISFIED`
+ There was not enough memory available in the RTEMS Workspace to allocate
+ the message buffers for the message queue.
+
+.. rubric:: NOTES:
+
+For message queues with a global scope, the maximum message size is effectively
+limited to the longest message which the :term:`MPCI` is capable of
+transmitting.
+
+For control and maintenance of the message queue, RTEMS allocates a :term:`QCB`
+from the local QCB free pool and initializes it.
+
+The QCB for a global message queue is allocated on the local node. Message
+queues should not be made global unless remote tasks must interact with the
+message queue. This is to avoid the system overhead incurred by the creation
+of a global message queue. When a global message queue is created, the message
+queue's name and identifier must be transmitted to every node in the system for
+insertion in the local copy of the global object table.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive may obtain and release the object allocator mutex. This may
+ cause the calling task to be preempted.
+
+* When the directive operates on a global object, the directive sends a message
+ to remote nodes. This may preempt the calling task.
+
+* The number of message queues available to the application is configured
+ through the :ref:`CONFIGURE_MAXIMUM_MESSAGE_QUEUES` application configuration
+ option.
+
+* Where the object class corresponding to the directive is configured to use
+ unlimited objects, the directive may allocate memory from the RTEMS
+ Workspace.
+
+* The number of global objects available to the application is configured
+ through the :ref:`CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS` application
+ configuration option.
+
+.. Generated from spec:/rtems/message/if/construct
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: rtems_message_queue_construct()
+
+.. _InterfaceRtemsMessageQueueConstruct:
+
+rtems_message_queue_construct()
+-------------------------------
+
+Constructs a message queue from the specified the message queue configuration.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_message_queue_construct(
+ const rtems_message_queue_config *config,
+ rtems_id *id
+ );
+
+.. rubric:: PARAMETERS:
+
+``config``
+ This parameter is the message queue configuration.
+
+``id``
+ This parameter is the pointer to an object identifier variable. When the
+ directive call is successful, the identifier of the constructed message
+ queue will be stored in this variable.
+
+.. rubric:: RETURN VALUES:
+
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``config`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+:c:macro:`RTEMS_INVALID_NAME`
+ The message queue name in the configuration was invalid.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``id`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+:c:macro:`RTEMS_INVALID_NUMBER`
+ The maximum number of pending messages in the configuration was zero.
+
+:c:macro:`RTEMS_INVALID_SIZE`
+ The maximum message size in the configuration was zero.
+
+:c:macro:`RTEMS_TOO_MANY`
+ There was no inactive message queue object available to construct a message
+ queue.
+
+:c:macro:`RTEMS_TOO_MANY`
+ In multiprocessing configurations, there was no inactive global object
+ available to construct a global message queue.
+
+:c:macro:`RTEMS_INVALID_SIZE`
+ The maximum message size in the configuration was too big and resulted in
+ integer overflows in calculations carried out to determine the size of the
+ message buffer area.
+
+:c:macro:`RTEMS_INVALID_NUMBER`
+ The maximum number of pending messages in the configuration was too big and
+ resulted in integer overflows in calculations carried out to determine the
+ size of the message buffer area.
+
+:c:macro:`RTEMS_UNSATISFIED`
+ The message queue storage area begin pointer in the configuration was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+:c:macro:`RTEMS_UNSATISFIED`
+ The message queue storage area size in the configuration was not equal to
+ the size calculated from the maximum number of pending messages and the
+ maximum message size.
+
+.. rubric:: NOTES:
+
+In contrast to message queues created by
+:ref:`InterfaceRtemsMessageQueueCreate`, the message queues constructed by this
+directive use a user-provided message buffer storage area.
+
+This directive is intended for applications which do not want to use the RTEMS
+Workspace and instead statically allocate all operating system resources. An
+application based solely on static allocation can avoid any runtime memory
+allocators. This can simplify the application architecture as well as any
+analysis that may be required.
+
+The value for :ref:`CONFIGURE_MESSAGE_BUFFER_MEMORY` should not include memory
+for message queues constructed by :ref:`InterfaceRtemsMessageQueueConstruct`.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive may obtain and release the object allocator mutex. This may
+ cause the calling task to be preempted.
+
+* When the directive operates on a global object, the directive sends a message
+ to remote nodes. This may preempt the calling task.
+
+* The number of message queues available to the application is configured
+ through the :ref:`CONFIGURE_MAXIMUM_MESSAGE_QUEUES` application configuration
+ option.
+
+* Where the object class corresponding to the directive is configured to use
+ unlimited objects, the directive may allocate memory from the RTEMS
+ Workspace.
+
+* The number of global objects available to the application is configured
+ through the :ref:`CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS` application
+ configuration option.
+
+.. Generated from spec:/rtems/message/if/ident
.. raw:: latex
- \clearpage
+ \clearpage
+
+.. index:: rtems_message_queue_ident()
+
+.. _InterfaceRtemsMessageQueueIdent:
+
+rtems_message_queue_ident()
+---------------------------
+
+Identifies a message queue by the object name.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_message_queue_ident(
+ rtems_name name,
+ uint32_t node,
+ rtems_id *id
+ );
+
+.. rubric:: PARAMETERS:
+
+``name``
+ This parameter is the object name to look up.
+
+``node``
+ This parameter is the node or node set to search for a matching object.
+
+``id``
+ This parameter is the pointer to an object identifier variable. When the
+ directive call is successful, the object identifier of an object with the
+ specified name will be stored in this variable.
+
+.. rubric:: DESCRIPTION:
+
+This directive obtains a message queue identifier associated with the message
+queue name specified in ``name``.
+
+The node to search is specified in ``node``. It shall be
+
+* a valid node number,
-.. index:: get ID of a message queue
-.. index:: rtems_message_queue_ident
+* the constant :c:macro:`RTEMS_SEARCH_ALL_NODES` to search in all nodes,
-.. _rtems_message_queue_ident:
+* the constant :c:macro:`RTEMS_SEARCH_LOCAL_NODE` to search in the local node
+ only, or
-MESSAGE_QUEUE_IDENT - Get ID of a queue
----------------------------------------
+* the constant :c:macro:`RTEMS_SEARCH_OTHER_NODES` to search in all nodes
+ except the local node.
-CALLING SEQUENCE:
- .. code-block:: c
+.. rubric:: RETURN VALUES:
- rtems_status_code rtems_message_queue_ident(
- rtems_name name,
- uint32_t node,
- rtems_id *id
- );
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``id`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
- * - ``RTEMS_SUCCESSFUL``
- - queue identified successfully
- * - ``RTEMS_INVALID_ADDRESS``
- - ``id`` is NULL
- * - ``RTEMS_INVALID_NAME``
- - queue name not found
- * - ``RTEMS_INVALID_NODE``
- - invalid node id
+:c:macro:`RTEMS_INVALID_NAME`
+ The ``name`` parameter was 0.
-DESCRIPTION:
- This directive obtains the queue id associated with the queue name
- specified in name. If the queue name is not unique, then the queue id will
- match one of the queues with that name. However, this queue id is not
- guaranteed to correspond to the desired queue. The queue id is used with
- other message related directives to access the message queue.
+:c:macro:`RTEMS_INVALID_NAME`
+ There was no object with the specified name on the specified nodes.
-NOTES:
- This directive will not cause the running task to be preempted.
+:c:macro:`RTEMS_INVALID_NODE`
+ In multiprocessing configurations, the specified node was invalid.
- If node is ``RTEMS_SEARCH_ALL_NODES``, all nodes are searched with the
- local node being searched first. All other nodes are searched with the
- lowest numbered node searched first.
+.. rubric:: NOTES:
- If node is a valid node number which does not represent the local node,
- then only the message queues exported by the designated node are searched.
+If the message queue name is not unique, then the message queue identifier will
+match the first message queue with that name in the search order. However, this
+message queue identifier is not guaranteed to correspond to the desired message
+queue.
- This directive does not generate activity on remote nodes. It accesses
- only the local copy of the global object table.
+The objects are searched from lowest to the highest index. If ``node`` is
+:c:macro:`RTEMS_SEARCH_ALL_NODES`, all nodes are searched with the local node
+being searched first. All other nodes are searched from lowest to the highest
+node number.
+
+If node is a valid node number which does not represent the local node, then
+only the message queues exported by the designated node are searched.
+
+This directive does not generate activity on remote nodes. It accesses only
+the local copy of the global object table.
+
+The message queue identifier is used with other message related directives to
+access the message queue.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/message/if/delete
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_message_queue_delete()
.. index:: delete a message queue
-.. index:: rtems_message_queue_delete
-.. _rtems_message_queue_delete:
+.. _InterfaceRtemsMessageQueueDelete:
+
+rtems_message_queue_delete()
+----------------------------
+
+Deletes the message queue.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_message_queue_delete( rtems_id id );
+
+.. rubric:: PARAMETERS:
+
+``id``
+ This parameter is the message queue identifier.
+
+.. rubric:: DESCRIPTION:
+
+This directive deletes the message queue specified by ``id``. As a result of
+this directive, all tasks blocked waiting to receive a message from this queue
+will be readied and returned a status code which indicates that the message
+queue was deleted.
+
+.. rubric:: RETURN VALUES:
-MESSAGE_QUEUE_DELETE - Delete a queue
--------------------------------------
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
-CALLING SEQUENCE:
- .. code-block:: c
+:c:macro:`RTEMS_INVALID_ID`
+ There was no message queue associated with the identifier specified by
+ ``id``.
- rtems_status_code rtems_message_queue_delete(
- rtems_id id
- );
+:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT`
+ The message queue resided on a remote node.
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+.. rubric:: NOTES:
- * - ``RTEMS_SUCCESSFUL``
- - queue deleted successfully
- * - ``RTEMS_INVALID_ID``
- - invalid queue id
- * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT``
- - cannot delete remote queue
+When the message queue is deleted, any messages in the queue are returned to
+the free message buffer pool. Any information stored in those messages is
+lost. The message buffers allocated for the message queue are reclaimed.
-DESCRIPTION:
- This directive deletes the message queue specified by ``id``. As a result
- of this directive, all tasks blocked waiting to receive a message from this
- queue will be readied and returned a status code which indicates that the
- message queue was deleted. If no tasks are waiting, but the queue contains
- messages, then RTEMS returns these message buffers back to the system
- message buffer pool. The QCB for this queue as well as the memory for the
- message buffers is reclaimed by RTEMS.
+The :term:`QCB` for the deleted message queue is reclaimed by RTEMS.
-NOTES:
- This directive may cause the calling task to be preempted due to an
- obtain and release of the object allocator mutex.
+When a global message queue is deleted, the message queue identifier must be
+transmitted to every node in the system for deletion from the local copy of the
+global object table.
- The calling task will be preempted if its preemption mode is enabled and
- one or more local tasks with a higher priority than the calling task are
- waiting on the deleted queue. The calling task will NOT be preempted if
- the tasks that are waiting are remote tasks.
+The message queue must reside on the local node, even if the message queue was
+created with the :c:macro:`RTEMS_GLOBAL` attribute.
- The calling task does not have to be the task that created the queue,
- although the task and queue must reside on the same node.
+Proxies, used to represent remote tasks, are reclaimed when the message queue
+is deleted.
- When the queue is deleted, any messages in the queue are returned to the
- free message buffer pool. Any information stored in those messages is
- lost.
+.. rubric:: CONSTRAINTS:
- When a global message queue is deleted, the message queue id must be
- transmitted to every node in the system for deletion from the local copy of
- the global object table.
+The following constraints apply to this directive:
- Proxies, used to represent remote tasks, are reclaimed when the message
- queue is deleted.
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive may obtain and release the object allocator mutex. This may
+ cause the calling task to be preempted.
+
+* When the directive operates on a global object, the directive sends a message
+ to remote nodes. This may preempt the calling task.
+
+* The calling task does not have to be the task that created the object. Any
+ local task that knows the object identifier can delete the object.
+
+* Where the object class corresponding to the directive is configured to use
+ unlimited objects, the directive may free memory to the RTEMS Workspace.
+
+.. Generated from spec:/rtems/message/if/send
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_message_queue_send()
.. index:: send message to a queue
-.. index:: rtems_message_queue_send
-
-.. _rtems_message_queue_send:
-
-MESSAGE_QUEUE_SEND - Put message at rear of a queue
----------------------------------------------------
-
-CALLING SEQUENCE:
- .. code-block:: c
-
- rtems_status_code rtems_message_queue_send(
- rtems_id id,
- const void *buffer,
- size_t size
- );
-
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
-
- * - ``RTEMS_SUCCESSFUL``
- - message sent successfully
- * - ``RTEMS_INVALID_ID``
- - invalid queue id
- * - ``RTEMS_INVALID_SIZE``
- - invalid message size
- * - ``RTEMS_INVALID_ADDRESS``
- - ``buffer`` is NULL
- * - ``RTEMS_UNSATISFIED``
- - out of message buffers
- * - ``RTEMS_TOO_MANY``
- - queue's limit has been reached
-
-DESCRIPTION:
- This directive sends the message buffer of size bytes in length to the
- queue specified by id. If a task is waiting at the queue, then the message
- is copied to the waiting task's buffer and the task is unblocked. If no
- tasks are waiting at the queue, then the message is copied to a message
- buffer which is obtained from this message queue's message buffer pool.
- The message buffer is then placed at the rear of the queue.
-
-NOTES:
- The calling task will be preempted if it has preemption enabled and a
- higher priority task is unblocked as the result of this directive.
-
- Sending a message to a global message queue which does not reside on the
- local node will generate a request to the remote node to post the message
- on the specified message queue.
-
- If the task to be unblocked resides on a different node from the message
- queue, then the message is forwarded to the appropriate node, the waiting
- task is unblocked, and the proxy used to represent the task is reclaimed.
+
+.. _InterfaceRtemsMessageQueueSend:
+
+rtems_message_queue_send()
+--------------------------
+
+Puts the message at the rear of the queue.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_message_queue_send(
+ rtems_id id,
+ const void *buffer,
+ size_t size
+ );
+
+.. rubric:: PARAMETERS:
+
+``id``
+ This parameter is the queue identifier.
+
+``buffer``
+ This parameter is the begin address of the message buffer to send.
+
+``size``
+ This parameter is the size in bytes of the message buffer to send.
+
+.. rubric:: DESCRIPTION:
+
+This directive sends the message ``buffer`` of ``size`` bytes in length to the
+queue specified by ``id``. If a task is waiting at the queue, then the message
+is copied to the waiting task's buffer and the task is unblocked. If no tasks
+are waiting at the queue, then the message is copied to a message buffer which
+is obtained from this message queue's message buffer pool. The message buffer
+is then placed at the rear of the queue.
+
+.. rubric:: RETURN VALUES:
+
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_ID`
+ There was no queue associated with the identifier specified by ``id``.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``buffer`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+:c:macro:`RTEMS_INVALID_SIZE`
+ The size of the message exceeded the maximum message size of the queue as
+ defined by :ref:`InterfaceRtemsMessageQueueCreate` or
+ :ref:`InterfaceRtemsMessageQueueConstruct`.
+
+:c:macro:`RTEMS_TOO_MANY`
+ The maximum number of pending messages supported by the queue as defined by
+ :ref:`InterfaceRtemsMessageQueueCreate` or
+ :ref:`InterfaceRtemsMessageQueueConstruct` has been reached.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within task context.
+
+* The directive may be called from within interrupt context.
+
+* The directive may unblock a task. This may cause the calling task to be
+ preempted.
+
+* When the directive operates on a remote object, the directive sends a message
+ to the remote node and waits for a reply. This will preempt the calling
+ task.
+
+.. Generated from spec:/rtems/message/if/urgent
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_message_queue_urgent()
.. index:: put message at front of queue
-.. index:: rtems_message_queue_urgent
-
-.. _rtems_message_queue_urgent:
-
-MESSAGE_QUEUE_URGENT - Put message at front of a queue
-------------------------------------------------------
-
-**CALLING SEQUENCE:**
- .. code-block:: c
-
- rtems_status_code rtems_message_queue_urgent(
- rtems_id id,
- const void *buffer,
- size_t size
- );
-
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
-
- * - ``RTEMS_SUCCESSFUL``
- - message sent successfully
- * - ``RTEMS_INVALID_ID``
- - invalid queue id
- * - ``RTEMS_INVALID_SIZE``
- - invalid message size
- * - ``RTEMS_INVALID_ADDRESS``
- - ``buffer`` is NULL
- * - ``RTEMS_UNSATISFIED``
- - out of message buffers
- * - ``RTEMS_TOO_MANY``
- - queue's limit has been reached
-
-DESCRIPTION:
- This directive sends the message buffer of size bytes in length to the
- queue specified by id. If a task is waiting on the queue, then the message
- is copied to the task's buffer and the task is unblocked. If no tasks are
- waiting on the queue, then the message is copied to a message buffer which
- is obtained from this message queue's message buffer pool. The message
- buffer is then placed at the front of the queue.
-
-NOTES:
- The calling task will be preempted if it has preemption enabled and a
- higher priority task is unblocked as the result of this directive.
-
- Sending a message to a global message queue which does not reside on the
- local node will generate a request telling the remote node to post the
- message on the specified message queue.
-
- If the task to be unblocked resides on a different node from the message
- queue, then the message is forwarded to the appropriate node, the waiting
- task is unblocked, and the proxy used to represent the task is reclaimed.
+
+.. _InterfaceRtemsMessageQueueUrgent:
+
+rtems_message_queue_urgent()
+----------------------------
+
+Puts the message at the front of the queue.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_message_queue_urgent(
+ rtems_id id,
+ const void *buffer,
+ size_t size
+ );
+
+.. rubric:: PARAMETERS:
+
+``id``
+ This parameter is the queue identifier.
+
+``buffer``
+ This parameter is the begin address of the message buffer to send urgently.
+
+``size``
+ This parameter is the size in bytes of the message buffer to send urgently.
+
+.. rubric:: DESCRIPTION:
+
+This directive sends the message ``buffer`` of ``size`` bytes in length to the
+queue specified by ``id``. If a task is waiting at the queue, then the message
+is copied to the waiting task's buffer and the task is unblocked. If no tasks
+are waiting at the queue, then the message is copied to a message buffer which
+is obtained from this message queue's message buffer pool. The message buffer
+is then placed at the front of the queue.
+
+.. rubric:: RETURN VALUES:
+
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_ID`
+ There was no queue associated with the identifier specified by ``id``.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``buffer`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+:c:macro:`RTEMS_INVALID_SIZE`
+ The size of the message exceeded the maximum message size of the queue as
+ defined by :ref:`InterfaceRtemsMessageQueueCreate` or
+ :ref:`InterfaceRtemsMessageQueueConstruct`.
+
+:c:macro:`RTEMS_TOO_MANY`
+ The maximum number of pending messages supported by the queue as defined by
+ :ref:`InterfaceRtemsMessageQueueCreate` or
+ :ref:`InterfaceRtemsMessageQueueConstruct` has been reached.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within task context.
+
+* The directive may be called from within interrupt context.
+
+* The directive may unblock a task. This may cause the calling task to be
+ preempted.
+
+* When the directive operates on a remote object, the directive sends a message
+ to the remote node and waits for a reply. This will preempt the calling
+ task.
+
+.. Generated from spec:/rtems/message/if/broadcast
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_message_queue_broadcast()
.. index:: broadcast message to a queue
-.. index:: rtems_message_queue_broadcast
-
-.. _rtems_message_queue_broadcast:
-
-MESSAGE_QUEUE_BROADCAST - Broadcast N messages to a queue
----------------------------------------------------------
-
-CALLING SEQUENCE:
- .. code-block:: c
-
- rtems_status_code rtems_message_queue_broadcast(
- rtems_id id,
- const void *buffer,
- size_t size,
- uint32_t *count
- );
-
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
-
- * - ``RTEMS_SUCCESSFUL``
- - message broadcasted successfully
- * - ``RTEMS_INVALID_ID``
- - invalid queue id
- * - ``RTEMS_INVALID_ADDRESS``
- - ``buffer`` is NULL
- * - ``RTEMS_INVALID_ADDRESS``
- - ``count`` is NULL
- * - ``RTEMS_INVALID_SIZE``
- - invalid message size
-
-DESCRIPTION:
- This directive causes all tasks that are waiting at the queue specified by
- id to be unblocked and sent the message contained in buffer. Before a task
- is unblocked, the message buffer of size byes in length is copied to that
- task's message buffer. The number of tasks that were unblocked is returned
- in count.
-
-NOTES:
- The calling task will be preempted if it has preemption enabled and a
- higher priority task is unblocked as the result of this directive.
-
- The execution time of this directive is directly related to the number of
- tasks waiting on the message queue, although it is more efficient than the
- equivalent number of invocations of ``rtems_message_queue_send``.
-
- Broadcasting a message to a global message queue which does not reside on
- the local node will generate a request telling the remote node to broadcast
- the message to the specified message queue.
-
- When a task is unblocked which resides on a different node from the message
- queue, a copy of the message is forwarded to the appropriate node, the
- waiting task is unblocked, and the proxy used to represent the task is
- reclaimed.
+
+.. _InterfaceRtemsMessageQueueBroadcast:
+
+rtems_message_queue_broadcast()
+-------------------------------
+
+Broadcasts the messages to the tasks waiting at the queue.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_message_queue_broadcast(
+ rtems_id id,
+ const void *buffer,
+ size_t size,
+ uint32_t *count
+ );
+
+.. rubric:: PARAMETERS:
+
+``id``
+ This parameter is the queue identifier.
+
+``buffer``
+ This parameter is the begin address of the message buffer to broadcast.
+
+``size``
+ This parameter is the size in bytes of the message buffer to broadcast.
+
+``count``
+ This parameter is the pointer to an `uint32_t
+ <https://en.cppreference.com/w/c/types/integer>`_ variable. When the
+ directive call is successful, the number of unblocked tasks will be stored
+ in this variable.
+
+.. rubric:: DESCRIPTION:
+
+This directive causes all tasks that are waiting at the queue specified by
+``id`` to be unblocked and sent the message contained in ``buffer``. Before a
+task is unblocked, the message ``buffer`` of ``size`` byes in length is copied
+to that task's message buffer. The number of tasks that were unblocked is
+returned in ``count``.
+
+.. rubric:: RETURN VALUES:
+
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_ID`
+ There was no queue associated with the identifier specified by ``id``.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``buffer`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``count`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+:c:macro:`RTEMS_INVALID_SIZE`
+ The size of the message exceeded the maximum message size of the queue as
+ defined by :ref:`InterfaceRtemsMessageQueueCreate` or
+ :ref:`InterfaceRtemsMessageQueueConstruct`.
+
+.. rubric:: NOTES:
+
+The execution time of this directive is directly related to the number of tasks
+waiting on the message queue, although it is more efficient than the equivalent
+number of invocations of :ref:`InterfaceRtemsMessageQueueSend`.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within task context.
+
+* The directive may be called from within interrupt context.
+
+* The directive may unblock a task. This may cause the calling task to be
+ preempted.
+
+* When the directive operates on a remote object, the directive sends a message
+ to the remote node and waits for a reply. This will preempt the calling
+ task.
+
+.. Generated from spec:/rtems/message/if/receive
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_message_queue_receive()
.. index:: receive message from a queue
-.. index:: rtems_message_queue_receive
-
-.. _rtems_message_queue_receive:
-
-MESSAGE_QUEUE_RECEIVE - Receive message from a queue
-----------------------------------------------------
-
-CALLING SEQUENCE:
- .. code-block:: c
-
- rtems_status_code rtems_message_queue_receive(
- rtems_id id,
- void *buffer,
- size_t *size,
- rtems_option option_set,
- rtems_interval timeout
- );
-
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
-
- * - ``RTEMS_SUCCESSFUL``
- - message received successfully
- * - ``RTEMS_INVALID_ID``
- - invalid queue id
- * - ``RTEMS_INVALID_ADDRESS``
- - ``buffer`` is NULL
- * - ``RTEMS_INVALID_ADDRESS``
- - ``size`` is NULL
- * - ``RTEMS_UNSATISFIED``
- - queue is empty
- * - ``RTEMS_TIMEOUT``
- - timed out waiting for message
- * - ``RTEMS_OBJECT_WAS_DELETED``
- - queue deleted while waiting
-
-DESCRIPTION:
- This directive receives a message from the message queue specified in id.
- The ``RTEMS_WAIT`` and ``RTEMS_NO_WAIT`` options of the options parameter
- allow the calling task to specify whether to wait for a message to become
- available or return immediately. For either option, if there is at least
- one message in the queue, then it is copied to buffer, size is set to
- return the length of the message in bytes, and this directive returns
- immediately with a successful return code. The buffer has to be big enough
- to receive a message of the maximum length with respect to this message
- queue.
- If the calling task chooses to return immediately and the queue is empty,
- then a status code indicating this condition is returned. If the calling
- task chooses to wait at the message queue and the queue is empty, then the
- calling task is placed on the message wait queue and blocked. If the queue
- was created with the ``RTEMS_PRIORITY`` option specified, then the calling
- task is inserted into the wait queue according to its priority. But, if
- the queue was created with the ``RTEMS_FIFO`` option specified, then the
- calling task is placed at the rear of the wait queue.
-
- A task choosing to wait at the queue can optionally specify a timeout value
- in the timeout parameter. The timeout parameter specifies the maximum
- interval to wait before the calling task desires to be unblocked. If it is
- set to ``RTEMS_NO_TIMEOUT``, then the calling task will wait forever.
-
-NOTES:
- The following message receive option constants are defined by RTEMS:
-
- .. list-table::
- :class: rtems-table
-
- * - ``RTEMS_WAIT``
- - task will wait for a message (default)
- * - ``RTEMS_NO_WAIT``
- - task should not wait
-
- Receiving a message from a global message queue which does not reside on
- the local node will generate a request to the remote node to obtain a
- message from the specified message queue. If no message is available and
- ``RTEMS_WAIT`` was specified, then the task must be blocked until a message
- is posted. A proxy is allocated on the remote node to represent the task
- until the message is posted.
-
- A clock tick is required to support the timeout functionality of this
- directive.
+.. _InterfaceRtemsMessageQueueReceive:
+
+rtems_message_queue_receive()
+-----------------------------
+
+Receives a message from the queue.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_message_queue_receive(
+ rtems_id id,
+ void *buffer,
+ size_t *size,
+ rtems_option option_set,
+ rtems_interval timeout
+ );
+
+.. rubric:: PARAMETERS:
+
+``id``
+ This parameter is the queue identifier.
+
+``buffer``
+ This parameter is the begin address of the buffer to receive the message.
+ The buffer shall be large enough to receive a message of the maximum length
+ of the queue as defined by :ref:`InterfaceRtemsMessageQueueCreate` or
+ :ref:`InterfaceRtemsMessageQueueConstruct`. The ``size`` parameter cannot
+ be used to specify the size of the buffer.
+
+``size``
+ This parameter is the pointer to a `size_t
+ <https://en.cppreference.com/w/c/types/size_t>`_ variable. When the
+ directive call is successful, the size in bytes of the received messages
+ will be stored in this variable. This parameter cannot be used to specify
+ the size of the buffer.
+
+``option_set``
+ This parameter is the option set.
+
+``timeout``
+ This parameter is the timeout in :term:`clock ticks <clock tick>` if the
+ :c:macro:`RTEMS_WAIT` option is set. Use :c:macro:`RTEMS_NO_TIMEOUT` to
+ wait potentially forever.
+
+.. rubric:: DESCRIPTION:
+
+This directive receives a message from the queue specified by ``id``.
+
+The **option set** specified in ``option_set`` is built through a *bitwise or*
+of the option constants described below. Not all combinations of options are
+allowed. Some options are mutually exclusive. If mutually exclusive options
+are combined, the behaviour is undefined. Options not mentioned below are not
+evaluated by this directive and have no effect. Default options can be selected
+by using the :c:macro:`RTEMS_DEFAULT_OPTIONS` constant.
+
+The calling task can **wait** or **try to receive** a message from the queue
+according to the mutually exclusive :c:macro:`RTEMS_WAIT` and
+:c:macro:`RTEMS_NO_WAIT` options.
+
+* **Waiting to receive** a message from the queue is the default and can be
+ emphasized through the use of the :c:macro:`RTEMS_WAIT` option. The
+ ``timeout`` parameter defines how long the calling task is willing to wait.
+ Use :c:macro:`RTEMS_NO_TIMEOUT` to wait potentially forever, otherwise set a
+ timeout interval in clock ticks.
+
+* **Trying to receive** a message from the queue is selected by the
+ :c:macro:`RTEMS_NO_WAIT` option. If this option is defined, then the
+ ``timeout`` parameter is ignored. When a message from the queue cannot be
+ immediately received, then the :c:macro:`RTEMS_UNSATISFIED` status is
+ returned.
+
+With either :c:macro:`RTEMS_WAIT` or :c:macro:`RTEMS_NO_WAIT` if there is at
+least one message in the queue, then it is copied to the buffer, the size is
+set to return the length of the message in bytes, and this directive returns
+immediately with the :c:macro:`RTEMS_SUCCESSFUL` status code. The buffer has
+to be big enough to receive a message of the maximum length with respect to
+this message queue.
+
+If the calling task chooses to return immediately and the queue is empty, then
+the directive returns immediately with the :c:macro:`RTEMS_UNSATISFIED` status
+code. If the calling task chooses to wait at the message queue and the queue
+is empty, then the calling task is placed on the message wait queue and
+blocked. If the queue was created with the :c:macro:`RTEMS_PRIORITY` option
+specified, then the calling task is inserted into the wait queue according to
+its priority. But, if the queue was created with the :c:macro:`RTEMS_FIFO`
+option specified, then the calling task is placed at the rear of the wait
+queue.
+
+.. rubric:: RETURN VALUES:
+
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_ID`
+ There was no queue associated with the identifier specified by ``id``.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``buffer`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``size`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+:c:macro:`RTEMS_UNSATISFIED`
+ The queue was empty.
+
+:c:macro:`RTEMS_UNSATISFIED`
+ The queue was flushed while the calling task was waiting to receive a
+ message.
+
+:c:macro:`RTEMS_TIMEOUT`
+ The timeout happened while the calling task was waiting to receive a
+ message
+
+:c:macro:`RTEMS_OBJECT_WAS_DELETED`
+ The queue was deleted while the calling task was waiting to receive a
+ message.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* When a local queue is accessed and the :c:macro:`RTEMS_NO_WAIT` option is
+ set, the directive may be called from within interrupt context.
+
+* The directive may be called from within task context.
+
+* When the request cannot be immediately satisfied and the
+ :c:macro:`RTEMS_WAIT` option is set, the calling task blocks at some point
+ during the directive call.
+
+* The timeout functionality of the directive requires a :term:`clock tick`.
+
+* When the directive operates on a remote object, the directive sends a message
+ to the remote node and waits for a reply. This will preempt the calling
+ task.
+
+.. Generated from spec:/rtems/message/if/get-number-pending
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_message_queue_get_number_pending()
.. index:: get number of pending messages
-.. index:: rtems_message_queue_get_number_pending
-.. _rtems_message_queue_get_number_pending:
+.. _InterfaceRtemsMessageQueueGetNumberPending:
+
+rtems_message_queue_get_number_pending()
+----------------------------------------
+
+Gets the number of messages pending on the queue.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_message_queue_get_number_pending(
+ rtems_id id,
+ uint32_t *count
+ );
-MESSAGE_QUEUE_GET_NUMBER_PENDING - Get number of messages pending on a queue
-----------------------------------------------------------------------------
+.. rubric:: PARAMETERS:
-CALLING SEQUENCE:
- .. code-block:: c
+``id``
+ This parameter is the queue identifier.
- rtems_status_code rtems_message_queue_get_number_pending(
- rtems_id id,
- uint32_t *count
- );
+``count``
+ This parameter is the pointer to an `uint32_t
+ <https://en.cppreference.com/w/c/types/integer>`_ variable. When the
+ directive call is successful, the number of pending messages will be stored
+ in this variable.
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+.. rubric:: DESCRIPTION:
- * - ``RTEMS_SUCCESSFUL``
- - number of messages pending returned successfully
- * - ``RTEMS_INVALID_ADDRESS``
- - ``count`` is NULL
- * - ``RTEMS_INVALID_ID``
- - invalid queue id
+This directive returns the number of messages pending on the queue specified by
+``id`` in ``count``. If no messages are present on the queue, count is set to
+zero.
-DESCRIPTION:
- This directive returns the number of messages pending on this message queue
- in count. If no messages are present on the queue, count is set to zero.
+.. rubric:: RETURN VALUES:
-NOTES:
- Getting the number of pending messages on a global message queue which does
- not reside on the local node will generate a request to the remote node to
- actually obtain the pending message count for the specified message queue.
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_ID`
+ There was no queue associated with the identifier specified by ``id``.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``count`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within task context.
+
+* The directive may be called from within interrupt context.
+
+* When the directive operates on a remote object, the directive sends a message
+ to the remote node and waits for a reply. This will preempt the calling
+ task.
+
+.. Generated from spec:/rtems/message/if/flush
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_message_queue_flush()
.. index:: flush messages on a queue
-.. index:: rtems_message_queue_flush
-.. _rtems_message_queue_flush:
+.. _InterfaceRtemsMessageQueueFlush:
+
+rtems_message_queue_flush()
+---------------------------
+
+Flushes all messages on the queue.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_message_queue_flush( rtems_id id, uint32_t *count );
+
+.. rubric:: PARAMETERS:
+
+``id``
+ This parameter is the queue identifier.
+
+``count``
+ This parameter is the pointer to an `uint32_t
+ <https://en.cppreference.com/w/c/types/integer>`_ variable. When the
+ directive call is successful, the number of unblocked tasks will be stored
+ in this variable.
+
+.. rubric:: DESCRIPTION:
+
+This directive removes all pending messages from the queue specified by ``id``.
+The number of messages removed is returned in ``count``. If no messages are
+present on the queue, count is set to zero.
+
+.. rubric:: RETURN VALUES:
+
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_ID`
+ There was no queue associated with the identifier specified by ``id``.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``count`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within task context.
+
+* The directive may be called from within interrupt context.
+
+* When the directive operates on a remote object, the directive sends a message
+ to the remote node and waits for a reply. This will preempt the calling
+ task.
+
+.. Generated from spec:/rtems/message/if/buffer
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: RTEMS_MESSAGE_QUEUE_BUFFER()
+
+.. _InterfaceRTEMSMESSAGEQUEUEBUFFER:
+
+RTEMS_MESSAGE_QUEUE_BUFFER()
+----------------------------
+
+Defines a structure which can be used as a message queue buffer for messages of
+the specified maximum size.
-MESSAGE_QUEUE_FLUSH - Flush all messages on a queue
----------------------------------------------------
+.. rubric:: CALLING SEQUENCE:
-CALLING SEQUENCE:
- .. code-block:: c
+.. code-block:: c
- rtems_status_code rtems_message_queue_flush(
- rtems_id id,
- uint32_t *count
- );
+ #define RTEMS_MESSAGE_QUEUE_BUFFER( maximum_message_size )
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+.. rubric:: PARAMETERS:
- * - ``RTEMS_SUCCESSFUL``
- - message queue flushed successfully
- * - ``RTEMS_INVALID_ADDRESS``
- - ``count`` is NULL
- * - ``RTEMS_INVALID_ID``
- - invalid queue id
+``maximum_message_size``
+ This parameter is the maximum message size in bytes.
-DESCRIPTION:
- This directive removes all pending messages from the specified queue id.
- The number of messages removed is returned in count. If no messages are
- present on the queue, count is set to zero.
+.. rubric:: NOTES:
-NOTES:
- Flushing all messages on a global message queue which does not reside on
- the local node will generate a request to the remote node to actually flush
- the specified message queue.
+Use this macro to define the message buffer storage area for
+:ref:`InterfaceRtemsMessageQueueConstruct`.
diff --git a/c-user/message/introduction.rst b/c-user/message/introduction.rst
index b10e06c..89fbfca 100644
--- a/c-user/message/introduction.rst
+++ b/c-user/message/introduction.rst
@@ -1,28 +1,71 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
+.. Copyright (C) 2020, 2021 embedded brains GmbH (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:/rtems/message/if/group
+
+.. _MessageManagerIntroduction:
+
Introduction
============
-The message manager provides communication and synchronization capabilities
-using RTEMS message queues. The directives provided by the message manager
-are:
+.. The following list was generated from:
+.. spec:/rtems/message/if/create
+.. spec:/rtems/message/if/construct
+.. spec:/rtems/message/if/ident
+.. spec:/rtems/message/if/delete
+.. spec:/rtems/message/if/send
+.. spec:/rtems/message/if/urgent
+.. spec:/rtems/message/if/broadcast
+.. spec:/rtems/message/if/receive
+.. spec:/rtems/message/if/get-number-pending
+.. spec:/rtems/message/if/flush
+.. spec:/rtems/message/if/buffer
+
+The Message Manager provides communication and synchronization capabilities
+using RTEMS message queues. The directives provided by the Message Manager are:
+
+* :ref:`InterfaceRtemsMessageQueueCreate` - Creates a message queue.
+
+* :ref:`InterfaceRtemsMessageQueueConstruct` - Constructs a message queue from
+ the specified the message queue configuration.
-- :ref:`rtems_message_queue_create`
+* :ref:`InterfaceRtemsMessageQueueIdent` - Identifies a message queue by the
+ object name.
-- :ref:`rtems_message_queue_ident`
+* :ref:`InterfaceRtemsMessageQueueDelete` - Deletes the message queue.
-- :ref:`rtems_message_queue_delete`
+* :ref:`InterfaceRtemsMessageQueueSend` - Puts the message at the rear of the
+ queue.
-- :ref:`rtems_message_queue_send`
+* :ref:`InterfaceRtemsMessageQueueUrgent` - Puts the message at the front of
+ the queue.
-- :ref:`rtems_message_queue_urgent`
+* :ref:`InterfaceRtemsMessageQueueBroadcast` - Broadcasts the messages to the
+ tasks waiting at the queue.
-- :ref:`rtems_message_queue_broadcast`
+* :ref:`InterfaceRtemsMessageQueueReceive` - Receives a message from the queue.
-- :ref:`rtems_message_queue_receive`
+* :ref:`InterfaceRtemsMessageQueueGetNumberPending` - Gets the number of
+ messages pending on the queue.
-- :ref:`rtems_message_queue_get_number_pending`
+* :ref:`InterfaceRtemsMessageQueueFlush` - Flushes all messages on the queue.
-- :ref:`rtems_message_queue_flush`
+* :ref:`InterfaceRTEMSMESSAGEQUEUEBUFFER` - Defines a structure which can be
+ used as a message queue buffer for messages of the specified maximum size.
diff --git a/c-user/multiprocessing.rst b/c-user/multiprocessing/background.rst
index f207106..2aaae6e 100644
--- a/c-user/multiprocessing.rst
+++ b/c-user/multiprocessing/background.rst
@@ -2,44 +2,6 @@
.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
-.. index:: multiprocessing
-
-Multiprocessing Manager
-***********************
-
-Introduction
-============
-
-In multiprocessor real-time systems, new requirements, such as sharing data and
-global resources between processors, are introduced. This requires an
-efficient and reliable communications vehicle which allows all processors to
-communicate with each other as necessary. In addition, the ramifications of
-multiple processors affect each and every characteristic of a real-time system,
-almost always making them more complicated.
-
-RTEMS addresses these issues by providing simple and flexible real-time
-multiprocessing capabilities. The executive easily lends itself to both
-tightly-coupled and loosely-coupled configurations of the target system
-hardware. In addition, RTEMS supports systems composed of both homogeneous and
-heterogeneous mixtures of processors and target boards.
-
-A major design goal of the RTEMS executive was to transcend the physical
-boundaries of the target hardware configuration. This goal is achieved by
-presenting the application software with a logical view of the target system
-where the boundaries between processor nodes are transparent. As a result, the
-application developer may designate objects such as tasks, queues, events,
-signals, semaphores, and memory blocks as global objects. These global objects
-may then be accessed by any task regardless of the physical location of the
-object and the accessing task. RTEMS automatically determines that the object
-being accessed resides on another processor and performs the actions required
-to access the desired object. Simply stated, RTEMS allows the entire system,
-both hardware and software, to be viewed logically as a single system.
-
-The directives provided by the Manager are:
-
-- rtems_multiprocessing_announce_ - A multiprocessing communications packet has
- arrived
-
.. index:: multiprocessing topologies
Background
@@ -455,54 +417,3 @@ of the following:
- RTEMS makes no assumptions regarding the application data component of the
packet.
-
-Operations
-==========
-
-Announcing a Packet
--------------------
-
-The ``rtems_multiprocessing_announce`` directive is called by the MPCI layer to
-inform RTEMS that a packet has arrived from another node. This directive can
-be called from an interrupt service routine or from within a polling routine.
-
-Directives
-==========
-
-This section details the additional directives required to support RTEMS in a
-multiprocessor configuration. A subsection is dedicated to each of this
-manager's directives and describes the calling sequence, related constants,
-usage, and status codes.
-
-.. raw:: latex
-
- \clearpage
-
-.. index:: announce arrival of package
-.. index:: rtems_multiprocessing_announce
-
-.. _rtems_multiprocessing_announce:
-
-MULTIPROCESSING_ANNOUNCE - Announce the arrival of a packet
------------------------------------------------------------
-
-CALLING SEQUENCE:
- .. code-block:: c
-
- void rtems_multiprocessing_announce( void );
-
-DIRECTIVE STATUS CODES:
- NONE
-
-DESCRIPTION:
- This directive informs RTEMS that a multiprocessing communications packet
- has arrived from another node. This directive is called by the
- user-provided MPCI, and is only used in multiprocessor configurations.
-
-NOTES:
- This directive is typically called from an ISR.
-
- This directive will almost certainly cause the calling task to be
- preempted.
-
- This directive does not generate activity on remote nodes.
diff --git a/c-user/multiprocessing/directives.rst b/c-user/multiprocessing/directives.rst
new file mode 100644
index 0000000..fc10640
--- /dev/null
+++ b/c-user/multiprocessing/directives.rst
@@ -0,0 +1,75 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2021 embedded brains GmbH (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
+
+.. _MultiprocessingManagerDirectives:
+
+Directives
+==========
+
+This section details the directives of the Multiprocessing Manager. A
+subsection is dedicated to each of this manager's directives and lists the
+calling sequence, parameters, description, return values, and notes of the
+directive.
+
+.. Generated from spec:/rtems/mp/if/announce
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: rtems_multiprocessing_announce()
+
+.. _InterfaceRtemsMultiprocessingAnnounce:
+
+rtems_multiprocessing_announce()
+--------------------------------
+
+Announces the arrival of a packet.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ void rtems_multiprocessing_announce( void );
+
+.. rubric:: DESCRIPTION:
+
+This directive informs RTEMS that a multiprocessing communications packet has
+arrived from another node. This directive is called by the user-provided MPCI,
+and is only used in multiprocessing configurations.
+
+.. rubric:: NOTES:
+
+This directive is typically called from an :term:`ISR`.
+
+This directive does not generate activity on remote nodes.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within interrupt context.
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive may unblock a task. This may cause the calling task to be
+ preempted.
diff --git a/c-user/multiprocessing/index.rst b/c-user/multiprocessing/index.rst
new file mode 100644
index 0000000..4ec4433
--- /dev/null
+++ b/c-user/multiprocessing/index.rst
@@ -0,0 +1,17 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+
+.. index:: multiprocessing
+
+.. _RTEMSAPIClassicMP:
+
+Multiprocessing Manager
+***********************
+
+.. toctree::
+
+ introduction
+ background
+ operations
+ directives
diff --git a/c-user/multiprocessing/introduction.rst b/c-user/multiprocessing/introduction.rst
new file mode 100644
index 0000000..742a034
--- /dev/null
+++ b/c-user/multiprocessing/introduction.rst
@@ -0,0 +1,61 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2021 embedded brains GmbH (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:/rtems/mp/if/group
+
+.. _MultiprocessingManagerIntroduction:
+
+Introduction
+============
+
+.. The following list was generated from:
+.. spec:/rtems/mp/if/announce
+
+The Multiprocessing Manager provides support for heterogeneous multiprocessing
+systems based on message passing in a network of multiprocessing nodes.
+
+In multiprocessor real-time systems, new requirements, such as sharing data and
+global resources between processors, are introduced. This requires an
+efficient and reliable communications vehicle which allows all processors to
+communicate with each other as necessary. In addition, the ramifications of
+multiple processors affect each and every characteristic of a real-time system,
+almost always making them more complicated.
+
+RTEMS addresses these issues by providing simple and flexible real-time
+multiprocessing capabilities. The executive easily lends itself to both
+tightly-coupled and loosely-coupled configurations of the target system
+hardware. In addition, RTEMS supports systems composed of both homogeneous and
+heterogeneous mixtures of processors and target boards.
+
+A major design goal of the RTEMS executive was to transcend the physical
+boundaries of the target hardware configuration. This goal is achieved by
+presenting the application software with a logical view of the target system
+where the boundaries between processor nodes are transparent. As a result, the
+application developer may designate objects such as tasks, queues, events,
+signals, semaphores, and memory blocks as global objects. These global objects
+may then be accessed by any task regardless of the physical location of the
+object and the accessing task. RTEMS automatically determines that the object
+being accessed resides on another processor and performs the actions required
+to access the desired object. Simply stated, RTEMS allows the entire system,
+both hardware and software, to be viewed logically as a single system. The
+directives provided by the Multiprocessing Manager are:
+
+* :ref:`InterfaceRtemsMultiprocessingAnnounce` - Announces the arrival of a
+ packet.
diff --git a/c-user/multiprocessing/operations.rst b/c-user/multiprocessing/operations.rst
new file mode 100644
index 0000000..08dcded
--- /dev/null
+++ b/c-user/multiprocessing/operations.rst
@@ -0,0 +1,13 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+
+Operations
+==========
+
+Announcing a Packet
+-------------------
+
+The ``rtems_multiprocessing_announce`` directive is called by the MPCI layer to
+inform RTEMS that a packet has arrived from another node. This directive can
+be called from an interrupt service routine or from within a polling routine.
diff --git a/c-user/rate-monotonic/background.rst b/c-user/rate-monotonic/background.rst
index 9ca7dff..c81af4e 100644
--- a/c-user/rate-monotonic/background.rst
+++ b/c-user/rate-monotonic/background.rst
@@ -112,7 +112,9 @@ less than its period. For example, a periodic task's requirements may state
that it should execute for 10 milliseconds every 100 milliseconds. Although
the execution time may be the average, worst, or best case, the worst-case
execution time is more appropriate for use when analyzing system behavior under
-transient overload conditions... index:: aperiodic task, definition
+transient overload conditions.
+
+.. index:: aperiodic task, definition
In contrast, an aperiodic task executes at irregular intervals and has only a
soft deadline. In other words, the deadlines for aperiodic tasks are not
diff --git a/c-user/rate-monotonic/directives.rst b/c-user/rate-monotonic/directives.rst
index d100c81..1935e8a 100644
--- a/c-user/rate-monotonic/directives.rst
+++ b/c-user/rate-monotonic/directives.rst
@@ -1,474 +1,719 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
+.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de)
+.. Copyright (C) 2017 Kuan-Hsun Chen
.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
-.. Copyright (C) 2017 Kuan-Hsun Chen.
+
+.. This file is part of the RTEMS quality process and was automatically
+.. generated. If you find something that needs to be fixed or
+.. worded better please post a report or patch to an RTEMS mailing list
+.. or raise a bug report:
+..
+.. https://www.rtems.org/bugs.html
+..
+.. For information on updating and regenerating please refer to the How-To
+.. section in the Software Requirements Engineering chapter of the
+.. RTEMS Software Engineering manual. The manual is provided as a part of
+.. a release. For development sources please refer to the online
+.. documentation at:
+..
+.. https://docs.rtems.org
+
+.. _RateMonotonicManagerDirectives:
Directives
==========
-This section details the rate monotonic manager's directives. A subsection is
-dedicated to each of this manager's directives and describes the calling
-sequence, related constants, usage, and status codes.
+This section details the directives of the Rate-Monotonic Manager. A subsection
+is dedicated to each of this manager's directives and lists the calling
+sequence, parameters, description, return values, and notes of the directive.
+
+.. Generated from spec:/rtems/ratemon/if/create
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_rate_monotonic_create()
.. index:: create a period
-.. index:: rtems_rate_monotonic_create
-.. _rtems_rate_monotonic_create:
+.. _InterfaceRtemsRateMonotonicCreate:
+
+rtems_rate_monotonic_create()
+-----------------------------
+
+Creates a period.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_rate_monotonic_create( rtems_name name, rtems_id *id );
+
+.. rubric:: PARAMETERS:
+
+``name``
+ This parameter is the object name of the period.
+
+``id``
+ This parameter is the pointer to an object identifier variable. When the
+ directive call is successful, the identifier of the created period will be
+ stored in this variable.
+
+.. rubric:: DESCRIPTION:
+
+This directive creates a period which resides on the local node. The period
+has the user-defined object name specified in ``name`` The assigned object
+identifier is returned in ``id``. This identifier is used to access the period
+with other rate monotonic related directives.
-RATE_MONOTONIC_CREATE - Create a rate monotonic period
-------------------------------------------------------
+.. rubric:: RETURN VALUES:
-CALLING SEQUENCE:
- .. code-block:: c
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
- rtems_status_code rtems_rate_monotonic_create(
- rtems_name name,
- rtems_id *id
- );
+:c:macro:`RTEMS_INVALID_NAME`
+ The ``name`` parameter was invalid.
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+:c:macro:`RTEMS_TOO_MANY`
+ There was no inactive object available to create a period. The number of
+ periods available to the application is configured through the
+ :ref:`CONFIGURE_MAXIMUM_PERIODS` application configuration option.
- * - ``RTEMS_SUCCESSFUL``
- - rate monotonic period created successfully
- * - ``RTEMS_INVALID_NAME``
- - invalid period name
- * - ``RTEMS_TOO_MANY``
- - too many periods created
+.. rubric:: NOTES:
-DESCRIPTION:
- This directive creates a rate monotonic period. The assigned rate
- monotonic id is returned in id. This id is used to access the period with
- other rate monotonic manager directives. For control and maintenance of
- the rate monotonic period, RTEMS allocates a PCB from the local PCB free
- pool and initializes it.
+The calling task is registered as the owner of the created period. Some
+directives can be only used by this task for the created period.
-NOTES:
- This directive may cause the calling task to be preempted due to an
- obtain and release of the object allocator mutex.
+For control and maintenance of the period, RTEMS allocates a :term:`PCB` from
+the local PCB free pool and initializes it.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive may obtain and release the object allocator mutex. This may
+ cause the calling task to be preempted.
+
+* The number of periods available to the application is configured through the
+ :ref:`CONFIGURE_MAXIMUM_PERIODS` application configuration option.
+
+* Where the object class corresponding to the directive is configured to use
+ unlimited objects, the directive may allocate memory from the RTEMS
+ Workspace.
+
+.. Generated from spec:/rtems/ratemon/if/ident
.. raw:: latex
- \clearpage
+ \clearpage
+
+.. index:: rtems_rate_monotonic_ident()
+
+.. _InterfaceRtemsRateMonotonicIdent:
+
+rtems_rate_monotonic_ident()
+----------------------------
-.. index:: get ID of a period
-.. index:: obtain ID of a period
-.. index:: rtems_rate_monotonic_ident
+Identifies a period by the object name.
-.. _rtems_rate_monotonic_ident:
+.. rubric:: CALLING SEQUENCE:
-RATE_MONOTONIC_IDENT - Get ID of a period
------------------------------------------
+.. code-block:: c
-CALLING SEQUENCE:
- .. code-block:: c
+ rtems_status_code rtems_rate_monotonic_ident( rtems_name name, rtems_id *id );
- rtems_status_code rtems_rate_monotonic_ident(
- rtems_name name,
- rtems_id *id
- );
+.. rubric:: PARAMETERS:
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+``name``
+ This parameter is the object name to look up.
- * - ``RTEMS_SUCCESSFUL``
- - period identified successfully
- * - ``RTEMS_INVALID_NAME``
- - period name not found
+``id``
+ This parameter is the pointer to an object identifier variable. When the
+ directive call is successful, the object identifier of an object with the
+ specified name will be stored in this variable.
-DESCRIPTION:
- This directive obtains the period id associated with the period name to be
- acquired. If the period name is not unique, then the period id will match
- one of the periods with that name. However, this period id is not
- guaranteed to correspond to the desired period. The period id is used to
- access this period in other rate monotonic manager directives.
+.. rubric:: DESCRIPTION:
-NOTES:
- This directive will not cause the running task to be preempted.
+This directive obtains a period identifier associated with the period name
+specified in ``name``.
+
+.. rubric:: RETURN VALUES:
+
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``id`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+:c:macro:`RTEMS_INVALID_NAME`
+ The ``name`` parameter was 0.
+
+:c:macro:`RTEMS_INVALID_NAME`
+ There was no object with the specified name on the local node.
+
+.. rubric:: NOTES:
+
+If the period name is not unique, then the period identifier will match the
+first period with that name in the search order. However, this period
+identifier is not guaranteed to correspond to the desired period.
+
+The objects are searched from lowest to the highest index. Only the local node
+is searched.
+
+The period identifier is used with other rate monotonic related directives to
+access the period.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/ratemon/if/cancel
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_rate_monotonic_cancel()
.. index:: cancel a period
-.. index:: rtems_rate_monotonic_cancel
-.. _rtems_rate_monotonic_cancel:
+.. _InterfaceRtemsRateMonotonicCancel:
-RATE_MONOTONIC_CANCEL - Cancel a period
----------------------------------------
+rtems_rate_monotonic_cancel()
+-----------------------------
+
+Cancels the period.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_rate_monotonic_cancel( rtems_id id );
+
+.. rubric:: PARAMETERS:
+
+``id``
+ This parameter is the rate monotonic period identifier.
+
+.. rubric:: DESCRIPTION:
-CALLING SEQUENCE:
- .. code-block:: c
+This directive cancels the rate monotonic period specified by ``id``. This
+period may be reinitiated by the next invocation of
+:ref:`InterfaceRtemsRateMonotonicPeriod`.
- rtems_status_code rtems_rate_monotonic_cancel(
- rtems_id id
- );
+.. rubric:: RETURN VALUES:
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
- * - ``RTEMS_SUCCESSFUL``
- - period canceled successfully
- * - ``RTEMS_INVALID_ID``
- - invalid rate monotonic period id
- * - ``RTEMS_NOT_OWNER_OF_RESOURCE``
- - rate monotonic period not created by calling task
+:c:macro:`RTEMS_INVALID_ID`
+ There was no rate monotonic period associated with the identifier specified
+ by ``id``.
-DESCRIPTION:
+:c:macro:`RTEMS_NOT_OWNER_OF_RESOURCE`
+ The rate monotonic period was not created by the calling task.
- This directive cancels the rate monotonic period id. This period will be
- reinitiated by the next invocation of ``rtems_rate_monotonic_period``
- with id.
+.. rubric:: CONSTRAINTS:
-NOTES:
- This directive will not cause the running task to be preempted.
+The following constraints apply to this directive:
- The rate monotonic period specified by id must have been created by the
- calling task.
+* The directive may be called from within task context.
+
+* The directive will not cause the calling task to be preempted.
+
+* The directive may be used exclusively by the task which created the
+ associated object.
+
+.. Generated from spec:/rtems/ratemon/if/delete
.. raw:: latex
- \clearpage
+ \clearpage
-.. index:: rtems_rate_monotonic_delete
+.. index:: rtems_rate_monotonic_delete()
.. index:: delete a period
-.. _rtems_rate_monotonic_delete:
+.. _InterfaceRtemsRateMonotonicDelete:
+
+rtems_rate_monotonic_delete()
+-----------------------------
+
+Deletes the period.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_rate_monotonic_delete( rtems_id id );
+
+.. rubric:: PARAMETERS:
+
+``id``
+ This parameter is the period identifier.
+
+.. rubric:: DESCRIPTION:
+
+This directive deletes the period specified by ``id``. If the period is
+running, it is automatically canceled.
-RATE_MONOTONIC_DELETE - Delete a rate monotonic period
-------------------------------------------------------
+.. rubric:: RETURN VALUES:
-CALLING SEQUENCE:
- .. code-block:: c
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
- rtems_status_code rtems_rate_monotonic_delete(
- rtems_id id
- );
+:c:macro:`RTEMS_INVALID_ID`
+ There was no period associated with the identifier specified by ``id``.
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+.. rubric:: NOTES:
- * - ``RTEMS_SUCCESSFUL``
- - period deleted successfully
- * - ``RTEMS_INVALID_ID``
- - invalid rate monotonic period id
+The :term:`PCB` for the deleted period is reclaimed by RTEMS.
-DESCRIPTION:
+.. rubric:: CONSTRAINTS:
- This directive deletes the rate monotonic period specified by id. If the
- period is running, it is automatically canceled. The PCB for the deleted
- period is reclaimed by RTEMS.
+The following constraints apply to this directive:
-NOTES:
- This directive may cause the calling task to be preempted due to an
- obtain and release of the object allocator mutex.
+* The directive may be called from within device driver initialization context.
- A rate monotonic period can be deleted by a task other than the task which
- created the period.
+* The directive may be called from within task context.
+
+* The directive may obtain and release the object allocator mutex. This may
+ cause the calling task to be preempted.
+
+* The calling task does not have to be the task that created the object. Any
+ local task that knows the object identifier can delete the object.
+
+* Where the object class corresponding to the directive is configured to use
+ unlimited objects, the directive may free memory to the RTEMS Workspace.
+
+.. Generated from spec:/rtems/ratemon/if/period
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_rate_monotonic_period()
.. index:: conclude current period
.. index:: start current period
.. index:: period initiation
-.. index:: rtems_rate_monotonic_period
-
-.. _rtems_rate_monotonic_period:
-
-RATE_MONOTONIC_PERIOD - Conclude current/Start next period
-----------------------------------------------------------
-
-CALLING SEQUENCE:
- .. code-block:: c
-
- rtems_status_code rtems_rate_monotonic_period(
- rtems_id id,
- rtems_interval length
- );
-
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
-
- * - ``RTEMS_SUCCESSFUL``
- - period initiated successfully
- * - ``RTEMS_INVALID_ID``
- - invalid rate monotonic period id
- * - ``RTEMS_NOT_OWNER_OF_RESOURCE``
- - period not created by calling task
- * - ``RTEMS_NOT_DEFINED``
- - period has never been initiated (only possible when period is set to PERIOD_STATUS)
- * - ``RTEMS_TIMEOUT``
- - period has expired
-
-DESCRIPTION:
- This directive initiates the rate monotonic period id with a length of
- period ticks. If id is running, then the calling task will block for the
- remainder of the period before reinitiating the period with the specified
- period. If id was not running (either expired or never initiated), the
- period is immediately initiated and the directive returns immediately.
- If id has expired its period, the postponed job will be released immediately
- and the following calls of this directive will release postponed
- jobs until there is no more deadline miss.
-
- If invoked with a period of ``RTEMS_PERIOD_STATUS`` ticks, the current
- state of id will be returned. The directive status indicates the current
- state of the period. This does not alter the state or period of the
- period.
-
-NOTES:
- This directive will not cause the running task to be preempted.
+
+.. _InterfaceRtemsRateMonotonicPeriod:
+
+rtems_rate_monotonic_period()
+-----------------------------
+
+Concludes the current period and start the next period, or gets the period
+status.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_rate_monotonic_period(
+ rtems_id id,
+ rtems_interval length
+ );
+
+.. rubric:: PARAMETERS:
+
+``id``
+ This parameter is the rate monotonic period identifier.
+
+``length``
+ This parameter is the period length in :term:`clock ticks <clock tick>` or
+ :c:macro:`RTEMS_PERIOD_STATUS` to get the period status.
+
+.. rubric:: DESCRIPTION:
+
+This directive initiates the rate monotonic period specified by ``id`` with a
+length of period ticks specified by ``length``. If the period is running, then
+the calling task will block for the remainder of the period before reinitiating
+the period with the specified period length. If the period was not running
+(either expired or never initiated), the period is immediately initiated and
+the directive returns immediately. If the period has expired, the postponed
+job will be released immediately and the following calls of this directive will
+release postponed jobs until there is no more deadline miss.
+
+If invoked with a period length of :c:macro:`RTEMS_PERIOD_STATUS` ticks, the
+current state of the period will be returned. The directive status indicates
+the current state of the period. This does not alter the state or period
+length of the period.
+
+.. rubric:: RETURN VALUES:
+
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_ID`
+ There was no rate monotonic period associated with the identifier specified
+ by ``id``.
+
+:c:macro:`RTEMS_NOT_OWNER_OF_RESOURCE`
+ The rate monotonic period was not created by the calling task.
+
+:c:macro:`RTEMS_NOT_DEFINED`
+ The rate monotonic period has never been initiated (only possible when the
+ ``length`` parameter was equal to :c:macro:`RTEMS_PERIOD_STATUS`).
+
+:c:macro:`RTEMS_TIMEOUT`
+ The rate monotonic period has expired.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within task context.
+
+* The directive may be used exclusively by the task which created the
+ associated object.
+
+.. Generated from spec:/rtems/ratemon/if/get-status
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_rate_monotonic_get_status()
.. index:: get status of period
.. index:: obtain status of period
-.. index:: rtems_rate_monotonic_get_status
-
-.. _rtems_rate_monotonic_get_status:
-
-RATE_MONOTONIC_GET_STATUS - Obtain status from a period
--------------------------------------------------------
-
-CALLING SEQUENCE:
- .. code-block:: c
-
- rtems_status_code rtems_rate_monotonic_get_status(
- rtems_id id,
- rtems_rate_monotonic_period_status *status
- );
-
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
-
- * - ``RTEMS_SUCCESSFUL``
- - period status retrieved successfully
- * - ``RTEMS_INVALID_ID``
- - invalid rate monotonic period id
- * - ``RTEMS_INVALID_ADDRESS``
- - invalid address of status
- * - ``RTEMS_NOT_DEFINED``
- - no status is available due to the cpu usage of the task having been
- reset since the period initiated
-
-*DESCRIPTION:
- This directive returns status information associated with the rate
- monotonic period id in the following data structure:
-
- .. index:: rtems_rate_monotonic_period_status
-
- .. code-block:: c
-
- typedef struct {
- rtems_id owner;
- rtems_rate_monotonic_period_states state;
- rtems_rate_monotonic_period_time_t since_last_period;
- rtems_thread_cpu_usage_t executed_since_last_period;
- uint32_t postponed_jobs_count;
- } rtems_rate_monotonic_period_status;
-
- .. COMMENT: RATE_MONOTONIC_INACTIVE does not have RTEMS in front of it.
-
- A configure time option can be used to select whether the time information
- is given in ticks or seconds and nanoseconds. The default is seconds and
- nanoseconds. If the period's state is ``RATE_MONOTONIC_INACTIVE``, both
- time values will be set to 0. Otherwise, both time values will contain
- time information since the last invocation of the
- ``rtems_rate_monotonic_period`` directive. More specifically, the
- since_last_period value contains the elapsed time which has occurred since
- the last invocation of the ``rtems_rate_monotonic_period`` directive and
- the ``executed_since_last_period`` contains how much processor time the
- owning task has consumed since the invocation of the
- ``rtems_rate_monotonic_period`` directive. In addition, the
- ``postponed_jobs_count value`` contains the count of jobs which are not
- released yet.
-
-NOTES:
- This directive will not cause the running task to be preempted.
+
+.. _InterfaceRtemsRateMonotonicGetStatus:
+
+rtems_rate_monotonic_get_status()
+---------------------------------
+
+Gets the detailed status of the period.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_rate_monotonic_get_status(
+ rtems_id id,
+ rtems_rate_monotonic_period_status *status
+ );
+
+.. rubric:: PARAMETERS:
+
+``id``
+ This parameter is the rate monotonic period identifier.
+
+``status``
+ This parameter is the pointer to a
+ :c:type:`rtems_rate_monotonic_period_status` variable. When the directive
+ call is successful, the detailed period status will be stored in this
+ variable.
+
+.. rubric:: DESCRIPTION:
+
+This directive returns the detailed status of the rate monotonic period
+specified by ``id``. The detailed status of the period will be returned in the
+members of the period status object referenced by ``status``:
+
+* The ``owner`` member is set to the identifier of the owner task of the
+ period.
+
+* The ``state`` member is set to the current state of the period.
+
+* The ``postponed_jobs_count`` member is set to the count of jobs which are not
+ released yet.
+
+* If the current state of the period is :c:macro:`RATE_MONOTONIC_INACTIVE`, the
+ ``since_last_period`` and ``executed_since_last_period`` members will be set
+ to zero. Otherwise, both members will contain time information since the
+ last successful invocation of the :ref:`InterfaceRtemsRateMonotonicPeriod`
+ directive by the owner task. More specifically, the ``since_last_period``
+ member will be set to the time elapsed since the last successful invocation.
+ The ``executed_since_last_period`` member will be set to the processor time
+ consumed by the owner task since the last successful invocation.
+
+.. rubric:: RETURN VALUES:
+
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_ID`
+ There was no rate monotonic period associated with the identifier specified
+ by ``id``.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``status`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+: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:
+
+* The directive may be called from within task context.
+
+* The directive may be called from within interrupt context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/ratemon/if/get-statistics
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_rate_monotonic_get_statistics()
.. index:: get statistics of period
.. index:: obtain statistics of period
-.. index:: rtems_rate_monotonic_get_statistics
-
-.. _rtems_rate_monotonic_get_statistics:
-
-RATE_MONOTONIC_GET_STATISTICS - Obtain statistics from a period
----------------------------------------------------------------
-
-CALLING SEQUENCE:
- .. code-block:: c
-
- rtems_status_code rtems_rate_monotonic_get_statistics(
- rtems_id id,
- rtems_rate_monotonic_period_statistics *statistics
- );
-
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
-
- * - ``RTEMS_SUCCESSFUL``
- - period statistics retrieved successfully
- * - ``RTEMS_INVALID_ID``
- - invalid rate monotonic period id
- * - ``RTEMS_INVALID_ADDRESS``
- - invalid address of statistics
-
-DESCRIPTION:
- This directive returns statistics information associated with the rate
- monotonic period id in the following data structure:
-
- .. index:: rtems_rate_monotonic_period_statistics
-
- .. code-block:: c
-
- typedef struct {
- uint32_t count;
- uint32_t missed_count;
- #ifdef RTEMS_ENABLE_NANOSECOND_CPU_USAGE_STATISTICS
- struct timespec min_cpu_time;
- struct timespec max_cpu_time;
- struct timespec total_cpu_time;
- #else
- uint32_t min_cpu_time;
- uint32_t max_cpu_time;
- uint32_t total_cpu_time;
- #endif
- #ifdef RTEMS_ENABLE_NANOSECOND_RATE_MONOTONIC_STATISTICS
- struct timespec min_wall_time;
- struct timespec max_wall_time;
- struct timespec total_wall_time;
- #else
- uint32_t min_wall_time;
- uint32_t max_wall_time;
- uint32_t total_wall_time;
- #endif
- } rtems_rate_monotonic_period_statistics;
-
- This directive returns the current statistics information for the period
- instance assocaited with ``id``. The information returned is indicated by
- the structure above.
-
-NOTES:
- This directive will not cause the running task to be preempted.
+
+.. _InterfaceRtemsRateMonotonicGetStatistics:
+
+rtems_rate_monotonic_get_statistics()
+-------------------------------------
+
+Gets the statistics of the period.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_rate_monotonic_get_statistics(
+ rtems_id id,
+ rtems_rate_monotonic_period_statistics *status
+ );
+
+.. rubric:: PARAMETERS:
+
+``id``
+ This parameter is the rate monotonic period identifier.
+
+``status``
+ This parameter is the pointer to a
+ :c:type:`rtems_rate_monotonic_period_statistics` variable. When the
+ directive call is successful, the period statistics will be stored in this
+ variable.
+
+.. rubric:: DESCRIPTION:
+
+This directive returns the statistics of the rate monotonic period specified by
+``id``. The statistics of the period will be returned in the members of the
+period statistics object referenced by ``status``:
+
+* The ``count`` member is set to the number of periods executed.
+
+* The ``missed_count`` member is set to the number of periods missed.
+
+* The ``min_cpu_time`` member is set to the least amount of processor time used
+ in the period.
+
+* The ``max_cpu_time`` member is set to the highest amount of processor time
+ used in the period.
+
+* The ``total_cpu_time`` member is set to the total amount of processor time
+ used in the period.
+
+* The ``min_wall_time`` member is set to the least amount of
+ :term:`CLOCK_MONOTONIC` time used in the period.
+
+* The ``max_wall_time`` member is set to the highest amount of
+ :term:`CLOCK_MONOTONIC` time used in the period.
+
+* The ``total_wall_time`` member is set to the total amount of
+ :term:`CLOCK_MONOTONIC` time used in the period.
+
+.. rubric:: RETURN VALUES:
+
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_ID`
+ There was no rate monotonic period associated with the identifier specified
+ by ``id``.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``status`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within task context.
+
+* The directive may be called from within interrupt context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/ratemon/if/reset-statistics
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_rate_monotonic_reset_statistics()
.. index:: reset statistics of period
-.. index:: rtems_rate_monotonic_reset_statistics
-.. _rtems_rate_monotonic_reset_statistics:
+.. _InterfaceRtemsRateMonotonicResetStatistics:
+
+rtems_rate_monotonic_reset_statistics()
+---------------------------------------
+
+Resets the statistics of the period.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_rate_monotonic_reset_statistics( rtems_id id );
+
+.. rubric:: PARAMETERS:
+
+``id``
+ This parameter is the rate monotonic period identifier.
-RATE_MONOTONIC_RESET_STATISTICS - Reset statistics for a period
----------------------------------------------------------------
+.. rubric:: DESCRIPTION:
-CALLING SEQUENCE:
- .. code-block:: c
+This directive resets the statistics of the rate monotonic period specified by
+``id``.
- rtems_status_code rtems_rate_monotonic_reset_statistics(
- rtems_id id
- );
+.. rubric:: RETURN VALUES:
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
- * - ``RTEMS_SUCCESSFUL``
- - period initiated successfully
- * - ``RTEMS_INVALID_ID``
- - invalid rate monotonic period id
+:c:macro:`RTEMS_INVALID_ID`
+ There was no rate monotonic period associated with the identifier specified
+ by ``id``.
-DESCRIPTION:
- This directive resets the statistics information associated with this rate
- monotonic period instance.
+.. rubric:: CONSTRAINTS:
-NOTES:
- This directive will not cause the running task to be preempted.
+The following constraints apply to this directive:
+
+* The directive may be called from within task context.
+
+* The directive may be called from within interrupt context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/ratemon/if/reset-all-statistics
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_rate_monotonic_reset_all_statistics()
.. index:: reset statistics of all periods
-.. index:: rtems_rate_monotonic_reset_all_statistics
-.. _rtems_rate_monotonic_reset_all_statistics:
+.. _InterfaceRtemsRateMonotonicResetAllStatistics:
+
+rtems_rate_monotonic_reset_all_statistics()
+-------------------------------------------
+
+Resets the statistics of all periods.
-RATE_MONOTONIC_RESET_ALL_STATISTICS - Reset statistics for all periods
-----------------------------------------------------------------------
+.. rubric:: CALLING SEQUENCE:
-CALLING SEQUENCE:
- .. code-block:: c
+.. code-block:: c
- void rtems_rate_monotonic_reset_all_statistics(void);
+ void rtems_rate_monotonic_reset_all_statistics( void );
-DIRECTIVE STATUS CODES:
- NONE
+.. rubric:: DESCRIPTION:
-DESCRIPTION:
- This directive resets the statistics information associated with all rate
- monotonic period instances.
+This directive resets the statistics information associated with all rate
+monotonic period instances.
-NOTES:
- This directive will not cause the running task to be preempted.
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within task context.
+
+* The directive may obtain and release the object allocator mutex. This may
+ cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/ratemon/if/report-statistics
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_rate_monotonic_report_statistics()
.. index:: print period statistics report
.. index:: period statistics report
-.. index:: rtems_rate_monotonic_report_statistics
-.. _rtems_rate_monotonic_report_statistics:
+.. _InterfaceRtemsRateMonotonicReportStatistics:
+
+rtems_rate_monotonic_report_statistics()
+----------------------------------------
+
+Reports the period statistics using the :c:func:`printk` printer.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ void rtems_rate_monotonic_report_statistics( void );
+
+.. rubric:: DESCRIPTION:
+
+This directive prints a report on all active periods which have executed at
+least one period using the :c:func:`printk` printer.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within task context.
+
+* The directive may obtain and release the object allocator mutex. This may
+ cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/ratemon/if/report-statistics-with-plugin
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: rtems_rate_monotonic_report_statistics_with_plugin()
+.. index:: print period statistics report
+.. index:: period statistics report
+
+.. _InterfaceRtemsRateMonotonicReportStatisticsWithPlugin:
+
+rtems_rate_monotonic_report_statistics_with_plugin()
+----------------------------------------------------
+
+Reports the period statistics using the printer plugin.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
-RATE_MONOTONIC_REPORT_STATISTICS - Print period statistics report
------------------------------------------------------------------
+ void rtems_rate_monotonic_report_statistics_with_plugin(
+ const struct rtems_printer *printer
+ );
-CALLING SEQUENCE:
- .. code-block:: c
+.. rubric:: PARAMETERS:
- void rtems_rate_monotonic_report_statistics(void);
+``printer``
+ This parameter is the printer plugin to output the report.
-DIRECTIVE STATUS CODES:
- NONE
+.. rubric:: DESCRIPTION:
-DESCRIPTION:
- This directive prints a report on all active periods which have executed at
- least one period. The following is an example of the output generated by
- this directive.
+This directive prints a report on all active periods which have executed at
+least one period using the printer plugin specified by ``printer``.
- .. index:: rtems_rate_monotonic_period_statistics
+.. rubric:: CONSTRAINTS:
- .. code-block:: c
+The following constraints apply to this directive:
- ID OWNER PERIODS MISSED CPU TIME WALL TIME
- MIN/MAX/AVG MIN/MAX/AVG
- 0x42010001 TA1 502 0 0/1/0.99 0/0/0.00
- 0x42010002 TA2 502 0 0/1/0.99 0/0/0.00
- 0x42010003 TA3 501 0 0/1/0.99 0/0/0.00
- 0x42010004 TA4 501 0 0/1/0.99 0/0/0.00
- 0x42010005 TA5 10 0 0/1/0.90 0/0/0.00
+* The directive may be called from within task context.
-NOTES:
- This directive will not cause the running task to be preempted.
+* The directive may obtain and release the object allocator mutex. This may
+ cause the calling task to be preempted.
diff --git a/c-user/rate-monotonic/introduction.rst b/c-user/rate-monotonic/introduction.rst
index cb09898..5b0c094 100644
--- a/c-user/rate-monotonic/introduction.rst
+++ b/c-user/rate-monotonic/introduction.rst
@@ -1,33 +1,76 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
+.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de)
+.. Copyright (C) 2017 Kuan-Hsun Chen
.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
-.. Copyright (C) 2017 Kuan-Hsun Chen.
+
+.. This file is part of the RTEMS quality process and was automatically
+.. generated. If you find something that needs to be fixed or
+.. worded better please post a report or patch to an RTEMS mailing list
+.. or raise a bug report:
+..
+.. https://www.rtems.org/bugs.html
+..
+.. For information on updating and regenerating please refer to the How-To
+.. section in the Software Requirements Engineering chapter of the
+.. RTEMS Software Engineering manual. The manual is provided as a part of
+.. a release. For development sources please refer to the online
+.. documentation at:
+..
+.. https://docs.rtems.org
+
+.. Generated from spec:/rtems/ratemon/if/group
+
+.. _RateMonotonicManagerIntroduction:
Introduction
============
-The rate monotonic manager provides facilities to implement tasks which execute
+.. The following list was generated from:
+.. spec:/rtems/ratemon/if/create
+.. spec:/rtems/ratemon/if/ident
+.. spec:/rtems/ratemon/if/cancel
+.. spec:/rtems/ratemon/if/delete
+.. spec:/rtems/ratemon/if/period
+.. spec:/rtems/ratemon/if/get-status
+.. spec:/rtems/ratemon/if/get-statistics
+.. spec:/rtems/ratemon/if/reset-statistics
+.. spec:/rtems/ratemon/if/reset-all-statistics
+.. spec:/rtems/ratemon/if/report-statistics
+.. spec:/rtems/ratemon/if/report-statistics-with-plugin
+
+The Rate-Monotonic Manager provides facilities to implement tasks which execute
in a periodic fashion. Critically, it also gathers information about the
execution of those periods and can provide important statistics to the user
-which can be used to analyze and tune the application. The directives provided
-by the rate monotonic manager are:
+which can be used to analyze and tune the application. The directives provided
+by the Rate-Monotonic Manager are:
+
+* :ref:`InterfaceRtemsRateMonotonicCreate` - Creates a period.
-- :ref:`rtems_rate_monotonic_create`
+* :ref:`InterfaceRtemsRateMonotonicIdent` - Identifies a period by the object
+ name.
-- :ref:`rtems_rate_monotonic_ident`
+* :ref:`InterfaceRtemsRateMonotonicCancel` - Cancels the period.
-- :ref:`rtems_rate_monotonic_cancel`
+* :ref:`InterfaceRtemsRateMonotonicDelete` - Deletes the period.
-- :ref:`rtems_rate_monotonic_delete`
+* :ref:`InterfaceRtemsRateMonotonicPeriod` - Concludes the current period and
+ start the next period, or gets the period status.
-- :ref:`rtems_rate_monotonic_period`
+* :ref:`InterfaceRtemsRateMonotonicGetStatus` - Gets the detailed status of the
+ period.
-- :ref:`rtems_rate_monotonic_get_status`
+* :ref:`InterfaceRtemsRateMonotonicGetStatistics` - Gets the statistics of the
+ period.
-- :ref:`rtems_rate_monotonic_get_statistics`
+* :ref:`InterfaceRtemsRateMonotonicResetStatistics` - Resets the statistics of
+ the period.
-- :ref:`rtems_rate_monotonic_reset_statistics`
+* :ref:`InterfaceRtemsRateMonotonicResetAllStatistics` - Resets the statistics
+ of all periods.
-- :ref:`rtems_rate_monotonic_reset_all_statistics`
+* :ref:`InterfaceRtemsRateMonotonicReportStatistics` - Reports the period
+ statistics using the :c:func:`printk` printer.
-- :ref:`rtems_rate_monotonic_report_statistics`
+* :ref:`InterfaceRtemsRateMonotonicReportStatisticsWithPlugin` - Reports the
+ period statistics using the printer plugin.
diff --git a/c-user/region/directives.rst b/c-user/region/directives.rst
index be994f6..86bb537 100644
--- a/c-user/region/directives.rst
+++ b/c-user/region/directives.rst
@@ -1,561 +1,916 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
+.. Copyright (C) 2020, 2021 embedded brains GmbH (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
+
+.. _RegionManagerDirectives:
+
Directives
==========
-This section details the region manager's directives. A subsection is
-dedicated to each of this manager's directives and describes the calling
-sequence, related constants, usage, and status codes.
+This section details the directives of the Region Manager. A subsection is
+dedicated to each of this manager's directives and lists the calling sequence,
+parameters, description, return values, and notes of the directive.
+
+.. Generated from spec:/rtems/region/if/create
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_region_create()
.. index:: create a region
-.. _rtems_region_create:
+.. _InterfaceRtemsRegionCreate:
-REGION_CREATE - Create a region
--------------------------------
+rtems_region_create()
+---------------------
+
+Creates a region.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_region_create(
+ rtems_name name,
+ void *starting_address,
+ uintptr_t length,
+ uintptr_t page_size,
+ rtems_attribute attribute_set,
+ rtems_id *id
+ );
+
+.. rubric:: PARAMETERS:
+
+``name``
+ This parameter is the object name of the region.
+
+``starting_address``
+ This parameter is the starting address of the memory area managed by the
+ region.
+
+``length``
+ This parameter is the length in bytes of the memory area managed by the
+ region.
+
+``page_size``
+ This parameter is the alignment of the starting address and length of each
+ allocated segment of the region.
+
+``attribute_set``
+ This parameter is the attribute set of the region.
+
+``id``
+ This parameter is the pointer to an object identifier variable. When the
+ directive call is successful, the identifier of the created region will be
+ stored in this variable.
+
+.. rubric:: DESCRIPTION:
+
+This directive creates a region which resides on the local node. The region
+has the user-defined object name specified in ``name``. The assigned object
+identifier is returned in ``id``. This identifier is used to access the region
+with other region related directives.
+
+The region manages the **contiguous memory area** which starts at
+``starting_address`` and is ``length`` bytes long. The memory area shall be
+large enough to contain some internal region administration data.
+
+The **starting address** and **length of segments** allocated from the region
+will be an integral multiple of ``page_size``. The specified page size will be
+aligned to an implementation-dependent minimum alignment if necessary.
+
+The **attribute set** specified in ``attribute_set`` is built through a
+*bitwise or* of the attribute constants described below. Not all combinations
+of attributes are allowed. Some attributes are mutually exclusive. If
+mutually exclusive attributes are combined, the behaviour is undefined.
+Attributes not mentioned below are not evaluated by this directive and have no
+effect. Default attributes can be selected by using the
+:c:macro:`RTEMS_DEFAULT_ATTRIBUTES` constant.
+
+The **task wait queue discipline** is selected by the mutually exclusive
+:c:macro:`RTEMS_FIFO` and :c:macro:`RTEMS_PRIORITY` attributes. The discipline
+defines the order in which tasks wait for allocatable segments on a currently
+empty region.
+
+* The **FIFO discipline** is the default and can be emphasized through use of
+ the :c:macro:`RTEMS_FIFO` attribute.
+
+* The **priority discipline** is selected by the :c:macro:`RTEMS_PRIORITY`
+ attribute.
+
+.. rubric:: RETURN VALUES:
+
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_NAME`
+ The ``name`` parameter was invalid.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``id`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``starting_address`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+:c:macro:`RTEMS_TOO_MANY`
+ There was no inactive object available to create a region. The number of
+ regions available to the application is configured through the
+ :ref:`CONFIGURE_MAXIMUM_REGIONS` application configuration option.
+
+:c:macro:`RTEMS_INVALID_SIZE`
+ The ``page_size`` parameter was invalid.
+
+:c:macro:`RTEMS_INVALID_SIZE`
+ The memory area specified in ``starting_address`` and ``length`` was too
+ small.
-CALLING SEQUENCE:
- .. code-block:: c
-
- rtems_status_code rtems_region_create(
- rtems_name name,
- void *starting_address,
- uintptr_t length,
- uintptr_t page_size,
- rtems_attribute attribute_set,
- rtems_id *id
- );
-
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
-
- * - ``RTEMS_SUCCESSFUL``
- - region created successfully
- * - ``RTEMS_INVALID_NAME``
- - invalid region name
- * - ``RTEMS_INVALID_ADDRESS``
- - ``id`` is NULL
- * - ``RTEMS_INVALID_ADDRESS``
- - ``starting_address`` is NULL
- * - ``RTEMS_TOO_MANY``
- - too many regions created
- * - ``RTEMS_INVALID_SIZE``
- - invalid page size
- * - ``RTEMS_INVALID_SIZE``
- - the memory area defined by the starting address and the length
- parameters is too small
-
-DESCRIPTION:
- This directive creates a region from a contiguous memory area
- which starts at starting_address and is length bytes long. The memory area
- must be large enough to contain some internal region administration data.
- Segments allocated from the region will be a multiple of page_size bytes in
- length. The specified page size will be aligned to an
- architecture-specific minimum alignment if necessary.
-
- The assigned region id is returned in id. This region id is used as an
- argument to other region related directives to access the region.
-
- For control and maintenance of the region, RTEMS allocates and initializes
- an RNCB from the RNCB free pool. Thus memory from the region is not used
- to store the RNCB. However, some overhead within the region is required by
- RTEMS each time a segment is constructed in the region.
-
- Specifying ``RTEMS_PRIORITY`` in attribute_set causes tasks waiting for a
- segment to be serviced according to task priority. Specifying
- ``RTEMS_FIFO`` in attribute_set or selecting ``RTEMS_DEFAULT_ATTRIBUTES``
- will cause waiting tasks to be serviced in First In-First Out order.
-
-NOTES:
- This directive will obtain the allocator mutex and may cause the calling
- task to be preempted.
-
- The following region attribute constants are defined by RTEMS:
-
- .. list-table::
- :class: rtems-table
-
- * - ``RTEMS_FIFO``
- - tasks wait by FIFO (default)
- * - ``RTEMS_PRIORITY``
- - tasks wait by priority
+.. rubric:: NOTES:
+
+For control and maintenance of the region, RTEMS allocates a :term:`RNCB` from
+the local RNCB free pool and initializes it.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive may obtain and release the object allocator mutex. This may
+ cause the calling task to be preempted.
+
+* The number of regions available to the application is configured through the
+ :ref:`CONFIGURE_MAXIMUM_REGIONS` application configuration option.
+
+* Where the object class corresponding to the directive is configured to use
+ unlimited objects, the directive may allocate memory from the RTEMS
+ Workspace.
+
+.. Generated from spec:/rtems/region/if/ident
.. raw:: latex
- \clearpage
+ \clearpage
+
+.. index:: rtems_region_ident()
+
+.. _InterfaceRtemsRegionIdent:
+
+rtems_region_ident()
+--------------------
+
+Identifies a region by the object name.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
-.. index:: get ID of a region
-.. index:: obtain ID of a region
-.. index:: rtems_region_ident
+ rtems_status_code rtems_region_ident( rtems_name name, rtems_id *id );
-.. _rtems_region_ident:
+.. rubric:: PARAMETERS:
-REGION_IDENT - Get ID of a region
----------------------------------
+``name``
+ This parameter is the object name to look up.
-CALLING SEQUENCE:
- .. code-block:: c
+``id``
+ This parameter is the pointer to an object identifier variable. When the
+ directive call is successful, the object identifier of an object with the
+ specified name will be stored in this variable.
- rtems_status_code rtems_region_ident(
- rtems_name name,
- rtems_id *id
- );
+.. rubric:: DESCRIPTION:
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+This directive obtains a region identifier associated with the region name
+specified in ``name``.
- * - ``RTEMS_SUCCESSFUL``
- - region identified successfully
- * - ``RTEMS_INVALID_ADDRESS``
- - ``id`` is NULL
- * - ``RTEMS_INVALID_NAME``
- - region name not found
+.. rubric:: RETURN VALUES:
-DESCRIPTION:
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
- This directive obtains the region id associated with the region name to be
- acquired. If the region name is not unique, then the region id will match
- one of the regions with that name. However, this region id is not
- guaranteed to correspond to the desired region. The region id is used to
- access this region in other region manager directives.
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``id`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
-NOTES:
- This directive will not cause the running task to be preempted.
+:c:macro:`RTEMS_INVALID_NAME`
+ The ``name`` parameter was 0.
+
+:c:macro:`RTEMS_INVALID_NAME`
+ There was no object with the specified name on the local node.
+
+.. rubric:: NOTES:
+
+If the region name is not unique, then the region identifier will match the
+first region with that name in the search order. However, this region
+identifier is not guaranteed to correspond to the desired region.
+
+The objects are searched from lowest to the highest index. Only the local node
+is searched.
+
+The region identifier is used with other region related directives to access
+the region.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/region/if/delete
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_region_delete()
.. index:: delete a region
-.. index:: rtems_region_delete
-.. _rtems_region_delete:
+.. _InterfaceRtemsRegionDelete:
-REGION_DELETE - Delete a region
--------------------------------
+rtems_region_delete()
+---------------------
+
+Deletes the region.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_region_delete( rtems_id id );
-CALLING SEQUENCE:
- .. code-block:: c
+.. rubric:: PARAMETERS:
- rtems_status_code rtems_region_delete(
- rtems_id id
- );
+``id``
+ This parameter is the region identifier.
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+.. rubric:: DESCRIPTION:
- * - ``RTEMS_SUCCESSFUL``
- - region deleted successfully
- * - ``RTEMS_INVALID_ID``
- - invalid region id
- * - ``RTEMS_RESOURCE_IN_USE``
- - segments still in use
+This directive deletes the region specified by ``id``.
-DESCRIPTION:
- This directive deletes the region specified by id. The region cannot be
- deleted if any of its segments are still allocated. The RNCB for the
- deleted region is reclaimed by RTEMS.
+.. rubric:: RETURN VALUES:
-NOTES:
- This directive will obtain the allocator mutex and may cause the calling
- task to be preempted.
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
- The calling task does not have to be the task that created the region. Any
- local task that knows the region id can delete the region.
+:c:macro:`RTEMS_INVALID_ID`
+ There was no region associated with the identifier specified by ``id``.
+
+:c:macro:`RTEMS_RESOURCE_IN_USE`
+ There were segments of the region still in use.
+
+.. rubric:: NOTES:
+
+The region cannot be deleted if any of its segments are still allocated.
+
+The :term:`RNCB` for the deleted region is reclaimed by RTEMS.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive may obtain and release the object allocator mutex. This may
+ cause the calling task to be preempted.
+
+* The calling task does not have to be the task that created the object. Any
+ local task that knows the object identifier can delete the object.
+
+* Where the object class corresponding to the directive is configured to use
+ unlimited objects, the directive may free memory to the RTEMS Workspace.
+
+.. Generated from spec:/rtems/region/if/extend
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_region_extend()
.. index:: add memory to a region
.. index:: region, add memory
-.. index:: rtems_region_extend
-
-.. _rtems_region_extend:
-
-REGION_EXTEND - Add memory to a region
---------------------------------------
-
-CALLING SEQUENCE:
- .. code-block:: c
-
- rtems_status_code rtems_region_extend(
- rtems_id id,
- void *starting_address,
- uintptr_t length
- );
-
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
-
- * - ``RTEMS_SUCCESSFUL``
- - region extended successfully
- * - ``RTEMS_INVALID_ADDRESS``
- - ``starting_address`` is NULL
- * - ``RTEMS_INVALID_ID``
- - invalid region id
- * - ``RTEMS_INVALID_ADDRESS``
- - invalid address of area to add
-
-DESCRIPTION:
- This directive adds the memory area which starts at
- :c:data:`starting_address` for :c:data:`length` bytes to the region
- specified by :c:data:`id`.
-
- There are no alignment requirements for the memory area. The memory area
- must be big enough to contain some maintenance blocks. It must not overlap
- parts of the current heap memory areas. Disconnected memory areas added to
- the heap will lead to used blocks which cover the gaps. Extending with an
- inappropriate memory area will corrupt the heap resulting in undefined
- behaviour.
-
-NOTES:
- This directive will obtain the allocator mutex and may cause the calling
- task to be preempted.
-
- The calling task does not have to be the task that created the region. Any
- local task that knows the region identifier can extend the region.
+
+.. _InterfaceRtemsRegionExtend:
+
+rtems_region_extend()
+---------------------
+
+Extends the region.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_region_extend(
+ rtems_id id,
+ void *starting_address,
+ uintptr_t length
+ );
+
+.. rubric:: PARAMETERS:
+
+``id``
+ This parameter is the region identifier.
+
+``starting_address``
+ This parameter is the starting address of the memory area to extend the
+ region.
+
+``length``
+ This parameter is the length in bytes of the memory area to extend the
+ region.
+
+.. rubric:: DESCRIPTION:
+
+This directive adds the memory area which starts at ``starting_address`` for
+``length`` bytes to the region specified by ``id``.
+
+.. rubric:: RETURN VALUES:
+
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``starting_address`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+:c:macro:`RTEMS_INVALID_ID`
+ There was no region associated with the identifier specified by ``id``.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The memory area specified by ``starting_address`` and ``length`` was
+ insufficient to extend the heap.
+
+.. rubric:: NOTES:
+
+There are no alignment requirements for the memory area. The memory area must
+be big enough to contain some maintenance blocks. It must not overlap parts of
+the current heap memory areas. Disconnected memory areas added to the heap
+will lead to used blocks which cover the gaps. Extending with an inappropriate
+memory area will corrupt the heap resulting in undefined behaviour.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive may obtain and release the object allocator mutex. This may
+ cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/region/if/get-segment
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_region_get_segment()
.. index:: get segment from region
-.. index:: rtems_region_get_segment
-
-.. _rtems_region_get_segment:
-
-REGION_GET_SEGMENT - Get segment from a region
-----------------------------------------------
-
-CALLING SEQUENCE:
- .. code-block:: c
-
- rtems_status_code rtems_region_get_segment(
- rtems_id id,
- uintptr_t size,
- rtems_option option_set,
- rtems_interval timeout,
- void **segment
- );
-
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
-
- * - ``RTEMS_SUCCESSFUL``
- - segment obtained successfully
- * - ``RTEMS_INVALID_ADDRESS``
- - ``segment`` is NULL
- * - ``RTEMS_INVALID_ID``
- - invalid region id
- * - ``RTEMS_INVALID_SIZE``
- - request is for zero bytes or exceeds the size of maximum segment which is
- possible for this region
- * - ``RTEMS_UNSATISFIED``
- - segment of requested size not available
- * - ``RTEMS_TIMEOUT``
- - timed out waiting for segment
- * - ``RTEMS_OBJECT_WAS_DELETED``
- - region deleted while waiting
-
-DESCRIPTION:
- This directive obtains a variable size segment from the region specified by
- ``id``. The address of the allocated segment is returned in segment. The
- ``RTEMS_WAIT`` and ``RTEMS_NO_WAIT`` components of the options parameter
- are used to specify whether the calling tasks wish to wait for a segment to
- become available or return immediately if no segment is available. For
- either option, if a sufficiently sized segment is available, then the
- segment is successfully acquired by returning immediately with the
- ``RTEMS_SUCCESSFUL`` status code.
-
- If the calling task chooses to return immediately and a segment large
- enough is not available, then an error code indicating this fact is
- returned. If the calling task chooses to wait for the segment and a
- segment large enough is not available, then the calling task is placed on
- the region's segment wait queue and blocked. If the region was created
- with the ``RTEMS_PRIORITY`` option, then the calling task is inserted into
- the wait queue according to its priority. However, if the region was
- created with the ``RTEMS_FIFO`` option, then the calling task is placed at
- the rear of the wait queue.
-
- The timeout parameter specifies the maximum interval that a task is willing
- to wait to obtain a segment. If timeout is set to ``RTEMS_NO_TIMEOUT``,
- then the calling task will wait forever.
-
-NOTES:
- This directive will obtain the allocator mutex and may cause the calling
- task to be preempted.
-
- The actual length of the allocated segment may be larger than the requested
- size because a segment size is always a multiple of the region's page size.
-
- The following segment acquisition option constants are defined by RTEMS:
-
- .. list-table::
- :class: rtems-table
-
- * - ``RTEMS_WAIT``
- - task will wait for segment (default)
- * - ``RTEMS_NO_WAIT``
- - task should not wait
-
- A clock tick is required to support the timeout functionality of this
- directive.
+
+.. _InterfaceRtemsRegionGetSegment:
+
+rtems_region_get_segment()
+--------------------------
+
+Gets a segment from the region.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_region_get_segment(
+ rtems_id id,
+ uintptr_t size,
+ rtems_option option_set,
+ rtems_interval timeout,
+ void **segment
+ );
+
+.. rubric:: PARAMETERS:
+
+``id``
+ This parameter is the region identifier.
+
+``size``
+ This parameter is the size in bytes of the segment to allocate.
+
+``option_set``
+ This parameter is the option set.
+
+``timeout``
+ This parameter is the timeout in :term:`clock ticks <clock tick>` if the
+ :c:macro:`RTEMS_WAIT` option is set. Use :c:macro:`RTEMS_NO_TIMEOUT` to
+ wait potentially forever.
+
+``segment``
+ This parameter is the pointer to a void pointer variable. When the
+ directive call is successful, the begin address of the allocated segment
+ will be stored in this variable.
+
+.. rubric:: DESCRIPTION:
+
+This directive gets a segment from the region specified by ``id``.
+
+The **option set** specified in ``option_set`` is built through a *bitwise or*
+of the option constants described below. Not all combinations of options are
+allowed. Some options are mutually exclusive. If mutually exclusive options
+are combined, the behaviour is undefined. Options not mentioned below are not
+evaluated by this directive and have no effect. Default options can be selected
+by using the :c:macro:`RTEMS_DEFAULT_OPTIONS` constant.
+
+The calling task can **wait** or **try to get** a segment from the region
+according to the mutually exclusive :c:macro:`RTEMS_WAIT` and
+:c:macro:`RTEMS_NO_WAIT` options.
+
+* **Waiting to get** a segment from the region is the default and can be
+ emphasized through the use of the :c:macro:`RTEMS_WAIT` option. The
+ ``timeout`` parameter defines how long the calling task is willing to wait.
+ Use :c:macro:`RTEMS_NO_TIMEOUT` to wait potentially forever, otherwise set a
+ timeout interval in clock ticks.
+
+* **Trying to get** a segment from the region is selected by the
+ :c:macro:`RTEMS_NO_WAIT` option. If this option is defined, then the
+ ``timeout`` parameter is ignored. When a segment from the region cannot be
+ immediately allocated, then the :c:macro:`RTEMS_UNSATISFIED` status is
+ returned.
+
+With either :c:macro:`RTEMS_WAIT` or :c:macro:`RTEMS_NO_WAIT` if there is a
+segment of the requested size is available, then it is returned in ``segment``
+and this directive returns immediately with the :c:macro:`RTEMS_SUCCESSFUL`
+status code.
+
+If the calling task chooses to return immediately and the region has no segment
+of the requested size available, then the directive returns immediately with
+the :c:macro:`RTEMS_UNSATISFIED` status code. If the calling task chooses to
+wait for a segment, then the calling task is placed on the region wait queue
+and blocked. If the region was created with the :c:macro:`RTEMS_PRIORITY`
+option specified, then the calling task is inserted into the wait queue
+according to its priority. But, if the region was created with the
+:c:macro:`RTEMS_FIFO` option specified, then the calling task is placed at the
+rear of the wait queue.
+
+.. rubric:: RETURN VALUES:
+
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``segment`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+:c:macro:`RTEMS_INVALID_SIZE`
+ The ``size`` parameter was zero.
+
+:c:macro:`RTEMS_INVALID_ID`
+ There was no region associated with the identifier specified by ``id``.
+
+:c:macro:`RTEMS_INVALID_SIZE`
+ The ``size`` parameter exceeded the maximum segment size which is possible
+ for the region.
+
+:c:macro:`RTEMS_UNSATISFIED`
+ The region had no segment of the requested size immediately available.
+
+:c:macro:`RTEMS_TIMEOUT`
+ The timeout happened while the calling task was waiting to get a segment
+ from the region.
+
+.. rubric:: NOTES:
+
+The actual length of the allocated segment may be larger than the requested
+size because a segment size is always a multiple of the region's page size.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive may obtain and release the object allocator mutex. This may
+ cause the calling task to be preempted.
+
+* When the request cannot be immediately satisfied and the
+ :c:macro:`RTEMS_WAIT` option is set, the calling task blocks at some point
+ during the directive call.
+
+* The timeout functionality of the directive requires a :term:`clock tick`.
+
+.. Generated from spec:/rtems/region/if/return-segment
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_region_return_segment()
.. index:: return segment to region
-.. index:: rtems_region_return_segment
-.. _rtems_region_return_segment:
+.. _InterfaceRtemsRegionReturnSegment:
-REGION_RETURN_SEGMENT - Return segment to a region
---------------------------------------------------
+rtems_region_return_segment()
+-----------------------------
-CALLING SEQUENCE:
- .. code-block:: c
+Returns the segment to the region.
- rtems_status_code rtems_region_return_segment(
- rtems_id id,
- void *segment
- );
+.. rubric:: CALLING SEQUENCE:
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+.. code-block:: c
- * - ``RTEMS_SUCCESSFUL``
- - segment returned successfully
- * - ``RTEMS_INVALID_ADDRESS``
- - ``segment`` is NULL
- * - ``RTEMS_INVALID_ID``
- - invalid region id
- * - ``RTEMS_INVALID_ADDRESS``
- - segment address not in region
+ rtems_status_code rtems_region_return_segment( rtems_id id, void *segment );
-DESCRIPTION:
- This directive returns the segment specified by segment to the region
- specified by id. The returned segment is merged with its neighbors to form
- the largest possible segment. The first task on the wait queue is examined
- to determine if its segment request can now be satisfied. If so, it is
- given a segment and unblocked. This process is repeated until the first
- task's segment request cannot be satisfied.
+.. rubric:: PARAMETERS:
-NOTES:
- This directive will cause the calling task to be preempted if one or more
- local tasks are waiting for a segment and the following conditions exist:
+``id``
+ This parameter is the region identifier.
- - a waiting task has a higher priority than the calling task
+``segment``
+ This parameter is the begin address of the segment to return.
- - the size of the segment required by the waiting task is less than or
- equal to the size of the segment returned.
+.. rubric:: DESCRIPTION:
-.. raw:: latex
+This directive returns the segment specified by ``segment`` to the region
+specified by ``id``. The returned segment is merged with its neighbors to form
+the largest possible segment. The first task on the wait queue is examined to
+determine if its segment request can now be satisfied. If so, it is given a
+segment and unblocked. This process is repeated until the first task's segment
+request cannot be satisfied.
- \clearpage
+.. rubric:: RETURN VALUES:
-.. index:: get size of segment
-.. index:: rtems_region_get_segment_size
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_ID`
+ There was no region associated with the identifier specified by ``id``.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The segment was not within the region.
-.. _rtems_region_get_segment_size:
+.. rubric:: NOTES:
-REGION_GET_SEGMENT_SIZE - Obtain size of a segment
---------------------------------------------------
+This directive will cause the calling task to be preempted if one or more local
+tasks are waiting for a segment and the following conditions exist:
-CALLING SEQUENCE:
- .. code-block:: c
+* A waiting task has a higher priority than the calling task.
- rtems_status_code rtems_region_get_segment_size(
- rtems_id id,
- void *segment,
- uintptr_t *size
- );
+* The size of the segment required by the waiting task is less than or equal to
+ the size of the segment returned.
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+.. rubric:: CONSTRAINTS:
- * - ``RTEMS_SUCCESSFUL``
- - segment obtained successfully
- * - ``RTEMS_INVALID_ADDRESS``
- - ``segment`` is NULL
- * - ``RTEMS_INVALID_ADDRESS``
- - ``size`` is NULL
- * - ``RTEMS_INVALID_ID``
- - invalid region id
- * - ``RTEMS_INVALID_ADDRESS``
- - segment address not in region
+The following constraints apply to this directive:
-DESCRIPTION:
- This directive obtains the size in bytes of the specified segment.
+* The directive may be called from within device driver initialization context.
-NOTES:
- The actual length of the allocated segment may be larger than the requested
- size because a segment size is always a multiple of the region's page size.
+* The directive may be called from within task context.
+
+* The directive may unblock a task. This may cause the calling task to be
+ preempted.
+
+* The directive may obtain and release the object allocator mutex. This may
+ cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/region/if/resize-segment
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_region_resize_segment()
.. index:: resize segment
-.. index:: rtems_region_resize_segment
-
-.. _rtems_region_resize_segment:
-
-REGION_RESIZE_SEGMENT - Change size of a segment
-------------------------------------------------
-
-CALLING SEQUENCE:
- .. code-block:: c
-
- rtems_status_code rtems_region_resize_segment(
- rtems_id id,
- void *segment,
- uintptr_t new_size,
- uintptr_t *old_size
- );
-
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
-
- * - ``RTEMS_SUCCESSFUL``
- - segment obtained successfully
- * - ``RTEMS_INVALID_ADDRESS``
- - ``segment`` is NULL
- * - ``RTEMS_INVALID_ADDRESS``
- - ``old_size`` is NULL
- * - ``RTEMS_INVALID_ID``
- - invalid region id
- * - ``RTEMS_INVALID_ADDRESS``
- - segment address not in region
- * - ``RTEMS_UNSATISFIED``
- - unable to make segment larger
-
-DESCRIPTION:
- This directive is used to increase or decrease the size of a segment. When
- increasing the size of a segment, it is possible that there is not memory
- available contiguous to the segment. In this case, the request is
- unsatisfied.
-
-NOTES:
- This directive will obtain the allocator mutex and may cause the calling
- task to be preempted.
-
- If an attempt to increase the size of a segment fails, then the application
- may want to allocate a new segment of the desired size, copy the contents
- of the original segment to the new, larger segment and then return the
- original segment.
+
+.. _InterfaceRtemsRegionResizeSegment:
+
+rtems_region_resize_segment()
+-----------------------------
+
+Changes the size of the segment.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_region_resize_segment(
+ rtems_id id,
+ void *segment,
+ uintptr_t size,
+ uintptr_t *old_size
+ );
+
+.. rubric:: PARAMETERS:
+
+``id``
+ This parameter is the region identifier.
+
+``segment``
+ This parameter is the begin address of the segment to resize.
+
+``size``
+ This parameter is the requested new size of the segment.
+
+``old_size``
+ This parameter is the pointer to an `uintptr_t
+ <https://en.cppreference.com/w/c/types/integer>`_ variable. When the
+ directive call is successful, the old size of the segment will be stored in
+ this variable.
+
+.. rubric:: DESCRIPTION:
+
+This directive is used to increase or decrease the size of the ``segment`` of
+the region specified by ``id``. When increasing the size of a segment, it is
+possible that there is no memory available contiguous to the segment. In this
+case, the request is unsatisfied.
+
+.. rubric:: RETURN VALUES:
+
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``old_size`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+:c:macro:`RTEMS_INVALID_ID`
+ There was no region associated with the identifier specified by ``id``.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The segment was not within the region.
+
+:c:macro:`RTEMS_UNSATISFIED`
+ The region was unable to resize the segment.
+
+.. rubric:: NOTES:
+
+If an attempt to increase the size of a segment fails, then the application may
+want to allocate a new segment of the desired size, copy the contents of the
+original segment to the new, larger segment and then return the original
+segment.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive may obtain and release the object allocator mutex. This may
+ cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/region/if/get-information
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_region_get_information()
.. index:: obtain region information
-.. index:: rtems_region_get_information
-.. _rtems_region_get_information:
+.. _InterfaceRtemsRegionGetInformation:
+
+rtems_region_get_information()
+------------------------------
+
+Gets the region information.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_region_get_information(
+ rtems_id id,
+ Heap_Information_block *the_info
+ );
+
+.. rubric:: PARAMETERS:
+
+``id``
+ This parameter is the region identifier.
+
+``the_info``
+ This parameter is the pointer to a Heap_Information_block variable. When
+ the directive call is successful, the information of the region will be
+ stored in this variable.
+
+.. rubric:: DESCRIPTION:
+
+This directive is used to obtain information about the used and free memory in
+the region specified by ``id``. This is a snapshot at the time of the call. The
+information will be returned in the structure pointed to by ``the_info``.
+
+.. rubric:: RETURN VALUES:
-REGION_GET_INFORMATION - Get region information
------------------------------------------------
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
-CALLING SEQUENCE:
- .. code-block:: c
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``the_info`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
- rtems_status_code rtems_region_get_information(
- rtems_id id,
- Heap_Information_block *the_info
- );
+:c:macro:`RTEMS_INVALID_ID`
+ There was no region associated with the identifier specified by ``id``.
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+.. rubric:: NOTES:
- * - ``RTEMS_SUCCESSFUL``
- - information obtained successfully
- * - ``RTEMS_INVALID_ADDRESS``
- - ``the_info`` is NULL
- * - ``RTEMS_INVALID_ID``
- - invalid region id
+This is primarily intended as a mechanism to obtain a diagnostic information.
+This method forms am O(n) scan of the free and an O(n) scan of the used blocks
+in the region to calculate the information provided. Given that the execution
+time is driven by the number of used and free blocks, it can take a
+non-deterministic time to execute.
-DESCRIPTION:
- This directive is used to obtain information about the used and free memory
- in the region specified by ``id``. This is a snapshot at the time
- of the call. The information will be returned in the structure pointed to
- by ``the_info``.
+To get only the free information of the region use
+:ref:`InterfaceRtemsRegionGetFreeInformation`.
-NOTES:
- This directive will obtain the allocator mutex and may cause the calling
- task to be preempted.
+.. rubric:: CONSTRAINTS:
- This is primarily intended as a mechanism to obtain a diagnostic information.
- This method forms am O(n) scan of the free and an O(n) scan of the
- used blocks in the region to calculate the information provided. Given that
- the execution time is driven by the number of used and free blocks, it can
- take a non-deterministic time to execute.
+The following constraints apply to this directive:
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive may obtain and release the object allocator mutex. This may
+ cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/region/if/get-free-information
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_region_get_free_information()
.. index:: obtain region information on free blocks
-.. index:: rtems_region_get_free_information
-
-.. _rtems_region_get_free_information:
-
-REGION_GET_FREE_INFORMATION - Get region free information
----------------------------------------------------------
-
-CALLING SEQUENCE:
- .. code-block:: c
-
- rtems_status_code rtems_region_get_free_information(
- rtems_id id,
- Heap_Information_block *the_info
- );
-
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
-
- * - ``RTEMS_SUCCESSFUL``
- - information obtained successfully
- * - ``RTEMS_INVALID_ADDRESS``
- - ``the_info`` is NULL
- * - ``RTEMS_INVALID_ID``
- - invalid region id
-
-DESCRIPTION:
- This directive is used to obtain information about the free memory
- in the region specified by ``id``. This is a snapshot at the time
- of the call. The information will be returned in the structure pointed to
- by ``the_info``.
-
-NOTES:
- This directive will obtain the allocator mutex and may cause the calling
- task to be preempted.
-
- This uses the same structure to return information as the
- ``rtems_region_get_information`` directive but does not fill in the
- used information.
-
- This is primarily intended as a mechanism to obtain a diagnostic information.
- This method forms am O(n) scan of the free in the region to calculate
- the information provided. Given that the execution time is driven by
- the number of used and free blocks, it can take a non-deterministic
- time to execute. Typically, there are many used blocks and a much smaller
- number of used blocks making a call to this directive less expensive than
- a call to ``rtems_region_get_information``.
+
+.. _InterfaceRtemsRegionGetFreeInformation:
+
+rtems_region_get_free_information()
+-----------------------------------
+
+Gets the region free information.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_region_get_free_information(
+ rtems_id id,
+ Heap_Information_block *the_info
+ );
+
+.. rubric:: PARAMETERS:
+
+``id``
+ This parameter is the region identifier.
+
+``the_info``
+ This parameter is the pointer to a Heap_Information_block variable. When
+ the directive call is successful, the free information of the region will
+ be stored in this variable.
+
+.. rubric:: DESCRIPTION:
+
+This directive is used to obtain information about the free memory in the
+region specified by ``id``. This is a snapshot at the time of the call. The
+information will be returned in the structure pointed to by ``the_info``.
+
+.. rubric:: RETURN VALUES:
+
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``the_info`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+:c:macro:`RTEMS_INVALID_ID`
+ There was no region associated with the identifier specified by ``id``.
+
+.. rubric:: NOTES:
+
+This directive uses the same structure to return information as the
+:ref:`InterfaceRtemsRegionGetInformation` directive but does not fill in the
+used information.
+
+This is primarily intended as a mechanism to obtain a diagnostic information.
+This method forms am O(n) scan of the free in the region to calculate the
+information provided. Given that the execution time is driven by the number of
+used and free blocks, it can take a non-deterministic time to execute.
+Typically, there are many used blocks and a much smaller number of used blocks
+making a call to this directive less expensive than a call to
+:ref:`InterfaceRtemsRegionGetInformation`.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive may obtain and release the object allocator mutex. This may
+ cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/region/if/get-segment-size
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: rtems_region_get_segment_size()
+.. index:: get size of segment
+
+.. _InterfaceRtemsRegionGetSegmentSize:
+
+rtems_region_get_segment_size()
+-------------------------------
+
+Gets the size of the region segment.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_region_get_segment_size(
+ rtems_id id,
+ void *segment,
+ uintptr_t *size
+ );
+
+.. rubric:: PARAMETERS:
+
+``id``
+ This parameter is the region identifier.
+
+``segment``
+ This parameter is the begin address of the segment.
+
+``size``
+ This parameter is the pointer to a `uintptr_t
+ <https://en.cppreference.com/w/c/types/integer>`_ variable. When the
+ directive call is successful, the size of the segment in bytes will be
+ stored in this variable.
+
+.. rubric:: DESCRIPTION:
+
+This directive obtains the size in bytes of the segment specified by
+``segment`` of the region specified by ``id`` in ``size``.
+
+.. rubric:: RETURN VALUES:
+
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``segment`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``size`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+:c:macro:`RTEMS_INVALID_ID`
+ There was no region associated with the identifier specified by ``id``.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The segment was not within the region.
+
+.. rubric:: NOTES:
+
+The actual length of the allocated segment may be larger than the requested
+size because a segment size is always a multiple of the region's page size.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive may obtain and release the object allocator mutex. This may
+ cause the calling task to be preempted.
diff --git a/c-user/region/introduction.rst b/c-user/region/introduction.rst
index 418e397..8075a84 100644
--- a/c-user/region/introduction.rst
+++ b/c-user/region/introduction.rst
@@ -1,29 +1,63 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
+.. Copyright (C) 2020, 2021 embedded brains GmbH (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:/rtems/region/if/group
+
+.. _RegionManagerIntroduction:
+
Introduction
============
-The region manager provides facilities to dynamically allocate memory in
-variable sized units. The directives provided by the region manager are:
+.. The following list was generated from:
+.. spec:/rtems/region/if/create
+.. spec:/rtems/region/if/ident
+.. spec:/rtems/region/if/delete
+.. spec:/rtems/region/if/extend
+.. spec:/rtems/region/if/get-segment
+.. spec:/rtems/region/if/return-segment
+.. spec:/rtems/region/if/resize-segment
+.. spec:/rtems/region/if/get-information
+.. spec:/rtems/region/if/get-free-information
+.. spec:/rtems/region/if/get-segment-size
+
+The Region Manager provides facilities to dynamically allocate memory in
+variable sized units. The directives provided by the Region Manager are:
-- :ref:`rtems_region_create`
+* :ref:`InterfaceRtemsRegionCreate` - Creates a region.
-- :ref:`rtems_region_ident`
+* :ref:`InterfaceRtemsRegionIdent` - Identifies a region by the object name.
-- :ref:`rtems_region_delete`
+* :ref:`InterfaceRtemsRegionDelete` - Deletes the region.
-- :ref:`rtems_region_extend`
+* :ref:`InterfaceRtemsRegionExtend` - Extends the region.
-- :ref:`rtems_region_get_segment`
+* :ref:`InterfaceRtemsRegionGetSegment` - Gets a segment from the region.
-- :ref:`rtems_region_return_segment`
+* :ref:`InterfaceRtemsRegionReturnSegment` - Returns the segment to the region.
-- :ref:`rtems_region_get_segment_size`
+* :ref:`InterfaceRtemsRegionResizeSegment` - Changes the size of the segment.
-- :ref:`rtems_region_resize_segment`
+* :ref:`InterfaceRtemsRegionGetInformation` - Gets the region information.
-- :ref:`rtems_region_get_information`
+* :ref:`InterfaceRtemsRegionGetFreeInformation` - Gets the region free
+ information.
-- :ref:`rtems_region_get_free_information`
+* :ref:`InterfaceRtemsRegionGetSegmentSize` - Gets the size of the region
+ segment.
diff --git a/c-user/scheduling-concepts/directives.rst b/c-user/scheduling-concepts/directives.rst
index 5b1246f..4785457 100644
--- a/c-user/scheduling-concepts/directives.rst
+++ b/c-user/scheduling-concepts/directives.rst
@@ -1,424 +1,705 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
-.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+.. Copyright (C) 2013, 2021 embedded brains GmbH (http://www.embedded-brains.de)
+.. Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR)
+
+.. This file is part of the RTEMS quality process and was automatically
+.. generated. If you find something that needs to be fixed or
+.. worded better please post a report or patch to an RTEMS mailing list
+.. or raise a bug report:
+..
+.. https://www.rtems.org/bugs.html
+..
+.. For information on updating and regenerating please refer to the How-To
+.. section in the Software Requirements Engineering chapter of the
+.. RTEMS Software Engineering manual. The manual is provided as a part of
+.. a release. For development sources please refer to the online
+.. documentation at:
+..
+.. https://docs.rtems.org
+
+.. _SchedulerManagerDirectives:
Directives
==========
-This section details the scheduler manager. A subsection is dedicated to each
-of these services and describes the calling sequence, related constants, usage,
-and status codes.
+This section details the directives of the Scheduler Manager. A subsection is
+dedicated to each of this manager's directives and lists the calling sequence,
+parameters, description, return values, and notes of the directive.
+
+.. Generated from spec:/rtems/scheduler/if/ident
.. raw:: latex
- \clearpage
+ \clearpage
-.. _rtems_scheduler_ident:
+.. index:: rtems_scheduler_ident()
-SCHEDULER_IDENT - Get ID of a scheduler
----------------------------------------
+.. _InterfaceRtemsSchedulerIdent:
+
+rtems_scheduler_ident()
+-----------------------
+
+Identifies a scheduler by the object name.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_scheduler_ident( rtems_name name, rtems_id *id );
+
+.. rubric:: PARAMETERS:
+
+``name``
+ This parameter is the scheduler name to look up.
+
+``id``
+ This parameter is the pointer to an object identifier variable. When the
+ directive call is successful, the identifier of the scheduler will be
+ stored in this variable.
-CALLING SEQUENCE:
- .. code-block:: c
+.. rubric:: DESCRIPTION:
- rtems_status_code rtems_scheduler_ident(
- rtems_name name,
- rtems_id *id
- );
+This directive obtains a scheduler identifier associated with the scheduler
+name specified in ``name``.
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+.. rubric:: RETURN VALUES:
- * - ``RTEMS_SUCCESSFUL``
- - Successful operation.
- * - ``RTEMS_INVALID_ADDRESS``
- - The ``id`` parameter is ``NULL``.
- * - ``RTEMS_INVALID_NAME``
- - Invalid scheduler name.
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
-DESCRIPTION:
- Identifies a scheduler by its name. The scheduler name is determined by
- the scheduler configuration. See :ref:`ConfigurationSchedulerTable`
- and :ref:`CONFIGURE_SCHEDULER_NAME`.
+:c:macro:`RTEMS_INVALID_NAME`
+ There was no scheduler associated with the name.
-NOTES:
- None.
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``id`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+.. rubric:: NOTES:
+
+The scheduler name is determined by the scheduler configuration.
+
+The scheduler identifier is used with other scheduler related directives to
+access the scheduler.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/scheduler/if/ident-by-processor
.. raw:: latex
- \clearpage
+ \clearpage
+
+.. index:: rtems_scheduler_ident_by_processor()
+
+.. _InterfaceRtemsSchedulerIdentByProcessor:
-.. _rtems_scheduler_ident_by_processor:
+rtems_scheduler_ident_by_processor()
+------------------------------------
-SCHEDULER_IDENT_BY_PROCESSOR - Get ID of a scheduler by processor
------------------------------------------------------------------
+Identifies a scheduler by the processor index.
-CALLING SEQUENCE:
- .. code-block:: c
+.. rubric:: CALLING SEQUENCE:
- rtems_status_code rtems_scheduler_ident_by_processor(
- uint32_t cpu_index,
- rtems_id *id
- );
+.. code-block:: c
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+ rtems_status_code rtems_scheduler_ident_by_processor(
+ uint32_t cpu_index,
+ rtems_id *id
+ );
- * - ``RTEMS_SUCCESSFUL``
- - Successful operation.
- * - ``RTEMS_INVALID_ADDRESS``
- - The ``id`` parameter is ``NULL``.
- * - ``RTEMS_INVALID_NAME``
- - Invalid processor index.
- * - ``RTEMS_INCORRECT_STATE``
- - The processor index is valid, however, this processor is not owned by
- a scheduler.
+.. rubric:: PARAMETERS:
-DESCRIPTION:
- Identifies a scheduler by a processor.
+``cpu_index``
+ This parameter is the processor index to identify the scheduler.
-NOTES:
- None.
+``id``
+ This parameter is the pointer to an object identifier variable. When the
+ directive call is successful, the identifier of the scheduler will be
+ stored in this variable.
+
+.. rubric:: RETURN VALUES:
+
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``id`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+:c:macro:`RTEMS_INVALID_NAME`
+ The processor index was invalid.
+
+:c:macro:`RTEMS_INCORRECT_STATE`
+ The processor index was valid, however, the corresponding processor was not
+ owned by a scheduler.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/scheduler/if/ident-by-processor-set
.. raw:: latex
- \clearpage
+ \clearpage
+
+.. index:: rtems_scheduler_ident_by_processor_set()
+
+.. _InterfaceRtemsSchedulerIdentByProcessorSet:
+
+rtems_scheduler_ident_by_processor_set()
+----------------------------------------
+
+Identifies a scheduler by the processor set.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_scheduler_ident_by_processor_set(
+ size_t cpusetsize,
+ const cpu_set_t *cpuset,
+ rtems_id *id
+ );
+
+.. rubric:: PARAMETERS:
+
+``cpusetsize``
+ This parameter is the size of the referenced processor set variable in
+ bytes. This value shall be positive.
+
+``cpuset``
+ This parameter is the pointer to a processor set variable. The referenced
+ processor set will be used to identify the scheduler.
-.. _rtems_scheduler_ident_by_processor_set:
+``id``
+ This parameter is the pointer to an object identifier variable. When the
+ directive call is successful, the identifier of the scheduler will be
+ stored in this variable.
-SCHEDULER_IDENT_BY_PROCESSOR_SET - Get ID of a scheduler by processor set
--------------------------------------------------------------------------
+.. rubric:: DESCRIPTION:
-CALLING SEQUENCE:
- .. code-block:: c
+The scheduler is selected according to the highest numbered online processor in
+the specified processor set.
- rtems_status_code rtems_scheduler_ident_by_processor_set(
- size_t cpusetsize,
- const cpu_set_t *cpuset,
- rtems_id *id
- );
+.. rubric:: RETURN VALUES:
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
- * - ``RTEMS_SUCCESSFUL``
- - Successful operation.
- * - ``RTEMS_INVALID_ADDRESS``
- - The ``id`` parameter is ``NULL``.
- * - ``RTEMS_INVALID_SIZE``
- - Invalid processor set size.
- * - ``RTEMS_INVALID_NAME``
- - The processor set contains no online processor.
- * - ``RTEMS_INCORRECT_STATE``
- - The processor set is valid, however, the highest numbered online
- processor in the specified processor set is not owned by a scheduler.
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``id`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
-DESCRIPTION:
- Identifies a scheduler by a processor set. The scheduler is selected
- according to the highest numbered online processor in the specified
- processor set.
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``cpuset`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
-NOTES:
- None.
+:c:macro:`RTEMS_INVALID_SIZE`
+ The processor set size was invalid.
+
+:c:macro:`RTEMS_INVALID_NAME`
+ The processor set contained no online processor.
+
+:c:macro:`RTEMS_INCORRECT_STATE`
+ The processor set was valid, however, the highest numbered online processor
+ in the processor set was not owned by a scheduler.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/scheduler/if/get-maximum-priority
.. raw:: latex
- \clearpage
+ \clearpage
+
+.. index:: rtems_scheduler_get_maximum_priority()
+
+.. _InterfaceRtemsSchedulerGetMaximumPriority:
+
+rtems_scheduler_get_maximum_priority()
+--------------------------------------
-.. _rtems_scheduler_get_maximum_priority:
+Gets the maximum task priority of the scheduler.
-SCHEDULER_GET_MAXIMUM_PRIORITY - Get maximum task priority of a scheduler
--------------------------------------------------------------------------
+.. rubric:: CALLING SEQUENCE:
-CALLING SEQUENCE:
- .. code-block:: c
+.. code-block:: c
- rtems_status_code rtems_scheduler_get_maximum_priority(
- rtems_id scheduler_id,
- rtems_task_priority *priority
- );
+ rtems_status_code rtems_scheduler_get_maximum_priority(
+ rtems_id scheduler_id,
+ rtems_task_priority *priority
+ );
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+.. rubric:: PARAMETERS:
- * - ``RTEMS_SUCCESSFUL``
- - Successful operation.
- * - ``RTEMS_INVALID_ID``
- - Invalid scheduler instance identifier.
- * - ``RTEMS_INVALID_ADDRESS``
- - The ``priority`` parameter is ``NULL``.
+``scheduler_id``
+ This parameter is the scheduler identifier.
-DESCRIPTION:
- Returns the maximum task priority of the specified scheduler instance in
- ``priority``.
+``priority``
+ This parameter is the pointer to a task priority variable. The maximum
+ priority of the scheduler will be stored in this variable, if the operation
+ is successful.
-NOTES:
- None.
+.. rubric:: RETURN VALUES:
+
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_ID`
+ There was no scheduler associated with the identifier specified by
+ ``scheduler_id``.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``priority`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/scheduler/if/map-priority-to-posix
.. raw:: latex
- \clearpage
+ \clearpage
-.. _rtems_scheduler_map_priority_to_posix:
+.. index:: rtems_scheduler_map_priority_to_posix()
-SCHEDULER_MAP_PRIORITY_TO_POSIX - Map task priority to POSIX thread prority
----------------------------------------------------------------------------
+.. _InterfaceRtemsSchedulerMapPriorityToPosix:
+
+rtems_scheduler_map_priority_to_posix()
+---------------------------------------
-CALLING SEQUENCE:
- .. code-block:: c
+Maps a Classic API task priority to the corresponding POSIX thread priority.
- rtems_status_code rtems_scheduler_map_priority_to_posix(
- rtems_id scheduler_id,
- rtems_task_priority priority,
- int *posix_priority
- );
+.. rubric:: CALLING SEQUENCE:
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+.. code-block:: c
- * - ``RTEMS_SUCCESSFUL``
- - Successful operation.
- * - ``RTEMS_INVALID_ADDRESS``
- - The ``posix_priority`` parameter is ``NULL``.
- * - ``RTEMS_INVALID_ID``
- - Invalid scheduler instance identifier.
- * - ``RTEMS_INVALID_PRIORITY``
- - Invalid task priority.
+ rtems_status_code rtems_scheduler_map_priority_to_posix(
+ rtems_id scheduler_id,
+ rtems_task_priority priority,
+ int *posix_priority
+ );
-DESCRIPTION:
- Maps a task priority to the corresponding POSIX thread priority.
+.. rubric:: PARAMETERS:
-NOTES:
- None.
+``scheduler_id``
+ This parameter is the scheduler identifier.
+
+``priority``
+ This parameter is the Classic API task priority to map.
+
+``posix_priority``
+ This parameter is the pointer to a POSIX thread priority variable. When
+ the directive call is successful, the POSIX thread priority value
+ corresponding to the specified Classic API task priority value will be
+ stored in this variable.
+
+.. rubric:: RETURN VALUES:
+
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``posix_priority`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+:c:macro:`RTEMS_INVALID_ID`
+ There was no scheduler associated with the identifier specified by
+ ``scheduler_id``.
+
+:c:macro:`RTEMS_INVALID_PRIORITY`
+ The Classic API task priority was invalid.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/scheduler/if/map-priority-from-posix
.. raw:: latex
- \clearpage
+ \clearpage
+
+.. index:: rtems_scheduler_map_priority_from_posix()
+
+.. _InterfaceRtemsSchedulerMapPriorityFromPosix:
+
+rtems_scheduler_map_priority_from_posix()
+-----------------------------------------
+
+Maps a POSIX thread priority to the corresponding Classic API task priority.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_scheduler_map_priority_from_posix(
+ rtems_id scheduler_id,
+ int posix_priority,
+ rtems_task_priority *priority
+ );
-.. _rtems_scheduler_map_priority_from_posix:
+.. rubric:: PARAMETERS:
-SCHEDULER_MAP_PRIORITY_FROM_POSIX - Map POSIX thread prority to task priority
------------------------------------------------------------------------------
+``scheduler_id``
+ This parameter is the scheduler identifier.
-CALLING SEQUENCE:
- .. code-block:: c
+``posix_priority``
+ This parameter is the POSIX thread priority to map.
- rtems_status_code rtems_scheduler_map_priority_from_posix(
- rtems_id scheduler_id,
- int posix_priority,
- rtems_task_priority *priority
- );
+``priority``
+ This parameter is the pointer to a Classic API task priority variable.
+ 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 variable.
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+.. rubric:: RETURN VALUES:
- * - ``RTEMS_SUCCESSFUL``
- - Successful operation.
- * - ``RTEMS_INVALID_ADDRESS``
- - The ``priority`` parameter is ``NULL``.
- * - ``RTEMS_INVALID_ID``
- - Invalid scheduler instance identifier.
- * - ``RTEMS_INVALID_PRIORITY``
- - Invalid POSIX thread priority.
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
-DESCRIPTION:
- Maps a POSIX thread priority to the corresponding task priority.
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``priority`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
-NOTES:
- None.
+:c:macro:`RTEMS_INVALID_ID`
+ There was no scheduler associated with the identifier specified by
+ ``scheduler_id``.
+
+:c:macro:`RTEMS_INVALID_PRIORITY`
+ The POSIX thread priority was invalid.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/scheduler/if/get-processor
.. raw:: latex
- \clearpage
+ \clearpage
+
+.. index:: rtems_scheduler_get_processor()
+
+.. _InterfaceRtemsSchedulerGetProcessor:
+
+rtems_scheduler_get_processor()
+-------------------------------
+
+Returns the index of the current processor.
-.. _rtems_scheduler_get_processor:
+.. rubric:: CALLING SEQUENCE:
-SCHEDULER_GET_PROCESSOR - Get current processor index
------------------------------------------------------
+.. code-block:: c
-CALLING SEQUENCE:
- .. code-block:: c
+ uint32_t rtems_scheduler_get_processor( void );
- uint32_t rtems_scheduler_get_processor( void );
+.. rubric:: DESCRIPTION:
-DIRECTIVE STATUS CODES:
- This directive returns the index of the current processor.
+Where the system was built with SMP support disabled, this directive evaluates
+to a compile time constant of zero.
-DESCRIPTION:
- In uniprocessor configurations, a value of zero will be returned.
+Where the system was built with SMP support enabled, this directive returns the
+index of the current processor. The set of processor indices is the range of
+integers starting with zero up to
+:ref:`InterfaceRtemsSchedulerGetProcessorMaximum` minus one.
- In SMP configurations, an architecture specific method is used to obtain the
- index of the current processor in the system. The set of processor indices
- is the range of integers starting with zero up to the processor count minus
- one.
+.. rubric:: RETURN VALUES:
- Outside of sections with disabled thread dispatching the current processor
- index may change after every instruction since the thread may migrate from
- one processor to another. Sections with disabled interrupts are sections
- with thread dispatching disabled.
+Returns the index of the current processor.
-NOTES:
- None.
+.. rubric:: NOTES:
+
+Outside of sections with disabled thread dispatching the current processor
+index may change after every instruction since the thread may migrate from one
+processor to another. Sections with disabled interrupts are sections with
+thread dispatching disabled.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/scheduler/if/get-processor-maximum
.. raw:: latex
- \clearpage
+ \clearpage
+
+.. index:: rtems_scheduler_get_processor_maximum()
+
+.. _InterfaceRtemsSchedulerGetProcessorMaximum:
+
+rtems_scheduler_get_processor_maximum()
+---------------------------------------
+
+Returns the processor maximum supported by the system.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ uint32_t rtems_scheduler_get_processor_maximum( void );
+
+.. rubric:: DESCRIPTION:
-.. _rtems_scheduler_get_processor_maximum:
+Where the system was built with SMP support disabled, this directive evaluates
+to a compile time constant of one.
-SCHEDULER_GET_PROCESSOR_MAXIMUM - Get processor maximum
--------------------------------------------------------
+Where the system was built with SMP support enabled, this directive returns the
+minimum of the processors (physically or virtually) available at the
+:term:`target` and the configured processor maximum (see
+:ref:`CONFIGURE_MAXIMUM_PROCESSORS`). Not all processors in the range from
+processor index zero to the last processor index (which is the processor
+maximum minus one) may be configured to be used by a scheduler or may be online
+(online processors have a scheduler assigned).
-CALLING SEQUENCE:
- .. code-block:: c
+.. rubric:: RETURN VALUES:
- uint32_t rtems_scheduler_get_processor_maximum( void );
+Returns the processor maximum supported by the system.
-DIRECTIVE STATUS CODES:
- This directive returns the processor maximum supported by the system.
+.. rubric:: CONSTRAINTS:
-DESCRIPTION:
- In uniprocessor configurations, a value of one will be returned.
+The following constraints apply to this directive:
- In SMP configurations, this directive returns the minimum of the processors
- (physically or virtually) available by the platform and the configured
- processor maximum. Not all processors in the range from processor index
- zero to the last processor index (which is the processor maximum minus one)
- may be configured to be used by a scheduler or online (online processors
- have a scheduler assigned).
+* The directive may be called from within any runtime context.
-NOTES:
- None.
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/scheduler/if/get-processor-set
.. raw:: latex
- \clearpage
+ \clearpage
+
+.. index:: rtems_scheduler_get_processor_set()
+
+.. _InterfaceRtemsSchedulerGetProcessorSet:
+
+rtems_scheduler_get_processor_set()
+-----------------------------------
+
+Gets the set of processors owned by the scheduler.
-.. _rtems_scheduler_get_processor_set:
+.. rubric:: CALLING SEQUENCE:
-SCHEDULER_GET_PROCESSOR_SET - Get processor set of a scheduler
---------------------------------------------------------------
+.. code-block:: c
-CALLING SEQUENCE:
- .. code-block:: c
+ rtems_status_code rtems_scheduler_get_processor_set(
+ rtems_id scheduler_id,
+ size_t cpusetsize,
+ cpu_set_t *cpuset
+ );
- rtems_status_code rtems_scheduler_get_processor_set(
- rtems_id scheduler_id,
- size_t cpusetsize,
- cpu_set_t *cpuset
- );
+.. rubric:: PARAMETERS:
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+``scheduler_id``
+ This parameter is the scheduler identifier.
- * - ``RTEMS_SUCCESSFUL``
- - Successful operation.
- * - ``RTEMS_INVALID_ID``
- - Invalid scheduler instance identifier.
- * - ``RTEMS_INVALID_ADDRESS``
- - The ``cpuset`` parameter is ``NULL``.
- * - ``RTEMS_INVALID_NUMBER``
- - The processor set buffer is too small for the set of processors owned
- by the scheduler instance.
+``cpusetsize``
+ This parameter is the size of the referenced processor set variable in
+ bytes.
-DESCRIPTION:
- Returns the processor set owned by the scheduler instance in ``cpuset``. A
- set bit in the processor set means that this processor is owned by the
- scheduler instance and a cleared bit means the opposite.
+``cpuset``
+ This parameter is the pointer to a processor set variable. When the
+ directive call is successful, the processor set of the scheduler will be
+ stored in this variable. A set bit in the processor set means that the
+ corresponding processor is owned by the scheduler, otherwise the bit is
+ cleared.
-NOTES:
- None.
+.. rubric:: RETURN VALUES:
+
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``cpuset`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+:c:macro:`RTEMS_INVALID_ID`
+ There was no scheduler associated with the identifier specified by
+ ``scheduler_id``.
+
+:c:macro:`RTEMS_INVALID_SIZE`
+ The provided processor set was too small for the set of processors owned by
+ the scheduler.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/scheduler/if/add-processor
.. raw:: latex
- \clearpage
+ \clearpage
+
+.. index:: rtems_scheduler_add_processor()
-.. _rtems_scheduler_add_processor:
+.. _InterfaceRtemsSchedulerAddProcessor:
-SCHEDULER_ADD_PROCESSOR - Add processor to a scheduler
-------------------------------------------------------
+rtems_scheduler_add_processor()
+-------------------------------
-CALLING SEQUENCE:
- .. code-block:: c
+Adds the processor to the set of processors owned by the scheduler.
- rtems_status_code rtems_scheduler_add_processor(
- rtems_id scheduler_id,
- uint32_t cpu_index
- );
+.. rubric:: CALLING SEQUENCE:
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+.. code-block:: c
- * - ``RTEMS_SUCCESSFUL``
- - Successful operation.
- * - ``RTEMS_INVALID_ID``
- - Invalid scheduler instance identifier.
- * - ``RTEMS_NOT_CONFIGURED``
- - The processor is not configured to be used by the application.
- * - ``RTEMS_INCORRECT_STATE``
- - The processor is configured to be used by the application, however, it
- is not online.
- * - ``RTEMS_RESOURCE_IN_USE``
- - The processor is already assigned to a scheduler instance.
+ rtems_status_code rtems_scheduler_add_processor(
+ rtems_id scheduler_id,
+ uint32_t cpu_index
+ );
-DESCRIPTION:
- Adds a processor to the set of processors owned by the specified scheduler
- instance.
+.. rubric:: PARAMETERS:
-NOTES:
- Must be called from task context. This operation obtains and releases the
- objects allocator lock.
+``scheduler_id``
+ This parameter is the scheduler identifier.
+
+``cpu_index``
+ This parameter is the index of the processor to add.
+
+.. rubric:: DESCRIPTION:
+
+This directive adds the processor specified by the ``cpu_index`` to the
+scheduler specified by ``scheduler_id``.
+
+.. rubric:: RETURN VALUES:
+
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_ID`
+ There was no scheduler associated with the identifier specified by
+ ``scheduler_id``.
+
+:c:macro:`RTEMS_NOT_CONFIGURED`
+ The processor was not configured to be used by the application.
+
+:c:macro:`RTEMS_INCORRECT_STATE`
+ The processor was configured to be used by the application, however, it was
+ not online.
+
+:c:macro:`RTEMS_RESOURCE_IN_USE`
+ The processor was already assigned to a scheduler.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive may obtain and release the object allocator mutex. This may
+ cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/scheduler/if/remove-processor
.. raw:: latex
- \clearpage
-
-.. _rtems_scheduler_remove_processor:
-
-SCHEDULER_REMOVE_PROCESSOR - Remove processor from a scheduler
---------------------------------------------------------------
-
-CALLING SEQUENCE:
- .. code-block:: c
-
- rtems_status_code rtems_scheduler_remove_processor(
- rtems_id scheduler_id,
- uint32_t cpu_index
- );
-
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
-
- * - ``RTEMS_SUCCESSFUL``
- - Successful operation.
- * - ``RTEMS_INVALID_ID``
- - Invalid scheduler instance identifier.
- * - ``RTEMS_INVALID_NUMBER``
- - The processor is not owned by the specified scheduler instance.
- * - ``RTEMS_RESOURCE_IN_USE``
- - The set of processors owned by the specified scheduler instance would
- be empty after the processor removal and there exists a non-idle task
- that uses this scheduler instance as its home scheduler instance.
- * - ``RTEMS_RESOURCE_IN_USE``
- - A task with a restricted processor affinity exists that uses this
- scheduler instance as its home scheduler instance and it would be no
- longer possible to allocate a processor for this task after the
- removal of this processor.
-
-DESCRIPTION:
- Removes a processor from set of processors owned by the specified scheduler
- instance.
-
-NOTES:
- Must be called from task context. This operation obtains and releases the
- objects allocator lock. Removing a processor from a scheduler is a complex
- operation that involves all tasks of the system.
+ \clearpage
+
+.. index:: rtems_scheduler_remove_processor()
+
+.. _InterfaceRtemsSchedulerRemoveProcessor:
+
+rtems_scheduler_remove_processor()
+----------------------------------
+
+Removes the processor from the set of processors owned by the scheduler.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_scheduler_remove_processor(
+ rtems_id scheduler_id,
+ uint32_t cpu_index
+ );
+
+.. rubric:: PARAMETERS:
+
+``scheduler_id``
+ This parameter is the scheduler identifier.
+
+``cpu_index``
+ This parameter is the index of the processor to remove.
+
+.. rubric:: DESCRIPTION:
+
+This directive removes the processor specified by the ``cpu_index`` from the
+scheduler specified by ``scheduler_id``.
+
+.. rubric:: RETURN VALUES:
+
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_ID`
+ There was no scheduler associated with the identifier specified by
+ ``scheduler_id``.
+
+:c:macro:`RTEMS_INVALID_NUMBER`
+ The processor was not owned by the scheduler.
+
+:c:macro:`RTEMS_RESOURCE_IN_USE`
+ The 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`.
+
+.. rubric:: NOTES:
+
+Removing a processor from a scheduler is a complex operation that involves all
+tasks of the system.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive may obtain and release the object allocator mutex. This may
+ cause the calling task to be preempted.
diff --git a/c-user/scheduling-concepts/introduction.rst b/c-user/scheduling-concepts/introduction.rst
index 92da6de..31de1c1 100644
--- a/c-user/scheduling-concepts/introduction.rst
+++ b/c-user/scheduling-concepts/introduction.rst
@@ -1,42 +1,86 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
-.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+.. Copyright (C) 2013, 2021 embedded brains GmbH (http://www.embedded-brains.de)
+.. Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR)
+
+.. This file is part of the RTEMS quality process and was automatically
+.. generated. If you find something that needs to be fixed or
+.. worded better please post a report or patch to an RTEMS mailing list
+.. or raise a bug report:
+..
+.. https://www.rtems.org/bugs.html
+..
+.. For information on updating and regenerating please refer to the How-To
+.. section in the Software Requirements Engineering chapter of the
+.. RTEMS Software Engineering manual. The manual is provided as a part of
+.. a release. For development sources please refer to the online
+.. documentation at:
+..
+.. https://docs.rtems.org
+
+.. Generated from spec:/rtems/scheduler/if/group
+
+.. _SchedulerManagerIntroduction:
Introduction
============
+.. The following list was generated from:
+.. spec:/rtems/scheduler/if/ident
+.. spec:/rtems/scheduler/if/ident-by-processor
+.. spec:/rtems/scheduler/if/ident-by-processor-set
+.. spec:/rtems/scheduler/if/get-maximum-priority
+.. spec:/rtems/scheduler/if/map-priority-to-posix
+.. spec:/rtems/scheduler/if/map-priority-from-posix
+.. spec:/rtems/scheduler/if/get-processor
+.. spec:/rtems/scheduler/if/get-processor-maximum
+.. spec:/rtems/scheduler/if/get-processor-set
+.. spec:/rtems/scheduler/if/add-processor
+.. spec:/rtems/scheduler/if/remove-processor
+
+The scheduling concepts relate to the allocation of processing time for tasks.
+
The concept of scheduling in real-time systems dictates the ability to provide
-an immediate response to specific external events, particularly the necessity of
-scheduling tasks to run within a specified time limit after the occurrence of
-an event. For example, software embedded in life-support systems used to
-monitor hospital patients must take instant action if a change in the patient's
+an immediate response to specific external events, particularly the necessity
+of scheduling tasks to run within a specified time limit after the occurrence
+of an event. For example, software embedded in life-support systems used to
+monitor hospital patients must take instant action if a change in the patient’s
status is detected.
The component of RTEMS responsible for providing this capability is
-appropriately called the scheduler. The scheduler's sole purpose is to
-allocate the all important resource of processor time to the various tasks
-competing for attention.
-
-The directives provided by the scheduler manager are:
+appropriately called the scheduler. The scheduler’s sole purpose is to allocate
+the all important resource of processor time to the various tasks competing for
+attention. The directives provided by the Scheduler Manager are:
-- :ref:`rtems_scheduler_ident`
+* :ref:`InterfaceRtemsSchedulerIdent` - Identifies a scheduler by the object
+ name.
-- :ref:`rtems_scheduler_ident_by_processor`
+* :ref:`InterfaceRtemsSchedulerIdentByProcessor` - Identifies a scheduler by
+ the processor index.
-- :ref:`rtems_scheduler_ident_by_processor_set`
+* :ref:`InterfaceRtemsSchedulerIdentByProcessorSet` - Identifies a scheduler by
+ the processor set.
-- :ref:`rtems_scheduler_get_maximum_priority`
+* :ref:`InterfaceRtemsSchedulerGetMaximumPriority` - Gets the maximum task
+ priority of the scheduler.
-- :ref:`rtems_scheduler_map_priority_to_posix`
+* :ref:`InterfaceRtemsSchedulerMapPriorityToPosix` - Maps a Classic API task
+ priority to the corresponding POSIX thread priority.
-- :ref:`rtems_scheduler_map_priority_from_posix`
+* :ref:`InterfaceRtemsSchedulerMapPriorityFromPosix` - Maps a POSIX thread
+ priority to the corresponding Classic API task priority.
-- :ref:`rtems_scheduler_get_processor`
+* :ref:`InterfaceRtemsSchedulerGetProcessor` - Returns the index of the current
+ processor.
-- :ref:`rtems_scheduler_get_processor_maximum`
+* :ref:`InterfaceRtemsSchedulerGetProcessorMaximum` - Returns the processor
+ maximum supported by the system.
-- :ref:`rtems_scheduler_get_processor_set`
+* :ref:`InterfaceRtemsSchedulerGetProcessorSet` - Gets the set of processors
+ owned by the scheduler.
-- :ref:`rtems_scheduler_add_processor`
+* :ref:`InterfaceRtemsSchedulerAddProcessor` - Adds the processor to the set of
+ processors owned by the scheduler.
-- :ref:`rtems_scheduler_remove_processor`
+* :ref:`InterfaceRtemsSchedulerRemoveProcessor` - Removes the processor from
+ the set of processors owned by the scheduler.
diff --git a/c-user/semaphore/directives.rst b/c-user/semaphore/directives.rst
index 54f40a4..45ed8c1 100644
--- a/c-user/semaphore/directives.rst
+++ b/c-user/semaphore/directives.rst
@@ -466,9 +466,9 @@ Obtains the semaphore.
This parameter is the option set.
``timeout``
- This parameter is the timeout in clock ticks if the :c:macro:`RTEMS_WAIT`
- option is set. Use :c:macro:`RTEMS_NO_TIMEOUT` to wait potentially
- forever.
+ This parameter is the timeout in :term:`clock ticks <clock tick>` if the
+ :c:macro:`RTEMS_WAIT` option is set. Use :c:macro:`RTEMS_NO_TIMEOUT` to
+ wait potentially forever.
.. rubric:: DESCRIPTION:
@@ -525,9 +525,17 @@ scheduler.
:c:macro:`RTEMS_INVALID_ID`
There was no semaphore associated with the identifier specified by ``id``.
+:c:macro:`RTEMS_NOT_DEFINED`
+ The semaphore uses a priority ceiling and there was no priority ceiling
+ defined for the :term:`home scheduler` of the calling task.
+
:c:macro:`RTEMS_UNSATISFIED`
The semaphore could not be obtained immediately.
+:c:macro:`RTEMS_INVALID_PRIORITY`
+ The semaphore uses a priority ceiling and the calling task had a current
+ priority less than the priority ceiling.
+
:c:macro:`RTEMS_INCORRECT_STATE`
Acquiring of the local, binary semaphore by the calling task would have
cased a deadlock.
@@ -686,7 +694,8 @@ The following constraints apply to this directive:
* The directive may be called from within task context.
-* The directive may unblock another task which may preempt the calling task.
+* The directive may unblock a task. This may cause the calling task to be
+ preempted.
* When the directive operates on a remote object, the directive sends a message
to the remote node and waits for a reply. This will preempt the calling
@@ -805,7 +814,8 @@ The following constraints apply to this directive:
* The directive may be called from within task context.
-* The directive may unblock another task which may preempt the calling task.
+* The directive may unblock a task. This may cause the calling task to be
+ preempted.
* When the directive operates on a remote object, the directive sends a message
to the remote node and waits for a reply. This will preempt the calling
@@ -1009,5 +1019,5 @@ The following constraints apply to this directive:
* The directive may be called from within task context.
-* The directive may change the priority of another task which may preempt the
- calling task.
+* The directive may change the priority of a task. This may cause the calling
+ task to be preempted.
diff --git a/c-user/task/directives.rst b/c-user/task/directives.rst
index b5574e9..2bfb8af 100644
--- a/c-user/task/directives.rst
+++ b/c-user/task/directives.rst
@@ -1,1454 +1,1970 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
-.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de)
+.. 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
+
+.. _TaskManagerDirectives:
Directives
==========
-This section details the task manager's directives. A subsection is dedicated
-to each of this manager's directives and describes the calling sequence,
-related constants, usage, and status codes.
+This section details the directives of the Task Manager. A subsection is
+dedicated to each of this manager's directives and lists the calling sequence,
+parameters, description, return values, and notes of the directive.
+
+.. Generated from spec:/rtems/task/if/create
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_task_create()
.. index:: create a task
-.. index:: rtems_task_create
-
-.. _rtems_task_create:
-
-TASK_CREATE - Create a task
----------------------------
-
-CALLING SEQUENCE:
- .. code-block:: c
-
- rtems_status_code rtems_task_create(
- rtems_name name,
- rtems_task_priority initial_priority,
- size_t stack_size,
- rtems_mode initial_modes,
- rtems_attribute attribute_set,
- rtems_id *id
- );
-
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
-
- * - ``RTEMS_SUCCESSFUL``
- - task created successfully
- * - ``RTEMS_INVALID_ADDRESS``
- - ``id`` is NULL
- * - ``RTEMS_INVALID_NAME``
- - invalid task name
- * - ``RTEMS_INVALID_PRIORITY``
- - invalid task priority
- * - ``RTEMS_TOO_MANY``
- - too many tasks created
- * - ``RTEMS_UNSATISFIED``
- - not enough memory for stack/FP context
- * - ``RTEMS_UNSATISFIED``
- - non-preemption mode not supported on SMP system
- * - ``RTEMS_UNSATISFIED``
- - interrupt level mode not supported on SMP system
- * - ``RTEMS_TOO_MANY``
- - too many global objects
-
-DESCRIPTION:
- This directive creates a task which resides on the local node. It
- allocates and initializes a TCB, a stack, and an optional floating point
- context area. The mode parameter contains values which sets the task's
- initial execution mode. The ``RTEMS_FLOATING_POINT`` attribute should be
- specified if the created task is to use a numeric coprocessor. For
- performance reasons, it is recommended that tasks not using the numeric
- coprocessor should specify the ``RTEMS_NO_FLOATING_POINT`` attribute. If
- the ``RTEMS_GLOBAL`` attribute is specified, the task can be accessed from
- remote nodes. The task id, returned in id, is used in other task related
- directives to access the task. When created, a task is placed in the
- dormant state and can only be made ready to execute using the directive
- ``rtems_task_start``.
-
-NOTES:
- This directive may cause the calling task to be preempted.
-
- The scheduler of the new task is the scheduler of the executing task at
- some point during the task creation. The specified task priority must be
- valid for the selected scheduler.
-
- The task processor affinity is initialized to the set of online processors.
-
- If the requested stack size is less than the configured minimum stack size,
- then RTEMS will use the configured minimum as the stack size for this task.
- In addition to being able to specify the task stack size as a integer,
- there are two constants which may be specified:
-
- ``RTEMS_MINIMUM_STACK_SIZE``
- The minimum stack size *RECOMMENDED* for use on this processor. This
- value is selected by the RTEMS developers conservatively to minimize the
- risk of blown stacks for most user applications. Using this constant
- when specifying the task stack size, indicates that the stack size will
- be at least ``RTEMS_MINIMUM_STACK_SIZE`` bytes in size. If the user
- configured minimum stack size is larger than the recommended minimum,
- then it will be used.
-
- ``RTEMS_CONFIGURED_MINIMUM_STACK_SIZE``
- Indicates this task is to be created with a stack size of the minimum
- stack size that was configured by the application. If not explicitly
- configured by the application, the default configured minimum stack size
- is the processor dependent value ``RTEMS_MINIMUM_STACK_SIZE``. Since
- this uses the configured minimum stack size value, you may get a stack
- size that is smaller or larger than the recommended minimum. This can be
- used to provide large stacks for all tasks on complex applications or
- small stacks on applications that are trying to conserve memory.
-
- Application developers should consider the stack usage of the device
- drivers when calculating the stack size required for tasks which utilize
- the driver.
-
- The following task attribute constants are defined by RTEMS:
-
- .. list-table::
- :class: rtems-table
-
- * - ``RTEMS_NO_FLOATING_POINT``
- - does not use coprocessor (default)
- * - ``RTEMS_FLOATING_POINT``
- - uses numeric coprocessor
- * - ``RTEMS_LOCAL``
- - local task (default)
- * - ``RTEMS_GLOBAL``
- - global task
-
- The following task mode constants are defined by RTEMS:
-
- .. list-table::
- :class: rtems-table
-
- * - ``RTEMS_PREEMPT``
- - enable preemption (default)
- * - ``RTEMS_NO_PREEMPT``
- - disable preemption
- * - ``RTEMS_NO_TIMESLICE``
- - disable timeslicing (default)
- * - ``RTEMS_TIMESLICE``
- - enable timeslicing
- * - ``RTEMS_ASR``
- - enable ASR processing (default)
- * - ``RTEMS_NO_ASR``
- - disable ASR processing
- * - ``RTEMS_INTERRUPT_LEVEL(0)``
- - enable all interrupts (default)
- * - ``RTEMS_INTERRUPT_LEVEL(n)``
- - execute at interrupt level ``n``
-
- The interrupt level portion of the task execution mode supports a maximum
- of 256 interrupt levels. These levels are mapped onto the interrupt
- levels actually supported by the target processor in a processor dependent
- fashion.
-
- Tasks should not be made global unless remote tasks must interact with
- them. This avoids the system overhead incurred by the creation of a
- global task. When a global task is created, the task's name and id must
- be transmitted to every node in the system for insertion in the local copy
- of the global object table.
-
- The total number of global objects, including tasks, is limited by the
- maximum_global_objects field in the Configuration Table.
+
+.. _InterfaceRtemsTaskCreate:
+
+rtems_task_create()
+-------------------
+
+Creates a task.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_task_create(
+ rtems_name name,
+ rtems_task_priority initial_priority,
+ size_t stack_size,
+ rtems_mode initial_modes,
+ rtems_attribute attribute_set,
+ rtems_id *id
+ );
+
+.. rubric:: PARAMETERS:
+
+``name``
+ This parameter is the object name of the task.
+
+``initial_priority``
+ This parameter is the initial task priority.
+
+``stack_size``
+ This parameter is the task stack size in bytes.
+
+``initial_modes``
+ This parameter is the initial mode set of the task.
+
+``attribute_set``
+ This parameter is the attribute set of the task.
+
+``id``
+ This parameter is the pointer to an object identifier variable. When the
+ directive call is successful, the identifier of the created task will be
+ stored in this variable.
+
+.. rubric:: DESCRIPTION:
+
+This directive creates a task which resides on the local node. The task has
+the user-defined object name specified in ``name``. The assigned object
+identifier is returned in ``id``. This identifier is used to access the task
+with other task related directives.
+
+The **initial priority** of the task is specified in ``initial_priority``. The
+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.
+
+The **stack size** of the task is specified in ``stack_size``. If the
+requested stack size is less than the configured minimum stack size, then RTEMS
+will use the configured minimum as the stack size for this task. The
+configured minimum stack size is defined by the
+:ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE` application configuration option. In
+addition to being able to specify the task stack size as a integer, there are
+two constants which may be specified:
+
+* The :c:macro:`RTEMS_MINIMUM_STACK_SIZE` constant can be specified to use the
+ **recommended minimum stack size** for the target processor. This value is
+ selected by the RTEMS maintainers conservatively to minimize the risk of
+ blown stacks for most user applications. Using this constant when specifying
+ the task stack size, indicates that the stack size will be at least
+ :c:macro:`RTEMS_MINIMUM_STACK_SIZE` bytes in size. If the user configured
+ minimum stack size is larger than the recommended minimum, then it will be
+ used.
+
+* The :c:macro:`RTEMS_CONFIGURED_MINIMUM_STACK_SIZE` constant can be specified
+ to use the minimum stack size that was configured by the application. If not
+ explicitly configured by the application, the default configured minimum
+ stack size is the target processor dependent value
+ :c:macro:`RTEMS_MINIMUM_STACK_SIZE`. Since this uses the configured minimum
+ stack size value, you may get a stack size that is smaller or larger than the
+ recommended minimum. This can be used to provide large stacks for all tasks
+ on complex applications or small stacks on applications that are trying to
+ conserve memory.
+
+The **initial mode set** specified in ``initial_modes`` is built through a
+*bitwise or* of the mode constants described below. Not all combinations of
+modes are allowed. Some modes are mutually exclusive. If mutually exclusive
+modes are combined, the behaviour is undefined. Default task modes can be
+selected by using the :c:macro:`RTEMS_DEFAULT_MODES` constant. The task mode
+set defines
+
+* the preemption mode of the task: :c:macro:`RTEMS_PREEMPT` (default) or
+ :c:macro:`RTEMS_NO_PREEMPT`,
+
+* the timeslicing mode of the task: :c:macro:`RTEMS_TIMESLICE` or
+ :c:macro:`RTEMS_NO_TIMESLICE` (default),
+
+* the :term:`ASR` processing mode of the task: :c:macro:`RTEMS_ASR` (default)
+ or :c:macro:`RTEMS_NO_ASR`,
+
+* the interrupt level of the task: :c:func:`RTEMS_INTERRUPT_LEVEL` with a
+ default of ``RTEMS_INTERRUPT_LEVEL( 0 )`` which is associated with enabled
+ interrupts.
+
+The **initial preemption mode** of the task is enabled or disabled.
+
+* An **enabled preemption** is the default and can be emphasized through the
+ use of the :c:macro:`RTEMS_PREEMPT` mode constant.
+
+* A **disabled preemption** is set by the :c:macro:`RTEMS_NO_PREEMPT` mode
+ constant.
+
+The **initial timeslicing mode** of the task is enabled or disabled.
+
+* A **disabled timeslicing** is the default and can be emphasized through the
+ use of the :c:macro:`RTEMS_NO_TIMESLICE` mode constant.
+
+* An **enabled timeslicing** is set by the :c:macro:`RTEMS_TIMESLICE` mode
+ constant.
+
+The **initial ASR processing mode** of the task is enabled or disabled.
+
+* An **enabled ASR processing** is the default and can be emphasized through
+ the use of the :c:macro:`RTEMS_ASR` mode constant.
+
+* A **disabled ASR processing** is set by the :c:macro:`RTEMS_NO_ASR` mode
+ constant.
+
+The **initial interrupt level mode** of the task is defined by
+:c:func:`RTEMS_INTERRUPT_LEVEL`.
+
+* Task execution with **interrupts enabled** the default and can be emphasized
+ through the use of the :c:func:`RTEMS_INTERRUPT_LEVEL` mode macro with a
+ value of zero (0) for the parameter. An interrupt level of zero is
+ associated with enabled interrupts on all target processors.
+
+* Task execution at a **non-zero interrupt level** can be specified by the
+ :c:func:`RTEMS_INTERRUPT_LEVEL` mode macro with a non-zero value for the
+ parameter. The interrupt level portion of the task mode supports a maximum
+ of 256 interrupt levels. These levels are mapped onto the interrupt levels
+ actually supported by the target processor in a processor dependent fashion.
+
+The **attribute set** specified in ``attribute_set`` is built through a
+*bitwise or* of the attribute constants described below. Not all combinations
+of attributes are allowed. Some attributes are mutually exclusive. If
+mutually exclusive attributes are combined, the behaviour is undefined.
+Attributes not mentioned below are not evaluated by this directive and have no
+effect. Default attributes can be selected by using the
+:c:macro:`RTEMS_DEFAULT_ATTRIBUTES` constant. The attribute set defines
+
+* the scope of the task: :c:macro:`RTEMS_LOCAL` (default) or
+ :c:macro:`RTEMS_GLOBAL` and
+
+* the floating-point unit use of the task: :c:macro:`RTEMS_FLOATING_POINT` or
+ :c:macro:`RTEMS_NO_FLOATING_POINT` (default).
+
+The task has a local or global **scope** in a multiprocessing network (this
+attribute does not refer to SMP systems). The scope is selected by the
+mutually exclusive :c:macro:`RTEMS_LOCAL` and :c:macro:`RTEMS_GLOBAL`
+attributes.
+
+* A **local scope** is the default and can be emphasized through the use of the
+ :c:macro:`RTEMS_LOCAL` attribute. A local task can be only used by the node
+ which created it.
+
+* A **global scope** is established if the :c:macro:`RTEMS_GLOBAL` attribute is
+ set. Setting the global attribute in a single node system has no effect.the
+
+The **use of the floating-point unit** is selected by the mutually exclusive
+:c:macro:`RTEMS_FLOATING_POINT` and :c:macro:`RTEMS_NO_FLOATING_POINT`
+attributes. On some target processors, the use of the floating-point unit can
+be enabled or disabled for each task. Other target processors may have no
+hardware floating-point unit or enable the use of the floating-point unit for
+all tasks. Consult the *RTEMS CPU Architecture Supplement* for the details.
+
+* A **disabled floating-point unit** is the default and can be emphasized
+ through use of the :c:macro:`RTEMS_NO_FLOATING_POINT` attribute. For
+ performance reasons, it is recommended that tasks not using the
+ floating-point unit should specify this attribute.
+
+* An **enabled floating-point unit** is selected by the
+ :c:macro:`RTEMS_FLOATING_POINT` attribute.
+
+.. rubric:: RETURN VALUES:
+
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_NAME`
+ The ``name`` parameter was invalid.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``id`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+:c:macro:`RTEMS_INVALID_PRIORITY`
+ The ``initial_priority`` was invalid.
+
+:c:macro:`RTEMS_TOO_MANY`
+ There was no inactive object available to create a task. The number of
+ tasks available to the application is configured through the
+ :ref:`CONFIGURE_MAXIMUM_TASKS` application configuration option.
+
+:c:macro:`RTEMS_TOO_MANY`
+ In multiprocessing configurations, there was no inactive global object
+ available to create a global task. The number of global objects available
+ to the application is configured through the
+ :ref:`CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS` application configuration
+ option.
+
+:c:macro:`RTEMS_UNSATISFIED`
+ There was not enough memory to allocate the task storage area. The task
+ storage area contains the task stack, the thread-local storage, and the
+ floating point context.
+
+:c:macro:`RTEMS_UNSATISFIED`
+ One of the task create extensions failed to create the task.
+
+:c:macro:`RTEMS_UNSATISFIED`
+ In SMP configurations, the non-preemption mode was not supported.
+
+:c:macro:`RTEMS_UNSATISFIED`
+ In SMP configurations, the interrupt level mode was not supported.
+
+.. rubric:: NOTES:
+
+The task processor affinity is initialized to the set of online processors.
+
+When created, a task is placed in the dormant state and can only be made ready
+to execute using the directive :ref:`InterfaceRtemsTaskStart`.
+
+Application developers should consider the stack usage of the device drivers
+when calculating the stack size required for tasks which utilize the driver.
+The task stack size shall account for an target processor dependent interrupt
+stack frame which may be placed on the stack of the interrupted task while
+servicing an interrupt. The stack checker may be used to monitor the stack
+usage, see :ref:`CONFIGURE_STACK_CHECKER_ENABLED`.
+
+For control and maintenance of the task, RTEMS allocates a :term:`TCB` from the
+local TCB free pool and initializes it.
+
+The TCB for a global task is allocated on the local node. Task should not be
+made global unless remote tasks must interact with the task. This is to avoid
+the system overhead incurred by the creation of a global task. When a global
+task is created, the task's name and identifier must be transmitted to every
+node in the system for insertion in the local copy of the global object table.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive may obtain and release the object allocator mutex. This may
+ cause the calling task to be preempted.
+
+* When the directive operates on a global object, the directive sends a message
+ to remote nodes. This may preempt the calling task.
+
+* The number of tasks available to the application is configured through the
+ :ref:`CONFIGURE_MAXIMUM_TASKS` application configuration option.
+
+* Where the object class corresponding to the directive is configured to use
+ unlimited objects, the directive may allocate memory from the RTEMS
+ Workspace.
+
+* The number of global objects available to the application is configured
+ through the :ref:`CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS` application
+ configuration option.
+
+.. Generated from spec:/rtems/task/if/construct
.. raw:: latex
- \clearpage
+ \clearpage
+
+.. index:: rtems_task_construct()
+
+.. _InterfaceRtemsTaskConstruct:
+
+rtems_task_construct()
+----------------------
+
+Constructs a task from the specified task configuration.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_task_construct(
+ const rtems_task_config *config,
+ rtems_id *id
+ );
+
+.. rubric:: PARAMETERS:
+
+``config``
+ This parameter is the task configuration.
+
+``id``
+ This parameter is the pointer to an object identifier variable. When the
+ directive call is successful, the identifier of the constructed task will
+ be stored in this variable.
+
+.. rubric:: RETURN VALUES:
+
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``config`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+:c:macro:`RTEMS_INVALID_NAME`
+ The task name was invalid.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``id`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+:c:macro:`RTEMS_INVALID_PRIORITY`
+ The initial task priority was invalid.
+
+:c:macro:`RTEMS_INVALID_SIZE`
+ The thread-local storage size is greater than the maximum thread-local
+ storage size specified in the task configuration. The thread-local storage
+ size is determined by the thread-local variables used by the application
+ and :ref:`CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE`.
+
+:c:macro:`RTEMS_INVALID_SIZE`
+ The task storage area was too small to provide a task stack of the
+ configured minimum size, see :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. The
+ task storage area contains the task stack, the thread-local storage, and
+ the floating-point context on architectures with a separate floating-point
+ context.
+
+:c:macro:`RTEMS_TOO_MANY`
+ There was no inactive task object available to construct a task.
+
+:c:macro:`RTEMS_TOO_MANY`
+ In multiprocessing configurations, there was no inactive global object
+ available to construct a global task.
+
+:c:macro:`RTEMS_UNSATISFIED`
+ One of the task create extensions failed during the task construction.
+
+:c:macro:`RTEMS_UNSATISFIED`
+ In SMP configurations, the non-preemption mode was not supported.
+
+:c:macro:`RTEMS_UNSATISFIED`
+ In SMP configurations, the interrupt level mode was not supported.
+
+.. rubric:: NOTES:
+
+In contrast to tasks created by :ref:`InterfaceRtemsTaskCreate`, the tasks
+constructed by this directive use a user-provided task storage area. The task
+storage area contains the task stack, the thread-local storage, and the
+floating-point context on architectures with a separate floating-point context.
+
+This directive is intended for applications which do not want to use the RTEMS
+Workspace and instead statically allocate all operating system resources. It
+is not recommended to use :ref:`InterfaceRtemsTaskCreate` and
+:ref:`InterfaceRtemsTaskConstruct` together in an application. It is also not
+recommended to use :ref:`InterfaceRtemsTaskConstruct` for drivers or general
+purpose libraries. The reason for these recommendations is that the task
+configuration needs settings which can be only given with a through knowledge
+of the application resources.
+
+An application based solely on static allocation can avoid any runtime memory
+allocators. This can simplify the application architecture as well as any
+analysis that may be required.
+
+The stack space estimate done by <rtems/confdefs.h> assumes that all tasks are
+created by :ref:`InterfaceRtemsTaskCreate`. The estimate can be adjusted to
+take user-provided task storage areas into account through the
+:ref:`CONFIGURE_MINIMUM_TASKS_WITH_USER_PROVIDED_STORAGE` application
+configuration option.
+
+The :ref:`CONFIGURE_MAXIMUM_TASKS` should include tasks constructed by
+:ref:`InterfaceRtemsTaskConstruct`.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive may obtain and release the object allocator mutex. This may
+ cause the calling task to be preempted.
+
+* When the directive operates on a global object, the directive sends a message
+ to remote nodes. This may preempt the calling task.
+
+* The number of tasks available to the application is configured through the
+ :ref:`CONFIGURE_MAXIMUM_TASKS` application configuration option.
+
+* Where the object class corresponding to the directive is configured to use
+ unlimited objects, the directive may allocate memory from the RTEMS
+ Workspace.
+
+* The number of global objects available to the application is configured
+ through the :ref:`CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS` application
+ configuration option.
+
+.. Generated from spec:/rtems/task/if/ident
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: rtems_task_ident()
+
+.. _InterfaceRtemsTaskIdent:
+
+rtems_task_ident()
+------------------
-.. index:: get ID of a task
-.. index:: rtems_task_ident
+Identifies a task by the object name.
-.. _rtems_task_ident:
+.. rubric:: CALLING SEQUENCE:
-TASK_IDENT - Get ID of a task
------------------------------
+.. code-block:: c
-CALLING SEQUENCE:
- .. code-block:: c
+ rtems_status_code rtems_task_ident(
+ rtems_name name,
+ uint32_t node,
+ rtems_id *id
+ );
- rtems_status_code rtems_task_ident(
- rtems_name name,
- uint32_t node,
- rtems_id *id
- );
+.. rubric:: PARAMETERS:
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+``name``
+ This parameter is the object name to look up.
- * - ``RTEMS_SUCCESSFUL``
- - task identified successfully
- * - ``RTEMS_INVALID_ADDRESS``
- - ``id`` is NULL
- * - ``RTEMS_INVALID_NAME``
- - invalid task name
- * - ``RTEMS_INVALID_NODE``
- - invalid node id
+``node``
+ This parameter is the node or node set to search for a matching object.
-DESCRIPTION:
- This directive obtains the task id associated with the task name specified
- in name. A task may obtain its own id by specifying ``RTEMS_SELF`` or its
- own task name in name. If the task name is not unique, then the task id
- returned will match one of the tasks with that name. However, this task id
- is not guaranteed to correspond to the desired task. The task id, returned
- in id, is used in other task related directives to access the task.
+``id``
+ This parameter is the pointer to an object identifier variable. When the
+ directive call is successful, the object identifier of an object with the
+ specified name will be stored in this variable.
-NOTES:
- This directive will not cause the running task to be preempted.
+.. rubric:: DESCRIPTION:
- If node is ``RTEMS_SEARCH_ALL_NODES``, all nodes are searched with the
- local node being searched first. All other nodes are searched with the
- lowest numbered node searched first.
+This directive obtains a task identifier associated with the task name
+specified in ``name``.
- If node is a valid node number which does not represent the local node,
- then only the tasks exported by the designated node are searched.
+A task may obtain its own identifier by specifying :c:macro:`RTEMS_SELF` for
+the name.
- This directive does not generate activity on remote nodes. It accesses
- only the local copy of the global object table.
+The node to search is specified in ``node``. It shall be
+
+* a valid node number,
+
+* the constant :c:macro:`RTEMS_SEARCH_ALL_NODES` to search in all nodes,
+
+* the constant :c:macro:`RTEMS_SEARCH_LOCAL_NODE` to search in the local node
+ only, or
+
+* the constant :c:macro:`RTEMS_SEARCH_OTHER_NODES` to search in all nodes
+ except the local node.
+
+.. rubric:: RETURN VALUES:
+
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``id`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+:c:macro:`RTEMS_INVALID_NAME`
+ There was no object with the specified name on the specified nodes.
+
+:c:macro:`RTEMS_INVALID_NODE`
+ In multiprocessing configurations, the specified node was invalid.
+
+.. rubric:: NOTES:
+
+If the task name is not unique, then the task identifier will match the first
+task with that name in the search order. However, this task identifier is not
+guaranteed to correspond to the desired task.
+
+The objects are searched from lowest to the highest index. If ``node`` is
+:c:macro:`RTEMS_SEARCH_ALL_NODES`, all nodes are searched with the local node
+being searched first. All other nodes are searched from lowest to the highest
+node number.
+
+If node is a valid node number which does not represent the local node, then
+only the tasks exported by the designated node are searched.
+
+This directive does not generate activity on remote nodes. It accesses only
+the local copy of the global object table.
+
+The task identifier is used with other task related directives to access the
+task.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/task/if/self
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_task_self()
.. index:: obtain ID of caller
-.. index:: rtems_task_self
-.. _rtems_task_self:
+.. _InterfaceRtemsTaskSelf:
+
+rtems_task_self()
+-----------------
+
+Gets the task identifier of the calling task.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_id rtems_task_self( void );
+
+.. rubric:: DESCRIPTION:
+
+This directive returns the task identifier of the calling task.
+
+.. rubric:: RETURN VALUES:
-TASK_SELF - Obtain ID of caller
--------------------------------
+Returns the task identifier of the calling task.
-CALLING SEQUENCE:
- .. code-block:: c
+.. rubric:: CONSTRAINTS:
- rtems_id rtems_task_self(void);
+The following constraints apply to this directive:
-DIRECTIVE STATUS CODES:
- Returns the object Id of the calling task.
+* The directive may be called from within device driver initialization context.
-DESCRIPTION:
- This directive returns the Id of the calling task.
+* The directive may be called from within task context.
-NOTES:
- If called from an interrupt service routine, this directive will return the
- Id of the interrupted task.
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/task/if/start
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_task_start()
.. index:: starting a task
-.. index:: rtems_task_start
-.. _rtems_task_start:
+.. _InterfaceRtemsTaskStart:
-TASK_START - Start a task
--------------------------
+rtems_task_start()
+------------------
+
+Starts the task.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_task_start(
+ rtems_id id,
+ rtems_task_entry entry_point,
+ rtems_task_argument argument
+ );
+
+.. rubric:: PARAMETERS:
+
+``id``
+ This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF`
+ may be used to specify the calling task.
+
+``entry_point``
+ This parameter is the task entry point.
+
+``argument``
+ This parameter is the task entry point argument.
+
+.. rubric:: DESCRIPTION:
+
+This directive readies the task, specified by ``id``, for execution based on
+the priority and execution mode specified when the task was created. The entry
+point of the task is given in ``entry_point``. The task's entry point argument
+is contained in ``argument``.
+
+.. rubric:: RETURN VALUES:
+
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``entry_point`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+:c:macro:`RTEMS_INVALID_ID`
+ There was no task associated with the identifier specified by ``id``.
+
+:c:macro:`RTEMS_INCORRECT_STATE`
+ The task was not in the dormant state.
+
+:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT`
+ The task resided on a remote node.
+
+.. rubric:: NOTES:
+
+The type of the entry point argument is an unsigned integer type. However, the
+integer type has the property that any valid pointer to ``void`` can be
+converted to this type and then converted back to a pointer to ``void``. The
+result will compare equal to the original pointer. The type can represent at
+least 32 bits. Some applications use the entry point argument as an index into
+a parameter table to get task-specific parameters.
+
+Any actions performed on a dormant task such as suspension or change of
+priority are nullified when the task is initiated via the
+:ref:`InterfaceRtemsTaskStart` directive.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within interrupt context.
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive may unblock a task. This may cause the calling task to be
+ preempted.
-CALLING SEQUENCE:
- .. code-block:: c
-
- rtems_status_code rtems_task_start(
- rtems_id id,
- rtems_task_entry entry_point,
- rtems_task_argument argument
- );
-
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
-
- * - ``RTEMS_SUCCESSFUL``
- - ask started successfully
- * - ``RTEMS_INVALID_ADDRESS``
- - invalid task entry point
- * - ``RTEMS_INVALID_ID``
- - invalid task id
- * - ``RTEMS_INCORRECT_STATE``
- - task not in the dormant state
- * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT``
- - cannot start remote task
-
-DESCRIPTION:
- This directive readies the task, specified by ``id``, for execution based
- on the priority and execution mode specified when the task was created.
- The starting address of the task is given in ``entry_point``. The task's
- starting argument is contained in argument. This argument can be a single
- value or used as an index into an array of parameter blocks. The type of
- this numeric argument is an unsigned integer type with the property that
- any valid pointer to void can be converted to this type and then converted
- back to a pointer to void. The result will compare equal to the original
- pointer.
-
-NOTES:
- The calling task will be preempted if its preemption mode is enabled and
- the task being started has a higher priority.
-
- Any actions performed on a dormant task such as suspension or change of
- priority are nullified when the task is initiated via the
- ``rtems_task_start`` directive.
+.. Generated from spec:/rtems/task/if/restart
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_task_restart()
.. index:: restarting a task
-.. index:: rtems_task_restart
-
-.. _rtems_task_restart:
-
-TASK_RESTART - Restart a task
------------------------------
-
-CALLING SEQUENCE:
- .. code-block:: c
-
- rtems_status_code rtems_task_restart(
- rtems_id id,
- rtems_task_argument argument
- );
-
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
-
- * - ``RTEMS_SUCCESSFUL``
- - task restarted successfully
- * - ``RTEMS_INVALID_ID``
- - task id invalid
- * - ``RTEMS_INCORRECT_STATE``
- - task never started
- * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT``
- - cannot restart remote task
-
-DESCRIPTION:
- This directive resets the task specified by id to begin execution at its
- original starting address. The task's priority and execution mode are set
- to the original creation values. If the task is currently blocked, RTEMS
- automatically makes the task ready. A task can be restarted from any
- state, except the dormant state.
-
- The task's starting argument is contained in argument. This argument can
- be a single value or an index into an array of parameter blocks. The type
- of this numeric argument is an unsigned integer type with the property that
- any valid pointer to void can be converted to this type and then converted
- back to a pointer to void. The result will compare equal to the original
- pointer. This new argument may be used to distinguish between the initial
- ``rtems_task_start`` of the task and any ensuing calls to
- ``rtems_task_restart`` of the task. This can be beneficial in deleting a
- task. Instead of deleting a task using the ``rtems_task_delete``
- directive, a task can delete another task by restarting that task, and
- allowing that task to release resources back to RTEMS and then delete
- itself.
-
-NOTES:
- If id is ``RTEMS_SELF``, the calling task will be restarted and will not
- return from this directive.
-
- The calling task will be preempted if its preemption mode is enabled and
- the task being restarted has a higher priority.
-
- The task must reside on the local node, even if the task was created with
- the ``RTEMS_GLOBAL`` option.
+
+.. _InterfaceRtemsTaskRestart:
+
+rtems_task_restart()
+--------------------
+
+Restarts the task.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_task_restart(
+ rtems_id id,
+ rtems_task_argument argument
+ );
+
+.. rubric:: PARAMETERS:
+
+``id``
+ This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF`
+ may be used to specify the calling task.
+
+``argument``
+ This parameter is the task entry point argument.
+
+.. rubric:: DESCRIPTION:
+
+This directive resets the task specified by ``id`` to begin execution at its
+original entry point. The task's priority and execution mode are set to the
+original creation values. If the task is currently blocked, RTEMS
+automatically makes the task ready. A task can be restarted from any state,
+except the dormant state. The task's entry point argument is contained in
+``argument``.
+
+.. rubric:: RETURN VALUES:
+
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_ID`
+ There was no task associated with the identifier specified by ``id``.
+
+:c:macro:`RTEMS_INCORRECT_STATE`
+ The task never started.
+
+:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT`
+ The task resided on a remote node.
+
+.. rubric:: NOTES:
+
+The type of the entry point argument is an unsigned integer type. However, the
+integer type has the property that any valid pointer to ``void`` can be
+converted to this type and then converted back to a pointer to ``void``. The
+result will compare equal to the original pointer. The type can represent at
+least 32 bits. Some applications use the entry point argument as an index into
+a parameter table to get task-specific parameters.
+
+A new entry point argument may be used to distinguish between the initial
+:ref:`InterfaceRtemsTaskStart` of the task and any ensuing calls to
+:ref:`InterfaceRtemsTaskRestart` of the task. This can be beneficial in
+deleting a task. Instead of deleting a task using the
+:ref:`InterfaceRtemsTaskDelete` directive, a task can delete another task by
+restarting that task, and allowing that task to release resources back to RTEMS
+and then delete itself.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within interrupt context.
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive may change the priority of a task. This may cause the calling
+ task to be preempted.
+
+* The directive may unblock a task. This may cause the calling task to be
+ preempted.
+
+.. Generated from spec:/rtems/task/if/delete
.. raw:: latex
- \clearpage
+ \clearpage
-.. index:: deleting a task
-.. index:: rtems_task_delete
-
-.. _rtems_task_delete:
-
-TASK_DELETE - Delete a task
----------------------------
-
-CALLING SEQUENCE:
- .. code-block:: c
-
- rtems_status_code rtems_task_delete(
- rtems_id id
- );
-
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
-
- * - ``RTEMS_SUCCESSFUL``
- - task deleted successfully
- * - ``RTEMS_INVALID_ID``
- - task id invalid
- * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT``
- - cannot restart remote task
-
-DESCRIPTION:
- This directive deletes a task, either the calling task or another task, as
- specified by id. RTEMS stops the execution of the task and reclaims the
- stack memory, any allocated delay or timeout timers, the TCB, and, if the
- task is ``RTEMS_FLOATING_POINT``, its floating point context area. RTEMS
- does not reclaim the following resources: region segments, partition
- buffers, semaphores, timers, or rate monotonic periods.
-
-NOTES:
- A task is responsible for releasing its resources back to RTEMS before
- deletion. To insure proper deallocation of resources, a task should not be
- deleted unless it is unable to execute or does not hold any RTEMS
- resources. If a task holds RTEMS resources, the task should be allowed to
- deallocate its resources before deletion. A task can be directed to
- release its resources and delete itself by restarting it with a special
- argument or by sending it a message, an event, or a signal.
-
- Deletion of the current task (``RTEMS_SELF``) will force RTEMS to select
- another task to execute.
-
- When a global task is deleted, the task id must be transmitted to every
- node in the system for deletion from the local copy of the global object
- table.
-
- The task must reside on the local node, even if the task was created with
- the ``RTEMS_GLOBAL`` option.
+.. index:: rtems_task_delete()
+.. index:: delete a task
+
+.. _InterfaceRtemsTaskDelete:
+
+rtems_task_delete()
+-------------------
+
+Deletes the task.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_task_delete( rtems_id id );
+
+.. rubric:: PARAMETERS:
+
+``id``
+ This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF`
+ may be used to specify the calling task.
+
+.. rubric:: DESCRIPTION:
+
+This directive deletes the task, either the calling task or another task, as
+specified by ``id``.
+
+.. rubric:: RETURN VALUES:
+
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_ID`
+ There was no task associated with the identifier specified by ``id``.
+
+:c:macro:`RTEMS_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
+explicitly does not reclaim the following resources: region segments, partition
+buffers, semaphores, timers, or rate monotonic periods.
+
+A task is responsible for releasing its resources back to RTEMS before
+deletion. To insure proper deallocation of resources, a task should not be
+deleted unless it is unable to execute or does not hold any RTEMS resources. If
+a task holds RTEMS resources, the task should be allowed to deallocate its
+resources before deletion. A task can be directed to release its resources and
+delete itself by restarting it with a special argument or by sending it a
+message, an event, or a signal.
+
+Deletion of the current 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 global task is deleted, the task identifier must be transmitted to every
+node in the system for deletion from the local copy of the global object table.
+
+The task must reside on the local node, even if the task was created with the
+:c:macro:`RTEMS_GLOBAL` attribute.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive may obtain and release the object allocator mutex. This may
+ cause the calling task to be preempted.
+
+* When the directive operates on a global object, the directive sends a message
+ to remote nodes. This may preempt the calling task.
+
+* The calling task does not have to be the task that created the object. Any
+ local task that knows the object identifier can delete the object.
+
+* Where the object class corresponding to the directive is configured to use
+ unlimited objects, the directive may free memory to the RTEMS Workspace.
+
+.. Generated from spec:/rtems/task/if/exit
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_task_exit()
.. index:: deleting a task
-.. index:: rtems_task_exit
-.. _rtems_task_exit:
+.. _InterfaceRtemsTaskExit:
+
+rtems_task_exit()
+-----------------
+
+Deletes the calling task.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
-TASK_EXIT - Delete the calling task
------------------------------------
+ void rtems_task_exit( void );
-CALLING SEQUENCE:
- .. code-block:: c
+.. rubric:: DESCRIPTION:
- void rtems_task_exit( void ) RTEMS_NO_RETURN;
+This directive deletes the calling task.
-DIRECTIVE STATUS CODES:
- NONE - This function will not return to the caller.
+.. rubric:: NOTES:
-DESCRIPTION:
- This directive deletes the calling task.
+The directive is an optimized variant of the following code sequences, see also
+:ref:`InterfaceRtemsTaskDelete`:
-NOTES:
- This directive must be called from a regular task context with enabled
- interrupts, otherwise one of the fatal errors
+.. code-block:: c
- * :ref:`INTERNAL_ERROR_BAD_THREAD_DISPATCH_DISABLE_LEVEL <internal_errors>`, or
- * :ref:`INTERNAL_ERROR_BAD_THREAD_DISPATCH_ENVIRONMENT <internal_errors>`
+ #include <pthread.h>
+ #include <rtems.h>
- will occur.
+ void classic_delete_self( void )
+ {
+ (void) rtems_task_delete( RTEMS_SELF );
+ }
- The ``rtems_task_exit()`` call is equivalent to the following code
- sequence:
+ void posix_delete_self( void )
+ {
+ (void) pthread_detach( pthread_self() );
+ (void) pthread_exit( NULL);
+ }
- .. code-block:: c
+.. rubric:: CONSTRAINTS:
- pthread_detach(pthread_self());
- pthread_exit(NULL);
+The following constraints apply to this directive:
- See also :ref:`rtems_task_delete() <rtems_task_delete>`.
+* The directive may be called from within task context.
+
+* The directive will not return to the caller.
+
+* While thread dispatching is disabled, if the directive performs a thread
+ dispatch, then the fatal error with the fatal source
+ :ref:`INTERNAL_ERROR_CORE <FatalErrorSources>` and the fatal code
+ :ref:`INTERNAL_ERROR_BAD_THREAD_DISPATCH_DISABLE_LEVEL <internal_errors>`
+ will occur.
+
+.. Generated from spec:/rtems/task/if/suspend
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_task_suspend()
.. index:: suspending a task
-.. index:: rtems_task_suspend
-.. _rtems_task_suspend:
+.. _InterfaceRtemsTaskSuspend:
+
+rtems_task_suspend()
+--------------------
+
+Suspends the task.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
-TASK_SUSPEND - Suspend a task
------------------------------
+ rtems_status_code rtems_task_suspend( rtems_id id );
-CALLING SEQUENCE:
- .. code-block:: c
+.. rubric:: PARAMETERS:
- rtems_status_code rtems_task_suspend(
- rtems_id id
- );
+``id``
+ This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF`
+ may be used to specify the calling task.
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+.. rubric:: DESCRIPTION:
- * - ``RTEMS_SUCCESSFUL``
- - task suspended successfully
- * - ``RTEMS_INVALID_ID``
- - task id invalid
- * - ``RTEMS_ALREADY_SUSPENDED``
- - task already suspended
+This directive suspends the task specified by ``id`` from further execution by
+placing it in the suspended state. This state is additive to any other blocked
+state that the task may already be in. The task will not execute again until
+another task issues the :ref:`InterfaceRtemsTaskResume` directive for this task
+and any blocked state has been removed. The :ref:`InterfaceRtemsTaskRestart`
+directive will also remove the suspended state.
-DESCRIPTION:
- This directive suspends the task specified by id from further execution by
- placing it in the suspended state. This state is additive to any other
- blocked state that the task may already be in. The task will not execute
- again until another task issues the ``rtems_task_resume`` directive for
- this task and any blocked state has been removed.
+.. rubric:: RETURN VALUES:
-NOTES:
- The requesting task can suspend itself by specifying ``RTEMS_SELF`` as id.
- In this case, the task will be suspended and a successful return code will
- be returned when the task is resumed.
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
- Suspending a global task which does not reside on the local node will
- generate a request to the remote node to suspend the specified task.
+:c:macro:`RTEMS_INVALID_ID`
+ There was no task associated with the identifier specified by ``id``.
- If the task specified by id is already suspended, then the
- ``RTEMS_ALREADY_SUSPENDED`` status code is returned.
+:c:macro:`RTEMS_ALREADY_SUSPENDED`
+ The task was already suspended.
+
+:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT`
+ The task resided on a remote node.
+
+.. rubric:: NOTES:
+
+The requesting task can suspend itself for example by specifying
+:c:macro:`RTEMS_SELF` as ``id``. In this case, the task will be suspended and
+a successful return code will be returned when the task is resumed.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within interrupt context.
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* When the directive operates on a remote object, the directive sends a message
+ to the remote node and waits for a reply. This will preempt the calling
+ task.
+
+.. Generated from spec:/rtems/task/if/resume
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_task_resume()
.. index:: resuming a task
-.. index:: rtems_task_resume
-.. _rtems_task_resume:
+.. _InterfaceRtemsTaskResume:
+
+rtems_task_resume()
+-------------------
+
+Resumes the task.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
-TASK_RESUME - Resume a task
----------------------------
+ rtems_status_code rtems_task_resume( rtems_id id );
-CALLING SEQUENCE:
- .. code-block:: c
+.. rubric:: PARAMETERS:
- rtems_status_code rtems_task_resume(
- rtems_id id
- );
+``id``
+ This parameter is the task identifier.
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+.. rubric:: DESCRIPTION:
- * - ``RTEMS_SUCCESSFUL``
- - task resumed successfully
- * - ``RTEMS_INVALID_ID``
- - task id invalid
- * - ``RTEMS_INCORRECT_STATE``
- - task not suspended
+This directive removes the task specified by ``id`` from the suspended state.
+If the task is in the ready state after the suspension is removed, then it will
+be scheduled to run. If the task is still in a blocked state after the
+suspension is removed, then it will remain in that blocked state.
-DESCRIPTION:
- This directive removes the task specified by id from the suspended state.
- If the task is in the ready state after the suspension is removed, then it
- will be scheduled to run. If the task is still in a blocked state after
- the suspension is removed, then it will remain in that blocked state.
+.. rubric:: RETURN VALUES:
-NOTES:
- The running task may be preempted if its preemption mode is enabled and the
- local task being resumed has a higher priority.
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
- Resuming a global task which does not reside on the local node will
- generate a request to the remote node to resume the specified task.
+:c:macro:`RTEMS_INVALID_ID`
+ There was no task associated with the identifier specified by ``id``.
- If the task specified by id is not suspended, then the
- ``RTEMS_INCORRECT_STATE`` status code is returned.
+:c:macro:`RTEMS_INCORRECT_STATE`
+ The task was not suspended.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within interrupt context.
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive may unblock a task. This may cause the calling task to be
+ preempted.
+
+* When the directive operates on a remote object, the directive sends a message
+ to the remote node and waits for a reply. This will preempt the calling
+ task.
+
+.. Generated from spec:/rtems/task/if/is-suspended
.. raw:: latex
- \clearpage
+ \clearpage
+
+.. index:: rtems_task_is_suspended()
+
+.. _InterfaceRtemsTaskIsSuspended:
+
+rtems_task_is_suspended()
+-------------------------
+
+Checks if the task is suspended.
+
+.. rubric:: CALLING SEQUENCE:
-.. index:: is task suspended
-.. index:: rtems_task_is_suspended
+.. code-block:: c
-.. _rtems_task_is_suspended:
+ rtems_status_code rtems_task_is_suspended( rtems_id id );
-TASK_IS_SUSPENDED - Determine if a task is Suspended
-----------------------------------------------------
+.. rubric:: PARAMETERS:
-CALLING SEQUENCE:
- .. code-block:: c
+``id``
+ This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF`
+ may be used to specify the calling task.
- rtems_status_code rtems_task_is_suspended(
- rtems_id id
- );
+.. rubric:: DESCRIPTION:
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+This directive returns a status code indicating whether or not the task
+specified by ``id`` is currently suspended.
- * - ``RTEMS_SUCCESSFUL``
- - task is NOT suspended
- * - ``RTEMS_ALREADY_SUSPENDED``
- - task is currently suspended
- * - ``RTEMS_INVALID_ID``
- - task id invalid
- * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT``
- - not supported on remote tasks
+.. rubric:: RETURN VALUES:
-DESCRIPTION:
- This directive returns a status code indicating whether or not the
- specified task is currently suspended.
+:c:macro:`RTEMS_SUCCESSFUL`
+ The task was **not** suspended.
-NOTES:
- This operation is not currently supported on remote tasks.
+:c:macro:`RTEMS_INVALID_ID`
+ There was no task associated with the identifier specified by ``id``.
+
+:c:macro:`RTEMS_ALREADY_SUSPENDED`
+ The task was suspended.
+
+:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT`
+ The task resided on a remote node.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within interrupt context.
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/task/if/set-priority
.. raw:: latex
- \clearpage
+ \clearpage
-.. index:: rtems_task_set_priority
+.. index:: rtems_task_set_priority()
.. index:: current task priority
.. index:: set task priority
.. index:: get task priority
.. index:: obtain task priority
-.. _rtems_task_set_priority:
-
-TASK_SET_PRIORITY - Set task priority
--------------------------------------
-
-CALLING SEQUENCE:
- .. code-block:: c
-
- rtems_status_code rtems_task_set_priority(
- rtems_id id,
- rtems_task_priority new_priority,
- rtems_task_priority *old_priority
- );
-
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
-
- * - ``RTEMS_SUCCESSFUL``
- - task priority set successfully
- * - ``RTEMS_INVALID_ID``
- - invalid task id
- * - ``RTEMS_INVALID_ADDRESS``
- - invalid return argument pointer
- * - ``RTEMS_INVALID_PRIORITY``
- - invalid task priority
-
-DESCRIPTION:
- This directive manipulates the priority of the task specified by id. An id
- of ``RTEMS_SELF`` is used to indicate the calling task. When new_priority
- is not equal to ``RTEMS_CURRENT_PRIORITY``, the specified task's previous
- priority is returned in old_priority. When new_priority is
- ``RTEMS_CURRENT_PRIORITY``, the specified task's current priority is
- returned in old_priority. Valid priorities range from a high of 1 to a low
- of 255.
-
-NOTES:
- The calling task may be preempted if its preemption mode is enabled and it
- lowers its own priority or raises another task's priority.
-
- In case the new priority equals the current priority of the task, then
- nothing happens.
-
- Setting the priority of a global task which does not reside on the local
- node will generate a request to the remote node to change the priority of
- the specified task.
-
- If the task specified by id is currently holding any binary semaphores
- which use the priority inheritance algorithm, then the task's priority
- cannot be lowered immediately. If the task's priority were lowered
- immediately, then priority inversion results. The requested lowering of
- the task's priority will occur when the task has released all priority
- inheritance binary semaphores. The task's priority can be increased
- regardless of the task's use of priority inheritance binary semaphores.
+.. _InterfaceRtemsTaskSetPriority:
+
+rtems_task_set_priority()
+-------------------------
+
+Sets the real priority or gets the current priority of the task.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_task_set_priority(
+ rtems_id id,
+ rtems_task_priority new_priority,
+ rtems_task_priority *old_priority
+ );
+
+.. rubric:: PARAMETERS:
+
+``id``
+ This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF`
+ may be used to specify the calling task.
+
+``new_priority``
+ This parameter is the new real priority or
+ :c:macro:`RTEMS_CURRENT_PRIORITY` to get the current priority.
+
+``old_priority``
+ This parameter is the pointer to an :c:type:`rtems_task_priority` variable.
+ 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
+ variable.
+
+.. rubric:: DESCRIPTION:
+
+This directive manipulates the priority of the task specified by ``id``. When
+``new_priority`` is not equal to :c:macro:`RTEMS_CURRENT_PRIORITY`, the
+specified task's previous priority is returned in ``old_priority``. When
+``new_priority`` is :c:macro:`RTEMS_CURRENT_PRIORITY`, the specified task's
+current priority is returned in ``old_priority``.
+
+.. rubric:: RETURN VALUES:
+
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``old_priority`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+:c:macro:`RTEMS_INVALID_ID`
+ There was no task associated with the identifier specified by ``id``.
+
+:c:macro:`RTEMS_INVALID_PRIORITY`
+ The task priority specified in ``new_priority`` was invalid with respect to
+ the :term:`home scheduler` of the task.
+
+.. rubric:: NOTES:
+
+Valid priorities range from one to a maximum value which depends on the
+configured scheduler. The lower the priority value the higher is the
+importance of the task.
+
+If the task is currently holding any binary semaphores which use a locking
+protocol, then the task's priority cannot be lowered immediately. If the
+task's priority were lowered immediately, then this could violate properties of
+the locking protocol and may result in priority inversion. The requested
+lowering of the task's priority will occur when the task has released all
+binary semaphores which make the task more important. The task's priority can
+be increased regardless of the task's use of binary semaphores with locking
+protocols.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within interrupt context.
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive may change the priority of a task. This may cause the calling
+ task to be preempted.
+
+* When the directive operates on a remote object, the directive sends a message
+ to the remote node and waits for a reply. This will preempt the calling
+ task.
+
+.. Generated from spec:/rtems/task/if/get-priority
.. raw:: latex
- \clearpage
+ \clearpage
-.. index:: rtems_task_get_priority
+.. index:: rtems_task_get_priority()
.. index:: current task priority
.. index:: get task priority
.. index:: obtain task priority
-.. _rtems_task_get_priority:
-
-TASK_GET_PRIORITY - Get task priority
--------------------------------------
-
-CALLING SEQUENCE:
- .. code-block:: c
-
- rtems_status_code rtems_task_get_priority(
- rtems_id task_id,
- rtems_id scheduler_id,
- rtems_task_priority *priority
- );
-
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
-
- * - ``RTEMS_SUCCESSFUL``
- - Successful operation.
- * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT``
- - Directive is illegal on remote tasks.
- * - ``RTEMS_INVALID_ADDRESS``
- - The priority parameter is NULL.
- * - ``RTEMS_INVALID_ID``
- - Invalid task or scheduler identifier.
- * - ``RTEMS_NOT_DEFINED``
- - The task has no priority within the specified scheduler instance.
- This error is only possible in SMP configurations.
-
-DESCRIPTION:
- This directive returns the current priority of the task specified by
- :c:data:`task_id` with respect to the scheduler instance specified by
- :c:data:`scheduler_id`. A task id of :c:macro:`RTEMS_SELF` is used to
- indicate the calling task.
-
-NOTES:
- The current priority reflects temporary priority adjustments due to locking
- protocols, the rate-monotonic period objects on some schedulers and other
- mechanisms.
+.. _InterfaceRtemsTaskGetPriority:
+
+rtems_task_get_priority()
+-------------------------
+
+Gets the current priority of the task with respect to the scheduler.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_task_get_priority(
+ rtems_id task_id,
+ rtems_id scheduler_id,
+ rtems_task_priority *priority
+ );
+
+.. rubric:: PARAMETERS:
+
+``task_id``
+ This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF`
+ may be used to specify the calling task.
+
+``scheduler_id``
+ This parameter is the scheduler identifier.
+
+``priority``
+ This parameter is the pointer to an :c:type:`rtems_task_priority` variable.
+ When the directive call is successful, the current priority of the task
+ with respect to the specified scheduler will be stored in this variable.
+
+.. rubric:: DESCRIPTION:
+
+This directive returns the current priority in ``priority`` of the task
+specified by ``task_id`` with respect to the scheduler specified by
+``scheduler_id``.
+
+.. rubric:: RETURN VALUES:
+
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``priority`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+:c:macro:`RTEMS_INVALID_ID`
+ There was no task associated with the identifier specified by ``task_id``.
+
+:c:macro:`RTEMS_INVALID_ID`
+ There was no scheduler associated with the identifier specified by
+ ``scheduler_id``.
+
+:c:macro:`RTEMS_NOT_DEFINED`
+ The task had no priority with respect to the scheduler.
+
+:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT`
+ The task resided on a remote node.
+
+.. rubric:: NOTES:
+
+The current priority reflects temporary priority adjustments due to locking
+protocols, the rate-monotonic period objects on some schedulers, and other
+mechanisms.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within interrupt context.
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/task/if/mode
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_task_mode()
.. index:: current task mode
.. index:: set task mode
.. index:: get task mode
.. index:: set task preemption mode
.. index:: get task preemption mode
.. index:: obtain task mode
-.. index:: rtems_task_mode
-
-.. _rtems_task_mode:
-
-TASK_MODE - Change the current task mode
-----------------------------------------
-
-CALLING SEQUENCE:
- .. code-block:: c
-
- rtems_status_code rtems_task_mode(
- rtems_mode mode_set,
- rtems_mode mask,
- rtems_mode *previous_mode_set
- );
-
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
-
- * - ``RTEMS_SUCCESSFUL``
- - task mode set successfully
- * - ``RTEMS_INVALID_ADDRESS``
- - ``previous_mode_set`` is NULL
- - not enough memory for stack/FP context
- * - ``RTEMS_NOT_IMPLEMENTED``
- - non-preemption mode not supported on SMP system
- * - ``RTEMS_NOT_IMPLEMENTED``
-
-DESCRIPTION:
- This directive manipulates the execution mode of the calling task. A
- task's execution mode enables and disables preemption, timeslicing,
- asynchronous signal processing, as well as specifying the current interrupt
- level. To modify an execution mode, the mode class(es) to be changed must
- be specified in the mask parameter and the desired mode(s) must be
- specified in the mode parameter.
-
-NOTES:
- The calling task will be preempted if it enables preemption and a higher
- priority task is ready to run.
-
- Enabling timeslicing has no effect if preemption is disabled. For a task
- to be timesliced, that task must have both preemption and timeslicing
- enabled.
-
- A task can obtain its current execution mode, without modifying it, by
- calling this directive with a mask value of ``RTEMS_CURRENT_MODE``.
-
- To temporarily disable the processing of a valid ASR, a task should call
- this directive with the ``RTEMS_NO_ASR`` indicator specified in mode.
-
- The set of task mode constants and each mode's corresponding mask constant
- is provided in the following table:
-
- .. list-table::
- :class: rtems-table
-
- * - ``RTEMS_PREEMPT``
- - is masked by ``RTEMS_PREEMPT_MASK`` and enables preemption
- * - ``RTEMS_NO_PREEMPT``
- - is masked by ``RTEMS_PREEMPT_MASK`` and disables preemption
- * - ``RTEMS_NO_TIMESLICE``
- - is masked by ``RTEMS_TIMESLICE_MASK`` and disables timeslicing
- * - ``RTEMS_TIMESLICE``
- - is masked by ``RTEMS_TIMESLICE_MASK`` and enables timeslicing
- * - ``RTEMS_ASR``
- - is masked by ``RTEMS_ASR_MASK`` and enables ASR processing
- * - ``RTEMS_NO_ASR``
- - is masked by ``RTEMS_ASR_MASK`` and disables ASR processing
- * - ``RTEMS_INTERRUPT_LEVEL(0)``
- - is masked by ``RTEMS_INTERRUPT_MASK`` and enables all interrupts
- * - ``RTEMS_INTERRUPT_LEVEL(n)``
- - is masked by ``RTEMS_INTERRUPT_MASK`` and sets interrupts level n
+
+.. _InterfaceRtemsTaskMode:
+
+rtems_task_mode()
+-----------------
+
+Gets and optionally sets the mode of the calling task.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_task_mode(
+ rtems_mode mode_set,
+ rtems_mode mask,
+ rtems_mode *previous_mode_set
+ );
+
+.. rubric:: PARAMETERS:
+
+``mode_set``
+ This parameter is the mode set to apply to the calling task. When ``mask``
+ is set to :c:macro:`RTEMS_CURRENT_MODE`, the value of this parameter is
+ ignored. Only modes requested by ``mask`` are applied to the calling task.
+
+``mask``
+ This parameter is the mode mask which specifies which modes in ``mode_set``
+ are applied to the calling task. When the value is
+ :c:macro:`RTEMS_CURRENT_MODE`, the mode of the calling task is not changed.
+
+``previous_mode_set``
+ This parameter is the pointer to a mode variable. When the directive call
+ is successful, the mode of the task before any mode changes done by the
+ directive call will be stored in this variable.
+
+.. rubric:: DESCRIPTION:
+
+This directive queries and optionally manipulates the execution mode of the
+calling task. A task's execution mode enables and disables preemption,
+timeslicing, asynchronous signal processing, as well as specifying the
+interrupt level. To modify an execution mode, the mode class(es) to be changed
+must be specified in the ``mask`` parameter and the desired mode(s) must be
+specified in the ``mode_set`` parameter.
+
+A task can obtain its current execution mode, without modifying it, by calling
+this directive with a ``mask`` value of :c:macro:`RTEMS_CURRENT_MODE`.
+
+The **mode set** specified in ``mode_set`` is built through a *bitwise or* of
+the mode constants described below. Not all combinations of modes are allowed.
+Some modes are mutually exclusive. If mutually exclusive modes are combined,
+the behaviour is undefined. Default task modes can be selected by using the
+:c:macro:`RTEMS_DEFAULT_MODES` constant. The task mode set defines
+
+* the preemption mode of the task: :c:macro:`RTEMS_PREEMPT` (default) or
+ :c:macro:`RTEMS_NO_PREEMPT`,
+
+* the timeslicing mode of the task: :c:macro:`RTEMS_TIMESLICE` or
+ :c:macro:`RTEMS_NO_TIMESLICE` (default),
+
+* the :term:`ASR` processing mode of the task: :c:macro:`RTEMS_ASR` (default)
+ or :c:macro:`RTEMS_NO_ASR`,
+
+* the interrupt level of the task: :c:func:`RTEMS_INTERRUPT_LEVEL` with a
+ default of ``RTEMS_INTERRUPT_LEVEL( 0 )`` which is associated with enabled
+ interrupts.
+
+The **mode mask** specified in ``mask`` is built through a *bitwise or* of the
+mode mask constants described below.
+
+When the :c:macro:`RTEMS_PREEMPT_MASK` is set in ``mask``, the **preemption
+mode** of the calling task is
+
+* enabled by using the :c:macro:`RTEMS_PREEMPT` mode constant in ``mode_set``
+ and
+
+* disabled by using the :c:macro:`RTEMS_NO_PREEMPT` mode constant in
+ ``mode_set``.
+
+When the :c:macro:`RTEMS_TIMESLICE_MASK` is set in ``mask``, the **timeslicing
+mode** of the calling task is
+
+* enabled by using the :c:macro:`RTEMS_TIMESLICE` mode constant in ``mode_set``
+ and
+
+* disabled by using the :c:macro:`RTEMS_NO_TIMESLICE` mode constant in
+ ``mode_set``.
+
+Enabling timeslicing has no effect if preemption is disabled. For a task to be
+timesliced, that task must have both preemption and timeslicing enabled.
+
+When the :c:macro:`RTEMS_ASR_MASK` is set in ``mask``, the **ASR processing
+mode** of the calling task is
+
+* enabled by using the :c:macro:`RTEMS_ASR` mode constant in ``mode_set`` and
+
+* disabled by using the :c:macro:`RTEMS_NO_ASR` mode constant in ``mode_set``.
+
+When the :c:macro:`RTEMS_INTERRUPT_MASK` is set in ``mask``, **interrupts** of
+the calling task are
+
+* enabled by using the :c:func:`RTEMS_INTERRUPT_LEVEL` mode macro with a value
+ of zero (0) in ``mode_set`` and
+
+* disabled up to the specified level by using the
+ :c:func:`RTEMS_INTERRUPT_LEVEL` mode macro with a positive value in
+ ``mode_set``.
+
+An interrupt level of zero is associated with enabled interrupts on all target
+processors. The interrupt level portion of the task mode supports a maximum of
+256 interrupt levels. These levels are mapped onto the interrupt levels
+actually supported by the target processor in a processor dependent fashion.
+
+.. rubric:: RETURN VALUES:
+
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+:c:macro:`RTEMS_NOT_IMPLEMENTED`
+ The :c:macro:`RTEMS_NO_PREEMPT` was set in ``mode_set`` and setting the
+ preemption mode was requested by :c:macro:`RTEMS_PREEMPT_MASK` in ``mask``
+ and the system configuration had no implementation for this mode.
+
+:c:macro:`RTEMS_NOT_IMPLEMENTED`
+ The :c:func:`RTEMS_INTERRUPT_LEVEL` was set to a positive level in
+ ``mode_set`` and setting the interrupt level was requested by
+ :c:macro:`RTEMS_INTERRUPT_MASK` in ``mask`` and the system configuration
+ had no implementation for this mode.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within task context.
+
+* When the directive enables preemption for the calling task, another task may
+ preempt the calling task.
+
+* While thread dispatching is disabled, if the directive performs a thread
+ dispatch, then the fatal error with the fatal source
+ :ref:`INTERNAL_ERROR_CORE <FatalErrorSources>` and the fatal code
+ :ref:`INTERNAL_ERROR_BAD_THREAD_DISPATCH_DISABLE_LEVEL <internal_errors>`
+ will occur.
+
+.. Generated from spec:/rtems/task/if/wake-after
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_task_wake_after()
.. index:: delay a task for an interval
.. index:: wake up after an interval
-.. index:: rtems_task_wake_after
-.. _rtems_task_wake_after:
+.. _InterfaceRtemsTaskWakeAfter:
+
+rtems_task_wake_after()
+-----------------------
-TASK_WAKE_AFTER - Wake up after interval
-----------------------------------------
+Wakes up after an interval in :term:`clock ticks <clock tick>` or yields the
+processor.
-CALLING SEQUENCE:
- .. code-block:: c
+.. rubric:: CALLING SEQUENCE:
- rtems_status_code rtems_task_wake_after(
- rtems_interval ticks
- );
+.. code-block:: c
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+ rtems_status_code rtems_task_wake_after( rtems_interval ticks );
- * - ``RTEMS_SUCCESSFUL``
- - always successful
+.. rubric:: PARAMETERS:
-DESCRIPTION:
- This directive blocks the calling task for the specified number of system
- clock ticks. When the requested interval has elapsed, the task is made
- ready. The clock tick directives automatically updates the delay period.
+``ticks``
+ This parameter is the interval in :term:`clock ticks <clock tick>` to delay
+ the task or :c:macro:`RTEMS_YIELD_PROCESSOR` to yield the processor.
-NOTES:
- Setting the system date and time with the ``rtems_clock_set`` directive has
- no effect on a ``rtems_task_wake_after`` blocked task.
+.. rubric:: DESCRIPTION:
- A task may give up the processor and remain in the ready state by
- specifying a value of ``RTEMS_YIELD_PROCESSOR`` in ticks.
+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
+:c:macro:`RTEMS_YIELD_PROCESSOR` in ``ticks``.
- The maximum timer interval that can be specified is the maximum value which
- can be represented by the uint32_t type.
+.. rubric:: RETURN VALUES:
- A clock tick is required to support the functionality of this directive.
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+.. rubric:: NOTES:
+
+Setting the system date and time with the :ref:`InterfaceRtemsClockSet`
+directive and similar directives which set :term:`CLOCK_REALTIME` have no
+effect on a :ref:`InterfaceRtemsTaskWakeAfter` blocked task.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within task context.
+
+* The directive requires a :term:`Clock Driver`.
+
+* While thread dispatching is disabled, if the directive performs a thread
+ dispatch, then the fatal error with the fatal source
+ :ref:`INTERNAL_ERROR_CORE <FatalErrorSources>` and the fatal code
+ :ref:`INTERNAL_ERROR_BAD_THREAD_DISPATCH_DISABLE_LEVEL <internal_errors>`
+ will occur.
+
+.. Generated from spec:/rtems/task/if/wake-when
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_task_wake_when()
.. index:: delay a task until a wall time
.. index:: wake up at a wall time
-.. index:: rtems_task_wake_when
-.. _rtems_task_wake_when:
+.. _InterfaceRtemsTaskWakeWhen:
-TASK_WAKE_WHEN - Wake up when specified
----------------------------------------
+rtems_task_wake_when()
+----------------------
-CALLING SEQUENCE:
- .. code-block:: c
+Wakes up when specified.
- rtems_status_code rtems_task_wake_when(
- rtems_time_of_day *time_buffer
- );
+.. rubric:: CALLING SEQUENCE:
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+.. code-block:: c
- * - ``RTEMS_SUCCESSFUL``
- - awakened at date/time successfully
- * - ``RTEMS_INVALID_ADDRESS``
- - ``time_buffer`` is NULL
- * - ``RTEMS_INVALID_TIME_OF_DAY``
- - invalid time buffer
- * - ``RTEMS_NOT_DEFINED``
- - system date and time is not set
+ rtems_status_code rtems_task_wake_when( rtems_time_of_day *time_buffer );
-DESCRIPTION:
- This directive blocks a task until the date and time specified in
- time_buffer. At the requested date and time, the calling task will be
- unblocked and made ready to execute.
+.. rubric:: PARAMETERS:
-NOTES:
- The ticks portion of time_buffer structure is ignored. The timing
- granularity of this directive is a second.
+``time_buffer``
+ This parameter is the date and time to wake up.
- A clock tick is required to support the functionality of this directive.
+.. rubric:: DESCRIPTION:
-.. raw:: latex
+This directive blocks a task until the date and time specified in
+``time_buffer``. At the requested date and time, the calling task will be
+unblocked and made ready to execute.
- \clearpage
+.. rubric:: RETURN VALUES:
-.. _rtems_task_get_scheduler:
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
-TASK_GET_SCHEDULER - Get scheduler of a task
---------------------------------------------
+:c:macro:`RTEMS_NOT_DEFINED`
+ The system date and time was not set.
-CALLING SEQUENCE:
- .. code-block:: c
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``time_buffer`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
- rtems_status_code rtems_task_get_scheduler(
- rtems_id task_id,
- rtems_id *scheduler_id
- );
+:c:macro:`RTEMS_INVALID_CLOCK`
+ The time of day was invalid.
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+.. rubric:: NOTES:
- * - ``RTEMS_SUCCESSFUL``
- - successful operation
- * - ``RTEMS_INVALID_ADDRESS``
- - ``scheduler_id`` is NULL
- * - ``RTEMS_INVALID_ID``
- - invalid task id
+The ticks portion of ``time_buffer`` structure is ignored. The timing
+granularity of this directive is a second.
-DESCRIPTION:
- Returns the scheduler identifier of a task identified by ``task_id`` in
- ``scheduler_id``.
+.. rubric:: CONSTRAINTS:
-NOTES:
- None.
+The following constraints apply to this directive:
-.. raw:: latex
+* The directive may be called from within task context.
+
+* The directive requires a :term:`Clock Driver`.
+
+* While thread dispatching is disabled, if the directive performs a thread
+ dispatch, then the fatal error with the fatal source
+ :ref:`INTERNAL_ERROR_CORE <FatalErrorSources>` and the fatal code
+ :ref:`INTERNAL_ERROR_BAD_THREAD_DISPATCH_DISABLE_LEVEL <internal_errors>`
+ will occur.
- \clearpage
-
-.. _rtems_task_set_scheduler:
-.. _TASK_SET_SCHEDULER - Set scheduler of a task:
-
-TASK_SET_SCHEDULER - Set scheduler of a task
---------------------------------------------
-
-CALLING SEQUENCE:
- .. code-block:: c
-
- rtems_status_code rtems_task_set_scheduler(
- rtems_id task_id,
- rtems_id scheduler_id,
- rtems_task_priority priority
- );
-
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
-
- * - ``RTEMS_SUCCESSFUL``
- - successful operation
- * - ``RTEMS_INVALID_ID``
- - invalid task or scheduler id
- * - ``RTEMS_INVALID_PRIORITY``
- - invalid task priority
- * - ``RTEMS_RESOURCE_IN_USE``
- - the task is in the wrong state to perform a scheduler change
- * - ``RTEMS_UNSATISFIED``
- - the processor set of the scheduler is empty
- * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT``
- - not supported on remote tasks
-
-DESCRIPTION:
- Sets the scheduler of a task identified by ``task_id`` to the scheduler
- identified by ``scheduler_id``. The scheduler of a task is initialized to
- the scheduler of the task that created it. The priority of the task is set
- to ``priority``.
-
-NOTES:
- It is recommended to set the scheduler of a task before it is started or in
- case it is guaranteed that the task owns no resources. Otherwise, sporadic
- ``RTEMS_RESOURCE_IN_USE`` errors may occur.
-
-EXAMPLE:
- .. code-block:: c
- :linenos:
-
- #include <rtems.h>
- #include <assert.h>
-
- rtems_task task( rtems_task_argument arg );
-
- void example( void )
- {
- rtems_status_code sc;
- rtems_id task_id;
- rtems_id scheduler_id;
- rtems_name scheduler_name;
-
- scheduler_name = rtems_build_name( 'W', 'O', 'R', 'K' );
-
- sc = rtems_scheduler_ident( scheduler_name, &scheduler_id );
- assert( sc == RTEMS_SUCCESSFUL );
-
- sc = rtems_task_create(
- rtems_build_name( 'T', 'A', 'S', 'K' ),
- 1,
- RTEMS_MINIMUM_STACK_SIZE,
- RTEMS_DEFAULT_MODES,
- RTEMS_DEFAULT_ATTRIBUTES,
- &task_id
- );
- assert( sc == RTEMS_SUCCESSFUL );
-
- sc = rtems_task_set_scheduler( task_id, scheduler_id, 2 );
- assert( sc == RTEMS_SUCCESSFUL );
-
- sc = rtems_task_start( task_id, task, 0 );
- assert( sc == RTEMS_SUCCESSFUL );
- }
+.. Generated from spec:/rtems/task/if/get-scheduler
.. raw:: latex
- \clearpage
+ \clearpage
-.. _rtems_task_get_affinity:
+.. index:: rtems_task_get_scheduler()
-TASK_GET_AFFINITY - Get task processor affinity
------------------------------------------------
+.. _InterfaceRtemsTaskGetScheduler:
-CALLING SEQUENCE:
- .. code-block:: c
+rtems_task_get_scheduler()
+--------------------------
- rtems_status_code rtems_task_get_affinity(
- rtems_id id,
- size_t cpusetsize,
- cpu_set_t *cpuset
- );
+Gets the home scheduler of the task.
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+.. rubric:: CALLING SEQUENCE:
- * - ``RTEMS_SUCCESSFUL``
- - successful operation
- * - ``RTEMS_INVALID_ADDRESS``
- - ``cpuset`` is NULL
- * - ``RTEMS_INVALID_ID``
- - invalid task id
- * - ``RTEMS_INVALID_NUMBER``
- - the affinity set buffer is too small for the current processor affinity
- set of the task
+.. code-block:: c
-DESCRIPTION:
- Returns the current processor affinity set of the task in ``cpuset``. A
- set bit in the affinity set means that the task can execute on this
- processor and a cleared bit means the opposite.
+ rtems_status_code rtems_task_get_scheduler(
+ rtems_id task_id,
+ rtems_id *scheduler_id
+ );
-NOTES:
- The task processor affinity is initialized to the set of online processors.
+.. rubric:: PARAMETERS:
-.. raw:: latex
+``task_id``
+ This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF`
+ may be used to specify the calling task.
- \clearpage
-
-.. _rtems_task_set_affinity:
-
-TASK_SET_AFFINITY - Set task processor affinity
------------------------------------------------
-
-CALLING SEQUENCE:
- .. code-block:: c
-
- rtems_status_code rtems_task_set_affinity(
- rtems_id id,
- size_t cpusetsize,
- const cpu_set_t *cpuset
- );
-
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
-
- * - ``RTEMS_SUCCESSFUL``
- - successful operation
- * - ``RTEMS_INVALID_ADDRESS``
- - ``cpuset`` is NULL
- * - ``RTEMS_INVALID_ID``
- - invalid task id
- * - ``RTEMS_INVALID_NUMBER``
- - invalid processor affinity set
-
-DESCRIPTION:
- Sets the processor affinity set for the task specified by ``cpuset``. A
- set bit in the affinity set means that the task can execute on this
- processor and a cleared bit means the opposite.
-
-NOTES:
- This function will not change the scheduler of the task. The intersection
- of the processor affinity set and the set of processors owned by the
- scheduler of the task must be non-empty. It is not an error if the
- processor affinity set contains processors that are not part of the set of
- processors owned by the scheduler instance of the task. A task will simply
- not run under normal circumstances on these processors since the scheduler
- ignores them. Some locking protocols may temporarily use processors that
- are not included in the processor affinity set of the task. It is also not
- an error if the processor affinity set contains processors that are not
- part of the system.
-
- In case a scheduler without support for task affinites is used for the
- task, then the task processor affinity set must contain all online
- processors of the system. This prevents odd corner cases if processors are
- added/removed at run-time to/from scheduler instances.
+``scheduler_id``
+ This parameter is the pointer to an :c:type:`rtems_id` variable. When the
+ directive call is successful, the identifier of the :term:`home scheduler`
+ of the task will be stored in this variable.
-.. raw:: latex
+.. rubric:: DESCRIPTION:
+
+This directive returns the identifier of the :term:`home scheduler` of the task
+specified by ``task_id`` in ``scheduler_id``.
+
+.. rubric:: RETURN VALUES:
- \clearpage
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
-.. index:: iterate over all threads
-.. index:: rtems_task_iterate
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``scheduler_id`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
-.. _rtems_task_iterate:
+:c:macro:`RTEMS_INVALID_ID`
+ There was no task associated with the identifier specified by ``task_id``.
-TASK_ITERATE - Iterate Over Tasks
----------------------------------
+:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT`
+ The task resided on a remote node.
-CALLING SEQUENCE:
- .. code-block:: c
+.. rubric:: CONSTRAINTS:
- typedef bool ( *rtems_task_visitor )( rtems_tcb *tcb, void *arg );
+The following constraints apply to this directive:
- void rtems_task_iterate(
- rtems_task_visitor visitor,
- void *arg
- );
+* The directive may be called from within interrupt context.
-DIRECTIVE STATUS CODES:
- NONE
+* The directive may be called from within device driver initialization context.
-DESCRIPTION:
- Iterates over all tasks in the system. This operation covers all tasks of
- all APIs. The user should be careful in accessing the contents of the
- thread control block :c:data:`tcb`. The visitor argument :c:data:`arg` is
- passed to all invocations of :c:data:`visitor` in addition to the thread
- control block. The iteration stops immediately in case the visitor
- function returns true.
+* The directive may be called from within task context.
-NOTES:
- Must be called from task context. This operation obtains and releases the
- objects allocator lock. The task visitor is called while owning the objects
- allocator lock. It is possible to perform blocking operations in the task
- visitor, however, take care that no deadlocks via the object allocator lock
- can occur.
+* The directive will not cause the calling task to be preempted.
-Deprecated Directives
-=====================
+.. Generated from spec:/rtems/task/if/set-scheduler
.. raw:: latex
- \clearpage
+ \clearpage
+
+.. index:: rtems_task_set_scheduler()
+
+.. _InterfaceRtemsTaskSetScheduler:
+
+rtems_task_set_scheduler()
+--------------------------
-.. index:: rtems_iterate_over_all_threads
+Sets the home scheduler for the task.
-.. _rtems_iterate_over_all_threads:
+.. rubric:: CALLING SEQUENCE:
-ITERATE_OVER_ALL_THREADS - Iterate Over Tasks
----------------------------------------------
+.. code-block:: c
-.. warning::
+ rtems_status_code rtems_task_set_scheduler(
+ rtems_id task_id,
+ rtems_id scheduler_id,
+ rtems_task_priority priority
+ );
- This directive is deprecated. Its use is unsafe. Use
- :ref:`rtems_task_iterate` instead.
+.. rubric:: PARAMETERS:
-CALLING SEQUENCE:
- .. code-block:: c
+``task_id``
+ This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF`
+ may be used to specify the calling task.
- typedef void (*rtems_per_thread_routine)(Thread_Control *the_thread);
- void rtems_iterate_over_all_threads(
- rtems_per_thread_routine routine
- );
+``scheduler_id``
+ This parameter is the scheduler identifier of the new :term:`home
+ scheduler` for the task specified by ``task_id``.
+
+``priority``
+ This parameter is the new real priority for the task with respect to the
+ scheduler specified by ``scheduler_id``.
+
+.. rubric:: DESCRIPTION:
+
+This directive sets the :term:`home scheduler` to the scheduler specified by
+``scheduler_id`` for the task specified by ``task_id``.
+
+.. rubric:: RETURN VALUES:
+
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_ID`
+ There was no scheduler associated with the identifier specified by
+ ``scheduler_id``.
-DIRECTIVE STATUS CODES:
- NONE
+:c:macro:`RTEMS_INVALID_PRIORITY`
+ There task priority specified in ``priority`` was invalid with respect to
+ the scheduler specified by ``scheduler_id``.
-DESCRIPTION:
- This directive iterates over all of the existant threads in the system and
- invokes ``routine`` on each of them. The user should be careful in
- accessing the contents of ``the_thread``.
+:c:macro:`RTEMS_INVALID_ID`
+ There was no task associated with the identifier specified by ``task_id``.
- This routine is intended for use in diagnostic utilities and is not
- intented for routine use in an operational system.
+:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT`
+ The task resided on a remote node.
-NOTES:
- There is **no protection** while this routine is called. The thread
- control block may be in an inconsistent state or may change due to
- interrupts or activity on other processors.
+.. rubric:: CONSTRAINTS:
-Removed Directives
-==================
+The following constraints apply to this directive:
+
+* The directive may be called from within interrupt context.
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive may change the priority of a task. This may cause the calling
+ task to be preempted.
+
+.. Generated from spec:/rtems/task/if/get-affinity
.. raw:: latex
- \clearpage
+ \clearpage
+
+.. index:: rtems_task_get_affinity()
+
+.. _InterfaceRtemsTaskGetAffinity:
+
+rtems_task_get_affinity()
+-------------------------
+
+Gets the processor affinity of the task.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_task_get_affinity(
+ rtems_id id,
+ size_t cpusetsize,
+ cpu_set_t *cpuset
+ );
-.. index:: get task notepad entry
-.. index:: rtems_task_get_note
+.. rubric:: PARAMETERS:
-.. _rtems_task_get_note:
+``id``
+ This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF`
+ may be used to specify the calling task.
-TASK_GET_NOTE - Get task notepad entry
---------------------------------------
+``cpusetsize``
+ This parameter is the size of the referenced processor set variable in
+ bytes.
-.. warning::
+``cpuset``
+ This parameter is the pointer to a processor set variable. When the
+ directive call is successful, the processor affinity set of the task will
+ be stored in this variable. A set bit in the processor set means that the
+ corresponding processor is in the processor affinity set of the task,
+ otherwise the bit is cleared.
- This directive was removed in RTEMS 5.1.
+.. rubric:: DESCRIPTION:
-CALLING SEQUENCE:
- .. code-block:: c
+This directive returns the processor affinity of the task in ``cpuset`` of the
+task specified by ``id``.
- rtems_status_code rtems_task_get_note(
- rtems_id id,
- uint32_t notepad,
- uint32_t *note
- );
+.. rubric:: RETURN VALUES:
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
- * - ``RTEMS_SUCCESSFUL``
- - note value obtained successfully
- * - ``RTEMS_INVALID_ADDRESS``
- - ``note`` parameter is NULL
- * - ``RTEMS_INVALID_ID``
- - invalid task id
- * - ``RTEMS_INVALID_NUMBER``
- - invalid notepad location
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``cpuset`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
-DESCRIPTION:
- This directive returns the note contained in the notepad location of the
- task specified by id.
+:c:macro:`RTEMS_INVALID_ID`
+ There was no task associated with the identifier specified by ``id``.
-NOTES:
- This directive will not cause the running task to be preempted.
+:c:macro:`RTEMS_INVALID_SIZE`
+ The provided processor set was too small for the processor affinity set of
+ the task.
- If id is set to ``RTEMS_SELF``, the calling task accesses its own notepad.
+:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT`
+ The task resided on a remote node.
- The sixteen notepad locations can be accessed using the constants
- ``RTEMS_NOTEPAD_0`` through ``RTEMS_NOTEPAD_15``.
+.. rubric:: CONSTRAINTS:
- Getting a note of a global task which does not reside on the local node
- will generate a request to the remote node to obtain the notepad entry of
- the specified task.
+The following constraints apply to this directive:
+
+* The directive may be called from within interrupt context.
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/task/if/set-affinity
.. raw:: latex
- \clearpage
+ \clearpage
-.. index:: set task notepad entry
-.. index:: rtems_task_set_note
+.. index:: rtems_task_set_affinity()
-.. _rtems_task_set_note:
+.. _InterfaceRtemsTaskSetAffinity:
-TASK_SET_NOTE - Set task notepad entry
---------------------------------------
+rtems_task_set_affinity()
+-------------------------
-.. warning::
+Sets the processor affinity of the task.
- This directive was removed in RTEMS 5.1.
+.. rubric:: CALLING SEQUENCE:
-CALLING SEQUENCE:
- .. code-block:: c
+.. code-block:: c
- rtems_status_code rtems_task_set_note(
- rtems_id id,
- uint32_t notepad,
- uint32_t note
- );
+ rtems_status_code rtems_task_set_affinity(
+ rtems_id id,
+ size_t cpusetsize,
+ const cpu_set_t *cpuset
+ );
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+.. rubric:: PARAMETERS:
- * - ``RTEMS_SUCCESSFUL``
- - note set successfully
- * - ``RTEMS_INVALID_ID``
- - invalid task id
- * - ``RTEMS_INVALID_NUMBER``
- - invalid notepad location
+``id``
+ This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF`
+ may be used to specify the calling task.
-DESCRIPTION:
- This directive sets the notepad entry for the task specified by id to the
- value note.
+``cpusetsize``
+ This parameter is the size of the referenced processor set variable in
+ bytes.
-NOTES:
- If ``id`` is set to ``RTEMS_SELF``, the calling task accesses its own
- notepad.
+``cpuset``
+ This parameter is the pointer to a processor set variable. The processor
+ set defines the new processor affinity set of the task. A set bit in the
+ processor set means that the corresponding processor shall be in the
+ processor affinity set of the task, otherwise the bit shall be cleared.
- This directive will not cause the running task to be preempted.
+.. rubric:: DESCRIPTION:
- The sixteen notepad locations can be accessed using the constants
- ``RTEMS_NOTEPAD_0`` through ``RTEMS_NOTEPAD_15``.
+This directive sets the processor affinity of the task specified by ``id``.
- Setting a note of a global task which does not reside on the local node
- will generate a request to the remote node to set the notepad entry of the
- specified task.
+.. rubric:: RETURN VALUES:
-.. raw:: latex
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``cpuset`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+:c:macro:`RTEMS_INVALID_ID`
+ There was no task associated with the identifier specified by ``id``.
+
+:c:macro:`RTEMS_INVALID_NUMBER`
+ The referenced processor set was not a valid new processor affinity set for
+ the task.
+
+:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT`
+ The task resided on a remote node.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within interrupt context.
- \clearpage
-
-.. index:: per-task variable
-.. index:: task private variable
-.. index:: task private data
-.. index:: rtems_task_variable_add
-
-.. _rtems_task_variable_add:
-
-TASK_VARIABLE_ADD - Associate per task variable
------------------------------------------------
-
-.. warning::
-
- This directive was removed in RTEMS 5.1.
-
-CALLING SEQUENCE:
- .. code-block:: c
-
- rtems_status_code rtems_task_variable_add(
- rtems_id tid,
- void **task_variable,
- void (*dtor)(void *)
- );
-
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
-
- * - ``RTEMS_SUCCESSFUL``
- - per task variable added successfully
- * - ``RTEMS_INVALID_ADDRESS``
- - ``task_variable`` is NULL
- * - ``RTEMS_INVALID_ID``
- - invalid task id
- * - ``RTEMS_NO_MEMORY``
- - invalid task id
- * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT``
- - not supported on remote tasks
-
-DESCRIPTION:
- This directive adds the memory location specified by the ptr argument to
- the context of the given task. The variable will then be private to the
- task. The task can access and modify the variable, but the modifications
- will not appear to other tasks, and other tasks' modifications to that
- variable will not affect the value seen by the task. This is accomplished
- by saving and restoring the variable's value each time a task switch occurs
- to or from the calling task. If the dtor argument is non-NULL it specifies
- the address of a 'destructor' function which will be called when the task
- is deleted. The argument passed to the destructor function is the task's
- value of the variable.
-
-NOTES:
- Task variables increase the context switch time to and from the tasks that
- own them so it is desirable to minimize the number of task variables. One
- efficient method is to have a single task variable that is a pointer to a
- dynamically allocated structure containing the task's private 'global'
- data. In this case the destructor function could be 'free'.
-
- Per-task variables are disabled in SMP configurations and this service is
- not available.
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive may change the processor affinity of a task. This may cause
+ the calling task to be preempted.
+
+.. Generated from spec:/rtems/task/if/iterate
.. raw:: latex
- \clearpage
+ \clearpage
+
+.. index:: rtems_task_iterate()
+
+.. _InterfaceRtemsTaskIterate:
+
+rtems_task_iterate()
+--------------------
+
+Iterates over all tasks and invokes the visitor routine for each task.
-.. index:: get per-task variable
-.. index:: obtain per-task variable
-.. index:: rtems_task_variable_get
+.. rubric:: CALLING SEQUENCE:
-.. _rtems_task_variable_get:
+.. code-block:: c
-TASK_VARIABLE_GET - Obtain value of a per task variable
--------------------------------------------------------
+ void rtems_task_iterate( rtems_task_visitor visitor, void *arg );
-.. warning::
+.. rubric:: PARAMETERS:
- This directive was removed in RTEMS 5.1.
+``visitor``
+ This parameter is the visitor routine invoked for each task.
-CALLING SEQUENCE:
- .. code-block:: c
+``arg``
+ This parameter is the argument passed to each visitor routine invocation
+ during the iteration.
- rtems_status_code rtems_task_variable_get(
- rtems_id tid,
- void **task_variable,
- void **task_variable_value
- );
+.. rubric:: DESCRIPTION:
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+This directive iterates over all tasks in the system. This operation covers
+all tasks of all APIs. The user should be careful in accessing the contents of
+the :term:`TCB`. The visitor argument ``arg`` is passed to all invocations of
+``visitor`` in addition to the TCB. The iteration stops immediately in case the
+visitor routine returns true.
- * - ``RTEMS_SUCCESSFUL``
- - per task variable obtained successfully
- * - ``RTEMS_INVALID_ADDRESS``
- - ``task_variable`` is NULL
- * - ``RTEMS_INVALID_ADDRESS``
- - ``task_variable_value`` is NULL
- * - ``RTEMS_INVALID_ADDRESS``
- - ``task_variable`` is not found
- * - ``RTEMS_NO_MEMORY``
- - invalid task id
- * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT``
- - not supported on remote tasks
+.. rubric:: NOTES:
-DESCRIPTION:
- This directive looks up the private value of a task variable for a
- specified task and stores that value in the location pointed to by the
- result argument. The specified task is usually not the calling task, which
- can get its private value by directly accessing the variable.
+The visitor routine is invoked while owning the objects allocator lock. It is
+allowed to perform blocking operations in the visitor routine, however, care
+must be taken so that no deadlocks via the object allocator lock can occur.
-NOTES:
- If you change memory which ``task_variable_value`` points to, remember to
- declare that memory as volatile, so that the compiler will optimize it
- correctly. In this case both the pointer ``task_variable_value`` and data
- referenced by ``task_variable_value`` should be considered volatile.
+.. rubric:: CONSTRAINTS:
- Per-task variables are disabled in SMP configurations and this service is
- not available.
+The following constraints apply to this directive:
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive may obtain and release the object allocator mutex. This may
+ cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/task/if/storage-size
.. raw:: latex
- \clearpage
+ \clearpage
+
+.. index:: RTEMS_TASK_STORAGE_SIZE()
-.. index:: per-task variable
-.. index:: task private variable
-.. index:: task private data
-.. index:: rtems_task_variable_delete
+.. _InterfaceRTEMSTASKSTORAGESIZE:
-.. _rtems_task_variable_delete:
+RTEMS_TASK_STORAGE_SIZE()
+-------------------------
-TASK_VARIABLE_DELETE - Remove per task variable
------------------------------------------------
+Gets the recommended task storage area size for the size and task attributes.
-.. warning::
+.. rubric:: CALLING SEQUENCE:
- This directive was removed in RTEMS 5.1.
+.. code-block:: c
-CALLING SEQUENCE:
- .. code-block:: c
+ #define RTEMS_TASK_STORAGE_SIZE( size, attributes )
- rtems_status_code rtems_task_variable_delete(
- rtems_id id,
- void **task_variable
- );
+.. rubric:: PARAMETERS:
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+``size``
+ This parameter is the size dedicated to the task stack and thread-local
+ storage in bytes.
- * - ``RTEMS_SUCCESSFUL``
- - per task variable deleted successfully
- * - ``RTEMS_INVALID_ID``
- - invalid task id
- * - ``RTEMS_NO_MEMORY``
- - invalid task id
- * - ``RTEMS_INVALID_ADDRESS``
- - ``task_variable`` is NULL
- * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT``
- - not supported on remote tasks
+``attributes``
+ This parameter is the attribute set of the task using the storage area.
-DESCRIPTION:
- This directive removes the given location from a task's context.
+.. rubric:: RETURN VALUES:
-NOTES:
- Per-task variables are disabled in SMP configurations and this service is
- not available.
+Returns the recommended task storage area size calculated from the input
+parameters.
diff --git a/c-user/task/introduction.rst b/c-user/task/introduction.rst
index 449b335..5d6eba4 100644
--- a/c-user/task/introduction.rst
+++ b/c-user/task/introduction.rst
@@ -1,50 +1,106 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
-.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de)
+.. Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR)
+
+.. This file is part of the RTEMS quality process and was automatically
+.. generated. If you find something that needs to be fixed or
+.. worded better please post a report or patch to an RTEMS mailing list
+.. or raise a bug report:
+..
+.. https://www.rtems.org/bugs.html
+..
+.. For information on updating and regenerating please refer to the How-To
+.. section in the Software Requirements Engineering chapter of the
+.. RTEMS Software Engineering manual. The manual is provided as a part of
+.. a release. For development sources please refer to the online
+.. documentation at:
+..
+.. https://docs.rtems.org
+
+.. Generated from spec:/rtems/task/if/group
+
+.. _TaskManagerIntroduction:
Introduction
============
-The task manager provides a comprehensive set of directives to create, delete,
-and administer tasks. The directives provided by the task manager are:
+.. The following list was generated from:
+.. spec:/rtems/task/if/create
+.. spec:/rtems/task/if/construct
+.. spec:/rtems/task/if/ident
+.. spec:/rtems/task/if/self
+.. spec:/rtems/task/if/start
+.. spec:/rtems/task/if/restart
+.. spec:/rtems/task/if/delete
+.. spec:/rtems/task/if/exit
+.. spec:/rtems/task/if/suspend
+.. spec:/rtems/task/if/resume
+.. spec:/rtems/task/if/is-suspended
+.. spec:/rtems/task/if/set-priority
+.. spec:/rtems/task/if/get-priority
+.. spec:/rtems/task/if/mode
+.. spec:/rtems/task/if/wake-after
+.. spec:/rtems/task/if/wake-when
+.. spec:/rtems/task/if/get-scheduler
+.. spec:/rtems/task/if/set-scheduler
+.. spec:/rtems/task/if/get-affinity
+.. spec:/rtems/task/if/set-affinity
+.. spec:/rtems/task/if/iterate
+.. spec:/rtems/task/if/storage-size
-- :ref:`rtems_task_create`
+The Task Manager provides a comprehensive set of directives to create, delete,
+and administer tasks. The directives provided by the Task Manager are:
-- :ref:`rtems_task_ident`
+* :ref:`InterfaceRtemsTaskCreate` - Creates a task.
-- :ref:`rtems_task_self`
+* :ref:`InterfaceRtemsTaskConstruct` - Constructs a task from the specified
+ task configuration.
-- :ref:`rtems_task_start`
+* :ref:`InterfaceRtemsTaskIdent` - Identifies a task by the object name.
-- :ref:`rtems_task_restart`
+* :ref:`InterfaceRtemsTaskSelf` - Gets the task identifier of the calling task.
-- :ref:`rtems_task_delete`
+* :ref:`InterfaceRtemsTaskStart` - Starts the task.
-- :ref:`rtems_task_exit`
+* :ref:`InterfaceRtemsTaskRestart` - Restarts the task.
-- :ref:`rtems_task_suspend`
+* :ref:`InterfaceRtemsTaskDelete` - Deletes the task.
-- :ref:`rtems_task_resume`
+* :ref:`InterfaceRtemsTaskExit` - Deletes the calling task.
-- :ref:`rtems_task_is_suspended`
+* :ref:`InterfaceRtemsTaskSuspend` - Suspends the task.
-- :ref:`rtems_task_set_priority`
+* :ref:`InterfaceRtemsTaskResume` - Resumes the task.
-- :ref:`rtems_task_get_priority`
+* :ref:`InterfaceRtemsTaskIsSuspended` - Checks if the task is suspended.
-- :ref:`rtems_task_mode`
+* :ref:`InterfaceRtemsTaskSetPriority` - Sets the real priority or gets the
+ current priority of the task.
-- :ref:`rtems_task_wake_after`
+* :ref:`InterfaceRtemsTaskGetPriority` - Gets the current priority of the task
+ with respect to the scheduler.
-- :ref:`rtems_task_wake_when`
+* :ref:`InterfaceRtemsTaskMode` - Gets and optionally sets the mode of the
+ calling task.
-- :ref:`rtems_task_get_scheduler`
+* :ref:`InterfaceRtemsTaskWakeAfter` - Wakes up after an interval in
+ :term:`clock ticks <clock tick>` or yields the processor.
-- :ref:`rtems_task_set_scheduler`
+* :ref:`InterfaceRtemsTaskWakeWhen` - Wakes up when specified.
-- :ref:`rtems_task_get_affinity`
+* :ref:`InterfaceRtemsTaskGetScheduler` - Gets the home scheduler of the task.
-- :ref:`rtems_task_set_affinity`
+* :ref:`InterfaceRtemsTaskSetScheduler` - Sets the home scheduler for the task.
-- :ref:`rtems_task_iterate`
+* :ref:`InterfaceRtemsTaskGetAffinity` - Gets the processor affinity of the
+ task.
+
+* :ref:`InterfaceRtemsTaskSetAffinity` - Sets the processor affinity of the
+ task.
+
+* :ref:`InterfaceRtemsTaskIterate` - Iterates over all tasks and invokes the
+ visitor routine for each task.
+
+* :ref:`InterfaceRTEMSTASKSTORAGESIZE` - Gets the recommended task storage area
+ size for the size and task attributes.
diff --git a/c-user/timer/directives.rst b/c-user/timer/directives.rst
index b5ec8f4..2affe42 100644
--- a/c-user/timer/directives.rst
+++ b/c-user/timer/directives.rst
@@ -212,8 +212,9 @@ Cancels the timer.
This directive cancels the timer specified by ``id``. This timer will be
reinitiated by the next invocation of :ref:`InterfaceRtemsTimerReset`,
-:ref:`InterfaceRtemsTimerFireAfter`, or :ref:`InterfaceRtemsTimerFireWhen` with
-the same timer identifier.
+:ref:`InterfaceRtemsTimerFireAfter`, :ref:`InterfaceRtemsTimerFireWhen`,
+:ref:`InterfaceRtemsTimerServerFireAfter`, or
+:ref:`InterfaceRtemsTimerServerFireWhen` with the same timer identifier.
.. rubric:: RETURN VALUES:
@@ -395,7 +396,7 @@ Fires the timer at the time of day.
rtems_status_code rtems_timer_fire_when(
rtems_id id,
- rtems_time_of_day *wall_time,
+ const rtems_time_of_day *wall_time,
rtems_timer_service_routine_entry routine,
void *user_data
);
@@ -648,7 +649,7 @@ Fires the timer at the time of day using the Timer Server.
rtems_status_code rtems_timer_server_fire_when(
rtems_id id,
- rtems_time_of_day *wall_time,
+ const rtems_time_of_day *wall_time,
rtems_timer_service_routine_entry routine,
void *user_data
);
diff --git a/c-user/user-extensions/background.rst b/c-user/user-extensions/background.rst
index 2dc2577..5aa747b 100644
--- a/c-user/user-extensions/background.rst
+++ b/c-user/user-extensions/background.rst
@@ -109,15 +109,10 @@ and release the extension buffers.
Order of Invocation
-------------------
-The user extensions are invoked in either `forward` or `reverse` order. In
-forward order, the user extensions of initial extension sets are invoked before
-the user extensions of the dynamic extension sets. The forward order of
-initial extension sets is defined by the initial extension sets table index.
-The forward order of dynamic extension sets is defined by the order in which
-the dynamic extension sets were created. The reverse order is defined
-accordingly. By invoking the user extensions in this order, extensions can be
-built upon one another. At the following system events, the user extensions
-are invoked in `forward` order
+The user extensions are invoked in either :term:`extension forward order` or
+:term:`extension reverse order`. By invoking the user extensions in these
+orders, extensions can be built upon one another. At the following system
+events, the user extensions are invoked in `forward` order
- thread creation,
diff --git a/eng/req/items.rst b/eng/req/items.rst
index 64a32cb..db39547 100644
--- a/eng/req/items.rst
+++ b/eng/req/items.rst
@@ -1023,10 +1023,6 @@ rationale
The attribute value shall be an optional string. If the value is present,
then it shall state the rationale or justification of the constraint.
-scope
- The attribute value shall be a string. It shall be the scope of the
- constraint.
-
text
The attribute value shall be a :ref:`SpecTypeRequirementText`. It shall
state the constraint.
@@ -1180,9 +1176,7 @@ appl-config-option-type
application configuration option type.
description
- The attribute value shall be an :ref:`SpecTypeInterfaceDescription`. The
- :ref:`SpecTypeApplicationConfigurationValueOptionItemType` items have an
- attribute for constraints.
+ The attribute value shall be an :ref:`SpecTypeInterfaceDescription`.
name
The attribute value shall be an
@@ -1191,10 +1185,6 @@ name
notes
The attribute value shall be an :ref:`SpecTypeInterfaceNotes`.
-text
- The attribute value shall be a :ref:`SpecTypeRequirementText`. It shall
- state the requirement for the application configuration option.
-
This type is refined by the following types:
* :ref:`SpecTypeApplicationConfigurationFeatureEnableOptionItemType`
@@ -1245,10 +1235,6 @@ This set of attributes specifies application configuration initializer or
integer option. All explicit attributes shall be specified. The explicit
attributes for this type are:
-constraints
- The attribute value shall be an
- :ref:`SpecTypeApplicationConfigurationOptionConstraintSet`.
-
default-value
The attribute value shall be an :ref:`SpecTypeIntegerOrString`. It shall
describe the default value of the application configuration option.
@@ -1575,6 +1561,9 @@ This type refines the following types:
the value is ``unspecified-function``
* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if
+ the value is ``unspecified-group``
+
+* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if
the value is ``unspecified-type``
This set of attributes specifies an unspecified interface. All explicit
@@ -1584,9 +1573,8 @@ name
The attribute value shall be a string. It shall be the name of the
unspecified interface.
-reference
- The attribute value shall be an optional string. If the value is present,
- then it shall be an URL to the standard or specification of the interface.
+references
+ The attribute value shall be an :ref:`SpecTypeInterfaceReferencesSet`.
.. _SpecTypeInterfaceVariableItemType:
@@ -2484,6 +2472,10 @@ test-local-includes
The attribute value shall be a list of strings. It shall be a list of
header files included via ``#include "..."``.
+test-suite-name
+ The attribute value shall be a string. It shall be the name of the test
+ suite.
+
test-target
The attribute value shall be a string. It shall be the path to the
generated target test suite source file.
@@ -2900,39 +2892,6 @@ This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the
value is ``appl-config-group-member``. It defines the application configuration
group membership role of links.
-.. _SpecTypeApplicationConfigurationOptionConstraintSet:
-
-Application Configuration Option Constraint Set
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This set of attributes defines application configuration option constraints.
-Additional constraints can be added through the links of the item using the
-:ref:`SpecTypeConstraintLinkRole`. None of the explicit attributes is
-mandatory, they are all optional. The explicit attributes for this type are:
-
-max
- The attribute value shall be an :ref:`SpecTypeIntegerOrString`. It shall be
- the maximum value of the application configuration option.
-
-min
- The attribute value shall be an :ref:`SpecTypeIntegerOrString`. It shall be
- the minimum value of the application configuration option.
-
-set
- The attribute value shall be a list. Each list element shall be an
- :ref:`SpecTypeIntegerOrString`. It shall be the set of valid values for the
- application configuration option.
-
-texts
- The attribute value shall be a list. Each list element shall be a
- :ref:`SpecTypeRequirementText`. It shall be a list of constraints specific
- to this application configuration option. For general constraints, use a
- link with the :ref:`SpecTypeConstraintLinkRole` to a constraint item.
-
-This type is used by the following types:
-
-* :ref:`SpecTypeApplicationConfigurationValueOptionItemType`
-
.. _SpecTypeApplicationConfigurationOptionName:
Application Configuration Option Name
@@ -3722,8 +3681,6 @@ A value of this type shall be of one of the following variants:
This type is used by the following types:
-* :ref:`SpecTypeApplicationConfigurationOptionConstraintSet`
-
* :ref:`SpecTypeApplicationConfigurationValueOptionItemType`
* :ref:`SpecTypeBuildOptionAction`
@@ -4317,6 +4274,20 @@ value is ``interface-placement``. It defines the interface placement role of
links. It is used to indicate that an interface definition is placed into an
interface container, for example a header file.
+.. _SpecTypeInterfaceReferencesSet:
+
+Interface References Set
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+This set of attributes defines references for the interface. Generic attributes
+may be specified. Each generic attribute key shall be a :ref:`SpecTypeName`.
+Each generic attribute value shall be a string. The key defines the reference
+kind. The value shall be a kind-specific reference target.
+
+This type is used by the following types:
+
+* :ref:`SpecTypeInterfaceUnspecifiedItemType`
+
.. _SpecTypeInterfaceReturnDirective:
Interface Return Directive
@@ -4419,6 +4390,8 @@ This type is refined by the following types:
* :ref:`SpecTypeSpecificationRefinementLinkRole`
+* :ref:`SpecTypeUnitTestLinkRole`
+
This type is used by the following types:
* :ref:`SpecTypeRootItemType`
@@ -4449,6 +4422,8 @@ This type is used by the following types:
* :ref:`SpecTypeInterfaceItemType`
+* :ref:`SpecTypeInterfaceReferencesSet`
+
* :ref:`SpecTypeLink`
* :ref:`SpecTypeNonFunctionalRequirementItemType`
@@ -4683,10 +4658,6 @@ This type is used by the following types:
* :ref:`SpecTypeApplicationConfigurationGroupItemType`
-* :ref:`SpecTypeApplicationConfigurationOptionConstraintSet`
-
-* :ref:`SpecTypeApplicationConfigurationOptionItemType`
-
* :ref:`SpecTypeConstraintItemType`
* :ref:`SpecTypeInterfaceGroupItemType`
@@ -5442,7 +5413,9 @@ checks
links
The attribute value shall be a list. Each list element shall be a
- :ref:`SpecTypeLink`.
+ :ref:`SpecTypeLink`. The links should use the
+ :ref:`SpecTypeRequirementValidationLinkRole` for validation tests and the
+ :ref:`SpecTypeUnitTestLinkRole` for unit tests.
This type is used by the following types:
@@ -5466,7 +5439,9 @@ code
links
The attribute value shall be a list. Each list element shall be a
- :ref:`SpecTypeLink`.
+ :ref:`SpecTypeLink`. The links should use the
+ :ref:`SpecTypeRequirementValidationLinkRole` for validation tests and the
+ :ref:`SpecTypeUnitTestLinkRole` for unit tests.
This type is used by the following types:
@@ -5629,3 +5604,18 @@ item UID.
This type is used by the following types:
* :ref:`SpecTypeLink`
+
+.. _SpecTypeUnitTestLinkRole:
+
+Unit Test Link Role
+^^^^^^^^^^^^^^^^^^^
+
+This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the
+value is ``unit-test``. It defines the unit test role of links. For unit tests
+the link target should be the :ref:`SpecTypeInterfaceDomainItemType` containing
+the software unit. All explicit attributes shall be specified. The explicit
+attributes for this type are:
+
+name
+ The attribute value shall be a string. It shall be the name of the tested
+ software unit.
diff --git a/legacy-networking/index.rst b/legacy-networking/index.rst
index b85119d..acbfd35 100644
--- a/legacy-networking/index.rst
+++ b/legacy-networking/index.rst
@@ -22,6 +22,7 @@ RTEMS Legacy Network User Manual (|version|).
:numbered:
preface
+ quick_start
network_task_structure
networking_driver
using_networking_rtems_app
diff --git a/legacy-networking/quick_start.rst b/legacy-networking/quick_start.rst
new file mode 100644
index 0000000..edc3b29
--- /dev/null
+++ b/legacy-networking/quick_start.rst
@@ -0,0 +1,33 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+Quick Start
+#######
+
+This legacy networking is now a standalone repository and needs to be built
+separately.
+
+The repository can be found here: https://git.rtems.org/rtems-net-legacy/
+
+There's an RSB recipe to build rtems-net-legacy. Here's an example of building
+rtems-net-legacy using RSB for powerpc/beatnik BSP with rtems version 6:
+
+ .. code-block:: shell
+
+ ../source-builder/sb-set-builder \
+ --prefix=/path/to/rtems/prefix \
+ 6/rtems-net-legacy \
+ --host=powerpc-rtems6 \
+ --with-rtems-bsp=beatnik
+
+Manually building the rtems-net-legacy repo:
+
+ .. code-block:: shell
+
+ git submodule init
+ git submodule update
+ ./waf configure --prefix=/path/to/rtems/prefix
+ ./waf
+ ./waf install
+
+Please refer to README.waf in rtems-net-legacy repository for more details on
+using waf with legacy networking.
diff --git a/user/bsps/arm/beagle.rst b/user/bsps/arm/beagle.rst
index 5789bb8..696b89d 100644
--- a/user/bsps/arm/beagle.rst
+++ b/user/bsps/arm/beagle.rst
@@ -67,23 +67,38 @@ Add the following to a file named uEnv.txt:
I2C Driver
----------
-The Beagle has the `i2c-0` device registered at initialization. For registering
-`i2c-1` and `i2c-2` ``bbb_register_i2c_1()`` and
-``bbb_register_i2c_2()`` wrapper functions are respectively used.
+The Beagle i2c initialization is based on the device tree. To initialize a i2c
+device, the user has to enable the respective node in the device tree using
+overlays.
-For registering an I2C device with a custom path (say `/dev/i2c-3`) the
-function ``am335x_i2c_bus_register()`` has to be used.
+For registering an I2C device with a custom path (say `/dev/i2c-eeprom`) an
+overlay has to be provided. The overlay must add an additional attribute
+`rtems,path` with the custom path as value to the respective i2c node.
-The function prototype is given below:
+For example,
-.. code-block:: C
+.. code-block::
+ /dts-v1/;
+
+ / {
+ compatible = "ti,am335x-bone-black", "ti,am335x-bone", "ti,am33xx";
+
+ fragment@0 {
+ target = <0xffffffff>;
+
+ __overlay__ {
+ compatible = "rtems,bsp-i2c", "ti,omap4-i2c";
+ status = "okay";
+ rtems,path = "/dev/i2c-eeprom";
+ };
+ };
+
+ __fixups__ {
+ i2c0 = "/fragment@0:target:0";
+ };
+ };
- int am335x_i2c_bus_register(
- const char *bus_path,
- uintptr_t register_base,
- uint32_t input_clock,
- rtems_vector_number irq
- );
+The above example registers a custom path `/dev/i2c-eeprom` for i2c0.
SPI Driver
----------