Introduction

This module contains APIs to program and use the MCSPI module. The APIs can be used by other drivers to get access to MCSPI and also by application to initiate data transfer operation.

Files
file	mcspi/v0/mcspi.h
	MCSPI Driver API/interface file.

Data Structures
struct	MCSPI_OpenParams
	MCSPI Parameters. More...

struct	MCSPI_Attrs
	MCSPI instance attributes - used during init time. More...

struct	MCSPI_Object
	MCSPI driver object. More...

struct	MCSPI_Config
	MCSPI global configuration array. More...

Typedefs
typedef void *	MCSPI_Handle
	A handle that is returned from a MCSPI_open() call. More...

Transfer Mode
This determines whether the driver operates synchronously or asynchronously In MCSPI_TRANSFER_MODE_BLOCKING mode MCSPI_transfer() blocks code execution until the transaction has completed In MCSPI_TRANSFER_MODE_CALLBACK MCSPI_transfer() does not block code execution and instead calls a MCSPI_CallbackFxn callback function when the transaction has completed
typedef void(*	MCSPI_CallbackFxn) (MCSPI_Handle handle, MCSPI_Transaction *transaction)
	The definition of a callback function used by the SPI driver when used in MCSPI_TRANSFER_MODE_CALLBACK. More...

MCSPI_Config	gMcspiConfig []
	Externally defined driver configuration array. More...

uint32_t	gMcspiConfigNum
	Externally defined driver configuration array size. More...

void	MCSPI_init (void)
	This function initializes the MCSPI module. More...

void	MCSPI_deinit (void)
	This function de-initializes the MCSPI module. More...

MCSPI_Handle	MCSPI_open (uint32_t index, const MCSPI_OpenParams *openPrms)
	This function opens a given MCSPI peripheral. More...

void	MCSPI_close (MCSPI_Handle handle)
	Function to close a MCSPI peripheral specified by the MCSPI handle. More...

MCSPI_Handle	MCSPI_getHandle (uint32_t index)
	Function to return a open'ed MCSPI handle given a MCSPI instance index. More...

int32_t	MCSPI_chConfig (MCSPI_Handle handle, const MCSPI_ChConfig *chCfg)
	Function to configure a MCSPI channel. More...

int32_t	MCSPI_dmaChConfig (MCSPI_Handle handle, const MCSPI_ChConfig chCfg, const MCSPI_DmaChConfig dmaChCfg)
	Function to configure a DMA of a channel. More...

int32_t	MCSPI_transfer (MCSPI_Handle handle, MCSPI_Transaction *transaction)
	Function to perform MCSPI transactions. More...

int32_t	MCSPI_transferCancel (MCSPI_Handle handle)
	Function to cancel MCSPI transactions on channel of a SPI peripheral specified by the MCSPI handle. More...

static void	MCSPI_OpenParams_init (MCSPI_OpenParams *openPrms)
	Function to initialize the MCSPI_OpenParams struct to its defaults. More...

static void	MCSPI_ChConfig_init (MCSPI_ChConfig *chConfig)
	Function to initialize the MCSPI_ChConfig struct to its defaults. More...

static void	MCSPI_Transaction_init (MCSPI_Transaction *trans)
	Function to initialize the MCSPI_Transaction struct to its defaults. More...

int32_t	MCSPI_reConfigFifo (MCSPI_Handle handle, uint32_t chNum, uint32_t numWordsRxTx)
	Function to re-configure Effective FIFO Words. More...

uint32_t	MCSPI_getBaseAddr (MCSPI_Handle handle)
	Function to get base address of MCSPI instance of a particular handle. More...

#define	MCSPI_TRANSFER_MODE_BLOCKING (0U)
	MCSPI_transfer() blocks execution. This mode can only be used when called within a Task context More...

#define	MCSPI_TRANSFER_MODE_CALLBACK (1U)
	MCSPI_transfer() does not block code execution and will call a MCSPI_CallbackFxn. This mode can be used in a Task, Swi, or Hwi context More...

Macro Definition Documentation

◆ MCSPI_TRANSFER_MODE_BLOCKING

#define MCSPI_TRANSFER_MODE_BLOCKING (0U)

MCSPI_transfer() blocks execution. This mode can only be used when called within a Task context

◆ MCSPI_TRANSFER_MODE_CALLBACK

