CMSIS-Driver  Version 2.02
Peripheral Interface for Middleware and Application Code
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
NAND Interface

Driver API for NAND Flash Device Interface (Driver_NAND.h). More...

Content

 Status Error Codes
 Negative values indicate errors (NAND has specific codes in addition to common Status Error Codes).
 
 NAND Events
 The NAND driver generates call back events that are notified via the function ARM_NAND_SignalEvent.
 
 NAND Flags
 Specify Flag codes.
 
 NAND Control Codes
 Many parameters of the NAND driver are configured using the ARM_NAND_Control function.
 
 NAND ECC Codes
 Specify ECC codes.
 
 NAND Sequence Execution Codes
 Specify execution codes.
 

Data Structures

struct  ARM_NAND_STATUS
 NAND Status. More...
 
struct  ARM_DRIVER_NAND
 Access structure of the NAND Driver. More...
 
struct  ARM_NAND_CAPABILITIES
 NAND Driver Capabilities. More...
 
struct  ARM_NAND_ECC_INFO
 NAND ECC (Error Correction Code) Information. More...
 

Typedefs

typedef void(* ARM_NAND_SignalEvent_t )(uint32_t dev_num, uint32_t event)
 Pointer to ARM_NAND_SignalEvent : Signal NAND Event.
 

Functions

ARM_DRIVER_VERSION ARM_NAND_GetVersion (void)
 Get driver version.
 
ARM_NAND_CAPABILITIES ARM_NAND_GetCapabilities (void)
 Get driver capabilities.
 
int32_t ARM_NAND_Initialize (ARM_NAND_SignalEvent_t cb_event)
 Initialize the NAND Interface.
 
int32_t ARM_NAND_Uninitialize (void)
 De-initialize the NAND Interface.
 
int32_t ARM_NAND_PowerControl (ARM_POWER_STATE state)
 Control the NAND interface power.
 
int32_t ARM_NAND_DevicePower (uint32_t voltage)
 Set device power supply voltage.
 
int32_t ARM_NAND_WriteProtect (uint32_t dev_num, bool enable)
 Control WPn (Write Protect).
 
int32_t ARM_NAND_ChipEnable (uint32_t dev_num, bool enable)
 Control CEn (Chip Enable).
 
int32_t ARM_NAND_GetDeviceBusy (uint32_t dev_num)
 Get Device Busy pin state.
 
int32_t ARM_NAND_SendCommand (uint32_t dev_num, uint8_t cmd)
 Send command to NAND device.
 
int32_t ARM_NAND_SendAddress (uint32_t dev_num, uint8_t addr)
 Send address to NAND device.
 
int32_t ARM_NAND_ReadData (uint32_t dev_num, void *data, uint32_t cnt, uint32_t mode)
 Read data from NAND device.
 
int32_t ARM_NAND_WriteData (uint32_t dev_num, const void *data, uint32_t cnt, uint32_t mode)
 Write data to NAND device.
 
int32_t ARM_NAND_ExecuteSequence (uint32_t dev_num, uint32_t code, uint32_t cmd, uint32_t addr_col, uint32_t addr_row, void *data, uint32_t data_cnt, uint8_t *status, uint32_t *count)
 Execute sequence of operations.
 
int32_t ARM_NAND_AbortSequence (uint32_t dev_num)
 Abort sequence execution.
 
int32_t ARM_NAND_Control (uint32_t dev_num, uint32_t control, uint32_t arg)
 Control NAND Interface.
 
ARM_NAND_STATUS ARM_NAND_GetStatus (uint32_t dev_num)
 Get NAND status.
 
int32_t ARM_NAND_InquireECC (int32_t index, ARM_NAND_ECC_INFO *info)
 Inquire about available ECC.
 
void ARM_NAND_SignalEvent (uint32_t dev_num, uint32_t event)
 Signal NAND event.
 

Description

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. Wikipedia offers more information about the Flash Memories, including NAND.

NAND Structure

 

NAND_Schematics.png
Simplified NAND Flash Schematic

 

NAND API

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.

Driver Functions

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


Data Structure Documentation

struct ARM_NAND_STATUS

NAND Status.

Structure with information about the status of a NAND. The bitfields encode flags for the driver.

Returned by:

