![]() |
![]() |
TI-RTOS Drivers
tidrivers_full_2_20_01_10
|
SPI driver interface.
============================================================================
The SPI header file should be included in an application as follows:
The SPI driver in TI-RTOS is designed to serve a means to move data between SPI peripherals. This driver does not interpret any of the data sent to or received from this peripheral.
The APIs in this driver serve as an interface to a typical TI-RTOS application. The specific peripheral implementations are responsible to create all the SYS/BIOS specific primitives to allow for thread-safe operation.
The SPI driver operates on some key definitions and assumptions:
Data transmitted and received by the SPI peripheral is performed using SPI_transfer(). SPI_transfer() accepts a pointer to a SPI_Transaction structure that dictates what quantity of data is sent and received.
SPI_transferCancel() is used to cancel a SPI transaction when the driver is used in SPI_MODE_CALLBACK mode.
Calling this API while no transfer is in progress has no effect. If a transfer is in progress, it canceled and a callback on the SPI_CallbackFxn is performed. The SPI_Status status field in the SPI_Transaction struct can be examined within the callback to determine if the transaction was successful.
This module serves as the main interface for TI-RTOS applications. Its purpose is to redirect the module's APIs to specific peripheral implementations which are specified using a pointer to a SPI_FxnTable.
The SPI driver interface module is joined (at link time) to a NULL-terminated array of SPI_Config data structures named SPI_config. SPI_config is implemented in the application with each entry being an instance of a SPI peripheral. Each entry in SPI_config contains a:
The SPI driver interface produces log statements if instrumentation is enabled.
Diagnostics Mask | Log details |
---|---|
Diags_USER1 | basic operations performed |
Diags_USER2 | detailed operations performed |
#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>
Go to the source code of this file.
Data Structures | |
struct | SPI_Transaction |
A SPI_Transaction data structure is used with SPI_transfer(). It indicates how many SPI_FrameFormat frames are sent and received from the buffers pointed to txBuf and rxBuf. The arg variable is an user-definable argument which gets passed to the SPI_CallbackFxn when the SPI driver is in SPI_MODE_CALLBACK. More... | |
struct | SPI_Params |
SPI Parameters. More... | |
struct | SPI_FxnTable |
The definition of a SPI function table that contains the required set of functions to control a specific SPI driver implementation. More... | |
struct | SPI_Config |
SPI Global configuration. More... | |
Macros | |
#define | SPI_CMD_RESERVED 32 |
#define | SPI_STATUS_RESERVED -32 |
#define | SPI_STATUS_SUCCESS 0 |
Successful status code returned by SPI_control(). More... | |
#define | SPI_STATUS_ERROR -1 |
Generic error status code returned by SPI_control(). More... | |
#define | SPI_STATUS_UNDEFINEDCMD -2 |
An error status code returned by SPI_control() for undefined command codes. More... | |
#define | SPI_WAIT_FOREVER ~(0) |
Wait forever define. More... | |
Typedefs | |
typedef struct SPI_Config * | SPI_Handle |
A handle that is returned from a SPI_open() call. More... | |
typedef enum SPI_Status | SPI_Status |
Status codes that are set by the SPI driver. More... | |
typedef struct SPI_Transaction | SPI_Transaction |
A SPI_Transaction data structure is used with SPI_transfer(). It indicates how many SPI_FrameFormat frames are sent and received from the buffers pointed to txBuf and rxBuf. The arg variable is an user-definable argument which gets passed to the SPI_CallbackFxn when the SPI driver is in SPI_MODE_CALLBACK. More... | |
typedef void(* | SPI_CallbackFxn) (SPI_Handle handle, SPI_Transaction *transaction) |
The definition of a callback function used by the SPI driver when used in SPI_MODE_CALLBACK. More... | |
typedef enum SPI_Mode | SPI_Mode |
Definitions for various SPI modes of operation. More... | |
typedef enum SPI_FrameFormat | SPI_FrameFormat |
Definitions for various SPI data frame formats. More... | |
typedef enum SPI_TransferMode | SPI_TransferMode |
SPI transfer mode determines the whether the SPI controller operates synchronously or asynchronously. In SPI_MODE_BLOCKING mode SPI_transfer() blocks code execution until the SPI transaction has completed. In SPI_MODE_CALLBACK SPI_transfer() does not block code execution and instead calls a SPI_CallbackFxn callback function when the transaction has completed. More... | |
typedef struct SPI_Params | SPI_Params |
SPI Parameters. More... | |
typedef void(* | SPI_CloseFxn) (SPI_Handle handle) |
A function pointer to a driver specific implementation of SPI_close(). More... | |
typedef int(* | SPI_ControlFxn) (SPI_Handle handle, unsigned int cmd, void *arg) |
A function pointer to a driver specific implementation of SPI_control(). More... | |
typedef void(* | SPI_InitFxn) (SPI_Handle handle) |
A function pointer to a driver specific implementation of SPI_init(). More... | |
typedef SPI_Handle(* | SPI_OpenFxn) (SPI_Handle handle, SPI_Params *params) |
A function pointer to a driver specific implementation of SPI_open(). More... | |
typedef void(* | SPI_ServiceISRFxn) (SPI_Handle handle) |
A function pointer to a driver specific implementation of SPI_serviceISR(). More... | |
typedef bool(* | SPI_TransferFxn) (SPI_Handle handle, SPI_Transaction *transaction) |
A function pointer to a driver specific implementation of SPI_transfer(). More... | |
typedef void(* | SPI_TransferCancelFxn) (SPI_Handle handle) |
A function pointer to a driver specific implementation of SPI_transferCancel(). More... | |
typedef struct SPI_FxnTable | SPI_FxnTable |
The definition of a SPI function table that contains the required set of functions to control a specific SPI driver implementation. More... | |
typedef struct SPI_Config | SPI_Config |
SPI Global configuration. More... | |
Enumerations | |
enum | SPI_Status { SPI_TRANSFER_COMPLETED = 0, SPI_TRANSFER_STARTED, SPI_TRANSFER_CANCELED, SPI_TRANSFER_FAILED, SPI_TRANSFER_CSN_DEASSERT } |
Status codes that are set by the SPI driver. More... | |
enum | SPI_Mode { SPI_MASTER = 0, SPI_SLAVE = 1 } |
Definitions for various SPI modes of operation. More... | |
enum | SPI_FrameFormat { SPI_POL0_PHA0 = 0, SPI_POL0_PHA1 = 1, SPI_POL1_PHA0 = 2, SPI_POL1_PHA1 = 3, SPI_TI = 4, SPI_MW = 5 } |
Definitions for various SPI data frame formats. More... | |
enum | SPI_TransferMode { SPI_MODE_BLOCKING, SPI_MODE_CALLBACK } |
SPI transfer mode determines the whether the SPI controller operates synchronously or asynchronously. In SPI_MODE_BLOCKING mode SPI_transfer() blocks code execution until the SPI transaction has completed. In SPI_MODE_CALLBACK SPI_transfer() does not block code execution and instead calls a SPI_CallbackFxn callback function when the transaction has completed. More... | |
Functions | |
void | SPI_close (SPI_Handle handle) |
Function to close a SPI peripheral specified by the SPI handle. More... | |
int | SPI_control (SPI_Handle handle, unsigned int cmd, void *arg) |
Function performs implementation specific features on a given SPI_Handle. More... | |
void | SPI_init (void) |
This function initializes the SPI module. More... | |
SPI_Handle | SPI_open (unsigned int index, SPI_Params *params) |
This function opens a given SPI peripheral. More... | |
void | SPI_Params_init (SPI_Params *params) |
Function to initialize the SPI_Params struct to its defaults. More... | |
void | SPI_serviceISR (SPI_Handle handle) |
Function to service the SPI module's interrupt service routine. More... | |
bool | SPI_transfer (SPI_Handle handle, SPI_Transaction *transaction) |
Function to perform SPI transactions. More... | |
void | SPI_transferCancel (SPI_Handle handle) |
Function to cancel SPI transactions. More... | |
#define SPI_WAIT_FOREVER ~(0) |
Wait forever define.
typedef struct SPI_Config* SPI_Handle |
A handle that is returned from a SPI_open() call.
typedef enum SPI_Status SPI_Status |
Status codes that are set by the SPI driver.
typedef struct SPI_Transaction SPI_Transaction |
A SPI_Transaction data structure is used with SPI_transfer(). It indicates how many SPI_FrameFormat frames are sent and received from the buffers pointed to txBuf and rxBuf. The arg variable is an user-definable argument which gets passed to the SPI_CallbackFxn when the SPI driver is in SPI_MODE_CALLBACK.
typedef void(* SPI_CallbackFxn) (SPI_Handle handle, SPI_Transaction *transaction) |
The definition of a callback function used by the SPI driver when used in SPI_MODE_CALLBACK.
SPI_Handle | SPI_Handle |
SPI_Transaction* | SPI_Transaction* |
typedef enum SPI_FrameFormat SPI_FrameFormat |
Definitions for various SPI data frame formats.
typedef enum SPI_TransferMode SPI_TransferMode |
SPI transfer mode determines the whether the SPI controller operates synchronously or asynchronously. In SPI_MODE_BLOCKING mode SPI_transfer() blocks code execution until the SPI transaction has completed. In SPI_MODE_CALLBACK SPI_transfer() does not block code execution and instead calls a SPI_CallbackFxn callback function when the transaction has completed.
typedef struct SPI_Params SPI_Params |
SPI Parameters.
SPI Parameters are used to with the SPI_open() call. Default values for these parameters are set using SPI_Params_init().
typedef void(* SPI_CloseFxn) (SPI_Handle handle) |
A function pointer to a driver specific implementation of SPI_close().
typedef int(* SPI_ControlFxn) (SPI_Handle handle, unsigned int cmd, void *arg) |
A function pointer to a driver specific implementation of SPI_control().
typedef void(* SPI_InitFxn) (SPI_Handle handle) |
A function pointer to a driver specific implementation of SPI_init().
typedef SPI_Handle(* SPI_OpenFxn) (SPI_Handle handle, SPI_Params *params) |
A function pointer to a driver specific implementation of SPI_open().
typedef void(* SPI_ServiceISRFxn) (SPI_Handle handle) |
A function pointer to a driver specific implementation of SPI_serviceISR().
typedef bool(* SPI_TransferFxn) (SPI_Handle handle, SPI_Transaction *transaction) |
A function pointer to a driver specific implementation of SPI_transfer().
typedef void(* SPI_TransferCancelFxn) (SPI_Handle handle) |
A function pointer to a driver specific implementation of SPI_transferCancel().
typedef struct SPI_FxnTable SPI_FxnTable |
The definition of a SPI function table that contains the required set of functions to control a specific SPI driver implementation.
typedef struct SPI_Config SPI_Config |
SPI Global configuration.
The SPI_Config structure contains a set of pointers used to characterize the SPI driver implementation.
This structure needs to be defined before calling SPI_init() and it must not be changed thereafter.
enum SPI_Status |
enum SPI_Mode |
enum SPI_FrameFormat |
enum SPI_TransferMode |
SPI transfer mode determines the whether the SPI controller operates synchronously or asynchronously. In SPI_MODE_BLOCKING mode SPI_transfer() blocks code execution until the SPI transaction has completed. In SPI_MODE_CALLBACK SPI_transfer() does not block code execution and instead calls a SPI_CallbackFxn callback function when the transaction has completed.
Enumerator | |
---|---|
SPI_MODE_BLOCKING |
SPI_transfer() blocks execution. This mode can only be used when called within a Task context |
SPI_MODE_CALLBACK |
SPI_transfer() does not block code execution and will call a SPI_CallbackFxn. This mode can be used in a Task, Swi, or Hwi context. |
void SPI_close | ( | SPI_Handle | handle | ) |
Function to close a SPI peripheral specified by the SPI handle.
handle | A SPI handle returned from SPI_open() |
int SPI_control | ( | SPI_Handle | handle, |
unsigned int | cmd, | ||
void * | arg | ||
) |
Function performs implementation specific features on a given SPI_Handle.
Commands for SPI_control can originate from SPI.h or from implementation specific SPI*.h (SPICC26XX.h, SPITiva.h, etc.. ) files. While commands from SPI.h are API portable across driver implementations, not all implementations may support all these commands. Conversely, commands from driver implementation specific SPI*.h files add unique driver capabilities but are not API portable across all SPI driver implementations.
Commands supported by SPI.h follow a SPI_CMD_<cmd> naming convention.
Commands supported by SPI*.h follow a SPI*_CMD_<cmd> naming convention.
Each control command defines arg differently. The types of arg are documented with each command.
See SPI_control command codes for command codes.
See SPI_control return status codes for status codes.
handle | A SPI handle returned from SPI_open() |
cmd | SPI.h or SPI*.h commands. |
arg | An optional R/W (read/write) command argument accompanied with cmd |
void SPI_init | ( | void | ) |
This function initializes the SPI module.
SPI_Handle SPI_open | ( | unsigned int | index, |
SPI_Params * | params | ||
) |
This function opens a given SPI peripheral.
index | Logical peripheral number for the SPI indexed into the SPI_config table |
params | Pointer to an parameter block, if NULL it will use default values. All the fields in this structure are RO (read-only). |
void SPI_Params_init | ( | SPI_Params * | params | ) |
Function to initialize the SPI_Params struct to its defaults.
params | An pointer to SPI_Params structure for initialization |
Defaults values are: transferMode = SPI_MODE_BLOCKING transferTimeout = SPI_WAIT_FOREVER transferCallbackFxn = NULL mode = SPI_MASTER bitRate = 1000000 (Hz) dataSize = 8 (bits) frameFormat = SPI_POL0_PHA0
void SPI_serviceISR | ( | SPI_Handle | handle | ) |
Function to service the SPI module's interrupt service routine.
This function is not supported on all driver implementations. Refer to implementation specific documentation for details.
handle | A SPI_Handle |
bool SPI_transfer | ( | SPI_Handle | handle, |
SPI_Transaction * | transaction | ||
) |
Function to perform SPI transactions.
If the SPI is in SPI_MASTER mode, it will immediately start the transaction. If the SPI is in SPI_SLAVE mode, it prepares itself for a transaction with a SPI master.
In SPI_MODE_BLOCKING, SPI_transfer will block task execution until the transaction has completed.
In SPI_MODE_CALLBACK, SPI_transfer() does not block task execution and calls a SPI_CallbackFxn. This makes the SPI_tranfer() safe to be used within a Task, Swi, or Hwi context. The SPI_Transaction structure must stay persistent until the SPI_transfer function has completed!
handle | A SPI_Handle |
transaction | A pointer to a SPI_Transaction. All of the fields within transaction except SPI_Transaction.count and SPI_Transaction.status are WO (write-only) unless otherwise noted in the driver implementations. If a transaction timeout has occured, SPI_Transaction.count will contain the number of frames that were transferred. |
void SPI_transferCancel | ( | SPI_Handle | handle | ) |
Function to cancel SPI transactions.
In SPI_MODE_BLOCKING, SPI_transferCancel has no effect.
In SPI_MODE_CALLBACK, SPI_transferCancel() will stop an SPI transfer if if one is in progress. If a transaction was in progress, its callback function will be called in context from which this API is called from. The SPI_CallbackFxn function can determine if the transaction was successful or not by reading the SPI_Status status value in the SPI_Transaction structure.
handle | A SPI_Handle |