HAL DCACHE Functions

Initialization and DeInitialization functions

group DCACHE_Exported_Functions_Group1

This section provides a set of functions allowing to initialize and deinitialize the DCACHE peripheral:

  • Call the function HAL_DCACHE_Init() to initialize the selected DCACHE handle and associate an instance.

  • Call the function HAL_DCACHE_DeInit() :

    • to reset the DCACHE to the initial state by resetting the monitors,

    • to reset the burst type to WRAP mode

    • to disable interrupts,

    • to reset and stop ongoing commands if any,

    • to stop the cache and clear the flags.

Functions

hal_status_t HAL_DCACHE_Init ( hal_dcache_handle_t * hdcache , hal_dcache_t instance )

Initialize the DCACHE according to the associated handle.

Parameters :

  • hdcache – Pointer to a hal_dcache_handle_t structure that contains the handle information for the specified DCACHE.

  • instance – DCACHE instance.

Return values :

  • HAL_INVALID_PARAM – When the handle is NULL.

  • HAL_OK – HAL DCACHE driver correctly Initialized for the given DCACHE instance.

void HAL_DCACHE_DeInit ( hal_dcache_handle_t * hdcache )

DeInitialize the Data Cache.

Note

The goal of this function is to reset the DCACHE to the initial state:

  • stop the DCACHE,

  • disable and reset the monitors,

  • reset the burst type to WRAP mode

  • disable interrupts,

  • clear the interrupt flags,

  • and reset the last error code.

Parameters :

hdcache – Pointer to a hal_dcache_handle_t structure that contains the handle information for the specified DCACHE instance.

Configuration functions

group DCACHE_Exported_Functions_Group2

This section provides a set of functions allowing to configure the DCACHE peripheral:

Functions

hal_status_t HAL_DCACHE_SetReadBurstType ( hal_dcache_handle_t * hdcache , hal_dcache_read_burst_t read_burst_type )

Set the Read Burst Type.

Note

If DCACHE is enabled, the read burst type cannot be set.

Parameters :

  • hdcache – Pointer to a hal_dcache_handle_t structure that contains the handle information for the specified DCACHE instance.

  • read_burst_type – Burst Type to be applied.

Return values :

HAL_OK – DCACHE instance has been correctly configured.

hal_dcache_read_burst_t HAL_DCACHE_GetReadBurstType ( const hal_dcache_handle_t * hdcache )

Get the Read Burst Type.

Parameters :

hdcache – Pointer to a hal_dcache_handle_t structure that contains the handle information for the specified DCACHE instance.

Return values :

  • HAL_DCACHE_READ_BURST_WRAP – WRAP Configuration

  • HAL_DCACHE_READ_BURST_INCR – INCR Configuration

Control functions

group DCACHE_Exported_Functions_Group3

The functions are :

Functions

hal_status_t HAL_DCACHE_Start ( hal_dcache_handle_t * hdcache , uint32_t interrupts )

Start the Data cache.

Note

This function can enable the interrupts, and starts the DCACHE.

Parameters :

  • hdcache – Pointer to a hal_dcache_handle_t structure that contains the handle information for the specified DCACHE instance.

  • interrupts – Interrupts

    • HAL_DCACHE_IT_NONE

    • HAL_DCACHE_IT_ERROR

Return values :

HAL_OK – Only success, even if there is any ongoing cache operation.

hal_status_t HAL_DCACHE_Stop ( hal_dcache_handle_t * hdcache )

Stop the Data cache.

Note

This function disables interrupts, clears the flags and stops the DCACHE.

Parameters :

hdcache – Pointer to a hal_dcache_handle_t structure that contains the handle information for the specified DCACHE instance.

Return values :

HAL_OK – Operation completed successfully.

Monitoring functions

group DCACHE_Exported_Functions_Group5

This section provides functions allowing to monitor Data Cache:

Functions

hal_status_t HAL_DCACHE_EnableMonitors ( hal_dcache_handle_t * hdcache , uint32_t monitor_type )

Enable the Data Cache performance monitoring.

Parameters :

  • hdcache – Pointer to a hal_dcache_handle_t structure that contains the handle information for the specified DCACHE instance.

  • monitor_type – This parameter can be a combination of the following values:

    • HAL_DCACHE_MONITOR_READ_HIT

    • HAL_DCACHE_MONITOR_READ_MISS

    • HAL_DCACHE_MONITOR_WRITE_HIT

    • HAL_DCACHE_MONITOR_WRITE_MISS

    • HAL_DCACHE_MONITOR_ALL

