[PATCH net-next] doc: generic phy: update generic PHY documentation

[Vladimir Oltean]

On Wed, Feb 11, 2026 at 09:30:06PM +0200, Vladimir Oltean wrote:
> On Wed, Feb 11, 2026 at 06:15:11PM +0000, Russell King (Oracle) wrote:
> > On Wed, Feb 11, 2026 at 05:48:39PM +0200, Vladimir Oltean wrote:
> > > My 2 cents: I would actually remove any reference to any sort of preferred
> > > call order. There's nothing in the framework to back up such a concept.
> > > Just say that it is recommended for PHY provider drivers to not rely on
> > > a particular calling order, such that PHY consumers have the freedom to
> > > choose depending on what suits them best.
> > 
> > Sending out this patch was a last ditch attempt to get a response to
> > improve the "generic" PHY subsystem, However, as the issue is now
> > almost two weeks old, and the current patch series causes a regression
> > according to Mohd's testing, I've rewritten the series to be a finer
> > set of smaller incremental changes.
> > 
> > This has meant dropping the idea of using the "generic" PHY subsystem
> > in generic code, because as "generic" PHY drivers are currently
> > written, that's just impossible given the current state of "generic"
> > PHY.
> > 
> > There are "generic" PHY drivers that require to be powered up for
> > any of the phy_set_*() functions to not error out. There are also
> > "generic" PHY drivers that require the PHY to be powered down
> > before calling phy_set_*() before the new setting taking effect
> > at PHY power up time. In this group there are drivers that error
> > out if phy_set_*() is called while the PHY is powered, and there
> > are drivers that silently accept the call, returning success, but
> > do not change the PHY mode.
> 
> Are we talking about PHY_MODE_ETHERNET generic PHYs here, or in general?
> 
> > This makes it pretty much impossible for platform independent code to
> > know the correct order to call the functions, and what to do if an
> > error or success is returned from any particular API call.
> > 
> > In other words, it's a trainwreck as currently implemented, and this
> > was my attempt to try and get some consistency.
> 
> Do you have a list of such PHYs relevant to phylink? We can still
> document the expectation, and modify them.

To (partially) answer my own question, here is what I found so far:

commit 5cb630925b49dd13bf3aa43f299b11615c8fe9cd
Author: Yoshihiro Shimoda <yoshihiro.shimoda.uh at renesas.com>
Date:   Wed Feb 1 22:14:53 2023 +0900

    net: renesas: rswitch: Add phy_power_{on,off}() calling

    Some Ethernet PHYs (like marvell10g) will decide the host interface
    mode by the media-side speed. So, the rswitch driver needs to
    initialize one of the Ethernet SERDES (r8a779f0-eth-serdes) ports
    after linked the Ethernet PHY up. The r8a779f0-eth-serdes driver has
    .init() for initializing all ports and .power_on() for initializing
    each port. So, add phy_power_{on,off} calling for it.

    Signed-off-by: Yoshihiro Shimoda <yoshihiro.shimoda.uh at renesas.com>
    Signed-off-by: David S. Miller <davem at davemloft.net>

This needs to be changed, for sure.

I'll take a closer look tomorrow at the rest and see how bad the
situation is overall.