![]() |
CMSIS Driver
Version 1.10 - Preliminary
Middleware Driver API for microcontroller peripherals
|
Driver API for NAND Flash Device Interface (Driver_NAND.h) More...
Data Structures | |
struct | ARM_DRIVER_NAND |
Access structure of the NAND Driver. More... | |
struct | ARM_NAND_CAPABILITIES |
NAND Driver Capabilities. More... | |
struct | ARM_NAND_DEVICE |
NAND Flash Device information. More... | |
struct | ARM_NAND_PAGE_LAYOUT |
NAND Page Layout configuration. More... | |
struct | ARM_NAND_PAGE_LAYOUT.spare |
Typedefs | |
typedef void(* | ARM_NAND_SignalEvent_t )(uint32_t dev_num) |
Pointer to ARM_NAND_SignalEvent : Signal NAND Event. | |
Functions | |
ARM_DRV_VERSION | ARM_NAND_GetVersion (void) |
Get driver version. | |
ARM_NAND_CAPABILITIES | ARM_NAND_GetCapabilities (void) |
Get driver capabilities. | |
ARM_NAND_STATUS | ARM_NAND_Initialize (ARM_NAND_SignalEvent_t cb_event, ARM_NAND_DEVICE *ptr_device, uint32_t num_devices) |
Initialize NAND Interface. | |
ARM_NAND_STATUS | ARM_NAND_Uninitialize (void) |
De-initialize NAND Interface. | |
ARM_NAND_STATUS | ARM_NAND_PowerControl (ARM_POWER_STATE state) |
Control the NAND interface power. | |
ARM_NAND_STATUS | ARM_NAND_ResetDevice (uint32_t dev_num) |
Reset a NAND device. | |
ARM_NAND_STATUS | ARM_NAND_ReadID (uint32_t dev_num, uint8_t addr, uint8_t *buf, uint32_t len) |
Read NAND device ID. | |
ARM_NAND_STATUS | ARM_NAND_ReadParamPage (uint32_t dev_num, uint32_t col, uint8_t *buf, uint32_t len) |
Read NAND parameter page. | |
ARM_NAND_STATUS | ARM_NAND_ReadPage (uint32_t dev_num, uint32_t row, uint32_t col, uint8_t *buf, uint32_t len) |
Read data from NAND page. | |
ARM_NAND_STATUS | ARM_NAND_WritePage (uint32_t dev_num, uint32_t row, uint32_t col, const uint8_t *buf, uint32_t len) |
Write data to NAND page. | |
ARM_NAND_STATUS | ARM_NAND_CopyPage (uint32_t dev_num, uint32_t row_src, uint32_t row_dst, uint32_t row_cnt) |
Copy pages within NAND device. | |
ARM_NAND_STATUS | ARM_NAND_EraseBlock (uint32_t dev_num, uint32_t row) |
Erase blocks in NAND device. | |
ARM_NAND_STATUS | ARM_NAND_ReadStatus (uint32_t dev_num, uint8_t *stat) |
Read NAND device status. | |
void | ARM_NAND_SignalEvent (uint32_t dev_num) |
Signal NAND event. Callback function. | |
Driver API for NAND Flash Device Interface (Driver_NAND.h)
NAND devices are a type of non-volatile storage and do not require power to hold data. NAND devices, such as hard disks or memory cards, are accessed in blocks. Each block consists of a number of pages. Refer to ARM_NAND_PAGE_LAYOUT for details. Wikipedia offers more information about the Flash Memories, including NAND.
The following header files define the Application Programming Interface (API) for the NAND interface:
The driver implementation is a typical part of the Device Family Pack (DFP) that supports the peripherals of the microcontroller family.
The driver functions are published in the access struct as explained in Driver Functions
A typical setup sequence for the driver is shown below:
Example Code:
struct ARM_DRIVER_NAND |
Access structure of the NAND Driver.
The functions of the NAND driver are accessed by function pointers exposed by this structure. Refer to Driver Functions for overview information.
Each instance of an NAND 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 ARM_DRIVER_NANDn. The default is 0, which connects a middleware to the first instance of a driver.
Data Fields | |
ARM_DRV_VERSION(* | GetVersion )(void) |
Pointer to ARM_NAND_GetVersion : Get driver version. | |
ARM_NAND_CAPABILITIES(* | GetCapabilities )(void) |
Pointer to ARM_NAND_GetCapabilities : Get driver capabilities. | |
ARM_NAND_STATUS(* | Initialize )(ARM_NAND_SignalEvent_t cb_event, ARM_NAND_DEVICE *ptr_device, uint32_t num_devices) |
Pointer to ARM_NAND_Initialize : Initialize NAND Interface. | |
ARM_NAND_STATUS(* | Uninitialize )(void) |
Pointer to ARM_NAND_Uninitialize : De-initialize NAND Interface. | |
ARM_NAND_STATUS(* | PowerControl )(ARM_POWER_STATE state) |
Pointer to ARM_NAND_PowerControl : Control NAND Interface Power. | |
ARM_NAND_STATUS(* | ResetDevice )(uint32_t dev_num) |
Pointer to ARM_NAND_ResetDevice : Reset NAND Device. | |
ARM_NAND_STATUS(* | ReadID )(uint32_t dev_num, uint8_t addr, uint8_t *buf, uint32_t len) |
Pointer to ARM_NAND_ReadID : Read Device ID from NAND. | |
ARM_NAND_STATUS(* | ReadParamPage )(uint32_t dev_num, uint32_t col, uint8_t *buf, uint32_t len) |
Pointer to ARM_NAND_ReadParamPage : Read parameter page from NAND. | |
ARM_NAND_STATUS(* | ReadPage )(uint32_t dev_num, uint32_t row, uint32_t col, uint8_t *buf, uint32_t len) |
Pointer to ARM_NAND_ReadPage : Read data from NAND Page. | |
ARM_NAND_STATUS(* | WritePage )(uint32_t dev_num, uint32_t row, uint32_t col, const uint8_t *buf, uint32_t len) |
Pointer to ARM_NAND_WritePage : Write data to NAND Page. | |
ARM_NAND_STATUS(* | CopyPage )(uint32_t dev_num, uint32_t row_src, uint32_t row_dst, uint32_t row_cnt) |
Pointer to ARM_NAND_CopyPage : Copy pages in NAND Device. | |
ARM_NAND_STATUS(* | EraseBlock )(uint32_t dev_num, uint32_t row) |
Pointer to ARM_NAND_EraseBlock : Erase block in NAND Device. | |
ARM_NAND_STATUS(* | ReadStatus )(uint32_t dev_num, uint8_t *stat) |
Pointer to ARM_NAND_ReadStatus : Read Device status from NAND. | |
ARM_NAND_STATUS(* CopyPage)(uint32_t dev_num, uint32_t row_src, uint32_t row_dst, uint32_t row_cnt) |
Pointer to ARM_NAND_CopyPage : Copy pages in NAND Device.
ARM_NAND_STATUS(* EraseBlock)(uint32_t dev_num, uint32_t row) |
Pointer to ARM_NAND_EraseBlock : Erase block in NAND Device.
ARM_NAND_CAPABILITIES(* GetCapabilities)(void) |
Pointer to ARM_NAND_GetCapabilities : Get driver capabilities.
ARM_DRV_VERSION(* GetVersion)(void) |
Pointer to ARM_NAND_GetVersion : Get driver version.
ARM_NAND_STATUS(* Initialize)(ARM_NAND_SignalEvent_t cb_event, ARM_NAND_DEVICE *ptr_device, uint32_t num_devices) |
Pointer to ARM_NAND_Initialize : Initialize NAND Interface.
ARM_NAND_STATUS(* PowerControl)(ARM_POWER_STATE state) |
Pointer to ARM_NAND_PowerControl : Control NAND Interface Power.
ARM_NAND_STATUS(* ReadID)(uint32_t dev_num, uint8_t addr, uint8_t *buf, uint32_t len) |
Pointer to ARM_NAND_ReadID : Read Device ID from NAND.
ARM_NAND_STATUS(* ReadPage)(uint32_t dev_num, uint32_t row, uint32_t col, uint8_t *buf, uint32_t len) |
Pointer to ARM_NAND_ReadPage : Read data from NAND Page.
ARM_NAND_STATUS(* ReadParamPage)(uint32_t dev_num, uint32_t col, uint8_t *buf, uint32_t len) |
Pointer to ARM_NAND_ReadParamPage : Read parameter page from NAND.
ARM_NAND_STATUS(* ReadStatus)(uint32_t dev_num, uint8_t *stat) |
Pointer to ARM_NAND_ReadStatus : Read Device status from NAND.
ARM_NAND_STATUS(* ResetDevice)(uint32_t dev_num) |
Pointer to ARM_NAND_ResetDevice : Reset NAND Device.
ARM_NAND_STATUS(* Uninitialize)(void) |
Pointer to ARM_NAND_Uninitialize : De-initialize NAND Interface.
ARM_NAND_STATUS(* WritePage)(uint32_t dev_num, uint32_t row, uint32_t col, const uint8_t *buf, uint32_t len) |
Pointer to ARM_NAND_WritePage : Write data to NAND Page.
struct ARM_NAND_CAPABILITIES |
NAND Driver Capabilities.
An NAND driver can be implemented with different capabilities. The bitfield members of this struct encode the capabilities implemented by this driver.
Returned by:
struct ARM_NAND_DEVICE |
NAND Flash Device information.
Stores the characteristics of a NAND Flash device. This includes the page layout configuration, NAND type, device number (chip select), number of blocks, pages, sectors, and error correction code.
Parameter for:
Data Fields | ||
---|---|---|
uint32_t | block_count | Number of Blocks in Device. |
uint16_t | block_sectors | Number of Sectors per Block. |
uint8_t | col_cycles | Number of Column address cycles. |
uint8_t | device_number | Device number (chip select) |
uint16_t | page_count | Number of Pages per Block. |
ARM_NAND_PAGE_LAYOUT * | page_layout | Page Layout configuration. |
uint8_t | page_sectors | Number of Sectors per Page. |
uint16_t | page_size | Page Size in bytes. |
uint8_t | row_cycles | Number of Row address cycles. |
uint8_t | sw_ecc |
value > 0: error correction code (ECC) encoding/decoding enabled in software: value = 0: Software ECC disabled value = 1: Hamming ECC algorithm enabled in software. |
uint8_t | type | ARM_NAND_TYPE |
struct ARM_NAND_PAGE_LAYOUT |
NAND Page Layout configuration.
Stores the default NAND page layout definition (with sector_inc, spare_inc, and spare_ofs), which contains a Spare area after each sector. The struct ARM_NAND_PAGE_LAYOUT.spare defines the Spare area layout.
The page size is defined as the sum of User area plus Spare area. Each page has a small number of associated "spare" bytes (typically 1/32 of the data size) to store the Error Correction Algorithms (ECC).
The following standard page sizes are available:
Page Size | User + Spare Area |
---|---|
528 | 512 + 16 bytes |
2112 | 2048 + 64 bytes |
4224 | 4096 + 128 bytes |
8448 | 8192 + 256 bytes |
NAND devices require bad block management by the driver software or by a separate controller chip. For example, SD cards have mechanisms that execute wear leveling and bad block management. The memory capacity shrinks as more blocks are marked bad. The block size is a value specified as amount of flash pages.
The following block sizes are available:
Block Size | Pages |
---|---|
8 | 8 |
16 | 16 |
32 | 32 |
64 | 64 |
128 | 128 |
256 | 256 |
Parameter for:
Data Fields | ||
---|---|---|
uint16_t | sector_inc | Column increment till next sector. If page contains multiple sectors, then the first sector always starts at the beginning of the page (byte zero). Second sector starts at sect_inc, third sector at (sect_inc + sect_inc) and so on. |
struct ARM_NAND_PAGE_LAYOUT | spare | Structure spare. |
uint16_t | spare_inc | Column increment till next spare. If page contains multiple sectors, then the first byte of the first spare area is determined by reading spare_ofs value. Location of the first byte of the second spare is (spare_inc + spare_ofs). |
uint16_t | spare_ofs | Spare area offset from beginning of the page. |
struct ARM_NAND_PAGE_LAYOUT.spare |
ARM_NAND_SignalEvent_t |
Pointer to ARM_NAND_SignalEvent : Signal NAND Event.
Provides the typedef for the callback function ARM_NAND_SignalEvent.
Parameter for:
enum ARM_NAND_COMMAND |
Mandatory NAND Flash Commands (ONFI V1.0 or higher)
NAND Flash Commands (ONFI V1.0 and V2.2 mandatory)
Optional NAND Flash Commands (ONFI V1.0 or higher)
Provides standardized values for optional NAND commands.
enum ARM_NAND_STATUS |
NAND Flash Driver Status.
Defines status and error codes returned by most of the NAND driver functions.
Returned by:
enum ARM_NAND_TYPE |
NAND Flash Device Type.
Provides standardized values for defining the NAND type.
Parameter for -ARM_NAND_DEVICE structure
ARM_NAND_STATUS ARM_NAND_CopyPage | ( | uint32_t | dev_num, |
uint32_t | row_src, | ||
uint32_t | row_dst, | ||
uint32_t | row_cnt | ||
) |
Copy pages within NAND device.
[in] | dev_num | Device number |
[in] | row_src | Source row address |
[in] | row_dst | Destination row address |
[in] | row_cnt | Number of pages (rows) to copy |
Copy pages in NAND Device.
ARM_NAND_STATUS ARM_NAND_EraseBlock | ( | uint32_t | dev_num, |
uint32_t | row | ||
) |
Erase blocks in NAND device.
[in] | dev_num | Device number |
[in] | row | Block start row address |
Erase block in NAND device.
ARM_NAND_CAPABILITIES ARM_NAND_GetCapabilities | ( | void | ) |
Get driver capabilities.
Retrieves information about capabilities in this driver implementation. The bitfield members of the struct ARM_NAND_CAPABILITIES encode various capabilities, for example if a hardware supports OneNAND Interface or is able to create signal events using the ARM_NAND_SignalEvent callback function.
Example:
DRV_VERSION ARM_NAND_GetVersion | ( | void | ) |
Get driver version.
Returns version information of the driver implementation in ARM_DRV_VERSION
Example:
ARM_NAND_STATUS ARM_NAND_Initialize | ( | ARM_NAND_SignalEvent_t | cb_event, |
ARM_NAND_DEVICE * | ptr_device, | ||
uint32_t | num_devices | ||
) |
Initialize NAND Interface.
[in] | cb_event | Pointer to ARM_NAND_SignalEvent |
[in] | ptr_device | Pointer to device information |
[in] | num_devices | Number of devices |
The function initializes the NAND 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_NAND_SignalEvent callback function; use a NULL pointer when no callback signals are required.
The parameter ptr_device is a pointer to the ARM_NAND_DEVICE structure that defines the NAND devices.
The parameter num_devices specifies the number of NAND devices.
Example:
ARM_NAND_STATUS ARM_NAND_PowerControl | ( | ARM_POWER_STATE | state | ) |
Control the NAND interface power.
[in] | state | Power state |
Control NAND Interface Power.
ARM_NAND_STATUS ARM_NAND_ReadID | ( | uint32_t | dev_num, |
uint8_t | addr, | ||
uint8_t * | buf, | ||
uint32_t | len | ||
) |
Read NAND device ID.
[in] | dev_num | Device number |
[in] | addr | ID address |
[out] | buf | Buffer for data read from NAND |
[in] | len | Number of bytes to read (buffer length) |
Read Device ID from NAND.
ARM_NAND_STATUS ARM_NAND_ReadPage | ( | uint32_t | dev_num, |
uint32_t | row, | ||
uint32_t | col, | ||
uint8_t * | buf, | ||
uint32_t | len | ||
) |
Read data from NAND page.
[in] | dev_num | Device number |
[in] | row | Row address |
[in] | col | Column address |
[out] | buf | Buffer for data read from NAND |
[in] | len | Number of bytes to read (buffer length) |
Read data from NAND Page.
ARM_NAND_STATUS ARM_NAND_ReadParamPage | ( | uint32_t | dev_num, |
uint32_t | col, | ||
uint8_t * | buf, | ||
uint32_t | len | ||
) |
Read NAND parameter page.
[in] | dev_num | Device number |
[in] | col | Column address |
[out] | buf | Buffer for data read from NAND |
[in] | len | Number of bytes to read (buffer length) |
Read parameter page from NAND.
ARM_NAND_STATUS ARM_NAND_ReadStatus | ( | uint32_t | dev_num, |
uint8_t * | stat | ||
) |
Read NAND device status.
[in] | dev_num | Device number |
[out] | stat | Pointer to store status read from NAND |
Read Device status from NAND.
ARM_NAND_STATUS ARM_NAND_ResetDevice | ( | uint32_t | dev_num | ) |
Reset a NAND device.
[in] | dev_num | Device number |
Reset NAND Device.
void ARM_NAND_SignalEvent | ( | uint32_t | dev_num | ) |
Signal NAND event. Callback function.
[in] | dev_num | Device number Occurs when Program/Erase (WritePage, CopyPage, EraseBlock) completes. |
Signal NAND Event. This callback function is invoked automatically after each read/write operation.
ARM_NAND_STATUS ARM_NAND_Uninitialize | ( | void | ) |
De-initialize NAND Interface.
The function ARM_NAND_Uninitialize de-initializes the resources of NAND interface and sets the peripheral to ARM_POWER_OFF power mode.
It is called when the middleware component stops operation and releases the software resources used by the interface.
ARM_NAND_STATUS ARM_NAND_WritePage | ( | uint32_t | dev_num, |
uint32_t | row, | ||
uint32_t | col, | ||
const uint8_t * | buf, | ||
uint32_t | len | ||
) |
Write data to NAND page.
[in] | dev_num | Device number |
[in] | row | Row address |
[in] | col | Column address |
[out] | buf | Buffer with data to write to NAND |
[in] | len | Number of bytes to write (buffer length) |
Write data to NAND Page.