From nobody Sun Feb 8 18:49:32 2026 Received: from mail-qk1-f196.google.com (mail-qk1-f196.google.com [209.85.222.196]) (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 5648933A71C for ; Sun, 11 Jan 2026 11:58:30 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.222.196 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768132712; cv=none; b=MFVJGOWHN4CI4L4wGXpRwGDxsEXi/qBf6/ieKlCyA821fO5sXhIxLzpt+6HjVQRteXg6CkGd/jQcp5Ds3kiXTvA6rlnAuLlOAGI+Bh2qs2ijDXY6eXgOKRMZqKkPri7TG5WsGN08Fd+2F5oeimjF/Xun1GI8KXkYIqwK643KhxY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768132712; c=relaxed/simple; bh=vYQWWDn3ZMU7ZhgJQIFMJBOWlbCCxJkWe+WqAR7ur6Q=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=t3p+jlR0EOsLsN1QKMtkQurrsCMYivD8iXjd5FphGppPuRLXr0Bny9aj4lTJubUfH9M4MgArdwnG3+zM/gfgcbyT1zsU3nJMsgg/yuFH/gLmnyXXGCAOW5RyXxgDZ3tUI3Gw3mDObmx+egLnobPbO8g/KhGwXlsbhPtN64Nw0nM= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=AC9PkEit; arc=none smtp.client-ip=209.85.222.196 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="AC9PkEit" Received: by mail-qk1-f196.google.com with SMTP id af79cd13be357-8b2ea2b9631so645387985a.3 for ; Sun, 11 Jan 2026 03:58:30 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1768132709; x=1768737509; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:feedback-id:from:to:cc:subject :date:message-id:reply-to; bh=Ai6kzfN6tjZuKrzAAXupramGsGRk1fhjTMyiwJSSmtI=; b=AC9PkEite8z/gBxsd3WGaZAb84X07bDU/RUog8T1244QdZH7QuyC+uzJQAyRXVlk05 Uci6xK1m/dkCR41Bw4D7f3H5A8hVjsIZ2s+Lz4jZtQhAb9Q+pKzXZeUXczFS/hVXfPMF JmYMGJn+c+C2DpdNKII3b3uFBGaWdfj86VlpstDMFjkm2Nci/kRmg0IEJlPhirEkIZFn yoFveFFSUGNT9CmnshlkqhS0E9UVvXir+g2YQqEGHOPCTM+uXccl9p0oxh/SLC31ZmCW lLThiy47c4qFm36TUWX6pwylacX3rl4GOO19Njdq6SJqW6d9K6wBdgF/acYw/FAR6b4t E4vA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1768132709; x=1768737509; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:feedback-id:x-gm-gg :x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=Ai6kzfN6tjZuKrzAAXupramGsGRk1fhjTMyiwJSSmtI=; b=kktZviIF/fvpe7pJoMYJd3GEKtcZM+uH18ysw3Ozymmci6NV6s/YnE6nKu8/8jxveU zYK+7rj4Wpg6oKJxsLJ9oWnN1YVIJAVoZD3vb+U0G+96UY6yXPI+TVi8tb0iptiaeCmk I8tq2vDEy3gciKePudNef/JSLOHnMeh/86BMux5VGdIn7R8J5LPRuEA2lfbjJAjHARMK 9mTwxTy8NYMXC70arOf9tOTzS1qBmcnVH/xpgiY/F59vB1xouQG0YiAsz4cevN7aGd9z MbmfDVJ3Cb8P70ZqHHVdeLS7S+6sRzxbc1+CtdMpq1iDe1C5bJpI2gJOQdo4uSud1EbE +u3A== X-Forwarded-Encrypted: i=1; AJvYcCXRzwCWVQf1DrhM+4hboHF8dqBybm/Onk3Qc8AQf10wcFKIAz1K7qPwy20VreseVUEGP9E2+Psv0ms8kcU=@vger.kernel.org X-Gm-Message-State: AOJu0YwC+Cig0dHCsIxYyo1SdwXLdSTgeckG54lAVNTrJGlLu2nQwe72 AJnDret4IzjGruiUjfLk5uxUUpr0nYjbpxDoGrWunkbmq/OzP1741Ver X-Gm-Gg: AY/fxX4Qqo1AnzbRL4eUjflSi8Bec9rtJnOzE0dgiLg87sR9wQBViRTJFcHKvLGrpOr 1j/9soxm7TGF94afVRZeSnvpJpl6+SzDmkhyHhNTTFd1voZDw8XdlKJcThLSC7JR/uwnCISaM+C yDPB+TysLTqXJ7baMalg7REEXPOIKpOmK70hSWoUjTAPzv4iY2MejLVEESueJbiC5O3bf6c9pHx xSTwS/0RrKXFntnoMB0aGmk1TbPZ3ghNbxmu9m1ouiFWPzzd/0Yso4F/bvufOqg+TVc0HUzSUos IDvnQgeaCy2iz/4qotsIYKO9YewLgbmi4pBbI28hSEaJu+x5Zox2+kaWjjn7XdS3kVMUNNKr0rq eHc58CVQ6iuha9xzSdKMcOXeDlH1CX4fQV0GpbR6KTLORsSWyy9siRmBlwnrQ4efFePCyfkRMYL ujcxAVoI5PyTpnchWSGZgfGbISPfjQHEcfOGAn/LeXnUglEnVk0TINOIOYDrH9ElJ9H9oUtENu0 fWxXGEJOyPnCLCthw2VILkwxg== X-Google-Smtp-Source: AGHT+IG3o0MsFaV703ugnLdBB/Lo8Ct7pECA2g3uzwf4YmMMcxBQsZcjjJ07zeF4DOTkUeievjG2qw== X-Received: by 2002:a05:620a:25ce:b0:8bb:a675:b545 with SMTP id af79cd13be357-8c3893f8712mr2151103585a.63.1768132709248; Sun, 11 Jan 2026 03:58:29 -0800 (PST) Received: from fauth-a2-smtp.messagingengine.com (fauth-a2-smtp.messagingengine.com. [103.168.172.201]) by smtp.gmail.com with ESMTPSA id af79cd13be357-8c37f4a6145sm1270837785a.5.2026.01.11.03.58.28 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 11 Jan 2026 03:58:28 -0800 (PST) Received: from phl-compute-06.internal (phl-compute-06.internal [10.202.2.46]) by mailfauth.phl.internal (Postfix) with ESMTP id 5537FF40068; Sun, 11 Jan 2026 06:58:28 -0500 (EST) Received: from phl-frontend-03 ([10.202.2.162]) by phl-compute-06.internal (MEProxy); Sun, 11 Jan 2026 06:58:28 -0500 X-ME-Sender: X-ME-Received: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeefgedrtddtgdduudegheduucetufdoteggodetrf dotffvucfrrhhofhhilhgvmecuhfgrshhtofgrihhlpdfurfetoffkrfgpnffqhgenuceu rghilhhouhhtmecufedttdenucesvcftvggtihhpihgvnhhtshculddquddttddmnecujf gurhephffvvefufffkofgjfhgggfestdekredtredttdenucfhrhhomhepuehoqhhunhcu hfgvnhhguceosghoqhhunhdrfhgvnhhgsehgmhgrihhlrdgtohhmqeenucggtffrrghtth gvrhhnpedvteethfeugeejjeeuvdfhgfekleeujefhkeeuieekgeeufeetffeflefgfffg feenucffohhmrghinhepmhhsghhiugdrlhhinhhkpdhinhhfohhrmhgrthhiohhnrdhsrg hfvghthienucevlhhushhtvghrufhiiigvpedtnecurfgrrhgrmhepmhgrihhlfhhrohhm pegsohhquhhnodhmvghsmhhtphgruhhthhhpvghrshhonhgrlhhithihqdeiledvgeehtd eigedqudejjeekheehhedvqdgsohhquhhnrdhfvghngheppehgmhgrihhlrdgtohhmsehf ihigmhgvrdhnrghmvgdpnhgspghrtghpthhtohepudehpdhmohguvgepshhmthhpohhuth dprhgtphhtthhopehpvghtvghriiesihhnfhhrrgguvggrugdrohhrghdprhgtphhtthho pehmihhnghhosehkvghrnhgvlhdrohhrghdprhgtphhtthhopehruhhsthdqfhhorhdqlh hinhhugiesvhhgvghrrdhkvghrnhgvlhdrohhrghdprhgtphhtthhopehlihhnuhigqdhk vghrnhgvlhesvhhgvghrrdhkvghrnhgvlhdrohhrghdprhgtphhtthhopeifihhllheskh gvrhhnvghlrdhorhhgpdhrtghpthhtohepmhgrrhhkrdhruhhtlhgrnhgusegrrhhmrdgt ohhmpdhrtghpthhtohepthhglhigsehlihhnuhhtrhhonhhigidruggvpdhrtghpthhtoh epohhjvggurgeskhgvrhhnvghlrdhorhhgpdhrtghpthhtohepghgrrhihsehgrghrhihg uhhordhnvght X-ME-Proxy: Feedback-ID: iad51458e:Fastmail Received: by mail.messagingengine.com (Postfix) with ESMTPA; Sun, 11 Jan 2026 06:58:27 -0500 (EST) From: Boqun Feng To: "Peter Zijlstra" , "Ingo Molnar" Cc: rust-for-linux@vger.kernel.org, linux-kernel@vger.kernel.org, "Will Deacon" , "Mark Rutland" , "Thomas Gleixner" , "Miguel Ojeda" , "Gary Guo" , "Alice Ryhl" , "Andreas Hindborg" , "Benno Lossin" , "Danilo Krummrich" , Daniel Almeida , Boqun Feng Subject: [PATCH 02/36] rust: sync: Clean up LockClassKey and its docs Date: Sun, 11 Jan 2026 19:57:34 +0800 Message-ID: <20260111115808.5702-3-boqun.feng@gmail.com> X-Mailer: git-send-email 2.51.0 In-Reply-To: <20260111115808.5702-1-boqun.feng@gmail.com> References: <20260111115808.5702-1-boqun.feng@gmail.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" From: Alice Ryhl Several aspects of the code and documentation for this type is incomplete. Also several things are hidden from the docs. Thus, clean it up and make it easier to read the rendered html docs. Reviewed-by: Daniel Almeida Signed-off-by: Alice Ryhl Reviewed-by: Benno Lossin Signed-off-by: Boqun Feng Link: https://patch.msgid.link/20250811-lock-class-key-cleanup-v3-2-b12967e= e1ca2@google.com --- rust/kernel/sync.rs | 54 +++++++++++++++++++++++++++++++++------------ 1 file changed, 40 insertions(+), 14 deletions(-) diff --git a/rust/kernel/sync.rs b/rust/kernel/sync.rs index 1dfbee8e9d00..b10e576221ff 100644 --- a/rust/kernel/sync.rs +++ b/rust/kernel/sync.rs @@ -32,7 +32,9 @@ pub use refcount::Refcount; pub use set_once::SetOnce; =20 -/// Represents a lockdep class. It's a wrapper around C's `lock_class_key`. +/// Represents a lockdep class. +/// +/// Wraps the kernel's `struct lock_class_key`. #[repr(transparent)] #[pin_data(PinnedDrop)] pub struct LockClassKey { @@ -40,6 +42,10 @@ pub struct LockClassKey { inner: Opaque, } =20 +// SAFETY: Unregistering a lock class key from a different thread than whe= re it was registered is +// allowed. +unsafe impl Send for LockClassKey {} + // SAFETY: `bindings::lock_class_key` is designed to be used concurrently = from multiple threads and // provides its own synchronization. unsafe impl Sync for LockClassKey {} @@ -47,28 +53,31 @@ unsafe impl Sync for LockClassKey {} impl LockClassKey { /// Initializes a statically allocated lock class key. /// - /// This is usually used indirectly through the [`static_lock_class!`]= macro. + /// This is usually used indirectly through the [`static_lock_class!`]= macro. See its + /// documentation for more information. /// /// # Safety /// /// * Before using the returned value, it must be pinned in a static m= emory location. /// * The destructor must never run on the returned `LockClassKey`. - #[doc(hidden)] pub const unsafe fn new_static() -> Self { LockClassKey { inner: Opaque::uninit(), } } =20 - /// Initializes a dynamically allocated lock class key. In the common = case of using a - /// statically allocated lock class key, the static_lock_class! macro = should be used instead. + /// Initializes a dynamically allocated lock class key. + /// + /// In the common case of using a statically allocated lock class key,= the + /// [`static_lock_class!`] macro should be used instead. /// /// # Examples + /// /// ``` - /// # use kernel::alloc::KBox; - /// # use kernel::types::ForeignOwnable; - /// # use kernel::sync::{LockClassKey, SpinLock}; - /// # use pin_init::stack_pin_init; + /// use kernel::alloc::KBox; + /// use kernel::types::ForeignOwnable; + /// use kernel::sync::{LockClassKey, SpinLock}; + /// use pin_init::stack_pin_init; /// /// let key =3D KBox::pin_init(LockClassKey::new_dynamic(), GFP_KERNEL= )?; /// let key_ptr =3D key.into_foreign(); @@ -86,7 +95,6 @@ impl LockClassKey { /// // SAFETY: We dropped `num`, the only use of the key, so the resul= t of the previous /// // `borrow` has also been dropped. Thus, it's safe to use from_for= eign. /// unsafe { drop(> as ForeignOwnable>::from_fo= reign(key_ptr)) }; - /// /// # Ok::<(), Error>(()) /// ``` pub fn new_dynamic() -> impl PinInit { @@ -96,7 +104,10 @@ pub fn new_dynamic() -> impl PinInit { }) } =20 - pub(crate) fn as_ptr(&self) -> *mut bindings::lock_class_key { + /// Returns a raw pointer to the inner C struct. + /// + /// It is up to the caller to use the raw pointer correctly. + pub fn as_ptr(&self) -> *mut bindings::lock_class_key { self.inner.get() } } @@ -104,14 +115,28 @@ pub(crate) fn as_ptr(&self) -> *mut bindings::lock_cl= ass_key { #[pinned_drop] impl PinnedDrop for LockClassKey { fn drop(self: Pin<&mut Self>) { - // SAFETY: self.as_ptr was registered with lockdep and self is pin= ned, so the address - // hasn't changed. Thus, it's safe to pass to unregister. + // SAFETY: `self.as_ptr()` was registered with lockdep and `self` = is pinned, so the address + // hasn't changed. Thus, it's safe to pass it to unregister. unsafe { bindings::lockdep_unregister_key(self.as_ptr()) } } } =20 /// Defines a new static lock class and returns a pointer to it. -#[doc(hidden)] +/// +/// # Examples +/// +/// ``` +/// use kernel::c_str; +/// use kernel::sync::{static_lock_class, Arc, SpinLock}; +/// +/// fn new_locked_int() -> Result>> { +/// Arc::pin_init(SpinLock::new( +/// 42, +/// c_str!("new_locked_int"), +/// static_lock_class!(), +/// ), GFP_KERNEL) +/// } +/// ``` #[macro_export] macro_rules! static_lock_class { () =3D> {{ @@ -122,6 +147,7 @@ macro_rules! static_lock_class { $crate::prelude::Pin::static_ref(&CLASS) }}; } +pub use static_lock_class; =20 /// Returns the given string, if one is provided, otherwise generates one = based on the source code /// location. --=20 2.51.0