From f81755ba4efdb33ea4951539d5718a1141f1b511 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Mon, 22 Jun 2020 08:50:02 +0200 Subject: rtems: Generate Change license to BSD-2-Clause according to file histories and documentation re-licensing agreement. Update #3899. Update #3993. --- cpukit/include/rtems/rtems/cache.h | 390 +++++++++++++++++++++---------------- 1 file changed, 219 insertions(+), 171 deletions(-) diff --git a/cpukit/include/rtems/rtems/cache.h b/cpukit/include/rtems/rtems/cache.h index dfcb8f64d1..b1bf596965 100644 --- a/cpukit/include/rtems/rtems/cache.h +++ b/cpukit/include/rtems/rtems/cache.h @@ -1,294 +1,342 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** * @file * - * @ingroup ClassicCache + * @brief This header file defines the Cache Manager API. + */ + +/* + * Copyright (C) 2014, 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 1988, 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: + * + * https://www.rtems.org/bugs.html * - * 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. + * 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 - -#if defined( RTEMS_SMP ) -#include -#endif +#include +#include #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. - * - * 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. - * - * @{ + * operations for data and instruction caches. */ +/* Generated from spec:/rtems/cache/if/aligned-malloc */ + /** - * @brief Returns the data cache line size in bytes. + * @ingroup RTEMSAPIClassicCache * - * For multi-level caches this is the maximum of the cache line sizes of all - * levels. + * @brief % * - * @retval 0 No data cache is present. - * @retval positive The data cache line size in bytes. + * @param nbytes % */ -size_t rtems_cache_get_data_line_size( void ); +void *rtems_cache_aligned_malloc( size_t nbytes ); + +/* Generated from spec:/rtems/cache/if/coherent-add-area */ /** - * @brief Returns the instruction cache line size in bytes. + * @ingroup RTEMSAPIClassicCache * - * For multi-level caches this is the maximum of the cache line sizes of all - * levels. + * @brief % * - * @retval 0 No instruction cache is present. - * @retval positive The instruction cache line size in bytes. + * @param area_begin % + * + * @param area_size % */ -size_t rtems_cache_get_instruction_line_size( void ); +void rtems_cache_coherent_add_area( void *area_begin, uintptr_t area_size ); + +/* Generated from spec:/rtems/cache/if/coherent-allocate */ /** - * @brief Returns the maximal cache line size of all cache kinds in bytes. + * @ingroup RTEMSAPIClassicCache * - * Returns computed or obtained maximal cache line size of all - * all caches in the system. + * @brief % * - * @retval 0 No cache is present - * @retval positive The maximal cache line size in bytes. - */ -size_t rtems_cache_get_maximal_line_size( void ); - -/** - * @brief Returns the data cache size in bytes. + * @param size % * - * @param[in] level The cache level of interest. The cache level zero - * specifies the entire data cache. + * @param alignment % * - * @returns The data cache size in bytes of the specified level. + * @param boundary % */ -size_t rtems_cache_get_data_cache_size( uint32_t level ); +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 size in bytes. + * @ingroup RTEMSAPIClassicCache * - * @param[in] level The cache level of interest. The cache level zero - * specifies the entire instruction cache. + * @brief % * - * @returns The instruction cache size in bytes of the specified level. + * @param ptr % */ -size_t rtems_cache_get_instruction_cache_size( uint32_t level ); +void rtems_cache_coherent_free( void *ptr ); + +/* Generated from spec:/rtems/cache/if/disable-data */ /** - * @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. + * @ingroup RTEMSAPIClassicCache * - * @param[in] addr The start address of the area to flush. - * @param[in] size The size in bytes of the area to flush. + * @brief % */ -void rtems_cache_flush_multiple_data_lines( const void *addr, size_t size ); +void rtems_cache_disable_data( void ); + +/* Generated from spec:/rtems/cache/if/disable-instruction */ /** - * @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. + * @ingroup RTEMSAPIClassicCache * - * 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. + * @brief % */ -void rtems_cache_invalidate_multiple_data_lines( - const void *addr, - size_t size -); +void rtems_cache_disable_instruction( void ); + +/* Generated from spec:/rtems/cache/if/enable-data */ /** - * @brief Invalidates multiple instruction cache lines. + * @ingroup RTEMSAPIClassicCache * - * 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. + * @brief % */ -void rtems_cache_invalidate_multiple_instruction_lines( - const void *addr, - size_t size -); +void rtems_cache_enable_data( void ); +/* Generated from spec:/rtems/cache/if/enable-instruction */ /** - * @brief Ensure necessary synchronization required after code changes - * - * 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. + * @ingroup RTEMSAPIClassicCache * - * @param[in] addr The start address of the area to invalidate. - * @param[in] size The size in bytes of the area to invalidate. + * @brief % */ -void rtems_cache_instruction_sync_after_code_change( - const void * code_addr, - size_t n_bytes -); +void rtems_cache_enable_instruction( void ); + +/* Generated from spec:/rtems/cache/if/flush-entire-data */ /** - * @brief Flushes the entire data cache. + * @ingroup RTEMSAPIClassicCache * - * @see rtems_cache_flush_multiple_data_lines(). + * @brief % */ void rtems_cache_flush_entire_data( void ); +/* Generated from spec:/rtems/cache/if/flush-multiple-data-lines */ + /** - * @brief Invalidates the entire instruction cache. + * @ingroup RTEMSAPIClassicCache + * + * @brief % * - * @see rtems_cache_invalidate_multiple_instruction_lines(). + * @param addr % + * + * @param size % */ -void rtems_cache_invalidate_entire_instruction( void ); +void rtems_cache_flush_multiple_data_lines( const void *addr, size_t size ); + +/* Generated from spec:/rtems/cache/if/freeze-data */ /** - * This function is responsible for performing a data cache - * invalidate. It invalidates the entire cache. + * @ingroup RTEMSAPIClassicCache + * + * @brief % */ -void rtems_cache_invalidate_entire_data( void ); +void rtems_cache_freeze_data( void ); + +/* Generated from spec:/rtems/cache/if/freeze-instruction */ /** - * This function freezes the data cache. + * @ingroup RTEMSAPIClassicCache + * + * @brief % */ -void rtems_cache_freeze_data( void ); +void rtems_cache_freeze_instruction( void ); + +/* Generated from spec:/rtems/cache/if/get-data-line-size */ /** - * This function unfreezes the data cache. + * @ingroup RTEMSAPIClassicCache + * + * @brief % */ -void rtems_cache_unfreeze_data( void ); +size_t rtems_cache_get_data_line_size( void ); + +/* Generated from spec:/rtems/cache/if/get-data-size */ /** - * This function enables the data cache. + * @ingroup RTEMSAPIClassicCache + * + * @brief % + * + * @param level % */ -void rtems_cache_enable_data( void ); +size_t rtems_cache_get_data_cache_size( uint32_t level ); + +/* Generated from spec:/rtems/cache/if/get-instruction-line-size */ /** - * This function disables the data cache. + * @ingroup RTEMSAPIClassicCache + * + * @brief % */ -void rtems_cache_disable_data( void ); +size_t rtems_cache_get_instruction_line_size( void ); + +/* Generated from spec:/rtems/cache/if/get-instruction-size */ /** - * This function freezes the instruction cache. + * @ingroup RTEMSAPIClassicCache + * + * @brief % + * + * @param level % */ -void rtems_cache_freeze_instruction( void ); +size_t rtems_cache_get_instruction_cache_size( uint32_t level ); + +/* Generated from spec:/rtems/cache/if/get-maximal-line-size */ /** - * This function unfreezes the instruction cache. + * @ingroup RTEMSAPIClassicCache + * + * @brief % */ -void rtems_cache_unfreeze_instruction( void ); +size_t rtems_cache_get_maximal_line_size( void ); + +/* Generated from spec:/rtems/cache/if/instruction-sync-after-code-change */ /** - * This function enables the instruction cache. + * @ingroup RTEMSAPIClassicCache + * + * @brief % + * + * @param code_addr % + * + * @param n_bytes % */ -void rtems_cache_enable_instruction( void ); +void rtems_cache_instruction_sync_after_code_change( + const void *code_addr, + size_t n_bytes +); + +/* Generated from spec:/rtems/cache/if/invalidate-entire-data */ /** - * This function disables the instruction cache. + * @ingroup RTEMSAPIClassicCache + * + * @brief % */ -void rtems_cache_disable_instruction( void ); +void rtems_cache_invalidate_entire_data( void ); + +/* Generated from spec:/rtems/cache/if/invalidate-entire-instruction */ /** - * This function is used to allocate storage that spans an - * integral number of cache blocks. + * @ingroup RTEMSAPIClassicCache + * + * @brief % */ -void *rtems_cache_aligned_malloc ( size_t nbytes ); +void rtems_cache_invalidate_entire_instruction( void ); + +/* Generated from spec:/rtems/cache/if/invalidate-multiple-data-lines */ /** - * @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 % * - * The memory allocated by this function can be released with a call to - * rtems_cache_coherent_free(). + * @param addr % * - * 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(). + * @param size % + */ +void rtems_cache_invalidate_multiple_data_lines( + const void *addr, + size_t size +); + +/* Generated from spec:/rtems/cache/if/invalidate-multiple-instruction-lines */ + +/** + * @ingroup RTEMSAPIClassicCache * - * This function must be called from driver initialization or task context - * only. + * @brief % * - * @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. + * @param addr % * - * @retval NULL If no memory is available or the parameters are inconsistent. - * @retval other A pointer to the begin of the allocated memory area. + * @param size % */ -void *rtems_cache_coherent_allocate( - size_t size, - uintptr_t alignment, - uintptr_t boundary +void rtems_cache_invalidate_multiple_instruction_lines( + const void *addr, + size_t size ); +/* Generated from spec:/rtems/cache/if/unfreeze-data */ + /** - * @brief Frees memory allocated by rtems_cache_coherent_allocate(). - * - * This function must be called from driver initialization or task context - * only. + * @ingroup RTEMSAPIClassicCache * - * @param[in] ptr A pointer returned by rtems_cache_coherent_allocate(). + * @brief % */ -void rtems_cache_coherent_free( void *ptr ); +void rtems_cache_unfreeze_data( void ); + +/* Generated from spec:/rtems/cache/if/unfreeze-instruction */ /** - * @brief Adds a cache coherent memory area to the cache coherent allocator. - * - * This function must be called from BSP initialization, driver initialization - * or task context only. + * @ingroup RTEMSAPIClassicCache * - * @param[in] area_begin The area begin address. - * @param[in] area_size The area size in bytes. - * - * @see rtems_cache_coherent_allocate(). + * @brief % */ -void rtems_cache_coherent_add_area( - void *area_begin, - uintptr_t area_size -); - -/**@}*/ +void rtems_cache_unfreeze_instruction( void ); #ifdef __cplusplus } #endif -#endif -/* end of include file */ +#endif /* _RTEMS_RTEMS_CACHE_H */ -- cgit v1.2.3