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

Loading...
Searching...
No Matches
Content | Data Structures | Typedefs | Functions
NAND Interface

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

## Content
| NAND 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.

Block Diagram

Simplified NAND Flash Schematic

NAND API

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

- Driver_NAND.h : Driver API for NAND Flash Device Interface

The driver implementation is a typical part of the Device Family Pack (DFP) that supports the peripherals of the microcontroller family.

NAND Flash is organized in pages, grouped into blocks as the smallest erasable unit. The addressing of data is achieved by `byte_address = block * block_size + page_in_block * page_size + offset_in_page`. In terms of this NAND API blocks and pages are referred to as `row` and the byte offset within the page as `col`. Thus one can calculate the `byte_address = row * page_size + col`. The parameters `page_size` and `block_size` are device specific and must be handled by the driver user appropriately.

Driver Functions

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

- ARM_DRIVER_NAND : access struct for NAND driver functions

Example Code:

#include "Driver_NAND.h"
/* ONFI commands */
#define ONFI_CMD_READ_1ST 0x00 ///< Read 1st Cycle
#define ONFI_CMD_PROGRAM_2ND 0x10 ///< Page Program 2nd Cycle
#define ONFI_CMD_READ_2ND 0x30 ///< Read 2nd Cycle
#define ONFI_CMD_PROGRAM_1ST 0x80 ///< Page Program 1st Cycle
#define ONFI_CMD_RESET 0xFF ///< Reset Command
/* NAND Signal Event callback function */
volatile uint32_t NAND_Events;
void NAND_SignalEventCallback (uint32_t dev_num, uint32_t event) {
if (dev_num == 0) {
NAND_Events |= event;
}
else {
// ..
}
}
/* NAND device Power ON */
void PowerOn (ARM_DRIVER_NAND *drv, uint32_t dev_num) {
ARM_NAND_CAPABILITIES capabilities;
// Query drivers capabilities
capabilities = drv->GetCapabilities();
// Initialize NAND device
drv->Initialize (NAND_SignalEventCallback);
// Power-on NAND driver
drv->PowerControl (ARM_POWER_FULL);
// Turn ON device power
uint32_t volt = 0U;
if (capabilities.vcc) { volt |= ARM_NAND_POWER_VCC_3V3; }
if (capabilities.vcc_1v8) { volt |= ARM_NAND_POWER_VCC_1V8; }
if (capabilities.vccq) { volt |= ARM_NAND_POWER_VCCQ_3V3; }
if (capabilities.vccq_1v8) { volt |= ARM_NAND_POWER_VCCQ_1V8; }
if (volt != 0U) {
drv->DevicePower (volt);
}
// Setting bus mode
drv->Control (0U, ARM_NAND_BUS_MODE, ARM_NAND_BUS_SDR);
// Setting bus data width
drv->Control (0U, ARM_NAND_BUS_DATA_WIDTH, ARM_NAND_BUS_DATA_WIDTH_8);
// Enable chip manually if needed
if (capabilities.ce_manual) {
drv->ChipEnable (dev_num, true);
}
// Send ONFI Reset command */
drv->SendCommand (dev_num, ONFI_CMD_RESET);
}
/* NAND device Power OFF */
void PowerOff (ARM_DRIVER_NAND *drv, uint32_t dev_num) {
ARM_NAND_CAPABILITIES capabilities;
// Query drivers capabilities
capabilities = drv->GetCapabilities();
// Disable chip manually if needed
if (capabilities.ce_manual) {
drv->ChipEnable (0U, false);
}
// Switch OFF gracefully
uint32_t volt = 0U;
if (capabilities.vcc) { volt |= ARM_NAND_POWER_VCC_OFF; }
if (capabilities.vccq) { volt |= ARM_NAND_POWER_VCCQ_OFF; }
if (volt) {
drv->DevicePower (volt);
}
drv->PowerControl (ARM_POWER_OFF);
drv->Uninitialize ();
}
/* Read NAND page. */
void ReadPage (ARM_DRIVER_NAND *drv, uint32_t row, uint8_t *data, uint32_t cnt) {
uint32_t dev_num = 0; // Device number
uint32_t mode;
// Send Read 1st command
drv->SendCommand (dev_num, ONFI_CMD_READ_1ST);
// Send address (column: 2 cycles, row: 3 cycles)
drv->SendAddress (dev_num, 0x00);
drv->SendAddress (dev_num, 0x00);
drv->SendAddress (dev_num, (uint8_t)(row));
drv->SendAddress (dev_num, (uint8_t)(row >> 8));
drv->SendAddress (dev_num, (uint8_t)(row >> 16));
// Send Read 2nd command
drv->SendCommand (dev_num, ONFI_CMD_READ_2ND);
// Wait until device ready
while (drv->GetDeviceBusy(dev_num) == 1) { ; }
// Use ECC algorithm number 2, ECC0 (ECC over main+spare)
mode = ARM_NAND_ECC(2) | ARM_NAND_ECC0;
// Transfer data from the NAND chip
if (drv->ReadData (dev_num, data, cnt, mode | ARM_NAND_DRIVER_DONE_EVENT) != cnt) {
// Wait until driver done event received
while ((NAND_Events & ARM_NAND_DRIVER_DONE_EVENT) == 0) { ; }
// Read page completed
if ((NAND_Events & ARM_NAND_EVENT_ECC_ERROR) != 0) {
// ECC correction failed
}
}
}
/* Write NAND page (ExecuteSequence interface). */
void WritePage_Seq (ARM_DRIVER_NAND *drv, uint32_t row, const uint8_t *data, uint32_t cnt) {
uint32_t dev_num = 0; // Device number
uint32_t cmd;
uint32_t code;
uint32_t seq;
// Prepare commands to send
cmd = ONFI_CMD_PROGRAM_1ST | (ONFI_CMD_PROGRAM_2ND << 8);
// Construct sequence code:
// - Send command 1
// - Send 2 cycles of column address and 3 cycles of row address
// - Write data from memory to device
// - Send command 2
code = ARM_NAND_CODE_SEND_CMD1 |
ARM_NAND_CODE_SEND_ADDR_COL1 |
ARM_NAND_CODE_SEND_ADDR_COL2 |
ARM_NAND_CODE_SEND_ADDR_ROW1 |
ARM_NAND_CODE_SEND_ADDR_ROW2 |
ARM_NAND_CODE_SEND_ADDR_ROW3 |
ARM_NAND_CODE_WRITE_DATA |
ARM_NAND_CODE_SEND_CMD2 ;
// - Use ECC algorithm number 2, ECC0 (ECC over main+spare)
code |= ARM_NAND_ECC(2) | ARM_NAND_ECC0;
// Number of iterations in a sequence
seq = 1;
drv->ExecuteSequence (dev_num, // Device number
code, // Sequence code
cmd, // Command(s)
0, // Column address
row, // Row address
(void *)data, // Data buffer
cnt, // Number of data items (per iteration)
NULL, // Device status will not be read
&seq); // Number of iterations
// Wait until done
while (drv->GetStatus(dev_num).busy != 0) { ; }
// Page write completed
}
ARM_POWER_OFF
@ ARM_POWER_OFF
Power off: no operation possible.
Definition: Driver_Common.h:64
ARM_POWER_FULL
@ ARM_POWER_FULL
Power on: full operation at maximum performance.
Definition: Driver_Common.h:66
Driver_NAND.h
ARM_NAND_BUS_DATA_WIDTH
#define ARM_NAND_BUS_DATA_WIDTH
Set Bus Data Width as specified with arg.
Definition: Driver_NAND.h:82
ARM_NAND_POWER_VCC_OFF
#define ARM_NAND_POWER_VCC_OFF
VCC Power off.
Definition: Driver_NAND.h:68
ARM_NAND_POWER_VCCQ_1V8
#define ARM_NAND_POWER_VCCQ_1V8
VCCQ = 1.8V.
Definition: Driver_NAND.h:75
ARM_NAND_POWER_VCCQ_3V3
#define ARM_NAND_POWER_VCCQ_3V3
VCCQ = 3.3V.
Definition: Driver_NAND.h:74
ARM_NAND_EVENT_ECC_ERROR
#define ARM_NAND_EVENT_ECC_ERROR
ECC could not correct data.
Definition: Driver_NAND.h:217
ARM_NAND_BUS_MODE
#define ARM_NAND_BUS_MODE
Set Bus Mode as specified with arg.
Definition: Driver_NAND.h:81
ARM_NAND_POWER_VCC_1V8
#define ARM_NAND_POWER_VCC_1V8
VCC = 1.8V.
Definition: Driver_NAND.h:70
ARM_NAND_POWER_VCCQ_OFF
#define ARM_NAND_POWER_VCCQ_OFF
VCCQ I/O Power off.
Definition: Driver_NAND.h:73
ARM_NAND_POWER_VCC_3V3
#define ARM_NAND_POWER_VCC_3V3
VCC = 3.3V.
Definition: Driver_NAND.h:69
ARM_NAND_DRIVER_DONE_EVENT
#define ARM_NAND_DRIVER_DONE_EVENT
Generate ARM_NAND_EVENT_DRIVER_DONE.
Definition: Driver_NAND.h:138
ARM_NAND_BUS_SDR
#define ARM_NAND_BUS_SDR
Data Interface: SDR (Single Data Rate) - Traditional interface (default)
ARM_NAND_BUS_DATA_WIDTH_8
#define ARM_NAND_BUS_DATA_WIDTH_8
Bus Data Width: 8 bit (default)
ARM_NAND_ECC0
#define ARM_NAND_ECC0
Use ECC0 of selected ECC.
ARM_NAND_ECC
#define ARM_NAND_ECC(n)
Select ECC.
ARM_NAND_CODE_WRITE_DATA
#define ARM_NAND_CODE_WRITE_DATA
Write Data.
ARM_NAND_CODE_SEND_ADDR_ROW2
#define ARM_NAND_CODE_SEND_ADDR_ROW2
Send Row Address 2.
ARM_NAND_CODE_SEND_ADDR_COL2
#define ARM_NAND_CODE_SEND_ADDR_COL2
Send Column Address 2.
ARM_NAND_CODE_SEND_ADDR_COL1
#define ARM_NAND_CODE_SEND_ADDR_COL1
Send Column Address 1.
ARM_NAND_CODE_SEND_CMD2
#define ARM_NAND_CODE_SEND_CMD2
Send Command 2.
ARM_NAND_CODE_SEND_ADDR_ROW1
#define ARM_NAND_CODE_SEND_ADDR_ROW1
Send Row Address 1.
ARM_NAND_CODE_SEND_ADDR_ROW3
#define ARM_NAND_CODE_SEND_ADDR_ROW3
Send Row Address 3.
ARM_NAND_CODE_SEND_CMD1
#define ARM_NAND_CODE_SEND_CMD1
Send Command 1.
ARM_DRIVER_NAND::ExecuteSequence
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.
Definition: Driver_NAND.h:411
ARM_NAND_CAPABILITIES::vcc_1v8
uint32_t vcc_1v8
Supports 1.8 VCC Power Supply.
Definition: Driver_NAND.h:373
ARM_NAND_CAPABILITIES::vccq_1v8
uint32_t vccq_1v8
Supports 1.8 VCCQ I/O Power Supply.
Definition: Driver_NAND.h:375
ARM_DRIVER_NAND::PowerControl
int32_t(* PowerControl)(ARM_POWER_STATE state)
Pointer to ARM_NAND_PowerControl : Control NAND Interface Power.
Definition: Driver_NAND.h:402
ARM_NAND_CAPABILITIES::ce_manual
uint32_t ce_manual
Supports manual CEn (Chip Enable) Control.
Definition: Driver_NAND.h:379
ARM_DRIVER_NAND::SendAddress
int32_t(* SendAddress)(uint32_t dev_num, uint8_t addr)
Pointer to ARM_NAND_SendAddress : Send address to NAND device.
Definition: Driver_NAND.h:408
ARM_DRIVER_NAND::Initialize
int32_t(* Initialize)(ARM_NAND_SignalEvent_t cb_event)
Pointer to ARM_NAND_Initialize : Initialize NAND Interface.
Definition: Driver_NAND.h:400
ARM_NAND_CAPABILITIES::vcc
uint32_t vcc
Supports VCC Power Supply Control.
Definition: Driver_NAND.h:372
ARM_DRIVER_NAND::ReadData
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.
Definition: Driver_NAND.h:409
ARM_DRIVER_NAND::GetStatus
ARM_NAND_STATUS(* GetStatus)(uint32_t dev_num)
Pointer to ARM_NAND_GetStatus : Get NAND status.
Definition: Driver_NAND.h:417
ARM_DRIVER_NAND::SendCommand
int32_t(* SendCommand)(uint32_t dev_num, uint8_t cmd)
Pointer to ARM_NAND_SendCommand : Send command to NAND device.
Definition: Driver_NAND.h:407
ARM_NAND_STATUS::busy
uint32_t busy
Driver busy flag.
Definition: Driver_NAND.h:207
ARM_DRIVER_NAND::GetDeviceBusy
int32_t(* GetDeviceBusy)(uint32_t dev_num)
Pointer to ARM_NAND_GetDeviceBusy : Get Device Busy pin state.
Definition: Driver_NAND.h:406
ARM_DRIVER_NAND::GetCapabilities
ARM_NAND_CAPABILITIES(* GetCapabilities)(void)
Pointer to ARM_NAND_GetCapabilities : Get driver capabilities.
Definition: Driver_NAND.h:399
ARM_DRIVER_NAND::Uninitialize
int32_t(* Uninitialize)(void)
Pointer to ARM_NAND_Uninitialize : De-initialize NAND Interface.
Definition: Driver_NAND.h:401
ARM_DRIVER_NAND::DevicePower
int32_t(* DevicePower)(uint32_t voltage)
Pointer to ARM_NAND_DevicePower : Set device power supply voltage.
Definition: Driver_NAND.h:403
ARM_NAND_CAPABILITIES::vccq
uint32_t vccq
Supports VCCQ I/O Power Supply Control.
Definition: Driver_NAND.h:374
ARM_DRIVER_NAND::ChipEnable
int32_t(* ChipEnable)(uint32_t dev_num, bool enable)
Pointer to ARM_NAND_ChipEnable : Control CEn (Chip Enable).
Definition: Driver_NAND.h:405
ARM_DRIVER_NAND::Control
int32_t(* Control)(uint32_t dev_num, uint32_t control, uint32_t arg)
Pointer to ARM_NAND_Control : Control NAND Interface.
Definition: Driver_NAND.h:416
ARM_DRIVER_NAND
Access structure of the NAND Driver.
Definition: Driver_NAND.h:397
ARM_NAND_CAPABILITIES
NAND Driver Capabilities.
Definition: Driver_NAND.h:368

