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.

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

px_board_init();

// Initialise SPI driver

px_spi_init();

// Open handle to SPI slave device

px_spi_open2(&px_spi_handle,

PX_SPI_NR_1,

PX_BOARD_SPI_CS_DF,

PX_SPI_BAUD_CLK_DIV_2,

PX_SPI_MODE0,

PX_SPI_DATA_ORDER_MSB);

// 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);

}

PX_SPI_MODE0
@ PX_SPI_MODE0
CPOL=0, CPHA=0; SCLK idle polarity low; data sampled on first (rising) edge.
Definition: px_spi.h:87

PX_SPI_DATA_ORDER_MSB
@ PX_SPI_DATA_ORDER_MSB
Data order is Most Significant Bit first (D7, D6, ..., D0)
Definition: px_spi.h:96

PX_SPI_BAUD_CLK_DIV_2
@ PX_SPI_BAUD_CLK_DIV_2
F_PCLK / 2.
Definition: px_spi.h:103

PX_BOARD_SPI_CS_DF
@ PX_BOARD_SPI_CS_DF
Adesto AT45D DataFlash.
Definition: px_board.h:66

px_board_init
void px_board_init(void)
Initialise the board hardware.
Definition: px_board.c:168

px_spi_close
bool px_spi_close(px_spi_handle_t *handle)
Close specified device.
Definition: px_spi.c:338

px_spi_init
void px_spi_init(void)
Initialise SPI driver.
Definition: px_spi.c:162

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.
Definition: px_spi.c:252