Data Fields
uint32_t busy: 1 Driver busy flag.
uint32_t ecc_error: 1 ECC error detected (cleared on next Read/WriteData or ExecuteSequence)
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 a 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:

  • Driver_NAND0 is the name of the access struct of the first instance (no. 0).
  • Driver_NAND1 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_NANDn. 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_NAND_GetVersion : Get driver version.
 
ARM_NAND_CAPABILITIES(* GetCapabilities )(void)
 Pointer to ARM_NAND_GetCapabilities : Get driver capabilities.
 
int32_t(* Initialize )(ARM_NAND_SignalEvent_t cb_event)
 Pointer to ARM_NAND_Initialize : Initialize NAND Interface.
 
int32_t(* Uninitialize )(void)
 Pointer to ARM_NAND_Uninitialize : De-initialize NAND Interface.
 
int32_t(* PowerControl )(ARM_POWER_STATE state)
 Pointer to ARM_NAND_PowerControl : Control NAND Interface Power.
 
int32_t(* DevicePower )(uint32_t voltage)
 Pointer to ARM_NAND_DevicePower : Set device power supply voltage.
 
int32_t(* WriteProtect )(uint32_t dev_num, bool enable)
 Pointer to ARM_NAND_WriteProtect : Control WPn (Write Protect).
 
int32_t(* ChipEnable )(uint32_t dev_num, bool enable)
 Pointer to ARM_NAND_ChipEnable : Control CEn (Chip Enable).
 
int32_t(* GetDeviceBusy )(uint32_t dev_num)
 Pointer to ARM_NAND_GetDeviceBusy : Get Device Busy pin state.
 
int32_t(* SendCommand )(uint32_t dev_num, uint8_t cmd)
 Pointer to ARM_NAND_SendCommand : Send command to NAND device.
 
int32_t(* SendAddress )(uint32_t dev_num, uint8_t addr)
 Pointer to ARM_NAND_SendAddress : Send address to NAND device.
 
int32_t(* ReadData )(uint32_t dev_num, void *data, uint32_t cnt, uint32_t mode)
 Pointer to ARM_NAND_ReadData : Read data from NAND device.
 
int32_t(* WriteData )(uint32_t dev_num, const void *data, uint32_t cnt, uint32_t mode)
 Pointer to ARM_NAND_WriteData : Write data to NAND device.
 
int32_t(* ExecuteSequence )(uint32_t dev_num, uint32_t code, uint32_t cmd, uint32_t addr_col, uint32_t addr_row, void *data, uint32_t data_cnt, uint8_t *status, uint32_t *count)
 Pointer to ARM_NAND_ExecuteSequence : Execute sequence of operations.
 
int32_t(* AbortSequence )(uint32_t dev_num)
 Pointer to ARM_NAND_AbortSequence : Abort sequence execution.
 
int32_t(* Control )(uint32_t dev_num, uint32_t control, uint32_t arg)
 Pointer to ARM_NAND_Control : Control NAND Interface.
 
ARM_NAND_STATUS(* GetStatus )(uint32_t dev_num)
 Pointer to ARM_NAND_GetStatus : Get NAND status.
 
int32_t(* InquireECC )(int32_t index, ARM_NAND_ECC_INFO *info)
 Pointer to ARM_NAND_InquireECC : Inquire about available ECC.
 

Field Documentation

int32_t(* AbortSequence)(uint32_t dev_num)

Pointer to ARM_NAND_AbortSequence : Abort sequence execution.

int32_t(* ChipEnable)(uint32_t dev_num, bool enable)

Pointer to ARM_NAND_ChipEnable : Control CEn (Chip Enable).

int32_t(* Control)(uint32_t dev_num, uint32_t control, uint32_t arg)

Pointer to ARM_NAND_Control : Control NAND Interface.

int32_t(* DevicePower)(uint32_t voltage)

Pointer to ARM_NAND_DevicePower : Set device power supply voltage.

int32_t(* ExecuteSequence)(uint32_t dev_num, uint32_t code, uint32_t cmd, uint32_t addr_col, uint32_t addr_row, void *data, uint32_t data_cnt, uint8_t *status, uint32_t *count)

Pointer to ARM_NAND_ExecuteSequence : Execute sequence of operations.

ARM_NAND_CAPABILITIES(* GetCapabilities)(void)

