Data Structures
struct	IotSPIMasterConfig_t
	The configuration parameters for SPI Master. More...

Macros
#define	IOT_SPI_SUCCESS ( 0 )
	The return codes for the methods in SPI. More...

#define	IOT_SPI_INVALID_VALUE ( 1 )

#define	IOT_SPI_WRITE_FAILED ( 2 )

#define	IOT_SPI_READ_FAILED ( 3 )

#define	IOT_SPI_TRANSFER_ERROR ( 4 )

#define	IOT_SPI_BUS_BUSY ( 5 )

#define	IOT_SPI_NOTHING_TO_CANCEL ( 6 )

#define	IOT_SPI_FUNCTION_NOT_SUPPORTED ( 7 )

Typedefs
typedef struct IotSPIDescriptor_t *	IotSPIHandle_t
	IotSPIHandle_t is the handle type returned by calling iot_spi_open(). This is initialized in open and returned to caller. The caller must pass this pointer to the rest of APIs.

typedef void(*	IotSPICallback_t) (IotSPITransactionStatus_t xStatus, void *pvSPIparam)
	The callback function for completion of SPI operation.

Enumerations
enum	IotSPITransactionStatus_t { eSPISuccess = IOT_SPI_SUCCESS, eSPIWriteError = IOT_SPI_WRITE_FAILED, eSPIReadError = IOT_SPI_READ_FAILED, eSPITransferError = IOT_SPI_TRANSFER_ERROR }
	The SPI return status from Async operations. More...

enum	IotSPIMode_t { eSPIMode0, eSPIMode1, eSPIMode2, eSPIMode3 }
	The SPI Modes denoting the clock polarity and clock phase. More...

enum	IotSPIBitOrder_t { eSPIMSBFirst, eSPILSBFirst }
	The bit order of the data transmission. More...

enum	IotSPIIoctlRequest_t { eSPISetMasterConfig, eSPIGetMasterConfig, eSPIGetTxNoOfbytes, eSPIGetRxNoOfbytes }
	Ioctl request for SPI HAL. More...

Functions
IotSPIHandle_t	iot_spi_open (int32_t lSPIInstance)
	Initializes SPI peripheral with default configuration. More...

void	iot_spi_set_callback (IotSPIHandle_t const pxSPIPeripheral, IotSPICallback_t xCallback, void *pvUserContext)
	Sets the application callback to be called on completion of an operation. More...

int32_t	iot_spi_ioctl (IotSPIHandle_t const pxSPIPeripheral, IotSPIIoctlRequest_t xSPIRequest, void *const pvBuffer)
	Configures the SPI port with user configuration. More...

int32_t	iot_spi_read_sync (IotSPIHandle_t const pxSPIPeripheral, uint8_t *const pvBuffer, size_t xBytes)
	The SPI master starts reading from the slave synchronously. More...

int32_t	iot_spi_read_async (IotSPIHandle_t const pxSPIPeripheral, uint8_t *const pvBuffer, size_t xBytes)
	The SPI master starts reading from the slave asynchronously. More...

int32_t	iot_spi_write_sync (IotSPIHandle_t const pxSPIPeripheral, uint8_t *const pvBuffer, size_t xBytes)
	The SPI master starts transmission of data to the slave synchronously. More...

int32_t	iot_spi_write_async (IotSPIHandle_t const pxSPIPeripheral, uint8_t *const pvBuffer, size_t xBytes)
	The SPI master starts transmission of data to the slave asynchronously. More...

int32_t	iot_spi_transfer_sync (IotSPIHandle_t const pxSPIPeripheral, uint8_t const pvTxBuffer, uint8_t const pvRxBuffer, size_t xBytes)
	The SPI master starts a synchronous transfer between master and the slave. More...

int32_t	iot_spi_transfer_async (IotSPIHandle_t const pxSPIPeripheral, uint8_t const pvTxBuffer, uint8_t const pvRxBuffer, size_t xBytes)
	The SPI master starts a asynchronous transfer between master and the slave. More...

int32_t	iot_spi_close (IotSPIHandle_t const pxSPIPeripheral)
	Stops the ongoing operation on SPI bus and de-initializes the SPI peripheral. More...

int32_t	iot_spi_cancel (IotSPIHandle_t const pxSPIPeripheral)
	This function is used to cancel the current operation in progress, if the underlying driver allows the cancellation. More...

