On Fri, 20 Oct 2023 20:42:10 +0200
Andrew Lunn [off-list ref] wrote:

quoted

quoted

+//! All the PHYLIB helper functions for `phy_device` modify some members in `phy_device`. Except for
+//! getter functions, [`Device`] methods take `&mut self`. This also applied to `read()`, which reads
+//! a hardware register and updates the stats.

I would use [`Device`] instead of `phy_device`, since the Rust reader
might not be aware what wraps `phy_device`.

We don't want to hide phy_device too much, since at the moment, the
abstraction is very minimal. Anybody writing a driver is going to need
a good understanding of the C code in order to find the helpers they
need, and then add them to the abstraction. So i would say we need to
explain the relationship between the C structure and the Rust
structure, to aid developers.

I'm sure that Rust readers would notice Device wraps `phy_device`
because the comment on Device clearly says so.

/// An instance of a PHY device.
///
/// Wraps the kernel's `struct phy_device`.
///
/// # Invariants
///
/// `self.0` is always in a valid state.
#[repr(transparent)]
pub struct Device(Opaque<bindings::phy_device>);


I think that the relationships between the C and Rust structures are
documented in phy.rs.