Pointer to ARM_NAND_GetCapabilities : Get driver capabilities.

int32_t(* GetDeviceBusy)(uint32_t dev_num)

Pointer to ARM_NAND_GetDeviceBusy : Get Device Busy pin state.

ARM_NAND_STATUS(* GetStatus)(uint32_t dev_num)

Pointer to ARM_NAND_GetStatus : Get NAND status.

ARM_DRIVER_VERSION(* GetVersion)(void)

Pointer to ARM_NAND_GetVersion : Get driver version.

int32_t(* Initialize)(ARM_NAND_SignalEvent_t cb_event)

Pointer to ARM_NAND_Initialize : Initialize NAND Interface.

int32_t(* InquireECC)(int32_t index, ARM_NAND_ECC_INFO *info)

Pointer to ARM_NAND_InquireECC : Inquire about available ECC.

int32_t(* PowerControl)(ARM_POWER_STATE state)

Pointer to ARM_NAND_PowerControl : Control NAND Interface Power.

int32_t(* ReadData)(uint32_t dev_num, void *data, uint32_t cnt, uint32_t mode)

Pointer to ARM_NAND_ReadData : Read data from NAND device.

int32_t(* SendAddress)(uint32_t dev_num, uint8_t addr)

Pointer to ARM_NAND_SendAddress : Send address to NAND device.

int32_t(* SendCommand)(uint32_t dev_num, uint8_t cmd)

Pointer to ARM_NAND_SendCommand : Send command to NAND device.

int32_t(* Uninitialize)(void)

Pointer to ARM_NAND_Uninitialize : De-initialize NAND Interface.

int32_t(* WriteData)(uint32_t dev_num, const void *data, uint32_t cnt, uint32_t mode)

Pointer to ARM_NAND_WriteData : Write data to NAND device.

int32_t(* WriteProtect)(uint32_t dev_num, bool enable)

Pointer to ARM_NAND_WriteProtect : Control WPn (Write Protect).

struct ARM_NAND_CAPABILITIES

NAND Driver Capabilities.

A NAND driver can be implemented with different capabilities. The bitfield members of this struct encode the capabilities implemented by this driver.

Returned by:

Data Fields
uint32_t ce_lines: 4 Number of CEn (Chip Enable) lines: ce_lines + 1.
uint32_t ce_manual: 1 Supports manual CEn (Chip Enable) Control.
uint32_t data_width_16: 1 Supports 16-bit data.
uint32_t ddr: 1 Supports NV-DDR Data Interface (ONFI)
uint32_t ddr2: 1 Supports NV-DDR2 Data Interface (ONFI)
uint32_t ddr2_timing_mode: 3 Fastest (highest) NV_DDR2 Timing Mode supported (ONFI)
uint32_t ddr_timing_mode: 3 Fastest (highest) NV_DDR Timing Mode supported (ONFI)
uint32_t driver_strength_18: 1 Supports Driver Strength 2.0x = 18 Ohms.
uint32_t driver_strength_25: 1 Supports Driver Strength 1.4x = 25 Ohms.
uint32_t driver_strength_50: 1 Supports Driver Strength 0.7x = 50 Ohms.
uint32_t event_device_ready: 1 Signal Device Ready event (R/Bn rising edge)
uint32_t rb_monitor: 1 Supports R/Bn (Ready/Busy) Monitoring.
uint32_t reentrant_operation: 1 Supports re-entrant operation (SendCommand/Address, Read/WriteData)
uint32_t sdr_timing_mode: 3 Fastest (highest) SDR Timing Mode supported (ONFI)
uint32_t sequence_operation: 1 Supports Sequence operation (ExecuteSequence, AbortSequence)
uint32_t vcc: 1 Supports VCC Power Supply Control.
uint32_t vcc_1v8: 1 Supports 1.8 VCC Power Supply.
uint32_t vccq: 1 Supports VCCQ I/O Power Supply Control.
uint32_t vccq_1v8: 1 Supports 1.8 VCCQ I/O Power Supply.
uint32_t vpp: 1 Supports VPP High Voltage Power Supply Control.
uint32_t wp: 1 Supports WPn (Write Protect) Control.
struct ARM_NAND_ECC_INFO

NAND ECC (Error Correction Code) Information.

