2 * Copyright (c) 2015-2016, Texas Instruments Incorporated
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
9 * * Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
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.
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.
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.
32 /*!*****************************************************************************
34 * @brief UART driver interface
36 * To use the UART driver, ensure that the correct driver library for your
37 * device is linked in and include this header file as follows:
39 * #include <ti/drivers/UART.h>
42 * This module serves as the main interface for applications. Its purpose
43 * is to redirect the UART APIs to specific driver implementations
44 * which are specified using a pointer to a #UART_FxnTable.
47 * A UART is used to translate data between the chip and a serial port.
48 * The UART driver simplifies reading and writing to any of the UART
49 * peripherals on the board, with multiple modes of operation and performance.
50 * These include blocking, non-blocking, and polling, as well as text/binary
51 * mode, echo and return characters.
53 * The APIs in this driver serve as an interface to a typical RTOS
54 * application. The specific peripheral implementations are responsible for
55 * creating all the RTOS specific primitives to allow for thread-safe
60 * The UART driver interface provides device independent APIs, data types,
61 * and macros. The following code example opens a UART instance, reads
62 * a byte from the UART, and then writes the byte back to the UART.
67 * UART_Params uartParams;
69 * // Initialize the UART driver.
72 * // Create a UART with data processing off.
73 * UART_Params_init(&uartParams);
74 * uartParams.writeDataMode = UART_DATA_BINARY;
75 * uartParams.readDataMode = UART_DATA_BINARY;
76 * uartParams.readReturnMode = UART_RETURN_FULL;
77 * uartParams.readEcho = UART_ECHO_OFF;
78 * uartParams.baudRate = 9600;
80 * // Open an instance of the UART drivers
81 * uart = UART_open(Board_UART0, &uartParams);
84 * // UART_open() failed
88 * // Loop forever echoing
90 * UART_read(uart, &input, 1);
91 * UART_write(uart, &input, 1);
95 * Details for the example code above are described in the following
99 * ### UART Driver Configuration #
101 * In order to use the UART APIs, the application is required
102 * to provide device-specific UART configuration in the Board.c file.
103 * The UART driver interface defines a configuration data structure:
106 * typedef struct UART_Config_ {
107 * UART_FxnTable const *fxnTablePtr;
109 * void const *hwAttrs;
113 * The application must declare an array of UART_Config elements, named
114 * UART_config[]. Each element of UART_config[] are populated with
115 * pointers to a device specific UART driver implementation's function
116 * table, driver object, and hardware attributes. The hardware attributes
117 * define properties such as the UART peripheral's base address, and
118 * the pins for RX and TX. Each element in UART_config[] corresponds to
119 * a UART instance, and none of the elements should have NULL pointers.
120 * There is no correlation between the index and the peripheral designation
121 * (such as UART0 or UART1). For example, it is possible to use
122 * UART_config[0] for UART1.
124 * You will need to check the device-specific UART driver implementation's
125 * header file for example configuration. Please also refer to the
126 * Board.c file of any of your examples to see the UART configuration.
128 * ### Initializing the UART Driver #
130 * UART_init() must be called before any other UART APIs. This function
131 * calls the device implementation's UART initialization function, for each
132 * element of UART_config[].
134 * ### Opening the UART Driver #
136 * Opening a UART requires four steps:
137 * 1. Create and initialize a UART_Params structure.
138 * 2. Fill in the desired parameters.
139 * 3. Call UART_open(), passing the index of the UART in the UART_config
140 * structure, and the address of the UART_Params structure. The
141 * UART instance is specified by the index in the UART_config structure.
142 * 4. Check that the UART handle returned by UART_open() is non-NULL,
143 * and save it. The handle will be used to read and write to the
144 * UART you just opened.
146 * Only one UART index can be used at a time; calling UART_open() a second
147 * time with the same index previosly passed to UART_open() will result in
148 * an error. You can, though, re-use the index if the instance is closed
150 * In the example code, Board_UART0 is passed to UART_open(). This macro
151 * is defined in the example's Board.h file.
154 * ### Modes of Operation #
156 * The UART driver can operate in blocking mode or callback mode, by
157 * setting the writeMode and readMode parameters passed to UART_open().
158 * If these parameters are not set, as in the example code, the UART
159 * driver defaults to blocking mode. Options for the writeMode and
160 * readMode parameters are #UART_MODE_BLOCKING and #UART_MODE_CALLBACK:
162 * - #UART_MODE_BLOCKING uses a semaphore to block while data is being sent.
163 * The context of calling UART_read() or UART_write() must be a Task when
164 * using #UART_MODE_BLOCKING. The UART_write() or UART_read() call
165 * will block until all data is sent or received, or the write timeout or
166 * read timeout expires, whichever happens first.
168 * - #UART_MODE_CALLBACK is non-blocking and UART_read() and UART_write()
169 * will return while data is being sent in the context of a hardware
170 * interrupt. When the read or write finishes, the UART driver will call
171 * the user's callback function. In some cases, the UART data transfer
172 * may have been canceled, or a newline may have been received, so the
173 * number of bytes sent/received are passed to the callback function. Your
174 * implementation of the callback function can use this imformation
175 * as needed. Since the user's callback may be called in the context of an
176 * ISR, the callback function must not make any RTOS blocking calls.
178 * The example sets the writeDataMode and readDataMode parameters to
179 * #UART_DATA_BINARY. Options for these parameters are #UART_DATA_BINARY
180 * and #UART_DATA_TEXT:
182 * - #UART_DATA_BINARY: The data is passed as is, without processing.
184 * - #UART_DATA_TEXT: Write actions add a carriage return before a
185 * newline character, and read actions replace a return with a newline.
186 * This effectively treats all device line endings as LF and all host
187 * PC line endings as CRLF.
189 * Other parameters set by the example are readReturnMode and readEcho.
190 * Options for the readReturnMode parameter are #UART_RETURN_FULL and
191 * #UART_RETURN_NEWLINE:
193 * - #UART_RETURN_FULL: The read action unblocks or returns when the buffer
195 * - #UART_RETURN_NEWLINE: The read action unblocks or returns when a
196 * newline character if read, before the buffer is full.
198 * Options for the readEcho parameter are #UART_ECHO_OFF and #UART_ECHO_ON.
199 * This parameter determines whether the driver echoes data back to the
200 * UART. When echo is turned on, each character that is read by the target
201 * is written back, independent of any write operations. If data is
202 * received in the middle of a write and echo is turned on, the echoed
203 * characters will be mixed in with the write data.
205 * ### Reading and Writing data #
207 * The example code reads one byte frome the UART instance, and then writes
208 * one byte back to the same instance:
211 * UART_read(uart, &input, 1);
212 * UART_write(uart, &input, 1);
215 * The UART driver allows full duplex data transfers. Therefore, it is
216 * possible to call UART_read() and UART_write() at the same time (for
217 * either blocking or callback modes). It is not possible, however,
218 * to issue multiple concurrent operations in the same direction.
219 * For example, if one thread calls UART_read(uart0, buffer0...),
220 * any other thread attempting UART_read(uart0, buffer1...) will result in
221 * an error of UART_ERROR, until all the data from the first UART_read()
222 * has been transferred to buffer0. This applies to both blocking and
223 * and callback modes. So applications must either synchronize
224 * UART_read() (or UART_write()) calls that use the same UART handle, or
225 * check for the UART_ERROR return code indicating that a transfer is still
230 * The UART driver interface module is joined (at link time) to an
231 * array of UART_Config data structures named *UART_config*.
232 * UART_config is implemented in the application with each entry being an
233 * instance of a UART peripheral. Each entry in *UART_config* contains a:
234 * - (UART_FxnTable *) to a set of functions that implement a UART peripheral
235 * - (void *) data object that is associated with the UART_FxnTable
236 * - (void *) hardware attributes that are associated with the UART_FxnTable
238 * The UART APIs are redirected to the device specific implementations
239 * using the UART_FxnTable pointer of the UART_config entry.
240 * In order to use device specific functions of the UART driver directly,
241 * link in the correct driver library for your device and include the
242 * device specific UART driver header file (which in turn includes UART.h).
243 * For example, for the MSP432 family of devices, you would include the
244 * following header file:
246 * #include <ti/drivers/uart/UARTMSP432.h>
249 * ### Stack Requirements #
250 * It is STRONGLY discouraged to perform UART_read() or UART_write()
251 * calls within the driver's own callback function when in
252 * #UART_MODE_CALLBACK mode. Doing so will incur additional task or system
253 * stack size requirements. See the peripheral implementations'
254 * documentation for stack size estimations. It is expected that the
255 * user perform their own stack and usage analysis when choosing to
258 *******************************************************************************
261 #ifndef ti_drivers_UART__include
262 #define ti_drivers_UART__include
272 * @defgroup UART_CONTROL UART_control command and status codes
273 * These UART macros are reservations for UART.h
278 * Common UART_control command code reservation offset.
279 * UART driver implementations should offset command codes with
280 * UART_CMD_RESERVED growing positively
282 * Example implementation specific command codes:
284 * #define UARTXYZ_CMD_COMMAND0 UART_CMD_RESERVED + 0
285 * #define UARTXYZ_CMD_COMMAND1 UART_CMD_RESERVED + 1
288 #define UART_CMD_RESERVED (32)
291 * Common UART_control status code reservation offset.
292 * UART driver implementations should offset status codes with
293 * UART_STATUS_RESERVED growing negatively.
295 * Example implementation specific status codes:
297 * #define UARTXYZ_STATUS_ERROR0 UART_STATUS_RESERVED - 0
298 * #define UARTXYZ_STATUS_ERROR1 UART_STATUS_RESERVED - 1
299 * #define UARTXYZ_STATUS_ERROR2 UART_STATUS_RESERVED - 2
302 #define UART_STATUS_RESERVED (-32)
305 * @defgroup UART_STATUS Status Codes
306 * UART_STATUS_* macros are general status codes returned by UART_control()
308 * @ingroup UART_CONTROL
312 * @brief Successful status code returned by UART_control().
314 * UART_control() returns UART_STATUS_SUCCESS if the control code was executed
317 #define UART_STATUS_SUCCESS (0)
320 * @brief Generic error status code returned by UART_control().
322 * UART_control() returns UART_STATUS_ERROR if the control code was not executed
325 #define UART_STATUS_ERROR (-1)
328 * @brief An error status code returned by UART_control() for undefined
331 * UART_control() returns UART_STATUS_UNDEFINEDCMD if the control code is not
332 * recognized by the driver implementation.
334 #define UART_STATUS_UNDEFINEDCMD (-2)
338 * @defgroup UART_CMD Command Codes
339 * UART_CMD_* macros are general command codes for UART_control(). Not all UART
340 * driver implementations support these command codes.
342 * @ingroup UART_CONTROL
346 * @brief Command code used by UART_control() to read the next unsigned char.
348 * This command is used to read the next unsigned char from the UART's circular
349 * buffer without removing it. With this command code, @b arg is a pointer to an
350 * integer. @b *arg contains the next @c unsigned @c char read if data is
351 * present, else @b *arg is set to #UART_ERROR.
353 #define UART_CMD_PEEK (0)
356 * @brief Command code used by UART_control() to determine if the read buffer
359 * This command is used to determine if there are any unsigned chars available
360 * to read from the UART's circular buffer using UART_read(). With this command
361 * code, @b arg is a pointer to a @c bool. @b *arg contains @c true if data is
362 * available, else @c false.
364 #define UART_CMD_ISAVAILABLE (1)
367 * @brief Command code used by UART_control() to determine how many unsigned
368 * chars are in the read buffer.
370 * This command is used to determine how many @c unsigned @c chars are available
371 * to read from the UART's circular buffer using UART_read(). With this command
372 * code, @b arg is a pointer to an @a integer. @b *arg contains the number of
373 * @c unsigned @c chars available to read.
375 #define UART_CMD_GETRXCOUNT (2)
378 * @brief Command code used by UART_control() to enable data receive by the
381 * This command is used to enable the UART in such a way that it stores received
382 * unsigned chars into the circular buffer. For drivers that support power
383 * management, this typically means that the UART will set a power constraint
384 * while receive is enabled. UART_open() will always have this option
385 * enabled. With this command code, @b arg is @a don't @a care.
387 #define UART_CMD_RXENABLE (3)
390 * @brief Command code used by UART_control() to disable data received by the
393 * This command is used to disable the UART in such a way that ignores the data
394 * it receives. For drivers that support power management, this typically means
395 * that the driver will release any power constraints, to permit the system to
396 * enter low power modes. With this command code, @b arg is @a don't @a care.
398 * @warning A call to UART_read() does @b NOT re-enable receive.
400 #define UART_CMD_RXDISABLE (4)
405 #define UART_ERROR (UART_STATUS_ERROR)
408 * @brief Wait forever define
410 #define UART_WAIT_FOREVER (~(0U))
413 * @brief A handle that is returned from a UART_open() call.
415 typedef struct UART_Config_ *UART_Handle;
418 * @brief The definition of a callback function used by the UART driver
419 * when used in #UART_MODE_CALLBACK
420 * The callback can occur in task or HWI context.
422 * @warning Making UART_read() or UART_write() calls within its own callback
423 * routines are STRONGLY discouraged as it will impact Task and
424 * System stack size requirements! See the documentation for the
425 * specific driver implementations for additional estimated stack
428 * @param UART_Handle UART_Handle
430 * @param buf Pointer to read/write buffer
432 * @param count Number of elements read/written
434 typedef void (*UART_Callback) (UART_Handle handle, void *buf, size_t count);
437 * @brief UART mode settings
439 * This enum defines the read and write modes for the configured UART.
441 typedef enum UART_Mode_ {
443 * Uses a semaphore to block while data is being sent. Context of the call
449 * Non-blocking and will return immediately. When UART_write() or
450 * UART_read() has finished, the callback function is called from either
451 * the caller's context or from an interrupt context.
457 * @brief UART return mode settings
459 * This enumeration defines the return modes for UART_read() and
460 * UART_readPolling(). This mode only functions when in #UART_DATA_TEXT mode.
462 * #UART_RETURN_FULL unblocks or performs a callback when the read buffer has
464 * #UART_RETURN_NEWLINE unblocks or performs a callback whenever a newline
465 * character has been received.
467 * UART operation | UART_RETURN_FULL | UART_RETURN_NEWLINE |
468 * -------------- | ---------------- | ------------------- |
469 * UART_read() | Returns when buffer is full | Returns when buffer is full or newline was read |
470 * UART_write() | Sends data as is | Sends data with an additional newline at the end |
472 * @pre UART driver must be used in #UART_DATA_TEXT mode.
474 typedef enum UART_ReturnMode_ {
475 /*! Unblock/callback when buffer is full. */
478 /*! Unblock/callback when newline character is received. */
483 * @brief UART data mode settings
485 * This enumeration defines the data mode for reads and writes.
487 * In #UART_DATA_BINARY, data is passed as is, with no processing.
489 * In #UART_DATA_TEXT mode, the driver will examine the #UART_ReturnMode
490 * value, to determine whether or not to unblock/callback when a newline
491 * is received. Read actions replace a carriage return with a newline,
492 * and write actions add a carriage return before a newline. This
493 * effectively treats all device line endings as LF, and all host PC line
496 typedef enum UART_DataMode_ {
497 UART_DATA_BINARY = 0, /*!< Data is not processed */
498 UART_DATA_TEXT = 1 /*!< Data is processed according to above */
502 * @brief UART echo settings
504 * This enumeration defines if the driver will echo data when uses in
505 * #UART_DATA_TEXT mode. This only applies to data received by the UART.
507 * #UART_ECHO_ON will echo back characters it received while in #UART_DATA_TEXT
509 * #UART_ECHO_OFF will not echo back characters it received in #UART_DATA_TEXT
512 * @pre UART driver must be used in #UART_DATA_TEXT mode.
514 typedef enum UART_Echo_ {
515 UART_ECHO_OFF = 0, /*!< Data is not echoed */
516 UART_ECHO_ON = 1 /*!< Data is echoed */
520 * @brief UART data length settings
522 * This enumeration defines the UART data lengths.
524 typedef enum UART_LEN_ {
525 UART_LEN_5 = 0, /*!< Data length is 5 bits */
526 UART_LEN_6 = 1, /*!< Data length is 6 bits */
527 UART_LEN_7 = 2, /*!< Data length is 7 bits */
528 UART_LEN_8 = 3 /*!< Data length is 8 bits */
532 * @brief UART stop bit settings
534 * This enumeration defines the UART stop bits.
536 typedef enum UART_STOP_ {
537 UART_STOP_ONE = 0, /*!< One stop bit */
538 UART_STOP_TWO = 1 /*!< Two stop bits */
542 * @brief UART parity type settings
544 * This enumeration defines the UART parity types.
546 typedef enum UART_PAR_ {
547 UART_PAR_NONE = 0, /*!< No parity */
548 UART_PAR_EVEN = 1, /*!< Parity bit is even */
549 UART_PAR_ODD = 2, /*!< Parity bit is odd */
550 UART_PAR_ZERO = 3, /*!< Parity bit is always zero */
551 UART_PAR_ONE = 4 /*!< Parity bit is always one */
555 * @brief UART Parameters
557 * UART parameters are used with the UART_open() call. Default values for
558 * these parameters are set using UART_Params_init().
560 * @sa UART_Params_init()
562 typedef struct UART_Params_ {
563 UART_Mode readMode; /*!< Mode for all read calls */
564 UART_Mode writeMode; /*!< Mode for all write calls */
565 uint32_t readTimeout; /*!< Timeout for read calls in blocking mode. */
566 uint32_t writeTimeout; /*!< Timeout for write calls in blocking mode. */
567 UART_Callback readCallback; /*!< Pointer to read callback function for callback mode. */
568 UART_Callback writeCallback; /*!< Pointer to write callback function for callback mode. */
569 UART_ReturnMode readReturnMode; /*!< Receive return mode */
570 UART_DataMode readDataMode; /*!< Type of data being read */
571 UART_DataMode writeDataMode; /*!< Type of data being written */
572 UART_Echo readEcho; /*!< Echo received data back */
573 uint32_t baudRate; /*!< Baud rate for UART */
574 UART_LEN dataLength; /*!< Data length for UART */
575 UART_STOP stopBits; /*!< Stop bits for UART */
576 UART_PAR parityType; /*!< Parity bit type for UART */
577 void *custom; /*!< Custom argument used by driver implementation */
581 * @brief A function pointer to a driver specific implementation of
584 typedef void (*UART_CloseFxn) (UART_Handle handle);
587 * @brief A function pointer to a driver specific implementation of
590 typedef int_fast16_t (*UART_ControlFxn) (UART_Handle handle, uint_fast16_t cmd, void *arg);
593 * @brief A function pointer to a driver specific implementation of
596 typedef void (*UART_InitFxn) (UART_Handle handle);
599 * @brief A function pointer to a driver specific implementation of
602 typedef UART_Handle (*UART_OpenFxn) (UART_Handle handle, UART_Params *params);
604 * @brief A function pointer to a driver specific implementation of
607 typedef int_fast32_t (*UART_ReadFxn) (UART_Handle handle, void *buffer,
611 * @brief A function pointer to a driver specific implementation of
612 * UART_ReadPollingFxn().
614 typedef int_fast32_t (*UART_ReadPollingFxn) (UART_Handle handle, void *buffer,
618 * @brief A function pointer to a driver specific implementation of
619 * UART_ReadCancelFxn().
621 typedef void (*UART_ReadCancelFxn) (UART_Handle handle);
624 * @brief A function pointer to a driver specific implementation of
627 typedef int_fast32_t (*UART_WriteFxn) (UART_Handle handle, const void *buffer,
631 * @brief A function pointer to a driver specific implementation of
632 * UART_WritePollingFxn().
634 typedef int_fast32_t (*UART_WritePollingFxn) (UART_Handle handle,
635 const void *buffer, size_t size);
638 * @brief A function pointer to a driver specific implementation of
639 * UART_WriteCancelFxn().
641 typedef void (*UART_WriteCancelFxn) (UART_Handle handle);
644 * @brief The definition of a UART function table that contains the
645 * required set of functions to control a specific UART driver
648 typedef struct UART_FxnTable_ {
649 /*! Function to close the specified peripheral */
650 UART_CloseFxn closeFxn;
652 /*! Function to implementation specific control function */
653 UART_ControlFxn controlFxn;
655 /*! Function to initialize the given data object */
656 UART_InitFxn initFxn;
658 /*! Function to open the specified peripheral */
659 UART_OpenFxn openFxn;
661 /*! Function to read from the specified peripheral */
662 UART_ReadFxn readFxn;
664 /*! Function to read via polling from the specified peripheral */
665 UART_ReadPollingFxn readPollingFxn;
667 /*! Function to cancel a read from the specified peripheral */
668 UART_ReadCancelFxn readCancelFxn;
670 /*! Function to write from the specified peripheral */
671 UART_WriteFxn writeFxn;
673 /*! Function to write via polling from the specified peripheral */
674 UART_WritePollingFxn writePollingFxn;
676 /*! Function to cancel a write from the specified peripheral */
677 UART_WriteCancelFxn writeCancelFxn;
681 * @brief UART Global configuration
683 * The UART_Config structure contains a set of pointers used to characterize
684 * the UART driver implementation.
686 * This structure needs to be defined before calling UART_init() and it must
687 * not be changed thereafter.
691 typedef struct UART_Config_ {
692 /*! Pointer to a table of driver-specific implementations of UART APIs */
693 UART_FxnTable const *fxnTablePtr;
695 /*! Pointer to a driver specific data object */
698 /*! Pointer to a driver specific hardware attributes structure */
703 * @brief Function to close a UART peripheral specified by the UART handle
705 * @pre UART_open() has been called.
706 * @pre Ongoing asynchronous read or write have been canceled using
707 * UART_readCancel() or UART_writeCancel() respectively.
709 * @param handle A #UART_Handle returned from UART_open()
713 extern void UART_close(UART_Handle handle);
716 * @brief Function performs implementation specific features on a given
719 * Commands for %UART_control() can originate from UART.h or from implementation
720 * specific UART*.h (_UARTCC26XX.h_, _UARTMSP432.h_, etc.. ) files.
721 * While commands from UART.h are API portable across driver implementations,
722 * not all implementations may support all these commands.
723 * Conversely, commands from driver implementation specific UART*.h files add
724 * unique driver capabilities but are not API portable across all UART driver
727 * Commands supported by UART.h follow a UART_CMD_\<cmd\> naming
729 * Commands supported by UART*.h follow a UART*_CMD_\<cmd\> naming
731 * Each control command defines @b arg differently. The types of @b arg are
732 * documented with each command.
734 * See @ref UART_CMD "UART_control command codes" for command codes.
736 * See @ref UART_STATUS "UART_control return status codes" for status codes.
738 * @pre UART_open() has to be called.
740 * @param handle A UART handle returned from UART_open()
742 * @param cmd UART.h or UART*.h commands.
744 * @param arg An optional R/W (read/write) command argument
745 * accompanied with cmd
747 * @return Implementation specific return codes. Negative values indicate
748 * unsuccessful operations.
752 extern int_fast16_t UART_control(UART_Handle handle, uint_fast16_t cmd, void *arg);
755 * @brief Function to initialize the UART module
757 * @pre The UART_config structure must exist and be persistent before this
758 * function can be called. This function must also be called before
759 * any other UART driver APIs.
761 extern void UART_init(void);
764 * @brief Function to initialize a given UART peripheral
766 * Function to initialize a given UART peripheral specified by the
767 * particular index value.
769 * @pre UART_init() has been called
771 * @param index Logical peripheral number for the UART indexed into
772 * the UART_config table
774 * @param params Pointer to a parameter block. If NULL, default
775 * parameter values will be used. All the fields in
776 * this structure are RO (read-only).
778 * @return A #UART_Handle upon success. NULL if an error occurs, or if the
779 * indexed UART peripheral is already opened.
784 extern UART_Handle UART_open(uint_least8_t index, UART_Params *params);
787 * @brief Function to initialize the UART_Params struct to its defaults
789 * @param params An pointer to UART_Params structure for
792 * Defaults values are:
793 * readMode = UART_MODE_BLOCKING;
794 * writeMode = UART_MODE_BLOCKING;
795 * readTimeout = UART_WAIT_FOREVER;
796 * writeTimeout = UART_WAIT_FOREVER;
797 * readCallback = NULL;
798 * writeCallback = NULL;
799 * readReturnMode = UART_RETURN_NEWLINE;
800 * readDataMode = UART_DATA_TEXT;
801 * writeDataMode = UART_DATA_TEXT;
802 * readEcho = UART_ECHO_ON;
804 * dataLength = UART_LEN_8;
805 * stopBits = UART_STOP_ONE;
806 * parityType = UART_PAR_NONE;
808 extern void UART_Params_init(UART_Params *params);
811 * @brief Function that writes data to a UART with interrupts enabled.
813 * %UART_write() writes data from a memory buffer to the UART interface.
814 * The source is specified by \a buffer and the number of bytes to write
815 * is given by \a size.
817 * In #UART_MODE_BLOCKING, UART_write() blocks task execution until all
818 * the data in buffer has been written.
820 * In #UART_MODE_CALLBACK, %UART_write() does not block task execution.
821 * Instead, a callback function specified by UART_Params::writeCallback is
822 * called when the transfer is finished.
823 * The callback function can occur in the caller's task context or in a HWI or
824 * SWI context, depending on the device implementation.
825 * An unfinished asynchronous write operation must always be canceled using
826 * UART_writeCancel() before calling UART_close().
828 * %UART_write() is mutually exclusive to UART_writePolling(). For an opened
829 * UART peripheral, either UART_write() or UART_writePolling() can be used,
832 * @warning Do not call %UART_write() from its own callback function when in
833 * #UART_MODE_CALLBACK.
835 * @sa UART_writePolling()
837 * @param handle A #UART_Handle returned by UART_open()
839 * @param buffer A read-only pointer to buffer containing data to
840 * be written to the UART
842 * @param size The number of bytes in the buffer that should be written
845 * @return Returns the number of bytes that have been written to the UART.
846 * If an error occurs, #UART_ERROR is returned.
847 * In #UART_MODE_CALLBACK mode, the return value is always 0.
849 extern int_fast32_t UART_write(UART_Handle handle, const void *buffer, size_t size);
852 * @brief Function that writes data to a UART, polling the peripheral to
853 * wait until new data can be written. Usage of this API is mutually
854 * exclusive with usage of UART_write().
856 * This function initiates an operation to write data to a UART controller.
858 * UART_writePolling() will not return until all the data was written to the
859 * UART (or to its FIFO if applicable).
863 * @param handle A #UART_Handle returned by UART_open()
865 * @param buffer A read-only pointer to the buffer containing the data to
866 * be written to the UART
868 * @param size The number of bytes in the buffer that should be written
871 * @return Returns the number of bytes that have been written to the UART.
872 * If an error occurs, #UART_ERROR is returned.
874 extern int_fast32_t UART_writePolling(UART_Handle handle, const void *buffer, size_t size);
877 * @brief Function that cancels a UART_write() function call.
879 * This function cancels an asynchronous UART_write() operation and is only
880 * applicable in #UART_MODE_CALLBACK.
881 * UART_writeCancel() calls the registered TX callback function no matter how many bytes
882 * were sent. It is the application's responsibility to check the count argument in
883 * the callback function and handle cases where only a subset of the bytes were sent.
885 * @param handle A #UART_Handle returned by UART_open()
887 extern void UART_writeCancel(UART_Handle handle);
890 * @brief Function that reads data from a UART with interrupt enabled.
892 * %UART_read() reads data from a UART controller. The destination is specified
893 * by \a buffer and the number of bytes to read is given by \a size.
895 * In #UART_MODE_BLOCKING, %UART_read() blocks task execution until all
896 * the data in buffer has been read.
898 * In #UART_MODE_CALLBACK, %UART_read() does not block task execution.
899 * Instead, a callback function specified by UART_Params::readCallback
900 * is called when the transfer is finished.
901 * The callback function can occur in the caller's context or in HWI or SWI
902 * context, depending on the device-specific implementation.
903 * An unfinished asynchronous read operation must always be canceled using
904 * UART_readCancel() before calling UART_close().
906 * %UART_read() is mutually exclusive to UART_readPolling(). For an opened
907 * UART peripheral, either %UART_read() or UART_readPolling() can be used,
910 * @warning Do not call %UART_read() from its own callback function when in
911 * #UART_MODE_CALLBACK.
913 * @sa UART_readPolling()
915 * @param handle A #UART_Handle returned by UART_open()
917 * @param buffer A pointer to an empty buffer to which
918 * received data should be written
920 * @param size The number of bytes to be written into buffer
922 * @return Returns the number of bytes that have been read from the UART,
923 * #UART_ERROR on an error.
925 extern int_fast32_t UART_read(UART_Handle handle, void *buffer, size_t size);
928 * @brief Function that reads data from a UART without interrupts. This API
929 * must be used mutually exclusive with UART_read().
931 * This function initiates an operation to read data from a UART peripheral.
933 * %UART_readPolling() will not return until size data was read to the UART.
937 * @param handle A #UART_Handle returned by UART_open()
939 * @param buffer A pointer to an empty buffer in which
940 * received data should be written to
942 * @param size The number of bytes to be written into buffer
944 * @return Returns the number of bytes that have been read from the UART,
945 * #UART_ERROR on an error.
947 extern int_fast32_t UART_readPolling(UART_Handle handle, void *buffer, size_t size);
950 * @brief Function that cancels a UART_read() function call.
952 * This function cancels an asynchronous UART_read() operation and is only
953 * applicable in #UART_MODE_CALLBACK.
954 * UART_readCancel() calls the registered RX callback function no matter how many bytes
955 * were received. It is the application's responsibility to check the count argument in
956 * the callback function and handle cases where only a subset of the bytes were received.
958 * @param handle A #UART_Handle returned by UART_open()
960 extern void UART_readCancel(UART_Handle handle);
966 #endif /* ti_drivers_UART__include */