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:
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 NVS_erase() command assumes that regions with sectorSize = 4096 bytes are erased using the SPIFLASH_SUBSECTOR_ERASE command (0x20). Otherwise the SPIFLASH_SECTOR_ERASE command (0xD8) is used to erase the flash sector. It is up to the user to ensure that each region's sectorSize matches these sector erase rules.
For each managed flash region, a corresponding SPI instance must be provided to the NVSSPI25X driver. As well, a GPIO instance index must be provided to the driver so that the SPI flash device's chip select can be asserted during SPI transfers.
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.
Regardless of whether a region's SPI instance is opened by the driver or elsewhere within the application, the GPIO instance used to select the SPI flash device during SPI operations MUST be provided. The GPIO pin will be configured as "GPIO_CFG_OUT_STD" and assertion of this pin is assumed to be active LOW.
Go to the source code of this file.
Data Structures | |
struct | NVSSPI25X_HWAttrs |
NVSSPI25X attributes. More... | |
struct | NVSSPI25X_Object |
Macros | |
#define | NVSSPI25X_CMD_MASS_ERASE (NVS_CMD_RESERVED + 0) |
Command to perform mass erase of entire flash. More... | |
Typedefs | |
typedef struct NVSSPI25X_HWAttrs | NVSSPI25X_HWAttrs |
NVSSPI25X attributes. More... | |
typedef struct NVSSPI25X_Object | NVSSPI25X_Object |
Functions | |
void | NVSSPI25X_close (NVS_Handle handle) |
int_fast16_t | NVSSPI25X_control (NVS_Handle handle, uint_fast16_t cmd, uintptr_t arg) |
int_fast16_t | NVSSPI25X_erase (NVS_Handle handle, size_t offset, size_t size) |
void | NVSSPI25X_getAttrs (NVS_Handle handle, NVS_Attrs *attrs) |
void | NVSSPI25X_init () |
int_fast16_t | NVSSPI25X_lock (NVS_Handle handle, uint32_t timeout) |
NVS_Handle | NVSSPI25X_open (uint_least8_t index, NVS_Params *params) |
int_fast16_t | NVSSPI25X_read (NVS_Handle handle, size_t offset, void *buffer, size_t bufferSize) |
void | NVSSPI25X_unlock (NVS_Handle handle) |
int_fast16_t | NVSSPI25X_write (NVS_Handle handle, size_t offset, void *buffer, size_t bufferSize, uint_fast16_t flags) |
Variables | |
const NVS_FxnTable | NVSSPI25X_fxnTable |
NVS function pointer table. More... | |
#define NVSSPI25X_CMD_MASS_ERASE (NVS_CMD_RESERVED + 0) |
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.
typedef struct NVSSPI25X_HWAttrs NVSSPI25X_HWAttrs |
NVSSPI25X attributes.
The 'regionBaseOffset' is the offset, in bytes, from the base of the SPI flash, of the flash region to be managed.
The 'regionSize' must be an integer multiple of the flash sector size.
The 'sectorSize' is SPI flash device specific. This parameter should correspond to the number of bytes erased when the 'SPIFLASH_SUBSECTOR_ERASE' (0x20) command is issued to the device.
The 'verifyBuf' and 'verifyBufSize' parameters are used by the NVS_write() command when either 'NVS_WRITE_PRE_VERIFY' or 'NVS_WRITE_POST_VERIFY' functions are requested in the 'flags' argument. The 'verifyBuf' is used to successively read back portions of the flash to compare with the data being written to it.
typedef struct NVSSPI25X_Object NVSSPI25X_Object |
void NVSSPI25X_close | ( | NVS_Handle | handle | ) |
int_fast16_t NVSSPI25X_control | ( | NVS_Handle | handle, |
uint_fast16_t | cmd, | ||
uintptr_t | arg | ||
) |
int_fast16_t NVSSPI25X_erase | ( | NVS_Handle | handle, |
size_t | offset, | ||
size_t | size | ||
) |
void NVSSPI25X_getAttrs | ( | NVS_Handle | handle, |
NVS_Attrs * | attrs | ||
) |
void NVSSPI25X_init | ( | ) |
int_fast16_t NVSSPI25X_lock | ( | NVS_Handle | handle, |
uint32_t | timeout | ||
) |
NVS_Handle NVSSPI25X_open | ( | uint_least8_t | index, |
NVS_Params * | params | ||
) |
int_fast16_t NVSSPI25X_read | ( | NVS_Handle | handle, |
size_t | offset, | ||
void * | buffer, | ||
size_t | bufferSize | ||
) |
void NVSSPI25X_unlock | ( | NVS_Handle | handle | ) |
int_fast16_t NVSSPI25X_write | ( | NVS_Handle | handle, |
size_t | offset, | ||
void * | buffer, | ||
size_t | bufferSize, | ||
uint_fast16_t | flags | ||
) |
const NVS_FxnTable NVSSPI25X_fxnTable |
NVS function pointer table.
'NVSSPI25X_fxnTable' is a fully populated function pointer table that can be referenced in the NVS_config[] array entries.
Users can minimize their application code size by providing their own custom NVS function pointer table that contains only those APIs used by the application.