RTEMS  5.0.0
Files | Functions
Cache

The Cache Manager provides functions to perform maintenance operations for data and instruction caches. More...

Files

file  cache.h
 
file  cachecoherentalloc.c
 

Functions

size_t rtems_cache_get_data_line_size (void)
 Returns the data cache line size in bytes. More...
 
size_t rtems_cache_get_instruction_line_size (void)
 Returns the instruction cache line size in bytes. More...
 
size_t rtems_cache_get_maximal_line_size (void)
 Returns the maximal cache line size of all cache kinds in bytes. More...
 
size_t rtems_cache_get_data_cache_size (uint32_t level)
 Returns the data cache size in bytes. More...
 
size_t rtems_cache_get_instruction_cache_size (uint32_t level)
 Returns the instruction cache size in bytes. More...
 
void rtems_cache_flush_multiple_data_lines (const void *addr, size_t size)
 Flushes multiple data cache lines. More...
 
void rtems_cache_invalidate_multiple_data_lines (const void *addr, size_t size)
 Invalidates multiple data cache lines. More...
 
void rtems_cache_invalidate_multiple_instruction_lines (const void *addr, size_t size)
 Invalidates multiple instruction cache lines. More...
 
void rtems_cache_instruction_sync_after_code_change (const void *code_addr, size_t n_bytes)
 Ensure necessary synchronization required after code changes. More...
 
void rtems_cache_flush_entire_data (void)
 Flushes the entire data cache. More...
 
void rtems_cache_invalidate_entire_instruction (void)
 Invalidates the entire instruction cache. More...
 
void rtems_cache_invalidate_entire_data (void)
 
void rtems_cache_freeze_data (void)
 
void rtems_cache_unfreeze_data (void)
 
void rtems_cache_enable_data (void)
 
void rtems_cache_disable_data (void)
 
void rtems_cache_freeze_instruction (void)
 
void rtems_cache_unfreeze_instruction (void)
 
void rtems_cache_enable_instruction (void)
 
void rtems_cache_disable_instruction (void)
 
void * rtems_cache_aligned_malloc (size_t nbytes)
 
void * rtems_cache_coherent_allocate (size_t size, uintptr_t alignment, uintptr_t boundary)
 Allocates a memory area of size size bytes from cache coherent memory. More...
 
void rtems_cache_coherent_free (void *ptr)
 Frees memory allocated by rtems_cache_coherent_allocate(). More...
 
void rtems_cache_coherent_add_area (void *area_begin, uintptr_t area_size)
 Adds a cache coherent memory area to the cache coherent allocator. More...
 

Detailed Description

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.

Function Documentation

◆ rtems_cache_aligned_malloc()

void* rtems_cache_aligned_malloc ( size_t  nbytes)

This function is used to allocate storage that spans an integral number of cache blocks.

◆ rtems_cache_coherent_add_area()

void rtems_cache_coherent_add_area ( void *  area_begin,
uintptr_t  area_size 
)

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.

Parameters
[in]area_beginThe area begin address.
[in]area_sizeThe area size in bytes.
See also
rtems_cache_coherent_allocate().

◆ rtems_cache_coherent_allocate()

void* rtems_cache_coherent_allocate ( size_t  size,
uintptr_t  alignment,
uintptr_t  boundary 
)

Allocates a memory area of size size bytes from cache coherent memory.

A size value of zero will return a unique address which may be freed with rtems_cache_coherent_free().

The memory allocated by this function can 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 must add cache coherent memory areas for the allocator via rtems_cache_coherent_add_area().

This function must be called from driver initialization or task context only.

Parameters
[in]alignmentIf the alignment parameter is not equal to zero, the allocated memory area will begin at an address aligned by this value.
[in]boundaryIf 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.
Return values
NULLIf no memory is available or the parameters are inconsistent.
otherA pointer to the begin of the allocated memory area.

◆ rtems_cache_coherent_free()

void rtems_cache_coherent_free ( void *  ptr)

Frees memory allocated by rtems_cache_coherent_allocate().

This function must be called from driver initialization or task context only.

Parameters
[in]ptrA pointer returned by rtems_cache_coherent_allocate().

◆ rtems_cache_disable_data()

void rtems_cache_disable_data ( void  )

