Flash Adapter. More...

Files
file	ad_flash.h
	Flash adapter API.

Macros
#define	AD_FLASH_ALWAYS_FLUSH_CACHE ((uint32_t) - 1)
	Special base address used to return to the default cache flushing mode. More...

Functions
void	ad_flash_init (void)
	Initialize the flash adapter. More...

size_t	ad_flash_read (uint32_t addr, uint8_t *buf, size_t len)
	Read data from flash memory. More...

size_t	ad_flash_write (uint32_t addr, const uint8_t *buf, size_t size)
	Write data to flash memory. More...

bool	ad_flash_erase_region (uint32_t addr, size_t size)
	Erase a flash memory region. More...

const __STATIC_INLINE void *	ad_flash_get_ptr (uint32_t addr)
	Translate a virtual address to a pointer that directly accesses the corresponding physical flash memory location. More...

int	ad_flash_update_possible (uint32_t addr, const uint8_t *data_to_write, size_t size)
	Check if a flash update can be performed without erasing memory. More...

size_t	ad_flash_erase_size (uint32_t addr)
	Get minimum flash erasable size (sector size) More...

bool	ad_flash_chip_erase_by_addr (uint32_t addr)
	Perform full erase of a specified flash memory. More...

void	ad_flash_lock (void)
	Lock the flash adapter to prevent multiple tasks from accessing the same flash memory simultaneously. More...

void	ad_flash_unlock (void)
	Release lock on flash adapter. More...

void	ad_flash_skip_cache_flushing (uint32_t base, uint32_t size)
	Control cache flushing on modifications to a specified flash region. More...

Detailed Description

Flash Adapter.

Note: The Flash Adapter should only be used with virtual addresses. Never pass physical or zero-based address.

Macro Definition Documentation

◆ AD_FLASH_ALWAYS_FLUSH_CACHE

#define AD_FLASH_ALWAYS_FLUSH_CACHE ((uint32_t) - 1)

Special base address used to return to the default cache flushing mode.

This constant can be used with the ad_flash_skip_cache_flushing() function to reset the cache flushing behavior, so that all flash writes and erases will trigger cache flushing. The constant has the value of the maximum 32-bit unsigned integer, which is used as a sentinel value to indicate the special behavior.

Function Documentation

◆ ad_flash_chip_erase_by_addr()

bool ad_flash_chip_erase_by_addr ( uint32_t addr )

Perform full erase of a specified flash memory.

The flash memory to be erased is specified by providing the corresponding virtual start address.

Parameters

[in] addr The virtual start address of the memory to be erased.

Returns: True, if the memory was successfully erased, false if the virtual start address is invalid.

◆ ad_flash_erase_region()

bool ad_flash_erase_region	(	uint32_t	addr,
		size_t	size
	)

Erase a flash memory region.

This function erases all sectors from the virtual start address addr to addr + size.

Parameters

[in]	addr	The virtual start address of the flash region to be erased.
[in]	size	The number of bytes to erase.

Returns: True, if the erase operation was successful.

Warning: If addr is not sector-aligned, the preceding data of the sector where addr resides will also be erased.; If addr + size is not sector aligned, the whole sector where the addr + size resides will also be erased.

◆ ad_flash_erase_size()

size_t ad_flash_erase_size ( uint32_t addr )

Get minimum flash erasable size (sector size)

This function returns the minimum size that can be erased in flash memory, which corresponds to the sector size.

Parameters

[in] addr The virtual address in flash memory.

Returns: The minimum erasable size in bytes (sector size).

◆ ad_flash_get_ptr()

const __STATIC_INLINE void* ad_flash_get_ptr ( uint32_t addr )

Translate a virtual address to a pointer that directly accesses the corresponding physical flash memory location.

Parameters

[in] addr The virtual address to translate.

Returns: A pointer to the physical memory location corresponding to the given virtual address, or NULL if the virtual address is invalid.

◆ ad_flash_init()

void ad_flash_init ( void )

Initialize the flash adapter.

This function is called by the system on power-up to initialize the flash adapter.

