SPI API

Defines

K_NUM_SPI YOTTA_CFG_HARDWARE_SPI_COUNT

Number of SPI buses available.

This value is derived from the platform specific target.json file.

Snippet from target.json:

"config": {
  "hardware": {
    "spi": {
      "count": 2
    }
  }
}

DEFAULT_SPI YOTTA_CFG_HARDWARE_SPI_DEFAULTS_BUS

Default SPI bus.

This value is derived from the platform specific target.json file. It is possible to override it in a project’s config.json.

Example of overriding via config.json:

"hardware": {
  "spi": {
    "defaults": {
       "bus": "K_SPI1"
     }
  }
}

Enums

enum KSPINum

Available SPI buses.

The number of buses defined in this enumeration is controlled by the number of SPI buses defined in the platform’s target.json file.

Values:

K_SPI_NO_BUS = 0

enum SPIRole

SPI bus roles.

Warning

Only the Master role is available as of v0.1.0

Values:

K_SPI_MASTER = 0

K_SPI_SLAVE

enum SPIDirection

SPI bus direction modes.

Note

MSP430F5 does not support 1-line mode

Values:

K_SPI_DIRECTION_2LINES = 0

K_SPI_DIRECTION_2LINES_RXONLY

K_SPI_DIRECTION_1LINE

enum SPIDataSize

SPI bus data sizes.

Note

MSP430F5 does not support 16-bit mode

Values:

K_SPI_DATASIZE_8BIT = 0

K_SPI_DATASIZE_16BIT

enum SPIClockPolarity

SPI bus clock polarities.

Values:

K_SPI_CPOL_LOW = 0

K_SPI_CPOL_HIGH

enum SPIClockPhase

SPI bus clock phases.

Values:

K_SPI_CPHA_1EDGE = 0

K_SPI_CPHA_2EDGE

enum SPIFirstBit

SPI bus first bit order/endianess.

Values:

K_SPI_FIRSTBIT_MSB = 0

K_SPI_FIRSTBIT_LSB

enum KSPIStatus

SPI return status values.

This enumeration is intended to be the primary return status of the functions in this SPI interface.

Values:

SPI_OK

SPI_ERROR

SPI_ERROR_BUSY

SPI_ERROR_TIMEOUT

SPI_ERROR_NULL_HANDLE

SPI_ERROR_CONFIG

Functions

void k_spi_init(KSPINum spi, KSPIConf *conf)

Configures and enables a SPI bus.

This function is used to configure and enable SPI buses for further usage (reading/writing). Calling this function is always the first step before using any SPI peripheral. This function takes a SPI bus number (KSPINum) and SPI configuration structure (KSPIConf). The SPI bus number must be a valid value from the KSPINum enum. The configuration can either be created manually or k_spi_conf_defaults can be used to retreive the default configuration.

After calling k_spi_init, the initalized bus can be used with the k_spi_read/k_spi_write/k_spi_terminate functions.

Example usage:

KSPIConf conf = {
    .role = K_SPI_MASTER,
    .direction = K_SPI_DIRECTION_2LINES,
    .data_size = K_SPI_DATASIZE_8BIT,
    .clock_polarity = K_SPI_CPOL_HIGH,
    .clock_phase = K_SPI_CPHA_1EDGE,
    .first_bit = K_SPI_FIRSTBIT_LSB,
    .speed = 100000
};

k_spi_init(K_SPI1, &conf);

Note

This function delegates the low-level initialization to the platform specific kprv_spi_dev_init

Parameters

• spi: number spi bus to initialize
• conf: config values to initialize with

void k_spi_terminate(KSPINum spi)

Terminates a SPI bus.

This function is used to terminate an active SPI bus. After calling this function, the bus number used will not be available for usage in reading/writing functions.

Example usage:

// init bus
k_spi_init(K_SPI1, &conf);

// read some data
k_spi_read(K_SPI1, buffer, length);

// shut down bus
k_spi_terminate(K_SPI1);

Note

This function delegates the low-level termination to the platform specific kprv_spi_dev_terminate

Parameters

• spi: spi bus to terminate

KSPIConf k_spi_conf_defaults(void)

Returns a copy of the default SPI configuration.

