![]() |
Altera HWLIB
16.0
The Altera HW Manager API Reference Manual
|
This module defines an API for configuration and management of access to NAND flash memory devices through the HPS NAND flash controller.
This API supports the following features:
This API provides basic I/O operations to unmanaged NAND flash memory with optional hardware assisted ECC protection. This module does not provide higher level flash I/O features such as a flash file system or capabilities for bad block life cycle management or wear leveling.
Support of certain operational features may be device dependent and therefore it is important to consult the data sheet for the specific NAND flash device that the NAND flash controller will interface to.
The comments in this module use the following NAND flash terminology:
The NAND flash controller uses indexed addressing to operate on flash device blocks or pages. The NAND flash 32-bit address is organized as follows:
Bits | Description |
---|---|
[31:24] | Reserved - Unused |
[23:m] | Specifies the block address portion of the address. |
[m:0] | Specifies the page address portion of the address. |
where m depends on the number of pages per block for the flash device.
For functions expecting block_addr parameters, only the bits 23 : m are relevant in a 32-bit address argument value. All other bits should be zero or a ALT_E_BAD_ARG is returned.
For functions expecting page_addr parameters, both the bits m : 0 specifying the page as well as the bits 23 : m specifying the block containing the page are relevant in a 32-bit address argument. All other bits should be zero or a ALT_E_BAD_ARG is returned.
Data Structures | |
struct | ALT_NAND_FLASH_ECC_STATUS_s |
Macros | |
#define | ALT_NAND_INVALID_FLASH_ADDR 0xffffffff |
#define | ALT_NAND_BAD_BLOCK_MARKER 0 |
Typedefs | |
typedef void(* | alt_nand_callback_t )(ALT_STATUS_CODE status, void *callback_arg) |
typedef ALT_STATUS_CODE(* | alt_nand_flash_custom_init_t )(void *user_arg) |
typedef enum ALT_NAND_ECC_CORRECTION_e | ALT_NAND_ECC_CORRECTION_t |
typedef struct ALT_NAND_FLASH_ECC_STATUS_s | ALT_NAND_FLASH_ECC_STATUS_t |
typedef enum ALT_NAND_INT_STATUS_e | ALT_NAND_INT_STATUS_t |
typedef uint32_t * | alt_nand_bad_block_table_t |
ENUMS | |
enum | ALT_NAND_ECC_CORRECTION_e { ALT_NAND_ECC_4_BIT_CORRECTION = 4, ALT_NAND_ECC_8_BIT_CORRECTION = 8, ALT_NAND_ECC_16_BIT_CORRECTION = 16, ALT_NAND_ECC_24_BIT_CORRECTION = 24 } |
enum | ALT_NAND_INT_STATUS_e { ALT_NAND_INT_STATUS_PAGE_XFER_INC = (1 << 15), ALT_NAND_INT_STATUS_PIPE_CMD_ERR = (1 << 14), ALT_NAND_INT_STATUS_RST_COMP = (1 << 13), ALT_NAND_INT_STATUS_INT_ACT = (1 << 12), ALT_NAND_INT_STATUS_UNSUP_CMD = (1 << 11), ALT_NAND_INT_STATUS_LOCKED_BLK = (1 << 10), ALT_NAND_INT_STATUS_PIPE_CPYBCK_CMD_COMP = (1 << 9), ALT_NAND_INT_STATUS_ERASE_COMP = (1 << 8), ALT_NAND_INT_STATUS_PROGRAM_COMP = (1 << 7), ALT_NAND_INT_STATUS_LOAD_COMP = (1 << 6), ALT_NAND_INT_STATUS_ERASE_FAIL = (1 << 5), ALT_NAND_INT_STATUS_PROGRAM_FAIL = (1 << 4), ALT_NAND_INT_STATUS_TIME_OUT = (1 << 3), ALT_NAND_INT_STATUS_DMA_CMD_COMP = (1 << 2), ALT_NAND_INT_STATUS_ECC_UNCOR_ERR = (1 << 0) } |
Functions | |
ALT_STATUS_CODE | alt_nand_flash_init (const bool load_block0_page0, const bool page_size_512, alt_nand_flash_custom_init_t custom_init, void *user_arg) |
ALT_STATUS_CODE | alt_nand_flash_uninit (void) |
uint32_t | alt_nand_block_address_get (const uint32_t addr) |
uint32_t | alt_nand_page_address_get (const uint32_t addr) |
uint32_t | alt_nand_flash_addr_compose (const uint32_t block_num, const uint32_t page_num) |
ALT_STATUS_CODE | alt_nand_flash_block_erase (const uint32_t block_addr, alt_nand_callback_t completion_callback, void *completion_arg) |
ALT_STATUS_CODE | alt_nand_flash_page_read (const uint32_t page_addr, const uint32_t num_pages, void *dest, const uint32_t dest_size) |
ALT_STATUS_CODE | alt_nand_flash_page_write (const uint32_t page_addr, const uint32_t num_pages, const void *src, const uint32_t src_size) |
ALT_STATUS_CODE | alt_nand_flash_page_dma_read (const uint32_t page_addr, const uint32_t num_pages, void *dest, const uint32_t dest_size, alt_nand_callback_t completion_callback, void *completion_arg) |
ALT_STATUS_CODE | alt_nand_flash_page_dma_write (const uint32_t page_addr, const uint32_t num_pages, const void *src, const uint32_t src_size, alt_nand_callback_t completion_callback, void *completion_arg) |
ALT_STATUS_CODE | alt_nand_flash_ecc_enable (const ALT_NAND_ECC_CORRECTION_t ecc_correction) |
ALT_STATUS_CODE | alt_nand_flash_ecc_disable (void) |
ALT_STATUS_CODE | alt_nand_flash_ecc_status_get (ALT_NAND_FLASH_ECC_STATUS_t *ecc_status) |
uint32_t | alt_nand_int_status_get (void) |
ALT_STATUS_CODE | alt_nand_int_clear (const uint32_t mask) |
ALT_STATUS_CODE | alt_nand_int_disable (const uint32_t mask) |
ALT_STATUS_CODE | alt_nand_int_enable (const uint32_t mask) |
uint32_t | alt_nand_num_planes_get (void) |
uint32_t | alt_nand_num_blocks_get (void) |
uint32_t | alt_nand_num_pages_per_block_get (void) |
uint32_t | alt_nand_sector_size_get (void) |
uint32_t | alt_nand_spare_size_get (void) |
bool | alt_nand_block_is_bad (const uint32_t block_addr) |
ALT_STATUS_CODE | alt_nand_bad_block_table_get (alt_nand_bad_block_table_t bad_block_table, const uint32_t bad_block_table_len) |
struct ALT_NAND_FLASH_ECC_STATUS_s |
This type defines a structure for accessing the ECC error correction information for the last transaction completed by the NAND flash controller.
#define ALT_NAND_INVALID_FLASH_ADDR 0xffffffff |
Defines an value to represent an invalid or bad flash device address.
#define ALT_NAND_BAD_BLOCK_MARKER 0 |
The ONFI Factory Defect Mapping defined value used by manufacturers to mark a block as defective. A manufacturer marks defective blocks by setting at least one byte in the spare area of the first or last page of the defective block to a value of 0.
typedef void(* alt_nand_callback_t)(ALT_STATUS_CODE status, void *callback_arg) |
Type definition for a callback function prototype used by NAND flash controller API functions to notify users of asynchronous operation completion or operational error status.
status | The final status of the asynchronous operation success or failure. |
completion_arg | A pointer for passing user defined data. The content of this parameter is user defined and is passed when the asynchronous operation is initiated. |
typedef ALT_STATUS_CODE(* alt_nand_flash_custom_init_t)(void *user_arg) |
Type definition for a user defined custom flash device initialization function. This function should be provided for flash devices that do not support automatic device discovery and parameter configuration or devices where customized settings are desired.
This function is invoked by the alt_nand_flash_init() routine at the proper point during the NAND flash controller initialization process.
Returning any status code other than ALT_E_SUCCESS from this custom initialization function will cause the alt_nand_flash_init() function to fail as well.
user_arg | A pointer for optionally passing user defined data. The content of this parameter is user defined and its value may be NULL if unused. |
ALT_E_SUCCESS | Custom flash device initialization was successful. |
ALT_E_ERROR | Custom flash device initialization failed. |
typedef enum ALT_NAND_ECC_CORRECTION_e ALT_NAND_ECC_CORRECTION_t |
This type definition enumerates the possible ECC correction code bit encodings and their applicability to sector size.
typedef struct ALT_NAND_FLASH_ECC_STATUS_s ALT_NAND_FLASH_ECC_STATUS_t |
This type defines a structure for accessing the ECC error correction information for the last transaction completed by the NAND flash controller.
typedef enum ALT_NAND_INT_STATUS_e ALT_NAND_INT_STATUS_t |
This type definition enumerates the interrupt status conditions for the NAND flash controller.
The enumerations serve as masks for the NAND flash controller events that can be set when the designated conditions occur and the corresponding event is enabled. When any of these event source conditions are true, the ALT_INT_INTERRUPT_NAND_IRQ interrupt output is asserted high.
Interrupt sources are cleared when software calls alt_nand_int_clear(). The interrupt sources are individually maskable using alt_nand_int_disable() and alt_nand_int_enable().
The NAND flash controller has a single active high interrupt output (nand_int). This interrupt is the logical "OR" of all of the interrupt bits within the flash controller that are enabled and set. There is also a global interrupt enable in the flash controller block that must be set to enable interrupts. Each interrupt source within the IP has an active high enable bit and a sticky bit. The sticky bit is an active high "write one to clear" status bit. There are four sets of identical interrupt bits, one for each of the four banks. The following conditions can trigger an interrupt:
typedef uint32_t* alt_nand_bad_block_table_t |
This type defines the data structure used to hold the bad block table.
The table is an array composed of uint32_t elements. Each array element contains the bad block status for 32 consecutive blocks on the flash device. The array is of length ceil( alt_nand_num_blocks_get() / 32 ) elements.
Each bit holds the defect status of a block in the device. The LSB bit position of the first element of the array corressponds to the defect status of Block 0. The MSB of the first element of the array corressponds to the defect status of Block 31. The second element of the array contains the defect status of the next 32 consecutive blocks of the device (Blocks 32-63) and so on.
The following code fragment illustrates how the bad block table is used to determine whether a particular block is bad or not:
This type definition enumerates the possible ECC correction code bit encodings and their applicability to sector size.
This type definition enumerates the interrupt status conditions for the NAND flash controller.
The enumerations serve as masks for the NAND flash controller events that can be set when the designated conditions occur and the corresponding event is enabled. When any of these event source conditions are true, the ALT_INT_INTERRUPT_NAND_IRQ interrupt output is asserted high.
Interrupt sources are cleared when software calls alt_nand_int_clear(). The interrupt sources are individually maskable using alt_nand_int_disable() and alt_nand_int_enable().
The NAND flash controller has a single active high interrupt output (nand_int). This interrupt is the logical "OR" of all of the interrupt bits within the flash controller that are enabled and set. There is also a global interrupt enable in the flash controller block that must be set to enable interrupts. Each interrupt source within the IP has an active high enable bit and a sticky bit. The sticky bit is an active high "write one to clear" status bit. There are four sets of identical interrupt bits, one for each of the four banks. The following conditions can trigger an interrupt:
ALT_STATUS_CODE alt_nand_flash_init | ( | const bool | load_block0_page0, |
const bool | page_size_512, | ||
alt_nand_flash_custom_init_t | custom_init, | ||
void * | user_arg | ||
) |
This function initializes the NAND flash controller and attached flash device by:
load_block0_page0 | If true then load block 0, page 0 from the flash device and configure the NAND flash controller for direct read access. This option is typically used by custom preloaders and should be set to false by most users. |
page_size_512 | If true the flash device has a 512 byte page size. This type of device typically does not support automatic discovery and therefore requires custom flash device initialization via the custom_init function. |
custom_init | A pointer to a user defined function to perform customized flash device initialization. The function must program the applicable NAND flash controller registers in the config group based on specific device features and operational performance parameters. The NAND flash controller registers are accessible via the NAND flash controller SoCAL header file "socal/alt_nand.h". A NULL value for this parameter allows the NAND flash controller to do automatic device discovery and parameter configuration. A NULL value should normally be passed for ONFI and supported legacy flash devices. |
user_arg | A user defined argument that is passed to the custom initialization function when invoked. |
ALT_E_SUCCESS | Successful status. |
ALT_E_ERROR | Details about error status code |
ALT_STATUS_CODE alt_nand_flash_uninit | ( | void | ) |
Uninitialize the NAND flash controller.
Uninitialize the NAND flash controller by putting the flash controller into reset.
ALT_E_SUCCESS | Successful status. |
ALT_E_ERROR | Details about error status code |
uint32_t alt_nand_block_address_get | ( | const uint32_t | addr | ) |
Returns the block number of the specified block or page address. The returned block address is right shift aligned to bit 0.
This function may be used after a successful call to alt_nand_flash_init().
addr | A block or page address value. |
uint32_t alt_nand_page_address_get | ( | const uint32_t | addr | ) |
Returns the page number of the specified block or page address. The returned page address is right shift aligned to bit 0.
This function may be used after a successful call to alt_nand_flash_init().
addr | A block or page address value. |
uint32_t alt_nand_flash_addr_compose | ( | const uint32_t | block_num, |
const uint32_t | page_num | ||
) |
Returns a valid block or page address for a flash device with the given block and page argument values.
This function may be used after a successful call to alt_nand_flash_init().
block_num | The flash device block number to use in composing the final flash device address. |
page_num | The flash device page number within the block to use in composing the final flash device address. |
ALT_STATUS_CODE alt_nand_flash_block_erase | ( | const uint32_t | block_addr, |
alt_nand_callback_t | completion_callback, | ||
void * | completion_arg | ||
) |
Erases the designated flash device block.
Erases the flash device block designated by block_addr. The erase operation proceeds asynchronously with a user callback notification upon completion or error.
Flash memory must be erased before being written. Erasing sets all bits in a given block of flash memory to '1' which is the erased state.
block_addr | The block address to erase. |
completion_callback | A user defined callback function that is called when the operation completes or an error occurs. |
completion_arg | A user defined argument that is passed to the callback function when the operation completes or an error occurs. |
ALT_E_SUCCESS | Successful status. |
ALT_E_ERROR | Details about error status code |
ALT_E_BAD_BLK | One or more device block(s) are marked defective and hence the operation was ignored. |
ALT_STATUS_CODE alt_nand_flash_page_read | ( | const uint32_t | page_addr, |
const uint32_t | num_pages, | ||
void * | dest, | ||
const uint32_t | dest_size | ||
) |
Read one or more pages from the flash device.
Reads num_pages from the flash device beginning at page_addr. Whole pages are read from flash memory. The pages are copied into the dest location.
If ECC is enabled then the NAND flash controller performs ECC correction and detection on the fly as data is read from the device and before being transferred out of the controller.
page_addr | The beginning page address to read. |
num_pages | The number of pages to read. |
dest | The address of the destination buffer. |
dest_size | The size of the destination buffer in bytes. |
ALT_E_SUCCESS | Successful status. |
ALT_E_ERROR | Details about error status code |
ALT_E_BAD_BLK | The device block is marked defective and hence the operation was ignored. |
ALT_E_BUF_OVF | The destination buffer does not contain enough space for the operation. |
ALT_E_ECC_UNCOR | An uncorrected ECC error occurred. |
ALT_STATUS_CODE alt_nand_flash_page_write | ( | const uint32_t | page_addr, |
const uint32_t | num_pages, | ||
const void * | src, | ||
const uint32_t | src_size | ||
) |
Write one or more pages to the flash device.
Writes num_pages to the flash device beginning at page_addr. Whole pages are written to flash memory. The block(s) containing the pages must have been previously erased.
page_addr | The beginning page address to write. |
num_pages | The number of pages to write. |
src | The address of the source buffer containing th data to be written to the flash device. |
src_size | The size of the source buffer in bytes. |
ALT_E_SUCCESS | Successful status. |
ALT_E_ERROR | Details about error status code |
ALT_E_BAD_BLK | The device block is marked defective and hence the operation was ignored. |
ALT_E_BUF_OVF | The source buffer is larger than the flash device page(s) destination. |
ALT_STATUS_CODE alt_nand_flash_page_dma_read | ( | const uint32_t | page_addr, |
const uint32_t | num_pages, | ||
void * | dest, | ||
const uint32_t | dest_size, | ||
alt_nand_callback_t | completion_callback, | ||
void * | completion_arg | ||
) |
Read one or more pages from the flash device using the NAND flash controller's internal DMA. The read operation proceeds asynchronously with a user callback notification upon completion or error.
Reads num_pages from the flash device beginning at page_addr. Whole pages are read from flash memory. The pages are copied into the dest location.
If ECC is enabled then the NAND flash controller performs ECC correction and detection on the fly as data is read from the device and before being transferred out of the controller.
page_addr | The beginning page address to read. |
num_pages | The number of pages to read. |
dest | The address of the destination buffer. |
dest_size | The size of the destination buffer in bytes. |
completion_callback | A user defined callback function that is called when the operation completes or an error occurs. |
completion_arg | A user defined argument that is passed to the callback function when the operation completes or an error occurs. |
ALT_E_SUCCESS | Successful status. |
ALT_E_ERROR | Details about error status code |
ALT_E_BAD_BLK | The device block is marked defective and hence the operation was ignored. |
ALT_E_BUF_OVF | The destination buffer does not contain enough space for the operation. |
ALT_STATUS_CODE alt_nand_flash_page_dma_write | ( | const uint32_t | page_addr, |
const uint32_t | num_pages, | ||
const void * | src, | ||
const uint32_t | src_size, | ||
alt_nand_callback_t | completion_callback, | ||
void * | completion_arg | ||
) |
Write one or more pages to the flash device using the NAND flash controller's internal DMA. The write operation proceeds asynchronously with a user callback notification upon completion or error.
Writes num_pages to the flash device beginning at page_addr. Whole pages are written to flash memory. The block(s) containing the pages must have been previously erased.
page_addr | The beginning page address to write. |
num_pages | The number of pages to write. |
src | The address of the source buffer containing th data to be written to the flash device. |
src_size | The size of the source buffer in bytes. |
completion_callback | A user defined callback function that is called when the operation completes or an error occurs. |
completion_arg | A user defined argument that is passed to the callback function when the operation completes or an error occurs. |
ALT_E_SUCCESS | Successful status. |
ALT_E_ERROR | Details about error status code |
ALT_E_BAD_BLK | The device block is marked defective and hence the operation was ignored. |
ALT_E_BUF_OVF | The destination buffer does not contain enough space for the operation. |
ALT_STATUS_CODE alt_nand_flash_ecc_enable | ( | const ALT_NAND_ECC_CORRECTION_t | ecc_correction | ) |
Enable hardware ECC protection for the flash device.
ecc_correction | The desired ECC correction code bit encoding. |
ALT_E_SUCCESS | Indicates successful completion. |
ALT_E_ERROR | Indicates an error occurred. |
ALT_E_INV_OPTION | The specified ECC correction value is not appropriate for the device page size and spare area available. |
ALT_STATUS_CODE alt_nand_flash_ecc_disable | ( | void | ) |
Disable hardware ECC protection for the flash device.
ALT_E_SUCCESS | Indicates successful completion. |
ALT_E_ERROR | Indicates an error occurred. |
ALT_STATUS_CODE alt_nand_flash_ecc_status_get | ( | ALT_NAND_FLASH_ECC_STATUS_t * | ecc_status | ) |
Gets the ECC error correction information for the last transaction completed by the NAND flash controller.
ecc_status | [out] Pointer to a ALT_NAND_FLASH_ECC_STATUS_t structure containing the ECC status for the last completed transaction. |
ALT_E_SUCCESS | Indicates successful completion. |
ALT_E_ERROR | Indicates an error occurred. |
uint32_t alt_nand_int_status_get | ( | void | ) |
Returns the NAND flash controller interrupt status register value.
This function returns the current value of the NAND flash controller interrupt status register value which reflects the current NAND flash controller status conditions.
ALT_STATUS_CODE alt_nand_int_clear | ( | const uint32_t | mask | ) |
Clears the specified NAND flash controller interrupt status conditions identified in the mask.
This function clears one or more of the status conditions as contributors to the ALT_INT_INTERRUPT_NAND_IRQ interrupt signal state.
mask | Specifies the QSPI interrupt status conditions to clear. mask is a mask of logically OR'ed ALT_NAND_INT_STATUS_t values that designate the status conditions to clear. |
ALT_E_SUCCESS | Indicates successful completion. |
ALT_E_ERROR | Indicates an error occurred. |
ALT_STATUS_CODE alt_nand_int_disable | ( | const uint32_t | mask | ) |
Disable the specified NAND flash controller interrupt status conditions identified in the mask.
This function disables one or more of the status conditions as contributors to the ALT_INT_INTERRUPT_NAND_IRQ interrupt signal state.
NOTE: A cleared bit for any status condition in the mask value does not have the effect of enabling it as a contributor to the ALT_INT_INTERRUPT_NAND_IRQ interrupt signal state. The function alt_nand_int_enable() is used to enable status source conditions.
mask | Specifies the status conditions to disable as interrupt source contributors. mask is a mask of logically OR'ed ALT_NAND_INT_STATUS_t values that designate the status conditions to disable. |
ALT_E_SUCCESS | Indicates successful completion. |
ALT_E_ERROR | Indicates an error occurred. |
ALT_STATUS_CODE alt_nand_int_enable | ( | const uint32_t | mask | ) |
Enable the specified NAND flash controller interrupt status conditions identified in the mask.
This function enables one or more of the status conditions as contributors to the ALT_INT_INTERRUPT_NAND_IRQ interrupt signal state.
NOTE: A cleared bit for any status condition in the mask value does not have the effect of disabling it as a contributor to the ALT_INT_INTERRUPT_NAND_IRQ interrupt signal state. The function alt_nand_int_disable() is used to disable status source conditions.
mask | Specifies the status conditions to enable as interrupt source contributors. mask is a mask of logically OR'ed ALT_NAND_INT_STATUS_t values that designate the status conditions to enable. |
ALT_E_SUCCESS | Indicates successful completion. |
ALT_E_ERROR | Indicates an error occurred. |
uint32_t alt_nand_num_planes_get | ( | void | ) |
Returns the number of planes in the flash memory device.
Returns the number of planes as read from the device during discovery and parameter configuration. For 512 byte devices this information typically has to be manually programmed by software.
uint32_t alt_nand_num_blocks_get | ( | void | ) |
Returns the number of blocks in the flash memory device.
Returns the number of blocks as read from the device during discovery and parameter configuration. For 512 byte devices this information typically has to be manually programmed by software.
uint32_t alt_nand_num_pages_per_block_get | ( | void | ) |
Returnes the number of pages per device block.
Returns the number of pages per block as read from the device during discovery and parameter configuration. For 512 byte devices this information typically has to be manually programmed by software.
uint32_t alt_nand_sector_size_get | ( | void | ) |
Returns the size of a page sector in bytes.
Returns the size of a page sector in bytes as read from the device during discovery and parameter configuration. For 512 byte devices this information typically has to be manually programmed by software.
uint32_t alt_nand_spare_size_get | ( | void | ) |
Returns the size of a page spare area in bytes.
Returns the size of a page spare area in bytes as read from the device during discovery and parameter configuration. For 512 byte devices this information typically has to be manually programmed by software.
bool alt_nand_block_is_bad | ( | const uint32_t | block_addr | ) |
Returns true if the specified device block is bad otherwise returns false.
Returns true if the specified device block is marked defective (i.e. bad) and should not be used. Otherwise the device block is assumed usable and true is returned.
block_addr | The block address to check. |
ALT_STATUS_CODE alt_nand_bad_block_table_get | ( | alt_nand_bad_block_table_t | bad_block_table, |
const uint32_t | bad_block_table_len | ||
) |
Get a copy of the bad block table for the device.
Returns a copy of the bad block table for the device in a user specified buffer. The size and organization of the bad block table are described in alt_nand_bad_block_table_t.
bad_block_table | [out] Pointer to a buffer of type alt_nand_bad_block_table_t to return a copy of the bad block table in. |
bad_block_table_len | The length of the bad_block_table parameter in number of elements. |
ALT_E_SUCCESS | Indicates successful completion. |
ALT_E_ERROR | Indicates an error occurred. |
ALT_E_BAD_ARG | The bad_block_table_len specifies a bad_block_table length that is not large enough to hold a copy of the bad block table for the device. |