Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Subject: Re: [PATCH] doc: phy: Document typical order of API calls
To:     Kishon Vijay Abraham I <kishon@ti.com>,
        Vinod Koul <vkoul@kernel.org>, linux-phy@lists.infradead.org
Cc:     Jonathan Corbet <corbet@lwn.net>, linux-kernel@vger.kernel.org,
        linux-doc@vger.kernel.org
References: <20221018175841.1906611-1-sean.anderson@seco.com>
From:   Sean Anderson <sean.anderson@seco.com>
Message-ID: <e002248f-7070-3f89-04f2-e7f694fad5cc@seco.com>
Date:   Tue, 18 Oct 2022 14:01:56 -0400
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101
 Thunderbird/68.10.0
In-Reply-To: <20221018175841.1906611-1-sean.anderson@seco.com>
Content-Type: text/plain; charset=utf-8
Content-Language: en-US
Content-Transfer-Encoding: 7bit
MIME-Version: 1.0
X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1
X-MS-Exchange-AntiSpam-MessageData-0: =?utf-8?B?ZVZTTjRNeEgvWlEvaEVUSzhCQkVoOE91MVNxZ0dFUGsybVdRbjFlY0tMbkp6?=
 =?utf-8?B?NEdPdUVqRW9ScFhaWWxWS0tvNDdQS3FmczNDS2tCSHlqd1lQNWpSSm1IOWNV?=
 =?utf-8?B?azIrazBIOWZiWEFub3RZTjJMZ1UyVE9JYys5bFdGdU5NVmxJaHpvT3RyNDZJ?=
 =?utf-8?B?aEdhR2F4bVNRMzRHdkVjeGVCZXpCRElmY2t6YWx6SFhEcFpVcFhwc2RHTnJz?=
 =?utf-8?B?eThvbmpyYU1oc3lOUjNKdVdTcE5GMVkyRkhXejNPSHBsZ055eGpFQUFLSHBr?=
 =?utf-8?B?RENjak5MRzNWMnM4YXE3ekp6am1zL3A5UEhFblk0am56RjVHQkE2WmNiWGx5?=
 =?utf-8?B?NURBeWlraHFOQm41eWY1WDQ5TlZvcXpxVWpWVkhRSERyVHZTUGNpdWcvRWlE?=
 =?utf-8?B?eWRaVEpHV0NUeUpJTWhDTEFiK25rSWdXSFlYYStBVXFIUERLZEFBWEdpLzhl?=
 =?utf-8?B?dlMyR2pxcXNXNUlBLysvVmJOeWpXNzdQRFU0NHJwakQzemFiVGhPSm5QR3J2?=
 =?utf-8?B?WXU1ektZenl0Wnl4NmhXZHd0OEpHaUZPV3pUZzB0a0xjSnNacCtmQXdvMGhB?=
 =?utf-8?B?azBKWXJwNE5OYnVIeTdFVEpORjRTa0w5aUhieFBGcUVyT3BweWg5b2M0cGZI?=
 =?utf-8?B?RmRKTWMxTnFXOFY4cDBoYk9QWnJnVGJQOFpST1dwL2luOFA1SVRQTUk1MDlC?=
 =?utf-8?B?b2JScUowR1liMmRYYjI2RkNQMGI5YnVBMzVtNHhDd3RsdnBFdUdkQkF6Qk9J?=
 =?utf-8?B?bU44QzM2aFBTR25VVWxBOCtFVDNXTXNncFNRUzhVbEc5MXVuRGhyZ3pvOVMr?=
 =?utf-8?B?bkRIU3lxN01KQkhpbHRnTnBiU0RhMVhHUUF1VCttaWZ4UmFiTmxXN3poZGNS?=
 =?utf-8?B?RGg3WXUyNStVOGlxdWp4YVJKQnB5YmtFVUlDc1NuODJBVDNFcFJ5NlBpbHRa?=
 =?utf-8?B?clZvWVZBWkNJZTlydnp1dExRdGVyNW95QzBZTkwyUng2eXFTTm03NnFwRktN?=
 =?utf-8?B?WVJVVWwxemI2bDNYRUU2V3hTdmp1SDdYOWNNdnZ4THdWLy9ZakVzK0dXUlZW?=
 =?utf-8?B?dS9CZ0hWT1RlbW91Nzg3ejFDbCtiWmwvOVJKRi9yUXJDMjliYmJNY3JoSDVm?=
 =?utf-8?B?SjdvNGNOTXJvcC80RlhaTzVweUpYWnl5OVIzYjRIcFZHYmRqQ2JQaUY5NFlv?=
 =?utf-8?B?bSs1LzQ4bkdsL0pyZ0FSNEZtRHR2RlpLY3V5VFY4aGZtVzcrU2txMHA0MjVM?=
 =?utf-8?B?aGRiaVdRTjdPNlM3Tnc3QVp6WFNySXRpU1BUdTllOUh6OC9UbCs4cnZDbjRu?=
 =?utf-8?B?MjNmcnZoeGZiSEtmSERsQmNwa0QyeVlZVVVPaVRyOWJYUkUrNmdOeDZTRDBJ?=
 =?utf-8?B?djJjZjRpWVlIcDdwdUtpNldrOUlpNE1MRkU4UHhSandzVkViUWd3cTlPcXlD?=
 =?utf-8?B?UGthckR0T1FQZmpLT1RRWFV2azVXZTI3dStFK00zM0JKYVBhWEhhSU5wbGR2?=
 =?utf-8?B?dUxRb2pJK2JhM3JWZFNlQU5TR095dlM0dWpEK3BoZVkyNC9Ec0pjQWF4R3Ra?=
 =?utf-8?B?eDhCZERRNVprdjhxanBMajF2TDgzT05BWlVteUhWdkwzZWhKMWdlSmYwQlBN?=
 =?utf-8?B?eEM1YUg1cnVWQi81WWp3enRnY2JuNHFQV2FNTDczWlVLVEtmUkJwMHhQYXlU?=
 =?utf-8?B?YzZkandRaXp2THlyL1Y3dnNqWmpSbWpDeHlBYlVCRkYrakxPWmVmcTE4ZTRj?=
 =?utf-8?B?ODFZUzcxRWdHd01KdVJ4YW4wSjMvR1ZRNWYwUDN1TmpWMkpaU1ZVaWR3M25D?=
 =?utf-8?B?emV4NEpqMDJzcHlNclI2ZzJDRmhWQk5WUUdwNEsyNTY4UmRZdzUzclpvUmtz?=
 =?utf-8?B?dlNhT0ltVXZTQWoxZ2p3LzVyNEQ3ZHdvNUM3a1hiSUpBY3lBUDlRTnZqb1V3?=
 =?utf-8?B?QkJMcjVPeXJUeENXUWNoTWRlNnBuQmFzbDNLeENEa2szUWtvMnVUS0dXbitK?=
 =?utf-8?B?dDhaMWtzb1B1VzRQQzM3bnpqRmJhQ3lYYU8xSUxoZjRBbUlvWlh3VEFoYXJD?=
 =?utf-8?B?OG5jTEh3eGg5SVRaWUZENFpzVVhlNVNJc2xEU3FQN3dLUEs2R1FTbEhhS0l1?=
 =?utf-8?B?cUtoR2NJbG9hdjdyM2tDM0hLUmhkL3hwQVgydmVEZ0dKNnBKMDg2TGlJd2dO?=
 =?utf-8?B?OXc9PQ==?=
