spi.h — Maple v0.0.12 Documentation

### Navigation

- next
- previous |
- LeafLabs |
- Index »
- `libmaple` »
- APIs »

# `spi.h`

Serial Peripheral Interface (SPI) support. Currently, there is no I2S support beyond register bit definitions.

Contents

- Types
- Devices
- Functions
- Register Map Base Pointers
- Register Bit Definitions
  - Control register 1
  - Control register 2
  - Status register
  - I2S configuration register

## Types

struct spi_reg_map

> SPI register map type.

> Public Members

> > __io uint32 CR1

> >   Control register 1.

> > __io uint32 CR2

> >   Control register 2.

> > __io uint32 SR

> >   Status register.

> > __io uint32 DR

> >   Data register.

> > __io uint32 CRCPR

> >   CRC polynomial register.

> > __io uint32 RXCRCR

> >   RX CRC register.

> > __io uint32 TXCRCR

> >   TX CRC register.

> > __io uint32 I2SCFGR

> >   I2S configuration register.

> > __io uint32 I2SPR

> >   I2S prescaler register.

struct spi_dev

> SPI device type.

> Public Members

> > spi_reg_map * regs

> >   Register map.

> > rcc_clk_id clk_id

> >   RCC clock information.

> > nvic_irq_num irq_num

> >   NVIC interrupt number.

spi_mode enum

  SPI mode configuration.

  Determines a combination of clock polarity (CPOL), which determines idle state of the clock line, and clock phase (CPHA), which determines which clock edge triggers data capture.

  Values:

  - `SPI_MODE_0` -

    Clock line idles low (0), data capture on first clock transition.

  - `SPI_MODE_1` -

    Clock line idles low (0), data capture on second clock transition.

  - `SPI_MODE_2` -

    Clock line idles high (1), data capture on first clock transition.

  - `SPI_MODE_3` -

    Clock line idles high (1), data capture on second clock transition.

spi_baud_rate enum

  SPI baud rate configuration, as a divisor of f_PCLK, the PCLK clock frequency.

  Values:

  - `SPI_BAUD_PCLK_DIV_2``= SPI_CR1_BR_PCLK_DIV_2` -

    f_PCLK/2

  - `SPI_BAUD_PCLK_DIV_4``= SPI_CR1_BR_PCLK_DIV_4` -

    f_PCLK/4

  - `SPI_BAUD_PCLK_DIV_8``= SPI_CR1_BR_PCLK_DIV_8` -

    f_PCLK/8

  - `SPI_BAUD_PCLK_DIV_16``= SPI_CR1_BR_PCLK_DIV_16` -

    f_PCLK/16

  - `SPI_BAUD_PCLK_DIV_32``= SPI_CR1_BR_PCLK_DIV_32` -

    f_PCLK/32

  - `SPI_BAUD_PCLK_DIV_64``= SPI_CR1_BR_PCLK_DIV_64` -

    f_PCLK/64

  - `SPI_BAUD_PCLK_DIV_128``= SPI_CR1_BR_PCLK_DIV_128` -

    f_PCLK/128

  - `SPI_BAUD_PCLK_DIV_256``= SPI_CR1_BR_PCLK_DIV_256` -

    f_PCLK/256

spi_cfg_flag enum

  SPI initialization flags.

  See: | spi_master_enable() spi_slave_enable()

  Values:

  - `SPI_BIDIMODE``= SPI_CR1_BIDIMODE` -

    Bidirectional mode enable.

  - `SPI_BIDIOE``= SPI_CR1_BIDIOE` -

    Output enable in bidirectional mode.

  - `SPI_CRCEN``= SPI_CR1_CRCEN` -

    Cyclic redundancy check (CRC) enable.

  - `SPI_DFF_8_BIT``= SPI_CR1_DFF_8_BIT` -

    8-bit data frame format (this is the default)

  - `SPI_DFF_16_BIT``= SPI_CR1_DFF_16_BIT` -

    16-bit data frame format

  - `SPI_RX_ONLY``= SPI_CR1_RXONLY` -

    Receive only.

  - `SPI_SW_SLAVE``= SPI_CR1_SSM` -

    Software slave management.

  - `SPI_SOFT_SS``= SPI_CR1_SSI` -

    Software (internal) slave select.

    This flag only has an effect when used in combination with SPI_SW_SLAVE.

  - `SPI_FRAME_LSB``= SPI_CR1_LSBFIRST` -

    LSB-first (little-endian) frame format.

  - `SPI_FRAME_MSB``= 0` -

    MSB-first (big-endian) frame format (this is the default).

