hardware_spi

Hardware SPI API. More...

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 instances. More...
void	spi_deinit (spi_inst_t *spi)
	Deinitialise SPI instances. More...
uint	spi_set_baudrate (spi_inst_t *spi, uint baudrate)
	Set SPI baudrate. More...
uint	spi_get_baudrate (const spi_inst_t *spi)
	Get SPI baudrate. 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 SPI. More...
static void	spi_set_slave (spi_inst_t *spi, bool slave)
	Set SPI master/slave. 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 device. More...
int	spi_write_blocking (spi_inst_t *spi, const uint8_t *src, size_t len)
	Write to an SPI device, blocking. More...
int	spi_read_blocking (spi_inst_t *spi, uint8_t repeated_tx_data, uint8_t *dst, size_t len)
	Read from an SPI device. 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 device. More...
int	spi_write16_blocking (spi_inst_t *spi, const uint16_t *src, size_t len)
	Write to an SPI device. More...
int	spi_read16_blocking (spi_inst_t *spi, uint16_t repeated_tx_data, uint16_t *dst, size_t len)
	Read from an SPI device. 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 instances.

Puts 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 baudrate.

Get 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 instances.

Puts 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 device.

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. 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 device.

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. 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 baudrate.

Set 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 SPI.

Configure 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/slave.

Configure 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 device.

Write 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 device.

Write 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, blocking.

Write 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 device.

Write 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