diff options
author | Sebastian Huber <sebastian.huber@embedded-brains.de> | 2014-02-26 10:35:48 +0100 |
---|---|---|
committer | Sebastian Huber <sebastian.huber@embedded-brains.de> | 2014-02-28 08:59:02 +0100 |
commit | 5e8301da86a514e9568e72880de81de08a67037a (patch) | |
tree | 81d9dc0439ef80832fab87fc20f92bd88b648d9c | |
parent | sptests/spcache01: Detect write-through cache (diff) | |
download | rtems-5e8301da86a514e9568e72880de81de08a67037a.tar.bz2 |
rtems: Cache manager documentation
Move useful functions to the top of the file.
-rw-r--r-- | 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 372f8f31fe..a8520d7e4e 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 */ |