| CMSIS-Driver Version 2.02 Peripheral Interface for Middleware and Application Code

- CMSIS
- CORE
- Driver
- DSP
- RTOS API
- Pack
- SVD

- Main Page
- Usage and Description
- Reference

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Content | Data Structures | Typedefs | Functions
Flash Interface

Driver API for Flash Device Interface (Driver_Flash.h) More...

## Content
| Flash Events
| The Flash driver generates call back events that are notified via the function ARM_Flash_SignalEvent.

## Data Structures
struct | ARM_FLASH_SECTOR
| Flash Sector information. More...
struct | ARM_FLASH_INFO
| Flash information. More...
struct | ARM_DRIVER_FLASH
| Access structure of the Flash Driver. More...
struct | ARM_FLASH_CAPABILITIES
| Flash Driver Capabilities. More...
struct | ARM_FLASH_STATUS
| Flash Status. More...

## Typedefs
typedef void(* | ARM_Flash_SignalEvent_t )(uint32_t event)
| Pointer to ARM_Flash_SignalEvent : Signal Flash Event.

## Functions
ARM_DRIVER_VERSION | ARM_Flash_GetVersion (void)
| Get driver version.
ARM_FLASH_CAPABILITIES | ARM_Flash_GetCapabilities (void)
| Get driver capabilities.
int32_t | ARM_Flash_Initialize (ARM_Flash_SignalEvent_t cb_event)
| Initialize the Flash Interface.
int32_t | ARM_Flash_Uninitialize (void)
| De-initialize the Flash Interface.
int32_t | ARM_Flash_PowerControl (ARM_POWER_STATE state)
| Control the Flash interface power.
int32_t | ARM_Flash_ReadData (uint32_t addr, void *data, uint32_t cnt)
| Read data from Flash.
int32_t | ARM_Flash_ProgramData (uint32_t addr, const void *data, uint32_t cnt)
| Program data to Flash.
int32_t | ARM_Flash_EraseSector (uint32_t addr)
| Erase Flash Sector.
int32_t | ARM_Flash_EraseChip (void)
| Erase complete Flash. Optional function for faster full chip erase.
ARM_FLASH_STATUS | ARM_Flash_GetStatus (void)
| Get Flash status.
ARM_FLASH_INFO * | ARM_Flash_GetInfo (void)
| Get Flash information.
void | ARM_Flash_SignalEvent (uint32_t event)
| Signal Flash event.

## Description

Driver API for Flash Device Interface (Driver_Flash.h)

NOR Flash is the preferred technology for embedded applications requiring a discrete non-volatile memory device. The low read latency characteristic of NOR Flash devices allow direct code execution and to store data in a single memory product. Wikipedia offers more information about the Flash Memories, including NOR.

Flash Structure

Simplified NOR Flash Schematic

Flash API

The following header files define the Application Programming Interface (API) for the Flash interface:

- Driver_Flash.h : Driver API for Flash Device Interface

Driver Functions

The driver functions are published in the access struct as explained in Driver Functions

- ARM_DRIVER_FLASH : access struct for Flash driver functions

## Data Structure Documentation

struct ARM_FLASH_SECTOR

Flash Sector information.

Specifies sector start and end address.

Element of:

- ARM_FLASH_INFO structure

Data Fields
uint32_t | end | Sector End address (start+size-1)
uint32_t | start | Sector Start address.

struct ARM_FLASH_INFO

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
uint8_t | erased_value | Contents of erased memory (usually 0xFF)
uint32_t | page_size | Optimal programming page size in bytes.
uint32_t | program_unit | Smallest programmable unit in bytes.
uint32_t | sector_count | Number of sectors.
ARM_FLASH_SECTOR * | sector_info | Sector layout information (NULL=Uniform sectors)
uint32_t | sector_size | Uniform sector size in bytes (0=sector_info used)

struct ARM_DRIVER_FLASH

Access structure of the Flash Driver.

The functions of the Flash driver are accessed by function pointers exposed by this structure. Refer to 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:

- Driver_Flash0 is the name of the access struct of the first instance (no. 0).
- Driver_Flash1 is the name of the access struct of the second instance (no. 1).

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.

