Chapter 4 - Azure RTOS LevelX NAND APIs

lx_nand_flash_close

Close NAND flash instance

Prototype

UINT lx_nand_flash_close(LX_NAND_FLASH *nand_flash);

Description

This service closes the previously opened NAND flash instance.

Input Parameters

  • nand_flash: NAND flash instance pointer.

Return Values

  • LX_SUCCESS: (0x00) Successful request.
  • LX_ERROR: (0x01) Error closing flash instance.

Allowed From

Threads

Example

/* Close NAND flash instance "my_nand_flash". */
status = lx_nand_flash_close(&my_nand_flash);  
  
/* If status is LX_SUCCESS the request was successful. */

See Also

  • lx_nand_flash_defragment
  • lx_nand_flash_extended_cache_enable
  • lx_nand_flash_initialize
  • lx_nand_flash_open
  • lx_nand_flash_page_ecc_check
  • lx_nand_flash_page_ecc_compute
  • lx_nand_flash_partial_defragment
  • lx_nand_flash_sector_read
  • lx_nand_flash_sector_release
  • lx_nand_flash_sector_write

lx_nand_flash_defragment

Defragment NAND flash instance

Prototype

UINT lx_nand_flash_defragment(LX_NAND_FLASH *nand_flash);

Description

This service defragments the previously opened NAND flash instance. The defragment process maximizes the number of free pages and blocks.

Input Parameters

  • nand_flash: NAND flash instance pointer.

Return Values

  • LX_SUCCESS: (0x00) Successful request.
  • LX_ERROR: (0x01) Error defragmenting flash instance.

Allowed From

Threads

Example

/* Defragment NAND flash instance "my_nand_flash". */  
status = lx_nand_flash_defragment(&my_nand_flash);  
  
/* If status is LX_SUCCESS the request was successful. */

See Also

  • lx_nand_flash_close
  • lx_nand_flash_extended_cache_enable
  • lx_nand_flash_initialize
  • lx_nand_flash_open
  • lx_nand_flash_page_ecc_check
  • lx_nand_flash_page_ecc_compute
  • lx_nand_flash_partial_defragment
  • lx_nand_flash_sector_read
  • lx_nand_flash_sector_release
  • lx_nand_flash_sector_write

lx_nand_flash_extended_cache_enable

Enable/disable extended NAND cache

Prototype

UINT lx_nand_flash_extended_cache_enable(
    LX_NAND_FLASH
    *nand_flash,  
    VOID *memory, 
    ULONG size);

Description

This service implements a cache layer in RAM using the memory supplied by the application. The total amount of memory required for full cache operation can be calculated as follows:

size (in_bytes) = number_of_blocks (rounded up to be divisible by 4) +  
    ((number_of_blocks * pages_per_block) * 4)  +  
    ((number_of_blocks * (pages_per_block + 1)) * 4)

If the supplied memory is not large enough to accommodate the full NAND cache, this routine will enable as much of the NAND flash cache as possible based on the memory supplied.

The NAND cache is disabled if the memory address specified is NULL. Hence, the NAND cache maybe be used in a temporary fashion.

Input Parameters

  • nand_flash: NAND flash instance pointer.
  • memory: Starting address for cache memory aligned for ULONG access. A value of LX_NULL disables the cache.
  • size: The size in bytes of the memory supplied.

Return Values

  • LX_SUCCESS: (0x00) Successful request.
  • LX_ERROR: (0x01) Not enough memory for one element of the NAND cache.

Allowed From

Threads

Example

/* Enable the NAND flash cache for the instance "my_nand_flash". */
status = lx_nand_flash_extended_cache_enable(&my_nand_flash,  
    &my_memory, sizeof(my_memory));  
  
/* If status is LX_SUCCESS the request was successful. */

See Also

  • lx_nand_flash_close
  • lx_nand_flash_defragment
  • lx_nand_flash_initialize
  • lx_nand_flash_open
  • lx_nand_flash_page_ecc_check
  • lx_nand_flash_page_ecc_compute
  • lx_nand_flash_partial_defragment
  • lx_nand_flash_sector_read
  • lx_nand_flash_sector_release
  • lx_nand_flash_sector_write

