px-lib  0.9.2
Cross-platform embedded library and documentation for 8/16/32-bit microcontrollers

Description

Driver for the SPI peripheral to communicate with SPI slaves.

File(s):

The driver must be configured by supplying a project specific "px_spi_cfg.h". "px_spi_cfg_template.h" can be copied, renamed and modified to supply compile time options.

The SPI peripheral Slave Select pin (SS) must be configured as an output or kept high if it is configured as an input. If this pin is configured as an input and pulled low, the SPI peripheral will automatically change from MASTER mode to SLAVE mode.

Example:
#include "px_spi.h"
#include "px_board.h"
// Create SPI Slave handle object
static px_spi_handle_t px_spi_handle;
int main(void)
{
uint8_t data;
// Initialise board
// Initialise SPI driver
// Open handle to SPI slave device
px_spi_open2(&px_spi_handle,
PX_SPI_NR_0,
// Take Chip Select low and send command byte
data = 0xd7;
px_spi_wr(px_at45d_spi_handle, &data, 1, PX_SPI_FLAG_START);
// Read status byte and take Chip Select high
px_spi_rd(px_at45d_spi_handle, &data, 1, PX_SPI_FLAG_STOP);
// Close SPI Handle
px_spi_close(px_spi_handle);
}

Data Structures

struct  px_spi_handle_t
 Define SPI handle. More...
 

Macros

#define PX_SPI_CFG_PER_COUNT   (PX_SPI_CFG_SPI0_EN)
 Number of enabled peripherals. More...
 
#define PX_SPI_CFG_SPI0_EN   1
 Enable/disable support for SPI0 peripheral. More...
 
#define PX_SPI_CFG_SPCR   ((0<<SPIE) | (1<<SPE) | (0<<DORD) | (1<<MSTR) | (0<<CPOL) | (0<<CPHA) | (0<<SPR1) | (0<<SPR0))
 Default value for SPI Control Register used in px_spi_open(). More...
 
#define PX_SPI_CFG_USE_SPI2X   0
 Default value for "Use double clock rate" used in px_spi_open(). More...
 
#define PX_SPI_CFG_DEFAULT_BAUD   PX_SPI_BAUD_CLK_DIV_2
 Specify default baud rate. More...
 
#define PX_SPI_CFG_DEFAULT_MODE   PX_SPI_MODE0
 Specify default SPI mode (clock phase and polarity) More...
 
#define PX_SPI_CFG_DEFAULT_DATA_ORDER   PX_SPI_DATA_ORDER_MSB
 Specify default SPI data order. More...
 
#define PX_SPI_CFG_CS_LO(cs_id)   px_board_spi_cs_lo(cs_id)
 Map PX_SPI_CFG_CS_LO() macro to board_spi_cs_lo() function. More...
 
#define PX_SPI_CFG_CS_HI(cs_id)   px_board_spi_cs_hi(cs_id)
 Map PX_SPI_CFG_CS_HI() macro to board_spi_cs_hi() function. More...
 

Enumerations

enum  px_spi_nr_t
 Specify SPI peripheral. More...
 
enum  px_spi_mode_t {
  PX_SPI_MODE0 = 0, PX_SPI_MODE1 = 1, PX_SPI_MODE2 = 2, PX_SPI_MODE3 = 3,
  PX_SPI_MODE0 = 0, PX_SPI_MODE1 = 1, PX_SPI_MODE2 = 2, PX_SPI_MODE3 = 3
}
 Specify SPI Clock polarity / Clock phase. More...
 
enum  px_spi_dord_t { PX_SPI_DATA_ORDER_MSB = 0, PX_SPI_DATA_ORDER_LSB = 1, PX_SPI_DATA_ORDER_MSB = 0, PX_SPI_DATA_ORDER_LSB = 1 }
 Specify SPI Data order. More...
 
enum  px_spi_baud_t {
  PX_SPI_BAUD_CLK_DIV_2 = 0, PX_SPI_BAUD_CLK_DIV_4, PX_SPI_BAUD_CLK_DIV_8, PX_SPI_BAUD_CLK_DIV_16,
  PX_SPI_BAUD_CLK_DIV_32, PX_SPI_BAUD_CLK_DIV_64, PX_SPI_BAUD_CLK_DIV_128, PX_SPI_BAUD_CLK_DIV_256,
  PX_SPI_BAUD_CLK_DIV_2 = 0, PX_SPI_BAUD_CLK_DIV_4, PX_SPI_BAUD_CLK_DIV_8, PX_SPI_BAUD_CLK_DIV_16,
  PX_SPI_BAUD_CLK_DIV_32, PX_SPI_BAUD_CLK_DIV_64, PX_SPI_BAUD_CLK_DIV_128
}
 Specify SPI baud rate as a ratio of the peripheral clock. More...
 

Functions

void px_spi_init (void)
 Initialise SPI driver. More...
 
bool px_spi_open (px_spi_handle_t *handle, px_spi_nr_t spi_nr, uint8_t cs_id)
 Open SPI peripheral using predefined (default) parameters. More...
 
bool px_spi_open2 (px_spi_handle_t *handle, px_spi_nr_t spi_nr, uint8_t cs_id, px_spi_baud_t baud, px_spi_mode_t mode, px_spi_dord_t data_order, uint8_t mo_dummy_byte)
 Open SPI peripheral using specified parameters. More...
 
bool px_spi_close (px_spi_handle_t *handle)
 Close specified device. More...
 
void px_spi_wr (px_spi_handle_t *handle, const void *data, size_t nr_of_bytes, uint8_t flags)
 Perform an SPI write transaction with an SPI slave. More...
 
void px_spi_rd (px_spi_handle_t *handle, void *data, size_t nr_of_bytes, uint8_t flags)
 Perform an SPI read transaction with an SPI slave. More...
 
void px_spi_xc (px_spi_handle_t *handle, const void *data_wr, void *data_rd, size_t nr_of_bytes, uint8_t flags)
 Perform an SPI exchange (write and read) transaction with an SPI slave. More...
 
void px_spi_ioctl_change_baud (px_spi_handle_t *handle, px_spi_baud_t baud)
 Change SPI peripheral baud. More...
 
px_spi_baud_t px_spi_util_baud_hz_to_clk_div (uint32_t baud_hz)
 Calculate clock divisor that will yield closest frequency equal to or less than specified baud rate (in Hz). More...
 
uint32_t px_spi_util_clk_div_to_baud_hz (px_spi_baud_t baud)
 Calculate the actual BAUD (in Hz) from the specified division. More...
 

SPI bit flags to demarcate the start and end of a transaction

#define PX_SPI_FLAG_START   (1<<0)
 Begin SPI transaction (take SPI slave's Chip Select line low) More...
 
#define PX_SPI_FLAG_STOP   (1<<1)
 Finish SPI transaction (take SPI slave's Chip Select line high) More...
 
#define PX_SPI_FLAG_START_AND_STOP   (PX_SPI_FLAG_START + PX_SPI_FLAG_STOP)
 Begin and finish SPI transaction. More...
 

Data Structure Documentation

◆ px_spi_handle_t

struct px_spi_handle_t

Define SPI handle.

Definition at line 123 of file px_spi.h.

Data Fields
struct px_spi_per_s * spi_per SPI peripheral.

SPI peripheral data.

uint8_t cs_id Chip Select GPIO ID.
uint32_t spi_cr1_val SPI Control Register 1 value (SPI_CR1)
uint8_t mo_dummy_byte Master Out dummy byte when data is read from Master In.
uint8_t spcr SPI Control Register value.
bool use_spi2x Use 2X clock rate.

Macro Definition Documentation

◆ PX_SPI_CFG_PER_COUNT

#define PX_SPI_CFG_PER_COUNT   (PX_SPI_CFG_SPI0_EN)

Number of enabled peripherals.

Definition at line 75 of file px_spi.h.

◆ PX_SPI_FLAG_START

#define PX_SPI_FLAG_START   (1<<0)

Begin SPI transaction (take SPI slave's Chip Select line low)

Definition at line 123 of file px_spi.h.

◆ PX_SPI_FLAG_STOP

#define PX_SPI_FLAG_STOP   (1<<1)

Finish SPI transaction (take SPI slave's Chip Select line high)

Definition at line 125 of file px_spi.h.

◆ PX_SPI_FLAG_START_AND_STOP

#define PX_SPI_FLAG_START_AND_STOP   (PX_SPI_FLAG_START + PX_SPI_FLAG_STOP)

Begin and finish SPI transaction.

Definition at line 127 of file px_spi.h.

◆ PX_SPI_CFG_SPI0_EN

#define PX_SPI_CFG_SPI0_EN   1

Enable/disable support for SPI0 peripheral.

Definition at line 34 of file px_spi_cfg_template.h.

◆ PX_SPI_CFG_SPCR

#define PX_SPI_CFG_SPCR   ((0<<SPIE) | (1<<SPE) | (0<<DORD) | (1<<MSTR) | (0<<CPOL) | (0<<CPHA) | (0<<SPR1) | (0<<SPR0))

Default value for SPI Control Register used in px_spi_open().

Definition at line 37 of file px_spi_cfg_template.h.

◆ PX_SPI_CFG_USE_SPI2X

#define PX_SPI_CFG_USE_SPI2X   0

Default value for "Use double clock rate" used in px_spi_open().

Definition at line 41 of file px_spi_cfg_template.h.

◆ PX_SPI_CFG_DEFAULT_BAUD

#define PX_SPI_CFG_DEFAULT_BAUD   PX_SPI_BAUD_CLK_DIV_2

Specify default baud rate.

Definition at line 44 of file px_spi_cfg_template.h.

◆ PX_SPI_CFG_DEFAULT_MODE

#define PX_SPI_CFG_DEFAULT_MODE   PX_SPI_MODE0

Specify default SPI mode (clock phase and polarity)

Definition at line 47 of file px_spi_cfg_template.h.

◆ PX_SPI_CFG_DEFAULT_DATA_ORDER

#define PX_SPI_CFG_DEFAULT_DATA_ORDER   PX_SPI_DATA_ORDER_MSB

Specify default SPI data order.

Definition at line 50 of file px_spi_cfg_template.h.

◆ PX_SPI_CFG_CS_LO

#define PX_SPI_CFG_CS_LO (   cs_id)    px_board_spi_cs_lo(cs_id)

Map PX_SPI_CFG_CS_LO() macro to board_spi_cs_lo() function.

A manual Chip Select function must be implemented, e.g.

void board_spi_cs_lo(uint8_t cs_id)
{
    switch(cs_id)
    {
    case BOARD_SPI_CS:
        PX_GPIO_PIN_SET_LO(PX_GPIO_SPI_CS);
        break;

    default:
        break;
    }
}

Definition at line 69 of file px_spi_cfg_template.h.

◆ PX_SPI_CFG_CS_HI

#define PX_SPI_CFG_CS_HI (   cs_id)    px_board_spi_cs_hi(cs_id)

Map PX_SPI_CFG_CS_HI() macro to board_spi_cs_hi() function.

A manual Chip Select function must be implemented, e.g.

void board_spi_cs_hi(uint8_t cs_id)
{
    switch(cs_id)
    {
    case BOARD_SPI_CS:
        PX_GPIO_PIN_SET_HI(PX_GPIO_SPI_CS);
        break;

    default:
        break;
    }
}

Definition at line 89 of file px_spi_cfg_template.h.

Enumeration Type Documentation

◆ px_spi_nr_t

Specify SPI peripheral.

Definition at line 87 of file px_spi.h.

◆ px_spi_mode_t

Specify SPI Clock polarity / Clock phase.

Enumerator
PX_SPI_MODE0 

CPOL=0, CPHA=0; SCLK idle polarity low; data sampled on first (rising) edge.

PX_SPI_MODE1 

CPOL=0, CPHA=1; SCLK idle polarity low; data sampled on second (falling) edge.

PX_SPI_MODE2 

CPOL=1, CPHA=0; SCLK idle polarity high; data sampled on first (falling) edge.

PX_SPI_MODE3 

CPOL=1, CPHA=1; SCLK idle polarity high; data sampled on second (rising) edge.

PX_SPI_MODE0 

CPOL=0, CPHA=0; SCLK idle polarity low; data sampled on first (rising) edge.

PX_SPI_MODE1 

CPOL=0, CPHA=1; SCLK idle polarity low; data sampled on second (falling) edge.

PX_SPI_MODE2 

CPOL=1, CPHA=0; SCLK idle polarity high; data sampled on first (falling) edge.

PX_SPI_MODE3 

CPOL=1, CPHA=1; SCLK idle polarity high; data sampled on second (rising) edge.

Definition at line 93 of file px_spi.h.

◆ px_spi_dord_t

Specify SPI Data order.

Enumerator
PX_SPI_DATA_ORDER_MSB 

Data order is Most Significant Bit first (D7, D6, ..., D0)

PX_SPI_DATA_ORDER_LSB 

Data order is Least Significant Bit first (D0, D1, ..., D7)

PX_SPI_DATA_ORDER_MSB 

Data order is Most Significant Bit first (D7, D6, ..., D0)

PX_SPI_DATA_ORDER_LSB 

Data order is Least Significant Bit first (D0, D1, ..., D7)

Definition at line 102 of file px_spi.h.

◆ px_spi_baud_t

Specify SPI baud rate as a ratio of the peripheral clock.

Enumerator
PX_SPI_BAUD_CLK_DIV_2 

F_PCLK / 2.

PX_SPI_BAUD_CLK_DIV_4 

F_PCLK / 4.

PX_SPI_BAUD_CLK_DIV_8 

F_PCLK / 8.

PX_SPI_BAUD_CLK_DIV_16 

F_PCLK / 16.

PX_SPI_BAUD_CLK_DIV_32 

F_PCLK / 32.

PX_SPI_BAUD_CLK_DIV_64 

F_PCLK / 64.

PX_SPI_BAUD_CLK_DIV_128 

F_PCLK / 128.

PX_SPI_BAUD_CLK_DIV_256 

F_PCLK / 256.

PX_SPI_BAUD_CLK_DIV_2 

F_CPU / 2.

PX_SPI_BAUD_CLK_DIV_4 

F_CPU / 4.

PX_SPI_BAUD_CLK_DIV_8 

F_CPU / 8.

PX_SPI_BAUD_CLK_DIV_16 

F_CPU / 16.

PX_SPI_BAUD_CLK_DIV_32 

F_CPU / 32.

PX_SPI_BAUD_CLK_DIV_64 

F_CPU / 64.

PX_SPI_BAUD_CLK_DIV_128 

F_CPU / 128.

Definition at line 109 of file px_spi.h.

Function Documentation

◆ px_spi_init()

void px_spi_init ( void  )

Initialise SPI driver.

Definition at line 152 of file px_spi.c.

◆ px_spi_open()

bool px_spi_open ( px_spi_handle_t handle,
px_spi_nr_t  spi_nr,
uint8_t  cs_id 
)

Open SPI peripheral using predefined (default) parameters.

Parameters
handlePointer to handle data structure
spi_nrSPI peripheral number
cs_idID to use when calling PX_SPI_CS_xx() macro
Return values
falseError: peripheral was not opened
trueSuccess: peripheral was opened

Definition at line 163 of file px_spi.c.

◆ px_spi_open2()

bool px_spi_open2 ( px_spi_handle_t handle,
px_spi_nr_t  spi_nr,
uint8_t  cs_id,
px_spi_baud_t  baud,
px_spi_mode_t  mode,
px_spi_dord_t  data_order,
uint8_t  mo_dummy_byte 
)

Open SPI peripheral using specified parameters.

Parameters
handlePointer to handle data structure
spi_nrSPI peripheral number
cs_idID to use when calling PX_SPI_CS() macro
baudDesired BAUD rate as a division of peripheral clock
modeClock mode 0,1,2 or 3
See also
px_spi_mode_t
Parameters
data_orderData order (MSB first of LSB first)
mo_dummy_byteMaster Out dummy byte used when reading data from SPI slave
Return values
falseError: peripheral was not opened
trueSuccess: peripheral was opened

Definition at line 226 of file px_spi.c.

◆ px_spi_close()

bool px_spi_close ( px_spi_handle_t handle)

Close specified device.

Parameters
handlePointer to handle data structure
Return values
trueSuccess
falseSpecified device was already closed (or not opened)

Definition at line 296 of file px_spi.c.

◆ px_spi_wr()

void px_spi_wr ( px_spi_handle_t handle,
const void *  data,
size_t  nr_of_bytes,
uint8_t  flags 
)

Perform an SPI write transaction with an SPI slave.

With the use of flags this function allows concatenation of one or more writes / reads / exchanges with an SPI slave to form one big transaction.

If the PX_SPI_FLAG_START flag is specified, the SPI slave is first selected by taking it's Chip Select line low.

The specified number of bytes is then written to the SPI slave.

Finally, if the PX_SPI_FLAG_STOP flag is specified, the SPI slave's Chip Select line is taken high to complete the transaction.

Parameters
handlePointer to handle data structure
dataBuffer containing data to write
nr_of_bytesNumber of bytes to write to the slave
flagsBit combination of PX_SPI_FLAG_START and PX_SPI_FLAG_STOP or nothing (0)

Definition at line 346 of file px_spi.c.

◆ px_spi_rd()

void px_spi_rd ( px_spi_handle_t handle,
void *  data,
size_t  nr_of_bytes,
uint8_t  flags 
)

Perform an SPI read transaction with an SPI slave.

With the use of flags this function allows concatenation of one or more writes / reads / exchanges with an SPI slave to form one big transaction.

If the PX_SPI_FLAG_START flag is specified, the SPI slave is first selected by taking it's Chip Select line low.

The specified number of bytes is then read from the SPI slave.

Finally, if the PX_SPI_FLAG_STOP flag is specified, the SPI slave's Chip Select line is taken high to complete the transaction.

Parameters
handlePointer to handle data structure
dataPointer to a buffer where the received data must be stored
nr_of_bytesNumber of bytes to read from slave
flagsBit combination of PX_SPI_FLAG_START and PX_SPI_FLAG_STOP or nothing (0)

Definition at line 431 of file px_spi.c.

◆ px_spi_xc()

void px_spi_xc ( px_spi_handle_t handle,
const void *  data_wr,
void *  data_rd,
size_t  nr_of_bytes,
uint8_t  flags 
)

Perform an SPI exchange (write and read) transaction with an SPI slave.

With the use of flags this function allows concatenation of one or more writes / reads / exchanges with an SPI slave to form one big transaction.

If the PX_SPI_FLAG_START flag is specified, the SPI slave is first selected by taking it's Chip Select line low.

The specified number of bytes is then written to the slave, while simultaneously reading the same number of bytes from the slave.

The write buffer and read buffer must both be at least "nr_of_bytes" bytes in size. It is acceptable to have the write buffer and read buffer point to the same location in which case the data to write will be overwritten by the received data.

Finally, if the PX_SPI_FLAG_STOP flag is specified, the SPI slave's Chip Select line is taken high to complete the transaction.

Parameters
handlePointer to handle data structure
data_wrPointer to a buffer containing data to be written
data_rdPointer to a buffer where the read data must be stored
nr_of_bytesNumber of bytes to exchange
flagsBit combination of PX_SPI_FLAG_START and PX_SPI_FLAG_STOP or nothing (0)

Definition at line 515 of file px_spi.c.

◆ px_spi_ioctl_change_baud()

void px_spi_ioctl_change_baud ( px_spi_handle_t handle,
px_spi_baud_t  baud 
)

Change SPI peripheral baud.

Parameters
handlePointer to handle data structure
baudDesired BAUD rate as a division of peripheral clock

Definition at line 599 of file px_spi.c.

◆ px_spi_util_baud_hz_to_clk_div()

px_spi_baud_t px_spi_util_baud_hz_to_clk_div ( uint32_t  baud_hz)

Calculate clock divisor that will yield closest frequency equal to or less than specified baud rate (in Hz).

Parameters
baud_hzDesired BAUD rate in Hz that SCK must be clocked
Returns
px_spi_baud_t Calculated divisor

Definition at line 631 of file px_spi.c.

◆ px_spi_util_clk_div_to_baud_hz()

uint32_t px_spi_util_clk_div_to_baud_hz ( px_spi_baud_t  baud)

Calculate the actual BAUD (in Hz) from the specified division.

Parameters
baudDesired BAUD rate as a division of peripheral clock
Returns
uint32_t Actual BAUD (in Hz)

Definition at line 654 of file px_spi.c.