Data Structures | Macros | Variables
NVSSPI25X.h File Reference

Detailed Description

Non-Volatile Storage driver implementation for SPI flash peripherals.


The NVSSPI25X module allows you to manage SPI flash memory. This driver works with most 256 byte/page SPI flash memory devices such as:

Winbond     W25xx   family
Macronics   MX25Rxx family
Micron      N25Qxx  family

The SPI flash commands used by this driver are as follows:

#define SPIFLASH_PAGE_WRITE 0x02 // Page Program (up to 256 bytes)
#define SPIFLASH_READ 0x03 // Read Data
#define SPIFLASH_READ_STATUS 0x05 // Read Status Register
#define SPIFLASH_WRITE_ENABLE 0x06 // Write Enable
#define SPIFLASH_SUBSECTOR_ERASE 0x20 // SubSector (4K bytes) Erase
#define SPIFLASH_SECTOR_ERASE 0xD8 // Sector (usually 64K bytes) Erase
#define SPIFLASH_RDP 0xAB // Release from Deep Power Down
#define SPIFLASH_DP 0xB9 // Deep Power Down
#define SPIFLASH_MASS_ERASE 0xC7 // Erase entire flash.

It is assumed that the SPI flash device used by this driver supports the byte programmability of the SPIFLASH_PAGE_WRITE command and that write page size is 256 bytes. The erase sector and subsector sizes are assumed to be 64K and 4K respectively.

The NVS_erase() command will issue a sector or subsector erase command based on the input size and offset.

The driver must query the SPI flash to ensure that the part is ready before commands are issued. If the part responds as busy, the poll function sleeps for a number of microseconds determined by the NVSSPI25X_HWAttrs.statusPollDelayUs field. A value of 0 means that the driver will continuously poll the external flash until it is ready, which may affect other threads ability to execute.

SPI Interface Management

For each managed flash region, a corresponding SPI instance must be provided to the NVSSPI25X driver.

The SPI instance can be opened and closed internally by the NVSSPI25X driver, or alternatively, a SPI handle can be provided to the NVSSPI25X driver, indicating that the SPI instance is being opened and closed elsewhere within the application. This mode is useful when the SPI bus is share by more than just the SPI flash device.

If the SPI instance is to be managed internally by the NVSSPI25X driver, a SPI instance index and bit rate must be configured in the region's HWAttrs. If the same SPI instance is referenced by multiple flash regions the driver will ensure that SPI_open() is invoked only once, and that SPI_close() will only be invoked when all flash regions using the SPI instance have been closed.

If the SPI bus that the SPI flash device is on is shared with other devices accessed by an application, then the SPI handle used to manage a SPI flash region can be provided in the region's HWAttrs "spiHandle" field. Keep in mind that the "spiHandle" field is a POINTER to a SPI Handle, NOT a SPI Handle. This allows the user to simply initialize this field with the name of the global variable used for the SPI handle. In this mode, the user MUST open the SPI instance prior to opening the NVS region instance so that the referenced spiHandle is valid.

By default, the "spiHandle" field is set to NULL, indicating that the user expects the NVS driver to open and close the SPI instance internally using the 'spiIndex' and 'spiBitRate' provided in the HWAttrs.

SPI Flash Chip Select Management

Option 1: NVSSPI25X Driver Manages Chip Select

By default, the NVSSPI25X driver will assert and de-assert a GPIO driver managed pin to select the SPI flash device before and after each SPI transfer to and from the device.

To enable this behavior, a valid GPIO driver instance index must be provided in the NVS region's spiCsnGpioIndex field of the NVSSPI25X_HWAttrs structure. The corresponding GPIO pin will be configured at runtime by the NVSSPI25X driver as "GPIO_CFG_OUT_STD" and assertion of this pin is assumed to be active LOW.

Option 2: SPI Driver Manages Chip Select

Some SPI peripherals can be configured to manage their own chip select. Setting the spiCsnGpioIndex field of the NVSSPI25X_HWAttrs structure to NVSSPI25X_SPI_MANAGES_CS informs the NVSSPI25X driver that the SPI peripheral used by the NVS driver has been configured that way.

Option 3: User Manages Chip Select

Alternatively, the user can manage the assertion and de-assertion of the SPI flash chip select entirely themselves by providing implementations of the following 4 APIs in their application code:

void NVSSPI25X_initSpiCs(NVS_Handle nvsHandle, uint16_t csId);
void NVSSPI25X_deinitSpiCs(NVS_Handle nvsHandle, uint16_t csId);
void NVSSPI25X_assertSpiCs(NVS_Handle nvsHandle, uint16_t csId);
void NVSSPI25X_deassertSpiCs(NVS_Handle nvsHandle, uint16_t csId);
All 4 of the above APIs must be provided by the user if this option is used, otherwise default internal implementations of the APIs will be called that will likely lead to application failure.
#include <stdint.h>
#include <stdbool.h>
#include <ti/drivers/SPI.h>
Include dependency graph for NVSSPI25X.h:

Go to the source code of this file.

Data Structures

struct  NVSSPI25X_HWAttrs
 NVSSPI25X attributes. More...
struct  NVSSPI25X_Object


 Command to perform mass erase of entire flash. More...
#define NVSSPI25X_SPI_MANAGES_CS   ((uint16_t)(~0))
 Disable internal management of SPI chip select. More...


const NVS_FxnTable NVSSPI25X_fxnTable

Macro Definition Documentation



Command to perform mass erase of entire flash.

As this command can erase flash memory outside the region associated with the NVS_Handle passed to the control command, the user must carefully orchestrate the use of the command.

Mass Erase is the only control command supported.


#define NVSSPI25X_SPI_MANAGES_CS   ((uint16_t)(~0))

Disable internal management of SPI chip select.

Some SPI peripherals can be configured to manage their own chip select. Setting the spiCsnGpioIndex field of the NVSSPI25X_HWAttrs structure to NVSSPI25X_SPI_MANAGES_CS informs the NVSSPI25X driver that the SPI peripheral used by the NVS driver is configured to manage its own chip select signal.

Variable Documentation

§ NVSSPI25X_fxnTable

const NVS_FxnTable NVSSPI25X_fxnTable
© Copyright 1995-2019, Texas Instruments Incorporated. All rights reserved.
Trademarks | Privacy policy | Terms of use | Terms of sale