Warning: It should NOT be called by the application, as it is automatically executed at system start-up.

◆ ad_flash_lock()

void ad_flash_lock ( void )

Lock the flash adapter to prevent multiple tasks from accessing the same flash memory simultaneously.

This function gets the flash adapter for exclusive usage, ensuring that only one task can access the flash memory at any given time.

◆ ad_flash_read()

size_t ad_flash_read	(	uint32_t	addr,
		uint8_t *	buf,
		size_t	len
	)

Read data from flash memory.

This function reads a specified number of bytes from flash memory, starting from the virtual address specified in the addr parameter. The contents of the read data will be copied to the destination array pointed by the buf parameter.

Parameters

[in]	addr	The virtual address in flash memory to read data from.
[out]	buf	Pointer to the destination array in System RAM, where the read data will be copied.
[in]	len	The number of bytes to read.

Returns: The number of bytes read from flash memory.

◆ ad_flash_skip_cache_flushing()

void ad_flash_skip_cache_flushing	(	uint32_t	base,
		uint32_t	size
	)

Control cache flushing on modifications to a specified flash region.

This function can be used to enable or disable the triggering of cache flushing when modifications (writes or erases) occur in a specific flash region. Only one such flash region can be defined.

This feature is useful when the programmer knows in advance that a large flash region is going to be updated (e.g. during firmware update). However, flash reads from that region should be avoided, as they might lead to cache incoherency.

Parameters

[in] base Starting offset of the flash region that should not trigger a cache flushing. If

See also: AD_FLASH_ALWAYS_FLUSH_CACHE is passed, selective cache flushing is disabled, regardless of the value of size.

Parameters

[in] size The size of the flash region that should not trigger cache flushing.

Warning: The effect of this function is limited to ad_flash_* layer and higher. Direct use of lower level APIs (e.g. hw_qspi_*, qspi_automode_* etc) will not be affected by the use of this function.

◆ ad_flash_unlock()

void ad_flash_unlock ( void )

Release lock on flash adapter.

Release exclusive access to the flash adapter that was obtained using ad_flash_lock(). This allows other tasks to use the flash adapter.

◆ ad_flash_update_possible()

int ad_flash_update_possible	(	uint32_t	addr,
		const uint8_t *	data_to_write,
		size_t	size
	)

Check if a flash update can be performed without erasing memory.

This function checks if an update to flash memory can be performed without erasing the memory first. An update is possible only if only "0s" need to be written.

Parameters

[in]	addr	The virtual address in flash memory to be checked.
[in]	data_to_write	Pointer to the source data to be written.
[in]	size	The number of bytes to check.

Returns: -1 if an erase is required. Otherwise, a non-negative value representing the number of bytes that do not need to be written (i.e., the data is already the same as the new data). If the return value is 0, then the write operation should start from offset 0, but no erase is needed.

◆ ad_flash_write()

size_t ad_flash_write	(	uint32_t	addr,
		const uint8_t *	buf,
		size_t	size
	)

Write data to flash memory.

This function writes a specified number of bytes from a source data pointer to a virtual address in flash memory. Before writing to the destination virtual address, the memory at that location should be erased.

Parameters

[in]	addr	The virtual address in flash memory where the data will be written.
[in]	buf	Pointer to the source data.
[in]	size	The number of bytes to write.

Returns: The number of bytes written to flash memory.

Warning: The memory at the destination virtual address should be erased before writing to it.

Note: The source data pointer can also point to XiP (Execute-In-Place) mapped memory.

Files

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ AD_FLASH_ALWAYS_FLUSH_CACHE

Function Documentation

◆ ad_flash_chip_erase_by_addr()

◆ ad_flash_erase_region()

◆ ad_flash_erase_size()

◆ ad_flash_get_ptr()

◆ ad_flash_init()

◆ ad_flash_lock()

◆ ad_flash_read()

◆ ad_flash_skip_cache_flushing()

◆ ad_flash_unlock()

◆ ad_flash_update_possible()

◆ ad_flash_write()