lx_nand_flash_initialize

Initialize NAND flash support

Prototype

UINT lx_nand_flash_initialize(void);

Description

This service initializes LevelX NAND flash support. It must be called before any other LevelX NAND APIs.

Input Parameters

  • None

Return Values

  • LX_SUCCESS: (0x00) Successful request.
  • LX_ERROR: (0x01) Error initializing NAND flash support.

Allowed From

Initialization, Threads

Example

/* Initialize NAND flash support. */
status = lx_nand_flash_initialize();  
  
/* If status is LX_SUCCESS the request was successful. */

See Also

  • lx_nand_flash_close
  • lx_nand_flash_defragment
  • lx_nand_flash_extended_cache_enable
  • lx_nand_flash_open
  • lx_nand_flash_page_ecc_check
  • lx_nand_flash_page_ecc_compute
  • lx_nand_flash_partial_defragment
  • lx_nand_flash_sector_read
  • lx_nand_flash_sector_release
  • lx_nand_flash_sector_write

lx_nand_flash_open

Open NAND flash instance

Prototype

UINT lx_nand_flash_open(
    LX_NAND_FLASH *nand_flash, 
    CHAR *name,  
    UINT (*nand_driver_initialize) (LX_NAND_FLASH *));

Description

This service opens a NAND flash instance with the specified NAND flash control block and driver initialization function. Note that the driver initialization function is responsible for installing various function pointers for reading, writing, and erasing blocks/pages of the NAND hardware associated with this NAND flash instance.

Input Parameters

  • nand_flash: NAND flash instance pointer.
  • name: Name of NAND flash instance.
  • nand_driver_initialize: Function pointer to NAND flash driver initialization function. Please refer to Chapter 3 of this guide for more details on NAND flash driver responsibilities.

Return Values

  • LX_SUCCESS: (0x00) Successful request.
  • LX_ERROR: (0x01) Error opening NAND flash instance.
  • LX_NO_MEMORY: (0x08) Driver did not provide buffer for reading one page into RAM.

Allowed From

Threads

Example

/* Open NAND flash instance "my_nand_flash" with the driver "my_nand_driver_initialize". */ 
status = lx_nand_flash_open(&my_nand_flash,"my nand flash",  
    my_nand_driver_initialize);  
  
/* If status is LX_SUCCESS the request was successful. */

See Also

  • lx_nand_flash_close
  • lx_nand_flash_defragment
  • lx_nand_flash_extended_cache_enable
  • lx_nand_flash_initialize
  • lx_nand_flash_page_ecc_check
  • lx_nand_flash_page_ecc_compute
  • lx_nand_flash_partial_defragment
  • lx_nand_flash_sector_read
  • lx_nand_flash_sector_release
  • lx_nand_flash_sector_write

lx_nand_flash_page_ecc_check

Check page for ECC errors with correction

Prototype

UINT lx_nand_flash_page_ecc_check(
    LX_NAND_FLASH *nand_flash,  
    UCHAR *page_buffer, 
    UCHAR *ecc_buffer);

Description

This service verifies the integrity of the supplied NAND page buffer with the supplied ECC. Page size (defined in the NAND flash instance pointer) is assumed to be a multiple of 256-bytes and the ECC code supplied is capable of correcting a 1 bit error in each 256-byte portion of the page.

Input Parameters

  • nand_flash: NAND flash instance pointer.
  • page_buffer: Pointer to NAND flash page buffer.
  • ecc_buffer: Pointer to ECC for NAND flash page. Note that there are 3 ECC bytes per 256-byte portion of the page.

Return Values

  • LX_SUCCESS: (0x00) NAND page has no errors.
  • LX_NAND_ERROR_CORRECTED: (0x06) One or more 1-bit errors were corrected in the NAND page—correction(s) are in the page buffer.
  • LX_NAND_ERROR_NOT_CORRECTED: (0x07) Too many errors to correct on the NAND page.

Allowed From

LevelX Driver

Example

