Cache

Instruction and data cache maintenance. More...

Macros
#define	DCACHE_LINE_SIZE_MAX   32U
	Largest data cache line of the supported cores, in bytes.
#define	DCACHE_ROUND_UP(size)   (((size) + DCACHE_LINE_SIZE_MAX - 1U) & ~(DCACHE_LINE_SIZE_MAX - 1U))
	size rounded up to whole DCACHE_LINE_SIZE_MAX lines.

Functions
void	icache_enable (void)
	Enable the instruction cache, invalidating it first.
void	icache_disable (void)
	Disable the instruction cache, invalidating it afterwards.
bool	icache_is_enabled (void)
	Check whether the instruction cache is enabled.
uint32_t	icache_line_size (void)
	Get the instruction cache line size.
void	icache_invalidate_all (void)
	Invalidate the entire instruction cache.
void	icache_invalidate (void *addr, size_t size)
	Invalidate the instruction cache for a range.
void	dcache_enable (void)
	Enable the data cache, invalidating it first.
void	dcache_disable (void)
	Disable the data cache, flushing and invalidating it first.
bool	dcache_is_enabled (void)
	Check whether the data cache is enabled.
uint32_t	dcache_line_size (void)
	Get the data cache line size.
void	dcache_flush_all (void)
	Flush the entire data cache.
void	dcache_invalidate_all (void)
	Invalidate the entire data cache.
void	dcache_flush_invalidate_all (void)
	Flush, then invalidate the entire data cache.
void	dcache_flush (const void *addr, size_t size)
	Flush the data cache for a range.
void	dcache_invalidate (void *addr, size_t size)
	Invalidate the data cache for a range.
void	dcache_flush_invalidate (const void *addr, size_t size)
	Flush, then invalidate the data cache for a range.
void	icache_align (uintptr_t *addr, size_t *size)
	Widen a range to whole instruction cache lines.
void	dcache_align (uintptr_t *addr, size_t *size)
	Widen a range to whole data cache lines.
uint32_t	dcache_alignment_mask_minimum (uint32_t min)
	Get the alignment mask for a buffer shared with a peripheral.

Detailed Description

Instruction and data cache maintenance.

The instruction and data caches are separate: to execute newly written code, flush the data cache and invalidate the instruction cache for that region. A flush writes cached data back to memory and keeps it cached; an invalidate discards cached data so it is reloaded from memory on the next access; flush_invalidate does both.

Range operations work on whole cache lines. Flushing memory beyond a buffer is harmless, but invalidating it destroys any pending writes to the neighbouring data, so align buffers that get invalidated (e.g. DMA receive buffers) with dcache_align() or dcache_alignment_mask_minimum().

On cores without a cache every operation is a no-op and the line size reads as 1.

uintptr_t addr = (uintptr_t)rx_buf;
size_t size = rx_len;
 
dcache_align(&addr, &size);
dcache_invalidate((void *)addr, size); // after the DMA transfer, before reading rx_buf

Macro Definition Documentation

DCACHE_LINE_SIZE_MAX

#define DCACHE_LINE_SIZE_MAX   32U

Largest data cache line of the supported cores, in bytes.

A buffer aligned to it and sized in multiples of it owns every cache line it touches, so it can be invalidated without harming neighbouring data; see DCACHE_ROUND_UP().

DCACHE_ROUND_UP

#define DCACHE_ROUND_UP

(

size

)

(((size) + DCACHE_LINE_SIZE_MAX - 1U) & ~(DCACHE_LINE_SIZE_MAX - 1U))

size rounded up to whole DCACHE_LINE_SIZE_MAX lines.

Function Documentation

dcache_align()

void dcache_align	(	uintptr_t *	addr,
		size_t *	size
	)

Widen a range to whole data cache lines.

Parameters

[in,out]	addr	Start address, rounded down to a line boundary.
[in,out]	size	Size in bytes, grown so the range still covers the original one.

dcache_alignment_mask_minimum()

uint32_t dcache_alignment_mask_minimum

(

uint32_t

min

)

Get the alignment mask for a buffer shared with a peripheral.

Combines the data cache line size with an alignment the peripheral itself requires.

Parameters

min	Minimum alignment in bytes, a power of two.

Returns

The larger of min and the line size, minus 1: the address bits that must be clear.

dcache_disable()

void dcache_disable

(

void

)

Disable the data cache, flushing and invalidating it first.

dcache_enable()

void dcache_enable

(

void

)

Enable the data cache, invalidating it first.

dcache_flush()

void dcache_flush	(	const void *	addr,
		size_t	size
	)

Flush the data cache for a range.

Parameters

addr	Start address, aligned to the line size.
size	Size in bytes, a multiple of the line size.

dcache_flush_all()

void dcache_flush_all

(

void

)

Flush the entire data cache.

dcache_flush_invalidate()

void dcache_flush_invalidate	(	const void *	addr,
		size_t	size
	)

Flush, then invalidate the data cache for a range.

Parameters

addr	Start address, aligned to the line size.
size	Size in bytes, a multiple of the line size.

dcache_flush_invalidate_all()

void dcache_flush_invalidate_all

(

void

)

Flush, then invalidate the entire data cache.

dcache_invalidate()

void dcache_invalidate	(	void *	addr,
		size_t	size
	)

Invalidate the data cache for a range.

Parameters

addr	Start address, aligned to the line size.
size	Size in bytes, a multiple of the line size.

dcache_invalidate_all()

void dcache_invalidate_all

(

void

)

Invalidate the entire data cache.

dcache_is_enabled()

bool dcache_is_enabled

(

void

)

Check whether the data cache is enabled.

Returns

true if enabled.

dcache_line_size()

uint32_t dcache_line_size

(

void

)

Get the data cache line size.

Only valid once dcache_enable() has run.

Returns

Line size in bytes, 1 without a data cache.

icache_align()

void icache_align	(	uintptr_t *	addr,
		size_t *	size
	)

Widen a range to whole instruction cache lines.

Parameters

[in,out]	addr	Start address, rounded down to a line boundary.
[in,out]	size	Size in bytes, grown so the range still covers the original one.

icache_disable()

void icache_disable

(

void

)

Disable the instruction cache, invalidating it afterwards.

icache_enable()

void icache_enable

(

void

)

Enable the instruction cache, invalidating it first.

icache_invalidate()

void icache_invalidate	(	void *	addr,
		size_t	size
	)

Invalidate the instruction cache for a range.

Parameters

addr	Start address, aligned to the line size.
size	Size in bytes, a multiple of the line size.

icache_invalidate_all()

void icache_invalidate_all

(

void

)

Invalidate the entire instruction cache.

icache_is_enabled()

bool icache_is_enabled

(

void

)

Check whether the instruction cache is enabled.

Returns

true if enabled.

icache_line_size()

uint32_t icache_line_size

(

void

)

Get the instruction cache line size.

Only valid once icache_enable() has run.

Returns

Line size in bytes, 1 without an instruction cache.