Documentation/dev-tools/context-analysis.rst

Source file repositories/reference/linux-study-clean/Documentation/dev-tools/context-analysis.rst

File Facts

System
Linux kernel
Corpus path
Documentation/dev-tools/context-analysis.rst
Extension
.rst
Size
7154 bytes
Lines
170
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

struct my_data {
            spinlock_t lock;
            int counter __guarded_by(&lock);
    };

    void init_my_data(struct my_data *d)
    {
            ...
            guard(spinlock_init)(&d->lock);
            d->counter = 0;
            ...
    }

Alternatively, initializing guarded variables can be done with context analysis
disabled, preferably in the smallest possible scope (due to lack of any other
checking): either with a ``context_unsafe(var = init)`` expression, or by
marking small initialization functions with the ``__context_unsafe(init)``
attribute.

Lockdep assertions, such as `lockdep_assert_held()`, inform the compiler's
context analysis that the associated synchronization primitive is held after
the assertion. This avoids false positives in complex control-flow scenarios
and encourages the use of Lockdep where static analysis is limited. For
example, this is useful when a function doesn't *always* require a lock, making
`__must_hold()` inappropriate.

Keywords
~~~~~~~~

.. kernel-doc:: include/linux/compiler-context-analysis.h
   :identifiers: context_lock_struct
                 token_context_lock token_context_lock_instance
                 __guarded_by __pt_guarded_by
                 __must_hold
                 __must_not_hold
                 __acquires
                 __cond_acquires
                 __releases
                 __must_hold_shared
                 __acquires_shared
                 __cond_acquires_shared
                 __releases_shared
                 __acquire
                 __release
                 __acquire_shared
                 __release_shared
                 __acquire_ret
                 __acquire_shared_ret
                 context_unsafe
                 __context_unsafe
                 disable_context_analysis enable_context_analysis

.. note::
   The function attribute `__no_context_analysis` is reserved for internal
   implementation of context lock types, and should be avoided in normal code.

Background
----------

Clang originally called the feature `Thread Safety Analysis
<https://clang.llvm.org/docs/ThreadSafetyAnalysis.html>`_, with some keywords
and documentation still using the thread-safety-analysis-only terminology. This
was later changed and the feature became more flexible, gaining the ability to
define custom "capabilities". Its foundations can be found in `Capability
Systems <https://www.cs.cornell.edu/talc/papers/capabilities.pdf>`_, used to
specify the permissibility of operations to depend on some "capability" being
held (or not held).

Because the feature is not just able to express capabilities related to
synchronization primitives, and "capability" is already overloaded in the

Annotation

Implementation Notes