SPI Driver

The SPI driver is used for allowing a project to have access to and control basic SPI functionality of an end device.

Data Structures

ATMO_SPI_Device_t

SPI single device configuration.

Member Name Type Description
ssActiveLow bool Slave select active low
ssContinuous bool Slave select continuous
clockContinuous bool Clock continuous
baudRate uint32_t Baud rate in hz
clockMode ATMO_SPI_ClockMode_t SPI Clock Mode
msbFirst bool MSB First

ATMO_SPI_Peripheral_t

SPI peripheral configuration.

Member Name Type Description
operatingMode ATMO_SPI_OperatingMode_t Operating mode
deviceConfig ATMO_SPI_Device_t Default device configuration
bufferSize uint32_t Buffer to be used for slave operation
cbFunc void * UNUSED
cbParam void * UNUSED

ATMO_SPI_SlaveTransfer_t

SPI non-blocking slave transfer event.

Member Name Type Description
event ATMO_SPI_SlaveEvent_t Event type
data uint8_t * Event data
dataSize uint32_t Event data size
transferComplete bool Transfer complete flag

ATMO_SPI_MasterTransfer_t

SPI non-blocking master transfer event.

Member Name Type Description
event ATMO_SPI_MasterEvent_t Event type
data uint8_t * Event data
dataSize uint32_t Event data size
transferComplete bool Transfer complete flag

Type Definitions

Name Definition
ATMO_SPI_Master_Callback_t typedef void(* ATMO_SPI_Master_Callback_t) (ATMO_SPI_MasterTransfer_t *xfer, void *cbParam)
ATMO_SPI_Slave_Callback_t typedef void(* ATMO_SPI_Slave_Callback_t) (ATMO_SPI_SlaveTransfer_t *xfer, void *cbParam)
ATMO_SPI_DriverInstance_t typedef struct ATMO_SPI_DriverInstance_t ATMO_SPI_DriverInstance_t

Enumerations

enum ATMO_SPI_OperatingMode_t

SPI operating mode.

Name Value
ATMO_SPI_OperatingMode_Uninitialized 0x00u
ATMO_SPI_OperatingMode_Master 0x01u
ATMO_SPI_OperatingMode_Slave 0x02u

enum ATMO_SPI_ClockMode_t

SPI clock mode.

Name Value Description
ATMO_SPI_ClockMode_0 0x00u clock idle low, data sampled rising edge
ATMO_SPI_ClockMode_1 0x01u clock idle low, data sampled falling edge
ATMO_SPI_ClockMode_2 0x02u clock idle high, data sampled falling edge
ATMO_SPI_ClockMode_3 0x03u clock idle high, data sampled rising edge

enum ATMO_SPI_Status_t

SPI driver return enumerations.

Name Value Description
ATMO_SPI_Status_Success 0x00u Common - Operation was successful
ATMO_SPI_Status_Fail 0x01u Common - Operation failed
ATMO_SPI_Status_Initialized 0x02u Common - Peripheral already initialized
ATMO_SPI_Status_Invalid 0x03u Common - Invalid operation
ATMO_SPI_Status_NotSupported 0x04u Common - Feature not supported by platform
ATMO_SPI_Status_Unknown 0x05u Common - Some other status not defined
ATMO_SPI_Status_Busy 0x20u Master - Transfer in progress
ATMO_SPI_Status_Timeout 0x21u Master - Transfer timed out
ATMO_SPI_Status_TxUnderrun 0x40u Slave - TX Underrun error
ATMO_SPI_Status_RxOverrun 0x41u Slave - RX Overrun error
ATMO_SPI_Status_Idle 0x42u Slave - Bus is Idle

enum ATMO_SPI_MasterEvent_t

SPI master non-blocking event.

Name Value Description
ATMO_SPI_MasterEvent_Unknown 0x00u  
ATMO_SPI_MasterEvent_Complete 0x01u Transfer Complete

enum ATMO_SPI_SlaveEvent_t

SPI slave non-blocking event.

