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

[Vladimir Oltean]

On Thu, Feb 12, 2026 at 10:44:27AM +0530, Vinod Koul wrote:
> Lets document that call order is immaterial and driver is expected to
> work both ways? As I said earlier logically people would set things up
> and power up, and on the fly mode changes can be handled internally in
> the driver by doing off-set-on dance.

FWIW, I already started telling people during review to not rely on call
order:
https://lore.kernel.org/linux-phy/20260210193516.temrg46yozxma7xb@skbuf

I don't mind continuing to scan for this in new submissions. Then, only
the topic of existing drivers remains to be resolved.

> Thinking out loud, we can also move this into framework and ensure when
> modes are set, we do off-set-on dance so that onus on providers is
> removed. Moving into fwk might expose some bugs in drivers though...
> 
> One thing I agree is that we should have consistency. How we drive that
> can be agreed upon.
> 
> Thanks
> -- 
> ~Vinod

I kind of like the fact that the framework doesn't have power vs mode
assumptions built in.

Also thinking out loud, we could do something else - introduce something
similar in spirit to CONFIG_DEBUG_TEST_DRIVER_REMOVE, which would be a
debug option that sees what power state the PHY is in during the
phy_set_mode_ext() call, flips it before calling ->set_mode() (calling
either ->power_on() or ->power_off()), and restores it after the call.

Having this option should also give PHY provider developers a quick way
of testing both calling orders without modifying the consumers.