int32_t	iot_spi_select_slave (int32_t lSPIInstance, int32_t lSPISlave)
	This function is used to select spi slave. More...

Detailed Description

Macro Definition Documentation

◆ IOT_SPI_SUCCESS

#define IOT_SPI_SUCCESS ( 0 )

The return codes for the methods in SPI.

SPI operation completed successfully.

◆ IOT_SPI_INVALID_VALUE

#define IOT_SPI_INVALID_VALUE ( 1 )

At least one parameter is invalid.

◆ IOT_SPI_WRITE_FAILED

#define IOT_SPI_WRITE_FAILED ( 2 )

SPI driver returns error when performing write operation.

◆ IOT_SPI_READ_FAILED

#define IOT_SPI_READ_FAILED ( 3 )

SPI driver returns error when performing read operation.

◆ IOT_SPI_TRANSFER_ERROR

#define IOT_SPI_TRANSFER_ERROR ( 4 )

SPI driver returns error when performing transfer.

◆ IOT_SPI_BUS_BUSY

#define IOT_SPI_BUS_BUSY ( 5 )

SPI bus is busy at current time.

◆ IOT_SPI_NOTHING_TO_CANCEL

#define IOT_SPI_NOTHING_TO_CANCEL ( 6 )

No ongoing operation when cancel operation is performed.

◆ IOT_SPI_FUNCTION_NOT_SUPPORTED

#define IOT_SPI_FUNCTION_NOT_SUPPORTED ( 7 )

SPI operation is not supported.

Enumeration Type Documentation

◆ IotSPITransactionStatus_t

enum IotSPITransactionStatus_t

The SPI return status from Async operations.

Enumerator
eSPISuccess	SPI operation completed successfully.
eSPIWriteError	SPI driver returns error when performing write operation.
eSPIReadError	SPI driver returns error when performing read operation.
eSPITransferError	SPI driver returns error when performing transfer.

◆ IotSPIMode_t

enum IotSPIMode_t

The SPI Modes denoting the clock polarity and clock phase.

Enumerator
eSPIMode0	CPOL = 0 and CPHA = 0
eSPIMode1	CPOL = 0 and CPHA = 1
eSPIMode2	CPOL = 1 and CPHA = 0
eSPIMode3	CPOL = 1 and CPHA = 1

◆ IotSPIBitOrder_t

enum IotSPIBitOrder_t

The bit order of the data transmission.

Enumerator
eSPIMSBFirst	The master sends the most-significant bit (MSB) first
eSPILSBFirst	The master sends the least-significant bit (LSB) first

◆ IotSPIIoctlRequest_t

enum IotSPIIoctlRequest_t

Ioctl request for SPI HAL.

Enumerator
eSPISetMasterConfig	Sets the configuration of the SPI master and the data type is IotSPIMasterConfig_t.
eSPIGetMasterConfig	Gets the configuration of the SPI master and the data type is IotSPIMasterConfig_t.
eSPIGetTxNoOfbytes	Get the number of bytes sent in write operation and the data type is uint16_t.
eSPIGetRxNoOfbytes	Get the number of bytes received in read operation and the data type is uint16_t.

Function Documentation

◆ iot_spi_open()

IotSPIHandle_t iot_spi_open ( int32_t lSPIInstance )

Initializes SPI peripheral with default configuration.

Warning: Once opened, the same SPI instance must be closed before calling open again.

Parameters

[in] lSPIInstance The instance of the SPI driver to initialize.

Returns

'the handle to the SPI port (not NULL)', on success.
'NULL', if
- invalid instance number
- open same instance more than once before closing it

◆ iot_spi_set_callback()

void iot_spi_set_callback	(	IotSPIHandle_t const	pxSPIPeripheral,
		IotSPICallback_t	xCallback,
		void *	pvUserContext
	)

Sets the application callback to be called on completion of an operation.

The callback is guaranteed to be invoked when the current asynchronous operation completes, either successful or failed. This simply provides a notification mechanism to user's application. It has no impact if the callback is not set.

Note: This callback will not be invoked when synchronous operation completes.; This callback is per handle. Each instance has its own callback.; Single callback is used for both read_async and write_async. Newly set callback overrides the one previously set.

Warning: If the input handle is invalid, this function silently takes no action.

Parameters