## Data Structure Documentation

## ◆ ARM_NAND_STATUS

struct ARM_NAND_STATUS

NAND Status.

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

Returned by:

- ARM_NAND_GetStatus

Data Fields
uint32_t | busy: 1 | Driver busy flag.
uint32_t | ecc_error: 1 | ECC error detected (cleared on next Read/WriteData or ExecuteSequence)
uint32_t | reserved: 30 |

## ◆ ARM_DRIVER_NAND

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 Common 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

## ◆ GetVersion

ARM_DRIVER_VERSION(* GetVersion) (void)

Pointer to ARM_NAND_GetVersion : Get driver version.

## ◆ GetCapabilities

ARM_NAND_CAPABILITIES(* GetCapabilities) (void)

Pointer to ARM_NAND_GetCapabilities : Get driver capabilities.

## ◆ Initialize

int32_t(* Initialize) (ARM_NAND_SignalEvent_t cb_event)

Pointer to ARM_NAND_Initialize : Initialize NAND Interface.

## ◆ Uninitialize

int32_t(* Uninitialize) (void)

Pointer to ARM_NAND_Uninitialize : De-initialize NAND Interface.

## ◆ PowerControl

int32_t(* PowerControl) (ARM_POWER_STATE state)

Pointer to ARM_NAND_PowerControl : Control NAND Interface Power.

