Serial Peripheral Interface (SPI)

Collaboration diagram for Serial Peripheral Interface (SPI):

Data Structures

struct  spi_master
 SPI master. More...

Modules

 Generic SPI polled internals

Defines

#define SPI_CPHA   (1 << 0)
 Clock phase.
#define SPI_CPOL   (1 << 1)
 Clock polarity.
#define SPI_MODE_0   0
 SPI mode 0.
#define SPI_MODE_1   (SPI_CPHA)
 SPI mode 1.
#define SPI_MODE_2   (SPI_CPOL)
 SPI mode 2.
#define SPI_MODE_3   (SPI_CPOL | SPI_CPHA)
 SPI mode 3.

Functions

static bool spi_request_bus (struct spi_master *master, struct workqueue_task *task)
 Request use of SPI bus.
static void spi_release_bus (struct spi_master *master)
 Release use of SPI bus.
static void spi_enable (spi_id_t spi_id)
 Enable SPI module.
static void spi_disable (spi_id_t spi_id)
 Disable SPI module.
static bool spi_is_enabled (spi_id_t spi_id)
 Check if SPI module is enabled.
static void spi_master_init (spi_id_t spi_id, struct spi_master *spi_master)
 Initialize SPI module in master mode.
static void spi_master_setup_device (spi_id_t spi_id, struct spi_master *spi_master, struct spi_device *spi_device, spi_flags_t flags, unsigned long baud_rate, board_spi_select_id_t sel_id)
 Setup a SPI device.
static void spi_select_device (spi_id_t spi_id, struct spi_master *master, struct spi_device *device)
 Select given device on the SPI bus.
static void spi_deselect_device (spi_id_t spi_id, struct spi_master *master, struct spi_device *device)
 Deselect given device on the SPI bus.
static void spi_write (spi_id_t spi_id, struct spi_master *master, const uint8_t *data, size_t len)
 Send a sequence of bytes to a SPI device.
static void spi_read (spi_id_t spi_id, struct spi_master *master, uint8_t *data, size_t len)
 Receive a sequence of bytes from a SPI device.
static void spi_exchange (spi_id_t spi_id, struct spi_master *master, const uint8_t *write, uint8_t *read, size_t len)
 Send/Receive a sequence of bytes to/from a SPI device.
static void spi_write_buf_list (spi_id_t spi_id, struct spi_master *master, struct slist *buf_list)
 Send bytes from a list of buffers to a SPI device.
static void spi_read_buf_list (spi_id_t spi_id, struct spi_master *master, struct slist *buf_list)
 Receive bytes into a list of buffers from a SPI device.
static void spi_exchange_buf_list (spi_id_t spi_id, struct spi_master *master, struct slist *write_buf_list, struct slist *read_buf_list)
 Send/Receive a list of buffers to/from a SPI device.

Detailed Description

This is the common API for SPIs on AVRs. Additional features are available in the documentation of the specific modules.

An SPI Module ID starts with 0 which stands for the first available SPI module on the device and the next SPI modules get increasing numbers. After the "standard" SPI modules the emulated versions are listed (e.g. USART in SPI mode or USI in SPI mode).

To add the SPI master driver to the build, the configuration symbol CONFIG_SPI_MASTER must be set.

The symbols CONFIG_SPI_MASTER_INT or CONFIG_SPI_MASTER_DMA enable interrupt or DMA driven communication for the SPI master, if available on the device.

SPI modes

There are four combinations of serial clock phase and polarity with respect to serial data. The table below shows the combinations and when data is sampled or set up. The leading edge is the first clock edge in a clock cycle. Trailing edge is the last clock edge in a clock cycle.

SPI Mode CPOL CPHA Leading Edge Trailing Edge
0 0 0 Sample on rising edge Setup on falling edge
1 0 1 Setup on rising edge Sample on falling edge
2 1 0 Sample on falling edge Setup on rising edge
3 1 1 Setup on falling edge Sample on rising edge

SPI poll loops

The internals of this SPI driver uses polling from a workqueue_task, and this can be controlled with the configuration symbol CONFIG_SPI_POLL_MAXLOOPS

If unconfigured, the default value is 255

