From nobody Sun Oct 5 23:38:28 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 3F9F0255F26 for ; Mon, 28 Jul 2025 09:43:07 +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=1753695789; cv=none; b=nJhEfn78bjEwZGDiUJvQbUaHi8auxx2kHTUIhVBah63i5mw0VRkaGyeJAVtlYLzUuEvTf3YI4N8UbwoSdQ90wVhPaGHEZkKSaoYvvGKa5ea0lF/JPEApDZKuqfH1rpdsvKO27dK8zLoF4xTQLHhPBwPvT1klKIdRpy2/UTLH3rc= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1753695789; c=relaxed/simple; bh=0eVkNrzPFJGzVOngpFcJmZHS8eIgg0jNC6gMVEMtWnU=; h=Date:In-Reply-To:Mime-Version:References:Message-ID:Subject:From: To:Cc:Content-Type; b=aJnFM4pZ0p7wLxXrbj6nEelAaJ9D7jMBajO9tF8W8tt3dFYcOA9cSuATuFhd4oLIq7iX+MTXla67hUQkS2HGr+M2XtPQuUBahmux4X21PB9hrIGxfIk4zBR5WdvTNhOXT8rzQjTtgfZRLrulBJJtfg5wd/kAuAbu97RoiUT9i9s= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=google.com; spf=pass smtp.mailfrom=flex--aliceryhl.bounces.google.com; dkim=pass (2048-bit key) header.d=google.com header.i=@google.com header.b=b96f3yGE; 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--aliceryhl.bounces.google.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=google.com header.i=@google.com header.b="b96f3yGE" Received: by mail-wm1-f74.google.com with SMTP id 5b1f17b1804b1-4560f28b2b1so13440205e9.2 for ; Mon, 28 Jul 2025 02:43:07 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20230601; t=1753695785; x=1754300585; 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=OoseXamUvXXGE8heVA1E+IY+v0GgDCwwey/7g0eIgn8=; b=b96f3yGEO6Fl9o3jpxNF24Y93fFBChnjfhm18XgsjWHNVOk/5YkpcA0Glcw4XGdbmn Eer6mKpOzqyk83SuBII5gFqfmJj70a3JZtw5L238UKCStLvRDqFHQASk2IEHGQ+wmjas cveNrQGW7eM8yozUTwT/4+4vccG0QPDUj5xC3IMYrE4VWCiWfk+d1zK8A4EfTb/JpfEl UGB3gtCAbCZH4T1rpLAjddnPZ1ihHRqMhjdjbVmTS2320FpHZsxaYasBDVEfvaH30rDI 6zUcl9mV9aleEiQtCO/286tUCCaJmsQvH7h/QCE+CLL5pqvlfB5/Nl0Cs+Lb2zY6HTuP 3VcA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1753695785; x=1754300585; 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=OoseXamUvXXGE8heVA1E+IY+v0GgDCwwey/7g0eIgn8=; b=QVDdcDvTzGxc3+WbtoCe7i/Fnu94N+9Ov11dS4bZFuQuFf1AvxwQRYfvBqWC4XNOqv Mf//KMMlhu1e0k8xS2jHlpcqWVWbHaaMsZd+sPTnhIIj+zVFiwKEtOKDEdE7PBuq33Zn UktRu1Kq1T5xgeTuE3zJU3qeR/ilp1mOiBqfVomE4BHQyd/dQ5Q5uYVnZitDRNB7qQwX /woDbVfRQY2tYnNAe35Wc3R9zXBcS5V3RST8kl1q+xb4zeJ3C/npzVINn98Ubm3+2oFF IKO1zb+G9C/SOKeKC8+vk5wdXt28KUbiG0LGGzyJ0XPjapU06nrhlSRamdMN7CRoPjg5 +ncg== X-Forwarded-Encrypted: i=1; AJvYcCV2sj/9eU5QZ1yOa/L+9tF4Z+6dGbYRDZjE4dpqJ64jz23ZBRID3JEp6Qi180OMR/hl8Ih/gsJsDbXFgZ4=@vger.kernel.org X-Gm-Message-State: AOJu0YzSEaKCQgLh/ikbcGNWLHLmWB81DGM0cSBL/hEI3uZuR53EmYEv aGNDcpHZ+CcVW9lpuI0KWJG8Vh91b8nwKPM9q9CNnyd09kXIzoHGVX3Fgf+djzKKQDwHZYAyrU2 dDeNZZnMIj9JQqf/rsQ== X-Google-Smtp-Source: AGHT+IG5AXmhm+TDSDOVfx/3JPAhzl4emRLD4RTTA8oMoIbHA7wwz9Gl5Pd+RD4hak6Ev3lQlrbocBRfuzkAt/Y= X-Received: from wmbds6.prod.google.com ([2002:a05:600c:6286:b0:456:1c99:78b4]) (user=aliceryhl job=prod-delivery.src-stubby-dispatcher) by 2002:a05:600c:4ed1:b0:453:1058:f8c1 with SMTP id 5b1f17b1804b1-45876304c42mr95616395e9.3.1753695785555; Mon, 28 Jul 2025 02:43:05 -0700 (PDT) Date: Mon, 28 Jul 2025 09:42:55 +0000 In-Reply-To: <20250728-lock-class-key-cleanup-v2-0-ad02b80c69e1@google.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: Mime-Version: 1.0 References: <20250728-lock-class-key-cleanup-v2-0-ad02b80c69e1@google.com> X-Developer-Key: i=aliceryhl@google.com; a=openpgp; fpr=49F6C1FAA74960F43A5B86A1EE7A392FDE96209F X-Developer-Signature: v=1; a=openpgp-sha256; l=2810; i=aliceryhl@google.com; h=from:subject:message-id; bh=0eVkNrzPFJGzVOngpFcJmZHS8eIgg0jNC6gMVEMtWnU=; b=owEBbQKS/ZANAwAKAQRYvu5YxjlGAcsmYgBoh0YnMXCsvyvIE04yEk8xUzINQpBoi9PPh8OKp TJVMcCR3vGJAjMEAAEKAB0WIQSDkqKUTWQHCvFIvbIEWL7uWMY5RgUCaIdGJwAKCRAEWL7uWMY5 RqOnD/9joDL3i9Ni9s68Pn6N/SDUtCcGCg3AriD//KmL5xv5h5DkHyixsmUN8CyBhGOvRqwAWIc qlMzhILPfV1Z7ru7DnfdxXRgigHbLSVoQTPlE/HL3hKfXfCwhapc89zLNjRXnrsBiT3XL7BiGSG dWrjJXH+H14pM4bTgMSU5608+jAap6YLqmDkFojTXnFFT8k4hNqOE+pWfPzNn9694Sx3o5Kikdy /jQ3pWjvlvKyTcJ3jBDCV21SmeQuhY6ICahgLdfHWEkbdbupiefjoFBZgpbZY2Jp7+W+VRcgz5R vKpuQ6O+2dYsiBvtd1fczIxC7ZtuWZvoArzcgiyRAP1+qQUojJXIyZf1obu7HwTu60eaWv2632r 8PJ2dAoo8LuJqgZEWQIeTpeKCSkRP1nkivQ2yb3VlegYmhV/zV9KKodlkw6HiPSGqpN5fUGCslE z/0JRStEPIoH8dVdKjItx2Q2EuZ81WYSfWgSNga7hpmAiCchjsLu/cwfkUJ7QpeuWQEzGRMl9wl Q3jDRVMTMKwk2mCa7JXD16+Nbabw7dQDLEPQuAc90++Jek1D3bR+gKlskyFRKXBVhQdE/OlowI6 TR6/JehZM8JDV4E8TQlBkPdu05LbKBwovKkKUott28+Xu5rDelHj1cvSO0hq+sonzFkx4SEDTWs sbcxiuobTGzdn2g== X-Mailer: b4 0.14.2 Message-ID: <20250728-lock-class-key-cleanup-v2-1-ad02b80c69e1@google.com> Subject: [PATCH v2 1/2] rust: sync: refactor static_lock_class!() macro From: Alice Ryhl To: Boqun Feng , Miguel Ojeda Cc: Gary Guo , "=?utf-8?q?Bj=C3=B6rn_Roy_Baron?=" , Benno Lossin , Andreas Hindborg , Trevor Gross , Danilo Krummrich , Daniel Almeida , rust-for-linux@vger.kernel.org, linux-kernel@vger.kernel.org, Alice Ryhl Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable By introducing a new_static() constructor, the macro does not need to go through MaybeUninit::uninit().assume_init(), which is a pattern that is best avoided when possible. The safety comment requires not only requires that the value is leaked, but also that it is stored in the right portion of memory. This is so that the lockdep static_obj() check will succeed when using this constructor. One could argue that lockdep detects this scenario, so the safety comment isn't needed. However, it simplifies matters to require that static_obj() will succeed and it's not a burdensome requirement on the caller. Suggested-by: Benno Lossin Reviewed-by: Daniel Almeida Signed-off-by: Alice Ryhl Reviewed-by: Benno Lossin --- rust/kernel/sync.rs | 27 ++++++++++++++++++++------- 1 file changed, 20 insertions(+), 7 deletions(-) diff --git a/rust/kernel/sync.rs b/rust/kernel/sync.rs index 00f9b558a3ade19e442b32b46d05885b67e1d830..2c04a3806ca885637583fde336d= 054426f569fe5 100644 --- a/rust/kernel/sync.rs +++ b/rust/kernel/sync.rs @@ -39,6 +39,21 @@ pub struct LockClassKey { unsafe impl Sync for LockClassKey {} =20 impl LockClassKey { + /// Initializes a statically allocated lock class key. + /// + /// This is usually used indirectly through the [`static_lock_class!`]= macro. + /// + /// # 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(), + } + } + /// 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. /// @@ -95,13 +110,11 @@ fn drop(self: Pin<&mut Self>) { #[macro_export] macro_rules! static_lock_class { () =3D> {{ - static CLASS: $crate::sync::LockClassKey =3D - // Lockdep expects uninitialized memory when it's handed a sta= tically allocated `struct - // lock_class_key`. - // - // SAFETY: `LockClassKey` transparently wraps `Opaque` which p= ermits uninitialized - // memory. - unsafe { ::core::mem::MaybeUninit::uninit().assume_init() }; + // SAFETY: The returned `LockClassKey` is stored in static memory.= Drop never runs on a + // static global. + static CLASS: $crate::sync::LockClassKey =3D unsafe { + $crate::sync::LockClassKey::new_static() + }; $crate::prelude::Pin::static_ref(&CLASS) }}; } --=20 2.50.1.470.g6ba607880d-goog From nobody Sun Oct 5 23:38:28 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 7057925C827 for ; Mon, 28 Jul 2025 09:43:08 +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=1753695790; cv=none; b=l6tCEvMPfQKHjwD4IzerScxAJE2vARQQD9KiXV3AZFIMAqrfxBIkeQZorwKahOqsMp9DdswbdsFiJenn8IbqaILwd+1IoLy/+PyoXEv5wXiMkKB9IG8NewfhNRT/i2vK9hJayb963+/jjF+/FrNgXHR1bS5fyYgieT4l1T5pFYQ= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1753695790; c=relaxed/simple; bh=np/gcN5m4MW2LLygCOMOx8cuw1o8AFXIBEsbdvS7NOE=; h=Date:In-Reply-To:Mime-Version:References:Message-ID:Subject:From: To:Cc:Content-Type; b=jxOui01vG2mxSkdOusTOxDZBYM/eyO9ZFmpHZxWL2Nxpdn6/YerBDtgPfw0k3+Zygzq2wHJAme5hr4LrUNCnP51uXoWY85flLHJF6uDCGZ4frMuraByeKapbczQal7E1QH9evHwY7S7s6QNo/qoukuPDfQBKhrZovjkxX0H8lUs= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=google.com; spf=pass smtp.mailfrom=flex--aliceryhl.bounces.google.com; dkim=pass (2048-bit key) header.d=google.com header.i=@google.com header.b=3TBWuZq+; 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--aliceryhl.bounces.google.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=google.com header.i=@google.com header.b="3TBWuZq+" Received: by mail-wm1-f74.google.com with SMTP id 5b1f17b1804b1-4561bc2f477so20618605e9.0 for ; Mon, 28 Jul 2025 02:43:08 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20230601; t=1753695787; x=1754300587; 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=f23mdrJtX4cECnR9yhw2cVkgQ/+P2GFW65BzXk2ui44=; b=3TBWuZq+/+3DywuBKk2hX0RLQ8CMgrLdkbZp5UQ2TljlRIuOS95bb6T6gas+ImLFDd CunTUk+6dz8shK8DDOa8YFMJYDCn4CEv+IQPfLe+aP6LdjgYNlRtlvbNkZVVZOf0jVlw k9NpQLMgWj5t8f0hDO9p/jbUJZYJG3HtCrOTI4qNyw85sIRtoL/yIHwssZN3kzS6AoDX k58CQYsOqhNITtoxCzyTkmU61tlQyTvsXIMwjHOYoKEU7+Elg4i9S1940W7vLxV33rDI sMjR4oJV9n20Qr6embBbwl+b17mSygWIG6kM2UbH5XxXPVhrxhgcI6ufENa24cg0wn+q UQcw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1753695787; x=1754300587; 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=f23mdrJtX4cECnR9yhw2cVkgQ/+P2GFW65BzXk2ui44=; b=b4euOzGKqaac7T510A1IirupfKpMpm7sj3tWM/9SzeEQGUER+eozKfvpmUyX4VbHRZ dAtu6ttMdMMNkzbjZwvDuUlP0KQBJ308v5+ebiRV9jZ0muC/F8nnpjrMdUrEWyKpk+9u oN5/GQJx3HO2yqLe7c+e92Rej7ATLfWSiDmVvKndVSZgSSuFPuXhLCtvlUaNmhlCbnDJ Z4Jj6/5Z3hP9hM+5NllCmDwU3kPD4JSyM/k3rq23/4QsgyqPFHlYoqC15CwZLPO+rPQH tRshnGSkWDaBKZbk7CtUcmde6Hsqv9dV7WdN9EE4FeTwwR4myjwvuhNcouXlvIXjR0no /3KQ== X-Forwarded-Encrypted: i=1; AJvYcCWTc1/2nLdQaXAwYUYsE2sstPfGAa8L/QLy8EXkozhb9wPGTMPHQ5Lzb7CcG7blbG1Xxz8Idwh77LzTVEU=@vger.kernel.org X-Gm-Message-State: AOJu0YyDDxd5//QXKKKBxxHbu+pP4aNtfF2IjkVISO/3VVgKgXWKG+1F tqlxD/BMyYrivFLd7fxbH7CiZHDZUXJ/95BCtI4Er/K30lRN/EgiF644ugaMmBJjSW6tOAYQSL/ Xa2M/otO6WPsUN40lbw== X-Google-Smtp-Source: AGHT+IGZevCfpzMP0vuNgBaCdLJtz9mM/Oj9S8mRwI1C4qqC98ZGTEX33Mt7j7fTojLZ1GQiUAnGrHbESCLijmg= X-Received: from wmbem22.prod.google.com ([2002:a05:600c:8216:b0:458:715c:51a1]) (user=aliceryhl job=prod-delivery.src-stubby-dispatcher) by 2002:a05:600c:c173:b0:456:18f3:b951 with SMTP id 5b1f17b1804b1-458788a2116mr89024445e9.15.1753695786877; Mon, 28 Jul 2025 02:43:06 -0700 (PDT) Date: Mon, 28 Jul 2025 09:42:56 +0000 In-Reply-To: <20250728-lock-class-key-cleanup-v2-0-ad02b80c69e1@google.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: Mime-Version: 1.0 References: <20250728-lock-class-key-cleanup-v2-0-ad02b80c69e1@google.com> X-Developer-Key: i=aliceryhl@google.com; a=openpgp; fpr=49F6C1FAA74960F43A5B86A1EE7A392FDE96209F X-Developer-Signature: v=1; a=openpgp-sha256; l=5390; i=aliceryhl@google.com; h=from:subject:message-id; bh=np/gcN5m4MW2LLygCOMOx8cuw1o8AFXIBEsbdvS7NOE=; b=owEBbQKS/ZANAwAKAQRYvu5YxjlGAcsmYgBoh0YnpX9fzxOyP2UjXbBtQu6a8QSJNk3YCJ0Pq okx/PVtJ+OJAjMEAAEKAB0WIQSDkqKUTWQHCvFIvbIEWL7uWMY5RgUCaIdGJwAKCRAEWL7uWMY5 Ro5+D/wLdui8frFRBP8zhE1x7IAQORblg1mlbn5H5VbU8M7Bnm7iN2zz7d4JaAhtubobWuvbcHT 2jcehaXOPfMRReYhORIiN/Q9B/t2Aq1OxfjaGIIfagMTbPJ9m3DiwNcsBVsF5V4DTdT1sHGPXF1 qTM1Ul29s8Dk/BPk+1I1NNNIi6NlA03ZGJFV0n0w1bmkFfG4vcRzY+9E3/m+vqdo5wBT/0+cdG1 5Y9+C7zWOFDWG2d0elDfrx5OIG687lrbqEWzbyk3kikn9f7oYWenIfSJTZMPC7H0juwXNpFHT48 969y7UnCOTw6f4HrVPkmXqxLiSthJm6R+VOzIfp+Ju1HVVMXcrO8jPSQPqu5ejTUgayrcqOEO+R Xtow0eBZNovdU7JTXWRr5lV3EbvwCKjg9iO0uOVVzBQ1KNzAdu/9iWpZVBqurQ2X4/1VpHt63hY 35owKb2/yRE2wdwm8vlMVWbEtJAlUkN7kzuJ8bjJUq4FNSimQ7+Jaut6ku7drg8q4FlWx3iUljT 931Sy9K6Fzxv2lMbsfE8ZwgD3oQOIOzuEWC/A9hQyvCBqtA2/lYYtuGwmvef9Ya4xXyNUlPvlwW v/dM7VudMHViSyn/Y+krndHE2kVkBr4M4aNPday+ZybvW2bnltyTvAjDK+5fiAtwwbbiU6O2sOF iGHW76vN7hKsytw== X-Mailer: b4 0.14.2 Message-ID: <20250728-lock-class-key-cleanup-v2-2-ad02b80c69e1@google.com> Subject: [PATCH v2 2/2] rust: sync: clean up LockClassKey and its docs From: Alice Ryhl To: Boqun Feng , Miguel Ojeda Cc: Gary Guo , "=?utf-8?q?Bj=C3=B6rn_Roy_Baron?=" , Benno Lossin , Andreas Hindborg , Trevor Gross , Danilo Krummrich , Daniel Almeida , rust-for-linux@vger.kernel.org, linux-kernel@vger.kernel.org, Alice Ryhl Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable 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 --- rust/kernel/sync.rs | 55 ++++++++++++++++++++++++++++++++++++++-----------= ---- 1 file changed, 40 insertions(+), 15 deletions(-) diff --git a/rust/kernel/sync.rs b/rust/kernel/sync.rs index 2c04a3806ca885637583fde336d054426f569fe5..66d0a3c2f92d76213bc7fdb7b86= d54d4835aee79 100644 --- a/rust/kernel/sync.rs +++ b/rust/kernel/sync.rs @@ -26,7 +26,9 @@ pub use lock::spinlock::{new_spinlock, SpinLock, SpinLockGuard}; pub use locked_by::LockedBy; =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 { @@ -34,6 +36,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 {} @@ -41,29 +47,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::c_str; - /// # use kernel::alloc::KBox; - /// # use kernel::types::ForeignOwnable; - /// # use kernel::sync::{LockClassKey, SpinLock}; - /// # use pin_init::stack_pin_init; + /// use kernel::c_str; + /// 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(); @@ -81,7 +89,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 { @@ -91,7 +98,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() } } @@ -99,14 +109,28 @@ pub(crate) fn as_ptr(&self) -> *mut bindings::lock_cla= ss_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> {{ @@ -118,6 +142,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.50.1.470.g6ba607880d-goog