This function returns a SPIConf structure with the default SPI configuration values already set. These default values are derived from the platform’s target.json. New default values can easily be set by creating a config.json in the project directory.

Example contents of config.json overriding defaults:

"hardware": {
   "spi": {
     "defaults": {
       "bus": "K_SPI1",
       "role": "K_SPI_MASTER",
       "direction": "K_SPI_DIRECTION_2LINES",
       "dataSize": "K_SPI_DATASIZE_8BIT",
       "clockPolarity": "K_SPI_CPOL_HIGH",
       "clockPhase": "K_SPI_CPHA_1EDGE",
       "firstBit": "K_SPI_FIRSTBIT_LSB",
       "speed": "10000"
     }
   }
}

Return

KSPIConf structure containing default config

KSPIStatus k_spi_write(KSPINum spi, uint8_t *buffer, uint32_t len)

Write data over specified SPI bus.

This function writes data over the specified SPI bus.

Example usage:

uint8_t buffer[10];
KSPIStatus write_status;

// init SPI bus
k_spi_init(K_SPI1, &conf);

// custom chip select function
chip_select(SPI_CS1);

write_status = k_spi_write(K_SPI1, buffer, 10);

// custom chip select function
chip_deselect(SPI_CS1);

Warning

This function does not handle the chip select line. The user is responsible for selecting the correct line.

Note

In order to ensure safe spi sharing, this function is semaphore locked. There is one semaphore per bus. This function will block indefinitely while waiting for the semaphore.

Note

This function delegates the low-level actions to the platform specific kprv_spi_write.

Return

KSPIStatus SPI_OK on success, otherwise failure

Parameters

• spi: spi bus to write to
• buffer: pointer to data buffer
• len: length of data to write

KSPIStatus k_spi_read(KSPINum spi, uint8_t *buffer, uint32_t len)

Reads data over specified SPI bus.

Example usage:

uint8_t buffer[10];
KSPIStatus read_status;

// init SPI bus
k_spi_init(K_SPI1, &conf);

// custom chip select function
chip_select(SPI_CS1);

read_status = k_spi_read(K_SPI1, buffer, 10);

// custom chip select function
chip_deselect(SPI_CS1);

Warning

This function does not handle the chip select line. The user is responsible for selecting the correct line.

Note

In order to ensure safe spi sharing, this function is semaphore locked. There is one semaphore per bus. This function will block indefinitely while waiting for the semaphore.

Note

This function delegates the low-level actions to the platform specific kprv_spi_read.

Return

KSPIStatus SPI_OK on success, otherwise failure

Parameters

• spi: spi bus to read from
• buffer: pointer to data buffer
• len: length of data to read

KSPIStatus k_spi_write_read(KSPINum spi, uint8_t *txBuffer, uint8_t *rxBuffer, uint32_t len)

Writes and reads data over SPI bus.

Example usage:

uint8_t read_buffer[10];
uint8_t write_buffer[10];
KSPIStatus read_status;

// init SPI bus
k_spi_init(K_SPI1, &conf);

// custom chip select function
chip_select(SPI_CS1);

read_status = k_spi_write_read(K_SPI1, write_buffer, read_buffer, 10);

// custom chip select function
chip_deselect(SPI_CS1);

Warning

This function does not handle the chip select line. The user is responsible for selecting the correct line.

Note

In order to ensure safe spi sharing, this function is semaphore locked. There is one semaphore per bus. This function will block indefinitely while waiting for the semaphore.

Note

This function delegates the low-level actions to the platform specific kprv_spi_write_read.

Return

KSPIStatus SPI_OK on success, otherwise failure

Parameters

• spi: spi bus to write to
• txBuffer: pointer to data buffer to write from
• rxBuffer: pointer to data buffer to read into
• len: length of data to write and read

KSPI *kprv_spi_get(KSPINum spi)

Fetches SPI bus data structure.

This function takes a SPI bus number and retrieves the bus data/config structure from the HAL’s internal static array.

Return

KSPI* pointer to data structure

Parameters

• spi: number of spi bus to fetch

KSPIStatus kprv_spi_write(KSPINum spi, uint8_t *buffer, uint32_t len)

Low-level SPI write.

This function is called by k_spi_write and is intended to perform the necessary low-level actions for a SPI write.

Note

This function must be implemented by each platform specific HAL

Return

KSPIStatus SPI_OK on success, otherwise failure

Parameters

• spi: spi bus to write to
• buffer: pointer to data buffer
• len: length of data to write

KSPIStatus kprv_spi_read(KSPINum spi, uint8_t *buffer, uint32_t len)

Low-level SPI read.

This function is called by k_spi_read and is intended to perform the necessary low-level actions for a SPI read.

Note

This function must be implemented by each platform specific HAL

Return

KSPIStatus SPI_OK on success, otherwise failure

Parameters

• spi: spi bus to read from
• buffer: pointer to data buffer
• len: length of data to read

KSPIStatus kprv_spi_write_read(KSPINum spi, uint8_t *txBuffer, uint8_t *rxBuffer, uint32_t len)

Low-level SPI write and read.

This function is called by k_spi_write_read and is intended to perform the necessary low-level actions for a SPI write and read.

Note

This function must be implemented by each platform specific HAL

Return

KSPIStatus SPI_OK on success, otherwise failure

Parameters

• spi: spi bus to write to
• txBuffer: pointer to data buffer to write from
• rxBuffer: pointer to data buffer to read into
• len: length of data to write and read

KSPIStatus kprv_spi_dev_init(KSPINum spi)

Low-level SPI bus initialization.

This function is called by k_spi_init and is intended to perform the necessary low-level initialization and configuration of a SPI bus.

Note

This function must be implemented by each platform specific HAL

Return

KSPIStatus SPI_OK on success, otherwise failure

Parameters

• spi: spi bus to initialize

KSPIStatus kprv_spi_dev_terminate(KSPINum spi)

Low-level SPI bus termination.

This function is called by k_spi_terminate and is intended to perform the necessary low-level actios to power-down and disable a SPI bus.

Note

This function must be implemented by each platform specific HAL

Return

KSPIStatus SPI_OK on success, otherwise failure

Parameters

• spi: spi bus to terminate

struct KSPIConf

#include <spi.h>

SPI configuration structure.

Public Members

SPIRole role

The role of the SPI bus.

Should be either master or slave, as specified by the SPIRole enumerator

Warning

Only the Master role is available as of v0.1.0

SPIDirection direction

The communication mode of the SPI bus.

Can be 2-wire Rx/Tx, 2-wire Rx only, or 1-wire bidirectional, as specified by the SPIDirection enumerator

SPIDataSize data_size

The amount of data in each transmit/receive of the SPI bus.

Can either send 8-bits at a time or 16-bits, as specified by the SPIDataSize enumerator

SPIClockPhase clock_phase

The clock phase of the SPI bus.

Can either be low (idle state = 0, active state = 1), or high (idle state = 1, active state = 0), as specified by the SPIClockPhase enumerator

SPIClockPolarity clock_polarity

The clock polarity of the SPI bus.

Can either be the first edge (falling if clock phase is high, rising if clock phase is low), or second edge (rising if clock phase is high, falling if clock phase is low), as specified by the SPIClockPolarity enumerator

SPIFirstBit first_bit

The bit ordering of the SPI bus communication.

Can be either least-significant bit first, or most-significant, as specified by the SPIFirstBit enumerator

uint32_t speed

The baud rate of the SPI bus.

Warning

For the STM32F4 and MSP430F5 microcontrollers, the speed of the SPI bus can only be defined as a factor of the peripheral clock to which it’s connected (PCLK1 for STM32F4 SPI bus 2 and 3, PCLK2 for STM32F4 SPI bus 1, SMCLK for MSP430F5 SPI buses). For example, PCLK_speed / 2. To make things easier, this speed field will take a normal baud rate number and then it will automatically be converted to the nearest available system speed without exceeding the original value. For example: Given conf.speed = 10MHz, PCLK_speed = 84MHz The closest speed without going over is 5.25Mhz (PCLK_speed / 16), so this is what the SPI bus speed will be set to.

struct KSPI

#include <spi.h>

SPI bus data structure.

The SPI interface holds a static array of these structures, one for each possible SPI bus.

Public Members

KSPIConf config

SPI interface configuration values.

KSPINum bus_num

Number of SPI interface.

csp_mutex_t spi_lock

Mutex used to lock access to SPI device.