1 /* 2 * Copyright (c) 2018-2019 Nordic Semiconductor ASA 3 * Copyright (c) 2015 Wind River Systems, Inc. 4 * 5 * SPDX-License-Identifier: Apache-2.0 6 */ 7 8 /** 9 * @file 10 * @brief Public APIs for UART drivers 11 */ 12 13 #ifndef ZEPHYR_INCLUDE_DRIVERS_UART_H_ 14 #define ZEPHYR_INCLUDE_DRIVERS_UART_H_ 15 16 /** 17 * @brief UART Interface 18 * @defgroup uart_interface UART Interface 19 * @since 1.0 20 * @version 1.0.0 21 * @ingroup io_interfaces 22 * @{ 23 */ 24 25 #include <stddef.h> 26 27 #include <zephyr/device.h> 28 29 #ifdef __cplusplus 30 extern "C" { 31 #endif 32 33 /** @brief Line control signals. */ 34 enum uart_line_ctrl { 35 UART_LINE_CTRL_BAUD_RATE = BIT(0), /**< Baud rate */ 36 UART_LINE_CTRL_RTS = BIT(1), /**< Request To Send (RTS) */ 37 UART_LINE_CTRL_DTR = BIT(2), /**< Data Terminal Ready (DTR) */ 38 UART_LINE_CTRL_DCD = BIT(3), /**< Data Carrier Detect (DCD) */ 39 UART_LINE_CTRL_DSR = BIT(4), /**< Data Set Ready (DSR) */ 40 }; 41 42 /** 43 * @brief Reception stop reasons. 44 * 45 * Values that correspond to events or errors responsible for stopping 46 * receiving. 47 */ 48 enum uart_rx_stop_reason { 49 /** @brief Overrun error */ 50 UART_ERROR_OVERRUN = (1 << 0), 51 /** @brief Parity error */ 52 UART_ERROR_PARITY = (1 << 1), 53 /** @brief Framing error */ 54 UART_ERROR_FRAMING = (1 << 2), 55 /** 56 * @brief Break interrupt 57 * 58 * A break interrupt was received. This happens when the serial input 59 * is held at a logic '0' state for longer than the sum of 60 * start time + data bits + parity + stop bits. 61 */ 62 UART_BREAK = (1 << 3), 63 /** 64 * @brief Collision error 65 * 66 * This error is raised when transmitted data does not match 67 * received data. Typically this is useful in scenarios where 68 * the TX and RX lines maybe connected together such as 69 * RS-485 half-duplex. This error is only valid on UARTs that 70 * support collision checking. 71 */ 72 UART_ERROR_COLLISION = (1 << 4), 73 /** @brief Noise error */ 74 UART_ERROR_NOISE = (1 << 5), 75 }; 76 77 /** @brief Parity modes */ 78 enum uart_config_parity { 79 UART_CFG_PARITY_NONE, /**< No parity */ 80 UART_CFG_PARITY_ODD, /**< Odd parity */ 81 UART_CFG_PARITY_EVEN, /**< Even parity */ 82 UART_CFG_PARITY_MARK, /**< Mark parity */ 83 UART_CFG_PARITY_SPACE, /**< Space parity */ 84 }; 85 86 /** @brief Number of stop bits. */ 87 enum uart_config_stop_bits { 88 UART_CFG_STOP_BITS_0_5, /**< 0.5 stop bit */ 89 UART_CFG_STOP_BITS_1, /**< 1 stop bit */ 90 UART_CFG_STOP_BITS_1_5, /**< 1.5 stop bits */ 91 UART_CFG_STOP_BITS_2, /**< 2 stop bits */ 92 }; 93 94 /** @brief Number of data bits. */ 95 enum uart_config_data_bits { 96 UART_CFG_DATA_BITS_5, /**< 5 data bits */ 97 UART_CFG_DATA_BITS_6, /**< 6 data bits */ 98 UART_CFG_DATA_BITS_7, /**< 7 data bits */ 99 UART_CFG_DATA_BITS_8, /**< 8 data bits */ 100 UART_CFG_DATA_BITS_9, /**< 9 data bits */ 101 }; 102 103 /** 104 * @brief Hardware flow control options. 105 * 106 * With flow control set to none, any operations related to flow control 107 * signals can be managed by user with uart_line_ctrl functions. 108 * In other cases, flow control is managed by hardware/driver. 109 */ 110 enum uart_config_flow_control { 111 UART_CFG_FLOW_CTRL_NONE, /**< No flow control */ 112 UART_CFG_FLOW_CTRL_RTS_CTS, /**< RTS/CTS flow control */ 113 UART_CFG_FLOW_CTRL_DTR_DSR, /**< DTR/DSR flow control */ 114 UART_CFG_FLOW_CTRL_RS485, /**< RS485 flow control */ 115 }; 116 117 /** 118 * @brief UART controller configuration structure 119 */ 120 struct uart_config { 121 uint32_t baudrate; /**< Baudrate setting in bps */ 122 uint8_t parity; /**< Parity bit, use @ref uart_config_parity */ 123 uint8_t stop_bits; /**< Stop bits, use @ref uart_config_stop_bits */ 124 uint8_t data_bits; /**< Data bits, use @ref uart_config_data_bits */ 125 uint8_t flow_ctrl; /**< Flow control setting, use @ref uart_config_flow_control */ 126 }; 127 128 /** 129 * @defgroup uart_interrupt Interrupt-driven UART API 130 * @{ 131 */ 132 133 /** 134 * @brief Define the application callback function signature for 135 * uart_irq_callback_user_data_set() function. 136 * 137 * @param dev UART device instance. 138 * @param user_data Arbitrary user data. 139 */ 140 typedef void (*uart_irq_callback_user_data_t)(const struct device *dev, 141 void *user_data); 142 143 /** 144 * @} 145 * 146 * @defgroup uart_async Async UART API 147 * @since 1.14 148 * @version 0.8.0 149 * @{ 150 */ 151 152 /** 153 * @brief Types of events passed to callback in UART_ASYNC_API 154 * 155 * Receiving: 156 * 1. To start receiving, uart_rx_enable has to be called with first buffer 157 * 2. When receiving starts to current buffer, 158 * #UART_RX_BUF_REQUEST will be generated, in response to that user can 159 * either: 160 * 161 * - Provide second buffer using uart_rx_buf_rsp, when first buffer is 162 * filled, receiving will automatically start to second buffer. 163 * - Ignore the event, this way when current buffer is filled 164 * #UART_RX_RDY event will be generated and receiving will be stopped. 165 * 166 * 3. If some data was received and timeout occurred #UART_RX_RDY event will be 167 * generated. It can happen multiples times for the same buffer. RX timeout 168 * is counted from last byte received i.e. if no data was received, there 169 * won't be any timeout event. 170 * 4. #UART_RX_BUF_RELEASED event will be generated when the current buffer is 171 * no longer used by the driver. It will immediately follow #UART_RX_RDY event. 172 * Depending on the implementation buffer may be released when it is completely 173 * or partially filled. 174 * 5. If there was second buffer provided, it will become current buffer and 175 * we start again at point 2. 176 * If no second buffer was specified receiving is stopped and 177 * #UART_RX_DISABLED event is generated. After that whole process can be 178 * repeated. 179 * 180 * Any time during reception #UART_RX_STOPPED event can occur. if there is any 181 * data received, #UART_RX_RDY event will be generated. It will be followed by 182 * #UART_RX_BUF_RELEASED event for every buffer currently passed to driver and 183 * finally by #UART_RX_DISABLED event. 184 * 185 * Receiving can be disabled using uart_rx_disable, after calling that 186 * function, if there is any data received, #UART_RX_RDY event will be 187 * generated. #UART_RX_BUF_RELEASED event will be generated for every buffer 188 * currently passed to driver and finally #UART_RX_DISABLED event will occur. 189 * 190 * Transmitting: 191 * 1. Transmitting starts by uart_tx function. 192 * 2. If whole buffer was transmitted #UART_TX_DONE is generated. If timeout 193 * occurred #UART_TX_ABORTED will be generated. 194 * 195 * Transmitting can be aborted using @ref uart_tx_abort, after calling that 196 * function #UART_TX_ABORTED event will be generated. 197 * 198 */ 199 enum uart_event_type { 200 /** @brief Whole TX buffer was transmitted. */ 201 UART_TX_DONE, 202 /** 203 * @brief Transmitting aborted due to timeout or uart_tx_abort call 204 * 205 * When flow control is enabled, there is a possibility that TX transfer 206 * won't finish in the allotted time. Some data may have been 207 * transferred, information about it can be found in event data. 208 */ 209 UART_TX_ABORTED, 210 /** 211 * @brief Received data is ready for processing. 212 * 213 * This event is generated in the following cases: 214 * - When RX timeout occurred, and data was stored in provided buffer. 215 * This can happen multiple times in the same buffer. 216 * - When provided buffer is full. 217 * - After uart_rx_disable(). 218 * - After stopping due to external event (#UART_RX_STOPPED). 219 */ 220 UART_RX_RDY, 221 /** 222 * @brief Driver requests next buffer for continuous reception. 223 * 224 * This event is triggered when receiving has started for a new buffer, 225 * i.e. it's time to provide a next buffer for a seamless switchover to 226 * it. For continuous reliable receiving, user should provide another RX 227 * buffer in response to this event, using uart_rx_buf_rsp function 228 * 229 * If uart_rx_buf_rsp is not called before current buffer 230 * is filled up, receiving will stop. 231 */ 232 UART_RX_BUF_REQUEST, 233 /** 234 * @brief Buffer is no longer used by UART driver. 235 */ 236 UART_RX_BUF_RELEASED, 237 /** 238 * @brief RX has been disabled and can be reenabled. 239 * 240 * This event is generated whenever receiver has been stopped, disabled 241 * or finished its operation and can be enabled again using 242 * uart_rx_enable 243 */ 244 UART_RX_DISABLED, 245 /** 246 * @brief RX has stopped due to external event. 247 * 248 * Reason is one of uart_rx_stop_reason. 249 */ 250 UART_RX_STOPPED, 251 }; 252 253 /** @brief UART TX event data. */ 254 struct uart_event_tx { 255 /** @brief Pointer to current buffer. */ 256 const uint8_t *buf; 257 /** @brief Number of bytes sent. */ 258 size_t len; 259 }; 260 261 /** 262 * @brief UART RX event data. 263 * 264 * The data represented by the event is stored in rx.buf[rx.offset] to 265 * rx.buf[rx.offset+rx.len]. That is, the length is relative to the offset. 266 */ 267 struct uart_event_rx { 268 /** @brief Pointer to current buffer. */ 269 uint8_t *buf; 270 /** @brief Currently received data offset in bytes. */ 271 size_t offset; 272 /** @brief Number of new bytes received. */ 273 size_t len; 274 }; 275 276 /** @brief UART RX buffer released event data. */ 277 struct uart_event_rx_buf { 278 /** @brief Pointer to buffer that is no longer in use. */ 279 uint8_t *buf; 280 }; 281 282 /** @brief UART RX stopped data. */ 283 struct uart_event_rx_stop { 284 /** @brief Reason why receiving stopped */ 285 enum uart_rx_stop_reason reason; 286 /** @brief Last received data. */ 287 struct uart_event_rx data; 288 }; 289 290 /** @brief Structure containing information about current event. */ 291 struct uart_event { 292 /** @brief Type of event */ 293 enum uart_event_type type; 294 /** @brief Event data */ 295 union uart_event_data { 296 /** @brief #UART_TX_DONE and #UART_TX_ABORTED events data. */ 297 struct uart_event_tx tx; 298 /** @brief #UART_RX_RDY event data. */ 299 struct uart_event_rx rx; 300 /** @brief #UART_RX_BUF_RELEASED event data. */ 301 struct uart_event_rx_buf rx_buf; 302 /** @brief #UART_RX_STOPPED event data. */ 303 struct uart_event_rx_stop rx_stop; 304 } data; 305 }; 306 307 /** 308 * @typedef uart_callback_t 309 * @brief Define the application callback function signature for 310 * uart_callback_set() function. 311 * 312 * @param dev UART device instance. 313 * @param evt Pointer to uart_event instance. 314 * @param user_data Pointer to data specified by user. 315 */ 316 typedef void (*uart_callback_t)(const struct device *dev, 317 struct uart_event *evt, void *user_data); 318 319 /** 320 * @} 321 */ 322 323 /** 324 * @brief Check whether an error was detected. 325 * 326 * @param dev UART device instance. 327 * 328 * @retval 0 If no error was detected. 329 * @retval err Error flags as defined in @ref uart_rx_stop_reason 330 * @retval -ENOSYS If not implemented. 331 */ 332 __syscall int uart_err_check(const struct device *dev); 333 334 /** 335 * @defgroup uart_polling Polling UART API 336 * @{ 337 */ 338 339 /** 340 * @brief Read a character from the device for input. 341 * 342 * This routine checks if the receiver has valid data. When the 343 * receiver has valid data, it reads a character from the device, 344 * stores to the location pointed to by p_char, and returns 0 to the 345 * calling thread. It returns -1, otherwise. This function is a 346 * non-blocking call. 347 * 348 * @param dev UART device instance. 349 * @param p_char Pointer to character. 350 * 351 * @retval 0 If a character arrived. 352 * @retval -1 If no character was available to read (i.e. the UART 353 * input buffer was empty). 354 * @retval -ENOSYS If the operation is not implemented. 355 * @retval -EBUSY If async reception was enabled using @ref uart_rx_enable 356 */ 357 __syscall int uart_poll_in(const struct device *dev, unsigned char *p_char); 358 359 /** 360 * @brief Read a 16-bit datum from the device for input. 361 * 362 * This routine checks if the receiver has valid data. When the 363 * receiver has valid data, it reads a 16-bit datum from the device, 364 * stores to the location pointed to by p_u16, and returns 0 to the 365 * calling thread. It returns -1, otherwise. This function is a 366 * non-blocking call. 367 * 368 * @param dev UART device instance. 369 * @param p_u16 Pointer to 16-bit data. 370 * 371 * @retval 0 If data arrived. 372 * @retval -1 If no data was available to read (i.e., the UART 373 * input buffer was empty). 374 * @retval -ENOTSUP If API is not enabled. 375 * @retval -ENOSYS If the function is not implemented. 376 * @retval -EBUSY If async reception was enabled using @ref uart_rx_enable 377 */ 378 __syscall int uart_poll_in_u16(const struct device *dev, uint16_t *p_u16); 379 380 /** 381 * @brief Write a character to the device for output. 382 * 383 * This routine checks if the transmitter is full. When the 384 * transmitter is not full, it writes a character to the data 385 * register. It waits and blocks the calling thread otherwise. This 386 * function is a blocking call. It blocks the calling thread until the 387 * character is sent. 388 * 389 * To send a character when hardware flow control is enabled, the handshake 390 * signal CTS must be asserted. 391 * 392 * @param dev UART device instance. 393 * @param out_char Character to send. 394 */ 395 __syscall void uart_poll_out(const struct device *dev, 396 unsigned char out_char); 397 398 /** 399 * @brief Write a 16-bit datum to the device for output. 400 * 401 * This routine checks if the transmitter is full. When the 402 * transmitter is not full, it writes a 16-bit datum to the data 403 * register. It waits and blocks the calling thread, otherwise. This 404 * function is a blocking call. 405 * 406 * To send a datum when hardware flow control is enabled, the handshake 407 * signal CTS must be asserted. 408 * 409 * @param dev UART device instance. 410 * @param out_u16 Wide data to send. 411 */ 412 __syscall void uart_poll_out_u16(const struct device *dev, uint16_t out_u16); 413 414 /** 415 * @} 416 */ 417 418 /** 419 * @brief Set UART configuration. 420 * 421 * Sets UART configuration using data from *cfg. 422 * 423 * @param dev UART device instance. 424 * @param cfg UART configuration structure. 425 * 426 * @retval 0 If successful. 427 * @retval -errno Negative errno code in case of failure. 428 * @retval -ENOSYS If configuration is not supported by device 429 * or driver does not support setting configuration in runtime. 430 * @retval -ENOTSUP If API is not enabled. 431 */ 432 __syscall int uart_configure(const struct device *dev, 433 const struct uart_config *cfg); 434 435 /** 436 * @brief Get UART configuration. 437 * 438 * Stores current UART configuration to *cfg, can be used to retrieve initial 439 * configuration after device was initialized using data from DTS. 440 * 441 * @param dev UART device instance. 442 * @param cfg UART configuration structure. 443 * 444 * @retval 0 If successful. 445 * @retval -errno Negative errno code in case of failure. 446 * @retval -ENOSYS If driver does not support getting current configuration. 447 * @retval -ENOTSUP If API is not enabled. 448 */ 449 __syscall int uart_config_get(const struct device *dev, 450 struct uart_config *cfg); 451 452 /** 453 * @addtogroup uart_interrupt 454 * @{ 455 */ 456 457 /** 458 * @brief Fill FIFO with data. 459 * 460 * @details This function is expected to be called from UART 461 * interrupt handler (ISR), if uart_irq_tx_ready() returns true. 462 * Result of calling this function not from an ISR is undefined 463 * (hardware-dependent). Likewise, *not* calling this function 464 * from an ISR if uart_irq_tx_ready() returns true may lead to 465 * undefined behavior, e.g. infinite interrupt loops. It's 466 * mandatory to test return value of this function, as different 467 * hardware has different FIFO depth (oftentimes just 1). 468 * 469 * @param dev UART device instance. 470 * @param tx_data Data to transmit. 471 * @param size Number of bytes to send. 472 * 473 * @return Number of bytes sent. 474 * @retval -ENOSYS if this function is not supported 475 * @retval -ENOTSUP If API is not enabled. 476 */ 477 static inline int uart_fifo_fill(const struct device *dev, const uint8_t *tx_data, int size); 478 479 /** 480 * @brief Fill FIFO with wide data. 481 * 482 * @details This function is expected to be called from UART 483 * interrupt handler (ISR), if uart_irq_tx_ready() returns true. 484 * Result of calling this function not from an ISR is undefined 485 * (hardware-dependent). Likewise, *not* calling this function 486 * from an ISR if uart_irq_tx_ready() returns true may lead to 487 * undefined behavior, e.g. infinite interrupt loops. It's 488 * mandatory to test return value of this function, as different 489 * hardware has different FIFO depth (oftentimes just 1). 490 * 491 * @param dev UART device instance. 492 * @param tx_data Wide data to transmit. 493 * @param size Number of datum to send. 494 * 495 * @return Number of datum sent. 496 * @retval -ENOSYS If this function is not implemented 497 * @retval -ENOTSUP If API is not enabled. 498 */ 499 static inline int uart_fifo_fill_u16(const struct device *dev, const uint16_t *tx_data, int size); 500 501 /** 502 * @brief Read data from FIFO. 503 * 504 * @details This function is expected to be called from UART 505 * interrupt handler (ISR), if uart_irq_rx_ready() returns true. 506 * Result of calling this function not from an ISR is undefined 507 * (hardware-dependent). It's unspecified whether "RX ready" 508 * condition as returned by uart_irq_rx_ready() is level- or 509 * edge- triggered. That means that once uart_irq_rx_ready() is 510 * detected, uart_fifo_read() must be called until it reads all 511 * available data in the FIFO (i.e. until it returns less data 512 * than was requested). 513 * 514 * @param dev UART device instance. 515 * @param rx_data Data container. 516 * @param size Container size. 517 * 518 * @return Number of bytes read. 519 * @retval -ENOSYS If this function is not implemented. 520 * @retval -ENOTSUP If API is not enabled. 521 */ 522 static inline int uart_fifo_read(const struct device *dev, uint8_t *rx_data, const int size); 523 524 /** 525 * @brief Read wide data from FIFO. 526 * 527 * @details This function is expected to be called from UART 528 * interrupt handler (ISR), if uart_irq_rx_ready() returns true. 529 * Result of calling this function not from an ISR is undefined 530 * (hardware-dependent). It's unspecified whether "RX ready" 531 * condition as returned by uart_irq_rx_ready() is level- or 532 * edge- triggered. That means that once uart_irq_rx_ready() is 533 * detected, uart_fifo_read() must be called until it reads all 534 * available data in the FIFO (i.e. until it returns less data 535 * than was requested). 536 * 537 * @param dev UART device instance. 538 * @param rx_data Wide data container. 539 * @param size Container size. 540 * 541 * @return Number of datum read. 542 * @retval -ENOSYS If this function is not implemented. 543 * @retval -ENOTSUP If API is not enabled. 544 */ 545 static inline int uart_fifo_read_u16(const struct device *dev, uint16_t *rx_data, const int size); 546 547 /** 548 * @brief Enable TX interrupt in IER. 549 * 550 * @param dev UART device instance. 551 */ 552 __syscall void uart_irq_tx_enable(const struct device *dev); 553 554 /** 555 * @brief Disable TX interrupt in IER. 556 * 557 * @param dev UART device instance. 558 */ 559 __syscall void uart_irq_tx_disable(const struct device *dev); 560 561 /** 562 * @brief Check if UART TX buffer can accept bytes 563 * 564 * @details Check if UART TX buffer can accept more bytes 565 * for transmission (i.e. uart_fifo_fill() will succeed and return 566 * non-zero). This function must be called in a UART interrupt 567 * handler, or its result is undefined. Before calling this function 568 * in the interrupt handler, uart_irq_update() must be called once per 569 * the handler invocation. 570 * 571 * @param dev UART device instance. 572 * 573 * @retval 0 If device is not ready to write a new byte. 574 * @retval >0 Minimum number of bytes that can be written in a single call to 575 * @ref uart_fifo_fill. It may be possible to write more bytes, but 576 * the actual number written must be checked in the return code from 577 * @ref uart_fifo_fill. 578 * @retval -ENOSYS If this function is not implemented. 579 * @retval -ENOTSUP If API is not enabled. 580 */ 581 static inline int uart_irq_tx_ready(const struct device *dev); 582 583 /** 584 * @brief Enable RX interrupt. 585 * 586 * @param dev UART device instance. 587 */ 588 __syscall void uart_irq_rx_enable(const struct device *dev); 589 590 /** 591 * @brief Disable RX interrupt. 592 * 593 * @param dev UART device instance. 594 */ 595 __syscall void uart_irq_rx_disable(const struct device *dev); 596 597 /** 598 * @brief Check if UART TX block finished transmission 599 * 600 * @details Check if any outgoing data buffered in UART TX block was 601 * fully transmitted and TX block is idle. When this condition is 602 * true, UART device (or whole system) can be power off. Note that 603 * this function is *not* useful to check if UART TX can accept more 604 * data, use uart_irq_tx_ready() for that. This function must be called 605 * in a UART interrupt handler, or its result is undefined. Before 606 * calling this function in the interrupt handler, uart_irq_update() 607 * must be called once per the handler invocation. 608 * 609 * @param dev UART device instance. 610 * 611 * @retval 1 If nothing remains to be transmitted. 612 * @retval 0 If transmission is not completed. 613 * @retval -ENOSYS If this function is not implemented. 614 * @retval -ENOTSUP If API is not enabled. 615 */ 616 static inline int uart_irq_tx_complete(const struct device *dev); 617 618 /** 619 * @brief Check if UART RX buffer has a received char 620 * 621 * @details Check if UART RX buffer has at least one pending character 622 * (i.e. uart_fifo_read() will succeed and return non-zero). This function 623 * must be called in a UART interrupt handler, or its result is undefined. 624 * Before calling this function in the interrupt handler, uart_irq_update() 625 * must be called once per the handler invocation. It's unspecified whether 626 * condition as returned by this function is level- or edge- triggered (i.e. 627 * if this function returns true when RX FIFO is non-empty, or when a new 628 * char was received since last call to it). See description of 629 * uart_fifo_read() for implication of this. 630 * 631 * @param dev UART device instance. 632 * 633 * @retval 1 If a received char is ready. 634 * @retval 0 If a received char is not ready. 635 * @retval -ENOSYS If this function is not implemented. 636 * @retval -ENOTSUP If API is not enabled. 637 */ 638 static inline int uart_irq_rx_ready(const struct device *dev); 639 640 /** 641 * @brief Enable error interrupt. 642 * 643 * @param dev UART device instance. 644 */ 645 __syscall void uart_irq_err_enable(const struct device *dev); 646 647 /** 648 * @brief Disable error interrupt. 649 * 650 * @param dev UART device instance. 651 */ 652 __syscall void uart_irq_err_disable(const struct device *dev); 653 654 /** 655 * @brief Check if any IRQs is pending. 656 * 657 * @param dev UART device instance. 658 * 659 * @retval 1 If an IRQ is pending. 660 * @retval 0 If an IRQ is not pending. 661 * @retval -ENOSYS If this function is not implemented. 662 * @retval -ENOTSUP If API is not enabled. 663 */ 664 __syscall int uart_irq_is_pending(const struct device *dev); 665 666 /** 667 * @brief Start processing interrupts in ISR. 668 * 669 * This function should be called the first thing in the ISR. Calling 670 * uart_irq_rx_ready(), uart_irq_tx_ready(), uart_irq_tx_complete() 671 * allowed only after this. 672 * 673 * The purpose of this function is: 674 * 675 * * For devices with auto-acknowledge of interrupt status on register 676 * read to cache the value of this register (rx_ready, etc. then use 677 * this case). 678 * * For devices with explicit acknowledgment of interrupts, to ack 679 * any pending interrupts and likewise to cache the original value. 680 * * For devices with implicit acknowledgment, this function will be 681 * empty. But the ISR must perform the actions needs to ack the 682 * interrupts (usually, call uart_fifo_read() on rx_ready, and 683 * uart_fifo_fill() on tx_ready). 684 * 685 * @param dev UART device instance. 686 * 687 * @retval 1 On success. 688 * @retval -ENOSYS If this function is not implemented. 689 * @retval -ENOTSUP If API is not enabled. 690 */ 691 __syscall int uart_irq_update(const struct device *dev); 692 693 /** 694 * @brief Set the IRQ callback function pointer. 695 * 696 * This sets up the callback for IRQ. When an IRQ is triggered, 697 * the specified function will be called with specified user data. 698 * See description of uart_irq_update() for the requirements on ISR. 699 * 700 * @param dev UART device instance. 701 * @param cb Pointer to the callback function. 702 * @param user_data Data to pass to callback function. 703 * 704 * @retval 0 On success. 705 * @retval -ENOSYS If this function is not implemented. 706 * @retval -ENOTSUP If API is not enabled. 707 */ 708 static inline int uart_irq_callback_user_data_set(const struct device *dev, 709 uart_irq_callback_user_data_t cb, 710 void *user_data); 711 712 /** 713 * @brief Set the IRQ callback function pointer (legacy). 714 * 715 * This sets up the callback for IRQ. When an IRQ is triggered, 716 * the specified function will be called with the device pointer. 717 * 718 * @param dev UART device instance. 719 * @param cb Pointer to the callback function. 720 * 721 * @retval 0 On success. 722 * @retval -ENOSYS If this function is not implemented. 723 * @retval -ENOTSUP If API is not enabled. 724 */ 725 static inline int uart_irq_callback_set(const struct device *dev, 726 uart_irq_callback_user_data_t cb); 727 728 /** 729 * @} 730 */ 731 732 /** 733 * @addtogroup uart_async 734 * @{ 735 */ 736 737 /** 738 * @brief Set event handler function. 739 * 740 * Since it is mandatory to set callback to use other asynchronous functions, 741 * it can be used to detect if the device supports asynchronous API. Remaining 742 * API does not have that detection. 743 * 744 * @param dev UART device instance. 745 * @param callback Event handler. 746 * @param user_data Data to pass to event handler function. 747 * 748 * @retval 0 If successful. 749 * @retval -ENOSYS If not supported by the device. 750 * @retval -ENOTSUP If API not enabled. 751 */ 752 static inline int uart_callback_set(const struct device *dev, 753 uart_callback_t callback, 754 void *user_data); 755 756 /** 757 * @brief Send given number of bytes from buffer through UART. 758 * 759 * Function returns immediately and event handler, 760 * set using @ref uart_callback_set, is called after transfer is finished. 761 * 762 * @param dev UART device instance. 763 * @param buf Pointer to transmit buffer. 764 * @param len Length of transmit buffer. 765 * @param timeout Timeout in microseconds. Valid only if flow control is 766 * enabled. @ref SYS_FOREVER_US disables timeout. 767 * 768 * @retval 0 If successful. 769 * @retval -ENOTSUP If API is not enabled. 770 * @retval -EBUSY If There is already an ongoing transfer. 771 * @retval -errno Other negative errno value in case of failure. 772 */ 773 __syscall int uart_tx(const struct device *dev, const uint8_t *buf, 774 size_t len, 775 int32_t timeout); 776 777 /** 778 * @brief Send given number of datum from buffer through UART. 779 * 780 * Function returns immediately and event handler, 781 * set using @ref uart_callback_set, is called after transfer is finished. 782 * 783 * @param dev UART device instance. 784 * @param buf Pointer to wide data transmit buffer. 785 * @param len Length of wide data transmit buffer. 786 * @param timeout Timeout in milliseconds. Valid only if flow control is 787 * enabled. @ref SYS_FOREVER_MS disables timeout. 788 * 789 * @retval 0 If successful. 790 * @retval -ENOTSUP If API is not enabled. 791 * @retval -EBUSY If there is already an ongoing transfer. 792 * @retval -errno Other negative errno value in case of failure. 793 */ 794 __syscall int uart_tx_u16(const struct device *dev, const uint16_t *buf, 795 size_t len, int32_t timeout); 796 797 /** 798 * @brief Abort current TX transmission. 799 * 800 * #UART_TX_DONE event will be generated with amount of data sent. 801 * 802 * @param dev UART device instance. 803 * 804 * @retval 0 If successful. 805 * @retval -ENOTSUP If API is not enabled. 806 * @retval -EFAULT There is no active transmission. 807 * @retval -errno Other negative errno value in case of failure. 808 */ 809 __syscall int uart_tx_abort(const struct device *dev); 810 811 /** 812 * @brief Start receiving data through UART. 813 * 814 * Function sets given buffer as first buffer for receiving and returns 815 * immediately. After that event handler, set using @ref uart_callback_set, 816 * is called with #UART_RX_RDY or #UART_RX_BUF_REQUEST events. 817 * 818 * @param dev UART device instance. 819 * @param buf Pointer to receive buffer. 820 * @param len Buffer length. 821 * @param timeout Inactivity period after receiving at least a byte which 822 * triggers #UART_RX_RDY event. Given in microseconds. 823 * @ref SYS_FOREVER_US disables timeout. See @ref uart_event_type 824 * for details. 825 * 826 * @retval 0 If successful. 827 * @retval -ENOTSUP If API is not enabled. 828 * @retval -EBUSY RX already in progress. 829 * @retval -errno Other negative errno value in case of failure. 830 * 831 */ 832 __syscall int uart_rx_enable(const struct device *dev, uint8_t *buf, 833 size_t len, 834 int32_t timeout); 835 836 /** 837 * @brief Start receiving wide data through UART. 838 * 839 * Function sets given buffer as first buffer for receiving and returns 840 * immediately. After that event handler, set using @ref uart_callback_set, 841 * is called with #UART_RX_RDY or #UART_RX_BUF_REQUEST events. 842 * 843 * @param dev UART device instance. 844 * @param buf Pointer to wide data receive buffer. 845 * @param len Buffer length. 846 * @param timeout Inactivity period after receiving at least a byte which 847 * triggers #UART_RX_RDY event. Given in milliseconds. 848 * @ref SYS_FOREVER_MS disables timeout. See 849 * @ref uart_event_type for details. 850 * 851 * @retval 0 If successful. 852 * @retval -ENOTSUP If API is not enabled. 853 * @retval -EBUSY RX already in progress. 854 * @retval -errno Other negative errno value in case of failure. 855 * 856 */ 857 __syscall int uart_rx_enable_u16(const struct device *dev, uint16_t *buf, 858 size_t len, int32_t timeout); 859 860 /** 861 * @brief Provide receive buffer in response to #UART_RX_BUF_REQUEST event. 862 * 863 * Provide pointer to RX buffer, which will be used when current buffer is 864 * filled. 865 * 866 * @note Providing buffer that is already in usage by driver leads to 867 * undefined behavior. Buffer can be reused when it has been released 868 * by driver. 869 * 870 * @param dev UART device instance. 871 * @param buf Pointer to receive buffer. 872 * @param len Buffer length. 873 * 874 * @retval 0 If successful. 875 * @retval -ENOTSUP If API is not enabled. 876 * @retval -EBUSY Next buffer already set. 877 * @retval -EACCES Receiver is already disabled (function called too late?). 878 * @retval -errno Other negative errno value in case of failure. 879 */ 880 static inline int uart_rx_buf_rsp(const struct device *dev, uint8_t *buf, 881 size_t len); 882 883 /** 884 * @brief Provide wide data receive buffer in response to #UART_RX_BUF_REQUEST 885 * event. 886 * 887 * Provide pointer to RX buffer, which will be used when current buffer is 888 * filled. 889 * 890 * @note Providing buffer that is already in usage by driver leads to 891 * undefined behavior. Buffer can be reused when it has been released 892 * by driver. 893 * 894 * @param dev UART device instance. 895 * @param buf Pointer to wide data receive buffer. 896 * @param len Buffer length. 897 * 898 * @retval 0 If successful. 899 * @retval -ENOTSUP If API is not enabled 900 * @retval -EBUSY Next buffer already set. 901 * @retval -EACCES Receiver is already disabled (function called too late?). 902 * @retval -errno Other negative errno value in case of failure. 903 */ 904 static inline int uart_rx_buf_rsp_u16(const struct device *dev, uint16_t *buf, 905 size_t len); 906 907 /** 908 * @brief Disable RX 909 * 910 * #UART_RX_BUF_RELEASED event will be generated for every buffer scheduled, 911 * after that #UART_RX_DISABLED event will be generated. Additionally, if there 912 * is any pending received data, the #UART_RX_RDY event for that data will be 913 * generated before the #UART_RX_BUF_RELEASED events. 914 * 915 * @param dev UART device instance. 916 * 917 * @retval 0 If successful. 918 * @retval -ENOTSUP If API is not enabled. 919 * @retval -EFAULT There is no active reception. 920 * @retval -errno Other negative errno value in case of failure. 921 */ 922 __syscall int uart_rx_disable(const struct device *dev); 923 924 /** 925 * @} 926 */ 927 928 /** 929 * @brief Manipulate line control for UART. 930 * 931 * @param dev UART device instance. 932 * @param ctrl The line control to manipulate (see enum uart_line_ctrl). 933 * @param val Value to set to the line control. 934 * 935 * @retval 0 If successful. 936 * @retval -ENOSYS If this function is not implemented. 937 * @retval -ENOTSUP If API is not enabled. 938 * @retval -errno Other negative errno value in case of failure. 939 */ 940 __syscall int uart_line_ctrl_set(const struct device *dev, 941 uint32_t ctrl, uint32_t val); 942 943 /** 944 * @brief Retrieve line control for UART. 945 * 946 * @param dev UART device instance. 947 * @param ctrl The line control to retrieve (see enum uart_line_ctrl). 948 * @param val Pointer to variable where to store the line control value. 949 * 950 * @retval 0 If successful. 951 * @retval -ENOSYS If this function is not implemented. 952 * @retval -ENOTSUP If API is not enabled. 953 * @retval -errno Other negative errno value in case of failure. 954 */ 955 __syscall int uart_line_ctrl_get(const struct device *dev, uint32_t ctrl, 956 uint32_t *val); 957 958 /** 959 * @brief Send extra command to driver. 960 * 961 * Implementation and accepted commands are driver specific. 962 * Refer to the drivers for more information. 963 * 964 * @param dev UART device instance. 965 * @param cmd Command to driver. 966 * @param p Parameter to the command. 967 * 968 * @retval 0 If successful. 969 * @retval -ENOSYS If this function is not implemented. 970 * @retval -ENOTSUP If API is not enabled. 971 * @retval -errno Other negative errno value in case of failure. 972 */ 973 __syscall int uart_drv_cmd(const struct device *dev, uint32_t cmd, uint32_t p); 974 975 #ifdef __cplusplus 976 } 977 #endif 978 979 /** 980 * @} 981 */ 982 983 #include <zephyr/drivers/uart/uart_internal.h> 984 #include <zephyr/syscalls/uart.h> 985 986 #endif /* ZEPHYR_INCLUDE_DRIVERS_UART_H_ */ 987
