Adapter for SPI controller. More...

Files
file	ad_spi.h
	SPI Controller access API.

Data Structures
struct	ad_spi_io_conf_t
	SPI I/O configuration. More...

struct	ad_spi_driver_conf_t
	SPI driver configuration. More...

struct	ad_spi_controller_conf_t
	SPI controller configuration. More...

Macros
#define	CONFIG_SPI_USE_ASYNC_TRANSACTIONS (1)
	Controls whether SPI asynchronous transaction API will be used.

#define	CONFIG_SPI_USE_SYNC_TRANSACTIONS (1)
	Controls whether SPI synchronous transaction API will be used. More...

Typedefs
typedef void *	ad_spi_handle_t
	SPI Handle returned by ad_spi_open()

Enumerations
enum	AD_SPI_ERROR
	enum with return values of API calls

Functions
void	ad_spi_init (void)
	Initialize adapter. More...

ad_spi_handle_t	ad_spi_open (const ad_spi_controller_conf_t *conf)
	Open SPI controller. More...

int	ad_spi_reconfig (ad_spi_handle_t handle, const ad_spi_driver_conf_t *drv_conf)
	Reconfigure SPI controller. More...

int	ad_spi_close (ad_spi_handle_t handle, bool force)
	Close SPI controller. More...

int	ad_spi_io_config (HW_SPI_ID id, const ad_spi_io_conf_t *io, AD_IO_CONF_STATE state)
	Initialize controller pins to on / off io configuration. More...

int	ad_spi_write (ad_spi_handle_t handle, const uint8_t *wbuf, size_t wlen)
	Perform a blocking write transaction. More...

int	ad_spi_read (ad_spi_handle_t handle, uint8_t *rbuf, size_t rlen)
	Perform a blocking read transaction. More...

int	ad_spi_write_read (ad_spi_handle_t handle, const uint8_t wbuf, uint8_t rbuf, size_t len)
	Perform a blocking write and read transaction. More...

void	ad_spi_activate_cs (ad_spi_handle_t handle, uint8_t csid)
	Activate chip select for a specific device. More...

void	ad_spi_deactivate_cs (ad_spi_handle_t handle)
	Deactivate chip select for a specific device. More...

void	ad_spi_deactivate_cs_when_spi_done (ad_spi_handle_t handle)
	Wait for SPI interface to be idle and deactivate chip select. More...

int	ad_spi_write_async (ad_spi_handle_t handle, const uint8_t wbuf, size_t wlen, ad_spi_user_cb cb, void user_data)
	Perform a non blocking write transaction. More...

int	ad_spi_read_async (ad_spi_handle_t handle, const uint8_t rbuf, size_t rlen, ad_spi_user_cb cb, void user_data)
	Perform a blocking read transaction. More...

int	ad_spi_write_read_async (ad_spi_handle_t handle, const uint8_t wbuf, size_t wlen, uint8_t rbuf, size_t rlen, ad_spi_user_cb cb, void *user_data)
	Perform asynchronous SPI write and then read transaction. It can be used as write command and read buffer operation. More...

Detailed Description

Adapter for SPI controller.

Macro Definition Documentation

◆ CONFIG_SPI_USE_SYNC_TRANSACTIONS

#define CONFIG_SPI_USE_SYNC_TRANSACTIONS (1)

Controls whether SPI synchronous transaction API will be used.

SPI synchronous transaction API maintains state in retention RAM for every SPI bus declared. If the API is not to be used, setting this macro to 0 will save retention RAM.

Function Documentation

◆ ad_spi_activate_cs()

void ad_spi_activate_cs	(	ad_spi_handle_t	handle,
		uint8_t	csid
	)

Activate chip select for a specific device.

Parameters

[in]	handle	The handle to the SPI device
[in]	csid	The index in the CS list

Warning: The task must own the controller before calling this function

Note: This function should be called only by SPI master.

◆ ad_spi_close()

int ad_spi_close	(	ad_spi_handle_t	handle,
		bool	force
	)

Close SPI controller.

This function:

Aborts ongoing transactions
De-initializes the drivers associated with the controller
Resets controller interface IOs (as specified in ad_spi_open())
Releases the controller resources

Parameters

[in]	handle	handle returned from ad_spi_open()
[in]	force	force close and abort ongoing transaction

Returns: 0: success, <0: error code

See also: ad_spi_open()

◆ ad_spi_deactivate_cs()

void ad_spi_deactivate_cs ( ad_spi_handle_t handle )

Deactivate chip select for a specific device.

Parameters

[in] handle The handle to the SPI device

Warning: The task must own the bus before calling this function.

Note: This function should be called only by SPI master.

◆ ad_spi_deactivate_cs_when_spi_done()

void ad_spi_deactivate_cs_when_spi_done ( ad_spi_handle_t handle )

Wait for SPI interface to be idle and deactivate chip select.

Parameters

[in] handle The handle to the SPI device

Warning: The device and the bus resources must have been acquired before calling this function.

Note: This function should be called only by SPI master.