## ◆ DevicePower

int32_t(* DevicePower) (uint32_t voltage)

Pointer to ARM_NAND_DevicePower : Set device power supply voltage.

## ◆ WriteProtect

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

Pointer to ARM_NAND_WriteProtect : Control WPn (Write Protect).

## ◆ ChipEnable

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

Pointer to ARM_NAND_ChipEnable : Control CEn (Chip Enable).

## ◆ GetDeviceBusy

int32_t(* GetDeviceBusy) (uint32_t dev_num)

Pointer to ARM_NAND_GetDeviceBusy : Get Device Busy pin state.

## ◆ SendCommand

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

Pointer to ARM_NAND_SendCommand : Send command to NAND device.

## ◆ SendAddress

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

Pointer to ARM_NAND_SendAddress : Send address to NAND device.

## ◆ ReadData

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.

## ◆ WriteData

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.

## ◆ ExecuteSequence

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.

## ◆ AbortSequence

int32_t(* AbortSequence) (uint32_t dev_num)

Pointer to ARM_NAND_AbortSequence : Abort sequence execution.

## ◆ Control

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

Pointer to ARM_NAND_Control : Control NAND Interface.

## ◆ GetStatus

ARM_NAND_STATUS(* GetStatus) (uint32_t dev_num)

Pointer to ARM_NAND_GetStatus : Get NAND status.