Name Value Description
ATMO_SPI_SlaveEvent_Unknown 0x0000u  
ATMO_SPI_SlaveEvent_Complete 0x0001u Transfer Complete

Functions

ATMO_Status_t ATMO_SPI_AddDriverInstance(const ATMO_SPI_DriverInstance_t *driverInstance, ATMO_DriverInstanceData_t *driverInstanceData, ATMO_DriverInstanceHandle_t *instanceNumber)

This routine will add an instance of a driver for SPI into the SPI driver handler.

Parameter Direction Type
instanceNumber N/A ATMO_DriverInstanceHandle_t *
driverInstanceData N/A ATMO_DriverInstanceData_t *
driverInstance N/A const ATMO_SPI_DriverInstance_t *
Return Type
ATMO_Status_t

ATMO_SPI_Status_t ATMO_SPI_Init(ATMO_DriverInstanceHandle_t instance)

This routine initializes the SPI peripheral.

Parameter Direction Type
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_SPI_Status_t

ATMO_SPI_Status_t ATMO_SPI_DeInit(ATMO_DriverInstanceHandle_t instance)

This routine de-initializes the SPI peripheral.

Parameter Direction Type
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_SPI_Status_t

ATMO_SPI_Status_t ATMO_SPI_SetConfiguration(ATMO_DriverInstanceHandle_t instance, const ATMO_SPI_Peripheral_t *config)

This routine configures the specified SPI peripheral instance. It is similar to the init function except the peripheral configuration settings are passed in via the config structure.

Parameter Direction Type
config N/A const ATMO_SPI_Peripheral_t *
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_SPI_Status_t

ATMO_SPI_Status_t ATMO_SPI_GetConfiguration(ATMO_DriverInstanceHandle_t instance, ATMO_SPI_Peripheral_t *config)

This routine retrieves the current configuration of the specified SPI peripheral instance.

Parameter Direction Type
config N/A ATMO_SPI_Peripheral_t *
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_SPI_Status_t

ATMO_SPI_Status_t ATMO_SPI_MasterSetDeviceConfiguration(ATMO_DriverInstanceHandle_t instance, uint16_t csPin, const ATMO_SPI_Device_t *config)

This routine configures the device-specific parameters for the specified SPI peripheral.

Parameter Direction Type
config N/A const ATMO_SPI_Device_t *
csPin N/A uint16_t
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_SPI_Status_t

ATMO_SPI_Status_t ATMO_SPI_MasterGetDeviceConfiguration(ATMO_DriverInstanceHandle_t instance, uint16_t csPin, ATMO_SPI_Device_t *config)

This routine retrieves the current configuration of the specified SPI peripheral instance device-specific parameters.

Parameter Direction Type
config N/A ATMO_SPI_Device_t *
csPin N/A uint16_t
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_SPI_Status_t

ATMO_SPI_Status_t AIR_SPI_MasterRegisterCallback(ATMO_DriverInstanceHandle_t instance, ATMO_SPI_Master_Callback_t cbFunc)

This routine will register or unregister a user-defined callback function for the specified SPI peripheral instance. Applicable only for SPI peripherals configured as master.

Parameter Direction Type
cbFunc N/A ATMO_SPI_Master_Callback_t
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_SPI_Status_t

ATMO_SPI_Status_t AIR_SPI_SlaveRegisterCallback(ATMO_DriverInstanceHandle_t instance, ATMO_SPI_Slave_Callback_t cbFunc)

This routine will register or unregister a user-defined callback function for the specified SPI peripheral instance. Applicable only for SPI peripherals configured as slave.

Parameter Direction Type
cbFunc N/A ATMO_SPI_Slave_Callback_t
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_SPI_Status_t

ATMO_SPI_Status_t ATMO_SPI_MasterAssertSlaveSelect(ATMO_DriverInstanceHandle_t instance, uint16_t csPin, bool ssActiveLow)

This routine drives a GPIO output pin to the active level.

Parameter Direction Type
ssActiveLow N/A bool
csPin N/A uint16_t
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_SPI_Status_t

