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

[Vladimir Oltean]

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.