## ◆ InquireECC

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

Pointer to ARM_NAND_InquireECC : Inquire about available ECC.

## ◆ ARM_NAND_CAPABILITIES

struct ARM_NAND_CAPABILITIES

NAND Driver Capabilities.

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

Returned by:

- ARM_NAND_GetCapabilities

Data Fields
uint32_t | event_device_ready: 1 | Signal Device Ready event (R/Bn rising edge)
uint32_t | reentrant_operation: 1 | Supports re-entrant operation (SendCommand/Address, Read/WriteData)
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.
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 | rb_monitor: 1 | Supports R/Bn (Ready/Busy) Monitoring.
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 | sdr_timing_mode: 3 | Fastest (highest) SDR Timing Mode supported (ONFI)
uint32_t | ddr_timing_mode: 3 | Fastest (highest) NV_DDR Timing Mode supported (ONFI)
uint32_t | ddr2_timing_mode: 3 | Fastest (highest) NV_DDR2 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 | reserved: 2 | Reserved (must be zero)

## ◆ ARM_NAND_ECC_INFO

struct ARM_NAND_ECC_INFO

NAND ECC (Error Correction Code) Information.

Stores the characteristics of a ECC (Error Correction Code) algorithm and provides the information about necessary application data handling in order to protect stored data from NAND bit errors.

ECC algorithms applied on NAND memory typically operate on NAND device page level which is virtually divided to multiple main and spare areas. Data from main and spare area is taken into account when generating ECC data which is also stored into spare area. ECC codeword defines how much data will be protected and how much ECC data will be generated.

To describe how application data must be organized, ECC information structure specifies protection type which defines the protected part of data. As main and spare are of different size, two different algorithms could be provided, we can describe them as ECC0 and ECC1. Type can then have the following values:

Type | Description
--- | ---
0 | ECC algorithm not used
1 | ECC0 algorithm protects main data
2 | ECC0 algorithm protects main and spare data
3 | ECC0 algorithm protects main and ECC1 algorithm protects spare data

Virtual page division is described with page layout (page_layout), number of pages (page_count) and virtual page size (page_size or virtual_page_size). Virtual page size used by ECC algorithm can be defined by either page_size or virtual_page_size, depending on the page_size values:

Value | Main + Spare size
--- | ---
0 | 512 + 16
1 | 1024 + 32
2 | 2048 + 64
3 | 4096 + 128
4 | 8192 + 256
8 | 512 + 28
9 | 1024 + 56
10 | 2048 + 112
11 | 4096 + 224
12 | 8192 + 448
15 | Not used, use virtual_page_size

Structure member virtual_page_size is an array of two 16-bit values. First field of array (i.e. virtual_page_size[0]) contains main area size while second (i.e. virtual_page_size[1]) contains spare area size. Number of virtual pages N is defined with page_count and must be calculated as N = 2 ^ page_count.

Page layout defines main and spare ordering and two different page layouts are possible. First ordering assumes that spare area follows after every main area, while in second case all main areas build one contiguous region followed by contiguous region of spare areas. This is defined by member page_layout:

Layout | Description
--- | ---
0 | Single spare follows after single main: Main0,Spare0 ... MainN-1,SpareN-1
1 | Contiguous spare follows after contiguous main: Main0 ... MainN-1,Spare0 ... SpareN-1

ECC codeword size defines the size of data that is protected by ECC algorithm and is different for main and spare area. All structure members that define the codeword are therefore arrays of two 16-bit values. Codeword offset defines where ECC protected data starts in main (codeword_offset[0]) or spare (codeword_offset[1]) area, codeword size (codeword_size) defines the number of data that is protected i.e. data over which ECC is calculated and codeword gap (codeword_gap) defines the space between two consecutive codeword regions.

Generated ECC data is stored into spare area and is described similar as codeword, with offset from start of spare area (ecc_offset), size of generated data (ecc_size) and gap (ecc_gap) between two consecutive ECC data regions.

Number of bits that ECC algorithm can correct per codeword is defined with correctable_bits.

