ra8_attributes.h

Go to the documentation of this file.

 
#pragma once
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* =============================================================================
 * Backend selection
 *
 * Each RA8_* annotation macro lowers to `[[clang::annotate("...")]]` under
 * clang and is exposed through libclang as `clang_Cursor_getAnnotations`. The
 * C23/C++11 attribute-specifier form is used (not the GNU
 * `__attribute__((annotate(...)))` form) because it is the spelling libclang
 * surfaces on a declaration. GCC parses the same syntax silently but does not
 * surface it; either way codegen is unaffected. We gate on `__clang__` so
 * non-clang toolchains compile a literal no-op (a pure comment placeholder).
 *
 * These annotations attach to a DECLARATION -- a function, variable, or type --
 * and NOWHERE ELSE. `[[clang::annotate]]` is not valid in statement position:
 * clang rejects `[[clang::annotate("x")]] for (...)` as "'annotate' attribute
 * cannot be applied to a statement", and under a non-clang toolchain the
 * comment no-op evaporates, binding to nothing. A per-LOOP bound therefore
 * cannot be one of these annotations, and a statement-position
 * `RA8_BOUNDED_LOOP(x);` was for that reason a hard clang error and a silent
 * GCC no-op that bound to no loop at all. `RA8_BOUNDED_LOOP` (section 15) is a
 * FUNCTION-level annotation: it decorates the function declaration and the
 * checker walks that function's loops. To bind a bound to ONE specific loop in
 * statement position, use `RA8_LOOP_BOUND` / `RA8_LOOP_BOUND_RUNTIME`
 * (sections 15b/15c) -- these are real C (a `static_assert`, or a symbol
 * reference), not annotations, so they compile and are enforced identically
 * under every toolchain and cannot degrade to a no-op.
 *
 * `__CPPCHECK__` is excluded because cppcheck's C parser cannot represent a
 * scoped attribute carrying a string argument: on `[[clang::annotate("x")]]`
 * it mis-parses the declaration that follows, and the damaged parse surfaces
 * as phantom MISRA findings in the annotated function (14.2 / 16.2 / 17.3
 * appearing where the source has no loop, no switch and no implicit
 * declaration, plus inflated 15.5 exit-point counts). cppcheck explores both
 * arms of the `#ifdef` above, so without this exclusion the audit reports the
 * defects of a configuration that is never built. The firmware ships compiled
 * by arm-none-eabi-gcc, where these macros are already comments -- pinning
 * cppcheck to that arm analyses the code that actually ships, and keeps the
 * annotation visible to clang-tidy and to the libclang annotation gate
 * (`scripts/checks/check_annotations.py`), neither of which defines
 * `__CPPCHECK__`. Suppressing the rules or absorbing the findings into the
 * MISRA baseline instead would blind the ratchet to real defects in every
 * annotated file.
 * =============================================================================
 */
 
#if defined(__clang__) && !defined(__CPPCHECK__)
#define RA8_INTERNAL_ANNOTATE(tag) [[clang::annotate(tag)]]
#else
#define RA8_INTERNAL_ANNOTATE(tag) /* annotation: tag */
#endif

#define RA8_INTERNAL_ANNOTATE_ARG(tag, arg) RA8_INTERNAL_ANNOTATE(tag arg)

#define RA8_NODISCARD __attribute__((warn_unused_result)) /* ATTR-OK: cppcheck 2.13, C23 gap */
 
/* =============================================================================
 * 1. RA8_TEST_HELPER
 * =============================================================================
 */

#define RA8_TEST_HELPER RA8_INTERNAL_ANNOTATE("ra8_test_helper")
 
/* =============================================================================
 * 2. RA8_INTERNAL
 * =============================================================================
 */

#define RA8_INTERNAL RA8_INTERNAL_ANNOTATE("ra8_internal")
 
/* =============================================================================
 * 3. RA8_PRIV
 * =============================================================================
 */

#define RA8_PRIV RA8_INTERNAL_ANNOTATE("ra8_priv")
 
/* =============================================================================
 * 4. RA8_DI_SLOT(role)
 * =============================================================================
 */

#define RA8_DI_SLOT(role) RA8_INTERNAL_ANNOTATE_ARG("ra8_di_slot:", role)
 
/* =============================================================================
 * 5. RA8_NSC_VENEER
 * =============================================================================
 */

#define RA8_NSC_VENEER RA8_INTERNAL_ANNOTATE("ra8_nsc_veneer")
 