spi_interrupt enum

  Available SPI interrupts.

  Values:

  - `SPI_TXE_INTERRUPT``= SPI_CR2_TXEIE` -

    TX buffer empty interrupt.

  - `SPI_RXNE_INTERRUPT``= SPI_CR2_RXNEIE` -

    RX buffer not empty interrupt.

  - `SPI_ERR_INTERRUPT``= SPI_CR2_ERRIE` -

    Error interrupt (CRC, overrun, and mode fault errors for SPI; underrun, overrun errors for I2S).

## Devices

spi_dev * SPI1

  SPI device 1.

spi_dev * SPI2

  SPI device 2.

spi_dev * SPI3

  SPI device 3.

## Functions

void spi_init(spi_dev * dev)

  Initialize and reset a SPI device.

  Parameters: | `dev` - Device to initialize and reset.

void spi_gpio_cfg(uint8 as_master, gpio_dev * nss_dev, uint8 nss_bit, gpio_dev * comm_dev, uint8 sck_bit, uint8 miso_bit, uint8 mosi_bit)

  Configure GPIO bit modes for use as a SPI port’s pins.

  Parameters: | `as_master` - If true, configure bits for use as a bus master. Otherwise, configure bits for use as slave. `nss_dev` - NSS pin’s GPIO device `comm_dev` - SCK, MISO, MOSI pins’ GPIO device `nss_bit` - NSS pin’s GPIO bit on nss_dev `sck_bit` - SCK pin’s GPIO bit on comm_dev `miso_bit` - MISO pin’s GPIO bit on comm_dev `mosi_bit` - MOSI pin’s GPIO bit on comm_dev

void spi_master_enable(spi_dev * dev, spi_baud_rate baud, spi_mode mode, uint32 flags)

  Configure and enable a SPI device as bus master.

  The device’s peripheral will be disabled before being reconfigured.

  Parameters: | `dev` - Device to configure as bus master `baud` - Bus baud rate `mode` - SPI mode `flags` - Logical OR of spi_cfg_flag values.
  See: | spi_cfg_flag

void spi_slave_enable(spi_dev * dev, spi_mode mode, uint32 flags)

  Configure and enable a SPI device as a bus slave.

  The device’s peripheral will be disabled before being reconfigured.

  Parameters: | `dev` - Device to configure as a bus slave `mode` - SPI mode `flags` - Logical OR of spi_cfg_flag values.
  See: | spi_cfg_flag

uint32 spi_tx(spi_dev * dev, const void * buf, uint32 len)

  Nonblocking SPI transmit.

  Parameters: | `dev` - SPI port to use for transmission `buf` - Buffer to transmit. The sizeof buf’s elements are inferred from dev’s data frame format (i.e., are correctly treated as 8-bit or 16-bit quantities). `len` - Maximum number of elements to transmit.
  Return: | Number of elements transmitted.

void spi_foreach(void(*)( spi_dev *) fn)

  Call a function on each SPI port.

  Parameters: | `fn` - Function to call.

void spi_peripheral_enable(spi_dev * dev)

  Enable a SPI peripheral.

  Parameters: | `dev` - Device to enable

void spi_peripheral_disable(spi_dev * dev)

  Disable a SPI peripheral.

  Parameters: | `dev` - Device to disable

void spi_peripheral_disable_all(void)

  Disable all SPI peripherals.

void spi_tx_dma_enable(spi_dev * dev)

  Enable DMA requests whenever the transmit buffer is empty.

  Parameters: | `dev` - SPI device on which to enable TX DMA requests

void spi_tx_dma_disable(spi_dev * dev)

  Disable DMA requests whenever the transmit buffer is empty.

  Parameters: | `dev` - SPI device on which to disable TX DMA requests