[in]	pxSPIPeripheral	The SPI peripheral handle returned in the open() call.
[in]	xCallback	The callback function to be called on completion of operation.
[in]	pvUserContext	The user context to be passed back when callback is called.

◆ iot_spi_ioctl()

int32_t iot_spi_ioctl	(	IotSPIHandle_t const	pxSPIPeripheral,
		IotSPIIoctlRequest_t	xSPIRequest,
		void *const	pvBuffer
	)

Configures the SPI port with user configuration.

Note: eSPISetMasterConfig sets the configurations for master. This request expects the buffer with size of IotSPIMasterConfig_t.; eSPIGetMasterConfig gets the current configuration for SPI master. This request expects the buffer with size of IotSPIMasterConfig_t.; eSPIGetTxNoOfbytes returns the number of written bytes in last operation. This is supposed to be called in the caller task or application callback, right after last operation completes. This request expects 2 bytes buffer (uint16_t).

If the last operation only did write, this returns the actual number of written bytes which might be smaller than the requested number (partial write).
If the last operation only did read, this returns 0.
If the last operation did both write and read, this returns the number of written bytes.

Note: eSPIGetRxNoOfbytes returns the number of read bytes in last operation. This is supposed to be called in the caller task or application callback, right after last operation completes. This request expects 2 bytes buffer (uint16_t).

If the last operation only did read, this returns the actual number of read bytes which might be smaller than the requested number (partial read).
If the last operation only did write, this returns 0.
If the last operation did both write and read, this returns the number of read bytes.

Parameters

[in]	pxSPIPeripheral	The SPI peripheral handle returned in open() call.
[in]	xSPIRequest	The configuration request from one of the IotSPIIoctlRequest_t.
[in,out]	pvBuffer	The configuration values for the SPI port.

Returns

IOT_SPI_SUCCESS, on success
IOT_SPI_INVALID_VALUE, if
- pxSPIPeripheral is NULL
- pxSPIPeripheral is not opened yet
- pucBuffer is NULL with requests which needs buffer
IOT_SPI_BUS_BUSY, if the bus is busy for only following requests:
- eSPISetMasterConfig

◆ iot_spi_read_sync()

int32_t iot_spi_read_sync	(	IotSPIHandle_t const	pxSPIPeripheral,
		uint8_t *const	pvBuffer,
		size_t	xBytes
	)

The SPI master starts reading from the slave synchronously.

This function attempts to read certain number of bytes from slave device to a pre-allocated buffer, in synchronous way. This function does not return on paritial read, unless there is an error. And the number of bytes that have been actually read can be obtained by calling iot_spi_ioctl.

Note: Dummy data will be written to slave while reading. The dummy data value can be configured with iot_spi_ioctl.

Warning: None of other read or write functions shall be called during this function.

Parameters

[in]	pxSPIPeripheral	The SPI peripheral handle returned in open() call.
[out]	pvBuffer	The buffer to store the received data.
[in]	xBytes	The number of bytes to read.

Returns

IOT_SPI_SUCCESS, on success (all the requested bytes have been read)
IOT_SPI_INVALID_VALUE, if
- pxSPIPeripheral is NULL
- pxSPIPeripheral is not opened yet
- pucBuffer is NULL
- xBytes is 0
IOT_SPI_READ_ERROR, if there is some unknown driver error.
IOT_SPI_BUSY, if the bus is busy which means there is an ongoing operation.

◆ iot_spi_read_async()

int32_t iot_spi_read_async	(	IotSPIHandle_t const	pxSPIPeripheral,
		uint8_t *const	pvBuffer,
		size_t	xBytes
	)

The SPI master starts reading from the slave asynchronously.

This function attempts to read certain number of bytes from a pre-allocated buffer, in asynchronous way. It returns immediately when the operation is started and the status can be check by calling iot_spi_ioctl.

Once the operation completes successfully, the user callback will be invoked. If the operation encounters an error, the user callback will be invoked. The callback is not invoked on paritial read, unless there is an error. And the number of bytes that have been actually read can be obtained by calling iot_spi_ioctl.

Note: Dummy data will be written to slave while reading. The dummy data value can be configured with iot_spi_ioctl.; In order to get notification when the asynchronous call is completed, iot_spi_set_callback must be called prior to this.

Warning: pvBuffer must be valid before callback is invoked.; None of other read or write functions shall be called during this function or before user callback.

Parameters