SPI Module ID

Overview of mapping between SPI module id (spi_id_t) and peripheral:

Define Documentation

#define SPI_CPHA   (1 << 0)

Clock phase.

Definition at line 114 of file spi.h.

#define SPI_CPOL   (1 << 1)

Clock polarity.

Definition at line 119 of file spi.h.

#define SPI_MODE_0   0

SPI mode 0.

Definition at line 124 of file spi.h.

#define SPI_MODE_1   (SPI_CPHA)

SPI mode 1.

Definition at line 128 of file spi.h.

#define SPI_MODE_2   (SPI_CPOL)

SPI mode 2.

Definition at line 132 of file spi.h.

#define SPI_MODE_3   (SPI_CPOL | SPI_CPHA)

SPI mode 3.

Definition at line 136 of file spi.h.

Function Documentation

void spi_deselect_device ( spi_id_t  spi_id,
struct spi_master *  master,
struct spi_device *  device 
) [inline, static]

Deselect given device on the SPI bus.

Calls board chip deselect.

Parameters:
spi_id SPI Module ID
master SPI master
device SPI device
Precondition:
This must only be used in workqueue task issued by driver
SPI device must be selected with spi_select_device() first

Definition at line 418 of file spi_mega_xmega.h.

References spi_priv_deselect_device().

Referenced by at45_deselect().

void spi_disable ( spi_id_t  spi_id  )  [inline, static]

Disable SPI module.

The SPI is only disabled when it is not used any more. This is ensured by an internal counter that is decreased each time this function is called.

Parameters:
spi_id SPI Module ID

Definition at line 373 of file spi_mega_xmega.h.

References assert, spi_id_is_valid, and spi_priv_disable().

void spi_enable ( spi_id_t  spi_id  )  [inline, static]

Enable SPI module.

The driver keeps a reference count that is increased each time this function is called.

Parameters:
spi_id SPI Module ID

Definition at line 364 of file spi_mega_xmega.h.

References assert, spi_id_is_valid, and spi_priv_enable().

void spi_exchange ( spi_id_t  spi_id,
struct spi_master *  master,
const uint8_t *  write,
uint8_t *  read,
size_t  len 
) [inline, static]

Send/Receive a sequence of bytes to/from a SPI device.

Send bytes from write buffer and receive bytes into read buffer. Length field len are common for both.

Parameters:
spi_id SPI Module ID
master SPI master
write data buffer to write
read data buffer to read
len Length of data
Precondition:
This must only be used in workqueue task issued by driver
SPI device must be selected with spi_select_device() first

Definition at line 438 of file spi_mega_xmega.h.

References spi_polled_exchange().

void spi_exchange_buf_list ( spi_id_t  spi_id,
struct spi_master *  master,
struct slist *  write_buf_list,
struct slist *  read_buf_list 
) [inline, static]

Send/Receive a list of buffers to/from a SPI device.

Buffer lists must be symetrical in the sense of number of buffers and buffer sizes.

Parameters:
spi_id SPI Module ID
master SPI master
write_buf_list List of buffers to send from
read_buf_list List of buffers to receive into
Precondition:
This must only be used in workqueue task issued by driver
SPI device must be selected with spi_select_device() first

Definition at line 456 of file spi_mega_xmega.h.

References spi_polled_exchange_buf_list().

bool spi_is_enabled ( spi_id_t  spi_id  )  [inline, static]

Check if SPI module is enabled.

Parameters:
spi_id SPI Module ID

Definition at line 382 of file spi_mega_xmega.h.

References assert, spi_id_is_valid, and spi_priv_is_enabled().

void spi_master_init ( spi_id_t  spi_id,
struct spi_master *  master 
) [inline, static]

Initialize SPI module in master mode.

Parameters:
spi_id SPI Module ID
master Pointer to SPI master struct.

Definition at line 391 of file spi_mega_xmega.h.

References spi_priv_master_init().

void spi_master_setup_device ( spi_id_t  spi_id,
struct spi_master *  master,
struct spi_device *  device,
spi_flags_t  flags,
unsigned long  baud_rate,
board_spi_select_id_t  sel_id 
) [inline, static]

