API Reference

Normative

The SPI driver API contract. A conformant driver MUST provide these types and functions with the behavior described. Function and type signatures are extracted from the driver headers with Doxygen/Breathe; only the interrupt handler is hand-framed, because its name is vendor-specific. Keywords per Requirement Keywords; behavioral rules in Spi — Requirements; error codes in Errors.

Data types at a glance

Type	Kind	Purpose
Spi_ConfigType	struct	Root configuration structure (build-time; `Spi_Init` takes `NULL_PTR`).
Spi_BufferDataType	typedef	Element type of an application data buffer.
Spi_BufferType	struct	One chunk of a TX/RX buffer (pointer + length).
Spi_BufferSetType	struct	A set of buffer chunks transferred in one chip-select sequence.
Spi_ChannelStateType	enum	Channel state (UNINIT / IDLE / READY / BUSY).

API at a glance

Function	Group	Purpose
Spi_Init	Initialization and shutdown	Initialize the driver and every channel.
Spi_DeInit	Initialization and shutdown	Abort transfers and de-initialize the driver.
Spi_StartTransaction	Transactions	Start (controller) or stage (target) a buffer-set transfer.
Spi_CancelTransaction	Transactions	Cancel a staged (not-yet-started) target transaction.
Spi_OnCs	Transactions	Target CS notification when the hardware cannot detect it.
Spi_GetChannelState	Status and scheduling	Read a channel’s current state.
Spi_PollFunction	Status and scheduling	Service events for polled channels.
Spi_Interrupt	Status and scheduling	Driver interrupt service routine.

Callouts and expected interfaces at a glance

The functions the integrator MUST provide (CHI-SPI-MUST-21); see the Callouts group below. SpiDrv has no upper-layer interface stack, so it reports its events through callouts that the integrator implements in the generated Spi_Callout_Stubs.c (see The Callout Stub File).

Function	Kind	Purpose
Spi_Callout_OnTransactionEnd	Callout	A transaction completed; reports the transferred length.
Spi_Callout_CsControl	Callout	Requests GPIO chip-select assert/release from the integration code.
LogM_Report	Common	Reports development / runtime errors with a log level.
`<Mip>_EnterCriticalSection` / `<Mip>_ExitCriticalSection`	Common (optional)	Bracket sections requiring exclusive access — see critical sections.

Transactions

Spi_StartTransaction

Std_ReturnType Spi_StartTransaction(uint8 channelId, uint8 csId, const Spi_BufferSetType *txBuffSetPtr, Spi_BufferSetType *rxBuffSetPtr)

This service starts transaction. If the channel is in controller mode, this function initiates the transaction. This function is non-blocking and returns immediately after initiating the transfer. If the channel is in Target Mode, this function will provide TX/RX buffers to the HW that are used for the next transaction.

Sync/Async:

Asynchronous

Reentrancy:

Conditionally reentrant (reentrant when called with different channelId)

Service ID [hex]:

0x02

Development error(s):

SPI_DEVERR_UNINIT SpiDrv state is SPI_DRV_STATE_UNINIT.
SPI_DEVERR_PARAM_CHANNELID channelId is out of range.
SPI_DEVERR_PARAM_CS csId is out of range.
SPI_DEVERR_PARAM_LENGTH Total transfer length in txBuffSetPtr and rxBuffSetPtr is inconsistent.
SPI_DEVERR_INVALID_CH_STATE Called when the channel state is NOT SPI_CH_STATE_IDLE.

Parameters:

channelId – [in] ID of the SPI channel to be addressed.
csId – [in] chip select ID in the channel. SPI_CS_UNSPECIFIED shall be set when the channel is Target Mode. Note: If the channel is Target Node, SpiDrv must not check the csId parameter. Even if the csId is not SPI_CS_UNSPECIFIED, SpiDrv must not log the development error
txBuffSetPtr – [in] Pointer to a buffer set to be transferred.
rxBuffSetPtr – [out] Pointer to a buffer set to fill with received data.

Return values:

E_OK – Start transaction has been accepted
E_NOT_OK – Development error occurred

Returns:

Std_ReturnType.

When to call: on an IDLE controller channel to start a transfer (with the target’s csId), or on a target channel to stage the next transfer (with SPI_CS_UNSPECIFIED). Returns: E_OK if accepted, else E_NOT_OK (development error). The caller MUST keep the buffer sets valid until Spi_Callout_OnTransactionEnd. A TX chunk with a null bufferDataPtr sends default_data; a null RX pointer discards the received data. Errors: see Errors. Available via: Spi.h

Spi_CancelTransaction

Std_ReturnType Spi_CancelTransaction(uint8 channelId)

This interface is Target Mode only. Cancel transaction set by Spi_StartTransaction. Cancellation does not mean canceling on-going transaction. This interface just cancel the transaction setup not yet transferred to the bus.

Sync/Async:

Synchronous

Reentrancy:

Conditionally reentrant (reentrant when called with different channelId)

Service ID [hex]:

0x08

Development error(s):

SPI_DEVERR_UNINIT Called when the internal state is SPI_CH_STATE_UNINIT
SPI_DEVERR_PARAM_CHANNELID channelId is out of range from configured channelIds.

Parameters:

channelId – [in] ID of the SPI channel to be addressed.

Return values:

E_OK – Request has been accepted, including no transaction setup to be cancelled.
E_NOT_OK – Development error occurred or request has not been accepted due to the transaction is already started.

When to call: on a target channel to cancel a staged transaction that has not started on the bus. Returns: E_OK if accepted (including when nothing was staged); E_NOT_OK if the transaction has already started. Errors: see Errors. Available via: Spi.h

Spi_OnCs

void Spi_OnCs(uint8 channelId, uint8 csId, boolean status)

Target Mode only and optional interface if the SPI HW cannot detect CS control. This service is a callback notification that is triggered by CS edge detection in the integration code. FALSE (deactivation) is mandatory if this interface is used. TRUE (activation) is optional if required.

Sync/Async:

Synchronous

Reentrancy:

Conditionally reentrant (reentrant when called with different channelId)

Service ID [hex]:

0x05

Development error(s):

SPI_DEVERR_PARAM_CHANNELID channelId is out of range from configured channelIds.
SPI_DEVERR_PARAM_CS csId is out of range.
SPI_DEVERR_UNINIT Called when the internal state is SPI_CH_STATE_UNINIT

Parameters:

channelId – [in] ID of the SPI channel to be addressed.
csId – [in] CS ID in the channel.
status – [in] status of the chip select, TRUE: CS activated, FALSE: CS deactivated

Returns:

None.

When to call: target mode only, from the integration code (typically a GPIO edge interrupt) when the SPI hardware cannot detect chip-select control. FALSE (deactivation) is mandatory; TRUE (activation) is optional. On deactivation the driver completes the transaction and calls Spi_Callout_OnTransactionEnd. Errors: see Errors. Available via: Spi.h