[in]	pxSPIPeripheral	The SPI peripheral handle returned in open() call.
[out]	pvBuffer	The buffer to store the received data.
[in]	xBytes	The number of bytes to read.

Returns

IOT_SPI_SUCCESS, on success (all the requested bytes have been read)
IOT_SPI_INVALID_VALUE, if
- pxSPIPeripheral is NULL
- pxSPIPeripheral is not opened yet
- pucBuffer is NULL
- xBytes is 0
IOT_SPI_READ_ERROR, if there is some unknown driver error.
IOT_SPI_BUSY, if the bus is busy which means there is an ongoing operation.

◆ iot_spi_write_sync()

int32_t iot_spi_write_sync	(	IotSPIHandle_t const	pxSPIPeripheral,
		uint8_t *const	pvBuffer,
		size_t	xBytes
	)

The SPI master starts transmission of data to the slave synchronously.

This function attempts to write certain number of bytes from a pre-allocated buffer to a slave device, in synchronous way. This function does not return on paritial write, unless there is an error. And the number of bytes that have been actually written can be obtained by calling iot_spi_ioctl.

Warning: None of other read or write functions shall be called during this function.

Parameters

[in]	pxSPIPeripheral	The SPI peripheral handle returned in open() call.
[in]	pvBuffer	The buffer with data to transmit.
[in]	xBytes	The number of bytes to write.

Returns

IOT_SPI_SUCCESS, on success (all the requested bytes have been read)
IOT_SPI_INVALID_VALUE, if
- pxSPIPeripheral is NULL
- pxSPIPeripheral is not opened yet
- pucBuffer is NULL
- xBytes is 0
IOT_SPI_WRITE_ERROR, if there is some unknown driver error.
IOT_SPI_BUSY, if the bus is busy which means there is an ongoing operation.

◆ iot_spi_write_async()

int32_t iot_spi_write_async	(	IotSPIHandle_t const	pxSPIPeripheral,
		uint8_t *const	pvBuffer,
		size_t	xBytes
	)

The SPI master starts transmission of data to the slave asynchronously.

This function attempts to read certain number of bytes from a pre-allocated buffer, in asynchronous way. It returns immediately when the operation is started and the status can be check by calling iot_spi_ioctl.

Once the operation completes successfully, the user callback will be invoked. If the operation encounters an error, the user callback will be invoked. The callback is not invoked on paritial write, unless there is an error. And the number of bytes that have been actually written can be obtained by calling iot_spi_ioctl.

Note: In order to get notification when the asynchronous call is completed, iot_spi_set_callback must be called prior to this.

Warning: pvBuffer must be valid before callback is invoked.; None of other read or write functions shall be called during this function or before user callback.

Parameters

[in]	pxSPIPeripheral	The SPI peripheral handle returned in open() call.
[in]	pvBuffer	The buffer with data to transmit.
[in]	xBytes	The number of bytes to write.

Returns

IOT_SPI_SUCCESS, on success (all the requested bytes have been read)
IOT_SPI_INVALID_VALUE, if
- pxSPIPeripheral is NULL
- pxSPIPeripheral is not opened yet
- pucBuffer is NULL
- xBytes is 0
IOT_SPI_WRITE_ERROR, if there is some unknown driver error.
IOT_SPI_BUSY, if the bus is busy which means there is an ongoing operation.

◆ iot_spi_transfer_sync()

int32_t iot_spi_transfer_sync	(	IotSPIHandle_t const	pxSPIPeripheral,
		uint8_t *const	pvTxBuffer,
		uint8_t *const	pvRxBuffer,
		size_t	xBytes
	)

The SPI master starts a synchronous transfer between master and the slave.

This function attempts to read/write certain number of bytes from/to two pre-allocated buffers at the same time, in synchronous way. This function does not return on paritial read/write, unless there is an error. And the number of bytes that have been actually read or written can be obtained by calling iot_spi_ioctl.

Parameters

[in]	pxSPIPeripheral	The SPI peripheral handle returned in open() call.
[in]	pvTxBuffer	The buffer to store the received data.
[out]	pvRxBuffer	The buffer with data to transmit.
[in]	xBytes	The number of bytes to transfer.

Returns

IOT_SPI_SUCCESS, on success (all the requested bytes have been read/written)
IOT_SPI_INVALID_VALUE, if
- pxSPIPeripheral is NULL
- pxSPIPeripheral is not opened yet
- pucBuffer is NULL
- xBytes is 0
IOT_SPI_TRANSFER_ERROR, if there is some unknown driver error.
IOT_SPI_BUSY, if the bus is busy which means there is an ongoing operation.

