SPI Slave RTOS Driver#

This driver can be used to instantiate and control a SPI slave I/O interface on xcore in an RTOS application.

SPI Slave API#

The following structures and functions are used to initialize and start a SPI slave driver instance.

typedef struct rtos_spi_slave_struct rtos_spi_slave_t#

Typedef to the RTOS SPI slave driver instance struct.

typedef void (*rtos_spi_slave_start_cb_t)(rtos_spi_slave_t *ctx, void *app_data)#

Function pointer type for application provided RTOS SPI slave start callback functions.

These callback functions are optionally called by a SPI slave driver’s thread when it is first started. This gives the application a chance to perform startup initialization from within the driver’s thread. It is a good place for the first call to spi_slave_xfer_prepare().

Param ctx:

A pointer to the associated SPI slave driver instance.

Param app_data:

A pointer to application specific data provided by the application. Used to share data between this callback function and the application.

typedef void (*rtos_spi_slave_xfer_done_cb_t)(rtos_spi_slave_t *ctx, void *app_data)#

Function pointer type for application provided RTOS SPI slave transfer done callback functions.

These callback functions are optionally called when a SPI slave driver instance is done transferring data with a master device.

An application can use this to be notified immediately when a transfer has completed. It can then call spi_slave_xfer_complete() with a timeout of 0 from within this callback to get the transfer results.

Param ctx:

A pointer to the associated SPI slave driver instance.

Param app_data:

A pointer to application specific data provided by the application. Used to share data between this callback function and the application.

typedef struct xfer_done_queue_item xfer_done_queue_item_t#

Internally used struct representing an received data packet.

The members in this struct should not be accessed directly.

void spi_slave_xfer_prepare(rtos_spi_slave_t *ctx, void *rx_buf, size_t rx_buf_len, void *tx_buf, size_t tx_buf_len)#

Prepares an RTOS SPI slave driver instance with buffers for subsequent transfers. Before this is called for the first time, any transfers initiated by a master device with result in all received data over MOSI being dropped, and all data sent over MISO being zeros.

This only needs to be called when the buffers need to be changed. If all transfers will use the same buffers, then this only needs to be called once during initialization.

If the application has not processed the previous transaction, the buffers will be held, and default buffers set by spi_slave_xfer_prepare_default_buffers() will be used if a new transaction starts.

Parameters:

  • ctx – A pointer to the SPI slave driver instance to use.

  • rx_buf – The buffer to receive data into for any subsequent transfers.

  • rx_buf_ – The length in bytes of rx_buf. If the master transfers more than this during a single transfer, then the bytes that do not fit within rx_buf will be lost.

  • tx_buf – The buffer to send data from for any subsequent transfers.

  • tx_buf_len – The length in bytes of tx_buf. If the master transfers more than this during a single transfer, zeros will be sent following the last byte tx_buf.

void spi_slave_xfer_prepare_default_buffers(rtos_spi_slave_t *ctx, void *rx_buf, size_t rx_buf_len, void *tx_buf, size_t tx_buf_len)#

Prepares an RTOS SPI slave driver instance with default buffers for subsequent transfers. Before this is called for the first time, any transfers initiated by a master device with result in all received data over MOSI being dropped, and all data sent over MISO being zeros.

This only needs to be called when the buffers need to be changed.

The default buffer will be used in the event that the application has not yet processed the previous transfer. This enables the application to have a default buffer to implement a sort of NACK over SPI in the event that the device was busy and had not yet finished handling the previous transaction before a new one started.

Parameters:

  • ctx – A pointer to the SPI slave driver instance to use.

  • rx_buf – The buffer to receive data into for any subsequent transfers.

  • rx_buf_ – The length in bytes of rx_buf. If the master transfers more than this during a single transfer, then the bytes that do not fit within rx_buf will be lost.

  • tx_buf – The buffer to send data from for any subsequent transfers.

  • tx_buf_len – The length in bytes of tx_buf. If the master transfers more than this during a single transfer, zeros will be sent following the last byte tx_buf.

int spi_slave_xfer_complete(rtos_spi_slave_t *ctx, void **rx_buf, size_t *rx_len, void **tx_buf, size_t *tx_len, unsigned timeout)#

Waits for a SPI transfer to complete. Returns either when the timeout is reached, or when a transfer completes, whichever comes first. If a transfer does complete, then the buffers and the number of bytes read from or written to them are returned via the parameters.

Note

The duration of this callback will effect the minimum duration between SPI transactions

