summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--c-user/cache/directives.rst665
-rw-r--r--c-user/cache/index.rst15
-rw-r--r--c-user/cache/introduction.rst101
-rw-r--r--c-user/clock/directives.rst19
-rw-r--r--c-user/fatal-error/directives.rst10
-rw-r--r--c-user/glossary.rst47
-rw-r--r--c-user/index.rst2
-rw-r--r--c-user/kernel-character-io/directives.rst372
-rw-r--r--c-user/kernel-character-io/index.rst15
-rw-r--r--c-user/kernel-character-io/introduction.rst69
-rw-r--r--c-user/message/directives.rst23
-rw-r--r--c-user/rate-monotonic/directives.rst4
-rw-r--r--c-user/rate-monotonic/introduction.rst2
-rw-r--r--c-user/scheduling-concepts/background.rst5
-rw-r--r--c-user/scheduling-concepts/smp-schedulers.rst9
-rw-r--r--c-user/task/background.rst14
-rw-r--r--c-user/user-extensions/directives.rst10
-rw-r--r--eng/build-system.rst4
-rw-r--r--eng/coding-conventions.rst2
-rw-r--r--eng/req/items.rst157
-rw-r--r--user/bsps/arm/raspberrypi.rst51
21 files changed, 1485 insertions, 111 deletions
diff --git a/c-user/cache/directives.rst b/c-user/cache/directives.rst
new file mode 100644
index 0000000..98349db
--- /dev/null
+++ b/c-user/cache/directives.rst
@@ -0,0 +1,665 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2016 Pavel Pisa
+.. Copyright (C) 2014, 2021 embedded brains GmbH (http://www.embedded-brains.de)
+.. Copyright (C) 2000, 2008 On-Line Applications Research Corporation (OAR)
+
+.. This file is part of the RTEMS quality process and was automatically
+.. generated. If you find something that needs to be fixed or
+.. worded better please post a report or patch to an RTEMS mailing list
+.. or raise a bug report:
+..
+.. https://www.rtems.org/bugs.html
+..
+.. For information on updating and regenerating please refer to the How-To
+.. section in the Software Requirements Engineering chapter of the
+.. RTEMS Software Engineering manual. The manual is provided as a part of
+.. a release. For development sources please refer to the online
+.. documentation at:
+..
+.. https://docs.rtems.org
+
+.. _CacheManagerDirectives:
+
+Directives
+==========
+
+This section details the directives of the Cache Manager. A subsection is
+dedicated to each of this manager's directives and lists the calling sequence,
+parameters, description, return values, and notes of the directive.
+
+.. Generated from spec:/rtems/cache/if/flush-multiple-data-lines
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: rtems_cache_flush_multiple_data_lines()
+
+.. _InterfaceRtemsCacheFlushMultipleDataLines:
+
+rtems_cache_flush_multiple_data_lines()
+---------------------------------------
+
+Flushes the data cache lines covering the memory area.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ void rtems_cache_flush_multiple_data_lines( const void *begin, size_t size );
+
+.. rubric:: PARAMETERS:
+
+``begin``
+ This parameter is the begin address of the memory area to flush.
+
+``size``
+ This parameter is the size in bytes of the memory area to flush.
+
+.. rubric:: DESCRIPTION:
+
+Dirty data cache lines covering the area are transfered to memory. Depending
+on the cache implementation this may mark the lines as invalid.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/cache/if/invalidate-multiple-data-lines
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: rtems_cache_invalidate_multiple_data_lines()
+
+.. _InterfaceRtemsCacheInvalidateMultipleDataLines:
+
+rtems_cache_invalidate_multiple_data_lines()
+--------------------------------------------
+
+Invalidates the data cache lines covering the memory area.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ void rtems_cache_invalidate_multiple_data_lines(
+ const void *begin,
+ size_t size
+ );
+
+.. rubric:: PARAMETERS:
+
+``begin``
+ This parameter is the begin address of the memory area to invalidate.
+
+``size``
+ This parameter is the size in bytes of the memory area to invalidate.
+
+.. rubric:: DESCRIPTION:
+
+The cache lines covering the area are marked as invalid. A later read access
+in the area will load the data from memory.
+
+.. rubric:: NOTES:
+
+In case the area is not aligned on cache line boundaries, then this operation
+may destroy unrelated data.
+
+On some systems, the cache lines may be flushed before they are invalidated.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/cache/if/invalidate-multiple-instruction-lines
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: rtems_cache_invalidate_multiple_instruction_lines()
+
+.. _InterfaceRtemsCacheInvalidateMultipleInstructionLines:
+
+rtems_cache_invalidate_multiple_instruction_lines()
+---------------------------------------------------
+
+Invalidates the instruction cache lines covering the memory area.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ void rtems_cache_invalidate_multiple_instruction_lines(
+ const void *begin,
+ size_t size
+ );
+
+.. rubric:: PARAMETERS:
+
+``begin``
+ This parameter is the begin address of the memory area to invalidate.
+
+``size``
+ This parameter is the size in bytes of the memory area to invalidate.
+
+.. rubric:: DESCRIPTION:
+
+The cache lines covering the area are marked as invalid. A later instruction
+fetch from the area will result in a load from memory.
+
+.. rubric:: NOTES:
+
+In SMP configurations, on processors without instruction cache snooping, this
+operation will invalidate the instruction cache lines on all processors.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/cache/if/instruction-sync-after-code-change
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: rtems_cache_instruction_sync_after_code_change()
+
+.. _InterfaceRtemsCacheInstructionSyncAfterCodeChange:
+
+rtems_cache_instruction_sync_after_code_change()
+------------------------------------------------
+
+Ensures necessary synchronization required after code changes.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ void rtems_cache_instruction_sync_after_code_change(
+ const void *begin,
+ size_t size
+ );
+
+.. rubric:: PARAMETERS:
+
+``begin``
+ This parameter is the begin address of the code area to synchronize.
+
+``size``
+ This parameter is the size in bytes of the code area to synchronize.
+
+.. rubric:: NOTES:
+
+When code is loaded or modified, then most systems require synchronization
+instructions to update the instruction caches so that the loaded or modified
+code is fetched. For example, systems with separate data and instruction
+caches or systems without instruction cache snooping. The directives should be
+used by run time loader for example.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/cache/if/get-maximal-line-size
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: rtems_cache_get_maximal_line_size()
+
+.. _InterfaceRtemsCacheGetMaximalLineSize:
+
+rtems_cache_get_maximal_line_size()
+-----------------------------------
+
+Gets the maximal cache line size in bytes of all caches (data, instruction, or
+unified).
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ size_t rtems_cache_get_maximal_line_size( void );
+
+.. rubric:: RETURN VALUES:
+
+``0``
+ There is no cache present.
+
+Returns the maximal cache line size in bytes of all caches (data, instruction,
+or unified).
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/cache/if/get-data-line-size
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: rtems_cache_get_data_line_size()
+
+.. _InterfaceRtemsCacheGetDataLineSize:
+
+rtems_cache_get_data_line_size()
+--------------------------------
+
+Gets the data cache line size in bytes.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ size_t rtems_cache_get_data_line_size( void );
+
+.. rubric:: RETURN VALUES:
+
+``0``
+ There is no data cache present.
+
+Returns the data cache line size in bytes. For multi-level caches this is the
+maximum of the cache line sizes of all levels.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/cache/if/get-instruction-line-size
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: rtems_cache_get_instruction_line_size()
+
+.. _InterfaceRtemsCacheGetInstructionLineSize:
+
+rtems_cache_get_instruction_line_size()
+---------------------------------------
+
+Gets the instruction cache line size in bytes.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ size_t rtems_cache_get_instruction_line_size( void );
+
+.. rubric:: RETURN VALUES:
+
+``0``
+ There is no instruction cache present.
+
+Returns the instruction cache line size in bytes. For multi-level caches this
+is the maximum of the cache line sizes of all levels.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/cache/if/get-data-size
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: rtems_cache_get_data_cache_size()
+
+.. _InterfaceRtemsCacheGetDataCacheSize:
+
+rtems_cache_get_data_cache_size()
+---------------------------------
+
+Gets the data cache size in bytes for the cache level.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ size_t rtems_cache_get_data_cache_size( uint32_t level );
+
+.. rubric:: PARAMETERS:
+
+``level``
+ This parameter is the requested data cache level. The cache level zero
+ specifies the entire data cache.
+
+.. rubric:: RETURN VALUES:
+
+``0``
+ There is no data cache present at the requested cache level.
+
+Returns the data cache size in bytes of the requested cache level.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/cache/if/get-instruction-size
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: rtems_cache_get_instruction_cache_size()
+
+.. _InterfaceRtemsCacheGetInstructionCacheSize:
+
+rtems_cache_get_instruction_cache_size()
+----------------------------------------
+
+Gets the instruction cache size in bytes for the cache level.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ size_t rtems_cache_get_instruction_cache_size( uint32_t level );
+
+.. rubric:: PARAMETERS:
+
+``level``
+ This parameter is the requested instruction cache level. The cache level
+ zero specifies the entire instruction cache.
+
+.. rubric:: RETURN VALUES:
+
+``0``
+ There is no instruction cache present at the requested cache level.
+
+Returns the instruction cache size in bytes of the requested cache level.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/cache/if/flush-entire-data
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: rtems_cache_flush_entire_data()
+
+.. _InterfaceRtemsCacheFlushEntireData:
+
+rtems_cache_flush_entire_data()
+-------------------------------
+
+Flushes the entire data cache.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ void rtems_cache_flush_entire_data( void );
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/cache/if/invalidate-entire-data
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: rtems_cache_invalidate_entire_data()
+
+.. _InterfaceRtemsCacheInvalidateEntireData:
+
+rtems_cache_invalidate_entire_data()
+------------------------------------
+
+Invalidates the entire data cache.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ void rtems_cache_invalidate_entire_data( void );
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/cache/if/invalidate-entire-instruction
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: rtems_cache_invalidate_entire_instruction()
+
+.. _InterfaceRtemsCacheInvalidateEntireInstruction:
+
+rtems_cache_invalidate_entire_instruction()
+-------------------------------------------
+
+Invalidates the entire instruction cache.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ void rtems_cache_invalidate_entire_instruction( void );
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/cache/if/enable-data
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: rtems_cache_enable_data()
+
+.. _InterfaceRtemsCacheEnableData:
+
+rtems_cache_enable_data()
+-------------------------
+
+Enables the data cache.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ void rtems_cache_enable_data( void );
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/cache/if/disable-data
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: rtems_cache_disable_data()
+
+.. _InterfaceRtemsCacheDisableData:
+
+rtems_cache_disable_data()
+--------------------------
+
+Disables the data cache.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ void rtems_cache_disable_data( void );
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/cache/if/enable-instruction
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: rtems_cache_enable_instruction()
+
+.. _InterfaceRtemsCacheEnableInstruction:
+
+rtems_cache_enable_instruction()
+--------------------------------
+
+Enables the instruction cache.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ void rtems_cache_enable_instruction( void );
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/cache/if/disable-instruction
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: rtems_cache_disable_instruction()
+
+.. _InterfaceRtemsCacheDisableInstruction:
+
+rtems_cache_disable_instruction()
+---------------------------------
+
+Disables the instruction cache.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ void rtems_cache_disable_instruction( void );
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/cache/if/aligned-malloc
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: rtems_cache_aligned_malloc()
+
+.. _InterfaceRtemsCacheAlignedMalloc:
+
+rtems_cache_aligned_malloc()
+----------------------------
+
+Allocates memory from the C Program Heap which begins at a cache line boundary.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ void *rtems_cache_aligned_malloc( size_t size );
+
+.. rubric:: PARAMETERS:
+
+``size``
+ This parameter is the size in bytes of the memory area to allocate.
+
+.. rubric:: RETURN VALUES:
+
+`NULL <https://en.cppreference.com/w/c/types/NULL>`_
+ There is not enough memory available to satisfy the allocation request.
+
+Returns the begin address of the allocated memory. The begin address is on a
+cache line boundary.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive may obtain and release the object allocator mutex. This may
+ cause the calling task to be preempted.
diff --git a/c-user/cache/index.rst b/c-user/cache/index.rst
new file mode 100644
index 0000000..c8f7263
--- /dev/null
+++ b/c-user/cache/index.rst
@@ -0,0 +1,15 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+
+.. index:: cache
+
+.. _RTEMSAPIClassicCache:
+
+Cache Manager
+*************
+
+.. toctree::
+
+ introduction
+ directives
diff --git a/c-user/cache/introduction.rst b/c-user/cache/introduction.rst
new file mode 100644
index 0000000..6cae4b2
--- /dev/null
+++ b/c-user/cache/introduction.rst
@@ -0,0 +1,101 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2016 Pavel Pisa
+.. Copyright (C) 2014, 2021 embedded brains GmbH (http://www.embedded-brains.de)
+.. Copyright (C) 2000, 2008 On-Line Applications Research Corporation (OAR)
+
+.. This file is part of the RTEMS quality process and was automatically
+.. generated. If you find something that needs to be fixed or
+.. worded better please post a report or patch to an RTEMS mailing list
+.. or raise a bug report:
+..
+.. https://www.rtems.org/bugs.html
+..
+.. For information on updating and regenerating please refer to the How-To
+.. section in the Software Requirements Engineering chapter of the
+.. RTEMS Software Engineering manual. The manual is provided as a part of
+.. a release. For development sources please refer to the online
+.. documentation at:
+..
+.. https://docs.rtems.org
+
+.. Generated from spec:/rtems/cache/if/group
+
+.. _CacheManagerIntroduction:
+
+Introduction
+============
+
+.. The following list was generated from:
+.. spec:/rtems/cache/if/flush-multiple-data-lines
+.. spec:/rtems/cache/if/invalidate-multiple-data-lines
+.. spec:/rtems/cache/if/invalidate-multiple-instruction-lines
+.. spec:/rtems/cache/if/instruction-sync-after-code-change
+.. spec:/rtems/cache/if/get-maximal-line-size
+.. spec:/rtems/cache/if/get-data-line-size
+.. spec:/rtems/cache/if/get-instruction-line-size
+.. spec:/rtems/cache/if/get-data-size
+.. spec:/rtems/cache/if/get-instruction-size
+.. spec:/rtems/cache/if/flush-entire-data
+.. spec:/rtems/cache/if/invalidate-entire-data
+.. spec:/rtems/cache/if/invalidate-entire-instruction
+.. spec:/rtems/cache/if/enable-data
+.. spec:/rtems/cache/if/disable-data
+.. spec:/rtems/cache/if/enable-instruction
+.. spec:/rtems/cache/if/disable-instruction
+.. spec:/rtems/cache/if/aligned-malloc
+
+The Cache Manager provides functions to perform maintenance operations for data
+and instruction caches.
+
+The actual actions of the Cache Manager operations depend on the hardware and
+the implementation provided by the CPU architecture port or a board support
+package. Cache implementations tend to be highly hardware dependent. The
+directives provided by the Cache Manager are:
+
+* :ref:`InterfaceRtemsCacheFlushMultipleDataLines` - Flushes the data cache
+ lines covering the memory area.
+
+* :ref:`InterfaceRtemsCacheInvalidateMultipleDataLines` - Invalidates the data
+ cache lines covering the memory area.
+
+* :ref:`InterfaceRtemsCacheInvalidateMultipleInstructionLines` - Invalidates
+ the instruction cache lines covering the memory area.
+
+* :ref:`InterfaceRtemsCacheInstructionSyncAfterCodeChange` - Ensures necessary
+ synchronization required after code changes.
+
+* :ref:`InterfaceRtemsCacheGetMaximalLineSize` - Gets the maximal cache line
+ size in bytes of all caches (data, instruction, or unified).
+
+* :ref:`InterfaceRtemsCacheGetDataLineSize` - Gets the data cache line size in
+ bytes.
+
+* :ref:`InterfaceRtemsCacheGetInstructionLineSize` - Gets the instruction cache
+ line size in bytes.
+
+* :ref:`InterfaceRtemsCacheGetDataCacheSize` - Gets the data cache size in
+ bytes for the cache level.
+
+* :ref:`InterfaceRtemsCacheGetInstructionCacheSize` - Gets the instruction
+ cache size in bytes for the cache level.
+
+* :ref:`InterfaceRtemsCacheFlushEntireData` - Flushes the entire data cache.
+
+* :ref:`InterfaceRtemsCacheInvalidateEntireData` - Invalidates the entire data
+ cache.
+
+* :ref:`InterfaceRtemsCacheInvalidateEntireInstruction` - Invalidates the
+ entire instruction cache.
+
+* :ref:`InterfaceRtemsCacheEnableData` - Enables the data cache.
+
+* :ref:`InterfaceRtemsCacheDisableData` - Disables the data cache.
+
+* :ref:`InterfaceRtemsCacheEnableInstruction` - Enables the instruction cache.
+
+* :ref:`InterfaceRtemsCacheDisableInstruction` - Disables the instruction
+ cache.
+
+* :ref:`InterfaceRtemsCacheAlignedMalloc` - Allocates memory from the C Program
+ Heap which begins at a cache line boundary.
diff --git a/c-user/clock/directives.rst b/c-user/clock/directives.rst
index e0f858a..1a65abf 100644
--- a/c-user/clock/directives.rst
+++ b/c-user/clock/directives.rst
@@ -70,10 +70,15 @@ Sets the :term:`CLOCK_REALTIME` to the time of day.
The date, time, and ticks specified by ``time_of_day`` are all range-checked,
and an error is returned if any one is out of its valid range.
-RTEMS can represent time points of this clock in nanoseconds ranging from
-1988-01-01T00:00:00.000000000Z to 2514-05-31T01:53:03.999999999Z. The future
-uptime of the system shall be in this range, otherwise the system behaviour is
-undefined.
+RTEMS can represent time points of the :term:`CLOCK_REALTIME` clock in
+nanoseconds ranging from 1988-01-01T00:00:00.000000000Z to
+2514-05-31T01:53:03.999999999Z. The future uptime of the system shall be in
+this range, otherwise the system behaviour is undefined. Due to implementation
+constraints, the time of day set by the directive shall be before
+2100-01-01:00:00.000000000Z. The latest valid time of day accepted by the
+POSIX `clock_settime()
+<https://pubs.opengroup.org/onlinepubs/9699919799/functions/clock_settime.html>`_
+is 2400-01-01T00:00:00.999999999Z.
The specified time is based on the configured :term:`clock tick` rate, see the
:ref:`CONFIGURE_MICROSECONDS_PER_TICK` application configuration option.
@@ -102,6 +107,12 @@ The following constraints apply to this directive:
* The directive may unblock a task. This may cause the calling task to be
preempted.
+* The time of day set by the directive shall be 1988-01-01T00:00:00.000000000Z
+ or later.
+
+* The time of day set by the directive shall be before
+ 2100-01-01T00:00:00.000000000Z.
+
.. Generated from spec:/rtems/clock/if/get-tod
.. raw:: latex
diff --git a/c-user/fatal-error/directives.rst b/c-user/fatal-error/directives.rst
index 98ce209..6aa4b20 100644
--- a/c-user/fatal-error/directives.rst
+++ b/c-user/fatal-error/directives.rst
@@ -116,10 +116,10 @@ Prints the message and invokes the fatal error handler.
.. rubric:: DESCRIPTION:
-This directive prints a message via :c:func:`printk` specified by the ``fmt``
-parameter and optional parameters and then invokes the fatal error handler.
-The fatal source is set to :c:macro:`RTEMS_FATAL_SOURCE_PANIC`. The fatal code
-is set to the value of the ``fmt`` parameter value.
+This directive prints a message via :ref:`InterfacePrintk` specified by the
+``fmt`` parameter and optional parameters and then invokes the fatal error
+handler. The fatal source is set to :c:macro:`RTEMS_FATAL_SOURCE_PANIC`. The
+fatal code is set to the value of the ``fmt`` parameter value.
.. rubric:: CONSTRAINTS:
@@ -216,7 +216,7 @@ Prints the exception frame.
.. rubric:: DESCRIPTION:
The exception frame is printed in an architecture-dependent format using
-:c:func:`printk`.
+:ref:`InterfacePrintk`.
.. Generated from spec:/rtems/fatal/if/source-text
diff --git a/c-user/glossary.rst b/c-user/glossary.rst
index 99f7c60..9274cf3 100644
--- a/c-user/glossary.rst
+++ b/c-user/glossary.rst
@@ -334,7 +334,8 @@ Glossary
This term is an acronym for :term:`First In First Out`.
First In First Out
- A discipline for manipulating entries in a data structure.
+ A discipline for manipulating entries in a data structure. See also
+ :term:`Last In First Out`.
floating point coprocessor
A component used in computer systems to enhance performance in
@@ -393,6 +394,10 @@ Glossary
heterogeneous
A multiprocessor computer system composed of dissimilar processors.
+ higher priority
+ A :term:`task` ``H`` has a higher :term:`priority` than a task ``L``, if
+ task ``H`` is more important than task ``L``.
+
home scheduler
The home scheduler of a :term:`task` is a :term:`scheduler` which is an
:term:`eligible scheduler` and which is assigned to the task during its
@@ -460,6 +465,13 @@ Glossary
kernel
In this document, this term is used as a synonym for executive.
+ Last In First Out
+ A discipline for manipulating entries in a data structure. See also
+ :term:`First In First Out`.
+
+ LIFO
+ This term is an acronym for :term:`Last In First Out`.
+
list
A data structure which allows for dynamic addition and removal of
entries. It is not statically limited to a particular size.
@@ -486,6 +498,10 @@ Glossary
A multiprocessor configuration where shared memory is not used for
communication.
+ lower priority
+ A :term:`task` ``L`` has a lower :term:`priority` than a task ``H``, if
+ task ``L`` is less important than task ``H``.
+
major number
The index of a device driver in the Device Driver Table.
@@ -652,8 +668,22 @@ Glossary
priority
The priority is a mechanism used to represent the relative importance of an
- element in a set of items. RTEMS uses :term:`task priorities <task priority>` to determine
- which :term:`task` should execute.
+ element in a set of items.
+
+ For example, :term:`RTEMS` uses :term:`task priorities <task priority>` to determine which
+ :term:`task` should execute on a processor. In RTEMS, priorities are
+ represented by non-negative integers.
+
+ For the Classic :term:`API`, if a numerical priority value ``A`` is greater
+ than a numerical priority value ``B``, then ``A`` expresses a
+ :term:`lower priority` than ``B``. If a numerical priority value ``C`` is
+ less than a numerical priority value ``D``, then ``C`` expresses a
+ :term:`higher priority` than ``D``.
+
+ For the :term:`POSIX` API, if a numerical priority value ``R`` is less than
+ a numerical priority value ``S``, then ``R`` expresses a lower priority than
+ ``S``. If a numerical priority value ``T`` is greater than a numerical
+ priority value ``U``, then ``T`` expresses a higher priority than ``U``.
priority boosting
A simple approach to extend the priority inheritance protocol for
@@ -987,13 +1017,18 @@ Glossary
and resumes execution on another processor.
task priority
- A task priority of a :term:`task` determines its importance relative to
- other tasks. The scheduler use task priorities to determine which
- :term:`ready task` gets a processor allocated, see :term:`scheduled task`. The
+ A task :term:`priority` of a :term:`task` determines its importance
+ relative to other tasks.
+
+ The scheduler use task priorities to determine which :term:`ready task` gets
+ a processor allocated, see :term:`scheduled task`. The
:term:`eligible priorities <eligible priority>` of a task define the position of the task in a
:term:`wait queue` which uses the priority discipline. Each task has at
least the :term:`real priority`.
+ Task priorities are used in :term:`wait queues <wait queue>` which use the priority
+ discipline to determine the dequeueing order of tasks.
+
task processor affinity
The set of processors on which a task is allowed to execute.
diff --git a/c-user/index.rst b/c-user/index.rst
index 5cd87af..385ea95 100644
--- a/c-user/index.rst
+++ b/c-user/index.rst
@@ -44,6 +44,8 @@ RTEMS Classic API Guide (|version|).
region/index
dual-ported-memory/index
io/index
+ kernel-character-io/index
+ cache/index
fatal-error/index
board_support_packages
user-extensions/index
diff --git a/c-user/kernel-character-io/directives.rst b/c-user/kernel-character-io/directives.rst
new file mode 100644
index 0000000..f13010e
--- /dev/null
+++ b/c-user/kernel-character-io/directives.rst
@@ -0,0 +1,372 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de)
+.. Copyright (C) 2015 On-Line Applications Research Corporation (OAR)
+
+.. This file is part of the RTEMS quality process and was automatically
+.. generated. If you find something that needs to be fixed or
+.. worded better please post a report or patch to an RTEMS mailing list
+.. or raise a bug report:
+..
+.. https://www.rtems.org/bugs.html
+..
+.. For information on updating and regenerating please refer to the How-To
+.. section in the Software Requirements Engineering chapter of the
+.. RTEMS Software Engineering manual. The manual is provided as a part of
+.. a release. For development sources please refer to the online
+.. documentation at:
+..
+.. https://docs.rtems.org
+
+.. _KernelCharacterIOSupportDirectives:
+
+Directives
+==========
+
+This section details the directives of the Kernel Character I/O Support. A
+subsection is dedicated to each of this manager's directives and lists the
+calling sequence, parameters, description, return values, and notes of the
+directive.
+
+.. Generated from spec:/rtems/io/if/putc
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: rtems_putc()
+
+.. _InterfaceRtemsPutc:
+
+rtems_putc()
+------------
+
+Outputs the character to the kernel character output device.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ void rtems_putc( char c );
+
+.. rubric:: PARAMETERS:
+
+``c``
+ This parameter is the character to output.
+
+.. rubric:: DESCRIPTION:
+
+The directive outputs the character specified by ``c`` to the kernel character
+output device using the polled character output implementation provided by
+BSP_output_char. The directive performs a character translation from ``NL`` to
+``CR`` followed by ``NR``.
+
+If the kernel character output device is concurrently accessed, then
+interleaved output may occur.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/io/if/put-char
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: rtems_put_char()
+
+.. _InterfaceRtemsPutChar:
+
+rtems_put_char()
+----------------
+
+Puts the character using :ref:`InterfaceRtemsPutc`
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ void rtems_put_char( int c, void *unused );
+
+.. rubric:: PARAMETERS:
+
+``c``
+ This parameter is the character to output.
+
+``unused``
+ This parameter is an unused argument.
+
+.. rubric:: NOTES:
+
+The directive is provided to support the RTEMS Testing Framework.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/io/if/putk
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: putk()
+
+.. _InterfacePutk:
+
+putk()
+------
+
+Outputs the characters of the string and a newline character to the kernel
+character output device.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ int putk( const char *s );
+
+.. rubric:: PARAMETERS:
+
+``s``
+ This parameter is the string to output.
+
+.. rubric:: RETURN VALUES:
+
+Returns the number of characters output to the kernel character output device.
+
+.. rubric:: NOTES:
+
+The directive may be used to print debug and test information. It uses
+:ref:`InterfaceRtemsPutc` to output the characters. This directive performs a
+character translation from ``NL`` to ``CR`` followed by ``NR``.
+
+If the kernel character output device is concurrently accessed, then
+interleaved output may occur.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/io/if/printk
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: printk()
+
+.. _InterfacePrintk:
+
+printk()
+--------
+
+Outputs the characters defined by the format string and the arguments to the
+kernel character output device.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ int printk( const char *fmt, ... );
+
+.. rubric:: PARAMETERS:
+
+``fmt``
+ This parameter is a printf()-style format string.
+
+``...``
+ This parameter is a list of optional parameters required by the format
+ string.
+
+.. rubric:: RETURN VALUES:
+
+Returns the number of characters output to the kernel character output device.
+
+.. rubric:: NOTES:
+
+The directive may be used to print debug and test information. It uses
+:ref:`InterfaceRtemsPutc` to output the characters. This directive performs a
+character translation from ``NL`` to ``CR`` followed by ``NR``.
+
+If the kernel character output device is concurrently accessed, then
+interleaved output may occur.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+* Formatting of floating point numbers is not supported.
+
+.. Generated from spec:/rtems/io/if/vprintk
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: vprintk()
+
+.. _InterfaceVprintk:
+
+vprintk()
+---------
+
+Outputs the characters defined by the format string and the variable argument
+list to the kernel character output device.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ int vprintk( const char *fmt, va_list ap );
+
+.. rubric:: PARAMETERS:
+
+``fmt``
+ This parameter is a printf()-style format string.
+
+``ap``
+ This parameter is the variable argument list required by the format string.
+
+.. rubric:: RETURN VALUES:
+
+Returns the number of characters output to the kernel character output device.
+
+.. rubric:: NOTES:
+
+The directive may be used to print debug and test information. It uses
+:ref:`InterfaceRtemsPutc` to output the characters. This directive performs a
+character translation from ``NL`` to ``CR`` followed by ``NR``.
+
+If the kernel character output device is concurrently accessed, then
+interleaved output may occur.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+* Formatting of floating point numbers is not supported.
+
+.. Generated from spec:/rtems/io/if/printk-printer
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: rtems_printk_printer()
+
+.. _InterfaceRtemsPrintkPrinter:
+
+rtems_printk_printer()
+----------------------
+
+Outputs the characters defined by the format string and the variable argument
+list to the kernel character output device.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ int rtems_printk_printer( void *unused, const char *fmt, va_list ap );
+
+.. rubric:: PARAMETERS:
+
+``unused``
+ This parameter is an unused argument.
+
+``fmt``
+ This parameter is a printf()-style format string.
+
+``ap``
+ This parameter is the variable argument list required by the format string.
+
+.. rubric:: RETURN VALUES:
+
+Returns the number of characters output to the kernel character output device.
+
+.. rubric:: NOTES:
+
+The directive may be used to print debug and test information. It uses
+:ref:`InterfaceRtemsPutc` to output the characters. This directive performs a
+character translation from ``NL`` to ``CR`` followed by ``NR``.
+
+If the kernel character output device is concurrently accessed, then
+interleaved output may occur.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+* Formatting of floating point numbers is not supported.
+
+.. Generated from spec:/rtems/io/if/getchark
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: getchark()
+
+.. _InterfaceGetchark:
+
+getchark()
+----------
+
+Tries to dequeue a character from the kernel character input device.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ int getchark( void );
+
+.. rubric:: DESCRIPTION:
+
+The directive tries to dequeue a character from the kernel character input
+device using the polled character input implementation referenced by
+BSP_poll_char if it is available.
+
+.. rubric:: RETURN VALUES:
+
+``-1``
+ The BSP_poll_char pointer was equal to `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+``-1``
+ There was no character enqueued on the kernel character input device.
+
+Returns the character least recently enqueued on the kernel character input
+device as an unsigned character value.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
diff --git a/c-user/kernel-character-io/index.rst b/c-user/kernel-character-io/index.rst
new file mode 100644
index 0000000..c6a9b6b
--- /dev/null
+++ b/c-user/kernel-character-io/index.rst
@@ -0,0 +1,15 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+
+.. index:: Kernel Character I/O Support
+
+.. _RTEMSAPIKernelCharIO:
+
+Kernel Character I/O Support
+****************************
+
+.. toctree::
+
+ introduction
+ directives
diff --git a/c-user/kernel-character-io/introduction.rst b/c-user/kernel-character-io/introduction.rst
new file mode 100644
index 0000000..ef3512b
--- /dev/null
+++ b/c-user/kernel-character-io/introduction.rst
@@ -0,0 +1,69 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de)
+.. Copyright (C) 2015 On-Line Applications Research Corporation (OAR)
+
+.. This file is part of the RTEMS quality process and was automatically
+.. generated. If you find something that needs to be fixed or
+.. worded better please post a report or patch to an RTEMS mailing list
+.. or raise a bug report:
+..
+.. https://www.rtems.org/bugs.html
+..
+.. For information on updating and regenerating please refer to the How-To
+.. section in the Software Requirements Engineering chapter of the
+.. RTEMS Software Engineering manual. The manual is provided as a part of
+.. a release. For development sources please refer to the online
+.. documentation at:
+..
+.. https://docs.rtems.org
+
+.. Generated from spec:/rtems/io/if/group-3
+
+.. _KernelCharacterIOSupportIntroduction:
+
+Introduction
+============
+
+.. The following list was generated from:
+.. spec:/rtems/io/if/putc
+.. spec:/rtems/io/if/put-char
+.. spec:/rtems/io/if/putk
+.. spec:/rtems/io/if/printk
+.. spec:/rtems/io/if/vprintk
+.. spec:/rtems/io/if/printk-printer
+.. spec:/rtems/io/if/getchark
+
+The kernel character input/output support is an extension of the
+:ref:`RTEMSAPIClassicIO` to output characters to the kernel character output
+device and receive characters from the kernel character input device using a
+polled and non-blocking implementation.
+
+The directives may be used to print debug and test information. The kernel
+character input/output support should work even if no Console Driver is
+configured, see :ref:`CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`. The kernel
+character input and output device is provided by the :term:`BSP`. Applications
+may change the device. The directives provided by the Kernel Character I/O
+Support are:
+
+* :ref:`InterfaceRtemsPutc` - Outputs the character to the kernel character
+ output device.
+
+* :ref:`InterfaceRtemsPutChar` - Puts the character using
+ :ref:`InterfaceRtemsPutc`
+
+* :ref:`InterfacePutk` - Outputs the characters of the string and a newline
+ character to the kernel character output device.
+
+* :ref:`InterfacePrintk` - Outputs the characters defined by the format string
+ and the arguments to the kernel character output device.
+
+* :ref:`InterfaceVprintk` - Outputs the characters defined by the format string
+ and the variable argument list to the kernel character output device.
+
+* :ref:`InterfaceRtemsPrintkPrinter` - Outputs the characters defined by the
+ format string and the variable argument list to the kernel character output
+ device.
+
+* :ref:`InterfaceGetchark` - Tries to dequeue a character from the kernel
+ character input device.
diff --git a/c-user/message/directives.rst b/c-user/message/directives.rst
index f320350..70a22d3 100644
--- a/c-user/message/directives.rst
+++ b/c-user/message/directives.rst
@@ -891,10 +891,6 @@ queue.
:c:macro:`RTEMS_UNSATISFIED`
The queue was empty.
-:c:macro:`RTEMS_UNSATISFIED`
- The queue was flushed while the calling task was waiting to receive a
- message.
-
:c:macro:`RTEMS_TIMEOUT`
The timeout happened while the calling task was waiting to receive a
message
@@ -1018,8 +1014,8 @@ Flushes all messages on the queue.
``count``
This parameter is the pointer to an `uint32_t
<https://en.cppreference.com/w/c/types/integer>`_ object. When the
- directive call is successful, the number of unblocked tasks will be stored
- in this object.
+ directive call is successful, the number of pending messages removed from
+ the queue will be stored in this object.
.. rubric:: DESCRIPTION:
@@ -1039,17 +1035,22 @@ present on the queue, count is set to zero.
The ``count`` parameter was `NULL
<https://en.cppreference.com/w/c/types/NULL>`_.
+.. rubric:: NOTES:
+
+The directive does not flush tasks waiting to receive a message from the
+:term:`wait queue` of the message queue.
+
.. rubric:: CONSTRAINTS:
The following constraints apply to this directive:
-* The directive may be called from within task context.
-
* The directive may be called from within interrupt context.
-* When the directive operates on a remote object, the directive sends a message
- to the remote node and waits for a reply. This will preempt the calling
- task.
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive will not cause the calling task to be preempted.
.. Generated from spec:/rtems/message/if/buffer
diff --git a/c-user/rate-monotonic/directives.rst b/c-user/rate-monotonic/directives.rst
index 02b8898..2e48aac 100644
--- a/c-user/rate-monotonic/directives.rst
+++ b/c-user/rate-monotonic/directives.rst
@@ -652,7 +652,7 @@ The following constraints apply to this directive:
rtems_rate_monotonic_report_statistics()
----------------------------------------
-Reports the period statistics using the :c:func:`printk` printer.
+Reports the period statistics using the :ref:`InterfacePrintk` printer.
.. rubric:: CALLING SEQUENCE:
@@ -663,7 +663,7 @@ Reports the period statistics using the :c:func:`printk` printer.
.. rubric:: DESCRIPTION:
This directive prints a report on all active periods which have executed at
-least one period using the :c:func:`printk` printer.
+least one period using the :ref:`InterfacePrintk` printer.
.. rubric:: CONSTRAINTS:
diff --git a/c-user/rate-monotonic/introduction.rst b/c-user/rate-monotonic/introduction.rst
index 5b0c094..9e3c6f0 100644
--- a/c-user/rate-monotonic/introduction.rst
+++ b/c-user/rate-monotonic/introduction.rst
@@ -70,7 +70,7 @@ by the Rate-Monotonic Manager are:
of all periods.
* :ref:`InterfaceRtemsRateMonotonicReportStatistics` - Reports the period
- statistics using the :c:func:`printk` printer.
+ statistics using the :ref:`InterfacePrintk` printer.
* :ref:`InterfaceRtemsRateMonotonicReportStatisticsWithPlugin` - Reports the
period statistics using the printer plugin.
diff --git a/c-user/scheduling-concepts/background.rst b/c-user/scheduling-concepts/background.rst
index 7f8a63d..1fe7089 100644
--- a/c-user/scheduling-concepts/background.rst
+++ b/c-user/scheduling-concepts/background.rst
@@ -117,10 +117,7 @@ Task Priority and Scheduling
The most significant task scheduling modification mechanism is the ability for
the user to assign a priority level to each individual task when it is created
-and to alter a task's priority at run-time. The maximum priority level depends
-on the configured scheduler. A lower priority level means higher priority
-(higher importance). The maximum priority level of the default uniprocessor
-scheduler is 255.
+and to alter a task's priority at run-time, see :ref:`TaskPriority`.
.. index:: preemption
diff --git a/c-user/scheduling-concepts/smp-schedulers.rst b/c-user/scheduling-concepts/smp-schedulers.rst
index cfab04f..d6c1dc6 100644
--- a/c-user/scheduling-concepts/smp-schedulers.rst
+++ b/c-user/scheduling-concepts/smp-schedulers.rst
@@ -45,7 +45,7 @@ Deterministic Priority SMP Scheduler
A fixed-priority scheduler which uses a table of chains with one chain per
priority level for the ready tasks. The maximum priority level is
configurable. By default, the maximum priority level is 255 (256 priority
-levels).
+levels), see :ref:`CONFIGURE_MAXIMUM_PRIORITY`.
.. _SchedulerSMPPrioritySimple:
@@ -64,6 +64,7 @@ Arbitrary Processor Affinity Priority SMP Scheduler
A fixed-priority scheduler which uses a table of chains with one chain per
priority level for the ready tasks. The maximum priority level is
configurable. By default, the maximum priority level is 255 (256 priority
-levels). This scheduler supports arbitrary task processor affinities. The
-worst-case run-time complexity of some scheduler operations exceeds
-:math:`O(n)` while :math:`n` is the count of ready tasks.
+levels), see :ref:`CONFIGURE_MAXIMUM_PRIORITY`. This scheduler supports
+arbitrary task processor affinities. The worst-case run-time complexity of
+some scheduler operations exceeds :math:`O(n)` while :math:`n` is the count of
+ready tasks.
diff --git a/c-user/task/background.rst b/c-user/task/background.rst
index a55f743..da6cabf 100644
--- a/c-user/task/background.rst
+++ b/c-user/task/background.rst
@@ -127,13 +127,19 @@ scheduling of a task is based on its current state and priority.
.. index:: priority, task
.. index:: rtems_task_priority
+.. _TaskPriority:
+
Task Priority
-------------
-A task's priority determines its importance in relation to the other tasks
-executing on the same processor. RTEMS supports 255 levels of priority ranging
-from 1 to 255. The data type ``rtems_task_priority`` is used to store task
-priorities.
+A task's :term:`priority` determines its importance in relation to the other
+tasks executing on the processor set owned by a :term:`scheduler`. Normally,
+RTEMS supports 256 levels of priority ranging from 0 to 255. The priority
+level 0 represents a special priority reserved for the operating system. The
+data type :c:type:`rtems_task_priority` is used to store task priorities. The
+maximum priority level depends on the configured scheduler, see
+:ref:`CONFIGURE_MAXIMUM_PRIORITY`, :ref:`ConfigurationSchedulersClustered`, and
+:ref:`RTEMSAPIClassicScheduler`.
Tasks of numerically smaller priority values are more important tasks than
tasks of numerically larger priority values. For example, a task at priority
diff --git a/c-user/user-extensions/directives.rst b/c-user/user-extensions/directives.rst
index 2dbac54..ac04cdd 100644
--- a/c-user/user-extensions/directives.rst
+++ b/c-user/user-extensions/directives.rst
@@ -102,11 +102,15 @@ The extension set is initialized using the extension table specified in
.. rubric:: NOTES:
-The user-provided extension set table is not used after the return of the
+The user-provided extension table is not used after the return of the
directive.
-Newly created extension sets are immediately installed and are invoked upon the
-next system event supporting an extension.
+Each extension of the extension table is optional and may be `NULL
+<https://en.cppreference.com/w/c/types/NULL>`_. All extensions except the task
+switch extension of the extension table are atomically and immediately
+installed. A task switch extension is separately installed after the other
+extensions. The extensions of the extension table are invoked upon the next
+system event supporting an extension.
An alternative to dynamically created extension sets are initial extensions,
see :ref:`CONFIGURE_INITIAL_EXTENSIONS`. Initial extensions are recommended
diff --git a/eng/build-system.rst b/eng/build-system.rst
index e76b606..030679d 100644
--- a/eng/build-system.rst
+++ b/eng/build-system.rst
@@ -355,8 +355,8 @@ Add a Base BSP to a BSP Family
items ``spec:/build/bsps/arch/family/bsprst``,
``spec:/build/bsps/arch/family/bspuvw``, and
``spec:/build/bsps/arch/family/bspxyz`` just define the name of the base
- BSP and set a link to the group item. The base BSP names can be used for
- example in the ``default-by-variant`` attribute of
+ BSP and set a link to the group item. The base BSP and BSP family names
+ can be used for example in the ``default-by-variant`` attribute of
:ref:`SpecTypeBuildOptionItemType` items. The items linked by the BSP
items are shown using relative UIDs.
diff --git a/eng/coding-conventions.rst b/eng/coding-conventions.rst
index 668a917..575dd44 100644
--- a/eng/coding-conventions.rst
+++ b/eng/coding-conventions.rst
@@ -219,8 +219,6 @@ Performance
* Understand the constraints of `real-time programming <https://devel.rtems.org/wiki/TBR/Review/Real-Time_Resources>`_..
Limit execution times in interrupt contexts and critical sections,
such as Interrupt and Timer Service Routines (TSRs).
-* Functions used only through function pointers should be declared
- 'static inline' (RTEMS_INLINE_ROUTINE)
* Prefer to ++preincrement instead of postincrement++.
* Avoid using floating point except where absolutely necessary.
diff --git a/eng/req/items.rst b/eng/req/items.rst
index e7727aa..2c1e361 100644
--- a/eng/req/items.rst
+++ b/eng/req/items.rst
@@ -719,8 +719,11 @@ default
default-by-variant
The attribute value shall be a list. Each list element shall be a
- :ref:`SpecTypeBuildOptionDefaultByVariant`. The list is processed from top
- to bottom. If a matching variant is found, then the processing stops.
+ :ref:`SpecTypeBuildOptionDefaultByVariant`. The list is checked two times
+ and processed from top to bottom. Firstly, the base BSP name is used to
+ match with a variant. Secondly, the BSP family name prefixed by ``bsps/``
+ is used to match with a variant. If a matching variant is found, then the
+ processing stops.
description
The attribute value shall be an optional string. It shall be the
@@ -750,6 +753,7 @@ Please have a look at the following example:
default-by-variant:
- value: 9600
variants:
+ - bsps/powerpc/motorola_powerpc
- m68k/m5484FireEngine
- powerpc/hsc_cm01
- value: 19200
@@ -1544,6 +1548,13 @@ name
notes
The attribute value shall be an :ref:`SpecTypeInterfaceNotes`.
+params
+ The attribute value shall be a list. Each list element shall be an
+ :ref:`SpecTypeInterfaceParameter`.
+
+return
+ The attribute value shall be an :ref:`SpecTypeInterfaceReturnDirective`.
+
.. _SpecTypeInterfaceUnspecifiedItemType:
Interface Unspecified Item Type
@@ -3090,7 +3101,7 @@ Build Install Path
A value of this type shall be of one of the following variants:
-* There may by be no value (null).
+* There may be no value (null).
* The value may be a string. It shall be the installation path of a
:ref:`SpecTypeBuildTarget`.
@@ -3451,7 +3462,7 @@ A value of this type shall be of one of the following variants:
* The value may be a list. Each list element shall be a string.
-* There may by be no value (null).
+* There may be no value (null).
* The value may be a string.
@@ -3692,7 +3703,7 @@ Interface Brief Description
A value of this type shall be of one of the following variants:
-* There may by be no value (null).
+* There may be no value (null).
* The value may be a string. It shall be the brief description of the
interface. It should be a single sentence. The value shall not match with
@@ -3786,23 +3797,27 @@ definition
Interface Compound Member Definition
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-This set of attributes specifies an interface compound member definition. All
-explicit attributes shall be specified. The explicit attributes for this type
-are:
+A value of this type shall be of one of the following variants:
-brief
- The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`.
+* The value may be a set of attributes. This set of attributes specifies an
+ interface compound member definition. All explicit attributes shall be
+ specified. The explicit attributes for this type are:
-description
- The attribute value shall be an :ref:`SpecTypeInterfaceDescription`.
+ brief
+ The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`.
-kind
- The attribute value shall be a string. It shall be the interface compound
- member kind.
+ description
+ The attribute value shall be an :ref:`SpecTypeInterfaceDescription`.
-name
- The attribute value shall be a string. It shall be the interface compound
- member name.
+ kind
+ The attribute value shall be a string. It shall be the interface compound
+ member kind.
+
+ name
+ The attribute value shall be a string. It shall be the interface compound
+ member name.
+
+* There may be no value (null).
This type is refined by the following types:
@@ -3871,7 +3886,7 @@ Interface Definition
A value of this type shall be of one of the following variants:
-* There may by be no value (null).
+* There may be no value (null).
* The value may be a string. It shall be the definition. On the definition a
context-sensitive substitution of item variables is performed.
@@ -3941,7 +3956,7 @@ Interface Description
A value of this type shall be of one of the following variants:
-* There may by be no value (null).
+* There may be no value (null).
* The value may be a string. It shall be the description of the interface. The
description should be short and concentrate on the average case. All special
@@ -4059,33 +4074,38 @@ links.
Interface Function Definition
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-This set of attributes specifies a function definition. All explicit attributes
-shall be specified. The explicit attributes for this type are:
+A value of this type shall be of one of the following variants:
-attributes
- The attribute value shall be an optional string. If the value is present,
- then it shall be the function attributes. On the attributes a
- context-sensitive substitution of item variables is performed. A function
- attribute is for example the indication that the function does not return
- to the caller.
+* The value may be a set of attributes. This set of attributes specifies a
+ function definition. All explicit attributes shall be specified. The explicit
+ attributes for this type are:
-body
- The attribute value shall be an optional string. If the value is present,
- then it shall be the definition of a static inline function. On the
- function definition a context-sensitive substitution of item variables is
- performed. If no value is present, then the function is declared as an
- external function.
+ attributes
+ The attribute value shall be an optional string. If the value is present,
+ then it shall be the function attributes. On the attributes a
+ context-sensitive substitution of item variables is performed. A
+ function attribute is for example the indication that the function does
+ not return to the caller.
-params
- The attribute value shall be a list of strings. It shall be the list of
- parameter declarations of the function. On the function parameter
- declarations a context-sensitive substitution of item variables is
- performed.
+ body
+ The attribute value shall be an optional string. If the value is present,
+ then it shall be the definition of a static inline function. On the
+ function definition a context-sensitive substitution of item variables is
+ performed. If no value is present, then the function is declared as an
+ external function.
-return
- The attribute value shall be a string. It shall be the function return
- type. On the return type a context-sensitive substitution of item
- variables is performed.
+ params
+ The attribute value shall be a list of strings. It shall be the list of
+ parameter declarations of the function. On the function parameter
+ declarations a context-sensitive substitution of item variables is
+ performed.
+
+ return
+ The attribute value shall be a string. It shall be the function return
+ type. On the return type a context-sensitive substitution of item
+ variables is performed.
+
+* There may be no value (null).
This type is used by the following types:
@@ -4171,6 +4191,18 @@ This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the
value is ``interface-ingroup``. It defines the interface group membership role
of links.
+.. _SpecTypeInterfaceHiddenGroupMembershipLinkRole:
+
+Interface Hidden Group Membership Link Role
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the
+value is ``interface-ingroup-hidden``. It defines the interface hidden group
+membership role of links. This role may be used to make an interface a group
+member and hide this relationship in the documentation. An example is an
+optimized macro implementation of a directive which has the same name as the
+corresponding directive.
+
.. _SpecTypeInterfaceIncludeLinkRole:
Interface Include Link Role
@@ -4194,7 +4226,7 @@ Interface Notes
A value of this type shall be of one of the following variants:
-* There may by be no value (null).
+* There may be no value (null).
* The value may be a string. It shall be the notes for the interface.
@@ -4240,6 +4272,8 @@ This type is used by the following types:
* :ref:`SpecTypeInterfaceMacroItemType`
+* :ref:`SpecTypeInterfaceTypedefItemType`
+
.. _SpecTypeInterfaceParameterDirection:
Interface Parameter Direction
@@ -4247,7 +4281,7 @@ Interface Parameter Direction
A value of this type shall be of one of the following variants:
-* There may by be no value (null).
+* There may be no value (null).
* The value may be a string. It specifies the interface parameter direction.
The value shall be an element of
@@ -4293,16 +4327,21 @@ This type is used by the following types:
Interface Return Directive
^^^^^^^^^^^^^^^^^^^^^^^^^^
-This set of attributes specifies an interface return. All explicit attributes
-shall be specified. The explicit attributes for this type are:
+A value of this type shall be of one of the following variants:
-return
- The attribute value shall be an optional string. It shall describe the
- interface return for unspecified return values.
+* The value may be a set of attributes. This set of attributes specifies an
+ interface return. All explicit attributes shall be specified. The explicit
+ attributes for this type are:
-return-values
- The attribute value shall be a list. Each list element shall be an
- :ref:`SpecTypeInterfaceReturnValue`.
+ return
+ The attribute value shall be an optional string. It shall describe the
+ interface return for unspecified return values.
+
+ return-values
+ The attribute value shall be a list. Each list element shall be an
+ :ref:`SpecTypeInterfaceReturnValue`.
+
+* There may be no value (null).
This type is used by the following types:
@@ -4310,6 +4349,8 @@ This type is used by the following types:
* :ref:`SpecTypeInterfaceMacroItemType`
+* :ref:`SpecTypeInterfaceTypedefItemType`
+
.. _SpecTypeInterfaceReturnValue:
Interface Return Value
@@ -4372,6 +4413,8 @@ This type is refined by the following types:
* :ref:`SpecTypeInterfaceGroupMembershipLinkRole`
+* :ref:`SpecTypeInterfaceHiddenGroupMembershipLinkRole`
+
* :ref:`SpecTypeInterfaceIncludeLinkRole`
* :ref:`SpecTypeInterfacePlacementLinkRole`
@@ -4455,7 +4498,7 @@ Optional String
A value of this type shall be of one of the following variants:
-* There may by be no value (null).
+* There may be no value (null).
* The value may be a string.
@@ -5471,7 +5514,7 @@ A value of this type shall be of one of the following variants:
member definition. It shall be a valid C structure member definition
without a trailing ``;``.
-* There may by be no value (null).
+* There may be no value (null).
This type is used by the following types:
@@ -5525,7 +5568,7 @@ A value of this type shall be of one of the following variants:
The attribute value shall be a string. It shall be the path to the
generated test header file.
-* There may by be no value (null).
+* There may be no value (null).
This type is used by the following types:
@@ -5587,7 +5630,7 @@ A value of this type shall be of one of the following variants:
The attribute value shall be an optional string. It shall be the test
support method description.
-* There may by be no value (null).
+* There may be no value (null).
This type is used by the following types:
diff --git a/user/bsps/arm/raspberrypi.rst b/user/bsps/arm/raspberrypi.rst
index c26f4b5..235134f 100644
--- a/user/bsps/arm/raspberrypi.rst
+++ b/user/bsps/arm/raspberrypi.rst
@@ -5,8 +5,9 @@
raspberrypi
===========
-This BSP supports `Raspberry Pi 1` and `Raspberry Pi 2` currently.
-The support for `Raspberry Pi 3` is work under progress.
+The 'raspberrypi' BSP supports the single core models (Zero, Zero W, A+, B+),
+and the 'raspberrypi2' BSP supports the Raspberry Pi 2, Raspberry Pi 3 A+, and Raspberry Pi 3.
+The Raspberry Pi 4 is not supported currently.
The default bootloader on the Raspberry Pi which is used to boot Raspbian
or other OS can be also used to boot RTEMS. U-boot can also be used.
@@ -19,10 +20,12 @@ The bootloader looks for a kernel image, by default the kernel images must
have a name of the form ``kernel*.img`` but this can be changed by adding
`kernel=<img_name>` to ``config.txt``.
-You must provide the required files for the GPU to proceed. These files
+You must provide the required firmware files on the SD card for the GPU to proceed,
+and thereby to boot RTEMS.
+The BSP currently boots up with an older version of the official firmware. These files
can be downloaded from
-`the Raspberry Pi Firmware Repository <https://github.com/raspberrypi/firmware/tree/master/boot>`_.
-You can remove the ``kernel*.img`` files if you want too, but don't touch
+`the Raspberry Pi Firmware Repository <https://github.com/raspberrypi/firmware/tree/1.20200601/boot>`_.
+You can remove the ``kernel*.img`` files if you want to, but don't touch
the other files.
Copy these files in to a SD card with FAT filesystem.
@@ -46,10 +49,46 @@ Make sure you have these lines below, in your ``config.txt``.
.. code-block:: none
- enable_uart=1
+ dtoverlay=disable-bt
kernel_address=0x200000
kernel=kernel.img
+SPI Driver
+------------
+
+SPI drivers are registered by the ``rpi_spi_init(bool bidirectional_mode)`` function.
+
+.. code-block:: none
+
+ #include <assert.h>
+ #include <bsp.h>
+
+ void spi_init(void)
+ {
+ int rv;
+
+ rv = rpi_spi_init(false);
+ assert(rv == 0);
+ }
+
+I2C Driver
+------------
+
+I2C drivers are registered by the ``rpi_setup_i2c_bus()`` function.
+
+.. code-block:: none
+
+ #include <assert.h>
+ #include <bsp.h>
+
+ void i2c_init(void)
+ {
+ int rv;
+
+ rv = rpi_setup_i2c_bus();
+ assert(rv == 0);
+ }
+
Testing using QEMU
------------------