Parameter for:

- ARM_NAND_InquireECC

Data Fields
uint32_t | type: 2 | Type: 1=ECC0 over Main, 2=ECC0 over Main+Spare, 3=ECC0 over Main and ECC1 over Spare.
uint32_t | page_layout: 1 | Page layout: 0=|Main0|Spare0|...|MainN-1|SpareN-1|, 1=|Main0|...|MainN-1|Spare0|...|SpareN-1|.
uint32_t | page_count: 3 | Number of virtual pages: N = 2 ^ page_count.
uint32_t | page_size: 4 | Virtual Page size (Main+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, 15=Not used (extended description)
uint32_t | reserved: 14 | Reserved (must be zero)
uint32_t | correctable_bits: 8 | Number of correctable bits (based on 512 byte codeword size)
uint16_t | codeword_size[2] | Number of bytes over which ECC is calculated.
uint16_t | ecc_size[2] | ECC size in bytes (rounded up)
uint16_t | ecc_offset[2] | ECC offset in bytes (where ECC starts in Spare)
uint16_t | virtual_page_size[2] | Virtual Page size in bytes (Main/Spare)
uint16_t | codeword_offset[2] | Codeword offset in bytes (where ECC protected data starts in Main/Spare)
uint16_t | codeword_gap[2] | Codeword gap in bytes till next protected data.
uint16_t | ecc_gap[2] | ECC gap in bytes till next generated ECC.

## Typedef Documentation

## ◆ ARM_NAND_SignalEvent_t

ARM_NAND_SignalEvent_t

Pointer to ARM_NAND_SignalEvent : Signal NAND Event.

Provides the typedef for the callback function ARM_NAND_SignalEvent.

Parameter for:

- ARM_NAND_Initialize

## Function Documentation

## ◆ ARM_NAND_GetVersion()

ARM_DRIVER_VERSION ARM_NAND_GetVersion | ( | void |  | ) |

Get driver version.

Returns
  ARM_DRIVER_VERSION

The function ARM_NAND_GetVersion 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) {
ARM_DRIVER_VERSION version;
drv_info = &Driver_NAND0;
version = drv_info->GetVersion ();
if (version.api < 0x10A) { // requires at minimum API version 1.10 or higher
// error handling
return;
}
}
ARM_DRIVER_VERSION::api
uint16_t api
API version.
Definition: Driver_Common.h:47
ARM_DRIVER_VERSION
Driver Version.
Definition: Driver_Common.h:46
ARM_DRIVER_NAND::GetVersion
ARM_DRIVER_VERSION(* GetVersion)(void)
Pointer to ARM_NAND_GetVersion : Get driver version.
Definition: Driver_NAND.h:398

## ◆ ARM_NAND_GetCapabilities()

ARM_NAND_CAPABILITIES ARM_NAND_GetCapabilities | ( | void |  | ) |

Get driver capabilities.

Returns
  ARM_NAND_CAPABILITIES

The function ARM_NAND_GetCapabilities retrieves information about capabilities in this driver implementation. The data fields of the structure 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
}

## ◆ ARM_NAND_Initialize()

int32_t ARM_NAND_Initialize | ( | ARM_NAND_SignalEvent_t | cb_event | ) |

Initialize the NAND Interface.

Parameters

  [in] | cb_event | Pointer to ARM_NAND_SignalEvent

Returns
  Status Error Codes

The function ARM_NAND_Initialize 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:

- see NAND Interface - Driver Functions

## ◆ ARM_NAND_Uninitialize()

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.

## ◆ ARM_NAND_PowerControl()

int32_t ARM_NAND_PowerControl | ( | ARM_POWER_STATE | state | ) |

Control the NAND interface power.

Parameters

  [in] | state | Power state

Returns
  Status Error Codes

The function ARM_NAND_PowerControl controls the power modes of the NAND interface.

The parameter state sets the operation and can have the following values:

- ARM_POWER_FULL : set-up peripheral for data transfers, enable interrupts (NVIC) and optionally DMA. Can be called multiple times. If the peripheral is already in this mode the function performs no operation and returns with ARM_DRIVER_OK.
- ARM_POWER_LOW : may use power saving. Returns ARM_DRIVER_ERROR_UNSUPPORTED when not implemented.
- ARM_POWER_OFF : terminates any pending data transfers, disables peripheral, disables related interrupts and DMA.

Refer to Function Call Sequence for more information.

## ◆ ARM_NAND_DevicePower()

int32_t ARM_NAND_DevicePower | ( | uint32_t | voltage | ) |

Set device power supply voltage.

Parameters

  [in] | voltage | NAND Device supply voltage

Returns
  Status Error Codes

The function ARM_NAND_DevicePower controls the 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

## ◆ ARM_NAND_WriteProtect()

int32_t ARM_NAND_WriteProtect | ( | uint32_t | dev_num,
|  | bool | enable
| ) |  |

Control WPn (Write Protect).

Parameters

  [in] | dev_num | Device number
  [in] | enable | false Write Protect off true Write Protect on

Returns
  Status Error Codes

The function ARM_NAND_WriteProtect controls the Write Protect (WPn) pin of a NAND device.

The parameter dev_num is the device number.
The parameter enable specifies whether to enable or disable write protection.

## ◆ ARM_NAND_ChipEnable()

int32_t ARM_NAND_ChipEnable | ( | uint32_t | dev_num,
|  | bool | enable
| ) |  |