Setup a SPI device.

The returned device descriptor structure must be passed to the driver whenever that device should be used as current slave device.

Parameters:
spi_id SPI Module ID
master Pointer to SPI master structure.
device Pointer to SPI device struct that should be initialized.
flags SPI configuration flags. Common flags for all implementations are the SPI modes SPI_MODE_0 ... SPI_MODE_3.
baud_rate Baud rate for communication with slave device in Hz.
sel_id Board specific seclet id

Definition at line 399 of file spi_mega_xmega.h.

References spi_priv_master_setup_device().

void spi_read ( spi_id_t  spi_id,
struct spi_master *  master,
uint8_t *  data,
size_t  len 
) [inline, static]

Receive a sequence of bytes from a SPI device.

All bytes sent out on SPI bus are sent as value 0.

Parameters:
spi_id SPI Module ID
master SPI master
data data buffer to read
len Length of data
Precondition:
This must only be used in workqueue task issued by driver
SPI device must be selected with spi_select_device() first

Definition at line 432 of file spi_mega_xmega.h.

References spi_polled_read().

Referenced by at45_read_rsp().

void spi_read_buf_list ( spi_id_t  spi_id,
struct spi_master *  master,
struct slist *  buf_list 
) [inline, static]

Receive bytes into a list of buffers from a SPI device.

All bytes sent out on SPI bus are sent as value 0.

Parameters:
spi_id SPI Module ID
master SPI master
buf_list List of buffers to receive into
Precondition:
This must only be used in workqueue task issued by driver
SPI device must be selected with spi_select_device() first

Definition at line 450 of file spi_mega_xmega.h.

References spi_polled_read_buf_list().

Referenced by at45_read_buf_list().

static void spi_release_bus ( struct spi_master *  master  )  [inline, static]

Release use of SPI bus.

Parameters:
master SPI master
Precondition:
This must only be used in workqueue task issued by driver

Definition at line 236 of file spi.h.

References nested_workqueue_next_task(), and spi_master::nwq.

Referenced by at45_release().

static bool spi_request_bus ( struct spi_master *  master,
struct workqueue_task *  task 
) [inline, static]

Request use of SPI bus.

Parameters:
master SPI master
task Task doing the SPI bus operations
Return values:
true The task was successfully queued
false The task has already been queued, so nothing was done

Definition at line 223 of file spi.h.

References nested_workqueue_add_task(), and spi_master::nwq.

Referenced by at45_request().

void spi_select_device ( spi_id_t  spi_id,
struct spi_master *  master,
struct spi_device *  device 
) [inline, static]

Select given device on the SPI bus.

Set device specific setting and calls board chip select.

Parameters:
spi_id SPI Module ID
master SPI master
device SPI device
Precondition:
This must only be used in workqueue task issued by driver

Definition at line 410 of file spi_mega_xmega.h.

References spi_priv_select_device().

Referenced by at45_select().

void spi_write ( spi_id_t  spi_id,
struct spi_master *  master,
const uint8_t *  data,
size_t  len 
) [inline, static]

Send a sequence of bytes to a SPI device.

Received bytes on the SPI bus are discarded.

Parameters:
spi_id SPI Module ID
master SPI master
data data buffer to write
len Length of data
Precondition:
This must only be used in workqueue task issued by driver
SPI device must be selected with spi_select_device() first

Definition at line 426 of file spi_mega_xmega.h.

References spi_polled_write().

Referenced by at45_write_cmd().

void spi_write_buf_list ( spi_id_t  spi_id,
struct spi_master *  master,
struct slist *  buf_list 
) [inline, static]

Send bytes from a list of buffers to a SPI device.

Received bytes on the SPI bus are discarded.

Parameters:
spi_id SPI Module ID
master SPI master
buf_list List of buffers send from
Precondition:
This must only be used in workqueue task issued by driver
SPI device must be selected with spi_select_device() first

Definition at line 444 of file spi_mega_xmega.h.

References spi_polled_write_buf_list().

Referenced by at45_write_buf_list().

Generated on Thu Apr 29 14:10:01 2010 for display-demo by  doxygen 1.6.3