Structure with information about the Error Correction Code for a NAND.

Parameter for:

Data Fields
uint16_t codeword_size Number of bytes over which ECC is calculated.
uint32_t correctable_bits: 8 Number of correctable bits (based on 512 byte codeword size)
uint16_t ecc_offset ECC offset in bytes (where ECC starts in Spare area)
uint16_t ecc_size ECC size in bytes (rounded up)
uint32_t page_count: 3 Number of virtual pages: N = 2 ^ page_count.
uint32_t page_layout: 1 Page layout: 0=|Data0|Spare0|...|DataN-1|SpareN-1|, 1=|Data0|...|DataN-1|Spare0|...|SpareN-1|.
uint32_t page_size: 4 Virtual Page size (Data+Spare): 0=512+16, 1=1k+32, 2=2k+64, 3=4k+128, 4=8k+256, 8=512+28, 9=1k+56, 10=2k+112, 11=4k+224, 12=8k+448.
uint32_t reserved: 14 Reserved (must be zero)
uint32_t type: 2 Type: 1=ECC0 over Data, 2=ECC0 over Data+Spare, 3=ECC0 over Data and ECC1 over Spare.

Typedef Documentation

ARM_NAND_SignalEvent_t

Pointer to ARM_NAND_SignalEvent : Signal NAND Event.

Provides the typedef for the callback function ARM_NAND_SignalEvent.

Parameter for:

Function Documentation

int32_t ARM_NAND_AbortSequence ( uint32_t  dev_num)

Abort sequence execution.

Parameters
[in]dev_numDevice number
Returns
Status Error Codes

Aborts execution of the current sequence for a NAND device. The parameter dev_num is the device number.

int32_t ARM_NAND_ChipEnable ( uint32_t  dev_num,
bool  enable 
)

Control CEn (Chip Enable).

Parameters
[in]dev_numDevice number
[in]enable
  • false Chip Enable off
  • true Chip Enable on
Returns
Status Error Codes

Controls the Chip Enable (CEn) pin of a NAND device in order to enable or disable the device. The parameter dev_num is the device number. The boolean parameter enable specifies to enables or disable the device.

This function is optional and supported only when reported by ce_manual flag in ARM_NAND_CAPABILITIES. Otherwise the Chip Enable (CEn) signal is controlled automatically by SendCommand/Address, Read/WriteData and ExecuteSequence (for example when the NAND device is connected to a memory bus).

int32_t ARM_NAND_Control ( uint32_t  dev_num,
uint32_t  control,
uint32_t  arg 
)

Control NAND Interface.

Parameters
[in]dev_numDevice number
[in]controlOperation
[in]argArgument of operation
Returns
Status Error Codes

Controls the NAND interface settings.

The parameter dev_num is the device number. The parameter control specifies various settings (see tables below). Depending on the control bits, the parameter arg provides additional information.

The table lists values for the parameter control.

Mode Control Bits Description
ARM_NAND_BUS_MODE Set the bus mode. Specify the value with the parameter arg as defined in the table Bus Mode.
ARM_NAND_BUS_DATA_WIDTH Set the data bus width. Specify the value with the parameter arg as defined in the table Data Bus Width.
ARM_NAND_DRIVER_STRENGTH Set the driver strength. Specify the value with the parameter arg as defined in the table Driver Strength.
ARM_NAND_DEVICE_READY_EVENT Generate ARM_NAND_EVENT_DEVICE_READY; arg = [0:disabled (default); 1:enabled].
ARM_NAND_DRIVER_READY_EVENT Generate ARM_NAND_EVENT_DRIVER_READY; arg = [0:disabled (default); 1:enabled].

ARM_NAND_BUS_xxx specifies the bus mode (ONFI - Open NAND Flash Interface).