Control CEn (Chip Enable).

Parameters

  [in] | dev_num | Device number
  [in] | enable | false Chip Enable off true Chip Enable on

Returns
  Status Error Codes

The function ARM_NAND_ChipEnable control the Chip Enable (CEn) pin of a NAND device.

The parameter dev_num is the device number.
The parameter enable specifies whether to enable or disable the device.

This function is optional and supported only when the data field ce_manual = 1 in the structure 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).

## ◆ ARM_NAND_GetDeviceBusy()

int32_t ARM_NAND_GetDeviceBusy | ( | uint32_t | dev_num | ) |

Get Device Busy pin state.

Parameters

  [in] | dev_num | Device number

Returns
  1=busy, 0=not busy, or error

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

The parameter dev_num is the device number.

## ◆ ARM_NAND_SendCommand()

int32_t ARM_NAND_SendCommand | ( | uint32_t | dev_num,
|  | uint8_t | cmd
| ) |  |

Send command to NAND device.

Parameters

  [in] | dev_num | Device number
  [in] | cmd | Command

Returns
  Status Error Codes

The function ARM_NAND_SendCommand sends 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.

## ◆ ARM_NAND_SendAddress()

int32_t ARM_NAND_SendAddress | ( | uint32_t | dev_num,
|  | uint8_t | addr
| ) |  |

Send address to NAND device.

Parameters

  [in] | dev_num | Device number
  [in] | addr | Address

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.

## ◆ ARM_NAND_ReadData()

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_num | Device number
  [out] | data | Pointer to buffer for data to read from NAND device
  [in] | cnt | Number of data items to read
  [in] | mode | Operation mode

Returns
  number of data items read or Status Error Codes

The function ARM_NAND_ReadData reads 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 data field. 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).

## ◆ ARM_NAND_WriteData()

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_num | Device number
  [out] | data | Pointer to buffer with data to write to NAND device
  [in] | cnt | Number of data items to write
  [in] | mode | Operation mode

Returns
  number of data items written or Status Error Codes

The function ARM_NAND_WriteData writes 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 data field. 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).

## ◆ ARM_NAND_ExecuteSequence()

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_num | Device number
  [in] | code | Sequence code
  [in] | cmd | Command(s)
  [in] | addr_col | Column address
  [in] | addr_row | Row address
  [in,out] | data | Pointer to data to be written or read
  [in] | data_cnt | Number of data items in one iteration
  [out] | status | Pointer to status read
  [in,out] | count | Number of iterations

Returns
  Status Error Codes

The function ARM_NAND_ExecuteSequence executes 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 data field.

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 the 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_AbortSequence()

int32_t ARM_NAND_AbortSequence | ( | uint32_t | dev_num | ) |

Abort sequence execution.

Parameters

  [in] | dev_num | Device number

Returns
  Status Error Codes

The function ARM_NAND_AbortSequence aborts execution of the current sequence for a NAND device.

The parameter dev_num is the device number.

## ◆ ARM_NAND_Control()

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

Control NAND Interface.

Parameters

  [in] | dev_num | Device number
  [in] | control | Operation
  [in] | arg | Argument of operation

Returns
  Status Error Codes

The function ARM_NAND_Control controls the NAND interface and executes operations.

The parameter dev_num is the device number.
The parameter control specifies the operation.
The parameter arg provides (depending on the control) additional information or sets values.

The table lists the operations for the parameter control.

Parameter control | Operation
--- | ---
ARM_NAND_BUS_MODE | Set the bus mode. The parameter arg sets the Bus Mode.
ARM_NAND_BUS_DATA_WIDTH | Set the data bus width. The parameter arg sets the Bus Data Width.
ARM_NAND_DRIVER_STRENGTH | Set the driver strength. The parameter arg sets the Driver Strength.
ARM_NAND_DRIVER_READY_EVENT | Control generation of callback event ARM_NAND_EVENT_DRIVER_READY. Enable: arg = 1. Disable: arg = 0.
ARM_NAND_DEVICE_READY_EVENT | Control generation of callback event ARM_NAND_EVENT_DEVICE_READY; Enable: arg = 1. Disable: arg = 0.

See Also

- ARM_NAND_GetCapabilities returns information about supported operations, which are stored in the structure ARM_NAND_CAPABILITIES.
- ARM_NAND_SignalEvent provides information about the callback events ARM_NAND_EVENT_DRIVER_READY and ARM_NAND_EVENT_DEVICE_READY

The table lists values for the parameter arg used with the control operation ARM_NAND_BUS_MODE, ARM_NAND_BUS_DATA_WIDTH, and ARM_NAND_DRIVER_STRENGTH. Values from different categories can be ORed.

