Contiki-NG
SPI Hardware Abstraction Layer

The SPI HAL provides a set of common functions that can be used in a platform-independent fashion. More...

Files

file  spi.c
 Implementation of the platform-independent aspects of the SPI HAL.
 
file  spi.h
 Header file for the SPI HAL.
 

Data Structures

struct  spi_device
 SPI Device Configuration. More...
 

Macros

#define SPI_DEVICE_PORT(member, device)   (device)->port_spi_##member
 Retrieve the SPI device's port number if applicable. More...
 

Functions

spi_status_t spi_acquire (const spi_device_t *dev)
 Locks and then opens an SPI controller. More...
 
spi_status_t spi_release (const spi_device_t *dev)
 Closes and then unlocks an SPI controller. More...
 
spi_status_t spi_select (const spi_device_t *dev)
 Selects the SPI peripheral. More...
 
spi_status_t spi_deselect (const spi_device_t *dev)
 Deselects the SPI peripheral. More...
 
bool spi_has_bus (const spi_device_t *dev)
 Checks if a device has locked an SPI controller. More...
 
spi_status_t spi_write_byte (const spi_device_t *dev, uint8_t data)
 Writes a single byte to an SPI device. More...
 
spi_status_t spi_write (const spi_device_t *dev, const uint8_t *data, int size)
 Writes a buffer to an SPI device. More...
 
spi_status_t spi_read_byte (const spi_device_t *dev, uint8_t *data)
 Reads a single byte from an SPI device. More...
 
spi_status_t spi_read (const spi_device_t *dev, uint8_t *data, int size)
 Reads a buffer from an SPI device. More...
 
spi_status_t spi_read_skip (const spi_device_t *dev, int size)
 Reads and ignores data from an SPI device. More...
 
spi_status_t spi_transfer (const spi_device_t *dev, const uint8_t *data, int wsize, uint8_t *buf, int rsize, int ignore)
 Performs a generic SPI transfer. More...
 
spi_status_t spi_read_register (const spi_device_t *dev, uint8_t reg, uint8_t *data, int size)
 Reads a buffer of bytes from a register of an SPI device. More...
 
spi_status_t spi_strobe (const spi_device_t *dev, uint8_t strobe, uint8_t *status)
 Reads and Writes one byte from/to an SPI device. More...
 
bool spi_arch_has_lock (const spi_device_t *dev)
 Checks if a device has locked an SPI controller. More...
 
bool spi_arch_is_bus_locked (const spi_device_t *dev)
 Checks if an SPI controller is locked by any device. More...
 
spi_status_t spi_arch_lock_and_open (const spi_device_t *dev)
 Locks and opens an SPI controller to the configuration specified. More...
 
spi_status_t spi_arch_close_and_unlock (const spi_device_t *dev)
 Closes and unlocks an SPI controller. More...
 
spi_status_t spi_arch_transfer (const spi_device_t *dev, const uint8_t *data, int wlen, uint8_t *buf, int rlen, int ignore_len)
 Performs an SPI transfer. More...
 
enum  spi_status_t
 SPI return codes.
 
typedef struct spi_device spi_device_t
 SPI Device Configuration. More...
 

Detailed Description

The SPI HAL provides a set of common functions that can be used in a platform-independent fashion.

Macro Definition Documentation

◆ SPI_DEVICE_PORT

#define SPI_DEVICE_PORT (   member,
  device 
)    (device)->port_spi_##member

Retrieve the SPI device's port number if applicable.

Parameters
memberRetrieve struct member port_spi_member (e.g. port_spi_miso)
deviceA pointer the a variable of type spi_device_t

The same macro is used for all four port_spi_foo members of the struct. So to retrieve port_spi_cs, use SPI_DEVICE_PORT(cs, device). Replace cs with mosi to retrieve port_spi_mosi.

Definition at line 129 of file spi.h.

Typedef Documentation

◆ spi_device_t

typedef struct spi_device spi_device_t

