# SPI - [Overview](#section652650751165623) - [Summary](#section1949059107165623) - [Files](#files) - [Data Structures](#nested-classes) - [Macros](#define-members) - [Enumerations](#enum-members) - [Functions](#func-members) - [Details](#section1765579536165623) - [Macro Definition](#section1272510252165623) - [SPI\_CLK\_PHASE](#ga430ad9ccffd42f4427ba22fcc8167c64) - [SPI\_CLK\_POLARITY](#ga4cafe948918622f80c27db640c6c23c6) - [SPI\_MODE\_3WIRE](#ga11113e647ddd2101c1c693632f63aa7c) - [SPI\_MODE\_CS\_HIGH](#ga33d89d81eb33b7a5de1a03e88279163d) - [SPI\_MODE\_LOOP](#ga8619b297de563eca6852af34c79daa62) - [SPI\_MODE\_LSBFE](#ga4da8777b0d2d7dd96d6038411791c36e) - [SPI\_MODE\_NOCS](#ga361195644b8e753d5469dd492c66217b) - [SPI\_MODE\_READY](#ga42f3ef9ad5429ac10662448fe1f5a746) - [Enumeration Type](#section1553762052165623) - [SpiTransferMode](#ga55946d1d895fc2b7b33007019de1668f) - [Function](#section496230935165623) - [SpiClose\(\)](#ga4c961307ea89008ba0f064c92eb1617d) - [SpiGetCfg\(\)](#ga77d533d55c550c4478185a02a4e12fb1) - [SpiOpen\(\)](#ga193e808f7e68a5b4c6b71ca2db47a11f) - [SpiRead\(\)](#gaa860e42dac8b2caabefda6e82ba1a541) - [SpiSetCfg\(\)](#gafbca6de683781921a8d1cb41ead0030e) - [SpiTransfer\(\)](#gaf9226a2ce4ff75c7dc76279b3bbd7af4) - [SpiWrite\(\)](#ga0073b24fba24fb37b3ea451a0c7d911f) ## **Overview** **Description:** Defines standard APIs of the Serial Peripheral Interface \(SPI\) capabilities. The SPI module abstracts the SPI capabilities of different system platforms to provide stable APIs for driver development. This module can create and destroy SPI device handles, read and write SPI data, and obtain and set configuration parameters. **Since:** 1.0 ## **Summary** ## Files

File Name

Description

spi_if.h

Defines standard SPI-specific interfaces for driver development.

## Data Structures

Data Structure Name

Description

SpiDevInfo

Defines the general SPI device descriptor, which can be used as the unique identifier of an SPI device. When operating an SPI device, you need to specify a descriptor of the SpiDevInfo type, and obtain the handle of the SPI device by calling SpiOpen.

SpiMsg

Defines the custom SPI transfer message.

SpiCfg

Defines the configuration of an SPI device.

## Macros

Macro Name and Value

Description

SPI_CLK_PHASE (1 << 0)

Indicates the SPI clock phase. The value 0 indicates that data will be sampled on the first clock edge, and 1 indicates that data will be sampled on the second clock edge.

SPI_CLK_POLARITY (1 << 1)

Indicates the SPI clock polarity. The value 0 indicates a low-level clock signal in the idle state, and 1 indicates a high-level clock signal in the idle state.

SPI_MODE_3WIRE (1 << 2)

Indicates that a single data line is used for both input and output.

SPI_MODE_LOOP (1 << 3)

Indicates the SPI loopback mode.

SPI_MODE_LSBFE (1 << 4)

Indicates the SPI data transfer order. The value 0 indicates that data is transferred from the most significant bit (MSB) to the least significant bit (LSB), and 1 indicates the opposite.

SPI_MODE_NOCS (1 << 5)

Indicates that there is only one SPI device, and no chip select (CS) is required.

SPI_MODE_CS_HIGH (1 << 6)

Indicates that the CS level is high when an SPI device is selected.

SPI_MODE_READY (1 << 7)

Indicates that the SPI device is set to low for pausing data transfer.

## Enumerations

Enumeration Name

Description

SpiTransferMode { SPI_INTERRUPT_TRANSFER = 0, SPI_POLLING_TRANSFER, SPI_DMA_TRANSFER }

Enumerates transfer modes of SPI data.

## Functions

Function

Description

SpiOpen (const struct SpiDevInfo *info)

DevHandle

Obtains the handle of an SPI device.

SpiClose (DevHandle handle)

void

Releases the handle of an SPI device.

SpiTransfer (DevHandle handle, struct SpiMsg *msgs, uint32_t count)

int32_t

Launches a custom transfer to an SPI device.

SpiRead (DevHandle handle, uint8_t *buf, uint32_t len)

int32_t

Reads data of a specified length from an SPI device.

SpiWrite (DevHandle handle, uint8_t *buf, uint32_t len)

int32_t

Writes data of a specified length to an SPI device.

SpiSetCfg (DevHandle handle, struct SpiCfg *cfg)

int32_t

Sets configuration parameters for an SPI device.

SpiGetCfg (DevHandle handle, struct SpiCfg *cfg)

int32_t

Obtains the configuration parameters of an SPI device.

