![]() |
CMSIS Driver
Version 1.10 - Preliminary
Middleware Driver API for microcontroller peripherals
|
Driver API for SPI Bus Master Peripheral in 8-bit mode (Driver_SPI.h) More...
Data Structures | |
struct | ARM_DRIVER_SPI |
Access structure of the SPI Driver. More... | |
struct | ARM_SPI_CAPABILITIES |
SPI Driver Capabilities. More... | |
Typedefs | |
typedef void(* | ARM_SPI_SignalEvent_t )(ARM_SPI_EVENT event) |
Pointer to ARM_SPI_SignalEvent : Signal SPI Event. | |
Enumerations | |
enum | ARM_SPI_STATUS { ARM_SPI_OK = 0, ARM_SPI_ERROR = 1, ARM_SPI_ERROR_UNSUPPORTED = 2 } |
SPI Status of executed operation. More... | |
enum | ARM_SPI_FRAME_FORMAT { ARM_SPI_CPOL0_CPHA0, ARM_SPI_CPOL0_CPHA1, ARM_SPI_CPOL1_CPHA0, ARM_SPI_CPOL1_CPHA1 } |
SPI Frame Format. More... | |
enum | ARM_SPI_BIT_ORDER { ARM_SPI_MSB_LSB, ARM_SPI_LSB_MSB } |
SPI Bit Order. More... | |
enum | ARM_SPI_SS_SIGNAL { ARM_SPI_SS_INACTIVE, ARM_SPI_SS_ACTIVE } |
SPI Slave Select Signal. More... | |
enum | ARM_SPI_EVENT { ARM_SPI_EVENT_SEND_DONE } |
SPI Event. More... | |
Functions | |
ARM_DRV_VERSION | ARM_SPI_GetVersion (void) |
Get driver version. | |
ARM_SPI_CAPABILITIES | ARM_SPI_GetCapabilities (void) |
Get driver capabilities. | |
ARM_SPI_STATUS | ARM_SPI_Initialize (ARM_SPI_SignalEvent_t cb_event) |
Initialize SPI Interface. | |
ARM_SPI_STATUS | ARM_SPI_Uninitialize (void) |
De-initialize SPI Interface. | |
ARM_SPI_STATUS | ARM_SPI_PowerControl (ARM_POWER_STATE state) |
Control SPI Interface Power. | |
ARM_SPI_STATUS | ARM_SPI_Configure (ARM_SPI_FRAME_FORMAT frame_format, ARM_SPI_BIT_ORDER bit_order) |
Configure SPI Interface. | |
uint32_t | ARM_SPI_BusSpeed (uint32_t bps) |
Set bus speed for SPI transfers. | |
ARM_SPI_STATUS | ARM_SPI_SlaveSelect (ARM_SPI_SS_SIGNAL ss) |
Control Slave Select (SS) signal. | |
uint8_t | ARM_SPI_TransferByte (uint8_t out) |
Send and receive one byte via SPI Interface. | |
ARM_SPI_STATUS | ARM_SPI_SendData (const uint8_t *buf, uint32_t len) |
Send data block to SPI Slave. | |
ARM_SPI_STATUS | ARM_SPI_ReceiveData (uint8_t *buf, uint32_t len, uint8_t out) |
Receive data block from SPI Slave. | |
ARM_SPI_STATUS | ARM_SPI_AbortTransfer (void) |
Abort current SPI transfer. | |
void | ARM_SPI_SignalEvent (ARM_SPI_EVENT event) |
Signal SPI Event. | |
Driver API for SPI Bus Master Peripheral in 8-bit mode (Driver_SPI.h)
The Serial Peripheral Interface Bus (SPI) implements a synchronous serial bus for data exchange. In microcontroller (MCU) applications, the interface is often used to connect peripheral components at board (PCB) level. SPI devices can operate as Master (SCLK and SS are outputs) or Slave (SCLK and SS are inputs). Wikipedia offers more information about the Serial Peripheral Interface Bus.
The SPI Driver API defines an SPI Master interface for middleware components. The SPI Driver supports multiple slaves, but if only one slave is connected, then the Slave Select signal can be omitted.
The SPI Driver functions control the following SPI signal lines.
Signal | Name | Description |
---|---|---|
SS | Slave Select (active low) | ARM_SPI_SlaveSelect controls this signal, which can be part of the SPI peripheral or implemented using a GPIO pin. |
MOSI | Master Out, Slave In | MOSI output of the Master connects to MOSI input of the Slave. |
SCLK | System Clock | Serial clock output from Master. Controls the transfer speed and when data are sent and read. |
MISO | Master In, Slave Out | MISO input of the Master connects to MISO input of the Slave. |
The following header files define the Application Programming Interface (API) for the SPI interface:
The driver implementation is a typical part of the Device Family Pack (DFP) that supports the peripherals of the microcontroller family.
The driver functions are published in the access struct as explained in Driver Functions
A typical setup sequence for the driver is shown below:
Example Code:
struct ARM_DRIVER_SPI |
Access structure of the SPI Driver.
The functions of the SPI driver are accessed by function pointers exposed by this structure. Refer to Driver Functions for overview information.
Each instance of an SPI interface provides such an access structure. The instance is identified by a postfix number in the symbol name of the access structure, for example:
A middleware configuration setting allows connecting the middleware to a specific driver instance ARM_DRIVER_SPIn. The default is 0, which connects a middleware to the first instance of a driver.
Data Fields | |
ARM_DRV_VERSION(* | GetVersion )(void) |
Pointer to ARM_SPI_GetVersion : Get driver version. | |
ARM_SPI_CAPABILITIES(* | GetCapabilities )(void) |
Pointer to ARM_SPI_GetCapabilities : Get driver capabilities. | |
ARM_SPI_STATUS(* | Initialize )(ARM_SPI_SignalEvent_t cb_event) |
Pointer to ARM_SPI_Initialize : Initialize SPI Interface. | |
ARM_SPI_STATUS(* | Uninitialize )(void) |
Pointer to ARM_SPI_Uninitialize : De-initialize SPI Interface. | |
ARM_SPI_STATUS(* | PowerControl )(ARM_POWER_STATE state) |
Pointer to ARM_SPI_PowerControl : Control SPI Interface Power. | |
ARM_SPI_STATUS(* | Configure )(ARM_SPI_FRAME_FORMAT frame_format, ARM_SPI_BIT_ORDER bit_order) |
Pointer to ARM_SPI_Configure : Configure SPI Interface. | |
uint32_t(* | BusSpeed )(uint32_t bps) |
Pointer to ARM_SPI_BusSpeed : Set bus speed for SPI transfers. | |
ARM_SPI_STATUS(* | SlaveSelect )(ARM_SPI_SS_SIGNAL ss) |
Pointer to ARM_SPI_SlaveSelect : Control Slave Select signal. | |
uint8_t(* | TransferByte )(uint8_t out) |
Pointer to ARM_SPI_TransferByte : Send and receive one byte via SPI Interface. | |
ARM_SPI_STATUS(* | SendData )(const uint8_t *buf, uint32_t len) |
Pointer to ARM_SPI_SendData : Send data block to SPI Slave. | |
ARM_SPI_STATUS(* | ReceiveData )(uint8_t *buf, uint32_t len, uint8_t out) |
Pointer to ARM_SPI_ReceiveData : Receive data block from SPI Slave. | |
ARM_SPI_STATUS(* | AbortTransfer )(void) |
Pointer to ARM_SPI_AbortTransfer : Abort current SPI transfer. | |
ARM_SPI_STATUS(* AbortTransfer)(void) |
Pointer to ARM_SPI_AbortTransfer : Abort current SPI transfer.
uint32_t(* BusSpeed)(uint32_t bps) |
Pointer to ARM_SPI_BusSpeed : Set bus speed for SPI transfers.
ARM_SPI_STATUS(* Configure)(ARM_SPI_FRAME_FORMAT frame_format, ARM_SPI_BIT_ORDER bit_order) |
Pointer to ARM_SPI_Configure : Configure SPI Interface.
ARM_SPI_CAPABILITIES(* GetCapabilities)(void) |
Pointer to ARM_SPI_GetCapabilities : Get driver capabilities.
ARM_DRV_VERSION(* GetVersion)(void) |
Pointer to ARM_SPI_GetVersion : Get driver version.
ARM_SPI_STATUS(* Initialize)(ARM_SPI_SignalEvent_t cb_event) |
Pointer to ARM_SPI_Initialize : Initialize SPI Interface.
ARM_SPI_STATUS(* PowerControl)(ARM_POWER_STATE state) |
Pointer to ARM_SPI_PowerControl : Control SPI Interface Power.
ARM_SPI_STATUS(* ReceiveData)(uint8_t *buf, uint32_t len, uint8_t out) |
Pointer to ARM_SPI_ReceiveData : Receive data block from SPI Slave.
ARM_SPI_STATUS(* SendData)(const uint8_t *buf, uint32_t len) |
Pointer to ARM_SPI_SendData : Send data block to SPI Slave.
ARM_SPI_STATUS(* SlaveSelect)(ARM_SPI_SS_SIGNAL ss) |
Pointer to ARM_SPI_SlaveSelect : Control Slave Select signal.
uint8_t(* TransferByte)(uint8_t out) |
Pointer to ARM_SPI_TransferByte : Send and receive one byte via SPI Interface.
ARM_SPI_STATUS(* Uninitialize)(void) |
Pointer to ARM_SPI_Uninitialize : De-initialize SPI Interface.
struct ARM_SPI_CAPABILITIES |
SPI Driver Capabilities.
An SPI driver can be implemented with different capabilities. The bitfield members of this struct encode the capabilities implemented by this driver.
Returned by:
Data Fields | ||
---|---|---|
uint32_t | reserved: 31 | reserved for future use |
uint32_t | send_done_event: 1 | Signal send data completed: ARM_SPI_EVENT_SEND_DONE. |
ARM_SPI_SignalEvent_t |
Pointer to ARM_SPI_SignalEvent : Signal SPI Event.
Provides the typedef for the callback function ARM_SPI_SignalEvent.
Parameter for:
enum ARM_SPI_BIT_ORDER |
SPI Bit Order.
Specifies whether SPI data transmission starts with the LSB bit or MSB bit.
Parameter for:
enum ARM_SPI_EVENT |
SPI Event.
Provides values for for the ARM_SPI_SignalEvent callback function (which is registered by the function ARM_SPI_Initialize). The function ARM_SPI_GetCapabilities returns information about the implemented callback events in a driver.
enum ARM_SPI_FRAME_FORMAT |
SPI Frame Format.
Specifies the clock polarity and the phase for SPI data transmissions.
Parameter for:
enum ARM_SPI_SS_SIGNAL |
SPI Slave Select Signal.
Lists values for controlling slave select signals.
Parameter for:
enum ARM_SPI_STATUS |
SPI Status of executed operation.
Defines status and error codes returned by most of the MCI driver functions.
Returned by:
ARM_SPI_STATUS ARM_SPI_AbortTransfer | ( | void | ) |
Abort current SPI transfer.
Stop an ongoing SPI data transfer operation that was initiated with the function ARM_SPI_ReceiveData or ARM_SPI_SendData.
uint32_t ARM_SPI_BusSpeed | ( | uint32_t | bps | ) |
Set bus speed for SPI transfers.
[in] | bps | Requested speed in bits/s |
Set the data transfer speed of the SPI to the requested baud rate in bits per second.
ARM_SPI_STATUS ARM_SPI_Configure | ( | ARM_SPI_FRAME_FORMAT | frame_format, |
ARM_SPI_BIT_ORDER | bit_order | ||
) |
Configure SPI Interface.
[in] | frame_format | ARM_SPI_FRAME_FORMAT |
[in] | bit_order | ARM_SPI_BIT_ORDER |
Configure the frame format and the bit order of the SPI data transfer.
ARM_SPI_CAPABILITIES ARM_SPI_GetCapabilities | ( | void | ) |
Get driver capabilities.
Retrieves information about capabilities in this driver implementation. The bitfield members of the struct ARM_SPI_CAPABILITIES encode various capabilities, for example if a hardware is capable of signaling events using the ARM_SPI_SignalEvent callback function.
Example:
ARM_DRV_VERSION ARM_SPI_GetVersion | ( | void | ) |
Get driver version.
Returns version information of the driver implementation in ARM_DRV_VERSION
Example:
ARM_SPI_STATUS ARM_SPI_Initialize | ( | ARM_SPI_SignalEvent_t | cb_event | ) |
Initialize SPI Interface.
[in] | cb_event | Pointer to ARM_SPI_SignalEvent |
The function initializes the SPI interface. It is called when the middleware component starts operation.
The function performs the following operations:
The parameter cb_event is a pointer to the ARM_SPI_SignalEvent callback function; use a NULL pointer when no callback signals are required.
Example:
ARM_SPI_STATUS ARM_SPI_PowerControl | ( | ARM_POWER_STATE | state | ) |
Control SPI Interface Power.
[in] | state | Power state |
Allows to control the power modes of the SPI interface.
state can be:
If state specifies an unsupported mode, the function returns ARM_SPI_ERROR_UNSUPPORTED.
ARM_SPI_STATUS ARM_SPI_ReceiveData | ( | uint8_t * | buf, |
uint32_t | len, | ||
uint8_t | out | ||
) |
Receive data block from SPI Slave.
[out] | buf | Pointer to the buffer for receiving data |
[in] | len | Data buffer length in bytes |
[in] | out | Byte to be sent repeatedly during receive |
Receive a data block from the SPI Slave and store the content in a data buffer.
ARM_SPI_STATUS ARM_SPI_SendData | ( | const uint8_t * | buf, |
uint32_t | len | ||
) |
Send data block to SPI Slave.
[in] | buf | Pointer to the buffer containing data to send |
[in] | len | Data buffer length in bytes |
Send the content of a data buffer to the SPI Slave.
The function may return even when not all data are transferred, but it is ensured that the content in the data buffer is fully consumed and transferred to internal buffers on function return.
void ARM_SPI_SignalEvent | ( | ARM_SPI_EVENT | event | ) |
Signal SPI Event.
[in] | event | ARM_SPI_EVENT |
Signal that an ARM_SPI_SendData operation has been completed. This optional call back function is implemented in the middleware and published to the driver by the function ARM_SPI_Initialize.
ARM_SPI_STATUS ARM_SPI_SlaveSelect | ( | ARM_SPI_SS_SIGNAL | ss | ) |
Control Slave Select (SS) signal.
[in] | ss | Slave Select status ARM_SPI_SS_SIGNAL |
Control the Slave Select (SS) output of the SPI interface. The function also sets the SPI to the active or inactive state. It is mandatory also when then SPI does not provide an SS output.
uint8_t ARM_SPI_TransferByte | ( | uint8_t | out | ) |
Send and receive one byte via SPI Interface.
[in] | out | Byte to be sent to the SPI data output |
Send and receive one byte via the SPI Interface.
ARM_SPI_STATUS ARM_SPI_Uninitialize | ( | void | ) |
De-initialize SPI Interface.
The function ARM_SPI_Uninitialize de-initializes the resources of SPI interface and sets the peripheral to ARM_POWER_LOW power mode.
It is called when the middleware component stops operation and releases the software resources used by the interface.