Return values :

HAL_OK – DCACHE Monitor(s) enabled successfully.

hal_status_t HAL_DCACHE_DisableMonitors ( hal_dcache_handle_t * hdcache , uint32_t monitor_type )

Disable the Data Cache performance monitoring.

Note

Stopping the monitoring does not reset the values.

Parameters :

  • hdcache – Pointer to a hal_dcache_handle_t structure that contains the handle information for the specified DCACHE instance.

  • monitor_type – This parameter can be a combination of the following values:

    • HAL_DCACHE_MONITOR_READ_HIT

    • HAL_DCACHE_MONITOR_READ_MISS

    • HAL_DCACHE_MONITOR_WRITE_HIT

    • HAL_DCACHE_MONITOR_WRITE_MISS

    • HAL_DCACHE_MONITOR_ALL

Return values :

HAL_OK – DCACHE Monitor(s) disabled successfully.

hal_status_t HAL_DCACHE_ResetMonitors ( hal_dcache_handle_t * hdcache , uint32_t monitor_type )

Reset the Data Cache performance monitoring values.

Parameters :

  • hdcache – Pointer to a hal_dcache_handle_t structure that contains the handle information for the specified DCACHE instance.

  • monitor_type – This parameter can be a combination of the following values:

    • HAL_DCACHE_MONITOR_READ_HIT

    • HAL_DCACHE_MONITOR_READ_MISS

    • HAL_DCACHE_MONITOR_WRITE_HIT

    • HAL_DCACHE_MONITOR_WRITE_MISS

    • HAL_DCACHE_MONITOR_ALL

Return values :

HAL_OK – DCACHE Monitor(s) reset successfully.

uint32_t HAL_DCACHE_GetMonitorReadHitValue ( const hal_dcache_handle_t * hdcache )

Get the Data Cache performance Read Hit monitoring value.

Note

Upon reaching the maximum value, monitor does not wrap.

Parameters :

hdcache – Pointer to a hal_dcache_handle_t structure that contains the handle information for the specified DCACHE instance.

Return values :

uint32_t – Read Hit monitoring value

uint32_t HAL_DCACHE_GetMonitorReadMissValue ( const hal_dcache_handle_t * hdcache )

Get the Data Cache performance Read Miss monitoring value.

Note

Upon reaching the maximum value, monitor does not wrap.

Parameters :

hdcache – Pointer to a hal_dcache_handle_t structure that contains the handle information for the specified DCACHE instance.

Return values :

uint32_t – Read Miss monitoring value.

uint32_t HAL_DCACHE_GetMonitorWriteHitValue ( const hal_dcache_handle_t * hdcache )

Get the Data Cache performance Write Hit monitoring value.

Note

Upon reaching the maximum value, monitor does not wrap.

Parameters :

hdcache – Pointer to a hal_dcache_handle_t structure that contains the handle information for the specified DCACHE instance.

Return values :

uint32_t – Write Hit monitoring value

uint32_t HAL_DCACHE_GetMonitorWriteMissValue ( const hal_dcache_handle_t * hdcache )

Get the Data Cache performance Write Miss monitoring value.

Note

Upon reaching the maximum value, monitor does not wrap.

Parameters :

hdcache – Pointer to a hal_dcache_handle_t structure that contains the handle information for the specified DCACHE instance.

Return values :

uint32_t – Write Miss monitoring value

Maintenance Operations functions

group DCACHE_Exported_Functions_Group6

This section provides functions allowing to launch maintenance operation:

Functions

hal_status_t HAL_DCACHE_Invalidate ( hal_dcache_handle_t * hdcache )

Invalidate the Data cache.

Note

This function waits for end of full cache invalidation

Parameters :

hdcache – Pointer to a hal_dcache_handle_t structure that contains the handle information for the specified DCACHE instance.

Return values :

  • HAL_ERROR – Operation error.

  • HAL_BUSY – DCACHE driver busy with another ongoing operation.

  • HAL_OK – DCACHE Invalidate operation ended successfully.

hal_status_t HAL_DCACHE_Invalidate_IT ( hal_dcache_handle_t * hdcache )

