SPI Master RTOS Driver

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

SPI Master Initialization API

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

typedef struct rtos_spi_master_struct rtos_spi_master_t

Typedef to the RTOS SPI master driver instance struct.

typedef struct rtos_spi_master_device_struct rtos_spi_master_device_t

Typedef to the RTOS SPI device instance struct.

void rtos_spi_master_start(rtos_spi_master_t *spi_master_ctx, unsigned priority)

Starts an RTOS SPI master driver instance. This must only be called by the tile that owns the driver instance. It may be called either before or after starting the RTOS, but must be called before any of the core SPI master driver functions are called with this instance.

rtos_spi_master_init() must be called on this SPI master driver instance prior to calling this.

Parameters

  • spi_master_ctx – A pointer to the SPI master driver instance to start.

  • priority – The priority of the task that gets created by the driver to handle the SPI master interface.

void rtos_spi_master_init(rtos_spi_master_t *bus_ctx, xclock_t clock_block, port_t cs_port, port_t sclk_port, port_t mosi_port, port_t miso_port)

Initializes an RTOS SPI master driver instance. This must only be called by the tile that owns the driver instance. It may be called either before or after starting the RTOS, but must be called before calling rtos_spi_master_start() or any of the core SPI master driver functions with this instance.

Parameters

  • bus_ctx – A pointer to the SPI master driver instance to initialize.

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

  • cs_port – The SPI interface’s chip select port. This may be a multi-bit port.

  • sclk_port – The SPI interface’s SCLK port. Must be a 1-bit port.

  • mosi_port – The SPI interface’s MOSI port. Must be a 1-bit port.

  • miso_port – The SPI interface’s MISO port. Must be a 1-bit port.

void rtos_spi_master_device_init(rtos_spi_master_device_t *dev_ctx, rtos_spi_master_t *bus_ctx, uint32_t cs_pin, int cpol, int cpha, spi_master_source_clock_t source_clock, uint32_t clock_divisor, spi_master_sample_delay_t miso_sample_delay, uint32_t miso_pad_delay, uint32_t cs_to_clk_delay_ticks, uint32_t clk_to_cs_delay_ticks, uint32_t cs_to_cs_delay_ticks)

Initialize a SPI device. Multiple SPI devices may be initialized per RTOS SPI master driver instance. Each must be on a unique pin of the interface’s chip select port. This must only be called by the tile that owns the driver instance. It may be called either before or after starting the RTOS, but must be called before calling rtos_spi_master_start() or any of the core SPI master driver functions with this instance.

Parameters

  • dev_ctx – A pointer to the SPI device instance to initialize.

  • bus_ctx – A pointer to the SPI master driver instance to attach the device to.

  • cs_pin – The bit number of the chip select port that is connected to the device’s chip select pin.

  • cpol – The clock polarity required by the device.

  • cpha – The clock phase required by the device.

  • source_clock – The source clock to derive SCLK from. See spi_master_source_clock_t.

  • clock_divisor – The value to divide the source clock by. The frequency of SCLK will be set to:

    • (F_src) / (4 * clock_divisor) when clock_divisor > 0

    • (F_src) / (2) when clock_divisor = 0 Where F_src is the frequency of the source clock.

  • miso_sample_delay – When to sample MISO. See spi_master_sample_delay_t.

  • miso_pad_delay – The number of core clock cycles to delay sampling the MISO pad during a transaction. This allows for more fine grained adjustment of sampling time. The value may be between 0 and 5.

  • cs_to_clk_delay_ticks – The minimum number of reference clock ticks between assertion of chip select and the first clock edge.

  • clk_to_cs_delay_ticks – The minimum number of reference clock ticks between the last clock edge and de-assertion of chip select.

  • cs_to_cs_delay_ticks – The minimum number of reference clock ticks between transactions, which is between de-assertion of chip select and the end of one transaction, and its re-assertion at the beginning of the next.

struct rtos_spi_master_struct
#include <rtos_spi_master.h>

Struct representing an RTOS SPI master driver instance.

The members in this struct should not be accessed directly.

struct rtos_spi_master_device_struct
#include <rtos_spi_master.h>

Struct representing an RTOS SPI device instance.

The members in this struct should not be accessed directly.

SPI Master Core API

The following functions are the core SPI master driver functions that are used after it has been initialized and started.

inline void rtos_spi_master_transaction_start(rtos_spi_master_device_t *ctx)

Starts a transaction with the specified SPI device on a SPI bus. This leaves chip select asserted.

Parameters

ctx – A pointer to the SPI device instance.

inline void rtos_spi_master_transfer(rtos_spi_master_device_t *ctx, uint8_t *data_out, uint8_t *data_in, size_t len)

