c-user: Add "Cache Manager" chapter

The Cache Manager directives are available via <rtems.h>.  Document most
of them in the Classic API Guide.

Not documented are the following directive since the API is not yet
stable:

* rtems_cache_coherent_allocate()
* rtems_cache_coherent_free()
* rtems_cache_coherent_add_area()

Not documented are the following directive since the directives are not
implemented on maintained platforms:

* rtems_cache_freeze_data()
* rtems_cache_freeze_instruction()
* rtems_cache_unfreeze_data()
* rtems_cache_unfreeze_instruction()

Close #4513.

4 files changed, 782 insertions, 0 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/index.rst b/c-user/index.rst
index ae782f0..385ea95 100644
--- a/c-user/index.rst
+++ b/c-user/index.rst
@@ -45,6 +45,7 @@ RTEMS Classic API Guide (|version|).
 	dual-ported-memory/index
 	io/index
 	kernel-character-io/index
+	cache/index
 	fatal-error/index
 	board_support_packages
 	user-extensions/index