1 /* 2 * Copyright (c) 2015-2020, 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 */ 32 /*!***************************************************************************** 33 * @file UART.h 34 * @brief Universal Asynchronous Receiver-Transmitter (UART) Driver 35 * 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: 38 * @code 39 * #include <ti/drivers/UART.h> 40 * @endcode 41 * 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. 45 * 46 * @anchor ti_drivers_UART_Overview 47 * # Overview 48 * A UART is used to translate data between the chip and a serial port. 49 * The UART driver simplifies reading and writing to any of the UART 50 * peripherals on the board, with multiple modes of operation and performance. 51 * These include blocking, non-blocking, and polling, as well as text/binary 52 * mode, echo and return characters. 53 * 54 * The UART driver interface provides device independent APIs, data types, 55 * and macros. The APIs in this driver serve as an interface to a typical RTOS 56 * application. The specific peripheral implementations are responsible for 57 * creating all the RTOS specific primitives to allow for thread-safe 58 * operation. 59 * 60 * <hr> 61 * @anchor ti_drivers_UART_Usage 62 * # Usage 63 * 64 * This documentation provides a basic @ref ti_drivers_UART_Synopsis 65 * "usage summary" and a set of @ref ti_drivers_UART_Examples "examples" 66 * in the form of commented code fragments. Detailed descriptions of the 67 * APIs are provided in subsequent sections. 68 * 69 * @anchor ti_drivers_UART_Synopsis 70 * ## Synopsis 71 * @anchor ti_drivers_UART_Synopsis_Code 72 * @code 73 * // Import the UART driver definitions 74 * #include <ti/drivers/UART.h> 75 * 76 * // One-time initialization of UART driver 77 * UART_init(); 78 * 79 * // Initialize UART parameters 80 * UART_Params params; 81 * UART_Params_init(¶ms); 82 * params.baudRate = 9600; 83 * params.readMode = UART_MODE_BLOCKING; 84 * params.writeMode = UART_MODE_BLOCKING; 85 * params.readTimeout = UART_WAIT_FOREVER; 86 * params.writeTimeout = UART_WAIT_FOREVER; 87 * 88 * // Open the UART 89 * UART_Handle uart; 90 * uart = UART_open(CONFIG_UART0, ¶ms); 91 * 92 * // Read from the UART 93 * int32_t readCount; 94 * uint8_t buffer[BUFSIZE]; 95 * readCount = UART_read(uart, buffer, BUFSIZE); 96 * 97 * // Write to the UART 98 * UART_write(uart, buffer, BUFSIZE); 99 * 100 * // Close the UART 101 * UART_close(uart); 102 * @endcode 103 * 104 * <hr> 105 * @anchor ti_drivers_UART_Examples 106 * # Examples 107 * The following code example opens a UART instance, reads 108 * a byte from the UART, and then writes the byte back to the UART. 109 * 110 * @code 111 * char input; 112 * UART_Handle uart; 113 * UART_Params uartParams; 114 * 115 * // Initialize the UART driver. UART_init() must be called before 116 * // calling any other UART APIs. 117 * UART_init(); 118 * 119 * // Create a UART with data processing off. 120 * UART_Params_init(&uartParams); 121 * uartParams.writeDataMode = UART_DATA_BINARY; 122 * uartParams.readDataMode = UART_DATA_BINARY; 123 * uartParams.readReturnMode = UART_RETURN_FULL; 124 * uartParams.baudRate = 115200; 125 * 126 * // Open an instance of the UART drivers 127 * uart = UART_open(CONFIG_UART0, &uartParams); 128 * 129 * if (uart == NULL) { 130 * // UART_open() failed 131 * while (1); 132 * } 133 * 134 * // Loop forever echoing 135 * while (1) { 136 * UART_read(uart, &input, 1); 137 * UART_write(uart, &input, 1); 138 * } 139 * @endcode 140 * 141 * Details for the example code above are described in the following 142 * subsections. 143 * 144 * ### Opening the UART Driver # 145 * 146 * Opening a UART requires four steps: 147 * 1. Create and initialize a UART_Params structure. 148 * 2. Fill in the desired parameters. 149 * 3. Call UART_open(), passing the index of the UART in the UART_config 150 * structure, and the address of the UART_Params structure. The 151 * UART instance is specified by the index in the UART_config structure. 152 * 4. Check that the UART handle returned by UART_open() is non-NULL, 153 * and save it. The handle will be used to read and write to the 154 * UART you just opened. 155 * 156 * Only one UART index can be used at a time; calling UART_open() a second 157 * time with the same index previosly passed to UART_open() will result in 158 * an error. You can, though, re-use the index if the instance is closed 159 * via UART_close(). 160 * In the example code, CONFIG_UART0 is passed to UART_open(). This macro 161 * is defined in the example's ti_drivers_config.h file. 162 * 163 * 164 * ### Modes of Operation # 165 * 166 * The UART driver can operate in blocking mode or callback mode, by 167 * setting the writeMode and readMode parameters passed to UART_open(). 168 * If these parameters are not set, as in the example code, the UART 169 * driver defaults to blocking mode. Options for the writeMode and 170 * readMode parameters are #UART_MODE_BLOCKING and #UART_MODE_CALLBACK: 171 * 172 * - #UART_MODE_BLOCKING uses a semaphore to block while data is being sent. 173 * The context of calling UART_read() or UART_write() must be a Task when 174 * using #UART_MODE_BLOCKING. The UART_write() or UART_read() call 175 * will block until all data is sent or received, or the write timeout or 176 * read timeout expires, whichever happens first. 177 * 178 * - #UART_MODE_CALLBACK is non-blocking and UART_read() and UART_write() 179 * will return while data is being sent in the context of a hardware 180 * interrupt. When the read or write finishes, the UART driver will call 181 * the user's callback function. In some cases, the UART data transfer 182 * may have been canceled, or a newline may have been received, so the 183 * number of bytes sent/received are passed to the callback function. Your 184 * implementation of the callback function can use this information 185 * as needed. Since the user's callback may be called in the context of an 186 * ISR, the callback function must not make any RTOS blocking calls. 187 * The buffer passed to UART_write() in #UART_MODE_CALLBACK is not copied. 188 * The buffer must remain coherent until all the characters have been sent 189 * (ie until the tx callback has been called with a byte count equal to 190 * that passed to UART_write()). 191 * 192 * The example sets the writeDataMode and readDataMode parameters to 193 * #UART_DATA_BINARY. Options for these parameters are #UART_DATA_BINARY 194 * and #UART_DATA_TEXT: 195 * 196 * - #UART_DATA_BINARY: The data is passed as is, without processing. 197 * 198 * - #UART_DATA_TEXT: Write actions add a carriage return before a 199 * newline character, and read actions replace a return with a newline. 200 * This effectively treats all device line endings as LF and all host 201 * PC line endings as CRLF. 202 * 203 * Other parameters set by the example are readReturnMode and readEcho. 204 * Options for the readReturnMode parameter are #UART_RETURN_FULL and 205 * #UART_RETURN_NEWLINE: 206 * 207 * - #UART_RETURN_FULL: The read action unblocks or returns when the buffer 208 * is full. 209 * - #UART_RETURN_NEWLINE: The read action unblocks or returns when a 210 * newline character is read, before the buffer is full. 211 * 212 * Options for the readEcho parameter are #UART_ECHO_OFF and #UART_ECHO_ON. 213 * This parameter determines whether the driver echoes data back to the 214 * UART. When echo is turned on, each character that is read by the target 215 * is written back, independent of any write operations. If data is 216 * received in the middle of a write and echo is turned on, the echoed 217 * characters will be mixed in with the write data. 218 * 219 * ### Reading and Writing data # 220 * 221 * The example code reads one byte frome the UART instance, and then writes 222 * one byte back to the same instance: 223 * 224 * @code 225 * UART_read(uart, &input, 1); 226 * UART_write(uart, &input, 1); 227 * @endcode 228 * 229 * The UART driver allows full duplex data transfers. Therefore, it is 230 * possible to call UART_read() and UART_write() at the same time (for 231 * either blocking or callback modes). It is not possible, however, 232 * to issue multiple concurrent operations in the same direction. 233 * For example, if one thread calls UART_read(uart0, buffer0...), 234 * any other thread attempting UART_read(uart0, buffer1...) will result in 235 * an error of UART_STATUS_ERROR, until all the data from the first UART_read() 236 * has been transferred to buffer0. This applies to both blocking and 237 * and callback modes. So applications must either synchronize 238 * UART_read() (or UART_write()) calls that use the same UART handle, or 239 * check for the UART_STATUS_ERROR return code indicating that a transfer is 240 * still ongoing. 241 * 242 * <hr> 243 * @anchor ti_drivers_UART_Configuration 244 * # Configuration 245 * 246 * Refer to the @ref driver_configuration "Driver's Configuration" section 247 * for driver configuration information. 248 * <hr> 249 * 250 * ============================================================================ 251 */ 252 253 #ifndef ti_drivers_UART__include 254 #define ti_drivers_UART__include 255 256 #include <stddef.h> 257 #include <stdint.h> 258 259 #ifdef __cplusplus 260 extern "C" { 261 #endif 262 263 /** 264 * @defgroup UART_CONTROL UART_control command and status codes 265 * These UART macros are reservations for UART.h 266 * @{ 267 */ 268 269 /*! 270 * Common UART_control command code reservation offset. 271 * UART driver implementations should offset command codes with 272 * UART_CMD_RESERVED growing positively 273 * 274 * Example implementation specific command codes: 275 * @code 276 * #define UARTXYZ_CMD_COMMAND0 UART_CMD_RESERVED + 0 277 * #define UARTXYZ_CMD_COMMAND1 UART_CMD_RESERVED + 1 278 * @endcode 279 */ 280 #define UART_CMD_RESERVED (32) 281 282 /*! 283 * Common UART_control status code reservation offset. 284 * UART driver implementations should offset status codes with 285 * UART_STATUS_RESERVED growing negatively. 286 * 287 * Example implementation specific status codes: 288 * @code 289 * #define UARTXYZ_STATUS_ERROR0 UART_STATUS_RESERVED - 0 290 * #define UARTXYZ_STATUS_ERROR1 UART_STATUS_RESERVED - 1 291 * #define UARTXYZ_STATUS_ERROR2 UART_STATUS_RESERVED - 2 292 * @endcode 293 */ 294 #define UART_STATUS_RESERVED (-32) 295 296 /** 297 * @defgroup UART_STATUS Status Codes 298 * UART_STATUS_* macros are general status codes returned by UART_control() 299 * @{ 300 * @ingroup UART_CONTROL 301 */ 302 303 /*! 304 * @brief Successful status code returned by UART_control(). 305 * 306 * UART_control() returns UART_STATUS_SUCCESS if the control code was executed 307 * successfully. 308 */ 309 #define UART_STATUS_SUCCESS (0) 310 311 /*! 312 * @brief Generic error status code returned by UART_control(). 313 * 314 * UART_control() returns UART_STATUS_ERROR if the control code was not executed 315 * successfully. 316 */ 317 #define UART_STATUS_ERROR (-1) 318 319 /*! 320 * @brief An error status code returned by UART_control() for undefined 321 * command codes. 322 * 323 * UART_control() returns UART_STATUS_UNDEFINEDCMD if the control code is not 324 * recognized by the driver implementation. 325 */ 326 #define UART_STATUS_UNDEFINEDCMD (-2) 327 /** @}*/ 328 329 /** 330 * @defgroup UART_CMD Command Codes 331 * UART_CMD_* macros are general command codes for UART_control(). Not all UART 332 * driver implementations support these command codes. 333 * @{ 334 * @ingroup UART_CONTROL 335 */ 336 337 /*! 338 * @brief Command code used by UART_control() to read the next unsigned char. 339 * 340 * This command is used to read the next unsigned char from the UART's circular 341 * buffer without removing it. With this command code, @b arg is a pointer to an 342 * integer. @b *arg contains the next @c unsigned @c char read if data is 343 * present, else @b *arg is set to #UART_STATUS_ERROR. 344 */ 345 #define UART_CMD_PEEK (0) 346 347 /*! 348 * @brief Command code used by UART_control() to determine if the read buffer 349 * is empty. 350 * 351 * This command is used to determine if there are any unsigned chars available 352 * to read from the UART's circular buffer using UART_read(). With this command 353 * code, @b arg is a pointer to a @c bool. @b *arg contains @c true if data is 354 * available, else @c false. 355 */ 356 #define UART_CMD_ISAVAILABLE (1) 357 358 /*! 359 * @brief Command code used by UART_control() to determine how many unsigned 360 * chars are in the read buffer. 361 * 362 * This command is used to determine how many @c unsigned @c chars are available 363 * to read from the UART's circular buffer using UART_read(). With this command 364 * code, @b arg is a pointer to an @a integer. @b *arg contains the number of 365 * @c unsigned @c chars available to read. 366 */ 367 #define UART_CMD_GETRXCOUNT (2) 368 369 /*! 370 * @brief Command code used by UART_control() to enable data receive by the 371 * UART. 372 * 373 * This command is used to enable the UART in such a way that it stores received 374 * unsigned chars into the circular buffer. For drivers that support power 375 * management, this typically means that the UART will set a power constraint 376 * while receive is enabled. UART_open() will always have this option 377 * enabled. With this command code, @b arg is @a don't @a care. 378 */ 379 #define UART_CMD_RXENABLE (3) 380 381 /*! 382 * @brief Command code used by UART_control() to disable data received by the 383 * UART. 384 * 385 * This command is used to disable the UART in such a way that ignores the data 386 * it receives. For drivers that support power management, this typically means 387 * that the driver will release any power constraints, to permit the system to 388 * enter low power modes. With this command code, @b arg is @a don't @a care. 389 * 390 * @warning A call to UART_read() does @b NOT re-enable receive. 391 */ 392 #define UART_CMD_RXDISABLE (4) 393 /** @}*/ 394 395 /** @}*/ 396 397 #define UART_ERROR (UART_STATUS_ERROR) 398 399 /*! 400 * @brief Wait forever define 401 */ 402 #define UART_WAIT_FOREVER (~(0U)) 403 404 /*! 405 * @brief A handle that is returned from a UART_open() call. 406 */ 407 typedef struct UART_Config_ *UART_Handle; 408 409 /*! 410 * @brief The definition of a callback function used by the UART driver 411 * when used in #UART_MODE_CALLBACK 412 * The callback can occur in task or HWI context. 413 * 414 * @param UART_Handle UART_Handle 415 * 416 * @param buf Pointer to read/write buffer 417 * 418 * @param count Number of elements read/written 419 */ 420 typedef void (*UART_Callback) (UART_Handle handle, void *buf, size_t count); 421 422 /*! 423 * @brief UART mode settings 424 * 425 * This enum defines the read and write modes for the configured UART. 426 */ 427 typedef enum { 428 /*! 429 * Uses a semaphore to block while data is being sent. Context of the call 430 * must be a Task. 431 */ 432 UART_MODE_BLOCKING, 433 434 /*! 435 * Non-blocking and will return immediately. When UART_write() or 436 * UART_read() has finished, the callback function is called from either 437 * the caller's context or from an interrupt context. 438 */ 439 UART_MODE_CALLBACK 440 } UART_Mode; 441 442 /*! 443 * @brief UART return mode settings 444 * 445 * This enumeration defines the return modes for UART_read() and 446 * UART_readPolling(). This mode only functions when in #UART_DATA_TEXT mode. 447 * 448 * #UART_RETURN_FULL unblocks or performs a callback when the read buffer has 449 * been filled. 450 * #UART_RETURN_NEWLINE unblocks or performs a callback whenever a newline 451 * character has been received. 452 * 453 * UART operation | UART_RETURN_FULL | UART_RETURN_NEWLINE | 454 * -------------- | ---------------- | ------------------- | 455 * UART_read() | Returns when buffer is full | Returns when buffer is full or newline was read | 456 * UART_write() | Sends data as is | Sends data with an additional newline at the end | 457 * 458 * @pre UART driver must be used in #UART_DATA_TEXT mode. 459 */ 460 typedef enum { 461 /*! Unblock/callback when buffer is full. */ 462 UART_RETURN_FULL, 463 464 /*! Unblock/callback when newline character is received. */ 465 UART_RETURN_NEWLINE 466 } UART_ReturnMode; 467 468 /*! 469 * @brief UART data mode settings 470 * 471 * This enumeration defines the data mode for reads and writes. 472 * 473 * In #UART_DATA_BINARY, data is passed as is, with no processing. 474 * 475 * In #UART_DATA_TEXT mode, the driver will examine the #UART_ReturnMode 476 * value, to determine whether or not to unblock/callback when a newline 477 * is received. Read actions replace a carriage return with a newline, 478 * and write actions add a carriage return before a newline. This 479 * effectively treats all device line endings as LF, and all host PC line 480 * endings as CRLF. 481 */ 482 typedef enum { 483 UART_DATA_BINARY = 0, /*!< Data is not processed */ 484 UART_DATA_TEXT = 1 /*!< Data is processed according to above */ 485 } UART_DataMode; 486 487 /*! 488 * @brief UART echo settings 489 * 490 * This enumeration defines if the driver will echo data when uses in 491 * #UART_DATA_TEXT mode. This only applies to data received by the UART. 492 * 493 * #UART_ECHO_ON will echo back characters it received while in #UART_DATA_TEXT 494 * mode. 495 * #UART_ECHO_OFF will not echo back characters it received in #UART_DATA_TEXT 496 * mode. 497 * 498 * @pre UART driver must be used in #UART_DATA_TEXT mode. 499 */ 500 typedef enum { 501 UART_ECHO_OFF = 0, /*!< Data is not echoed */ 502 UART_ECHO_ON = 1 /*!< Data is echoed */ 503 } UART_Echo; 504 505 /*! 506 * @brief UART data length settings 507 * 508 * This enumeration defines the UART data lengths. 509 */ 510 typedef enum { 511 UART_LEN_5 = 0, /*!< Data length is 5 bits */ 512 UART_LEN_6 = 1, /*!< Data length is 6 bits */ 513 UART_LEN_7 = 2, /*!< Data length is 7 bits */ 514 UART_LEN_8 = 3 /*!< Data length is 8 bits */ 515 } UART_LEN; 516 517 /*! 518 * @brief UART stop bit settings 519 * 520 * This enumeration defines the UART stop bits. 521 */ 522 typedef enum { 523 UART_STOP_ONE = 0, /*!< One stop bit */ 524 UART_STOP_TWO = 1 /*!< Two stop bits */ 525 } UART_STOP; 526 527 /*! 528 * @brief UART parity type settings 529 * 530 * This enumeration defines the UART parity types. 531 */ 532 typedef enum { 533 UART_PAR_NONE = 0, /*!< No parity */ 534 UART_PAR_EVEN = 1, /*!< Parity bit is even */ 535 UART_PAR_ODD = 2, /*!< Parity bit is odd */ 536 UART_PAR_ZERO = 3, /*!< Parity bit is always zero */ 537 UART_PAR_ONE = 4 /*!< Parity bit is always one */ 538 } UART_PAR; 539 540 /*! 541 * @brief UART Parameters 542 * 543 * UART parameters are used with the UART_open() call. Default values for 544 * these parameters are set using UART_Params_init(). 545 * 546 * @sa UART_Params_init() 547 */ 548 typedef struct { 549 UART_Mode readMode; /*!< Mode for all read calls */ 550 UART_Mode writeMode; /*!< Mode for all write calls */ 551 uint32_t readTimeout; /*!< Timeout for read calls in blocking mode. */ 552 uint32_t writeTimeout; /*!< Timeout for write calls in blocking mode. */ 553 UART_Callback readCallback; /*!< Pointer to read callback function for callback mode. */ 554 UART_Callback writeCallback; /*!< Pointer to write callback function for callback mode. */ 555 UART_ReturnMode readReturnMode; /*!< Receive return mode */ 556 UART_DataMode readDataMode; /*!< Type of data being read */ 557 UART_DataMode writeDataMode; /*!< Type of data being written */ 558 UART_Echo readEcho; /*!< Echo received data back */ 559 uint32_t baudRate; /*!< Baud rate for UART */ 560 UART_LEN dataLength; /*!< Data length for UART */ 561 UART_STOP stopBits; /*!< Stop bits for UART */ 562 UART_PAR parityType; /*!< Parity bit type for UART */ 563 void *custom; /*!< Custom argument used by driver implementation */ 564 } UART_Params; 565 566 /*! 567 * @brief A function pointer to a driver specific implementation of 568 * UART_CloseFxn(). 569 */ 570 typedef void (*UART_CloseFxn) (UART_Handle handle); 571 572 /*! 573 * @brief A function pointer to a driver specific implementation of 574 * UART_ControlFxn(). 575 */ 576 typedef int_fast16_t (*UART_ControlFxn) (UART_Handle handle, uint_fast16_t cmd, void *arg); 577 578 /*! 579 * @brief A function pointer to a driver specific implementation of 580 * UART_InitFxn(). 581 */ 582 typedef void (*UART_InitFxn) (UART_Handle handle); 583 584 /*! 585 * @brief A function pointer to a driver specific implementation of 586 * UART_OpenFxn(). 587 */ 588 typedef UART_Handle (*UART_OpenFxn) (UART_Handle handle, UART_Params *params); 589 /*! 590 * @brief A function pointer to a driver specific implementation of 591 * UART_ReadFxn(). 592 */ 593 typedef int_fast32_t (*UART_ReadFxn) (UART_Handle handle, void *buffer, 594 size_t size); 595 596 /*! 597 * @brief A function pointer to a driver specific implementation of 598 * UART_ReadPollingFxn(). 599 */ 600 typedef int_fast32_t (*UART_ReadPollingFxn) (UART_Handle handle, void *buffer, 601 size_t size); 602 603 /*! 604 * @brief A function pointer to a driver specific implementation of 605 * UART_ReadCancelFxn(). 606 */ 607 typedef void (*UART_ReadCancelFxn) (UART_Handle handle); 608 609 /*! 610 * @brief A function pointer to a driver specific implementation of 611 * UART_WriteFxn(). 612 */ 613 typedef int_fast32_t (*UART_WriteFxn) (UART_Handle handle, const void *buffer, 614 size_t size); 615 616 /*! 617 * @brief A function pointer to a driver specific implementation of 618 * UART_WritePollingFxn(). 619 */ 620 typedef int_fast32_t (*UART_WritePollingFxn) (UART_Handle handle, 621 const void *buffer, size_t size); 622 623 /*! 624 * @brief A function pointer to a driver specific implementation of 625 * UART_WriteCancelFxn(). 626 */ 627 typedef void (*UART_WriteCancelFxn) (UART_Handle handle); 628 629 /*! 630 * @brief The definition of a UART function table that contains the 631 * required set of functions to control a specific UART driver 632 * implementation. 633 */ 634 typedef struct { 635 /*! Function to close the specified peripheral */ 636 UART_CloseFxn closeFxn; 637 638 /*! Function to implementation specific control function */ 639 UART_ControlFxn controlFxn; 640 641 /*! Function to initialize the given data object */ 642 UART_InitFxn initFxn; 643 644 /*! Function to open the specified peripheral */ 645 UART_OpenFxn openFxn; 646 647 /*! Function to read from the specified peripheral */ 648 UART_ReadFxn readFxn; 649 650 /*! Function to read via polling from the specified peripheral */ 651 UART_ReadPollingFxn readPollingFxn; 652 653 /*! Function to cancel a read from the specified peripheral */ 654 UART_ReadCancelFxn readCancelFxn; 655 656 /*! Function to write from the specified peripheral */ 657 UART_WriteFxn writeFxn; 658 659 /*! Function to write via polling from the specified peripheral */ 660 UART_WritePollingFxn writePollingFxn; 661 662 /*! Function to cancel a write from the specified peripheral */ 663 UART_WriteCancelFxn writeCancelFxn; 664 } UART_FxnTable; 665 666 /*! 667 * @brief UART Global configuration 668 * 669 * The UART_Config structure contains a set of pointers used to characterize 670 * the UART driver implementation. 671 * 672 * This structure needs to be defined before calling UART_init() and it must 673 * not be changed thereafter. 674 * 675 * @sa UART_init() 676 */ 677 typedef struct UART_Config_ { 678 /*! Pointer to a table of driver-specific implementations of UART APIs */ 679 UART_FxnTable const *fxnTablePtr; 680 681 /*! Pointer to a driver specific data object */ 682 void *object; 683 684 /*! Pointer to a driver specific hardware attributes structure */ 685 void const *hwAttrs; 686 } UART_Config; 687 688 /*! 689 * @brief Function to close a UART peripheral specified by the UART handle 690 * 691 * @pre UART_open() has been called. 692 * @pre Ongoing asynchronous read or write have been canceled using 693 * UART_readCancel() or UART_writeCancel() respectively. 694 * 695 * @param handle A #UART_Handle returned from UART_open() 696 * 697 * @sa UART_open() 698 */ 699 extern void UART_close(UART_Handle handle); 700 701 /*! 702 * @brief Function performs implementation specific features on a given 703 * #UART_Handle. 704 * 705 * Commands for %UART_control() can originate from UART.h or from implementation 706 * specific UART*.h (_UARTCC26XX.h_, _UARTMSP432E4.h_, etc.. ) files. 707 * While commands from UART.h are API portable across driver implementations, 708 * not all implementations may support all these commands. 709 * Conversely, commands from driver implementation specific UART*.h files add 710 * unique driver capabilities but are not API portable across all UART driver 711 * implementations. 712 * 713 * Commands supported by UART.h follow a UART_CMD_\<cmd\> naming 714 * convention.<br> 715 * Commands supported by UART*.h follow a UART*_CMD_\<cmd\> naming 716 * convention.<br> 717 * Each control command defines @b arg differently. The types of @b arg are 718 * documented with each command. 719 * 720 * See @ref UART_CMD "UART_control command codes" for command codes. 721 * 722 * See @ref UART_STATUS "UART_control return status codes" for status codes. 723 * 724 * @pre UART_open() has to be called. 725 * 726 * @param handle A UART handle returned from UART_open() 727 * 728 * @param cmd UART.h or UART*.h commands. 729 * 730 * @param arg An optional R/W (read/write) command argument 731 * accompanied with cmd 732 * 733 * @return Implementation specific return codes. Negative values indicate 734 * unsuccessful operations. 735 * 736 * @sa UART_open() 737 */ 738 extern int_fast16_t UART_control(UART_Handle handle, uint_fast16_t cmd, void *arg); 739 740 /*! 741 * @brief Function to initialize the UART module 742 * 743 * @pre The UART_config structure must exist and be persistent before this 744 * function can be called. This function must also be called before 745 * any other UART driver APIs. 746 */ 747 extern void UART_init(void); 748 749 /*! 750 * @brief Function to initialize a given UART peripheral 751 * 752 * Function to initialize a given UART peripheral specified by the 753 * particular index value. 754 * 755 * @pre UART_init() has been called 756 * 757 * @param index Logical peripheral number for the UART indexed into 758 * the UART_config table 759 * 760 * @param params Pointer to a parameter block. If NULL, default 761 * parameter values will be used. All the fields in 762 * this structure are RO (read-only). 763 * 764 * @return A #UART_Handle upon success. NULL if an error occurs, or if the 765 * indexed UART peripheral is already opened. 766 * 767 * @sa UART_init() 768 * @sa UART_close() 769 */ 770 extern UART_Handle UART_open(uint_least8_t index, UART_Params *params); 771 772 /*! 773 * @brief Function to initialize the UART_Params struct to its defaults 774 * 775 * @param params An pointer to UART_Params structure for 776 * initialization 777 * 778 * Defaults values are: 779 * readMode = UART_MODE_BLOCKING; 780 * writeMode = UART_MODE_BLOCKING; 781 * readTimeout = UART_WAIT_FOREVER; 782 * writeTimeout = UART_WAIT_FOREVER; 783 * readCallback = NULL; 784 * writeCallback = NULL; 785 * readReturnMode = UART_RETURN_NEWLINE; 786 * readDataMode = UART_DATA_TEXT; 787 * writeDataMode = UART_DATA_TEXT; 788 * readEcho = UART_ECHO_ON; 789 * baudRate = 115200; 790 * dataLength = UART_LEN_8; 791 * stopBits = UART_STOP_ONE; 792 * parityType = UART_PAR_NONE; 793 */ 794 extern void UART_Params_init(UART_Params *params); 795 796 /*! 797 * @brief Function that writes data to a UART with interrupts enabled. 798 * 799 * %UART_write() writes data from a memory buffer to the UART interface. 800 * The source is specified by \a buffer and the number of bytes to write 801 * is given by \a size. 802 * 803 * In #UART_MODE_BLOCKING, UART_write() blocks task execution until all 804 * the data in buffer has been written. 805 * 806 * In #UART_MODE_CALLBACK, %UART_write() does not block task execution. 807 * Instead, a callback function specified by UART_Params::writeCallback is 808 * called when the transfer is finished. The buffer passed to UART_write() 809 * in #UART_MODE_CALLBACK is not copied. The buffer must remain coherent 810 * until all the characters have been sent (ie until the tx callback has 811 * been called with a byte count equal to that passed to UART_write()). 812 * The callback function can occur in the caller's task context or in a HWI or 813 * SWI context, depending on the device implementation. 814 * An unfinished asynchronous write operation must always be canceled using 815 * UART_writeCancel() before calling UART_close(). 816 * 817 * %UART_write() is mutually exclusive to UART_writePolling(). For an opened 818 * UART peripheral, either UART_write() or UART_writePolling() can be used, 819 * but not both. 820 * 821 * @sa UART_writePolling() 822 * 823 * @param handle A #UART_Handle returned by UART_open() 824 * 825 * @param buffer A read-only pointer to buffer containing data to 826 * be written to the UART 827 * 828 * @param size The number of bytes in the buffer that should be written 829 * to the UART 830 * 831 * @return Returns the number of bytes that have been written to the UART. 832 * If an error occurs, #UART_STATUS_ERROR is returned. 833 * In #UART_MODE_CALLBACK mode, the return value is always 0. 834 */ 835 extern int_fast32_t UART_write(UART_Handle handle, const void *buffer, size_t size); 836 837 /*! 838 * @brief Function that writes data to a UART, polling the peripheral to 839 * wait until new data can be written. Usage of this API is mutually 840 * exclusive with usage of UART_write(). 841 * 842 * This function initiates an operation to write data to a UART controller. 843 * 844 * UART_writePolling() will not return until all the data was written to the 845 * UART (or to its FIFO if applicable). 846 * 847 * @sa UART_write() 848 * 849 * @param handle A #UART_Handle returned by UART_open() 850 * 851 * @param buffer A read-only pointer to the buffer containing the data to 852 * be written to the UART 853 * 854 * @param size The number of bytes in the buffer that should be written 855 * to the UART 856 * 857 * @return Returns the number of bytes that have been written to the UART. 858 * If an error occurs, #UART_STATUS_ERROR is returned. 859 */ 860 extern int_fast32_t UART_writePolling(UART_Handle handle, const void *buffer, size_t size); 861 862 /*! 863 * @brief Function that cancels a UART_write() function call. 864 * 865 * This function cancels an asynchronous UART_write() operation and is only 866 * applicable in #UART_MODE_CALLBACK. 867 * UART_writeCancel() calls the registered TX callback function no matter how many bytes 868 * were sent. It is the application's responsibility to check the count argument in 869 * the callback function and handle cases where only a subset of the bytes were sent. 870 * 871 * @param handle A #UART_Handle returned by UART_open() 872 */ 873 extern void UART_writeCancel(UART_Handle handle); 874 875 /*! 876 * @brief Function that reads data from a UART with interrupt enabled. 877 * 878 * %UART_read() reads data from a UART controller. The destination is specified 879 * by \a buffer and the number of bytes to read is given by \a size. 880 * 881 * In #UART_MODE_BLOCKING, %UART_read() blocks task execution until all 882 * the data in buffer has been read. 883 * 884 * In #UART_MODE_CALLBACK, %UART_read() does not block task execution. 885 * Instead, a callback function specified by UART_Params::readCallback 886 * is called when the transfer is finished. 887 * The callback function can occur in the caller's context or in HWI or SWI 888 * context, depending on the device-specific implementation. 889 * An unfinished asynchronous read operation must always be canceled using 890 * UART_readCancel() before calling UART_close(). 891 * 892 * %UART_read() is mutually exclusive to UART_readPolling(). For an opened 893 * UART peripheral, either %UART_read() or UART_readPolling() can be used, 894 * but not both. 895 * 896 * @sa UART_readPolling() 897 * 898 * @param handle A #UART_Handle returned by UART_open() 899 * 900 * @param buffer A pointer to an empty buffer to which 901 * received data should be written 902 * 903 * @param size The number of bytes to be written into buffer 904 * 905 * @return Returns the number of bytes that have been read from the UART, 906 * #UART_STATUS_ERROR on an error. 907 */ 908 extern int_fast32_t UART_read(UART_Handle handle, void *buffer, size_t size); 909 910 /*! 911 * @brief Function that reads data from a UART without interrupts. This API 912 * must be used mutually exclusive with UART_read(). 913 * 914 * This function initiates an operation to read data from a UART peripheral. 915 * 916 * %UART_readPolling() will not return until size data was read to the UART. 917 * 918 * @sa UART_read() 919 * 920 * @param handle A #UART_Handle returned by UART_open() 921 * 922 * @param buffer A pointer to an empty buffer in which 923 * received data should be written to 924 * 925 * @param size The number of bytes to be written into buffer 926 * 927 * @return Returns the number of bytes that have been read from the UART, 928 * #UART_STATUS_ERROR on an error. 929 */ 930 extern int_fast32_t UART_readPolling(UART_Handle handle, void *buffer, size_t size); 931 932 /*! 933 * @brief Function that cancels a UART_read() function call. 934 * 935 * This function cancels an asynchronous UART_read() operation and is only 936 * applicable in #UART_MODE_CALLBACK. 937 * UART_readCancel() calls the registered RX callback function no matter how many bytes 938 * were received. It is the application's responsibility to check the count argument in 939 * the callback function and handle cases where only a subset of the bytes were received. 940 * 941 * @param handle A #UART_Handle returned by UART_open() 942 */ 943 extern void UART_readCancel(UART_Handle handle); 944 945 #ifdef __cplusplus 946 } 947 #endif 948 949 #endif /* ti_drivers_UART__include */ 950
