1 // Copyright (C) 2022 Beken Corporation 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 #pragma once 16 17 #include <common/bk_include.h> 18 #include <driver/uart_types.h> 19 20 #ifdef __cplusplus 21 extern "C" { 22 #endif 23 24 /** 25 * @brief Init the UART driver 26 * 27 * This API init the resoure common to all UART id: 28 * - Init UART driver control memory 29 * 30 * @attention 1. This API should be called before any other UART APIs. 31 * 32 * @return 33 * - BK_OK: succeed 34 * - others: other errors. 35 */ 36 bk_err_t bk_uart_driver_init(void); 37 38 /** 39 * @brief Deinit the UART driver 40 * 41 * This API free all resource related to UART and power down all UART id. 42 * 43 * @return 44 * - BK_OK: succeed 45 * - others: other errors. 46 */ 47 bk_err_t bk_uart_driver_deinit(void); 48 49 /** 50 * @brief Get the UART whether in used 51 * 52 * @param id UART id 53 * 54 * @return 55 * - 1: in used 56 * - 0: not in used 57 */ 58 int bk_uart_is_in_used(uart_id_t id); 59 60 /** 61 * @brief Init the UART id 62 * 63 * This API init the UART id: 64 * - Power up the UART id 65 * - Configure the UART id clock 66 * - Map the UART id to dedicated GPIO port 67 * - Set the UART baud rate, data bits, parity, stop bits,flow ctrl and source clock 68 * - Start the UART id 69 * 70 * @param id UART id 71 * @param config UART parameter settings 72 * 73 * @return 74 * - BK_OK: succeed 75 * - BK_ERR_UART_NOT_INIT: UART driver not init 76 * - BK_ERR_NULL_PARAM: UART config parameter is NULL 77 * - BK_ERR_UART_INVALID_ID: UART id is invalid 78 * - BK_ERR_UART_BAUD_RATE_NOT_SUPPORT: UART baud rate is not support 79 * - others: other errors. 80 */ 81 bk_err_t bk_uart_init(uart_id_t id, const uart_config_t *config); 82 83 /** 84 * @brief Deinit the UART id 85 * 86 * This API deinit the UART id: 87 * - Stop the UART id 88 * - Reset all configuration of UART id to default value 89 * - Disable the UART id interrupt 90 * - Power down the UART id 91 * 92 * @param id UART id 93 * 94 * @return 95 * - BK_OK: succeed 96 * - others: other errors. 97 */ 98 bk_err_t bk_uart_deinit(uart_id_t id); 99 100 /** 101 * @brief Set the UART baud rate 102 * 103 * @param id UART id 104 * @param baud_rate UART baud rate 105 * 106 * @return 107 * - BK_OK: succeed 108 * - others: other errors. 109 */ 110 bk_err_t bk_uart_set_baud_rate(uart_id_t id, uint32_t baud_rate); 111 112 /** 113 * @brief Set the UART data bits 114 * 115 * @param id UART id 116 * @param data_bits UART data bits 117 * 118 * @return 119 * - BK_OK: succeed 120 * - others: other errors. 121 */ 122 bk_err_t bk_uart_set_data_bits(uart_id_t id, uart_data_bits_t data_bits); 123 124 /** 125 * @brief Set the UART stop bits 126 * 127 * @param id UART id 128 * @param stop_bits UART stop bits 129 * 130 * @return 131 * - BK_OK: succeed 132 * - others: other errors. 133 */ 134 bk_err_t bk_uart_set_stop_bits(uart_id_t id, uart_stop_bits_t stop_bits); 135 136 /** 137 * @brief Set the UART partiy 138 * 139 * @param id UART id 140 * @param partiy UART partiy 141 * 142 * @return 143 * - BK_OK: succeed 144 * - others: other errors. 145 */ 146 bk_err_t bk_uart_set_parity(uart_id_t id, uart_parity_t partiy); 147 148 /** 149 * @brief Set the UART hardware flow control 150 * 151 * @param id UART id 152 * @param rx_threshold Threshold of Hardware RX flow control 153 * 154 * @return 155 * - BK_OK: succeed 156 * - others: other errors. 157 */ 158 bk_err_t bk_uart_set_hw_flow_ctrl(uart_id_t id, uint8_t rx_threshold); 159 160 /** 161 * @brief Set the UART threshold value for RX fifo full 162 * 163 * @param id UART id 164 * @param threshold Threshold value above which RX fifo full interrupt is generated 165 * 166 * @return 167 * - BK_OK: succeed 168 * - others: other errors. 169 */ 170 bk_err_t bk_uart_set_rx_full_threshold(uart_id_t id, uint8_t threshold); 171 172 /** 173 * @brief Set the UART threshold value for TX fifo empty 174 * 175 * @param id UART id 176 * @param threshold Threshold value below which TX fifo empty interrupt is generated 177 * 178 * @return 179 * - BK_OK: succeed 180 * - others: other errors. 181 */ 182 bk_err_t bk_uart_set_tx_empty_threshold(uart_id_t id, uint8_t threshold); 183 184 /** 185 * @brief Set the UART threshold timeout for receive data, unit is bit 186 * 187 * UART finish receiving data when the periods is more than timeout threshold. 188 * If the time is expired, the UART_RX_STOP_END interrupt is triggered. 189 * 190 * @param id UART id 191 * @param timeout_thresh timeout threshold 192 * 193 * @return 194 * - BK_OK: succeed 195 * - others: other errors. 196 */ 197 bk_err_t bk_uart_set_rx_timeout(uart_id_t id, uart_rx_stop_detect_time_t timeout_thresh); 198 199 /** 200 * @brief Disable the UART hardware flow control 201 * 202 * @param id UART id 203 * 204 * @return 205 * - BK_OK: succeed 206 * - others: other errors. 207 */ 208 bk_err_t bk_uart_disable_hw_flow_ctrl(uart_id_t id); 209 210 /** 211 * @brief Enable TX interrupt of UART id 212 * 213 * @param id UART id 214 * 215 * @return 216 * - BK_OK: succeed 217 * - others: other errors. 218 */ 219 bk_err_t bk_uart_enable_tx_interrupt(uart_id_t id); 220 221 /** 222 * @brief Disable TX interrupt of UART id 223 * 224 * @param id UART id 225 * 226 * @return 227 * - BK_OK: succeed 228 * - others: other errors. 229 */ 230 bk_err_t bk_uart_disable_tx_interrupt(uart_id_t id); 231 232 /** 233 * @brief Enable RX interrupt of UART id 234 * 235 * @param id UART id 236 * 237 * @return 238 * - BK_OK: succeed 239 * - others: other errors. 240 */ 241 bk_err_t bk_uart_enable_rx_interrupt(uart_id_t id); 242 243 /** 244 * @brief Disable RX interrupt of UART id 245 * 246 * @param id UART id 247 * 248 * @return 249 * - BK_OK: succeed 250 * - others: other errors. 251 */ 252 bk_err_t bk_uart_disable_rx_interrupt(uart_id_t id); 253 254 /** 255 * @brief Register the RX interrupt service routine for UART id 256 * 257 * @param id UART id 258 * @param isr UART RX callback 259 * @param param UART RX callback parameter 260 * 261 * @return 262 * - BK_OK: succeed 263 * - others: other errors. 264 */ 265 bk_err_t bk_uart_register_rx_isr(uart_id_t id, uart_isr_t isr, void *param); 266 267 /** 268 * @brief Register the TX interrupt service routine for UART id 269 * 270 * @param id UART id 271 * @param isr UART TX callback 272 * @param param UART TX callback parameter 273 * 274 * @return 275 * - BK_OK: succeed 276 * - others: other errors. 277 */ 278 bk_err_t bk_uart_register_tx_isr(uart_id_t id, uart_isr_t isr, void *param); 279 280 /** 281 * @brief Send data to the UART port from a given buffer and length 282 * 283 * @param id UART id 284 * @param data data buffer address 285 * @param size data length to send 286 * 287 * @return 288 * - BK_OK: succeed 289 * - others: other errors. 290 */ 291 bk_err_t bk_uart_write_bytes(uart_id_t id, const void *data, uint32_t size); 292 293 /** 294 * @brief UART read bytes from UART buffer 295 * 296 * @param id UART id 297 * @param data pointer to the buffer 298 * @param size data length to read 299 * @param timeout_ms timeout ms, if set BEKEN_WAIT_FOREVER, read will wait forever 300 * 301 * @return 302 * - BK_ERR_UART_NOT_INIT: UART driver not init 303 * - BK_ERR_UART_INVALID_ID: UART id number is invalid 304 * - BK_ERR_UART_ID_NOT_INIT: UART id not init 305 * - BK_ERR_UART_RX_TIMEOUT: UART receive data timeout 306 * - others (>=0): The number of bytes read from UART FIFO 307 */ 308 int bk_uart_read_bytes(uart_id_t id, void *data, uint32_t size, uint32_t timeout_ms); 309 310 /** 311 * @brief Disable UART TX pin and set as GPIO 312 * 313 * @param id UART id 314 * 315 * @return 316 * - BK_OK: succeed 317 * - others: other errors. 318 */ 319 bk_err_t bk_uart_disable_rx(uart_id_t id); 320 321 /** 322 * @brief Disable UART TX pin and set as GPIO 323 * 324 * @param id UART id 325 * 326 * @return 327 * - BK_OK: succeed 328 * - others: other errors. 329 */ 330 bk_err_t bk_uart_disable_tx(uart_id_t id); 331 332 /** 333 * @brief Just set UART RX enable/disable, doesn't set pin 334 * 335 * @param id UART id 336 * @param enable: true, enable, flase disable 337 * 338 * @return 339 * - BK_OK: succeed 340 * - others: other errors. 341 */ 342 bk_err_t bk_uart_set_enable_rx(uart_id_t id, bool enable); 343 344 /** 345 * @brief Just set UART TX enable/disable, doesn't set pin 346 * 347 * @param id UART id 348 * @param enable: true, enable, flase disable 349 * 350 * @return 351 * - BK_OK: succeed 352 * - others: other errors. 353 */ 354 bk_err_t bk_uart_set_enable_tx(uart_id_t id, bool enable); 355 356 /** 357 * @brief Enable UART software fifo 358 * 359 * @param id UART id 360 * 361 * @return 362 * - BK_OK: succeed 363 * - others: other errors. 364 */ 365 bk_err_t bk_uart_enable_sw_fifo(uart_id_t id); 366 367 /** 368 * @brief Disable UART software fifo 369 * 370 * @param id UART id 371 * 372 * @return 373 * - BK_OK: succeed 374 * - others: other errors. 375 */ 376 bk_err_t bk_uart_disable_sw_fifo(uart_id_t id); 377 378 /** 379 * @brief Get the gpio pin when in ate detect 380 * 381 * @return the ate detect gpio pin 382 */ 383 uint32_t bk_uart_get_ate_detect_gpio(void); 384 385 /** 386 * @brief Register uart rx isr and disable software fifo 387 * 388 * @param id UART id 389 * @param isr UART RX callback 390 * @param param UART RX callback parameter 391 * 392 * @return 393 * - BK_OK: succeed 394 * - others: other errors. 395 */ 396 bk_err_t bk_uart_take_rx_isr(uart_id_t id, uart_isr_t isr, void *param); 397 398 /** 399 * @brief Recover uart rx isr 400 * 401 * @param id UART id 402 * 403 * @return 404 * - BK_OK: succeed 405 * - others: other errors. 406 */ 407 bk_err_t bk_uart_recover_rx_isr(uart_id_t id); 408 409 #ifdef __cplusplus 410 } 411 #endif 412 413