◆ ad_spi_init()

void ad_spi_init ( void )

Initialize adapter.

Note: It should ONLY be called by the system.

◆ ad_spi_io_config()

int ad_spi_io_config	(	HW_SPI_ID	id,
		const ad_spi_io_conf_t *	io,
		AD_IO_CONF_STATE	state
	)

Initialize controller pins to on / off io configuration.

This function should be called for setting pins to the correct level before external devices are powered up (e.g on system init). It does not need to be called before every ad_spi_open() call.

Parameters

[in]	id	controller instance
[in]	io	controller io configuration
[in]	state	on/off io configuration

Returns: 0: success, <0: error code

◆ ad_spi_open()

ad_spi_handle_t ad_spi_open ( const ad_spi_controller_conf_t * conf )

Open SPI controller.

This function:

Acquires the resources needed for using the controller
Configures the controller interface IOs. The CS (SPI enable pin) is the first in the relevant I/O list.
Initializes the drivers associated with the controller

Parameters

[in] conf controller configuration

Returns: >0: handle that should be used in subsequent API calls, NULL: error

Note: The function will block until it acquires all controller resources

◆ ad_spi_read()

int ad_spi_read	(	ad_spi_handle_t	handle,
		uint8_t *	rbuf,
		size_t	rlen
	)

Perform a blocking read transaction.

This function performs a synchronous read only transaction

Parameters

[in]	handle	handle returned from ad_spi_open()
[out]	rbuf	buffer for incoming data
[in]	rlen	number of bytes to read

Returns: 0 on success, <0: error

See also: ad_spi_open(); ad_spi_close()

Note: Supplied buffer address and length must be SPI-word-aligned (no alignment needed for 9-bit SPI word configurations).

◆ ad_spi_read_async()

int ad_spi_read_async	(	ad_spi_handle_t	handle,
		const uint8_t *	rbuf,
		size_t	rlen,
		ad_spi_user_cb	cb,
		void *	user_data
	)

Perform a blocking read transaction.

This function performs a synchronous read only transaction

Parameters

[in]	handle	handle returned from ad_spi_open()
[out]	rbuf	buffer for incoming data
[in]	rlen	number of bytes to read
[in]	cb	callback to call after transaction is over (from ISR context)
[in]	user_data	user data passed to cb callback

See also: ad_spi_open()

Returns: 0 on success, <0: error

◆ ad_spi_reconfig()

int ad_spi_reconfig	(	ad_spi_handle_t	handle,
		const ad_spi_driver_conf_t *	drv_conf
	)

Reconfigure SPI controller.

This function will apply a new SPI driver configuration.

Parameters

[in]	handle	handle returned from ad_spi_open()
[in]	drv_conf	new driver configuration

Returns: 0: success, <0: error code

See also: ad_spi_open()

Note: No change in I/O configuration is done.

◆ ad_spi_write()

int ad_spi_write	(	ad_spi_handle_t	handle,
		const uint8_t *	wbuf,
		size_t	wlen
	)

Perform a blocking write transaction.

This function performs a synchronous write only transaction

Parameters

[in]	handle	handle returned from ad_spi_open()
[in]	wbuf	buffer containing the data to be sent to the device
[in]	wlen	size of data to be sent to the device

Returns: 0 on success, <0: error

Note

In slave mode, the first word to be transmitted should be written to the TX buffer and the remaining words are written to the TX FIFO. Moreover, there are cases where the ad_spi_write() is non-blocking. In such cases, the application should resolve this by a higher layer protocol. Otherwise, ad_spi_writeread() can be used where the incoming buffer is set to NULL, i.e. used in write only mode. This is always blocking because the terminating event is triggered when all bytes are received.

TX FIFO width = 8 bits and depth = 4 Bytes
TX Buffer = 32 bits

SPI_WORD_LENGTH = 3..7 => word size = 1 Byte: a. wlen = 1 (DMA is not enabled), b. wlen = 2 and SPI_TX_TL = 0..4, c. wlen = 3 and SPI_TX_TL = 1..4, d. wlen = 4 and SPI_TX_TL = 2..4, e. wlen = 5 and SPI_TX_TL = 3..4, and f. wlen > 5 and SPI_TX_TL = 4.
SPI_WORD_LENGTH = 8..15 => word size = 2 Bytes: a. wlen = 2 (DMA is not enabled), b. wlen = 4 and SPI_TX_TL = 0..4, c. wlen = 6 and SPI_TX_TL = 2..4, d. wlen >= 8 and SPI_TX_TL = 4.
SPI_WORD_LENGTH = 16..31 => word size = 4 Bytes: a. wlen = 4 (DMA is not enabled), b. wlen = 8 and SPI_TX_TL = 0..4, and c. wlen >= 12 and SPI_TX_TL = 4.

The mechanism that fetches data into the TX fifo and from TX fifo to TX buffer is as follows:

