Driver API for SPI Bus Peripheral (Driver_SPI.h) More...
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.
Block Diagram
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.
SPI Master connected to a single slave
SPI Master connected to 3 slaves
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 Common Driver Functions
Example Code
The following example code shows the usage of the SPI interface.
#include "cmsis_os.h"
void mySPI_Thread(void const *argument);
osThreadId tid_mySPI_Thread;
void mySPI_callback(uint32_t event)
{
switch (event)
{
osSignalSet(tid_mySPI_Thread, 0x01);
break;
__breakpoint(0);
break;
__breakpoint(0);
break;
}
}
const uint8_t testdata_out[8] = { 0, 1, 2, 3, 4, 5, 6, 7 };
uint8_t testdata_in [8];
void mySPI_Thread(void const* arg)
{
osEvent evt;
#ifdef DEBUG
if(version.
api< 0x200)
{
return;
}
{
return;
}
#endif
while (1)
{
SPIdrv->
Send(testdata_out,
sizeof(testdata_out));
evt = osSignalWait(0x01, 100);
if (evt.status == osEventTimeout) {
__breakpoint(0);
}
evt = osSignalWait(0x01, 100);
if (evt.status == osEventTimeout) {
__breakpoint(0);
}
}
}
Access structure of the SPI Driver.
The functions of the SPI driver are accessed by function pointers exposed by this structure. Refer to Common 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.
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.
int32_t(* Control)(uint32_t control, uint32_t arg)Pointer to ARM_SPI_Control : Control SPI Interface.
struct ARM_SPI_CAPABILITIESSPI Driver Capabilities.
A SPI driver can be implemented with different capabilities. The data fields of this structure encode the capabilities implemented by this driver.
Returned by:
Data Fields uint32_t simplex: 1 supports Simplex Mode (Master and Slave)SPI Status.
Structure with information about the status of the SPI. The data fields encode busy flag and error flags.
Returned by:
Data Fields uint32_t busy: 1 Transmitter/Receiver busy flag. uint32_t data_lost: 1 Data lost: Receive overflow / Transmit underflow (cleared on start of transfer operation) uint32_t mode_fault: 1 Mode fault detected; optional (cleared on start of transfer operation) uint32_t reserved: 29Get driver version.
The function ARM_SPI_GetVersion returns version information of the driver implementation in ARM_DRIVER_VERSION
Example:
void setup_spi (void) {
drv_info = &Driver_SPI0;
if(version.
api< 0x10A) {
return;
}
}
Get driver capabilities.
The function ARM_SPI_GetCapabilities returns information about the capabilities in this driver implementation. The data fields of the structure ARM_SPI_CAPABILITIES encode various capabilities, for example supported modes.
Example:
void read_capabilities (void) {
drv_info = &Driver_SPI0;
}
Initialize SPI Interface.
The function ARM_SPI_Initialize initializes the SPI interface.
The parameter cb_event is a pointer to the ARM_SPI_SignalEvent callback function; use a NULL pointer when no callback signals are required.
The function is called when the middleware component starts operation and performs the following:
Example:
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.
Control SPI Interface Power.
The function ARM_SPI_PowerControl controls the power modes of the SPI interface.
The parameter state sets the operation and can have the following values:
Refer to Function Call Sequence for more information.
int32_t ARM_SPI_Send ( const void * data, uint32_t num )Start sending data to SPI transmitter.
This function ARM_SPI_Send is used to send data to the SPI transmitter (received data is ignored).
The parameter data specifies the data buffer.
The parameter num specifies 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 data field, 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.
int32_t ARM_SPI_Receive ( void * data, uint32_t num )Start receiving data from SPI receiver.
The function ARM_SPI_Receive is used to receive data (transmits the default value as specified by ARM_SPI_Control with ARM_SPI_SET_DEFAULT_TX_VALUE as control parameter).
The parameter data specifies the data buffer.
The parameter num specifies 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 data field, 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_Transfer ( const void * data_out, void * data_in, uint32_t num )Start sending/receiving data to/from SPI transmitter/receiver.
The function ARM_SPI_Transfer transfers data via SPI. It synchronously sends data to the SPI transmitter and receives data from the SPI receiver.
The parameter data_out is a pointer to the buffer with data to send.
The parameter data_in is a pointer to the buffer which receives data.
The parameter num specifies 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.
uint32_t ARM_SPI_GetDataCount ( void )Get transferred data count.
The function ARM_SPI_GetDataCount returns the number of currently transferred data items during ARM_SPI_Send, ARM_SPI_Receive and ARM_SPI_Transfer operation.
int32_t ARM_SPI_Control ( uint32_t control, uint32_t arg )Control SPI Interface.
The function ARM_SPI_Control controls the SPI interface settings and executes various operations.
The parameter control is a bit mask that specifies various operations.
The parameter arg provides (depending on the parameter control) additional information, for example the Bus Speed.
Parameter control Bit Category Description ARM_SPI_MODE_INACTIVE 0..7 Mode Controls 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_CPOL0_CPHA0 (default) 8..11 Clock PolarityExample
Get SPI status.
The function ARM_SPI_GetStatus returns the current SPI interface status.
void ARM_SPI_SignalEvent ( uint32_t event )Signal SPI Events.
The function ARM_SPI_SignalEvent is a callback function registered by the function ARM_SPI_Initialize.
The parameter event indicates one or more events that occurred during driver operation. Each event is encoded in a separate bit and therefore it is possible to signal multiple events within the same call.
Not every event is necessarily generated by the driver. This depends on the implemented capabilities stored in the data fields of the structure ARM_SPI_CAPABILITIES, which can be retrieved with the function ARM_SPI_GetCapabilities.
The following events can be generated:
Parameter event Bit Description supported when ARM_SPI_CAPABILITIES ARM_SPI_EVENT_TRANSFER_COMPLETE 0 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. always supported ARM_SPI_EVENT_DATA_LOST 1 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. Occurs also in master mode when driver cannot transfer data fast enough. always supported ARM_SPI_EVENT_MODE_FAULT 2 Occurs in master mode when Slave Select is deactivated and indicates Master Mode Fault. The driver is ready for the next transfer operation. data field event_mode_fault = 1RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4