1 /*
2 * Copyright (c) 2017 - 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_COMMON_H__
35 #define NRFX_COMMON_H__
36
37 #include <stdint.h>
38 #include <stddef.h>
39 #include <stdbool.h>
40 #include <string.h>
41 #include <limits.h>
42
43 #include <nrf.h>
44 #include "nrfx_utils.h"
45 #include <nrf_peripherals.h>
46 #include <nrf_mem.h>
47 #include "nrfx_ext.h"
48
49 #ifdef __cplusplus
50 extern "C" {
51 #endif
52
53 #if defined(__CORTEX_M) || defined(__NRFX_DOXYGEN__)
54 #define ISA_ARM 1
55 #elif defined(__VPR_REV)
56 #define ISA_RISCV 1
57 #else
58 #define ISA_UNKNOWN 1
59 #endif
60
61 #if defined(ISA_RISCV)
62 #define __STATIC_INLINE __attribute__((always_inline)) static inline
63 #endif
64
65 #ifndef NRFX_STATIC_INLINE
66 #ifdef NRFX_DECLARE_ONLY
67 #define NRFX_STATIC_INLINE
68 #else
69 #define NRFX_STATIC_INLINE __STATIC_INLINE
70 #endif
71 #endif // NRFX_STATIC_INLINE
72
73 #define NRFY_STATIC_INLINE __STATIC_INLINE
74
75 #ifndef NRF_STATIC_INLINE
76 #ifdef NRF_DECLARE_ONLY
77 #define NRF_STATIC_INLINE
78 #else
79 #define NRF_STATIC_INLINE __STATIC_INLINE
80 #endif
81 #endif // NRF_STATIC_INLINE
82
83 /**
84 * @defgroup nrfx_common Common module
85 * @{
86 * @ingroup nrfx
87 * @brief Common module.
88 */
89
90 /** @brief Symbol specifying major number of the current nrfx version. */
91 #define NRFX_RELEASE_VER_MAJOR 3
92
93 /** @brief Symbol specifying minor number of the current nrfx version. */
94 #define NRFX_RELEASE_VER_MINOR 10
95
96 /** @brief Symbol specifying micro number of the current nrfx version. */
97 #define NRFX_RELEASE_VER_MICRO 0
98
99 /**
100 * @brief Macro for checking if the specified identifier is defined and it has
101 * a non-zero value.
102 *
103 * Normally, preprocessors treat all undefined identifiers as having the value
104 * zero. However, some tools, like static code analyzers, can issue a warning
105 * when such identifier is evaluated. This macro gives the possibility to suppress
106 * such warnings only in places where this macro is used for evaluation, not in
107 * the whole analyzed code.
108 */
109 #define NRFX_CHECK(module_enabled) NRFX_IS_ENABLED(module_enabled)
110
111 /**
112 * @brief Macro for checking if the nrfx version is greater than or equal
113 * to the specified version.
114 *
115 * @note Current nrfx version is specified with the following symbols:
116 * - @ref NRFX_RELEASE_VER_MAJOR
117 * - @ref NRFX_RELEASE_VER_MINOR
118 * - @ref NRFX_RELEASE_VER_MICRO
119 *
120 * @param[in] major Major version.
121 * @param[in] minor Minor version.
122 * @param[in] micro Micro version.
123 *
124 * @retval true Current nrfx version is greater than or equal to the specified version.
125 * @retval false Current nrfx version is smaller than the specified version.
126 */
127 #define NRFX_RELEASE_VER_AT_LEAST(major, minor, micro) \
128 (((NRFX_RELEASE_VER_MAJOR > (major))) || \
129 ((NRFX_RELEASE_VER_MAJOR == major) && (NRFX_RELEASE_VER_MINOR > (minor))) || \
130 ((NRFX_RELEASE_VER_MAJOR == major) && (NRFX_RELEASE_VER_MINOR == minor) && \
131 (NRFX_RELEASE_VER_MICRO >= (micro))))
132
133 /**
134 * @brief Macro for checking if the configured API version is greater than or equal
135 * to the specified API version.
136 *
137 * @note API version to be used is configured using following symbols:
138 * - @ref NRFX_CONFIG_API_VER_MAJOR
139 * - @ref NRFX_CONFIG_API_VER_MINOR
140 * - @ref NRFX_CONFIG_API_VER_MICRO
141 *
142 * @param[in] major Major API version.
143 * @param[in] minor Minor API version.
144 * @param[in] micro Micro API version.
145 *
146 * @retval true Configured API version is greater than or equal to the specified API version.
147 * @retval false Configured API version is smaller than the specified API version.
148 */
149 #define NRFX_API_VER_AT_LEAST(major, minor, micro) \
150 (((NRFX_CONFIG_API_VER_MAJOR > (major))) || \
151 ((NRFX_CONFIG_API_VER_MAJOR == major) && (NRFX_CONFIG_API_VER_MINOR > (minor))) || \
152 ((NRFX_CONFIG_API_VER_MAJOR == major) && (NRFX_CONFIG_API_VER_MINOR == minor) && \
153 (NRFX_CONFIG_API_VER_MICRO >= (micro))))
154
155 /**
156 * @brief Macro for creating unsigned integer with bit position @p x set.
157 *
158 * @param[in] x Bit position to be set.
159 *
160 * @return Unsigned integer with requested bit position set.
161 */
162 #define NRFX_BIT(x) (1UL << (x))
163
164 /**
165 * @brief Macro for returning bit mask or 0 if @p x is 0.
166 *
167 * @param[in] x Bit mask size. Bit mask has bits 0 through x-1 (inclusive) set.
168 *
169 * @return Bit mask.
170 */
171 #define NRFX_BIT_MASK(x) (((x) == 32) ? UINT32_MAX : ((1UL << (x)) - 1))
172
173 /**
174 * @brief Macro for returning size in bits for given size in bytes.
175 *
176 * @param[in] x Size in bytes.
177 *
178 * @return Size in bits.
179 */
180 #define NRFX_BIT_SIZE(x) ((x) << 3)
181
182 /**
183 * @brief Macro for concatenating two tokens in macro expansion.
184 *
185 * @note This macro is expanded in two steps so that tokens given as macros
186 * themselves are fully expanded before they are merged.
187 *
188 * @param[in] p1 First token.
189 * @param[in] p2 Second token.
190 *
191 * @return The two tokens merged into one, unless they cannot together form
192 * a valid token (in such case, the preprocessor issues a warning and
193 * does not perform the concatenation).
194 *
195 * @sa NRFX_CONCAT_3
196 */
197 #define NRFX_CONCAT_2(p1, p2) NRFX_CONCAT_2_(p1, p2)
198
199 /** @brief Internal macro used by @ref NRFX_CONCAT_2 to perform the expansion in two steps. */
200 #define NRFX_CONCAT_2_(p1, p2) p1 ## p2
201
202 /**
203 * @brief Macro for concatenating three tokens in macro expansion.
204 *
205 * @note This macro is expanded in two steps so that tokens given as macros
206 * themselves are fully expanded before they are merged.
207 *
208 * @param[in] p1 First token.
209 * @param[in] p2 Second token.
210 * @param[in] p3 Third token.
211 *
212 * @return The three tokens merged into one, unless they cannot together form
213 * a valid token (in such case, the preprocessor issues a warning and
214 * does not perform the concatenation).
215 *
216 * @sa NRFX_CONCAT_2
217 */
218 #define NRFX_CONCAT_3(p1, p2, p3) NRFX_CONCAT_3_(p1, p2, p3)
219
220 /** @brief Internal macro used by @ref NRFX_CONCAT_3 to perform the expansion in two steps. */
221 #define NRFX_CONCAT_3_(p1, p2, p3) p1 ## p2 ## p3
222
223 /**
224 * @brief Macro for computing the absolute value of an integer number.
225 *
226 * @param[in] a Input value.
227 *
228 * @return Absolute value.
229 */
230 #define NRFX_ABS(a) ((a) < (0) ? -(a) : (a))
231
232 /**
233 * @brief Macro for checking whether any of the instance of the specified peripheral supports a given feature.
234 *
235 * Macro checks flags set in \<device\>_peripherals.h file.
236 *
237 * Macro supports check on instances with following names:
238 * - \<periph_name\>0 - \<periph_name\>255 - e.g. SPIM0, SPIM255
239 * - \<periph_name\>00 - \<periph_name\>099 - e.g. SPIM00, SPIM099
240 * - \<periph_name\>000 - \<periph_name\>009 - e.g. SPIM000, SPIM009
241 *
242 * @param[in] periph_name Peripheral name, e.g. SPIM.
243 * @param[in] feature_name Feature flag name suffix following an instance name, e.g.
244 * _FEATURE_HARDWARE_CSN_PRESENT.
245 *
246 * @retval 1 At least one instance on current device supports a given feature.
247 * @retval 0 None of peripheral instances supports a given feature.
248 */
249 #define NRFX_FEATURE_PRESENT(periph_name, feature_name) \
250 NRFX_COND_CODE_0(NRFX_CONCAT(0, \
251 _NRFX_FEATURE_PRESENT(periph_name, feature_name, 256), \
252 _NRFX_FEATURE_PRESENT(NRFX_CONCAT(periph_name, 0), feature_name, 100), \
253 _NRFX_FEATURE_PRESENT(NRFX_CONCAT(periph_name, 00), feature_name, 10) \
254 ), \
255 (0), (1))
256
257 /**
258 * @brief Macro for resolving provided user macro for enabled instances of a driver.
259 *
260 * Macro checks if driver instances are enabled for all potential instaces of a
261 * peripheral. It takes peripheral name and checks whether NRFX_\<peripheral\>\<id\>_ENABLED
262 * is set to 1 and if yes then provided macro is evaluated for given instance.
263 *
264 * Macro supports check on instances with following names:
265 * - \<periph_name\>0 - \<periph_name\>255 - e.g. SPIM0, SPIM255
266 * - \<periph_name\>00 - \<periph_name\>099 - e.g. SPIM00, SPIM099
267 * - \<periph_name\>000 - \<periph_name\>009 - e.g. SPIM000, SPIM009
268 *
269 * @param[in] periph_name Peripheral name, e.g. SPIM.
270 * @param[in] macro Macro which is resolved if driver instance is enabled. Macro has following
271 * arguments: macro(periph_name, prefix, i, ...).
272 * @param[in] sep Separator added between all evaluations, in parentheses.
273 * @param[in] off_code Code injected for disabled instances, in parentheses.
274 */
275 #define NRFX_FOREACH_ENABLED(periph_name, macro, sep, off_code, ...) \
276 NRFX_LISTIFY(256, _NRFX_EVAL_IF_ENABLED, sep, \
277 off_code, periph_name, , macro, __VA_ARGS__) NRFX_DEBRACKET sep \
278 NRFX_LISTIFY(100, _NRFX_EVAL_IF_ENABLED, sep, \
279 off_code, periph_name, 0, macro, __VA_ARGS__) NRFX_DEBRACKET sep \
280 NRFX_LISTIFY(10, _NRFX_EVAL_IF_ENABLED, sep, \
281 off_code, periph_name, 00, macro, __VA_ARGS__)
282
283 /**
284 * @brief Macro for resolving provided user macro for present instances of a peripheral.
285 *
286 * Macro checks if peripheral instances are present by checking if there is a token
287 * NRF_\<periph_name\>\<id\> defined with wrapped in parenthesis value.
288 *
289 * Macro supports check on instances with following names:
290 * - \<periph_name\>0 - \<periph_name\>255 - e.g. SPIM0, SPIM255
291 * - \<periph_name\>00 - \<periph_name\>099 - e.g. SPIM00, SPIM099
292 * - \<periph_name\>000 - \<periph_name\>009 - e.g. SPIM000, SPIM009
293 * - \<periph_name\> - e.g. SPIM
294 *
295 * @param[in] periph_name Peripheral name, e.g. SPIM.
296 * @param[in] macro Macro which is resolved if peripheral instance is present.
297 * Macro has following arguments: macro(periph_name, prefix, i, ...).
298 * @param[in] sep Separator added between all evaluations, in parentheses.
299 * @param[in] off_code Code injected for disabled instances, in parentheses.
300 */
301 #define NRFX_FOREACH_PRESENT(periph_name, macro, sep, off_code, ...) \
302 NRFX_LISTIFY(256, _NRFX_EVAL_IF_PRESENT, sep, \
303 off_code, periph_name, , macro, __VA_ARGS__) NRFX_DEBRACKET sep \
304 NRFX_LISTIFY(100, _NRFX_EVAL_IF_PRESENT, sep, \
305 off_code, periph_name, 0, macro, __VA_ARGS__) NRFX_DEBRACKET sep \
306 NRFX_LISTIFY(10, _NRFX_EVAL_IF_PRESENT, sep, \
307 off_code, periph_name, 00, macro, __VA_ARGS__) NRFX_DEBRACKET sep \
308 _NRFX_EVAL_IF_PRESENT(, off_code, periph_name, , macro, __VA_ARGS__)
309
310 /**
311 * @brief Macro for resolving provided user macro on concatenated peripheral name
312 * and instance index.
313 *
314 * Execute provided macro with single argument <instance\>
315 * that is the concatenation of @p periph_name, @p prefix and @p i.
316 *
317 * @param[in] i Instance index.
318 * @param[in] periph_name Peripheral name, e.g. SPIM.
319 * @param[in] prefix Prefix added before instance index, e.g. some device has
320 * instances named like SPIM00. First 0 is passed here as prefix.
321 * @param[in] macro Macro which is executed.
322 * @param[in] ... Variable length arguments passed to the @p macro. Macro has following
323 * arguments: macro(instance, ...).
324 */
325 #define NRFX_INSTANCE_CONCAT(periph_name, prefix, i, macro, ...) \
326 macro(NRFX_CONCAT(periph_name, prefix, i), __VA_ARGS__)
327
328 /**
329 * @brief Macro for creating a content for enum which is listing enabled driver instances.
330 *
331 * It creates comma separated list of entries like NRFX_\<instance_name\>_INST_IDX,
332 * e.g. (NRFX_SPIM0_INST_IDX) for all enabled instances (NRFX_\<instance_name\>_ENABLED
333 * is set to 1). It should be called within enum declaration. Created enum is used
334 * by the driver to index all enabled instances of the driver.
335 *
336 * @param[in] periph_name Peripheral name (e.g. SPIM).
337 */
338 #define NRFX_INSTANCE_ENUM_LIST(periph_name) \
339 NRFX_FOREACH_ENABLED(periph_name, _NRFX_INST_ENUM, (), ())
340
341 /**
342 * @brief Macro for creating an interrupt handler for all enabled driver instances.
343 *
344 * Macro creates a set of functions which calls generic @p irq_handler function with two parameters:
345 * - peripheral instance register pointer
346 * - pointer to a control block structure associated with the given instance
347 *
348 * Generic interrupt handler function with above mentioned parameters named @p irq_handler
349 * must be implemented in the driver.
350 *
351 * @note Handlers are using enum which should be generated using @ref NRFX_INSTANCE_ENUM_LIST.
352 *
353 * @param[in] periph_name Peripheral name, e.g. SPIM.
354 * @param[in] periph_name_small Peripheral name written with small letters, e.g. spim.
355 */
356 #define NRFX_INSTANCE_IRQ_HANDLERS(periph_name, periph_name_small) \
357 NRFX_FOREACH_ENABLED(periph_name, _NRFX_IRQ_HANDLER, (), (), periph_name_small)
358
359 /**
360 * @brief Macro for creating an interrupt handler for all enabled driver instances
361 * with the specified extra parameter.
362 *
363 * Macro creates set of function which calls generic @p irq_handler function with three parameters:
364 * - peripheral instance register pointer
365 * - pointer to a control block structure associated with the given instance
366 * - provided @p ext_macro called with peripheral name suffix (e.g. 01 for TIMER01)
367 *
368 * Generic interrupt handler function with above mentioned parameters named @p irq_handler
369 * must be implemented in the driver.
370 *
371 * @note Handlers are using enum which should be generated using @ref NRFX_INSTANCE_ENUM_LIST.
372 *
373 * @param[in] periph_name Peripheral name, e.g. SPIM.
374 * @param[in] periph_name_small Peripheral name written with small letters, e.g. rtc.
375 * @param[in] ext_macro External macro to be executed for each instance.
376 */
377 #define NRFX_INSTANCE_IRQ_HANDLERS_EXT(periph_name, periph_name_small, ext_macro) \
378 NRFX_FOREACH_ENABLED(periph_name, _NRFX_IRQ_HANDLER_EXT, (), (), periph_name_small, ext_macro)
379
380 /**
381 * @brief Macro for declaring an interrupt handler for all enabled driver instances.
382 *
383 * Macro creates set of function declarations. It is intended to be used in the driver header.
384 *
385 * @param[in] periph_name Peripheral name, e.g. SPIM.
386 * @param[in] periph_name_small Peripheral name written with small letters, e.g. spim.
387 */
388 #define NRFX_INSTANCE_IRQ_HANDLERS_DECLARE(periph_name, periph_name_small) \
389 NRFX_FOREACH_ENABLED(periph_name, _NRFX_IRQ_HANDLER_DECLARE, (), (), periph_name_small)
390
391 /**
392 * @brief Macro for generating comma-separated list of interrupt handlers for all
393 * enabled driver instances.
394 *
395 * Interrupt handlers are generated using @ref NRFX_INSTANCE_IRQ_HANDLERS.
396 * It is intended to be used to create a list which is used for passing an interrupt
397 * handler function to the PRS driver.
398 *
399 * @param[in] periph_name Peripheral name, e.g. SPIM.
400 * @param[in] periph_name_small Peripheral name written with small letters, e.g. spim.
401 */
402 #define NRFX_INSTANCE_IRQ_HANDLERS_LIST(periph_name, periph_name_small) \
403 NRFX_FOREACH_ENABLED(periph_name, _NRFX_IRQ_HANDLER_LIST, (), (), periph_name_small)
404
405 /**
406 * @brief Macro for checking if given peripheral instance is present on the target.
407 *
408 * Macro utilizes the fact that for each existing instance a define is created which points to
409 * the memory mapped register set casted to a register set structure. It is wrapped in parenthesis
410 * and existance of parethesis wrapping is used to determine if instance exists. It if does not
411 * exist then token (e.g. NRF_SPIM10) is undefined so it does not have parenthesis wrapping.
412 *
413 * Since macro returns literal 1 it can be used by other macros.
414 *
415 * @param[in] _inst Instance, .e.g SPIM10.
416 *
417 * @retval 1 If instance is present.
418 * @retval 0 If instance is not present.
419 */
420 #define NRFX_INSTANCE_PRESENT(_inst) NRFX_ARG_HAS_PARENTHESIS(NRFX_CONCAT(NRF_, _inst))
421
422 /**
423 * @brief Macro for getting the smaller value between two arguments.
424 *
425 * @param[in] a First argument.
426 * @param[in] b Second argument.
427 *
428 * @return Smaller value between two arguments.
429 */
430 #define NRFX_MIN(a, b) ((a) < (b) ? (a) : (b))
431
432 /**
433 * @brief Macro for getting the larger value between two arguments.
434 *
435 * @param[in] a First argument.
436 * @param[in] b Second argument.
437 *
438 * @return Larger value between two arguments.
439 */
440 #define NRFX_MAX(a, b) ((a) > (b) ? (a) : (b))
441
442 /**
443 * @brief Macro for checking if a given value is in a given range.
444 *
445 * @note @p val is evaluated twice.
446 *
447 * @param[in] val A value to be checked.
448 * @param[in] min The lower bound (inclusive).
449 * @param[in] max The upper bound (inclusive).
450 *
451 * @retval true The value is in the given range.
452 * @retval false The value is out of the given range.
453 */
454 #define NRFX_IN_RANGE(val, min, max) ((val) >= (min) && (val) <= (max))
455
456 /**
457 * @brief Macro for performing rounded integer division (as opposed to
458 * truncating the result).
459 *
460 * @param[in] a Numerator.
461 * @param[in] b Denominator.
462 *
463 * @return Rounded (integer) result of dividing @c a by @c b.
464 */
465 #define NRFX_ROUNDED_DIV(a, b) \
466 ((((a) < 0) ^ ((b) < 0)) ? (((a) - (b) / 2) / (b)) : (((a) + (b) / 2) / (b)))
467
468 /**
469 * @brief Macro for performing integer division, making sure the result is rounded up.
470 *
471 * @details A typical use case for this macro is to compute the number of objects
472 * with size @c b required to hold @c a number of bytes.
473 *
474 * @param[in] a Numerator.
475 * @param[in] b Denominator.
476 *
477 * @return Integer result of dividing @c a by @c b, rounded up.
478 */
479 #define NRFX_CEIL_DIV(a, b) ((((a) - 1) / (b)) + 1)
480
481 /**
482 * @brief Macro for getting the number of elements in an array.
483 *
484 * @param[in] array Name of the array.
485 *
486 * @return Array element count.
487 */
488 #define NRFX_ARRAY_SIZE(array) (sizeof(array) / sizeof((array)[0]))
489
490 /**
491 * @brief Macro for getting the offset (in bytes) from the beginning of a structure
492 * of the specified type to its specified member.
493 *
494 * @param[in] type Structure type.
495 * @param[in] member Structure member whose offset is searched for.
496 *
497 * @return Member offset in bytes.
498 */
499 #define NRFX_OFFSETOF(type, member) ((size_t) & (((type *)0)->member))
500
501 /**
502 * @brief Macro for checking whether given number is power of 2.
503 *
504 * @param[in] val Tested value.
505 *
506 * @retval true The value is power of 2.
507 * @retval false The value is not power of 2.
508 */
509 #define NRFX_IS_POWER_OF_TWO(val) (((val) != 0) && ((val) & ((val) - 1)) == 0)
510
511 /**
512 * @brief Macro for checking whether a given number is even.
513 *
514 * @param[in] val Tested value.
515 *
516 * @retval true The value is even.
517 * @retval false The value is odd.
518 */
519 #define NRFX_IS_EVEN(val) (((val) % 2) == 0)
520
521 /**
522 * @brief Macro for checking if given lengths of EasyDMA transfers do not exceed
523 * the limit of the specified peripheral.
524 *
525 * @param[in] peripheral Peripheral to check the lengths against.
526 * @param[in] length1 First length to be checked.
527 * @param[in] length2 Second length to be checked (pass 0 if not needed).
528 *
529 * @retval true The length of buffers does not exceed the limit of the specified peripheral.
530 * @retval false The length of buffers exceeds the limit of the specified peripheral.
531 */
532 #define NRFX_EASYDMA_LENGTH_VALIDATE(peripheral, length1, length2) \
533 (((length1) < (1U << NRFX_CONCAT_2(peripheral, _EASYDMA_MAXCNT_SIZE))) && \
534 ((length2) < (1U << NRFX_CONCAT_2(peripheral, _EASYDMA_MAXCNT_SIZE))))
535
536 /**
537 * @brief Macro for waiting until condition is met.
538 *
539 * @param[in] condition Condition to meet.
540 * @param[in] attempts Maximum number of condition checks. Must not be 0.
541 * @param[in] delay_us Delay between consecutive checks, in microseconds.
542 * @param[out] result Boolean variable to store the result of the wait process.
543 * Set to true if the condition is met or false otherwise.
544 */
545 #define NRFX_WAIT_FOR(condition, attempts, delay_us, result) \
546 do { \
547 result = false; \
548 uint32_t remaining_attempts = (attempts); \
549 do { \
550 if (condition) \
551 { \
552 result = true; \
553 break; \
554 } \
555 NRFX_DELAY_US(delay_us); \
556 } while (--remaining_attempts); \
557 } while(0)
558
559 /**
560 * @brief Macro for getting the ID number of the specified peripheral.
561 *
562 * For peripherals in Nordic SoCs, there is a direct relationship between their
563 * ID numbers and their base addresses. See the chapter "Peripheral interface"
564 * (section "Peripheral ID") in the Product Specification.
565 *
566 * @param[in] base_addr Peripheral base address or pointer.
567 *
568 * @return ID number associated with the specified peripheral.
569 */
570 #define NRFX_PERIPHERAL_ID_GET(base_addr) (uint16_t)(((uint32_t)(base_addr) >> 12) & 0x000001FF)
571
572 /**
573 * @brief Macro for getting the interrupt number assigned to a specific
574 * peripheral.
575 *
576 * For peripherals in Nordic SoCs, the IRQ number assigned to a peripheral is
577 * equal to its ID number. See the chapter "Peripheral interface" (sections
578 * "Peripheral ID" and "Interrupts") in the Product Specification.
579 *
580 * @param[in] base_addr Peripheral base address or pointer.
581 *
582 * @return Interrupt number associated with the specified peripheral.
583 */
584 #define NRFX_IRQ_NUMBER_GET(base_addr) NRFX_PERIPHERAL_ID_GET(base_addr)
585
586 /**
587 * @brief Macro for converting frequency in kHz to Hz.
588 *
589 * @param[in] freq Frequency value in kHz.
590 *
591 * @return Number of Hz in @p freq kHz.
592 */
593 #define NRFX_KHZ_TO_HZ(freq) ((freq) * 1000)
594
595 /**
596 * @brief Macro for converting frequency in MHz to Hz.
597 *
598 * @param[in] freq Frequency value in MHz.
599 *
600 * @return Number of Hz in @p freq MHz.
601 */
602 #define NRFX_MHZ_TO_HZ(freq) ((freq) * 1000 * 1000)
603
604 /** @brief IRQ handler type. */
605 typedef void (* nrfx_irq_handler_t)(void);
606
607 /** @brief Driver state. */
608 typedef enum
609 {
610 NRFX_DRV_STATE_UNINITIALIZED, ///< Uninitialized.
611 NRFX_DRV_STATE_INITIALIZED, ///< Initialized but powered off.
612 NRFX_DRV_STATE_POWERED_ON, ///< Initialized and powered on.
613 } nrfx_drv_state_t;
614
615 /**
616 * @brief Function for checking if an object is placed in the Data RAM region.
617 *
618 * Several peripherals (the ones using EasyDMA) require the transfer buffers
619 * to be placed in the Data RAM region. This function can be used to check if
620 * this condition is met.
621 *
622 * @param[in] p_object Pointer to an object whose location is to be checked.
623 *
624 * @retval true The pointed object is located in the Data RAM region.
625 * @retval false The pointed object is not located in the Data RAM region.
626 */
627 NRF_STATIC_INLINE bool nrfx_is_in_ram(void const * p_object);
628
629 /**
630 * @brief Function for checking if an object is aligned to a 32-bit word
631 *
632 * Several peripherals (the ones using EasyDMA) require the transfer buffers
633 * to be aligned to a 32-bit word. This function can be used to check if
634 * this condition is met.
635 *
636 * @param[in] p_object Pointer to an object whose location is to be checked.
637 *
638 * @retval true The pointed object is aligned to a 32-bit word.
639 * @retval false The pointed object is not aligned to a 32-bit word.
640 */
641 NRF_STATIC_INLINE bool nrfx_is_word_aligned(void const * p_object);
642
643 /**
644 * @brief Function for getting the interrupt number for the specified peripheral.
645 *
646 * @param[in] p_reg Peripheral base pointer.
647 *
648 * @return Interrupt number associated with the pointed peripheral.
649 */
650 NRF_STATIC_INLINE IRQn_Type nrfx_get_irq_number(void const * p_reg);
651
652 /**
653 * @brief Function for converting an INTEN register bit position to the
654 * corresponding event identifier.
655 *
656 * The event identifier is the offset between the event register address and
657 * the peripheral base address, and is equal (thus, can be directly cast) to
658 * the corresponding value of the enumerated type from HAL (nrf_*_event_t).
659 *
660 * @param[in] bit INTEN register bit position.
661 *
662 * @return Event identifier.
663 *
664 * @sa nrfx_event_to_bitpos
665 */
666 NRF_STATIC_INLINE uint32_t nrfx_bitpos_to_event(uint32_t bit);
667
668 /**
669 * @brief Function for converting an event identifier to the corresponding
670 * INTEN register bit position.
671 *
672 * The event identifier is the offset between the event register address and
673 * the peripheral base address, and is equal (thus, can be directly cast) to
674 * the corresponding value of the enumerated type from HAL (nrf_*_event_t).
675 *
676 * @param[in] event Event identifier.
677 *
678 * @return INTEN register bit position.
679 *
680 * @sa nrfx_bitpos_to_event
681 */
682 NRF_STATIC_INLINE uint32_t nrfx_event_to_bitpos(uint32_t event);
683
684 #ifndef NRF_DECLARE_ONLY
685
nrfx_is_in_ram(void const * p_object)686 NRF_STATIC_INLINE bool nrfx_is_in_ram(void const * p_object)
687 {
688 return ((((uint32_t)p_object) & 0xE0000000u) == 0x20000000u);
689 }
690
nrfx_is_word_aligned(void const * p_object)691 NRF_STATIC_INLINE bool nrfx_is_word_aligned(void const * p_object)
692 {
693 return ((((uint32_t)p_object) & 0x3u) == 0u);
694 }
695
nrfx_get_irq_number(void const * p_reg)696 NRF_STATIC_INLINE IRQn_Type nrfx_get_irq_number(void const * p_reg)
697 {
698 return (IRQn_Type)NRFX_IRQ_NUMBER_GET(p_reg);
699 }
700
nrfx_bitpos_to_event(uint32_t bit)701 NRF_STATIC_INLINE uint32_t nrfx_bitpos_to_event(uint32_t bit)
702 {
703 static const uint32_t event_reg_offset = 0x100u;
704 return event_reg_offset + (bit * sizeof(uint32_t));
705 }
706
nrfx_event_to_bitpos(uint32_t event)707 NRF_STATIC_INLINE uint32_t nrfx_event_to_bitpos(uint32_t event)
708 {
709 static const uint32_t event_reg_offset = 0x100u;
710 return (event - event_reg_offset) / sizeof(uint32_t);
711 }
712
713 #endif // NRF_DECLARE_ONLY
714
715 /** @} */
716
717 #ifdef __cplusplus
718 }
719 #endif
720
721 #endif // NRFX_COMMON_H__
722
