Macros
#define	spi0 ((spi_inst_t *)spi0_hw)

#define	spi1 ((spi_inst_t *)spi1_hw)

Enumerations
enum	spi_cpha_t { SPI_CPHA_0 = 0, SPI_CPHA_1 = 1 }
	Enumeration of SPI CPHA (clock phase) values.

enum	spi_cpol_t { SPI_CPOL_0 = 0, SPI_CPOL_1 = 1 }
	Enumeration of SPI CPOL (clock polarity) values.

enum	spi_order_t { SPI_LSB_FIRST = 0, SPI_MSB_FIRST = 1 }
	Enumeration of SPI bit-order values.

Functions
uint	spi_init (spi_inst_t *spi, uint baudrate)
	Initialise SPI instancesPuts the SPI into a known state, and enable it. Must be called before other functions. More...

void	spi_deinit (spi_inst_t *spi)
	Deinitialise SPI instancesPuts the SPI into a disabled state. Init will need to be called to reenable the device functions. More...

uint	spi_set_baudrate (spi_inst_t *spi, uint baudrate)
	Set SPI baudrateSet SPI frequency as close as possible to baudrate, and return the actual achieved rate. More...

uint	spi_get_baudrate (const spi_inst_t *spi)
	Get SPI baudrateGet SPI baudrate which was set by. More...

static uint	spi_get_index (const spi_inst_t *spi)
	Convert SPI instance to hardware instance number. More...

static void	spi_set_format (spi_inst_t *spi, uint data_bits, spi_cpol_t cpol, spi_cpha_t cpha, __unused spi_order_t order)
	Configure SPIConfigure how the SPI serialises and deserialises data on the wire. More...

static void	spi_set_slave (spi_inst_t *spi, bool slave)
	Set SPI master/slaveConfigure the SPI for master- or slave-mode operation. By default, spi_init() sets master-mode. More...

static bool	spi_is_writable (const spi_inst_t *spi)
	Check whether a write can be done on SPI device. More...

static bool	spi_is_readable (const spi_inst_t *spi)
	Check whether a read can be done on SPI device. More...

static bool	spi_is_busy (const spi_inst_t *spi)
	Check whether SPI is busy. More...

int	spi_write_read_blocking (spi_inst_t spi, const uint8_t src, uint8_t *dst, size_t len)
	Write/Read to/from an SPI deviceWrite `len` bytes from `src` to SPI. Simultaneously read `len` bytes from SPI to `dst`. Blocks until all data is transferred. No timeout, as SPI hardware always transfers at a known data rate. More...

int	spi_write_blocking (spi_inst_t spi, const uint8_t src, size_t len)
	Write to an SPI device, blockingWrite `len` bytes from `src` to SPI, and discard any data received back Blocks until all data is transferred. No timeout, as SPI hardware always transfers at a known data rate. More...

int	spi_read_blocking (spi_inst_t spi, uint8_t repeated_tx_data, uint8_t dst, size_t len)
	Read from an SPI deviceRead `len` bytes from SPI to `dst`. Blocks until all data is transferred. No timeout, as SPI hardware always transfers at a known data rate. `repeated_tx_data` is output repeatedly on TX as data is read in from RX. Generally this can be 0, but some devices require a specific value here, e.g. SD cards expect 0xff. More...

int	spi_write16_read16_blocking (spi_inst_t spi, const uint16_t src, uint16_t *dst, size_t len)
	Write/Read half words to/from an SPI deviceWrite `len` halfwords from `src` to SPI. Simultaneously read `len` halfwords from SPI to `dst`. Blocks until all data is transferred. No timeout, as SPI hardware always transfers at a known data rate. More...

int	spi_write16_blocking (spi_inst_t spi, const uint16_t src, size_t len)
	Write to an SPI deviceWrite `len` halfwords from `src` to SPI. Discard any data received back. Blocks until all data is transferred. No timeout, as SPI hardware always transfers at a known data rate. More...

int	spi_read16_blocking (spi_inst_t spi, uint16_t repeated_tx_data, uint16_t dst, size_t len)
	Read from an SPI deviceRead `len` halfwords from SPI to `dst`. Blocks until all data is transferred. No timeout, as SPI hardware always transfers at a known data rate. `repeated_tx_data` is output repeatedly on TX as data is read in from RX. Generally this can be 0, but some devices require a specific value here, e.g. SD cards expect 0xff. More...

static uint	spi_get_dreq (spi_inst_t *spi, bool is_tx)
	Return the DREQ to use for pacing transfers to/from a particular SPI instance. More...

Detailed Description

Hardware SPI API

RP2040 has 2 identical instances of the Serial Peripheral Interface (SPI) controller.

