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

[Russell King (Oracle)]

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.

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.

-- 
RMK's Patch system: https://www.armlinux.org.uk/developer/patches/
FTTP is here! 80Mbps down 10Mbps up. Decent connectivity at last!