### Data Fields
ARM_DRIVER_VERSION(* | GetVersion )(void)
| Pointer to ARM_Flash_GetVersion : Get driver version.
ARM_FLASH_CAPABILITIES(* | GetCapabilities )(void)
| Pointer to ARM_Flash_GetCapabilities : Get driver capabilities.
int32_t(* | Initialize )(ARM_Flash_SignalEvent_t cb_event)
| Pointer to ARM_Flash_Initialize : Initialize Flash Interface.
int32_t(* | Uninitialize )(void)
| Pointer to ARM_Flash_Uninitialize : De-initialize Flash Interface.
int32_t(* | PowerControl )(ARM_POWER_STATE state)
| Pointer to ARM_Flash_PowerControl : Control Flash Interface Power.
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.
int32_t(* | EraseSector )(uint32_t addr)
| Pointer to ARM_Flash_EraseSector : Erase Flash Sector.
int32_t(* | EraseChip )(void)
| Pointer to ARM_Flash_EraseChip : Erase complete Flash.
ARM_FLASH_STATUS(* | GetStatus )(void)
| Pointer to ARM_Flash_GetStatus : Get Flash status.
ARM_FLASH_INFO *(* | GetInfo )(void)
| Pointer to ARM_Flash_GetInfo : Get Flash information.

#### Field Documentation

int32_t(* EraseChip)(void)

Pointer to ARM_Flash_EraseChip : Erase complete Flash.

int32_t(* EraseSector)(uint32_t addr)

Pointer to ARM_Flash_EraseSector : Erase Flash Sector.

ARM_FLASH_CAPABILITIES(* GetCapabilities)(void)

Pointer to ARM_Flash_GetCapabilities : Get driver capabilities.

ARM_FLASH_INFO*(* GetInfo)(void)

Pointer to ARM_Flash_GetInfo : Get Flash information.

ARM_FLASH_STATUS(* GetStatus)(void)

Pointer to ARM_Flash_GetStatus : Get Flash status.

ARM_DRIVER_VERSION(* GetVersion)(void)

Pointer to ARM_Flash_GetVersion : Get driver version.

int32_t(* Initialize)(ARM_Flash_SignalEvent_t cb_event)

Pointer to ARM_Flash_Initialize : Initialize Flash Interface.

int32_t(* PowerControl)(ARM_POWER_STATE state)

Pointer to ARM_Flash_PowerControl : Control Flash Interface Power.

int32_t(* ProgramData)(uint32_t addr, const void *data, uint32_t cnt)

Pointer to ARM_Flash_ProgramData : Program data to Flash.

int32_t(* ReadData)(uint32_t addr, void *data, uint32_t cnt)

Pointer to ARM_Flash_ReadData : Read data from Flash.

int32_t(* Uninitialize)(void)

Pointer to ARM_Flash_Uninitialize : De-initialize Flash Interface.

struct ARM_FLASH_CAPABILITIES

Flash Driver Capabilities.

A Flash driver can be implemented with different capabilities. The bitfield members 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:

- ARM_Flash_GetCapabilities

Data Fields
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 | event_ready: 1 | Signal Flash Ready event.

struct ARM_FLASH_STATUS

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:

- ARM_Flash_GetStatus

Data Fields
uint32_t | busy: 1 | Flash busy flag.
uint32_t | error: 1 | Read/Program/Erase error flag (cleared on start of next operation)

## Typedef Documentation

ARM_Flash_SignalEvent_t

Pointer to ARM_Flash_SignalEvent : Signal Flash Event.

Provides the typedef for the callback function ARM_Flash_SignalEvent.

Parameter for:

- ARM_Flash_Initialize

## Function Documentation

int32_t ARM_Flash_EraseChip | ( | void |  | ) |

Erase complete Flash. Optional function for faster full chip erase.

Returns
  Status Error Codes

This optional function 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 this functions returns the error value ARM_DRIVER_ERROR_UNSUPPORTED. Function ARM_Flash_GetCapabilities reports if the function ARM_Flash_EraseChip is supported.

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_EraseSector | ( | uint32_t | addr | ) |

Erase Flash Sector.

Parameters

  [in] | addr | Sector address

Returns
  Status Error Codes

This function 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.

ARM_FLASH_CAPABILITIES ARM_Flash_GetCapabilities | ( | void |  | ) |

Get driver capabilities.

Returns
  ARM_FLASH_CAPABILITIES

Retrieves information about capabilities in this driver implementation. The bitfield members 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:

