#include <stdint.h>
#include <stdbool.h>

Include dependency graph for XMEMWFF3.h:

Data Structures
struct	FlashRegister
	Flash register structure for address-data pairs. More...

struct	FlashStigEraseCfg
	Flash STIG erase configuration structure. More...

struct	FlashStigWriteCfg
	Flash STIG write configuration structure. More...

struct	FlashStigReadCfg
	Flash STIG read configuration structure. More...

struct	FlashPollingCfg
	Flash polling configuration structure. More...

struct	FlashType
	Flash type configuration structure. More...

struct	XMEMWFF3_HWAttrs
	Hardware attributes structure for the XMEMWFF3 driver. More...

struct	XMEMWFF3_Object
	Runtime state object for the XMEMWFF3 driver instance. More...

struct	XMEM_Attrs
	XMEM attributes. More...

struct	XMEM_Config_
	XMEM Global configuration. More...

struct	XMEM_Params
	Parameters for opening an XMEM region. More...

Macros
#define	XMEM_FLASH 0
	Device enumeration. More...

#define	XMEM_PSRAM 1

#define	XMEM_WORD_SIZE 4
	size of one word which can be read by STIG command and used in: XMEMWFF3_read() More...

#define	CONFIG_XMEM_COUNT 1
	Number of max available XMEM Configuration. More...

#define	XMEM_NUM_HANDLER 16
	Number of max available XMEM handlers. More...

#define	XMEM_STATUS_SUCCESS (0)
	Successful status code returned by: XMEMWFF3_read(), XMEMWFF3_write(), XMEMWFF3_erase(), or XMEMWFF3_lock(). More...

#define	XMEM_STATUS_ERROR (-1)
	Generic error status code returned by: XMEMWFF3_erase(), or XMEMWFF3_write(),. More...

#define	XMEM_STATUS_TIMEOUT (-3)
	An error status code returned by XMEMWFF3_lock() More...

#define	XMEM_STATUS_INV_OFFSET (-4)
	An error status code returned by XMEMWFF3_read(), XMEMWFF3_write(), or XMEMWFF3_erase() More...

#define	XMEM_STATUS_INV_ALIGNMENT (-5)
	An error status code. More...

#define	XMEM_STATUS_INV_SIZE (-6)
	An error status code returned by XMEMWFF3_erase() and XMEMWFF3_write() More...

#define	XMEM_STATUS_INV_WRITE (-7)
	An error status code returned by XMEMWFF3_write() More...

#define	XMEM_STATUS_VERIFYBUFFER (-8)
	An error status code returned by XMEMWFF3_write() More...

#define	XMEM_STATUS_INVALID_PARAMS (-9)
	An error status code returned by various XMEM functions. More...

#define	XMEM_READ (0x0)
	read flag. More...

#define	XMEM_READ_STIG (0x1)
	read STIG flag. More...


#define	XMEM_WRITE (0x0)
	XMEM write flags. More...

#define	XMEM_WRITE_ERASE (0x1)
	Erase write flag. More...

#define	XMEM_WRITE_PRE_VERIFY (0x2)
	Validate write flag. More...

#define	XMEM_WRITE_POST_VERIFY (0x4)
	Validate write flag. More...

#define	XMEM_WRITE_STIG (0x8)
	Write STIG write flag. More...

Typedefs
typedef struct XMEM_Config_ *	XMEM_Handle
	A handle that is returned from the XMEMWFF3_open() call. More...

typedef struct XMEM_Config_	XMEM_Config
	XMEM Global configuration. More...

Enumerations
enum	XMEM_Flash_Idx { IS25WJ032F_IDX = 0, IS25WJ064F_IDX = 1, W25Q32JW_IDX = 2, W25Q64JW_IDX = 3, GD25LF32ETJGY_IDX = 4, GD25LF64ETJGY_IDX = 5, PY25Q32LB_IDX = 6, PY25Q64LB_IDX = 7, PY25Q128LA_IDX = 8, PY25Q256LC_IDX = 9, MX25U3235F_IDX = 10, MX25U6435F_IDX = 11, IS25WJ128F_IDX = 12, W25Q12PW_IDX = 13 }
	External flash device type identifiers. More...

Functions
int_fast16_t	XMEMWFF3_close (XMEM_Handle handle)
	Function to close an XMEM_Handle. More...

int_fast16_t	XMEMWFF3_erase (XMEM_Handle handle, size_t offset, size_t size)
	Erase `size` bytes of the region beginning at `offset` bytes from the base of the region referenced by the XMEM_Handle. More...

