Line data Source code
1 1 : /* 2 : * Copyright (c) 2023 Nordic Semiconductor ASA 3 : * 4 : * SPDX-License-Identifier: Apache-2.0 5 : */ 6 : 7 : /** 8 : * @file 9 : * @brief Helper module for receiving using UART Asynchronous API. 10 : */ 11 : 12 : #ifndef ZEPHYR_DRIVERS_SERIAL_UART_ASYNC_RX_H_ 13 : #define ZEPHYR_DRIVERS_SERIAL_UART_ASYNC_RX_H_ 14 : 15 : #ifdef __cplusplus 16 : extern "C" { 17 : #endif 18 : 19 : #include <zephyr/kernel.h> 20 : 21 : /* @brief RX buffer structure which holds the buffer and its state. */ 22 0 : struct uart_async_rx_buf { 23 : /* Write index which is incremented whenever new data is reported to be 24 : * received to that buffer. 25 : */ 26 0 : uint8_t wr_idx:7; 27 : 28 : /* Set to one if buffer is released by the driver. */ 29 0 : uint8_t completed:1; 30 : 31 : /* Location which is passed to the UART driver. */ 32 0 : uint8_t buffer[]; 33 : }; 34 : 35 : /** @brief UART asynchronous RX helper structure. */ 36 1 : struct uart_async_rx { 37 : /* Pointer to the configuration structure. Structure must be persistent. */ 38 0 : const struct uart_async_rx_config *config; 39 : 40 : /* Total amount of pending bytes. Bytes may be spread across multiple RX buffers. */ 41 0 : atomic_t pending_bytes; 42 : 43 : /* Number of buffers which are free. */ 44 0 : atomic_t free_buf_cnt; 45 : 46 : /* Single buffer size. */ 47 0 : uint8_t buf_len; 48 : 49 : /* Index of the next buffer to be provided to the driver. */ 50 0 : uint8_t drv_buf_idx; 51 : 52 : /* Current buffer from which data is being consumed. */ 53 0 : uint8_t rd_buf_idx; 54 : 55 : /* Current read index in the buffer from which data is being consumed. 56 : * Read index which is incremented whenever data is consumed from the buffer. 57 : */ 58 0 : uint8_t rd_idx; 59 : }; 60 : 61 : /** @brief UART asynchronous RX helper configuration structure. */ 62 1 : struct uart_async_rx_config { 63 : /* Pointer to the buffer. */ 64 0 : uint8_t *buffer; 65 : 66 : /* Buffer length. */ 67 0 : size_t length; 68 : 69 : /* Number of buffers into provided space shall be split. */ 70 0 : uint8_t buf_cnt; 71 : }; 72 : 73 : /** @brief Get RX buffer length. 74 : * 75 : * @param async_rx Pointer to the helper instance. 76 : * 77 : * @return Buffer length. 78 : */ 79 1 : static inline uint8_t uart_async_rx_get_buf_len(struct uart_async_rx *async_rx) 80 : { 81 : return async_rx->buf_len; 82 : } 83 : 84 : /** @brief Get amount of space dedicated for managing each buffer state. 85 : * 86 : * User buffer provided during the initialization is split into chunks and each 87 : * chunk has overhead. This overhead can be used to calculate actual space used 88 : * for UART data. 89 : * 90 : * @return Overhead space in bytes. 91 : */ 92 1 : #define UART_ASYNC_RX_BUF_OVERHEAD offsetof(struct uart_async_rx_buf, buffer) 93 : 94 : /** @brief Initialize the helper instance. 95 : * 96 : * @param async_rx Pointer to the helper instance. 97 : * @param config Configuration. Must be persistent. 98 : * 99 : * @retval 0 on successful initialization. 100 : */ 101 1 : int uart_async_rx_init(struct uart_async_rx *async_rx, 102 : const struct uart_async_rx_config *config); 103 : 104 : /** @brief Reset state of the helper instance. 105 : * 106 : * Helper can be reset after RX abort to discard all received data and bring 107 : * the helper to its initial state. 108 : * 109 : * @param async_rx Pointer to the helper instance. 110 : */ 111 1 : void uart_async_rx_reset(struct uart_async_rx *async_rx); 112 : 113 : /** @brief Indicate received data. 114 : * 115 : * Function shall be called from @ref UART_RX_RDY context. 116 : * 117 : * @param async_rx Pointer to the helper instance. 118 : * @param buffer Buffer received in the UART driver event. 119 : * @param length Length received in the UART driver event. 120 : */ 121 1 : void uart_async_rx_on_rdy(struct uart_async_rx *async_rx, uint8_t *buffer, size_t length); 122 : 123 : /** @brief Get next RX buffer. 124 : * 125 : * Returned pointer shall be provided to @ref uart_rx_buf_rsp or @ref uart_rx_enable. 126 : * If null is returned that indicates that there are no available buffers since all 127 : * buffers are used by the driver or contain not consumed data. 128 : * 129 : * @param async_rx Pointer to the helper instance. 130 : * 131 : * @return Pointer to the next RX buffer or null if no buffer available. 132 : */ 133 1 : uint8_t *uart_async_rx_buf_req(struct uart_async_rx *async_rx); 134 : 135 : /** @brief Indicate that buffer is no longer used by the UART driver. 136 : * 137 : * Function shall be called on @ref UART_RX_BUF_RELEASED event. 138 : * 139 : * @param async_rx Pointer to the helper instance. 140 : * @param buf Buffer pointer received in the UART driver event. 141 : */ 142 1 : void uart_async_rx_on_buf_rel(struct uart_async_rx *async_rx, uint8_t *buf); 143 : 144 : /** @brief Claim received data for processing. 145 : * 146 : * Helper module works in the zero copy mode. It provides a pointer to the buffer 147 : * that was directly used by the UART driver. Since received data is spread across 148 : * multiple buffers there is no possibility to read all data at once. It can only be 149 : * consumed in chunks. After data is processed, @ref uart_async_rx_data_consume is 150 : * used to indicate that data is consumed. 151 : * 152 : * @param async_rx Pointer to the helper instance. 153 : * @param data Location where address to the buffer is written. Untouched if no data to claim. 154 : * @param length Amount of requested data. 155 : * 156 : * @return Amount valid of data in the @p data buffer. 0 is returned when there is no data. 157 : */ 158 1 : size_t uart_async_rx_data_claim(struct uart_async_rx *async_rx, uint8_t **data, size_t length); 159 : 160 : /** @brief Consume claimed data. 161 : * 162 : * It pairs with @ref uart_async_rx_data_claim. 163 : * 164 : * @param async_rx Pointer to the helper instance. 165 : * @param length Amount of data to consume. It must be less or equal than amount of claimed data. 166 : * 167 : * @retval true If there are free buffers in the pool after data got consumed. 168 : * @retval false If there are no free buffers. 169 : */ 170 1 : bool uart_async_rx_data_consume(struct uart_async_rx *async_rx, size_t length); 171 : 172 : #ifdef __cplusplus 173 : } 174 : #endif 175 : 176 : #endif /* ZEPHYR_DRIVERS_SERIAL_UART_ASYNC_RX_H_ */