The PrimeCell SSP is a master or slave interface for synchronous serial communication with peripheral devices that have Motorola SPI, National Semiconductor Microwire, or Texas Instruments synchronous serial interfaces.

Controller can be defined as master or slave using the spi_set_slave function.

Each controller can be connected to a number of GPIO pins, see the datasheet GPIO function selection table for more information.

Macro Definition Documentation

◆ spi0

#define spi0 ((spi_inst_t *)spi0_hw)

Identifier for the first (SPI 0) hardware SPI instance (for use in SPI functions).

e.g. spi_init(spi0, 48000)

◆ spi1

#define spi1 ((spi_inst_t *)spi1_hw)

Identifier for the second (SPI 1) hardware SPI instance (for use in SPI functions).

e.g. spi_init(spi1, 48000)

Function Documentation

◆ spi_deinit()

void spi_deinit ( spi_inst_t * spi )

Deinitialise SPI instancesPuts the SPI into a disabled state. Init will need to be called to reenable the device functions.

Parameters

spi	SPI instance specifier, either spi0 or spi1

◆ spi_get_baudrate()

uint spi_get_baudrate ( const spi_inst_t * spi )

Get SPI baudrateGet SPI baudrate which was set by.

See also: spi_set_baudrate

Parameters

spi	SPI instance specifier, either spi0 or spi1

Returns: The actual baudrate set

◆ spi_get_dreq()

static uint spi_get_dreq	(	spi_inst_t *	spi,
		bool	is_tx
	)

inlinestatic

Return the DREQ to use for pacing transfers to/from a particular SPI instance.

Parameters

spi	SPI instance specifier, either spi0 or spi1
is_tx	true for sending data to the SPI instance, false for receiving data from the SPI instance

◆ spi_get_index()

static uint spi_get_index ( const spi_inst_t * spi )

inlinestatic

Convert SPI instance to hardware instance number.

Parameters

spi	SPI instance

Returns: Number of SPI, 0 or 1.

◆ spi_init()

uint spi_init	(	spi_inst_t *	spi,
		uint	baudrate
	)

Initialise SPI instancesPuts the SPI into a known state, and enable it. Must be called before other functions.

Note: There is no guarantee that the baudrate requested can be achieved exactly; the nearest will be chosen and returned

Parameters

spi	SPI instance specifier, either spi0 or spi1
baudrate	Baudrate requested in Hz

Returns: the actual baud rate set

◆ spi_is_busy()

static bool spi_is_busy ( const spi_inst_t * spi )

inlinestatic

Check whether SPI is busy.

Parameters

spi	SPI instance specifier, either spi0 or spi1

Returns: true if SPI is busy

◆ spi_is_readable()

static bool spi_is_readable ( const spi_inst_t * spi )

inlinestatic

Check whether a read can be done on SPI device.

Parameters

spi	SPI instance specifier, either spi0 or spi1

Returns: true if a read is possible i.e. data is present

◆ spi_is_writable()

static bool spi_is_writable ( const spi_inst_t * spi )

inlinestatic

Check whether a write can be done on SPI device.

Parameters

spi	SPI instance specifier, either spi0 or spi1

Returns: false if no space is available to write. True if a write is possible

◆ spi_read16_blocking()

int spi_read16_blocking	(	spi_inst_t *	spi,
		uint16_t	repeated_tx_data,
		uint16_t *	dst,
		size_t	len
	)

Read from an SPI deviceRead len halfwords from SPI to dst. Blocks until all data is transferred. No timeout, as SPI hardware always transfers at a known data rate. repeated_tx_data is output repeatedly on TX as data is read in from RX. Generally this can be 0, but some devices require a specific value here, e.g. SD cards expect 0xff.

Note: SPI should be initialised with 16 data_bits using spi_set_format first, otherwise this function will only read 8 data_bits.

Parameters

spi	SPI instance specifier, either spi0 or spi1
repeated_tx_data	Buffer of data to write
dst	Buffer for read data
len	Length of buffer `dst` in halfwords

Returns: Number of halfwords written/read

◆ spi_read_blocking()

int spi_read_blocking	(	spi_inst_t *	spi,
		uint8_t	repeated_tx_data,
		uint8_t *	dst,
		size_t	len
	)

Read from an SPI deviceRead len bytes from SPI to dst. Blocks until all data is transferred. No timeout, as SPI hardware always transfers at a known data rate. repeated_tx_data is output repeatedly on TX as data is read in from RX. Generally this can be 0, but some devices require a specific value here, e.g. SD cards expect 0xff.

Parameters

spi	SPI instance specifier, either spi0 or spi1
repeated_tx_data	Buffer of data to write
dst	Buffer for read data
len	Length of buffer `dst`