This function disables the data cache.

◆ rtems_cache_disable_instruction()

void rtems_cache_disable_instruction ( void  )

This function disables the instruction cache.

◆ rtems_cache_enable_data()

void rtems_cache_enable_data ( void  )

This function enables the data cache.

◆ rtems_cache_enable_instruction()

void rtems_cache_enable_instruction ( void  )

This function enables the instruction cache.

◆ rtems_cache_flush_entire_data()

void rtems_cache_flush_entire_data ( void  )

Flushes the entire data cache.

See also
rtems_cache_flush_multiple_data_lines().

◆ rtems_cache_flush_multiple_data_lines()

void rtems_cache_flush_multiple_data_lines ( const void *  addr,
size_t  size 
)

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.

Parameters
[in]addrThe start address of the area to flush.
[in]sizeThe size in bytes of the area to flush.

◆ rtems_cache_freeze_data()

void rtems_cache_freeze_data ( void  )

This function freezes the data cache.

◆ rtems_cache_freeze_instruction()

void rtems_cache_freeze_instruction ( void  )

This function freezes the instruction cache.

◆ rtems_cache_get_data_cache_size()

size_t rtems_cache_get_data_cache_size ( uint32_t  level)

Returns the data cache size in bytes.

Parameters
[in]levelThe cache level of interest. The cache level zero specifies the entire data cache.
Returns
The data cache size in bytes of the specified level.

◆ rtems_cache_get_data_line_size()

size_t rtems_cache_get_data_line_size ( void  )

Returns the data cache line size in bytes.

For multi-level caches this is the maximum of the cache line sizes of all levels.

Return values
0No data cache is present.
positiveThe data cache line size in bytes.

◆ rtems_cache_get_instruction_cache_size()

size_t rtems_cache_get_instruction_cache_size ( uint32_t  level)

Returns the instruction cache size in bytes.

Parameters
[in]levelThe cache level of interest. The cache level zero specifies the entire instruction cache.
Returns
The instruction cache size in bytes of the specified level.

◆ rtems_cache_get_instruction_line_size()

size_t rtems_cache_get_instruction_line_size ( void  )

Returns the instruction cache line size in bytes.

For multi-level caches this is the maximum of the cache line sizes of all levels.

Return values
0No instruction cache is present.
positiveThe instruction cache line size in bytes.

◆ rtems_cache_get_maximal_line_size()

size_t rtems_cache_get_maximal_line_size ( void  )

Returns the maximal cache line size of all cache kinds in bytes.

Returns computed or obtained maximal cache line size of all all caches in the system.

Return values
0No cache is present
positiveThe maximal cache line size in bytes.

◆ rtems_cache_instruction_sync_after_code_change()

void rtems_cache_instruction_sync_after_code_change ( const void *  code_addr,
size_t  n_bytes 
)

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.

Parameters
[in]addrThe start address of the area to invalidate.
[in]sizeThe size in bytes of the area to invalidate.

◆ rtems_cache_invalidate_entire_data()

void rtems_cache_invalidate_entire_data ( void  )

This function is responsible for performing a data cache invalidate. It invalidates the entire cache.

◆ rtems_cache_invalidate_entire_instruction()

void rtems_cache_invalidate_entire_instruction ( void  )

Invalidates the entire instruction cache.

See also
rtems_cache_invalidate_multiple_instruction_lines().

◆ rtems_cache_invalidate_multiple_data_lines()

void rtems_cache_invalidate_multiple_data_lines ( const void *  addr,
size_t  size 
)

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.

Parameters
[in]addrThe start address of the area to invalidate.
[in]sizeThe size in bytes of the area to invalidate.

◆ rtems_cache_invalidate_multiple_instruction_lines()

void rtems_cache_invalidate_multiple_instruction_lines ( const void *  addr,
size_t  size 
)

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. 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.

Parameters
[in]addrThe start address of the area to invalidate.
[in]sizeThe size in bytes of the area to invalidate.

◆ rtems_cache_unfreeze_data()

void rtems_cache_unfreeze_data ( void  )

This function unfreezes the data cache.

◆ rtems_cache_unfreeze_instruction()

void rtems_cache_unfreeze_instruction ( void  )

This function unfreezes the instruction cache.