extern ARM_DRIVER_FLASH Driver_Flash0;
ARM_DRIVER_FLASH *drv_info;
void read_capabilities (void) {
ARM_FLASH_CAPABILITIES drv_capabilities;
drv_info = &Driver_Flash0;
drv_capabilities = drv_info->GetCapabilities ();
// interrogate capabilities
}

ARM_FLASH_INFO * ARM_Flash_GetInfo | ( | void |  | ) |

Get Flash information.

Returns
  Pointer to Flash information ARM_FLASH_INFO

Retrieves information about the Flash device.

ARM_FLASH_STATUS ARM_Flash_GetStatus | ( | void |  | ) |

Get Flash status.

Returns
  Flash status ARM_FLASH_STATUS

Retrieves current Flash interface status.

ARM_DRIVER_VERSION ARM_Flash_GetVersion | ( | void |  | ) |

Get driver version.

Returns
  ARM_DRIVER_VERSION

Returns version information of the driver implementation in ARM_DRIVER_VERSION

- API version is the version of the CMSIS-Driver specification used to implement this driver.
- Driver version is source code version of the actual driver implementation.

Example:

extern ARM_DRIVER_FLASH Driver_Flash0;
ARM_DRIVER_FLASH *drv_info;
void read_version (void) {
ARM_DRIVER_VERSION version;
drv_info = &Driver_Flash0;
version = drv_info->GetVersion ();
if (version.api < 0x10A) { // requires at minimum API version 1.10 or higher
// error handling
return;
}
}

int32_t ARM_Flash_Initialize | ( | ARM_Flash_SignalEvent_t | cb_event | ) |

Initialize the Flash Interface.

Parameters

  [in] | cb_event | Pointer to ARM_Flash_SignalEvent

Returns
  Status Error Codes

The function initializes the Flash interface. It is called when the middleware component starts operation.

The function performs the following operations:

- Initializes the resources needed for the Flash interface.
- Registers the ARM_Flash_SignalEvent callback function.

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:

- see Flash Interface - Driver Functions

int32_t ARM_Flash_PowerControl | ( | ARM_POWER_STATE | state | ) |

Control the Flash interface power.

Parameters

  [in] | state | Power state

Returns
  Status Error Codes

Control Flash Interface Power.

int32_t ARM_Flash_ProgramData | ( | uint32_t | addr,
|  | const void * | data,
|  | uint32_t | cnt
| ) |  |

Program data to Flash.

Parameters

  [in] | addr | Data address.
  [in] | data | Pointer to a buffer containing the data to be programmed to Flash.
  [in] | cnt | Number of data items to program.

Returns
  number of data items programmed or Status Error Codes

This function 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:

- When the operation is non-blocking (typically) then the function only starts the operation and returns with zero number of data items programmed. 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.
- When the operation is blocking then the function returns after the data is programmed and returns the number of data items programmed.

int32_t ARM_Flash_ReadData | ( | uint32_t | addr,
|  | void * | data,
|  | uint32_t | cnt
| ) |  |

Read data from Flash.

Parameters

  [in] | addr | Data address.
  [out] | data | Pointer to a buffer storing the data read from Flash.
  [in] | cnt | Number of data items to read.

Returns
  number of data items read or Status Error Codes

This function 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:

- When the operation is non-blocking (typical for SPI Flash) then the function only starts the operation and returns with zero number of data items read. 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.
- When the operation is blocking (typical for memory mapped Flash) then the function returns after the data is read and returns the number of data items read.

void ARM_Flash_SignalEvent | ( | uint32_t | event | ) |

Signal Flash event.

Parameters

  [in] | event | Event notification mask

Returns
  none

The function ARM_Flash_SignalEvent notifies the application of the Flash Events and it is registered by the function ARM_Flash_Initialize. The function is called automatically after read/program/erase operation completes. The function ARM_Flash_GetCapabilities returns information about the implemented optional events in a driver.

The argument event represents the notification mask of the events. Each event is coded in a separate bit and therefore it is possible to signal multiple events in the event call back function. The following call back notifications are generated:

Bit | Event | Description
--- | --- | ---
0 | ARM_FLASH_EVENT_READY | Occurs after read/program/erase operation completes.
1 | ARM_FLASH_EVENT_ERROR | Occurs together with ARM_FLASH_EVENT_READY when operation completes with errors.

int32_t ARM_Flash_Uninitialize | ( | void |  | ) |

De-initialize the Flash Interface.

Returns
  Status Error Codes

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.