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().

Parameters

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

  • 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.

Parameters

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

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

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.

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.

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.

Returns

  • 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 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.

  • 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().

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.

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.