1 /* 2 * Copyright (c) 2015 - 2018, Nordic Semiconductor ASA 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 are met: 7 * 8 * 1. Redistributions of source code must retain the above copyright notice, this 9 * list of conditions and the following disclaimer. 10 * 11 * 2. Redistributions in binary form must reproduce the above copyright 12 * notice, this list of conditions and the following disclaimer in the 13 * documentation and/or other materials provided with the distribution. 14 * 15 * 3. Neither the name of the copyright holder nor the names of its 16 * contributors may be used to endorse or promote products derived from this 17 * software without specific prior written permission. 18 * 19 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 20 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 23 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 24 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 25 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 26 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 27 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 28 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 29 * POSSIBILITY OF SUCH DAMAGE. 30 */ 31 32 #ifndef NRFX_UARTE_H__ 33 #define NRFX_UARTE_H__ 34 35 #include <nrfx.h> 36 #include <hal/nrf_uarte.h> 37 38 #ifdef __cplusplus 39 extern "C" { 40 #endif 41 42 /** 43 * @defgroup nrfx_uarte UARTE driver 44 * @{ 45 * @ingroup nrf_uarte 46 * @brief UARTE peripheral driver. 47 */ 48 49 /** 50 * @brief Structure for the UARTE driver instance. 51 */ 52 typedef struct 53 { 54 NRF_UARTE_Type * p_reg; ///< Pointer to a structure with UARTE registers. 55 uint8_t drv_inst_idx; ///< Driver instance index. 56 } nrfx_uarte_t; 57 58 enum { 59 #if NRFX_CHECK(NRFX_UARTE0_ENABLED) 60 NRFX_UARTE0_INST_IDX, 61 #endif 62 #if NRFX_CHECK(NRFX_UARTE1_ENABLED) 63 NRFX_UARTE1_INST_IDX, 64 #endif 65 #if NRFX_CHECK(NRFX_UARTE2_ENABLED) 66 NRFX_UARTE2_INST_IDX, 67 #endif 68 #if NRFX_CHECK(NRFX_UARTE3_ENABLED) 69 NRFX_UARTE3_INST_IDX, 70 #endif 71 NRFX_UARTE_ENABLED_COUNT 72 }; 73 74 /** 75 * @brief Macro for creating a UARTE driver instance. 76 */ 77 #define NRFX_UARTE_INSTANCE(id) \ 78 { \ 79 .p_reg = NRFX_CONCAT_2(NRF_UARTE, id), \ 80 .drv_inst_idx = NRFX_CONCAT_3(NRFX_UARTE, id, _INST_IDX), \ 81 } 82 83 /** 84 * @brief Types of UARTE driver events. 85 */ 86 typedef enum 87 { 88 NRFX_UARTE_EVT_TX_DONE, ///< Requested TX transfer completed. 89 NRFX_UARTE_EVT_RX_DONE, ///< Requested RX transfer completed. 90 NRFX_UARTE_EVT_ERROR, ///< Error reported by UART peripheral. 91 } nrfx_uarte_evt_type_t; 92 93 /** 94 * @brief Structure for UARTE configuration. 95 */ 96 typedef struct 97 { 98 uint32_t pseltxd; ///< TXD pin number. 99 uint32_t pselrxd; ///< RXD pin number. 100 uint32_t pselcts; ///< CTS pin number. 101 uint32_t pselrts; ///< RTS pin number. 102 void * p_context; ///< Context passed to interrupt handler. 103 nrf_uarte_hwfc_t hwfc; ///< Flow control configuration. 104 nrf_uarte_parity_t parity; ///< Parity configuration. 105 nrf_uarte_baudrate_t baudrate; ///< Baudrate. 106 uint8_t interrupt_priority; ///< Interrupt priority. 107 } nrfx_uarte_config_t; 108 109 /** 110 * @brief UARTE default configuration. 111 */ 112 #define NRFX_UARTE_DEFAULT_CONFIG \ 113 { \ 114 .pseltxd = NRF_UARTE_PSEL_DISCONNECTED, \ 115 .pselrxd = NRF_UARTE_PSEL_DISCONNECTED, \ 116 .pselcts = NRF_UARTE_PSEL_DISCONNECTED, \ 117 .pselrts = NRF_UARTE_PSEL_DISCONNECTED, \ 118 .p_context = NULL, \ 119 .hwfc = (nrf_uarte_hwfc_t)NRFX_UARTE_DEFAULT_CONFIG_HWFC, \ 120 .parity = (nrf_uarte_parity_t)NRFX_UARTE_DEFAULT_CONFIG_PARITY, \ 121 .baudrate = (nrf_uarte_baudrate_t)NRFX_UARTE_DEFAULT_CONFIG_BAUDRATE, \ 122 .interrupt_priority = NRFX_UARTE_DEFAULT_CONFIG_IRQ_PRIORITY, \ 123 } 124 125 /** 126 * @brief Structure for UARTE transfer completion event. 127 */ 128 typedef struct 129 { 130 uint8_t * p_data; ///< Pointer to memory used for transfer. 131 size_t bytes; ///< Number of bytes transfered. 132 } nrfx_uarte_xfer_evt_t; 133 134 /** 135 * @brief Structure for UARTE error event. 136 */ 137 typedef struct 138 { 139 nrfx_uarte_xfer_evt_t rxtx; ///< Transfer details includes number of bytes transferred. 140 uint32_t error_mask; ///< Mask of error flags that generated the event. 141 } nrfx_uarte_error_evt_t; 142 143 /** 144 * @brief Structure for UARTE event. 145 */ 146 typedef struct 147 { 148 nrfx_uarte_evt_type_t type; ///< Event type. 149 union 150 { 151 nrfx_uarte_xfer_evt_t rxtx; ///< Data provided for transfer completion events. 152 nrfx_uarte_error_evt_t error; ///< Data provided for error event. 153 } data; 154 } nrfx_uarte_event_t; 155 156 /** 157 * @brief UARTE interrupt event handler. 158 * 159 * @param[in] p_event Pointer to event structure. Event is allocated on the stack so it is available 160 * only within the context of the event handler. 161 * @param[in] p_context Context passed to interrupt handler, set on initialization. 162 */ 163 typedef void (*nrfx_uarte_event_handler_t)(nrfx_uarte_event_t const * p_event, 164 void * p_context); 165 166 /** 167 * @brief Function for initializing the UARTE driver. 168 * 169 * This function configures and enables UARTE. After this function GPIO pins are controlled by UARTE. 170 * 171 * @param[in] p_instance Pointer to the driver instance structure. 172 * @param[in] p_config Pointer to the structure with initial configuration. 173 * @param[in] event_handler Event handler provided by the user. If not provided driver works in 174 * blocking mode. 175 * 176 * @retval NRFX_SUCCESS If initialization was successful. 177 * @retval NRFX_ERROR_INVALID_STATE If driver is already initialized. 178 * @retval NRFX_ERROR_BUSY If some other peripheral with the same 179 * instance ID is already in use. This is 180 * possible only if @ref nrfx_prs module 181 * is enabled. 182 */ 183 nrfx_err_t nrfx_uarte_init(nrfx_uarte_t const * p_instance, 184 nrfx_uarte_config_t const * p_config, 185 nrfx_uarte_event_handler_t event_handler); 186 187 /** 188 * @brief Function for uninitializing the UARTE driver. 189 * @param[in] p_instance Pointer to the driver instance structure. 190 */ 191 void nrfx_uarte_uninit(nrfx_uarte_t const * p_instance); 192 193 /** 194 * @brief Function for getting the address of a specific UARTE task. 195 * 196 * @param[in] p_instance Pointer to the driver instance structure. 197 * @param[in] task Task. 198 * 199 * @return Task address. 200 */ 201 __STATIC_INLINE uint32_t nrfx_uarte_task_address_get(nrfx_uarte_t const * p_instance, 202 nrf_uarte_task_t task); 203 204 /** 205 * @brief Function for getting the address of a specific UARTE event. 206 * 207 * @param[in] p_instance Pointer to the driver instance structure. 208 * @param[in] event Event. 209 * 210 * @return Event address. 211 */ 212 __STATIC_INLINE uint32_t nrfx_uarte_event_address_get(nrfx_uarte_t const * p_instance, 213 nrf_uarte_event_t event); 214 215 /** 216 * @brief Function for sending data over UARTE. 217 * 218 * If an event handler was provided in nrfx_uarte_init() call, this function 219 * returns immediately and the handler is called when the transfer is done. 220 * Otherwise, the transfer is performed in blocking mode, i.e. this function 221 * returns when the transfer is finished. Blocking mode is not using interrupt 222 * so there is no context switching inside the function. 223 * 224 * @note Peripherals using EasyDMA (including UARTE) require the transfer buffers 225 * to be placed in the Data RAM region. If this condition is not met, 226 * this function will fail with the error code NRFX_ERROR_INVALID_ADDR. 227 * 228 * @param[in] p_instance Pointer to the driver instance structure. 229 * @param[in] p_data Pointer to data. 230 * @param[in] length Number of bytes to send. Maximum possible length is 231 * dependent on the used SoC (see the MAXCNT register 232 * description in the Product Specification). The driver 233 * checks it with assertion. 234 * 235 * @retval NRFX_SUCCESS If initialization was successful. 236 * @retval NRFX_ERROR_BUSY If driver is already transferring. 237 * @retval NRFX_ERROR_FORBIDDEN If the transfer was aborted from a different context 238 * (blocking mode only). 239 * @retval NRFX_ERROR_INVALID_ADDR If p_data does not point to RAM buffer. 240 */ 241 nrfx_err_t nrfx_uarte_tx(nrfx_uarte_t const * p_instance, 242 uint8_t const * p_data, 243 size_t length); 244 245 /** 246 * @brief Function for checking if UARTE is currently transmitting. 247 * 248 * @param[in] p_instance Pointer to the driver instance structure. 249 * 250 * @retval true If UARTE is transmitting. 251 * @retval false If UARTE is not transmitting. 252 */ 253 bool nrfx_uarte_tx_in_progress(nrfx_uarte_t const * p_instance); 254 255 /** 256 * @brief Function for aborting any ongoing transmission. 257 * @note @ref NRFX_UARTE_EVT_TX_DONE event will be generated in non-blocking mode. 258 * It will contain number of bytes sent until abort was called. The event 259 * handler will be called from UARTE interrupt context. 260 * 261 * @param[in] p_instance Pointer to the driver instance structure. 262 */ 263 void nrfx_uarte_tx_abort(nrfx_uarte_t const * p_instance); 264 265 /** 266 * @brief Function for receiving data over UARTE. 267 * 268 * If an event handler was provided in the nrfx_uarte_init() call, this function 269 * returns immediately and the handler is called when the transfer is done. 270 * Otherwise, the transfer is performed in blocking mode, i.e. this function 271 * returns when the transfer is finished. Blocking mode is not using interrupt so 272 * there is no context switching inside the function. 273 * The receive buffer pointer is double buffered in non-blocking mode. The secondary 274 * buffer can be set immediately after starting the transfer and will be filled 275 * when the primary buffer is full. The double buffering feature allows 276 * receiving data continuously. 277 * 278 * @note Peripherals using EasyDMA (including UARTE) require the transfer buffers 279 * to be placed in the Data RAM region. If this condition is not met, 280 * this function will fail with the error code NRFX_ERROR_INVALID_ADDR. 281 * 282 * @param[in] p_instance Pointer to the driver instance structure. 283 * @param[in] p_data Pointer to data. 284 * @param[in] length Number of bytes to receive. Maximum possible length is 285 * dependent on the used SoC (see the MAXCNT register 286 * description in the Product Specification). The driver 287 * checks it with assertion. 288 * 289 * @retval NRFX_SUCCESS If initialization was successful. 290 * @retval NRFX_ERROR_BUSY If the driver is already receiving 291 * (and the secondary buffer has already been set 292 * in non-blocking mode). 293 * @retval NRFX_ERROR_FORBIDDEN If the transfer was aborted from a different context 294 * (blocking mode only). 295 * @retval NRFX_ERROR_INTERNAL If UARTE peripheral reported an error. 296 * @retval NRFX_ERROR_INVALID_ADDR If p_data does not point to RAM buffer. 297 */ 298 nrfx_err_t nrfx_uarte_rx(nrfx_uarte_t const * p_instance, 299 uint8_t * p_data, 300 size_t length); 301 302 303 304 /** 305 * @brief Function for testing the receiver state in blocking mode. 306 * 307 * @param[in] p_instance Pointer to the driver instance structure. 308 * 309 * @retval true If the receiver has at least one byte of data to get. 310 * @retval false If the receiver is empty. 311 */ 312 bool nrfx_uarte_rx_ready(nrfx_uarte_t const * p_instance); 313 314 /** 315 * @brief Function for aborting any ongoing reception. 316 * @note @ref NRFX_UARTE_EVT_RX_DONE event will be generated in non-blocking mode. 317 * It will contain number of bytes received until abort was called. The event 318 * handler will be called from UARTE interrupt context. 319 * 320 * @param[in] p_instance Pointer to the driver instance structure. 321 */ 322 void nrfx_uarte_rx_abort(nrfx_uarte_t const * p_instance); 323 324 /** 325 * @brief Function for reading error source mask. Mask contains values from @ref nrf_uarte_error_mask_t. 326 * @note Function should be used in blocking mode only. In case of non-blocking mode, an error event is 327 * generated. Function clears error sources after reading. 328 * 329 * @param[in] p_instance Pointer to the driver instance structure. 330 * 331 * @retval Mask of reported errors. 332 */ 333 uint32_t nrfx_uarte_errorsrc_get(nrfx_uarte_t const * p_instance); 334 335 336 #ifndef SUPPRESS_INLINE_IMPLEMENTATION 337 __STATIC_INLINE uint32_t nrfx_uarte_task_address_get(nrfx_uarte_t const * p_instance, 338 nrf_uarte_task_t task) 339 { 340 return nrf_uarte_task_address_get(p_instance->p_reg, task); 341 } 342 343 __STATIC_INLINE uint32_t nrfx_uarte_event_address_get(nrfx_uarte_t const * p_instance, 344 nrf_uarte_event_t event) 345 { 346 return nrf_uarte_event_address_get(p_instance->p_reg, event); 347 } 348 #endif // SUPPRESS_INLINE_IMPLEMENTATION 349 350 351 void nrfx_uarte_0_irq_handler(void); 352 void nrfx_uarte_1_irq_handler(void); 353 void nrfx_uarte_2_irq_handler(void); 354 void nrfx_uarte_3_irq_handler(void); 355 356 /** @} */ 357 358 #ifdef __cplusplus 359 } 360 #endif 361 362 #endif // NRFX_UARTE_H__ 363