libquadflash API#
The libquadflash library provides functions for reading and writing data to Quad-SPI flash devices that use the xCORE format shown in the diagram below.
![../../../../_images/flash-format3.png](../../../../_images/flash-format3.png)
Fig. 10 Flash format diagram#
All functions are prototyped in the header file
<quadflash.h>
. Except where otherwise stated, functions
return 0 on success and non-zero on failure.
General operations#
The program must explicitly open a connection to the Quad-SPI device before attempting to use it, and must disconnect once finished accessing the device.
The functions fl_connect
and fl_connectToDevice
require an
argument of type fl_QSPIPorts
, which defines the four ports and
clock block used to connect to the device.
typedef struct {
out port qspiCS;
out port qspiSCLK;
out buffered port:32 qspiSIO;
clock qspiClkblk;
} fl_QSPIPorts;
-
int fl_connect(fl_QSPIPorts *SPI)#
fl_connect
opens a connection to a Quad-SPI device.This API requires a flash device that supports SFDP.
-
int fl_connectToDevice(fl_QSPIPorts *SPI, fl_QuadDeviceSpec spec[], unsigned n)#
fl_connectToDevice
opens a connection to a Quad-SPI device. It iterates through an array of n Quad-SPI device specifications, attempting to connect using each specification until one succeeds.This API makes use of SFDP if available on the target flash device.
-
int fl_connectToDeviceLight(fl_QSPIPorts *SPI, fl_QuadDeviceSpec spec[], unsigned n)#
fl_connectToDeviceLight
opens a connection to a Quad-SPI device. It iterates through an array of n Quad-SPI device specifications, attempting to connect using each specification until one succeeds.This API does not use SFDP and expects a complete device specification to be provided. It is provided for a reduced memory footprint.
-
unsigned fl_getJedecId(void)#
fl_getJedecId
returns the response to the ‘Read Identification’ command used during connection, typically the JEDEC ID. This uses the command and size defined by the SPI specification in use.For the majority of flash devices, this will be the response to command
0x9f
.
-
unsigned fl_getFlashSize(void)#
fl_getFlashSize
returns the capacity of the Quad-SPI device in bytes.
-
void fl_copySpec(fl_QuadDeviceSpec *dest)#
fl_copySpec
exports the completed SPI specification in use for the current connection. Where applicable, this may have been amended at runtime using the SFDP response.
-
unsigned fl_getLibraryStatus(void)#
fl_getLibraryStatus
returns a bitmask of errors and warnings from connection. The bits are defined as follows:typedef enum { LIBRARY_ERROR_PAGESIZE_MISSING = 1 << 8, LIBRARY_ERROR_NUMPAGES_MISSING = 1 << 9, LIBRARY_ERROR_SECTORSIZE_MISSING = 1 << 10, LIBRARY_WARNING_PAGESIZE_MISMATCH = 1 << 16, LIBRARY_WARNING_NUMPAGES_MISMATCH = 1 << 17, LIBRARY_WARNING_QUADENABLE_MISMATCH = 1 << 18, } fl_LibraryStatus;
These generally indicate the reason for connection failure, typically due to incomplete or incorrect SPI specification. Mismatch warnings indicate that a configuration parameter has been overridden in the device specification but does not match the SFDP response.
-
int fl_command(unsigned int cmd, unsigned char input[], unsigned int num_in, unsigned char output[], unsigned int num_out)#
fl_command
issues a command to the SPI device at the lowest level. Thecmd
is sent first, followed bynum_in
bytes frominput
.num_out
bytes are then read tooutput
.Bits 12..15 of
cmd
set the number of data lines used forinput
. Bits 8..11 ofcmd
set the number of data lines used foroutput
.The supported values for the above fields are
1
and4
. If unspecified, they default to1
.
-
int fl_disconnect(void)#
fl_disconnect
closes the connection to the Quad-SPI device.
Boot partition functions#
By default, the size of the boot partition is set to the size of the flash device. Access to boot images is provided through an iterator interface.
-
int fl_getImageInfo(fl_BootImageInfo *bootImageInfo, const unsigned char page[])#
fl_getImageInfo
provides information about a boot image header stored in memory. A single page of the image data must be provided.
-
int fl_getFactoryImage(fl_BootImageInfo *bootImageInfo)#
fl_getFactoryImage
provides information about the factory boot image.
-
int fl_getNextBootImage(fl_BootImageInfo *bootImageInfo)#
fl_getNextBootImage
provides information about the next upgrade image. Once located, an image can be upgraded. Functions are also provided for reading the contents of an upgrade image.
-
unsigned fl_getImageTag(fl_BootImageInfo *bootImageInfo)#
fl_getImageTag
returns the magic number of the specified image.
-
unsigned fl_getImageVersion(fl_BootImageInfo *bootImageInfo)#
fl_getImageVersion
returns the version number of the specified image.
-
unsigned fl_getImageAddress(fl_BootImageInfo *bootImageInfo)#
fl_getImageAddress
returns the start address in flash of the specified image.
-
unsigned fl_getImageSize(fl_BootImageInfo *bootImageInfo)#
fl_getImageSize
returns the size of the specified image.
-
int fl_getToolsMajor(fl_BootImageInfo *bootImageInfo)#
fl_getToolsMajor
returns the tools major version used to build the specified image, or -1 on failure.
-
int fl_getToolsMinor(fl_BootImageInfo *bootImageInfo)#
fl_getToolsMinor
returns the tools minor version used to build the specified image, or -1 on failure.
-
int fl_getToolsPatch(fl_BootImageInfo *bootImageInfo)#
fl_getToolsPatch
returns the tools patch version used to build the specified image, or -1 on failure.
-
int fl_getImageFormat(fl_BootImageInfo *bootImageInfo)#
fl_getImageFormat
returns the compatibility version of the specified image, or -1 on failure.
-
int fl_startImageReplace(fl_BootImageInfo*, unsigned maxsize)#
fl_startImageReplace
prepares the Quad-SPI device for replacing an image. The old image can no longer be assumed to exist after this call.Attempting to write into the data partition or the space of another upgrade image is invalid. A non-zero return value signifies that the preparation is not yet complete and that the function should be called again. Repeated calling of this function is required to iterate over all the sectors needed by the image and erase them.
-
int fl_startImageAdd(fl_BootImageInfo*, unsigned maxsize, unsigned padding)#
fl_startImageAdd
prepares the Quad-SPI device for adding an image after the specified image. The start of the new image is at least padding bytes after the previous image.Attempting to write into the data partition or the space of another upgrade image is invalid. A non-zero return value signifies that the preparation is not yet complete and that the function must be called again. Repeated calling of this function is required to iterate over all the sectors needed by the image and erase them.
-
int fl_startImageAddAt(unsigned offset, unsigned maxsize)#
fl_startImageAddAt
prepares the Quad-SPI device for adding an image at the specified address offset from the base of the first sector after the factory image.Attempting to write into the data partition or the space of another upgrade image is invalid. A non-zero return value signifies that the preparation is not yet complete and that the function must be called again. Repeated calling of this function is required to iterate over all the sectors needed by the image and erase them.
-
int fl_writeImagePage(const unsigned char page[])#
fl_writeImagePage
waits until the Quad-SPI device is able to accept a request and then outputs the next page of data to the device. Attempting to write past the maximum size passed tofl_startImageReplace
,fl_startImageAdd
orfl_startImageAddAt
is invalid.
-
int fl_writeImageEnd(void)#
fl_writeImageEnd
waits until the Quad-SPI device has written the last page of data to its memory.
-
int fl_startImageRead(fl_BootImageInfo *b)#
fl_startImageRead
prepares the Quad-SPI device for reading the contents of the specified upgrade image.
-
int fl_readImagePage(unsigned char page[])#
fl_readImagePage
inputs the next page of data from the Quad-SPI device and writes it to the array page.
-
int fl_deleteImage(fl_BootImageInfo *b)#
fl_deleteImage
erases the upgrade image with the specified image.
Data partition functions#
All flash devices are assumed to have uniform page sizes but are not assumed to have uniform sector sizes. Read and write operations occur at the page level, and erase operations occur at the sector level. This means that to write part of a sector, a buffer size of at least one sector is required to preserve other data.
In the following functions, writes to the data partition and erasures from the data partition are not fail-safe. If the operation is interrupted, for example due to a power failure, the data in the page or sector is undefined.
-
unsigned fl_getDataPartitionSize(void)#
fl_getDataPartitionSize
returns the size of the data partition in bytes.
-
int fl_readData(unsigned offset, unsigned size, unsigned char dst[])#
fl_readData
reads a number of bytes from an offset into the data partition and writes them to the array dst.
-
unsigned fl_getWriteScratchSize(unsigned offset, unsigned size)#
fl_getWriteScratchSize
returns the buffer size needed byfl_writeData
for the given parameters.
-
int fl_writeData(unsigned offset, unsigned size, const unsigned char src[], unsigned char buffer[])#
fl_writeData
writes the arraysrc
to the specified offset in the data partition. It uses the arraybuffer
to preserve page data that must be re-written.
Page-level functions#
-
unsigned fl_getPageSize(void)#
fl_getPageSize
returns the page size in bytes.
-
unsigned fl_getNumDataPages(void)#
fl_getNumDataPages
returns the number of pages in the data partition.
-
unsigned fl_writeDataPage(unsigned n, const unsigned char data[])#
fl_writeDataPage
writes the array data to the n-th page in the data partition. The data array must be at least as big as the page size; if larger, the highest elements are ignored.
-
unsigned fl_readDataPage(unsigned n, unsigned char data[])#
fl_readDataPage
reads the n-th page in the data partition and writes it to the array data. The size of data must be at least as large as the page size.
Sector-level functions#
-
unsigned fl_getNumDataSectors(void)#
fl_getNumDataSectors
returns the number of sectors in the data partition.
-
unsigned fl_getDataSectorSize(unsigned n)#
fl_getDataSectorSize
returns the size of the n-th sector in the data partition in bytes.
-
unsigned fl_eraseDataSector(unsigned n)#
fl_eraseDataSector
erases the n-th sector in the data partition.
-
unsigned fl_eraseAllDataSectors(void)#
fl_eraseAllDataSectors
erases all sectors in the data partition.