void spi_rx_dma_enable(spi_dev * dev)

  Enable DMA requests whenever the receive buffer is empty.

  Parameters: | `dev` - SPI device on which to enable RX DMA requests

void spi_rx_dma_disable(spi_dev * dev)

  Disable DMA requests whenever the receive buffer is empty.

  Parameters: | `dev` - SPI device on which to disable RX DMA requests

uint8 spi_is_enabled(spi_dev * dev)

  Determine if a SPI peripheral is enabled.

  Parameters: | `dev` - SPI device
  Return: | True, if and only if dev’s peripheral is enabled.

void spi_irq_enable(spi_dev * dev, uint32 interrupt_flags)

  Enable SPI interrupt requests.

  Parameters: | `dev` - SPI device `interrupt_flags` - Bitwise OR of spi_interrupt values to enable
  See: | spi_interrupt

void spi_irq_disable(spi_dev * dev, uint32 interrupt_flags)

  Disable SPI interrupt requests.

  Parameters: | `dev` - SPI device `interrupt_flags` - Bitwise OR of spi_interrupt values to disable
  See: | spi_interrupt

spi_cfg_flag spi_dff(spi_dev * dev)

  Get the data frame format flags with which a SPI port is configured.

  Parameters: | `dev` - SPI device whose data frame format to get.
  Return: | SPI_DFF_8_BIT, if dev has an 8-bit data frame format. Otherwise, SPI_DFF_16_BIT.

uint8 spi_is_rx_nonempty(spi_dev * dev)

  Determine whether the device’s peripheral receive (RX) register is empty.

  Parameters: | `dev` - SPI device
  Return: | true, iff dev’s RX register is empty.

uint16 spi_rx_reg(spi_dev * dev)

  Retrieve the contents of the device’s peripheral receive (RX) register.

  You may only call this function when the RX register is nonempty. Calling this function clears the contents of the RX register.

  Parameters: | `dev` - SPI device
  Return: | Contents of dev’s peripheral RX register
  See: | spi_is_rx_reg_nonempty()

uint8 spi_is_tx_empty(spi_dev * dev)

  Determine whether the device’s peripheral transmit (TX) register is empty.

  Parameters: | `dev` - SPI device
  Return: | true, iff dev’s TX register is empty.

void spi_tx_reg(spi_dev * dev, uint16 val)

  Load a value into the device’s peripheral transmit (TX) register.

  You may only call this function when the TX register is empty. Calling this function loads val into the peripheral’s TX register. If the device is properly configured, this will initiate a transmission, the completion of which will cause the TX register to be empty again.

  Parameters: | `dev` - SPI device `val` - Value to load into the TX register. If the SPI data frame format is 8 bit, the value must be right-aligned.
  See: | spi_is_tx_reg_empty() spi_init() spi_master_enable() spi_slave_enable()

uint8 spi_is_busy(spi_dev * dev)

  Determine whether the device’s peripheral busy (SPI_SR_BSY) flag is set.

  Parameters: | `dev` - SPI device
  Return: | true, iff dev’s BSY flag is set.

## Register Map Base Pointers

SPI1_BASE

  SPI1 register map base pointer.

SPI2_BASE

  SPI2 register map base pointer.

SPI3_BASE

  SPI3 register map base pointer.

## Register Bit Definitions

### Control register 1

SPI_CR1_BIDIMODE_BIT

SPI_CR1_BIDIOE_BIT

SPI_CR1_CRCEN_BIT

SPI_CR1_CRCNEXT_BIT

SPI_CR1_DFF_BIT

SPI_CR1_RXONLY_BIT

SPI_CR1_SSM_BIT

SPI_CR1_SSI_BIT

SPI_CR1_LSBFIRST_BIT

SPI_CR1_SPE_BIT

SPI_CR1_MSTR_BIT

SPI_CR1_CPOL_BIT

SPI_CR1_CPHA_BIT

SPI_CR1_BIDIMODE

SPI_CR1_BIDIMODE_2_LINE

SPI_CR1_BIDIMODE_1_LINE

SPI_CR1_BIDIOE

SPI_CR1_CRCEN

