Re: [PATCH] phy: core: document calibrate() method

From: Kishon Vijay Abraham I
Date: Fri Jul 19 2019 - 06:06:02 EST


Hi Marek,

On 19/07/19 3:22 PM, Marek Szyprowski wrote:
> Commit 36914111e682 ("drivers: phy: add calibrate method") added support
> for generic phy_calibrate() method, but it didn't explain in detail when
> such method is supposed to be called. Add some more documentation directly
> to the phy.h to make it clean that it is intended to be called after every
> host controller reset.
>
> Signed-off-by: Marek Szyprowski <m.szyprowski@xxxxxxxxxxx>
> ---
> include/linux/phy/phy.h | 12 ++++++++++++
> 1 file changed, 12 insertions(+)
>
> diff --git a/include/linux/phy/phy.h b/include/linux/phy/phy.h
> index 15032f145063..46775e8b0ed9 100644
> --- a/include/linux/phy/phy.h
> +++ b/include/linux/phy/phy.h
> @@ -101,6 +101,18 @@ struct phy_ops {
> int (*validate)(struct phy *phy, enum phy_mode mode, int submode,
> union phy_configure_opts *opts);
> int (*reset)(struct phy *phy);
> +
> + /**
> + * @calibrate:
> + *
> + * Optional.
> + *
> + * Used to calibrate phy, typically by adjusting some parameters
> + * in runtime, which are otherwise lost after host controller
> + * reset and cannot be set in phy_init() and phy_power_on().
> + *
> + * Returns: 0 if successful, an negative error code otherwise
> + */
> int (*calibrate)(struct phy *phy);

This should be added in drivers/phy/phy-core.c before phy_calibrate()? We could
add a separate section in Documentation/phy.txt to document these phy_ops.

Thanks
Kishon