SPI

SPI bus master driver. More...

Data Structures
struct	ove_spi_cfg
	SPI bus configuration descriptor. More...
struct	ove_spi_cs
	SPI chip-select descriptor. More...
struct	ove_spi_xfer
	SPI transfer segment for multi-segment transactions. More...

Enumerations
enum	ove_spi_mode_t { OVE_SPI_MODE_0 = 0 , OVE_SPI_MODE_1 = 1 , OVE_SPI_MODE_2 = 2 , OVE_SPI_MODE_3 = 3 }
	SPI clock polarity / phase mode. More...
enum	ove_spi_bit_order_t { OVE_SPI_MSB_FIRST = 0 , OVE_SPI_LSB_FIRST = 1 }
	SPI bit order. More...

Functions
int	ove_spi_init (ove_spi_t *spi, ove_spi_storage_t *storage, const struct ove_spi_cfg *cfg)
	Initialise an SPI bus controller with caller-provided storage.
void	ove_spi_deinit (ove_spi_t spi)
	Release an SPI bus handle previously created with ove_spi_init.
int	ove_spi_create (ove_spi_t *spi, const struct ove_spi_cfg *cfg)
	Heap-mode counterpart of ove_spi_init() — allocates storage internally.
void	ove_spi_destroy (ove_spi_t spi)
	Destroy an SPI bus handle previously created with ove_spi_create.
int	ove_spi_transfer (ove_spi_t spi, const struct ove_spi_cs *cs, const void *tx, void *rx, size_t len, uint64_t timeout_ns)
	Full-duplex SPI transfer.
int	ove_spi_write (ove_spi_t spi, const struct ove_spi_cs *cs, const void *data, size_t len, uint64_t timeout_ns)
	Write-only SPI transfer (TX only, ignore RX).
int	ove_spi_read (ove_spi_t spi, const struct ove_spi_cs *cs, void *buf, size_t len, uint64_t timeout_ns)
	Read-only SPI transfer (clock out zeros, capture RX).
int	ove_spi_transfer_seq (ove_spi_t spi, const struct ove_spi_cs *cs, const struct ove_spi_xfer *xfers, unsigned int num_xfers, uint64_t timeout_ns)
	Multi-segment SPI transfer under a single CS assertion.
int	ove_spi_transfer_async (ove_spi_t spi, const struct ove_spi_cs *cs, const void *tx, void *rx, size_t len, ove_dma_complete_cb cb, void *user_data)
	Submit an SPI transfer asynchronously and return immediately.

Detailed Description

SPI bus master driver.

Provides a portable SPI master API with configurable clock, mode, thread-safe bus locking, and software chip-select management via GPIO.

Two allocation strategies are supported:

• _create() / _destroy() — heap-allocated. Available only when OVE_HEAP_SPI is defined (i.e. CONFIG_OVE_ZERO_HEAP is not set).
• _init() / _deinit() — caller-supplied storage. Available in both modes. See OVE_SPI_DEFINE_STATIC for a one-step static helper.

Note

Requires CONFIG_OVE_SPI.

Enumeration Type Documentation

ove_spi_mode_t

enum ove_spi_mode_t

SPI clock polarity / phase mode.

Enumerator
OVE_SPI_MODE_0	CPOL=0, CPHA=0.
OVE_SPI_MODE_1	CPOL=0, CPHA=1.
OVE_SPI_MODE_2	CPOL=1, CPHA=0.
OVE_SPI_MODE_3	CPOL=1, CPHA=1.

ove_spi_bit_order_t

enum ove_spi_bit_order_t

SPI bit order.

Enumerator
OVE_SPI_MSB_FIRST	Most significant bit first (common).
OVE_SPI_LSB_FIRST	Least significant bit first.

Function Documentation

ove_spi_init()

int ove_spi_init	(	ove_spi_t *	spi,
		ove_spi_storage_t *	storage,
		const struct ove_spi_cfg *	cfg
	)

Initialise an SPI bus controller with caller-provided storage.

Parameters

[out]	spi	Receives the initialised handle.
[in]	storage	Statically-allocated SPI storage.
[in]	cfg	Bus configuration (pins, mode, clock rate).

Returns

OVE_OK on success, negative error code on failure.

ove_spi_create()

int ove_spi_create	(	ove_spi_t *	spi,
		const struct ove_spi_cfg *	cfg
	)

Heap-mode counterpart of ove_spi_init() — allocates storage internally.

