[PATCH 2/8] rtems: Cache manager documentation

[Sebastian Huber]

Move useful functions to the top of the file.
---
 cpukit/rtems/include/rtems/rtems/cache.h |  145 ++++++++++++++++--------------
 1 files changed, 79 insertions(+), 66 deletions(-)

diff --git a/cpukit/rtems/include/rtems/rtems/cache.h b/cpukit/rtems/include/rtems/rtems/cache.h
index 372f8f3..a8520d7 100644
--- a/cpukit/rtems/include/rtems/rtems/cache.h
+++ b/cpukit/rtems/include/rtems/rtems/cache.h
@@ -1,12 +1,7 @@
 /**
- * @file rtems/rtems/cache.h
+ * @file
  *
- * @defgroup ClassicCache Cache
- *
- * @ingroup ClassicRTEMS
- * @brief Cache Manager
- *
- * Functionality Associated with the Cache Manager 
+ * @ingroup ClassicCache
  */
 
 /* COPYRIGHT (c) 1989-2013.
@@ -28,62 +23,104 @@ extern "C" {
 #include <sys/types.h>
 
 /**
- *  @defgroup ClassicCache Cache
+ * @defgroup ClassicCache Cache
+ *
+ * @ingroup ClassicRTEMS
+ *
+ * @brief 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.
+ *
+ * @{
+ */
+
+/**
+ * @brief Returns the data cache line size in bytes.
  *
- *  @ingroup ClassicRTEMS
+ * For multi-level caches this is the maximum of the cache line sizes of all
+ * levels.
  *
- *  The functions in this file define the API to the RTEMS Cache Manager and
- *  are divided into data cache and instruction cache functions. Data cache
- *  functions are only meaningful if a data cache is supported. Instruction
- *  cache functions are only meaningful if an instruction cache is supported.
+ * @retval 0 No data cache is present.
+ * @retval positive The data cache line size in bytes.
+ */
+int rtems_cache_get_data_line_size( void );
+
+/**
+ * @brief Returns the instruction cache line size in bytes.
  *
- *  The functions are implemented with CPU dependent support routines
- *  implemented as part of libcpu. In the event that a CPU does not support a
- *  specific function, the CPU dependent routine does nothing (but does exist).
+ * For multi-level caches this is the maximum of the cache line sizes of all
+ * levels.
  *
- *  At this point, the Cache Manager makes no considerations, and provides no
- *  support for BSP specific issues such as a secondary cache. In such a system,
- *  the CPU dependent routines would have to be modified, or a BSP layer added
- *  to this Manager.
+ * @retval 0 No instruction cache is present.
+ * @retval positive The instruction cache line size in bytes.
  */
-/**@{*/
+int rtems_cache_get_instruction_line_size( void );
 
-/*
- *  These functions will ONLY do something if the
- *  libcpu support includes data cache routines AND
- *  the CPU model supports data caching.
+/**
+ * @brief Flushes multiple data cache lines.
+ *
+ * Dirty cache lines covering the area are transfered to memory.  Depending on
+ * the cache implementation this may mark the lines as invalid.
+ *
+ * @param[in] addr The start address of the area to flush.
+ * @param[in] size The size in bytes of the area to flush.
  */
+void rtems_cache_flush_multiple_data_lines( const void *addr, size_t size );
 
 /**
- * This function is called to flush the data cache by performing cache
- * copybacks. It must determine how many cache lines need to be copied
- * back and then perform the copybacks.
+ * @brief Invalidates multiple data cache lines.
+ *
+ * The cache lines covering the area are marked as invalid.  A later read
+ * access in the area will load the data from memory.
+ *
+ * In case the area is not aligned on cache line boundaries, then this
+ * operation may destroy unrelated data.
+ *
+ * @param[in] addr The start address of the area to invalidate.
+ * @param[in] size The size in bytes of the area to invalidate.
  */
-void rtems_cache_flush_multiple_data_lines( const void *, size_t );
+void rtems_cache_invalidate_multiple_data_lines(
+  const void *addr,
+  size_t size
+);
 
 /**
- * This function is responsible for performing a data cache invalidate.
- * It must determine how many cache lines need to be invalidated and then
- * perform the invalidations.
+ * @brief Invalidates multiple instruction cache lines.
+ *
+ * The cache lines covering the area are marked as invalid.  A later
+ * instruction fetch from the area will result in a load from memory.
+ *
+ * @param[in] addr The start address of the area to invalidate.
+ * @param[in] size The size in bytes of the area to invalidate.
  */
-void rtems_cache_invalidate_multiple_data_lines( const void *, size_t );
+void rtems_cache_invalidate_multiple_instruction_lines(
+  const void *addr,
+  size_t size
+);
 
 /**
- * This function is responsible for performing a data cache flush.
- * It flushes the entire cache.
+ * @brief Flushes the entire data cache.
+ *
+ * @see rtems_cache_flush_multiple_data_lines().
  */
 void rtems_cache_flush_entire_data( void );
 
 /**
- * This function is responsible for performing a data cache
- * invalidate. It invalidates the entire cache.
+ * @brief Invalidates the entire instruction cache.
+ *
+ * @see rtems_cache_invalidate_multiple_instruction_lines().
  */
-void rtems_cache_invalidate_entire_data( void );
+void rtems_cache_invalidate_entire_instruction( void );
 
 /**
- * This function returns the data cache granularity.
+ * This function is responsible for performing a data cache
+ * invalidate. It invalidates the entire cache.
  */
-int rtems_cache_get_data_line_size( void );
+void rtems_cache_invalidate_entire_data( void );
 
 /**
  * This function freezes the data cache.
@@ -106,30 +143,6 @@ void rtems_cache_enable_data( void );
 void rtems_cache_disable_data( void );
 
 /**
- *  These functions will ONLY do something if the
- *  libcpu support includes instruction cache routines AND
- *  the CPU model supports instruction caching.
- */
-
-/**
- * This function is responsible for performing an instruction cache
- * invalidate. It must determine how many cache lines need to be invalidated
- * and then perform the invalidations.
- */
-void rtems_cache_invalidate_multiple_instruction_lines( const void *, size_t );
-
-/**
- * This function is responsible for performing an instruction cache
- * invalidate. It invalidates the entire cache.
- */
-void rtems_cache_invalidate_entire_instruction( void );
-
-/**
- * This function returns the instruction cache granularity.
- */
-int rtems_cache_get_instruction_line_size( void );
-
-/**
  * This function freezes the instruction cache.
  */
 void rtems_cache_freeze_instruction( void );
@@ -155,11 +168,11 @@ void rtems_cache_disable_instruction( void );
  */
 void *rtems_cache_aligned_malloc ( size_t nbytes );
 
+/**@}*/
+
 #ifdef __cplusplus
 }
 #endif
 
-/**@}*/
-
 #endif
 /* end of include file */
-- 
1.7.7