Invalidate the Data cache with interrupt.

Note

This function launches maintenance operation and returns immediately. User must rely on the corresponding callback.

Parameters :

hdcache – Pointer to a hal_dcache_handle_t structure that contains the handle information for the specified DCACHE instance.

Return values :

  • HAL_BUSY – DCACHE driver busy with another ongoing operation.

  • HAL_OK – DCACHE Invalidate operation started successfully.

hal_status_t HAL_DCACHE_InvalidateByAddr ( hal_dcache_handle_t * hdcache , uint32_t addr , uint32_t size_byte )

Invalidate the Data cache by Address.

Note

This function waits for end of DCACHE Invalidation.

Note

The Address must be aligned on 16 bytes and the Size must be a multiple of 16 or 32 bytes, it depends on U5 series (check the reference manual).

Parameters :

  • hdcache – Pointer to a hal_dcache_handle_t structure that contains the handle information for the specified DCACHE instance.

  • addr – Start address of the region to be Invalidated

  • size_byte – Size of the region to be Invalidated (in bytes)

Return values :

  • HAL_ERROR – Operation error.

  • HAL_BUSY – DCACHE driver busy with another ongoing operation.

  • HAL_OK – DCACHE Invalidate by Address operation ended successfully.

hal_status_t HAL_DCACHE_InvalidateByAddr_IT ( hal_dcache_handle_t * hdcache , uint32_t addr , uint32_t size_byte )

Invalidate the Data cache by Address with interrupt.

Note

This function launches maintenance operation and returns immediately. User must rely on the corresponding callback.

Note

The Address must be aligned on 16 bytes and the Size must be a multiple of 16 or 32 bytes, it depends on U5 series (check the reference manual).

Parameters :

  • hdcache – Pointer to a hal_dcache_handle_t structure that contains the handle information for the specified DCACHE instance.

  • addr – Start address of the region to be Invalidated

  • size_byte – Size of the region to be Invalidated

Return values :

  • HAL_BUSY – DCACHE driver busy with another ongoing operation.

  • HAL_OK – DCACHE Invalidate by Address operation started successfully.

hal_status_t HAL_DCACHE_CleanByAddr ( hal_dcache_handle_t * hdcache , uint32_t addr , uint32_t size_byte )

Clean the Data cache by Address.

Note

This function waits for end of DCACHE Clean.

Note

The Address must be aligned on 16 bytes and the Size must be a multiple of 16 or 32 bytes, it depends on U5 series (check the reference manual).

Parameters :

  • hdcache – Pointer to a hal_dcache_handle_t structure that contains the handle information for the specified DCACHE instance.

  • addr – Start address of the region to be Cleaned

  • size_byte – Size of the region to be Cleaned (in bytes)

Return values :

  • HAL_ERROR – Operation error.

  • HAL_BUSY – DCACHE driver busy with another ongoing operation.

  • HAL_OK – DCACHE Clean by Address operation ended successfully.

hal_status_t HAL_DCACHE_CleanByAddr_IT ( hal_dcache_handle_t * hdcache , uint32_t addr , uint32_t size_byte )

Clean the Data cache by Address with interrupt.

Note

This function launches maintenance operation and returns immediately. User must rely on the corresponding callback.

Note

The Address must be aligned on 16 bytes and the Size must be a multiple of 16 or 32 bytes, it depends on U5 series (check the reference manual).

Parameters :

  • hdcache – Pointer to a hal_dcache_handle_t structure that contains the handle information for the specified DCACHE instance.

  • addr – Start address of the region to be Cleaned

  • size_byte – Size of the region to be Cleaned

Return values :

  • HAL_BUSY – DCACHE driver busy with another ongoing operation.

  • HAL_OK – DCACHE Clean by Address operation started successfully.

hal_status_t HAL_DCACHE_CleanInvalidByAddr ( hal_dcache_handle_t * hdcache , uint32_t addr , uint32_t size_byte )

Clean and Invalidate the Data cache by Address.

Note

This function waits for end of DCACHE Clean and Invalidation.

Note

The Address must be aligned on 16 bytes and the Size must be a multiple of 16 or 32 bytes, it depends on U5 series (check the reference manual).

Parameters :

  • hdcache – Pointer to a hal_dcache_handle_t structure that contains the handle information for the specified DCACHE instance.

  • addr – Start address of the region to be Cleaned and Invalidated

  • size_byte – Size of the region to be Cleaned and Invalidated (in bytes)