/* Check the NAND page pointed to by "page_pointer" of the NAND flash instance "my_nand_flash" . */
status = lx_nand_flash_page_ecc_check(&my_nand_flash, page_pointer, ecc_pointer);  
  
/* If status is LX_SUCCESS the page is valid. */

See Also

  • lx_nand_flash_close
  • lx_nand_flash_defragment
  • lx_nand_flash_extended_cache_enable
  • lx_nand_flash_initialize
  • lx_nand_flash_open
  • lx_nand_flash_page_ecc_compute
  • lx_nand_flash_partial_defragment
  • lx_nand_flash_sector_read
  • lx_nand_flash_sector_release
  • lx_nand_flash_sector_write

lx_nand_flash_page_ecc_compute

Compute ECC for page

Prototype

UINT lx_nand_flash_page_ecc_compute(
    LX_NAND_FLASH *nand_flash,  
    UCHAR *page_buffer, 
    UCHAR *ecc_buffer);

Description

This service computes the ECC of the supplied NAND page buffer and returns the ECC in the supplied ECC buffer. Page size is assume to be a multiple of 256-bytes (defined in the NAND flash instance pointer). The ECC code is used to verify the integrity of the page when it is read at a later time.

Input Parameters

  • nand_flash: NAND flash instance pointer.
  • page_buffer: Pointer to NAND flash page buffer.
  • ecc_buffer: Pointer to destination for ECC of the NAND flash page. Note that must be 3 bytes of ECC storage per 256-byte portion of the page. For example, a 2048 byte page would require 24 bytes for the ECC.

Return Values

  • LX_SUCCESS: (0x00) ECC successfully calculated.
  • LX_ERROR: (0x01) Error calculating ECC.

Allowed From

LevelX Driver

Example

/* Compute ECC for the NAND page pointed to by "page_pointer" of the NAND flash instance "my_nand_flash". */  
status = lx_nand_flash_page_ecc_compute(&my_nand_flash, page_pointer, ecc_pointer);  
  
/* If status is LX_SUCCESS the ECC was calculated and Can be found in the memory pointed to by "ecc_pointer." */

See Also

  • lx_nand_flash_close
  • lx_nand_flash_defragment
  • lx_nand_flash_extended_cache_enable
  • lx_nand_flash_initialize
  • lx_nand_flash_open
  • lx_nand_flash_page_ecc_check
  • lx_nand_flash_partial_defragment
  • lx_nand_flash_sector_read
  • lx_nand_flash_sector_release
  • lx_nand_flash_sector_write

lx_nand_flash_partial_defragment

Partial defragment of NAND flash instance

Prototype

UINT lx_nand_flash_partial_defragment(
    LX_NAND_FLASH *nand_flash,  
    UINT max_blocks);

Description

This service defragments the previously opened NAND flash instance up to the maximum number of blocks specified. The defragment process maximizes the number of free pages and blocks.

Input Parameters

  • nand_flash: NAND flash instance pointer.
  • max_blocks: Maximum number of blocks.

Return Values

  • LX_SUCCESS: (0x00) Successful request.
  • LX_ERROR: (0x01) Error defragmenting flash instance.

Allowed From

Threads

Example

/* Defragment 1 block of NAND flash instance "my_nand_flash". */  
status = lx_nand_flash_partial_defragment(&my_nand_flash, 1);  
  
/* If status is LX_SUCCESS the request was successful. */

See Also

  • lx_nand_flash_close
  • lx_nand_flash_defragment
  • lx_nand_flash_extended_cache_enable
  • lx_nand_flash_initialize
  • lx_nand_flash_open
  • lx_nand_flash_page_ecc_check
  • lx_nand_flash_page_ecc_compute
  • lx_nand_flash_sector_read
  • lx_nand_flash_sector_release
  • lx_nand_flash_sector_write

lx_nand_flash_sector_read

Read NAND flash sector

Prototype

UINT lx_nand_flash_sector_read(
    LX_NAND_FLASH *nand_flash,  
    ULONG logical_sector, 
    VOID *buffer);

Description