Control Bits: Bus Mode Description
ARM_NAND_BUS_SDR Set the Data Interface: SDR (Single Data Rate) - Traditional interface (default)
ARM_NAND_BUS_DDR Set the Data Interface: NV-DDR (Double Data Rate)
ARM_NAND_BUS_DDR2 Set the Data Interface: NV-DDR2 (Double Data Rate)
ARM_NAND_BUS_TIMING_MODE_0 Set the Timing Mode 0 (default)
ARM_NAND_BUS_TIMING_MODE_1 Set the Timing Mode 1
ARM_NAND_BUS_TIMING_MODE_2 Set the Timing Mode 2
ARM_NAND_BUS_TIMING_MODE_3 Set the Timing Mode 3
ARM_NAND_BUS_TIMING_MODE_4 Set the Timing Mode 4 (SDR EDO capable)
ARM_NAND_BUS_TIMING_MODE_5 Set the Timing Mode 5 (SDR EDO capable)
ARM_NAND_BUS_TIMING_MODE_6 Set the Timing Mode 6 (NV-DDR2 only)
ARM_NAND_BUS_TIMING_MODE_7 Set the Timing Mode 7 (NV-DDR2 only)
ARM_NAND_BUS_DDR2_DO_WCYC_0 Set the DDR2 Data Output Warmup cycles: 0 (default)
ARM_NAND_BUS_DDR2_DO_WCYC_1 Set the DDR2 Data Output Warmup cycles: 1
ARM_NAND_BUS_DDR2_DO_WCYC_2 Set the DDR2 Data Output Warmup cycles: 2
ARM_NAND_BUS_DDR2_DO_WCYC_4 Set the DDR2 Data Output Warmup cycles: 4
ARM_NAND_BUS_DDR2_DI_WCYC_0 Set the DDR2 Data Input Warmup cycles: 0 (default)
ARM_NAND_BUS_DDR2_DI_WCYC_1 Set the DDR2 Data Input Warmup cycles: 1
ARM_NAND_BUS_DDR2_DI_WCYC_2 Set the DDR2 Data Input Warmup cycles: 2
ARM_NAND_BUS_DDR2_DI_WCYC_4 Set the DDR2 Data Input Warmup cycles: 4
ARM_NAND_BUS_DDR2_VEN Set the DDR2 Enable external VREFQ as reference
ARM_NAND_BUS_DDR2_CMPD Set the DDR2 Enable complementary DQS (DQS_c) signal
ARM_NAND_BUS_DDR2_CMPR Set the DDR2 Enable complementary RE_n (RE_c) signal

ARM_NAND_BUS_DATA_WIDTH_xx specifies the bus data width.

Control Bits: Data Bus Width Description
ARM_NAND_BUS_DATA_WIDTH_8 Set the Bus Data Width: 8 bit (default)
ARM_NAND_BUS_DATA_WIDTH_16 Set the Bus Data Width: 16 bit

ARM_NAND_DRIVER_STRENGTH_xx specifies the driver strength (ONFI - Open NAND Flash Interface).

Control Bits: Driver Strength Description
ARM_NAND_DRIVER_STRENGTH_18 Set the Driver Strength 2.0x = 18 Ohms
ARM_NAND_DRIVER_STRENGTH_25 Set the Driver Strength 1.4x = 25 Ohms
ARM_NAND_DRIVER_STRENGTH_35 Set the Driver Strength 1.0x = 35 Ohms (default)
ARM_NAND_DRIVER_STRENGTH_50 Set the Driver Strength 0.7x = 50 Ohms
int32_t ARM_NAND_DevicePower ( uint32_t  voltage)

Set device power supply voltage.

Parameters
[in]voltageNAND Device supply voltage
Returns
Status Error Codes

Controls power supply of the NAND device.

The parameter voltage sets the device supply voltage as defined in the table.

AMR_NAND_POWER_xxx_xxx specifies power settings.

Device Power Bits Description
ARM_NAND_POWER_VCC_OFF Set VCC Power off
ARM_NAND_POWER_VCC_3V3 Set VCC = 3.3V
ARM_NAND_POWER_VCC_1V8 Set VCC = 1.8V
ARM_NAND_POWER_VCCQ_OFF Set VCCQ I/O Power off
ARM_NAND_POWER_VCCQ_3V3 Set VCCQ = 3.3V
ARM_NAND_POWER_VCCQ_1V8 Set VCCQ = 1.8V
ARM_NAND_POWER_VPP_OFF Set VPP off
ARM_NAND_POWER_VPP_ON Set VPP on
int32_t ARM_NAND_ExecuteSequence ( uint32_t  dev_num,
uint32_t  code,
uint32_t  cmd,
uint32_t  addr_col,
uint32_t  addr_row,
void *  data,
uint32_t  data_cnt,
uint8_t *  status,
uint32_t *  count 
)

