Functions
ALT_STATUS_CODE	alt_cache_l1_enable_all (void)

ALT_STATUS_CODE	alt_cache_l1_disable_all (void)

ALT_STATUS_CODE	alt_cache_l1_instruction_enable (void)

ALT_STATUS_CODE	alt_cache_l1_instruction_disable (void)

bool	alt_cache_l1_instruction_is_enabled (void)

ALT_STATUS_CODE	alt_cache_l1_instruction_invalidate (void)

ALT_STATUS_CODE	alt_cache_l1_data_enable (void)

ALT_STATUS_CODE	alt_cache_l1_data_disable (void)

bool	alt_cache_l1_data_is_enabled (void)

ALT_STATUS_CODE	alt_cache_l1_data_invalidate (void *vaddress, size_t length)

ALT_STATUS_CODE	alt_cache_l1_data_invalidate_all (void)

ALT_STATUS_CODE	alt_cache_l1_data_clean (void *vaddress, size_t length)

ALT_STATUS_CODE	alt_cache_l1_data_clean_all (void)

ALT_STATUS_CODE	alt_cache_l1_data_purge (void *vaddress, size_t length)

ALT_STATUS_CODE	alt_cache_l1_data_purge_all (void)

ALT_STATUS_CODE	alt_cache_l1_parity_enable (void)

ALT_STATUS_CODE	alt_cache_l1_parity_disable (void)

bool	alt_cache_l1_parity_is_enabled (void)

ALT_STATUS_CODE	alt_cache_l1_branch_enable (void)

ALT_STATUS_CODE	alt_cache_l1_branch_disable (void)

bool	alt_cache_l1_branch_is_enabled (void)

ALT_STATUS_CODE	alt_cache_l1_branch_invalidate (void)

ALT_STATUS_CODE	alt_cache_l1_prefetch_enable (void)

ALT_STATUS_CODE	alt_cache_l1_prefetch_disable (void)

bool	alt_cache_l1_prefetch_is_enabled (void)

Detailed Description

This API group provides functions to interact with various components of the L1 cache on the SoCFPGA. This includes the following cache components:

Instruction Cache
Data Cache
Parity error detection
Dynamic branch prediction
Data prefetching

The API within this group only affects the L1 cache on the current CPU. To interact the L1 cache on another CPU, the API must be called from that other CPU.

With respect to bring-up, the L1 and L2 cache controller setups are fully independent. The L2 can be setup at any time, before or after the L1 is setup.

Function Documentation

◆ alt_cache_l1_branch_disable()

ALT_STATUS_CODE alt_cache_l1_branch_disable ( void )

Disables the dynamic branch predictor features on the current CPU core.

This operation disables both the Branch Target Address Cache (BTAC) and the Global History Buffer (GHB).

Return values

ALT_E_SUCCESS	The operation was successful.
ALT_E_ERROR	The operation failed.

◆ alt_cache_l1_branch_enable()

ALT_STATUS_CODE alt_cache_l1_branch_enable ( void )

Enables the dynamic branch predictor features on the current CPU core.

This operation enables both the Branch Target Address Cache (BTAC) and the Global History Buffer (GHB). Affected caches are automatically invalidated before use.

Return values

ALT_E_SUCCESS	The operation was successful.
ALT_E_ERROR	The operation failed.

◆ alt_cache_l1_branch_invalidate()

ALT_STATUS_CODE alt_cache_l1_branch_invalidate ( void )

Invalidates the dynamic branch predictor feature caches on the current CPU core.

Return values

ALT_E_SUCCESS	The operation was successful.
ALT_E_ERROR	The operation failed.

◆ alt_cache_l1_branch_is_enabled()

bool alt_cache_l1_branch_is_enabled ( void )

Returns true when both the dynamic predictor features are enabled and false when they are disabled on the current CPU core.

Return values

