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