SPI Device Configuration.

This is a structure to an architecture-independent SPI configuration.

Note
Do not access the port_spi_foo members directly. Access them by using the SPI_DEVICE_PORT() macro instead

Function Documentation

◆ spi_acquire()

spi_status_t spi_acquire ( const spi_device_t dev)

Locks and then opens an SPI controller.

Parameters
devAn SPI device configuration which defines the controller to be locked and the opening configuration.
Returns
SPI return code

Definition at line 46 of file spi.c.

Referenced by ext_flash_open().

◆ spi_arch_close_and_unlock()

spi_status_t spi_arch_close_and_unlock ( const spi_device_t dev)

Closes and unlocks an SPI controller.

Parameters
devAn SPI device configuration that specifies the controller.
Returns
SPI return code

This should turn off the SPI controller to put it in low power mode and unlock it. It should work only if the device has already locked the SPI controller.

Definition at line 268 of file spi-arch.c.

References spi_arch_has_lock().

◆ spi_arch_has_lock()

bool spi_arch_has_lock ( const spi_device_t dev)

Checks if a device has locked an SPI controller.

Parameters
devAn SPI device configuration which defines the controller to be checked if it is locked and the respective device.
Returns
1 if the device has the lock, 0 otherwise.

Definition at line 151 of file spi-arch.c.

Referenced by spi_arch_close_and_unlock(), and spi_select().

◆ spi_arch_is_bus_locked()

bool spi_arch_is_bus_locked ( const spi_device_t dev)

Checks if an SPI controller is locked by any device.

Parameters
devAn SPI device configuration which defines the controller to be checked.
Returns
1 if the controller is locked, 0 otherwise.

Definition at line 161 of file spi-arch.c.

◆ spi_arch_lock_and_open()

spi_status_t spi_arch_lock_and_open ( const spi_device_t dev)

Locks and opens an SPI controller to the configuration specified.

Parameters
devAn SPI device configuration.
Returns
SPI return code

This should work only if the device has already locked the SPI controller.

Definition at line 171 of file spi-arch.c.

◆ spi_arch_transfer()

spi_status_t spi_arch_transfer ( const spi_device_t dev,
const uint8_t *  data,
int  wlen,
uint8_t *  buf,
int  rlen,
int  ignore_len 
)

Performs an SPI transfer.

Parameters
devAn SPI device configuration that specifies the controller.
dataA pointer to the data to be written. Set it to NULL to skip writing.
wlenLength of data to write.
bufA pointer to buffer to copy the data read. Set to NULL to skip reading.
rlenLength of data to read.
ignore_lenLength of data to read and ignore.
Returns
SPI return code

It should work only if the device has already locked the SPI controller. A total of rlen+ignore_len bytes will be read. The first rlen bytes will be copied to buf. The remaining ignore_len bytes won't be copied to the buffer. The maximum of wlen and rlen+ignore_len of bytes will be transfered.

Definition at line 286 of file spi-arch.c.

◆ spi_deselect()

spi_status_t spi_deselect ( const spi_device_t dev)

Deselects the SPI peripheral.

Parameters
devAn SPI device configuration which defines the CS pin.
Returns
SPI return code

Sets the CS pin. Lock is not required.

Definition at line 80 of file spi.c.

Referenced by deselect().

◆ spi_has_bus()

bool spi_has_bus ( const spi_device_t dev)

Checks if a device has locked an SPI controller.

Parameters
devAn SPI device configuration which defines the controller.
Returns
true if the device has the lock, false otherwise.

Definition at line 88 of file spi.c.

◆ spi_read()

spi_status_t spi_read ( const spi_device_t dev,
uint8_t *  data,
int  size 
)

Reads a buffer from an SPI device.

Parameters
devAn SPI device configuration.
dataA pointer to the data
sizeSize of the data to read
Returns
SPI return code

It should work only if the device has already locked the SPI controller.

Definition at line 140 of file spi.c.

◆ spi_read_byte()