#define MCSPI_TRANSFER_MODE_CALLBACK (1U)

MCSPI_transfer() does not block code execution and will call a MCSPI_CallbackFxn. This mode can be used in a Task, Swi, or Hwi context

Typedef Documentation

◆ MCSPI_Handle

typedef void* MCSPI_Handle

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

◆ MCSPI_CallbackFxn

typedef void(* MCSPI_CallbackFxn) (MCSPI_Handle handle, MCSPI_Transaction *transaction)

The definition of a callback function used by the SPI driver when used in MCSPI_TRANSFER_MODE_CALLBACK.

Parameters

MCSPI_Handle	MCSPI_Handle
MCSPI_Transaction*	Pointer to a MCSPI_Transaction

Function Documentation

◆ MCSPI_init()

void MCSPI_init ( void )

This function initializes the MCSPI module.

◆ MCSPI_deinit()

void MCSPI_deinit ( void )

This function de-initializes the MCSPI module.

◆ MCSPI_open()

MCSPI_Handle MCSPI_open	(	uint32_t	index,
		const MCSPI_OpenParams *	openPrms
	)

This function opens a given MCSPI peripheral.

Precondition: MCSPI controller has been initialized using MCSPI_init()

Parameters

index	Index of config to use in the MCSPI_Config array
openPrms	Pointer to open parameters. If NULL is passed, then default values will be used

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

See also: MCSPI_init(); MCSPI_close(); MCSPI_OpenParams_init

◆ MCSPI_close()

void MCSPI_close ( MCSPI_Handle handle )

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

Precondition: MCSPI_open() has to be called first

Parameters

handle MCSPI_Handle returned from MCSPI_open()

See also: MCSPI_open()

◆ MCSPI_getHandle()

MCSPI_Handle MCSPI_getHandle ( uint32_t index )

Function to return a open'ed MCSPI handle given a MCSPI instance index.

Parameters

index Index of config to use in the MCSPI_Config array

Returns: A MCSPI_Handle on success or a NULL on an error or if the instance index has NOT been opened yet

◆ MCSPI_chConfig()

int32_t MCSPI_chConfig	(	MCSPI_Handle	handle,
		const MCSPI_ChConfig *	chCfg
	)

Function to configure a MCSPI channel.

Parameters

handle	MCSPI_Handle returned from MCSPI_open()
chCfg	Pointer to MCSPI_ChConfig. This parameter can't be NULL

Returns: SystemP_SUCCESS if successful; else error on failure

See also: MCSPI_open; MCSPI_ChConfig_init

◆ MCSPI_dmaChConfig()

int32_t MCSPI_dmaChConfig	(	MCSPI_Handle	handle,
		const MCSPI_ChConfig *	chCfg,
		const MCSPI_DmaChConfig *	dmaChCfg
	)

Function to configure a DMA of a channel.

Parameters

handle	MCSPI_Handle returned from MCSPI_open()
chCfg	Pointer to MCSPI_ChConfig. This parameter can't be NULL
dmaChCfg	Pointer to MCSPI_DmaChConfig. This parameter can't be NULL

Returns: SystemP_SUCCESS if successful; else error on failure

See also: MCSPI_open; MCSPI_ChConfig_init

◆ MCSPI_transfer()

int32_t MCSPI_transfer	(	MCSPI_Handle	handle,
		MCSPI_Transaction *	transaction
	)

Function to perform MCSPI transactions.

If the MCSPI is in MCSPI_MS_MODE_CONTROLLER mode, it will immediately start the transaction. If the MCSPI is in MCSPI_MS_MODE_PERIPHERAL mode, it prepares the driver for a transaction with a MCSPI controller device. The device will then wait until the controller begins the transfer.

In MCSPI_TRANSFER_MODE_BLOCKING, MCSPI_transfer() will block task execution until the transaction has completed or a timeout has occurred.

In MCSPI_TRANSFER_MODE_CALLBACK, MCSPI_transfer() does not block task execution, but calls a MCSPI_CallbackFxn once the transfer has finished. This makes MCSPI_transfer() safe to be used within a Task, software or hardware interrupt context.

From calling MCSPI_transfer() until transfer completion, the MCSPI_Transaction structure must stay persistent and must not be altered by application code. It is also forbidden to modify the content of the MCSPI_Transaction.txBuf during a transaction, even though the physical transfer might not have started yet. Doing this can result in data corruption. This is especially important for peripheral operations where MCSPI_transfer() might be called a long time before the actual data transfer begins.