Transfers data to and from the specified SPI device on a SPI bus. The transaction must already have been started by calling rtos_spi_master_transaction_start() on the same device instance. This may be called multiple times during a single transaction.

This function may return before the transfer is complete when data_in is NULL, as the actual transfer operation is queued and executed by a thread created by the driver.

Parameters

  • ctx – A pointer to the SPI device instance.

  • data_out – Pointer to the data to transfer to the device. This may be NULL if there is no data to send.

  • data_in – Pointer to the buffer to save the received data to. This may be NULL if the received data is not needed.

  • len – The number of bytes to transfer in each direction. This number of bytes must be available in both the data_out and data_in buffers if they are not NULL.

inline void rtos_spi_master_delay_before_next_transfer(rtos_spi_master_device_t *ctx, uint32_t delay_ticks)

If there is a minimum amount of idle time that is required by the device between transfers within a single transaction, then this may be called between each transfer where a delay is required.

This function will return immediately. If the call for the next transfer happens before the minimum time specified has elapsed, the delay will occur then before the transfer begins.

Note

This must be called during a transaction, otherwise the behavior is unspecified.

Note

Technically the next transfer will occur no earlier than delay_ticks after this function is called, so this should be called immediately following a transfer, rather than immediately before the next.

Parameters

  • ctx – A pointer to the SPI device instance.

  • delay_ticks – The number of reference clock ticks to delay.

inline void rtos_spi_master_transaction_end(rtos_spi_master_device_t *ctx)

Ends a transaction with the specified SPI device on a SPI bus. This leaves chip select de-asserted.

Parameters

ctx – A pointer to the SPI device instance.

SPI Master RPC Initialization API

The following functions may be used to share a SPI master driver instance with other xcore tiles. Tiles that the driver instance is shared with may call any of the core functions listed above.

void rtos_spi_master_rpc_client_init(rtos_spi_master_t *spi_master_ctx, rtos_spi_master_device_t *spi_device_ctx[], size_t spi_device_count, rtos_driver_rpc_t *rpc_config, rtos_intertile_t *host_intertile_ctx)

Initializes an RTOS SPI master driver instance on a client tile, as well as any number of SPI device instances. This allows a tile that does not own the actual driver instance to use a driver instance on another tile. This will be called instead of rtos_spi_master_init() and rtos_spi_master_device_init(). The host tile that owns the actual instances must simultaneously call rtos_spi_master_rpc_host_init().

Parameters

  • spi_master_ctx – A pointer to the SPI master driver instance to initialize.

  • spi_device_ctx – An array of pointers to SPI device instances to initialize.

  • spi_device_count – The number of SPI device instances to initialize.

  • rpc_config – A pointer to an RPC config struct. This must have the same scope as spi_master_ctx.

  • host_intertile_ctx – A pointer to the intertile driver instance to use for performing the communication between the client and host tiles. This must have the same scope as spi_master_ctx.

void rtos_spi_master_rpc_host_init(rtos_spi_master_t *spi_master_ctx, rtos_spi_master_device_t *spi_device_ctx[], size_t spi_device_count, rtos_driver_rpc_t *rpc_config, rtos_intertile_t *client_intertile_ctx[], size_t remote_client_count)

Performs additional initialization on a SPI master driver instance to allow client tiles to use the SPI master driver instance. Each client tile that will use this instance must simultaneously call rtos_spi_master_rpc_client_init().

Parameters

  • spi_master_ctx – A pointer to the SPI master driver instance to share with clients.

  • spi_device_ctx – An array of pointers to SPI device instances to share with clients.

  • spi_device_count – The number of SPI device instances to share.

  • rpc_config – A pointer to an RPC config struct. This must have the same scope as spi_master_ctx.

  • client_intertile_ctx – An array of pointers to the intertile driver instances to use for performing the communication between the host tile and each client tile. This must have the same scope as spi_master_ctx.

  • remote_client_count – The number of client tiles to share this driver instance with.

void rtos_spi_master_rpc_config(rtos_spi_master_t *spi_master_ctx, unsigned intertile_port, unsigned host_task_priority)

Configures the RPC for a SPI master driver instance. This must be called by both the host tile and all client tiles.

On the client tiles this must be called after calling rtos_spi_master_rpc_client_init(). After calling this, the client tile may immediately begin to call the core SPI master functions on this driver instance. It does not need to wait for the host to call rtos_spi_master_start().

On the host tile this must be called both after calling rtos_spi_master_rpc_host_init() and before calling rtos_spi_master_start().

Parameters

  • spi_master_ctx – A pointer to the SPI master driver instance to configure the RPC for.

  • intertile_port – The port number on the intertile channel to use for transferring the RPC requests and responses for this driver instance. This port must not be shared by any other functions. The port must be the same for the host and all its clients.

  • host_task_priority – The priority to use for the task on the host tile that handles RPC requests from the clients.