summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--c-user/clock/background.rst85
-rw-r--r--c-user/clock/directives.rst38
-rw-r--r--c-user/config/general.rst6
-rw-r--r--c-user/config/mpci.rst17
-rw-r--r--c-user/config/posix-api.rst28
-rw-r--r--c-user/config/scheduler-general.rst93
-rw-r--r--c-user/interrupt/directives.rst7
-rw-r--r--c-user/interrupt/introduction.rst2
-rw-r--r--c-user/symmetric_multiprocessing_services.rst23
-rw-r--r--c-user/task/directives.rst6
-rw-r--r--cpu-supplement/aarch64.rst5
-rw-r--r--cpu-supplement/arm.rst6
-rw-r--r--cpu-supplement/index.rst1
-rw-r--r--cpu-supplement/sparc.rst57
-rw-r--r--cpu-supplement/xilinx_microblaze.rst52
-rw-r--r--eng/release-process.rst72
-rw-r--r--eng/req/howto.rst103
-rw-r--r--eng/req/items.rst20
-rw-r--r--eng/tester.rst13
-rw-r--r--user/bsps/aarch64/xilinx-zynqmp.rst167
-rw-r--r--user/bsps/arm/bsp-stm32h7.rst32
-rw-r--r--user/bsps/arm/imxrt.rst6
-rw-r--r--user/bsps/bsps-arm.rst1
-rw-r--r--user/bsps/bsps-microblaze.rst149
-rw-r--r--user/hosts/posix.rst14
-rw-r--r--user/overview/index.rst7
26 files changed, 816 insertions, 194 deletions
diff --git a/c-user/clock/background.rst b/c-user/clock/background.rst
index 64e8311..ded0461 100644
--- a/c-user/clock/background.rst
+++ b/c-user/clock/background.rst
@@ -1,5 +1,6 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
+.. Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
Background
@@ -8,20 +9,28 @@ Background
Required Support
----------------
-For the features provided by the clock manager to be utilized, periodic timer
-interrupts are required. Therefore, a real-time clock or hardware timer is
-necessary to create the timer interrupts. The clock tick directive
-is normally called by the timer ISR to announce to RTEMS that a system clock
-tick has occurred. Elapsed time is measured in ticks. A tick is defined to be
-an integral number of microseconds which is specified by the user in the
-Configuration Table.
+For the features provided by the Clock Manager to be utilized, a :term:`Clock
+Driver` is required. The Clock Driver usually provides a clock interrupt which
+is serviced on each configured processor at each :term:`clock tick`. In
+addition, the Clock Driver provides three clock sources:
+
+* clock tick
+
+* :term:`CLOCK_REALTIME`
+
+* :term:`CLOCK_MONOTONIC`
+
+The time of these clock sources advances at each clock tick. This yields the
+time of the clock sources in a coarse resolution. To get the time of the
+``CLOCK_REALTIME`` or ``CLOCK_MONOTONIC`` clock sources in a higher resolution,
+the Clock Driver may use a clock device to get the time between clock ticks.
.. _Time and Date Data Structures:
Time and Date Data Structures
-----------------------------
-The clock facilities of the clock manager operate upon calendar time. These
+The clock facilities of the Clock Manager operate upon calendar time. These
directives utilize the following date and time structure for the native time
and date format:
@@ -29,7 +38,7 @@ and date format:
.. code-block:: c
- struct rtems_tod_control {
+ typedef struct {
uint32_t year; /* greater than 1987 */
uint32_t month; /* 1 - 12 */
uint32_t day; /* 1 - 31 */
@@ -37,20 +46,34 @@ and date format:
uint32_t minute; /* 0 - 59 */
uint32_t second; /* 0 - 59 */
uint32_t ticks; /* elapsed between seconds */
- };
- typedef struct rtems_tod_control rtems_time_of_day;
+ } rtems_time_of_day;
The native date and time format is the only format supported when setting the
-system date and time using the ``rtems_clock_set`` directive. Some
+system date and time using the :ref:`InterfaceRtemsClockSet` directive. Some
applications expect to operate on a *UNIX-style* date and time data structure.
-The ``rtems_clock_get_tod_timeval`` always returns the date and time in
-``struct timeval`` format.
-
-The ``struct timeval`` data structure has two fields: ``tv_sec`` and
-``tv_usec`` which are seconds and microseconds, respectively. The ``tv_sec``
-field in this data structure is the number of seconds since the POSIX epoch of
-*January 1, 1970* but will never be prior to the RTEMS epoch of *January 1,
-1988*.
+For example, the :ref:`InterfaceRtemsClockGetTodTimeval` returns the date and
+time in ``struct timeval`` format.
+
+.. index:: struct timeval
+.. index:: struct timespec
+
+Some directives use data structures defined by :term:`POSIX`. The ``struct
+timeval`` data structure has two members: ``tv_sec`` and ``tv_usec`` which are
+seconds and microseconds, respectively. The ``struct timespec`` data structure
+has two members: ``tv_sec`` and ``tv_nsec`` which are seconds and nanoseconds,
+respectively. For :term:`CLOCK_REALTIME` time points, the ``tv_sec`` member in
+these data structures is the number of seconds since the :term:`Unix epoch` but
+will never be prior to the :term:`RTEMS epoch`.
+
+.. index:: struct bintime
+.. index:: sbintime_t
+
+The ``struct bintime`` and ``sbintime_t`` time formats used by some directives
+originate in FreeBSD. The ``struct bintime`` data structure which represents
+time in a binary time format has two members: ``sec`` and ``frac`` which are
+seconds and fractions of a second in units of :math:`1 / 2^{64}` seconds,
+respectively. The ``sbintime_t`` type is a signed 64-bit integer type used to
+represent time in units of :math:`1 / 2^{32}` seconds.
.. index:: timeslicing
@@ -64,8 +87,9 @@ scheduling algorithm. The length of time allocated to each task is known as
the quantum or timeslice.
The system's timeslice is defined as an integral number of ticks, and is
-specified in the Configuration Table. The timeslice is defined for the entire
-system of tasks, but timeslicing is enabled and disabled on a per task basis.
+specified by the :ref:`CONFIGURE_TICKS_PER_TIMESLICE` application configuration
+option. The timeslice is defined for the entire system of tasks, but
+timeslicing is enabled and disabled on a per task basis.
The clock tick directives implement timeslicing by decrementing the
running task's time-remaining counter when both timeslicing and preemption are
@@ -79,10 +103,10 @@ Delays
A sleep timer allows a task to delay for a given interval or up until a given
time, and then wake and continue execution. This type of timer is created
-automatically by the ``rtems_task_wake_after`` and ``rtems_task_wake_when``
-directives and, as a result, does not have an RTEMS ID. Once activated, a
-sleep timer cannot be explicitly deleted. Each task may activate one and only
-one sleep timer at a time.
+automatically by the :ref:`InterfaceRtemsTaskWakeAfter` and
+:ref:`InterfaceRtemsTaskWakeWhen` directives and, as a result, does not have an
+object identifier. Once activated, a sleep timer cannot be explicitly deleted.
+Each task may activate one and only one sleep timer at a time.
.. index:: timeouts
@@ -90,7 +114,8 @@ Timeouts
--------
Timeouts are a special type of timer automatically created when the timeout
-option is used on the ``rtems_message_queue_receive``, ``rtems_event_receive``,
-``rtems_semaphore_obtain`` and ``rtems_region_get_segment`` directives. Each
-task may have one and only one timeout active at a time. When a timeout
-expires, it unblocks the task with a timeout status code.
+option is used on the :ref:`InterfaceRtemsBarrierWait`,
+:ref:`InterfaceRtemsEventReceive`, :ref:`InterfaceRtemsMessageQueueReceive`,
+:ref:`InterfaceRtemsRegionGetSegment`, and :ref:`InterfaceRtemsSemaphoreObtain`
+directives. Each task may have one and only one timeout active at a time.
+When a timeout expires, it unblocks the task with a timeout status code.
diff --git a/c-user/clock/directives.rst b/c-user/clock/directives.rst
index 080968e..6e1542c 100644
--- a/c-user/clock/directives.rst
+++ b/c-user/clock/directives.rst
@@ -298,7 +298,7 @@ Gets the time elapsed since the :term:`Unix epoch` measured using
.. rubric:: PARAMETERS:
``time_snapshot``
- This parameter is the pointer to a :c:type:`bintime` object. The time
+ This parameter is the pointer to a ``struct bintime`` object. The time
elapsed since the :term:`Unix epoch` measured using the
:term:`CLOCK_REALTIME` at some time point during the directive call will be
stored in this object. Calling the directive with a pointer equal to `NULL
@@ -457,7 +457,7 @@ Gets the time elapsed since the :term:`Unix epoch` measured using
.. rubric:: PARAMETERS:
``time_snapshot``
- This parameter is the pointer to a :c:type:`bintime` object. The time
+ This parameter is the pointer to a ``struct bintime`` object. The time
elapsed since the :term:`Unix epoch` measured using the
:term:`CLOCK_REALTIME` at some time point close to the directive call will
be stored in this object. Calling the directive with a pointer equal to
@@ -564,7 +564,8 @@ the :term:`CLOCK_MONOTONIC` in seconds and nanoseconds format.
.. rubric:: PARAMETERS:
``time_snapshot``
- This parameter is the pointer to a :c:type:`bintime` object. The time
+ This parameter is the pointer to a `struct timespec
+ <https://en.cppreference.com/w/c/chrono/timespec>`_ object. The time
elapsed since some fixed time point in the past measured using the
:term:`CLOCK_MONOTONIC` at some time point during the directive call will
be stored in this object. Calling the directive with a pointer equal to
@@ -618,7 +619,7 @@ the :term:`CLOCK_MONOTONIC` in binary time format.
.. rubric:: PARAMETERS:
``time_snapshot``
- This parameter is the pointer to a :c:type:`bintime` object. The time
+ This parameter is the pointer to a ``struct bintime`` object. The time
elapsed since some fixed time point in the past measured using the
:term:`CLOCK_MONOTONIC` at some time point during the directive call will
be stored in this object. Calling the directive with a pointer equal to
@@ -719,11 +720,12 @@ the :term:`CLOCK_MONOTONIC` in seconds and microseconds format.
.. rubric:: PARAMETERS:
``time_snapshot``
- This parameter is the pointer to a :c:type:`bintime` object. The time
- elapsed since some fixed time point in the past measured using the
- :term:`CLOCK_MONOTONIC` at some time point during the directive call will
- be stored in this object. Calling the directive with a pointer equal to
- `NULL <https://en.cppreference.com/w/c/types/NULL>`_ is undefined
+ This parameter is the pointer to a `struct timeval
+ <https://pubs.opengroup.org/onlinepubs/009695399/basedefs/sys/time.h.html>`_
+ object. The time elapsed since some fixed time point in the past measured
+ using the :term:`CLOCK_MONOTONIC` at some time point during the directive
+ call will be stored in this object. Calling the directive with a pointer
+ equal to `NULL <https://en.cppreference.com/w/c/types/NULL>`_ is undefined
behaviour.
.. rubric:: NOTES:
@@ -774,7 +776,8 @@ format.
.. rubric:: PARAMETERS:
``time_snapshot``
- This parameter is the pointer to a :c:type:`bintime` object. The time
+ This parameter is the pointer to a `struct timespec
+ <https://en.cppreference.com/w/c/chrono/timespec>`_ object. The time
elapsed since some fixed time point in the past measured using the
:term:`CLOCK_MONOTONIC` at some time point close to the directive call will
be stored in this object. Calling the directive with a pointer equal to
@@ -827,7 +830,7 @@ the :term:`CLOCK_MONOTONIC` in coarse resolution in binary time format.
.. rubric:: PARAMETERS:
``time_snapshot``
- This parameter is the pointer to a :c:type:`bintime` object. The time
+ This parameter is the pointer to a ``struct bintime`` object. The time
elapsed since some fixed time point in the past measured using the
:term:`CLOCK_MONOTONIC` at some time point close to the directive call will
be stored in this object. Calling the directive with a pointer equal to
@@ -881,11 +884,12 @@ format.
.. rubric:: PARAMETERS:
``time_snapshot``
- This parameter is the pointer to a :c:type:`bintime` object. The time
- elapsed since some fixed time point in the past measured using the
- :term:`CLOCK_MONOTONIC` at some time point close to the directive call will
- be stored in this object. Calling the directive with a pointer equal to
- `NULL <https://en.cppreference.com/w/c/types/NULL>`_ is undefined
+ This parameter is the pointer to a `struct timeval
+ <https://pubs.opengroup.org/onlinepubs/009695399/basedefs/sys/time.h.html>`_
+ object. The time elapsed since some fixed time point in the past measured
+ using the :term:`CLOCK_MONOTONIC` at some time point close to the directive
+ call will be stored in this object. Calling the directive with a pointer
+ equal to `NULL <https://en.cppreference.com/w/c/types/NULL>`_ is undefined
behaviour.
.. rubric:: NOTES:
@@ -983,7 +987,7 @@ system initialization in binary time format.
.. rubric:: PARAMETERS:
``boot_time``
- This parameter is the pointer to a :c:type:`bintime` object. The time
+ This parameter is the pointer to a ``struct bintime`` object. The time
elapsed since the :term:`Unix epoch` at some time point during system
initialization call will be stored in this object. Calling the directive
with a pointer equal to `NULL
diff --git a/c-user/config/general.rst b/c-user/config/general.rst
index a1f242a..0da7530 100644
--- a/c-user/config/general.rst
+++ b/c-user/config/general.rst
@@ -437,9 +437,9 @@ Each processor needs an IDLE task stack and interrupt stack for example.
If there are more processors available than configured, the rest will be
ignored.
-This configuration option is only evaluated in SMP configurations (e.g. RTEMS
-was built with the ``--enable-smp`` build configuration option). In all
-other configurations it has no effect.
+This configuration option is only evaluated in SMP configurations of RTEMS
+(e.g. RTEMS was built with the SMP build configuration option enabled).
+In all other configurations it has no effect.
.. rubric:: CONSTRAINTS:
diff --git a/c-user/config/mpci.rst b/c-user/config/mpci.rst
index 09c541f..d40f15c 100644
--- a/c-user/config/mpci.rst
+++ b/c-user/config/mpci.rst
@@ -23,12 +23,13 @@
Multiprocessing Configuration
=============================
-This section describes multiprocessing related configuration options. The
-options are only used if RTEMS was built with the ``--enable-multiprocessing``
-build configuration option. Additionally, this class of configuration options
-are only applicable if the configuration option :ref:`CONFIGURE_MP_APPLICATION`
-is defined. The multiprocessing (MPCI) support must not be confused with the
-SMP support.
+This section describes multiprocessing related configuration options.
+The options are only used if RTEMS was built when the multiprocessing
+build configuration option is enabled. The multiprocessing configuration
+is distinct from the SMP configuration. Additionally, this class of
+configuration options are only applicable if the configuration option
+:ref:`CONFIGURE_MP_APPLICATION` is defined. The multiprocessing (MPCI)
+support must not be confused with the SMP support.
.. Generated from spec:/acfg/if/mp-extra-server-stack
@@ -115,8 +116,8 @@ options are assumed to be provided.
.. rubric:: NOTES:
This configuration option shall be undefined if the multiprocessing support
-is not enabled (e.g. RTEMS was built without the ``--enable-multiprocessing``
-build configuration option). Otherwise a compile time error in the
+is not enabled (e.g. RTEMS was built without the multiprocessing build
+configuration option enabled). Otherwise a compile time error in the
configuration file will occur.
.. Generated from spec:/acfg/if/mp-max-global-objects
diff --git a/c-user/config/posix-api.rst b/c-user/config/posix-api.rst
index 12e6410..78cb724 100644
--- a/c-user/config/posix-api.rst
+++ b/c-user/config/posix-api.rst
@@ -25,7 +25,7 @@ POSIX API Configuration
This section describes configuration options related to the POSIX API. Most
POSIX API objects are available by default since RTEMS 5.1. The queued signals
-and timers are only available if RTEMS was built with the ``--enable-posix``
+and timers are only available if RTEMS was built with the enable POSIX
build configuration option.
.. Generated from spec:/acfg/if/max-posix-keys
@@ -231,8 +231,8 @@ API Queued Signals that can be concurrently active.
Unlimited objects are not available for queued signals.
-Queued signals are only available if RTEMS was built with the
-``--enable-posix`` build configuration option.
+Queued signals are only available if RTEMS was built with the POSIX API
+build configuration option enabled.
.. rubric:: CONSTRAINTS:
@@ -470,29 +470,33 @@ API Timers that can be concurrently active.
This object class can be configured in unlimited allocation mode, see
:ref:`ConfigUnlimitedObjects`.
-Timers are only available if RTEMS was built with the
-``--enable-posix`` build configuration option.
+Timers are only available if RTEMS was built with the POSIX API build
+configuration option enabled.
.. rubric:: CONSTRAINTS:
The following constraints apply to this configuration option:
-* The value of the configuration option shall be greater than or equal to zero.
+* The value of the configuration option shall be greater than or equal
+to zero.
-* The value of the configuration option shall be less than or equal to 65535.
+* The value of the configuration option shall be less than or equal
+to 65535.
* The value of the configuration option shall be less than or equal to a
- BSP-specific and application-specific value which depends on the size of the
- memory available to the application.
+ BSP-specific and application-specific value which depends on the size
+ of the memory available to the application.
* The value of the configuration option may be defined through
:c:func:`rtems_resource_unlimited` the enable unlimited objects for the
object class, if the value passed to :c:func:`rtems_resource_unlimited`
satisfies all other constraints of the configuration option.
-* The value of the configuration option shall be 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
+* The value of the configuration option shall be zero if the POSIX API
+is not
+ enabled (e.g. RTEMS was built without the ``RTEMS_POSIX_API = True``
+ build configuration option). Otherwise a compile time error in the
+ configuration
file will occur.
.. Generated from spec:/acfg/if/min-posix-thread-stack-size
diff --git a/c-user/config/scheduler-general.rst b/c-user/config/scheduler-general.rst
index 7c42039..7169a83 100644
--- a/c-user/config/scheduler-general.rst
+++ b/c-user/config/scheduler-general.rst
@@ -1,6 +1,6 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
-.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de)
+.. Copyright (C) 2020, 2022 embedded brains GmbH (http://www.embedded-brains.de)
.. Copyright (C) 2010 Gedare Bloom
.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -198,7 +198,8 @@ scheduler to processor assignments.
.. rubric:: NOTES:
-This configuration option is only evaluated in SMP configurations.
+Where the system was built with SMP support enabled, this configuration
+option is evaluated, otherwise it is ignored.
This is an advanced configuration option, see
:ref:`ConfigurationSchedulersClustered`.
@@ -210,10 +211,21 @@ The following constraints apply to this configuration option:
* The value of the configuration option shall be a list of the following
macros:
- * ``RTEMS_SCHEDULER_ASSIGN( processor_index, attributes )``
+ * ``RTEMS_SCHEDULER_ASSIGN( scheduler_index, attributes )``
* ``RTEMS_SCHEDULER_ASSIGN_NO_SCHEDULER``
+ The ``scheduler_index`` macro parameter shall be a valid index of the
+ scheduler table defined by the :ref:`CONFIGURE_SCHEDULER_TABLE_ENTRIES`
+ configuration option.
+
+ The ``attributes`` macro parameter shall be set to exactly one of the
+ following constants:
+
+ * ``RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY``
+
+ * ``RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL``
+
* The value of the configuration option shall be a list of exactly
:ref:`CONFIGURE_MAXIMUM_PROCESSORS` elements.
@@ -667,6 +679,81 @@ support enabled.
This scheduler algorithm is not correctly implemented. Do not use it.
+.. Generated from spec:/acfg/if/scheduler-table-entries
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: CONFIGURE_SCHEDULER_TABLE_ENTRIES
+
+.. _CONFIGURE_SCHEDULER_TABLE_ENTRIES:
+
+CONFIGURE_SCHEDULER_TABLE_ENTRIES
+---------------------------------
+
+.. rubric:: CONSTANT:
+
+``CONFIGURE_SCHEDULER_TABLE_ENTRIES``
+
+.. rubric:: OPTION TYPE:
+
+This configuration option is an initializer define.
+
+.. rubric:: DEFAULT VALUE:
+
+The default value of this configuration option is the definition of exactly
+one table entry for the configured scheduler.
+
+.. rubric:: DESCRIPTION:
+
+The value of this configuration option is used to initialize the table of
+configured schedulers.
+
+.. rubric:: NOTES:
+
+Schedulers registered in the scheduler table by this configuration option are
+available to the application. The scheduler table entry index defines the
+index of the scheduler.
+
+This is an advanced configuration option, see
+:ref:`ConfigurationSchedulersClustered`.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this configuration option:
+
+* The value of the configuration option shall be a list of the following
+ macros:
+
+ * ``RTEMS_SCHEDULER_TABLE_CBS( name, obj_name )``
+
+ * ``RTEMS_SCHEDULER_TABLE_EDF( name, obj_name )``
+
+ * ``RTEMS_SCHEDULER_TABLE_EDF_SMP( name, obj_name )``
+
+ * ``RTEMS_SCHEDULER_TABLE_PRIORITY_AFFINITY_SMP( name, obj_name )``
+
+ * ``RTEMS_SCHEDULER_TABLE_PRIORITY( name, obj_name )``
+
+ * ``RTEMS_SCHEDULER_TABLE_PRIORITY_SMP( name, obj_name )``
+
+ * ``RTEMS_SCHEDULER_TABLE_SIMPLE( name, obj_name )``
+
+ * ``RTEMS_SCHEDULER_TABLE_SIMPLE_SMP( name, obj_name )``
+
+ * ``RTEMS_SCHEDULER_TABLE_STRONG_APA( name, obj_name )``
+
+ The ``name`` macro parameter shall be the name associated with the scheduler
+ data structures, see :ref:`ConfigurationSchedulersClustered`.
+
+ The ``obj_name`` macro parameter shall be the scheduler object name. It is
+ recommended to define the scheduler object name through
+ :c:func:`rtems_build_name`.
+
+* Where the system was build with SMP support enabled, the table shall have one
+ or more entries, otherwise it shall have exactly one entry.
+
.. Generated from spec:/acfg/if/scheduler-user
.. raw:: latex
diff --git a/c-user/interrupt/directives.rst b/c-user/interrupt/directives.rst
index 2d7dccf..d4855b6 100644
--- a/c-user/interrupt/directives.rst
+++ b/c-user/interrupt/directives.rst
@@ -1,6 +1,6 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
-.. Copyright (C) 2008, 2021 embedded brains GmbH (http://www.embedded-brains.de)
+.. Copyright (C) 2008, 2022 embedded brains GmbH (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
@@ -2123,6 +2123,11 @@ Sets the processor affinity set of the interrupt vector.
The :ref:`InterfaceRtemsInterruptGetAttributes` directive may be used to check
if the processor affinity of an interrupt vector can be set.
+Only online processors of the affinity set specified by ``affinity_size`` and
+``affinity`` are considered by the directive. Other processors of the set are
+ignored. If the set contains no online processor, then the set is invalid and
+an error status is returned.
+
.. rubric:: CONSTRAINTS:
The following constraints apply to this directive:
diff --git a/c-user/interrupt/introduction.rst b/c-user/interrupt/introduction.rst
index 7987b54..3e10414 100644
--- a/c-user/interrupt/introduction.rst
+++ b/c-user/interrupt/introduction.rst
@@ -1,6 +1,6 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
-.. Copyright (C) 2008, 2021 embedded brains GmbH (http://www.embedded-brains.de)
+.. Copyright (C) 2008, 2022 embedded brains GmbH (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
diff --git a/c-user/symmetric_multiprocessing_services.rst b/c-user/symmetric_multiprocessing_services.rst
index acfee56..89dc48c 100644
--- a/c-user/symmetric_multiprocessing_services.rst
+++ b/c-user/symmetric_multiprocessing_services.rst
@@ -13,10 +13,19 @@ Symmetric Multiprocessing (SMP)
Introduction
============
-The Symmetric Multiprocessing (SMP) support of the RTEMS is available on
+RTEMS Symmetric Multiprocessing (SMP) support is available on a subset
+of target architectures supported by RTEMS. Further on some target
+architectures, it is only available on a subset of BSPs. The user is
+advised to check the BSP specific documentation and RTEMS source code
+to verify the status of SMP support for a specific BSP. The following
+architectures have support for SMP:
+
+-- AArch64
- ARMv7-A,
+- i386,
+
- PowerPC,
- RISC-V, and
@@ -25,8 +34,8 @@ The Symmetric Multiprocessing (SMP) support of the RTEMS is available on
.. warning::
- The SMP support is only available if RTEMS was built with the
- ``--enable-smp`` build configuration option.
+ SMP support is only available if RTEMS was built with the
+ SMP build configuration option enabled.
RTEMS is supposed to be a real-time operating system. What does this mean in
the context of SMP? The RTEMS interpretation of real-time on SMP is the
@@ -580,10 +589,10 @@ Profiling
---------
To identify the bottlenecks in the system, support for profiling of low-level
-synchronization is optionally available. The profiling support is a BSP build
-time configuration option (``--enable-profiling``) and is implemented with an
-acceptable overhead, even for production systems. A low-overhead counter for
-short time intervals must be provided by the hardware.
+synchronization is optionally available. The profiling support is
+an RTEMS build time configuration option and is implemented with an
+acceptable overhead, even for production systems. A low-overhead counter
+for short time intervals must be provided by the hardware.
Profiling reports are generated in XML for most test programs of the RTEMS
testsuite (more than 500 test programs). This gives a good sample set for
diff --git a/c-user/task/directives.rst b/c-user/task/directives.rst
index ce2013c..64b591d 100644
--- a/c-user/task/directives.rst
+++ b/c-user/task/directives.rst
@@ -86,9 +86,9 @@ identifier is returned in ``id``. This identifier is used to access the task
with other task related directives.
The **initial priority** of the task is specified in ``initial_priority``. The
-scheduler of the created task is the scheduler of the calling task at some
-point during the task creation. The initial task priority specified in
-``initial_priority`` shall be valid for this scheduler.
+:term:`home scheduler` of the created task is the home scheduler of the calling
+task at some time point during the task creation. The initial task priority
+specified in ``initial_priority`` shall be valid for this scheduler.
The **stack size** of the task is specified in ``stack_size``. If the
requested stack size is less than the configured minimum stack size, then RTEMS
diff --git a/cpu-supplement/aarch64.rst b/cpu-supplement/aarch64.rst
index 2b3d620..1e9b8d6 100644
--- a/cpu-supplement/aarch64.rst
+++ b/cpu-supplement/aarch64.rst
@@ -73,6 +73,11 @@ A flat 64-bit or 32-bit memory model is supported depending on the selected mult
variant. All AArch64 CPU variants support a built-in MMU for which basic initialization
for a flat memory model is handled.
+Note that memcpy() and memset() must not be used on device memory as those
+functions are hand-optimized and will take advantage of unaligned accesses.
+*As per ARM*(https://developer.arm.com/documentation/ka004708/latest), unaligned
+accesses are not permitted for device memory.
+
Interrupt Processing
====================
diff --git a/cpu-supplement/arm.rst b/cpu-supplement/arm.rst
index ac9e8c6..b92e6d6 100644
--- a/cpu-supplement/arm.rst
+++ b/cpu-supplement/arm.rst
@@ -132,6 +132,12 @@ Memory Model
A flat 32-bit memory model is supported. The board support package must take
care of initializing the MMU if necessary.
+Note that architecture variants which support unaligned accesses must not use
+memcpy() or memset() on device memory as those functions are hand-optimized and
+will take advantage of unaligned accesses where available. *As per ARM*
+(https://developer.arm.com/documentation/ddi0406/c/Application-Level-Architecture/Application-Level-Memory-Model/Alignment-support/Unaligned-data-access-restrictions-in-ARMv7-and-ARMv6),
+unaligned accesses are not permitted for device memory.
+
Interrupt Processing
====================
diff --git a/cpu-supplement/index.rst b/cpu-supplement/index.rst
index 951d6b7..733ffcc 100644
--- a/cpu-supplement/index.rst
+++ b/cpu-supplement/index.rst
@@ -24,6 +24,7 @@ RTEMS CPU Architecture Supplement (|version|).
preface
port
+ aarch64
arm
atmel_avr
blackfin
diff --git a/cpu-supplement/sparc.rst b/cpu-supplement/sparc.rst
index 4f39f34..11b63d9 100644
--- a/cpu-supplement/sparc.rst
+++ b/cpu-supplement/sparc.rst
@@ -1,5 +1,6 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
+.. Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
.. Copyright (C) 1988, 2002 On-Line Applications Research Corporation (OAR)
SPARC Specific Information
@@ -563,35 +564,52 @@ state changes occur in the processor itself. The return address reported by
the processor for synchronous traps is the instruction which caused the trap
and the following instruction.
+Trap Table
+----------
+
+A SPARC processor uses a trap table to execute the trap handler associated with
+a trap. The trap table location is defined by the Trap Base Register
+(``TBR``). The trap table has 256 entries. Each entry has space for four
+instructions (16 bytes). RTEMS uses a statically initialized trap table. The
+start address of the trap table is associated with the ``trap_table`` global
+symbol. The first action of the system initialization (entry points ``_start``
+and ``hard_reset``) is to set the ``TBR`` to ``trap_table``. The interrupt
+traps (trap numbers 16 to 31) are connected with the RTEMS interrupt handling.
+Some traps are connected to standard services defined by the SPARC
+architecture, for example the window overflow, underflow, and flush handling.
+Most traps are connected to a fatal error handler. The fatal error trap
+handler saves the processor context to an exception frame and starts the system
+termination procedure.
+
Vectoring of Interrupt Handler
------------------------------
-Upon receipt of an interrupt the SPARC automatically performs the following
-actions:
+Upon receipt of an interrupt a SPARC processor automatically performs the
+following actions:
-- disables traps (sets the ET bit of the ``PSR`` to 0),
+- disables traps (sets the ``PSR.ET`` bit to 0 in the ``PSR``),
-- the S bit of the ``PSR`` is copied into the Previous Supervisor Mode (PS) bit of
- the ``PSR``,
+- the ``PSR.S`` bit is copied into the Previous Supervisor Mode (``PSR.PS``)
+ bit in the ``PSR``,
- the ``CWP`` is decremented by one (modulo the number of register windows) to
activate a trap window,
-- the PC and nPC are loaded into local register 1 and 2 (l0 and l1),
+- the PC and nPC are loaded into local register 1 and 2 (``%l0`` and ``%l1``),
-- the trap type (tt) field of the Trap Base Register (``TBR``) is set to the
- appropriate value, and
+- the trap type (``tt``) field of the Trap Base Register (``TBR``) is set to
+ the appropriate value, and
- if the trap is not a reset, then the PC is written with the contents of the
- ``TBR`` and the nPC is written with ``TBR`` + 4. If the trap is a reset, then the PC
- is set to zero and the nPC is set to 4.
+ ``TBR`` and the nPC is written with ``TBR`` + 4. If the trap is a reset,
+ then the PC is set to zero and the nPC is set to 4.
Trap processing on the SPARC has two features which are noticeably different
than interrupt processing on other architectures. First, the value of ``PSR``
register in effect immediately before the trap occurred is not explicitly
saved. Instead only reversible alterations are made to it. Second, the
-Processor Interrupt Level (pil) is not set to correspond to that of the
-interrupt being processed. When a trap occurs, ALL subsequent traps are
+Processor Interrupt Level (``PSR.PIL``) is not set to correspond to that of the
+interrupt being processed. When a trap occurs, **all** subsequent traps are
disabled. In order to safely invoke a subroutine during trap handling, traps
must be enabled to allow for the possibility of register window overflow and
underflow traps.
@@ -698,15 +716,16 @@ Interrupt Stack
The SPARC architecture does not provide for a dedicated interrupt stack. Thus
by default, trap handlers would execute on the stack of the RTEMS task which
they interrupted. This artificially inflates the stack requirements for each
-task since EVERY task stack would have to include enough space to account for
-the worst case interrupt stack requirements in addition to it's own worst case
-usage. RTEMS addresses this problem on the SPARC by providing a dedicated
+task since **every** task stack would have to include enough space to account
+for the worst case interrupt stack requirements in addition to it's own worst
+case usage. RTEMS addresses this problem on the SPARC by providing a dedicated
interrupt stack managed by software.
-During system initialization, RTEMS allocates the interrupt stack from the
-Workspace Area. The amount of memory allocated for the interrupt stack is
-determined by the interrupt_stack_size field in the CPU Configuration Table.
-As part of processing a non-nested interrupt, RTEMS will switch to the
+The interrupt stack is statically allocated by RTEMS. There is one interrupt
+stack for each configured processor. The interrupt stack is used to initialize
+the system. The amount of memory allocated for the interrupt stack is
+determined by the ``CONFIGURE_INTERRUPT_STACK_SIZE`` application configuration
+option. As part of processing a non-nested interrupt, RTEMS will switch to the
interrupt stack before invoking the installed handler.
Default Fatal Error Processing
diff --git a/cpu-supplement/xilinx_microblaze.rst b/cpu-supplement/xilinx_microblaze.rst
index 2a92b61..350aeff 100644
--- a/cpu-supplement/xilinx_microblaze.rst
+++ b/cpu-supplement/xilinx_microblaze.rst
@@ -1,10 +1,58 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
-.. Copyright (C) 1988, 2002 On-Line Applications Research Corporation (OAR)
+.. Copyright (C) 2022 On-Line Applications Research Corporation (OAR)
Xilinx MicroBlaze Specific Information
**************************************
+This chapter discusses the dependencies of the *MicroBlaze architecture*
+(https://en.wikipedia.org/wiki/MicroBlaze).
+
+**Architecture Documents**
+
+For information on the MicroBlaze architecture, refer to
+*UG984 MicroBlaze Processor Reference Guide*
+(https://www.xilinx.com/support/documentation/sw_manuals/xilinx2021_2/ug984-vivado-microblaze-ref.pdf).
+
+CPU Model Dependent Features
+============================
+
+There are no CPU model dependent features in this port.
+
+Calling Conventions
+===================
+
+Please refer to "Chapter 4: MicroBlaze Application Binary Interface" of
+*UG984 MicroBlaze Processor Reference Guide*
+(https://www.xilinx.com/support/documentation/sw_manuals/xilinx2021_2/ug984-vivado-microblaze-ref.pdf).
+
+Interrupt Processing
+====================
+
+Hardware exceptions, interrupts, and user exceptions are all supported. When a
+hardware exception or user exception occurs, a fatal error will be generated.
+When an interrupt occurs, the interrupt source is determined by reading the
+AXI Interrupt Controller's Interrupt Status Register and masking it with the
+Interrupt Enable Register.
+
+Interrupt Levels
+----------------
+
+There are exactly two interrupt levels on MicroBlaze with respect to RTEMS.
+Level zero corresponds to interrupts disabled. Level one corresponds to
+interrupts enabled. This is the inverse of how most other architectures handle
+interrupt enable status.
+
+Interrupt Stack
+---------------
+
+The memory region for the interrupt stack is defined by the BSP.
+
+Default Fatal Error Processing
+==============================
+
+The default fatal error is BSP-specific.
+
Symmetric Multiprocessing
=========================
@@ -13,4 +61,4 @@ SMP is not supported.
Thread-Local Storage
====================
-Thread-local storage is not implemented.
+Thread-local storage is supported.
diff --git a/eng/release-process.rst b/eng/release-process.rst
index e571b0d..7c250ea 100644
--- a/eng/release-process.rst
+++ b/eng/release-process.rst
@@ -159,21 +159,23 @@ Release Repositories
The following are the repositories that a release effects. Any repository
action is to be performed in the following repositories:
-#. ``rtems.git``
+* ``rtems.git``
-#. ``rtems-docs.git``
+* ``rtems-central.git``
-#. ``rtems-examples.git``
+* ``rtems-docs.git``
-#. ``rtems-libbsd.git``
+* ``rtems-examples.git``
-#. ``rtems-source-builder.git``
+* ``rtems-libbsd.git``
-#. ``rtems-tools.git``
+* ``rtems-release.git``
-#. ``rtems_waf.git``
+* ``rtems-source-builder.git``
-#. ``rtems-release.git``
+* ``rtems-tools.git``
+
+* ``rtems_waf.git``
Pre-Release Procedure
=====================
@@ -220,7 +222,7 @@ Pre-Branch Procedure
* Check and make sure the RSB kernel, libbsd and tools configurations
reference the ``master`` when the branch is made.
- The RSB GIT builds reference a specific commit so it is important
+ The RSB Git builds reference a specific commit so it is important
the relevant configurations are valid.
Branch Procedure
@@ -274,29 +276,29 @@ Post-Branch Procedure
#. Add the milestones for the new development branch. The Trac page
is:
- .. code-block:: none
+ .. code-block:: none
- = 6.1 (open)
+ = 6.1 (open)
- == Statistics
+ == Statistics
- || '''Total'''||[[TicketQuery(milestone=6.1,count)]] ||
- || Fixed||[[TicketQuery(status=closed&milestone=6.1,resolution=fixed,count,)]] ||
- || Invalid||[[TicketQuery(status=closed&milestone=6.1,resolution=invalid,count,)]] ||
- || Works for me||[[TicketQuery(status=closed&milestone=6.1,resolution=worksforme,count,)]] ||
- || Duplicate||[[TicketQuery(status=closed&milestone=6.1,resolution=duplicate,count,)]] ||
- || Won't fix||[[TicketQuery(status=closed&milestone=6.1,resolution=wontfix,count,)]] ||
+ || '''Total'''||[[TicketQuery(milestone=6.1,count)]] ||
+ || Fixed||[[TicketQuery(status=closed&milestone=6.1,resolution=fixed,count,)]] ||
+ || Invalid||[[TicketQuery(status=closed&milestone=6.1,resolution=invalid,count,)]] ||
+ || Works for me||[[TicketQuery(status=closed&milestone=6.1,resolution=worksforme,count,)]] ||
+ || Duplicate||[[TicketQuery(status=closed&milestone=6.1,resolution=duplicate,count,)]] ||
+ || Won't fix||[[TicketQuery(status=closed&milestone=6.1,resolution=wontfix,count,)]] ||
- == Distribution
- [[TicketQuery(milestone=6.1&group=type,format=progress)]]
+ == Distribution
+ [[TicketQuery(milestone=6.1&group=type,format=progress)]]
- == Summary
- [[TicketQuery(milestone=6.1)]]
+ == Summary
+ [[TicketQuery(milestone=6.1)]]
- == Details
- [[TicketQuery(col=id|time|resolution|component|reporter|owner|changetime,status=closed&milestone=6.1,rows=summary|description,table)]]
+ == Details
+ [[TicketQuery(col=id|time|resolution|component|reporter|owner|changetime,status=closed&milestone=6.1,rows=summary|description,table)]]
- Replace ``6.1`` with the required milestone.
+ Replace ``6.1`` with the required milestone.
#. Create the RC1 release candidate with the source as close the
branch point as possible.
@@ -307,6 +309,14 @@ Post-Branch Procedure
add no value to a released RSB. For example leaving RTEMS 6 tool
building configurations in the RTEMS 5 release.
+#. Check out the release branch of ``rtems-central.git``. Change all Git
+ submodules to reference commits of the corresponding release branch. Run
+ ``./spec2modules.py``. Inspect all Git submodules for changes. If there
+ are locally modified files, then there are two options. Firstly, integrate
+ the changes in the release branches. Afterwards update the Git submodule
+ commit. Secondly, change the specification so that a particular change is
+ not made. Make sure that there are no changes after this procedure.
+
Post-Branch Version Number Updates
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -316,17 +326,17 @@ the needed changes.
#. RTEMS requires the following files be changed:
- * :file:`aclocal/version.m4`
+ * :file:`Doxyfile`: Update ``PROJECT_NUMBER``.
- * :file:`c/src/aclocal/version.m4`
+ * :file:`rtems-bsps`: Update ``rtems_version``.
- * :file:`cpukit/aclocal/version.m4`
+ * :file:`spec/build/cpukit/optvermaj.yml`: Update ``set-value``.
- * :file:`Doxyfile`
+ * :file:`spec/build/cpukit/optvermin.yml`: Update ``set-value``.
- * :file:`testsuites/aclocal/version.m4`
+ * :file:`spec/build/cpukit/optverrev.yml`: Update ``set-value``.
- * :file:`rtems-bsps`
+ * :file:`wscript`: Update ``default_prefix``.
#. RTEMS Documentation the following files be changed:
diff --git a/eng/req/howto.rst b/eng/req/howto.rst
index c8bd8c5..bd94b77 100644
--- a/eng/req/howto.rst
+++ b/eng/req/howto.rst
@@ -1,6 +1,6 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
-.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de)
+.. Copyright (C) 2020, 2022 embedded brains GmbH (http://www.embedded-brains.de)
How-To
======
@@ -33,6 +33,100 @@ environment in your shell:
cd rtems-central
. env/bin/activate
+View the Specification Graph
+----------------------------
+
+The specification items form directed graphs through :ref:`SpecTypeLink`
+attributes. Each link has a role. For a particular view only specific roles
+may be of interest. For example, the requirements specification of RTEMS
+starts with the ``spec:/req/root`` specification item. It should form a tree
+(connected graph without cycles). A text representation of the tree can be
+printed with the ``./specview.py`` script:
+
+.. code-block:: none
+
+ cd rtems-central
+ . env/bin/activate
+ ./specview.py
+
+This gives the following example output (shortened):
+
+.. code-block:: none
+
+ /req/root (type=requirement/non-functional/design)
+ /bsp/if/group (type=requirement/non-functional/design-group, role=requirement-refinement)
+ /bsp/if/acfg-idle-task-body (type=interface/unspecified-define, role=interface-ingroup)
+ /bsp/sparc/leon3/req/idle-task-body (type=requirement/functional/function, role=interface-function)
+ /bsp/sparc/leon3/req/idle-task-power-down (type=requirement/functional/function, role=requirement-refinement)
+ /bsp/sparc/leon3/val/errata-gr712rc-08 (type=validation, role=validation)
+ /bsp/sparc/leon3/req/idle-task-power-down-errata (type=requirement/functional/function, role=requirement-refinement)
+ /bsp/sparc/leon3/val/errata-gr712rc-08 (type=validation, role=validation)
+
+The actual specification graph depends on build configuration options which
+enable or disable specification items. The ``--enabled`` command line option
+may be used to specify the build configuration options, for example
+``--enabled=sparc,bsps/sparc/leon3,sparc/gr740,RTEMS_SMP,RTEMS_QUAL``.
+
+The ``./specview.py`` script can display other views of the specification
+through the ``--filter`` command line option. Transition maps of
+:ref:`SpecTypeActionRequirementItemType` items can be printed using the
+``--filter=action-table`` or ``--filter=action-list`` filters. For example,
+``./specview.py --filter=action-table /rtems/timer/req/create`` prints
+something like this:
+
+.. code-block:: none
+
+ .. table::
+ :class: longtable
+
+ ===== ========== ======= ===== ==== ======= ======= =====
+ Entry Descriptor Name Id Free Status Name IdVar
+ ===== ========== ======= ===== ==== ======= ======= =====
+ 0 0 Valid Valid Yes Ok Valid Set
+ 1 0 Valid Valid No TooMany Invalid Nop
+ 2 0 Valid Null Yes InvAddr Invalid Nop
+ 3 0 Valid Null No InvAddr Invalid Nop
+ 4 0 Invalid Valid Yes InvName Invalid Nop
+ 5 0 Invalid Valid No InvName Invalid Nop
+ 6 0 Invalid Null Yes InvName Invalid Nop
+ 7 0 Invalid Null No InvName Invalid Nop
+ ===== ========== ======= ===== ==== ======= ======= =====
+
+For example, ``./specview.py --filter=action-list /rtems/timer/req/create``
+prints something like this:
+
+.. code-block:: none
+
+ Status = Ok, Name = Valid, IdVar = Set
+
+ * Name = Valid, Id = Valid, Free = Yes
+
+ Status = TooMany, Name = Invalid, IdVar = Nop
+
+ * Name = Valid, Id = Valid, Free = No
+
+ Status = InvAddr, Name = Invalid, IdVar = Nop
+
+ * Name = Valid, Id = Null, Free = { Yes, No }
+
+ Status = InvName, Name = Invalid, IdVar = Nop
+
+ * Name = Invalid, Id = { Valid, Null }, Free = { Yes, No }
+
+The view above yields for each variation of post-condition states the list of
+associated pre-condition state variations.
+
+Generate Files from Specification Items
+---------------------------------------
+
+The ``./spec2modules.py`` script generates program and documentation files in
+:file:`modules/rtems` and :file:`modules/rtems-docs` using the specification
+items as input. The script should be invoked whenever a specification item was
+modified. After running the script, go into the subdirectories and create
+corresponding patch sets. For these patch sets, the normal patch review
+process applies, see *Support and Contributing* chapter of the *RTEMS User
+Manual*.
+
Application Configuration Options
---------------------------------
@@ -1030,3 +1124,10 @@ the following post-condition states.
Objects referenced by the ${../if/directive:/params[0]/name}
parameter in past calls to ${../if/directive:/name} shall not be
accessed by the ${../if/directive:/name} call.
+
+Verify the Specification Items
+------------------------------
+
+The ``./specverify.py`` script verifies that the specification items have the
+format documented in :ref:`ReqEngSpecificationItems`. To some extent the
+values of attributes are verified as well.
diff --git a/eng/req/items.rst b/eng/req/items.rst
index 2c1e361..e4f600a 100644
--- a/eng/req/items.rst
+++ b/eng/req/items.rst
@@ -2650,7 +2650,7 @@ Action Requirement Expression State Name
The value shall be a string. It shall be the name of a state of the condition
or ``N/A`` if the condition is not applicable. The value
-* shall match with the regular expression "``^[A-Z][a-zA-Z0-9]+$``",
+* shall match with the regular expression "``^[A-Z][a-zA-Z0-9]*$``",
* or, shall be equal to "``N/A``".
@@ -2672,7 +2672,7 @@ A value of this type shall be of one of the following variants:
* The value may be a string. It shall be the name of a state of the condition
or ``N/A`` if the condition is not applicable. The value
- * shall match with the regular expression "``^[A-Z][a-zA-Z0-9]+$``",
+ * shall match with the regular expression "``^[A-Z][a-zA-Z0-9]*$``",
* or, shall be equal to "``N/A``".
@@ -2693,7 +2693,7 @@ the horizontal space is limited by the page width. The more conditions you
have in an action requirement, the shorter the names should be. The name
``NA`` is reserved and indicates that a condition is not applicable. The value
-* shall match with the regular expression "``^[A-Z][a-zA-Z0-9]+$``",
+* shall match with the regular expression "``^[A-Z][a-zA-Z0-9]*$``",
* and, shall be not equal to "``NA``".
@@ -2807,7 +2807,7 @@ A value of this type shall be of one of the following variants:
corresponding post-condition or ``N/A`` if the post-condition is not
applicable. The value
- * shall match with the regular expression "``^[A-Z][a-zA-Z0-9]+$``",
+ * shall match with the regular expression "``^[A-Z][a-zA-Z0-9]*$``",
* or, shall be equal to "``N/A``".
@@ -2837,7 +2837,7 @@ A value of this type shall be of one of the following variants:
reason is given instead of a listing of post-condition states, then this
transition is skipped and no test code runs for this transition. The value
- * shall match with the regular expression "``^[A-Z][a-zA-Z0-9]+$``",
+ * shall match with the regular expression "``^[A-Z][a-zA-Z0-9]*$``",
* and, shall be not equal to "``NA``".
@@ -3322,6 +3322,12 @@ get-string
``name`` attribute. If no such variable exists in the configuration file,
then the default value is used. The value is converted to a string.
+get-string-command-line
+ The attribute value shall be a string. The action gets the action value for
+ subsequent actions from the value of a command line option named by the
+ items ``name`` attribute. If no such command line option is present, then
+ the attribute value is used. The value is converted to a string.
+
script
The attribute value shall be a string. The action executes the attribute
value with the Python ``eval()`` function in the context of the script
@@ -4816,6 +4822,10 @@ value. The value shall be an element of
* "``mean-upper-bound``",
+* "``median-lower-bound``",
+
+* "``median-upper-bound``",
+
* "``min-lower-bound``", and
* "``min-upper-bound``".
diff --git a/eng/tester.rst b/eng/tester.rst
index a538caf..5b57842 100644
--- a/eng/tester.rst
+++ b/eng/tester.rst
@@ -1,12 +1,17 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
-.. Copyright (C) 2018.
+.. Copyright (C) 2018, 2022.
.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project
RTEMS Tester
************
-TBD - Convert the following to Rest and insert into this file
-TBD https://devel.rtems.org/wiki/Testing/Tester
-TBD - Above file is horribly out of date. Find new docs and refer to them
+The RTEMS Tester is a test tool which provides a command line interface and
+automates execution of test executables. It is part of the `rtems-tools`
+repository and built as part of the RTEMS Tools for all targets by the
+RTEMS Source Builder. The RTEMS Tester can be configured to test based
+on local lab setup or to test on custom boards.
+
+The RTEMS Tester is documented the `RTEMS Tester and Run` section of the
+`RTEMS User Manual`.
diff --git a/user/bsps/aarch64/xilinx-zynqmp.rst b/user/bsps/aarch64/xilinx-zynqmp.rst
index ca232de..78bff12 100644
--- a/user/bsps/aarch64/xilinx-zynqmp.rst
+++ b/user/bsps/aarch64/xilinx-zynqmp.rst
@@ -44,6 +44,173 @@ When booting via u-boot, RTEMS must be packaged into a u-boot image or booted
as a raw binary since u-boot does not currently support ELF64 which is required
for AArch64 ELF binaries.
+Example: Booting a RTEMS image on the ZCU102 ZynqMP board
+---------------------------------------------------------
+
+This example will walk through the steps needed for booting RTEMS from a SD card
+on the
+`ZCU102 ZynqMP board. <https://www.xilinx.com/products/boards-and-kits/ek-u1-zcu102-g.html>`_
+The reference for setting up a SD card and obtaining pre-built boot images is
+`here. <https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/18841858/Board+bring+up+using+pre-built+images>`_
+
+Hardware Setup
+^^^^^^^^^^^^^^
+
+Set the dip switch SW6 according to the table below. This will allow the board
+to boot from the SD card. Connect a Micro-USB cable to the USB UART interface
+J83. This is a quad USB UART interface which will show up on the development
+host computer as four different serial or tty devices. Use the first channel
+for the console UART. It should be set to 115k baud.
+
++---------------------------+
+| Dip Switch JW6 |
++------+------+------+------+
+| ON | OFF | OFF | OFF |
++------+------+------+------+
+
+Prepare a SD card with a bootable partition
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The goal is to have a bootable SD card with a partition that is formatted with
+the FAT file system. The file system will contain the boot artifacts including
+BOOT.bin and the u-boot image. The RTEMS image will be placed on this volume. To
+create the bootable SD card, follow the directions
+`here. <https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/18842385/How+to+format+SD+card+for+SD+boot>`_
+
+Once you have the card formatted correctly, you need to place the files from
+`this archive <https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/2202763266/2021.2+Release#Downloads>`_
+on the FAT partition. The following file was used for this example:
+`xilinx-vck190-v2021.2-final.bsp <https://www.xilinx.com/member/forms/download/xef.html?filename=xilinx-vck190-v2021.2-final.bsp>`_
+
+In order to download these files, you need to have a Xilinx account login. As an
+alternative, you can download a bootable image for Ubuntu 20.04 and write it to
+an SD card using a utility such as `Balena Etcher <https://www.balena.io/etcher>`_
+or dd. The Ubuntu image is available `here. <https://ubuntu.com/download/xilinx>`_
+Download the image for the Zynq Ultrascale+ MPSoC Development boards, uncompress
+it and write it to the SD card. This image creates multiple partitions, but we
+only need to use the FAT partition with the boot artifacts on it.
+
+Verify that the board can boot from the SD card
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It is worth booting the board from the SD card before trying to boot RTEMS.
+Insert the card and power on the board. You should see the messages on the first
+console indicating the various boot loader stages and eventually the Linux
+kernel. The goal is to interrupt u-boot when given the chance to access the
+u-boot command prompt.
+
+Build RTEMS with examples
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Build the RTEMS `xilinx-zynqmp-lp64-zu3eg` BSP. Use the ticker.exe sample which
+can be found in the directory:
+
+.. code-block:: shell
+
+ build/aarch64/xilinx-zynqmp-lp64-zu3eg/testsuites/samples
+
+Prepare the RTEMS image
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Prepare your RTEMS image to boot from u-boot with the following commands:
+
+.. code-block:: shell
+
+ $ aarch64-rtems6-objcopy -Obinary ticker.exe ticker.bin
+ $ gzip -9 ticker.bin
+ $ mkimage -A arm64 -O rtems -T kernel -a 0x10000000 -e 0x10000000 -n RTEMS -d ticker.bin.gz rtems.img
+
+Boot the RTEMS image
+^^^^^^^^^^^^^^^^^^^^
+Copy the prepared RTEMS image to the SD card and insert the SD crd in the ZCU102
+board. Power on the board. When you see the prompt on the console to interupt
+u-boot, hit a key to bring up the u-boot command prompt. On the u-boot command
+prompt you can boot your RTEMS image:
+
+.. code-block:: shell
+
+ Zynq-MP> fatload mmc 0:1 0x1000 rtems.img
+ Zynq-MP> bootm 0x1000
+
+This is the entire boot sequence:
+
+.. code-block:: shell
+
+ Pre-FSBL boot Started
+ Xilinx Zynq MP First Stage Boot Loader
+ Release 2020.2 Nov 18 2020 - 11:46:01
+ NOTICE: ATF running on XCZU9EG/silicon v1/RTL5.1 at 0xfffea000
+ NOTICE: BL31: v2.2(release):xilinx_rebase_v2.2_2020.1-10-ge6eea88b1
+ NOTICE: BL31: Built : 12:28:45, Nov 17 2020
+
+ U-Boot 2020.01 (Jun 15 2021 - 14:24:32 +0000)
+
+ Model: ZynqMP ZCU102 Rev1.0
+ Board: Xilinx ZynqMP
+ DRAM: 4 GiB
+ PMUFW: v1.1
+ EL Level: EL2
+ Chip ID: zu9eg
+ NAND: 0 MiB
+ MMC: mmc@ff170000: 0
+ In: serial@ff000000
+ Out: serial@ff000000
+ Err: serial@ff000000
+ Bootmode: SD_MODE1
+ Reset reason: SOFT
+ Net:
+ ZYNQ GEM: ff0e0000, mdio bus ff0e0000, phyaddr 12, interface rgmii-id
+
+ Warning: ethernet@ff0e0000 (eth0) using random MAC address - 82:32:1d:80:d9:c9
+ eth0: ethernet@ff0e0000
+ Hit any key to stop autoboot: 0
+
+ ZynqMP> fatload mmc 0:1 0x1000 rtems.img
+ 46669 bytes read in 27 ms (1.6 MiB/s)
+ ZynqMP> bootm 0x1000
+ ## Booting kernel from Legacy Image at 00001000 ...
+ Image Name: RTEMS
+ Image Type: AArch64 RTEMS Kernel Image (gzip compressed)
+ Data Size: 46605 Bytes = 45.5 KiB
+ Load Address: 10000000
+ Entry Point: 10000000
+ Verifying Checksum ... OK
+ Uncompressing Kernel Image
+ ## Transferring control to RTEMS (at address 10000000) ...
+
+ *** BEGIN OF TEST CLOCK TICK ***
+ *** TEST VERSION: 6.0.0.f381e9bab29278e4434b1a93e70d17a7562dc64c
+ *** TEST STATE: EXPECTED_PASS
+ *** TEST BUILD: RTEMS_POSIX_API RTEMS_SMP
+ *** TEST TOOLS: 10.3.1 20210409 (RTEMS 6, RSB ad54d1dd3cf8249d9d39deb1dd28b2f294df062d, Newlib eb03ac1)
+ TA1 - rtems_clock_get_tod - 09:00:00 12/31/1988
+ TA2 - rtems_clock_get_tod - 09:00:00 12/31/1988
+ TA3 - rtems_clock_get_tod - 09:00:00 12/31/1988
+ TA1 - rtems_clock_get_tod - 09:00:05 12/31/1988
+ TA2 - rtems_clock_get_tod - 09:00:10 12/31/1988
+ TA1 - rtems_clock_get_tod - 09:00:10 12/31/1988
+ TA1 - rtems_clock_get_tod - 09:00:15 12/31/1988
+ TA3 - rtems_clock_get_tod - 09:00:15 12/31/1988
+ TA2 - rtems_clock_get_tod - 09:00:20 12/31/1988
+ TA1 - rtems_clock_get_tod - 09:00:20 12/31/1988
+ TA1 - rtems_clock_get_tod - 09:00:25 12/31/1988
+ TA2 - rtems_clock_get_tod - 09:00:30 12/31/1988
+ TA1 - rtems_clock_get_tod - 09:00:30 12/31/1988
+ TA3 - rtems_clock_get_tod - 09:00:30 12/31/1988
+
+ *** END OF TEST CLOCK TICK ***
+
+ [ RTEMS shutdown ]
+
+
+Follow up
+^^^^^^^^^
+
+This is just one possible way to boot the RTEMS image. For a development
+environment you may wish to configure u-boot to boot the RTEMS image from a TFTP
+server. For a production environment, you may wish to download, configure, and
+build u-boot, or develop a BOOT.BIN image with the RTEMS application.
+
Clock Driver
------------
diff --git a/user/bsps/arm/bsp-stm32h7.rst b/user/bsps/arm/bsp-stm32h7.rst
deleted file mode 100644
index bc2b471..0000000
--- a/user/bsps/arm/bsp-stm32h7.rst
+++ /dev/null
@@ -1,32 +0,0 @@
-.. SPDX-License-Identifier: CC-BY-SA-4.0
-
-.. Copyright (C) 2020 embedded brains GmbH
-
-stm32h7
-=======
-
-This BSP supports the
-`STM32H7 Series <https://www.st.com/en/microcontrollers-microprocessors/stm32h7-series.html>`_.
-The BSP is known to run on these boards:
-
-* `STM32H743I-EVAL 2 <https://www.st.com/en/evaluation-tools/stm32h743i-eval.html>`_
-
-Clock Driver
-------------
-
-The clock driver uses the `ARMv7-M Systick` module.
-
-Console Driver
---------------
-
-The console driver supports the on-chip UART and USART modules.
-
-Network Interface Driver
-------------------------
-
-The network interface driver ``if_stmac`` is provided by the ``libbsd``.
-
-USB Host Driver
----------------
-
-The USB host driver ``dwc_otg`` is provided by the ``libbsd``.
diff --git a/user/bsps/arm/imxrt.rst b/user/bsps/arm/imxrt.rst
index f8d9731..6dacfd9 100644
--- a/user/bsps/arm/imxrt.rst
+++ b/user/bsps/arm/imxrt.rst
@@ -128,9 +128,11 @@ with your FDT source names)::
-I ${PREFIX}/arm-rtems6/imxrt1052/lib/include \
-include "YOUR.dts" /dev/null | \
dtc -O dtb -o "YOUR.dtb" -b 0 -p 64
- sh> rtems-bin2c -C -N imxrt_dtb "YOUR.dtb" "YOUR.c"
+ sh> rtems-bin2c -A 8 -C -N imxrt_dtb "YOUR.dtb" "YOUR.c"
-Make sure that your new C file is compiled and linked into the application.
+You'll get a C file which defines the `imxrt_dtb` array. Make sure that your new
+C file is compiled and linked into the application. It will overwrite the
+existing definition of the `imxrt_dtb` in RTEMS.
PLL Settings
------------
diff --git a/user/bsps/bsps-arm.rst b/user/bsps/bsps-arm.rst
index f8a1d60..7f1e9d4 100644
--- a/user/bsps/bsps-arm.rst
+++ b/user/bsps/bsps-arm.rst
@@ -9,7 +9,6 @@ arm (ARM)
.. include:: arm/altera-cyclone-v.rst
.. include:: arm/atsam.rst
.. include:: arm/beagle.rst
-.. include:: arm/bsp-stm32h7.rst
.. include:: arm/csb336.rst
.. include:: arm/csb337.rst
.. include:: arm/edb7312.rst
diff --git a/user/bsps/bsps-microblaze.rst b/user/bsps/bsps-microblaze.rst
index dbb574f..e20df53 100644
--- a/user/bsps/bsps-microblaze.rst
+++ b/user/bsps/bsps-microblaze.rst
@@ -1,8 +1,153 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
.. Copyright (C) 2018 embedded brains GmbH
+.. Copyright (C) 2022 On-Line Applications Research Corporation (OAR)
-microblaze (Microblaze)
+microblaze (MicroBlaze)
***********************
-There are no Microblaze BSPs yet.
+KCU105 QEMU
+===========
+
+The basic hardware initialization is performed by the BSP. This BSP supports the
+QEMU emulated Xilinx AXI Interrupt Controller v4.1.
+
+Boot via ELF
+------------
+
+The executable image is booted by QEMU in ELF format.
+
+Clock Driver
+------------
+
+The clock driver supports the QEMU emulated Xilinx AXI Timer v2.0. It is
+implemented as a simple downcounter.
+
+Console Driver
+--------------
+
+The console driver supports the QEMU emulated Xilinx AXI UART Lite v2.0. It is
+initialized to a baud rate of 115200.
+
+Network Driver
+--------------
+
+Support for networking is provided by the libbsd library. Network interface
+configuration is extracted from the device tree binary which, by default, is
+in `<bsp/microblaze-dtb.h> <https://git.rtems.org/rtems/tree/bsps/microblaze/microblaze_fpga/include/bsp/microblaze-dtb.h>`_.
+The device tree source for the default device tree is at `dts/system.dts <https://git.rtems.org/rtems/tree/bsps/microblaze/microblaze_fpga/dts/system.dts>`_.
+
+To replace the default device tree with your own, assuming ``my_device_tree.dts``
+is the name of your device tree source file, first you must convert your device
+tree to .dtb format.
+
+.. code-block:: none
+
+ $ dtc -I dts -O dtb my_device_tree.dts > my_device_tree.dtb
+
+The device tree blob, ``my_device_tree.dtb``, can now be converted to a C file.
+The name ``system_dtb`` is significant as it is the name expected by the BSP.
+
+.. code-block:: none
+
+ $ rtems-bin2c -C -A 8 -N system_dtb my_device_tree.dtb my_dtb
+
+The ``BSP_MICROBLAZE_FPGA_DTB_HEADER_PATH`` BSP configuration option can then be
+set to the path of the resulting source file, ``my_dtb.c``, to include it in the
+BSP build.
+
+.. code-block:: none
+
+ BSP_MICROBLAZE_FPGA_DTB_HEADER_PATH = /path/to/my_dtb.c
+
+
+Running Executables
+-------------------
+
+A .dtb (device tree blob) file should be provided to QEMU via the ``-hw-dtb``
+option. In the example command below, the device tree blob comes from the Xilinx
+Petalinux KCU105 MicroBlaze BSP (https://www.xilinx.com/support/download/index.html/content/xilinx/en/downloadNav/embedded-design-tools.html).
+
+Executables generated by this BSP can be run using the following command:
+
+.. code-block:: none
+
+ $ qemu-system-microblazeel -no-reboot -nographic -M microblaze-fdt-plnx -m 256 \
+ -serial mon:stdio -display none -hw-dtb system.dtb -kernel example.exe
+
+Debugging with QEMU
+-------------------
+
+To debug an application, add the option ``-s`` to make QEMU listen for GDB
+connections on port 1234. Add the ``-S`` option to also stop execution until
+a connection is made.
+
+For example, to debug the hello sample and break at ``Init``, first start QEMU.
+
+.. code-block:: none
+
+ $ qemu-system-microblazeel -no-reboot -nographic -M microblaze-fdt-plnx -m 256 \
+ -serial mon:stdio -display none -hw-dtb system.dtb -kernel \
+ build/microblaze/kcu105_qemu/testsuites/samples/hello.exe -s -S
+
+Then start GDB and connect to QEMU.
+
+.. code-block:: none
+
+ $ microblaze-rtems6-gdb build/microblaze/kcu105_qemu/testsuites/samples/hello.exe
+ (gdb) target remote localhost:1234
+ (gdb) break Init
+ (gdb) continue
+
+KCU105
+======
+
+The basic hardware initialization is performed by the BSP. This BSP supports the
+Xilinx AXI Interrupt Controller v4.1.
+
+This BSP was tested using the Xilinx Kintex UltraScale FPGA KCU105 board
+configured with the default Petalinux KCU105 MicroBlaze BSP. The defaults may
+need to be adjusted using BSP configuration options to match the memory layout
+and configuration of your board.
+
+Clock Driver
+------------
+
+The clock driver supports the Xilinx AXI Timer v2.0. It is implemented as a
+simple downcounter.
+
+Console Driver
+--------------
+
+The console driver supports the Xilinx AXI UART Lite v2.0.
+
+Debugging
+---------
+
+The following debugging procedure was used for debugging RTEMS applications
+running on the Xilinx KCU105 board using GDB.
+
+First send an FPGA bitstream to the board using OpenOCD.
+
+.. code-block:: none
+
+ $ openocd -f board/kcu105.cfg -c "init; pld load 0 system.bit; exit"
+
+After the board has been programmed, start the Vivado ``hw_server`` application
+to serve as the debug server. Leave it running in the background for the rest of
+the process.
+
+.. code-block:: none
+
+ $ tools/Xilinx/Vivado/2020.2/bin/hw_server
+
+With the debug server running, connect to the debug server with GDB, load the
+application, and debug as usual. By default the GDB server listens on port 3002.
+
+.. code-block:: none
+
+ $ microblaze-rtems6-gdb example.exe
+ (gdb) target extended-remote localhost:3002
+ (gdb) load
+ (gdb) break Init
+ (gdb) continue
diff --git a/user/hosts/posix.rst b/user/hosts/posix.rst
index 818eb25..9769e07 100644
--- a/user/hosts/posix.rst
+++ b/user/hosts/posix.rst
@@ -74,7 +74,7 @@ provide a manual override:
CentOS
~~~~~~
-The following packages are required on a minimal CentOS 6.3 or Cent)S 7
+The following packages are required on a minimal CentOS 6.3 or CentOS 7
64-bit installation:
.. code-block:: none
@@ -137,23 +137,23 @@ prefix under your home directory as recommended and end up on the SD card.
Ubuntu
~~~~~~
-The latest version is Ubuntu 18.04.1 LTS 64-bit. This section also includes
+The latest version is Ubuntu 20.04.3 LTS 64-bit. This section also includes
Xubuntu. A minimal installation was used and the following packages installed:
.. code-block:: none
- $ sudo apt-get build-dep build-essential gcc-defaults g++ gdb git \
- unzip pax bison flex texinfo unzip python3-dev libpython-dev \
- libncurses5-dev zlib1g-dev
+ $ sudo apt-get build-dep build-essential gcc-defaults g++ gdb unzip \
+ pax bison flex texinfo python3-dev libpython2-dev libncurses5-dev \
+ zlib1g-dev
-Note that in previous versions of Ubuntu, the package libpython-dev was
+Note that in previous versions of Ubuntu, the package libpython2-dev was
python2.7-dev. The name of packages changes over time. You need the
package with Python development libraries for C/C++ programs. The following
is needed for recent versions:
.. code-block:: none
- $ sudo apt-get install python-dev
+ $ sudo apt-get install python git
It is likely necessary that you will have to enable the Ubuntu Source
Repositories. Users have suggested the following web pages which have
diff --git a/user/overview/index.rst b/user/overview/index.rst
index 550724a..16389d9 100644
--- a/user/overview/index.rst
+++ b/user/overview/index.rst
@@ -355,6 +355,7 @@ sophisticated real-time applications are significantly reduced.
.. [#] Thread-local storage requires some support by the tool chain and the
RTEMS architecture support, e.g. context-switch code. It is supported
- at least on ARM, PowerPC, RISC-V, SPARC and m68k. Check the
- `RTEMS CPU Architecture Supplement <https://docs.rtems.org/branches/master/cpu-supplement.pdf>`_
- if it is supported.
+ at least on ARM, AArch64, PowerPC, RISC-V, SPARC, MicroBlaze, Nios II,
+ and m68k. Check the `RTEMS CPU Architecture Supplement
+ <https://docs.rtems.org/branches/master/cpu-supplement.pdf>`_ if it is
+ supported.