/* =============================================================================
 * 6. RA8_HW_REGISTER_ACCESS
 * =============================================================================
 */

#define RA8_HW_REGISTER_ACCESS RA8_INTERNAL_ANNOTATE("ra8_hw_register_access")
 
/* =============================================================================
 * 7. RA8_NASA_RULE_3_OK(reason)
 * =============================================================================
 */

#define RA8_NASA_RULE_3_OK(reason) RA8_INTERNAL_ANNOTATE_ARG("ra8_nasa_rule_3_ok:", reason)
 
/* =============================================================================
 * 8. RA8_MCDC_DEACTIVATED(reason)
 * =============================================================================
 */

#define RA8_MCDC_DEACTIVATED(reason) RA8_INTERNAL_ANNOTATE_ARG("ra8_mcdc_deactivated:", reason)
 
/* =============================================================================
 * 9. RA8_MAX_STACK(bytes)
 * =============================================================================
 */

#define RA8_MAX_STACK(bytes) RA8_INTERNAL_ANNOTATE("ra8_max_stack:" #bytes)
 
/* =============================================================================
 * 10. RA8_ISR_SAFE
 * =============================================================================
 */

#define RA8_ISR_SAFE RA8_INTERNAL_ANNOTATE("ra8_isr_safe")
 
/* =============================================================================
 * 11. RA8_EXPECTS_LOCK(name)
 * =============================================================================
 */

#define RA8_EXPECTS_LOCK(name) RA8_INTERNAL_ANNOTATE_ARG("ra8_expects_lock:", name)
 
/* =============================================================================
 * 12. RA8_HOST_FRIENDLY
 * =============================================================================
 */

#define RA8_HOST_FRIENDLY RA8_INTERNAL_ANNOTATE("ra8_host_friendly")
 
/* =============================================================================
 * 13. RA8_LATENCY_BUDGET_NS(n)
 * =============================================================================
 */

#define RA8_LATENCY_BUDGET_NS(n) RA8_INTERNAL_ANNOTATE("ra8_latency_budget_ns:" #n)
 
/* =============================================================================
 * 14. RA8_NO_RECURSION
 * =============================================================================
 */

#define RA8_NO_RECURSION RA8_INTERNAL_ANNOTATE("ra8_no_recursion")
 
/* =============================================================================
 * 15. RA8_BOUNDED_LOOP(symbol)
 * =============================================================================
 */

#define RA8_BOUNDED_LOOP(symbol) RA8_INTERNAL_ANNOTATE("ra8_bounded_loop:" #symbol)
 
/* =============================================================================
 * 15b. RA8_LOOP_BOUND(ceiling)
 * =============================================================================
 */

#define RA8_LOOP_BOUND(ceiling)                                                                    \
  static_assert((uint32_t)(ceiling) > 0U,                                                          \
                "RA8_LOOP_BOUND requires a positive compile-time constant bound")
 
/* =============================================================================
 * 15c. RA8_LOOP_BOUND_RUNTIME(ceiling_ref)
 * =============================================================================
 */

#define RA8_LOOP_BOUND_RUNTIME(ceiling_ref) ((void)sizeof(&(ceiling_ref)))
 
/* =============================================================================
 * 16. RA8_VALIDATES(n)
 * =============================================================================
 */

#define RA8_VALIDATES(n) RA8_INTERNAL_ANNOTATE("ra8_validates:" #n)
 
/* =============================================================================
 * 17. RA8_OWNS_RESOURCE(kind)
 * =============================================================================
 */

#define RA8_OWNS_RESOURCE(kind) RA8_INTERNAL_ANNOTATE_ARG("ra8_owns_resource:", kind)

#define RA8_RELEASES_RESOURCE(kind) RA8_INTERNAL_ANNOTATE_ARG("ra8_releases_resource:", kind)
 
/* =============================================================================
 * 18. RA8_REVIEWED_BY(name)
 * =============================================================================
 */

#define RA8_REVIEWED_BY(name) RA8_INTERNAL_ANNOTATE_ARG("ra8_reviewed_by:", name)
 
/* =============================================================================
 * 19. RA8_REGISTER_BANK(peripheral)
 * =============================================================================
 */

#define RA8_REGISTER_BANK(peripheral) RA8_INTERNAL_ANNOTATE_ARG("ra8_register_bank:", peripheral)
 
#ifdef __cplusplus
}
#endif