◆ iot_spi_transfer_async()

int32_t iot_spi_transfer_async	(	IotSPIHandle_t const	pxSPIPeripheral,
		uint8_t *const	pvTxBuffer,
		uint8_t *const	pvRxBuffer,
		size_t	xBytes
	)

The SPI master starts a asynchronous transfer between master and the slave.

This function attempts to read/write certain number of bytes from/to two pre-allocated buffers at the same time, in asynchronous way. It returns immediately when the operation is started and the status can be check by calling iot_spi_ioctl.

Once the operation completes successfully, the user callback will be invoked. If the operation encounters an error, the user callback will be invoked. The callback is not invoked on paritial read/write, unless there is an error. And the number of bytes that have been actually read/write can be obtained by calling iot_spi_ioctl.

Parameters

[in]	pxSPIPeripheral	The SPI peripheral handle returned in open() call.
[in]	pvTxBuffer	The buffer to store the received data.
[out]	pvRxBuffer	The buffer with data to transmit.
[in]	xBytes	The number of bytes to transfer.

IOT_SPI_SUCCESS, on success (all the requested bytes have been read/written)
IOT_SPI_INVALID_VALUE, if
- pxSPIPeripheral is NULL
- pxSPIPeripheral is not opened yet
- pucBuffer is NULL
- xBytes is 0
IOT_SPI_TRANSFER_ERROR, if there is some unknown driver error.
IOT_SPI_BUSY, if the bus is busy which means there is an ongoing opeartion.

◆ iot_spi_close()

int32_t iot_spi_close ( IotSPIHandle_t const pxSPIPeripheral )

Stops the ongoing operation on SPI bus and de-initializes the SPI peripheral.

Parameters

[in] pxSPIPeripheral The SPI peripheral handle returned in open() call.

Returns

IOT_SPI_SUCCESS, on success
IOT_SPI_INVALID_VALUE, if
- pxSPIPeripheral is NULL
- pxSPIPeripheral is not opened yet

◆ iot_spi_cancel()

int32_t iot_spi_cancel ( IotSPIHandle_t const pxSPIPeripheral )

This function is used to cancel the current operation in progress, if the underlying driver allows the cancellation.

Parameters

[in] pxSPIPeripheral The SPI peripheral handle returned in open() call.

Returns

IOT_SPI_SUCCESS, on success
IOT_SPI_INVALID_VALUE, if
- pxSPIPeripheral is NULL
- pxSPIPeripheral is not opened yet
IOT_SPI_NOTHING_TO_CANCEL, if there is no on-going operation.
IOT_SPI_FUNCTION_NOT_SUPPORTED, if this board doesn't support this operation.

◆ iot_spi_select_slave()

int32_t iot_spi_select_slave	(	int32_t	lSPIInstance,
		int32_t	lSPISlave
	)

This function is used to select spi slave.

Parameters

[in]	lSPIInstance	The instance of the SPI driver to initialize.
[in]	lSPISlave	Slave select number.

Returns

IOT_SPI_SUCCESS, on success
IOT_SPI_INVALID_VALUE, if
- lSPISlave is invalid

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ IOT_SPI_SUCCESS

◆ IOT_SPI_INVALID_VALUE

◆ IOT_SPI_WRITE_FAILED

◆ IOT_SPI_READ_FAILED

◆ IOT_SPI_TRANSFER_ERROR

◆ IOT_SPI_BUS_BUSY

◆ IOT_SPI_NOTHING_TO_CANCEL

◆ IOT_SPI_FUNCTION_NOT_SUPPORTED

Enumeration Type Documentation

◆ IotSPITransactionStatus_t

◆ IotSPIMode_t

◆ IotSPIBitOrder_t

◆ IotSPIIoctlRequest_t

Function Documentation

◆ iot_spi_open()

◆ iot_spi_set_callback()

◆ iot_spi_ioctl()

◆ iot_spi_read_sync()

◆ iot_spi_read_async()

◆ iot_spi_write_sync()

◆ iot_spi_write_async()

◆ iot_spi_transfer_sync()

◆ iot_spi_transfer_async()

◆ iot_spi_close()

◆ iot_spi_cancel()

◆ iot_spi_select_slave()