Cache Manager

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

Functions
void	rtems_cache_flush_multiple_data_lines (const void *begin, size_t size)
	Flushes the data cache lines covering the memory area.
void	rtems_cache_invalidate_multiple_data_lines (const void *begin, size_t size)
	Invalidates the data cache lines covering the memory area.
void	rtems_cache_invalidate_multiple_instruction_lines (const void *begin, size_t size)
	Invalidates the instruction cache lines covering the memory area.
void	rtems_cache_instruction_sync_after_code_change (const void *begin, size_t size)
	Ensures necessary synchronization required after code changes.
size_t	rtems_cache_get_maximal_line_size (void)
	Gets the maximal cache line size in bytes of all caches (data, instruction, or unified).
size_t	rtems_cache_get_data_line_size (void)
	Gets the data cache line size in bytes.
size_t	rtems_cache_get_instruction_line_size (void)
	Gets the instruction cache line size in bytes.
size_t	rtems_cache_get_data_cache_size (uint32_t level)
	Gets the data cache size in bytes for the cache level.
size_t	rtems_cache_get_instruction_cache_size (uint32_t level)
	Gets the instruction cache size in bytes for the cache level.
void	rtems_cache_flush_entire_data (void)
	Flushes the entire data cache.
void	rtems_cache_invalidate_entire_data (void)
	Invalidates the entire data cache.
void	rtems_cache_invalidate_entire_instruction (void)
	Invalidates the entire instruction cache.
void	rtems_cache_enable_data (void)
	Enables the data cache.
void	rtems_cache_disable_data (void)
	Disables the data cache.
void	rtems_cache_enable_instruction (void)
	Enables the instruction cache.
void	rtems_cache_disable_instruction (void)
	Disables the instruction cache.
void *	rtems_cache_aligned_malloc (size_t size)
	Allocates memory from the C Program Heap which begins at a cache line boundary.

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

size

)

Allocates memory from the C Program Heap which begins at a cache line boundary.

Parameters

size	is the size in bytes of the memory area to allocate.

Return values

NULL	There is not enough memory available to satisfy the allocation request.

Returns

Returns the begin address of the allocated memory. The begin address is on a cache line boundary.

Constraints

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.

rtems_cache_disable_data()

void rtems_cache_disable_data

(

void

)

Disables the data cache.

Notes

On some targets or configurations, calling this directive may cause a fatal error with a fatal source of INTERNAL_ERROR_CORE and fatal code of INTERNAL_ERROR_CANNOT_DISABLE_DATA_CACHE. The data cache may be necessary to provide atomic operations. In SMP configurations, the data cache may be required to ensure data coherency. See the BSP documentation in the RTEMS User Manual for more information.

Constraints

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.

rtems_cache_disable_instruction()

void rtems_cache_disable_instruction

(

void

)

Disables the instruction cache.

Constraints

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.

rtems_cache_enable_data()

void rtems_cache_enable_data

(

void

)

Enables the data cache.

Constraints

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.

rtems_cache_enable_instruction()

void rtems_cache_enable_instruction

(

void

)

Enables the instruction cache.

Constraints

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.

rtems_cache_flush_entire_data()

void rtems_cache_flush_entire_data

(

void

)

Flushes the entire data cache.

Constraints

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.

rtems_cache_flush_multiple_data_lines()

void rtems_cache_flush_multiple_data_lines	(	const void *	begin,
		size_t	size
	)

Flushes the data cache lines covering the memory area.

Parameters

begin	is the begin address of the memory area to flush.
size	is the size in bytes of the memory area to flush.

Dirty data cache lines covering the area are transfered to memory. Depending on the cache implementation this may mark the lines as invalid.

Constraints

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.

rtems_cache_get_data_cache_size()

size_t rtems_cache_get_data_cache_size

(

uint32_t

level

)

Gets the data cache size in bytes for the cache level.

Parameters

level

is the requested data cache level. The cache level zero specifies the entire data cache.

Return values

0	There is no data cache present at the requested cache level.

Returns

Returns the data cache size in bytes of the requested cache level.

Constraints

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.

rtems_cache_get_data_line_size()

size_t rtems_cache_get_data_line_size

(

void

)

Gets the data cache line size in bytes.

Return values

0	There is no data cache present.

Returns

Returns the data cache line size in bytes. For multi-level caches this is the maximum of the cache line sizes of all levels.

Constraints

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.

rtems_cache_get_instruction_cache_size()

size_t rtems_cache_get_instruction_cache_size

(

uint32_t

level

)

Gets the instruction cache size in bytes for the cache level.

Parameters

level

is the requested instruction cache level. The cache level zero specifies the entire instruction cache.

Return values

0	There is no instruction cache present at the requested cache level.

Returns

Returns the instruction cache size in bytes of the requested cache level.

Constraints

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.

rtems_cache_get_instruction_line_size()

size_t rtems_cache_get_instruction_line_size

(

void

)

Gets the instruction cache line size in bytes.

Return values

0	There is no instruction cache present.

Returns

Returns the instruction cache line size in bytes. For multi-level caches this is the maximum of the cache line sizes of all levels.

Constraints

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.

rtems_cache_get_maximal_line_size()

size_t rtems_cache_get_maximal_line_size

(

void

)

Gets the maximal cache line size in bytes of all caches (data, instruction, or unified).

Return values

0	There is no cache present.

Returns

Returns the maximal cache line size in bytes of all caches (data, instruction, or unified).

Constraints

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.

rtems_cache_instruction_sync_after_code_change()

void rtems_cache_instruction_sync_after_code_change	(	const void *	begin,
		size_t	size
	)

Ensures necessary synchronization required after code changes.

Parameters

begin	is the begin address of the code area to synchronize.
size	is the size in bytes of the code area to synchronize.

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.

Constraints

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.

rtems_cache_invalidate_entire_data()

void rtems_cache_invalidate_entire_data

(

void

)

Invalidates the entire data cache.

Constraints

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.

rtems_cache_invalidate_entire_instruction()

void rtems_cache_invalidate_entire_instruction

(

void

)

Invalidates the entire instruction cache.

Constraints

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.

rtems_cache_invalidate_multiple_data_lines()

void rtems_cache_invalidate_multiple_data_lines	(	const void *	begin,
		size_t	size
	)

Invalidates the data cache lines covering the memory area.

Parameters

begin	is the begin address of the memory area to invalidate.
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.

Notes

In case the area is not aligned on cache line boundaries, then this operation may destroy unrelated data.

On some systems, the cache lines may be flushed before they are invalidated.

Constraints

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.

rtems_cache_invalidate_multiple_instruction_lines()

void rtems_cache_invalidate_multiple_instruction_lines	(	const void *	begin,
		size_t	size
	)

Invalidates the instruction cache lines covering the memory area.

Parameters

begin	is the begin address of the memory area to invalidate.
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.

Notes

In SMP configurations, on processors without instruction cache snooping, this operation will invalidate the instruction cache lines on all processors.

Constraints

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.