From mboxrd@z Thu Jan 1 00:00:00 1970 Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.remote-ip=209.85.210.178 ARC-Seal: i=1; d=subspace.kernel.org; s=arc20261015; a=rsa-sha256; cv=none; t=1794658740; b=Ai3sMicqECzD/dWxQQ3ASfZnrqNJan88gRdQzZyVqDzWVYdJui7vPGSugVlR4ImVRAAJ xrNZ0VxJS1W/8QckkNmgxFbfhIn7tWxw8KAPx7Qilrq+y44OmdkvuM9+TUd3TD5AErpb7 s6lmLwrxaYvAI78kK3nS2PwHQx+NEZ0IucMPAt9UvhHtoep/AYbZLLAlQOL2TfN/zK0yj eBBl3h3I6jeHUEUYTc/VsNDZOYNIzhOunOFKC9EVkVHYeuQ5GS5ia7rSThlyCi0jkEi7I BELkpKGx0hyw6lEFy6Kxjl5QmxzwTY5pnW5Eawsp5dOBZ3QvKFVEHffBCy1DADYRQ6Q== ARC-Message-Signature: i=1; d=subspace.kernel.org; s=arc20261015; a=rsa-sha256; c=relaxed/relaxed; t=1794658740; h=DMARC-Filter:Received:DKIM-Signature:X-Google-DKIM-Signature: X-Forwarded-Encrypted:X-Gm-Message-State:X-Gm-Gg:X-Received:Received: From:Date:Subject:MIME-Version:Content-Type:Content-Transfer-Encoding: Message-Id:References:In-Reply-To:To:Cc:X-Mailer; bh=Hlklr9HjlYj9YlI7wKU2ZXzvdmAz50MqQ9W4xUO0aG4=; b=QMjK8hwX/i3VXvjNRdddYnlukSvrdsne3wS3lnx3OS3V+Xw6UIIiWWiPWuQuW2Xl1WUZ PRnaYtWAtJds58zfT9OgFnzhDkqPDV6rXAsQMX4MyueWKk4TLCdJ3D+8n3+7xaBun1rdp B3G0sR5ABzKl4UMm8obDMmmHVR7n8C9JSd7IbjsnjcBTLc4lWMgJQ5oOPJBsyH6IjukrK HCDXBzbV8gunnG1qOGS9VFOxRL9j+ygRlkJ1EipHz2Avu+Qb9fAS/xSToDV5CVnjEUdXN WTuGLaZy6Opfbb/SKfrYCPmZD6eACLzQbnxu81qlwUQzokoLMw3KZgiMLgZdP28J3fQ== ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass header.d=gmail.com header.i=@gmail.com header.a=rsa-sha256 header.s=20260707 header.b=nk0I9zop; arc=none smtp.remote-ip=209.85.210.178 Received: from mail-pf1-f178.google.com (mail-pf1-f178.google.com [209.85.210.178]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits) key-exchange X25519 server-signature ECDSA (prime256v1) server-digest SHA256) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id C6DFF606A327 for ; Sat, 14 Nov 2026 12:18:59 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.4.2 smtp.subspace.kernel.org C6DFF606A327 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.a=rsa-sha256 header.s=20260707 header.b=nk0I9zop Received: by mail-pf1-f178.google.com with SMTP id d2e1a72fcca58-8a06e79e152so876131b3a.0 for ; Sat, 14 Nov 2026 04:18:59 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20260707; t=1794658739; x=1795263539; darn=vger.kernel.org; h=cc:to:in-reply-to:references:message-id:content-transfer-encoding :content-type:mime-version:subject:date:from:from:to:cc:subject:date :message-id:reply-to:content-type; bh=Hlklr9HjlYj9YlI7wKU2ZXzvdmAz50MqQ9W4xUO0aG4=; b=nk0I9zoplicYOXQWxcVzh1Z8tt+dew+nPalHTF1yw0TUgpPwH2AoIlZVPkH+rgDzQN FsDUz0EKzXW62kD438IFcf+X0Y00KCf+2qS/CLsA1BInTKjyQ7i1QczZnkHWhND+nH2K 5ch5z/VAU4TDqKNIFO3hiXuTzcn9BiQeEjSZnPl6684+RhOC4TalSau1DMjMCidfrs8a wlTxoDdqsRqJSqzysu3a8sVvwyYvBsGTI/rAW08l524lWOL4XZEAWN5x8OeNlL/gy9QV S3hAJ8B4aL7wDO+U3oMhDdzQaH78ul6lzAFD0pXTvCPGbK8n+pVgXV1GsnnnLH2H/w84 +u2A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20260707; t=1794658739; x=1795263539; h=cc:to:in-reply-to:references:message-id:content-transfer-encoding :content-type:mime-version:subject:date:from:x-gm-gg :x-gm-message-state:from:to:cc:subject:date:message-id:reply-to :content-type; bh=Hlklr9HjlYj9YlI7wKU2ZXzvdmAz50MqQ9W4xUO0aG4=; b=sUcOhHNXffxs//Hi9QKIH23S4v+o/UAUjHjG5BvQTnw2AjOxtXHpmYeuw9vCZymbE6 dRMfsZ/uLUBtcvRmIVxEhUjuMKjSYkZJJu7248ONCCmToyFepB+ORjNdV7QTWPLS4UE0 amBASTGlfqGL5uFBQr5nSjai861Elp9Myn7IFnH3nxEoU+uQw5jEk8+TSEbhuTurfo9L Q4Qf26dbAUdVexoZ/VLnuRI0yZfQjHoAEm/Kb1lAX4unSJunCVaquSczRSsCXSvU8EiT 9LIueQRLOwsKDlScfovV/emHD+4eJwVSkdWtt1/UTbORz2+gqcyLeJYpTREQnmazc8Pk mWKA== X-Forwarded-Encrypted: i=1; AL+hErGx7WKqe3qpXgr9S7xc+wGJiv7eSji7uypIutnHtL6H7CwV644MkzEOwuCGUb5CGYHemxUXjP/mspp7kQU=@vger.kernel.org X-Gm-Message-State: APuU4Z+rY7WseqZVC/Tb7jZt1pbkx9gAI2RtdfRjqIYOZBVk6sdfJ3yP C/iur7cbwnHnqxL6AwNevfoC//NmA4uC2iG+aTy6E3t3ij3kmTZW0xyX X-Gm-Gg: AYBFou1ONN4DT9/iRKN4BHyd3EY0QptDZTa9Z6dGIyQ5of5mDq9mf37VRS3hXxMYcSP e9bvqS0b1fx9yFuZ1lfSFCmkI55Oz8rz32kRFqgEaPR7kAaEXZz6mV4uK8kqA77fTfyC3fWvmnT TYWMkDJ0fiOBsL+HI/3MVg336/9VZ7MtlBG7K5b14s/Xkf/C7zltv/KPT7ocIzSdTjYwOZaMPq2 2JEctUb+fpgAjxoIkWYXKERh/CvPCO5/vcLjDOhVNGDglrgUEZtvexeK1LenGNaMYetd52GKztO czBGQlZdXTW5NMHgibbmsyTCoOmI7J3ZvRPPxOqHyhWJtFrlLsxfZJ5YCVf9EtTFeIRdf14KHde 9ALsHgREPMbm00SrGKY1VWAqhqD6jZwst/ZKT4s+qFeQ5eYblsu1QG3jP8c+PHv52aW7d8o2vyY hgZcIurboeKnMuGGs4LxoI1kI+/eIqYgz1TRk223rRvl5jntwm4RJaYiCvn9ffnaR1Ubivns5q6 CYLwiQ8Mj76z5kwxdjwv9UmvjX125aAo2sGVa3aTvSHSNtNYpYrjV3UkoehVJvM7rHBNP7bzuP8 aFsRQOsbkjCW8O9yJDkJUAodwS8jlq5IGgipVBdJygY4tJZc97zaxuJmEH2wrhCtzPrBUp8px0Q CCeG4UE6ZkvgBp7M6FTnElE0X3aH39HETjuXCt0zc5CBenPak8ZoyZTXK X-Received: by 2002:a05:6a20:6a2b:b0:3eb:485f:7c9c with SMTP id adf61e73a8af0-3f7a6cad659mr4768680637.29.1794658739103; Sat, 14 Nov 2026 04:18:59 -0800 (PST) Received: from [169.254.3.1] ([143.248.188.96]) by smtp.gmail.com with ESMTPSA id d2e1a72fcca58-8bececcca19sm2094389b3a.4.2026.11.14.04.18.52 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sat, 14 Nov 2026 04:18:58 -0800 (PST) From: SeungJong Ha Date: Sat, 14 Nov 2026 21:18:24 +0900 Subject: [PATCH net-next v2 2/3] rust: net: phy: make Device generic over a lock context X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Post: List-Help: List-Subscribe: List-Unsubscribe: List-Owner: Precedence: list MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: 7bit Message-Id: <20261114-exp-phy-rs-maybelocked-v2-2-19a4dd658b6b@gmail.com> References: <20261114-exp-phy-rs-maybelocked-v2-0-19a4dd658b6b@gmail.com> In-Reply-To: <20261114-exp-phy-rs-maybelocked-v2-0-19a4dd658b6b@gmail.com> To: FUJITA Tomonori , Trevor Gross , "David S. Miller" , Eric Dumazet , Jakub Kicinski , Paolo Abeni , Simon Horman , Miguel Ojeda , Boqun Feng , Gary Guo , =?utf-8?q?Bj=C3=B6rn_Roy_Baron?= , Benno Lossin , Andreas Hindborg , Alice Ryhl , Danilo Krummrich , Daniel Almeida , Tamir Duberstein , Alexandre Courbot , =?utf-8?q?Onur_=C3=96zkan?= , Andrew Lunn , Heiner Kallweit , Russell King Cc: netdev@vger.kernel.org, rust-for-linux@vger.kernel.org, linux-kernel@vger.kernel.org, SeungJong Ha X-Mailer: b4 0.15.2 Some PHY driver callbacks run without `phy_device->lock`, but every callback gets a `Device` whose type says the lock is held. Make `Device` generic over a lock context, `Locked` (the default) or `MaybeLocked`, as `device::Device` is over its device context, and move the methods that do not need the lock to both contexts. Update the documentation and SAFETY comments to match. The next patch uses `MaybeLocked`. No functional change. Signed-off-by: SeungJong Ha --- rust/kernel/net/phy.rs | 141 ++++++++++++++++++++++++++++++--------------- rust/kernel/net/phy/reg.rs | 17 +++--- 2 files changed, 105 insertions(+), 53 deletions(-) diff --git a/rust/kernel/net/phy.rs b/rust/kernel/net/phy.rs index 7ca3f2329e6a..105a1b727a08 100644 --- a/rust/kernel/net/phy.rs +++ b/rust/kernel/net/phy.rs @@ -50,6 +50,51 @@ pub enum DuplexMode { Unknown, } +/// A trait implemented by all contexts a [`Device`] can be used in. +/// +/// - [`Locked`]: Serialized against every access made under `phy_device->lock`. The default +/// context of [`Device`]. +/// - [`MaybeLocked`]: `phy_device->lock` may or may not be held. +pub trait PhyContext: private::Sealed {} + +/// The [`Device`] context of every [`Driver`] callback that does not take a +/// [`Device`]. +/// +/// PHYLIB calls these callbacks in one of three ways: +/// +/// - With `phy_device->lock` held: every callback not listed below. +/// - Without the lock, but where PHYLIB ensures by other means that no other path accesses the +/// instance: [`Driver::probe`] and [`Driver::get_features`], which are called from +/// `phy_probe()`, and [`Driver::suspend`] and [`Driver::resume`]. +/// - Without the lock, possibly on an unbound device or one bound to another driver: +/// [`Driver::match_phy_device`], which therefore only gets a shared reference. +/// +/// # Invariants +/// +/// For the lifetime of a `&mut Device`, no other thread accesses the state of the +/// `phy_device` that `phy_device->lock` protects. +pub struct Locked; + +/// The [`Device`] context of callbacks that PHYLIB calls both with and without +/// `phy_device->lock` held. +/// +/// A callback in this context must not take `phy_device->lock`. +/// +/// # Invariants +/// +/// None beyond those of [`Device`]. +pub struct MaybeLocked; + +mod private { + pub trait Sealed {} + + impl Sealed for super::Locked {} + impl Sealed for super::MaybeLocked {} +} + +impl PhyContext for Locked {} +impl PhyContext for MaybeLocked {} + /// An instance of a PHY device. /// /// Wraps the kernel's [`struct phy_device`]. @@ -57,6 +102,9 @@ pub enum DuplexMode { /// A [`Device`] instance is created when a callback in [`Driver`] is executed. A PHY driver /// executes [`Driver`]'s methods during the callback. /// +/// `Ctx` is the [`PhyContext`] of the callback. Methods that rely on the exclusive access that +/// [`Locked`] describes are implemented for [`Device`] only. +/// /// # Invariants /// /// - Referencing a `phy_device` using this struct asserts that you are in @@ -71,34 +119,9 @@ pub enum DuplexMode { // [`Driver::resume`] and [`Driver::suspend`] also are called where only one thread can access // to the instance. #[repr(transparent)] -pub struct Device(Opaque); +pub struct Device(Opaque, PhantomData); impl Device { - /// Creates a new [`Device`] instance from a raw pointer. - /// - /// # Safety - /// - /// For the duration of `'a`, - /// - the pointer must point at a valid `phy_device`, and the caller - /// must be in a context where all methods defined on this struct - /// are safe to call. - /// - `(*ptr).mdio.dev` must be a valid. - unsafe fn from_raw<'a>(ptr: *mut bindings::phy_device) -> &'a mut Self { - // CAST: `Self` is a `repr(transparent)` wrapper around `bindings::phy_device`. - let ptr = ptr.cast::(); - // SAFETY: by the function requirements the pointer is valid and we have unique access for - // the duration of `'a`. - unsafe { &mut *ptr } - } - - /// Gets the id of the PHY. - pub fn phy_id(&self) -> u32 { - let phydev = self.0.get(); - // SAFETY: The struct invariant ensures that we may access - // this field without additional synchronization. - unsafe { (*phydev).phy_id } - } - /// Gets the state of PHY state machine states. pub fn state(&self) -> DeviceState { let phydev = self.0.get(); @@ -177,17 +200,6 @@ pub fn set_duplex(&mut self, mode: DuplexMode) { unsafe { (*phydev).duplex = v as c_int }; } - /// Reads a PHY register. - // This function reads a hardware register and updates the stats so takes `&mut self`. - pub fn read(&mut self, reg: R) -> Result { - reg.read(self) - } - - /// Writes a PHY register. - pub fn write(&mut self, reg: R, val: u16) -> Result { - reg.write(self, val) - } - /// Reads a paged register. pub fn read_paged(&mut self, page: u16, regnum: u16) -> Result { let phydev = self.0.get(); @@ -206,14 +218,6 @@ pub fn resolve_aneg_linkmode(&mut self) { unsafe { bindings::phy_resolve_aneg_linkmode(phydev) }; } - /// Executes software reset the PHY via `BMCR_RESET` bit. - pub fn genphy_soft_reset(&mut self) -> Result { - let phydev = self.0.get(); - // SAFETY: `phydev` is pointing to a valid object by the type invariant of `Self`. - // So it's just an FFI call. - to_result(unsafe { bindings::genphy_soft_reset(phydev) }) - } - /// Initializes the PHY. pub fn init_hw(&mut self) -> Result { let phydev = self.0.get(); @@ -276,7 +280,52 @@ pub fn genphy_read_abilities(&mut self) -> Result { } } -impl AsRef for Device { +impl Device { + /// Creates a new [`Device`] instance from a raw pointer. + /// + /// # Safety + /// + /// For the duration of `'a`, + /// - the pointer must point at a valid `phy_device`, and the caller + /// must be in the `Ctx` context, see [`Locked`] and [`MaybeLocked`]. + /// - `(*ptr).mdio.dev` must be a valid. + unsafe fn from_raw<'a>(ptr: *mut bindings::phy_device) -> &'a mut Self { + // CAST: `Self` is a `repr(transparent)` wrapper around `bindings::phy_device`. + let ptr = ptr.cast::(); + // SAFETY: By the function requirements the pointer is valid for `'a`. `Opaque` permits + // other `&mut` to the same `phy_device`, e.g. in a concurrent `MaybeLocked` callback. + unsafe { &mut *ptr } + } + + /// Gets the id of the PHY. + pub fn phy_id(&self) -> u32 { + let phydev = self.0.get(); + // SAFETY: `phydev` is valid by the type invariant of `Self`. `phy_id` is set by + // `phy_device_create()` and never written afterwards. + unsafe { (*phydev).phy_id } + } + + /// Reads a PHY register. + // This function reads a hardware register and updates the stats so takes `&mut self`. + pub fn read(&mut self, reg: R) -> Result { + reg.read(self) + } + + /// Writes a PHY register. + pub fn write(&mut self, reg: R, val: u16) -> Result { + reg.write(self, val) + } + + /// Executes software reset the PHY via `BMCR_RESET` bit. + pub fn genphy_soft_reset(&mut self) -> Result { + let phydev = self.0.get(); + // SAFETY: `phydev` is pointing to a valid object by the type invariant of `Self`. The C + // function does not require `phy_device->lock`; PHYLIB itself calls it without the lock. + to_result(unsafe { bindings::genphy_soft_reset(phydev) }) + } +} + +impl AsRef for Device { fn as_ref(&self) -> &kernel::device::Device { let phydev = self.0.get(); // SAFETY: The struct invariant ensures that `mdio.dev` is valid. diff --git a/rust/kernel/net/phy/reg.rs b/rust/kernel/net/phy/reg.rs index 80e22c264ea8..e6892f3b855f 100644 --- a/rust/kernel/net/phy/reg.rs +++ b/rust/kernel/net/phy/reg.rs @@ -8,7 +8,10 @@ //! Ethernet management interface clauses 22 and 45 register namespaces, as //! defined in IEEE 802.3. -use super::Device; +use super::{ + Device, + PhyContext, // +}; use crate::{ build_assert::build_assert, error::*, @@ -44,10 +47,10 @@ pub trait Sealed {} /// ``` pub trait Register: private::Sealed { /// Reads a PHY register. - fn read(&self, dev: &mut Device) -> Result; + fn read(&self, dev: &mut Device) -> Result; /// Writes a PHY register. - fn write(&self, dev: &mut Device, val: u16) -> Result; + fn write(&self, dev: &mut Device, val: u16) -> Result; /// Checks the link status and updates current link state. fn read_status(dev: &mut Device) -> Result; @@ -104,7 +107,7 @@ pub const fn vendor_specific() -> Self { impl private::Sealed for C22 {} impl Register for C22 { - fn read(&self, dev: &mut Device) -> Result { + fn read(&self, dev: &mut Device) -> Result { let phydev = dev.0.get(); // SAFETY: `phydev` is pointing to a valid object by the type invariant of `Device`. // So it's just an FFI call, open code of `phy_read()` with a valid `phy_device` pointer @@ -116,7 +119,7 @@ fn read(&self, dev: &mut Device) -> Result { Ok(ret as u16) } - fn write(&self, dev: &mut Device, val: u16) -> Result { + fn write(&self, dev: &mut Device, val: u16) -> Result { let phydev = dev.0.get(); // SAFETY: `phydev` is pointing to a valid object by the type invariant of `Device`. // So it's just an FFI call, open code of `phy_write()` with a valid `phy_device` pointer @@ -196,7 +199,7 @@ pub fn new(devad: Mmd, regnum: u16) -> Self { impl private::Sealed for C45 {} impl Register for C45 { - fn read(&self, dev: &mut Device) -> Result { + fn read(&self, dev: &mut Device) -> Result { let phydev = dev.0.get(); // SAFETY: `phydev` is pointing to a valid object by the type invariant of `Device`. // So it's just an FFI call. @@ -206,7 +209,7 @@ fn read(&self, dev: &mut Device) -> Result { Ok(ret as u16) } - fn write(&self, dev: &mut Device, val: u16) -> Result { + fn write(&self, dev: &mut Device, val: u16) -> Result { let phydev = dev.0.get(); // SAFETY: `phydev` is pointing to a valid object by the type invariant of `Device`. // So it's just an FFI call. -- 2.54.0