RTEMS: Cache

| RTEMS 5.4-rc2

Loading...
Searching...
No Matches
Files | Functions
Cache
API » Classic

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.
size_t | rtems_cache_get_instruction_line_size (void)
| Returns the instruction cache line size in bytes.
size_t | rtems_cache_get_maximal_line_size (void)
| Returns the maximal cache line size of all cache kinds in bytes.
size_t | rtems_cache_get_data_cache_size (uint32_t level)
| Returns the data cache size in bytes.
size_t | rtems_cache_get_instruction_cache_size (uint32_t level)
| Returns the instruction cache size in bytes.
void | rtems_cache_flush_multiple_data_lines (const void *addr, size_t size)
| Flushes multiple data cache lines.
void | rtems_cache_invalidate_multiple_data_lines (const void *addr, size_t size)
| Invalidates multiple data cache lines.
void | rtems_cache_invalidate_multiple_instruction_lines (const void *addr, size_t size)
| Invalidates multiple instruction cache lines.
void | rtems_cache_instruction_sync_after_code_change (const void *code_addr, size_t n_bytes)
| Ensure necessary synchronization required after code changes.
void | rtems_cache_flush_entire_data (void)
| Flushes the entire data cache.
void | rtems_cache_invalidate_entire_instruction (void)
| Invalidates the entire instruction cache.
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.
void | rtems_cache_coherent_free (void *ptr)
| Frees memory allocated by rtems_cache_coherent_allocate().
void | rtems_cache_coherent_add_area (void *area_begin, uintptr_t area_size)
| Adds a cache coherent memory area to the cache coherent allocator.

## 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_begin | The area begin address.
  [in] | area_size | The 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] | alignment | If the alignment parameter is not equal to zero, the allocated memory area will begin at an address aligned by this value.
  [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.

Return values

  NULL | If no memory is available or the parameters are inconsistent.
  other | A 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] | ptr | A 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] | addr | The start address of the area to flush.
  [in] | size | The 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] | level | The 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

  0 | No data cache is present.
  positive | The 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] | level | The 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

  0 | No instruction cache is present.
  positive | The 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

  0 | No cache is present
  positive | The 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] | addr | The start address of the area to invalidate.
  [in] | size | The 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] | addr | The start address of the area to invalidate.
  [in] | size | The 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] | addr | The start address of the area to invalidate.
  [in] | size | The 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.