1 /***************************************************************************//**
2 * @file
3 * @brief General purpose utilities.
4 *******************************************************************************
5 * # License
6 * <b>Copyright 2021 Silicon Laboratories Inc. www.silabs.com</b>
7 *******************************************************************************
8 *
9 * SPDX-License-Identifier: Zlib
10 *
11 * The licensor of this software is Silicon Laboratories Inc.
12 *
13 * This software is provided 'as-is', without any express or implied
14 * warranty. In no event will the authors be held liable for any damages
15 * arising from the use of this software.
16 *
17 * Permission is granted to anyone to use this software for any purpose,
18 * including commercial applications, and to alter it and redistribute it
19 * freely, subject to the following restrictions:
20 *
21 * 1. The origin of this software must not be misrepresented; you must not
22 * claim that you wrote the original software. If you use this software
23 * in a product, an acknowledgment in the product documentation would be
24 * appreciated but is not required.
25 * 2. Altered source versions must be plainly marked as such, and must not be
26 * misrepresented as being the original software.
27 * 3. This notice may not be removed or altered from any source distribution.
28 *
29 ******************************************************************************/
30
31 #ifndef SL_COMMON_H
32 #define SL_COMMON_H
33
34 #include <stdint.h>
35 #include <stdbool.h>
36 #include "sl_assert.h"
37
38 #ifdef __cplusplus
39 extern "C" {
40 #endif
41
42 #if !defined(__STATIC_INLINE)
43 #if !defined(__unix__) && defined(__arm__)
44 /* Compiler agnostic definitions */
45 #include "cmsis_compiler.h"
46 #elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L)
47 #define __STATIC_INLINE static inline
48 #else
49 #warning Please provide a macro for your compiler and architecture
50 #define __STATIC_INLINE static
51 #endif
52 #endif
53
54 /***************************************************************************//**
55 * @addtogroup common COMMON - Common Utilities
56 * @brief General purpose utilities and cross-compiler support
57 * @details
58 * This SDK supports the following compilers/IDEs:
59 * @li Simplicity Studio
60 * @li IAR Embedded Workbench
61 * @li Keil uVision IDE
62 * @li Plain armgcc
63 *
64 * Certain compiler features such as alignment is implemented differently in the tools.
65 * Therefore, macros such as @ref SL_ALIGN are provided to enable compiler independent
66 * code.
67 *
68 * @note RAM code macros are implemented in [RAMFUNC](/gecko-platform/<docspace-docleaf-version>/emlib-efm32g/).
69 * Cross-compiler RAM code support needs extended documentation and it is therefore
70 * implemented as a separate module.
71 *
72 * @{
73 ******************************************************************************/
74
75 /** @brief Macros to concatenate. */
76 #define SL_CONCAT_PASTER_2(first, second) first ## second ///< sl concat paster 2.
77 #define SL_CONCAT_PASTER_3(first, second, third) first ## second ## third ///< sl concat paster 3.
78 #define SL_CONCAT_PASTER_4(first, second, third, fourth) first ## second ## third ## fourth ///< sl concat paster 4.
79
80 /** @brief Round n up to closest interval of i. */
81 #define SL_CEILING(n, i) ((((n) + (i) - 1U) / (i)) * (i))
82
83 /** @brief Round n down to closest interval of i. */
84 #define SL_FLOOR(n, i) ((n / i) * i)
85
86 /** @brief Stringify X */
87 #define STRINGIZE(X) #X
88
89 #if !defined(__GNUC__)
90 /* Not GCC compilers */
91
92 /** @brief Macro for getting minimum value. */
93 #define SL_MIN(a, b) ((a) < (b) ? (a) : (b))
94
95 /** @brief Macro for getting maximum value. */
96 #define SL_MAX(a, b) ((a) > (b) ? (a) : (b))
97
98 /** @brief Macros for handling packed structures. */
99 #define SL_PACK_START(X) _Pragma(STRINGIZE(pack(X)))
100 #define SL_PACK_END() _Pragma("pack()")
101 #define SL_ATTRIBUTE_PACKED
102
103 #if defined(__CC_ARM)
104 /** @brief MDK-ARM compiler: Macros for handling aligned structures. */
105 #define SL_ALIGN(X) __align(X)
106
107 /** MDK-ARM compiler: Macro for handling weak symbols. */
108 #define SL_WEAK __attribute__ ((weak))
109
110 /** MDK-ARM compiler: Macro for handling non-returning functions. */
111 #define SL_NORETURN __attribute__ ((noreturn))
112
113 /** MDK-ARM compiler: Macro for handling section placement */
114 #define SL_ATTRIBUTE_SECTION(X) __attribute__ ((section(X)))
115 #endif
116
117 #if defined(__ICCARM__)
118
119 #if (__VER__ >= 8000000)
120 /** @brief Obsoleted macro from version 8.00 and on . */
121 #define _STD_BEGIN
122 /** @brief Obsoleted macro from version 8.00 and on . */
123 #define _STD_END
124 #endif
125
126 /** @brief IAR Embedded Workbench: Macros for handling aligned structures. */
127 #define SL_ALIGN(X) _Pragma(STRINGIZE(data_alignment = X))
128
129 /** @brief IAR Embedded Workbench: Macros for handling weak symbols. */
130 #define SL_WEAK __weak
131
132 /** @brief IAR Embedded Workbench: Macro for handling non-returning functions. */
133 #define SL_NORETURN __noreturn
134
135 /* *INDENT-OFF* */
136 /** IAR Embedded Workbench: Macro for handling section placement */
137 #define SL_ATTRIBUTE_SECTION(X) @ X
138 #endif
139 /* *INDENT-ON* */
140
141 #define SL_ATTRIBUTE_ALIGN(X)
142
143 /** @brief Macro for notifying the compiler of an intended
144 * switch case fallthrough. */
145 #define SL_FALLTHROUGH
146
147 /** @brief A macro for notifying the compiler to ignore type limit check. */
148 #define SL_IGNORE_TYPE_LIMIT_BEGIN
149 #define SL_IGNORE_TYPE_LIMIT_END
150
151 #else // !defined(__GNUC__)
152 /* GCC compilers */
153
154 /** @brief A macro for getting the minimum value. No side-effects, a and b are evaluated one time only. */
155 #define SL_MIN(a, b) __extension__({ __typeof__(a)_a = (a); __typeof__(b)_b = (b); _a < _b ? _a : _b; })
156
157 /** @brief A macro for getting the maximum value. No side-effects, a and b are evaluated one time only. */
158 #define SL_MAX(a, b) __extension__({ __typeof__(a)_a = (a); __typeof__(b)_b = (b); _a > _b ? _a : _b; })
159
160 /** @brief A GCC style macro for handling packed structures. */
161 #define SL_ATTRIBUTE_PACKED __attribute__ ((packed))
162
163 /** @brief A macro for handling packed structures.
164 * @n Use this macro before the structure definition.
165 * @n X denotes the maximum alignment of structure members. X is not supported with
166 * GCC. GCC always uses 1 byte maximum alignment.
167 */
168 #define SL_PACK_START(x)
169
170 /** @brief A macro for handling packed structures.
171 * @n Use this macro after the structure definition.
172 * @n With GCC, add SL_ATTRIBUTE_PACKED after the closing curly braces of the structure
173 * definition.
174 */
175 #define SL_PACK_END()
176
177 /** @brief GCC style macro for aligning a variable. */
178 #define SL_ATTRIBUTE_ALIGN(X) __attribute__ ((aligned(X)))
179
180 /** @brief A macro for aligning a variable.
181 * @n Use this macro before the variable definition.
182 * @n X denotes the storage alignment value in bytes.
183 * @n To be GCC-compatible, use SL_ATTRIBUTE_ALIGN(X) before the semicolon on normal
184 * variables. Use SL_ATTRIBUTE_ALIGN(X) before the opening curly brace on structure variables.
185 */
186 #define SL_ALIGN(X)
187
188 /** @brief A macro for defining a weak symbol. */
189 #define SL_WEAK __attribute__ ((weak))
190
191 /** @brief A macro for handling non-returning functions. */
192 #define SL_NORETURN __attribute__ ((noreturn))
193
194 /** A macro for placing a variable in a section.
195 * @n Use this macro after the variable definition, before the equal sign or a semicolon.
196 * @n X denotes the section to place the variable in.
197 */
198 #define SL_ATTRIBUTE_SECTION(X) __attribute__ ((section(X)))
199
200 /** @brief A macro for notifying the compiler of an intended
201 * switch case fallthrough. */
202 #if __GNUC__ >= 7
203 #define SL_FALLTHROUGH __attribute__ ((fallthrough));
204 #else
205 #define SL_FALLTHROUGH
206 #endif
207
208 /** @brief A macro for notifying the compiler to ignore type limit check. */
209 #if __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 6)
210 #define SL_IGNORE_TYPE_LIMIT_BEGIN \
211 _Pragma("GCC diagnostic push") \
212 _Pragma("GCC diagnostic ignored \"-Wtype-limits\"")
213 #define SL_IGNORE_TYPE_LIMIT_END \
214 _Pragma("GCC diagnostic pop")
215 #else
216 #define SL_IGNORE_TYPE_LIMIT_BEGIN
217 #define SL_IGNORE_TYPE_LIMIT_END ///< A MACRO to notify the compiler, limit END.
218 #endif
219
220 #endif // !defined(__GNUC__)
221
222 /** @cond DO_NOT_INCLUDE_WITH_DOXYGEN */
223
224 /** @brief
225 * Macro for marking deprecated functions
226 *
227 * @details
228 * SL_DEPRECATED_API_SDK_<RELEASE> is used to mark functions that are
229 * deprecated and should not be used from a given version of the SDK.
230 * The accompanying SL_SUPPRESS_DEPRECATION_WARNINGS_SDK_<RELEASE>
231 * define can be set to suppress warnings generated when using
232 * deprecated APIs.
233 */
234 #ifdef SL_SUPPRESS_DEPRECATION_WARNINGS_SDK_3_0
235 #define SL_DEPRECATED_API_SDK_3_0
236 #else
237 #define SL_DEPRECATED_API_SDK_3_0 __attribute__ ((deprecated))
238 #endif
239
240 #ifdef SL_SUPPRESS_DEPRECATION_WARNINGS_SDK_3_2
241 #define SL_DEPRECATED_API_SDK_3_2
242 #else
243 #define SL_DEPRECATED_API_SDK_3_2 __attribute__ ((deprecated))
244 #endif
245
246 #ifdef SL_SUPPRESS_DEPRECATION_WARNINGS_SDK_3_3
247 #define SL_DEPRECATED_API_SDK_3_3
248 #else
249 #define SL_DEPRECATED_API_SDK_3_3 __attribute__ ((deprecated))
250 #endif
251
252 #ifdef SL_SUPPRESS_DEPRECATION_WARNINGS_SDK_4_1
253 #define SL_DEPRECATED_API_SDK_4_1
254 #else
255 #define SL_DEPRECATED_API_SDK_4_1 __attribute__ ((deprecated))
256 #endif
257
258 #ifdef SL_SUPPRESS_DEPRECATION_WARNINGS_SDK_4_2
259 #define SL_DEPRECATED_API_SDK_4_2
260 #else
261 #define SL_DEPRECATED_API_SDK_4_2 __attribute__ ((deprecated))
262 #endif
263
264 #ifdef SL_SUPPRESS_DEPRECATION_WARNINGS_SDK_4_4
265 #define SL_DEPRECATED_API_SDK_4_4
266 #else
267 #define SL_DEPRECATED_API_SDK_4_4 __attribute__ ((deprecated))
268 #endif
269 /** @endcond */
270
271 /***************************************************************************//**
272 * @brief
273 * Count trailing number of zeros. Use CLZ instruction if available.
274 *
275 * @param[in] value
276 * Data value to check for number of trailing zero bits.
277 *
278 * @return
279 * A number of trailing zeros in value.
280 ******************************************************************************/
SL_CTZ(uint32_t value)281 __STATIC_INLINE uint32_t SL_CTZ(uint32_t value)
282 {
283 #if defined(__CORTEX_M) && (__CORTEX_M >= 3U)
284 return __CLZ(__RBIT(value));
285
286 #else
287 uint32_t zeros;
288 for (zeros = 0; (zeros < 32) && ((value & 0x1) == 0); zeros++, value >>= 1) {
289 ;
290 }
291 return zeros;
292 #endif
293 }
294
295 /** @cond DO_NOT_INCLUDE_WITH_DOXYGEN */
296 /* Deprecated function. New code should use @ref SL_CTZ. */
EFM32_CTZ(uint32_t value)297 __STATIC_INLINE uint32_t EFM32_CTZ(uint32_t value)
298 {
299 return SL_CTZ(value);
300 }
301 /** @endcond */
302
303 /***************************************************************************//**
304 * @brief
305 * Reverse the bits. Use the RBIT instruction if available, else process.
306 *
307 * @param[in] value
308 * Data value to reverse.
309 *
310 * @return
311 * A reversed value.
312 ******************************************************************************/
SL_RBIT(uint32_t value)313 __STATIC_INLINE uint32_t SL_RBIT(uint32_t value)
314 {
315 uint32_t result;
316
317 #if defined(__CORTEX_M) && (__CORTEX_M >= 0x03U)
318 result = __RBIT(value);
319 #else
320 int32_t s = 4 * 8 - 1;
321
322 result = value;
323 for (value >>= 1U; value != 0U; value >>= 1U) {
324 result <<= 1U;
325 result |= value & 1U;
326 s--;
327 }
328 result <<= s;
329 #endif
330 return result;
331 }
332
333 /***************************************************************************//**
334 * @brief
335 * Reverse the bits. Use the RBIT instruction if available, else process.
336 *
337 * @param[in] value
338 * 16-bit data value to reverse.
339 *
340 * @return
341 * A 16-bit reversed value.
342 ******************************************************************************/
SL_RBIT16(uint16_t value)343 __STATIC_INLINE uint16_t SL_RBIT16(uint16_t value)
344 {
345 return (uint16_t)(SL_RBIT(value) >> 16);
346 }
347
348 /***************************************************************************//**
349 * @brief
350 * Reverse the bits. Use the RBIT instruction if available, else process.
351 *
352 * @param[in] value
353 * 8-bit data value to reverse.
354 *
355 * @return
356 * A 8-bit reversed value.
357 ******************************************************************************/
SL_RBIT8(uint8_t value)358 __STATIC_INLINE uint8_t SL_RBIT8(uint8_t value)
359 {
360 return (uint8_t)(SL_RBIT(value) >> 24);
361 }
362
363 /***************************************************************************//**
364 * @brief
365 * Convert logarithm of 2 to division factor.
366 *
367 * @param[in] log2
368 * Logarithm of 2.
369 *
370 * @return
371 * Dividend.
372 ******************************************************************************/
SL_Log2ToDiv(uint32_t log2)373 __STATIC_INLINE uint32_t SL_Log2ToDiv(uint32_t log2)
374 {
375 EFM_ASSERT(log2 < 32U);
376 return 1UL << log2;
377 }
378
379 /** @} (end addtogroup common) */
380
381 #ifdef __cplusplus
382 }
383 #endif
384
385 #endif /* SL_COMMON_H */
386