true	The L1 branch predictor caches are all enabled.
false	Some or all L1 branch predictor caches are disabled.

◆ alt_cache_l1_data_clean()

ALT_STATUS_CODE alt_cache_l1_data_clean	(	void *	vaddress,
		size_t	length
	)

Cleans the specified contents of the L1 data cache on the current CPU core for the given memory segment.

The memory segment address and length specified must align to the characteristics of the cache line. This means the address and length must be multiples of the cache line size. To determine the cache line size, use the ALT_CACHE_LINE_SIZE macro.

Parameters

vaddress	The virtual address of the memory segment to be cleaned.
length	The length of the memory segment to be cleaned.

Return values

ALT_E_SUCCESS	The operation was successful.
ALT_E_ERROR	The operation failed.
ALT_E_BAD_ARG	The memory segment is invalid.

◆ alt_cache_l1_data_clean_all()

ALT_STATUS_CODE alt_cache_l1_data_clean_all ( void )

Cleans the entire L1 data cache for the current CPU core.

Return values

ALT_E_SUCCESS	The operation was successful.
ALT_E_ERROR	The operation failed.

◆ alt_cache_l1_data_disable()

ALT_STATUS_CODE alt_cache_l1_data_disable ( void )

Disables the L1 data cache on the current CPU core.

If the cache is already disabled nothing is done. Otherwise the data cache is first cleaned before being disabled.

Return values

ALT_E_SUCCESS	The operation was successful.
ALT_E_ERROR	The operation failed.

◆ alt_cache_l1_data_enable()

ALT_STATUS_CODE alt_cache_l1_data_enable ( void )

Enables the L1 data cache on the current CPU core.

If the cache is already enabled nothing is done. Otherwise the data cache is first invalidated before being enabled.

Return values

ALT_E_SUCCESS	The operation was successful.
ALT_E_ERROR	The operation failed.

◆ alt_cache_l1_data_invalidate()

ALT_STATUS_CODE alt_cache_l1_data_invalidate	(	void *	vaddress,
		size_t	length
	)

Invalidates the specified contents of the L1 data cache on the current CPU core for the given memory segment.

The memory segment address and length specified must align to the characteristics of the cache line. This means the address and length must be multiples of the cache line size. To determine the cache line size, use the ALT_CACHE_LINE_SIZE macro.

Parameters

vaddress	The virtual address of the memory segment to be invalidated.
length	The length of the memory segment to be invalidated.

Return values

ALT_E_SUCCESS	The operation was successful.
ALT_E_ERROR	The operation failed.
ALT_E_BAD_ARG	The memory segment is invalid.

◆ alt_cache_l1_data_invalidate_all()

ALT_STATUS_CODE alt_cache_l1_data_invalidate_all ( void )

Invalidates the entire contents of the L1 data cache on the current CPU core.

Normally this is done automatically as part of alt_cache_l1_data_enable(), but in certain circumstances it may be necessary to invalidate it manually. An example of this situation is when the address space is remapped and the processor accesses memory from the new memory area.

Return values

ALT_E_SUCCESS	The operation was successful.
ALT_E_ERROR	The operation failed.

◆ alt_cache_l1_data_is_enabled()

bool alt_cache_l1_data_is_enabled ( void )

Returns true when the L1 data cache is enabled and false when it is disabled on the current CPU core.

Return values

true	The L1 data cache is enabled.
false	The L1 data cache is disabled.

◆ alt_cache_l1_data_purge()

ALT_STATUS_CODE alt_cache_l1_data_purge	(	void *	vaddress,
		size_t	length
	)

Cleans and invalidates the specified contents of the L1 data cache on the current CPU core for the given memory segment.

The memory segment address and length specified must align to the characteristics of the cache line. This means the address and length must be multiples of the cache line size. To determine the cache line size, use the ALT_CACHE_LINE_SIZE macro.