DMA mode: When data is to be transmitted in Slave mode using DMA, the first word is written to SPI_TXBUFFER_FORCE_REG and the DMA is programmed to send the remaining words. When the number of bytes in the TX fifo is less or equal to the TX threshold level set by the user (SPI_TX_TL), an SPI_STATUS_TX_EMPTY event triggers the DMA to fetch new data into the TX FIFO. When the last byte is added in the TX fifo, the dma has finished, the TX dma callback is called and ad_spi_write() returns. This means that for the TX Path, there is no signal notifying about the actual transmission of the last byte on the bus.

Interrupt mode: When the number of bytes in the TX fifo is less or equal to the TX threshold level set by the user (SPI_TX_TL), an SPI_STATUS_TX_EMPTY event triggers the spi interrupt handler, which adds new data in the TX fifo. The user callback is called when the last byte is added in the TX fifo.

Case 1.a: In the special case where only one word needs to be sent, DMA cannot not be enabled to send zero words, although DMA may have been requested by the user during driver initialization. Instead, interrupt mode will be enabled for receiving an asynchronous notification and eventually call the user callback as required by the driver API.

Case 1.b: In the special case where two words needs to be sent, DMA will be enabled. The first word is written to SPI_TXBUFFER_FORCE_REG and the DMA is programmed to send the remaining word. The first time, the TX fifo is always empty i.e. it always has less or equal bytes to the TX threshold level set by the user (SPI_TX_TL). Therefore, an SPI_STATUS_TX_EMPTY event triggers the DMA to fetch a new word into the TX FIFO. When the last and only one word is added in the TX fifo, the dma has finished and the TX dma callback is called.

Note: Supplied buffer address and length must be non-zero and SPI-word-aligned

◆ ad_spi_write_async()

int ad_spi_write_async	(	ad_spi_handle_t	handle,
		const uint8_t *	wbuf,
		size_t	wlen,
		ad_spi_user_cb	cb,
		void *	user_data
	)

Perform a non blocking write transaction.

This function performs an asynchronous write only transaction Caller task should retry until function returns no error Callback will be called when transaction is completed

Parameters

[in]	handle	handle returned from ad_spi_open()
[in]	wbuf	buffer containing the data to be sent to the device
[in]	wlen	size of data to be sent to the device
[in]	cb	callback to call after transaction is over (from ISR context)
[in]	user_data	user data passed to cb callback

See also: ad_spi_open()

Returns: 0 on success, <0: error

◆ ad_spi_write_read()

int ad_spi_write_read	(	ad_spi_handle_t	handle,
		const uint8_t *	wbuf,
		uint8_t *	rbuf,
		size_t	len
	)

Perform a blocking write and read transaction.

This function performs a synchronous write and read transaction If wbuf is NULL then the function is used to read data If rbuf is NULL then the function is used to write data Buffers wbuf and rbuf cannot be both NULL

Parameters

[in]	handle	handle returned from ad_spi_open()
[in]	wbuf	buffer containing the data to be sent to the device
[in]	rbuf	buffer for incoming data
[in]	len	size of data to be sent/read to the device

Returns: 0 on success, <0: error

Note: Supplied buffer address and length must be SPI-word-aligned (DA1468X and DA1469X: no alignment needed for 9-bit SPI word configurations).

◆ ad_spi_write_read_async()

int ad_spi_write_read_async	(	ad_spi_handle_t	handle,
		const uint8_t *	wbuf,
		size_t	wlen,
		uint8_t *	rbuf,
		size_t	rlen,
		ad_spi_user_cb	cb,
		void *	user_data
	)

Perform asynchronous SPI write and then read transaction. It can be used as write command and read buffer operation.

This function performs write command and read buffer transaction on SPI bus. The device and the bus resources must have been acquired and the chip select must be activated before calling this function. This can be achieved by calling ad_spi_start(). The callback function is executed when transaction has been completed. At this point SPI data are available to be used by the application. In the callback function one of the following actions can be performed:

Read or write additional data by calling ad_spi_async_read() / ad_spi_async_write()
Notify application task that SPI transaction has been completed. ad_spi_end() must be called from application task context.

Parameters

[in]	handle	handle returned from ad_spi_open()
[in]	wbuf	data to send
[in]	wlen	number of bytes to write
[out]	rbuf	buffer for incoming data
[in]	rlen	number of bytes to read
[in]	cb	callback to call after transaction is over (from ISR context)
[in]	user_data	user data to pass to `cb`

See also: ad_spi_open()

Returns: 0 on success, <0: error

Files

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ CONFIG_SPI_USE_SYNC_TRANSACTIONS

Function Documentation

◆ ad_spi_activate_cs()

◆ ad_spi_close()

◆ ad_spi_deactivate_cs()

◆ ad_spi_deactivate_cs_when_spi_done()

◆ ad_spi_init()

◆ ad_spi_io_config()

◆ ad_spi_open()

◆ ad_spi_read()

◆ ad_spi_read_async()

◆ ad_spi_reconfig()

◆ ad_spi_write()

◆ ad_spi_write_async()

◆ ad_spi_write_read()

◆ ad_spi_write_read_async()