Atomic-context checking (reloco-atomic-context)
reloco-atomic-context is a reloco-tidy check that finds sleeping inside atomic context and
atomic-only calls made outside it, statically. Annotations live in
<reloco/atomic_context.hpp>; every macro expands to nothing when clang::annotate is unavailable.
Rules
- A call to a
RELOCO_MIGHT_SLEEPfunction (or a function that transitively calls one, through visible bodies) is reported while atomic depth may be > 0 on any path reaching it. - A call to a
RELOCO_ATOMIC_ONLYfunction is reported when atomic depth is 0 on some path. - A function marked both
RELOCO_MIGHT_SLEEPandRELOCO_ATOMIC_ONLY/RELOCO_ATOMIC_ENTRYis reported at its declaration. - Atomic depth rises when a scope object comes into existence (constructor, by-value return, copy/move)
and falls when it is destroyed;
RELOCO_ENTER_ATOMIC/RELOCO_LEAVE_ATOMICcalls do the same explicitly (leave clamps at 0). - The body of an
RELOCO_ATOMIC_ONLY/RELOCO_ATOMIC_ENTRYfunction, or of one taking aRELOCO_ATOMIC_TOKENparameter, starts at depth 1. - A lambda is analysed in the state where it is created; a lambda passed to a
RELOCO_ATOMIC_CALLBACKparameter gets one extra level.
Macros
| Macro | Placed on | Meaning |
|---|---|---|
RELOCO_MIGHT_SLEEP |
function / member | May block. Annotate individual members, not whole mutex classes (try_lock/unlock don’t sleep). |
RELOCO_ATOMIC_ONLY |
function | Callable only in atomic context. |
RELOCO_ATOMIC_ENTRY |
function | Body runs atomic (e.g. interrupt handler); may not sleep. |
RELOCO_ATOMIC_SCOPE |
class | Live object = atomic context (irq/preemption guards). |
RELOCO_ATOMIC_LOCK |
class | Lock type; guards over it become scopes. |
RELOCO_ATOMIC_GUARD |
class template | Specialisation over an ATOMIC_LOCK type is a scope. |
RELOCO_ENTER_ATOMIC / RELOCO_LEAVE_ATOMIC |
function | Explicit depth +1 / -1 (lock() / unlock()). |
RELOCO_ATOMIC_CALLBACK |
parameter | Callable argument runs atomic. |
RELOCO_ATOMIC_TOKEN |
class | Proof-of-atomic-context parameter type. |
RELOCO_ATOMIC_EXEMPT |
function | Suppress findings and sleep inference. |
RELOCO_ACQUIRES(n) / RELOCO_RELEASES(n) / RELOCO_TRY_ACQUIRES(n) / RELOCO_LEGACY_LOCK |
function / type | Free-function and legacy lock support (see lock-annotations.md). |
RELOCO_LOCK_IMPL |
function | Lock implementation: may return with a lock held (see lock-discipline.md). |
Example
#include <reloco/atomic_context.hpp>
// Sleeps: waits for a mutex.
RELOCO_MIGHT_SLEEP void wait_for_io();
// Scope class: while an object lives, we are atomic.
struct RELOCO_ATOMIC_SCOPE irq_off { irq_off(); ~irq_off(); };
// Needs atomic context (e.g. touches CPU-local data).
RELOCO_ATOMIC_ONLY void touch_cpu_local();
void f() {
touch_cpu_local(); // reported: not atomic here
{
irq_off g; // depth 1
touch_cpu_local(); // ok
wait_for_io(); // reported: sleeping in atomic context
}
wait_for_io(); // ok: scope ended
}
// Token parameter: caller must prove atomic context; body starts at depth 1.
struct RELOCO_ATOMIC_TOKEN irq_token {};
void g(irq_token);
// Callback runs atomic; a sleeping call inside the lambda is reported.
template <class F> void with_irq_off(F &&fn RELOCO_ATOMIC_CALLBACK);
Exemptions
RELOCO_ATOMIC_EXEMPT on the function, // NOLINT(reloco-atomic-context) on the line, or a
reloco unsafe region.
Limits
- One atomic level; IRQ-off, preemption-off and held spinlock are not distinguished.
core_pin_guard(migration only) is deliberately not a scope, andper_cpu_ptr::get()is not atomic-only. - Joins are path-insensitive:
if (f) lock(); ... if (f) unlock();leaves depth possibly 1 and may produce a false positive (use NOLINT). - Lambdas are judged where created, not where invoked.
try_lockis not an enter.- Sleep inference only follows visible bodies and does not descend into lambdas.
Integration
reloco annotates: mutex/recursive_mutex/shared_mutex lock/lock_shared, condition_variable::wait*,
thread::join (MIGHT_SLEEP); spin_lock (ATOMIC_LOCK with enter/leave); unique_lock
(ATOMIC_GUARD). structo annotates irq_guard, preemption_guard, spinlock_entry_guard and the
spinlock guards (ATOMIC_SCOPE), their tokens (ATOMIC_TOKEN), with_* helpers
(ATOMIC_CALLBACK) and the kernel spinlocks (ATOMIC_LOCK). Run with
clang-tidy --checks='-*,reloco-atomic-context'.