Driver API for Flash Device Interface (Driver_Flash.h) More...
Driver API for Flash Device Interface (Driver_Flash.h)
Flash devices based on NOR memory cells are the preferred technology for embedded applications requiring a discrete non-volatile memory device. The low read latency characteristic of these Flash devices allow a direct code execution (XIP) and data storage in a single memory product.
Flash API
The Flash API provides a generic API suitable for Flashes with NOR memory cells independent from the actual interface to the MCU (memory bus, SPI, ...). SPI flashes are typically not named NOR flashes but have usually same flash cell properties.
The following header files define the Application Programming Interface (API) for the Flash interface:
Driver Functions
The driver functions are published in the access struct as explained in Common Driver Functions
A typical setup sequence for the driver is shown below:
Example Code:
#include "cmsis_os2.h"
osThreadId_t Flash_Thread_Id;
void Flash_Callback(uint32_t event)
{
osThreadFlagsSet(Flash_Thread_Id, 1U);
}
__breakpoint(0);
}
}
void Flash_Thread (void *argument)
{
} else {
}
uint8_t buf[256U];
osThreadFlagsWait (1U, osFlagsWaitAny, 100U);
} else {
osDelay(100U);
}
}
Flash Sector information.
Specifies sector start and end address.
Element of:
Flash information.
Stores the characteristics of a Flash device. This includes sector layout, programming size and a default value for erased memory. This information can be obtained from the Flash device datasheet and is used by the middleware in order to properly interact with the Flash device.
Sector layout is described by specifying the sector_info which points to an array of sector information (start and end address) and by specifying the sector_count which defines the number of sectors. The element sector_size is not used in this case and needs to be 0. Flash sectors need not to be aligned continuously. Gaps are allowed in the device memory space in order to reserve sectors for other usage (for example application code).
When the device has uniform sector size than the sector layout can be described by specifying the sector_size which defines the size of a single sector and by specifying the sector_count which defines the number of sectors. The element sector_info is not used in this case and needs to be NULL.
The smallest programmable unit within a sector is specified by the program_unit. It defines the granularity for programming data.
Optimal programming page size is specified by the page_size and defines the amount of data that should be programmed in one step to achieve maximum programming speed.
Contents of erased memory is specified by the erased_value and is typically 0xFF. This value can be used before erasing a sector to check if the sector is blank and erase can be skipped.
Data Fields ARM_FLASH_SECTOR * sector_info Sector layout information (NULL=Uniform sectors) uint32_t sector_count Number of sectors. uint32_t sector_size Uniform sector size in bytes (0=sector_info used) uint32_t page_size Optimal programming page size in bytes. uint32_t program_unit Smallest programmable unit in bytes. uint8_t erased_value Contents of erased memory (usually 0xFF) uint8_t reserved[3] Reserved (must be zero)Access structure of the Flash Driver.
The functions of the Flash driver are accessed by function pointers exposed by this structure. Refer to Common Driver Functions for overview information.
Each instance of a Flash interface provides such an access structure. The instance is identified by a postfix number in the symbol name of the access structure, for example:
A middleware configuration setting allows connecting the middleware to a specific driver instance Driver_Flashn. The default is 0, which connects a middleware to the first instance of a driver.
int32_t(* ReadData)(uint32_t addr, void *data, uint32_t cnt)Pointer to ARM_Flash_ReadData : Read data from Flash.
int32_t(* ProgramData)(uint32_t addr, const void *data, uint32_t cnt)Pointer to ARM_Flash_ProgramData : Program data to Flash.
struct ARM_FLASH_CAPABILITIESFlash Driver Capabilities.
A Flash driver can be implemented with different capabilities. The data fields of this struct encode the capabilities implemented by this driver.
The element event_ready indicates that the driver is able to generate the ARM_FLASH_EVENT_READY event. In case that this event is not available it is possible to poll the driver status by calling the ARM_Flash_GetStatus and check the busy flag.
The element data_width specifies the data access size and also defines the data type (uint8_t, uint16_t or uint32_t) for the data parameter in ARM_Flash_ReadData and ARM_Flash_ProgramData functions.
The element erase_chip specifies that the ARM_Flash_EraseChip function is supported. Typically full chip erase is much faster than erasing the whole device sector per sector.
Returned by:
Data Fields uint32_t event_ready: 1 Signal Flash Ready event. uint32_t data_width: 2 Data width: 0=8-bit, 1=16-bit, 2=32-bit. uint32_t erase_chip: 1 Supports EraseChip operation. uint32_t reserved: 28 Reserved (must be zero)Flash Status.
Structure with information about the status of the Flash.
The flag busy indicates that the driver is busy executing read/program/erase operation.
The flag error flag is cleared on start of read/program/erase operation and is set at the end of the current operation in case of error.
Returned by:
Data Fields uint32_t busy: 1 Flash busy flag. uint32_t error: 1 Read/Program/Erase error flag (cleared on start of next operation) uint32_t reserved: 30Get driver version.
The function ARM_Flash_GetVersion returns version information of the driver implementation in ARM_DRIVER_VERSION
Example:
void read_version (void) {
drv_info = &Driver_Flash0;
if(version.
api< 0x10A) {
return;
}
}
Get driver capabilities.
The function ARM_Flash_GetCapabilities returns information about capabilities in this driver implementation. The data fields of the struct ARM_FLASH_CAPABILITIES encode various capabilities, for example if a hardware is able to create signal events using the ARM_Flash_SignalEvent callback function.
Example:
void read_capabilities (void) {
drv_info = &Driver_Flash0;
}
Initialize the Flash Interface.
The function ARM_Flash_Initialize initializes the Flash interface. It is called when the middleware component starts operation.
The function performs the following operations:
The parameter cb_event is a pointer to the ARM_Flash_SignalEvent callback function; use a NULL pointer when no callback signals are required.
Example:
De-initialize the Flash Interface.
The function ARM_Flash_Uninitialize de-initializes the resources of Flash interface.
It is called when the middleware component stops operation and releases the software resources used by the interface.
Control the Flash interface power.
The function ARM_Flash_PowerControl operates the power modes of the Flash interface.
The parameter state can have the following values:
Refer to Function Call Sequence for more information.
int32_t ARM_Flash_ReadData ( uint32_t addr, void * data, uint32_t cnt )Read data from Flash.
This function ARM_Flash_ReadData reads data from the Flash device.
The parameter addr specifies the address from where to read data (needs to be aligned to data type size).
The parameter data specifies the pointer to a buffer storing the data read. The data type is uint8_t, uint16_t or uint32_t and is specified by the data_width in ARM_FLASH_CAPABILITIES.
The parameter cnt specifies the number of data items to read.
The function executes in the following ways:
Program data to Flash.
This function ARM_Flash_ProgramData programs data to the Flash device.
The parameter addr specifies the address to where to program data (needs to be aligned to program_unit specified in ARM_FLASH_INFO).
The parameter data specifies the pointer to a buffer containing data to be programmed. The data type is uint8_t, uint16_t or uint32_t and is specified by the data_width in ARM_FLASH_CAPABILITIES.
The parameter cnt specifies the number of data items to program (data size needs to be a multiple of program_unit).
The function executes in the following ways:
Erase Flash Sector.
This function ARM_Flash_EraseSector erases a flash sector specified by the parameter adr (points to start of the sector).
The function is non-blocking and returns as soon as the driver has started the operation. When the operation is completed the ARM_FLASH_EVENT_READY event is generated (if supported and reported by ARM_Flash_GetCapabilities). In case of errors the ARM_FLASH_EVENT_ERROR event is generated at the same time. Progress of the operation can also be monitored by calling the ARM_Flash_GetStatus function and checking the busy flag.
int32_t ARM_Flash_EraseChip ( void )Erase complete Flash. Optional function for faster full chip erase.
The optional function ARM_Flash_EraseChip erases the complete device. If the device does not support global erase or only a portion of the Flash memory space is used for storing files, then the functions returns the error value ARM_DRIVER_ERROR_UNSUPPORTED. The data field eras_chip = 1 of the structure ARM_FLASH_CAPABILITIES encodes that ARM_Flash_EraseChip is supported. The field can be verified with the function ARM_Flash_GetCapabilities.
The function is non-blocking and returns as soon as the driver has started the operation. When the operation is completed, the ARM_FLASH_EVENT_READY event is generated (if supported and reported by ARM_Flash_GetCapabilities). In case of errors, the ARM_FLASH_EVENT_ERROR event is generated at the same time. Progress of the operation can also be monitored by calling the ARM_Flash_GetStatus function and checking the busy flag.
See also:
Get Flash status.
The function ARM_Flash_GetStatus returns the current Flash interface status stored in the structure ARM_FLASH_STATUS.
Get Flash information.
The function ARM_Flash_GetInfo returns information about the Flash device.
void ARM_Flash_SignalEvent ( uint32_t event )Signal Flash event.
The function ARM_Flash_SignalEvent is a callback function registered by the function ARM_Flash_Initialize. The function is called automatically after read/program/erase operation completes.
The parameter event indicates one or more events that occurred during driver operation. Each event is coded in a separate bit and therefore it is possible to signal multiple events in the event call back function.
Not every event is necessarily generated by the driver. This depends on the implemented capabilities stored in the data fields of the structure ARM_FLASH_CAPABILITIES, which can be retrieved with the function ARM_Flash_GetCapabilities.
The following events can be generated:
See also:
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4