void	XMEMWFF3_getAttrs (XMEM_Handle handle, XMEM_Attrs *attrs)
	Function to get the XMEM attributes. More...

void	XMEMWFF3_getObject (XMEM_Handle handle, XMEMWFF3_Object *object)
	Function to get the XMEM object. More...

uint8_t	XMEMWFF3_getActiveHandlers (void)
	Function to get the number of active XMEM handlers. More...

void	XMEMWFF3_init (void)
	Function to initialize the XMEM module. More...

int_fast16_t	XMEMWFF3_lock (XMEM_Handle handle, uint32_t timeout)
	Function to lock the XMEM driver. More...

XMEM_Handle	XMEMWFF3_open (XMEM_Params *params)
	Open an XMEM region for reading and writing. More...

int_fast16_t	XMEMWFF3_read (XMEM_Handle handle, size_t offset, void *buffer, size_t bufferSize, uint_fast16_t flags)
	Read data from the XMEM region associated with the XMEM_Handle. More...

void	XMEMWFF3_unlock (XMEM_Handle handle)
	Function to unlock the XMEM driver. More...

int_fast16_t	XMEMWFF3_write (XMEM_Handle handle, size_t offset, void *buffer, size_t bufferSize, uint_fast16_t flags)
	Write data to the XMEM region associated with the XMEM_Handle. More...

Macro Definition Documentation

§ XMEM_FLASH

#define XMEM_FLASH 0

Device enumeration.

§ XMEM_PSRAM

#define XMEM_PSRAM 1

§ XMEM_WORD_SIZE

#define XMEM_WORD_SIZE 4

size of one word which can be read by STIG command and used in: XMEMWFF3_read()

§ CONFIG_XMEM_COUNT

#define CONFIG_XMEM_COUNT 1

Number of max available XMEM Configuration.

§ XMEM_NUM_HANDLER

#define XMEM_NUM_HANDLER 16

Number of max available XMEM handlers.

§ XMEM_STATUS_SUCCESS

#define XMEM_STATUS_SUCCESS (0)

Successful status code returned by: XMEMWFF3_read(), XMEMWFF3_write(), XMEMWFF3_erase(), or XMEMWFF3_lock().

APIs returns XMEM_STATUS_SUCCESS if the API was executed successfully.

§ XMEM_STATUS_ERROR

#define XMEM_STATUS_ERROR (-1)

Generic error status code returned by: XMEMWFF3_erase(), or XMEMWFF3_write(),.

APIs return XMEM_STATUS_ERROR if the API was not executed successfully.

§ XMEM_STATUS_TIMEOUT

#define XMEM_STATUS_TIMEOUT (-3)

An error status code returned by XMEMWFF3_lock()

XMEMWFF3_lock() will return this value if the timeout has expired

§ XMEM_STATUS_INV_OFFSET

#define XMEM_STATUS_INV_OFFSET (-4)

An error status code returned by XMEMWFF3_read(), XMEMWFF3_write(), or XMEMWFF3_erase()

Error status code returned if the offset argument is invalid (e.g., when offset + bufferSize exceeds the size of the region).

§ XMEM_STATUS_INV_ALIGNMENT

#define XMEM_STATUS_INV_ALIGNMENT (-5)

An error status code.

Error status code returned by XMEMWFF3_erase() if the offset argument is not aligned on a flash sector address.

§ XMEM_STATUS_INV_SIZE

#define XMEM_STATUS_INV_SIZE (-6)

An error status code returned by XMEMWFF3_erase() and XMEMWFF3_write()

Error status code returned by XMEMWFF3_erase() if the size argument is not a multiple of the flash sector size, or if offset + size extends past the end of the region.

§ XMEM_STATUS_INV_WRITE

#define XMEM_STATUS_INV_WRITE (-7)

An error status code returned by XMEMWFF3_write()

XMEMWFF3_write() will return this value if #XMEMWFF3_WRITE_PRE_VERIFY is requested and a flash location can not be changed to the value desired.

§ XMEM_STATUS_VERIFYBUFFER

#define XMEM_STATUS_VERIFYBUFFER (-8)

An error status code returned by XMEMWFF3_write()

XMEMWFF3_write() will return this value if XMEM_WRITE_PRE_VERIFY or XMEM_WRITE_POST_VERIFY is requested but the verification buffer has not been configured.

§ XMEM_STATUS_INVALID_PARAMS

#define XMEM_STATUS_INVALID_PARAMS (-9)

