From 023f60936cb4aa49764a8abcb3e39a0455debebe Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Fri, 10 Sep 2021 10:36:44 +0200 Subject: c-user: Add "Cache Manager" chapter The Cache Manager directives are available via . 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/directives.rst | 665 ++++++++++++++++++++++++++++++++++++++++++ c-user/cache/index.rst | 15 + c-user/cache/introduction.rst | 101 +++++++ c-user/index.rst | 1 + 4 files changed, 782 insertions(+) create mode 100644 c-user/cache/directives.rst create mode 100644 c-user/cache/index.rst create mode 100644 c-user/cache/introduction.rst 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 `_ + 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 -- cgit v1.2.3