![]() |
PDK API Guide for J721E
|
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... | |
struct | OSPI_Transaction |
A SPI_Transaction data structure is used with OSPI_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 | OSPI_Params |
OSPI Parameters. More... | |
struct | OSPI_FxnTable |
The definition of a SPI function table that contains the required set of functions to control a specific SPI driver implementation. More... | |
struct | OSPI_Config |
OSPI 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 domain, uint32_t idx, SPI_Params *params) |
This function opens a given SPI peripheral. More... | |
void | OSPI_close (OSPI_Handle handle) |
Function to close a OSPI peripheral specified by the OSPI handle. More... | |
int32_t | OSPI_control (OSPI_Handle handle, uint32_t cmd, void *arg) |
Function performs implementation specific features on a given OSPI_Handle. More... | |
void | OSPI_init (void) |
This function initializes the SPI module. More... | |
OSPI_Handle | OSPI_open (uint32_t domain, uint32_t idx, OSPI_Params *params) |
This function opens a given OSPI peripheral. More... | |
void | OSPI_Params_init (OSPI_Params *params) |
Function to initialize the OSPI_Params struct to its defaults. More... | |
bool | OSPI_transfer (OSPI_Handle handle, OSPI_Transaction *spiTrans) |
Function to perform SPI transactions. 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_DOMAIN_CNT][SPI_MAX_CONFIG_CNT] |
typedef struct OSPI_Config_s * | OSPI_Handle |
A handle that is returned from a SPI_open() call. More... | |
typedef void(* | OSPI_CallbackFxn) (OSPI_Handle handle, OSPI_Transaction *transaction) |
The definition of a callback function used by the SPI driver when used in SPI_MODE_CALLBACK. More... | |
typedef void(* | OSPI_CloseFxn) (OSPI_Handle handle) |
A function pointer to a driver specific implementation of OSPI_close(). More... | |
typedef int32_t(* | OSPI_ControlFxn) (OSPI_Handle handle, uint32_t cmd, const void *arg) |
A function pointer to a driver specific implementation of OSPI_control(). More... | |
typedef void(* | OSPI_InitFxn) (OSPI_Handle handle) |
A function pointer to a driver specific implementation of OSPI_init(). More... | |
typedef OSPI_Handle(* | OSPI_OpenFxn) (OSPI_Handle handle, const OSPI_Params *params) |
A function pointer to a driver specific implementation of SPI_open(). More... | |
typedef void(* | OSPI_ServiceISRFxn) (OSPI_Handle handle) |
A function pointer to a driver specific implementation of SPI_serviceISR(). More... | |
typedef bool(* | OSPI_TransferFxn) (OSPI_Handle handle, OSPI_Transaction *transaction) |
A function pointer to a driver specific implementation of OSPI_transfer(). More... | |
typedef void(* | OSPI_TransferCancelFxn) (OSPI_Handle handle) |
A function pointer to a driver specific implementation of OSPI_transferCancel(). More... | |
typedef OSPI_Config | OSPI_config_list[OSPI_MAX_DOMAIN_CNT][OSPI_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... | |
enum | OSPI_Status { OSPI_TRANSFER_COMPLETED = 0, OSPI_TRANSFER_STARTED, OSPI_TRANSFER_CANCELED, OSPI_TRANSFER_FAILED, OSPI_TRANSFER_CSN_DEASSERT, OSPI_TRANSFER_TIMEOUT } |
Status codes that are set by the SPI driver. More... | |
enum | OSPI_Mode { OSPI_MASTER = 0, OSPI_SLAVE = 1 } |
Definitions for various SPI modes of operation. More... | |
enum | OSPI_FrameFormat { OSPI_POL0_PHA0 = 0, OSPI_POL0_PHA1 = 1, OSPI_POL1_PHA0 = 2, OSPI_POL1_PHA1 = 3, OSPI_TI = 4, OSPI_MW = 5 } |
Definitions for various SPI data frame formats. More... | |
enum | OSPI_TransferMode { OSPI_MODE_BLOCKING, OSPI_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 OSPI_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 | OSPI_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) |
#define | SPI_MAX_DOMAIN_CNT (2U) |
#define | OSPI_MAX_CONFIG_CNT (2U) |
#define | OSPI_MAX_DOMAIN_CNT (2U) |
#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 OSPI_CMD_RESERVED (32U) |
#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 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.
#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.
#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.
#define SPI_WAIT_FOREVER (~(0U)) |
Wait forever define.
#define SPI_MAX_CONFIG_CNT (8U) |
#define SPI_MAX_DOMAIN_CNT (2U) |
#define OSPI_MAX_CONFIG_CNT (2U) |
#define OSPI_MAX_DOMAIN_CNT (2U) |
typedef struct SPI_Config_s* SPI_Handle |
A handle that is returned from a SPI_open() call.
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.
SPI_Handle | SPI_Handle |
SPI_Transaction* | SPI_Transaction* |
typedef void(* SPI_CloseFxn) (SPI_Handle handle) |
A function pointer to a driver specific implementation of SPI_close().
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().
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, const 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 SPI_Config SPI_config_list[SPI_MAX_DOMAIN_CNT][SPI_MAX_CONFIG_CNT] |
typedef struct OSPI_Config_s* OSPI_Handle |
A handle that is returned from a SPI_open() call.
typedef void(* OSPI_CallbackFxn) (OSPI_Handle handle, OSPI_Transaction *transaction) |
The definition of a callback function used by the SPI driver when used in SPI_MODE_CALLBACK.
OSPI_Handle | OSPI_Handle |
OSPI_Transaction* | OSPI_Transaction* |
typedef void(* OSPI_CloseFxn) (OSPI_Handle handle) |
A function pointer to a driver specific implementation of OSPI_close().
typedef int32_t(* OSPI_ControlFxn) (OSPI_Handle handle, uint32_t cmd, const void *arg) |
A function pointer to a driver specific implementation of OSPI_control().
typedef void(* OSPI_InitFxn) (OSPI_Handle handle) |
A function pointer to a driver specific implementation of OSPI_init().
typedef OSPI_Handle(* OSPI_OpenFxn) (OSPI_Handle handle, const OSPI_Params *params) |
A function pointer to a driver specific implementation of SPI_open().
typedef void(* OSPI_ServiceISRFxn) (OSPI_Handle handle) |
A function pointer to a driver specific implementation of SPI_serviceISR().
typedef bool(* OSPI_TransferFxn) (OSPI_Handle handle, OSPI_Transaction *transaction) |
A function pointer to a driver specific implementation of OSPI_transfer().
typedef void(* OSPI_TransferCancelFxn) (OSPI_Handle handle) |
A function pointer to a driver specific implementation of OSPI_transferCancel().
typedef OSPI_Config OSPI_config_list[OSPI_MAX_DOMAIN_CNT][OSPI_MAX_CONFIG_CNT] |
enum SPI_Status |
enum SPI_Mode |
enum SPI_FrameFormat |
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. |
enum OSPI_Status |
enum OSPI_Mode |
enum OSPI_FrameFormat |
enum OSPI_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 OSPI_transfer() does not block code execution and instead calls a SPI_CallbackFxn callback function when the transaction has completed.
Enumerator | |
---|---|
OSPI_MODE_BLOCKING | SPI_transfer() blocks execution. This mode can only be used when called within a Task context |
OSPI_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. |
void SPI_close | ( | SPI_Handle | handle | ) |
Function to close a SPI peripheral specified by the SPI handle.
handle | A SPI handle returned from SPI_open() |
int32_t SPI_control | ( | SPI_Handle | handle, |
uint32_t | cmd, | ||
void * | arg | ||
) |
Function performs implementation specific features on a given SPI_Handle.
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 |
void SPI_init | ( | void | ) |
This function initializes the SPI module.
SPI_Handle SPI_open | ( | uint32_t | domain, |
uint32_t | idx, | ||
SPI_Params * | params | ||
) |
This function opens a given SPI peripheral.
domain | Logical domain number of domain where SPI IP is present |
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). |
void OSPI_close | ( | OSPI_Handle | handle | ) |
Function to close a OSPI peripheral specified by the OSPI handle.
handle | A OSPI handle returned from OSPI_open() |
int32_t OSPI_control | ( | OSPI_Handle | handle, |
uint32_t | cmd, | ||
void * | arg | ||
) |
Function performs implementation specific features on a given OSPI_Handle.
handle | A OSPI handle returned from OSPI_open() |
cmd | A command value defined by the driver specific implementation |
arg | An optional R/W (read/write) argument that is accompanied with cmd |
void OSPI_init | ( | void | ) |
This function initializes the SPI module.
OSPI_Handle OSPI_open | ( | uint32_t | domain, |
uint32_t | idx, | ||
OSPI_Params * | params | ||
) |
This function opens a given OSPI peripheral.
domain | domain where OSPI IP is located |
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). |
void OSPI_Params_init | ( | OSPI_Params * | params | ) |
Function to initialize the OSPI_Params struct to its defaults.
params | An pointer to OSPI_Params structure for initialization |
Defaults values are: transferMode = OSPI_MODE_BLOCKING transferTimeout = OSPI_WAIT_FOREVER transferCallbackFxn = NULL mode = OSPI_MASTER bitRate = 1000000 (Hz) dataSize = 8 (bits) frameFormat = OSPI_POL0_PHA0
bool OSPI_transfer | ( | OSPI_Handle | handle, |
OSPI_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 OSPI_MODE_BLOCKING, OSPI_transfer will block task execution until the transaction has completed.
In OSPI_MODE_CALLBACK, OSPI_transfer() does not block task execution and calls a SPI_CallbackFxn. This makes the OSPI_tranfer() safe to be used within a Task, Swi, or Hwi context. The SPI_Transaction structure must stay persistent until the OSPI_transfer function has completed!
handle | A OSPI_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. |
void SPI_Params_init | ( | SPI_Params * | params | ) |
Function to initialize the SPI_Params struct to its defaults.
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.
handle | A SPI_Handle |
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!
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. |
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.
handle | A SPI_Handle |