Parameters:

  • ctx – A pointer to the SPI slave driver instance to use.

  • rx_buf – The receive buffer used for the completed transfer. This is set by the function upon completion of a transfer.

  • rx_len – The number of bytes written to rx_buf. This is set by the function upon completion of a transfer.

  • tx_buf – The transmit buffer used for the completed transfer. This is set by the function upon completion of a transfer.

  • tx_len – The number of bytes sent from tx_buf. This is set by the function upon completion of a transfer.

  • timeout – The number of RTOS ticks to wait before the next transfer is complete. When called from within the “xfer_done” callback, this should be 0.

Return values:

  • 0 – if a transfer completed. All buffers and lengths are set in this case.

  • -1 – if no transfer completed before the timeout expired. No buffers or lengths are returned in this case.

void spi_slave_default_buf_xfer_ended_enable(rtos_spi_slave_t *ctx)#

Sets the driver to use callbacks for all default transactions. This will result in transfers done with the default buffer generating callbacks to the application to xfer_done. This will require default buffer transaction items to be processed with spi_slave_xfer_complete()

Note

This is the default setting

Parameters:

  • ctx – A pointer to the SPI slave driver instance to use.

void spi_slave_default_buf_xfer_ended_disable(rtos_spi_slave_t *ctx)#

Sets the driver to drop all default transactions. This will result in transfers done with the default buffer not generating callbacks to the application to xfer_done. This will also stop default buffer transaction items from being required to be processed with spi_slave_xfer_complete()

Parameters:

  • ctx – A pointer to the SPI slave driver instance to use.

void rtos_spi_slave_start(rtos_spi_slave_t *spi_slave_ctx, void *app_data, rtos_spi_slave_start_cb_t start, rtos_spi_slave_xfer_done_cb_t xfer_done, unsigned interrupt_core_id, unsigned priority)#

Starts an RTOS SPI slave driver instance. This must only be called by the tile that owns the driver instance. It must be called after starting the RTOS from an RTOS thread.

rtos_spi_slave_init() must be called on this SPI slave driver instance prior to calling this.

Parameters:

  • spi_slave_ctx – A pointer to the SPI slave driver instance to start.

  • app_data – A pointer to application specific data to pass to the callback functions.

  • start – The callback function that is called when the driver’s thread starts. This is optional and may be NULL.

  • xfer_done – The callback function that is notified when transfers are complete. This is optional and may be NULL.

  • interrupt_core_id – The ID of the core on which to enable the SPI interrupt. This core should not be shared with threads that disable interrupts for long periods of time, nor enable other interrupts.

  • priority – The priority of the task that gets created by the driver to call the callback functions. If both callback functions are NULL, then this is unused.

void rtos_spi_slave_init(rtos_spi_slave_t *spi_slave_ctx, uint32_t io_core_mask, xclock_t clock_block, int cpol, int cpha, port_t p_sclk, port_t p_mosi, port_t p_miso, port_t p_cs)#

Initializes an RTOS SPI slave driver instance. This must only be called by the tile that owns the driver instance. It should be called before starting the RTOS, and must be called before calling rtos_spi_slave_start().

For timing parameters and maximum clock rate, refer to the underlying HIL IO API.

Parameters:

  • spi_slave_ctx – A pointer to the SPI slave driver instance to initialize.

  • io_core_mask – A bitmask representing the cores on which the low level SPI I/O thread created by the driver is allowed to run. Bit 0 is core 0, bit 1 is core 1, etc.

  • clock_block – The clock block to use for the SPI slave.

  • cpol – The clock polarity to use.

  • cpha – The clock phase to use.

  • p_sclk – The SPI slave’s SCLK port. Must be a 1-bit port.

  • p_mosi – The SPI slave’s MOSI port. Must be a 1-bit port.

  • p_miso – The SPI slave’s MISO port. Must be a 1-bit port.

  • p_cs – The SPI slave’s CS port. Must be a 1-bit port.

RTOS_SPI_SLAVE_CALLBACK_ATTR#

This attribute must be specified on all RTOS SPI slave callback functions provided by the application.

HIL_IO_SPI_SLAVE_HIGH_PRIO#

Set SPI Slave thread to high priority

HIL_IO_SPI_SLAVE_FAST_MODE#

Set SPI Slave thread to run in fast mode

struct xfer_done_queue_item#
#include <rtos_spi_slave.h>

Internally used struct representing an received data packet.

The members in this struct should not be accessed directly.

struct rtos_spi_slave_struct#
#include <rtos_spi_slave.h>

Struct representing an RTOS SPI slave driver instance.

The members in this struct should not be accessed directly.