![]() |
CMSIS-Driver
Version 2.02
Peripheral Interface for Middleware and Application Code
|
Driver API for SPI Bus Peripheral (Driver_SPI.h) More...
Content | |
Status Error Codes | |
Negative values indicate errors (SPI has specific codes in addition to common Status Error Codes). | |
SPI Events | |
The SPI driver generates call back events that are notified via the function ARM_SPI_SignalEvent. | |
SPI Control Codes | |
Many parameters of the SPI driver are configured using the ARM_SPI_Control function. | |
Data Structures | |
struct | ARM_DRIVER_SPI |
Access structure of the SPI Driver. More... | |
struct | ARM_SPI_CAPABILITIES |
SPI Driver Capabilities. More... | |
struct | ARM_SPI_STATUS |
SPI Status. More... | |
Typedefs | |
typedef void(* | ARM_SPI_SignalEvent_t )(uint32_t event) |
Pointer to ARM_SPI_SignalEvent : Signal SPI Event. | |
Functions | |
ARM_DRIVER_VERSION | ARM_SPI_GetVersion (void) |
Get driver version. | |
ARM_SPI_CAPABILITIES | ARM_SPI_GetCapabilities (void) |
Get driver capabilities. | |
int32_t | ARM_SPI_Initialize (ARM_SPI_SignalEvent_t cb_event) |
Initialize SPI Interface. | |
int32_t | ARM_SPI_Uninitialize (void) |
De-initialize SPI Interface. | |
int32_t | ARM_SPI_PowerControl (ARM_POWER_STATE state) |
Control SPI Interface Power. | |
int32_t | ARM_SPI_Send (const void *data, uint32_t num) |
Start sending data to SPI transmitter. | |
int32_t | ARM_SPI_Receive (void *data, uint32_t num) |
Start receiving data from SPI receiver. | |
int32_t | ARM_SPI_Transfer (const void *data_out, void *data_in, uint32_t num) |
Start sending/receiving data to/from SPI transmitter/receiver. | |
uint32_t | ARM_SPI_GetDataCount (void) |
Get transferred data count. | |
int32_t | ARM_SPI_Control (uint32_t control, uint32_t arg) |
Control SPI Interface. | |
ARM_SPI_STATUS | ARM_SPI_GetStatus (void) |
Get SPI status. | |
void | ARM_SPI_SignalEvent (uint32_t event) |
Signal SPI Events. | |
Driver API for SPI Bus Peripheral (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.
SPI Structure
The SPI Driver API defines a SPI 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) | Selects the slave. This signal 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 | Serial 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 output of the Slave. |
SPI API
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.
Driver Functions
The driver functions are published in the access struct as explained in Driver Functions
Example Code
The following example code shows the usage of the SPI interface.
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 a 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 Driver_SPIn. The default is 0, which connects a middleware to the first instance of a driver.
Data Fields | |
ARM_DRIVER_VERSION(* | GetVersion )(void) |
Pointer to ARM_SPI_GetVersion : Get driver version. | |
ARM_SPI_CAPABILITIES(* | GetCapabilities )(void) |
Pointer to ARM_SPI_GetCapabilities : Get driver capabilities. | |
int32_t(* | Initialize )(ARM_SPI_SignalEvent_t cb_event) |
Pointer to ARM_SPI_Initialize : Initialize SPI Interface. | |
int32_t(* | Uninitialize )(void) |
Pointer to ARM_SPI_Uninitialize : De-initialize SPI Interface. | |
int32_t(* | PowerControl )(ARM_POWER_STATE state) |
Pointer to ARM_SPI_PowerControl : Control SPI Interface Power. | |
int32_t(* | Send )(const void *data, uint32_t num) |
Pointer to ARM_SPI_Send : Start sending data to SPI Interface. | |
int32_t(* | Receive )(void *data, uint32_t num) |
Pointer to ARM_SPI_Receive : Start receiving data from SPI Interface. | |
int32_t(* | Transfer )(const void *data_out, void *data_in, uint32_t num) |
Pointer to ARM_SPI_Transfer : Start sending/receiving data to/from SPI. | |
uint32_t(* | GetDataCount )(void) |
Pointer to ARM_SPI_GetDataCount : Get transferred data count. | |
int32_t(* | Control )(uint32_t control, uint32_t arg) |
Pointer to ARM_SPI_Control : Control SPI Interface. | |
ARM_SPI_STATUS(* | GetStatus )(void) |
Pointer to ARM_SPI_GetStatus : Get SPI status. | |
int32_t(* Control)(uint32_t control, uint32_t arg) |
Pointer to ARM_SPI_Control : Control SPI Interface.
ARM_SPI_CAPABILITIES(* GetCapabilities)(void) |
Pointer to ARM_SPI_GetCapabilities : Get driver capabilities.
uint32_t(* GetDataCount)(void) |
Pointer to ARM_SPI_GetDataCount : Get transferred data count.
ARM_SPI_STATUS(* GetStatus)(void) |
Pointer to ARM_SPI_GetStatus : Get SPI status.
ARM_DRIVER_VERSION(* GetVersion)(void) |
Pointer to ARM_SPI_GetVersion : Get driver version.
int32_t(* Initialize)(ARM_SPI_SignalEvent_t cb_event) |
Pointer to ARM_SPI_Initialize : Initialize SPI Interface.
int32_t(* PowerControl)(ARM_POWER_STATE state) |
Pointer to ARM_SPI_PowerControl : Control SPI Interface Power.
int32_t(* Receive)(void *data, uint32_t num) |
Pointer to ARM_SPI_Receive : Start receiving data from SPI Interface.
int32_t(* Send)(const void *data, uint32_t num) |
Pointer to ARM_SPI_Send : Start sending data to SPI Interface.
int32_t(* Transfer)(const void *data_out, void *data_in, uint32_t num) |
Pointer to ARM_SPI_Transfer : Start sending/receiving data to/from SPI.
int32_t(* Uninitialize)(void) |
Pointer to ARM_SPI_Uninitialize : De-initialize SPI Interface.
struct ARM_SPI_CAPABILITIES |
SPI Driver Capabilities.
A 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 | event_mode_fault: 1 | Signal Mode Fault event: ARM_SPI_EVENT_MODE_FAULT. |
uint32_t | microwire: 1 | supports Microwire Interface |
uint32_t | simplex: 1 | supports Simplex Mode (Master and Slave) |
uint32_t | ti_ssi: 1 | supports TI Synchronous Serial Interface |
struct ARM_SPI_STATUS |
SPI Status.
Structure with information about the status of the SPI. The bitfields encode busy flag and error flags.
Returned by:
ARM_SPI_SignalEvent_t |
Pointer to ARM_SPI_SignalEvent : Signal SPI Event.
Provides the typedef for the callback function ARM_SPI_SignalEvent.
Parameter for:
int32_t ARM_SPI_Control | ( | uint32_t | control, |
uint32_t | arg | ||
) |
Control SPI Interface.
[in] | control | Operation |
[in] | arg | Argument of operation (optional) |
Controls the SPI interface settings and executes various operations.
The parameter control is a bit mask that specifies various operations (see tables below). The control bits of the various groups can be combined to a control code as shown in the following example. Depending on the control bits, the parameter arg provides additional information, for example the baudrate.
Example
ARM_SPI_MODE_xxx specifies the SPI mode.
Mode Control Bits | Description |
---|---|
ARM_SPI_MODE_INACTIVE | Set SPI to inactive. |
ARM_SPI_MODE_MASTER | Set the SPI Master (Output on MOSI, and the Input on MISO); arg = Bus Speed in bps |
ARM_SPI_MODE_SLAVE | Set the SPI Slave (Output on MISO, and the Input on MOSI) |
ARM_SPI_MODE_MASTER_SIMPLEX | Set the SPI Master (Output and Input on MOSI); arg = Bus Speed in bps |
ARM_SPI_MODE_SLAVE_SIMPLEX | Set the SPI Slave (Output and Input on MISO) |
ARM_SPI_CPOLx_CPHAy specifies the clock polarity and clock phase. Additional parameters ARM_SPI_TI_SSI and ARM_SPI_MICROWIRE specify special formats.
Mode Parameters: Frame Format | Description |
---|---|
ARM_SPI_CPOL0_CPHA0 | CPOL=0 and CPHA=0: Clock Polarity 0, Clock Phase 0 (default) |
ARM_SPI_CPOL0_CPHA1 | CPOL=0 and CPHA=1: Clock Polarity 0, Clock Phase 1 |
ARM_SPI_CPOL1_CPHA0 | CPOL=1 and CPHA=0: Clock Polarity 1, Clock Phase 0 |
ARM_SPI_CPOL1_CPHA1 | CPOL=1 and CPHA=1: Clock Polarity 1, Clock Phase 1 |
ARM_SPI_TI_SSI | Specifies that the frame format corresponds to the Texas Instruments Frame Format |
ARM_SPI_MICROWIRE | Specifies that the frame format corresponds to the National Microwire Frame Format |
ARM_SPI_DATA_BITS(x) specifies the number of bits transferred per SPI frame.
Mode Parameters: Data Bits | Description |
---|---|
ARM_SPI_DATA_BITS(n) | Set the number of bits per SPI frame; the possible range for n is 1..32. |
ARM_SPI_MSB_LSB and ARM_SPI_LSB_MSB specify the bit order.
Mode Parameters: Bit order | Description |
---|---|
ARM_SPI_MSB_LSB | Set the bit order from MSB to LSB (default) |
ARM_SPI_LSB_MSB | Set the bit order from LSB to MSB |
ARM_SPI_SS_MASTER_xxx and ARM_SPI_SS_SLAVE_xxx specify the Slave Select mode.
Mode Parameters: Slave Select Mode | Description |
---|---|
ARM_SPI_SS_MASTER_UNUSED | Set the Slave Select mode for the master to Not used (default) |
ARM_SPI_SS_MASTER_SW | Set the Slave Select mode for the master to Software controlled |
ARM_SPI_SS_MASTER_HW_OUTPUT | Set the Slave Select mode for the master to Hardware controlled Output |
ARM_SPI_SS_MASTER_HW_INPUT | Set the Slave Select mode for the master to Hardware monitored Input |
ARM_SPI_SS_SLAVE_HW | Set the Slave Select mode for the slave to Hardware monitored (default) |
ARM_SPI_SS_SLAVE_SW | Set the Slave Select mode for the slave to Software controlled |
Miscellaneous Controls execute various operations.
Miscellaneous Controls | Description |
---|---|
ARM_SPI_SET_BUS_SPEED | Set the bus speed in bps; the argument arg specifies the speed value |
ARM_SPI_GET_BUS_SPEED | Get the bus speed in bps |
ARM_SPI_SET_DEFAULT_TX_VALUE | Set the default transmission value; the argument arg sets the value |
ARM_SPI_CONTROL_SS | Control the Slave Select signal; the argument arg: 0=inactive; 1=active |
ARM_SPI_ABORT_TRANSFER | Abort the current 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 supported modes.
Example:
uint32_t ARM_SPI_GetDataCount | ( | void | ) |
Get transferred data count.
Returns the number of currently transferred data items during ARM_SPI_Send, ARM_SPI_Receive and ARM_SPI_Transfer operation.
ARM_SPI_STATUS ARM_SPI_GetStatus | ( | void | ) |
ARM_DRIVER_VERSION ARM_SPI_GetVersion | ( | void | ) |
Get driver version.
Returns version information of the driver implementation in ARM_DRIVER_VERSION
Example:
int32_t 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:
int32_t ARM_SPI_PowerControl | ( | ARM_POWER_STATE | state | ) |
Control SPI Interface Power.
[in] | state | Power state |
Allows you to control the power modes of the SPI interface.
int32_t ARM_SPI_Receive | ( | void * | data, |
uint32_t | num | ||
) |
Start receiving data from SPI receiver.
[out] | data | Pointer to buffer for data to receive from SPI receiver |
[in] | num | Number of data items to receive |
This functions is used to only receive data (transmits the default value as specified by ARM_SPI_Control with ARM_SPI_SET_DEFAULT_TX_VALUE as control parameter).
The function parameters specify the buffer for data and the number of items to receive. The item size is defined by the data type which depends on the configured number of data bits.
Data type is:
Calling the function ARM_SPI_Receive only starts the receive operation. The function is non-blocking and returns as soon as the driver has started the operation (driver typically configures DMA or the interrupt system for continuous transfer). When in slave mode the operation is only registered and started when the master starts the transfer. During the operation it is not allowed to call this function or any other data transfer function again. Also the data buffer must stay allocated. When receive operation is completed (requested number of items received) the ARM_SPI_EVENT_TRANSFER_COMPLETE event is generated. Progress of receive operation can also be monitored by reading the number of items already received by calling ARM_SPI_GetDataCount.
Status of the receiver can also be monitored by calling the ARM_SPI_GetStatus and checking the busy flag which indicates if reception is still in progress or pending.
When in master mode and configured to monitor slave select and the slave select gets deactivated during transfer then the SPI mode changes to inactive and the ARM_SPI_EVENT_MODE_FAULT event is generated (instead of ARM_SPI_EVENT_TRANSFER_COMPLETE).
When in slave mode but send/receive/transfer operation is not started and data is sent/requested by the master then the ARM_SPI_EVENT_DATA_LOST event is generated.
Receive operation can be aborted by calling ARM_SPI_Control with ARM_SPI_ABORT_TRANSFER as the control parameter.
int32_t ARM_SPI_Send | ( | const void * | data, |
uint32_t | num | ||
) |
Start sending data to SPI transmitter.
[in] | data | Pointer to buffer with data to send to SPI transmitter |
[in] | num | Number of data items to send |
This functions is used to only send data to the SPI transmitter (received data is ignored).
The function parameters specify the buffer with data and the number of items to send. The item size is defined by the data type which depends on the configured number of data bits.
Data type is:
Calling the function ARM_SPI_Send only starts the send operation. When in slave mode the operation is only registered and started when the master starts the transfer. The function is non-blocking and returns as soon as the driver has started the operation (driver typically configures DMA or the interrupt system for continuous transfer). During the operation it is not allowed to call this function or any other data transfer function again. Also the data buffer must stay allocated and the contents of unsent data must not be modified. When send operation is completed (requested number of items sent) the ARM_SPI_EVENT_TRANSFER_COMPLETE event is generated. Progress of send operation can also be monitored by reading the number of items already sent by calling ARM_SPI_GetDataCount.
Status of the transmitter can also be monitored by calling the ARM_SPI_GetStatus and checking the busy flag which indicates if transmission is still in progress or pending.
When in master mode and configured to monitor slave select and the slave select gets deactivated during transfer then the SPI mode changes to inactive and the ARM_SPI_EVENT_MODE_FAULT event is generated (instead of ARM_SPI_EVENT_TRANSFER_COMPLETE).
When in slave mode but send/receive/transfer operation is not started and data is sent/requested by the master then the ARM_SPI_EVENT_DATA_LOST event is generated.
Send operation can be aborted by calling ARM_SPI_Control with ARM_SPI_ABORT_TRANSFER as the control parameter.
void ARM_SPI_SignalEvent | ( | uint32_t | event | ) |
Signal SPI Events.
[in] | event | SPI Events notification mask |
The function ARM_SPI_SignalEvent notifies the application of the SPI Events and it is registered by the function ARM_SPI_Initialize. The function ARM_SPI_GetCapabilities returns information about the implemented optional events in a driver.
The argument event represents the notification mask of the events. Each event is coded in a separate bit and therefore it is possible to signal multiple events in the event call back function. The following call back notifications are generated:
Bit | Event | Description |
---|---|---|
0 | ARM_SPI_EVENT_TRANSFER_COMPLETE | Occurs after call to ARM_SPI_Send, ARM_SPI_Receive or ARM_SPI_Transfer to indicate that all the data has been transferred. The driver is ready for the next transfer operation. |
1 | ARM_SPI_EVENT_DATA_LOST | Occurs in slave mode when data is requested/sent by master but send/receive/transfer operation has not been started and indicates that data is lost. |
2 | ARM_SPI_EVENT_MODE_FAULT | Occurs in master mode when Slave Select is deactivated and indicates Master Mode Fault. |
int32_t ARM_SPI_Transfer | ( | const void * | data_out, |
void * | data_in, | ||
uint32_t | num | ||
) |
Start sending/receiving data to/from SPI transmitter/receiver.
[in] | data_out | Pointer to buffer with data to send to SPI transmitter |
[out] | data_in | Pointer to buffer for data to receive from SPI receiver |
[in] | num | Number of data items to transfer |
This functions is used to transfer data via SPI. It synchronously sends data to the SPI transmitter and receives data from the SPI receiver.
The function parameters specify the buffer with data to send, the buffer for data to receive and the number of items to transfer. The item size is defined by the data type which depends on the configured number of data bits.
Data type is:
Calling the function ARM_SPI_Transfer only starts the transfer operation. The function is non-blocking and returns as soon as the driver has started the operation (driver typically configures DMA or the interrupt system for continuous transfer). When in slave mode the operation is only registered and started when the master starts the transfer. During the operation it is not allowed to call this function or any other data transfer function again. Also the data buffers must stay allocated and the contents of unsent data must not be modified. When transfer operation is completed (requested number of items transferred) the ARM_SPI_EVENT_TRANSFER_COMPLETE event is generated. Progress of transfer operation can also be monitored by reading the number of items already transferred by calling ARM_SPI_GetDataCount.
Status of the transmitter and receiver can also be monitored by calling the ARM_SPI_GetStatus and checking the busy flag.
When in master mode and configured to monitor slave select and the slave select gets deactivated during transfer then the SPI mode changes to inactive and the ARM_SPI_EVENT_MODE_FAULT event is generated (instead of ARM_SPI_EVENT_TRANSFER_COMPLETE).
When in slave mode but send/receive/transfer operation is not started and data is sent/requested by the master then the ARM_SPI_EVENT_DATA_LOST event is generated.
Transfer operation can also be aborted by calling ARM_SPI_Control with ARM_SPI_ABORT_TRANSFER as the control parameter.
int32_t ARM_SPI_Uninitialize | ( | void | ) |
De-initialize SPI Interface.
The function ARM_SPI_Uninitialize de-initializes the resources of SPI interface.
It is called when the middleware component stops operation and releases the software resources used by the interface.