cache_control.h File Reference

Explicit owned Cortex-M7 cold cache transitions. More...

#include <stdbool.h>
#include <stdint.h>

Go to the source code of this file.

Data Structures
struct	nx_arch_cache_control_t
	Caller-owned cache responsibility and selector recovery. More...

Macros
#define	NX_ARCH_CACHE_DATA   1U
	Data-cache ownership bit, independent of the hardware CCR layout.
#define	NX_ARCH_CACHE_INSTRUCTION   2U
	Instruction-cache ownership bit.

Enumerations
enum	nx_arch_cache_control_result_t {   NX_ARCH_CACHE_OK = 0 , NX_ARCH_CACHE_INVALID , NX_ARCH_CACHE_CONTEXT , NX_ARCH_CACHE_UNSUPPORTED ,   NX_ARCH_CACHE_STATE , NX_ARCH_CACHE_IO }
	Cold-transition admission or execution result. More...

Functions
nx_arch_cache_control_result_t	nx_arch_cache_cold_enable (nx_arch_cache_control_t *control, uint32_t mask)
	Admit cold caches and enable the explicitly selected ones.
nx_arch_cache_control_result_t	nx_arch_cache_cold_disable (nx_arch_cache_control_t *control)
	Clean and disable caches owned by this control object.

Detailed Description

Explicit owned Cortex-M7 cold cache transitions.

Author

Nexus Team

Definition in file cache_control.h.

Macro Definition Documentation

NX_ARCH_CACHE_DATA

#define NX_ARCH_CACHE_DATA   1U

Data-cache ownership bit, independent of the hardware CCR layout.

Definition at line 14 of file cache_control.h.

NX_ARCH_CACHE_INSTRUCTION

#define NX_ARCH_CACHE_INSTRUCTION   2U

Instruction-cache ownership bit.

Definition at line 16 of file cache_control.h.

Enumeration Type Documentation

nx_arch_cache_control_result_t

enum nx_arch_cache_control_result_t

Cold-transition admission or execution result.

Enumerator
NX_ARCH_CACHE_OK
NX_ARCH_CACHE_INVALID
NX_ARCH_CACHE_CONTEXT
NX_ARCH_CACHE_UNSUPPORTED
NX_ARCH_CACHE_STATE
NX_ARCH_CACHE_IO

Definition at line 18 of file cache_control.h.

Function Documentation

nx_arch_cache_cold_disable()

nx_arch_cache_control_result_t nx_arch_cache_cold_disable

(

nx_arch_cache_control_t *

control

)

Clean and disable caches owned by this control object.

Parameters

[in,out]

control

Same live object passed to cold_enable.

Returns

OK only after cache disable and selector restoration; INVALID, CONTEXT, UNSUPPORTED, STATE or IO retain ownership.

Note

Satisfies enable's exclusion and context contract after every DMA/provider has drained. Rejects enabled caches outside owned_mask. The data clean/disable transition uses a stack-free leaf so no local dirty line can appear between the final clean and CCR update. Its bounded work is four ways times the verified set count, not constant latency. Failed operations remain retryable without adopting a new cache or forgetting the original selector. A zero object is an idempotent no-op on a supported CPU profile.

nx_arch_cache_cold_enable()

nx_arch_cache_control_result_t nx_arch_cache_cold_enable	(	nx_arch_cache_control_t *	control,
		uint32_t	mask )

Admit cold caches and enable the explicitly selected ones.

Parameters

[in,out]	control	Exclusively owned, initially empty control object.
[in]	mask	Nonzero combination of DATA and INSTRUCTION bits.

Returns

OK after verified enable and selector restoration; INVALID for arguments; CONTEXT for unsafe context; UNSUPPORTED for an unreviewed CPU/geometry; STATE for live/foreign caches; IO when a register write is not confirmed by readback.

Note

Reviewed M7 only. Requires privileged Thread, PRIMASK=1, BASEPRI=FAULTMASK=0 and known-clean caches from a trusted reset or prior successful owned clean/disable. CCR bits being zero alone do not prove clean foreign state; never adopt an unknown bootloader state. Caller excludes all other cache users, DMA, NMI and HardFault access to affected memory throughout the transition. It owns memory attributes, execution and coherency policy; enabling a cache does not establish DMA coherence. No IRQ mask changes, allocation or cache adoption occur. Rejected initial admission has no retained responsibility. An IO failure can retain owned_mask/selector_pending; call cold_disable and retain storage until it succeeds.