Spi — Requirements

Normative

Defines what a conformant SPI driver MUST do. Keywords per Requirement Keywords; conformance per Conformance. Requirements do not carry individual status — the set-level status applies to all of them. Signatures, error codes, and configuration properties are in the API Reference, Errors, and Configuration Reference pages. Cross-module rules (types, error model, naming, memory mapping) are in General.

Mandatory (MUST) - 23 Requirements

The conformance contract — an implementation MUST satisfy every requirement here.

Modes and event handling

CHI-SPI-MUST-01 — Controller mode

The driver MUST support operating a channel as an SPI controller, initiating a full-duplex transaction to a chip-select-addressed device and driving the chip select.

CHI-SPI-MUST-02 — Target mode

The driver MUST support operating a channel as an SPI target, responding to a controller that selects it, using data staged by the integration code (or default_data when none is staged).

CHI-SPI-MUST-03 — Event handling mode

For each channel, event handling MUST be statically configurable as interrupt or polling. In interrupt mode Spi_Init MUST enable the interrupt and Spi_Interrupt MUST service it; in polling mode Spi_PollFunction MUST service events.

State machine

CHI-SPI-MUST-04 — State after reset

After reset the driver MUST be in SPI_DRV_STATE_UNINIT with every channel in SPI_CH_STATE_UNINIT.

CHI-SPI-MUST-05 — State after initialization

Spi_Init MUST move the driver to SPI_DRV_STATE_INIT and every channel to SPI_CH_STATE_IDLE.

CHI-SPI-MUST-06 — State after de-initialization

Spi_DeInit MUST abort any ongoing transaction and return the driver (and its channels) to SPI_DRV_STATE_UNINIT.

CHI-SPI-MUST-07 — Controller channel state transitions

A controller channel MUST follow the controller-mode state machine in Concepts: IDLE → BUSY on Spi_StartTransaction; BUSY → IDLE when the whole buffer set has been transferred, evaluated in Spi_Interrupt / Spi_PollFunction before Spi_Callout_OnTransactionEnd.

CHI-SPI-MUST-08 — Target channel state transitions

A target channel MUST follow the target-mode state machine: IDLE → READY when Spi_StartTransaction stages a buffer; READY → IDLE on Spi_CancelTransaction; IDLE/READY → BUSY on chip-select activation; BUSY → IDLE on chip-select deactivation before Spi_Callout_OnTransactionEnd. Where the hardware raises no CS-activation interrupt, the state MUST be evaluated from the hardware status when an API is called.

Initialization and shutdown

CHI-SPI-MUST-09 — Initialization

Spi_Init MUST initialize driver state and the hardware per the configuration. configPtr MUST be NULL_PTR. A target channel MUST begin detecting chip-select activation.

CHI-SPI-MUST-10 — De-initialization

Spi_DeInit MUST immediately stop any ongoing transfer and de-initialize the hardware.

Transactions

CHI-SPI-MUST-11 — Start a transaction

Spi_StartTransaction MUST, on a controller channel, initiate the transfer with the given buffer sets and the addressed chip select; on a target channel it MUST stage the buffer sets for the next controller-initiated transaction (with csId == SPI_CS_UNSPECIFIED). It is non-blocking and MUST return immediately after initiating (controller) or staging (target).

CHI-SPI-MUST-12 — Buffer-set model

A transaction MUST transfer a buffer set (Spi_BufferSetType) — an array of Spi_BufferType chunks — within one chip-select sequence. The driver MUST cast element size from Spi_BufferDataType to the configured data_width (uint16 for 9–16 bits, uint32 for 17–32 bits). A null bufferDataPtr MUST send default_data on TX and discard received data on RX. In target mode, a request longer than the staged TX buffer MUST send default_data for the excess, and one longer than the RX buffer MUST ignore the excess.

CHI-SPI-MUST-13 — Data transfer and consistency

During interrupt or poll handling the driver MUST transfer the elements to/from the buffer sets supplied to Spi_StartTransaction. The caller’s buffer sets and TX data MUST remain valid and unmodified until the matching Spi_Callout_OnTransactionEnd fires; the driver MUST NOT rely on them afterwards.