An error status code returned by various XMEM functions.

APIs return XMEM_STATUS_INVALID_PARAMS if one or more of the input parameters are invalid (e.g., invalid flag combinations, NULL pointers, or out-of-range values).

§ XMEM_READ

#define XMEM_READ (0x0)

read flag.

If XMEM_READ_STIG is set in the flags passed to XMEMWFF3_read(), the read operation is done using udma.

§ XMEM_READ_STIG

#define XMEM_READ_STIG (0x1)

read STIG flag.

If XMEM_READ_STIG is set in the flags passed to XMEMWFF3_read(), the read operation is done using STIG command.

§ XMEM_WRITE

#define XMEM_WRITE (0x0)

XMEM write flags.

The following flags can be or'd together and passed as a bit mask to XMEMWFF3_write().

write flag.

If XMEM_WRITE is used in XMEMWFF3_write(), the write operation will be performed directly without any validation or erasing of the destination sectors. Operation is done using udma.

§ XMEM_WRITE_ERASE

#define XMEM_WRITE_ERASE (0x1)

Erase write flag.

If XMEM_WRITE_ERASE is set in the flags passed to XMEMWFF3_write(), the affected destination flash sectors will be erased prior to the start of the write operation.

§ XMEM_WRITE_PRE_VERIFY

#define XMEM_WRITE_PRE_VERIFY (0x2)

Validate write flag.

If XMEM_WRITE_PRE_VERIFY is set in the flags passed to XMEMWFF3_write(), the destination address range will be pre-tested to guarantee that the source data can be successfully written. If XMEM_WRITE_ERASE is also requested in the write flags, then the XMEM_WRITE_PRE_VERIFY modifier is ignored.

§ XMEM_WRITE_POST_VERIFY

#define XMEM_WRITE_POST_VERIFY (0x4)

Validate write flag.

If XMEM_WRITE_POST_VERIFY is set in the flags passed to XMEMWFF3_write(), the destination address range will be tested after the write is finished to verify that the write operation was completed successfully.

§ XMEM_WRITE_STIG

#define XMEM_WRITE_STIG (0x8)

Write STIG write flag.

If XMEM_WRITE_STIG is set in the flags passed to XMEMWFF3_write(), the write operation is done using STIG command.

Typedef Documentation

§ XMEM_Handle

typedef struct XMEM_Config_* XMEM_Handle

A handle that is returned from the XMEMWFF3_open() call.

§ XMEM_Config

typedef struct XMEM_Config_ XMEM_Config

XMEM Global configuration.

The XMEM_Config structure contains a set of pointers used to characterize the XMEM driver implementation.

This structure needs to be defined before calling XMEMWFF3_init() and it must not be changed thereafter.

See also: XMEMWFF3_init()

Enumeration Type Documentation

§ XMEM_Flash_Idx

enum XMEM_Flash_Idx

External flash device type identifiers.

This enumeration defines identifiers for supported external flash memory devices. These values are used to select the appropriate flash device configuration and command sequences for memory operations.

Enumerator
IS25WJ032F_IDX
IS25WJ064F_IDX
W25Q32JW_IDX
W25Q64JW_IDX
GD25LF32ETJGY_IDX
GD25LF64ETJGY_IDX
PY25Q32LB_IDX
PY25Q64LB_IDX
PY25Q128LA_IDX
PY25Q256LC_IDX
MX25U3235F_IDX
MX25U6435F_IDX
IS25WJ128F_IDX
W25Q12PW_IDX

Function Documentation

§ XMEMWFF3_close()

int_fast16_t XMEMWFF3_close ( XMEM_Handle handle )

Function to close an XMEM_Handle.

Parameters

handle A handle returned from XMEMWFF3_open()

Return values

XMEM_STATUS_SUCCESS	Success.
XMEM_STATUS_INVALID_PARAMS	If handle is NULL.

See also: XMEMWFF3_open()

§ XMEMWFF3_erase()

int_fast16_t XMEMWFF3_erase	(	XMEM_Handle	handle,
		size_t	offset,
		size_t	size
	)

Erase size bytes of the region beginning at offset bytes from the base of the region referenced by the XMEM_Handle.

Warning: Erasing internal flash on most devices can introduce significant interrupt latencies while the erase operation is in in progress. The user may want to surround certain real-time critical code sections with XMEMWFF3_lock() and XMEMWFF3_unlock() calls in order to prevent uncoordinated flash erase operations from negatively impacting performance.

Parameters