Execute sequence of operations.

Parameters
[in]dev_numDevice number
[in]codeSequence code
[in]cmdCommand(s)
[in]addr_colColumn address
[in]addr_rowRow address
[in,out]dataPointer to data to be written or read
[in]data_cntNumber of data items in one iteration
[out]statusPointer to status read
[in,out]countNumber of iterations
Returns
Status Error Codes

Execute a sequence of operations for a NAND device. The parameter dev_num is the device number. The parameter code is the sequence encoding as defined in the table Sequence execution Code. The parameter cmd is the command or a series of commands The parameter addr_col is the column address. The parameter addr_row is the row address. The parameter data is a pointer to the buffer that stores the data to or loads the data from. The parameter data_cnt is the number of data items to read or write in one iteration. The parameter status is a pointer to the buffer that stores the status read. The parameter count is a pointer to the number of iterations.

ARM_NAND_CODE_xxx specifies sequence execution codes.

Sequence Execution Code Description
ARM_NAND_CODE_SEND_CMD1 Send Command 1 (cmd[7..0])
ARM_NAND_CODE_SEND_ADDR_COL1 Send Column Address 1 (addr_col[7..0])
ARM_NAND_CODE_SEND_ADDR_COL2 Send Column Address 2 (addr_col[15..8])
ARM_NAND_CODE_SEND_ADDR_ROW1 Send Row Address 1 (addr_row[7..0])
ARM_NAND_CODE_SEND_ADDR_ROW2 Send Row Address 2 (addr_row[15..8])
ARM_NAND_CODE_SEND_ADDR_ROW3 Send Row Address 3 (addr_row[23..16])
ARM_NAND_CODE_INC_ADDR_ROW Auto-increment Row Address
ARM_NAND_CODE_WRITE_DATA Write Data
ARM_NAND_CODE_SEND_CMD2 Send Command 2 (cmd[15..8])
ARM_NAND_CODE_WAIT_BUSY Wait while R/Bn busy
ARM_NAND_CODE_READ_DATA Read Data
ARM_NAND_CODE_SEND_CMD3 Send Command 3 (cmd[23..16])
ARM_NAND_CODE_READ_STATUS Read Status byte and check FAIL bit (bit 0)
ARM_NAND_ECC(n) Select ECC
ARM_NAND_ECC0 Use ECC0 of selected ECC
ARM_NAND_ECC1 Use ECC1 of selected ECC
ARM_NAND_DRIVER_DONE_EVENT Generate ARM_NAND_EVENT_DRIVER_DONE

The data item size is defined by the data type which depends on the configured data bus width.

Data type is:

  • uint8_t for 8-bit data bus
  • uint16_t for 16-bit data bus

The function is non-blocking and returns as soon as the driver has started executing the specified sequence. When the operation is completed the ARM_NAND_EVENT_DRIVER_DONE event is generated (if enabled by ARM_NAND_DRIVER_DONE_EVENT). Progress of the operation can also be monitored by calling the ARM_NAND_GetStatus function and checking the busy flag.

Driver executes the number of specified iterations where in each iteration items specified by ARM_NAND_CODE_xxx are executed in the order as listed in the table Sequence execution Code. The parameter count is holding the current number of iterations left.

Execution is automatically aborted and ARM_NAND_EVENT_DRIVER_DONE event is generated (if enabled by ARM_NAND_DRIVER_DONE_EVENT):

  • if Read Status is enabled and the FAIL bit (bit 0) is set
  • if ECC is used and ECC fails (also sets ARM_NAND_EVENT_ECC_ERROR event)
Note
ARM_NAND_CODE_WAIT_BUSY can only be specified if Device Ready event can be generated (reported by event_device_ready in ARM_NAND_CAPABILITIES). The event ARM_NAND_EVENT_DEVICE_READY is not generated during sequence execution but rather used internally by the driver.
ARM_NAND_CAPABILITIES ARM_NAND_GetCapabilities ( void  )

Get driver capabilities.

Returns
ARM_NAND_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 is able to create signal events using the ARM_NAND_SignalEvent callback function.

Example:

