Detailed Description

Low-level SPI peripheral driver.

This interface defines an abstraction for using a CPU's hardware SPI units. The interface only supports SPI master mode.

As SPI buses can have multiple devices connected to them they are to be considered as shared resources. To reflect this, the SPI interface is based on a transaction model. This requires that the bus needs to be acquired before usage and released afterwards, using the spi_acquire() and the spi_release() functions.

This interface supports both software and hardware chip select lines. This is reflected by the cpi_cs_t type, which overloads the gpio_t type with platform specific values for defining platform dependent hardware chip select lines.

Some devices have however very uncommon requirements on the usage and the timings of their chip select line. For those cases this interface allows to manage the chip select line manually from the user code (e.g. by calling gpio_set/clear explicitly) while deactivating the SPI driver internal chip select handling by passing GPIO_UNDEF as CS parameter.

In the time, when the SPI bus is not used, the SPI unit should be in low-power mode to save energy.

The SPI unit's initialization is split into 3 parts:

spi_init() should be called once for each SPI unit defined by a board during system initialization.

spi_init_cs() should be called during device driver initialization, as each chip select pin/line is used uniquely by a specific device, i.e. chip select lines are no shared resource.

spi_acquire() needs to be called for each new transaction. This function configures the bus with specific parameters (clock, mode) for the duration of that transaction.

Function Documentation

Starting a new SPI transaction will get exclusive access to the SPI bus and configure it according to the given values. If another SPI transaction is active when this function is called, this function will block until the other transaction is complete (spi_relase was called).

Note

This function expects the bus and the cs parameters to be valid (they are checked in spi_init and spi_init_cs before)

Parameters

[in]

bus

SPI device to access

[in]

cs

chip select pin/line to use, set to SPI_CS_UNDEF if chip select should not be handled by the SPI driver

This function does the basic initialization including pin configuration for MISO, MOSI, and CLK pins. After initialization, the given device should be in power down state.

This function is intended to be called by the board initialization code during system startup to prepare the (shared) SPI device for further usage. It uses the board specific initialization parameters as defined in the board's periph_conf.h.

Errors (e.g. invalid bus parameter) are not signaled through a return value, but should be signaled using the assert() function internally.

The chip select can be any generic GPIO pin (e.g. GPIO_PIN(x,y)), or it can be a hardware chip select line. The existence and number of hardware chip select lines depends on the underlying platform and the actual pins used for hardware chip select lines are defined in the board's periph_conf.h.

Define the used chip select line using the SPI_HWCS(x) macro for hardware chip select line x or the GPIO_PIN(x,y) macro for using any GPIO pin for manual chip select.

After calling spi_init, the pins must be initialized (i.e. spi_init is calling this function internally). In normal cases, this function will not be used. But there are some devices (e.g. CC110x), that use SPI bus lines also for other purposes and need the option to dynamically re-configure one or more of the used pins. So they can take control over certain pins and return control back to the SPI driver using this function.