Data Structures
struct	IotFlashInfo_t
	flash information More...

struct	IotFlashWriteProtectConfig_t
	Flash protection configuration. More...

Macros
#define	IOT_FLASH_SUCCESS ( 0 )
	Return values used by this driver. More...

#define	IOT_FLASH_INVALID_VALUE ( 1 )

#define	IOT_FLASH_WRITE_FAILED ( 2 )

#define	IOT_FLASH_READ_FAILED ( 3 )

#define	IOT_FLASH_ERASE_FAILED ( 4 )

#define	IOT_FLASH_DEVICE_BUSY ( 5 )

#define	IOT_FLASH_CTRL_OP_FAILED ( 6 )

#define	IOT_FLASH_FUNCTION_NOT_SUPPORTED ( 7 )

Typedefs
typedef struct IotFlashDescriptor *	IotFlashHandle_t
	IotFlashHandle_t type is the flash handle returned by calling iot_flash_open() this is initialized in open and returned to caller. Caller must pass this pointer to the rest of the APIs.

typedef void(*	IotFlashCallback_t) (IotFlashOperationStatus_t xStatus, void *pvUserContext)
	Flash notification callback type. This callback can be passed to the driver by using iot_flash_set_callback API (the callback is used only if flash supports asynchronous operations, which can be checked from flashInfo.ucAsyncSupported value. More...

Enumerations
enum	IotFlashStatus_t { eFlashIdle, eFlashCmdInProgress, eFlashEraseFailed, eFlashProgramSuspended, eFlashEraseSuspended }
	Flash current status. More...

enum	IotFlashOperationStatus_t { eFlashCompleted = IOT_FLASH_SUCCESS, eFlashLastEraseFailed = IOT_FLASH_ERASE_FAILED, eFlashLastReadFailed = IOT_FLASH_READ_FAILED, eFlashLastWriteFailed = IOT_FLASH_WRITE_FAILED }
	Flash driver last operation status. More...

enum	IotFlashWriteProtect_t { eFlashReadWrite, eFlashReadOnly }
	Flash sector protection type. More...

enum	IotFlashIoctlRequest_t { eSetFlashBlockProtection, eGetFlashBlockProtection, eSuspendFlashProgramErase, eResumeFlashProgramErase, eGetFlashStatus, eGetFlashTxNoOfbytes, eGetFlashRxNoOfbytes }
	Ioctl request types. More...

Functions
IotFlashHandle_t	iot_flash_open (int32_t lFlashInstance)
	iot_flash_open is used to initialize the flash device. This must be called before using any other flash APIs. This function Initializes the peripheral, configures buses etc. More...

IotFlashInfo_t *	iot_flash_getinfo (IotFlashHandle_t const pxFlashHandle)
	iot_flash_getinfo is used to get the information about the physical flash device. More...

void	iot_flash_set_callback (IotFlashHandle_t const pxFlashHandle, IotFlashCallback_t xCallback, void *pvUserContext)
	iot_flash_set_callback is used to set the callback to be called upon completion of erase/program/read. The callback is used only if the underlying HW supports asynchronous operations. Caller can check if asynchronous operations are supported by checking the "ucAsyncSupported" flag in IotFlashInfo_t structure. If asynchronous operations are not supported, then erase/write/read operations are blocking operations, and this API has no affect, i.e even if a callback is set, it will never be called back. More...

int32_t	iot_flash_ioctl (IotFlashHandle_t const pxFlashHandle, IotFlashIoctlRequest_t xRequest, void *const pvBuffer)
	iot_flash_ioctl is used to configure the flash parameters and setup certain flash operations and also used to read flash info and configuration. More...

int32_t	iot_flash_erase_sectors (IotFlashHandle_t const pxFlashHandle, uint32_t ulStartAddress, size_t xSize)
	iot_flash_erase_sectors is used to erase data in flash from the start of the address specified until the startAddress plus size passed. The address passed in 'ulAddress' must be aligned to ulSectorSize, and size must be a multiple of ulSectorSize. If there is another flash operation is in progress, the erase_sectors API will return an error and this usually happens if flash supports asynchronous erase/write/read operations. More...

int32_t	iot_flash_erase_chip (IotFlashHandle_t const pxFlashHandle)
	iot_erase_chip is used to erase the entire flash chip. If there is another flash operation is in progress, the erase_chip API will return an error. More...

int32_t	iot_flash_write_sync (IotFlashHandle_t const pxFlashHandle, uint32_t ulAddress, uint8_t *const pvBuffer, size_t xBytes)
	iot_flash_write_sync is used to write data to flash starting at the address provided. The sector(s) being written to, must be erased first before any write can take place. This is a blocking operation and waits until the number of bytes are written before returning. If there is another flash operation is in progress, write will return an error. More...

int32_t	iot_flash_read_sync (IotFlashHandle_t const pxFlashHandle, uint32_t ulAddress, uint8_t *const pvBuffer, size_t xBytes)
	iot_flash_read_sync is used to read data from flash. This is a blocking operation and waits until the number of bytes are read before returning. If there is another flash operation is in progress, this will return an error. More...

int32_t	iot_flash_write_async (IotFlashHandle_t const pxFlashHandle, uint32_t ulAddress, uint8_t *const pvBuffer, size_t xBytes)
	iot_flash_write_async is used to write data to flash starting at the address provided. The sector(s) being written to, must be erased first before any write can take place. This is an asynchronous (non-blocking) operation and returns as soon as the write operation is started. When the write is completed, user callback is called to notify that the write is complete. The caller can check the status of the operation by using eGetStatus IOCTL. User must register for a callback when using the non-blocking operations to know when they are complete. If there is another flash operation is in progress, write will return an error. More...

int32_t	iot_flash_read_async (IotFlashHandle_t const pxFlashHandle, uint32_t ulAddress, uint8_t *const pvBuffer, size_t xBytes)
	iot_flash_read_async is used to read data from flash. This is an asynchronous (non-blocking) operation and returns as soon as the read operation is started. When the read is completed, user callback is called to notify that the read is complete. The caller can check the status of the operation by using eGetStatus IOCTL and use the buffer. User must register for a callback when using the non-blocking operations to know when they are complete. If there is another flash operation is in progress, this will return an error. More...

int32_t	iot_flash_close (IotFlashHandle_t const pxFlashHandle)
	iot_flash_close is used to close the flash device. If any operations are in progress when close is called, flash driver aborts those if possible. More...

Detailed Description

Macro Definition Documentation

◆ IOT_FLASH_SUCCESS

#define IOT_FLASH_SUCCESS ( 0 )

Return values used by this driver.

Flash operation completed succesfully.

◆ IOT_FLASH_INVALID_VALUE

#define IOT_FLASH_INVALID_VALUE ( 1 )

At least one parameter is invalid.

◆ IOT_FLASH_WRITE_FAILED

#define IOT_FLASH_WRITE_FAILED ( 2 )

Flash write operation failed.

◆ IOT_FLASH_READ_FAILED

#define IOT_FLASH_READ_FAILED ( 3 )

Flash read operation failed.

◆ IOT_FLASH_ERASE_FAILED

#define IOT_FLASH_ERASE_FAILED ( 4 )

Flash erase operation failed.

◆ IOT_FLASH_DEVICE_BUSY

#define IOT_FLASH_DEVICE_BUSY ( 5 )

Previous flash operation not complete yet.

◆ IOT_FLASH_CTRL_OP_FAILED

#define IOT_FLASH_CTRL_OP_FAILED ( 6 )

Flash control operation failed.

◆ IOT_FLASH_FUNCTION_NOT_SUPPORTED

#define IOT_FLASH_FUNCTION_NOT_SUPPORTED ( 7 )

Flash operation not supported.

Typedef Documentation

◆ IotFlashCallback_t

typedef void( * IotFlashCallback_t) (IotFlashOperationStatus_t xStatus, void *pvUserContext)

Flash notification callback type. This callback can be passed to the driver by using iot_flash_set_callback API (the callback is used only if flash supports asynchronous operations, which can be checked from flashInfo.ucAsyncSupported value.

Parameters

[out]	xStatus	Flash asynchronous operation status.
[in]	pvUserContext	User Context passed when setting the callback. This is not used or modified by the driver. The context is provided by the caller when setting the callback, and is passed back to the caller in the callback.

Enumeration Type Documentation

◆ IotFlashStatus_t

enum IotFlashStatus_t

Flash current status.

Enumerator
eFlashIdle	Flash is idle.
eFlashCmdInProgress	Flash command in progress.
eFlashEraseFailed	Flash erase failed.
eFlashProgramSuspended	Flash program operation suspended.

◆ IotFlashOperationStatus_t

enum IotFlashOperationStatus_t

Flash driver last operation status.

Enumerator
eFlashCompleted	Flash operation completed successfully.
eFlashLastEraseFailed	Flash erase operation failed.
eFlashLastReadFailed	Flash read operation failed.
eFlashLastWriteFailed	Flash write operation failed.

◆ IotFlashWriteProtect_t

enum IotFlashWriteProtect_t

Flash sector protection type.

Enumerator
eFlashReadWrite	Flash write protect set to read/write
eFlashReadOnly	Flash write protect set to read only

◆ IotFlashIoctlRequest_t

enum IotFlashIoctlRequest_t

Ioctl request types.

Enumerator
eSetFlashBlockProtection	Set block protection, takes the input of IotFlashWriteProtectConfig_t type
eGetFlashBlockProtection	Get block protection. takes the input of IotFlashWriteProtectConfig_t type and updates the xProtectionLevel for the address passed. ulSize in the input is ignored
eSuspendFlashProgramErase	Suspends any program or erase operations. This may be useful if there is an high priority read that needs to happen when program or erase may be in progress. Ex: XiP access
eResumeFlashProgramErase	Resumes any program or erase operation that was previously Suspended using eSuspendFlashProgramErase IOCTL
eGetFlashStatus	Get flash status. Return IotFlashStatus_t type
eGetFlashTxNoOfbytes	Get the number of bytes sent in write operation. Returns uint32_t type.
eGetFlashRxNoOfbytes	Get the number of bytes received in read operation. Returns uint32_t type.

Function Documentation

◆ iot_flash_open()

IotFlashHandle_t iot_flash_open ( int32_t lFlashInstance )

iot_flash_open is used to initialize the flash device. This must be called before using any other flash APIs. This function Initializes the peripheral, configures buses etc.

Parameters

[in] lFlashInstance The instance of the flash to initialize. If there are more than one flash per device, the first flash is 0, the second flash is 1 etc.

Returns

returns the handle IotFlashHandle_t on success
NULL if
- instance number is invalid
- same instance is already open.

◆ iot_flash_getinfo()

IotFlashInfo_t* iot_flash_getinfo ( IotFlashHandle_t const pxFlashHandle )

iot_flash_getinfo is used to get the information about the physical flash device.

Parameters

[in] pxFlashHandle handle to flash driver returned in iot_flash_open()

Returns

the pointer to flash information structure IotFlashInfo_t
NULL if pxFlashHandle was invalid

◆ iot_flash_set_callback()

void iot_flash_set_callback	(	IotFlashHandle_t const	pxFlashHandle,
		IotFlashCallback_t	xCallback,
		void *	pvUserContext
	)

iot_flash_set_callback is used to set the callback to be called upon completion of erase/program/read. The callback is used only if the underlying HW supports asynchronous operations. Caller can check if asynchronous operations are supported by checking the "ucAsyncSupported" flag in IotFlashInfo_t structure. If asynchronous operations are not supported, then erase/write/read operations are blocking operations, and this API has no affect, i.e even if a callback is set, it will never be called back.

Note: Single callback is used for asynchronous read / write / erase APIs.; Newly set callback overrides the one previously set; This callback will not be invoked when synchronous operation completes.; This callback is per handle. Each instance has its own callback.

Warning: If input handle or if callback function is NULL, this function silently takes no action.

Parameters

[in]	pxFlashHandle	handle to flash driver returned in iot_flash_open()
[in]	xCallback	callback function to be called.
[in]	pvUserContext	user context to be passed when callback is called.

Returns: None

◆ iot_flash_ioctl()

int32_t iot_flash_ioctl	(	IotFlashHandle_t const	pxFlashHandle,
		IotFlashIoctlRequest_t	xRequest,
		void *const	pvBuffer
	)

iot_flash_ioctl is used to configure the flash parameters and setup certain flash operations and also used to read flash info and configuration.

Parameters

[in]	pxFlashHandle	handle to flash driver returned in iot_flash_open()
[in]	xRequest	configuration request of type IotFlashIoctlRequest_t
[in,out]	pvBuffer	configuration values to be written to flash or to be read from flash.

Returns

IOT_FLASH_SUCCESS on success
IOT_FLASH_INVALID_VALUE on NULL pxFlashHandle, invalid xRequest, or NULL pvBuffer when required.
IOT_FLASH_DEVICE_BUSY if previous flash command still in progress.
IOT_FLASH_CTRL_OP_FAILED if ioctl operation failed for any reason.
IOT_FLASH_FUNCTION_NOT_SUPPORTED valid only for the following if not supported
- eSetFlashBlockProtection / eGetFlashBlockProtection
- eSuspendFlashProgramErase / eResumeFlashProgramErase

◆ iot_flash_erase_sectors()

int32_t iot_flash_erase_sectors	(	IotFlashHandle_t const	pxFlashHandle,
		uint32_t	ulStartAddress,
		size_t	xSize
	)

iot_flash_erase_sectors is used to erase data in flash from the start of the address specified until the startAddress plus size passed. The address passed in 'ulAddress' must be aligned to ulSectorSize, and size must be a multiple of ulSectorSize. If there is another flash operation is in progress, the erase_sectors API will return an error and this usually happens if flash supports asynchronous erase/write/read operations.

Parameters

[in]	pxFlashHandle	handle to flash driver returned in iot_flash_open()
[in]	ulStartAddress	starting address(offset) in flash, from where erase starts. Aligned to ulSectorSize
[in]	xSize	size of the flash range to be erased. multiple of ulSectorSize

Returns

IOT_FLASH_SUCCESS on success.
IOT_FLASH_INVALID_VALUE if any parameter is invalid.
IOT_FLASH_DEVICE_BUSY if another asynchronous operation is currently being executed.
IOT_FLASH_ERASE_FAILED on error.

Example

IotFlashHandle_t xFlashHandle;
IotFlashInfo_t* pxFlashInfo;
int32_t lRetVal;
uint32_t ulChunkOffset;
// Open flash to initialize hardware.
xFlashHandle = iot_flash_open(0);
// assert(xFlashHandle == NULL );
// Get the flash information.
pxFlashInfo = iot_flash_getinfo(xFlashHandle);
// assert(pxFlashInfo == NULL);
// If Erase asyc is supported, register a callback
if ( pxFlashInfo->ucAsyncSupported )
{
    iot_flash_set_callback(xFlashHandle,
                           prvIotFlashEraseCallback,
                           NULL);
}
// Erase 2 sectors
lRetVal = iot_flash_erase_sectors(xFlashHandle,
                                  ultestIotFlashStartOffset,
                                  pxFlashInfo->ulSectorSize * 2);
//assert(IOT_FLASH_SUCCESS != lRetVal);
if ( pxFlashInfo->ucAsyncSupported )
{
    // Wait for the Erase to be completed and callback is called.
    lRetVal = xSemaphoreTake(xtestIotFlashSemaphore, portMAX_DELAY);
    //assert(pdTRUE != lRetVal);
}
// Close the flash handle.
lRetVal = iot_flash_close(xFlashHandle);
//assert(IOT_FLASH_SUCCESS != lRetVal);

◆ iot_flash_erase_chip()

int32_t iot_flash_erase_chip ( IotFlashHandle_t const pxFlashHandle )

iot_erase_chip is used to erase the entire flash chip. If there is another flash operation is in progress, the erase_chip API will return an error.

Parameters

[in] pxFlashHandle handle to flash driver returned in iot_flash_open()

Returns

IOT_FLASH_SUCCESS on success.
IOT_FLASH_INVALID_VALUE if any parameter is invalid.
IOT_FLASH_DEVICE_BUSY if another asynchronous operation is currently being executed.
IOT_FLASH_ERASE_FAILED on error.

◆ iot_flash_write_sync()

int32_t iot_flash_write_sync	(	IotFlashHandle_t const	pxFlashHandle,
		uint32_t	ulAddress,
		uint8_t *const	pvBuffer,
		size_t	xBytes
	)

iot_flash_write_sync is used to write data to flash starting at the address provided. The sector(s) being written to, must be erased first before any write can take place. This is a blocking operation and waits until the number of bytes are written before returning. If there is another flash operation is in progress, write will return an error.

Warning: writing to a sector that was not erased first, may result in incorrect data being written while the API returns IOT_FLASH_SUCCESS.

Parameters

[in]	pxFlashHandle	handle to flash driver returned in iot_flash_open()
[in]	ulAddress	starting address(offset) in flash to write.
[in]	xBytes	number of bytes to write.
[in]	pvBuffer	data buffer to write to flash

Returns

IOT_FLASH_SUCCESS on success.
IOT_FLASH_INVALID_VALUE if any parameter is invalid.
IOT_FLASH_DEVICE_BUSY if another asynchronous operation is currently being executed.
IOT_FLASH_WRITE_FAILED on error.

◆ iot_flash_read_sync()

int32_t iot_flash_read_sync	(	IotFlashHandle_t const	pxFlashHandle,
		uint32_t	ulAddress,
		uint8_t *const	pvBuffer,
		size_t	xBytes
	)

iot_flash_read_sync is used to read data from flash. This is a blocking operation and waits until the number of bytes are read before returning. If there is another flash operation is in progress, this will return an error.

Parameters

[in]	pxFlashHandle	handle to flash driver returned in iot_flash_open()
[in]	ulAddress	starting address(offset) in flash to read.
[in]	xBytes	number of bytes to be read.
[out]	pvBuffer	data buffer to hold the data read from flash

Returns

IOT_FLASH_SUCCESS on success.
IOT_FLASH_INVALID_VALUE if any parameter is invalid.
IOT_FLASH_DEVICE_BUSY if another asynchronous operation is currently being executed.
IOT_FLASH_READ_FAILED on error.

◆ iot_flash_write_async()

int32_t iot_flash_write_async	(	IotFlashHandle_t const	pxFlashHandle,
		uint32_t	ulAddress,
		uint8_t *const	pvBuffer,
		size_t	xBytes
	)

iot_flash_write_async is used to write data to flash starting at the address provided. The sector(s) being written to, must be erased first before any write can take place. This is an asynchronous (non-blocking) operation and returns as soon as the write operation is started. When the write is completed, user callback is called to notify that the write is complete. The caller can check the status of the operation by using eGetStatus IOCTL. User must register for a callback when using the non-blocking operations to know when they are complete. If there is another flash operation is in progress, write will return an error.

Parameters

[in]	pxFlashHandle	handle to flash driver returned in iot_flash_open()
[in]	ulAddress	starting address(offset) in flash to write.
[in]	xBytes	number of bytes to write.
[in]	pvBuffer	data buffer to write to flash

Returns

IOT_FLASH_SUCCESS on success.
IOT_FLASH_INVALID_VALUE if any parameter is invalid.
IOT_FLASH_DEVICE_BUSY if another asynchronous operation is currently being executed.
IOT_FLASH_WRITE_FAILED on error.
IOT_FLASH_FUNCTION_NOT_SUPPORTED if asynchronous operation is not supported (i,e ucAsyncSupported is set to false)

◆ iot_flash_read_async()

int32_t iot_flash_read_async	(	IotFlashHandle_t const	pxFlashHandle,
		uint32_t	ulAddress,
		uint8_t *const	pvBuffer,
		size_t	xBytes
	)

iot_flash_read_async is used to read data from flash. This is an asynchronous (non-blocking) operation and returns as soon as the read operation is started. When the read is completed, user callback is called to notify that the read is complete. The caller can check the status of the operation by using eGetStatus IOCTL and use the buffer. User must register for a callback when using the non-blocking operations to know when they are complete. If there is another flash operation is in progress, this will return an error.

Parameters

[in]	pxFlashHandle	handle to flash driver returned in iot_flash_open()
[in]	ulAddress	starting address(offset) in flash to read.
[in]	xBytes	number of bytes to be read.
[out]	pvBuffer	data buffer to hold the data read from flash

Returns

IOT_FLASH_SUCCESS on success.
IOT_FLASH_INVALID_VALUE if any parameter is invalid.
IOT_FLASH_DEVICE_BUSY if another asynchronous operation is currently being executed.
IOT_FLASH_READ_FAILED on error.
IOT_FLASH_FUNCTION_NOT_SUPPORTED if asynchronous operation is not supported (i,e ucAsyncSupported is set to false)

◆ iot_flash_close()

int32_t iot_flash_close ( IotFlashHandle_t const pxFlashHandle )

iot_flash_close is used to close the flash device. If any operations are in progress when close is called, flash driver aborts those if possible.

Parameters

[in] pxFlashHandle handle to flash driver returned in iot_flash_open()

Returns

IOT_FLASH_SUCCESS on success close
IOT_FLASH_INVALID_VALUE on invalid pxFlashHandle.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ IOT_FLASH_SUCCESS

◆ IOT_FLASH_INVALID_VALUE

◆ IOT_FLASH_WRITE_FAILED

◆ IOT_FLASH_READ_FAILED

◆ IOT_FLASH_ERASE_FAILED

◆ IOT_FLASH_DEVICE_BUSY

◆ IOT_FLASH_CTRL_OP_FAILED

◆ IOT_FLASH_FUNCTION_NOT_SUPPORTED

Typedef Documentation

◆ IotFlashCallback_t

Enumeration Type Documentation

◆ IotFlashStatus_t

◆ IotFlashOperationStatus_t

◆ IotFlashWriteProtect_t

◆ IotFlashIoctlRequest_t

Function Documentation

◆ iot_flash_open()

◆ iot_flash_getinfo()

◆ iot_flash_set_callback()

◆ iot_flash_ioctl()

◆ iot_flash_erase_sectors()

◆ iot_flash_erase_chip()

◆ iot_flash_write_sync()

◆ iot_flash_read_sync()

◆ iot_flash_write_async()

◆ iot_flash_read_async()

◆ iot_flash_close()