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

Sean Anderson
2022-10-18T18:02:19Z

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
> ================================
>
>