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
nrfx_uarte_task_address_get(nrfx_uarte_t const * p_instance,nrf_uarte_task_t task)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
nrfx_uarte_event_address_get(nrfx_uarte_t const * p_instance,nrf_uarte_event_t event)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