1 /*
2 * Copyright (c) 2014-2019, Texas Instruments Incorporated
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 *
9 * * Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 *
12 * * Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the 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 "AS IS"
21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
22 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
27 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
28 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
29 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
30 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 */
33 /**
34 * \defgroup DRV_UART_MODULE UART Driver
35 *
36 * @{
37 */
38 /* @} */
40 /**
41 * \ingroup DRV_UART_MODULE
42 * \defgroup DRV_UART_API_MODULE UART Driver API
43 * UART driver interface
44 *
45 * @{
46 */
48 /** ============================================================================
49 * @file UART.h
50 *
51 * @brief UART driver interface
52 *
53 * The UART header file should be included in an application as follows:
54 * @code
55 * #include <ti/drv/uart/UART.h>
56 * @endcode
57 *
58 * # Operation #
59 * The UART driver simplifies reading and writing to any of the UART
60 * peripherals on the board with multiple modes of operation and performance.
61 * These include blocking, non-blocking, and polling as well as text/binary
62 * mode, echo and return characters. The boards UART peripheral and pins must
63 * be configured before initializing the UART driver. The application
64 * initializes the UART driver by calling UART_init() and is then ready to
65 * open a UART by calling UART_open() and passing in a UART parameters data
66 * structure.
67 *
68 * The APIs in this driver serve as an interface to a typical TI-RTOS
69 * application. The specific peripheral implementations are responsible to
70 * create all the OS specific primitives to allow for thread-safe
71 * operation.
72 *
73 * ## Opening the driver #
74 *
75 * @code
76 * UART_Handle handle;
77 * UART_Params params;
78 *
79 * UART_Params_init(¶ms);
80 * params.baudRate = someNewBaudRate;
81 * params.writeDataMode = UART_DATA_BINARY;
82 * params.readDataMode = UART_DATA_BINARY;
83 * params.readReturnMode = UART_RETURN_FULL;
84 * params.readEcho = UART_ECHO_OFF;
85 * handle = UART_open(someUART_configIndexValue, ¶ms);
86 * if (!handle) {
87 * System_printf("UART did not open");
88 * }
89 * @endcode
90 *
91 * ## Writing data #
92 *
93 * @code
94 * const unsigned char hello[] = "Hello World\n";
95 *
96 * ret = UART_write(handle, hello, sizeof(hello));
97 * System_printf("The UART wrote %d bytes\n", ret);
98 * @endcode
99 *
100 * ## Reading data #
101 *
102 * @code
103 * unsigned char rxBuffer[20];
104 *
105 * ret = UART_read(handle, rxBuffer, sizeof(rxBuffer));
106 * System_printf("The UART read %d bytes\n", ret);
107 * @endcode
108 *
109 * # Implementation #
110 *
111 * This module serves as the main interface for TI-RTOS
112 * applications. Its purpose is to redirect the module's APIs to specific
113 * peripheral implementations which are specified using a pointer to a
114 * UART_FxnTable.
115 *
116 * The UART driver interface module is joined (at link time) to a
117 * NULL-terminated array of UART_Config data structures named *UART_config*.
118 * *UART_config* is implemented in the application with each entry being an
119 * instance of a UART peripheral. Each entry in *UART_config* contains a:
120 * - (UART_FxnTable *) to a set of functions that implement a UART peripheral
121 * - (void *) data object that is associated with the UART_FxnTable
122 * - (void *) hardware attributes that are associated to the UART_FxnTable
123 *
124 *
125 * ============================================================================
126 */
128 #ifndef ti_drivers_UART__include
129 #define ti_drivers_UART__include
131 #ifdef __cplusplus
132 extern "C" {
133 #endif
135 #include <stdint.h>
136 #include <stddef.h>
139 #define UART_SUCCESS ((int32_t)(0))
140 #define UART_ERROR (-((int32_t)1))
142 /*!
143 * @brief A handle that is returned from a UART_open() call.
144 */
145 typedef struct UART_Config_s *UART_Handle;
147 /*!
148 * @brief The definition of a callback function used by the UART driver
149 * when used in ::UART_MODE_CALLBACK
150 *
151 * @param UART_Handle UART_Handle
152 *
153 * @param buf Pointer to read/write buffer
154 *
155 * @param count Number of elements read/written
156 */
157 typedef void (*UART_Callback) (UART_Handle handle, void *buf, size_t count);
159 /*!
160 * @brief UART transaction timeout define
161 */
162 #define UART_NO_WAIT ((uint32_t)0U)
163 #define UART_WAIT_FOREVER (~((uint32_t)0U))
165 /*!
166 * @brief Transfer API version.
167 */
168 typedef enum UART_TransferApiVer_s {
169 UART_TRANSFER_API_VER_1 = 1,
170 UART_TRANSFER_API_VER_2 = 2
172 } UART_TransferApiVer;
174 /*!
175 * @brief Transfer status codes that are set by the UART driver.
176 */
177 typedef enum UART_TransferStatus_s {
178 UART_TRANSFER_STATUS_SUCCESS = 0,
179 UART_TRANSFER_STATUS_TIMEOUT, /* Time out error */
180 UART_TRANSFER_STATUS_ERROR_BI, /* Break condition error */
181 UART_TRANSFER_STATUS_ERROR_FE, /* Framing error */
182 UART_TRANSFER_STATUS_ERROR_PE, /* Parity error */
183 UART_TRANSFER_STATUS_ERROR_OE, /* Overrun error */
184 UART_TRANSFER_STATUS_ERROR_OTH /* Other error */
186 } UART_TransferStatus;
188 /*!
189 * @brief
190 * A ::UART_Transaction data structure is used with UART_read2(), UART_write2() and UART_Callback2()
191 */
192 typedef struct UART_Transaction_s {
193 /* User input (write-only) fields */
194 void *buf; /**< void * to a buffer with data to be transferred */
195 uint32_t timeout; /**< Timeout for this transaction */
197 /* User input (write-only) and output (read-only) fields */
198 uint32_t count; /**< Number of bytes for this transaction */
200 /* User output (read-only) fields */
201 UART_TransferStatus status; /**< Status code set by UART_read2() and UART_write2() */
203 /* Driver-use only fields */
204 } UART_Transaction;
206 /*!
207 * @brief The definition of a callback2 function used by the UART driver
208 * when used in ::UART_MODE_CALLBACK
209 *
210 * @param UART_Handle UART_Handle
211 *
212 * @param transaction A pointer to a UART_Transaction. All of the fields within
213 * transaction except UART_Transaction.count and
214 * UART_Transaction.status are WO (write-only) unless
215 * otherwise noted in the driver implementations. If a
216 * transaction timeout or error has occured,
217 * UART_Transaction.count will contain the number of bytes
218 * that were transferred.
219 */
220 typedef void (*UART_Callback2) (UART_Handle handle, UART_Transaction *transaction);
222 /*!
223 * @brief UART mode settings
224 *
225 * This enum defines the read and write modes for the
226 * configured UART.
227 */
228 typedef enum UART_Mode_e {
229 /*!
230 * Uses a semaphore to block while data is being sent. Context of the call
231 * must be a Task.
232 */
233 UART_MODE_BLOCKING,
235 /*!
236 * Non-blocking and will return immediately. When the transfer by the Hwi
237 * is finished the configured callback function is called.
238 */
239 UART_MODE_CALLBACK,
240 } UART_Mode;
242 /*!
243 * @brief UART return mode settings
244 *
245 * This enumeration defines the return modes for UART_read and UART_readPolling.
246 * UART_RETURN_FULL unblocks or performs a callback when the read buffer has
247 * been filled.
248 * UART_RETURN_NEWLINE unblocks or performs a callback whenever a newline
249 * character has been received.
250 */
251 typedef enum UART_ReturnMode_e {
252 /*! Unblock/callback when buffer is full. */
253 UART_RETURN_FULL,
255 /*! Unblock/callback when newline character is received. */
256 UART_RETURN_NEWLINE
257 } UART_ReturnMode;
259 /*!
260 * @brief UART data mode settings
261 *
262 * This enumeration defines the data mode for read and write.
263 * If the DataMode is text for write, write will add a return before a newline
264 * character. If the DataMode is text for a read, read will replace a return
265 * with a newline. This effectively treats all device line endings as LF and
266 * all host PC line endings as CRLF.
267 */
268 typedef enum UART_DataMode_e {
269 UART_DATA_BINARY, /*!< Data is not processed */
270 UART_DATA_TEXT /*!< Data is processed according to above */
271 } UART_DataMode;
273 /*!
274 * @brief UART echo settings
275 *
276 * This enumeration defines if the driver will echo data.
277 */
278 typedef enum UART_Echo_e {
279 UART_ECHO_OFF = 0, /*!< Data is not echoed */
280 UART_ECHO_ON = 1 /*!< Data is echoed */
281 } UART_Echo;
283 /*!
284 * @brief UART data length settings
285 *
286 * This enumeration defines the UART data lengths.
287 */
289 typedef enum UART_LEN_e {
290 UART_LEN_5 = 0, /*!< Data length is 5 */
291 UART_LEN_6 = 1, /*!< Data length is 6 */
292 UART_LEN_7 = 2, /*!< Data length is 7 */
293 UART_LEN_8 = 3, /*!< Data length is 8 */
294 #ifdef PRU_ICSS_FW // PRU UART FW SW IP only
295 UART_LEN_9 = 4 /*!< Data length is 9 */
296 #endif
297 } UART_LEN;
299 /*!
300 * @brief UART stop bit settings
301 *
302 * This enumeration defines the UART stop bits.
303 */
304 typedef enum UART_STOP_e {
305 UART_STOP_ONE = 0, /*!< One stop bit */
306 UART_STOP_TWO = 1, /*!< Two stop bits */
307 #ifdef PRU_ICSS_FW // PRU UART FW SW IP only, currently unsupported by HW IP driver
308 UART_STOP_ONEP5 = 2 /*!< One plus one half stop bits */
309 #endif
310 } UART_STOP;
312 /*!
313 * @brief UART parity type settings
314 *
315 * This enumeration defines the UART parity types.
316 */
317 typedef enum UART_PAR_e {
318 UART_PAR_NONE = 0, /*!< No parity */
319 UART_PAR_EVEN = 1, /*!< Parity bit is even */
320 UART_PAR_ODD = 2, /*!< Parity bit is odd */
321 UART_PAR_ZERO = 3, /*!< Parity bit is always zero */
322 UART_PAR_ONE = 4 /*!< Parity bit is always one */
323 } UART_PAR;
325 #ifdef PRU_ICSS_FW // PRU UART FW only
326 /*!
327 * @brief UART flow control settings
328 *
329 * This enumeration defines the UART parity types.
330 */
331 typedef enum UART_FC_TYPE_e {
332 UART_FC_NONE = 0, /*!< No flow control */
333 UART_FC_HW = 1 /*!< Hardware flow control */
334 } UART_FC_TYPE;
335 #endif
337 /*!
338 * @brief Basic UART Parameters
339 */
340 typedef struct UART_Params_s {
341 UART_Mode readMode; /*!< Mode for all read calls */
342 UART_Mode writeMode; /*!< Mode for all write calls */
343 uint32_t readTimeout; /*!< Timeout for read semaphore */
344 uint32_t writeTimeout; /*!< Timeout for write semaphore */
345 UART_Callback readCallback; /*!< Pointer to read callback */
346 UART_Callback writeCallback; /*!< Pointer to write callback */
347 UART_ReturnMode readReturnMode; /*!< Receive return mode */
348 UART_DataMode readDataMode; /*!< Type of data being read */
349 UART_DataMode writeDataMode; /*!< Type of data being written */
350 UART_Echo readEcho; /*!< Echo received data back */
351 uint32_t baudRate; /*!< Baud rate for UART */
352 UART_LEN dataLength; /*!< Data length for UART */
353 UART_STOP stopBits; /*!< Stop bits for UART */
354 UART_PAR parityType; /*!< Parity bit type for UART */
355 UART_Callback2 readCallback2; /**< Pointer to read callback2 */
356 UART_Callback2 writeCallback2; /**< Pointer to write callback2 */
357 #ifdef PRU_ICSS_FW // PRU UART FW only, currently unsupported by HW IP driver
358 UART_FC_TYPE flowControlType; /*!< Flow Control type */
359 uint8_t hwFlowControlThr; /*!< Hardware flow Control threshold, 0-0x100 */
360 #endif
361 } UART_Params;
363 /*!
364 * @brief A function pointer to a driver specific implementation of
365 * UART_CloseFxn().
366 */
367 typedef void (*UART_CloseFxn) (UART_Handle handle);
369 /*!
370 * @brief A function pointer to a driver specific implementation of
371 * UART_control().
372 */
373 typedef int32_t (*UART_ControlFxn) (UART_Handle handle,
374 uint32_t cmd,
375 void *arg);
377 /*!
378 * @brief A function pointer to a driver specific implementation of
379 * UART_init().
380 */
381 typedef void (*UART_InitFxn) (UART_Handle handle);
383 /*!
384 * @brief A function pointer to a driver specific implementation of
385 * UART_OpenFxn().
386 */
387 typedef UART_Handle (*UART_OpenFxn) (UART_Handle handle,
388 const UART_Params *params);
389 /*!
390 * @brief A function pointer to a driver specific implementation of
391 * UART_ReadFxn().
392 */
393 typedef int32_t (*UART_ReadFxn) (UART_Handle handle, void *buffer,
394 size_t size);
396 /*!
397 * @brief A function pointer to a driver specific implementation of
398 * UART_ReadPollingFxn().
399 */
400 typedef int32_t (*UART_ReadPollingFxn) (UART_Handle handle, void *buffer,
401 size_t size);
403 /*!
404 * @brief A function pointer to a driver specific implementation of
405 * UART_ReadCancelFxn().
406 */
407 typedef void (*UART_ReadCancelFxn) (UART_Handle handle);
409 /*!
410 * @brief A function pointer to a driver specific implementation of
411 * UART_CloseFxn().
412 */
413 typedef int32_t (*UART_WriteFxn) (UART_Handle handle,
414 const void *buffer,
415 size_t size);
417 /*!
418 * @brief A function pointer to a driver specific implementation of
419 * UART_WritePollingFxn().
420 */
421 typedef int32_t (*UART_WritePollingFxn) (UART_Handle handle,
422 const void *buffer,
423 size_t size);
425 /*!
426 * @brief A function pointer to a driver specific implementation of
427 * UART_WriteCancelFxn().
428 */
429 typedef void (*UART_WriteCancelFxn) (UART_Handle handle);
431 /*!
432 * @brief A function pointer to a driver specific implementation of
433 * UART_ReadFxn2().
434 */
435 typedef int32_t (*UART_ReadFxn2) (UART_Handle handle,
436 UART_Transaction *transaction);
437 /*!
438 * @brief A function pointer to a driver specific implementation of
439 * UART_WriteFxn2().
440 */
441 typedef int32_t (*UART_WriteFxn2) (UART_Handle handle,
442 UART_Transaction *transaction);
444 /*!
445 * @brief The definition of a UART function table that contains the
446 * required set of functions to control a specific UART driver
447 * implementation.
448 */
449 typedef struct UART_FxnTable_s {
450 /*! Function to close the specified peripheral */
451 UART_CloseFxn closeFxn;
452 /*! Function to implementation specific control function */
453 UART_ControlFxn controlFxn;
454 /*! Function to initialize the given data object */
455 UART_InitFxn uartInitFxn;
456 /*! Function to open the specified peripheral */
457 UART_OpenFxn openFxn;
458 /*! Function to read from the specified peripheral */
459 UART_ReadFxn readFxn;
460 /*! Function to read via polling from the specified peripheral */
461 UART_ReadPollingFxn readPollingFxn;
462 /*! Function to cancel a read from the specified peripheral */
463 UART_ReadCancelFxn readCancelFxn;
464 /*! Function to write from the specified peripheral */
465 UART_WriteFxn writeFxn;
466 /*! Function to write via polling from the specified peripheral */
467 UART_WritePollingFxn writePollingFxn;
468 /*! Function to cancel a write from the specified peripheral */
469 UART_WriteCancelFxn writeCancelFxn;
470 /*! Function to read from the specified peripheral */
471 UART_ReadFxn2 readFxn2;
472 /*! Function to write from the specified peripheral */
473 UART_WriteFxn2 writeFxn2;
475 } UART_FxnTable;
478 /*! @brief UART Global configuration */
479 typedef struct UART_Config_s {
480 /*! Pointer to a table of a driver-specific implementation of UART functions */
481 UART_FxnTable const *fxnTablePtr;
483 /*! Pointer to a driver specific data object */
484 void *object;
486 /*! Pointer to a driver specific hardware attributes structure */
487 void const *hwAttrs;
488 } UART_Config;
490 #define UART_MAX_CONFIG_CNT (14U)
491 typedef UART_Config UART_config_list[UART_MAX_CONFIG_CNT];
494 /*!
495 * @brief Function to closes a given UART peripheral specified by the UART
496 * handle.
497 *
498 * @pre UART_open() had to be called first.
499 *
500 * @param uartHnd A UART_Handle returned from UART_open
501 *
502 * @sa UART_open
503 */
504 extern void UART_close(UART_Handle uartHnd);
506 /*!
507 * @brief Function performs implementation specific features on a given
508 * UART_Handle.
509 *
510 * @pre UART_open() has to be called first.
511 *
512 * @param uartHnd A UART handle returned from UART_open()
513 *
514 * @param cmd A command value defined by the driver specific implementation
515 *
516 * @param arg An optional argument that is accompanied with cmd
517 *
518 * @return Implementation specific return codes. Negative values indicate
519 * unsuccessful operations.
520 *
521 * @sa UART_open()
522 */
523 extern int32_t UART_control(UART_Handle uartHnd, uint32_t cmd, void *arg);
525 /*!
526 * @brief Function to initializes the UART module
527 *
528 * @pre The UART controller needs to be powered up and clocked. The
529 * UART_config structure must exist and be persistent before this
530 * function can be called. This function must also be called before
531 * any other UART driver APIs.
532 */
533 extern void UART_init(void);
535 /*!
536 * @brief Function to initialize a given UART peripheral specified by the
537 * particular index value. The parameter specifies which mode the UART
538 * will operate.
539 *
540 * @pre UART controller has been initialized
541 *
542 * @param idx Logical peripheral number indexed into the HWAttrs
543 * table
544 *
545 * @param uartParams Pointer to an parameter block, if NULL it will use
546 * default values
547 *
548 * @return A UART_Handle on success or a NULL on an error or if it has been
549 * already opened
550 *
551 * @sa UART_close
552 */
553 extern UART_Handle UART_open(uint32_t idx, UART_Params *uartParams);
555 /*!
556 * @brief Function to initialize the UART_Params struct to its defaults
557 *
558 * Defaults values are:
559 * readMode = UART_MODE_BLOCKING;
560 * writeMode = UART_MODE_BLOCKING;
561 * readTimeout = BIOS_WAIT_FOREVER;
562 * writeTimeout = BIOS_WAIT_FOREVER;
563 * readCallback = NULL;
564 * writeCallback = NULL;
565 * readReturnMode = UART_RETURN_NEWLINE;
566 * writeDataMode = UART_DATA_TEXT;
567 * readDataMode = UART_DATA_TEXT;
568 * readEcho = UART_ECHO_ON;
569 * baudRate = 115200;
570 * stopBits = UART_STOP_ONE;
571 * parityType = UART_PAR_NONE;
572 *
573 * @param uartParams Parameter structure to initialize
574 */
575 extern void UART_Params_init(UART_Params *uartParams);
578 /*!
579 * @brief Function that writes data to a UART
580 *
581 * This function initiates an operation to write data to a UART controller.
582 *
583 * In UART_MODE_BLOCKING, UART_write will block task execution until all
584 * the data in buffer has been written.
585 *
586 * In UART_MODE_CALLBACK, UART_write does not block task execution an calls a
587 * callback function specified by writeCallback.
588 *
589 * @param uartHnd A UART_Handle
590 *
591 * @param buffer A pointer to buffer containing data to be written
592 *
593 * @param size The number of bytes in buffer that should be written
594 * onto the UART.
595 *
596 * @return Returns the number of bytes that have been written to the UART,
597 * UART_ERROR on an error.
598 */
599 extern int32_t UART_write(UART_Handle uartHnd, const void *buffer, size_t size);
601 /*!
602 * @brief Function that writes data to a UART
603 *
604 * This function initiates an operation to write data to a UART controller.
605 *
606 * UART_write will not return until all the data was written to the UART.
607 *
608 * @param uartHnd A UART_Handle
609 *
610 * @param buffer A pointer to buffer containing data to be written
611 *
612 * @param size The number of bytes in buffer that should be written
613 * onto the UART.
614 *
615 * @return Returns the number of bytes that have been written to the UART,
616 * UART_ERROR on an error.
617 */
618 extern int32_t UART_writePolling(UART_Handle uartHnd, const void *buffer,
619 size_t size);
621 /*!
622 * @brief Function that cancels a UART_write function call.
623 *
624 * This function cancels an operation to write data to a UART controller
625 * when in UART_MODE_CALLBACK.
626 *
627 * @param handle A UART_Handle
628 */
629 extern void UART_writeCancel(UART_Handle handle);
631 /*!
632 * @brief Function that read data from a UART
633 *
634 * This function initiates an operation to read data from a UART controller.
635 *
636 * In UART_MODE_BLOCKING, UART_read will block task execution until all
637 * the data in buffer has been read.
638 *
639 * In UART_MODE_CALLBACK, UART_read does not block task execution an calls a
640 * callback function specified by readCallback.
641 *
642 * @param handle A UART_Handle
643 *
644 * @param buffer A pointer to an empty buffer in which data should be
645 * written to
646 *
647 * @param size The number of bytes to be written into buffer
648 *
649 * @return Returns the number of bytes that have been read from the UART,
650 * UART_ERROR on an error.
651 */
652 extern int32_t UART_read(UART_Handle handle, void *buffer, size_t size);
654 /*!
655 * @brief Function that reads data from a UART
656 *
657 * This function initiates an operation to read data from a UART controller.
658 *
659 * UART_readPolling will not return until size data was read to the UART.
660 *
661 * @param handle A UART_Handle
662 *
663 * @param buffer A pointer to an empty buffer in which data should be
664 * written to
665 *
666 * @param size The number of bytes to be written into buffer
667 *
668 * @return Returns the number of bytes that have been read from the UART,
669 * UART_ERROR on an error.
670 */
671 extern int32_t UART_readPolling(UART_Handle handle, void *buffer, size_t size);
673 /*!
674 * @brief Function that cancels a UART_read function call.
675 *
676 * This function cancels an operation to read data from a UART controller
677 * when in UART_MODE_CALLBACK.
678 *
679 * @param handle A UART_Handle
680 */
681 extern void UART_readCancel(UART_Handle handle);
683 /*!
684 * @brief Extended function that read data from a UART
685 *
686 * This function initiates an operation to read data from a UART controller.
687 *
688 * In UART_MODE_BLOCKING, UART_read2 will block task execution until all
689 * the data in buffer has been read.
690 *
691 * In UART_MODE_CALLBACK, UART_read2 does not block task execution an calls a
692 * callback function specified by readCallback.
693 *
694 * @param handle A UART_Handle
695 *
696 * @param uartTrans A pointer to a UART_Transaction. All of the fields within
697 * transaction except UART_Transaction.count and
698 * UART_Transaction.status are WO (write-only) unless
699 * otherwise noted in the driver implementations. If a
700 * transaction timeout or error has occured,
701 * UART_Transaction.count will contain the number of bytes
702 * that were transferred. In the callback mode, the application
703 * allocates transaction memory and UART driver owns the pointer
704 * unitil it is returned to the application via the callback
705 * function, thus the memory should not be allocated on the
706 * stack, and dynamic free must occur in the callback (not
707 * immediately after calling read2/write2)
708 *
709 * @return Returns UART_SUCCESS or UART_ERROR on an error.
710 */
711 extern int32_t UART_read2(UART_Handle handle, UART_Transaction *uartTrans);
713 /*!
714 * @brief Extended function that writes data to a UART
715 *
716 * This function initiates an operation to write data to a UART controller.
717 *
718 * In UART_MODE_BLOCKING, UART_write will block task execution until all
719 * the data in buffer has been written.
720 *
721 * In UART_MODE_CALLBACK, UART_write does not block task execution an calls a
722 * callback function specified by writeCallback.
723 *
724 * @param handle A UART_Handle
725 *
726 * @param uartTrans A pointer to a UART_Transaction. All of the fields within
727 * transaction except UART_Transaction.count and
728 * UART_Transaction.status are WO (write-only) unless
729 * otherwise noted in the driver implementations. If a
730 * transaction timeout or error has occured,
731 * UART_Transaction.count will contain the number of bytes
732 * that were transferred. In the callback mode, the application
733 * allocates transaction memory and UART driver owns the pointer
734 * unitil it is returned to the application via the callback
735 * function, thus the memory should not be allocated on the
736 * stack, and dynamic free must occur in the callback (not
737 * immediately after calling read2/write2)
738 *
739 * @return Returns UART_SUCCESS or UART_ERROR on an error.
740 */
741 extern int32_t UART_write2(UART_Handle handle, UART_Transaction *uartTrans);
743 /*!
744 * @brief Function to initialize the UART_Transaction struct to its defaults
745 *
746 * @param uartTrans A pointer to a UART_Transaction to be initialized.
747 *
748 * @return uartTrans initialized with default values such as:
749 * uartTrans->buf = NULL;
750 * uartTrans->timeout = UART_WAIT_FOREVER;
751 * uartTrans->count = 0;
752 * uartTrans->status = UART_TRANSFER_STATUS_SUCCESS;
753 */
754 extern void UART_transactionInit(UART_Transaction *uartTrans);
756 #ifdef __cplusplus
757 }
758 #endif
760 #endif /* ti_drivers_UART__include */
762 /* @} */