This service reads the logical sector from the NAND flash instance and if successful returns the contents in the supplied buffer. Note that NAND sector size is always the page size of the underlying NAND hardware.

Input Parameters

  • nand_flash: NAND flash instance pointer.
  • logical_sector: Logical sector to read.
  • buffer: Pointer to destination for contents of the logical sector. Note that the buffer is assumed to be the size of the NAND flash page size and aligned for ULONG access.

Return Values

  • LX_SUCCESS: (0x00) Successful request.
  • LX_ERROR: (0x01) Error reading NAND flash sector.

Allowed From

Threads

Example

/* Read logical sector 20 of the NAND flash instance "my_nand_flash" and place contents in "buffer". */
status = lx_nand_flash_sector_read(&my_nand_flash, 20, buffer);  
  
/* If status is LX_SUCCESS, "buffer" contains the contentsnof logical sector 20. */

See Also

  • lx_nand_flash_close
  • lx_nand_flash_defragment
  • lx_nand_flash_extended_cache_enable
  • lx_nand_flash_initialize
  • lx_nand_flash_open
  • lx_nand_flash_page_ecc_check
  • lx_nand_flash_page_ecc_compute
  • lx_nand_flash_partial_defragment
  • lx_nand_flash_sector_release
  • lx_nand_flash_sector_write

lx_nand_flash_sector_release

Release NAND flash sector

Prototype

UINT lx_nand_flash_sector_release(
    LX_NAND_FLASH *nand_flash,
    ULONG logical_sector);

Description

This service releases the logical sector mapping in the NAND flash instance. Releasing a logical sector when not used makes the LevelX wear leveling more efficient.

Input Parameters

  • nand_flash: NAND flash instance pointer.
  • logical_sector: Logical sector to release.

Return Values

  • LX_SUCCESS: (0x00) Successful request.
  • LX_ERROR: (0x01) Error NAND flash sector write.

Allowed From

Threads

Example

/* Release logical sector 20 of the NAND flash instance "my_nand_flash". */  
status = lx_nand_flash_sector_release(&my_nand_flash, 20);  
  
/* If status is LX_SUCCESS, logical sector 20 has been released. */

See Also

  • lx_nand_flash_close
  • lx_nand_flash_defragment
  • lx_nand_flash_extended_cache_enable
  • lx_nand_flash_initialize
  • lx_nand_flash_open
  • lx_nand_flash_page_ecc_check
  • lx_nand_flash_page_ecc_compute
  • lx_nand_flash_partial_defragment
  • lx_nand_flash_sector_read
  • lx_nand_flash_sector_write

lx_nand_flash_sector_write

Write NAND flash sector

Prototype

UINT lx_nand_flash_sector_write(
    LX_NAND_FLASH *nand_flash,
    ULONG logical_sector, 
    VOID *buffer);

Description

This service writes the specified logical sector in the NAND flash instance.

Input Parameters

  • nand_flash: NAND flash instance pointer.
  • logical_sector: Logical sector to write.
  • buffer: Pointer to the contents of the logical sector. Note that the buffer is assumed to be the size of the NAND flash page size and aligned for ULONG access.

Return Values

  • LX_SUCCESS: (0x00) Successful request.
  • LX_NO_SECTORS: (0x02) No more free sectors are available to perform the write.
  • LX_ERROR: (0x01) Error releasing NAND flash sector.

Allowed From

Threads

Example

/* Write logical sector 20 of the NAND flash instance "my_nand_flash" with the contents pointed to by "buffer". */  
status = lx_nand_flash_sector_write(&my_nand_flash, 20, buffer);  
  
/* If status is LX_SUCCESS, logical sector 20 has been written with the contents of "buffer". */

See Also

  • lx_nand_flash_close
  • lx_nand_flash_defragment
  • lx_nand_flash_extended_cache_enable
  • lx_nand_flash_initialize
  • lx_nand_flash_open
  • lx_nand_flash_page_ecc_check
  • lx_nand_flash_page_ecc_compute
  • lx_nand_flash_partial_defragment
  • lx_nand_flash_sector_read
  • lx_nand_flash_sector_release