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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Date:   Tue, 18 Oct 2022 14:01:56 -0400
From:   Sean Anderson <sean.anderson@...o.com>
To:     Kishon Vijay Abraham I <kishon@...com>,
        Vinod Koul <vkoul@...nel.org>, linux-phy@...ts.infradead.org
Cc:     Jonathan Corbet <corbet@....net>, linux-kernel@...r.kernel.org,
        linux-doc@...r.kernel.org
Subject: Re: [PATCH] doc: phy: Document typical order of API calls

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@...o.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
>  ================================
>  
>