[PATCH] doc: phy: Document typical order of API calls

[PATCH] doc: phy: Document typical order of API calls

[Sean Anderson]

Document the typical order of API calls to used by new drivers and
controllers. Many existing controllers follow this order, but some do
not. This is especially true for controllers designed to work with one
particular PHY driver, which may not need a call to (for example)
phy_init.

Signed-off-by: Sean Anderson <sean.anderson@seco.com>
---

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

diff --git a/Documentation/driver-api/phy/phy.rst b/Documentation/driver-api/phy/phy.rst
index 8fc1ce0bb905..8e8b3e8f9523 100644
--- a/Documentation/driver-api/phy/phy.rst
+++ b/Documentation/driver-api/phy/phy.rst
@@ -94,7 +94,8 @@ Inorder to dereference the private data (in phy_ops), the phy provider driver
 can use phy_set_drvdata() after creating the PHY and use phy_get_drvdata() in
 phy_ops to get back the private data.
 
-4. Getting a reference to the PHY
+Getting a reference to the PHY
+==============================
 
 Before the controller can make use of the PHY, it has to get a reference to
 it. This framework provides the following APIs to get a reference to the PHY.
@@ -130,6 +131,28 @@ the phy_init() and phy_exit() calls, and phy_power_on() and
 phy_power_off() calls are all NOP when applied to a NULL phy. The NULL
 phy is useful in devices for handling optional phy devices.
 
+Order of API calls
+==================
+
+The general order of calls should be::
+
+    [devm_][of_]phy_get()
+    phy_init()
+    phy_power_on()
+    [phy_set_mode[_ext]()]
+    ...
+    phy_power_off()
+    phy_exit()
+    [[of_]phy_put()]
+
+Some PHY drivers may not implement :c:func:`phy_init` or :c:func:`phy_power_on`,
+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
+:c:func:`phy_power_on`, although some PHY drivers may allow it at any time.
+
 Releasing a reference to the PHY
 ================================
 
-- 
2.35.1.1320.gc452695387.dirty


-- 
linux-phy mailing list
linux-phy@lists.infradead.org
https://lists.infradead.org/mailman/listinfo/linux-phy

Re: [PATCH] doc: phy: Document typical order of API calls

[Sean Anderson]

Hi Vinod,

When sending this patch, I noticed that Kishon's email bounced. Is he
still maintaining this subsystem? He hasn't been very active for the
past year.

--Sean

On 10/18/22 1:58 PM, Sean Anderson wrote:
> Document the typical order of API calls to used by new drivers and
> controllers. Many existing controllers follow this order, but some do
> not. This is especially true for controllers designed to work with one
> particular PHY driver, which may not need a call to (for example)
> phy_init.
> 
> Signed-off-by: Sean Anderson <sean.anderson@seco.com>
> ---
> 
>  Documentation/driver-api/phy/phy.rst | 25 ++++++++++++++++++++++++-
>  1 file changed, 24 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/driver-api/phy/phy.rst b/Documentation/driver-api/phy/phy.rst
> index 8fc1ce0bb905..8e8b3e8f9523 100644
> --- a/Documentation/driver-api/phy/phy.rst
> +++ b/Documentation/driver-api/phy/phy.rst
> @@ -94,7 +94,8 @@ Inorder to dereference the private data (in phy_ops), the phy provider driver
>  can use phy_set_drvdata() after creating the PHY and use phy_get_drvdata() in
>  phy_ops to get back the private data.
>  
> -4. Getting a reference to the PHY
> +Getting a reference to the PHY
> +==============================
>  
>  Before the controller can make use of the PHY, it has to get a reference to
>  it. This framework provides the following APIs to get a reference to the PHY.
> @@ -130,6 +131,28 @@ the phy_init() and phy_exit() calls, and phy_power_on() and
>  phy_power_off() calls are all NOP when applied to a NULL phy. The NULL
>  phy is useful in devices for handling optional phy devices.
>  
> +Order of API calls
> +==================
> +
> +The general order of calls should be::
> +
> +    [devm_][of_]phy_get()
> +    phy_init()
> +    phy_power_on()
> +    [phy_set_mode[_ext]()]
> +    ...
> +    phy_power_off()
> +    phy_exit()
> +    [[of_]phy_put()]
> +
> +Some PHY drivers may not implement :c:func:`phy_init` or :c:func:`phy_power_on`,
> +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
> +:c:func:`phy_power_on`, although some PHY drivers may allow it at any time.
> +
>  Releasing a reference to the PHY
>  ================================
>  
> 

-- 
linux-phy mailing list
linux-phy@lists.infradead.org
https://lists.infradead.org/mailman/listinfo/linux-phy

Re: [PATCH] doc: phy: Document typical order of API calls

[Vinod Koul]

On 18-10-22, 14:01, Sean Anderson wrote:
> Hi Vinod,
> 
> When sending this patch, I noticed that Kishon's email bounced. Is he

See 76845ba539c3 is phy/fixes

-- 
~Vinod

-- 
linux-phy mailing list
linux-phy@lists.infradead.org
https://lists.infradead.org/mailman/listinfo/linux-phy

Re: [PATCH] doc: phy: Document typical order of API calls

[Bagas Sanjaya]

On 10/19/22 01:01, Sean Anderson wrote:
> Hi Vinod,
> 
> When sending this patch, I noticed that Kishon's email bounced. Is he
> still maintaining this subsystem? He hasn't been very active for the
> past year.
> 

He's now using @kernel.org address <kishon@kernel.org> (see [1]).

Thanks.

[1]: https://lore.kernel.org/lkml/20220928102431.658-1-kishon@ti.com/

-- 
An old man doll... just what I always wanted! - Clara


-- 
linux-phy mailing list
linux-phy@lists.infradead.org
https://lists.infradead.org/mailman/listinfo/linux-phy

Re: [PATCH] doc: phy: Document typical order of API calls

[Vinod Koul]

On 18-10-22, 13:58, Sean Anderson wrote:
> Document the typical order of API calls to used by new drivers and
> controllers. Many existing controllers follow this order, but some do
> not. This is especially true for controllers designed to work with one
> particular PHY driver, which may not need a call to (for example)
> phy_init.

Applied, thanks

-- 
~Vinod

-- 
linux-phy mailing list
linux-phy@lists.infradead.org
https://lists.infradead.org/mailman/listinfo/linux-phy