| /****************************************************************************** | |
| * | |
| * Copyright 2013 Altera Corporation. All Rights Reserved. | |
| * | |
| * Redistribution and use in source and binary forms, with or without | |
| * modification, are permitted provided that the following conditions are met: | |
| * | |
| * 1. Redistributions of source code must retain the above copyright notice, | |
| * this list of conditions and the following disclaimer. | |
| * | |
| * 2. Redistributions in binary form must reproduce the above copyright notice, | |
| * this list of conditions and the following disclaimer in the documentation | |
| * and/or other materials provided with the distribution. | |
| * | |
| * 3. The name of the author may not be used to endorse or promote products | |
| * derived from this software without specific prior written permission. | |
| * | |
| * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER "AS IS" AND ANY EXPRESS OR | |
| * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF | |
| * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, ARE DISCLAIMED. IN NO | |
| * EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, | |
| * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT | |
| * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS | |
| * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN | |
| * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING | |
| * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY | |
| * OF SUCH DAMAGE. | |
| * | |
| ******************************************************************************/ | |
| /*! \file | |
| * Altera - NAND Flash Controller Module | |
| */ | |
| #ifndef __ALT_NAND_FLASH_H__ | |
| #define __ALT_NAND_FLASH_H__ | |
| #include "hwlib.h" | |
| #ifdef __cplusplus | |
| extern "C" | |
| { | |
| #endif /* __cplusplus */ | |
| /******************************************************************************/ | |
| /*! \addtogroup ALT_NAND_FLASH NAND Flash Controller | |
| * | |
| * 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: | |
| * * Support for ONFI 1.0 devices or legacy devices that can be identified by | |
| * the NAND flash controller. | |
| * * Automatic initialization and discovery of supported NAND flash devices. | |
| * * ECC protection in hardware. | |
| * * Erase by block. | |
| * * Read/Write by (whole) pages. | |
| * * DMA read/write transfers. | |
| * | |
| * 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: | |
| * * \b Plane - A collection of blocks typically on a single die of a multi-die | |
| * device. | |
| * * \b Block - The basic unit of NAND flash memory. Blocks are the smallest unit | |
| * that can be erased. Blocks contain pages. | |
| * * \b Page - A subdivision of a block. It contains the data payload and spare | |
| * data areas used to store ECC and bad block information. | |
| * * \b Sector - A subdivision of a page. It contains the data payload protected | |
| * by ECC. | |
| * * \b Spare - The area of a page used to store ECC and bad block information. | |
| * | |
| * 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] | <em>Reserved - Unused</em> | |
| * [23:\e m] | Specifies the block address portion of the address. | |
| * [\e m:0] | Specifies the page address portion of the address. | |
| * | |
| * where \e m depends on the number of pages per block for the flash device. | |
| * | |
| * For functions expecting \e block_addr parameters, only the bits 23 : \e 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 \e page_addr parameters, both the bits \e m : 0 | |
| * specifying the page as well as the bits 23 : \e 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. | |
| * | |
| * \internal | |
| * General Implementation Notes: | |
| * * Command data and control paths that bypass HW ECC or require SW ECC are not | |
| * used in this implementation or supported by the API. This does not imply that | |
| * a user must elect to enable ECC in order to use flash memory but if the user | |
| * so chooses then this module API only employs HW assisted ECC protection in | |
| * its implementation. | |
| * * Whether to use ECC protection or not should be decided from the first used of | |
| * the NAND flash device and then used consistently thereafter. Once ECC | |
| * protection is enabled then the flash memory locations must be initialized | |
| * before ever reading from them. Flash memory is initialized by erasing and | |
| * then writing to the flash memory while ECC is enabled. | |
| * * The ECC program mode of "Main Area Transfer Mode" operation is used and | |
| * maintained throughout the implementation of this API. No API is provided for | |
| * switching ECC program modes in order to simplify the implementation and user | |
| * programming model. | |
| * \endinternal | |
| * | |
| * @{ | |
| */ | |
| /*! | |
| * 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. | |
| * | |
| * \param status | |
| * The final status of the asynchronous operation success or failure. | |
| * | |
| * \param 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 void (*alt_nand_callback_t)(ALT_STATUS_CODE status, void *callback_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. | |
| * | |
| * \param 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. | |
| * | |
| * \retval ALT_E_SUCCESS Custom flash device initialization was successful. | |
| * \retval ALT_E_ERROR Custom flash device initialization failed. | |
| */ | |
| typedef ALT_STATUS_CODE (*alt_nand_flash_custom_init_t)(void *user_arg); | |
| /*! | |
| * This function initializes the NAND flash controller and attached flash device by: | |
| * * Taking the NAND flash controller out of reset. | |
| * * Performing automatic NAND flash device discovery and parameter configuration | |
| * for supported devices. | |
| * * Optionally loading block 0, page 0 of the device and configuring direct read | |
| * access (preloader use case only). | |
| * * And assuming the device discovery and parameter configuration (automatic or | |
| * custom) process is successful, then scans the device for blocks marked as | |
| * defective at manufacture time and builds a bad block table. The bad block | |
| * table is used at runtime to avoid erasing or programming any block marked as | |
| * defective. | |
| * | |
| * \param load_block0_page0 | |
| * If \b 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 | |
| * \b false by most users. | |
| * | |
| * \param page_size_512 | |
| * If \b 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 \e | |
| * custom_init function. | |
| * | |
| * \param 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. | |
| * | |
| * \param user_arg | |
| * A user defined argument that is passed to the custom | |
| * initialization function when invoked. | |
| * | |
| * \retval ALT_E_SUCCESS Successful status. | |
| * \retval ALT_E_ERROR Details about error status code | |
| * | |
| * \internal | |
| * See: | |
| * * Cadence DB | |
| * - Section 4.4 Initialization Protocol | |
| * - Section 11.2 Device Initialization Sequence | |
| * - Section 11.3 Device Operation Control (Maybe?) | |
| * * CV Device Handbook | |
| * - Discovery and Initialization | |
| * - Bootstrap Interface | |
| * - Configuration by Host (Provide SW hook) | |
| * - Clocks | |
| * - Resets | |
| * - Device Initialization Sequence | |
| * * Open NAND Flash Interface Specification Revision 1.0 | |
| * - Section 3.2. Factory Defect Mapping for bad block table construction. | |
| * | |
| * 1) Discovery and Initialization section of HPS TRM | |
| * 2) Bootstrap Interface section of HPS TRM | |
| * 3) Configuration by Host section of HPS TRM | |
| * | |
| * Checks: | |
| * - nand_x_clk and nand_clk | |
| * | |
| * ONFI - Use ONFI discovery protocol to identify device and read its feature properties. | |
| * | |
| * Legacy - Use the Read Electronic Signature command to identify device. | |
| * | |
| * Others - Generally 512 byte page size devices. | |
| * | |
| * Unless bootstrap_inhibit_b0p0_load (sysmgr.nandgrp.bootstrap.noloadb0p0) signal | |
| * is asserted, the NAND flash controller will page load block 0/page 0 to | |
| * allow for booting. | |
| * | |
| * If bootstrap_inhibit_init () is asserted the NAND flash controller do not | |
| * perform initialization and just issues a RESET command to the device. | |
| * | |
| * \endinternal | |
| */ | |
| 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); | |
| /*! | |
| * Uninitialize the NAND flash controller. | |
| * | |
| * Uninitialize the NAND flash controller by putting the flash controller into | |
| * reset. | |
| * | |
| * \retval ALT_E_SUCCESS Successful status. | |
| * \retval ALT_E_ERROR Details about error status code | |
| * | |
| * \internal | |
| * \endinternal | |
| */ | |
| ALT_STATUS_CODE alt_nand_flash_uninit(void); | |
| /*! | |
| * Defines an value to represent an invalid or bad flash device address. | |
| */ | |
| #define ALT_NAND_INVALID_FLASH_ADDR 0xffffffff | |
| /*! | |
| * 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(). | |
| * | |
| * \param addr | |
| * A block or page address value. | |
| * | |
| * \returns The bit 0 right aligned block address portion of the \e addr | |
| * argument. | |
| */ | |
| uint32_t alt_nand_block_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(). | |
| * | |
| * \param addr | |
| * A block or page address value. | |
| * | |
| * \returns The bit 0 right aligned page address portion of the \e addr | |
| * argument. | |
| */ | |
| uint32_t alt_nand_page_address_get(const uint32_t addr); | |
| /*! | |
| * 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(). | |
| * | |
| * \param block_num | |
| * The flash device block number to use in composing the final flash | |
| * device address. | |
| * | |
| * \param page_num | |
| * The flash device page number within the block to use in composing | |
| * the final flash device address. | |
| * | |
| * \returns A valid block or page address for the flash | |
| * device. ALT_NAND_INVALID_FLASH_ADDR is returned if either of the \e | |
| * block_num or \e page_num arguments is invalid for the device. | |
| */ | |
| uint32_t alt_nand_flash_addr_compose(const uint32_t block_num, | |
| const uint32_t page_num); | |
| /*! | |
| * Erases the designated flash device block. | |
| * | |
| * Erases the flash device block designated by \e 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. | |
| * | |
| * \param block_addr | |
| * The block address to erase. | |
| * | |
| * \param completion_callback | |
| * A user defined callback function that is called when the operation | |
| * completes or an error occurs. | |
| * | |
| * \param completion_arg | |
| * A user defined argument that is passed to the callback function | |
| * when the operation completes or an error occurs. | |
| * | |
| * \retval ALT_E_SUCCESS Successful status. | |
| * \retval ALT_E_ERROR Details about error status code | |
| * \retval ALT_E_BAD_BLK One or more device block(s) are marked defective | |
| * and hence the operation was ignored. | |
| * | |
| * \internal | |
| * See: | |
| * * CV Device Handbook | |
| * - Flash-Related Special Function Operations - Erase Operations | |
| * + Single Block Erase | |
| * + Multi-Plane Erase | |
| * | |
| * Command to erase a single block (section 5.2.3.1 of Cadence DB). | |
| * \endinternal | |
| */ | |
| ALT_STATUS_CODE alt_nand_flash_block_erase(const uint32_t block_addr, | |
| alt_nand_callback_t completion_callback, | |
| void *completion_arg); | |
| /*! | |
| * Read one or more pages from the flash device. | |
| * | |
| * Reads \e num_pages from the flash device beginning at \e page_addr. Whole pages | |
| * are read from flash memory. The pages are copied into the \e 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. | |
| * | |
| * \param page_addr | |
| * The beginning page address to read. | |
| * | |
| * \param num_pages | |
| * The number of pages to read. | |
| * | |
| * \param dest | |
| * The address of the destination buffer. | |
| * | |
| * \param dest_size | |
| * The size of the destination buffer in bytes. | |
| * | |
| * \retval ALT_E_SUCCESS Successful status. | |
| * \retval ALT_E_ERROR Details about error status code | |
| * \retval ALT_E_BAD_BLK The device block is marked defective and hence the | |
| * operation was ignored. | |
| * \retval ALT_E_BUF_OVF The destination buffer does not contain enough space | |
| * for the operation. | |
| * \retval ALT_E_ECC_UNCOR An uncorrected ECC error occurred. | |
| * | |
| * \internal | |
| * See: | |
| * * CV Device Handbook | |
| * - Indexed Addressing | |
| * - MAP01 Commands | |
| * - MAP10 Commands | |
| * - Data DMA (ignore Burst DMA) | |
| * * Pipeline Read-Ahead and Write-Ahead Operations | |
| * | |
| * Map01 Commands (section 5.2.2 of Cadence DB). | |
| * Pipeline read-ahead operations (sections 5.2.3.6 and 5.2.3.6.1 of Cadence DB). | |
| * | |
| * Do not use Map00 in this implementation. ECC correction is not performed while | |
| * doing such operations and is not recommended in MLC devices. | |
| * | |
| * Entire page(s) are read. | |
| * | |
| * Use Map01 for single page reads. | |
| * | |
| * Use pipeline read-ahead technique to optimize multi-page reads. | |
| * \endinternal | |
| */ | |
| 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); | |
| /*! | |
| * Write one or more pages to the flash device. | |
| * | |
| * Writes \e num_pages to the flash device beginning at \e page_addr. Whole pages | |
| * are written to flash memory. The block(s) containing the pages must have been | |
| * previously erased. | |
| * | |
| * \param page_addr | |
| * The beginning page address to write. | |
| * | |
| * \param num_pages | |
| * The number of pages to write. | |
| * | |
| * \param src | |
| * The address of the source buffer containing th data to be written | |
| * to the flash device. | |
| * | |
| * \param src_size | |
| * The size of the source buffer in bytes. | |
| * | |
| * \retval ALT_E_SUCCESS Successful status. | |
| * \retval ALT_E_ERROR Details about error status code | |
| * \retval ALT_E_BAD_BLK The device block is marked defective and hence the | |
| * operation was ignored. | |
| * \retval ALT_E_BUF_OVF The source buffer is larger than the flash device | |
| * page(s) destination. | |
| * | |
| * \internal | |
| * \endinternal | |
| */ | |
| 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); | |
| /*! | |
| * 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 \e num_pages from the flash device beginning at \e page_addr. Whole pages | |
| * are read from flash memory. The pages are copied into the \e 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. | |
| * | |
| * \param page_addr | |
| * The beginning page address to read. | |
| * | |
| * \param num_pages | |
| * The number of pages to read. | |
| * | |
| * \param dest | |
| * The address of the destination buffer. | |
| * | |
| * \param dest_size | |
| * The size of the destination buffer in bytes. | |
| * | |
| * \param completion_callback | |
| * A user defined callback function that is called when the operation | |
| * completes or an error occurs. | |
| * | |
| * \param completion_arg | |
| * A user defined argument that is passed to the callback function | |
| * when the operation completes or an error occurs. | |
| * | |
| * \retval ALT_E_SUCCESS Successful status. | |
| * \retval ALT_E_ERROR Details about error status code | |
| * \retval ALT_E_BAD_BLK The device block is marked defective and hence the | |
| * operation was ignored. | |
| * \retval ALT_E_BUF_OVF The destination buffer does not contain enough space | |
| * for the operation. | |
| * | |
| * \internal | |
| * See: | |
| * * CV Device Handbook | |
| * - Data DMA | |
| * - Multitransaction DMA Command | |
| * - Interrupt and DMA Enabling | |
| * * Pipeline Read-Ahead and Write-Ahead Operations | |
| * \endinternal | |
| */ | |
| 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); | |
| /*! | |
| * 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 \e num_pages to the flash device beginning at \e page_addr. Whole pages | |
| * are written to flash memory. The block(s) containing the pages must have been | |
| * previously erased. | |
| * | |
| * \param page_addr | |
| * The beginning page address to write. | |
| * | |
| * \param num_pages | |
| * The number of pages to write. | |
| * | |
| * \param src | |
| * The address of the source buffer containing th data to be written | |
| * to the flash device. | |
| * | |
| * \param src_size | |
| * The size of the source buffer in bytes. | |
| * | |
| * \param completion_callback | |
| * A user defined callback function that is called when the operation | |
| * completes or an error occurs. | |
| * | |
| * \param completion_arg | |
| * A user defined argument that is passed to the callback function | |
| * when the operation completes or an error occurs. | |
| * | |
| * \retval ALT_E_SUCCESS Successful status. | |
| * \retval ALT_E_ERROR Details about error status code | |
| * \retval ALT_E_BAD_BLK The device block is marked defective and hence the | |
| * operation was ignored. | |
| * \retval ALT_E_BUF_OVF The destination buffer does not contain enough space | |
| * for the operation. | |
| * | |
| * \internal | |
| * See: | |
| * * CV Device Handbook | |
| * - Data DMA | |
| * - Multitransaction DMA Command | |
| * - Interrupt and DMA Enabling | |
| * * Pipeline Read-Ahead and Write-Ahead Operations | |
| * \endinternal | |
| */ | |
| 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); | |
| /*! | |
| * This type definition enumerates the possible ECC correction code bit encodings | |
| * and their applicability to sector size. | |
| */ | |
| typedef enum ALT_NAND_ECC_CORRECTION_e | |
| { | |
| ALT_NAND_ECC_4_BIT_CORRECTION = 4, /*!< Performs 4 bit correction over a 512 byte sector */ | |
| ALT_NAND_ECC_8_BIT_CORRECTION = 8, /*!< Performs 8 bit correction over a 512 byte sector */ | |
| ALT_NAND_ECC_16_BIT_CORRECTION = 16, /*!< Performs 16 bit correction over a 512 byte sector */ | |
| ALT_NAND_ECC_24_BIT_CORRECTION = 24 /*!< Performs 24 bit correction over a 1024 byte sector */ | |
| } ALT_NAND_ECC_CORRECTION_t; | |
| /*! | |
| * Enable hardware ECC protection for the flash device. | |
| * | |
| * \param ecc_correction | |
| * The desired ECC correction code bit encoding. | |
| * | |
| * \retval ALT_E_SUCCESS Indicates successful completion. | |
| * \retval ALT_E_ERROR Indicates an error occurred. | |
| * \retval ALT_E_INV_OPTION The specified ECC correction value is not | |
| * appropriate for the device page size and | |
| * spare area available. | |
| * | |
| * \internal | |
| * See: Cadence DB - Section 11.4 ECC Enabling | |
| * \endinternal | |
| */ | |
| ALT_STATUS_CODE alt_nand_flash_ecc_enable(const ALT_NAND_ECC_CORRECTION_t ecc_correction); | |
| /*! | |
| * Disable hardware ECC protection for the flash device. | |
| * | |
| * \retval ALT_E_SUCCESS Indicates successful completion. | |
| * \retval ALT_E_ERROR Indicates an error occurred. | |
| * | |
| * \internal | |
| * See: Cadence DB - Section 11.4 ECC Enabling | |
| * \endinternal | |
| */ | |
| ALT_STATUS_CODE alt_nand_flash_ecc_disable(void); | |
| /*! | |
| * This type defines a structure for accessing the ECC error correction | |
| * information for the last transaction completed by the NAND flash controller. | |
| */ | |
| typedef struct ALT_NAND_FLASH_ECC_STATUS_s | |
| { | |
| uint32_t corrected_errors[4]; /*!< Maximum of number of errors corrected | |
| * per sector in a bank. This field is | |
| * not valid for uncorrectable errors. A | |
| * value of zero indicates that no ECC | |
| * error occurred in last completed | |
| * transaction. Index \e n corressponds | |
| * to bank \e n. | |
| */ | |
| bool uncorrected_error[4]; /*!< \b true if an uncorrectable error | |
| * occurred while reading pages for last | |
| * transaction in a bank. Uncorrectable | |
| * errors also generate | |
| * ALT_NAND_INT_STATUS_ECC_UNCOR_ERR | |
| * interrupt status conditions. Index | |
| * \e n corressponds to bank \e n. | |
| */ | |
| } ALT_NAND_FLASH_ECC_STATUS_t; | |
| /*! | |
| * Gets the ECC error correction information for the last transaction completed by | |
| * the NAND flash controller. | |
| * | |
| * \param ecc_status | |
| * [out] Pointer to a \ref ALT_NAND_FLASH_ECC_STATUS_t structure | |
| * containing the ECC status for the last completed transaction. | |
| * | |
| * \retval ALT_E_SUCCESS Indicates successful completion. | |
| * \retval ALT_E_ERROR Indicates an error occurred. | |
| * | |
| * \internal | |
| * nandregs.ecc.ECCCorInfo_b01 | |
| * nandregs.ecc.ECCCorInfo_b23 | |
| * \endinternal | |
| */ | |
| ALT_STATUS_CODE alt_nand_flash_ecc_status_get(ALT_NAND_FLASH_ECC_STATUS_t *ecc_status); | |
| /*! | |
| * 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 \b | |
| * 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: | |
| * - Page transfer | |
| * - Pipeline command sequence violation | |
| * - Rest/initialization complete | |
| * - Ready/Busy pin low to high transition | |
| * - Unsupported command | |
| * - Locked block command failure | |
| * - Pipeline command or copyback command complete | |
| * - Erase complete | |
| * - Program complete | |
| * - Load complete | |
| * - Erase fail | |
| * - Program fail | |
| * - Timeout | |
| * - DMA command complete | |
| * - Uncorrectable ECC error | |
| */ | |
| typedef enum ALT_NAND_INT_STATUS_e | |
| { | |
| ALT_NAND_INT_STATUS_PAGE_XFER_INC = (1 << 15), | |
| /*!< For every page of data | |
| * transfer to or from the | |
| * device, this status will be | |
| * set. | |
| */ | |
| ALT_NAND_INT_STATUS_PIPE_CMD_ERR = (1 << 14), | |
| /*!< A pipeline command sequence | |
| * has been violated. This | |
| * occurs when MAP01 page | |
| * read/write address does not | |
| * match the corresponding | |
| * expected address from the | |
| * pipeline commands issued | |
| * earlier. | |
| */ | |
| ALT_NAND_INT_STATUS_RST_COMP = (1 << 13), | |
| /*!< The NAND flash controller | |
| * has finished reset and | |
| * initialization process. | |
| */ | |
| ALT_NAND_INT_STATUS_INT_ACT = (1 << 12), | |
| /*!< R/B pin of device | |
| * transitioned from low to | |
| * high. | |
| */ | |
| ALT_NAND_INT_STATUS_UNSUP_CMD = (1 << 11), | |
| /*!< An unsupported command was | |
| * received. This interrupt is | |
| * set when an invalid command | |
| * is received, or when a | |
| * command sequence is broken. | |
| */ | |
| ALT_NAND_INT_STATUS_LOCKED_BLK = (1 << 10), | |
| /*!< The address to program or | |
| * erase operation is to a | |
| * locked block and the | |
| * operation failed due to this | |
| * reason. | |
| */ | |
| ALT_NAND_INT_STATUS_PIPE_CPYBCK_CMD_COMP = (1 << 9), | |
| /*!< A pipeline command or a | |
| * copyback bank command has | |
| * completed on this particular | |
| * bank. | |
| */ | |
| ALT_NAND_INT_STATUS_ERASE_COMP = (1 << 8), | |
| /*!< Device erase operation | |
| * complete. | |
| */ | |
| ALT_NAND_INT_STATUS_PROGRAM_COMP = (1 << 7), | |
| /*!< Device finished the last | |
| * issued program command. | |
| */ | |
| ALT_NAND_INT_STATUS_LOAD_COMP = (1 << 6), | |
| /*!< Device finished the last | |
| * issued load command. | |
| */ | |
| ALT_NAND_INT_STATUS_ERASE_FAIL = (1 << 5), | |
| /*!< Erase failure occurred in the | |
| * device on issuance of a erase | |
| * command. err_block_addr and | |
| * err_page_addr contain the | |
| * block address and page | |
| * address that failed erase | |
| * operation. | |
| */ | |
| ALT_NAND_INT_STATUS_PROGRAM_FAIL = (1 << 4), | |
| /*!< Program failure occurred in | |
| * the device on issuance of a | |
| * program | |
| * command. err_block_addr and | |
| * err_page_addr contain the | |
| * block address and page | |
| * address that failed program | |
| * operation. | |
| */ | |
| ALT_NAND_INT_STATUS_TIME_OUT = (1 << 3), | |
| /*!< Watchdog timer has triggered | |
| * in the controller due to one | |
| * of the reasons like device | |
| * not responding or controller | |
| * state machine did not get | |
| * back to idle. | |
| */ | |
| ALT_NAND_INT_STATUS_DMA_CMD_COMP = (1 << 2), | |
| /*!< A data DMA command has | |
| * completed on this bank. | |
| */ | |
| ALT_NAND_INT_STATUS_ECC_UNCOR_ERR = (1 << 0) | |
| /*!< ECC logic detected | |
| * uncorrectable error while | |
| * reading data from flash | |
| * device. | |
| */ | |
| } ALT_NAND_INT_STATUS_t; | |
| /*! | |
| * 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. | |
| * | |
| * \returns The current value of the NAND flash controller interrupt status | |
| * register value which reflects the current NAND flash controller | |
| * status conditions as defined by the \ref ALT_NAND_INT_STATUS_t | |
| * mask. If the corresponding bit is set then the condition is | |
| * asserted. | |
| */ | |
| uint32_t alt_nand_int_status_get(void); | |
| /*! | |
| * 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 \b ALT_INT_INTERRUPT_NAND_IRQ interrupt signal state. | |
| * | |
| * \param mask | |
| * Specifies the QSPI interrupt status conditions to clear. \e mask | |
| * is a mask of logically OR'ed \ref ALT_NAND_INT_STATUS_t values | |
| * that designate the status conditions to clear. | |
| * | |
| * \retval ALT_E_SUCCESS Indicates successful completion. | |
| * \retval ALT_E_ERROR Indicates an error occurred. | |
| */ | |
| ALT_STATUS_CODE alt_nand_int_clear(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 \b 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 \b ALT_INT_INTERRUPT_NAND_IRQ | |
| * interrupt signal state. The function alt_nand_int_enable() is used to enable | |
| * status source conditions. | |
| * | |
| * \param mask | |
| * Specifies the status conditions to disable as interrupt source | |
| * contributors. \e mask is a mask of logically OR'ed \ref | |
| * ALT_NAND_INT_STATUS_t values that designate the status conditions | |
| * to disable. | |
| * | |
| * \retval ALT_E_SUCCESS Indicates successful completion. | |
| * \retval ALT_E_ERROR Indicates an error occurred. | |
| */ | |
| ALT_STATUS_CODE alt_nand_int_disable(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 \b 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 \b ALT_INT_INTERRUPT_NAND_IRQ | |
| * interrupt signal state. The function alt_nand_int_disable() is used to disable | |
| * status source conditions. | |
| * | |
| * \param mask | |
| * Specifies the status conditions to enable as interrupt source | |
| * contributors. \e mask is a mask of logically OR'ed \ref | |
| * ALT_NAND_INT_STATUS_t values that designate the status conditions | |
| * to enable. | |
| * | |
| * \retval ALT_E_SUCCESS Indicates successful completion. | |
| * \retval ALT_E_ERROR Indicates an error occurred. | |
| */ | |
| ALT_STATUS_CODE alt_nand_int_enable(const uint32_t mask); | |
| /*! | |
| * 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. | |
| * | |
| * \returns The number of planes contained in the device. | |
| * | |
| * \internal | |
| * nandregs.config.number_of_planes | |
| * \endinternal | |
| */ | |
| uint32_t alt_nand_num_planes_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. | |
| * | |
| * \returns The number of blocks contained in the device. | |
| * | |
| * \internal | |
| * ??? | |
| * \endinternal | |
| */ | |
| uint32_t alt_nand_num_blocks_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. | |
| * | |
| * \returns The number of pages per device block. | |
| * | |
| * \internal | |
| * nandregs.config.pages_per_block | |
| * \endinternal | |
| */ | |
| uint32_t alt_nand_num_pages_per_block_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. | |
| * | |
| * \returns Returns the size of a page sector in bytes. | |
| * | |
| * \internal | |
| * nandregs.config.device_main_area_size | |
| * \endinternal | |
| */ | |
| uint32_t alt_nand_sector_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. | |
| * | |
| * \returns Returns the size of a page spare area in bytes. | |
| * | |
| * \internal | |
| * nandregs.config.device_spare_area_size | |
| * \endinternal | |
| */ | |
| uint32_t alt_nand_spare_size_get(void); | |
| /*! | |
| * Returns \b true if the specified device block is bad otherwise returns \b | |
| * false. | |
| * | |
| * Returns \b 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 \b true is returned. | |
| * | |
| * \param block_addr | |
| * The block address to check. | |
| * | |
| * \returns \b true if the specified device block is bad otherwise returns | |
| * \b false. | |
| * | |
| * \internal | |
| * Uses the bad block table constructed by alt_nand_flash_init(). | |
| * \endinternal | |
| */ | |
| bool alt_nand_block_is_bad(const uint32_t block_addr); | |
| /*! | |
| * 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. | |
| */ | |
| #define ALT_NAND_BAD_BLOCK_MARKER 0 | |
| /*! | |
| * 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 <em>ceil( alt_nand_num_blocks_get() / 32 )</em> | |
| * 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: | |
| * | |
| * \code | |
| * #define ALT_NAND_GOOD_BLOCK_FLAG 0 | |
| * #define ALT_NAND_BAD_BLOCK_FLAG 1 | |
| * | |
| * block_is_bad = false; | |
| * block_table_index = block_number / 32; | |
| * block_bit_position = block_number % 32; | |
| * if ((( bad_block_table[block_table_index] >> block_bit_position) & 0x1) == ALT_NAND_BAD_BLOCK_FLAG) | |
| * block_is_bad = true; | |
| * \endcode | |
| */ | |
| typedef uint32_t * alt_nand_bad_block_table_t; | |
| /*! | |
| * 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 \ref | |
| * alt_nand_bad_block_table_t. | |
| * | |
| * \param 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. | |
| * | |
| * \param bad_block_table_len | |
| * The length of the \e bad_block_table parameter in number of | |
| * elements. | |
| * | |
| * \retval ALT_E_SUCCESS Indicates successful completion. | |
| * \retval ALT_E_ERROR Indicates an error occurred. | |
| * \retval ALT_E_BAD_ARG The \e 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. | |
| * | |
| */ | |
| 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); | |
| /*! @} */ | |
| #ifdef __cplusplus | |
| } | |
| #endif /* __cplusplus */ | |
| #endif /* __ALT_NAND_FLASH_H__ */ |