1 /*
2 * Copyright (c) 2015 - 2020, 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_UART_H__
33 #define NRFX_UART_H__
34
35 #include <nrfx.h>
36 #include <hal/nrf_uart.h>
37
38 #ifdef __cplusplus
39 extern "C" {
40 #endif
41
42 /**
43 * @defgroup nrfx_uart UART driver
44 * @{
45 * @ingroup nrf_uart
46 * @brief UART peripheral driver.
47 */
48
49 /** @brief Data structure of the UART driver instance. */
50 typedef struct
51 {
52 NRF_UART_Type * p_reg; ///< Pointer to a structure with UART registers.
53 uint8_t drv_inst_idx; ///< Index of the driver instance. For internal use only.
54 } nrfx_uart_t;
55
56 #ifndef __NRFX_DOXYGEN__
57 enum {
58 #if NRFX_CHECK(NRFX_UART0_ENABLED)
59 NRFX_UART0_INST_IDX,
60 #endif
61 NRFX_UART_ENABLED_COUNT
62 };
63 #endif
64
65 /** @brief Macro for creating a UART driver instance. */
66 #define NRFX_UART_INSTANCE(id) \
67 { \
68 .p_reg = NRFX_CONCAT_2(NRF_UART, id), \
69 .drv_inst_idx = NRFX_CONCAT_3(NRFX_UART, id, _INST_IDX), \
70 }
71
72 /** @brief Types of UART driver events. */
73 typedef enum
74 {
75 NRFX_UART_EVT_TX_DONE, ///< Requested TX transfer completed.
76 NRFX_UART_EVT_RX_DONE, ///< Requested RX transfer completed.
77 NRFX_UART_EVT_ERROR, ///< Error reported by UART peripheral.
78 } nrfx_uart_evt_type_t;
79
80 /** @brief Structure for the UART configuration. */
81 typedef struct
82 {
83 uint32_t pseltxd; ///< TXD pin number.
84 uint32_t pselrxd; ///< RXD pin number.
85 uint32_t pselcts; ///< CTS pin number.
86 uint32_t pselrts; ///< RTS pin number.
87 void * p_context; ///< Context passed to interrupt handler.
88 nrf_uart_baudrate_t baudrate; ///< Baud rate.
89 uint8_t interrupt_priority; ///< Interrupt priority.
90 nrf_uart_config_t hal_cfg; ///< Parity, flow control and stop bits settings.
91 } nrfx_uart_config_t;
92
93 #if defined(UART_CONFIG_STOP_Msk) || defined(__NRFX_DOXYGEN__)
94 /** @brief UART additional stop bits configuration. */
95 #define NRFX_UART_DEFAULT_EXTENDED_STOP_CONFIG \
96 .stop = NRF_UART_STOP_ONE,
97 #else
98 #define NRFX_UART_DEFAULT_EXTENDED_STOP_CONFIG
99 #endif
100
101 #if defined(UART_CONFIG_PARITYTYPE_Msk) || defined(__NRFX_DOXYGEN__)
102 /** @brief UART additional parity type configuration. */
103 #define NRFX_UART_DEFAULT_EXTENDED_PARITYTYPE_CONFIG \
104 .paritytype = NRF_UART_PARITYTYPE_EVEN,
105 #else
106 #define NRFX_UART_DEFAULT_EXTENDED_PARITYTYPE_CONFIG
107 #endif
108
109 /**
110 * @brief UART driver default configuration.
111 *
112 * This configuration sets up UART with the following options:
113 * - hardware flow control disabled
114 * - no parity bit
115 * - one stop bit
116 * - baudrate: 115200
117 *
118 * @param[in] _pin_tx TX pin.
119 * @param[in] _pin_rx RX pin.
120 */
121 #define NRFX_UART_DEFAULT_CONFIG(_pin_tx, _pin_rx) \
122 { \
123 .pseltxd = _pin_tx, \
124 .pselrxd = _pin_rx, \
125 .pselcts = NRF_UART_PSEL_DISCONNECTED, \
126 .pselrts = NRF_UART_PSEL_DISCONNECTED, \
127 .p_context = NULL, \
128 .baudrate = NRF_UART_BAUDRATE_115200, \
129 .interrupt_priority = NRFX_UART_DEFAULT_CONFIG_IRQ_PRIORITY, \
130 .hal_cfg = { \
131 .hwfc = NRF_UART_HWFC_DISABLED, \
132 .parity = NRF_UART_PARITY_EXCLUDED, \
133 NRFX_UART_DEFAULT_EXTENDED_STOP_CONFIG \
134 NRFX_UART_DEFAULT_EXTENDED_PARITYTYPE_CONFIG \
135 } \
136 }
137
138 /** @brief Structure for the UART transfer completion event. */
139 typedef struct
140 {
141 uint8_t * p_data; ///< Pointer to memory used for transfer.
142 uint32_t bytes; ///< Number of bytes transfered.
143 } nrfx_uart_xfer_evt_t;
144
145 /** @brief Structure for the UART error event. */
146 typedef struct
147 {
148 nrfx_uart_xfer_evt_t rxtx; ///< Transfer details, including number of bytes transferred.
149 uint32_t error_mask; ///< Mask of error flags that generated the event.
150 } nrfx_uart_error_evt_t;
151
152 /** @brief Structure for the UART event. */
153 typedef struct
154 {
155 nrfx_uart_evt_type_t type; ///< Event type.
156 union
157 {
158 nrfx_uart_xfer_evt_t rxtx; ///< Data provided for transfer completion events.
159 nrfx_uart_error_evt_t error; ///< Data provided for error event.
160 } data; ///< Union to store event data.
161 } nrfx_uart_event_t;
162
163 /**
164 * @brief UART interrupt event handler.
165 *
166 * @param[in] p_event Pointer to event structure. Event is allocated on the stack so it is available
167 * only within the context of the event handler.
168 * @param[in] p_context Context passed to the interrupt handler, set on initialization.
169 */
170 typedef void (*nrfx_uart_event_handler_t)(nrfx_uart_event_t const * p_event,
171 void * p_context);
172
173 /**
174 * @brief Function for initializing the UART driver.
175 *
176 * This function configures and enables UART. After this function GPIO pins are controlled by UART.
177 *
178 * @param[in] p_instance Pointer to the driver instance structure.
179 * @param[in] p_config Pointer to the structure with the initial configuration.
180 * @param[in] event_handler Event handler provided by the user. If not provided, the driver works in
181 * blocking mode.
182 *
183 * @retval NRFX_SUCCESS Initialization is successful.
184 * @retval NRFX_ERROR_INVALID_STATE The driver is already initialized.
185 * @retval NRFX_ERROR_BUSY Some other peripheral with the same
186 * instance ID is already in use. This is
187 * possible only if @ref nrfx_prs module
188 * is enabled.
189 */
190 nrfx_err_t nrfx_uart_init(nrfx_uart_t const * p_instance,
191 nrfx_uart_config_t const * p_config,
192 nrfx_uart_event_handler_t event_handler);
193
194 /**
195 * @brief Function for uninitializing the UART driver.
196 *
197 * @param[in] p_instance Pointer to the driver instance structure.
198 */
199 void nrfx_uart_uninit(nrfx_uart_t const * p_instance);
200
201 /**
202 * @brief Function for getting the address of the specified UART task.
203 *
204 * @param[in] p_instance Pointer to the driver instance structure.
205 * @param[in] task Task.
206 *
207 * @return Task address.
208 */
209 NRFX_STATIC_INLINE uint32_t nrfx_uart_task_address_get(nrfx_uart_t const * p_instance,
210 nrf_uart_task_t task);
211
212 /**
213 * @brief Function for getting the address of the specified UART event.
214 *
215 * @param[in] p_instance Pointer to the driver instance structure.
216 * @param[in] event Event.
217 *
218 * @return Event address.
219 */
220 NRFX_STATIC_INLINE uint32_t nrfx_uart_event_address_get(nrfx_uart_t const * p_instance,
221 nrf_uart_event_t event);
222
223 /**
224 * @brief Function for sending data over UART.
225 *
226 * If an event handler was provided in nrfx_uart_init() call, this function
227 * returns immediately and the handler is called when the transfer is done.
228 * Otherwise, the transfer is performed in blocking mode, that is this function
229 * returns when the transfer is finished. Blocking mode is not using interrupt
230 * so there is no context switching inside the function.
231 *
232 * @param[in] p_instance Pointer to the driver instance structure.
233 * @param[in] p_data Pointer to data.
234 * @param[in] length Number of bytes to send.
235 *
236 * @retval NRFX_SUCCESS Initialization was successful.
237 * @retval NRFX_ERROR_BUSY Driver is already transferring.
238 * @retval NRFX_ERROR_FORBIDDEN The transfer was aborted from a different context
239 * (blocking mode only).
240 */
241 nrfx_err_t nrfx_uart_tx(nrfx_uart_t const * p_instance,
242 uint8_t const * p_data,
243 size_t length);
244
245 /**
246 * @brief Function for checking if UART is currently transmitting.
247 *
248 * @param[in] p_instance Pointer to the driver instance structure.
249 *
250 * @retval true The UART is transmitting.
251 * @retval false The UART is not transmitting.
252 */
253 bool nrfx_uart_tx_in_progress(nrfx_uart_t const * p_instance);
254
255 /**
256 * @brief Function for aborting any ongoing transmission.
257 * @note @ref NRFX_UART_EVT_TX_DONE event will be generated in non-blocking mode.
258 * It will contain number of bytes sent until the abort was called. The event
259 * handler will be called from the function context.
260 *
261 * @param[in] p_instance Pointer to the driver instance structure.
262 */
263 void nrfx_uart_tx_abort(nrfx_uart_t const * p_instance);
264
265 /**
266 * @brief Function for receiving data over UART.
267 *
268 * If an event handler is provided in the nrfx_uart_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, that is 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 * If this function is used without a previous call to @ref nrfx_uart_rx_enable, the reception
279 * will be stopped on error or when the supplied buffer fills up. In both cases,
280 * RX FIFO gets disabled. This means that, in case of error, the bytes that follow are lost.
281 * If this nrfx_uart_rx() function is used with the previous call to @ref nrfx_uart_rx_enable,
282 * the reception is stopped in case of error, but FIFO is still ongoing. The receiver is still
283 * working, so after handling the error, an immediate repeated call to this nrfx_uart_rx()
284 * function with fresh data buffer will re-establish reception. To disable the receiver,
285 * you must call @ref nrfx_uart_rx_disable explicitly.
286 *
287 * @param[in] p_instance Pointer to the driver instance structure.
288 * @param[in] p_data Pointer to data.
289 * @param[in] length Number of bytes to receive.
290 *
291 * @retval NRFX_SUCCESS Reception is complete (in case of blocking mode) or it is
292 * successfully started (in case of non-blocking mode).
293 * @retval NRFX_ERROR_BUSY The driver is already receiving
294 * (and the secondary buffer has already been set
295 * in non-blocking mode).
296 * @retval NRFX_ERROR_FORBIDDEN The transfer was aborted from a different context
297 * (blocking mode only, also see @ref nrfx_uart_rx_disable).
298 * @retval NRFX_ERROR_INTERNAL The UART peripheral reported an error.
299 */
300 nrfx_err_t nrfx_uart_rx(nrfx_uart_t const * p_instance,
301 uint8_t * p_data,
302 size_t length);
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 The receiver has at least one byte of data to get.
310 * @retval false The receiver is empty.
311 */
312 bool nrfx_uart_rx_ready(nrfx_uart_t const * p_instance);
313
314 /**
315 * @brief Function for enabling the receiver.
316 *
317 * UART has a 6-byte-long RX FIFO and it is used to store incoming data. If a user does not call the
318 * UART receive function before the FIFO is filled, an overrun error will appear. The receiver must be
319 * explicitly closed by the user @sa nrfx_uart_rx_disable.
320 *
321 * @param[in] p_instance Pointer to the driver instance structure.
322 */
323 void nrfx_uart_rx_enable(nrfx_uart_t const * p_instance);
324
325 /**
326 * @brief Function for disabling the receiver.
327 *
328 * This function must be called to close the receiver after it has been explicitly enabled by
329 * @sa nrfx_uart_rx_enable.
330 *
331 * @param[in] p_instance Pointer to the driver instance structure.
332 */
333 void nrfx_uart_rx_disable(nrfx_uart_t const * p_instance);
334
335 /**
336 * @brief Function for aborting any ongoing reception.
337 * @note @ref NRFX_UART_EVT_TX_DONE event will be generated in non-blocking mode.
338 * It will contain number of bytes received until the abort was called. The event
339 * handler will be called from the UART interrupt context.
340 *
341 * @param[in] p_instance Pointer to the driver instance structure.
342 */
343 void nrfx_uart_rx_abort(nrfx_uart_t const * p_instance);
344
345 /**
346 * @brief Function for reading error source mask. Mask contains values from @ref nrf_uart_error_mask_t.
347 * @note Function must be used in blocking mode only. In case of non-blocking mode, an error event is
348 * generated. Function clears error sources after reading.
349 *
350 * @param[in] p_instance Pointer to the driver instance structure.
351 *
352 * @return Mask of reported errors.
353 */
354 uint32_t nrfx_uart_errorsrc_get(nrfx_uart_t const * p_instance);
355
356
357 #ifndef NRFX_DECLARE_ONLY
nrfx_uart_task_address_get(nrfx_uart_t const * p_instance,nrf_uart_task_t task)358 NRFX_STATIC_INLINE uint32_t nrfx_uart_task_address_get(nrfx_uart_t const * p_instance,
359 nrf_uart_task_t task)
360 {
361 return nrf_uart_task_address_get(p_instance->p_reg, task);
362 }
363
nrfx_uart_event_address_get(nrfx_uart_t const * p_instance,nrf_uart_event_t event)364 NRFX_STATIC_INLINE uint32_t nrfx_uart_event_address_get(nrfx_uart_t const * p_instance,
365 nrf_uart_event_t event)
366 {
367 return nrf_uart_event_address_get(p_instance->p_reg, event);
368 }
369 #endif // NRFX_DECLARE_ONLY
370
371 /** @} */
372
373
374 void nrfx_uart_0_irq_handler(void);
375
376
377 #ifdef __cplusplus
378 }
379 #endif
380
381 #endif // NRFX_UART_H__
382