X-OriginatorOrg: seco.com
X-MS-Exchange-CrossTenant-Network-Message-Id: dd87c345-2209-456a-481a-08dab132dad8
X-MS-Exchange-CrossTenant-AuthSource: DB7PR03MB4972.eurprd03.prod.outlook.com
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 18 Oct 2022 18:02:00.5684
 (UTC)
X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted
X-MS-Exchange-CrossTenant-Id: bebe97c3-6438-442e-ade3-ff17aa50e733
X-MS-Exchange-CrossTenant-MailboxType: HOSTED
X-MS-Exchange-CrossTenant-UserPrincipalName: x8dijnLdZAYpuy3be0nbLThLudFsnoJllh+/vCAmsehSFnb/RyKDMng1+EJwVvK4iKHoSiY/3CLz2QyfLMmK3g==
X-MS-Exchange-Transport-CrossTenantHeadersStamped: GV2PR03MB9428
X-Spam-Status: No, score=-2.1 required=5.0 tests=BAYES_00,DKIM_SIGNED,
        DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,NICE_REPLY_A,RCVD_IN_DNSWL_NONE,
        RCVD_IN_MSPIKE_H2,SPF_HELO_PASS,SPF_PASS autolearn=ham
        autolearn_force=no version=3.4.6
X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on
        lindbergh.monkeyblade.net
Precedence: bulk
List-ID: <linux-kernel.vger.kernel.org>
X-Mailing-List: linux-kernel@vger.kernel.org

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