MT2523 API Reference  LinkIt SDK v4
CACHE

This section describes the programming interfaces of the CACHE controller. More...

Overview

This section describes the programming interfaces of the CACHE controller.

The CACHE controller is a unified CACHE (I-CACHE and D-CACHE use the same CACHE). This CACHE driver allows the user to set the CACHE size, configure the cacheable region(s), enable or disable the CACHE and to perform CACHE maintenance operations, such as invalidate and flush. These maintenance operations may be performed on the entire CACHE or based on the given address and length.
When a memory is set as cacheable, the CPU exchanges data with the CACHE memory during the CACHE hit instead of an external memory, so it can accelerate the access performance. But a data coherency issue might rise when the memory is shared between the Central Processing Unit (CPU) and hardware co-processors, such as Direct Memory Access (DMA). Peripherals (Inter-Integrated Circuit(I2C), Universal Asynchronous Receiver/Transmitter(UART), Serial Peripheral Interface(SPI)) or hardware modules (Graphics 2D(G2D), CAMERA) that operate in DMA mode also face the same issue.
These peripherals or hardware modules must work with non-cacheable memory.

Terms and acronyms

The following provides descriptions to the terms commonly used in the CACHE controller and how to use its various functions.

Terms Details
AHB Advanced High-performance Bus (AHB) is a bus protocol introduced in the Advanced Microcontroller Bus Architecture version 2 published by ARM Ltd.
CACHE A collection of data duplicating original values stored in external memory, to accelerate the data access and enhance the MCU performance.
CACHE line The smallest unit of memory that can be transferred between the main memory and the CACHE. Unless otherwise indicated, the CACHE line size is 8 words (64 bytes).
TCM Tightly Coupled Memory (TCM), memory which resides directly in the processor.
flush Data in invalid CACHE line with dirty bit set is evicted to write-back buffer, then dirty bits are cleared. If the entry is invalid or the dirty flag is not set, leave as it is. The action does not clear the valid bit(s).
invalidate Unconditionally clear valid and dirty bits of the corresponding CACHE line(s).

Supported features

Features supported by this module are listed below:

How to use this driver

Functions

hal_cache_status_t hal_cache_init (void)
 This function initializes the CACHE, sets the default cacheable attribute for the project memory layout. More...
 
hal_cache_status_t hal_cache_deinit (void)
 This function deinitializes the CACHE, returning the CACHE module to its default state. More...
 
hal_cache_status_t hal_cache_enable (void)
 This function enables the CACHE controller. More...
 
hal_cache_status_t hal_cache_disable (void)
 This function disables the CACHE controller. More...
 
hal_cache_status_t hal_cache_region_enable (hal_cache_region_t region)
 This function enables a single CACHE region. More...
 
hal_cache_status_t hal_cache_region_disable (hal_cache_region_t region)
 This function disables a single CACHE region. More...
 
hal_cache_status_t hal_cache_set_size (hal_cache_size_t cache_size)
 This function sets the total size of the CACHE. More...
 
hal_cache_status_t hal_cache_region_config (hal_cache_region_t region, const hal_cache_region_config_t *region_config)
 This function configures the CACHE. More...
 
hal_cache_status_t hal_cache_invalidate_one_cache_line (uint32_t address)
 This function invalidates a CACHE line at a given address. More...
 
hal_cache_status_t hal_cache_invalidate_multiple_cache_lines (uint32_t address, uint32_t length)
 This function invalidates the CACHE lines by address and length. More...
 
hal_cache_status_t hal_cache_invalidate_all_cache_lines (void)
 This function invalidates the whole CACHE. More...
 
hal_cache_status_t hal_cache_flush_one_cache_line (uint32_t address)
 This function flushes one CACHE line by address. More...
 
hal_cache_status_t hal_cache_flush_multiple_cache_lines (uint32_t address, uint32_t length)
 This function flushes the CACHE lines by address and length. More...
 
hal_cache_status_t hal_cache_flush_all_cache_lines (void)
 This function flushes the whole CACHE. More...
 

Modules

 Define
 
 Enum
 
 Struct
 

Function Documentation

hal_cache_status_t hal_cache_deinit ( void  )

This function deinitializes the CACHE, returning the CACHE module to its default state.

Returns
HAL_CACHE_STATUS_OK, the CACHE is successfully deinitialized.
hal_cache_status_t hal_cache_disable ( void  )

This function disables the CACHE controller.

See also
hal_cache_region_disable().
Returns
HAL_CACHE_STATUS_OK, the CACHE is successfully disabled.
hal_cache_status_t hal_cache_enable ( void  )

This function enables the CACHE controller.

See also
hal_cache_region_enable().
Returns
HAL_CACHE_STATUS_OK, the CACHE is successfully enabled.
HAL_CACHE_STATUS_ERROR_CACHE_SIZE, the CACHE cannot be enabled when the CACHE size is 0kB.
hal_cache_status_t hal_cache_flush_all_cache_lines ( void  )

This function flushes the whole CACHE.