Parameter arg for control = ARM_NAND_BUS_MODE | Bit | Category | Description | Supported when ARM_NAND_CAPABILITIES
--- | --- | --- | --- | ---
ARM_NAND_BUS_TIMING_MODE_0 (default) | 0..3 | Bus Timing Mode | 0 | The maximum timing mode that can be applied to a specific Bus Data Interface is stored in the data fields: sdr_timing_mode - for SDR ddr_timing_mode - for NV-DDR ddr2_timing_mode - for NV_DDR2
ARM_NAND_BUS_TIMING_MODE_1 | 1
ARM_NAND_BUS_TIMING_MODE_2 | 2
ARM_NAND_BUS_TIMING_MODE_3 | 3
ARM_NAND_BUS_TIMING_MODE_4 | 4 (SDR EDO capable)
ARM_NAND_BUS_TIMING_MODE_5 | 5 (SDR EDO capable)
ARM_NAND_BUS_TIMING_MODE_6 | 6 (NV-DDR2 only)
ARM_NAND_BUS_TIMING_MODE_7 | 7 (NV-DDR2 only)
ARM_NAND_BUS_SDR (default) | 4..7 | Bus Data Interface | SDR (Single Data Rate) - Traditional interface | always supported
ARM_NAND_BUS_DDR | NV-DDR (Double Data Rate) | data field ddr = 1
ARM_NAND_BUS_DDR2 | NV-DDR2 (Double Data Rate) | data field ddr2 = 1
ARM_NAND_BUS_DDR2_DO_WCYC_0 (default) | 8..11 | Data Output Warm-up | Set the DDR2 Data Output Warm-up to 0 cycles | Data Output Warm-up cycles are dummy cycles for interface calibration with no incremental data transfer and apply to NV-DDR2 of the Bus Data Interface.
ARM_NAND_BUS_DDR2_DO_WCYC_1 | Set the DDR2 Data Output Warm-up to 1 cycles
ARM_NAND_BUS_DDR2_DO_WCYC_2 | Set the DDR2 Data Output Warm-up to 2 cycles
ARM_NAND_BUS_DDR2_DO_WCYC_4 | Set the DDR2 Data Output Warm-up to 4 cycles
ARM_NAND_BUS_DDR2_DI_WCYC_0 (default) | 12..15 | Data Input Warm-up | Set the DDR2 Data Input Warm-up to 0 cycles | Data Input Warm-up cycles are dummy cycles for interface calibration with no incremental data transfer and apply to NV-DDR2 of the Bus Data Interface.
ARM_NAND_BUS_DDR2_DI_WCYC_1 | Set the DDR2 Data Input Warm-up to 1 cycles
ARM_NAND_BUS_DDR2_DI_WCYC_2 | Set the DDR2 Data Input Warm-up to 2 cycles
ARM_NAND_BUS_DDR2_DI_WCYC_4 | Set the DDR2 Data Input Warm-up to 4 cycles
ARM_NAND_BUS_DDR2_VEN | 16 | Miscellaneous | Set the DDR2 Enable external VREFQ as reference |
ARM_NAND_BUS_DDR2_CMPD | 17 | Set the DDR2 Enable complementary DQS (DQS_c) signal
ARM_NAND_BUS_DDR2_CMPR | 18 | Set the DDR2 Enable complementary RE_n (RE_c) signal
Parameter arg for control = ARM_NAND_BUS_DATA_WIDTH | Bit | Category | Description | Supported when ARM_NAND_CAPABILITIES
ARM_NAND_BUS_DATA_WIDTH_8 (default) | 0..1 | Bus Data Width | Set to 8 bit | always supported
ARM_NAND_BUS_DATA_WIDTH_16 | Set to 16 bit | data field data_width_16 = 1
Parameter arg for control = ARM_NAND_DRIVER_STRENGTH | Bit | Category | Description | Supported when ARM_NAND_CAPABILITIES
ARM_NAND_DRIVER_STRENGTH_18 | 0..3 | Driver Strength | Set the Driver Strength 2.0x = 18 Ohms | data field driver_strength_18 = 1
ARM_NAND_DRIVER_STRENGTH_25 | Set the Driver Strength 1.4x = 25 Ohms | data field driver_strength_25 = 1
ARM_NAND_DRIVER_STRENGTH_35 (default) | Set the Driver Strength 1.0x = 35 Ohms | always supported
ARM_NAND_DRIVER_STRENGTH_50 | Set the Driver Strength 0.7x = 50 Ohms | data field driver_strength_50 = 1

Example

extern ARM_DRIVER_NAND Driver_NAND0;
status = Driver_NAND0.Control (0, ARM_NAND_BUS_MODE, ARM_NAND_BUS_TIMING_MODE_5 |
ARM_NAND_BUS_DDR2 |
ARM_NAND_BUS_DDR2_VEN);
status = Driver_NAND0.Control (0, ARM_NAND_BUS_DATA_WIDTH, ARM_NAND_BUS_DATA_WIDTH_16);
status = Driver_NAND0.Control (0, ARM_NAND_DRIVER_STRENGTH, ARM_NAND_DRIVER_STRENGTH_50);
ARM_NAND_DRIVER_STRENGTH
#define ARM_NAND_DRIVER_STRENGTH
Set Driver Strength as specified with arg.
Definition: Driver_NAND.h:83
ARM_NAND_BUS_DDR2
#define ARM_NAND_BUS_DDR2
Data Interface: NV-DDR2 (Double Data Rate)
ARM_NAND_BUS_DDR2_VEN
#define ARM_NAND_BUS_DDR2_VEN
DDR2 Enable external VREFQ as reference.
ARM_NAND_BUS_TIMING_MODE_5
#define ARM_NAND_BUS_TIMING_MODE_5
Timing Mode 5 (SDR EDO capable)
ARM_NAND_BUS_DATA_WIDTH_16
#define ARM_NAND_BUS_DATA_WIDTH_16
Bus Data Width: 16 bit.
ARM_NAND_DRIVER_STRENGTH_50
#define ARM_NAND_DRIVER_STRENGTH_50
Driver Strength 0.7x = 50 Ohms.

## ◆ ARM_NAND_GetStatus()

