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_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 /** @brief Structure for the UARTE driver instance. */
50 typedef struct
51 {
52 NRF_UARTE_Type * p_reg; ///< Pointer to a structure with UARTE registers.
53 uint8_t drv_inst_idx; ///< Index of the driver instance. For internal use only.
54 } nrfx_uarte_t;
55
56 #ifndef __NRFX_DOXYGEN__
57 enum {
58 #if NRFX_CHECK(NRFX_UARTE0_ENABLED)
59 NRFX_UARTE0_INST_IDX,
60 #endif
61 #if NRFX_CHECK(NRFX_UARTE1_ENABLED)
62 NRFX_UARTE1_INST_IDX,
63 #endif
64 #if NRFX_CHECK(NRFX_UARTE2_ENABLED)
65 NRFX_UARTE2_INST_IDX,
66 #endif
67 #if NRFX_CHECK(NRFX_UARTE3_ENABLED)
68 NRFX_UARTE3_INST_IDX,
69 #endif
70 NRFX_UARTE_ENABLED_COUNT
71 };
72 #endif
73
74 /** @brief Macro for creating a UARTE driver instance. */
75 #define NRFX_UARTE_INSTANCE(id) \
76 { \
77 .p_reg = NRFX_CONCAT_2(NRF_UARTE, id), \
78 .drv_inst_idx = NRFX_CONCAT_3(NRFX_UARTE, id, _INST_IDX), \
79 }
80
81 /** @brief Types of UARTE driver events. */
82 typedef enum
83 {
84 NRFX_UARTE_EVT_TX_DONE, ///< Requested TX transfer completed.
85 NRFX_UARTE_EVT_RX_DONE, ///< Requested RX transfer completed.
86 NRFX_UARTE_EVT_ERROR, ///< Error reported by UART peripheral.
87 } nrfx_uarte_evt_type_t;
88
89 /** @brief Structure for the UARTE configuration. */
90 typedef struct
91 {
92 uint32_t pseltxd; ///< TXD pin number.
93 uint32_t pselrxd; ///< RXD pin number.
94 uint32_t pselcts; ///< CTS pin number.
95 uint32_t pselrts; ///< RTS pin number.
96 void * p_context; ///< Context passed to interrupt handler.
97 nrf_uarte_baudrate_t baudrate; ///< Baud rate.
98 uint8_t interrupt_priority; ///< Interrupt priority.
99 nrf_uarte_config_t hal_cfg; ///< Parity, flow control and stop bits settings.
100 } nrfx_uarte_config_t;
101
102 #if defined(UARTE_CONFIG_STOP_Msk) || defined(__NRFX_DOXYGEN__)
103 /** @brief UARTE additional stop bits configuration. */
104 #define NRFX_UARTE_DEFAULT_EXTENDED_STOP_CONFIG \
105 .stop = (nrf_uarte_stop_t)NRF_UARTE_STOP_ONE,
106 #else
107 #define NRFX_UARTE_DEFAULT_EXTENDED_STOP_CONFIG
108 #endif
109
110 #if defined(UARTE_CONFIG_PARITYTYPE_Msk) || defined(__NRFX_DOXYGEN__)
111 /** @brief UARTE additional parity type configuration. */
112 #define NRFX_UARTE_DEFAULT_EXTENDED_PARITYTYPE_CONFIG \
113 .paritytype = NRF_UARTE_PARITYTYPE_EVEN,
114 #else
115 #define NRFX_UARTE_DEFAULT_EXTENDED_PARITYTYPE_CONFIG
116 #endif
117
118 /**
119 * @brief UARTE driver default configuration.
120 *
121 * This configuration sets up UARTE with the following options:
122 * - hardware flow control disabled
123 * - no parity bit
124 * - one stop bit
125 * - baudrate: 115200
126 *
127 * @param[in] _pin_tx TX pin.
128 * @param[in] _pin_rx RX pin.
129 */
130 #define NRFX_UARTE_DEFAULT_CONFIG(_pin_tx, _pin_rx) \
131 { \
132 .pseltxd = _pin_tx, \
133 .pselrxd = _pin_rx, \
134 .pselcts = NRF_UARTE_PSEL_DISCONNECTED, \
135 .pselrts = NRF_UARTE_PSEL_DISCONNECTED, \
136 .p_context = NULL, \
137 .baudrate = NRF_UARTE_BAUDRATE_115200, \
138 .interrupt_priority = NRFX_UARTE_DEFAULT_CONFIG_IRQ_PRIORITY, \
139 .hal_cfg = { \
140 .hwfc = NRF_UARTE_HWFC_DISABLED, \
141 .parity = NRF_UARTE_PARITY_EXCLUDED, \
142 NRFX_UARTE_DEFAULT_EXTENDED_STOP_CONFIG \
143 NRFX_UARTE_DEFAULT_EXTENDED_PARITYTYPE_CONFIG \
144 } \
145 }
146
147 /** @brief Structure for the UARTE transfer completion event. */
148 typedef struct
149 {
150 uint8_t * p_data; ///< Pointer to memory used for transfer.
151 size_t bytes; ///< Number of bytes transfered.
152 } nrfx_uarte_xfer_evt_t;
153
154 /** @brief Structure for UARTE error event. */
155 typedef struct
156 {
157 nrfx_uarte_xfer_evt_t rxtx; ///< Transfer details, including number of bytes transferred.
158 uint32_t error_mask; ///< Mask of error flags that generated the event.
159 } nrfx_uarte_error_evt_t;
160
161 /** @brief Structure for UARTE event. */
162 typedef struct
163 {
164 nrfx_uarte_evt_type_t type; ///< Event type.
165 union
166 {
167 nrfx_uarte_xfer_evt_t rxtx; ///< Data provided for transfer completion events.
168 nrfx_uarte_error_evt_t error; ///< Data provided for error event.
169 } data; ///< Union to store event data.
170 } nrfx_uarte_event_t;
171
172 /**
173 * @brief UARTE interrupt event handler.
174 *
175 * @param[in] p_event Pointer to event structure. Event is allocated on the stack so it is available
176 * only within the context of the event handler.
177 * @param[in] p_context Context passed to the interrupt handler, set on initialization.
178 */
179 typedef void (*nrfx_uarte_event_handler_t)(nrfx_uarte_event_t const * p_event,
180 void * p_context);
181
182 /**
183 * @brief Function for initializing the UARTE driver.
184 *
185 * This function configures and enables UARTE. After this function GPIO pins are controlled by UARTE.
186 *
187 * @param[in] p_instance Pointer to the driver instance structure.
188 * @param[in] p_config Pointer to the structure with the initial configuration.
189 * @param[in] event_handler Event handler provided by the user. If not provided driver works in
190 * blocking mode.
191 *
192 * @retval NRFX_SUCCESS Initialization was successful.
193 * @retval NRFX_ERROR_INVALID_STATE Driver is already initialized.
194 * @retval NRFX_ERROR_BUSY Some other peripheral with the same
195 * instance ID is already in use. This is
196 * possible only if @ref nrfx_prs module
197 * is enabled.
198 */
199 nrfx_err_t nrfx_uarte_init(nrfx_uarte_t const * p_instance,
200 nrfx_uarte_config_t const * p_config,
201 nrfx_uarte_event_handler_t event_handler);
202
203 /**
204 * @brief Function for uninitializing the UARTE driver.
205 *
206 * @param[in] p_instance Pointer to the driver instance structure.
207 */
208 void nrfx_uarte_uninit(nrfx_uarte_t const * p_instance);
209
210 /**
211 * @brief Function for getting the address of the specified UARTE task.
212 *
213 * @param[in] p_instance Pointer to the driver instance structure.
214 * @param[in] task Task.
215 *
216 * @return Task address.
217 */
218 NRFX_STATIC_INLINE uint32_t nrfx_uarte_task_address_get(nrfx_uarte_t const * p_instance,
219 nrf_uarte_task_t task);
220
221 /**
222 * @brief Function for getting the address of the specified UARTE event.
223 *
224 * @param[in] p_instance Pointer to the driver instance structure.
225 * @param[in] event Event.
226 *
227 * @return Event address.
228 */
229 NRFX_STATIC_INLINE uint32_t nrfx_uarte_event_address_get(nrfx_uarte_t const * p_instance,
230 nrf_uarte_event_t event);
231
232 /**
233 * @brief Function for sending data over UARTE.
234 *
235 * If an event handler is provided in nrfx_uarte_init() call, this function
236 * returns immediately and the handler is called when the transfer is done.
237 * Otherwise, the transfer is performed in blocking mode, that is this function
238 * returns when the transfer is finished. Blocking mode is not using interrupt
239 * so there is no context switching inside the function.
240 *
241 * @note Peripherals using EasyDMA (including UARTE) require the transfer buffers
242 * to be placed in the Data RAM region. If this condition is not met,
243 * this function will fail with the error code NRFX_ERROR_INVALID_ADDR.
244 *
245 * @param[in] p_instance Pointer to the driver instance structure.
246 * @param[in] p_data Pointer to data.
247 * @param[in] length Number of bytes to send. Maximum possible length is
248 * dependent on the used SoC (see the MAXCNT register
249 * description in the Product Specification). The driver
250 * checks it with assertion.
251 *
252 * @retval NRFX_SUCCESS Initialization was successful.
253 * @retval NRFX_ERROR_BUSY Driver is already transferring.
254 * @retval NRFX_ERROR_FORBIDDEN The transfer was aborted from a different context
255 * (blocking mode only).
256 * @retval NRFX_ERROR_INVALID_ADDR p_data does not point to RAM buffer.
257 */
258 nrfx_err_t nrfx_uarte_tx(nrfx_uarte_t const * p_instance,
259 uint8_t const * p_data,
260 size_t length);
261
262 /**
263 * @brief Function for checking if UARTE is currently transmitting.
264 *
265 * @param[in] p_instance Pointer to the driver instance structure.
266 *
267 * @retval true The UARTE is transmitting.
268 * @retval false The UARTE is not transmitting.
269 */
270 bool nrfx_uarte_tx_in_progress(nrfx_uarte_t const * p_instance);
271
272 /**
273 * @brief Function for aborting any ongoing transmission.
274 * @note @ref NRFX_UARTE_EVT_TX_DONE event will be generated in non-blocking mode.
275 * It will contain number of bytes sent until the abort was called. The event
276 * handler will be called from the UARTE interrupt context.
277 *
278 * @param[in] p_instance Pointer to the driver instance structure.
279 */
280 void nrfx_uarte_tx_abort(nrfx_uarte_t const * p_instance);
281
282 /**
283 * @brief Function for receiving data over UARTE.
284 *
285 * If an event handler is provided in the nrfx_uarte_init() call, this function
286 * returns immediately and the handler is called when the transfer is done.
287 * Otherwise, the transfer is performed in blocking mode, that is this function
288 * returns when the transfer is finished. Blocking mode is not using interrupt so
289 * there is no context switching inside the function.
290 * The receive buffer pointer is double-buffered in non-blocking mode. The secondary
291 * buffer can be set immediately after starting the transfer and will be filled
292 * when the primary buffer is full. The double-buffering feature allows
293 * receiving data continuously.
294 *
295 * @note Peripherals using EasyDMA (including UARTE) require the transfer buffers
296 * to be placed in the Data RAM region. If this condition is not met,
297 * this function fails with the error code NRFX_ERROR_INVALID_ADDR.
298 *
299 * @warning When the double-buffering feature is used and the UARTE interrupt
300 * is processed with a delay (for example, due to a higher priority interrupt)
301 * long enough for both buffers to get filled completely,
302 * the event handler will be invoked only once, to notify that
303 * the first buffer has been filled. This is because from hardware perspective it
304 * is impossible to deduce in such case if the second buffer was also filled completely or not.
305 * To prevent this from happening, keep the UARTE interrupt latency low
306 * or use large enough reception buffers.
307 *
308 * @param[in] p_instance Pointer to the driver instance structure.
309 * @param[in] p_data Pointer to data.
310 * @param[in] length Number of bytes to receive. Maximum possible length is
311 * dependent on the used SoC (see the MAXCNT register
312 * description in the Product Specification). The driver
313 * checks it with assertion.
314 *
315 * @retval NRFX_SUCCESS Initialization is successful.
316 * @retval NRFX_ERROR_BUSY The driver is already receiving
317 * (and the secondary buffer has already been set
318 * in non-blocking mode).
319 * @retval NRFX_ERROR_FORBIDDEN The transfer is aborted from a different context
320 * (blocking mode only).
321 * @retval NRFX_ERROR_INTERNAL The UARTE peripheral reports an error.
322 * @retval NRFX_ERROR_INVALID_ADDR p_data does not point to RAM buffer.
323 */
324 nrfx_err_t nrfx_uarte_rx(nrfx_uarte_t const * p_instance,
325 uint8_t * p_data,
326 size_t length);
327
328
329
330 /**
331 * @brief Function for testing the receiver state in blocking mode.
332 *
333 * @param[in] p_instance Pointer to the driver instance structure.
334 *
335 * @retval true The receiver has at least one byte of data to get.
336 * @retval false The receiver is empty.
337 */
338 bool nrfx_uarte_rx_ready(nrfx_uarte_t const * p_instance);
339
340 /**
341 * @brief Function for aborting any ongoing reception.
342 * @note @ref NRFX_UARTE_EVT_RX_DONE event will be generated in non-blocking mode.
343 * It will contain number of bytes received until the abort was called. The event
344 * handler will be called from the UARTE interrupt context.
345 *
346 * @warning When the double-buffering feature is used and the UARTE interrupt
347 * is processed with a delay (for example, due to a higher priority
348 * interrupt) long enough for the first buffer to be filled completely,
349 * the event handler will be supplied with the pointer to the first
350 * buffer and the number of bytes received in the second buffer.
351 * This is because from hardware perspective it is impossible to deduce
352 * the reception of which buffer has been aborted.
353 * To prevent this from happening, keep the UARTE interrupt latency low
354 * or use large enough reception buffers.
355 *
356 * @param[in] p_instance Pointer to the driver instance structure.
357 */
358 void nrfx_uarte_rx_abort(nrfx_uarte_t const * p_instance);
359
360 /**
361 * @brief Function for reading error source mask. Mask contains values from @ref nrf_uarte_error_mask_t.
362 * @note Function must be used in the blocking mode only. In case of non-blocking mode, an error event is
363 * generated. Function clears error sources after reading.
364 *
365 * @param[in] p_instance Pointer to the driver instance structure.
366 *
367 * @return Mask of reported errors.
368 */
369 uint32_t nrfx_uarte_errorsrc_get(nrfx_uarte_t const * p_instance);
370
371
372 #ifndef NRFX_DECLARE_ONLY
nrfx_uarte_task_address_get(nrfx_uarte_t const * p_instance,nrf_uarte_task_t task)373 NRFX_STATIC_INLINE uint32_t nrfx_uarte_task_address_get(nrfx_uarte_t const * p_instance,
374 nrf_uarte_task_t task)
375 {
376 return nrf_uarte_task_address_get(p_instance->p_reg, task);
377 }
378
nrfx_uarte_event_address_get(nrfx_uarte_t const * p_instance,nrf_uarte_event_t event)379 NRFX_STATIC_INLINE uint32_t nrfx_uarte_event_address_get(nrfx_uarte_t const * p_instance,
380 nrf_uarte_event_t event)
381 {
382 return nrf_uarte_event_address_get(p_instance->p_reg, event);
383 }
384 #endif // NRFX_DECLARE_ONLY
385
386 /** @} */
387
388
389 void nrfx_uarte_0_irq_handler(void);
390 void nrfx_uarte_1_irq_handler(void);
391 void nrfx_uarte_2_irq_handler(void);
392 void nrfx_uarte_3_irq_handler(void);
393
394
395 #ifdef __cplusplus
396 }
397 #endif
398
399 #endif // NRFX_UARTE_H__
400