Branch data Line data Source code
1 : : /*
2 : : * Copyright (c) 2017 - 2022, 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 : :
41 : : #include <nrf.h>
42 : : #include <nrf_peripherals.h>
43 : :
44 : : #ifdef __cplusplus
45 : : extern "C" {
46 : : #endif
47 : :
48 : : #ifndef NRFX_STATIC_INLINE
49 : : #ifdef NRFX_DECLARE_ONLY
50 : : #define NRFX_STATIC_INLINE
51 : : #else
52 : : #define NRFX_STATIC_INLINE __STATIC_INLINE
53 : : #endif
54 : : #endif // NRFX_STATIC_INLINE
55 : :
56 : : #ifndef NRF_STATIC_INLINE
57 : : #ifdef NRF_DECLARE_ONLY
58 : : #define NRF_STATIC_INLINE
59 : : #else
60 : : #define NRF_STATIC_INLINE __STATIC_INLINE
61 : : #endif
62 : : #endif // NRF_STATIC_INLINE
63 : :
64 : : /**
65 : : * @defgroup nrfx_common Common module
66 : : * @{
67 : : * @ingroup nrfx
68 : : * @brief Common module.
69 : : */
70 : :
71 : : /**
72 : : * @brief Macro for checking if the specified identifier is defined and it has
73 : : * a non-zero value.
74 : : *
75 : : * Normally, preprocessors treat all undefined identifiers as having the value
76 : : * zero. However, some tools, like static code analyzers, can issue a warning
77 : : * when such identifier is evaluated. This macro gives the possibility to suppress
78 : : * such warnings only in places where this macro is used for evaluation, not in
79 : : * the whole analyzed code.
80 : : */
81 : : #define NRFX_CHECK(module_enabled) (module_enabled)
82 : :
83 : : /**
84 : : * @brief Macro for creating unsigned integer with bit position @p x set.
85 : : *
86 : : * @param[in] x Bit position to be set.
87 : : *
88 : : * @return Unsigned integer with requested bit position set.
89 : : */
90 : : #define NRFX_BIT(x) (1UL << (x))
91 : :
92 : : /**
93 : : * @brief Macro for returning bit mask or 0 if @p x is 0.
94 : : *
95 : : * @param[in] x Bit mask size. Bit mask has bits 0 through x-1 (inclusive) set.
96 : : *
97 : : * @return Bit mask.
98 : : */
99 : : #define NRFX_BIT_MASK(x) (NRFX_BIT(x) - 1UL)
100 : :
101 : : /**
102 : : * @brief Macro for concatenating two tokens in macro expansion.
103 : : *
104 : : * @note This macro is expanded in two steps so that tokens given as macros
105 : : * themselves are fully expanded before they are merged.
106 : : *
107 : : * @param[in] p1 First token.
108 : : * @param[in] p2 Second token.
109 : : *
110 : : * @return The two tokens merged into one, unless they cannot together form
111 : : * a valid token (in such case, the preprocessor issues a warning and
112 : : * does not perform the concatenation).
113 : : *
114 : : * @sa NRFX_CONCAT_3
115 : : */
116 : : #define NRFX_CONCAT_2(p1, p2) NRFX_CONCAT_2_(p1, p2)
117 : :
118 : : /** @brief Internal macro used by @ref NRFX_CONCAT_2 to perform the expansion in two steps. */
119 : : #define NRFX_CONCAT_2_(p1, p2) p1 ## p2
120 : :
121 : : /**
122 : : * @brief Macro for concatenating three tokens in macro expansion.
123 : : *
124 : : * @note This macro is expanded in two steps so that tokens given as macros
125 : : * themselves are fully expanded before they are merged.
126 : : *
127 : : * @param[in] p1 First token.
128 : : * @param[in] p2 Second token.
129 : : * @param[in] p3 Third token.
130 : : *
131 : : * @return The three tokens merged into one, unless they cannot together form
132 : : * a valid token (in such case, the preprocessor issues a warning and
133 : : * does not perform the concatenation).
134 : : *
135 : : * @sa NRFX_CONCAT_2
136 : : */
137 : : #define NRFX_CONCAT_3(p1, p2, p3) NRFX_CONCAT_3_(p1, p2, p3)
138 : :
139 : : /** @brief Internal macro used by @ref NRFX_CONCAT_3 to perform the expansion in two steps. */
140 : : #define NRFX_CONCAT_3_(p1, p2, p3) p1 ## p2 ## p3
141 : :
142 : : /**
143 : : * @brief Macro for performing rounded integer division (as opposed to
144 : : * truncating the result).
145 : : *
146 : : * @param[in] a Numerator.
147 : : * @param[in] b Denominator.
148 : : *
149 : : * @return Rounded (integer) result of dividing @c a by @c b.
150 : : */
151 : : #define NRFX_ROUNDED_DIV(a, b) (((a) + ((b) / 2)) / (b))
152 : :
153 : : /**
154 : : * @brief Macro for performing integer division, making sure the result is rounded up.
155 : : *
156 : : * @details A typical use case for this macro is to compute the number of objects
157 : : * with size @c b required to hold @c a number of bytes.
158 : : *
159 : : * @param[in] a Numerator.
160 : : * @param[in] b Denominator.
161 : : *
162 : : * @return Integer result of dividing @c a by @c b, rounded up.
163 : : */
164 : : #define NRFX_CEIL_DIV(a, b) ((((a) - 1) / (b)) + 1)
165 : :
166 : : /**
167 : : * @brief Macro for getting the number of elements in an array.
168 : : *
169 : : * @param[in] array Name of the array.
170 : : *
171 : : * @return Array element count.
172 : : */
173 : : #define NRFX_ARRAY_SIZE(array) (sizeof(array) / sizeof((array)[0]))
174 : :
175 : : /**
176 : : * @brief Macro for getting the offset (in bytes) from the beginning of a structure
177 : : * of the specified type to its specified member.
178 : : *
179 : : * @param[in] type Structure type.
180 : : * @param[in] member Structure member whose offset is searched for.
181 : : *
182 : : * @return Member offset in bytes.
183 : : */
184 : : #define NRFX_OFFSETOF(type, member) ((size_t)&(((type *)0)->member))
185 : :
186 : : /**@brief Macro for checking if given lengths of EasyDMA transfers do not exceed
187 : : * the limit of the specified peripheral.
188 : : *
189 : : * @param[in] peripheral Peripheral to check the lengths against.
190 : : * @param[in] length1 First length to be checked.
191 : : * @param[in] length2 Second length to be checked (pass 0 if not needed).
192 : : *
193 : : * @retval true The length of buffers does not exceed the limit of the specified peripheral.
194 : : * @retval false The length of buffers exceeds the limit of the specified peripheral.
195 : : */
196 : : #define NRFX_EASYDMA_LENGTH_VALIDATE(peripheral, length1, length2) \
197 : : (((length1) < (1U << NRFX_CONCAT_2(peripheral, _EASYDMA_MAXCNT_SIZE))) && \
198 : : ((length2) < (1U << NRFX_CONCAT_2(peripheral, _EASYDMA_MAXCNT_SIZE))))
199 : :
200 : : /**
201 : : * @brief Macro for waiting until condition is met.
202 : : *
203 : : * @param[in] condition Condition to meet.
204 : : * @param[in] attempts Maximum number of condition checks. Must not be 0.
205 : : * @param[in] delay_us Delay between consecutive checks, in microseconds.
206 : : * @param[out] result Boolean variable to store the result of the wait process.
207 : : * Set to true if the condition is met or false otherwise.
208 : : */
209 : : #define NRFX_WAIT_FOR(condition, attempts, delay_us, result) \
210 : : do { \
211 : : result = false; \
212 : : uint32_t remaining_attempts = (attempts); \
213 : : do { \
214 : : if (condition) \
215 : : { \
216 : : result = true; \
217 : : break; \
218 : : } \
219 : : NRFX_DELAY_US(delay_us); \
220 : : } while (--remaining_attempts); \
221 : : } while(0)
222 : :
223 : : /**
224 : : * @brief Macro for getting the ID number of the specified peripheral.
225 : : *
226 : : * For peripherals in Nordic SoCs, there is a direct relationship between their
227 : : * ID numbers and their base addresses. See the chapter "Peripheral interface"
228 : : * (section "Peripheral ID") in the Product Specification.
229 : : *
230 : : * @param[in] base_addr Peripheral base address or pointer.
231 : : *
232 : : * @return ID number associated with the specified peripheral.
233 : : */
234 : : #define NRFX_PERIPHERAL_ID_GET(base_addr) (uint8_t)((uint32_t)(base_addr) >> 12)
235 : :
236 : : /**
237 : : * @brief Macro for getting the interrupt number assigned to a specific
238 : : * peripheral.
239 : : *
240 : : * For peripherals in Nordic SoCs, the IRQ number assigned to a peripheral is
241 : : * equal to its ID number. See the chapter "Peripheral interface" (sections
242 : : * "Peripheral ID" and "Interrupts") in the Product Specification.
243 : : *
244 : : * @param[in] base_addr Peripheral base address or pointer.
245 : : *
246 : : * @return Interrupt number associated with the specified peripheral.
247 : : */
248 : : #define NRFX_IRQ_NUMBER_GET(base_addr) NRFX_PERIPHERAL_ID_GET(base_addr)
249 : :
250 : : /** @brief IRQ handler type. */
251 : : typedef void (* nrfx_irq_handler_t)(void);
252 : :
253 : : /** @brief Driver state. */
254 : : typedef enum
255 : : {
256 : : NRFX_DRV_STATE_UNINITIALIZED, ///< Uninitialized.
257 : : NRFX_DRV_STATE_INITIALIZED, ///< Initialized but powered off.
258 : : NRFX_DRV_STATE_POWERED_ON, ///< Initialized and powered on.
259 : : } nrfx_drv_state_t;
260 : :
261 : :
262 : : /**
263 : : * @brief Function for checking if an object is placed in the Data RAM region.
264 : : *
265 : : * Several peripherals (the ones using EasyDMA) require the transfer buffers
266 : : * to be placed in the Data RAM region. This function can be used to check if
267 : : * this condition is met.
268 : : *
269 : : * @param[in] p_object Pointer to an object whose location is to be checked.
270 : : *
271 : : * @retval true The pointed object is located in the Data RAM region.
272 : : * @retval false The pointed object is not located in the Data RAM region.
273 : : */
274 : : NRF_STATIC_INLINE bool nrfx_is_in_ram(void const * p_object);
275 : :
276 : : /**
277 : : * @brief Function for checking if an object is aligned to a 32-bit word
278 : : *
279 : : * Several peripherals (the ones using EasyDMA) require the transfer buffers
280 : : * to be aligned to a 32-bit word. This function can be used to check if
281 : : * this condition is met.
282 : : *
283 : : * @param[in] p_object Pointer to an object whose location is to be checked.
284 : : *
285 : : * @retval true The pointed object is aligned to a 32-bit word.
286 : : * @retval false The pointed object is not aligned to a 32-bit word.
287 : : */
288 : : NRF_STATIC_INLINE bool nrfx_is_word_aligned(void const * p_object);
289 : :
290 : : /**
291 : : * @brief Function for getting the interrupt number for the specified peripheral.
292 : : *
293 : : * @param[in] p_reg Peripheral base pointer.
294 : : *
295 : : * @return Interrupt number associated with the pointed peripheral.
296 : : */
297 : : NRF_STATIC_INLINE IRQn_Type nrfx_get_irq_number(void const * p_reg);
298 : :
299 : : /**
300 : : * @brief Function for converting an INTEN register bit position to the
301 : : * corresponding event identifier.
302 : : *
303 : : * The event identifier is the offset between the event register address and
304 : : * the peripheral base address, and is equal (thus, can be directly cast) to
305 : : * the corresponding value of the enumerated type from HAL (nrf_*_event_t).
306 : : *
307 : : * @param[in] bit INTEN register bit position.
308 : : *
309 : : * @return Event identifier.
310 : : *
311 : : * @sa nrfx_event_to_bitpos
312 : : */
313 : : NRF_STATIC_INLINE uint32_t nrfx_bitpos_to_event(uint32_t bit);
314 : :
315 : : /**
316 : : * @brief Function for converting an event identifier to the corresponding
317 : : * INTEN register bit position.
318 : : *
319 : : * The event identifier is the offset between the event register address and
320 : : * the peripheral base address, and is equal (thus, can be directly cast) to
321 : : * the corresponding value of the enumerated type from HAL (nrf_*_event_t).
322 : : *
323 : : * @param[in] event Event identifier.
324 : : *
325 : : * @return INTEN register bit position.
326 : : *
327 : : * @sa nrfx_bitpos_to_event
328 : : */
329 : : NRF_STATIC_INLINE uint32_t nrfx_event_to_bitpos(uint32_t event);
330 : :
331 : :
332 : : #ifndef NRF_DECLARE_ONLY
333 : :
334 : : NRF_STATIC_INLINE bool nrfx_is_in_ram(void const * p_object)
335 : : {
336 : : return ((((uint32_t)p_object) & 0xE0000000u) == 0x20000000u);
337 : : }
338 : :
339 : : NRF_STATIC_INLINE bool nrfx_is_word_aligned(void const * p_object)
340 : : {
341 : : return ((((uint32_t)p_object) & 0x3u) == 0u);
342 : : }
343 : :
344 : 3 : NRF_STATIC_INLINE IRQn_Type nrfx_get_irq_number(void const * p_reg)
345 : : {
346 : 3 : return (IRQn_Type)NRFX_IRQ_NUMBER_GET(p_reg);
347 : : }
348 : :
349 : : NRF_STATIC_INLINE uint32_t nrfx_bitpos_to_event(uint32_t bit)
350 : : {
351 : : static const uint32_t event_reg_offset = 0x100u;
352 : : return event_reg_offset + (bit * sizeof(uint32_t));
353 : : }
354 : :
355 : : NRF_STATIC_INLINE uint32_t nrfx_event_to_bitpos(uint32_t event)
356 : : {
357 : : static const uint32_t event_reg_offset = 0x100u;
358 : : return (event - event_reg_offset) / sizeof(uint32_t);
359 : : }
360 : :
361 : : #endif // NRF_DECLARE_ONLY
362 : :
363 : : /** @} */
364 : :
365 : : #ifdef __cplusplus
366 : : }
367 : : #endif
368 : :
369 : : #endif // NRFX_COMMON_H__
|