Controller transactions

Informative

How a controller-mode channel transfers data on the bus. Binding rules: CHI-SPI-MUST-01, CHI-SPI-MUST-11…CHI-SPI-MUST-14, and CHI-SPI-MUST-16 in Spi — Requirements.

Full-duplex transfer

A controller transaction is full-duplex: you provide a TX buffer set, an RX buffer set, or both. Supply NULL_PTR for a direction you do not need — a null RX set discards the received data; a TX chunk with a null bufferDataPtr sends the configured default_data.

static uint8 cmd[1]   = { 0x9Fu };            /* e.g. a read-id command */
static uint8 resp[3];

static Spi_BufferType txChunks[1] = { { cmd, 1u } };
static Spi_BufferType rxChunks[1] = { { resp, 3u } };
static Spi_BufferSetType txSet = { txChunks, 1u };
static Spi_BufferSetType rxSet = { rxChunks, 1u };

/* transfer on channel 0, chip select 0 */
Spi_StartTransaction(0u, 0u, &txSet, &rxSet);

The call starts a transaction on an IDLE channel (moving it to BUSY) and returns immediately; the transfer completes asynchronously. Keep the buffer sets and their data valid until the completion callout fires.

Completion

void Spi_Callout_OnTransactionEnd(uint8 channelId, uint8 csId, uint16 length)
{
    /* the transaction finished; `length` elements were transferred */
}

Chip-select control (GPIO)

When a device is configured with cs_ctrl: ViaGPIO, the driver does not touch the CS pin. It asks the integration code to toggle it, just before the transfer and at the end:

void Spi_Callout_CsControl(uint8 channelId, uint8 csId, boolean status)
{
    /* status == TRUE  -> assert the CS line for (channelId, csId)
       status == FALSE -> release it */
}

With cs_ctrl: ViaHW the SPI hardware drives CS and this callout is not used.

Bus errors

A bus error detected during a transfer is reported through LogM_Report at runtime-error level with a vendor-specific SPI_RTERR_* code (CHI-SPI-MUST-18); errors not tied to a specific chip select carry SPI_CS_UNSPECIFIED.