PX_SPI_FLAG_START
#define PX_SPI_FLAG_START
Begin SPI transaction (take SPI slave's Chip Select line low)
Definition: px_spi.h:117

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.
Definition: px_spi.c:396

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.
Definition: px_spi.c:479

PX_SPI_FLAG_STOP
#define PX_SPI_FLAG_STOP
Finish SPI transaction (take SPI slave's Chip Select line high)
Definition: px_spi.h:119

px_spi_handle_t
Define SPI handle.
Definition: px_spi.h:126

Data Structures
struct	px_spi_handle_t
	Define SPI handle. More...

Macros
#define	PX_SPI_CFG_PER_COUNT (PX_SPI_CFG_SPI1_EN + PX_SPI_CFG_SPI2_EN )
	Number of enabled peripherals. More...

#define	PX_SPI_CFG_SPI1_EN 1
	Enable/disable support for SPI1 peripheral. More...

#define	PX_SPI_CFG_SPI2_EN 1
	Enable/disable support for SPI2 peripheral. More...

#define	PX_SPI_CFG_DEFAULT_BAUD PX_SPI_BAUD_CLK_DIV_32
	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 px_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 px_board_spi_cs_hi() function. More...

Enumerations
enum	px_spi_nr_t
	Specify SPI peripheral number. 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_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 125 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_SPI1_EN + PX_SPI_CFG_SPI2_EN )

Number of enabled peripherals.

Definition at line 66 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 117 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 119 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 121 of file px_spi.h.

◆ PX_SPI_CFG_SPI1_EN

#define PX_SPI_CFG_SPI1_EN 1

Enable/disable support for SPI1 peripheral.

Definition at line 35 of file px_spi_cfg_template.h.

◆ PX_SPI_CFG_SPI2_EN

#define PX_SPI_CFG_SPI2_EN 1

Enable/disable support for SPI2 peripheral.

Definition at line 38 of file px_spi_cfg_template.h.

◆ PX_SPI_CFG_DEFAULT_BAUD

#define PX_SPI_CFG_DEFAULT_BAUD PX_SPI_BAUD_CLK_DIV_32

Specify default baud rate.

Definition at line 41 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 44 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 47 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 px_board_spi_cs_lo() function.

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

void px_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 66 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 px_board_spi_cs_hi() function.

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

void px_board_spi_cs_hi(uint8_t cs_id)
{
    switch(cs_id)
    {
    case BOARD_SPI_CS:
        PX_GPIO_OUT_SET_HI(PX_GPIO_SPI_CS);
        break;

    default:
        break;
    }
}

Definition at line 86 of file px_spi_cfg_template.h.

Enumeration Type Documentation

◆ px_spi_nr_t

enum px_spi_nr_t

Specify SPI peripheral number.

Definition at line 78 of file px_spi.h.

◆ px_spi_mode_t

enum 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 85 of file px_spi.h.

◆ px_spi_dord_t

enum 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 94 of file px_spi.h.

◆ px_spi_baud_t

enum 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 101 of file px_spi.h.

Function Documentation

◆ px_spi_init()

void px_spi_init ( void )

Initialise SPI driver.

Definition at line 162 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

handle	Pointer to handle data structure
spi_nr	SPI peripheral number
cs_id	ID to use when calling PX_SPI_CS_xx() macro

Return values

false	Error: peripheral was not opened
true	Success: peripheral was opened

Definition at line 173 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

handle	Pointer to handle data structure
spi_nr	SPI peripheral number
cs_id	ID to use when calling PX_SPI_CS() macro
baud	Desired BAUD rate as a division of peripheral clock
mode	Clock mode 0,1,2 or 3

See also: px_spi_mode_t

Parameters

data_order	Data order (MSB first of LSB first)
mo_dummy_byte	Master Out dummy byte used when reading data from SPI slave

Return values

false	Error: peripheral was not opened
true	Success: peripheral was opened

Definition at line 252 of file px_spi.c.

◆ px_spi_close()

bool px_spi_close ( px_spi_handle_t * handle )

Close specified device.

Parameters

handle Pointer to handle data structure

Return values

true	Success
false	Specified device was already closed (or not opened)

Definition at line 338 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

handle	Pointer to handle data structure
data	Buffer containing data to write
nr_of_bytes	Number of bytes to write to the slave
flags	Bit combination of PX_SPI_FLAG_START and PX_SPI_FLAG_STOP or nothing (0)

Definition at line 396 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

handle	Pointer to handle data structure
data	Pointer to a buffer where the received data must be stored
nr_of_bytes	Number of bytes to read from slave
flags	Bit combination of PX_SPI_FLAG_START and PX_SPI_FLAG_STOP or nothing (0)

Definition at line 479 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

handle	Pointer to handle data structure
data_wr	Pointer to a buffer containing data to be written
data_rd	Pointer to a buffer where the read data must be stored
nr_of_bytes	Number of bytes to exchange
flags	Bit combination of PX_SPI_FLAG_START and PX_SPI_FLAG_STOP or nothing (0)

Definition at line 568 of file px_spi.c.

◆ px_spi_change_baud()

void px_spi_change_baud	(	px_spi_handle_t *	handle,
		px_spi_baud_t	baud
	)

Change SPI peripheral baud.

Parameters

handle	Pointer to handle data structure
baud	Desired BAUD rate as a division of peripheral clock

Definition at line 657 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_hz Desired BAUD rate in Hz that SCK must be clocked

Returns: px_spi_baud_t Calculated divisor

Definition at line 698 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

baud	Desired BAUD rate as a division of peripheral clock

Returns: uint32_t Actual BAUD (in Hz)

Definition at line 720 of file px_spi.c.

Description

Data Structures

Macros

Enumerations

Functions

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

Data Structure Documentation

◆ px_spi_handle_t

Macro Definition Documentation

◆ PX_SPI_CFG_PER_COUNT

◆ PX_SPI_FLAG_START

◆ PX_SPI_FLAG_STOP

◆ PX_SPI_FLAG_START_AND_STOP

◆ PX_SPI_CFG_SPI1_EN

◆ PX_SPI_CFG_SPI2_EN

◆ PX_SPI_CFG_DEFAULT_BAUD

◆ PX_SPI_CFG_DEFAULT_MODE

◆ PX_SPI_CFG_DEFAULT_DATA_ORDER

◆ PX_SPI_CFG_CS_LO

◆ PX_SPI_CFG_CS_HI

Enumeration Type Documentation

◆ px_spi_nr_t

◆ px_spi_mode_t

◆ px_spi_dord_t

◆ px_spi_baud_t

Function Documentation

◆ px_spi_init()

◆ px_spi_open()

◆ px_spi_open2()

◆ px_spi_close()

◆ px_spi_wr()

◆ px_spi_rd()

◆ px_spi_xc()

◆ px_spi_change_baud()

◆ px_spi_util_baud_hz_to_clk_div()

◆ px_spi_util_clk_div_to_baud_hz()