From nobody Tue Dec 2 02:06:42 2025 Received: from mail-wm1-f74.google.com (mail-wm1-f74.google.com [209.85.128.74]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 30CD82E8B86 for ; Thu, 20 Nov 2025 15:02:58 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.128.74 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1763650997; cv=none; b=Igpt1ZtdNa1RIoy3vhWUb6HP2HP4c72r9X5JujOcCmA0lcP48Aatm21dJ4gckwsKi+CAKH4OWTmsgeg4D1cHtRDbWkeH0kweB55rtjZATrk4IXXVpUrwERb0RWwrEKPxZNM4ImEt12dQExtD6agoZMImOTuHQ8gaLITBTukT4/I= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1763650997; c=relaxed/simple; bh=RlAtbvGe2o7GLZNK2osXwConM8SMxqUIfv+xbK8o9+E=; h=Date:In-Reply-To:Mime-Version:References:Message-ID:Subject:From: To:Cc:Content-Type; b=Z5Cj6gIUg3JF1+kJ9OSccvzH0Q0HC/viHX2rgs5k5l1WMxdwHEZSEYRqwAr2E00ho7HvPmmdNxiO51Y2vcCPTNR0LZbnCa4BRnKd80jQzahWHCv6fF/9YDmr3oP/j3jR8Pck2xxZn58/wRMI35Elo34yHybo5eG8VdtQl5XeTBw= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=google.com; spf=pass smtp.mailfrom=flex--elver.bounces.google.com; dkim=pass (2048-bit key) header.d=google.com header.i=@google.com header.b=NKoFanqO; arc=none smtp.client-ip=209.85.128.74 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=google.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=flex--elver.bounces.google.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=google.com header.i=@google.com header.b="NKoFanqO" Received: by mail-wm1-f74.google.com with SMTP id 5b1f17b1804b1-47106a388cfso6313975e9.0 for ; Thu, 20 Nov 2025 07:02:58 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20230601; t=1763650976; x=1764255776; darn=vger.kernel.org; h=cc:to:from:subject:message-id:references:mime-version:in-reply-to :date:from:to:cc:subject:date:message-id:reply-to; bh=zAJGdoX03+Z7kHA10F2BJAYl/c1vU7j8o14tItuzLUc=; b=NKoFanqOwY+7a1Jy9XT0NiAK9uAdjfQJDPWB9hbwPdUfpRaIUDMLZieCSeCVa1JYTZ iRFtTmAtBInDAorPpMhuwlVDfcDA5b25xX5sqgTAAlpi9LXzqm4FVwL3O9eDXXJkt5N4 +dcr5mNqHyQMsoR4n1Kfwh3Q7U/T5RCoxqv+p54eGNnf5XbDEdyooHIG79B213ENpqfa kOgzE/cMiLcB5lImpbfsORpfIuialdtTIg5O0pPCxATCMiUl4sMKt2X4Ep7Cj0yB0o2v QLU9pdkoNsr2dPXZ6TL8JDnN55yQQIIwT7LsMrCqspkqKEMNYYhOj2Mxo4T+cuzeDveI IgZg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1763650976; x=1764255776; h=cc:to:from:subject:message-id:references:mime-version:in-reply-to :date:x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=zAJGdoX03+Z7kHA10F2BJAYl/c1vU7j8o14tItuzLUc=; b=gz5NTJnLJ2nWAzUgA4Hz0XtDbcinsWiX7TDe8XZggaLWC7E2T0AB2mi5uNp8SW8n+M gWYGllCbdCr1Wy4qIykyWWy/PhvuAFcCs5oH7ajNolbSFa0aQ9ND0JJE7p0WXrXp0ExU mWZ8A61JIOR58i56kaL1jLllOwk9qMooUKbSwv2FUR6zNHz/qVEsg3tj1Z87nGPAMovC SG9G62GeKj1qJklZ9gFLAVFdGmPxSBwsEsWJsziDTpBPnsKUGp0gkue2qyfDnsmuKxEp vi9xWS26pxfrhzgeECTI6ABOz4SBfjNIxZHLoPRiWd8MMjqPWJqkSd4eMf2PKi2sgooQ xPuA== X-Forwarded-Encrypted: i=1; AJvYcCWGbAVDALKE26H+ixgNknMf+qGQRB6io9TQmu55hYO3DKoB1xXb7DFUbGeKsebBtW4gGgJkt3OSAd10Heo=@vger.kernel.org X-Gm-Message-State: AOJu0YxpxSBoH4FLmRgVTUIl52UHwtXof3nCWR24RIeFyB0owV5qNp9N mEEXC9ckMSgfD5stuI1V+g25mcYKa5iI/lYRGf4hq6seTsdW0N0LfA6HpCGNWDBn635P6Ck/y8R myA== X-Google-Smtp-Source: AGHT+IFIYsn75+II8LsVddaa6qNKEfaR+cAEgpbzcwe6Py2Tl/ywj/JLpQudo1QVKMjc586QGSbi0kmLJg== X-Received: from wmot8.prod.google.com ([2002:a05:600c:4508:b0:477:a4d4:607a]) (user=elver job=prod-delivery.src-stubby-dispatcher) by 2002:a05:600c:1d05:b0:477:54cd:200a with SMTP id 5b1f17b1804b1-477b8a518f4mr26264575e9.6.1763650976118; Thu, 20 Nov 2025 07:02:56 -0800 (PST) Date: Thu, 20 Nov 2025 15:49:06 +0100 In-Reply-To: <20251120145835.3833031-2-elver@google.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: Mime-Version: 1.0 References: <20251120145835.3833031-2-elver@google.com> X-Mailer: git-send-email 2.52.0.rc1.455.g30608eb744-goog Message-ID: <20251120145835.3833031-6-elver@google.com> Subject: [PATCH v4 04/35] Documentation: Add documentation for Compiler-Based Context Analysis From: Marco Elver To: elver@google.com, Peter Zijlstra , Boqun Feng , Ingo Molnar , Will Deacon Cc: "David S. Miller" , Luc Van Oostenryck , Chris Li , "Paul E. McKenney" , Alexander Potapenko , Arnd Bergmann , Bart Van Assche , Christoph Hellwig , Dmitry Vyukov , Eric Dumazet , Frederic Weisbecker , Greg Kroah-Hartman , Herbert Xu , Ian Rogers , Jann Horn , Joel Fernandes , Johannes Berg , Jonathan Corbet , Josh Triplett , Justin Stitt , Kees Cook , Kentaro Takeda , Lukas Bulwahn , Mark Rutland , Mathieu Desnoyers , Miguel Ojeda , Nathan Chancellor , Neeraj Upadhyay , Nick Desaulniers , Steven Rostedt , Tetsuo Handa , Thomas Gleixner , Thomas Graf , Uladzislau Rezki , Waiman Long , kasan-dev@googlegroups.com, linux-crypto@vger.kernel.org, linux-doc@vger.kernel.org, linux-kbuild@vger.kernel.org, linux-kernel@vger.kernel.org, linux-mm@kvack.org, linux-security-module@vger.kernel.org, linux-sparse@vger.kernel.org, linux-wireless@vger.kernel.org, llvm@lists.linux.dev, rcu@vger.kernel.org Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Adds documentation in Documentation/dev-tools/context-analysis.rst, and adds it to the index. Signed-off-by: Marco Elver --- v4: * Rename capability -> context analysis. v2: * Remove cross-reference to Sparse, since we plan to remove Sparse support anyway. * Mention __no_context_analysis should be avoided. --- Documentation/dev-tools/context-analysis.rst | 145 +++++++++++++++++++ Documentation/dev-tools/index.rst | 1 + 2 files changed, 146 insertions(+) create mode 100644 Documentation/dev-tools/context-analysis.rst diff --git a/Documentation/dev-tools/context-analysis.rst b/Documentation/d= ev-tools/context-analysis.rst new file mode 100644 index 000000000000..a15436e288fd --- /dev/null +++ b/Documentation/dev-tools/context-analysis.rst @@ -0,0 +1,145 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. Copyright (C) 2025, Google LLC. + +.. _context-analysis: + +Compiler-Based Context Analysis +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D + +Context Analysis is a language extension, which enables statically checking +that required contexts are active (or inactive) by acquiring and releasing +user-definable "context guards". An obvious application is lock-safety che= cking +for the kernel's various synchronization primitives (each of which represe= nts a +"context guard"), and checking that locking rules are not violated. + +The Clang compiler currently supports the full set of context analysis +features. To enable for Clang, configure the kernel with:: + + CONFIG_WARN_CONTEXT_ANALYSIS=3Dy + +The feature requires Clang 22 or later. + +The analysis is *opt-in by default*, and requires declaring which modules = and +subsystems should be analyzed in the respective `Makefile`:: + + CONTEXT_ANALYSIS_mymodule.o :=3D y + +Or for all translation units in the directory:: + + CONTEXT_ANALYSIS :=3D y + +It is possible to enable the analysis tree-wide, however, which will resul= t in +numerous false positive warnings currently and is *not* generally recommen= ded:: + + CONFIG_WARN_CONTEXT_ANALYSIS_ALL=3Dy + +Programming Model +----------------- + +The below describes the programming model around using context guard types. + +.. note:: + Enabling context analysis can be seen as enabling a dialect of Linux C = with + a Context System. Some valid patterns involving complex control-flow are + constrained (such as conditional acquisition and later conditional rele= ase + in the same function). + +Context analysis is a way to specify permissibility of operations to depen= d on +context guards being held (or not held). Typically we are interested in +protecting data and code in a critical section by requiring a specific con= text +to be active, for example by holding a specific lock. The analysis ensures= that +callers cannot perform an operation without the required context being act= ive. + +Context guards are associated with named structs, along with functions that +operate on struct instances to acquire and release the associated context +guard. + +Context guards can be held either exclusively or shared. This mechanism al= lows +assigning more precise privileges when a context is active, typically to +distinguish where a thread may only read (shared) or also write (exclusive= ) to +data guarded within a context. + +The set of contexts that are actually active in a given thread at a given = point +in program execution is a run-time concept. The static analysis works by +calculating an approximation of that set, called the context environment. = The +context environment is calculated for every program point, and describes t= he +set of contexts that are statically known to be active, or inactive, at th= at +particular point. This environment is a conservative approximation of the = full +set of contexts that will actually be active in a thread at run-time. + +More details are also documented `here +`_. + +.. note:: + Clang's analysis explicitly does not infer context guards acquired or + released by inline functions. It requires explicit annotations to (a) a= ssert + that it's not a bug if a context guard is released or acquired, and (b)= to + retain consistency between inline and non-inline function declarations. + +Supported Kernel Primitives +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. Currently the following synchronization primitives are supported: + +For context guards with an initialization function (e.g., `spin_lock_init(= )`), +calling this function before initializing any guarded members or globals +prevents the compiler from issuing warnings about unguarded initialization. + +Lockdep assertions, such as `lockdep_assert_held()`, inform the compiler's +context analysis that the associated synchronization primitive is held aft= er +the assertion. This avoids false positives in complex control-flow scenari= os +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, m= aking +`__must_hold()` inappropriate. + +Keywords +~~~~~~~~ + +.. kernel-doc:: include/linux/compiler-context-analysis.h + :identifiers: context_guard_struct + token_context_guard token_context_guard_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 + __cond_lock + __acquire_shared + __release_shared + __cond_lock_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 guard types, and should be avoided in normal = code. + +Background +---------- + +Clang originally called the feature `Thread Safety Analysis +`_, with some keywo= rds +and documentation still using the thread-safety-analysis-only terminology.= This +was later changed and the feature became more flexible, gaining the abilit= y to +define custom "capabilities". Its foundations can be found in `Capability +Systems `_, used = to +specify the permissibility of operations to depend on some "capability" be= ing +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 +kernel, the naming chosen for the kernel departs from Clang's initial "Thr= ead +Safety" and "capability" nomenclature; we refer to the feature as "Context +Analysis" to avoid confusion. The internal implementation still makes +references to Clang's terminology in a few places, such as `-Wthread-safet= y` +being the warning option that also still appears in diagnostic messages. diff --git a/Documentation/dev-tools/index.rst b/Documentation/dev-tools/in= dex.rst index 4b8425e348ab..d864b3da4cc7 100644 --- a/Documentation/dev-tools/index.rst +++ b/Documentation/dev-tools/index.rst @@ -21,6 +21,7 @@ Documentation/process/debugging/index.rst checkpatch clang-format coccinelle + context-analysis sparse kcov gcov --=20 2.52.0.rc1.455.g30608eb744-goog