AM64x MCU+ SDK  10.00.00

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_HandleMCSPI_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
indexIndex of config to use in the MCSPI_Config array
openPrmsPointer 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
handleMCSPI_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
indexIndex 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
handleMCSPI_Handle returned from MCSPI_open()
chCfgPointer 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
handleMCSPI_Handle returned from MCSPI_open()
chCfgPointer to MCSPI_ChConfig. This parameter can't be NULL
dmaChCfgPointer 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
handleMCSPI_Handle returned from MCSPI_open()
transactionPointer 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
handleMCSPI_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
openPrmsPointer 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
chConfigPointer 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
transPointer 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
handleMCSPI_Handle returned from MCSPI_open()
chNumChannel used for communication.
numWordsRxTxNumber 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
handleMCSPI_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.