Returns: Number of bytes written/read

◆ spi_set_baudrate()

uint spi_set_baudrate	(	spi_inst_t *	spi,
		uint	baudrate
	)

Set SPI baudrateSet SPI frequency as close as possible to baudrate, and return the actual achieved rate.

Parameters

spi	SPI instance specifier, either spi0 or spi1
baudrate	Baudrate required in Hz, should be capable of a bitrate of at least 2Mbps, or higher, depending on system clock settings.

Returns: The actual baudrate set

◆ spi_set_format()

static void spi_set_format	(	spi_inst_t *	spi,
		uint	data_bits,
		spi_cpol_t	cpol,
		spi_cpha_t	cpha,
		__unused spi_order_t	order
	)

inlinestatic

Configure SPIConfigure how the SPI serialises and deserialises data on the wire.

Parameters

spi	SPI instance specifier, either spi0 or spi1
data_bits	Number of data bits per transfer. Valid values 4..16.
cpol	SSPCLKOUT polarity, applicable to Motorola SPI frame format only.
cpha	SSPCLKOUT phase, applicable to Motorola SPI frame format only
order	Must be SPI_MSB_FIRST, no other values supported on the PL022

◆ spi_set_slave()

static void spi_set_slave	(	spi_inst_t *	spi,
		bool	slave
	)

inlinestatic

Set SPI master/slaveConfigure the SPI for master- or slave-mode operation. By default, spi_init() sets master-mode.

Parameters

spi	SPI instance specifier, either spi0 or spi1
slave	true to set SPI device as a slave device, false for master.

◆ spi_write16_blocking()

int spi_write16_blocking	(	spi_inst_t *	spi,
		const uint16_t *	src,
		size_t	len
	)

Write to an SPI deviceWrite len halfwords from src to SPI. Discard any data received back. Blocks until all data is transferred. No timeout, as SPI hardware always transfers at a known data rate.

Note: SPI should be initialised with 16 data_bits using spi_set_format first, otherwise this function will only write 8 data_bits.

Parameters

spi	SPI instance specifier, either spi0 or spi1
src	Buffer of data to write
len	Length of buffers

Returns: Number of halfwords written/read

◆ spi_write16_read16_blocking()

int spi_write16_read16_blocking	(	spi_inst_t *	spi,
		const uint16_t *	src,
		uint16_t *	dst,
		size_t	len
	)

Write/Read half words to/from an SPI deviceWrite len halfwords from src to SPI. Simultaneously read len halfwords from SPI to dst. Blocks until all data is transferred. No timeout, as SPI hardware always transfers at a known data rate.

Note: SPI should be initialised with 16 data_bits using spi_set_format first, otherwise this function will only read/write 8 data_bits.

Parameters

spi	SPI instance specifier, either spi0 or spi1
src	Buffer of data to write
dst	Buffer for read data
len	Length of BOTH buffers in halfwords

Returns: Number of halfwords written/read

◆ spi_write_blocking()

int spi_write_blocking	(	spi_inst_t *	spi,
		const uint8_t *	src,
		size_t	len
	)

Write to an SPI device, blockingWrite len bytes from src to SPI, and discard any data received back Blocks until all data is transferred. No timeout, as SPI hardware always transfers at a known data rate.

Parameters

spi	SPI instance specifier, either spi0 or spi1
src	Buffer of data to write
len	Length of `src`

Returns: Number of bytes written/read

◆ spi_write_read_blocking()

int spi_write_read_blocking	(	spi_inst_t *	spi,
		const uint8_t *	src,
		uint8_t *	dst,
		size_t	len
	)

Write/Read to/from an SPI deviceWrite len bytes from src to SPI. Simultaneously read len bytes from SPI to dst. Blocks until all data is transferred. No timeout, as SPI hardware always transfers at a known data rate.

Parameters

spi	SPI instance specifier, either spi0 or spi1
src	Buffer of data to write
dst	Buffer for read data
len	Length of BOTH buffers

Returns: Number of bytes written/read

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ spi0

◆ spi1

Function Documentation

◆ spi_deinit()

◆ spi_get_baudrate()

◆ spi_get_dreq()

◆ spi_get_index()

◆ spi_init()

◆ spi_is_busy()

◆ spi_is_readable()

◆ spi_is_writable()

◆ spi_read16_blocking()

◆ spi_read_blocking()

◆ spi_set_baudrate()

◆ spi_set_format()

◆ spi_set_slave()

◆ spi_write16_blocking()

◆ spi_write16_read16_blocking()

◆ spi_write_blocking()

◆ spi_write_read_blocking()