diff options
Diffstat (limited to 'cpukit/include/rtems/rtems/cache.h')
| -rw-r--r-- | cpukit/include/rtems/rtems/cache.h | 669 |
1 files changed, 519 insertions, 150 deletions
diff --git a/cpukit/include/rtems/rtems/cache.h b/cpukit/include/rtems/rtems/cache.h index dfcb8f64d1..d59a3fddca 100644 --- a/cpukit/include/rtems/rtems/cache.h +++ b/cpukit/include/rtems/rtems/cache.h @@ -1,294 +1,663 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** * @file * - * @ingroup ClassicCache + * @ingroup RTEMSImplClassicCache + * + * @brief This header file defines the Cache Manager API. + */ + +/* + * Copyright (C) 2016 Pavel Pisa + * Copyright (C) 2014, 2021 embedded brains GmbH & Co. KG + * Copyright (C) 2000, 2008 On-Line Applications Research Corporation (OAR) + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. */ -/* COPYRIGHT (c) 1989-2013. - * 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: * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * http://www.rtems.org/license/LICENSE. + * 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/header */ + #ifndef _RTEMS_RTEMS_CACHE_H #define _RTEMS_RTEMS_CACHE_H -#include <rtems/score/basedefs.h> - -#if defined( RTEMS_SMP ) -#include <sys/cpuset.h> -#endif +#include <stddef.h> +#include <stdint.h> +#include <rtems/rtems/status.h> #ifdef __cplusplus extern "C" { #endif +/* Generated from spec:/rtems/cache/if/group */ + /** - * @defgroup ClassicCache Cache + * @defgroup RTEMSAPIClassicCache Cache Manager * * @ingroup RTEMSAPIClassic * * @brief The Cache Manager provides functions to perform maintenance - * operations for data and instruction caches. + * 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. + */ + +/* Generated from spec:/rtems/cache/if/coherent-add-area */ + +/** + * @brief Adds a cache coherent memory area to the cache coherent allocator. + * + * @param begin is the begin address of the cache coherent memory area to add. + * + * @param size is the size in bytes of the cache coherent memory area to add. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_UNSATISFIED The requested operation was not successful. + * + * @par Constraints + * @parblock + * 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. + * @endparblock */ +rtems_status_code rtems_cache_coherent_add_area( void *begin, uintptr_t size ); + +/* Generated from spec:/rtems/cache/if/coherent-allocate */ /** - * @brief Returns the data cache line size in bytes. + * @brief Allocates a memory area from cache coherent memory. + * + * @param size is the requested size in bytes of the memory area to allocate. + * + * @param alignment is the requested alignment in bytes of the memory area to + * allocate. If the alignment parameter is not equal to zero, the allocated + * memory area will begin at an address aligned by this value. + * + * @param boundary is the requested boundary in bytes of the memory area to + * allocate. If the boundary parameter is not equal to zero, the allocated + * memory area will comply with a boundary constraint. The boundary value + * specifies the set of addresses which are aligned by the boundary value. + * The interior of the allocated memory area will not contain an element of + * this set. The begin or end address of the area may be a member of the + * set. * - * For multi-level caches this is the maximum of the cache line sizes of all - * levels. + * @retval NULL There is not enough memory available to satisfy the allocation + * request. * - * @retval 0 No data cache is present. - * @retval positive The data cache line size in bytes. + * @return Returns the begin address of the allocated memory. + * + * @par Notes + * @parblock + * A size value of zero will return a unique address which may be freed with + * rtems_cache_coherent_free(). + * + * The memory allocated by the directive may be released with a call to + * rtems_cache_coherent_free(). + * + * By default the C Program Heap allocator is used. In case special memory + * areas must be used, then the BSP or the application should add cache + * coherent memory areas for the allocator via rtems_cache_coherent_add_area(). + * @endparblock + * + * @par Constraints + * @parblock + * 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. + * @endparblock */ -size_t rtems_cache_get_data_line_size( void ); +void *rtems_cache_coherent_allocate( + size_t size, + uintptr_t alignment, + uintptr_t boundary +); + +/* Generated from spec:/rtems/cache/if/coherent-free */ /** - * @brief Returns the instruction cache line size in bytes. + * @brief Frees memory allocated by rtems_cache_coherent_allocate(). + * + * @param ptr is a pointer returned by rtems_cache_coherent_allocate(). + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within device driver initialization + * context. * - * For multi-level caches this is the maximum of the cache line sizes of all - * levels. + * * The directive may be called from within task context. * - * @retval 0 No instruction cache is present. - * @retval positive The instruction cache line size in bytes. + * * The directive may obtain and release the object allocator mutex. This may + * cause the calling task to be preempted. + * @endparblock */ -size_t rtems_cache_get_instruction_line_size( void ); +void rtems_cache_coherent_free( void *ptr ); + +/* Generated from spec:/rtems/cache/if/freeze-data */ /** - * @brief Returns the maximal cache line size of all cache kinds in bytes. + * @brief Freezes the data caches. * - * Returns computed or obtained maximal cache line size of all - * all caches in the system. + * @par Constraints + * @parblock + * The following constraints apply to this directive: * - * @retval 0 No cache is present - * @retval positive The maximal cache line size in bytes. + * * The directive may be called from within any runtime context. + * + * * The directive will not cause the calling task to be preempted. + * @endparblock */ -size_t rtems_cache_get_maximal_line_size( void ); +void rtems_cache_freeze_data( void ); + +/* Generated from spec:/rtems/cache/if/freeze-instruction */ /** - * @brief Returns the data cache size in bytes. + * @brief Freezes the instruction caches. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: * - * @param[in] level The cache level of interest. The cache level zero - * specifies the entire data cache. + * * The directive may be called from within any runtime context. * - * @returns The data cache size in bytes of the specified level. + * * The directive will not cause the calling task to be preempted. + * @endparblock */ -size_t rtems_cache_get_data_cache_size( uint32_t level ); +void rtems_cache_freeze_instruction( void ); + +/* Generated from spec:/rtems/cache/if/unfreeze-data */ /** - * @brief Returns the instruction cache size in bytes. + * @brief Unfreezes the data cache. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: * - * @param[in] level The cache level of interest. The cache level zero - * specifies the entire instruction cache. + * * The directive may be called from within any runtime context. * - * @returns The instruction cache size in bytes of the specified level. + * * The directive will not cause the calling task to be preempted. + * @endparblock */ -size_t rtems_cache_get_instruction_cache_size( uint32_t level ); +void rtems_cache_unfreeze_data( void ); + +/* Generated from spec:/rtems/cache/if/unfreeze-instruction */ + +/** + * @brief Unfreezes the instruction cache. + * + * @par Constraints + * @parblock + * 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. + * @endparblock + */ +void rtems_cache_unfreeze_instruction( void ); + +/* Generated from spec:/rtems/cache/if/flush-multiple-data-lines */ /** - * @brief Flushes multiple data cache lines. + * @ingroup RTEMSAPIClassicCache + * + * @brief Flushes the data cache lines covering the memory area. + * + * @param begin is the begin address of the memory area to flush. + * + * @param size is the size in bytes of the memory area to flush. * - * Dirty cache lines covering the area are transfered to memory. Depending on - * the cache implementation this may mark the lines as invalid. + * Dirty data 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. + * @par Constraints + * @parblock + * 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. + * @endparblock */ -void rtems_cache_flush_multiple_data_lines( const void *addr, size_t size ); +void rtems_cache_flush_multiple_data_lines( const void *begin, size_t size ); + +/* Generated from spec:/rtems/cache/if/invalidate-multiple-data-lines */ /** - * @brief Invalidates multiple data cache lines. + * @ingroup RTEMSAPIClassicCache + * + * @brief Invalidates the data cache lines covering the memory area. + * + * @param begin is the begin address of the memory area to invalidate. + * + * @param size is the size in bytes of the memory area to invalidate. * * The cache lines covering the area are marked as invalid. A later read * access in the area will load the data from memory. * + * @par Notes + * @parblock * 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. + * On some systems, the cache lines may be flushed before they are invalidated. + * @endparblock + * + * @par Constraints + * @parblock + * 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. + * @endparblock */ void rtems_cache_invalidate_multiple_data_lines( - const void *addr, - size_t size + const void *begin, + size_t size ); +/* Generated from spec:/rtems/cache/if/invalidate-multiple-instruction-lines */ + /** - * @brief Invalidates multiple instruction cache lines. + * @ingroup RTEMSAPIClassicCache + * + * @brief Invalidates the instruction cache lines covering the memory area. + * + * @param begin is the begin address of the memory area to invalidate. + * + * @param size is the size in bytes of the memory area to invalidate. * * The cache lines covering the area are marked as invalid. A later * instruction fetch from the area will result in a load from memory. - * In SMP mode, on processors without instruction cache snooping, this - * operation will invalidate the instruction cache lines on all processors. - * It should not be called from interrupt context in such case. * - * @param[in] addr The start address of the area to invalidate. - * @param[in] size The size in bytes of the area to invalidate. + * @par Notes + * In SMP configurations, on processors without instruction cache snooping, + * this operation will invalidate the instruction cache lines on all + * processors. + * + * @par Constraints + * @parblock + * 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. + * @endparblock */ void rtems_cache_invalidate_multiple_instruction_lines( - const void *addr, - size_t size + const void *begin, + size_t size ); +/* Generated from spec:/rtems/cache/if/instruction-sync-after-code-change */ /** - * @brief Ensure necessary synchronization required after code changes + * @ingroup RTEMSAPIClassicCache + * + * @brief Ensures necessary synchronization required after code changes. + * + * @param begin is the begin address of the code area to synchronize. + * + * @param size is the size in bytes of the code area to synchronize. * - * When code is loaded or modified then many Harvard cache equipped - * systems require synchronization of main memory and or updated - * code in data cache to ensure visibility of change in all - * connected CPUs instruction memory view. This operation - * should be used by run time loader for example. + * @par 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. * - * @param[in] addr The start address of the area to invalidate. - * @param[in] size The size in bytes of the area to invalidate. + * @par Constraints + * @parblock + * 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. + * @endparblock */ void rtems_cache_instruction_sync_after_code_change( - const void * code_addr, - size_t n_bytes + const void *begin, + size_t size ); +/* Generated from spec:/rtems/cache/if/get-maximal-line-size */ + /** - * @brief Flushes the entire data cache. + * @ingroup RTEMSAPIClassicCache + * + * @brief Gets the maximal cache line size in bytes of all caches (data, + * instruction, or unified). + * + * @retval 0 There is no cache present. + * + * @return Returns the maximal cache line size in bytes of all caches (data, + * instruction, or unified). * - * @see rtems_cache_flush_multiple_data_lines(). + * @par Constraints + * @parblock + * 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. + * @endparblock */ -void rtems_cache_flush_entire_data( void ); +size_t rtems_cache_get_maximal_line_size( void ); + +/* Generated from spec:/rtems/cache/if/get-data-line-size */ /** - * @brief Invalidates the entire instruction cache. + * @ingroup RTEMSAPIClassicCache * - * @see rtems_cache_invalidate_multiple_instruction_lines(). + * @brief Gets the data cache line size in bytes. + * + * @retval 0 There is no data cache present. + * + * @return Returns the data cache line size in bytes. For multi-level caches + * this is the maximum of the cache line sizes of all levels. + * + * @par Constraints + * @parblock + * 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. + * @endparblock */ -void rtems_cache_invalidate_entire_instruction( void ); +size_t rtems_cache_get_data_line_size( void ); -/** - * This function is responsible for performing a data cache - * invalidate. It invalidates the entire cache. - */ -void rtems_cache_invalidate_entire_data( void ); +/* Generated from spec:/rtems/cache/if/get-instruction-line-size */ /** - * This function freezes the data cache. + * @ingroup RTEMSAPIClassicCache + * + * @brief Gets the instruction cache line size in bytes. + * + * @retval 0 There is no instruction cache present. + * + * @return Returns the instruction cache line size in bytes. For multi-level + * caches this is the maximum of the cache line sizes of all levels. + * + * @par Constraints + * @parblock + * 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. + * @endparblock */ -void rtems_cache_freeze_data( void ); +size_t rtems_cache_get_instruction_line_size( void ); -/** - * This function unfreezes the data cache. - */ -void rtems_cache_unfreeze_data( void ); +/* Generated from spec:/rtems/cache/if/get-data-size */ /** - * This function enables the data cache. + * @ingroup RTEMSAPIClassicCache + * + * @brief Gets the data cache size in bytes for the cache level. + * + * @param level is the requested data cache level. The cache level zero + * specifies the entire data cache. + * + * @retval 0 There is no data cache present at the requested cache level. + * + * @return Returns the data cache size in bytes of the requested cache level. + * + * @par Constraints + * @parblock + * 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. + * @endparblock */ -void rtems_cache_enable_data( void ); +size_t rtems_cache_get_data_cache_size( uint32_t level ); -/** - * This function disables the data cache. - */ -void rtems_cache_disable_data( void ); +/* Generated from spec:/rtems/cache/if/get-instruction-size */ /** - * This function freezes the instruction cache. + * @ingroup RTEMSAPIClassicCache + * + * @brief Gets the instruction cache size in bytes for the cache level. + * + * @param level is the requested instruction cache level. The cache level zero + * specifies the entire instruction cache. + * + * @retval 0 There is no instruction cache present at the requested cache + * level. + * + * @return Returns the instruction cache size in bytes of the requested cache + * level. + * + * @par Constraints + * @parblock + * 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. + * @endparblock */ -void rtems_cache_freeze_instruction( void ); +size_t rtems_cache_get_instruction_cache_size( uint32_t level ); + +/* Generated from spec:/rtems/cache/if/flush-entire-data */ /** - * This function unfreezes the instruction cache. + * @ingroup RTEMSAPIClassicCache + * + * @brief Flushes the entire data cache. + * + * @par Constraints + * @parblock + * 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. + * @endparblock */ -void rtems_cache_unfreeze_instruction( void ); +void rtems_cache_flush_entire_data( void ); + +/* Generated from spec:/rtems/cache/if/invalidate-entire-data */ /** - * This function enables the instruction cache. + * @ingroup RTEMSAPIClassicCache + * + * @brief Invalidates the entire data cache. + * + * @par Constraints + * @parblock + * 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. + * @endparblock */ -void rtems_cache_enable_instruction( void ); +void rtems_cache_invalidate_entire_data( void ); + +/* Generated from spec:/rtems/cache/if/invalidate-entire-instruction */ /** - * This function disables the instruction cache. + * @ingroup RTEMSAPIClassicCache + * + * @brief Invalidates the entire instruction cache. + * + * @par Constraints + * @parblock + * 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. + * @endparblock */ -void rtems_cache_disable_instruction( void ); +void rtems_cache_invalidate_entire_instruction( void ); + +/* Generated from spec:/rtems/cache/if/enable-data */ /** - * This function is used to allocate storage that spans an - * integral number of cache blocks. + * @ingroup RTEMSAPIClassicCache + * + * @brief Enables the data cache. + * + * @par Constraints + * @parblock + * 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. + * @endparblock */ -void *rtems_cache_aligned_malloc ( size_t nbytes ); +void rtems_cache_enable_data( void ); + +/* Generated from spec:/rtems/cache/if/disable-data */ /** - * @brief Allocates a memory area of size @a size bytes from cache coherent - * memory. + * @ingroup RTEMSAPIClassicCache * - * A size value of zero will return a unique address which may be freed with - * rtems_cache_coherent_free(). + * @brief Disables the data cache. * - * The memory allocated by this function can be released with a call to - * rtems_cache_coherent_free(). + * @par Constraints + * @parblock + * The following constraints apply to this directive: * - * By default the C program heap allocator is used. In case special memory - * areas must be used, then the BSP or the application must add cache coherent - * memory areas for the allocator via rtems_cache_coherent_add_area(). + * * The directive may be called from within any runtime context. * - * This function must be called from driver initialization or task context - * only. + * * The directive will not cause the calling task to be preempted. + * @endparblock + */ +void rtems_cache_disable_data( void ); + +/* Generated from spec:/rtems/cache/if/enable-instruction */ + +/** + * @ingroup RTEMSAPIClassicCache + * + * @brief Enables the instruction cache. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: * - * @param[in] alignment If the alignment parameter is not equal to zero, the - * allocated memory area will begin at an address aligned by this value. - * @param[in] boundary If the boundary parameter is not equal to zero, the - * allocated memory area will comply with a boundary constraint. The - * boundary value specifies the set of addresses which are aligned by the - * boundary value. The interior of the allocated memory area will not - * contain an element of this set. The begin or end address of the area may - * be a member of the set. + * * The directive may be called from within any runtime context. * - * @retval NULL If no memory is available or the parameters are inconsistent. - * @retval other A pointer to the begin of the allocated memory area. + * * The directive will not cause the calling task to be preempted. + * @endparblock */ -void *rtems_cache_coherent_allocate( - size_t size, - uintptr_t alignment, - uintptr_t boundary -); +void rtems_cache_enable_instruction( void ); + +/* Generated from spec:/rtems/cache/if/disable-instruction */ /** - * @brief Frees memory allocated by rtems_cache_coherent_allocate(). + * @ingroup RTEMSAPIClassicCache + * + * @brief Disables the instruction cache. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: * - * This function must be called from driver initialization or task context - * only. + * * The directive may be called from within any runtime context. * - * @param[in] ptr A pointer returned by rtems_cache_coherent_allocate(). + * * The directive will not cause the calling task to be preempted. + * @endparblock */ -void rtems_cache_coherent_free( void *ptr ); +void rtems_cache_disable_instruction( void ); + +/* Generated from spec:/rtems/cache/if/aligned-malloc */ /** - * @brief Adds a cache coherent memory area to the cache coherent allocator. + * @ingroup RTEMSAPIClassicCache + * + * @brief Allocates memory from the C Program Heap which begins at a cache line + * boundary. + * + * @param size is the size in bytes of the memory area to allocate. * - * This function must be called from BSP initialization, driver initialization - * or task context only. + * @retval NULL There is not enough memory available to satisfy the allocation + * request. * - * @param[in] area_begin The area begin address. - * @param[in] area_size The area size in bytes. + * @return Returns the begin address of the allocated memory. The begin + * address is on a cache line boundary. * - * @see rtems_cache_coherent_allocate(). + * @par Constraints + * @parblock + * 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. + * @endparblock */ -void rtems_cache_coherent_add_area( - void *area_begin, - uintptr_t area_size -); - -/**@}*/ +void *rtems_cache_aligned_malloc( size_t size ); #ifdef __cplusplus } #endif -#endif -/* end of include file */ +#endif /* _RTEMS_RTEMS_CACHE_H */ |