SPI

Serial Peripheral Interface (SPI) interface for hardware platforms. More...

Collaboration diagram for SPI:

Data Structures
struct	hw_spi_config_t
	SPI initialization configuration. More...

Enumerations
enum	hw_spi_mode_t { hw_spi_mode_0, hw_spi_mode_1, hw_spi_mode_2, hw_spi_mode_3 }
	SPI mode selection. More...

Lifecycle
hw_deviceio_t *	hw_spi_init_default (uint32_t baud_rate, const hw_spi_config_t *config)
	Initialize an SPI interface using the platform default adapter and pins. More...
hw_deviceio_t *	hw_spi_init (uint8_t index, hw_gpio_t *sck_pin, hw_gpio_t *tx_pin, hw_gpio_t *rx_pin, hw_gpio_t *cs_pin, uint32_t baud_rate, const hw_spi_config_t *config)
	Initialize an SPI interface with a specific adapter and pins. More...
hw_deviceio_t *	hw_spi_init_device (const char *device, uint32_t baud_rate, const hw_spi_config_t *config)
	Initialize an SPI interface from a platform-specific device path. More...

Properties
uint8_t	hw_spi_count (void)
	Get the total number of available SPI adapters. More...

Detailed Description

Serial Peripheral Interface (SPI) interface for hardware platforms.

This module provides functions to initialize SPI peripherals in master mode and configure device-specific framing; transfers are performed through the generic hw_deviceio_t interface (see deviceio.h) that hw_spi_init*() returns a handle to.

Note

On Raspberry Pi OS, SPI controllers are disabled by default and must be enabled. The primary bus is enabled in config.txt with dtparam=spi=on, giving /dev/spidev0.0 / /dev/spidev0.1 on GPIO8-11. Further buses are enabled with device tree overlays, for example dtoverlay=spi1-3cs for /dev/spidev1.0-/dev/spidev1.2 on GPIO16-21; see /boot/firmware/overlays/README for the full list of overlays, buses, and pin options.

Enumeration Type Documentation

hw_spi_mode_t

enum hw_spi_mode_t

SPI mode selection.

Enumerator
hw_spi_mode_0	CPOL = 0, CPHA = 0 (clock idles low; sample on rising edge)
hw_spi_mode_1	CPOL = 0, CPHA = 1 (clock idles low; sample on falling edge)
hw_spi_mode_2	CPOL = 1, CPHA = 0 (clock idles high; sample on falling edge)
hw_spi_mode_3	CPOL = 1, CPHA = 1 (clock idles high; sample on rising edge)

Definition at line 34 of file spi.h.

             {
  hw_spi_mode_0 =
      0, 
  hw_spi_mode_1 =
      1, 
  hw_spi_mode_2 =
      2, 
  hw_spi_mode_3 =
      3, 
} hw_spi_mode_t;

Function Documentation

hw_spi_count()

uint8_t hw_spi_count

(

void

)

Get the total number of available SPI adapters.

Returns

Number of SPI adapters available on the current platform.

On platforms that open SPI buses by device path, this may return 0 even when SPI is supported. In that case, use hw_spi_init_device() instead of enumerating adapters by index.

hw_spi_init()

hw_deviceio_t* hw_spi_init	(	uint8_t	index,
		hw_gpio_t *	sck_pin,
		hw_gpio_t *	tx_pin,
		hw_gpio_t *	rx_pin,
		hw_gpio_t *	cs_pin,
		uint32_t	baud_rate,
		const hw_spi_config_t *	config
	)

Initialize an SPI interface with a specific adapter and pins.

Parameters

index	SPI adapter index to use.
sck_pin	GPIO handle for SCK.
tx_pin	GPIO handle for MOSI.
rx_pin	GPIO handle for MISO.
cs_pin	Optional GPIO handle for CS. Pass NULL to leave CS unmanaged.
baud_rate	Desired SPI clock rate in Hz.
config	Optional pointer to extended SPI configuration. Pass NULL to use default mode and frame size.

Returns

Device I/O handle bound to the SPI device, or NULL on failure. Release it with hw_deviceio_deinit() - there is no separate hw_spi_deinit().

hw_spi_init_default()

hw_deviceio_t* hw_spi_init_default	(	uint32_t	baud_rate,
		const hw_spi_config_t *	config
	)

Initialize an SPI interface using the platform default adapter and pins.

Parameters

baud_rate	Desired SPI clock rate in Hz.
config	Optional pointer to extended SPI configuration. Pass NULL to use default mode and frame size.

Returns

Device I/O handle bound to the SPI device, or NULL on failure. Release it with hw_deviceio_deinit() - there is no separate hw_spi_deinit().

Note

On platforms where SPI buses are selected by device path instead of index (for example Linux), this function may be unsupported and return NULL by design. Use hw_spi_init_device() on those platforms.

hw_spi_init_device()

hw_deviceio_t* hw_spi_init_device	(	const char *	device,
		uint32_t	baud_rate,
		const hw_spi_config_t *	config
	)

Initialize an SPI interface from a platform-specific device path.

Parameters

device	Device identifier such as /dev/spidev0.0.
baud_rate	Desired SPI clock rate in Hz.
config	Optional pointer to extended SPI configuration. Pass NULL to use default mode and frame size.

Returns

Device I/O handle bound to the SPI device, or NULL on failure. Release it with hw_deviceio_deinit() - there is no separate hw_spi_deinit().

This entry point is intended for platforms where SPI buses are exposed as named devices rather than a fixed, enumerable set of adapters.