spi.h File Reference

The one owner of the shared SPI bus for the peripheral drivers. More...

#include "config/platform/platform.h"
#include "protocore_config.h"

Go to the source code of this file.

Macros
#define	PROTOCORE_SPI_HZ   1000000u
	Bus clock for the shared peripheral bus; 1 MHz is safe on every part on it.
#define	PROTOCORE_SPI_MODE   0u
	Clock polarity and phase, as SPI mode 0..3. Mode 0 is what these parts use.
#define	PROTOCORE_SPI_HOST   0u
	Controller the plain verbs drive.
#define	PROTOCORE_SPI_QUADWP_PIN   (-1)
	Third and fourth data lines, for a quad-width bus; -1 leaves the bus single or dual.
#define	PROTOCORE_SPI_QUADHD_PIN   (-1)

Functions
PROTOCORE_BEGIN_DECLS PROTOCORE_INLINE proto_bool	protocore_spi_begin_on (uint8_t host, int mosi, int miso, int sclk, int quadwp, int quadhd)
PROTOCORE_INLINE proto_bool	protocore_spi_begin (void)
PROTOCORE_INLINE proto_bool	protocore_spi_txn_on (uint8_t host, uint32_t hz, uint8_t bit_order, uint8_t mode, const uint8_t *tx, uint8_t *rx, size_t len)
PROTOCORE_INLINE proto_bool	protocore_spi_txn_at (uint32_t hz, uint8_t bit_order, uint8_t mode, const uint8_t *tx, uint8_t *rx, size_t len)
PROTOCORE_INLINE proto_bool	protocore_spi_txn (const uint8_t *tx, uint8_t *rx, size_t len)
PROTOCORE_INLINE proto_bool	protocore_spi_write (const uint8_t *tx, size_t len)
PROTOCORE_INLINE proto_bool	protocore_spi_read (uint8_t *rx, size_t len)
PROTOCORE_INLINE proto_bool	protocore_spi_txn_ext_on (uint8_t host, uint32_t hz, uint8_t bit_order, uint8_t mode, uint16_t cmd, uint8_t cmd_bits, uint32_t addr, uint8_t addr_bits, uint8_t dummy_bits, uint8_t lanes, const uint8_t *tx, uint8_t *rx, size_t len)
PROTOCORE_INLINE proto_bool	protocore_spi_txn_ext (uint16_t cmd, uint8_t cmd_bits, uint32_t addr, uint8_t addr_bits, uint8_t dummy_bits, uint8_t lanes, const uint8_t *tx, uint8_t *rx, size_t len)
PROTOCORE_INLINE void	protocore_spi_cs_idle (uint8_t pin)
PROTOCORE_INLINE void	protocore_spi_cs_select (uint8_t pin)
PROTOCORE_INLINE void	protocore_spi_cs_release (uint8_t pin)

Detailed Description

The one owner of the shared SPI bus for the peripheral drivers.