CHI-SPI-MUST-14 — Controller completion and notification

On transferring the whole buffer set on a controller channel the driver MUST move the channel to IDLE and call Spi_Callout_OnTransactionEnd with the total transferred length. For a GPIO-controlled chip select it MUST call Spi_Callout_CsControl(..., FALSE) before the completion callout.

CHI-SPI-MUST-15 — Target completion and notification

On detecting chip-select deactivation the driver MUST move the target channel to IDLE and call Spi_Callout_OnTransactionEnd with the total transferred length. If no buffer was staged before the transaction, the driver MUST send nothing and ignore received data, and MUST still call Spi_Callout_OnTransactionEnd with length = 0.

Chip-select control

CHI-SPI-MUST-16 — GPIO chip-select control

Where a controller’s chip select is configured as GPIO control, the driver MUST call Spi_Callout_CsControl with status = TRUE just before starting the transfer and status = FALSE when deactivation is required, and MUST NOT drive the chip-select pin itself. Where it is configured as hardware control, the driver MUST NOT call Spi_Callout_CsControl.

Cancellation

CHI-SPI-MUST-17 — Cancel a staged transaction

Spi_CancelTransaction (target mode) MUST cancel a transaction staged by Spi_StartTransaction that has not yet started on the bus, returning E_OK (including when nothing was staged). If the transaction has already started it MUST NOT cancel it and MUST return E_NOT_OK.

Errors, status, and scheduling

CHI-SPI-MUST-18 — Bus error handling

On an SPI bus error the driver MUST report it via LogM_Report at runtime-error level with a SPI_RTERR / SPI_RTERR_<VENDOR_SPECIFIC> code (CHI-GEN-MUST-10). A failure not tied to a chip select MUST use SPI_CS_UNSPECIFIED as the csId.

CHI-SPI-MUST-19 — Channel state query

Spi_GetChannelState MUST return the current state of the requested channel.

CHI-SPI-MUST-20 — Development error detection

When development error reporting is enabled, each API MUST detect the conditions listed in Errors and report them via LogM_Report (CHI-GEN-MUST-10).

Types, callouts, and configuration

CHI-SPI-MUST-21 — Callout notifications

The driver MUST call Spi_Callout_OnTransactionEnd (and, for GPIO chip selects, Spi_Callout_CsControl) with the parameters and at the points defined in API Reference.

CHI-SPI-MUST-22 — Public types and error identifiers

The driver MUST provide Spi_ConfigType, Spi_BufferDataType, Spi_BufferType, Spi_BufferSetType, Spi_ChannelStateType, the development and runtime error identifiers, and SPI_CS_UNSPECIFIED as defined in API Reference, and MUST use the shared type system from General (CHI-GEN-MUST-09). The total TX/RX transfer length supplied to Spi_StartTransaction MUST be consistent.

CHI-SPI-MUST-23 — Configuration model

The driver MUST support the configuration model in Configuration Reference — a General section and a ConfigSet with ControllerChannel and TargetChannel entries (with their device configurations) — following the common model in General (CHI-GEN-MUST-12).

Recommended (SHOULD) - 1 Requirement

Chip-select detection

CHI-SPI-SHOULD-01 — Chip-select detection service

Where a target channel’s hardware cannot detect chip-select control, the driver SHOULD provide Spi_OnCs so the integration code can notify chip-select edges. On deactivation (status = FALSE) it MUST complete the transaction — ensuring received data has been copied to the RX buffer — and call Spi_Callout_OnTransactionEnd. Deactivation notification is mandatory when the interface is used; activation notification is optional.

Optional (MAY) - 1 Requirement

Polling

CHI-SPI-MAY-01 — Poll function

The driver MAY provide Spi_PollFunction, which MUST offer the same functionality as Spi_Interrupt by polling the hardware instead of servicing an interrupt. It is appropriate where the poll cycle is fast enough or transfers are handled by DMA.