Return values :

  • HAL_ERROR – Operation error.

  • HAL_BUSY – DCACHE driver busy with another ongoing operation.

  • HAL_OK – DCACHE Clean and Invalidate by Address operation ended successfully.

hal_status_t HAL_DCACHE_CleanInvalidByAddr_IT ( hal_dcache_handle_t * hdcache , uint32_t addr , uint32_t size_byte )

Clean and Invalidate the Data cache by Address with interrupt.

Note

This function launches maintenance operation and returns immediately. User must rely on the corresponding callback.

Note

The Address must be aligned on 16 bytes and the Size must be a multiple of 16 or 32 bytes, it depends on U5 series (check the reference manual).

Parameters :

  • hdcache – Pointer to a hal_dcache_handle_t structure that contains the handle information for the specified DCACHE instance.

  • addr – Start address of the region to be Cleaned and Invalidated

  • size_byte – Size of the region to be Cleaned and Invalidated

Return values :

  • HAL_BUSY – DCACHE driver busy with another ongoing operation.

  • HAL_OK – DCACHE Clean and Invalidate by Address operation started successfully.

IRQ and callback functions

group DCACHE_Exported_Functions_Group7

The functions are :

Note

The register user callback functions can be used only if USE_HAL_DCACHE_REGISTER_CALLBACKS = 1

Functions

void HAL_DCACHE_IRQHandler ( hal_dcache_handle_t * hdcache )

Handle the Data Cache interrupt request.

Note

This function must be called from DCACHE_IRQHandler().

Note

This function disables the interrupt related to a detected operation flag.

Parameters :

hdcache – Pointer to a hal_dcache_handle_t structure that contains the handle information for the specified DCACHE instance.

void HAL_DCACHE_ErrorCallback ( hal_dcache_handle_t * hdcache )

DCACHE Error callback.

Parameters :

hdcache – Pointer to a hal_dcache_handle_t structure that contains the handle information for the specified DCACHE instance.

void HAL_DCACHE_InvalidateCompleteCallback ( hal_dcache_handle_t * hdcache )

DCACHE Invalidation complete callback.

Parameters :

hdcache – Pointer to a hal_dcache_handle_t structure that contains the handle information for the specified DCACHE instance.

void HAL_DCACHE_CleanByAddrCallback ( hal_dcache_handle_t * hdcache )

Cache clean command by address callback.

Parameters :

hdcache – Pointer to a hal_dcache_handle_t structure that contains the handle information for the specified DCACHE instance.

void HAL_DCACHE_InvalidateByAddrCallback ( hal_dcache_handle_t * hdcache )

Cache Invalidate command by address callback.

Parameters :

hdcache – Pointer to a hal_dcache_handle_t structure that contains the handle information for the specified DCACHE instance.

void HAL_DCACHE_CleanInvalidByAddrCallback ( hal_dcache_handle_t * hdcache )

Cache clean and Invalidate command by address callback.

Parameters :

hdcache – Pointer to a hal_dcache_handle_t structure that contains the handle information for the specified DCACHE instance.

hal_status_t HAL_DCACHE_RegisterErrorCallback ( hal_dcache_handle_t * hdcache , hal_dcache_cb_t p_callback )

Register a User DCACHE callback for error.

Note

The function is only available if USE_HAL_DCACHE_REGISTER_CALLBACKS = 1.

Parameters :

  • hdcache – Pointer to a hal_dcache_handle_t structure that contains the handle information for the specified DCACHE instance.

  • p_callback – Pointer to the hal_dcache_error_cb_t Error Callback function.

Return values :

  • HAL_OK – Callback registered successfully.

  • HAL_INVALID_PARAM – p_callback pointer is NULL.

hal_status_t HAL_DCACHE_RegisterInvalidateCompleteCallback ( hal_dcache_handle_t * hdcache , hal_dcache_cb_t p_callback )

Register a User DCACHE callback for Invalidate.

Note

The function is only available if USE_HAL_DCACHE_REGISTER_CALLBACKS = 1.

Parameters :

  • hdcache – Pointer to a hal_dcache_handle_t structure that contains the handle information for the specified DCACHE instance.

  • p_callback – Pointer to the hal_dcache_cb_t Callback function.

