Directives

22.2. Directives#

This section details the directives of the Cache Manager. A subsection is dedicated to each of this manager’s directives and lists the calling sequence, parameters, description, return values, and notes of the directive.

22.2.1. rtems_cache_flush_multiple_data_lines()#

Flushes the data cache lines covering the memory area.

CALLING SEQUENCE:

void rtems_cache_flush_multiple_data_lines( const void *begin, size_t size );

PARAMETERS:

begin

This parameter is the begin address of the memory area to flush.

size

This parameter is the size in bytes of the memory area to flush.

DESCRIPTION:

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.

22.2.2. rtems_cache_invalidate_multiple_data_lines()#

Invalidates the data cache lines covering the memory area.

CALLING SEQUENCE:

void rtems_cache_invalidate_multiple_data_lines(
  const void *begin,
  size_t      size
);

PARAMETERS:

begin

This parameter is the begin address of the memory area to invalidate.

size

This parameter is the size in bytes of the memory area to invalidate.

DESCRIPTION:

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.

22.2.3. rtems_cache_invalidate_multiple_instruction_lines()#

Invalidates the instruction cache lines covering the memory area.

CALLING SEQUENCE:

void rtems_cache_invalidate_multiple_instruction_lines(
  const void *begin,
  size_t      size
);

PARAMETERS:

begin

This parameter is the begin address of the memory area to invalidate.

size

This parameter is the size in bytes of the memory area to invalidate.

DESCRIPTION:

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.

22.2.4. rtems_cache_instruction_sync_after_code_change()#

Ensures necessary synchronization required after code changes.

CALLING SEQUENCE:

void rtems_cache_instruction_sync_after_code_change(
  const void *begin,
  size_t      size
);

PARAMETERS:

begin

This parameter is the begin address of the code area to synchronize.

size

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

22.2.5. rtems_cache_get_maximal_line_size()#

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

CALLING SEQUENCE:

size_t rtems_cache_get_maximal_line_size( void );

RETURN VALUES:

0

There is no cache present.

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.

22.2.6. rtems_cache_get_data_line_size()#

Gets the data cache line size in bytes.

CALLING SEQUENCE:

size_t rtems_cache_get_data_line_size( void );

RETURN VALUES:

0

There is no data cache present.

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.

22.2.7. rtems_cache_get_instruction_line_size()#

Gets the instruction cache line size in bytes.

CALLING SEQUENCE:

size_t rtems_cache_get_instruction_line_size( void );

RETURN VALUES:

0

There is no instruction cache present.

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.

22.2.8. rtems_cache_get_data_cache_size()#

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

CALLING SEQUENCE:

size_t rtems_cache_get_data_cache_size( uint32_t level );

PARAMETERS:

level

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

22.2.9. rtems_cache_get_instruction_cache_size()#

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

CALLING SEQUENCE:

size_t rtems_cache_get_instruction_cache_size( uint32_t level );

PARAMETERS:

level

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

22.2.10. rtems_cache_flush_entire_data()#

Flushes the entire data cache.

CALLING SEQUENCE:

void rtems_cache_flush_entire_data( void );

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.

22.2.11. rtems_cache_invalidate_entire_data()#

Invalidates the entire data cache.

CALLING SEQUENCE:

void rtems_cache_invalidate_entire_data( void );

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.

22.2.12. rtems_cache_invalidate_entire_instruction()#

Invalidates the entire instruction cache.

CALLING SEQUENCE:

void rtems_cache_invalidate_entire_instruction( void );

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.

22.2.13. rtems_cache_enable_data()#

Enables the data cache.

CALLING SEQUENCE:

void rtems_cache_enable_data( void );

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.

22.2.14. rtems_cache_disable_data()#

Disables the data cache.

CALLING SEQUENCE:

void rtems_cache_disable_data( void );

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.

22.2.15. rtems_cache_enable_instruction()#

Enables the instruction cache.

CALLING SEQUENCE:

void rtems_cache_enable_instruction( void );

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.

22.2.16. rtems_cache_disable_instruction()#

Disables the instruction cache.

CALLING SEQUENCE:

void rtems_cache_disable_instruction( void );

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.

22.2.17. rtems_cache_aligned_malloc()#

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

CALLING SEQUENCE:

void *rtems_cache_aligned_malloc( size_t size );

PARAMETERS:

size

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