Detailed Description

SPI driver interface.

============================================================================

The SPI header file should be included in an application as follows:

Operation

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:

The driver operates transparent from the chip select. Some SPI controllers feature a hardware chip select to assert SPI slave peripherals. See the specific peripheral implementations on chip select requirements.
The SPI protocol does not account for a built-in handshaking mechanism and neither does this SPI driver. Therefore, when operating in SPI_SLAVE mode, the application must provide such a mechanism to ensure that the SPI slave is ready for the SPI master. The SPI slave must call SPI_transfer() before the SPI master starts transmitting. Some example application mechanisms could include:
- Timed delays on the SPI master to guarantee the SPI slave is be ready for a SPI transaction.
- A form of GPIO flow control from the slave to the SPI master to notify the master when ready.

Opening the driver

SPI_Handle      handle;
SPI_Params      params;
SPI_Transaction spiTransaction;
SPI_Params_init(&params);
params.bitRate  = someNewBitRate;
handle = SPI_open(someSPI_configIndexValue, &params);
if (!handle) {
    System_printf("SPI did not open");
}

Transferring data

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_Transaction spiTransaction;
spiTransaction.count = someIntegerValue;
spiTransaction.txBuf = transmitBufferPointer;
spiTransaction.rxBuf = receiveBufferPointer;
ret = SPI_transfer(handle, &spiTransaction);
if (!ret) {
    System_printf("Unsuccessful SPI transfer");
}

Canceling a transaction

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.

SPI_transferCancel(handle);

Implementation

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:

(SPI_FxnTable *) to a set of functions that implement a SPI peripheral
(void *) data object that is associated with the SPI_FxnTable
(void *) hardware attributes that are associated to the SPI_FxnTable

Instrumentation

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>

Include dependency graph for SPI.h:

This graph shows which files directly or indirectly include this file:

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...

Macro Definition Documentation

#define SPI_WAIT_FOREVER ~(0)

Wait forever define.

Typedef Documentation

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.

Parameters

SPI_Handle	SPI_Handle
SPI_Transaction*	SPI_Transaction*

typedef enum SPI_Mode SPI_Mode

Definitions for various SPI modes of operation.

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().

See also: 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.

See also: SPI_init()

Enumeration Type Documentation

enum SPI_Status

Status codes that are set by the SPI driver.

Enumerator
SPI_TRANSFER_COMPLETED
SPI_TRANSFER_STARTED
SPI_TRANSFER_CANCELED
SPI_TRANSFER_FAILED
SPI_TRANSFER_CSN_DEASSERT

enum SPI_Mode

Definitions for various SPI modes of operation.

Enumerator
SPI_MASTER	SPI in master mode
SPI_SLAVE	SPI in slave mode

enum SPI_FrameFormat

Definitions for various SPI data frame formats.

Enumerator
SPI_POL0_PHA0	SPI mode Polarity 0 Phase 0
SPI_POL0_PHA1	SPI mode Polarity 0 Phase 1
SPI_POL1_PHA0	SPI mode Polarity 1 Phase 0
SPI_POL1_PHA1	SPI mode Polarity 1 Phase 1
SPI_TI	TI mode
SPI_MW	Micro-wire mode

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.

Function Documentation

void SPI_close ( SPI_Handle handle )

Function to close a SPI peripheral specified by the SPI handle.

Precondition: SPI_open() has to be called first.

Parameters

handle A SPI handle returned from SPI_open()

See also: 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.

Precondition: SPI_open() has to be called first.

Parameters

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

Returns: Implementation specific return codes. Negative values indicate unsuccessful operations.

See also: SPI_open()

void SPI_init ( void )

This function initializes the SPI module.

Precondition: The SPI_config structure must exist and be persistent before this function can be called. This function must also be called before any other SPI driver APIs. This function call does not modify any peripheral registers.

SPI_Handle SPI_open	(	unsigned int	index,
		SPI_Params *	params
	)

This function opens a given SPI peripheral.

Precondition: SPI controller has been initialized using SPI_init()

Parameters

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).

Returns: A SPI_Handle on success or a NULL on an error or if it has been opened already.

See also: SPI_init(); SPI_close()

void SPI_Params_init ( SPI_Params * params )

Function to initialize the SPI_Params struct to its defaults.

Parameters

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.

Parameters

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!

Parameters

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.

Returns: true if started successfully; else false

See also: SPI_open; SPI_transferCancel

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.

Parameters

handle A SPI_Handle

See also: SPI_open; SPI_transfer

Detailed Description

Operation

Opening the driver

Transferring data

Canceling a transaction

Implementation

Instrumentation

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation