hardware_spi

Hardware SPI API. More...

Macros

#define spi0   ((spi_inst_t * const)spi0_hw)
 
#define spi1   ((spi_inst_t * const)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...
 

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 * const)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 * const)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
spiSPI 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
spiSPI instance specifier, either spi0 or spi1
Returns
The actual baudrate set

◆ spi_get_index()

static uint spi_get_index ( const spi_inst_t spi)
inlinestatic

Convert SPI instance to hardware instance number.

Parameters
spiSPI 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
spiSPI instance specifier, either spi0 or spi1
baudrateBaudrate 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
spiSPI 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
spiSPI 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
spiSPI 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
spiSPI instance specifier, either spi0 or spi1
repeated_tx_dataBuffer of data to write
dstBuffer for read data
lenLength 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
spiSPI instance specifier, either spi0 or spi1
repeated_tx_dataBuffer of data to write
dstBuffer for read data
lenLength 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
spiSPI instance specifier, either spi0 or spi1
baudrateBaudrate 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
spiSPI instance specifier, either spi0 or spi1
data_bitsNumber of data bits per transfer. Valid values 4..16.
cpolSSPCLKOUT polarity, applicable to Motorola SPI frame format only.
cphaSSPCLKOUT phase, applicable to Motorola SPI frame format only
orderMust 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
spiSPI instance specifier, either spi0 or spi1
slavetrue 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
spiSPI instance specifier, either spi0 or spi1
srcBuffer of data to write
lenLength 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
spiSPI instance specifier, either spi0 or spi1
srcBuffer of data to write
dstBuffer for read data
lenLength 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
spiSPI instance specifier, either spi0 or spi1
srcBuffer of data to write
lenLength 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
spiSPI instance specifier, either spi0 or spi1
srcBuffer of data to write
dstBuffer for read data
lenLength of BOTH buffers
Returns
Number of bytes written/read