Normally this is done automatically as part of alt_cache_l1_data_disable(), but in certain circumstances it may be necessary to purged it manually. An example of this situation is when the address space is remapped and the processor accesses memory from the new memory area.

Parameters

vaddress	The virtual address of the memory segment to be purged.
length	The length of the memory segment to be purged.

Return values

ALT_E_SUCCESS	The operation was successful.
ALT_E_ERROR	The operation failed.
ALT_E_BAD_ARG	The memory segment is invalid.

◆ alt_cache_l1_data_purge_all()

ALT_STATUS_CODE alt_cache_l1_data_purge_all ( void )

Cleans and invalidates the entire L1 data cache for the current CPU core.

Return values

ALT_E_SUCCESS	The operation was successful.
ALT_E_ERROR	The operation failed.

◆ alt_cache_l1_disable_all()

ALT_STATUS_CODE alt_cache_l1_disable_all ( void )

Disables all L1 caches and features on the current CPU core. This includes the instruction cache, data cache, parity error detection, branch target address cache, global history buffer, and data prefetching. All necessary maintenance tasks will be taken care of.

This function should not be mixed with other L1 cache related functions which enable or disable caches individually.

Return values

ALT_E_SUCCESS	The operation was successful.
ALT_E_ERROR	The operation failed.

◆ alt_cache_l1_enable_all()

ALT_STATUS_CODE alt_cache_l1_enable_all ( void )

Enables all L1 caches and features on the current CPU core. This includes the instruction cache, data cache, parity error detection, branch target address cache, global history buffer, and data prefetching. All necessary maintenance tasks will be taken care of.

This function should not be mixed with other L1 cache related functions which enable or disable caches individually.

Return values

ALT_E_SUCCESS	The operation was successful.
ALT_E_ERROR	The operation failed.

◆ alt_cache_l1_instruction_disable()

ALT_STATUS_CODE alt_cache_l1_instruction_disable ( void )

Disables the L1 instruction cache on the current CPU core.

Return values

ALT_E_SUCCESS	The operation was successful.
ALT_E_ERROR	The operation failed.

◆ alt_cache_l1_instruction_enable()

ALT_STATUS_CODE alt_cache_l1_instruction_enable ( void )

Enables the L1 instruction cache on the current CPU core. If the cache is already enabled, nothing is done. Otherwise the instruction cache is first invalidated before being enabled.

Return values

ALT_E_SUCCESS	The operation was successful.
ALT_E_ERROR	The operation failed.

◆ alt_cache_l1_instruction_invalidate()

ALT_STATUS_CODE alt_cache_l1_instruction_invalidate ( void )

Invalidates the contents of the L1 instruction cache on the current CPU core.

Normally this is done automatically as part of alt_cache_l1_instruction_enable(), but in certain circumstances it may be necessary to invalidate it manually. An example of this situation is when the address space is remapped and the processor executes instructions from the new memory area.

Return values

ALT_E_SUCCESS	The operation was successful.
ALT_E_ERROR	The operation failed.

◆ alt_cache_l1_instruction_is_enabled()

bool alt_cache_l1_instruction_is_enabled ( void )

Returns true when the L1 instruction cache is enabled and false when it is disabled on the current CPU core.

Return values

true	The L1 instruction cache is enabled.
false	The L1 instruction cache is disabled.

◆ alt_cache_l1_parity_disable()

ALT_STATUS_CODE alt_cache_l1_parity_disable ( void )

Disables parity error detection in the L1 caches.

Return values

ALT_E_SUCCESS	The operation was successful.
ALT_E_ERROR	The operation failed.

◆ alt_cache_l1_parity_enable()

ALT_STATUS_CODE alt_cache_l1_parity_enable ( void )

Enables the parity error detection feature in the L1 caches on the current CPU core.

Ideally parity should be enabled before any L1 caches are enabled. If the instruction, data, and / or dynamic branch predictor caches are already enabled, they will first be cleaned (if needed) and disabled before parity is enabled in hardware. Afterwards, the affected caches will be invalidated and enabled.

