v2.0.0
Macros | Enumerations | Functions
hardware_spi
Hardware APIs

Hardware SPI API. More...

## Macros
#define | spi0 ((spi_inst_t *)spi0_hw)
#define | spi1 ((spi_inst_t *)spi1_hw)
#define | SPI_NUM(spi)
| Returns the SPI number for a SPI instance. More...
#define | SPI_INSTANCE(num)
| Returns the SPI instance with the given SPI number. More...
#define | SPI_DREQ_NUM(spi, is_tx)
| Returns the dreq_num_t used for pacing DMA transfers to or from this SPI instance. If is_tx is true, then it is for transfers to the SPI else for transfers from the SPI. More...

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

RP-series microcontrollers have 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)

## ◆ SPI_DREQ_NUM

#define SPI_DREQ_NUM | ( |  | spi,
|  |  | is_tx
| ) |  |

Returns the dreq_num_t used for pacing DMA transfers to or from this SPI instance. If is_tx is true, then it is for transfers to the SPI else for transfers from the SPI.

Note this macro is intended to resolve at compile time, and does no parameter checking

## ◆ SPI_INSTANCE

#define SPI_INSTANCE | ( |  | num | ) |

Returns the SPI instance with the given SPI number.

Note this macro is intended to resolve at compile time, and does no parameter checking

## ◆ SPI_NUM

#define SPI_NUM | ( |  | spi | ) |

Returns the SPI number for a SPI instance.

Note this macro is intended to resolve at compile time, and does no parameter checking

## 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 re-enable 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