Returns
HAL_CACHE_STATUS_OK, the CACHE is successfully flushed.
Note
Flush all CACHE lines.
hal_cache_status_t hal_cache_flush_multiple_cache_lines ( uint32_t  address,
uint32_t  length 
)

This function flushes the CACHE lines by address and length.

Parameters
[in]addressis the start address of the memory to flush.
[in]lengthis the length of the memory to be flushed. The unit of the memory length is in bytes and both address and length must be CACHE line size aligned when the API is called.
Returns
HAL_CACHE_STATUS_OK, the CACHE is successfully flushed.
HAL_CACHE_STATUS_INVALID_PARAMETER, either address or length is not CACHE line size aligned. The alignment requires that the address and the length of a CACHE line must be a multiple of HAL_CACHE_LINE_SIZE.
hal_cache_status_t hal_cache_flush_one_cache_line ( uint32_t  address)

This function flushes one CACHE line by address.

Parameters
[in]addressis the start address of the memory that is flushed.
Returns
HAL_CACHE_STATUS_OK, the CACHE is successfully flushed.
HAL_CACHE_STATUS_INVALID_PARAMETER, address is not CACHE line size aligned. The alignment requires that the address of a CACHE line must be a multiple of HAL_CACHE_LINE_SIZE.
hal_cache_status_t hal_cache_init ( void  )

This function initializes the CACHE, sets the default cacheable attribute for the project memory layout.

Returns
HAL_CACHE_STATUS_OK, the CACHE is successfully initialized.
HAL_CACHE_STATUS_ERROR_BUSY, the CACHE is busy.
hal_cache_status_t hal_cache_invalidate_all_cache_lines ( void  )

This function invalidates the whole CACHE.

Returns
HAL_CACHE_STATUS_OK, the CACHE is successfully invalidated.
hal_cache_status_t hal_cache_invalidate_multiple_cache_lines ( uint32_t  address,
uint32_t  length 
)

This function invalidates the CACHE lines by address and length.

Parameters
[in]addressis the start address of the memory that is invalidated.
[in]lengthis the length of memory that to be invalidated.The unit of the memory length is in bytes and both address and length must be CACHE line size aligned when the API is called.
Returns
HAL_CACHE_STATUS_OK, the CACHE is successfully invalidated.
HAL_CACHE_STATUS_INVALID_PARAMETER, either address or length is not CACHE line size aligned. The alignment requires that the address and the length of a CACHE line must be a multiple of HAL_CACHE_LINE_SIZE.
hal_cache_status_t hal_cache_invalidate_one_cache_line ( uint32_t  address)

This function invalidates a CACHE line at a given address.

Parameters
[in]addressis the start address of the memory that is invalidated.
Returns
HAL_CACHE_STATUS_OK, the CACHE is successfully invalidated.
HAL_CACHE_STATUS_INVALID_PARAMETER, address is not CACHE line size aligned. The alignment requires that the address of a CACHE line must be a multiple of HAL_CACHE_LINE_SIZE.
hal_cache_status_t hal_cache_region_config ( hal_cache_region_t  region,
const hal_cache_region_config_t region_config 
)

This function configures the CACHE.

Parameters
[in]regionis the region to configure.
[in]region_configis the configuration information of the region.
Returns
HAL_CACHE_STATUS_OK, the CACHE region is successfully configured.
HAL_CACHE_STATUS_INVALID_PARAMETER, region_config is NULL.
HAL_CACHE_STATUS_ERROR_REGION, the region is invalid.
HAL_CACHE_STATUS_ERROR_REGION_SIZE, the region size is invalid.
HAL_CACHE_STATUS_ERROR_REGION_ADDRESS, the region address is invalid.
hal_cache_status_t hal_cache_region_disable ( hal_cache_region_t  region)

This function disables a single CACHE region.

When this function is called, the CACHE settings of corresponding region are disabled, even if the hal_cache_enable() function is called.

See also
hal_cache_disable().
Parameters
[in]regionis the disabled region, this parameter is any value of type hal_cache_region_t.
Returns
HAL_CACHE_STATUS_OK, CACHE region is successfully disabled.
HAL_CACHE_STATUS_ERROR_REGION, the region is invalid.
hal_cache_status_t hal_cache_region_enable ( hal_cache_region_t  region)

This function enables a single CACHE region.

Once hal_cache_enable() is called, the settings of the specified region take effect.

See also
hal_cache_enable().
Parameters
[in]regionis the enabled region, this parameter can only be a value of type hal_cache_region_t.
Returns
HAL_CACHE_STATUS_OK, the CACHE region is successfully enabled.
HAL_CACHE_STATUS_ERROR_REGION, the region is invalid.
HAL_CACHE_STATUS_ERROR, the region is not configured before enable.
hal_cache_status_t hal_cache_set_size ( hal_cache_size_t  cache_size)

This function sets the total size of the CACHE.

Parameters
[in]cache_sizeshould only be any value of type hal_cache_size_t.
Returns
HAL_CACHE_STATUS_OK, the CACHE size setting is successful.
HAL_CACHE_STATUS_ERROR_CACHE_SIZE, the CACHE size is invalid.