AM263Px MCU+ SDK: APIs for MCSPI

| AM263Px MCU+ SDK 26.00.00 |

Files | Data Structures | Typedefs
APIs for MCSPI
APIs for SOC Specific Device Drivers

## 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 struct MCSPI_Config_s * | 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 struct MCSPI_Config_s* 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

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