XCORE SDK
XCORE Software Development Kit
Classes | Macros | Typedefs | Functions
rtos_spi_slave_driver

Classes

struct  rtos_spi_slave_struct
 

Macros

#define RTOS_SPI_SLAVE_CALLBACK_ATTR   __attribute__((fptrgroup("rtos_spi_slave_cb_fptr_grp")))
 

Typedefs

typedef struct rtos_spi_slave_struct rtos_spi_slave_t
 
typedef void(* rtos_spi_slave_start_cb_t) (rtos_spi_slave_t *ctx, void *app_data)
 
typedef void(* rtos_spi_slave_xfer_done_cb_t) (rtos_spi_slave_t *ctx, void *app_data)
 

Functions

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

Detailed Description

The public API for using the RTOS SPI slave driver.

Macro Definition Documentation

◆ RTOS_SPI_SLAVE_CALLBACK_ATTR

#define RTOS_SPI_SLAVE_CALLBACK_ATTR   __attribute__((fptrgroup("rtos_spi_slave_cb_fptr_grp")))

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

Typedef Documentation

◆ rtos_spi_slave_start_cb_t

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
ctxA pointer to the associated SPI slave driver instance.
app_dataA pointer to application specific data provided by the application. Used to share data between this callback function and the application.

◆ rtos_spi_slave_t

Typedef to the RTOS SPI slave driver instance struct.

◆ rtos_spi_slave_xfer_done_cb_t

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
ctxA pointer to the associated SPI slave driver instance.
app_dataA pointer to application specific data provided by the application. Used to share data between this callback function and the application.

Function Documentation

◆ rtos_spi_slave_init()

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_ctxA pointer to the SPI slave driver instance to initialize.
io_core_maskA 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_blockThe clock block to use for the SPI slave.
cpolThe clock polarity to use.
cphaThe clock phase to use.
p_sclkThe SPI slave's SCLK port. Must be a 1-bit port.
p_mosiThe SPI slave's MOSI port. Must be a 1-bit port.
p_misoThe SPI slave's MISO port. Must be a 1-bit port.
p_csThe SPI slave's CS port. Must be a 1-bit port.

◆ rtos_spi_slave_start()

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_ctxA pointer to the SPI slave driver instance to start.
app_dataA pointer to application specific data to pass to the callback functions.
startThe callback function that is called when the driver's thread starts. This is optional and may be NULL.
xfer_doneThe callback function that is notified when transfers are complete. This is optional and may be NULL.
interrupt_core_idThe ID of the core on which to enable the SPI interrupt.
priorityThe 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.

◆ spi_slave_xfer_complete()

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
ctxA pointer to the SPI slave driver instance to use.
rx_bufThe receive buffer used for the completed transfer. This is set by the function upon completion of a transfer.
rx_lenThe number of bytes written to rx_buf. This is set by the function upon completion of a transfer.
tx_bufThe transmit buffer used for the completed transfer. This is set by the function upon completion of a transfer.
tx_lenThe number of bytes sent from tx_buf. This is set by the function upon completion of a transfer.
timeoutThe 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
0if a transfer completed. All buffers and lengths are set in this case.
-1if no transfer completed before the timeout expired. No buffers or lengths are returned in this case.

◆ spi_slave_xfer_prepare()

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
ctxA pointer to the SPI slave driver instance to use.
rx_bufThe 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_bufThe buffer to send data from for any subsequent transfers.
tx_buf_lenThe 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.