handle	A handle returned from XMEMWFF3_open()
offset	The byte offset into the XMEM region to start erasing from (must be erase sector aligned)
size	The number of bytes to erase (must be integer multiple of sector size)

Return values

XMEM_STATUS_SUCCESS	Success.
XMEM_STATUS_INV_ALIGNMENT	If `offset` is not aligned on a sector boundary
XMEM_STATUS_INV_OFFSET	If `offset` exceeds region size
XMEM_STATUS_INV_SIZE	If `size` or `offset` + `size` exceeds region size, or if `size` is not an integer multiple of the flash sector size.
XMEM_STATUS_ERROR	If an internal error occurred erasing the flash.

§ XMEMWFF3_getAttrs()

void XMEMWFF3_getAttrs	(	XMEM_Handle	handle,
		XMEM_Attrs *	attrs
	)

Function to get the XMEM attributes.

This function will populate a XMEM_Attrs structure with attributes specific to the memory region associated with the XMEM_Handle.

Parameters

handle	A handle returned from XMEMWFF3_open()
attrs	Location to store attributes.

§ XMEMWFF3_getObject()

void XMEMWFF3_getObject	(	XMEM_Handle	handle,
		XMEMWFF3_Object *	object
	)

Function to get the XMEM object.

This function will populate an XMEMWFF3_Object structure with the object data specific to the memory region associated with the XMEM_Handle.

Parameters

handle	A handle returned from XMEMWFF3_open()
object	Location to store the XMEMWFF3 object.

§ XMEMWFF3_getActiveHandlers()

uint8_t XMEMWFF3_getActiveHandlers ( void )

Function to get the number of active XMEM handlers.

This function will return the count of active handlers that have been opened using the XMEMWFF3_open() function and not yet closed.

Returns: The number of currently active XMEM handlers.

§ XMEMWFF3_init()

void XMEMWFF3_init ( void )

Function to initialize the XMEM module.

Precondition: The XMEM_config structure must exist and be persistent before this function can be called. This function must also be called before any other XMEM APIs.

§ XMEMWFF3_lock()

int_fast16_t XMEMWFF3_lock	(	XMEM_Handle	handle,
		uint32_t	timeout
	)

Function to lock the XMEM driver.

This function is provided in the event that the user needs to perform some flash related operation not provided by the XMEM driver API set or if the user simply needs to block flash operations for a period of time.

For example, the interrupt latency introduced by an uncoordinated flash write operation could interfere with some critical operation being performed by the application.

XMEMWFF3_lock() prevents any other thread from initiating read, write, or erase operations while the user is performing an operation which is incompatible with those functions.

When the application no longer needs to block flash operations by other threads, XMEMWFF3_unlock() must be called to allow XMEM write or erase APIs to complete.

Parameters

handle	A handle returned from XMEMWFF3_open()
timeout	Timeout (in milliseconds) to wait, or #XMEM_LOCK_WAIT_FOREVER, #XMEM_LOCK_NO_WAIT

Return values

XMEM_STATUS_SUCCESS	Success.
XMEM_STATUS_TIMEOUT	If `timeout` has expired.

§ XMEMWFF3_open()

XMEM_Handle XMEMWFF3_open ( XMEM_Params * params )

Open an XMEM region for reading and writing.

Precondition: XMEMWFF3_init() was called.

Parameters

params Pointer to a parameter block. Parameters muse be initialized before calling XMEMWFF3_open()

Returns: A non-zero handle on success, else NULL.

§ XMEMWFF3_read()

int_fast16_t XMEMWFF3_read	(	XMEM_Handle	handle,
		size_t	offset,
		void *	buffer,
		size_t	bufferSize,
		uint_fast16_t	flags
	)

Read data from the XMEM region associated with the XMEM_Handle.

Parameters

handle	A handle returned from XMEMWFF3_open()
offset	The byte offset into the XMEM region to start reading from. Note: When using STIG mode, the offset + word size must not cross page boundaries (256 bytes). Operations that would exceed the current page will return an error.
buffer	A buffer to copy the data to.
bufferSize	The size of the buffer (number of bytes to read). If XMEM_READ_STIG flash is on, and bufferSize is higher than 4 (one word), only the first 4 bytes will be read. If XMEM_READ_STIG flash is on, bufferSize is not allowed to be lower than 4 (one word).
flags	Write flags (XMEM_READ_STIG)

Return values