spi_status_t spi_read_byte ( const spi_device_t dev,
uint8_t *  data 
)

Reads a single byte from an SPI device.

Parameters
devAn SPI device configuration.
dataA pointer to a byte of data
Returns
SPI return code

It should work only if the device has already locked the SPI controller.

Definition at line 126 of file spi.c.

◆ spi_read_register()

spi_status_t spi_read_register ( const spi_device_t dev,
uint8_t  reg,
uint8_t *  data,
int  size 
)

Reads a buffer of bytes from a register of an SPI device.

Parameters
devAn SPI device configuration.
regRegister
dataA pointer to the data
sizeSize of the data to read
Returns
SPI return code

It should work only if the device has already locked the SPI controller.

Definition at line 192 of file spi.c.

◆ spi_read_skip()

spi_status_t spi_read_skip ( const spi_device_t dev,
int  size 
)

Reads and ignores data from an SPI device.

Parameters
devAn SPI device configuration.
sizeSize of the data to read and ignore
Returns
SPI return code

Reads size bytes from the SPI and throws them away. It should work only if the device has already locked the SPI controller.

Definition at line 154 of file spi.c.

◆ spi_release()

spi_status_t spi_release ( const spi_device_t dev)

Closes and then unlocks an SPI controller.

Parameters
devAn SPI device configuration which defines the controller to be closed and unlocked.
Returns
SPI return code

Releasing an SPI controller should put it in low-power mode. This should work only if the device has already locked the SPI controller.

Definition at line 57 of file spi.c.

Referenced by ext_flash_close().

◆ spi_select()

spi_status_t spi_select ( const spi_device_t dev)

Selects the SPI peripheral.

Parameters
devAn SPI device configuration which defines the CS pin.
Returns
SPI return code

Clears the CS pin. This should work only if the device has already locked the SPI controller.

Definition at line 68 of file spi.c.

References spi_arch_has_lock().

Referenced by select_on_bus().

◆ spi_strobe()

spi_status_t spi_strobe ( const spi_device_t dev,
uint8_t  strobe,
uint8_t *  status 
)

Reads and Writes one byte from/to an SPI device.

Parameters
devAn SPI device configuration.
strobeByte to write
statusPointer to byte to read
Returns
SPI return code

It should work only if the device has already locked the SPI controller.

Definition at line 215 of file spi.c.

◆ spi_transfer()

spi_status_t spi_transfer ( const spi_device_t dev,
const uint8_t *  data,
int  wsize,
uint8_t *  buf,
int  rsize,
int  ignore 
)

Performs a generic SPI transfer.

Parameters
devAn SPI device configuration.
dataA pointer to the data to be written. Set it to NULL to skip writing.
wsizeSize of data to write.
bufA pointer to buffer to copy the data read. Set to NULL to skip reading.
rsizeSize of data to read.
ignoreSize of data to read and ignore.
Returns
SPI return code

It should work only if the device has already locked the SPI controller. A total of rlen+ignore_len bytes will be read. The first rlen bytes will be copied to buf. The remaining ignore_len bytes won't be copied to the buffer. The maximum of wlen and rlen+ignore_len of bytes will be transfered.

Definition at line 168 of file spi.c.

◆ spi_write()

spi_status_t spi_write ( const spi_device_t dev,
const uint8_t *  data,
int  size 
)

Writes a buffer to an SPI device.

Parameters
devAn SPI device configuration.
dataA pointer to the data
sizeSize of the data to write
Returns
SPI return code

It should work only if the device has already locked the SPI controller.

Definition at line 112 of file spi.c.

Referenced by wait_ready(), and write_enable().

◆ spi_write_byte()

spi_status_t spi_write_byte ( const spi_device_t dev,
uint8_t  data 
)

Writes a single byte to an SPI device.

Parameters
devAn SPI device configuration.
dataA byte of data
Returns
SPI return code

It should work only if the device has already locked the SPI controller.

Definition at line 98 of file spi.c.