extern ARM_DRIVER_NAND Driver_NAND0;
ARM_DRIVER_NAND *drv_info;
void read_capabilities (void) {
ARM_NAND_CAPABILITIES drv_capabilities;
drv_info = &Driver_NAND0;
drv_capabilities = drv_info->GetCapabilities ();
// interrogate capabilities
}
int32_t ARM_NAND_GetDeviceBusy ( uint32_t  dev_num)

Get Device Busy pin state.

Parameters
[in]dev_numDevice number
Returns
1=busy, 0=not busy, or error

Retrieve the Device Busy pin state of a NAND device. The parameter dev_num is the device number.

The function returns the status of the Device Busy pin: [1=busy; 0=not busy or error].

ARM_NAND_STATUS ARM_NAND_GetStatus ( uint32_t  dev_num)

Get NAND status.

Parameters
[in]dev_numDevice number
Returns
NAND status ARM_NAND_STATUS

Retrieve the current NAND interface status. The parameter dev_num is the device number.

ARM_DRIVER_VERSION ARM_NAND_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_NAND Driver_NAND0;
ARM_DRIVER_NAND *drv_info;
void setup_nand (void) {
drv_info = &Driver_NAND0;
version = drv_info->GetVersion ();
if (version.api < 0x10A) { // requires at minimum API version 1.10 or higher
// error handling
return;
}
}
int32_t ARM_NAND_Initialize ( ARM_NAND_SignalEvent_t  cb_event)

Initialize the NAND Interface.

Parameters
[in]cb_eventPointer to ARM_NAND_SignalEvent
Returns
Status Error Codes

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

The function performs the following operations:

  • Initializes the resources needed for the NAND interface.
  • Registers the ARM_NAND_SignalEvent callback function.

The parameter cb_event is a pointer to the ARM_NAND_SignalEvent callback function; use a NULL pointer when no callback signals are required.

Example:

int32_t ARM_NAND_InquireECC ( int32_t  index,
ARM_NAND_ECC_INFO info 
)

Inquire about available ECC.

Parameters
[in]indexDevice number
[out]infoPointer to ECC information ARM_NAND_ECC_INFO retrieved
Returns
Status Error Codes

Retrieve information about the ECC referenced by index.

int32_t ARM_NAND_PowerControl ( ARM_POWER_STATE  state)

Control the NAND interface power.

Parameters
[in]statePower state
Returns
Status Error Codes

Allows you to control the power modes of the NAND interface.

int32_t ARM_NAND_ReadData ( uint32_t  dev_num,
void *  data,
uint32_t  cnt,
uint32_t  mode 
)

Read data from NAND device.

Parameters
[in]dev_numDevice number
[out]dataPointer to buffer for data to read from NAND device
[in]cntNumber of data items to read
[in]modeOperation mode
Returns
number of data items read or Status Error Codes

Read data from a NAND device. The parameter dev_num is the device number. The parameter data is a pointer to the buffer that stores the data read from a NAND device. The parameter cnt is the number of data items to read. The parameter mode defines the operation mode as listed in the table below.

Read Data Mode Description
ARM_NAND_ECC(n) Select ECC
ARM_NAND_ECC0 Use ECC0 of selected ECC
ARM_NAND_ECC1 Use ECC1 of selected ECC
ARM_NAND_DRIVER_DONE_EVENT Generate ARM_NAND_EVENT_DRIVER_DONE

The data item size is defined by the data type which depends on the configured data bus width.

Data type is:

  • uint8_t for 8-bit data bus
  • uint16_t for 16-bit data bus

The function executes in the following ways:

  • When the operation is blocking (typical for devices connected to memory bus when not using DMA) then the function returns after all data is read and returns the number of data items read.
  • When the operation is non-blocking (typical for NAND controllers) then the function only starts the operation and returns with zero number of data items read. After the operation is completed the ARM_NAND_EVENT_DRIVER_DONE event is generated (if enabled by ARM_NAND_DRIVER_DONE_EVENT). Progress of the operation can also be monitored by calling the ARM_NAND_GetStatus function and checking the busy flag. Operation is automatically aborted if ECC is used and ECC correction fails which generates the ARM_NAND_EVENT_ECC_ERROR event (together with ARM_NAND_DRIVER_DONE_EVENT if enabled).
int32_t ARM_NAND_SendAddress ( uint32_t  dev_num,
uint8_t  addr 
)

