1 /*
2 * Copyright (c) 2015 - 2025, Nordic Semiconductor ASA
3 * All rights reserved.
4 *
5 * SPDX-License-Identifier: BSD-3-Clause
6 *
7 * Redistribution and use in source and binary forms, with or without
8 * modification, are permitted provided that the following conditions are met:
9 *
10 * 1. Redistributions of source code must retain the above copyright notice, this
11 * list of conditions and the following disclaimer.
12 *
13 * 2. Redistributions in binary form must reproduce the above copyright
14 * notice, this list of conditions and the following disclaimer in the
15 * documentation and/or other materials provided with the distribution.
16 *
17 * 3. Neither the name of the copyright holder nor the names of its
18 * contributors may be used to endorse or promote products derived from this
19 * software without specific prior written permission.
20 *
21 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
22 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
23 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
24 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
25 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
26 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
27 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
28 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
29 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
30 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
31 * POSSIBILITY OF SUCH DAMAGE.
32 */
33
34 #ifndef NRFX_UARTE_H__
35 #define NRFX_UARTE_H__
36
37 #include <nrfx.h>
38 #include <haly/nrfy_uarte.h>
39
40 #ifdef __cplusplus
41 extern "C" {
42 #endif
43
44 /**
45 * @defgroup nrfx_uarte UARTE driver
46 * @{
47 * @ingroup nrf_uarte
48 * @brief UARTE peripheral driver.
49 */
50
51 /** @brief Structure for the UARTE driver instance. */
52 typedef struct
53 {
54 NRF_UARTE_Type * p_reg; ///< Pointer to a structure with UARTE registers.
55 uint8_t drv_inst_idx; ///< Index of the driver instance. For internal use only.
56 } nrfx_uarte_t;
57
58 #ifndef __NRFX_DOXYGEN__
59 enum {
60 /* List all enabled driver instances (in the format NRFX_\<instance_name\>_INST_IDX). */
61 NRFX_INSTANCE_ENUM_LIST(UARTE)
62 NRFX_UARTE_ENABLED_COUNT
63 };
64 #endif
65
66 /** @brief Macro for creating a UARTE driver instance. */
67 #define NRFX_UARTE_INSTANCE(id) \
68 { \
69 .p_reg = NRFX_CONCAT(NRF_, UARTE, id), \
70 .drv_inst_idx = NRFX_CONCAT(NRFX_UARTE, id, _INST_IDX), \
71 }
72
73 /**@defgroup NRFX_UARTE_RX_ENABLE_FLAGS Flags used for @ref nrfx_uarte_rx_enable.
74 * @{ */
75
76 /**
77 * @brief Flag for configuring continuous reception.
78 *
79 * When the flag is set, the ENDRX event is shortened with the STARTRX task.
80 * The flag should not be used together with short buffers in case there is a risk that a new buffer
81 * is not provided on time. If the flag is set and a new buffer is not provided on time,
82 * a receiver starts to overwrite the current buffer. If not set and a new buffer has been provided
83 * on time, a new transfer will be triggered from the ENDRX interrupt handler.
84 * This flag is recommended to be used with longer buffers to ensure lossless reception
85 * without HWFC detection.
86 */
87 #define NRFX_UARTE_RX_ENABLE_CONT NRFX_BIT(0)
88
89 /**
90 * @brief Flag indicating that receiver is stopped when new buffer is not provided.
91 *
92 * Setting a flag changes the behavior of the UARTE driver when receiving to the buffer is
93 * completed and a new buffer is not provided. When the flag is set, stopping is initiated.
94 * Since the stopping takes time, this operation can still be revoked by providing a new buffer
95 * (@ref nrfx_uarte_rx_buffer_set). When the flag is not set, then the receiver is kept enabled, and
96 * incoming data is put in the hardware FIFO (if HWFC is disabled) until FIFO is
97 * full and bytes are dropped.
98 */
99 #define NRFX_UARTE_RX_ENABLE_STOP_ON_END NRFX_BIT(1)
100
101 /**
102 * @brief Flag indicating that FIFO content that was flushed after the last stopping shall be kept.
103 *
104 * When a receiver is stopped, it is possible that there is some data in the hardware FIFO
105 * that was not stored in the user buffer due to the lack of capacity. As a result, that data
106 * is flushed to an internal buffer. If the flag is set, the flushed data is kept and copied into
107 * the user buffer.
108 *
109 * Using the flag makes the user to provide their buffer for flushed data during the initialization.
110 */
111 #define NRFX_UARTE_RX_ENABLE_KEEP_FIFO_CONTENT NRFX_BIT(2)
112
113 /**@} */
114
115 /**@defgroup NRFX_UARTE_TX_FLAGS Flags used for @ref nrfx_uarte_tx.
116 *
117 * Flags apply only if an instance is initialized with a user handler. Otherwise flags are
118 * ignored and all transfers are blocking.
119 *
120 * @{ */
121
122 /**
123 * @brief Flag indicating blocking transfer.
124 *
125 * When the flag is set, the transfer is synchronous even if the driver is configured
126 * to non-blocking operation. If UARTE is transmitting when the user requests blocking transfer,
127 * @ref NRFX_ERROR_BUSY is returned. A driver state is determined by hardware, thus it is
128 * accepted to poll the driver and continuously request blocking transfer until it
129 * is accepted. It can be done from any priority context. Blocking transfer returns
130 * when the buffer is transferred or when the user buffer is no longer in use
131 * (see @ref NRFX_UARTE_TX_EARLY_RETURN).
132 */
133 #define NRFX_UARTE_TX_BLOCKING NRFX_BIT(0)
134
135 /**
136 * @brief Flag indicating to return from blocking transfer not waiting for the last transmit event.
137 *
138 * The flag indicates a blocking transfer just like @ref NRFX_UARTE_TX_BLOCKING.
139 * However, when the flag is set, if the transfer is still ongoing and if the transfer of the last
140 * byte already has started, @ref nrfx_uarte_tx returns instead of waiting for the transfer to end.
141 */
142 #define NRFX_UARTE_TX_EARLY_RETURN NRFX_BIT(1)
143
144 /**
145 * @brief Flag indicating that the @ref nrfx_uarte_tx call will be linked to an active transfer.
146 *
147 * UARTE DMA registers are buffered which means that once transfer is started, registers with
148 * transfer details (pointer and length) can be overwritten. If that is combined with the (D)PPI
149 * connection between ENDTX and STARTTX events, then two transfers are linked together and
150 * bytes are transferred without any gap allowing to utilize the maximum bandwidth.
151 *
152 * When the flag is set, it indicates that the user can set up an ENDTX-STARTTX (D)PPI connection and
153 * wants to perform linked transfers. It is the user's responsibility to disable the (D)PPI connection
154 * when the last transfer is started. If the user does not set up an ENDTX-STARTTX (D)PPI connection, then
155 * the transfer is restarted from the context of ENDTX event handling which is earlier than context
156 * of the @ref NRFX_UARTE_EVT_TX_DONE. The flag has no impact if used while there is no ongoing
157 * transfer.
158 *
159 * For example, if a sequence consists of three transfers, then the first @ref nrfx_uarte_tx
160 * can be called with or without the flag and the following two transfers must have the flag
161 * set. The second @ref nrfx_uarte_tx can be called immediately after the first one and the third
162 * one after the first @ref NRFX_UARTE_EVT_TX_DONE event. After the second
163 * @ref NRFX_UARTE_EVT_TX_DONE event is received, the (D)PPI connection must be disabled (if it was
164 * used).
165 *
166 * When (D)PPI connection is used, then it is critical that (D)PPI connection is disabled on time,
167 * before the last transfer is completed. Otherwise, the transfer will be repeated, and unwanted data
168 * will be transferred. Hence, it is recommended to use longer buffers. Time needed to
169 * send the buffer must be longer than the maximum system latency.
170 *
171 * When the flag is used, then the driver instance must not use the ENDTX-STOPTX (D)PPI connection.
172 *
173 * When linked transfers are used, then blocking transfers (see @ref NRFX_UARTE_TX_BLOCKING and
174 * @ref NRFX_UARTE_TX_EARLY_RETURN) cannot be performed. An error is returned when the flag is set
175 * and the @ref nrfx_uarte_tx is called during ongoing blocking transfer.
176 */
177 #define NRFX_UARTE_TX_LINK NRFX_BIT(2)
178
179 /**@} */
180
181 /**@defgroup NRFX_UARTE_TX_DONE_FLAGS Flags used for @ref nrfx_uarte_tx_evt_t.
182 * @{ */
183
184 /** @brief Flag indicating that TX transfer was aborted. */
185 #define NRFX_UARTE_TX_DONE_ABORTED NRFX_BIT(0)
186
187 /**@} */
188
189 /** @brief Types of UARTE driver events. */
190 typedef enum
191 {
192 NRFX_UARTE_EVT_TX_DONE, ///< Requested TX transfer completed.
193 NRFX_UARTE_EVT_RX_DONE, ///< Requested RX transfer completed.
194 NRFX_UARTE_EVT_ERROR, ///< Error reported by UART peripheral.
195 NRFX_UARTE_EVT_RX_BUF_REQUEST, ///< Request for a RX buffer.
196 NRFX_UARTE_EVT_RX_DISABLED, ///< Receiver is disabled.
197 NRFX_UARTE_EVT_RX_BUF_TOO_LATE, ///< RX buffer request handled too late.
198 NRFX_UARTE_EVT_RX_BYTE, ///< Byte was received.
199 NRFX_UARTE_EVT_TRIGGER, ///< Result of @ref nrfx_uarte_int_trigger.
200 } nrfx_uarte_evt_type_t;
201
202 /** @brief Structure used internally to handle reception through cache buffers. */
203 typedef struct
204 {
205 nrfy_uarte_buffer_t user[2]; ///< User buffers.
206 nrfy_uarte_buffer_t cache[2]; ///< Cache buffers.
207 size_t cache_len; ///< Single cache buffer length.
208 size_t started; ///< Used for tracking progress of the current user buffer.
209 size_t received; ///< Amount of received data in the current user buffer.
210 uint8_t idx; ///< Used for determining which cache buffer to use.
211 bool buf_req; ///< Flag indicate that next user buffer should be requested.
212 } nrfx_uarte_rx_cache_t;
213
214 /** @brief Structure for the UARTE configuration. */
215 typedef struct
216 {
217 uint32_t txd_pin; ///< TXD pin number.
218 uint32_t rxd_pin; ///< RXD pin number.
219 uint32_t rts_pin; ///< RTS pin number.
220 uint32_t cts_pin; ///< CTS pin number.
221 void * p_context; ///< Context passed to interrupt handler.
222 nrfy_uarte_buffer_t tx_cache; ///< TX cache buffer.
223 nrfy_uarte_buffer_t rx_cache; ///< RX cache buffer.
224 /**< A buffer to store flushed RX data. The buffer is also
225 * used when the input RX buffer is from an address space
226 * that cannot be handled by the DMA.
227 * A buffer size must be at least 5 bytes which is the
228 * size of the HW FIFO, and should be bigger if
229 * expected to be used as cache when an input RX buffer
230 * cannot be used for the DMA. If not provided,
231 * then bytes left in the FIFO after a receiver is
232 * disabled will be discarded, and reception will not
233 * be performed if the input RX buffer cannot be used by
234 * the DMA. */
235 nrfx_uarte_rx_cache_t * p_rx_cache_scratch; /**< Static RAM memory area used for receiving data
236 * through RX cache buffer. Can be NULL if RX
237 * caching is not used. */
238 nrf_uarte_baudrate_t baudrate; ///< Baud rate.
239 nrf_uarte_config_t config; ///< Peripheral configuration.
240 bool skip_psel_cfg; ///< Skip pin selection configuration.
241 /**< When set to true, the driver does not modify
242 * pin select registers in the peripheral.
243 * Those registers are supposed to be set up
244 * externally before the driver is initialized.
245 * @note When both GPIO configuration and pin
246 * selection are to be skipped, the structure
247 * fields that specify pins can be omitted,
248 * as they are ignored anyway. */
249 bool skip_gpio_cfg; ///< Skip GPIO configuration of pins.
250 /**< When set to true, the driver does not modify
251 * any GPIO parameters of the used pins. Those
252 * parameters are supposed to be configured
253 * externally before the driver is initialized. */
254 bool tx_stop_on_end; ///< Indicates that the STOPTX task is PPIed with ENDTX event
255 /**< If SHORT exists, then it will be used by the driver,
256 * otherwise (D)PPI connection must be setup by the user. */
257 uint8_t interrupt_priority; ///< Interrupt priority.
258 } nrfx_uarte_config_t;
259
260 /**
261 * @brief UARTE driver default configuration.
262 *
263 * This configuration sets up UARTE with the following options:
264 * - hardware flow control disabled
265 * - no parity bit
266 * - one stop bit
267 * - baudrate: 115200
268 *
269 * @param[in] _pin_tx TX pin.
270 * @param[in] _pin_rx RX pin.
271 */
272 #define NRFX_UARTE_DEFAULT_CONFIG(_pin_tx, _pin_rx) \
273 { \
274 .txd_pin = _pin_tx, \
275 .rxd_pin = _pin_rx, \
276 .rts_pin = NRF_UARTE_PSEL_DISCONNECTED, \
277 .cts_pin = NRF_UARTE_PSEL_DISCONNECTED, \
278 .p_context = NULL, \
279 .tx_cache = \
280 { \
281 .p_buffer = NULL, \
282 .length = 0 \
283 }, \
284 .rx_cache = \
285 { \
286 .p_buffer = NULL, \
287 .length = 0 \
288 }, \
289 .p_rx_cache_scratch = NULL, \
290 .baudrate = NRF_UARTE_BAUDRATE_115200, \
291 .config = \
292 { \
293 .hwfc = NRF_UARTE_HWFC_DISABLED, \
294 .parity = NRF_UARTE_PARITY_EXCLUDED, \
295 NRFX_COND_CODE_1(NRF_UART_HAS_STOP_BITS, \
296 (.stop = (nrf_uarte_stop_t)NRF_UARTE_STOP_ONE,), ()) \
297 NRFX_COND_CODE_1(NRF_UART_HAS_PARITY_BIT, \
298 (.paritytype = NRF_UARTE_PARITYTYPE_EVEN,), ()) \
299 }, \
300 .skip_psel_cfg = false, \
301 .skip_gpio_cfg = false, \
302 .tx_stop_on_end = false, \
303 .interrupt_priority = NRFX_UARTE_DEFAULT_CONFIG_IRQ_PRIORITY \
304 }
305
306 /** @brief Structure for @ref NRFX_UARTE_EVT_RX_DONE event. */
307 typedef struct
308 {
309 uint8_t * p_buffer; ///< Pointer to the received data.
310 size_t length; ///< Amount of received data.
311 } nrfx_uarte_rx_evt_t;
312
313 /** @brief Structure for the @ref NRFX_UARTE_EVT_TX_DONE event. */
314 typedef struct
315 {
316 const uint8_t * p_buffer; ///< Pointer to the transferred data.
317 size_t length; ///< Amount of transferred data.
318 uint32_t flags; ///< Flags. See @ref NRFX_UARTE_TX_DONE_FLAGS.
319 } nrfx_uarte_tx_evt_t;
320
321 /** @brief Structure for the @ref NRFX_UARTE_EVT_ERROR. */
322 typedef struct
323 {
324 nrfy_uarte_buffer_t rx; ///< Transfer details, including number of bytes received.
325 uint32_t error_mask; ///< Mask of error flags that generated the event.
326 } nrfx_uarte_error_evt_t;
327
328 /** @brief Structure for the @ref NRFX_UARTE_EVT_RX_DISABLED. */
329 typedef struct
330 {
331 size_t flush_cnt; ///< Number of bytes flushed from RX FIFO.
332 /**< They will be copied to the next provided buffer if
333 * @ref NRFX_UARTE_RX_ENABLE_KEEP_FIFO_CONTENT is set. */
334 } nrfx_uarte_rx_disabled_evt_t;
335
336 /** @brief Structure for UARTE event. */
337 typedef struct
338 {
339 nrfx_uarte_evt_type_t type; ///< Event type.
340 union
341 {
342 nrfx_uarte_rx_evt_t rx; ///< Data for @ref NRFX_UARTE_EVT_RX_DONE.
343 nrfx_uarte_tx_evt_t tx; ///< Data for @ref NRFX_UARTE_EVT_TX_DONE.
344 nrfx_uarte_error_evt_t error; ///< Data for @ref NRFX_UARTE_EVT_ERROR.
345 nrfx_uarte_rx_disabled_evt_t rx_disabled; ///< Data for @ref NRFX_UARTE_EVT_RX_DISABLED.
346 } data; ///< Union to store event data.
347 } nrfx_uarte_event_t;
348
349 /**
350 * @brief UARTE interrupt event handler.
351 *
352 * @param[in] p_event Pointer to event structure. Event is allocated on the stack so it is
353 * available only within the context of the event handler.
354 * @param[in] p_context Context passed to the interrupt handler, set on initialization.
355 */
356 typedef void (*nrfx_uarte_event_handler_t)(nrfx_uarte_event_t const * p_event,
357 void * p_context);
358
359 /**
360 * @brief Function for initializing the UARTE driver.
361 *
362 * This function configures UARTE but peripheral is kept disabled to reduce power consumption.
363 *
364 * @param[in] p_instance Pointer to the driver instance structure.
365 * @param[in] p_config Pointer to the structure with the initial configuration.
366 * @param[in] event_handler Event handler provided by the user. If not provided driver works in
367 * blocking mode.
368 *
369 * @retval NRFX_SUCCESS Initialization was successful.
370 * @retval NRFX_ERROR_ALREADY The driver is already initialized.
371 * @retval NRFX_ERROR_INVALID_STATE The driver is already initialized.
372 * Deprecated - use @ref NRFX_ERROR_ALREADY instead.
373 * @retval NRFX_ERROR_INVALID_PARAM Invalid configuration.
374 * @retval NRFX_ERROR_BUSY Some other peripheral with the same
375 * instance ID is already in use. This is
376 * possible only if @ref nrfx_prs module
377 * is enabled.
378 */
379 nrfx_err_t nrfx_uarte_init(nrfx_uarte_t const * p_instance,
380 nrfx_uarte_config_t const * p_config,
381 nrfx_uarte_event_handler_t event_handler);
382
383 /**
384 * @brief Function for reconfiguring the UARTE driver.
385 *
386 * @param[in] p_instance Pointer to the driver instance structure.
387 * @param[in] p_config Pointer to the structure with the configuration.
388 *
389 * @retval NRFX_SUCCESS Reconfiguration was successful.
390 * @retval NRFX_ERROR_BUSY The driver is during transfer.
391 * @retval NRFX_ERROR_INVALID_STATE The driver is uninitialized.
392 */
393 nrfx_err_t nrfx_uarte_reconfigure(nrfx_uarte_t const * p_instance,
394 nrfx_uarte_config_t const * p_config);
395
396 /**
397 * @brief Function for uninitializing the UARTE driver.
398 *
399 * @param[in] p_instance Pointer to the driver instance structure.
400 */
401 void nrfx_uarte_uninit(nrfx_uarte_t const * p_instance);
402
403 /**
404 * @brief Function for checking if the UARTE driver instance is initialized.
405 *
406 * @param[in] p_instance Pointer to the driver instance structure.
407 *
408 * @retval true Instance is already initialized.
409 * @retval false Instance is not initialized.
410 */
411 bool nrfx_uarte_init_check(nrfx_uarte_t const * p_instance);
412
413 /**
414 * @brief Function for getting the address of the specified UARTE task.
415 *
416 * @param[in] p_instance Pointer to the driver instance structure.
417 * @param[in] task Task.
418 *
419 * @return Task address.
420 */
421 NRFX_STATIC_INLINE uint32_t nrfx_uarte_task_address_get(nrfx_uarte_t const * p_instance,
422 nrf_uarte_task_t task);
423
424 /**
425 * @brief Function for getting the address of the specified UARTE event.
426 *
427 * @param[in] p_instance Pointer to the driver instance structure.
428 * @param[in] event Event.
429 *
430 * @return Event address.
431 */
432 NRFX_STATIC_INLINE uint32_t nrfx_uarte_event_address_get(nrfx_uarte_t const * p_instance,
433 nrf_uarte_event_t event);
434
435 /**
436 * @brief Function for sending data over UARTE.
437 *
438 * If an event handler is provided in nrfx_uarte_init() call, this function
439 * returns immediately (unless special flags are used) and the handler is called when the transfer
440 * is done. Otherwise, the transfer is performed in blocking mode, that is, this function
441 * returns when the transfer is finished.
442 *
443 * @note Peripherals using EasyDMA (including UARTE) require the transfer buffers
444 * to be placed in the Data RAM region. If this condition is not met,
445 * this function will attempt to use the cache buffer provided in the configuration
446 * and if it is not available it will return error.
447 *
448 * @note To achieve the lowest power consumption, transmitter is stopped and peripheral is disabled
449 * (if receiver is not used) when transfer is completed.
450 *
451 * @param[in] p_instance Pointer to the driver instance structure.
452 * @param[in] p_data Pointer to data.
453 * @param[in] length Number of bytes to send. Maximum possible length is
454 * dependent on the used SoC (see the MAXCNT register
455 * description in the Product Specification). The driver
456 * checks it with assertion.
457 * @param[in] flags Option flags. See @ref NRFX_UARTE_TX_FLAGS.
458 *
459 * @retval NRFX_SUCCESS Initialization was successful.
460 * @retval NRFX_ERROR_BUSY Driver is busy transferring the data.
461 * @retval NRFX_ERROR_FORBIDDEN The transfer was aborted from a different context
462 * (blocking mode only) or transfer cannot be performed due to
463 * driver state, configuration or transfer parameters.
464 * @retval NRFX_ERROR_INVALID_ADDR p_data does not point to RAM buffer and cache buffer is not
465 * provided or attempted to use non DMA buffer with linked
466 * transfer (see @ref NRFX_UARTE_TX_LINK).
467 * @retval NRFX_ERROR_INVALID_LENGTH Flag @ref NRFX_UARTE_TX_EARLY_RETURN is used
468 * but @p length exceeds internal buffer size.
469 */
470 nrfx_err_t nrfx_uarte_tx(nrfx_uarte_t const * p_instance,
471 uint8_t const * p_data,
472 size_t length,
473 uint32_t flags);
474
475 /**
476 * @brief Function for checking if UARTE is currently transmitting.
477 *
478 * @param[in] p_instance Pointer to the driver instance structure.
479 *
480 * @retval true The UARTE is transmitting.
481 * @retval false The UARTE is not transmitting.
482 */
483 bool nrfx_uarte_tx_in_progress(nrfx_uarte_t const * p_instance);
484
485 /**
486 * @brief Function for aborting any ongoing transmission.
487 *
488 * @note When abortion is not synchronous, the @ref NRFX_UARTE_EVT_TX_DONE event will be generated
489 * in non-blocking mode. It will contain the number of bytes sent until the abort was called.
490 * If @ref NRFX_UARTE_TX_LINK flag was used for the transfer and linked transfer have not
491 * started yet, there will be the second @ref NRFX_UARTE_EVT_TX_DONE event with length equal
492 * to 0. The event handler will be called from the UARTE interrupt context.
493 *
494 * @param[in] p_instance Pointer to the driver instance structure.
495 * @param[in] sync If true operation is synchronous. Transmitter is stopped upon
496 * function return and no event is generated.
497 *
498 * @retval NRFX_SUCCESS Successfully initiated abort or when transmitter synchronously
499 * stopped.
500 * @retval NRFX_ERROR_INVALID_STATE Attempt to asynchronously abort when no transfer is active.
501 */
502 nrfx_err_t nrfx_uarte_tx_abort(nrfx_uarte_t const * p_instance, bool sync);
503
504 /**
505 * @brief Function for enabling the receiver.
506 *
507 * The event handler will be called from the caller context with
508 * the @ref NRFX_UARTE_EVT_RX_BUF_REQUEST event. The user may respond and provide a buffer
509 * using @ref nrfx_uarte_rx_buffer_set. An error is returned if buffer is not provided. After that,
510 * the receiver is started and another @ref NRFX_UARTE_EVT_RX_BUF_REQUEST is generated.
511 * If a new buffer is not provided, then the receiver is disabled once the first buffer
512 * becomes full. If a new buffer is provided, then the receiver will seamlessly switch to
513 * a new buffer (using a hardware shortcut).
514 *
515 * @note If transmitter is inactive then peripheral is disabled after receiver is stopped to achieve
516 * the lowest power consumption.
517 *
518 * @param[in] p_instance Pointer to the driver instance structure.
519 * @param[in] flags Option flags. See @ref NRFX_UARTE_RX_ENABLE_FLAGS.
520 *
521 * @retval NRFX_SUCCESS Receiver successfully enabled.
522 * @retval NRFX_ERROR_BUSY When receiver is already enabled.
523 * @retval NRFX_ERROR_NO_MEM When buffer was not provided.
524 */
525 nrfx_err_t nrfx_uarte_rx_enable(nrfx_uarte_t const * p_instance, uint32_t flags);
526
527 /**
528 * @brief Function for providing reception buffer.
529 *
530 * The function should be called as a response to the @ref NRFX_UARTE_EVT_RX_BUF_REQUEST event.
531 * If the function is called before enabling the receiver, the first buffer is configured.
532 * If the function is called and there is no active buffer but the receiver is enabled
533 * but not started, it starts reception.
534 *
535 * @param[in] p_instance Pointer to the driver instance structure.
536 * @param[in] p_data Pointer to a buffer.
537 * @param[in] length Buffer length.
538 *
539 * @retval NRFX_SUCCESS Buffer successfully set.
540 * @retval NRFX_ERROR_INVALID_STATE Buffer provided without pending request.
541 * @retval NRFX_ERROR_TIMEOUT Buffer provided too late. Receiver is being disabled.
542 */
543 nrfx_err_t nrfx_uarte_rx_buffer_set(nrfx_uarte_t const * p_instance,
544 uint8_t * p_data,
545 size_t length);
546
547 /**
548 * @brief Function for receiving data over UARTE.
549 *
550 * If an event handler is provided in the nrfx_uarte_init() call, this function
551 * returns immediately and the handler is called when the transfer is done.
552 * Otherwise, the transfer is performed in blocking mode, that is this function
553 * returns when the transfer is finished. Blocking mode is not using interrupt so
554 * there is no context switching inside the function.
555 * The receive buffer pointer is double-buffered in non-blocking mode. The secondary
556 * buffer can be set immediately after starting the transfer and will be filled
557 * when the primary buffer is full. The double-buffering feature allows
558 * receiving data continuously.
559 *
560 * @note Peripherals using EasyDMA (including UARTE) require the transfer buffers
561 * to be placed in the Data RAM region. If this condition is not met,
562 * this function fails with the error code NRFX_ERROR_INVALID_ADDR.
563 *
564 * @warning When the double-buffering feature is used and the UARTE interrupt
565 * is processed with a delay (for example, due to a higher priority interrupt)
566 * long enough for both buffers to get filled completely,
567 * the event handler will be invoked only once, to notify that
568 * the first buffer has been filled. This is because from hardware perspective it
569 * is impossible to deduce in such case if the second buffer was also filled completely or not.
570 * To prevent this from happening, keep the UARTE interrupt latency low
571 * or use large enough reception buffers.
572 *
573 * @deprecated Use @ref nrfx_uarte_rx_enable and @ref nrfx_uarte_rx_buffer_set.
574 *
575 * @param[in] p_instance Pointer to the driver instance structure.
576 * @param[in] p_data Pointer to data.
577 * @param[in] length Number of bytes to receive. Maximum possible length is
578 * dependent on the used SoC (see the MAXCNT register
579 * description in the Product Specification). The driver
580 * checks it with assertion.
581 *
582 * @retval NRFX_SUCCESS Initialization is successful.
583 * @retval NRFX_ERROR_BUSY The driver is already receiving
584 * (and the secondary buffer has already been set
585 * in non-blocking mode).
586 * @retval NRFX_ERROR_FORBIDDEN The transfer is aborted from a different context
587 * (blocking mode only).
588 * @retval NRFX_ERROR_INTERNAL The UARTE peripheral reports an error.
589 * @retval NRFX_ERROR_INVALID_ADDR p_data does not point to RAM buffer.
590 */
591 nrfx_err_t nrfx_uarte_rx(nrfx_uarte_t const * p_instance,
592 uint8_t * p_data,
593 size_t length);
594
595 /**
596 * @brief Function for testing the receiver state in blocking mode.
597 *
598 * @param[in] p_instance Pointer to the driver instance structure.
599 * @param[out] p_rx_amount Pointer to the variable to be filled with the number of received bytes.
600 * Can be NULL.
601 *
602 * @retval NRFX_SUCCESS The receiving operation is completed.
603 * @retval NRFX_ERROR_BUSY The receiver did not complete the operation.
604 * @retval NRFX_ERROR_ALREADY The receiver is disabled.
605 * @retval NRFX_ERROR_FORBIDDEN Operation is not supporting in the current configuration.
606 */
607 nrfx_err_t nrfx_uarte_rx_ready(nrfx_uarte_t const * p_instance, size_t * p_rx_amount);
608
609 /**
610 * @brief Function for aborting any ongoing reception.
611 *
612 * @note @ref NRFX_UARTE_EVT_RX_DONE event will be generated in non-blocking mode.
613 * It will contain number of bytes received until the abort was called. The event
614 * handler will be called from the UARTE interrupt context.
615 *
616 * @warning When the double-buffering feature is used and the UARTE interrupt
617 * is processed with a delay (for example, due to a higher priority
618 * interrupt) long enough for the first buffer to be filled completely,
619 * the event handler will be supplied with the pointer to the first
620 * buffer and the number of bytes received in the second buffer.
621 * This is because from hardware perspective it is impossible to deduce
622 * the reception of which buffer has been aborted.
623 * To prevent this from happening, keep the UARTE interrupt latency low
624 * or use large enough reception buffers.
625 *
626 * @param[in] p_instance Pointer to the driver instance structure.
627 * @param[in] disable_all If true, UARTE is stopped. If false and there is a second RX buffer provided,
628 * only the first transfer is stopped.
629 * @param[in] sync If true, receiver is disabled synchronously.
630 *
631 * @retval NRFX_SUCCESS Successfully initiate disabling or disabled (synchronous mode).
632 * @retval NRFX_ERROR_INVALID_STATE Receiver was not enabled.
633 */
634 nrfx_err_t nrfx_uarte_rx_abort(nrfx_uarte_t const * p_instance, bool disable_all, bool sync);
635
636 /**
637 * @brief Function for reading error source mask.
638 *
639 * Mask contains values from @ref nrf_uarte_error_mask_t.
640 *
641 * @note Function must be used in the blocking mode only. In case of non-blocking mode, an error
642 * event is generated. Function clears error sources after reading.
643 *
644 * @param[in] p_instance Pointer to the driver instance structure.
645 *
646 * @return Mask of reported errors.
647 */
648 uint32_t nrfx_uarte_errorsrc_get(nrfx_uarte_t const * p_instance);
649
650 /**
651 * @brief Function for checking if there was new RX data since the last check.
652 *
653 * Function checks @ref NRF_UARTE_EVENT_RXDRDY event and clears it if it was set.
654 *
655 * @param[in] p_instance Pointer to the driver instance structure.
656 *
657 * @retval true At least one byte was received since the last check.
658 * @retval false No new data was received since the last check.
659 */
660 bool nrfx_uarte_rx_new_data_check(nrfx_uarte_t const * p_instance);
661
662 /**
663 * @brief Function for enabling @ref NRFX_UARTE_EVT_RX_BYTE event.
664 *
665 * The function enables the @ref NRF_UARTE_EVENT_RXDRDY hardware event which is generated whenever a byte is
666 * received in RXD registers. The event indicates only that data is received, hence it must not be used yet
667 * because it may not be present yet in the RAM buffer handled by the EasyDMA. The event can be used only to
668 * detect a receiver activity. The event can be enabled at any time. Enabling it may increase the number of interrupts (after each received byte).
669 *
670 * @note If there were a receiver activity prior to enabling the @ref NRF_UARTE_EVENT_RXDRDY event,
671 * the @ref NRF_UARTE_EVENT_RXDRDY event may already be set and the @ref NRFX_UARTE_EVT_RX_BYTE will be
672 * triggered immediately. To avoid that, it is recommended to clear that event by calling
673 * the @ref nrfx_uarte_rx_new_data_check.
674 *
675 * @param[in] p_instance Pointer to the driver instance structure.
676 */
677 NRFX_STATIC_INLINE void nrfx_uarte_rxdrdy_enable(nrfx_uarte_t const * p_instance);
678
679 /**
680 * @brief Function for disabling @ref NRFX_UARTE_EVT_RX_BYTE event.
681 *
682 * The function disables the RXDRDY hardware event. See the @ref nrfx_uarte_rxdrdy_enable for more details.
683 * The event can be disabled at any time.
684 *
685 * @param[in] p_instance Pointer to the driver instance structure.
686 */
687 NRFX_STATIC_INLINE void nrfx_uarte_rxdrdy_disable(nrfx_uarte_t const * p_instance);
688
689 /**
690 * @brief Function for triggering UARTE interrupt.
691 *
692 * Function can be used to jump into UARTE interrupt context. User handler is
693 * called with the event @ref NRFX_UARTE_EVT_TRIGGER.
694 *
695 * @param[in] p_instance Pointer to the driver instance structure.
696 *
697 * @retval NRFX_ERROR_FORBIDDEN Failure. User handler is not configured.
698 * @retval NRFX_SUCCESS If interrupt is successfully triggered.
699 */
700 nrfx_err_t nrfx_uarte_int_trigger(nrfx_uarte_t const * p_instance);
701
702 #ifndef NRFX_DECLARE_ONLY
nrfx_uarte_task_address_get(nrfx_uarte_t const * p_instance,nrf_uarte_task_t task)703 NRFX_STATIC_INLINE uint32_t nrfx_uarte_task_address_get(nrfx_uarte_t const * p_instance,
704 nrf_uarte_task_t task)
705 {
706 return nrfy_uarte_task_address_get(p_instance->p_reg, task);
707 }
708
nrfx_uarte_event_address_get(nrfx_uarte_t const * p_instance,nrf_uarte_event_t event)709 NRFX_STATIC_INLINE uint32_t nrfx_uarte_event_address_get(nrfx_uarte_t const * p_instance,
710 nrf_uarte_event_t event)
711 {
712 return nrfy_uarte_event_address_get(p_instance->p_reg, event);
713 }
714
nrfx_uarte_rxdrdy_enable(nrfx_uarte_t const * p_instance)715 NRFX_STATIC_INLINE void nrfx_uarte_rxdrdy_enable(nrfx_uarte_t const * p_instance)
716 {
717 nrfy_uarte_int_enable(p_instance->p_reg, NRF_UARTE_INT_RXDRDY_MASK);
718 }
719
nrfx_uarte_rxdrdy_disable(nrfx_uarte_t const * p_instance)720 NRFX_STATIC_INLINE void nrfx_uarte_rxdrdy_disable(nrfx_uarte_t const * p_instance)
721 {
722 nrfy_uarte_int_disable(p_instance->p_reg, NRF_UARTE_INT_RXDRDY_MASK);
723 }
724
725 #endif // NRFX_DECLARE_ONLY
726
727 /**
728 * @brief Macro returning UARTE interrupt handler.
729 *
730 * param[in] idx UARTE index.
731 *
732 * @return Interrupt handler.
733 */
734 #define NRFX_UARTE_INST_HANDLER_GET(idx) NRFX_CONCAT_3(nrfx_uarte_, idx, _irq_handler)
735
736 /** @} */
737
738 /*
739 * Declare interrupt handlers for all enabled driver instances in the following format:
740 * nrfx_\<periph_name\>_\<idx\>_irq_handler (for example, nrfx_uarte_0_irq_handler).
741 *
742 * A specific interrupt handler for the driver instance can be retrieved by using
743 * the NRFX_UARTE_INST_HANDLER_GET macro.
744 *
745 * Here is a sample of using the NRFX_UARTE_INST_HANDLER_GET macro to map an interrupt handler
746 * in a Zephyr application:
747 *
748 * IRQ_CONNECT(NRFX_IRQ_NUMBER_GET(NRF_UARTE_INST_GET(\<instance_index\>)), \<priority\>,
749 * NRFX_UARTE_INST_HANDLER_GET(\<instance_index\>), 0, 0);
750 */
751 NRFX_INSTANCE_IRQ_HANDLERS_DECLARE(UARTE, uarte)
752
753 #ifdef __cplusplus
754 }
755 #endif
756
757 #endif // NRFX_UARTE_H__
758
