From 023f60936cb4aa49764a8abcb3e39a0455debebe Mon Sep 17 00:00:00 2001
From: Sebastian Huber <sebastian.huber@embedded-brains.de>
Date: Fri, 10 Sep 2021 10:36:44 +0200
Subject: 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.
---
 c-user/cache/introduction.rst | 101 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 101 insertions(+)
 create mode 100644 c-user/cache/introduction.rst

(limited to 'c-user/cache/introduction.rst')

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.
-- 
cgit v1.2.3