From: SeungJong Ha <engineer.jjhama@gmail.com>
To: "FUJITA Tomonori" <fujita.tomonori@gmail.com>,
"Trevor Gross" <tmgross@umich.edu>,
"David S. Miller" <davem@davemloft.net>,
"Eric Dumazet" <edumazet@kernel.org>,
"Jakub Kicinski" <kuba@kernel.org>,
"Paolo Abeni" <pabeni@redhat.com>,
"Simon Horman" <horms@kernel.org>,
"Miguel Ojeda" <ojeda@kernel.org>,
"Boqun Feng" <boqun@kernel.org>, "Gary Guo" <gary@garyguo.net>,
"Björn Roy Baron" <bjorn3_gh@protonmail.com>,
"Benno Lossin" <lossin@kernel.org>,
"Andreas Hindborg" <a.hindborg@kernel.org>,
"Alice Ryhl" <aliceryhl@google.com>,
"Danilo Krummrich" <dakr@kernel.org>,
"Daniel Almeida" <daniel.almeida@collabora.com>,
"Tamir Duberstein" <tamird@kernel.org>,
"Alexandre Courbot" <acourbot@nvidia.com>,
"Onur Özkan" <work@onurozkan.dev>, "Andrew Lunn" <andrew@lunn.ch>,
"Heiner Kallweit" <hkallweit1@gmail.com>,
"Russell King" <linux@armlinux.org.uk>
Cc: netdev@vger.kernel.org, rust-for-linux@vger.kernel.org,
linux-kernel@vger.kernel.org,
SeungJong Ha <engineer.jjhama@gmail.com>
Subject: [PATCH RESEND net-next v2 2/3] rust: net: phy: make Device generic over a lock context
Date: Sun, 15 Nov 2026 15:47:37 +0900 [thread overview]
Message-ID: <20261115-exp-phy-rs-maybelocked-v2-2-8fa7897a0352@gmail.com> (raw)
In-Reply-To: <20261115-exp-phy-rs-maybelocked-v2-0-8fa7897a0352@gmail.com>
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 <engineer.jjhama@gmail.com>
---
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<MaybeLocked>`].
+///
+/// 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<Locked>`, 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<Locked>`] 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<bindings::phy_device>);
+pub struct Device<Ctx: PhyContext = Locked>(Opaque<bindings::phy_device>, PhantomData<Ctx>);
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::<Self>();
- // 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<R: reg::Register>(&mut self, reg: R) -> Result<u16> {
- reg.read(self)
- }
-
- /// Writes a PHY register.
- pub fn write<R: reg::Register>(&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<u16> {
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<kernel::device::Device> for Device {
+impl<Ctx: PhyContext> Device<Ctx> {
+ /// 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::<Self>();
+ // 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<R: reg::Register>(&mut self, reg: R) -> Result<u16> {
+ reg.read(self)
+ }
+
+ /// Writes a PHY register.
+ pub fn write<R: reg::Register>(&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<Ctx: PhyContext> AsRef<kernel::device::Device> for Device<Ctx> {
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<u16>;
+ fn read<C: PhyContext>(&self, dev: &mut Device<C>) -> Result<u16>;
/// Writes a PHY register.
- fn write(&self, dev: &mut Device, val: u16) -> Result;
+ fn write<C: PhyContext>(&self, dev: &mut Device<C>, val: u16) -> Result;
/// Checks the link status and updates current link state.
fn read_status(dev: &mut Device) -> Result<u16>;
@@ -104,7 +107,7 @@ pub const fn vendor_specific<const N: u8>() -> Self {
impl private::Sealed for C22 {}
impl Register for C22 {
- fn read(&self, dev: &mut Device) -> Result<u16> {
+ fn read<C: PhyContext>(&self, dev: &mut Device<C>) -> Result<u16> {
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<u16> {
Ok(ret as u16)
}
- fn write(&self, dev: &mut Device, val: u16) -> Result {
+ fn write<C: PhyContext>(&self, dev: &mut Device<C>, 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<u16> {
+ fn read<C: PhyContext>(&self, dev: &mut Device<C>) -> Result<u16> {
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<u16> {
Ok(ret as u16)
}
- fn write(&self, dev: &mut Device, val: u16) -> Result {
+ fn write<C: PhyContext>(&self, dev: &mut Device<C>, 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
next prev parent reply other threads:[~2026-11-15 6:48 UTC|newest]
Thread overview: 6+ messages / expand[flat|nested] mbox.gz Atom feed top
2026-11-15 6:47 [net-next PATCH RESEND v2 0/3] rust: net: phy: soft_reset may run without phy_device->lock SeungJong Ha
2026-11-15 6:47 ` [PATCH RESEND net-next v2 1/3] rust: net: phy: drop read_mmd and write_mmd from Driver SeungJong Ha
2026-11-15 6:47 ` SeungJong Ha [this message]
2026-11-16 7:33 ` [PATCH RESEND net-next v2 2/3] rust: net: phy: make Device generic over a lock context netdev-bot+sashiko
2026-11-15 6:47 ` [PATCH RESEND net-next v2 3/3] rust: net: phy: pass a MaybeLocked device to soft_reset SeungJong Ha
2026-11-16 7:33 ` netdev-bot+sashiko
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20261115-exp-phy-rs-maybelocked-v2-2-8fa7897a0352@gmail.com \
--to=engineer.jjhama@gmail.com \
--cc=a.hindborg@kernel.org \
--cc=acourbot@nvidia.com \
--cc=aliceryhl@google.com \
--cc=andrew@lunn.ch \
--cc=bjorn3_gh@protonmail.com \
--cc=boqun@kernel.org \
--cc=dakr@kernel.org \
--cc=daniel.almeida@collabora.com \
--cc=davem@davemloft.net \
--cc=edumazet@kernel.org \
--cc=fujita.tomonori@gmail.com \
--cc=gary@garyguo.net \
--cc=hkallweit1@gmail.com \
--cc=horms@kernel.org \
--cc=kuba@kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux@armlinux.org.uk \
--cc=lossin@kernel.org \
--cc=netdev@vger.kernel.org \
--cc=ojeda@kernel.org \
--cc=pabeni@redhat.com \
--cc=rust-for-linux@vger.kernel.org \
--cc=tamird@kernel.org \
--cc=tmgross@umich.edu \
--cc=work@onurozkan.dev \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox
all inboxes | Powered by JetHome®