1 /* 2 * Copyright (c) 2019-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 UART2.h 34 * @brief <b>PRELIMINARY</b> UART driver interface 35 * 36 * <b>WARNING</b> These APIs are <b>PRELIMINARY</b>, and subject to 37 * change in the next few months. 38 * 39 * To use the UART2 driver, ensure that the correct driver library for your 40 * device is linked in and include this header file as follows: 41 * @code 42 * #include <ti/drivers/UART2.h> 43 * @endcode 44 * 45 * This module serves as the main interface for applications. Its purpose 46 * is to redirect the UART2 APIs to specific driver implementations 47 * which are specified using a pointer to a #UART2_FxnTable. 48 * 49 * @anchor ti_drivers_UART2_Overview 50 * # Overview 51 * A UART is used to translate data between the chip and a serial port. 52 * The UART2 driver simplifies reading and writing to any of the UART 53 * peripherals on the board, with multiple modes of operation and performance. 54 * These include blocking, non-blocking, and polling modes. 55 * 56 * The UART2 driver interface provides device independent APIs, data types, 57 * and macros. The APIs in this driver serve as an interface to a typical RTOS 58 * application. The specific peripheral implementations are responsible for 59 * creating all the RTOS specific primitives to allow for thread-safe 60 * operation. 61 * 62 * <hr> 63 * @anchor ti_drivers_UART2_Usage 64 * # Usage 65 * 66 * This documentation provides a basic @ref ti_drivers_UART2_Synopsis 67 * "usage summary" and a set of @ref ti_drivers_UART2_Examples "examples" 68 * in the form of commented code fragments. Detailed descriptions of the 69 * APIs are provided in subsequent sections. 70 * 71 * @anchor ti_drivers_UART2_Synopsis 72 * ## Synopsis 73 * @anchor ti_drivers_UART2_Synopsis_Code 74 * @code 75 * // Import the UART2 driver definitions 76 * #include <ti/drivers/UART2.h> 77 * 78 * // Initialize UART2 parameters 79 * UART2_Params params; 80 * UART2_Params_init(¶ms); 81 * params.baudRate = 9600; 82 * params.readMode = UART2_Mode_BLOCKING; 83 * params.writeMode = UART2_Mode_BLOCKING; 84 * 85 * // Open the UART 86 * UART2_Handle uart; 87 * uart = UART2_open(CONFIG_UART0, ¶ms); 88 * 89 * // Read from the UART. 90 * size_t bytesRead; 91 * uint8_t buffer[BUFSIZE]; 92 * int32_t status; 93 * status = UART2_read(uart, buffer, BUFSIZE, &bytesRead); 94 * 95 * // Write to the UART 96 * size_t bytesWritten; 97 * status = UART2_write(uart, buffer, BUFSIZE, &bytesWritten); 98 * 99 * // Close the UART 100 * UART2_close(uart); 101 * @endcode 102 * 103 * <hr> 104 * @anchor ti_drivers_UART2_Examples 105 * # Examples 106 * The following code example opens a UART instance, reads 107 * a byte from the UART, and then writes the byte back to the UART. 108 * 109 * @code 110 * char input; 111 * UART2_Handle uart; 112 * UART2_Params uartParams; 113 * 114 * // Open an instance of the UART2 driver 115 * UART2_Params_init(&uartParams); 116 * uartParams.baudRate = 115200; 117 * uart = UART2_open(CONFIG_UART0, &uartParams); 118 * 119 * if (uart == NULL) { 120 * // UART2_open() failed 121 * while (1); 122 * } 123 * 124 * // Loop forever echoing 125 * while (1) { 126 * status = UART2_read(uart, &input, 1, &bytesRead); 127 * status = UART2_write(uart, &input, 1, &bytesWritten); 128 * } 129 * @endcode 130 * 131 * Details for the example code above are described in the following 132 * subsections. 133 * 134 * ### Opening the UART2 Driver # 135 * 136 * Opening a UART requires four steps: 137 * 1. Create and initialize a UART2_Params structure. 138 * 2. Fill in the desired parameters. 139 * 3. Call UART2_open(), passing the index of the UART in the UART2_config 140 * structure, and the address of the UART2_Params structure. The 141 * UART2 instance is specified by the index in the UART2_config structure. 142 * 4. Check that the UART2 handle returned by UART2_open() is non-NULL, 143 * and save it. The handle will be used to read and write to the 144 * UART you just opened. 145 * 146 * Only one UART index can be used at a time; calling UART2_open() a second 147 * time with the same index previosly passed to UART2_open() will result in 148 * an error. You can, though, re-use the index if the instance is closed 149 * via UART2_close(). 150 * In the previous example code, CONFIG_UART0 is passed to UART2_open(). 151 * This macro is defined in the example's ti_drivers_config.h file. 152 * 153 * 154 * ### Modes of Operation # 155 * 156 * The UART driver can operate in blocking, callback, or polling mode, by 157 * setting the writeMode and readMode parameters passed to UART2_open(). 158 * If these parameters are not set, as in the example code, the UART2 159 * driver defaults to blocking mode. Options for the writeMode and 160 * readMode parameters are #UART2_Mode_BLOCKING, #UART2_Mode_CALLBACK, and 161 * #UART2_Mode_POLLING: 162 * 163 * - #UART2_Mode_BLOCKING uses a semaphore to block while data is being sent. 164 * The context of calling UART2_read() and UART2_write() must be a Task when 165 * using #UART2_Mode_BLOCKING. The UART2_write() or UART2_read() call 166 * will block until all data is sent or received, or an error occurs (e.g., 167 * framing or FIFO overrun). In #UART2_Mode_BLOCKING, UART2_readTimeout() 168 * can be used to specify a timeout in system clock ticks, to wait for 169 * data. UART2_readTimeout() will return when all data is received, or 170 * the specified timeout expires, or an error occurs, whichever happens 171 * first. 172 * 173 * - #UART2_Mode_CALLBACK is non-blocking and UART2_read() and UART2_write() 174 * will return while data is being sent in the context of a hardware 175 * interrupt. When the read or write finishes, the UART2 driver will call 176 * the user's callback function. In some cases, the UART data transfer 177 * may have been cancelled, so the number of bytes sent/received are 178 * passed to the callback function. Your implementation of the callback 179 * function can use this information as needed. 180 * Since the user's callback may be called in the context of a hardware 181 * interrupt, the callback function must not make any RTOS blocking calls. 182 * The buffer passed to UART2_write() in #UART2_Mode_CALLBACK is not copied. 183 * The buffer must remain coherent until all the characters have been sent 184 * (ie until the tx callback has been called with a byte count equal to 185 * that passed to UART2_write()). 186 * 187 * ### Reading and Writing data # 188 * 189 * The example code reads one byte frome the UART instance, and then writes 190 * one byte back to the same instance: 191 * 192 * @code 193 * status = UART2_read(uart, &input, 1, &bytesRead); 194 * status = UART2_write(uart, &input, 1, &bytesWritten); 195 * @endcode 196 * 197 * The UART2 driver allows full duplex data transfers. Therefore, it is 198 * possible to call UART2_read() and UART2_write() at the same time (for 199 * either blocking or callback modes). It is not possible, however, 200 * to issue multiple concurrent operations in the same direction. 201 * For example, if one thread calls UART2_read(uart0, buffer0...), 202 * any other thread attempting UART2_read(uart0, buffer1...) will result in 203 * an error of UART2_STATUS_EINUSE, until all the data from the first 204 * UART2_read() has been transferred to buffer0. This applies to blocking, 205 * callback, and polling modes. So applications must either synchronize 206 * UART2_read() (or UART2_write()) calls that use the same UART handle, or 207 * check for the UART2_STATUS_EINUSE return code indicating that a transfer is 208 * still ongoing. 209 * 210 * <hr> 211 * @anchor ti_drivers_UART2_Configuration 212 * # Configuration 213 * 214 * Refer to the @ref driver_configuration "Driver's Configuration" section 215 * for driver configuration information. 216 * <hr> 217 * 218 * ============================================================================ 219 */ 220 221 #ifndef ti_drivers_UART2__include 222 #define ti_drivers_UART2__include 223 224 #include <stddef.h> 225 #include <stdint.h> 226 227 #ifdef __cplusplus 228 extern "C" { 229 #endif 230 231 /** @addtogroup UART2_STATUS 232 * @{ 233 */ 234 /*! 235 * @brief Successful status code returned by UART2 APIs. 236 */ 237 #define UART2_STATUS_SUCCESS (0) 238 239 /*! 240 * @brief A read timeout occurred (not an error). 241 */ 242 #define UART2_STATUS_SREADTIMEOUT (1) 243 244 /*! 245 * @brief A framing error occurred. 246 */ 247 #define UART2_STATUS_EFRAMING (-1) 248 249 /*! 250 * @brief A parity error occurred. 251 */ 252 #define UART2_STATUS_EPARITY (-2) 253 254 /*! 255 * @brief A break error occurred. 256 */ 257 #define UART2_STATUS_EBREAK (-4) 258 259 /*! 260 * @brief A FIFO overrun occurred. 261 */ 262 #define UART2_STATUS_EOVERRUN (-8) 263 264 /*! 265 * @brief The UART is currently in use. 266 */ 267 #define UART2_STATUS_EINUSE (-9) 268 269 /*! 270 * @brief An invalid argument or UART2_Params field was passed to UART2 API. 271 */ 272 #define UART2_STATUS_EINVALID (-10) 273 274 /*! 275 * @brief General failure status returned by UART2 API. 276 */ 277 #define UART2_STATUS_EFAIL (-11) 278 279 /*! 280 * @brief A memory allocation failure occurred. 281 */ 282 #define UART2_STATUS_EMEMORY (-12) 283 284 /*! 285 * @brief A timeout occurred for a blocking UART2_read or UART2_write call. 286 */ 287 #define UART2_STATUS_ETIMEOUT (-13) 288 289 /*! 290 * @brief A UART2_write() or UART2_read() operation was cancelled. 291 */ 292 #define UART2_STATUS_ECANCELLED (-14) 293 294 /*! 295 * @brief A UART2_write() or UART2_read() called on a device not opened. 296 */ 297 #define UART2_STATUS_ENOTOPEN (-15) 298 299 /** @}*/ 300 301 /*! 302 * @brief Wait forever define 303 */ 304 #define UART2_WAIT_FOREVER (~(0U)) 305 306 /*! 307 * @brief A handle that is returned from a UART2_open() call. 308 */ 309 typedef struct UART2_Config_ *UART2_Handle; 310 311 /*! 312 * @brief The definition of a callback function used by the UART2 driver 313 * when used in #UART2_Mode_CALLBACK 314 * The callback can occur in task or interrupt context. 315 * 316 * @param[in] UART2_Handle UART2_Handle 317 * 318 * @param[in] buf Pointer to read/write buffer 319 * 320 * @param[in] count Number of elements read/written 321 * 322 * @param[in] userArg A user supplied argument specified 323 * in UART2_Params. 324 * 325 * @param[in] status A UART2_STATUS code indicating 326 * success or failure of the transfer. 327 */ 328 typedef void (*UART2_Callback) (UART2_Handle handle, void *buf, size_t count, 329 void *userArg, int_fast16_t status); 330 331 /*! 332 * @brief UART2 mode settings 333 * 334 * This enum defines the read and write modes for the configured UART. 335 */ 336 typedef enum { 337 /*! 338 * Uses a semaphore to block while data is being sent. Context of the 339 * call must be a Task. 340 */ 341 UART2_Mode_BLOCKING, 342 343 /*! 344 * Non-blocking, UART2_write() or UART2_read() will return immediately. 345 * When the transfer has finished, the callback function is called 346 * from either the caller's context or from an interrupt context. 347 */ 348 UART2_Mode_CALLBACK, 349 350 /*! 351 * UART is polled until all available data is received, or all data 352 * that can be sent without blocking is sent. Context of the call 353 * can be main(), Task, software interrupt, or hardware interrupt. 354 */ 355 UART2_Mode_POLLING 356 } UART2_Mode; 357 358 /*! 359 * @brief UART2 return mode settings 360 * 361 * This enumeration defines the return modes for UART2_read(). 362 * 363 * #UART2_ReadReturnMode_FULL unblocks or performs a callback when the read 364 * buffer has been filled with the number of bytes passed to #UART2_read(). 365 * #UART2_ReadReturnMode_PARTIAL unblocks or performs a callback whenever a 366 * read timeout error occurs on the UART peripheral. This timeout 367 * error is not the same as the blocking read timeout in the UART2_Params; 368 * the read timeout occurs if the read FIFO is non-empty and no new 369 * data has been received for a device/baudrate dependent number of 370 * clock cycles. This mode can be used when the exact number of bytes to 371 * be read is not known. 372 */ 373 typedef enum { 374 /*! Unblock/callback when buffer is full. */ 375 UART2_ReadReturnMode_FULL, 376 377 /*! Unblock/callback when no new data comes in. */ 378 UART2_ReadReturnMode_PARTIAL 379 } UART2_ReadReturnMode; 380 381 /*! 382 * @brief UART2 data length settings 383 * 384 * This enumeration defines the UART data lengths. 385 */ 386 typedef enum { 387 UART2_DataLen_5 = 0, /*!< Data length is 5 bits */ 388 UART2_DataLen_6 = 1, /*!< Data length is 6 bits */ 389 UART2_DataLen_7 = 2, /*!< Data length is 7 bits */ 390 UART2_DataLen_8 = 3 /*!< Data length is 8 bits */ 391 } UART2_DataLen; 392 393 /*! 394 * @brief UART2 stop bit settings 395 * 396 * This enumeration defines the UART2 stop bits. 397 */ 398 typedef enum { 399 UART2_StopBits_1 = 0, /*!< One stop bit */ 400 UART2_StopBits_2 = 1 /*!< Two stop bits */ 401 } UART2_StopBits; 402 403 /*! 404 * @brief UART2 parity type settings 405 * 406 * This enumeration defines the UART2 parity types. 407 */ 408 typedef enum { 409 UART2_Parity_NONE = 0, /*!< No parity */ 410 UART2_Parity_EVEN = 1, /*!< Parity bit is even */ 411 UART2_Parity_ODD = 2, /*!< Parity bit is odd */ 412 UART2_Parity_ZERO = 3, /*!< Parity bit is always zero */ 413 UART2_Parity_ONE = 4 /*!< Parity bit is always one */ 414 } UART2_Parity; 415 416 /*! 417 * @brief UART2 Parameters 418 * 419 * UART2 parameters are used with the UART2_open() call. Default values for 420 * these parameters are set using UART2_Params_init(). 421 * 422 * @sa UART2_Params_init() 423 */ 424 typedef struct { 425 UART2_Mode readMode; /*!< Mode for all read calls */ 426 UART2_Mode writeMode; /*!< Mode for all write calls */ 427 UART2_Callback readCallback; /*!< Pointer to read callback function for callback mode. */ 428 UART2_Callback writeCallback; /*!< Pointer to write callback function for callback mode. */ 429 UART2_ReadReturnMode readReturnMode; /*!< Receive return mode */ 430 uint32_t baudRate; /*!< Baud rate for UART */ 431 UART2_DataLen dataLength; /*!< Data length for UART */ 432 UART2_StopBits stopBits; /*!< Stop bits for UART */ 433 UART2_Parity parityType; /*!< Parity bit type for UART */ 434 void *userArg; /*!< User supplied argument for callback functions */ 435 } UART2_Params; 436 437 /*! 438 * @brief A function pointer to a driver specific implementation of 439 * UART2_CloseFxn(). 440 */ 441 typedef void (*UART2_CloseFxn) (UART2_Handle handle); 442 443 /*! 444 * @brief A function to flush the RX data currently in the FIFO. 445 */ 446 typedef void (*UART2_FlushRxFxn) (UART2_Handle handle); 447 448 /*! 449 * @brief A function pointer to a driver specific implementation of 450 * UART2_OpenFxn(). 451 */ 452 typedef UART2_Handle (*UART2_OpenFxn) (uint_least8_t index, UART2_Params *params); 453 454 /*! 455 * @brief A function pointer to a driver specific implementation of 456 * UART2_ReadFxn(). 457 */ 458 typedef int_fast16_t (*UART2_ReadFxn) (UART2_Handle handle, 459 void *buffer, size_t size, size_t *bytesRead, uint32_t timeout); 460 461 /*! 462 * @brief A function pointer to a driver specific implementation of 463 * UART2_ReadCancelFxn(). 464 */ 465 typedef void (*UART2_ReadCancelFxn) (UART2_Handle handle); 466 467 /*! 468 * @brief A function pointer to a driver specific implementation of 469 * UART2_WriteFxn(). 470 */ 471 typedef int_fast16_t (*UART2_WriteFxn) (UART2_Handle handle, 472 const void *buffer, size_t size, size_t *bytesWritten, 473 uint32_t timeout); 474 475 /*! 476 * @brief A function pointer to a driver specific implementation of 477 * UART2_WriteCancelFxn(). 478 */ 479 typedef void (*UART2_WriteCancelFxn) (UART2_Handle handle); 480 481 /*! 482 * @brief The definition of a UART2 function table that contains the 483 * required set of functions to control a specific UART2 driver 484 * implementation. 485 */ 486 typedef struct { 487 /*! Function to close the specified peripheral */ 488 UART2_CloseFxn closeFxn; 489 490 /*! Function to open the specified peripheral */ 491 UART2_OpenFxn openFxn; 492 493 /*! Function to read from the specified peripheral */ 494 UART2_ReadFxn readFxn; 495 496 /*! Function to cancel a read from the specified peripheral */ 497 UART2_ReadCancelFxn readCancelFxn; 498 499 /*! Function to write from the specified peripheral */ 500 UART2_WriteFxn writeFxn; 501 502 /*! Function to cancel a write from the specified peripheral */ 503 UART2_WriteCancelFxn writeCancelFxn; 504 505 /*! Function to flush the RX FIFO */ 506 UART2_FlushRxFxn flushRxFxn; 507 } UART2_FxnTable; 508 509 /*! 510 * @brief UART2 Global configuration 511 * 512 * The UART2_Config structure contains a set of pointers used to characterize 513 * the UART2 driver implementation. 514 * 515 */ 516 typedef struct UART2_Config_ { 517 /*! Pointer to a table of driver-specific implementations of UART APIs */ 518 UART2_FxnTable const *fxnTablePtr; 519 520 /*! Pointer to a driver specific data object */ 521 void *object; 522 523 /*! Pointer to a driver specific hardware attributes structure */ 524 void const *hwAttrs; 525 } UART2_Config; 526 527 extern const UART2_Config UART2_config[]; 528 extern const uint_least8_t UART2_count; 529 530 /*! 531 * @brief Function to close a UART peripheral specified by the UART2 handle 532 * 533 * @pre UART2_open() has been called. 534 * @pre There are no ongoing read or write calls. Any ongoing read 535 * or write calls can be cancelled with UART2_readCancel() or 536 * UART2_writeCancel(). 537 * 538 * @param[in] handle A #UART2_Handle returned from UART2_open() 539 * 540 * @sa UART2_open() 541 */ 542 extern void UART2_close(UART2_Handle handle); 543 544 /*! 545 * @brief Function to flush data in the UART RX FIFO. 546 * 547 * @pre UART2_open() has been called. 548 * 549 * This function can be called to remove all data from the RX FIFO, for 550 * example, after a UART read error has occurred. 551 * 552 * @param[in] handle A #UART2_Handle returned from UART2_open() 553 */ 554 extern void UART2_flushRx(UART2_Handle handle); 555 556 /*! 557 * @brief Function to initialize a given UART peripheral 558 * 559 * Function to initialize a given UART peripheral specified by the 560 * particular index value. 561 * 562 * @param[in] index Logical peripheral number for the UART indexed into 563 * the UART2_config table 564 * 565 * @param[in] params Pointer to a parameter block. If NULL, default 566 * parameter values will be used. All the fields in 567 * this structure are read-only. 568 * 569 * @sa UART2_close() 570 */ 571 extern UART2_Handle UART2_open(uint_least8_t index, UART2_Params *params); 572 573 /*! 574 * @brief Function to initialize the UART2_Params struct to its defaults 575 * 576 * @param[in] params A pointer to UART2_Params structure for 577 * initialization 578 * 579 * Defaults values are: 580 * readMode = UART2_Mode_BLOCKING; 581 * writeMode = UART2_Mode_BLOCKING; 582 * readCallback = NULL; 583 * writeCallback = NULL; 584 * readReturnMode = UART2_ReadReturnMode_FULL; 585 * baudRate = 115200; 586 * dataLength = UART2_DataLen_8; 587 * stopBits = UART2_StopBits_1; 588 * parityType = UART2_Parity_NONE; 589 * userArg = NULL; 590 */ 591 extern void UART2_Params_init(UART2_Params *params); 592 593 /*! 594 * @brief Function that reads data from a UART. 595 * 596 * %UART2_read() reads data from a UART controller. The destination is 597 * specified by \a buffer and the number of bytes to read is given by 598 * \a size. 599 * 600 * In #UART2_Mode_BLOCKING, %UART2_read() blocks task execution until all 601 * the data in buffer has been read, if the read return mode is 602 * #UART2_ReadReturnMode_FULL. 603 * If the read return mode is #UART2_ReadReturnMode_PARTIAL, %UART2_read() 604 * returns before all the data has been read, if some data has been received, 605 * but reception has been inactive sufficiently long for a hardware read 606 * timeout to occur (e.g., for a 32-bit period). 607 * If a receive error occurs (e.g., framing, fifo overrun), %UART2_read() 608 * will return with the number of bytes read up to the occurance of the 609 * error. 610 * 611 * In #UART2_Mode_CALLBACK, %UART2_read() does not block task execution. 612 * Instead, a callback function specified by UART2_Params::readCallback 613 * is called when the transfer is finished (#UART2_ReadReturnMode_FULL), or 614 * reception has become inactive (#UART2_ReadReturnMode_PARTIAL). 615 * The callback function can occur in the caller's context or in SWI 616 * context, depending on the device-specific implementation. 617 * An unfinished asynchronous read operation must always be cancelled using 618 * UART2_readCancel() before calling UART2_close(). 619 * 620 * In #UART2_Mode_POLLING, %UART2_read() will return the minimum of size 621 * and the number of data in the RX FIFO. In this mode, UART2_read() is 622 * non-blocking, but the application should check the number of bytes 623 * read in the bytesRead parameter. A status of success will be returned 624 * even if not all bytes requested were read, unless an error occured. 625 * 626 * @note It is ok to call %UART2_read() from its own callback function when in 627 * #UART2_Mode_CALLBACK. 628 * 629 * @param[in] handle A #UART2_Handle returned by UART2_open() 630 * 631 * @param[in] buffer A pointer to an empty buffer to which 632 * received data should be read 633 * 634 * @param[in] size The number of bytes to be read into buffer 635 * 636 * @param[out] bytesRead If non-NULL, the location to store the number of 637 * bytes actually read into the buffer. If NULL, this 638 * parameter will be ignored. In callback mode, NULL 639 * could be passed in for this parameter, since the 640 * callback function will be passed the number of bytes 641 * read. In blocking mode, NULL can be passed, 642 * however, status should be checked in case the number 643 * of bytes requested was not received due to errors. 644 * In polling mode, it is not recommended to pass NULL 645 * for this parameter, as it would be impossible to 646 * determine the number of bytes actually read. 647 * 648 * @return Returns a status indicating success or failure of the read. 649 * 650 * @retval #UART2_STATUS_SUCCESS The call was successful. 651 * @retval #UART2_STATUS_EINUSE Another read from the UART is currently 652 * ongoing. 653 * @retval #UART2_STATUS_EOVERRUN A fifo overrun occurred. 654 * @retval #UART2_STATUS_EFRAMING A framinig error occurred. 655 * @retval #UART2_STATUS_EBREAK A break error occurred. 656 * @retval #UART2_STATUS_EPARITY A parity error occurred. 657 */ 658 extern int_fast16_t UART2_read(UART2_Handle handle, void *buffer, size_t size, 659 size_t *bytesRead); 660 661 /*! 662 * @brief Function that reads data from a UART, with a specified timeout 663 * for blocking mode. 664 * 665 * %UART2_readTimeout() reads data from a UART controller. The destination is 666 * specified by \a buffer and the number of bytes to read is given by 667 * \a size. 668 * 669 * In #UART2_Mode_BLOCKING with #UART2_ReadReturnMode_FULL, 670 * %UART2_readTimeout() blocks task execution until all the data in buffer 671 * has been read, or the specified timeout has elapsed. 672 * In #UART2_Mode_BLOCKING with #UART2_ReadReturnMode_PARTIAL, 673 * %UART2_readTimeout() returns before all the data has been read, if some 674 * data has been received, but reception has been inactive sufficiently 675 * long for a hardware read timeout to occur (e.g., for a 32-bit period). 676 * %UART2_readTimeout() will also return if the specified timeout parameter 677 * has elapsed. Note that the timeout parameter is different from the 678 * hardware read timeout. 679 * 680 * In #UART2_Mode_CALLBACK, %UART2_readTimeout() does not block task 681 * execution. Instead, a callback function specified by 682 * UART2_Params::readCallback is called when the transfer is finished 683 * (#UART2_ReadReturnMode_FULL), or reception has become inactive 684 * (#UART2_ReadReturnMode_PARTIAL). 685 * The callback function can occur in the caller's context or in HWI 686 * context, depending on the device-specific implementation. 687 * An unfinished asynchronous read operation must always be cancelled using 688 * UART2_readCancel() before calling UART2_close(). In #UART2_Mode_CALLBACK, 689 * the timeout parameter passed to %UART2_readTimeout(), is ignored. 690 * 691 * In #UART2_Mode_POLLING, %UART2_readTimeout() will return the minimum of 692 * size and the number of data in the RX FIFO. In this mode, 693 * UART2_readTimeout() is non-blocking, but the application should check the 694 * number of bytes read in the bytesRead parameter. A status of success 695 * will be returned even if not all bytes requested were read, unless an 696 * error occured. In #UART2_Mode_POLLING, the timeout parameter passed to 697 * %UART2_readTimeout(), is ignored. 698 * 699 * @note It is ok to call %UART2_readTimeout() from its own callback function 700 * when in #UART2_Mode_CALLBACK. 701 * 702 * @param[in] handle A #UART2_Handle returned by UART2_open() 703 * 704 * @param[in] buffer A pointer to an empty buffer to which 705 * received data should be read 706 * 707 * @param[in] size The number of bytes to be read into buffer 708 * 709 * @param[out] bytesRead If non-NULL, the location to store the number of 710 * bytes actually read into the buffer. If NULL, this 711 * parameter will be ignored. In callback mode, NULL 712 * could be passed in for this parameter, since the 713 * callback function will be passed the number of bytes 714 * read. Similarly, in blocking mode with infinite 715 * timeout, NULL can be passed. However, status should 716 * be checked in case the number of bytes requested was 717 * not received due to errors. 718 * In polling mode, it is not recommended to pass NULL 719 * for this parameter, as it would be impossible to 720 * determine the number of bytes actually read. 721 * 722 * @param[in] timeout The number of system clock ticks to wait until 723 * all data is received. If not all requested data 724 * was received within the timeout period, an error of 725 * UART2_STATUS_ETIMEOUT will be returned. This 726 * parameter is only applicable to #UART2_Mode_BLOCKING. 727 * 728 * @return Returns a status indicating success or failure of the read. 729 * 730 * @retval #UART2_STATUS_SUCCESS The call was successful. 731 * @retval #UART2_STATUS_EINUSE Another read from the UART is currently 732 * ongoing. 733 * @retval #UART2_STATUS_ETIMEOUT The read operation timed out. 734 * @retval #UART2_STATUS_EOVERRUN A fifo overrun occurred. 735 * @retval #UART2_STATUS_EFRAMING A framinig error occurred. 736 * @retval #UART2_STATUS_EBREAK A break error occurred. 737 * @retval #UART2_STATUS_EPARITY A parity error occurred. 738 */ 739 extern int_fast16_t UART2_readTimeout(UART2_Handle handle, void *buffer, 740 size_t size, size_t *bytesRead, uint32_t timeout); 741 742 /*! 743 * @brief Function that cancels a UART2_read() function call. 744 * 745 * This function cancels an asynchronous UART2_read() operation in 746 * in #UART2_Mode_CALLBACK, or unblocks a UART2_read() call in 747 * #UART2_Mode_BLOCKING. 748 * In #UART2_Mode_CALLBACK, UART2_readCancel() calls the registered read 749 * callback function with the number of bytes received so far. 750 * It is the application's responsibility to check the count argument 751 * in the callback function and handle the case where only a subset of the 752 * bytes were received. The callback function will be passed a status of 753 * #UART2_STATUS_ECANCELLED. 754 * 755 * In #UART2_Mode_BLOCKING, #UART2_read() will return 756 * #UART2_STATUS_ECANCELLED, and the bytesRead parameter will be set to 757 * the number of bytes received so far. 758 * 759 * This API has no affect in #UART2_Mode_POLLING. 760 * 761 * @param[in] handle A #UART2_Handle returned by UART2_open() 762 */ 763 extern void UART2_readCancel(UART2_Handle handle); 764 765 /*! 766 * @brief Function that writes data to a UART. 767 * 768 * %UART2_write() writes data from a memory buffer to the UART interface. 769 * The source is specified by \a buffer and the number of bytes to write 770 * is given by \a size. 771 * 772 * In #UART2_Mode_BLOCKING, UART2_write() blocks task execution until all 773 * the data in buffer has been written. 774 * 775 * In #UART2_Mode_CALLBACK, %UART2_write() does not block task execution. 776 * Instead, a callback function specified by UART2_Params::writeCallback is 777 * called when the transfer is finished. The buffer passed to UART2_write() 778 * in #UART2_Mode_CALLBACK is not copied. The buffer must remain coherent 779 * until all the characters have been sent (ie until the write callback has 780 * been called with a byte count equal to that passed to UART2_write()). 781 * The callback function can occur in the caller's task context or in a HWI or 782 * SWI context, depending on the device implementation. 783 * An unfinished asynchronous write operation must always be cancelled using 784 * UART2_writeCancel() before calling UART2_close(). 785 * 786 * In #UART2_Mode_POLLING, UART2_write() will send out as many of the 787 * bytes in the buffer as possible, until the TX FIFO is full. In polling 788 * mode, UART2_write() is non-blocking and can be called from any context. 789 * The bytesWritten parameter should not be NULL so the application can 790 * determine the number of bytes actually written. 791 * 792 * @param[in] handle A #UART2_Handle returned by UART2_open() 793 * 794 * @param[in] buffer A read-only pointer to buffer containing data to 795 * be written to the UART 796 * 797 * @param[in] size The number of bytes in the buffer that should be 798 * written to the UART 799 * 800 * @param[out] bytesWritten If non-NULL, the location to store the number of 801 * bytes actually written to the UART in 802 * UART2_Mode_BLOCKING and UART2_Mode_POLLING. In 803 * UART2_Mode_CALLBACK, bytesWritten will be set to 0. 804 * If bytesWritten is NULL, this parameter will be 805 * ignored. 806 * In polling mode, it is not recommended to pass NULL 807 * for bytesWritten, as the application would have 808 * no way to determine the number of bytes actually 809 * written. In polling mode, a status of success 810 * will be returned even if not all the requested 811 * bytes could be written. 812 * 813 * @return Returns a status indicating success or failure of the write. 814 * 815 * @retval #UART2_STATUS_SUCCESS The call was successful. 816 * @retval #UART2_STATUS_EINUSE Another write to the UART is currently 817 * ongoing. 818 */ 819 extern int_fast16_t UART2_write(UART2_Handle handle, const void *buffer, 820 size_t size, size_t *bytesWritten); 821 822 /*! 823 * @brief Function that writes data to a UART, with a specified timeout. 824 * 825 * %UART2_writeTimeout() writes data from a memory buffer to the UART 826 * interface. 827 * The source is specified by \a buffer and the number of bytes to write 828 * is given by \a size. 829 * A timeout in system clock ticks specifies the maximum time to wait 830 * until all data is written (#UART2_Mode_BLOCKING only). 831 * 832 * In #UART2_Mode_BLOCKING, UART2_writeTimeout() blocks task execution until 833 * all the data in buffer has been written, or the timeout expires. 834 * 835 * In #UART2_Mode_CALLBACK, %UART2_writeTimeout() does not block task 836 * execution. Instead, a callback function specified by 837 * UART2_Params::writeCallback is called when the transfer is finished. 838 * The buffer passed to UART2_writeTimeout() in #UART2_Mode_CALLBACK is not 839 * copied. The buffer must remain coherent until all the characters have 840 * been sent (ie until the write callback has been called with a byte count 841 * equal to that passed to UART2_writeTimeout()). 842 * The callback function can occur in the caller's task context or in 843 * interrupt context, depending on the device implementation. 844 * An unfinished asynchronous write operation must always be cancelled using 845 * UART2_writeCancel() before calling UART2_close(). 846 * 847 * In #UART2_Mode_POLLING, UART2_writeTimeout() will send out as many of the 848 * bytes in the buffer as possible, until the TX FIFO is full. In polling 849 * mode, UART2_writeTimeout() is non-blocking and can be called from any 850 * context. The bytesWritten parameter should not be NULL so the application 851 * can determine the number of bytes actually written. 852 * 853 * @param[in] handle A #UART2_Handle returned by UART2_open() 854 * 855 * @param[in] buffer A read-only pointer to buffer containing data to 856 * be written to the UART 857 * 858 * @param[in] size The number of bytes in the buffer that should be 859 * written to the UART 860 * 861 * @param[out] bytesWritten If non-NULL, the location to store the number of 862 * bytes actually written to the UART in 863 * UART2_Mode_BLOCKING and UART2_Mode_POLLING. In 864 * UART2_Mode_CALLBACK, bytesWritten will be set to 0. 865 * If bytesWritten is NULL, this parameter will be 866 * ignored. 867 * In polling mode, it is not recommended to pass NULL 868 * for bytesWritten, as the application would have 869 * no way to determine the number of bytes actually 870 * written. In polling mode, a status of success 871 * will be returned even if not all the requested 872 * bytes could be written. 873 * 874 * @param[in] timeout The number of system clock ticks to wait for the 875 * write to complete (#UART2_Mode_BLOCKING only). If 876 * the timeout expires before all bytes are written, a 877 * status of UART2_STATUS_ETIMEOUT will be returned. 878 * 879 * @return Returns a status indicating success or failure of the write. 880 * 881 * @retval #UART2_STATUS_SUCCESS The call was successful. 882 * @retval #UART2_STATUS_EINUSE Another write to the UART is currently 883 * ongoing. 884 * @retval #UART2_STATUS_ETIMEOUT The write operation timed out. 885 */ 886 extern int_fast16_t UART2_writeTimeout(UART2_Handle handle, const void *buffer, 887 size_t size, size_t *bytesWritten, uint32_t timeout); 888 889 /*! 890 * @brief Function that cancels a UART2_write() function call. 891 * 892 * This function cancels an asynchronous UART2_write() operation when 893 * write mode is #UART2_Mode_CALLBACK, or an ongoing UART2_write() in 894 * #UART2_Mode_POLLING. 895 * In callback mode, UART2_writeCancel() calls the registered 896 * write callback function no matter how many bytes were sent. It 897 * is the application's responsibility to check the count argument in the 898 * callback function and handle cases where only a subset of the bytes were 899 * sent. The callback function will be passed a status of 900 * #UART2_STATUS_ECANCELLED. 901 * In blocking mode, UART2_write() will return #UART2_STATUS_ECANCELLED. 902 * 903 * @note The above applies to %UART2_writeTimeout() as well. 904 * 905 * This API has no affect in polling mode. 906 * 907 * @param[in] handle A #UART2_Handle returned by UART2_open() 908 */ 909 extern void UART2_writeCancel(UART2_Handle handle); 910 911 #ifdef __cplusplus 912 } 913 #endif 914 915 #endif /* ti_drivers_UART2__include */ 916