Parameters

[out]	spi	Receives the initialised handle.
[in]	cfg	Bus configuration.

Returns

OVE_OK on success, negative error code on failure.

ove_spi_transfer()

int ove_spi_transfer	(	ove_spi_t	spi,
		const struct ove_spi_cs *	cs,
		const void *	tx,
		void *	rx,
		size_t	len,
		uint64_t	timeout_ns
	)

Full-duplex SPI transfer.

Simultaneously transmits from tx and receives into rx. Either tx or rx may be NULL for half-duplex operation. CS is asserted before and deasserted after the transfer.

Parameters

[in]	spi	SPI handle.
[in]	cs	Chip-select descriptor, or NULL to skip CS.
[in]	tx	Transmit buffer, or NULL.
[out]	rx	Receive buffer, or NULL.
[in]	len	Number of bytes to transfer.
[in]	timeout_ns	Maximum wait time.

Returns

OVE_OK on success, negative error code on failure.

ove_spi_write()

int ove_spi_write	(	ove_spi_t	spi,
		const struct ove_spi_cs *	cs,
		const void *	data,
		size_t	len,
		uint64_t	timeout_ns
	)

Write-only SPI transfer (TX only, ignore RX).

Parameters

[in]	spi	SPI handle.
[in]	cs	Chip-select descriptor, or NULL.
[in]	data	Data to transmit.
[in]	len	Number of bytes.
[in]	timeout_ns	Maximum wait time.

Returns

OVE_OK on success, negative error code on failure.

ove_spi_read()

int ove_spi_read	(	ove_spi_t	spi,
		const struct ove_spi_cs *	cs,
		void *	buf,
		size_t	len,
		uint64_t	timeout_ns
	)

Read-only SPI transfer (clock out zeros, capture RX).

Parameters

[in]	spi	SPI handle.
[in]	cs	Chip-select descriptor, or NULL.
[out]	buf	Buffer to receive data.
[in]	len	Number of bytes.
[in]	timeout_ns	Maximum wait time.

Returns

OVE_OK on success, negative error code on failure.

ove_spi_transfer_seq()

int ove_spi_transfer_seq	(	ove_spi_t	spi,
		const struct ove_spi_cs *	cs,
		const struct ove_spi_xfer *	xfers,
		unsigned int	num_xfers,
		uint64_t	timeout_ns
	)

Multi-segment SPI transfer under a single CS assertion.

Executes num_xfers transfer segments sequentially without releasing CS between them. Useful for protocols that require command + address + data in one transaction.

Parameters

[in]	spi	SPI handle.
[in]	cs	Chip-select descriptor, or NULL.
[in]	xfers	Array of transfer segments.
[in]	num_xfers	Number of segments.
[in]	timeout_ns	Maximum wait time for the entire sequence.

Returns

OVE_OK on success, negative error code on failure.

ove_spi_transfer_async()

int ove_spi_transfer_async	(	ove_spi_t	spi,
		const struct ove_spi_cs *	cs,
		const void *	tx,
		void *	rx,
		size_t	len,
		ove_dma_complete_cb	cb,
		void *	user_data
	)

Submit an SPI transfer asynchronously and return immediately.

Initiates a full-duplex transfer (TX from tx, RX into rx; either may be NULL but not both). The call returns OVE_OK as soon as the transfer has been accepted by the backend — completion is signalled via cb.

Completion context is backend-dependent:

• STM32F7 + FreeRTOS: DMA TC ISR (callable from interrupt context).
• Zephyr: poll signal handler (typically a system workqueue thread).
• NuttX / POSIX: a worker thread that runs the blocking transfer and invokes cb on return. No real DMA — provides the async surface for testing.

The callback must be non-blocking and ISR-safe. Higher-level bindings (Rust AsyncSpi) wrap this with AtomicWaker.

Parameters

[in]	spi	SPI handle.
[in]	cs	Chip-select descriptor, or NULL.
[in]	tx	Transmit buffer, or NULL. Must outlive the transfer.
[in]	rx	Receive buffer, or NULL. Must outlive the transfer.
[in]	len	Number of bytes to transfer.
[in]	cb	Completion callback. Must not be NULL.
[in]	user_data	Opaque pointer forwarded to cb.

Returns

OVE_OK if accepted (transfer in flight; callback will fire), negative error code if the submission itself failed (the callback will NOT fire in this case).