[PATCH] rtems: Generate <rtems/rtems/cache.h>
Gedare Bloom
gedare at rtems.org
Thu Sep 9 15:22:14 UTC 2021
This looks ok, but I am reminded that maybe the API for cache coherent
allocations is not well-defined in case the BSP doesn't support
coherent allocation. That's a separate, but related concern.
On Wed, Sep 8, 2021 at 11:58 AM Sebastian Huber
<sebastian.huber at embedded-brains.de> wrote:
>
> 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 | 688 ++++++++++++++++++++++-------
> 1 file changed, 532 insertions(+), 156 deletions(-)
>
> diff --git a/cpukit/include/rtems/rtems/cache.h b/cpukit/include/rtems/rtems/cache.h
> index dfcb8f64d1..843d1ef99a 100644
> --- a/cpukit/include/rtems/rtems/cache.h
> +++ b/cpukit/include/rtems/rtems/cache.h
> @@ -1,294 +1,670 @@
> +/* SPDX-License-Identifier: BSD-2-Clause */
> +
> /**
> * @file
> *
> - * @ingroup ClassicCache
> + * @brief This header file defines the Cache Manager API.
> + */
> +
> +/*
> + * 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)
> + *
> + * 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 <rtems/score/basedefs.h>
> -
> -#if defined( RTEMS_SMP )
> -#include <sys/cpuset.h>
> -#endif
> +#include <stddef.h>
> +#include <stdint.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/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 Allocates memory from the C Program Heap which begins at a cache line
> + * boundary.
> *
> - * @retval 0 No data cache is present.
> - * @retval positive The data cache line size in bytes.
> - */
> -size_t rtems_cache_get_data_line_size( void );
> -
> -/**
> - * @brief Returns the instruction cache line size in bytes.
> + * @param size is the size in bytes of the memory area to allocate.
> + *
> + * @retval NULL There is not enough memory available to satisfy the allocation
> + * request.
> + *
> + * @return Returns the begin address of the allocated memory. The begin
> + * address is on a cache line boundary.
> + *
> + * @par Constraints
> + * @parblock
> + * The following constraints apply to this directive:
> *
> - * For multi-level caches this is the maximum of the cache line sizes of all
> - * levels.
> + * * The directive may be called from within device driver initialization
> + * context.
> *
> - * @retval 0 No instruction cache is present.
> - * @retval positive The instruction cache line size in bytes.
> + * * 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_instruction_line_size( void );
> +void *rtems_cache_aligned_malloc( size_t size );
> +
> +/* Generated from spec:/rtems/cache/if/coherent-add-area */
>
> /**
> - * @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 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.
> + *
> + * @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 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_maximal_line_size( void );
> +void rtems_cache_coherent_add_area( void *begin, uintptr_t size );
> +
> +/* Generated from spec:/rtems/cache/if/coherent-allocate */
>
> /**
> - * @brief Returns the data cache size in bytes.
> + * @ingroup RTEMSAPIClassicCache
> + *
> + * @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.
> + *
> + * @retval NULL There is not enough memory available to satisfy the allocation
> + * request.
> + *
> + * @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:
> *
> - * @param[in] level The cache level of interest. The cache level zero
> - * specifies the entire data cache.
> + * * The directive may be called from within device driver initialization
> + * context.
> *
> - * @returns The data cache size in bytes of the specified level.
> + * * 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_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 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.
> *
> - * @returns The instruction cache size in bytes of the specified level.
> + * * 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_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.
> + * @ingroup RTEMSAPIClassicCache
> + *
> + * @brief Disables the data cache.
> *
> - * Dirty cache lines covering the area are transfered to memory. Depending on
> - * the cache implementation this may mark the lines as invalid.
> + * @par Constraints
> + * @parblock
> + * The following constraints apply to this directive:
> *
> - * @param[in] addr The start address of the area to flush.
> - * @param[in] size The size in bytes of the area to flush.
> + * * 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_disable_data( void );
> +
> +/* Generated from spec:/rtems/cache/if/disable-instruction */
>
> /**
> - * @brief Invalidates multiple data cache lines.
> + * @ingroup RTEMSAPIClassicCache
> *
> - * The cache lines covering the area are marked as invalid. A later read
> - * access in the area will load the data from memory.
> + * @brief Disables the instruction cache.
> *
> - * In case the area is not aligned on cache line boundaries, then this
> - * operation may destroy unrelated data.
> + * @par Constraints
> + * @parblock
> + * The following constraints apply to this directive:
> *
> - * @param[in] addr The start address of the area to invalidate.
> - * @param[in] size The size in bytes of the area to invalidate.
> + * * 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
> -);
> +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.
> + * @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.
> *
> - * @param[in] addr The start address of the area to invalidate.
> - * @param[in] size The size in bytes of the area to invalidate.
> + * * 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
> -);
> +void rtems_cache_enable_data( void );
>
> +/* Generated from spec:/rtems/cache/if/enable-instruction */
>
> /**
> - * @brief Ensure necessary synchronization required after code changes
> + * @ingroup RTEMSAPIClassicCache
> *
> - * 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.
> + * @brief Enables the instruction cache.
> *
> - * @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
> -);
> +void rtems_cache_enable_instruction( void );
> +
> +/* Generated from spec:/rtems/cache/if/flush-entire-data */
>
> /**
> + * @ingroup RTEMSAPIClassicCache
> + *
> * @brief Flushes the entire data cache.
> *
> - * @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 );
>
> +/* Generated from spec:/rtems/cache/if/flush-multiple-data-lines */
> +
> /**
> - * @brief Invalidates the entire instruction cache.
> + * @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.
> *
> - * @see rtems_cache_invalidate_multiple_instruction_lines().
> + * Dirty data cache lines covering the area are transfered to memory.
> + * Depending on the cache implementation this may mark the lines as invalid.
> + *
> + * @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 );
> +void rtems_cache_flush_multiple_data_lines( const void *begin, 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 Freezes the data caches.
> + *
> + * @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_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 Freezes the instruction caches.
> + *
> + * @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 );
> +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 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_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 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 );
> +
> +/* Generated from spec:/rtems/cache/if/get-instruction-line-size */
>
> /**
> - * This function disables 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_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 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/get-maximal-line-size */
>
> /**
> - * This function unfreezes the instruction 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).
> + *
> + * @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 );
> +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 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.
> + *
> + * @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.
> + *
> + * @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_instruction_sync_after_code_change(
> + const void *begin,
> + size_t size
> +);
> +
> +/* Generated from spec:/rtems/cache/if/invalidate-entire-data */
>
> /**
> - * This function disables 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_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 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_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 Invalidates the data cache lines covering the memory area.
> *
> - * The memory allocated by this function can be released with a call to
> - * rtems_cache_coherent_free().
> + * @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.
> *
> - * 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().
> + * @par Notes
> + * @parblock
> + * In case the area is not aligned on cache line boundaries, then this
> + * operation may destroy unrelated data.
> *
> - * This function must be called from driver initialization or task context
> - * only.
> + * On some systems, the cache lines may be flushed before they are invalidated.
> + * @endparblock
> *
> - * @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.
> + * @par Constraints
> + * @parblock
> + * The following constraints apply to this directive:
> *
> - * @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 may be called from within any runtime context.
> + *
> + * * 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_invalidate_multiple_data_lines(
> + const void *begin,
> + size_t size
> );
>
> +/* Generated from spec:/rtems/cache/if/invalidate-multiple-instruction-lines */
> +
> /**
> - * @brief Frees memory allocated by rtems_cache_coherent_allocate().
> + * @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.
> + *
> + * @par Notes
> + * In SMP configurations, on processors without instruction cache snooping,
> + * this operation will invalidate the instruction cache lines on all
> + * processors.
> *
> - * This function must be called from driver initialization or task context
> - * only.
> + * @par Constraints
> + * @parblock
> + * The following constraints apply to this directive:
> *
> - * @param[in] ptr A pointer returned by rtems_cache_coherent_allocate().
> + * * 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_coherent_free( void *ptr );
> +void rtems_cache_invalidate_multiple_instruction_lines(
> + const void *begin,
> + size_t size
> +);
> +
> +/* Generated from spec:/rtems/cache/if/unfreeze-data */
>
> /**
> - * @brief Adds a cache coherent memory area to the cache coherent allocator.
> + * @ingroup RTEMSAPIClassicCache
> + *
> + * @brief Unfreezes the data cache.
> *
> - * This function must be called from BSP initialization, driver initialization
> - * or task context only.
> + * @par Constraints
> + * @parblock
> + * The following constraints apply to this directive:
> *
> - * @param[in] area_begin The area begin address.
> - * @param[in] area_size The area size in bytes.
> + * * The directive may be called from within any runtime context.
> *
> - * @see rtems_cache_coherent_allocate().
> + * * The directive will not cause the calling task to be preempted.
> + * @endparblock
> */
> -void rtems_cache_coherent_add_area(
> - void *area_begin,
> - uintptr_t area_size
> -);
> +void rtems_cache_unfreeze_data( void );
>
> -/**@}*/
> +/* Generated from spec:/rtems/cache/if/unfreeze-instruction */
> +
> +/**
> + * @ingroup RTEMSAPIClassicCache
> + *
> + * @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 );
>
> #ifdef __cplusplus
> }
> #endif
>
> -#endif
> -/* end of include file */
> +#endif /* _RTEMS_RTEMS_CACHE_H */
> --
> 2.31.1
>
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel
More information about the devel
mailing list