Common mistakes

Informative

Pitfalls when using the SPI driver, and how to avoid them. Each maps to a rule in Spi — Requirements or an error in Errors.

  • Passing a real pointer to Spi_Init. configPtr MUST be NULL_PTR — a non-null pointer raises SPI_DEVERR_PARAM_POINTER (CHI-SPI-MUST-09). The configuration is selected at build time.

  • Modifying or freeing the buffer too early. The TX/RX buffer sets and their data must stay valid and unmodified from Spi_StartTransaction until Spi_Callout_OnTransactionEnd fires (CHI-SPI-MUST-13). The driver does not copy them.

  • Inconsistent TX/RX lengths. The total transfer length across txBuffSetPtr and rxBuffSetPtr must match; a mismatch raises SPI_DEVERR_PARAM_LENGTH (CHI-SPI-MUST-20).

  • Forgetting to stage a target response. A target only transfers data you staged with Spi_StartTransaction before the controller selects it; otherwise it sends default_data and ignores what it receives, still firing Spi_Callout_OnTransactionEnd with length = 0 (CHI-SPI-MUST-15).

  • Expecting Spi_CancelTransaction to abort a live transfer. It only cancels a staged target transaction that has not started on the bus; once transferring it returns E_NOT_OK (CHI-SPI-MUST-17). To stop a live transfer, use Spi_DeInit.

  • Driving the CS pin twice. With cs_ctrl: ViaGPIO the driver calls Spi_Callout_CsControl and the integration code owns the pin; with ViaHW the hardware owns it. Do not toggle CS from both (CHI-SPI-MUST-16).

  • Forgetting to service polled events. If a channel is configured for Polling you must call Spi_PollFunction cyclically, or no transfer progresses and no callout fires (CHI-SPI-MAY-01).

  • Using Spi_OnCs when the hardware detects CS. Spi_OnCs is only for target channels whose hardware cannot detect chip-select deactivation (CHI-SPI-SHOULD-01).

  • Calling Spi_DeInit mid-transaction. It aborts immediately and can leave a target in an undefined state; call it when the channel is SPI_CH_STATE_IDLE (CHI-SPI-MUST-10).