AM261x MCU+ SDK: uart.h Source File

| AM261x MCU+ SDK 26.00.00 |

uart/v0/uart.h
Go to the documentation of this file.
1 /*
2 * Copyright (C) 2021-2023 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
48 #ifndef UART_H_
49 #define UART_H_
50
51 /* ========================================================================== */
52 /* Include Files */
53 /* ========================================================================== */
54
55 #include <stdint.h>
56 #include <kernel/dpl/SemaphoreP.h>
57 #include <kernel/dpl/HwiP.h>
58 #include <drivers/hw_include/cslr.h>
59 #include <drivers/hw_include/cslr_uart.h>
60 #include <drivers/hw_include/hw_types.h>
61 #include <drivers/uart/v0/lld/uart_lld.h>
62
63 #ifdef __cplusplus
64 extern "C" {
65 #endif
66
67 /* ========================================================================== */
68 /* Macros & Typedefs */
69 /* ========================================================================== */
70
71 typedef struct UART_Config_s* UART_Handle;
72
92 #define UART_TRANSFER_MODE_BLOCKING (0U)
93
97 #define UART_TRANSFER_MODE_CALLBACK (1U)
98
106 typedef void (*UART_CallbackFxn) (UART_Handle handle,
107 UART_Transaction *transaction);
108
119 typedef struct
120 {
121 uint32_t baudRate;
123 uint32_t dataLength;
125 uint32_t stopBits;
127 uint32_t parityType;
129 uint32_t readMode;
131 uint32_t readReturnMode;
133 uint32_t writeMode;
135 UART_CallbackFxn readCallbackFxn;
137 UART_CallbackFxn writeCallbackFxn;
139 uint32_t hwFlowControl;
141 uint32_t hwFlowControlThr;
144 /*
145 * Driver configuration
146 */
147 uint32_t transferMode;
149 uint32_t intrNum;
151 uint8_t intrPriority;
153 uint32_t skipIntrReg;
155 int32_t uartDmaIndex;
160 /*
161 * UART configuration
162 */
163 uint32_t operMode;
165 uint32_t rxTrigLvl;
167 uint32_t txTrigLvl;
169 uint32_t rxEvtNum;
171 uint32_t txEvtNum;
173 uint32_t timeGuardVal;
174 /* timeguard feature by UART*/
175 } UART_Params;
176
178 typedef struct
179 {
180 /*
181 * SOC configuration
182 */
183 uint32_t baseAddr;
185 uint32_t inputClkFreq;
187 } UART_Attrs;
188
189 /* ========================================================================== */
190 /* Internal/Private Structure Declarations */
191 /* ========================================================================== */
192
196 typedef struct
197 {
198 /*
199 * User parameters
200 */
201 UART_Params prms;
203 /*
204 * UART write variables
205 */
206 const uint8_t *writeBuf;
208 uint32_t writeCount;
210 uint32_t writeSizeRemaining;
212 /*
213 * UART receive variables
214 */
215 uint8_t *readBuf;
217 uint32_t readCount;
219 uint32_t readSizeRemaining;
221 uint32_t rxTimeoutCnt;
223 uint32_t readErrorCnt;
225 /*
226 * UART ransaction status variables
227 */
228 UART_Transaction *readTrans;
230 UART_Transaction *writeTrans;
232 /*
233 * State variables
234 */
235 uint32_t isOpen;
237 SemaphoreP_Object *lock;
239 SemaphoreP_Object lockObj;
241 SemaphoreP_Object *readTransferSem;
244 SemaphoreP_Object readTransferSemObj;
246 SemaphoreP_Object *writeTransferSem;
249 SemaphoreP_Object writeTransferSemObj;
251 HwiP_Object *hwiHandle;
253 HwiP_Object hwiObj;
255 void* uartDmaHandle;
257 UARTLLD_Object uartLld_object;
258 UARTLLD_Handle uartLld_handle;
260 UARTLLD_InitHandle uartLld_initHandle;
261 UARTLLD_InitObject uartLld_initObject;
262 } UART_Object;
263
270 typedef struct UART_Config_s
271 {
272 UART_Attrs *attrs;
274 UART_Object *object;
276 } UART_Config;
277
278 //typedef UART_Config* UART_Handle;
279
281 extern UART_Config gUartConfig[];
283 extern uint32_t gUartConfigNum;
284
285 /* ========================================================================== */
286 /* Global Variables Declarations */
287 /* ========================================================================== */
288
289 /* None */
290
291 /* ========================================================================== */
292 /* Function Declarations */
293 /* ========================================================================== */
294
298 void UART_init(void);
299
303 void UART_deinit(void);
304
321 UART_Handle UART_open(uint32_t index, const UART_Params *prms);
322
332 void UART_close(UART_Handle handle);
333
372 int32_t UART_write(UART_Handle handle, UART_Transaction *trans);
373
408 int32_t UART_read(UART_Handle handle, UART_Transaction *trans);
409
441 int32_t UART_writeCancel(UART_Handle handle, UART_Transaction *trans);
442
474 int32_t UART_readCancel(UART_Handle handle, UART_Transaction *trans);
475
484 UART_Handle UART_getHandle(uint32_t index);
485
495 void UART_flushTxFifo(UART_Handle handle);
496
497 /* ========================================================================== */
498 /* Advanced Function Declarations */
499 /* ========================================================================== */
508 uint32_t UART_getBaseAddr(UART_Handle handle);
509
516 void UART_Transaction_init(UART_Transaction *trans);
517
523 void UART_Params_init(UART_Params *prms);
524
525 #ifdef __cplusplus
526 }
527 #endif
528
529 #endif /* #ifndef UART_H_ */
530
UART_deinit
void UART_deinit(void)
This function de-initializes the UART module.
UART_Object::lockObj
SemaphoreP_Object lockObj
Definition: uart/v0/uart.h:239
UART_Params::timeGuardVal
uint32_t timeGuardVal
Definition: uart/v0/uart.h:173
UART_Object::readTransferSemObj
SemaphoreP_Object readTransferSemObj
Definition: uart/v0/uart.h:244
UART_Object::uartLld_object
UARTLLD_Object uartLld_object
Definition: uart/v0/uart.h:257
UART_Object::readTransferSem
SemaphoreP_Object * readTransferSem
Definition: uart/v0/uart.h:241
UART_Object::writeTrans
UART_Transaction * writeTrans
Definition: uart/v0/uart.h:230
UART_Transaction_init
void UART_Transaction_init(UART_Transaction *trans)
Function to initialize the UART_Transaction struct to its defaults.
UART_Object::readBuf
uint8_t * readBuf
Definition: uart/v0/uart.h:215
UART_getHandle
UART_Handle UART_getHandle(uint32_t index)
Function to return a open'ed UART handle given a UART instance index.
UART_writeCancel
int32_t UART_writeCancel(UART_Handle handle, UART_Transaction *trans)
Function to perform UART canceling of current write transaction.
UART_Object::uartLld_initObject
UARTLLD_InitObject uartLld_initObject
Definition: uart/v0/uart.h:261
UART_Config
UART global configuration array.
Definition: uart/v0/uart.h:271
UART_Params::writeMode
uint32_t writeMode
Definition: uart/v0/uart.h:133
UART_Object::writeSizeRemaining
uint32_t writeSizeRemaining
Definition: uart/v0/uart.h:210
UART_Object::writeTransferSem
SemaphoreP_Object * writeTransferSem
Definition: uart/v0/uart.h:246
UART_Params_init
void UART_Params_init(UART_Params *prms)
Function to initialize the UART_Params struct to its defaults.
UART_CallbackFxn
void(* UART_CallbackFxn)(UART_Handle handle, UART_Transaction *transaction)
The definition of a callback function used by the UART driver when used in UART_TRANSFER_MODE_CALLBAC...
Definition: uart/v0/uart.h:106
UART_Params::dataLength
uint32_t dataLength
Definition: uart/v0/uart.h:123
UART_Params::intrPriority
uint8_t intrPriority
Definition: uart/v0/uart.h:151
UART_write
int32_t UART_write(UART_Handle handle, UART_Transaction *trans)
Function to perform UART write operation.
UART_Params::readMode
uint32_t readMode
Definition: uart/v0/uart.h:129
SemaphoreP.h
UART_Object::writeBuf
const uint8_t * writeBuf
Definition: uart/v0/uart.h:206
UART_Params::rxTrigLvl
uint32_t rxTrigLvl
Definition: uart/v0/uart.h:165
UART_close
void UART_close(UART_Handle handle)
Function to close a UART peripheral specified by the UART handle.
gUartConfig
UART_Config gUartConfig[]
Externally defined driver configuration array.
UARTLLD_InitObject
UART driver initialization object.
Definition: uart_lld.h:500
UART_Object::uartLld_handle
UARTLLD_Handle uartLld_handle
Definition: uart/v0/uart.h:258
UART_Params::uartDmaIndex
int32_t uartDmaIndex
Definition: uart/v0/uart.h:155
UART_Object::uartDmaHandle
void * uartDmaHandle
Definition: uart/v0/uart.h:255
UART_Object::isOpen
uint32_t isOpen
Definition: uart/v0/uart.h:235
UART_flushTxFifo
void UART_flushTxFifo(UART_Handle handle)
Function to flush a TX FIFO of peripheral specified by the UART handle.
UARTLLD_Object
UART driver object.
Definition: uart_lld.h:568
UART_Params::transferMode
uint32_t transferMode
Definition: uart/v0/uart.h:147
UART_Params::skipIntrReg
uint32_t skipIntrReg
Definition: uart/v0/uart.h:153
UART_Config::attrs
UART_Attrs * attrs
Definition: uart/v0/uart.h:272
UART_Object::writeTransferSemObj
SemaphoreP_Object writeTransferSemObj
Definition: uart/v0/uart.h:249
UART_Object::readCount
uint32_t readCount
Definition: uart/v0/uart.h:217
UART_Params::parityType
uint32_t parityType
Definition: uart/v0/uart.h:127
UART_Object::rxTimeoutCnt
uint32_t rxTimeoutCnt
Definition: uart/v0/uart.h:221
UART_Handle
struct UART_Config_s * UART_Handle
Definition: uart/v0/uart.h:71
UART_Object::writeCount
uint32_t writeCount
Definition: uart/v0/uart.h:208
UART_Params::hwFlowControl
uint32_t hwFlowControl
Definition: uart/v0/uart.h:139
UART_Object::readSizeRemaining
uint32_t readSizeRemaining
Definition: uart/v0/uart.h:219
UART_Params::readReturnMode
uint32_t readReturnMode
Definition: uart/v0/uart.h:131
HwiP.h
UART_init
void UART_init(void)
This function initializes the UART module.
UART_Params
UART Parameters.
Definition: uart/v0/uart.h:120
UART_readCancel
int32_t UART_readCancel(UART_Handle handle, UART_Transaction *trans)
Function to perform UART canceling of current read transaction.
UART_Params::baudRate
uint32_t baudRate
Definition: uart/v0/uart.h:121
UART_Params::readCallbackFxn
UART_CallbackFxn readCallbackFxn
Definition: uart/v0/uart.h:135
UART_Object::readErrorCnt
uint32_t readErrorCnt
Definition: uart/v0/uart.h:223
UART_Config::object
UART_Object * object
Definition: uart/v0/uart.h:274
UART_Transaction
Data structure used with UART_read() and UART_write()
Definition: uart_lld.h:457
UART_getBaseAddr
uint32_t UART_getBaseAddr(UART_Handle handle)
Function to get base address of UART instance of a particular handle.
UART_Params::intrNum
uint32_t intrNum
Definition: uart/v0/uart.h:149
UART_Attrs::inputClkFreq
uint32_t inputClkFreq
Definition: uart/v0/uart.h:185
UART_open
UART_Handle UART_open(uint32_t index, const UART_Params *prms)
This function opens a given UART peripheral.
UART_Params::writeCallbackFxn
UART_CallbackFxn writeCallbackFxn
Definition: uart/v0/uart.h:137
HwiP_Object
Opaque Hwi object used with the Hwi APIs.
Definition: HwiP.h:142
UART_Object
UART driver object.
Definition: uart/v0/uart.h:197
UART_Params::hwFlowControlThr
uint32_t hwFlowControlThr
Definition: uart/v0/uart.h:141
UART_Object::readTrans
UART_Transaction * readTrans
Definition: uart/v0/uart.h:228
UART_Params::stopBits
uint32_t stopBits
Definition: uart/v0/uart.h:125
UART_Params::rxEvtNum
uint32_t rxEvtNum
Definition: uart/v0/uart.h:169
gUartConfigNum
uint32_t gUartConfigNum
Externally defined driver configuration array size.
UART_Object::lock
SemaphoreP_Object * lock
Definition: uart/v0/uart.h:237
UART_read
int32_t UART_read(UART_Handle handle, UART_Transaction *trans)
Function to perform UART read operation.
uart_lld.h
This file contains the prototype of UART driver APIs.
UART_Attrs
UART instance attributes - used during init time.
Definition: uart/v0/uart.h:179
UART_Object::hwiHandle
HwiP_Object * hwiHandle
Definition: uart/v0/uart.h:251
UART_Params::txEvtNum
uint32_t txEvtNum
Definition: uart/v0/uart.h:171
UART_Attrs::baseAddr
uint32_t baseAddr
Definition: uart/v0/uart.h:183
UART_Object::uartLld_initHandle
UARTLLD_InitHandle uartLld_initHandle
Definition: uart/v0/uart.h:260
UART_Object::hwiObj
HwiP_Object hwiObj
Definition: uart/v0/uart.h:253
UART_Object::prms
UART_Params prms
Definition: uart/v0/uart.h:201
UART_Params::txTrigLvl
uint32_t txTrigLvl
Definition: uart/v0/uart.h:167
UART_Params::operMode
uint32_t operMode
Definition: uart/v0/uart.h:163