Return values :

  • HAL_OK – Callback registered successfully.

  • HAL_INVALID_PARAM – p_callback pointer is NULL.

hal_status_t HAL_DCACHE_RegisterCleanByAddrCallback ( hal_dcache_handle_t * hdcache , hal_dcache_cb_t p_callback )

Register a User DCACHE callback for CleanByAddr.

Note

The function is only available if USE_HAL_DCACHE_REGISTER_CALLBACKS = 1.

Parameters :

  • hdcache – Pointer to a hal_dcache_handle_t structure that contains the handle information for the specified DCACHE instance.

  • p_callback – Pointer to the hal_dcache_cb_t Callback function.

Return values :

  • HAL_OK – Callback registered successfully.

  • HAL_INVALID_PARAM – p_callback pointer is NULL.

hal_status_t HAL_DCACHE_RegisterInvalidateByAddrCallback ( hal_dcache_handle_t * hdcache , hal_dcache_cb_t p_callback )

Register a User DCACHE callback for InvalidateByAddr.

Note

The function is only available if USE_HAL_DCACHE_REGISTER_CALLBACKS = 1.

Parameters :

  • hdcache – Pointer to a hal_dcache_handle_t structure that contains the handle information for the specified DCACHE instance.

  • p_callback – Pointer to the hal_dcache_cb_t Callback function.

Return values :

  • HAL_OK – Callback registered successfully.

  • HAL_INVALID_PARAM – p_callback pointer is NULL.

hal_status_t HAL_DCACHE_RegisterCleanInvalidByAddrCallback ( hal_dcache_handle_t * hdcache , hal_dcache_cb_t p_callback )

Register a User DCACHE callback for CleanInvalidByAddr.

Note

The function is only available if USE_HAL_DCACHE_REGISTER_CALLBACKS = 1.

Parameters :

  • hdcache – Pointer to a hal_dcache_handle_t structure that contains the handle information for the specified DCACHE instance.

  • p_callback – Pointer to the hal_dcache_cb_t Callback function.

Return values :

  • HAL_OK – Callback registered successfully.

  • HAL_INVALID_PARAM – p_callback pointer is NULL.

State functions

group DCACHE_Exported_Functions_Group8

The function is :

Functions

hal_dcache_state_t HAL_DCACHE_GetState ( const hal_dcache_handle_t * hdcache )

Get the DCACHE handle state.

Parameters :

hdcache – Pointer to a hal_dcache_handle_t structure that contains the handle information for the specified DCACHE instance.

Return values :

  • HAL_DCACHE_STATE_RESET – DCACHE driver not initialized and not started.

  • HAL_DCACHE_STATE_IDLE – DCACHE driver initialized and not started.

  • HAL_DCACHE_STATE_ACTIVE – DCACHE driver initialized and started.

  • HAL_DCACHE_STATE_MAINTENANCE – DCACHE driver initialized, started and a maintenance operation is ongoing.

Error functions

group DCACHE_Exported_Functions_Group9

This section permits to get in runtime the last error codes of the peripheral DCACHE.

Functions

uint32_t HAL_DCACHE_GetLastErrorCodes ( const hal_dcache_handle_t * hdcache )

Get the DCACHE last error codes.

Parameters :

hdcache – Pointer to a hal_dcache_handle_t structure that contains the handle information for the specified DCACHE instance.

Return values :

  • HAL_DCACHE_ERROR_NONE – No error.

  • HAL_DCACHE_ERROR_EVICTION_CLEAN – Error due to line eviction or clean operation.

Set/Get user data functions

group DCACHE_Exported_Functions_Group10

This section provides functions allowing to Set and Get user data:

Functions

void HAL_DCACHE_SetUserData ( hal_dcache_handle_t * hdcache , const void * p_user_data )

Store the user data into the DCACHE handle.

Parameters :

  • hdcache – Pointer to a hal_dcache_handle_t structure that contains the handle information for the specified DCACHE instance.

  • p_user_data – Pointer to the user data.

const void * HAL_DCACHE_GetUserData ( const hal_dcache_handle_t * hdcache )

Retrieve the user data from the DCACHE handle.

Parameters :

hdcache – Pointer to a hal_dcache_handle_t structure that contains the handle information for the specified DCACHE instance.

Return values :

Pointer – to the user data.