[PATCH 0/2] Cleanup the call ordering of phy_init and phy_power_on

[PATCH 0/2] Cleanup the call ordering of phy_init and phy_power_on

[Jules Maselbas]

Hi,

Last year Ahmad asked what is the correct order when calling phy_init
and phy_power_on. Since then, I didn't see the situation improve much
and I am once again toying around with usb phy driver.

The following two patches were in my tree for a year... Last year i
previously tried to change the call order in the dwc2 driver but this
requires the relevent phy to be also compatible with the "new" ordering.
The stm32-usbphyc driver wasn't compatible, I am not sure if that is
still is the case.

For now simply add documentation, hopefully correct, but I am not an
expert on actual phy sementics or usage in the kernel. And add warning
when the order is not what's expected.

Best,

Jules Maselbas (2):
  phy: core: Add documentation of phy operation order
  phy: core: Warn when phy_power_on is called before phy_init

 drivers/phy/phy-core.c | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

-- 
2.17.1

[PATCH 1/2] phy: core: Add documentation of phy operation order

[Jules Maselbas]

Add documentation on phy function usage: init function must be
called before power_on; power_off must be called before exit.

Signed-off-by: Jules Maselbas <jmaselbas@kalray.eu>
CC: Ahmad Fatoum <a.fatoum@pengutronix.de>
CC: Amelie DELAUNAY <amelie.delaunay@foss.st.com>
---
 drivers/phy/phy-core.c | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/drivers/phy/phy-core.c b/drivers/phy/phy-core.c
index 91e28d6ce450..ed10cbb24b08 100644
--- a/drivers/phy/phy-core.c
+++ b/drivers/phy/phy-core.c
@@ -229,6 +229,17 @@ void phy_pm_runtime_forbid(struct phy *phy)
 }
 EXPORT_SYMBOL_GPL(phy_pm_runtime_forbid);
 
+/**
+ * phy_init - phy internal initialization before phy operation
+ * @phy: the phy returned by phy_get()
+ *
+ * Used to allow phy's driver to perform phy internal initialization,
+ * such as PLL block powering, clock initialization or anything that's
+ * is required by the phy to perform the start of operation.
+ * Must be called before phy_power_on().
+ *
+ * Returns: 0 if successful, an negative error code otherwise
+ */
 int phy_init(struct phy *phy)
 {
 	int ret;
@@ -258,6 +269,14 @@ int phy_init(struct phy *phy)
 }
 EXPORT_SYMBOL_GPL(phy_init);
 
+/**
+ * phy_exit - Phy internal un-initialization
+ * @phy: the phy returned by phy_get()
+ *
+ * Must be called after phy_power_off().
+ *
+ * Returns: 0 if successful, an negative error code otherwise
+ */
 int phy_exit(struct phy *phy)
 {
 	int ret;
@@ -287,6 +306,14 @@ int phy_exit(struct phy *phy)
 }
 EXPORT_SYMBOL_GPL(phy_exit);
 
+/**
+ * phy_power_on - Enable the phy and enter proper operation
+ * @phy: the phy returned by phy_get()
+ *
+ * Must be called after phy_init().
+ *
+ * Returns: 0 if successful, an negative error code otherwise
+ */
 int phy_power_on(struct phy *phy)
 {
 	int ret = 0;
@@ -329,6 +356,14 @@ int phy_power_on(struct phy *phy)
 }
 EXPORT_SYMBOL_GPL(phy_power_on);
 
+/**
+ * phy_power_off - Disable the phy.
+ * @phy: the phy returned by phy_get()
+ *
+ * Must be called before phy_exit().
+ *
+ * Returns: 0 if successful, an negative error code otherwise
+ */
 int phy_power_off(struct phy *phy)
 {
 	int ret;
-- 
2.17.1

Re: [PATCH 1/2] phy: core: Add documentation of phy operation order

[Randy Dunlap]

Hi--

On 3/22/22 07:30, Jules Maselbas wrote:
> Add documentation on phy function usage: init function must be
> called before power_on; power_off must be called before exit.
> 
> Signed-off-by: Jules Maselbas <jmaselbas@kalray.eu>
> CC: Ahmad Fatoum <a.fatoum@pengutronix.de>
> CC: Amelie DELAUNAY <amelie.delaunay@foss.st.com>
> ---
>  drivers/phy/phy-core.c | 35 +++++++++++++++++++++++++++++++++++
>  1 file changed, 35 insertions(+)
> 
> diff --git a/drivers/phy/phy-core.c b/drivers/phy/phy-core.c
> index 91e28d6ce450..ed10cbb24b08 100644
> --- a/drivers/phy/phy-core.c
> +++ b/drivers/phy/phy-core.c
> @@ -229,6 +229,17 @@ void phy_pm_runtime_forbid(struct phy *phy)
>  }
>  EXPORT_SYMBOL_GPL(phy_pm_runtime_forbid);
>  
> +/**
> + * phy_init - phy internal initialization before phy operation
> + * @phy: the phy returned by phy_get()
> + *
> + * Used to allow phy's driver to perform phy internal initialization,
> + * such as PLL block powering, clock initialization or anything that's
> + * is required by the phy to perform the start of operation.
> + * Must be called before phy_power_on().
> + *
> + * Returns: 0 if successful, an negative error code otherwise

    * Return: %0 if successful, a negative error code otherwise

(in all 4 functions)

> + */
>  int phy_init(struct phy *phy)

-- 
~Randy

[PATCH 2/2] phy: core: Warn when phy_power_on is called before phy_init

[Jules Maselbas]

A warning when the order of phy operation is mixed up by drivers,
this is an atempt to make the phy usage more uniform across (usb)
drivers.

CC: Ahmad Fatoum <a.fatoum@pengutronix.de>
CC: Amelie DELAUNAY <amelie.delaunay@foss.st.com>
Signed-off-by: Jules Maselbas <jmaselbas@kalray.eu>
---
 drivers/phy/phy-core.c | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/drivers/phy/phy-core.c b/drivers/phy/phy-core.c
index ed10cbb24b08..2c2c0f073080 100644
--- a/drivers/phy/phy-core.c
+++ b/drivers/phy/phy-core.c
@@ -252,6 +252,9 @@ int phy_init(struct phy *phy)
 		return ret;
 	ret = 0; /* Override possible ret == -ENOTSUPP */
 
+	if (phy->power_count > phy->init_count)
+		dev_warn(&phy->dev, "phy_power_on was called before phy_init\n");
+
 	mutex_lock(&phy->mutex);
 	if (phy->init_count == 0 && phy->ops->init) {
 		ret = phy->ops->init(phy);
-- 
2.17.1