summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--c-user/clock/background.rst85
-rw-r--r--c-user/clock/directives.rst92
-rw-r--r--c-user/clock/introduction.rst12
-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/altera_nios_ii.rst2
-rw-r--r--cpu-supplement/arm.rst6
-rw-r--r--cpu-supplement/index.rst1
-rw-r--r--cpu-supplement/sparc.rst101
-rw-r--r--cpu-supplement/xilinx_microblaze.rst52
-rw-r--r--eng/coding-conventions.rst2
-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/imx.rst17
-rw-r--r--user/bsps/arm/imxrt.rst6
-rw-r--r--user/bsps/arm/stm32h7.rst544
-rw-r--r--user/bsps/arm/xilinx-zynq.rst18
-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
32 files changed, 1435 insertions, 268 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 b6a1069..6e1542c 100644
--- a/c-user/clock/directives.rst
+++ b/c-user/clock/directives.rst
@@ -255,9 +255,9 @@ Gets the time elapsed since the :term:`Unix epoch` measured using
.. rubric:: NOTES:
The directive accesses a device provided by the :term:`Clock Driver` to get the
-time in the highest precision available to the system. Alternatively, the
+time in the highest resolution available to the system. Alternatively, the
:ref:`InterfaceRtemsClockGetRealtimeCoarse` directive may be used to get the
-time with less precision and less runtime overhead.
+time in a lower resolution and with less runtime overhead.
See :ref:`InterfaceRtemsClockGetRealtimeBintime` and
:ref:`InterfaceRtemsClockGetRealtimeTimeval` to get the time in alternative
@@ -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
@@ -307,9 +307,9 @@ Gets the time elapsed since the :term:`Unix epoch` measured using
.. rubric:: NOTES:
The directive accesses a device provided by the :term:`Clock Driver` to get the
-time in the highest precision available to the system. Alternatively, the
+time in the highest resolution available to the system. Alternatively, the
:ref:`InterfaceRtemsClockGetRealtimeCoarseBintime` directive may be used to get
-the time with less precision and less runtime overhead.
+the time in a lower resolution and with less runtime overhead.
See :ref:`InterfaceRtemsClockGetRealtime` and
:ref:`InterfaceRtemsClockGetRealtimeTimeval` to get the time in alternative
@@ -360,9 +360,9 @@ Gets the time elapsed since the :term:`Unix epoch` measured using
.. rubric:: NOTES:
The directive accesses a device provided by the :term:`Clock Driver` to get the
-time in the highest precision available to the system. Alternatively, the
+time in the highest resolution available to the system. Alternatively, the
:ref:`InterfaceRtemsClockGetRealtimeCoarseTimeval` directive may be used to get
-the time with less precision and less runtime overhead.
+the time in a lower resolution and with less runtime overhead.
See :ref:`InterfaceRtemsClockGetRealtime` and
:ref:`InterfaceRtemsClockGetRealtimeBintime` to get the time in alternative
@@ -392,7 +392,7 @@ rtems_clock_get_realtime_coarse()
---------------------------------
Gets the time elapsed since the :term:`Unix epoch` measured using
-:term:`CLOCK_REALTIME` in coarse precision in seconds and nanoseconds format.
+:term:`CLOCK_REALTIME` in coarse resolution in seconds and nanoseconds format.
.. rubric:: CALLING SEQUENCE:
@@ -415,8 +415,8 @@ Gets the time elapsed since the :term:`Unix epoch` measured using
The directive does not access a device to get the time. It uses a recent
snapshot provided by the :term:`Clock Driver`. Alternatively, the
-:ref:`InterfaceRtemsClockGetRealtime` directive may be used to get the time
-with higher precision and higher runtime overhead.
+:ref:`InterfaceRtemsClockGetRealtime` directive may be used to get the time in
+a higher resolution and with a higher runtime overhead.
See :ref:`InterfaceRtemsClockGetRealtimeCoarseBintime` and
:ref:`InterfaceRtemsClockGetRealtimeCoarseTimeval` to get the time in
@@ -446,7 +446,7 @@ rtems_clock_get_realtime_coarse_bintime()
-----------------------------------------
Gets the time elapsed since the :term:`Unix epoch` measured using
-:term:`CLOCK_REALTIME` in coarse precision in binary time format.
+:term:`CLOCK_REALTIME` in coarse resolution in binary time format.
.. rubric:: CALLING SEQUENCE:
@@ -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
@@ -469,7 +469,7 @@ Gets the time elapsed since the :term:`Unix epoch` measured using
The directive does not access a device to get the time. It uses a recent
snapshot provided by the :term:`Clock Driver`. Alternatively, the
:ref:`InterfaceRtemsClockGetRealtimeBintime` directive may be used to get the
-time with higher precision and higher runtime overhead.
+time in a higher resolution and with a higher runtime overhead.
See :ref:`InterfaceRtemsClockGetRealtimeCoarse` and
:ref:`InterfaceRtemsClockGetRealtimeCoarseTimeval` to get the time in
@@ -499,7 +499,7 @@ rtems_clock_get_realtime_coarse_timeval()
-----------------------------------------
Gets the time elapsed since the :term:`Unix epoch` measured using
-:term:`CLOCK_REALTIME` in coarse precision in seconds and microseconds format.
+:term:`CLOCK_REALTIME` in coarse resolution in seconds and microseconds format.
.. rubric:: CALLING SEQUENCE:
@@ -523,7 +523,7 @@ Gets the time elapsed since the :term:`Unix epoch` measured using
The directive does not access a device to get the time. It uses a recent
snapshot provided by the :term:`Clock Driver`. Alternatively, the
:ref:`InterfaceRtemsClockGetRealtimeTimeval` directive may be used to get the
-time with higher precision and higher runtime overhead.
+time in a higher resolution and with a higher runtime overhead.
See :ref:`InterfaceRtemsClockGetRealtimeCoarse` and
:ref:`InterfaceRtemsClockGetRealtimeCoarseTimeval` to get the time in
@@ -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
@@ -574,9 +575,9 @@ the :term:`CLOCK_MONOTONIC` in seconds and nanoseconds format.
.. rubric:: NOTES:
The directive accesses a device provided by the :term:`Clock Driver` to get the
-time in the highest precision available to the system. Alternatively, the
+time in the highest resolution available to the system. Alternatively, the
:ref:`InterfaceRtemsClockGetMonotonicCoarse` directive may be used to get the
-time with less precision and less runtime overhead.
+time with in a lower resolution and with less runtime overhead.
See :ref:`InterfaceRtemsClockGetMonotonicBintime`,
:ref:`InterfaceRtemsClockGetMonotonicSbintime`, and
@@ -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
@@ -628,9 +629,9 @@ the :term:`CLOCK_MONOTONIC` in binary time format.
.. rubric:: NOTES:
The directive accesses a device provided by the :term:`Clock Driver` to get the
-time in the highest precision available to the system. Alternatively, the
+time in the highest resolution available to the system. Alternatively, the
:ref:`InterfaceRtemsClockGetMonotonicCoarseBintime` directive may be used to
-get the time with less precision and less runtime overhead.
+get the time in a lower resolution and with less runtime overhead.
See :ref:`InterfaceRtemsClockGetMonotonic`,
:ref:`InterfaceRtemsClockGetMonotonicSbintime`, and
@@ -677,7 +678,7 @@ the :term:`CLOCK_MONOTONIC` at some time point during the directive call.
.. rubric:: NOTES:
The directive accesses a device provided by the :term:`Clock Driver` to get the
-time in the highest precision available to the system.
+time in the highest resolution available to the system.
See :ref:`InterfaceRtemsClockGetMonotonic`,
:ref:`InterfaceRtemsClockGetMonotonicBintime`, and
@@ -719,19 +720,20 @@ 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:
The directive accesses a device provided by the :term:`Clock Driver` to get the
-time in the highest precision available to the system. Alternatively, the
+time in the highest resolution available to the system. Alternatively, the
:ref:`InterfaceRtemsClockGetMonotonicCoarseTimeval` directive may be used to
-get the time with less precision and less runtime overhead.
+get the time in a lower resolution and with less runtime overhead.
See :ref:`InterfaceRtemsClockGetMonotonic`,
:ref:`InterfaceRtemsClockGetMonotonicBintime`, and
@@ -762,7 +764,7 @@ rtems_clock_get_monotonic_coarse()
----------------------------------
Gets the time elapsed since some fixed time point in the past measured using
-the :term:`CLOCK_MONOTONIC` in coarse precision in seconds and nanoseconds
+the :term:`CLOCK_MONOTONIC` in coarse resolution in seconds and nanoseconds
format.
.. rubric:: CALLING SEQUENCE:
@@ -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
@@ -785,8 +788,8 @@ format.
The directive does not access a device to get the time. It uses a recent
snapshot provided by the :term:`Clock Driver`. Alternatively, the
-:ref:`InterfaceRtemsClockGetMonotonic` directive may be used to get the time
-with higher precision and higher runtime overhead.
+:ref:`InterfaceRtemsClockGetMonotonic` directive may be used to get the time in
+a higher resolution and with a higher runtime overhead.
See :ref:`InterfaceRtemsClockGetMonotonicCoarseBintime` and
:ref:`InterfaceRtemsClockGetMonotonicCoarseTimeval` to get the time in
@@ -816,7 +819,7 @@ rtems_clock_get_monotonic_coarse_bintime()
------------------------------------------
Gets the time elapsed since some fixed time point in the past measured using
-the :term:`CLOCK_MONOTONIC` in coarse precision in binary time format.
+the :term:`CLOCK_MONOTONIC` in coarse resolution in binary time format.
.. rubric:: CALLING SEQUENCE:
@@ -827,7 +830,7 @@ the :term:`CLOCK_MONOTONIC` in coarse precision 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
@@ -839,7 +842,7 @@ the :term:`CLOCK_MONOTONIC` in coarse precision in binary time format.
The directive does not access a device to get the time. It uses a recent
snapshot provided by the :term:`Clock Driver`. Alternatively, the
:ref:`InterfaceRtemsClockGetMonotonicBintime` directive may be used to get the
-time with higher precision and higher runtime overhead.
+time in a higher resolution and with a higher runtime overhead.
See :ref:`InterfaceRtemsClockGetMonotonicCoarse` and
:ref:`InterfaceRtemsClockGetMonotonicCoarseTimeval` to get the time in
@@ -869,7 +872,7 @@ rtems_clock_get_monotonic_coarse_timeval()
------------------------------------------
Gets the time elapsed since some fixed time point in the past measured using
-the :term:`CLOCK_MONOTONIC` in coarse precision in seconds and microseconds
+the :term:`CLOCK_MONOTONIC` in coarse resolution in seconds and microseconds
format.
.. rubric:: CALLING SEQUENCE:
@@ -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:
@@ -893,7 +897,7 @@ format.
The directive does not access a device to get the time. It uses a recent
snapshot provided by the :term:`Clock Driver`. Alternatively, the
:ref:`InterfaceRtemsClockGetMonotonicTimeval` directive may be used to get the
-time with higher precision and higher runtime overhead.
+time in a higher resolution and with a higher runtime overhead.
See :ref:`InterfaceRtemsClockGetMonotonicCoarse` and
:ref:`InterfaceRtemsClockGetMonotonicCoarseBintime` to get the time in
@@ -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/clock/introduction.rst b/c-user/clock/introduction.rst
index cfc8871..13be673 100644
--- a/c-user/clock/introduction.rst
+++ b/c-user/clock/introduction.rst
@@ -81,16 +81,16 @@ capabilities. The directives provided by the Clock Manager are:
microseconds format.
* :ref:`InterfaceRtemsClockGetRealtimeCoarse` - Gets the time elapsed since the
- :term:`Unix epoch` measured using :term:`CLOCK_REALTIME` in coarse precision
+ :term:`Unix epoch` measured using :term:`CLOCK_REALTIME` in coarse resolution
in seconds and nanoseconds format.
* :ref:`InterfaceRtemsClockGetRealtimeCoarseBintime` - Gets the time elapsed
since the :term:`Unix epoch` measured using :term:`CLOCK_REALTIME` in coarse
- precision in binary time format.
+ resolution in binary time format.
* :ref:`InterfaceRtemsClockGetRealtimeCoarseTimeval` - Gets the time elapsed
since the :term:`Unix epoch` measured using :term:`CLOCK_REALTIME` in coarse
- precision in seconds and microseconds format.
+ resolution in seconds and microseconds format.
* :ref:`InterfaceRtemsClockGetMonotonic` - Gets the time elapsed since some
fixed time point in the past measured using the :term:`CLOCK_MONOTONIC` in
@@ -110,15 +110,15 @@ capabilities. The directives provided by the Clock Manager are:
* :ref:`InterfaceRtemsClockGetMonotonicCoarse` - Gets the time elapsed since
some fixed time point in the past measured using the :term:`CLOCK_MONOTONIC`
- in coarse precision in seconds and nanoseconds format.
+ in coarse resolution in seconds and nanoseconds format.
* :ref:`InterfaceRtemsClockGetMonotonicCoarseBintime` - Gets the time elapsed
since some fixed time point in the past measured using the
- :term:`CLOCK_MONOTONIC` in coarse precision in binary time format.
+ :term:`CLOCK_MONOTONIC` in coarse resolution in binary time format.
* :ref:`InterfaceRtemsClockGetMonotonicCoarseTimeval` - Gets the time elapsed
since some fixed time point in the past measured using the
- :term:`CLOCK_MONOTONIC` in coarse precision in seconds and microseconds
+ :term:`CLOCK_MONOTONIC` in coarse resolution in seconds and microseconds
format.
* :ref:`InterfaceRtemsClockGetBootTime` - Gets the time elapsed since the
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/altera_nios_ii.rst b/cpu-supplement/altera_nios_ii.rst
index e8a6e95..d30a40d 100644
--- a/cpu-supplement/altera_nios_ii.rst
+++ b/cpu-supplement/altera_nios_ii.rst
@@ -13,4 +13,4 @@ SMP is not supported.
Thread-Local Storage
====================
-Thread-local storage is not implemented.
+Thread-local storage is supported.
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 f3851dc..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
@@ -25,7 +26,7 @@ to that processor.
**SPARC Architecture Documents**
For information on the SPARC architecture, refer to the following documents
-available from SPARC International, Inc. (http://www.sparc.com):
+available from SPARC International, Inc. (`<https://sparc.org/>`_):
- SPARC Standard Version 7.
@@ -285,11 +286,11 @@ Special Registers
~~~~~~~~~~~~~~~~~
The SPARC architecture includes two special registers which are critical to the
-programming model: the Processor State Register (psr) and the Window Invalid
-Mask (wim). The psr contains the condition codes, processor interrupt level,
+programming model: the Processor State Register (``PSR``) and the Window Invalid
+Mask (``WIM``). The ``PSR`` contains the condition codes, processor interrupt level,
trap enable bit, supervisor mode and previous supervisor mode bits, version
information, floating point unit and coprocessor enable bits, and the current
-window pointer (cwp). The cwp field of the psr and wim register are used to
+window pointer (``CWP``). The ``CWP`` field of the ``PSR`` and ``WIM`` register are used to
manage the register windows in the SPARC architecture. The register windows
are discussed in more detail below.
@@ -330,15 +331,15 @@ underflow condition must be handled in software by a trap handler. The window
underflow trap handler is responsible for reloading the contents of the
register window requested by the restore instruction from the program stack.
-The Window Invalid Mask (wim) and the Current Window Pointer (cwp) field in the
-psr are used in conjunction to manage the finite set of register windows and
-detect the window overflow and underflow conditions. The cwp contains the
+The Window Invalid Mask (``WIM``) and the Current Window Pointer (``CWP``) field in the
+``PSR`` are used in conjunction to manage the finite set of register windows and
+detect the window overflow and underflow conditions. The ``CWP`` contains the
index of the register window currently in use. The save instruction decrements
-the cwp modulo the number of register windows. Similarly, the restore
-instruction increments the cwp modulo the number of register windows. Each bit
-in the wim represents represents whether a register window contains valid
+the ``CWP`` modulo the number of register windows. Similarly, the restore
+instruction increments the ``CWP`` modulo the number of register windows. Each bit
+in the ``WIM`` represents represents whether a register window contains valid
information. The value of 0 indicates the register window is valid and 1
-indicates it is invalid. When a save instruction causes the cwp to point to a
+indicates it is invalid. When a save instruction causes the ``CWP`` to point to a
register window which is marked as invalid, a window overflow condition
results. Conversely, the restore instruction may result in a window underflow
condition.
@@ -346,8 +347,8 @@ condition.
Other than the assumption that a register window is always available for trap
(i.e. interrupt) handlers, the SPARC architecture places no limits on the
number of register windows simultaneously marked as invalid (i.e. number of
-bits set in the wim). However, RTEMS assumes that only one register window is
-marked invalid at a time (i.e. only one bit set in the wim). This makes the
+bits set in the ``WIM``). However, RTEMS assumes that only one register window is
+marked invalid at a time (i.e. only one bit set in the ``WIM``). This makes the
maximum possible number of register windows available to the user while still
meeting the requirement that window overflow and underflow conditions can be
detected.
@@ -356,7 +357,7 @@ The window overflow and window underflow trap handlers are a critical part of
the run-time environment for a SPARC application. The SPARC architectural
specification allows for the number of register windows to be any power of two
less than or equal to 32. The most common choice for SPARC implementations
-appears to be 8 register windows. This results in the cwp ranging in value
+appears to be 8 register windows. This results in the ``CWP`` ranging in value
from 0 to 7 on most implementations.
The second complicating factor is the sharing of registers between adjacent
@@ -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
+- 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
+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
@@ -764,27 +783,27 @@ An RTEMS based application is initiated or re-initiated when the SPARC
processor is reset. When the SPARC is reset, the processor performs the
following actions:
-- the enable trap (ET) of the psr is set to 0 to disable traps,
+- the enable trap (ET) of the ``PSR`` is set to 0 to disable traps,
-- the supervisor bit (S) of the psr is set to 1 to enter supervisor mode, and
+- the supervisor bit (S) of the ``PSR`` is set to 1 to enter supervisor mode, and
- the PC is set 0 and the nPC is set to 4.
The processor then begins to execute the code at location 0. It is important
-to note that all fields in the psr are not explicitly set by the above steps
+to note that all fields in the ``PSR`` are not explicitly set by the above steps
and all other registers retain their value from the previous execution mode.
-This is true even of the Trap Base Register (TBR) whose contents reflect the
+This is true even of the Trap Base Register (``TBR``) whose contents reflect the
last trap which occurred before the reset.
Processor Initialization
------------------------
It is the responsibility of the application's initialization code to initialize
-the TBR and install trap handlers for at least the register window overflow and
+the ``TBR`` and install trap handlers for at least the register window overflow and
register window underflow conditions. Traps should be enabled before invoking
any subroutines to allow for register window management. However, interrupts
should be disabled by setting the Processor Interrupt Level (pil) field of the
-psr to 15. RTEMS installs it's own Trap Table as part of initialization which
+``PSR`` to 15. RTEMS installs it's own Trap Table as part of initialization which
is initialized with the contents of the Trap Table in place when the
``rtems_initialize_executive`` directive was invoked. Upon completion of
executive initialization, interrupts are enabled.
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/coding-conventions.rst b/eng/coding-conventions.rst
index 575dd44..b56d3c2 100644
--- a/eng/coding-conventions.rst
+++ b/eng/coding-conventions.rst
@@ -206,7 +206,7 @@ Portability
Maintainability
---------------
-* Minimize modifications to `third-party code <https://devel.rtems.org/wiki/Developer/Coding/ThirdPartyCode>`_..
+* Minimize modifications to `third-party code <https://devel.rtems.org/wiki/Developer/Coding/ThirdPartyCode>`_.
* Keep it simple! Simple code is easier to debug and easier to read than clever code.
* Share code with other architectures, CPUs, and BSPs where possible.
* Do not duplicate standard OS or C Library routines.
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/imx.rst b/user/bsps/arm/imx.rst
index ee98f0b..e2fd7f2 100644
--- a/user/bsps/arm/imx.rst
+++ b/user/bsps/arm/imx.rst
@@ -174,6 +174,23 @@ config like that:
SYSINIT_DRIVER_REFERENCE(ksz8091rnb, miibus);
#include <machine/rtems-bsd-config.h>
+On chips with two Ethernet controllers, the MDIO lines are shared between the
+two controllers for a number of chips variants. This is currently supported with
+some restrictions on the initialization order. For this configuration to work,
+you have to make sure that the pins are assigned to the Ethernet controller that
+is initialized first. The initialization order in `libbsd` depends on the order
+of the Ethernet controllers in the device tree. So if (for example) `fec2` is
+defined in the device tree sources before `fec1`, make sure that the MDIO lines
+are routed to `fec2` and that the Ethernet PHYs are a sub-node of `fec2` in the
+device tree.
+
+Note that the clock for the second Ethernet controller is not necessarily
+enabled in the `CCM`. On the i.MX6UL/ULL, the clock will be enabled by the
+startup code if the node that is compatible with `fsl,imx6ul-anatop` can be
+found in the device tree. If you have trouble with the second Ethernet
+controller make sure that the `ENET2_125M_EN` bit in the `CCM_ANALOG_PLL_ENET`
+register is set as expected.
+
MMC/SDCard Driver
-----------------
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/arm/stm32h7.rst b/user/bsps/arm/stm32h7.rst
index b508595..ec7440f 100644
--- a/user/bsps/arm/stm32h7.rst
+++ b/user/bsps/arm/stm32h7.rst
@@ -2,16 +2,36 @@
.. Copyright (C) 2020 embedded brains GmbH
+.. Copyright (C) 2022 Karel Gardas <karel@functional.vision>
+
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:
+The BSP is known to run on these boards on specified core with using specified BSP variant.
+
+.. table::
+
+ +----------------------------------------------------------------------------------+-----------+------------------------+
+ | Board name | Core name | BSP variant name |
+ +==================================================================================+===========+========================+
+ |`STM32H743I-EVAL 2 <https://www.st.com/en/evaluation-tools/stm32h743i-eval.html>`_| M7 | arm/stm32h7 |
+ +----------------------------------------------------------------------------------+-----------+------------------------+
+ |`STM32H743ZI-Nucleo <https://www.st.com/en/evaluation-tools/nucleo-h743zi.html>`_ | M7 | arm/nucleo-h743zi |
+ +----------------------------------------------------------------------------------+-----------+------------------------+
+ |`STM32H7B3I-DK <https://www.st.com/en/evaluation-tools/stm32h7b3i-dk.html>`_ | M7 | arm/stm32h7b3i-dk |
+ +----------------------------------------------------------------------------------+-----------+------------------------+
+ |`STM32H757I-EVAL <https://www.st.com/en/evaluation-tools/stm32h757i-eval.html>`_ | M7 | arm/stm32h757i-eval |
+ | +-----------+------------------------+
+ | | M4 | arm/stm32h757i-eval-m4 |
+ +----------------------------------------------------------------------------------+-----------+------------------------+
+ |`STM32H747I-DISCO <https://www.st.com/en/evaluation-tools/stm32h747i-disco.html>`_| M7 | arm/stm32h747i-disco |
+ | +-----------+------------------------+
+ | | M4 | arm/stm32h747i-disco-m4|
+ +----------------------------------------------------------------------------------+-----------+------------------------+
-* `STM32H743I-EVAL 2 <https://www.st.com/en/evaluation-tools/stm32h743i-eval.html>`_
-* `STM32H743ZI-Nucleo <https://www.st.com/en/evaluation-tools/nucleo-h743zi.html>`_
Clock Driver
------------
@@ -23,20 +43,28 @@ boards, so it is recommended to check the default values of the BSP.
Console Driver
--------------
-The console driver supports the on-chip UART and USART modules.
-Different board variations use different GPIO pins and blocks for the default
-communication UART and it is recommended to check whether the default
-configuration provided is valid in the BSP.
+The console driver supports the on-chip UART and USART modules. Even
+the MCU supports about 10 U(S)ARTs, only those supported by the chosen
+board are enabled by default configuration. The board needs to support
+some kind of connector-based connection to the U(S)ART in order for the
+feature to be considered supported here.
+..
+.. Leaving previous notes here as a comment. They may still be useful
+.. and incorporated into the later version of the document.
+..
+.. Different board variations use different GPIO pins and blocks for the default
+.. communication UART and it is recommended to check whether the default
+.. configuration provided is valid in the BSP.
-To specify that the BSP should be built for the STM32H743ZI-Nucleo board,
-users can supply ``STM32H743ZI_NUCLEO = True`` to ``config.ini`` when
-building the BSP.
+.. To specify that the BSP should be built for the STM32H743ZI-Nucleo board,
+.. users can supply ``STM32H743ZI_NUCLEO = True`` to ``config.ini`` when
+.. building the BSP.
-Alternatively, users can supply the configuration structs defined in ``hal.h``
-in the application for other boards. For the console driver, the
-``stm32h7_usartX_config`` structs are used to configure the GPIO pins and other
-parameters. The default implementations can be found in
-``bsps/arm/stm32ht/console`` in the RTEMS sources.
+.. Alternatively, users can supply the configuration structs defined in ``hal.h``
+.. in the application for other boards. For the console driver, the
+.. ``stm32h7_usartX_config`` structs are used to configure the GPIO pins and other
+.. parameters. The default implementations can be found in
+.. ``bsps/arm/stm32ht/console`` in the RTEMS sources.
Network Interface Driver
------------------------
@@ -70,6 +98,490 @@ Known limitations:
for UHS cards are not available. All cards fall back to High Speed transfers.
* The driver uses the IDMA only. MDMA is currently not implemented. For SDMMC1
that means that the memory buffers can only come from AXI SRAM, QSPI memory,
- Flash or the FMC (SDRAM, ...). The internal SRAM1, SRAM2, SRAM3 and SRAM4 is
+ Flash or the FMC (SDRAM, ...). The internal SRAM1, SRAM2, SRAM3 and SRAM4 are
not supported. SDMMC2 should not have that limitation. See ST AN5200 "Getting
started with STM32H7 Series SDMMC host controller" for more details.
+
+
+How to run RTEMS on the board
+-----------------------------
+Following few paragraphs save a purpose of simple HOWTO or a quick
+starting guide for the users not versed in STM32 toolchain and their
+boards workflow.
+
+Board hardware setup
+^^^^^^^^^^^^^^^^^^^^
+Connect board with the host computer using micro-USB cable connected
+to micro-USB connector on the board marked with 'ST-LINK V3E' in case of evaluation
+and discovery boards or with 'USB PWR' in case of Nucleo board.
+
+STM32CubeIDE installation
+^^^^^^^^^^^^^^^^^^^^^^^^^
+Download and install STM32CubeIDE from
+https://www.st.com/en/development-tools/stm32cubeide.html. Install the
+software into the user directory. On Linux install with 'sudo' command
+to install as a root since as part of the installation USB permissions
+rules for ST-Link GDB server are also installed. The reason for
+installing into the user directory is that the IDE is based on
+Eclipse, which provides
+its own update method and this will not work well in case of read-only
+access to the installation directory. In case of any troubles consult
+installation manual provided by ST here https://www.st.com/resource/en/user_manual/um2563-stm32cubeide-installation-guide-stmicroelectronics.pdf.
+Although we will not used full fledged IDE here, the package provides ST-Link GDB Server which will be used for uploading RTEMS binaries to the board
+memory.
+
+STM32CubeProgrammer installation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Download and install STM32CubeProgrammer from
+https://www.st.com/en/development-tools/stm32cubeprog.html. We will
+use this software for board setup required for RTEMS and later when
+something goes wrong to delete content of the MCU flash memory. The
+software is also internally used by the ST-Link GDB Server from
+STM32CubeIDE so it is crucial to have it installed.
+
+Board ST-Link firmware upgrade
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Download ST-Link board firmware upgrade package from
+https://www.st.com/en/development-tools/stsw-link007.html. The
+software is distributed in a form of Java jar file for Linux and Mac
+OSX and in a form of Windows binary for MS Windows. Unpack it
+somewhere and run it with
+
+.. code-block:: shell
+
+ $ unzip en.stsw-link007-v3-9-3_v3.9.3.zip
+ $ cd stsw-link007/AllPlatforms
+ $ java -jar STLinkUpgrade.jar
+
+Click on *Open in update mode* button and then if *Version* and *Update
+to Firmware* version information are different in shown version number/code, click on *Upgrade*
+button and wait till upgrade finishes.
+
+.. note: On Linux you will need to have libusb library installed in
+ order to make upgrade process working. On Ubuntu 20.04 LTS you can do
+ that with following command.
+
+.. code-block:: shell
+
+ $ sudo apt install libusb-1.0-0
+
+
+Dual core board setup for RTEMS
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Current RTEMS BSP supports
+running MCU in a single-core mode only on either M7 core or M4
+core. That means that to not leave other core interfering with the
+system we either need to upload short infinite loop code to it or we
+may switch off the core completely. The second option is what is
+described here. The board by default switches on and starts both
+cores. Based on chosen BSP variant you may like to switch off other
+core with using STMCubeProgrammer tool.
+Go to the directory where you have installed STMCubeProgrammer
+software and run it with
+
+.. code-block:: shell
+
+ $ cd bin
+ $ ./STM32CubeProgrammer
+
+
+.. important:: It is absolutely necessary you will do that from inside the bin
+ directory where STM32CubeProgrammer binary resides. If you don't, then
+ programmer UI will crash on attempt to connect to the board. Probable
+ reason is a bug in the programmer which is not able to correctly locate
+ its C dynamic library responsible for connecting to the ST-Link board
+ interface. Version 2.9.0 of the programmer is described here. Other
+ versions may behave a bit differently.
+
+When you start the programmer application, the UI window of the programmer will
+appear.
+Click on green *Connect* button in the right upper corner of
+the UI. This will connect programmer to the board.
+Then click on *OB*
+icon in the left upper corner. Actually this is hidden menu item which you
+can un-hide by clicking on menu icon (three horizontal stripes) in the
+upper left corner.
+When you click on *OB* or *Option bytes* in un-hidden state, then
+click on *User Configuration* in the options list and when the user
+configuration list opens
+unselect preselected *BCM4* item inside it to switch off M4 core or
+unselect preselected *BCM7* item to switch off M7 core from
+starting up. The action needs to be saved by clicking on *Apply* button
+below the option table.
+
+.. warning:: Be careful! Wrong setup in STM32H7 configuration may result in
+ *bricked* board.
+
+Do not forget to disconnect the programmer application from the board by clicking on green *Disconnect* button
+in the upper right corner and then close the programmer UI.
+
+.. important:: If you keep programmer connected then you will not be able
+ to connect ST-Link GDB server to the board and upload RTEMS binary to
+ it.
+
+
+STM32CubeIDE ST-Link GDB Server setup
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+In order to use STM provided ST-Link GDB server externally, that is
+not from inside the IDE, we need to configure it. Please go to the
+directory where you have installed STM32CubeIDE software. Look for
+file containing *ST-LINK* string inside its name. Following shell
+command sequence shows example about how to find it.
+
+.. code-block:: shell
+
+ $ cd $HOME/sfw/stm32cubeide_1.8.0
+ $ find . -name 'ST-LINK*'
+ ./plugins/com.st.stm32cube.ide.mcu.externaltools.stlink-gdb-server.linux64_2.0.200.202202231230/tools/bin/ST-LINK_gdbserver.sh
+ ./plugins/com.st.stm32cube.ide.mcu.externaltools.stlink-gdb-server.linux64_2.0.200.202202231230/tools/bin/ST-LINK_gdbserver
+ ./plugins/com.st.stm32cube.ide.mcu.externaltools.stlink-gdb-server.linux64_2.0.100.202109301221/tools/bin/ST-LINK_gdbserver.sh
+ ./plugins/com.st.stm32cube.ide.mcu.externaltools.stlink-gdb-server.linux64_2.0.100.202109301221/tools/bin/ST-LINK_gdbserver
+
+Notice that in this particular installation case we already have two
+versions of GDB server installed. This is due to fact that version
+1.8.0 of the IDE was later upgraded to 1.9.0 version. Anyway, we will choose
+to use the latest one, or if there is only one, then the only one
+installed. Please go to its *bin* directory. E.g.
+
+.. code-block:: shell
+
+ $ cd plugins/com.st.stm32cube.ide.mcu.externaltools.stlink-gdb-server.linux64_2.0.200.202202231230/tools/bin
+
+Now, you will need to edit provided *config.txt* file inside the
+directory. Use your favorite editor. Open the file and scrolls
+down to its end. You will see following comment:
+
+.. code-block:: none
+
+ ###############################################################
+ # -cp <path> : Path to STM32CubeProgrammer
+ # Modify to correct path
+ # for STM32_Programmer_CLI executable
+ ###############################################################
+ -cp
+
+and here you will need to place path where your STM32CubeProgrammer is
+installed directly behind the *-cp* parameter. E.g.
+
+.. code-block:: none
+
+ ###############################################################
+ # -cp <path> : Path to STM32CubeProgrammer
+ # Modify to correct path
+ # for STM32_Programmer_CLI executable
+ ###############################################################
+ -cp /home/karel/sfw/stm32cubeide_1.8.0/plugins/com.st.stm32cube.ide.mcu.externaltools.cubeprogrammer.linux64_2.0.200.202202231230/tools/bin
+
+Once you are done with it, you can save the file and close the
+editor. Let's verify that GDB server is configured and running well by starting
+it inside the shell. Please go inside the directory where
+ST-LINK_gdbserver.sh is located and run it by:
+
+.. code-block:: shell
+
+ $ ./ST-LINK_gdbserver.sh
+
+If everything is all right and if you have board still connected to
+the host computer then you should see output like following:
+
+.. code-block:: shell
+
+ $ ./ST-LINK_gdbserver.sh
+
+ STMicroelectronics ST-LINK GDB server. Version 6.1.0
+ Copyright (c) 2022, STMicroelectronics. All rights reserved.
+
+ Starting server with the following options:
+ Persistent Mode : Enabled
+ LogFile Name : debug.log
+ Logging Level : 31
+ Listen Port Number : 61234
+ Status Refresh Delay : 15s
+ Verbose Mode : Disabled
+ SWD Debug : Enabled
+
+ COM frequency = 24000 kHz
+ Target connection mode: Default
+ Reading ROM table for AP 0 @0xe00fefd0
+ Hardware watchpoint supported by the target
+ ST-LINK Firmware version : V3J9M3
+ Device ID: 0x450
+ PC: 0x8028fa4
+ ST-LINK device status: HALT_MODE
+ ST-LINK detects target voltage = 3.28 V
+ ST-LINK device status: HALT_MODE
+ ST-LINK device initialization OK
+ Stm32Device, pollAndNotify running...
+ SwvSrv state change: 0 -> 1
+ Waiting for connection on port 61235...
+ Waiting for debugger connection...
+ Waiting for connection on port 61234...
+
+In output above you can see ST-Link GDB server waiting for debugger
+connection. If this is the case in your case, then you can finish GDB server by hitting
+*Ctrl-C* key combination.
+
+RTEMS BSP samples build and run
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+We will use STM32H747I-DISCO board as an example hereafter. If you use
+different board please adjust configuration steps in BSP configuration
+accordingly. You should use BSP variant name specified for your
+particular board in the table above.
+
+Generate default configuration for the board:
+
+.. code-block:: shell
+
+ $ ./waf bsp_defaults --rtems-bsps=arm/stm32h747i-disco > stm32h747i-disco.ini
+ Regenerate build specification cache (needs a couple of seconds)...
+
+To run basic hello world or ticker samples you do not need to modify
+default BSP configuration here as the compilation of basic RTEMS demo samples is
+enabled by default. Let's continue with configuration of
+the RTEMS source by running following command. Please change the RTEMS
+tools installation prefix to suite your installation.
+
+.. code-block:: shell
+
+ $ ./waf configure --rtems-bsps=arm/stm32h747i-disco --rtems-config=./stm32h747i-disco.ini --rtems-tools=$HOME/workspace/rtems-tools
+ Setting top to : /home/rtems/workspace/rtems
+ Setting out to : /home/rtems/workspace/rtems/build
+ Configure board support package (BSP) : arm/stm32h747i-disco
+ Checking for program 'arm-rtems6-gcc' : /home/rtems/workspace/rtems-tools/bin/arm-rtems6-gcc
+ Checking for program 'arm-rtems6-g++' : /home/rtems/workspace/rtems-tools/bin/arm-rtems6-g++
+ Checking for program 'arm-rtems6-ar' : /home/rtems/workspace/rtems-tools/bin/arm-rtems6-ar
+ Checking for program 'arm-rtems6-ld' : /home/rtems/workspace/rtems-tools/bin/arm-rtems6-ld
+ Checking for program 'ar' : /home/rtems/workspace/rtems-tools/bin/arm-rtems6-ar
+ Checking for program 'g++, c++' : /home/rtems/workspace/rtems-tools/bin/arm-rtems6-g++
+ Checking for program 'ar' : /home/rtems/workspace/rtems-tools/bin/arm-rtems6-ar
+ Checking for program 'gas, gcc' : /home/rtems/workspace/rtems-tools/bin/arm-rtems6-gcc
+ Checking for program 'ar' : /home/rtems/workspace/rtems-tools/bin/arm-rtems6-ar
+ Checking for program 'gcc, cc' : /home/rtems/workspace/rtems-tools/bin/arm-rtems6-gcc
+ Checking for program 'ar' : /home/rtems/workspace/rtems-tools/bin/arm-rtems6-ar
+ Checking for asm flags '-MMD' : yes
+ Checking for c flags '-MMD' : yes
+ Checking for cxx flags '-MMD' : yes
+ 'configure' finished successfully (0.454s)
+
+Build the BSP including samples using *build* command:
+
+.. code-block:: shell
+
+ $ ./waf build
+
+the command outputs a lot of information about files being compiled
+and ends with output like:
+
+.. code-block:: shell
+
+ Waf: Leaving directory `/home/rtems/workspace/rtems/build/arm/stm32h747i-disco'
+ 'build_arm/stm32h747i-disco' finished successfully (12.086s)
+
+As your RTEMS BSP including samples is compiled, we will proceed with
+running the hello world sample on the board now.
+Open 3 shell windows for the test on the host computer. Also make sure
+board is connected to the computer and is running. It does not matter
+if manufacturer's demo is running there or if you navigated to some
+demo part and left it there. ST-Link GDB server always takes over the
+board when connected to it.
+
+Start GDB server in the first window by switching to GDB server
+directory and running the shell script. This is from testing machine
+installation, the path to GDB server will probably look different in your
+installation case.
+
+.. code-block:: shell
+
+ $ cd sfw/stm32cubeide_1.8.0/plugins/com.st.stm32cube.ide.mcu.externaltools.stlink-gdb-server.linux64_2.0.200.202202231230/tools/bin
+ $ ./ST-LINK_gdbserver.sh
+
+ STMicroelectronics ST-LINK GDB server. Version 6.1.0
+ Copyright (c) 2022, STMicroelectronics. All rights reserved.
+
+ Starting server with the following options:
+ Persistent Mode : Enabled
+ LogFile Name : debug.log
+ Logging Level : 31
+ Listen Port Number : 61234
+ Status Refresh Delay : 15s
+ Verbose Mode : Disabled
+ SWD Debug : Enabled
+
+ COM frequency = 24000 kHz
+ Target connection mode: Default
+ Reading ROM table for AP 0 @0xe00fefd0
+ Hardware watchpoint supported by the target
+ ST-LINK Firmware version : V3J9M3
+ Device ID: 0x450
+ PC: 0x8028fa4
+ ST-LINK device status: HALT_MODE
+ ST-LINK detects target voltage = 3.28 V
+ ST-LINK device status: HALT_MODE
+ ST-LINK device initialization OK
+ Stm32Device, pollAndNotify running...
+ SwvSrv state change: 0 -> 1
+ Waiting for connection on port 61235...
+ Waiting for debugger connection...
+ Waiting for connection on port 61234...
+
+In second shell window you will need to run your terminal program and
+connect to the board virtual serial port. Following steps describes
+how to do that on the Ubuntu 20.04. The recommended way here is to use minicom. Let's install it
+first by:
+
+.. code-block:: shell
+
+ $ sudo apt install minicom
+
+And run it with root privileges to be able to reach USB serial port
+provided by board:
+
+.. code-block:: shell
+
+ $ sudo minicom -s
+
+The minicom is invoked with configuration menu open. Go into the
+*Serial port setup* and hit *a* key to select *Serial Device*
+setup. Change */dev/modem* from there into */dev/ttyACM0* and hit
+*Enter* key. Hit *f* key to change hardware flow control from *Yes* to
+*No*. When you are done with it, you can hit *Enter* key to finish
+this part of configuration and then scrolls in menu to *Exit* and hit
+*Enter* key on it. The minicom will switch to terminal mode with just
+provided configuration.
+
+In the third shell window navigate into the BSP build directory and start
+RTEMS GDB with the hello.exe sample.
+
+.. code-block:: shell
+
+ $ arm-rtems6-gdb build/arm/stm32h747i-disco/testsuites/samples/hello.exe
+ GNU gdb (GDB) 10.1.90.20210409-git
+ Copyright (C) 2021 Free Software Foundation, Inc.
+ License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
+ This is free software: you are free to change and redistribute it.
+ There is NO WARRANTY, to the extent permitted by law.
+ Type "show copying" and "show warranty" for details.
+ This GDB was configured as "--host=x86_64-linux-gnu --target=arm-rtems6".
+ Type "show configuration" for configuration details.
+ For bug reporting instructions, please see:
+ <https://www.gnu.org/software/gdb/bugs/>.
+ Find the GDB manual and other documentation resources online at:
+ <http://www.gnu.org/software/gdb/documentation/>.
+
+ For help, type "help".
+ Type "apropos word" to search for commands related to "word"...
+ Reading symbols from build/arm/stm32h747i-disco/testsuites/samples/hello.exe...
+ (gdb)
+
+Now, you need to connect GDB with the ST's GDB server by:
+
+.. code-block:: shell
+
+ (gdb) target extended-remote :61234
+ Remote debugging using :61234
+ 0x08028fa4 in ?? ()
+ (gdb)
+
+and finally you will need to load hello.exe binary into the board
+memory by:
+
+.. code-block:: shell
+
+ (gdb) load
+ Loading section .start, size 0x458 lma 0x24000000
+ Loading section .text, size 0xfca8 lma 0x24000480
+ Loading section .init, size 0xc lma 0x24010128
+ Loading section .fini, size 0xfecc lma 0x24010134
+ Loading section .rodata, size 0x1aab lma 0x24020000
+ Loading section .ARM.exidx, size 0x8 lma 0x24021aac
+ Loading section .eh_frame, size 0x4 lma 0x24021ab4
+ Loading section .init_array, size 0x4 lma 0x24021ab8
+ Loading section .fini_array, size 0x4 lma 0x24021abc
+ Loading section .rtemsroset, size 0x540 lma 0x24021ac0
+ Loading section .data, size 0x6a4 lma 0x24022000
+ Start address 0x24000400, load size 140923
+ Transfer rate: 684 KB/sec, 2562 bytes/write.
+ (gdb)
+
+If everything went fine, then you can run the RTEMS binary by using
+*cont* GDB command.
+
+.. note:: Memory address values in the load output in the gdb shows
+ that we have loaded our application into the AXI
+ SRAM. Memory addresses will be different when loading into
+ different part of MCU memory.
+
+.. code-block:: shell
+
+ (gdb) cont
+ Continuing.
+
+Note that this command should never finish. To see the actual output
+from RTEMS switch to
+the second shell window with minicom (or other terminal emulation
+program) running and you should see hello output
+there:
+
+.. code-block:: none
+
+ *** BEGIN OF TEST HELLO WORLD ***
+ *** TEST VERSION: 6.0.0.50ce036cfbd9807a54af47eb60eadb6a33a9e82d
+ *** TEST STATE: EXPECTED_PASS
+ *** TEST BUILD:
+ *** TEST TOOLS: 10.3.1 20220224 (RTEMS 6, RSB 49e3dac17765fa82ce2f754da839638ee352f95c, Newlib 64b2081)
+ Hello World
+
+ *** END OF TEST HELLO WORLD ***
+
+
+ [ RTEMS shutdown ]
+ RTEMS version: 6.0.0.50ce036cfbd9807a54af47eb60eadb6a33a9e82d
+ RTEMS tools: 10.3.1 20220224 (RTEMS 6, RSB 49e3dac17765fa82ce2f754da839638ee352f95c, Newlib 64b2081)
+ executing thread ID: 0x08a010001
+
+Since default RTEMS BSP configuration resets the board after run
+immediately you can also see output from the immediately started ST
+demo:
+
+.. code-block:: none
+
+ STM32H747I-DISCO_MB1248: Out Of the Box Demonstration V1.0.1 (Build Aug 22 2019 at 11:56:22)
+ STM32H747I-DISCO_MB1248: ST Menu Launcher V1.1.0
+ CPU running at 400MHz, Peripherals at 100MHz/100Mz
+
+which is not a problem here at all. Later we can reconfigure BSP to
+not reset board to prevent demo output here.
+
+How to load binary file into the QSPI NOR
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Connect the board to your host computer using micro-USB
+cable. Start STM32CubeProgrammer and connect it to the board by
+clicking on *Connect* button which is located in the right upper
+corner of the programmer application UI. For accessing QSPI connected
+memory you will need to configure programmer's external loader which
+needs to match your target board. Click on *EL* icon (or *External
+loaders*) in the left sidebar menu. Either go thorough the list of
+external loaders or just search for your board by typing board
+name (or part of the name) into the search bar located on top of the table view. When
+you find your board, select it by selecting rectangle in the *Select*
+table column. That's what is needed to make programmer ready to
+program your board memory.
+For uploading file to the board, you need to continue with clicking on
+*Erase & programming* menu item in the left sidebar menu. It's second item
+from the top. Now, let's select
+your file to upload by clicking on *Browse* button and selecting the
+file name from your host computer filesystem. The most important thing here is
+to specify start address of flashing process. You need to do that by
+typing start address into the *Start address* field.
+
+.. note:: Usually external memory connected to QSPI has 0x90000000 starting
+ address.
+
+When all is set you can click on *Start Programming* button.
+
+.. important:: Cube programmer is very picky about files it shows in the file list. The only recognized suffixes are: elf, bin, hex and
+ similar. Also do not try to fool programmer by renaming let's say text
+ file to bin file. It'll detect file type as ascii text and will not
+ show it in the list of files to flash. So bin file type is really for
+ media types like avi, jpeg, mpeg or for binary dumps from elf
+ files. If you need to save text file, convert it to hex file first.
diff --git a/user/bsps/arm/xilinx-zynq.rst b/user/bsps/arm/xilinx-zynq.rst
index 29f9cb0..0ac4487 100644
--- a/user/bsps/arm/xilinx-zynq.rst
+++ b/user/bsps/arm/xilinx-zynq.rst
@@ -1,6 +1,6 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
-.. Copyright (C) 2020 Chris Johns (chrisj@rtems.org)
+.. Copyright (C) 2015, 2020 Chris Johns (chrisj@rtems.org)
xilinx-zynq
===========
@@ -49,6 +49,22 @@ tools or a bootloader will be overwritten.
The settings for the console driver can be changed by the user
application through the termios API afterwards.
+Network
+-------
+
+The Cadence network interface driver of LibBSD works on the Xilinx Zynq
+platform. The hardware checksum support works on real hardware but does not
+seem to be supported on Qemu therefore the default state is to disable
+``IFCAP_TXCSUM`` and ``IFCAP_RXCSUM`` and this can be enabled from the shell
+with:
+
+.. code-block:: none
+
+ ifconfig cgem0 rxcsum txcsum
+
+or with an ``ioctl()`` call to the network interface driver with ``SIOCSIFCAP``
+and the mask ``IFCAP_TXCSUM`` and ``IFCAP_RXCSUM`` set.
+
Debugging with xilinx_zynq_a9_qemu
----------------------------------
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.