Parity and TLB interaction deserves special attention. The TLB is considered to be a L1 cache but is enabled when the MMU, which is grouped in another API, is enabled. Due to the system-wide influence of the MMU, it cannot be disabled and enabled with impunity as the other L1 caches, which are designed to operate as transparently as possible. Thus parity error detection must be enabled before the L1 TLB cache, and by extension the MMU, is enabled.

For a parity error to be reported, the appropriate CPU PARITYFAIL interrupt for the current CPU core must be enabled using the interrupt controller API. For CPU0, ALT_INT_INTERRUPT_CPU0_PARITYFAIL is asserted if any parity error is detected while the other PARITYFAIL interrupts are for parity errors in a specific memory. Refer to the interrupt controller API for more details about programming the interrupt controller.

In the event of a parity error is detected, the appropriate CPU parity interrupt will be raised. CPU parity interrupts are all edge triggered and are cleared by acknowledging them in the interrupt controller API.

Return values

ALT_E_SUCCESS	The operation was successful.
ALT_E_ERROR	The operation failed.

◆ alt_cache_l1_parity_is_enabled()

bool alt_cache_l1_parity_is_enabled ( void )

Returns true when parity error detection is enabled and false when it is disabled on the current CPU core.

Return values

true	Parity error detection for L1 caches is enabled.
false	Parity error detection for L1 caches is disabled.

◆ alt_cache_l1_prefetch_disable()

ALT_STATUS_CODE alt_cache_l1_prefetch_disable ( void )

Disables the L1 cache data prefetch feature on the current CPU core.

Return values

ALT_E_SUCCESS	The operation was successful.
ALT_E_ERROR	The operation failed.

◆ alt_cache_l1_prefetch_enable()

ALT_STATUS_CODE alt_cache_l1_prefetch_enable ( void )

Enables the L1 cache data prefetch feature on the current CPU core.

This allows data to be prefetched into the data cache before it is to be used. For example in a loop the current iteration may want to preload the data which will be used in the next teration. This is done by using the PLD instructions.

Return values

ALT_E_SUCCESS	The operation was successful.
ALT_E_ERROR	The operation failed.

◆ alt_cache_l1_prefetch_is_enabled()

bool alt_cache_l1_prefetch_is_enabled ( void )

Returns true if the L1 cache data prefetch feature is enabled and false if it is disabled on the current CPU core.

Return values

true	The L1 data cache prefetch feature is enabled.
false	The L1 data cache prefetch feature is disabled.

Functions

Detailed Description

Function Documentation

◆ alt_cache_l1_branch_disable()

◆ alt_cache_l1_branch_enable()

◆ alt_cache_l1_branch_invalidate()

◆ alt_cache_l1_branch_is_enabled()

◆ alt_cache_l1_data_clean()

◆ alt_cache_l1_data_clean_all()

◆ alt_cache_l1_data_disable()

◆ alt_cache_l1_data_enable()

◆ alt_cache_l1_data_invalidate()

◆ alt_cache_l1_data_invalidate_all()

◆ alt_cache_l1_data_is_enabled()

◆ alt_cache_l1_data_purge()

◆ alt_cache_l1_data_purge_all()

◆ alt_cache_l1_disable_all()

◆ alt_cache_l1_enable_all()

◆ alt_cache_l1_instruction_disable()

◆ alt_cache_l1_instruction_enable()

◆ alt_cache_l1_instruction_invalidate()

◆ alt_cache_l1_instruction_is_enabled()

◆ alt_cache_l1_parity_disable()

◆ alt_cache_l1_parity_enable()

◆ alt_cache_l1_parity_is_enabled()

◆ alt_cache_l1_prefetch_disable()

◆ alt_cache_l1_prefetch_enable()

◆ alt_cache_l1_prefetch_is_enabled()