ARM_NAND_STATUS ARM_NAND_GetStatus | ( | uint32_t | dev_num | ) |

Get NAND status.

Parameters

  [in] | dev_num | Device number

Returns
  NAND status ARM_NAND_STATUS

The function ARM_NAND_GetStatus returns the current NAND device status.

The parameter dev_num is the device number.

## ◆ ARM_NAND_InquireECC()

int32_t ARM_NAND_InquireECC | ( | int32_t | index,
|  | ARM_NAND_ECC_INFO * | info
| ) |  |

Inquire about available ECC.

Parameters

  [in] | index | Inquire ECC index
  [out] | info | Pointer to ECC information ARM_NAND_ECC_INFO retrieved

Returns
  Status Error Codes

The function ARM_NAND_InquireECC reads error correction code information.

The parameter index is the ECC index and is used to retrieve different ECC configurations.
The parameter info is a pointer of type ARM_NAND_ECC_INFO. The data fields store the information.

When multiple different ECC configurations exist, ARM_NAND_ECC_INFO structure exists for each configuration. Parameter index denotes which configuration will be retrieved. Value of index should start with zero to retrieve first ECC configuration and should be incremented in order to retrieve next ECC configuration. When index is out of range function ARM_NAND_InquireECC returns with error.

Parameter index is used by ARM_NAND_ECC(n) in ARM_NAND_ReadData, ARM_NAND_WriteData and ARM_NAND_ExecuteSequence to select suitable ECC configuration.

Example

extern ARM_DRIVER_NAND Driver_NAND0;
ARM_NAND_ECC_INFO ecc;
int32_t idx;
idx = 0;
while (Driver_NAND0.InquireECC (idx, &ecc) == ARM_DRIVER_OK) {
// Examine retrieved ECC configuration
if (ecc.type == 2) {
// Algorithm ECC0 protects Main+Spare
}
// ..
idx++;
}
ARM_DRIVER_OK
#define ARM_DRIVER_OK
Operation succeeded.
ARM_NAND_ECC_INFO::type
uint32_t type
Type: 1=ECC0 over Main, 2=ECC0 over Main+Spare, 3=ECC0 over Main and ECC1 over Spare.
Definition: Driver_NAND.h:186
ARM_DRIVER_NAND::InquireECC
int32_t(* InquireECC)(int32_t index, ARM_NAND_ECC_INFO *info)
Pointer to ARM_NAND_InquireECC : Inquire about available ECC.
Definition: Driver_NAND.h:418
ARM_NAND_ECC_INFO
NAND ECC (Error Correction Code) Information.
Definition: Driver_NAND.h:185

## ◆ ARM_NAND_SignalEvent()

void ARM_NAND_SignalEvent | ( | uint32_t | dev_num,
|  | uint32_t | event
| ) |  |

Signal NAND event.

Parameters

  [in] | dev_num | Device number
  [in] | event | Event notification mask

The function ARM_NAND_SignalEvent is a callback function registered by the function ARM_NAND_Initialize.

The parameter dev_num is the device number.
The parameter event indicates one or more events that occurred during driver operation. Each event is encoded in a separate bit and therefore it is possible to signal multiple events within the same call.

Not every event is necessarily generated by the driver. This depends on the implemented capabilities stored in the data fields of the structure ARM_NAND_CAPABILITIES, which can be retrieved with the function ARM_NAND_GetCapabilities.

The following events can be generated:

Parameter event | Bit | Description
--- | --- | ---
ARM_NAND_EVENT_DEVICE_READY | 0 | Occurs when rising edge is detected on R/Bn (Ready/Busy) pin indicating that the device is ready.
ARM_NAND_EVENT_DRIVER_READY | 1 | Occurs to indicate that commands can be executed (after previously being busy and not able to start the requested operation).
ARM_NAND_EVENT_DRIVER_DONE | 2 | Occurs after an operation completes. An operation was successfully started before with ARM_NAND_ReadData, ARM_NAND_WriteData, ARM_NAND_ExecuteSequence.
ARM_NAND_EVENT_ECC_ERROR | 3 | Occurs when ECC generation failed or ECC correction failed. An operation was successfully started before with ARM_NAND_ReadData, ARM_NAND_WriteData, ARM_NAND_ExecuteSequence.

The event ARM_NAND_EVENT_DEVICE_READY occurs after complete execution of commands (initiated with the functions ARM_NAND_SendCommand, ARM_NAND_SendAddress, ARM_NAND_ReadData, ARM_NAND_WriteData, ARM_NAND_ExecuteSequence). It is useful to indicate completion of complex operations (such as erase). The event is only generated when ARM_NAND_GetCapabilities returns data field event_device_ready = 1 and was enabled by calling ARM_NAND_Control (ARM_NAND_DEVICE_READY_EVENT, 1). If the event is not available, poll the busy data field using the function ARM_NAND_GetStatus.

The event ARM_NAND_EVENT_DRIVER_READY occurs when previously a function (ARM_NAND_SendCommand, ARM_NAND_SendAddress, ARM_NAND_ReadData, ARM_NAND_WriteData, ARM_NAND_ExecuteSequence) returned with ARM_DRIVER_ERROR_BUSY. It is useful when functions are called simultaneously from independent threads (for example to control multiple devices) and the threads have no knowledge about each other (driver rejects reentrant calls with return of ARM_DRIVER_ERROR_BUSY). dev_num indicates the device that returned previously busy.