XMEM_STATUS_SUCCESS	Success.
XMEM_STATUS_INV_OFFSET	If `offset` + `size` exceed the size of the region.
XMEM_STATUS_ERROR	If XMEM_READ_STIG flash is on and bufferSize is lower than 4 (one word). If the internal read STIG operation is failed.
XMEM_STATUS_INVALID_PARAMS	If flags is not contain allowed bits.

§ XMEMWFF3_unlock()

void XMEMWFF3_unlock ( XMEM_Handle handle )

Function to unlock the XMEM driver.

This function allows XMEM write and erase operations to proceed after being temporarily inhibited by a call to XMEMWFF3_lock().

Parameters

handle A handle returned from XMEMWFF3_open()

§ XMEMWFF3_write()

int_fast16_t XMEMWFF3_write	(	XMEM_Handle	handle,
		size_t	offset,
		void *	buffer,
		size_t	bufferSize,
		uint_fast16_t	flags
	)

Write data to the XMEM region associated with the XMEM_Handle.

Warning: Writing to internal flash on most devices can introduce significant interrupt latencies while the write operation is in in progress. The user may want to surround certain real-time critical code sections with XMEMWFF3_lock() and XMEMWFF3_unlock() calls in order to prevent uncoordinated flash write operations from negatively impacting performance.

Parameters

handle	A handle returned from XMEMWFF3_open()
offset	The byte offset into the XMEM region to start writing. Note: When using STIG mode, the offset + word size must not cross page boundaries (256 bytes). Operations that would exceed the current page will return an error.
buffer	A buffer containing data to write to the XMEM region.
bufferSize	The size of the buffer (number of bytes to write). If XMEM_WRITE_STIG flash is on, and bufferSize is higher than 4 (one word), only the first 4 bytes will be write. If XMEM_WRITE_STIG flash is on, bufferSize is not allowed to be lower than 4 (one word).
flags	Write flags (XMEM_WRITE_ERASE, XMEM_WRITE_PRE_VERIFY, XMEM_WRITE_POST_VERIFY, XMEM_WRITE_STIG).

Return values

XMEM_STATUS_SUCCESS	Success.
XMEM_STATUS_ERROR	If the internal flash write operation failed, or if XMEM_WRITE_POST_VERIFY was requested and the destination flash range does not match the source `buffer` data.
XMEM_STATUS_INV_OFFSET	If `offset` + `size` exceed the size of the region.
XMEM_STATUS_INV_WRITE	If XMEM_WRITE_PRE_VERIFY is requested and the destination flash address range cannot be change to the values desired.
XMEM_STATUS_INV_ALIGNMENT	If XMEM_WRITE_ERASE is requested and `offset` is not aligned on a sector boundary
XMEM_STATUS_VERIFYBUFFER	If XMEM_WRITE_PRE_VERIFY or XMEM_WRITE_POST_VERIFY is requested but the verification buffer has not been configured.
XMEM_STATUS_INVALID_PARAMS	If flags is not contain allowed bits.

Remarks: This call may lock a region to ensure atomic access to the region.

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

§ XMEM_FLASH

§ XMEM_PSRAM

§ XMEM_WORD_SIZE

§ CONFIG_XMEM_COUNT

§ XMEM_NUM_HANDLER

§ XMEM_STATUS_SUCCESS

§ XMEM_STATUS_ERROR

§ XMEM_STATUS_TIMEOUT

§ XMEM_STATUS_INV_OFFSET

§ XMEM_STATUS_INV_ALIGNMENT

§ XMEM_STATUS_INV_SIZE

§ XMEM_STATUS_INV_WRITE

§ XMEM_STATUS_VERIFYBUFFER

§ XMEM_STATUS_INVALID_PARAMS

§ XMEM_READ

§ XMEM_READ_STIG

§ XMEM_WRITE

§ XMEM_WRITE_ERASE

§ XMEM_WRITE_PRE_VERIFY

§ XMEM_WRITE_POST_VERIFY

§ XMEM_WRITE_STIG

Typedef Documentation

§ XMEM_Handle

§ XMEM_Config

Enumeration Type Documentation

§ XMEM_Flash_Idx

Function Documentation

§ XMEMWFF3_close()

§ XMEMWFF3_erase()

§ XMEMWFF3_getAttrs()

§ XMEMWFF3_getObject()

§ XMEMWFF3_getActiveHandlers()

§ XMEMWFF3_init()

§ XMEMWFF3_lock()

§ XMEMWFF3_open()

§ XMEMWFF3_read()

§ XMEMWFF3_unlock()

§ XMEMWFF3_write()