Parameters

handle MCSPI_Handle returned from MCSPI_open()

transaction Pointer to a MCSPI_Transaction. All of the fields within transaction except MCSPI_Transaction.count and MCSPI_Transaction.status are WO (write-only) unless otherwise noted in the driver implementations. If a transaction timeout has occurred, MCSPI_Transaction.count will contain the number of frames that were transferred. Neither is it allowed to modify the transaction object nor the content of MCSPI_Transaction.txBuf until the transfer has completed

Returns: SystemP_SUCCESS if started successfully; else error on failure

See also: MCSPI_open; MCSPI_transferCancel

◆ MCSPI_transferCancel()

int32_t MCSPI_transferCancel ( MCSPI_Handle handle )

Function to cancel MCSPI transactions on channel of a SPI peripheral specified by the MCSPI handle.

In MCSPI_TRANSFER_MODE_BLOCKING, MCSPI_transferCancel has no effect.

In MCSPI_TRANSFER_MODE_CALLBACK, MCSPI_transferCancel() will stop an MCSPI transfer 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 MCSPI_CallbackFxn function can determine if the transaction was successful or not by reading the MCSPI_TransferStatus status value in the MCSPI_Transaction structure.

Parameters

handle MCSPI_Handle returned from MCSPI_open()

See also: MCSPI_open; MCSPI_transfer

◆ MCSPI_OpenParams_init()

static void MCSPI_OpenParams_init ( MCSPI_OpenParams * openPrms )

inlinestatic

Function to initialize the MCSPI_OpenParams struct to its defaults.

Parameters

openPrms Pointer to MCSPI_OpenParams structure for initialization

◆ MCSPI_ChConfig_init()

static void MCSPI_ChConfig_init ( MCSPI_ChConfig * chConfig )

inlinestatic

Function to initialize the MCSPI_ChConfig struct to its defaults.

Parameters

chConfig Pointer to MCSPI_ChConfig structure for initialization

◆ MCSPI_Transaction_init()

static void MCSPI_Transaction_init ( MCSPI_Transaction * trans )

inlinestatic

Function to initialize the MCSPI_Transaction struct to its defaults.

Parameters

trans Pointer to MCSPI_Transaction structure for initialization

◆ MCSPI_reConfigFifo()

int32_t MCSPI_reConfigFifo	(	MCSPI_Handle	handle,
		uint32_t	chNum,
		uint32_t	numWordsRxTx
	)

Function to re-configure Effective FIFO Words.

Parameters

handle	MCSPI_Handle returned from MCSPI_open()
chNum	Channel used for communication.
numWordsRxTx	Number of words to transfer

Returns: SystemP_SUCCESS if successful; else error on failure

See also: MCSPI_open

◆ MCSPI_getBaseAddr()

uint32_t MCSPI_getBaseAddr ( MCSPI_Handle handle )

Function to get base address of MCSPI instance of a particular handle.

Parameters

handle MCSPI_Handle returned from MCSPI_open()

See also: MCSPI_open

Variable Documentation

◆ gMcspiConfig

MCSPI_Config gMcspiConfig[]

extern

Externally defined driver configuration array.

◆ gMcspiConfigNum

uint32_t gMcspiConfigNum

extern

Externally defined driver configuration array size.

Introduction

Files

Data Structures

Typedefs

Transfer Mode

Macro Definition Documentation

◆ MCSPI_TRANSFER_MODE_BLOCKING

◆ MCSPI_TRANSFER_MODE_CALLBACK

Typedef Documentation

◆ MCSPI_Handle

◆ MCSPI_CallbackFxn

Function Documentation

◆ MCSPI_init()

◆ MCSPI_deinit()

◆ MCSPI_open()

◆ MCSPI_close()

◆ MCSPI_getHandle()

◆ MCSPI_chConfig()

◆ MCSPI_dmaChConfig()

◆ MCSPI_transfer()

◆ MCSPI_transferCancel()

◆ MCSPI_OpenParams_init()

◆ MCSPI_ChConfig_init()

◆ MCSPI_Transaction_init()

◆ MCSPI_reConfigFifo()

◆ MCSPI_getBaseAddr()

Variable Documentation

◆ gMcspiConfig

◆ gMcspiConfigNum