AM263Px MCU+ SDK: mcspi.h Source File

| AM263Px MCU+ SDK 26.00.00 |

mcspi/v0/mcspi.h
Go to the documentation of this file.
1 /*
2 * Copyright (C) 2021-23 Texas Instruments Incorporated
3 *
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions
6 * are met:
7 *
8 * Redistributions of source code must retain the above copyright
9 * notice, this list of conditions and the following disclaimer.
10 *
11 * Redistributions in binary form must reproduce the above copyright
12 * notice, this list of conditions and the following disclaimer in the
13 * documentation and/or other materials provided with the
14 * distribution.
15 *
16 * Neither the name of Texas Instruments Incorporated nor the names of
17 * its contributors may be used to endorse or promote products derived
18 * from this software without specific prior written permission.
19 *
20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
22 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
23 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
24 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
25 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
26 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
27 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
28 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
30 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 */
32
50 #ifndef MCSPI_H_
51 #define MCSPI_H_
52
53 /* ========================================================================== */
54 /* Include Files */
55 /* ========================================================================== */
56
57 #include <stdint.h>
58 #include <kernel/dpl/SemaphoreP.h>
59 #include <kernel/dpl/HwiP.h>
60 #include <drivers/mcspi/v0/lld/mcspi_lld.h>
61
62 #ifdef __cplusplus
63 extern "C" {
64 #endif
65
66 /* ========================================================================== */
67 /* Macros & Typedefs */
68 /* ========================================================================== */
69
71 typedef struct MCSPI_Config_s *MCSPI_Handle;
72
92 #define MCSPI_TRANSFER_MODE_BLOCKING (0U)
93
97 #define MCSPI_TRANSFER_MODE_CALLBACK (1U)
98
99 /* ========================================================================== */
100 /* Structure Declarations */
101 /* ========================================================================== */
102
110 typedef void (*MCSPI_CallbackFxn) (MCSPI_Handle handle,
111 MCSPI_Transaction *transaction);
112
123 typedef struct
124 {
125 uint32_t transferMode;
127 uint32_t transferTimeout;
129 MCSPI_CallbackFxn transferCallbackFxn;
131 uint32_t msMode;
133 int32_t mcspiDmaIndex;
137 } MCSPI_OpenParams;
138
140 typedef struct
141 {
142 /*
143 * SOC configuration
144 */
145 uint32_t baseAddr;
147 uint32_t inputClkFreq;
150 /*
151 * Driver configuration
152 */
153 uint32_t intrNum;
155 uint32_t operMode;
157 uint8_t intrPriority;
160 /*
161 * MCSPI instance configuration - common across all channels
162 */
163 uint32_t chMode;
165 uint32_t pinMode;
167 uint32_t initDelay;
169 uint32_t multiWordAccess;
171 } MCSPI_Attrs;
172
173 /* ========================================================================== */
174 /* Internal/Private Structure Declarations */
175 /* ========================================================================== */
176
180 typedef struct
181 {
182 /*
183 * User parameters
184 */
185 MCSPI_Handle handle;
187 MCSPI_OpenParams openPrms;
189 uint32_t baseAddr;
191 MCSPI_ChObject chObj[MCSPI_MAX_NUM_CHANNELS];
194 /*
195 * State variables
196 */
197 uint32_t isOpen;
199 void *transferSem;
202 SemaphoreP_Object transferSemObj;
204 void *hwiHandle;
206 HwiP_Object hwiObj;
209 MCSPI_Transaction *transaction;
211 void *mcspiDmaHandle;
213 MCSPILLD_Object mcspiLldObject;
214 MCSPILLD_Handle mcspiLldHandle;
215 MCSPILLD_InitObject mcspiLldInitObj;
216 /* MCSPI driver object for LLD */
217 } MCSPI_Object;
218
228 typedef struct MCSPI_Config_s
229 {
230 const MCSPI_Attrs *attrs;
232 MCSPI_Object *object;
234 } MCSPI_Config;
235
237 extern MCSPI_Config gMcspiConfig[];
239 extern uint32_t gMcspiConfigNum;
240
241 /* ========================================================================== */
242 /* Function Declarations */
243 /* ========================================================================== */
244
248 void MCSPI_init(void);
249
253 void MCSPI_deinit(void);
254
271 MCSPI_Handle MCSPI_open(uint32_t index, const MCSPI_OpenParams *openPrms);
272
282 void MCSPI_close(MCSPI_Handle handle);
283
292 MCSPI_Handle MCSPI_getHandle(uint32_t index);
293
306 int32_t MCSPI_chConfig(MCSPI_Handle handle, const MCSPI_ChConfig *chCfg);
307
320 int32_t MCSPI_dmaChConfig(MCSPI_Handle handle,
321 const MCSPI_ChConfig *chCfg,
322 const MCSPI_DmaChConfig *dmaChCfg);
323
366 int32_t MCSPI_transfer(MCSPI_Handle handle, MCSPI_Transaction *transaction);
367
387 int32_t MCSPI_transferCancel(MCSPI_Handle handle);
388
395 static inline void MCSPI_OpenParams_init(MCSPI_OpenParams *openPrms);
396
403 static inline void MCSPI_ChConfig_init(MCSPI_ChConfig *chConfig);
404
411 static inline void MCSPI_Transaction_init(MCSPI_Transaction *trans);
412
424 int32_t MCSPI_reConfigFifo(MCSPI_Handle handle, uint32_t chNum, uint32_t numWordsRxTx);
425
426 /* ========================================================================== */
427 /* Static Function Definitions */
428 /* ========================================================================== */
429
430 static inline void MCSPI_OpenParams_init(MCSPI_OpenParams *openPrms)
431 {
432 if(openPrms != NULL)
433 {
434 openPrms->transferMode = MCSPI_TRANSFER_MODE_BLOCKING;
435 openPrms->transferCallbackFxn = NULL;
436 openPrms->msMode = MCSPI_MS_MODE_CONTROLLER;
437 openPrms->transferTimeout = SystemP_WAIT_FOREVER;
438 }
439 }
440
441 static inline void MCSPI_ChConfig_init(MCSPI_ChConfig *chConfig)
442 {
443 if(chConfig != NULL)
444 {
445 chConfig->chNum = MCSPI_CHANNEL_0;
446 chConfig->frameFormat = MCSPI_FF_POL0_PHA0;
447 chConfig->bitRate = 1000000U;
448 chConfig->csPolarity = MCSPI_CS_POL_LOW;
449 chConfig->trMode = MCSPI_TR_MODE_TX_RX;
450 chConfig->inputSelect = MCSPI_IS_D1;
451 chConfig->dpe0 = MCSPI_DPE_ENABLE;
452 chConfig->dpe1 = MCSPI_DPE_DISABLE;
453 chConfig->slvCsSelect = MCSPI_SLV_CS_SELECT_0;
454 chConfig->startBitEnable = FALSE;
455 chConfig->startBitPolarity = MCSPI_SB_POL_LOW;
456 chConfig->csIdleTime = MCSPI_TCS0_0_CLK;
457 chConfig->defaultTxData = 0x00000000U;
458 chConfig->txFifoTrigLvl = 16;
459 chConfig->rxFifoTrigLvl = 16;
460 }
461 }
462
463 static inline void MCSPI_Transaction_init(MCSPI_Transaction *trans)
464 {
465 if(trans != NULL)
466 {
467 trans->channel = 0U;
468 trans->csDisable = TRUE;
469 trans->dataSize = 8U;
470 trans->count = 0U;
471 trans->txBuf = NULL;
472 trans->rxBuf = NULL;
473 trans->args = NULL;
474 trans->status = MCSPI_TRANSFER_COMPLETED;
475 }
476 }
477
478 /* ========================================================================== */
479 /* Advanced Macros & Typedefs */
480 /* ========================================================================== */
481
482
483 /* ========================================================================== */
484 /* Advanced Function Declarations */
485 /* ========================================================================== */
494 uint32_t MCSPI_getBaseAddr(MCSPI_Handle handle);
495
496 /* ========================================================================== */
497 /* Advanced Function Definitions */
498 /* ========================================================================== */
499
500 /* ========================================================================== */
501 /* Internal/Private Structure Declarations */
502 /* ========================================================================== */
503
504 #ifdef __cplusplus
505 }
506 #endif
507
508 #endif /* #ifndef MCSPI_H_ */
509
MCSPI_Object::mcspiLldHandle
MCSPILLD_Handle mcspiLldHandle
Definition: mcspi/v0/mcspi.h:214
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.
MCSPI_close
void MCSPI_close(MCSPI_Handle handle)
Function to close a MCSPI peripheral specified by the MCSPI handle.
MCSPI_Attrs
MCSPI instance attributes - used during init time.
Definition: mcspi/v0/mcspi.h:141
MCSPI_OpenParams::transferTimeout
uint32_t transferTimeout
Definition: mcspi/v0/mcspi.h:127
MCSPILLD_InitObject
MCSPI driver initialization object.
Definition: mcspi_lld.h:698
MCSPI_ChObject
MCSPI channel object.
Definition: mcspi_lld.h:639
MCSPI_Transaction::count
uint32_t count
Definition: mcspi_lld.h:493
MCSPI_ChConfig::txFifoTrigLvl
uint32_t txFifoTrigLvl
Definition: mcspi_lld.h:603
MCSPI_FF_POL0_PHA0
#define MCSPI_FF_POL0_PHA0
Definition: mcspi_lld.h:231
MCSPI_ChConfig::rxFifoTrigLvl
uint32_t rxFifoTrigLvl
Definition: mcspi_lld.h:605
MCSPI_CallbackFxn
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_CALLBAC...
Definition: mcspi/v0/mcspi.h:110
MCSPI_DPE_DISABLE
#define MCSPI_DPE_DISABLE
No transmission on Data Line.
Definition: mcspi_lld.h:283
MCSPI_Attrs::operMode
uint32_t operMode
Definition: mcspi/v0/mcspi.h:155
MCSPI_Transaction::status
uint32_t status
Definition: mcspi_lld.h:518
MCSPI_Transaction
Data structure used with MCSPI_transfer()
Definition: mcspi_lld.h:472
MCSPI_Attrs::initDelay
uint32_t initDelay
Definition: mcspi/v0/mcspi.h:167
MCSPI_TCS0_0_CLK
#define MCSPI_TCS0_0_CLK
0.5 clock cycles delay
Definition: mcspi_lld.h:319
MCSPI_reConfigFifo
int32_t MCSPI_reConfigFifo(MCSPI_Handle handle, uint32_t chNum, uint32_t numWordsRxTx)
Function to re-configure Effective FIFO Words.
MCSPI_OpenParams::transferMode
uint32_t transferMode
Definition: mcspi/v0/mcspi.h:125
MCSPI_SLV_CS_SELECT_0
#define MCSPI_SLV_CS_SELECT_0
Definition: mcspi_lld.h:292
MCSPI_Object
MCSPI driver object.
Definition: mcspi/v0/mcspi.h:181
MCSPI_getBaseAddr
uint32_t MCSPI_getBaseAddr(MCSPI_Handle handle)
Function to get base address of MCSPI instance of a particular handle.
MCSPI_ChConfig::bitRate
uint32_t bitRate
Definition: mcspi_lld.h:574
MCSPI_deinit
void MCSPI_deinit(void)
This function de-initializes the MCSPI module.
MCSPI_Object::handle
MCSPI_Handle handle
Definition: mcspi/v0/mcspi.h:185
MCSPILLD_Object
MCSPI driver object.
Definition: mcspi_lld.h:735
MCSPI_SB_POL_LOW
#define MCSPI_SB_POL_LOW
Start-bit polarity is held to 0 during MCSPI transfer.
Definition: mcspi_lld.h:307
MCSPI_OpenParams
MCSPI Parameters.
Definition: mcspi/v0/mcspi.h:124
MCSPI_DPE_ENABLE
#define MCSPI_DPE_ENABLE
Data line selected for transmission.
Definition: mcspi_lld.h:281
SystemP_WAIT_FOREVER
#define SystemP_WAIT_FOREVER
Value to use when needing a timeout of infinity or wait forver until resource is available.
Definition: SystemP.h:83
MCSPI_Transaction::csDisable
uint32_t csDisable
Definition: mcspi_lld.h:476
MCSPI_IS_D1
#define MCSPI_IS_D1
Data line 1 (SPIDAT[1]) selected for reception.
Definition: mcspi_lld.h:271
SemaphoreP.h
MCSPI_ChConfig::trMode
uint32_t trMode
Definition: mcspi_lld.h:578
MCSPI_TRANSFER_COMPLETED
#define MCSPI_TRANSFER_COMPLETED
Definition: mcspi_lld.h:188
MCSPI_Config::object
MCSPI_Object * object
Definition: mcspi/v0/mcspi.h:232
MCSPI_Attrs::inputClkFreq
uint32_t inputClkFreq
Definition: mcspi/v0/mcspi.h:147
MCSPI_init
void MCSPI_init(void)
This function initializes the MCSPI module.
MCSPI_TR_MODE_TX_RX
#define MCSPI_TR_MODE_TX_RX
Definition: mcspi_lld.h:257
MCSPI_TRANSFER_MODE_BLOCKING
#define MCSPI_TRANSFER_MODE_BLOCKING
MCSPI_transfer() blocks execution. This mode can only be used when called within a Task context
Definition: mcspi/v0/mcspi.h:92
MCSPI_CHANNEL_0
#define MCSPI_CHANNEL_0
Definition: mcspi_lld.h:158
MCSPI_Object::hwiObj
HwiP_Object hwiObj
Definition: mcspi/v0/mcspi.h:206
MCSPI_Object::transferSemObj
SemaphoreP_Object transferSemObj
Definition: mcspi/v0/mcspi.h:202
MCSPI_Attrs::baseAddr
uint32_t baseAddr
Definition: mcspi/v0/mcspi.h:145
MCSPI_Attrs::multiWordAccess
uint32_t multiWordAccess
Definition: mcspi/v0/mcspi.h:169
MCSPI_ChConfig::csPolarity
uint32_t csPolarity
Definition: mcspi_lld.h:576
MCSPI_ChConfig::startBitPolarity
uint32_t startBitPolarity
Definition: mcspi_lld.h:592
MCSPI_Attrs::chMode
uint32_t chMode
Definition: mcspi/v0/mcspi.h:163
MCSPI_transfer
int32_t MCSPI_transfer(MCSPI_Handle handle, MCSPI_Transaction *transaction)
Function to perform MCSPI transactions.
MCSPI_Attrs::intrNum
uint32_t intrNum
Definition: mcspi/v0/mcspi.h:153
HwiP.h
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.
MCSPI_OpenParams::msMode
uint32_t msMode
Definition: mcspi/v0/mcspi.h:131
MCSPI_Handle
struct MCSPI_Config_s * MCSPI_Handle
A handle that is returned from a MCSPI_open() call.
Definition: mcspi/v0/mcspi.h:71
MCSPI_Transaction_init
static void MCSPI_Transaction_init(MCSPI_Transaction *trans)
Function to initialize the MCSPI_Transaction struct to its defaults.
Definition: mcspi/v0/mcspi.h:463
MCSPI_Transaction::args
void * args
Definition: mcspi_lld.h:514
MCSPI_Attrs::pinMode
uint32_t pinMode
Definition: mcspi/v0/mcspi.h:165
mcspi_lld.h
MCSPI LLD Driver API/interface file.
MCSPI_ChConfig::startBitEnable
uint32_t startBitEnable
Definition: mcspi_lld.h:589
MCSPI_Transaction::txBuf
void * txBuf
Definition: mcspi_lld.h:496
MCSPI_Transaction::rxBuf
void * rxBuf
Definition: mcspi_lld.h:507
MCSPI_MAX_NUM_CHANNELS
#define MCSPI_MAX_NUM_CHANNELS
Max number of channels/Chip Select (CS) supported.
Definition: mcspi_lld.h:178
MCSPI_Transaction::dataSize
uint32_t dataSize
Definition: mcspi_lld.h:482
MCSPI_ChConfig_init
static void MCSPI_ChConfig_init(MCSPI_ChConfig *chConfig)
Function to initialize the MCSPI_ChConfig struct to its defaults.
Definition: mcspi/v0/mcspi.h:441
MCSPI_ChConfig::slvCsSelect
uint32_t slvCsSelect
Definition: mcspi_lld.h:586
MCSPI_chConfig
int32_t MCSPI_chConfig(MCSPI_Handle handle, const MCSPI_ChConfig *chCfg)
Function to configure a MCSPI channel.
MCSPI_Attrs::intrPriority
uint8_t intrPriority
Definition: mcspi/v0/mcspi.h:157
MCSPI_getHandle
MCSPI_Handle MCSPI_getHandle(uint32_t index)
Function to return a open'ed MCSPI handle given a MCSPI instance index.
MCSPI_Object::mcspiDmaHandle
void * mcspiDmaHandle
Definition: mcspi/v0/mcspi.h:211
MCSPI_Config
MCSPI global configuration array.
Definition: mcspi/v0/mcspi.h:229
MCSPI_Object::transferSem
void * transferSem
Definition: mcspi/v0/mcspi.h:199
HwiP_Object
Opaque Hwi object used with the Hwi APIs.
Definition: HwiP.h:142
MCSPI_CS_POL_LOW
#define MCSPI_CS_POL_LOW
SPIEN (CS) is held low during the ACTIVE state.
Definition: mcspi_lld.h:248
MCSPI_Object::openPrms
MCSPI_OpenParams openPrms
Definition: mcspi/v0/mcspi.h:187
MCSPI_ChConfig::defaultTxData
uint32_t defaultTxData
Definition: mcspi_lld.h:600
MCSPI_OpenParams_init
static void MCSPI_OpenParams_init(MCSPI_OpenParams *openPrms)
Function to initialize the MCSPI_OpenParams struct to its defaults.
Definition: mcspi/v0/mcspi.h:430
MCSPI_ChConfig::dpe1
uint32_t dpe1
Definition: mcspi_lld.h:584
gMcspiConfigNum
uint32_t gMcspiConfigNum
Externally defined driver configuration array size.
MCSPI_DmaChConfig
struct MCSPI_DmaChConfig_s * MCSPI_DmaChConfig
Definition: mcspi_dma_edma.h:78
MCSPI_OpenParams::mcspiDmaIndex
int32_t mcspiDmaIndex
Definition: mcspi/v0/mcspi.h:133
MCSPI_Transaction::channel
uint32_t channel
Definition: mcspi_lld.h:473
MCSPI_ChConfig::inputSelect
uint32_t inputSelect
Definition: mcspi_lld.h:580
MCSPI_Object::isOpen
uint32_t isOpen
Definition: mcspi/v0/mcspi.h:197
MCSPI_ChConfig::dpe0
uint32_t dpe0
Definition: mcspi_lld.h:582
MCSPI_MS_MODE_CONTROLLER
#define MCSPI_MS_MODE_CONTROLLER
The module generates the clock and CS.
Definition: mcspi_lld.h:212
MCSPI_open
MCSPI_Handle MCSPI_open(uint32_t index, const MCSPI_OpenParams *openPrms)
This function opens a given MCSPI peripheral.
MCSPI_ChConfig
MCSPI configuration parameters for the channel.
Definition: mcspi_lld.h:569
gMcspiConfig
MCSPI_Config gMcspiConfig[]
Externally defined driver configuration array.
MCSPI_OpenParams::transferCallbackFxn
MCSPI_CallbackFxn transferCallbackFxn
Definition: mcspi/v0/mcspi.h:129
MCSPI_Object::baseAddr
uint32_t baseAddr
Definition: mcspi/v0/mcspi.h:189
MCSPI_Config::attrs
const MCSPI_Attrs * attrs
Definition: mcspi/v0/mcspi.h:230
MCSPI_Object::mcspiLldObject
MCSPILLD_Object mcspiLldObject
Definition: mcspi/v0/mcspi.h:213
MCSPI_Object::transaction
MCSPI_Transaction * transaction
Definition: mcspi/v0/mcspi.h:209
MCSPI_ChConfig::frameFormat
uint32_t frameFormat
Definition: mcspi_lld.h:572
MCSPI_ChConfig::csIdleTime
uint32_t csIdleTime
Definition: mcspi_lld.h:597
MCSPI_ChConfig::chNum
uint32_t chNum
Definition: mcspi_lld.h:570
MCSPI_Object::hwiHandle
void * hwiHandle
Definition: mcspi/v0/mcspi.h:204
MCSPI_Object::mcspiLldInitObj
MCSPILLD_InitObject mcspiLldInitObj
Definition: mcspi/v0/mcspi.h:215