Every PHY driver callback gets a `Device` that assumes `phy_device->lock` is held, but suspend may run while another path holds it. Make `Device` generic over a lock context, `Locked` (the default) or `MaybeLocked`, as `device::Device` is, and move the methods that do not need the lock to both contexts. The next patch moves suspend to `MaybeLocked`. Document when the `Locked` callbacks run without the lock, including the existing phy_mii_ioctl() race, and fix their SAFETY comments. No functional change. Signed-off-by: SeungJong Ha --- rust/kernel/net/phy.rs | 207 +++++++++++++++++++++++++++------------------ rust/kernel/net/phy/reg.rs | 17 ++-- 2 files changed, 133 insertions(+), 91 deletions(-) diff --git a/rust/kernel/net/phy.rs b/rust/kernel/net/phy.rs index 4604a9c0a511..8cbb4c19dac1 100644 --- a/rust/kernel/net/phy.rs +++ b/rust/kernel/net/phy.rs @@ -50,6 +50,55 @@ 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 with `phy_device->lock` held, except: +/// +/// - [`Driver::probe`] and [`Driver::get_features`], which `phy_probe()` calls without the lock +/// before the device is attached. +/// - [`Driver::soft_reset`], which `phy_init_hw()` calls without the lock from +/// `phy_attach_direct()` and `mdio_bus_phy_resume()` while the state machine is not running, and +/// from MAC drivers that call `phy_init_hw()` directly, which are then responsible for exclusive +/// access. `phy_mii_ioctl()` also calls it without the lock while the state machine may run, +/// which is an existing PHYLIB race. +/// - [`Driver::read_status`], when a MAC driver calls `phy_read_status()` directly. The MAC +/// driver is then responsible for exclusive access. +/// +/// # 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 may call without `phy_device->lock` while +/// another path holds it. +/// +/// Only methods that do not rely on the lock are available. 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,48 +106,19 @@ 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 -/// a context where all methods defined on this struct are safe to call. -/// - This struct always has a valid `self.0.mdio.dev`. +/// - `self.0` is a valid `phy_device`, and `self.0.mdio.dev` is a valid `struct device`. +/// - The invariants of `Ctx` hold for the lifetime of a `&mut Device`. /// /// [`struct phy_device`]: srctree/include/linux/phy.h -// During the calls to most functions in [`Driver`], the C side (`PHYLIB`) holds a lock that is -// unique for every instance of [`Device`]. `PHYLIB` uses a different serialization technique for -// [`Driver::resume`] and [`Driver::suspend`]: `PHYLIB` updates `phy_device`'s state with -// the lock held, thus guaranteeing that [`Driver::resume`] has exclusive access to the instance. -// [`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 +197,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(); @@ -238,14 +247,6 @@ pub fn genphy_resume(&mut self) -> Result { to_result(unsafe { bindings::genphy_resume(phydev) }) } - /// Suspends the PHY via `BMCR_PDOWN` bit. - pub fn genphy_suspend(&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_suspend(phydev) }) - } - /// Checks the link status and updates current link state. pub fn genphy_read_status(&mut self) -> Result { R::read_status(self) @@ -276,7 +277,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) + } + + /// Suspends the PHY via `BMCR_PDOWN` bit. + pub fn genphy_suspend(&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 only sets `BMCR_PDOWN`, serialized by the MDIO bus lock. + to_result(unsafe { bindings::genphy_suspend(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. @@ -309,10 +355,10 @@ impl Adapter { /// `phydev` must be passed by the corresponding callback in `phy_driver`. unsafe extern "C" fn soft_reset_callback(phydev: *mut bindings::phy_device) -> c_int { from_result(|| { - // SAFETY: This callback is called only in contexts - // where we hold `phy_device->lock`, so the accessors on - // `Device` are okay to call. - let dev = unsafe { Device::from_raw(phydev) }; + // SAFETY: `phy_init_hw()` calls this with `phy_device->lock` held, or without it while + // the state machine is not running or a MAC driver ensures exclusive access. + // `phy_mii_ioctl()` is an exception, see `Locked`. This is the `Locked` context. + let dev = unsafe { Device::::from_raw(phydev) }; T::soft_reset(dev)?; Ok(0) }) @@ -323,11 +369,9 @@ impl Adapter { /// `phydev` must be passed by the corresponding callback in `phy_driver`. unsafe extern "C" fn probe_callback(phydev: *mut bindings::phy_device) -> c_int { from_result(|| { - // SAFETY: This callback is called only in contexts - // where we can exclusively access `phy_device` because - // it's not published yet, so the accessors on `Device` are okay - // to call. - let dev = unsafe { Device::from_raw(phydev) }; + // SAFETY: `phy_probe()` calls this before the device is attached, when no other PHYLIB + // path accesses it. This is the `Locked` context. + let dev = unsafe { Device::::from_raw(phydev) }; T::probe(dev)?; Ok(0) }) @@ -338,10 +382,9 @@ impl Adapter { /// `phydev` must be passed by the corresponding callback in `phy_driver`. unsafe extern "C" fn get_features_callback(phydev: *mut bindings::phy_device) -> c_int { from_result(|| { - // SAFETY: This callback is called only in contexts - // where we hold `phy_device->lock`, so the accessors on - // `Device` are okay to call. - let dev = unsafe { Device::from_raw(phydev) }; + // SAFETY: `phy_probe()` calls this without `phy_device->lock`, under the same + // assumption as `probe`. This is the `Locked` context. + let dev = unsafe { Device::::from_raw(phydev) }; T::get_features(dev)?; Ok(0) }) @@ -366,10 +409,9 @@ impl Adapter { /// `phydev` must be passed by the corresponding callback in `phy_driver`. unsafe extern "C" fn resume_callback(phydev: *mut bindings::phy_device) -> c_int { from_result(|| { - // SAFETY: The C core code ensures that the accessors on - // `Device` are okay to call even though `phy_device->lock` - // might not be held. - let dev = unsafe { Device::from_raw(phydev) }; + // SAFETY: `__phy_resume()` asserts that `phy_device->lock` is held. This is the + // `Locked` context. + let dev = unsafe { Device::::from_raw(phydev) }; T::resume(dev)?; Ok(0) }) @@ -380,10 +422,9 @@ impl Adapter { /// `phydev` must be passed by the corresponding callback in `phy_driver`. unsafe extern "C" fn config_aneg_callback(phydev: *mut bindings::phy_device) -> c_int { from_result(|| { - // SAFETY: This callback is called only in contexts - // where we hold `phy_device->lock`, so the accessors on - // `Device` are okay to call. - let dev = unsafe { Device::from_raw(phydev) }; + // SAFETY: PHYLIB holds `phy_device->lock` when it calls this. This is the `Locked` + // context. + let dev = unsafe { Device::::from_raw(phydev) }; T::config_aneg(dev)?; Ok(0) }) @@ -394,10 +435,10 @@ impl Adapter { /// `phydev` must be passed by the corresponding callback in `phy_driver`. unsafe extern "C" fn read_status_callback(phydev: *mut bindings::phy_device) -> c_int { from_result(|| { - // SAFETY: This callback is called only in contexts - // where we hold `phy_device->lock`, so the accessors on - // `Device` are okay to call. - let dev = unsafe { Device::from_raw(phydev) }; + // SAFETY: PHYLIB holds `phy_device->lock` when it calls this, or a MAC driver that + // calls `phy_read_status()` directly ensures exclusive access. This is the `Locked` + // context. + let dev = unsafe { Device::::from_raw(phydev) }; T::read_status(dev)?; Ok(0) }) @@ -407,10 +448,8 @@ impl Adapter { /// /// `phydev` must be passed by the corresponding callback in `phy_driver`. unsafe extern "C" fn link_change_notify_callback(phydev: *mut bindings::phy_device) { - // SAFETY: This callback is called only in contexts - // where we hold `phy_device->lock`, so the accessors on - // `Device` are okay to call. - let dev = unsafe { Device::from_raw(phydev) }; + // SAFETY: PHYLIB holds `phy_device->lock` when it calls this. This is the `Locked` context. + let dev = unsafe { Device::::from_raw(phydev) }; T::link_change_notify(dev); } } 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