SPI_CR1_CRCNEXT

SPI_CR1_DFF

SPI_CR1_DFF_8_BIT

SPI_CR1_DFF_16_BIT

SPI_CR1_RXONLY

SPI_CR1_SSM

SPI_CR1_SSI

SPI_CR1_LSBFIRST

SPI_CR1_SPE

SPI_CR1_BR

SPI_CR1_BR_PCLK_DIV_2

SPI_CR1_BR_PCLK_DIV_4

SPI_CR1_BR_PCLK_DIV_8

SPI_CR1_BR_PCLK_DIV_16

SPI_CR1_BR_PCLK_DIV_32

SPI_CR1_BR_PCLK_DIV_64

SPI_CR1_BR_PCLK_DIV_128

SPI_CR1_BR_PCLK_DIV_256

SPI_CR1_MSTR

SPI_CR1_CPOL

SPI_CR1_CPOL_LOW

SPI_CR1_CPOL_HIGH

SPI_CR1_CPHA

### Control register 2

SPI_CR2_TXEIE_BIT

SPI_CR2_RXNEIE_BIT

SPI_CR2_ERRIE_BIT

SPI_CR2_SSOE_BIT

SPI_CR2_TXDMAEN_BIT

SPI_CR2_RXDMAEN_BIT

SPI_CR2_TXEIE

SPI_CR2_RXNEIE

SPI_CR2_ERRIE

SPI_CR2_SSOE

SPI_CR2_TXDMAEN

SPI_CR2_RXDMAEN

### Status register

SPI_SR_BSY_BIT

SPI_SR_OVR_BIT

SPI_SR_MODF_BIT

SPI_SR_CRCERR_BIT

SPI_SR_UDR_BIT

SPI_SR_CHSIDE_BIT

SPI_SR_TXE_BIT

SPI_SR_RXNE_BIT

SPI_SR_BSY

SPI_SR_OVR

SPI_SR_MODF

SPI_SR_CRCERR

SPI_SR_UDR

SPI_SR_CHSIDE

SPI_SR_CHSIDE_LEFT

SPI_SR_CHSIDE_RIGHT

SPI_SR_TXE

SPI_SR_RXNE

### I2S configuration register

SPI_I2SCFGR_I2SMOD_BIT

SPI_I2SCFGR_I2SE_BIT

SPI_I2SCFGR_PCMSYNC_BIT

SPI_I2SCFGR_CKPOL_BIT

SPI_I2SCFGR_CHLEN_BIT

SPI_I2SCFGR_I2SMOD

SPI_I2SCFGR_I2SMOD_SPI

SPI_I2SCFGR_I2SMOD_I2S

SPI_I2SCFGR_I2SE

SPI_I2SCFGR_I2SCFG

SPI_I2SCFGR_I2SCFG_SLAVE_TX

SPI_I2SCFGR_I2SCFG_SLAVE_RX

SPI_I2SCFGR_I2SCFG_MASTER_TX

SPI_I2SCFGR_I2SCFG_MASTER_RX

SPI_I2SCFGR_PCMSYNC

SPI_I2SCFGR_PCMSYNC_SHORT

SPI_I2SCFGR_PCMSYNC_LONG

SPI_I2SCFGR_I2SSTD

SPI_I2SCFGR_I2SSTD_PHILLIPS

SPI_I2SCFGR_I2SSTD_MSB

SPI_I2SCFGR_I2SSTD_LSB

SPI_I2SCFGR_I2SSTD_PCM

SPI_I2SCFGR_CKPOL

SPI_I2SCFGR_CKPOL_LOW

SPI_I2SCFGR_CKPOL_HIGH

SPI_I2SCFGR_DATLEN

SPI_I2SCFGR_DATLEN_16_BIT

SPI_I2SCFGR_DATLEN_24_BIT

SPI_I2SCFGR_DATLEN_32_BIT

SPI_I2SCFGR_CHLEN

SPI_I2SCFGR_CHLEN_16_BIT

SPI_I2SCFGR_CHLEN_32_BIT

### Navigation

- next
- previous |
- LeafLabs |
- Index »
- `libmaple` »
- APIs »