ATMO_SPI_Status_t ATMO_SPI_MasterDeAssertSlaveSelect(ATMO_DriverInstanceHandle_t instance, uint16_t csPin, bool ssActiveLow)

This routine drives a GPIO output pin to the inactive level.

Parameter Direction Type
ssActiveLow N/A bool
csPin N/A uint16_t
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_SPI_Status_t

ATMO_SPI_Status_t ATMO_SPI_MasterWrite(ATMO_DriverInstanceHandle_t instance, uint16_t csPin, const uint8_t *cmdBytes, uint16_t numCmdBytes, const uint8_t *writeBytes, uint16_t numWriteBytes, uint16_t timeout_ms)

This routine will send one or more bytes to a slave device via the specified SPI peripheral. This is a blocking operation and the function will not return until the SPI transfer completes or the timeout expires.

Parameter Direction Type
timeout_ms N/A uint16_t
numWriteBytes N/A uint16_t
writeBytes N/A const uint8_t *
numCmdBytes N/A uint16_t
cmdBytes N/A const uint8_t *
csPin N/A uint16_t
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_SPI_Status_t

ATMO_SPI_Status_t ATMO_SPI_MasterWriteNonBlocking(ATMO_DriverInstanceHandle_t instance, uint16_t csPin, const uint8_t *cmdBytes, uint16_t numCmdBytes, const uint8_t *writeBytes, uint16_t numWriteBytes)

This routine will send one or more bytes to a slave device via the specified SPI peripheral. This function does not wait for the SPI transfer to complete before returning (i.e. returns immediately). It is up to the application to wait for the SPI peripheral to become available before performing another data transfer (write or read).

Parameter Direction Type
numWriteBytes N/A uint16_t
writeBytes N/A const uint8_t *
numCmdBytes N/A uint16_t
cmdBytes N/A const uint8_t *
csPin N/A uint16_t
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_SPI_Status_t

ATMO_SPI_Status_t ATMO_SPI_MasterRead(ATMO_DriverInstanceHandle_t instance, uint16_t csPin, const uint8_t *cmdBytes, uint16_t numCmdBytes, uint8_t *readBytes, uint16_t numReadBytes, uint16_t timeout_ms)

This routine will read one or more bytes from a slave device via the specified SPI peripheral. If the command buffer has a valid pointer (i.e. not NULL) and the number of command bytes is greater than zero then the values in the command buffer are sent to the device during the read process, otherwise the output data is zero. This is a blocking operation and the function will not return until the SPI transfer completes or the timeout expires.

Parameter Direction Type
timeout_ms N/A uint16_t
numReadBytes N/A uint16_t
readBytes N/A uint8_t *
numCmdBytes N/A uint16_t
cmdBytes N/A const uint8_t *
csPin N/A uint16_t
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_SPI_Status_t

ATMO_SPI_Status_t ATMO_SPI_MasterReadNonBlocking(ATMO_DriverInstanceHandle_t instance, uint16_t csPin, const uint8_t *cmdBytes, uint16_t numCmdBytes, uint8_t *readBytes, uint16_t numReadBytes)

This routine will read one or more bytes from a slave device via the specified SPI peripheral. If the command buffer has a valid pointer (i.e. not NULL) and the number of command bytes is greater than zero then the values in the command buffer are sent to the device during the read process, otherwise the output data is zero. This function does not wait for the SPI transfer to complete before returning (i.e. returns immediately). It is up to the application to wait for the SPI peripheral to become available before performing another data transfer (write or read).

Parameter Direction Type
numReadBytes N/A uint16_t
readBytes N/A uint8_t *
numCmdBytes N/A uint16_t
cmdBytes N/A const uint8_t *
csPin N/A uint16_t
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_SPI_Status_t

ATMO_SPI_Status_t ATMO_SPI_SlaveWaitForReceive(ATMO_DriverInstanceHandle_t instance, uint16_t xferSize)

This routine starts the receive process for a SPI peripheral configured in Slave mode. It only needs to be called once.

Parameter Direction Type
xferSize N/A uint16_t
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_SPI_Status_t