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

[Russell King (Oracle)]

Update the generic PHY documentation as a result of the discussion for
the s32g submission.

Link: https://lore.kernel.org/r/aXtvDn_-pCuKPrnf@vaman
Signed-off-by: Russell King (Oracle) <rmk+kernel at armlinux.org.uk>
---
I didn't get any replies to my follow-up question to Vinod:

  Please also indicate in the documentation whether changing the submode
  of the serdes (particularly for ethernet) is permitted without doing a
  phy_power_down()..phy_power_up() dance around the phy_set_mode_ext()
  call.

I also didn't get any response to:

  For drivers such as stmmac, it will be important that details such as
  whether phy_est_mode*() can be called with the PHY powered on are
  riveted down and not left up to the generic PHY driver author - without
  that, generic PHYs basically aren't usable from SoC/platform
  independent code, and stmmac has bazillions of platform specific glue
  already because of (a) bad code structuring and (b) lack of
  generalisation through standardised interfaces that abstract platform
  differences.

  I want to be able for core stmmac code, or even phylink code (which
  is even more platform generic) to be able to make use of generic PHY
  stuff, but if the calls that can be made into generic PHY are platform
  dependent, that is a blocking issue against that, and makes me question
  why we have the generic PHY subsystem... it's not very generic if it
  exposes the differences of each implementation to users of its
  interfaces.

 Documentation/driver-api/phy/phy.rst | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/driver-api/phy/phy.rst b/Documentation/driver-api/phy/phy.rst
index 719a2b3fd2ab..cf73e4fb0951 100644
--- a/Documentation/driver-api/phy/phy.rst
+++ b/Documentation/driver-api/phy/phy.rst
@@ -142,6 +142,7 @@ Order of API calls
 
     [devm_][of_]phy_get()
     phy_init()
+    [phy_set_mode[_ext]()]
     phy_power_on()
     [phy_set_mode[_ext]()]
     ...
@@ -154,7 +155,7 @@ but controllers should always call these functions to be compatible with other
 PHYs. Some PHYs may require :c:func:`phy_set_mode <phy_set_mode_ext>`, while
 others may use a default mode (typically configured via devicetree or other
 firmware). For compatibility, you should always call this function if you know
-what mode you will be using. Generally, this function should be called after
+what mode you will be using. Generally, this function should be called before
 :c:func:`phy_power_on`, although some PHY drivers may allow it at any time.
 
 Releasing a reference to the PHY
-- 
2.47.3