Software APIs
macros.h
Go to the documentation of this file.
1 // Copyright lowRISC contributors (OpenTitan project).
2 // Licensed under the Apache License, Version 2.0, see LICENSE for details.
3 // SPDX-License-Identifier: Apache-2.0
4 
5 #ifndef OPENTITAN_SW_DEVICE_LIB_BASE_MACROS_H_
6 #define OPENTITAN_SW_DEVICE_LIB_BASE_MACROS_H_
7 
8 // This file may be used in .S files, in which case standard library includes
9 // should be elided.
10 #if !defined(__ASSEMBLER__) && !defined(NOSTDINC)
11 #include <assert.h>
12 #include <stddef.h>
13 #include <stdint.h>
14 
15 #ifdef __cplusplus
16 // The <type_traits> header is required for the C++-only `SignConverter` class.
17 // See `SignConverter` for an explanation of this `extern "C++"` block.
18 extern "C++" {
19 #include <type_traits>
20 }
21 #endif
22 #endif
23 
24 /**
25  * @file
26  * @brief Generic preprocessor macros that don't really fit anywhere else.
27  */
28 
29 /**
30  * Computes the number of elements in the given array.
31  *
32  * Note that this can only determine the length of *fixed-size* arrays. Due to
33  * limitations of C, it will incorrectly compute the size of an array passed as
34  * a function argument, because those automatically decay into pointers. This
35  * function can only be used correctly with:
36  * - Arrays declared as stack variables.
37  * - Arrays declared at global scope.
38  * - Arrays that are members of a struct or union.
39  *
40  * @param array The array expression to measure.
41  * @return The number of elements in the array, as a `size_t`.
42  */
43 // This is a sufficiently well-known macro that we don't really need to bother
44 // with a prefix like the others, and a rename will cause churn.
45 #define ARRAYSIZE(array) (sizeof(array) / sizeof(array[0]))
46 
47 /**
48  * An annotation that a switch/case fallthrough is the intended behavior.
49  */
50 #define OT_FALLTHROUGH_INTENDED __attribute__((fallthrough))
51 
52 /**
53  * A directive to force the compiler to inline a function.
54  */
55 #define OT_ALWAYS_INLINE __attribute__((always_inline)) inline
56 
57 /**
58  * The `restrict` keyword is C specific, so we provide a C++-portable wrapper
59  * that uses the GCC name.
60  *
61  * It only needs to be used in headers; .c files can use `restrict` directly.
62  */
63 #define OT_RESTRICT __restrict__
64 
65 /**
66  * An argument stringification macro.
67  */
68 #define OT_STRINGIFY(a) OT_STRINGIFY_(a)
69 #define OT_STRINGIFY_(a) #a
70 
71 /**
72  * A variable-argument macro that expands to the number of arguments passed into
73  * it, between 0 and 31 arguments.
74  *
75  * This macro is based off of a well-known preprocessor trick. This
76  * StackOverflow post expains the trick in detail:
77  * https://stackoverflow.com/questions/2308243/macro-returning-the-number-of-arguments-it-is-given-in-c
78  * TODO #2026: a dummy token is required for this to work correctly.
79  *
80  * @param dummy a dummy token that is required to be passed for the calculation
81  * to work correctly.
82  * @param ... the variable args list.
83  */
84 #define OT_VA_ARGS_COUNT(dummy, ...) \
85  OT_SHIFT_N_VARIABLE_ARGS_(dummy, ##__VA_ARGS__, 31, 30, 29, 28, 27, 26, 25, \
86  24, 23, 22, 21, 20, 19, 18, 17, 16, 15, 14, 13, \
87  12, 11, 10, 9, 8, 7, 6, 5, 4, 3, 2, 1, 0)
88 
89 // Implementation details for `OT_VA_ARGS_COUNT()`.
90 #define OT_SHIFT_N_VARIABLE_ARGS_(...) OT_GET_NTH_VARIABLE_ARG_(__VA_ARGS__)
91 #define OT_GET_NTH_VARIABLE_ARG_(x0, x1, x2, x3, x4, x5, x6, x7, x8, x9, x10, \
92  x11, x12, x13, x14, x15, x16, x17, x18, x19, \
93  x20, x21, x22, x23, x24, x25, x26, x27, x28, \
94  x29, x30, x31, n, ...) \
95  n
96 
97 /**
98  * An argument concatenation macro.
99  *
100  * Because the `##` operator inhibits expansion, we use a level of indirection
101  * to create a macro which concatenates without inhibition.
102  */
103 #define OT_CAT(a, ...) OT_PRIMITIVE_CAT(a, __VA_ARGS__)
104 #define OT_PRIMITIVE_CAT(a, ...) a##__VA_ARGS__
105 
106 /**
107  * A macro which gets the nth arg from a __VA_LIST__
108  */
109 #define OT_GET_ARG(n, ...) OT_CAT(OT_CAT(OT_GET_ARG_, n), _)(__VA_ARGS__)
110 
111 /**
112  * A macro which gets the last arg from a __VA_LIST__
113  *
114  * Note: we leave out the dummy argument because we want count to
115  * give us the number of args minus one so that the created
116  * OT_GET_ARG_n token will contain the correct integer.
117  */
118 #define OT_GET_LAST_ARG(...) \
119  OT_GET_ARG(OT_VA_ARGS_COUNT(__VA_ARGS__), ##__VA_ARGS__)
120 
121 /**
122  * The following collection of `OT_GET_ARG` macros are used to construct the
123  * generic "get nth arg" macro.
124  */
125 #define OT_GET_ARG_0_(x0, ...) x0
126 #define OT_GET_ARG_1_(x1, x0, ...) x0
127 #define OT_GET_ARG_2_(x2, x1, x0, ...) x0
128 #define OT_GET_ARG_3_(x3, x2, x1, x0, ...) x0
129 #define OT_GET_ARG_4_(x4, x3, x2, x1, x0, ...) x0
130 #define OT_GET_ARG_5_(x5, x4, x3, x2, x1, x0, ...) x0
131 #define OT_GET_ARG_6_(x6, x5, x4, x3, x2, x1, x0, ...) x0
132 #define OT_GET_ARG_7_(x7, x6, x5, x4, x3, x2, x1, x0, ...) x0
133 #define OT_GET_ARG_8_(x8, x7, x6, x5, x4, x3, x2, x1, x0, ...) x0
134 #define OT_GET_ARG_9_(x9, x8, x7, x6, x5, x4, x3, x2, x1, x0, ...) x0
135 #define OT_GET_ARG_10_(x10, x9, x8, x7, x6, x5, x4, x3, x2, x1, x0, ...) x0
136 #define OT_GET_ARG_11_(x11, x10, x9, x8, x7, x6, x5, x4, x3, x2, x1, x0, ...) x0
137 #define OT_GET_ARG_12_(x12, x11, x10, x9, x8, x7, x6, x5, x4, x3, x2, x1, x0, \
138  ...) \
139  x0
140 #define OT_GET_ARG_13_(x13, x12, x11, x10, x9, x8, x7, x6, x5, x4, x3, x2, x1, \
141  x0, ...) \
142  x0
143 #define OT_GET_ARG_14_(x14, x13, x12, x11, x10, x9, x8, x7, x6, x5, x4, x3, \
144  x2, x1, x0, ...) \
145  x0
146 #define OT_GET_ARG_15_(x15, x14, x13, x12, x11, x10, x9, x8, x7, x6, x5, x4, \
147  x3, x2, x1, x0, ...) \
148  x0
149 #define OT_GET_ARG_16_(x16, x15, x14, x13, x12, x11, x10, x9, x8, x7, x6, x5, \
150  x4, x3, x2, x1, x0, ...) \
151  x0
152 #define OT_GET_ARG_17_(x17, x16, x15, x14, x13, x12, x11, x10, x9, x8, x7, x6, \
153  x5, x4, x3, x2, x1, x0, ...) \
154  x0
155 #define OT_GET_ARG_18_(x18, x17, x16, x15, x14, x13, x12, x11, x10, x9, x8, \
156  x7, x6, x5, x4, x3, x2, x1, x0, ...) \
157  x0
158 #define OT_GET_ARG_19_(x19, x18, x17, x16, x15, x14, x13, x12, x11, x10, x9, \
159  x8, x7, x6, x5, x4, x3, x2, x1, x0, ...) \
160  x0
161 #define OT_GET_ARG_20_(x20, x19, x18, x17, x16, x15, x14, x13, x12, x11, x10, \
162  x9, x8, x7, x6, x5, x4, x3, x2, x1, x0, ...) \
163  x0
164 #define OT_GET_ARG_21_(x21, x20, x19, x18, x17, x16, x15, x14, x13, x12, x11, \
165  x10, x9, x8, x7, x6, x5, x4, x3, x2, x1, x0, ...) \
166  x0
167 #define OT_GET_ARG_22_(x22, x21, x20, x19, x18, x17, x16, x15, x14, x13, x12, \
168  x11, x10, x9, x8, x7, x6, x5, x4, x3, x2, x1, x0, ...) \
169  x0
170 #define OT_GET_ARG_23_(x23, x22, x21, x20, x19, x18, x17, x16, x15, x14, x13, \
171  x12, x11, x10, x9, x8, x7, x6, x5, x4, x3, x2, x1, x0, \
172  ...) \
173  x0
174 #define OT_GET_ARG_24_(x24, x23, x22, x21, x20, x19, x18, x17, x16, x15, x14, \
175  x13, x12, x11, x10, x9, x8, x7, x6, x5, x4, x3, x2, x1, \
176  x0, ...) \
177  x0
178 #define OT_GET_ARG_25_(x25, x24, x23, x22, x21, x20, x19, x18, x17, x16, x15, \
179  x14, x13, x12, x11, x10, x9, x8, x7, x6, x5, x4, x3, \
180  x2, x1, x0, ...) \
181  x0
182 #define OT_GET_ARG_26_(x26, x25, x24, x23, x22, x21, x20, x19, x18, x17, x16, \
183  x15, x14, x13, x12, x11, x10, x9, x8, x7, x6, x5, x4, \
184  x3, x2, x1, x0, ...) \
185  x0
186 #define OT_GET_ARG_27_(x27, x26, x25, x24, x23, x22, x21, x20, x19, x18, x17, \
187  x16, x15, x14, x13, x12, x11, x10, x9, x8, x7, x6, x5, \
188  x4, x3, x2, x1, x0, ...) \
189  x0
190 #define OT_GET_ARG_28_(x28, x27, x26, x25, x24, x23, x22, x21, x20, x19, x18, \
191  x17, x16, x15, x14, x13, x12, x11, x10, x9, x8, x7, x6, \
192  x5, x4, x3, x2, x1, x0, ...) \
193  x0
194 #define OT_GET_ARG_29_(x29, x28, x27, x26, x25, x24, x23, x22, x21, x20, x19, \
195  x18, x17, x16, x15, x14, x13, x12, x11, x10, x9, x8, \
196  x7, x6, x5, x4, x3, x2, x1, x0, ...) \
197  x0
198 #define OT_GET_ARG_30_(x30, x29, x28, x27, x26, x25, x24, x23, x22, x21, x20, \
199  x19, x18, x17, x16, x15, x14, x13, x12, x11, x10, x9, \
200  x8, x7, x6, x5, x4, x3, x2, x1, x0, ...) \
201  x0
202 #define OT_GET_ARG_31_(x31, x30, x29, x28, x27, x26, x25, x24, x23, x22, x21, \
203  x20, x19, x18, x17, x16, x15, x14, x13, x12, x11, x10, \
204  x9, x8, x7, x6, x5, x4, x3, x2, x1, x0, ...) \
205  x0
206 
207 /**
208  * A macro that expands to an assertion for the offset of a struct member.
209  *
210  * @param type A struct type.
211  * @param member A member of the struct.
212  * @param offset Expected offset of the member.
213  */
214 #define OT_ASSERT_MEMBER_OFFSET(type, member, offset) \
215  static_assert(offsetof(type, member) == UINT32_C(offset), \
216  "Unexpected offset for " #type "." #member)
217 
218 /**
219  * A macro that expands to an assertion for the offset of a struct member.
220  *
221  * @param type A struct type.
222  * @param member A member of the struct.
223  * @param enum_offset Expected offset of the member as an enum constant.
224  */
225 #define OT_ASSERT_MEMBER_OFFSET_AS_ENUM(type, member, enum_offset) \
226  static_assert(offsetof(type, member) == enum_offset, \
227  "Unexpected offset for " #type "." #member)
228 
229 /**
230  * A macro that expands to an assertion for the size of a struct member.
231  *
232  * @param type A struct type.
233  * @param member A member of the struct.
234  * @param size Expected size of the type.
235  */
236 #define OT_ASSERT_MEMBER_SIZE(type, member, size) \
237  static_assert(sizeof(((type){0}).member) == UINT32_C(size), \
238  "Unexpected size for " #type)
239 
240 /**
241  * A macro that expands to an assertion for the size of a struct member.
242  *
243  * Identical to `OT_ASSERT_MEMBER_SIZE`, except the size parameter is provided
244  * as an enum constant.
245  *
246  * @param type A struct type.
247  * @param member A member of the struct.
248  * @param enum_size Expected size of the type as an enum constant.
249  */
250 #define OT_ASSERT_MEMBER_SIZE_AS_ENUM(type, member, enum_size) \
251  static_assert(sizeof(((type){0}).member) == enum_size, \
252  "Unexpected size for " #type)
253 
254 /**
255  * A macro that expands to an assertion for the size of a type.
256  *
257  * @param type A type.
258  * @param size Expected size of the type.
259  */
260 #define OT_ASSERT_SIZE(type, size) \
261  static_assert(sizeof(type) == UINT32_C(size), "Unexpected size for " #type)
262 
263 /**
264  * A macro that expands to an assertion for an expected enum value.
265  *
266  * @param var An enum entry.
267  * @param expected_value Expected enum value.
268  */
269 #define OT_ASSERT_ENUM_VALUE(var, expected_value) \
270  static_assert(var == expected_value, "Unexpected value for " #var)
271 
272 /**
273  * A variable-argument macro that expands to the number of arguments passed into
274  * it, between 1 and 32 arguments (1 action and 0-31 others).
275  *
276  * This macro accepts a macro name and a variable list of items, and will then
277  * expand to sequentially call the macro with each provided item in order. This
278  * can be useful for performing compile-time checks on arguments in variadic
279  * functions defined via macros.
280  *
281  * For example, OT_VAR_FOR_EACH(TEST, 5, 19, 32, 1, 4) would expand to be
282  * `do {TEST(5); TEST(19); TEST(32); TEST(1); TEST(4);} while (false)`
283  *
284  * @param action The name of the macro to invoke with each item individually.
285  * @param ... The variable args list to call the macro on.
286  */
287 #define OT_VA_FOR_EACH(action, ...) \
288  do { \
289  OT_CAT(OT_CAT(OT_VA_FOR_EACH_, OT_VA_ARGS_COUNT(0, ##__VA_ARGS__)), _) \
290  (action, ##__VA_ARGS__) \
291  } while (false)
292 
293 /**
294  * The following collection of `OT_VA_FOR_EACH` macros are used to construct
295  * the generic "for each" `OT_VA_FOR_EACH` macro.
296  */
297 #define OT_VA_FOR_EACH_0_(action)
298 #define OT_VA_FOR_EACH_1_(action, item, ...) \
299  action(item); \
300  OT_VA_FOR_EACH_0_(action, ##__VA_ARGS__)
301 #define OT_VA_FOR_EACH_2_(action, item, ...) \
302  action(item); \
303  OT_VA_FOR_EACH_1_(action, ##__VA_ARGS__)
304 #define OT_VA_FOR_EACH_3_(action, item, ...) \
305  action(item); \
306  OT_VA_FOR_EACH_2_(action, ##__VA_ARGS__)
307 #define OT_VA_FOR_EACH_4_(action, item, ...) \
308  action(item); \
309  OT_VA_FOR_EACH_3_(action, ##__VA_ARGS__)
310 #define OT_VA_FOR_EACH_5_(action, item, ...) \
311  action(item); \
312  OT_VA_FOR_EACH_4_(action, ##__VA_ARGS__)
313 #define OT_VA_FOR_EACH_6_(action, item, ...) \
314  action(item); \
315  OT_VA_FOR_EACH_5_(action, ##__VA_ARGS__)
316 #define OT_VA_FOR_EACH_7_(action, item, ...) \
317  action(item); \
318  OT_VA_FOR_EACH_6_(action, ##__VA_ARGS__)
319 #define OT_VA_FOR_EACH_8_(action, item, ...) \
320  action(item); \
321  OT_VA_FOR_EACH_7_(action, ##__VA_ARGS__)
322 #define OT_VA_FOR_EACH_9_(action, item, ...) \
323  action(item); \
324  OT_VA_FOR_EACH_8_(action, ##__VA_ARGS__)
325 #define OT_VA_FOR_EACH_10_(action, item, ...) \
326  action(item); \
327  OT_VA_FOR_EACH_9_(action, ##__VA_ARGS__)
328 #define OT_VA_FOR_EACH_11_(action, item, ...) \
329  action(item); \
330  OT_VA_FOR_EACH_10_(action, ##__VA_ARGS__)
331 #define OT_VA_FOR_EACH_12_(action, item, ...) \
332  action(item); \
333  OT_VA_FOR_EACH_11_(action, ##__VA_ARGS__)
334 #define OT_VA_FOR_EACH_13_(action, item, ...) \
335  action(item); \
336  OT_VA_FOR_EACH_12_(action, ##__VA_ARGS__)
337 #define OT_VA_FOR_EACH_14_(action, item, ...) \
338  action(item); \
339  OT_VA_FOR_EACH_13_(action, ##__VA_ARGS__)
340 #define OT_VA_FOR_EACH_15_(action, item, ...) \
341  action(item); \
342  OT_VA_FOR_EACH_14_(action, ##__VA_ARGS__)
343 #define OT_VA_FOR_EACH_16_(action, item, ...) \
344  action(item); \
345  OT_VA_FOR_EACH_15_(action, ##__VA_ARGS__)
346 #define OT_VA_FOR_EACH_17_(action, item, ...) \
347  action(item); \
348  OT_VA_FOR_EACH_16_(action, ##__VA_ARGS__)
349 #define OT_VA_FOR_EACH_18_(action, item, ...) \
350  action(item); \
351  OT_VA_FOR_EACH_17_(action, ##__VA_ARGS__)
352 #define OT_VA_FOR_EACH_19_(action, item, ...) \
353  action(item); \
354  OT_VA_FOR_EACH_18_(action, ##__VA_ARGS__)
355 #define OT_VA_FOR_EACH_20_(action, item, ...) \
356  action(item); \
357  OT_VA_FOR_EACH_19_(action, ##__VA_ARGS__)
358 #define OT_VA_FOR_EACH_21_(action, item, ...) \
359  action(item); \
360  OT_VA_FOR_EACH_20_(action, ##__VA_ARGS__)
361 #define OT_VA_FOR_EACH_22_(action, item, ...) \
362  action(item); \
363  OT_VA_FOR_EACH_21_(action, ##__VA_ARGS__)
364 #define OT_VA_FOR_EACH_23_(action, item, ...) \
365  action(item); \
366  OT_VA_FOR_EACH_22_(action, ##__VA_ARGS__)
367 #define OT_VA_FOR_EACH_24_(action, item, ...) \
368  action(item); \
369  OT_VA_FOR_EACH_23_(action, ##__VA_ARGS__)
370 #define OT_VA_FOR_EACH_25_(action, item, ...) \
371  action(item); \
372  OT_VA_FOR_EACH_24_(action, ##__VA_ARGS__)
373 #define OT_VA_FOR_EACH_26_(action, item, ...) \
374  action(item); \
375  OT_VA_FOR_EACH_25_(action, ##__VA_ARGS__)
376 #define OT_VA_FOR_EACH_27_(action, item, ...) \
377  action(item); \
378  OT_VA_FOR_EACH_26_(action, ##__VA_ARGS__)
379 #define OT_VA_FOR_EACH_28_(action, item, ...) \
380  action(item); \
381  OT_VA_FOR_EACH_27_(action, ##__VA_ARGS__)
382 #define OT_VA_FOR_EACH_29_(action, item, ...) \
383  action(item); \
384  OT_VA_FOR_EACH_28_(action, ##__VA_ARGS__)
385 #define OT_VA_FOR_EACH_30_(action, item, ...) \
386  action(item); \
387  OT_VA_FOR_EACH_29_(action, ##__VA_ARGS__)
388 #define OT_VA_FOR_EACH_31_(action, item, ...) \
389  action(item); \
390  OT_VA_FOR_EACH_30_(action, ##__VA_ARGS__)
391 
392 /**
393  * A macro that checks whether a specified argument is not a standard C integer
394  * type with a width of 64 bits. Useful when assuming that variable arguments
395  * are 32 bits integers.
396  *
397  * @param arg An argument/expression
398  */
399 #define OT_CHECK_NOT_INT64(arg) \
400  _Generic((arg), int64_t: false, uint64_t: false, default: true)
401 
402 /**
403  * A macro that expands to an assertion that wraps the `OT_CHECK_NOT_INT64`
404  * macro, failing with a relevant error message if the provided argument is a
405  * standard C integer type with a width of 64 bits.
406  *
407  * @param arg An argument/expression to check
408  * @param func_name The name of the macro/functionality being invoked, to be
409  * printed in a relevant error if the assertion fails.
410  */
411 #define OT_FAIL_IF_64_BIT(arg, func_name) \
412  do { \
413  static_assert(OT_CHECK_NOT_INT64(arg), \
414  "Argument '" #arg "' passed to the " #func_name \
415  " function must be no wider than 32 bits. " \
416  "Hint: maybe cast with '(uint32_t) " #arg "'?"); \
417  } while (0)
418 
419 /**
420  * A macro representing the OpenTitan execution platform.
421  */
422 #if __riscv_xlen == 32
423 #define OT_PLATFORM_RV32 1
424 #endif
425 
426 /**
427  * A macro indicating whether software should assume reduced hardware
428  * support (for the `top_englishbreakafst` toplevel).
429  */
430 #ifdef OT_IS_ENGLISH_BREAKFAST_REDUCED_SUPPORT_FOR_INTERNAL_USE_ONLY_
431 #define OT_IS_ENGLISH_BREAKFAST 1
432 #endif
433 
434 /**
435  * Attribute for functions which return errors that must be acknowledged.
436  *
437  * This attribute must be used to mark all DIFs which return an error value of
438  * some kind, to ensure that callers do not accidentally drop the error on the
439  * ground.
440  *
441  * Normally, the standard way to drop such a value on the ground explicitly is
442  * with the syntax `(void)expr;`, in analogy with the behavior of C++'s
443  * `[[nodiscard]]` attribute.
444  * However, GCC does not implement this, so the idiom `if (expr) {}` should be
445  * used instead, for the time being.
446  * See https://gcc.gnu.org/bugzilla/show_bug.cgi?id=25509.
447  */
448 #define OT_WARN_UNUSED_RESULT __attribute__((warn_unused_result))
449 
450 /**
451  * Attribute for weak functions that can be overridden, e.g., ISRs.
452  */
453 #define OT_WEAK __attribute__((weak))
454 
455 /**
456  * Attribute to construct functions without prologue/epilogue sequences.
457  *
458  * Only basic asm statements can be safely included in naked functions.
459  *
460  * See https://gcc.gnu.org/onlinedocs/gcc/RISC-V-Function-Attributes.html
461  * #RISC-V-Function-Attributes
462  */
463 #define OT_NAKED __attribute__((naked))
464 
465 /**
466  * Attribute to place symbols into particular sections.
467  *
468  * See https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html
469  * #Common-Function-Attributes
470  */
471 #define OT_SECTION(name) __attribute__((section(name)))
472 
473 /**
474  * Pragma meant to place symbols into a NOBITS section with a specified name.
475  *
476  * This should only be used for zero-initialized globals (including
477  * implicitly zero-initialized ones, when the initializer is missing). The
478  * pragma won't affect variables that do not go into the bss section.
479  *
480  * Example:
481  *
482  * OT_SET_BSS_SECTION(".foo",
483  * uint32_t x; // emitted in section .foo instead of .bss
484  * uint32_t y = 42; // emitted in regular .data section (but don't do this)
485  * )
486  */
487 #define OT_SET_BSS_SECTION(name, ...) \
488  OT_SET_BSS_SECTION_(clang section bss = name) \
489  __VA_ARGS__ \
490  _Pragma("clang section bss = \"\"")
491 #define OT_SET_BSS_SECTION_(section) _Pragma(#section)
492 
493 /**
494  * Attribute to suppress the inlining of a function at its call sites.
495  *
496  * See https://clang.llvm.org/docs/AttributeReference.html#noinline.
497  */
498 #define OT_NOINLINE __attribute__((noinline))
499 
500 /**
501  * Returns the address of the current function stack frame.
502  *
503  * See https://gcc.gnu.org/onlinedocs/gcc/Return-Address.html.
504  */
505 #define OT_FRAME_ADDR() __builtin_frame_address(0)
506 
507 /**
508  * Hints to the compiler that some point is not reachable.
509  *
510  * One use case could be a function that never returns.
511  *
512  * Please not that if the control flow reaches the point of the
513  * __builtin_unreachable, the program is undefined.
514  *
515  * See https://gcc.gnu.org/onlinedocs/gcc/Other-Builtins.html.
516  */
517 #define OT_UNREACHABLE() __builtin_unreachable()
518 
519 /**
520  * Attribute for weak alias that can be overridden, e.g., Mock overrides in
521  * DIFs.
522  */
523 #define OT_ALIAS(name) __attribute__((alias(name)))
524 
525 /**
526  * Defines a local symbol named `kName_` whose address resolves to the
527  * program counter value an inline assembly block at this location would
528  * see.
529  *
530  * The primary intention of this macro is to allow for peripheral tests to be
531  * written that want to assert that a specific program counter reported by the
532  * hardware corresponds to actual code that executed.
533  *
534  * For example, suppose that we're waiting for an interrupt to fire, and want
535  * to verify that it fired in a specific region. We have two volatile globals:
536  * `irq_happened`, which the ISR sets before returning, and `irq_pc`, which
537  * the ISR sets to whatever PC the hardware reports it came from. The
538  * code below tests that the reported PC matches expectations.
539  *
540  * ```
541  * OT_ADDRESSABLE_LABEL(kIrqWaitStart);
542  * enable_interrupts();
543  * while(!irq_happened) {
544  * wait_for_interrupt();
545  * }
546  * OT_ADDRESSABLE_LABEL(kIrqWaitEnd);
547  *
548  * CHECK(irq_pc >= &kIrqWaitStart && irq_pc < &IrqWaitEnd);
549  * ```
550  *
551  * Note that this only works if all functions called between the two labels
552  * are actually inlined; if the interrupt fires inside of one of those two
553  * functions, it will appear to not have the right PC, even though it is
554  * logically inside the pair of labels.
555  *
556  * # Volatile Semantics
557  *
558  * This has the same semantics as a `volatile` inline assembly block: it
559  * may be reordered with respect to all operations except other volatile
560  * operations (i.e. volatile assembly and volatile read/write, such as
561  * MMIO). For example, in the following code, `kBefore` and `kAfter` can
562  * wind up having the same address:
563  *
564  * ```
565  * OT_ADDRESSABLE_LABEL(kBefore);
566  * x += 5;
567  * OT_ADDRESSABLE_LABEL(kAfter);
568  * ```
569  *
570  * Because it can be reordered and the compiler is free to emit whatever
571  * instructions it likes, comparing a program counter value obtained from
572  * the hardware with a symbol emitted by this macro is brittle (and,
573  * ultimately, futile). Instead, it should be used in pairs to create a
574  * range of addresses that a value can be checked for being within.
575  *
576  * For this primitive to work correctly there must be something that counts as
577  * a volatile operation between the two labels. These include:
578  *
579  * - Direct reads or writes to MMIO registers or CSRs.
580  * - A volatile assembly block with at least one instruction.
581  * - Any DIF or driver call that may touch an MMIO register or a CSR.
582  * - `LOG`ging, `printf`ing, or `CHECK`ing.
583  * - `wait_for_interrupt()`.
584  * - `barrier32()`, but NOT `launder32()`.
585  *
586  * This macro should not be used on the host side. It will compile, but will
587  * probably not provide any meaningful values. In the future, it may start
588  * producing a garbage value on the host side.
589  *
590  * # Symbol Access
591  *
592  * The symbol reference `kName_` will only be scoped to the current block
593  * in a function, but it can be redeclared in the same file with
594  *
595  * ```
596  * extern const char kName_[];
597  * ```
598  *
599  * if needed elsewhere (although this should be avoided for readability's sake).
600  * The name of the constant is global to the current `.c` file only.
601  *
602  * # Example Uses
603  */
604 #define OT_ADDRESSABLE_LABEL(kName_) \
605  extern const char kName_[]; \
606  asm volatile(".local " #kName_ "; " #kName_ ":;"); \
607  /* Force this to be at function scope. It could go at global scope, but it \
608  * would give a garbage value dependent on the whims of the linker. */ \
609  do { \
610  } while (false)
611 
612 /**
613  * Evaluates and discards `expr_`.
614  *
615  * This is needed because ‘(void)expr;` does not work for gcc.
616  */
617 #define OT_DISCARD(expr_) \
618  if (expr_) { \
619  }
620 
621 /**
622  * An attribute used for static variables indicating that they should be
623  * retained in the object file, even if they are seemingly unreferenced.
624  */
625 #define OT_USED __attribute__((used))
626 
627 /**
628  * OT_BUILD_FOR_STATIC_ANALYZER indicates whether we are compiling for the
629  * purpose of static analysis. Currently, this macro only detects
630  * Clang-Analyzer, which is used as a backend by Clang-Tidy.
631  */
632 #ifdef __clang_analyzer__
633 #define OT_BUILD_FOR_STATIC_ANALYZER 1
634 #else
635 #define OT_BUILD_FOR_STATIC_ANALYZER 0
636 #endif
637 
638 /**
639  * This macro is used to align an offset to point to a 32b value.
640  */
641 #define OT_ALIGN_MEM(x) (uint32_t)(4 + (((uintptr_t)(x)-1) & ~3u))
642 
643 #if !defined(__ASSEMBLER__) && !defined(NOSTDINC) && \
644  !defined(RUST_PREPROCESSOR_EMIT)
645 #ifndef __cplusplus
646 struct OtSignConversionUnsupportedType {
647  char err;
648 };
649 
650 /**
651  * This macro converts a given unsigned integer value to its signed counterpart.
652  */
653 #define OT_SIGNED(value) \
654  _Generic((value), \
655  uint8_t: (int8_t)(value), \
656  uint16_t: (int16_t)(value), \
657  uint32_t: (int32_t)(value), \
658  uint64_t: (int64_t)(value), \
659  default: (struct OtSignConversionUnsupportedType){.err = 1})
660 
661 /**
662  * This macro converts a given signed integer value to its unsigned counterpart.
663  */
664 #define OT_UNSIGNED(value) \
665  _Generic((value), \
666  int8_t: (uint8_t)(value), \
667  int16_t: (uint16_t)(value), \
668  int32_t: (uint32_t)(value), \
669  int64_t: (uint64_t)(value), \
670  default: (struct OtSignConversionUnsupportedType){.err = 1})
671 #else // __cplusplus
672 // Templates require "C++" linkage. Even though this block is only reachable
673 // when __cplusplus is defined, it's possible that we are in the middle of an
674 // `extern "C"` block. In case that is true, we explicitly set the linkage to
675 // "C++" for the coming C++ templates.
676 extern "C++" {
677 namespace {
678 template <typename T>
679 class SignConverter {
680  public:
681  using SignedT = typename std::make_signed<T>::type;
682  using UnsignedT = typename std::make_unsigned<T>::type;
683  static constexpr SignedT as_signed(T value) {
684  return static_cast<SignedT>(value);
685  }
686  static constexpr UnsignedT as_unsigned(T value) {
687  return static_cast<UnsignedT>(value);
688  }
689 };
690 } // namespace
691 }
692 #define OT_SIGNED(value) (SignConverter<typeof(value)>::as_signed((value)))
693 #define OT_UNSIGNED(value) (SignConverter<typeof(value)>::as_unsigned((value)))
694 #endif // __cplusplus
695 #endif // !defined(__ASSEMBLER__) && !defined(NOSTDINC) &&
696  // !defined(RUST_PREPROCESSOR_EMIT)
697 
698 // This routine makes sure that a condition that can be changed by IRQs
699 // is evaluated inside a critical session. It executes a `wfi` between
700 // evaluations.
701 #define ATOMIC_WAIT_FOR_INTERRUPT(_volatile_condition) \
702  while (true) { \
703  irq_global_ctrl(false); \
704  if ((_volatile_condition)) { \
705  break; \
706  } \
707  wait_for_interrupt(); \
708  irq_global_ctrl(true); \
709  } \
710  irq_global_ctrl(true)
711 
712 /**
713  * Macros for implementing OT ISRs.
714  */
715 #define OT_WORD_SIZE 4
716 #define OT_HALF_WORD_SIZE (OT_WORD_SIZE / 2)
717 // The ISR context size is 30 words. There are 32 cpu registers; 30 of them
718 // need to be saved. The two that do not are `sp` and `gp` (x2 and x3).
719 #define OT_CONTEXT_SIZE (OT_WORD_SIZE * 30)
720 
721 #endif // OPENTITAN_SW_DEVICE_LIB_BASE_MACROS_H_
Return to OpenTitan Documentation