Send address to NAND device.

Parameters
[in]dev_numDevice number
[in]addrAddress
Returns
Status Error Codes

Send an address to the NAND device. The parameter dev_num is the device number. The parameter addr is the address.

int32_t ARM_NAND_SendCommand ( uint32_t  dev_num,
uint8_t  cmd 
)

Send command to NAND device.

Parameters
[in]dev_numDevice number
[in]cmdCommand
Returns
Status Error Codes

Send a command to the NAND device. The parameter dev_num is the device number. The parameter cmd is the command sent to the NAND device.

void ARM_NAND_SignalEvent ( uint32_t  dev_num,
uint32_t  event 
)

Signal NAND event.

Parameters
[in]dev_numDevice number
[in]eventEvent notification mask
Returns
none

The function ARM_NAND_SignalEvent notifies the application of the NAND Events and it is registered by the function ARM_NAND_Initialize. The function ARM_NAND_GetCapabilities returns information about the implemented optional events in a driver.

The parameter dev_num is the device number. 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_NAND_EVENT_DEVICE_READY Occurs when rising edge is detected on R/Bn (Ready/Busy) pin indicating that the device is ready.
1 ARM_NAND_EVENT_DRIVER_READY Occurs when SendCommand/Address, Read/WriteData or ExecuteSequence indicate that they can be executed (after previously being busy and not able to start the requested operation).
2 ARM_NAND_EVENT_DRIVER_DONE Occurs after Read/WriteData or ExecuteSequence operation has finished (after being successfully started).
3 ARM_NAND_EVENT_ECC_ERROR Occurs after Read/WriteData or ExecuteSequence (together with ARM_NAND_EVENT_DRIVER_DONE) when ECC generation or correction failed.
int32_t ARM_NAND_Uninitialize ( void  )

De-initialize the NAND Interface.

Returns
Status Error Codes

The function ARM_NAND_Uninitialize de-initializes the resources of NAND interface.

It is called when the middleware component stops operation and releases the software resources used by the interface.

int32_t ARM_NAND_WriteData ( uint32_t  dev_num,
const void *  data,
uint32_t  cnt,
uint32_t  mode 
)

Write data to NAND device.

Parameters
[in]dev_numDevice number
[out]dataPointer to buffer with data to write to NAND device
[in]cntNumber of data items to write
[in]modeOperation mode
Returns
number of data items written or Status Error Codes

Write data to a NAND device. The parameter dev_num is the device number. The parameter data is a pointer to the buffer with data to write. The parameter cnt is the number of data items to write. The parameter mode defines the operation mode as listed in the table below.

Write Data Mode Description
ARM_NAND_ECC(n) Select ECC
ARM_NAND_ECC0 Use ECC0 of selected ECC
ARM_NAND_ECC1 Use ECC1 of selected ECC
ARM_NAND_DRIVER_DONE_EVENT Generate ARM_NAND_EVENT_DRIVER_DONE

The data item size is defined by the data type which depends on the configured data bus width.

Data type is:

  • uint8_t for 8-bit data bus
  • uint16_t for 16-bit data bus

The function executes in the following ways:

  • When the operation is blocking (typical for devices connected to memory bus when not using DMA) then the function returns after all data is written and returns the number of data items written.
  • When the operation is non-blocking (typical for NAND controllers) then the function only starts the operation and returns with zero number of data items written. After the operation is completed the ARM_NAND_EVENT_DRIVER_DONE event is generated (if enabled by ARM_NAND_DRIVER_DONE_EVENT). Progress of the operation can also be monitored by calling the ARM_NAND_GetStatus function and checking the busy flag. Operation is automatically aborted if ECC is used and ECC generation fails which generates the ARM_NAND_EVENT_ECC_ERROR event (together with ARM_NAND_DRIVER_DONE_EVENT if enabled).
int32_t ARM_NAND_WriteProtect ( uint32_t  dev_num,
bool  enable 
)

Control WPn (Write Protect).

Parameters
[in]dev_numDevice number
[in]enable
  • false Write Protect off
  • true Write Protect on
Returns
Status Error Codes

Control the Write Protect (WPn) pin of a NAND device in order to enable or disable write protection. The parameter dev_num is the device number. The boolean parameter enable specifies to enables or disables write protection.