Introduction

SPI driver interface

Files
file	SPI.h
	SPI driver interface.

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

Functions
void	SPI_close (SPI_Handle handle)
	Function to close a SPI peripheral specified by the SPI handle. More...

int32_t	SPI_control (SPI_Handle handle, uint32_t 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 (uint32_t idx, 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 *spiTrans)
	Function to perform SPI transactions. More...

void	SPI_transferCancel (SPI_Handle handle)
	Function to cancel SPI transactions. More...

Typedefs
typedef struct SPI_Config_s *	SPI_Handle
	A handle that is returned from a SPI_open() call. 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 void(*	SPI_CloseFxn) (SPI_Handle handle)
	A function pointer to a driver specific implementation of SPI_close(). More...

typedef int32_t(*	SPI_ControlFxn) (SPI_Handle handle, uint32_t cmd, const 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, const 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 SPI_Config	SPI_config_list[SPI_MAX_CONFIG_CNT]

Enumerations
enum	SPI_Status { SPI_TRANSFER_COMPLETED = 0, SPI_TRANSFER_STARTED, SPI_TRANSFER_CANCELED, SPI_TRANSFER_FAILED, SPI_TRANSFER_CSN_DEASSERT, SPI_TRANSFER_TIMEOUT }
	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...

Macros
#define	SPI_CMD_RESERVED (32U)

#define	SPI_STATUS_RESERVED (-((int32_t)32))

#define	SPI_STATUS_SUCCESS (int32_t)(0)
	Successful status code returned by SPI_control(). More...

#define	SPI_STATUS_ERROR (-((int32_t)1))
	Generic error status code returned by SPI_control(). More...

#define	SPI_STATUS_UNDEFINEDCMD (-((int32_t)2))
	An error status code returned by SPI_control() for undefined command codes. More...

#define	SPI_WAIT_FOREVER (~(0U))
	Wait forever define. More...

#define	SPI_MAX_CONFIG_CNT (8U)

Macro Definition Documentation

◆ SPI_CMD_RESERVED

#define SPI_CMD_RESERVED (32U)

Common SPI_control command code reservation offset. SPI driver implementations should offset command codes with SPI_CMD_RESERVED growing positively

Example implementation specific command codes:

#define SPIXYZ_COMMAND0 SPI_CMD_RESERVED + 0

#define SPIXYZ_COMMAND1 SPI_CMD_RESERVED + 1

◆ SPI_STATUS_RESERVED

#define SPI_STATUS_RESERVED (-((int32_t)32))

Common SPI_control status code reservation offset. SPI driver implementations should offset status codes with SPI_STATUS_RESERVED growing negatively.

Example implementation specific status codes:

#define SPIXYZ_STATUS_ERROR0    SPI_STATUS_RESERVED - 0
#define SPIXYZ_STATUS_ERROR1    SPI_STATUS_RESERVED - 1
#define SPIXYZ_STATUS_ERROR2    SPI_STATUS_RESERVED - 2

◆ SPI_STATUS_SUCCESS

#define SPI_STATUS_SUCCESS (int32_t)(0)

Successful status code returned by SPI_control().

SPI_control() returns SPI_STATUS_SUCCESS if the control code was executed successfully.

◆ SPI_STATUS_ERROR

#define SPI_STATUS_ERROR (-((int32_t)1))

Generic error status code returned by SPI_control().

SPI_control() returns SPI_STATUS_ERROR if the control code was not executed successfully.

◆ SPI_STATUS_UNDEFINEDCMD

#define SPI_STATUS_UNDEFINEDCMD (-((int32_t)2))

An error status code returned by SPI_control() for undefined command codes.

SPI_control() returns SPI_STATUS_UNDEFINEDCMD if the control code is not recognized by the driver implementation.

◆ SPI_WAIT_FOREVER

#define SPI_WAIT_FOREVER (~(0U))

Wait forever define.

◆ SPI_MAX_CONFIG_CNT

#define SPI_MAX_CONFIG_CNT (8U)

Typedef Documentation

◆ SPI_Handle

typedef struct SPI_Config_s* SPI_Handle

A handle that is returned from a SPI_open() call.

◆ SPI_CallbackFxn

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*

◆ SPI_CloseFxn

typedef void(* SPI_CloseFxn) (SPI_Handle handle)

A function pointer to a driver specific implementation of SPI_close().

◆ SPI_ControlFxn

typedef int32_t(* SPI_ControlFxn) (SPI_Handle handle, uint32_t cmd, const void *arg)

A function pointer to a driver specific implementation of SPI_control().

◆ SPI_InitFxn

typedef void(* SPI_InitFxn) (SPI_Handle handle)

A function pointer to a driver specific implementation of SPI_init().

◆ SPI_OpenFxn

typedef SPI_Handle(* SPI_OpenFxn) (SPI_Handle handle, const SPI_Params *params)

A function pointer to a driver specific implementation of SPI_open().

◆ SPI_ServiceISRFxn

typedef void(* SPI_ServiceISRFxn) (SPI_Handle handle)

A function pointer to a driver specific implementation of SPI_serviceISR().

◆ SPI_TransferFxn

typedef bool(* SPI_TransferFxn) (SPI_Handle handle, SPI_Transaction *transaction)

A function pointer to a driver specific implementation of SPI_transfer().

◆ SPI_TransferCancelFxn

typedef void(* SPI_TransferCancelFxn) (SPI_Handle handle)

A function pointer to a driver specific implementation of SPI_transferCancel().

◆ SPI_config_list

typedef SPI_Config SPI_config_list[SPI_MAX_CONFIG_CNT]

Enumeration Type Documentation

◆ SPI_Status

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
SPI_TRANSFER_TIMEOUT

◆ SPI_Mode

enum SPI_Mode

Definitions for various SPI modes of operation.

Enumerator
SPI_MASTER	SPI in master mode
SPI_SLAVE	SPI in slave mode

◆ SPI_FrameFormat

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

◆ SPI_TransferMode

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

◆ SPI_close()

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

◆ SPI_control()

int32_t SPI_control	(	SPI_Handle	handle,
		uint32_t	cmd,
		void *	arg
	)

Function performs implementation specific features on a given SPI_Handle.

Precondition: SPI_open() has to be called first.

Parameters

handle	A SPI handle returned from SPI_open()
cmd	A command value defined by the driver specific implementation
arg	An optional R/W (read/write) argument that is accompanied with cmd

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

See also: SPI_open()

◆ SPI_init()

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

SPI_Handle SPI_open	(	uint32_t	idx,
		SPI_Params *	params
	)

This function opens a given SPI peripheral.

Precondition: SPI controller has been initialized using SPI_init()

Parameters

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

◆ SPI_Params_init()

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

◆ SPI_serviceISR()

void SPI_serviceISR ( SPI_Handle handle )

Function to service the SPI module's interrupt service routine.

Parameters

handle A SPI_Handle

◆ SPI_transfer()

bool SPI_transfer	(	SPI_Handle	handle,
		SPI_Transaction *	spiTrans
	)

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

◆ 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

Introduction

Files

Data Structures

Functions

Typedefs

Enumerations

Macros

Macro Definition Documentation

◆ SPI_CMD_RESERVED

◆ SPI_STATUS_RESERVED

◆ SPI_STATUS_SUCCESS

◆ SPI_STATUS_ERROR

◆ SPI_STATUS_UNDEFINEDCMD

◆ SPI_WAIT_FOREVER

◆ SPI_MAX_CONFIG_CNT

Typedef Documentation

◆ SPI_Handle

◆ SPI_CallbackFxn

◆ SPI_CloseFxn

◆ SPI_ControlFxn

◆ SPI_InitFxn

◆ SPI_OpenFxn

◆ SPI_ServiceISRFxn

◆ SPI_TransferFxn

◆ SPI_TransferCancelFxn

◆ SPI_config_list

Enumeration Type Documentation

◆ SPI_Status

◆ SPI_Mode

◆ SPI_FrameFormat

◆ SPI_TransferMode

Function Documentation

◆ SPI_close()

◆ SPI_control()

◆ SPI_init()

◆ SPI_open()

◆ SPI_Params_init()

◆ SPI_serviceISR()

◆ SPI_transfer()

◆ SPI_transferCancel()