## **Details** ## **Macro Definition ** ## SPI\_CLK\_PHASE ``` #define SPI_CLK_PHASE (1 << 0) ``` **Description:** Indicates the SPI clock phase. The value **0** indicates that data will be sampled on the first clock edge, and **1** indicates that data will be sampled on the second clock edge. ## SPI\_CLK\_POLARITY ``` #define SPI_CLK_POLARITY (1 << 1) ``` **Description:** Indicates the SPI clock polarity. The value **0** indicates a low-level clock signal in the idle state, and **1** indicates a high-level clock signal in the idle state. ## SPI\_MODE\_3WIRE ``` #define SPI_MODE_3WIRE (1 << 2) ``` **Description:** Indicates that a single data line is used for both input and output. ## SPI\_MODE\_CS\_HIGH ``` #define SPI_MODE_CS_HIGH (1 << 6) ``` **Description:** Indicates that the CS level is high when an SPI device is selected. ## SPI\_MODE\_LOOP ``` #define SPI_MODE_LOOP (1 << 3) ``` **Description:** Indicates the SPI loopback mode. ## SPI\_MODE\_LSBFE ``` #define SPI_MODE_LSBFE (1 << 4) ``` **Description:** Indicates the SPI data transfer order. The value **0** indicates that data is transferred from the most significant bit \(MSB\) to the least significant bit \(LSB\), and **1** indicates the opposite. ## SPI\_MODE\_NOCS ``` #define SPI_MODE_NOCS (1 << 5) ``` **Description:** Indicates that there is only one SPI device, and no chip select \(CS\) is required. ## SPI\_MODE\_READY ``` #define SPI_MODE_READY (1 << 7) ``` **Description:** Indicates that the SPI device is set to low for pausing data transfer. ## **Enumeration Type ** ## SpiTransferMode ``` enum [SpiTransferMode](SPI.md#ga55946d1d895fc2b7b33007019de1668f) ``` **Description:** Enumerates transfer modes of SPI data. **Attention:** The specific SPI controller determines which variables in this structure are supported.

Enumerator

Description
SPI_INTERRUPT_TRANSFER

Interrupt transfer mode

SPI_POLLING_TRANSFER

Polling transfer mode

SPI_DMA_TRANSFER

Direct Memory Access (DMA) transfer mode

## **Function ** ## SpiClose\(\) ``` void SpiClose ([DevHandle](COMMON.md#gab8c2d38e46eec50bd097a27d3d8bf041) handle) ``` **Description:** Releases the handle of an SPI device. **Parameters:**

Name

Description
handle Indicates the pointer to the SPI device handle obtained via SpiOpen.
## SpiGetCfg\(\) ``` int32_t SpiGetCfg ([DevHandle](COMMON.md#gab8c2d38e46eec50bd097a27d3d8bf041) handle, struct [SpiCfg](SpiCfg.md) * cfg ) ``` **Description:** Obtains the configuration parameters of an SPI device. **Parameters:**

Name

Description
handle Indicates the pointer to the SPI device handle obtained via SpiOpen.
cfg Indicates the pointer to the configuration parameters.
**Returns:** Returns **0** if the operation is successful; returns a negative value otherwise. ## SpiOpen\(\) ``` [DevHandle](COMMON.md#gab8c2d38e46eec50bd097a27d3d8bf041) SpiOpen (const struct [SpiDevInfo](SpiDevInfo.md) * info) ``` **Description:** Obtains the handle of an SPI device. **Parameters:**

Name

Description
info Indicates the pointer to the SPI device information.
**Returns:** Returns the pointer to the handle of the SPI device if the operation is successful; returns **NULL** otherwise. ## SpiRead\(\) ``` int32_t SpiRead ([DevHandle](COMMON.md#gab8c2d38e46eec50bd097a27d3d8bf041) handle, uint8_t * buf, uint32_t len ) ``` **Description:** Reads data of a specified length from an SPI device. **Parameters:**

Name

Description
handle Indicates the pointer to the SPI device handle obtained via SpiOpen.
buf Indicates the pointer to the buffer for receiving the data.
len Indicates the length of the data to read.
**Returns:** Returns **0** if the operation is successful; returns a negative value otherwise. ## SpiSetCfg\(\) ``` int32_t SpiSetCfg ([DevHandle](COMMON.md#gab8c2d38e46eec50bd097a27d3d8bf041) handle, struct [SpiCfg](SpiCfg.md) * cfg ) ``` **Description:** Sets configuration parameters for an SPI device. **Parameters:**

Name

Description
handle Indicates the pointer to the SPI device handle obtained via SpiOpen.
cfg Indicates the pointer to the configuration parameters.
**Returns:** Returns **0** if the operation is successful; returns a negative value otherwise. ## SpiTransfer\(\) ``` int32_t SpiTransfer ([DevHandle](COMMON.md#gab8c2d38e46eec50bd097a27d3d8bf041) handle, struct [SpiMsg](SpiMsg.md) * msgs, uint32_t count ) ``` **Description:** Launches a custom transfer to an SPI device. **Parameters:**

Name

Description
handle Indicates the pointer to the SPI device handle obtained via SpiOpen.
msgs Indicates the pointer to the data to transfer.
count Indicates the length of the message structure array.
**Returns:** Returns **0** if the operation is successful; returns a negative value otherwise. **See also:** [SpiMsg](SpiMsg.md) ## SpiWrite\(\) ``` int32_t SpiWrite ([DevHandle](COMMON.md#gab8c2d38e46eec50bd097a27d3d8bf041) handle, uint8_t * buf, uint32_t len ) ``` **Description:** Writes data of a specified length to an SPI device. **Parameters:**

Name

Description
handle Indicates the pointer to the SPI device handle obtained via SpiOpen.
buf Indicates the pointer to the data to write.
len Indicates the length of the data to write.
**Returns:** Returns **0** if the operation is successful; returns a negative value otherwise.