The sibling of i2c.h, for the drivers whose part is on SPI rather than I2C (the interface bridge, the W5500 Ethernet, the radio modules). They share one bus and bring it up through these verbs. The pins come from PROTOCORE_SPI_MOSI_PIN / PROTOCORE_SPI_MISO_PIN / PROTOCORE_SPI_SCLK_PIN (default -1 = the platform's default host pins). Re-begin is idempotent, so per-driver calls are harmless.

SPI is symmetric: every clock shifts a bit out and a bit in, so one transfer verb covers the three shapes a driver needs. Pass a null rx to discard what comes back (a write), a null tx to clock zeros out (a read), or both to exchange.

protocore_spi_txn runs at the configured clock, bit order and mode; protocore_spi_txn_at names its own, which is what a bus carrying parts with different timing needs.

protocore_spi_txn_ext adds the framing a flash, a display controller or an ADC front end expects: a command, an address, dummy clocks, and a data phase one, two or four bits wide. The controller drives each phase, so the data buffer holds data alone.

Chip select is the caller's: which pin selects a part is a board fact, and a driver often holds it across several transfers. protocore_spi_cs_idle / protocore_spi_cs_select / protocore_spi_cs_release drive it through the GPIO seam.

The bodies compile wherever the platform states a bus.

Author

Douglas Quigg (dstroy0)

Date

2026

Definition in file spi.h.

Macro Definition Documentation

PROTOCORE_SPI_HZ

#define PROTOCORE_SPI_HZ   1000000u

Bus clock for the shared peripheral bus; 1 MHz is safe on every part on it.

Definition at line 44 of file spi.h.

PROTOCORE_SPI_MODE

#define PROTOCORE_SPI_MODE   0u

Clock polarity and phase, as SPI mode 0..3. Mode 0 is what these parts use.

Definition at line 49 of file spi.h.

PROTOCORE_SPI_HOST

#define PROTOCORE_SPI_HOST   0u

Controller the plain verbs drive.

Definition at line 54 of file spi.h.

PROTOCORE_SPI_QUADWP_PIN

#define PROTOCORE_SPI_QUADWP_PIN   (-1)

Third and fourth data lines, for a quad-width bus; -1 leaves the bus single or dual.

Definition at line 59 of file spi.h.

PROTOCORE_SPI_QUADHD_PIN

#define PROTOCORE_SPI_QUADHD_PIN   (-1)

Definition at line 62 of file spi.h.

Function Documentation

protocore_spi_begin_on()

PROTOCORE_BEGIN_DECLS PROTOCORE_INLINE proto_bool protocore_spi_begin_on	(	uint8_t	host,
		int	mosi,
		int	miso,
		int	sclk,
		int	quadwp,
		int	quadhd
	)

Definition at line 168 of file spi.h.

References PROTO_TRUE.

protocore_spi_begin()

PROTOCORE_INLINE proto_bool protocore_spi_begin

(

void

)

Definition at line 179 of file spi.h.

References PROTO_TRUE.

protocore_spi_txn_on()

PROTOCORE_INLINE proto_bool protocore_spi_txn_on	(	uint8_t	host,
		uint32_t	hz,
		uint8_t	bit_order,
		uint8_t	mode,
		const uint8_t *	tx,
		uint8_t *	rx,
		size_t	len
	)

Definition at line 184 of file spi.h.

References PROTO_FALSE.

Referenced by protocore_spi_txn_at().

protocore_spi_txn_at()

PROTOCORE_INLINE proto_bool protocore_spi_txn_at	(	uint32_t	hz,
		uint8_t	bit_order,
		uint8_t	mode,
		const uint8_t *	tx,
		uint8_t *	rx,
		size_t	len
	)

Definition at line 197 of file spi.h.

References PROTOCORE_SPI_HOST, and protocore_spi_txn_on().

Referenced by protocore_spi_txn().

protocore_spi_txn()

PROTOCORE_INLINE proto_bool protocore_spi_txn	(	const uint8_t *	tx,
		uint8_t *	rx,
		size_t	len
	)

Definition at line 203 of file spi.h.

References PROTOCORE_SPI_HZ, PROTOCORE_SPI_MODE, and protocore_spi_txn_at().

Referenced by protocore_spi_read(), and protocore_spi_write().

protocore_spi_write()

PROTOCORE_INLINE proto_bool protocore_spi_write	(	const uint8_t *	tx,
		size_t	len
	)

Definition at line 208 of file spi.h.

References protocore_spi_txn().

protocore_spi_read()

PROTOCORE_INLINE proto_bool protocore_spi_read	(	uint8_t *	rx,
		size_t	len
	)

Definition at line 213 of file spi.h.

References protocore_spi_txn().

protocore_spi_txn_ext_on()

PROTOCORE_INLINE proto_bool protocore_spi_txn_ext_on	(	uint8_t	host,
		uint32_t	hz,
		uint8_t	bit_order,
		uint8_t	mode,
		uint16_t	cmd,
		uint8_t	cmd_bits,
		uint32_t	addr,
		uint8_t	addr_bits,
		uint8_t	dummy_bits,
		uint8_t	lanes,
		const uint8_t *	tx,
		uint8_t *	rx,
		size_t	len
	)

Definition at line 218 of file spi.h.

References PROTO_FALSE.

protocore_spi_txn_ext()

PROTOCORE_INLINE proto_bool protocore_spi_txn_ext	(	uint16_t	cmd,
		uint8_t	cmd_bits,
		uint32_t	addr,
		uint8_t	addr_bits,
		uint8_t	dummy_bits,
		uint8_t	lanes,
		const uint8_t *	tx,
		uint8_t *	rx,
		size_t	len
	)

Definition at line 239 of file spi.h.

References PROTO_FALSE.

protocore_spi_cs_idle()

PROTOCORE_INLINE void protocore_spi_cs_idle

(

uint8_t

pin

)

Definition at line 255 of file spi.h.

protocore_spi_cs_select()

PROTOCORE_INLINE void protocore_spi_cs_select

(

uint8_t

pin

)

Definition at line 260 of file spi.h.

protocore_spi_cs_release()

PROTOCORE_INLINE void protocore_spi_cs_release

(

uint8_t

pin

)

Definition at line 265 of file spi.h.