[devicetree,1/2] dt-bindings: phy: Convert generic PHY provider binding to YAML

Commit Message

Marek Behún Dec. 14, 2021, 11:34 p.m. UTC

Convert phy-bindings.txt to YAML. This creates binding only for PHY
provider, since PHY consumer binding is in dtschema. Consumer binding
example is provided.

Signed-off-by: Marek Behún <[e-mail]>
---
 .../devicetree/bindings/phy/phy-bindings.txt  | 73 +------------------
 .../devicetree/bindings/phy/phy.yaml          | 59 +++++++++++++++
 2 files changed, 60 insertions(+), 72 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/phy/phy.yaml

Comments

Rob Herring (Arm) Dec. 15, 2021, 9:41 p.m. UTC | #1

On Wed, Dec 15, 2021 at 12:34:31AM +0100, Marek Behún wrote:
> Convert phy-bindings.txt to YAML. This creates binding only for PHY
> provider, since PHY consumer binding is in dtschema. Consumer binding
> example is provided.
> 
> Signed-off-by: Marek Behún <[e-mail]>
> ---
>  .../devicetree/bindings/phy/phy-bindings.txt  | 73 +------------------
>  .../devicetree/bindings/phy/phy.yaml          | 59 +++++++++++++++
>  2 files changed, 60 insertions(+), 72 deletions(-)
>  create mode 100644 Documentation/devicetree/bindings/phy/phy.yaml

We already have phy-provider.yaml and phy-consumer.yaml in dtschema 
repo. Add what's missing there (anything copied from here will need to 
be relicensed).

Rob

Patch

diff --git a/Documentation/devicetree/bindings/phy/phy-bindings.txt b/Documentation/devicetree/bindings/phy/phy-bindings.txt
index c4eb38902533..ded3cf18352d 100644
--- a/Documentation/devicetree/bindings/phy/phy-bindings.txt
+++ b/Documentation/devicetree/bindings/phy/phy-bindings.txt
@@ -1,72 +1 @@ 
-This document explains only the device tree data binding. For general
-information about PHY subsystem refer to Documentation/driver-api/phy/phy.rst
-
-PHY device node
-===============
-
-Required Properties:
-#phy-cells:	Number of cells in a PHY specifier;  The meaning of all those
-		cells is defined by the binding for the phy node. The PHY
-		provider can use the values in cells to find the appropriate
-		PHY.
-
-Optional Properties:
-phy-supply:	Phandle to a regulator that provides power to the PHY. This
-		regulator will be managed during the PHY power on/off sequence.
-
-For example:
-
-phys: phy {
-    compatible = "xxx";
-    reg = <...>;
-    .
-    .
-    #phy-cells = <1>;
-    .
-    .
-};
-
-That node describes an IP block (PHY provider) that implements 2 different PHYs.
-In order to differentiate between these 2 PHYs, an additional specifier should be
-given while trying to get a reference to it.
-
-PHY user node
-=============
-
-Required Properties:
-phys : the phandle for the PHY device (used by the PHY subsystem; not to be
-       confused with the Ethernet specific 'phy' and 'phy-handle' properties,
-       see Documentation/devicetree/bindings/net/ethernet.txt for these)
-phy-names : the names of the PHY corresponding to the PHYs present in the
-	    *phys* phandle
-
-Example 1:
-usb1: usb_otg_ss@xxx {
-    compatible = "xxx";
-    reg = <xxx>;
-    .
-    .
-    phys = <&usb2_phy>, <&usb3_phy>;
-    phy-names = "usb2phy", "usb3phy";
-    .
-    .
-};
-
-This node represents a controller that uses two PHYs, one for usb2 and one for
-usb3.
-
-Example 2:
-usb2: usb_otg_ss@xxx {
-    compatible = "xxx";
-    reg = <xxx>;
-    .
-    .
-    phys = <&phys 1>;
-    phy-names = "usbphy";
-    .
-    .
-};
-
-This node represents a controller that uses one of the PHYs of the PHY provider
-device defined previously. Note that the phy handle has an additional specifier
-"1" to differentiate between the two PHYs.
+This file has moved to ./phy.yaml.
diff --git a/Documentation/devicetree/bindings/phy/phy.yaml b/Documentation/devicetree/bindings/phy/phy.yaml
new file mode 100644
index 000000000000..a5b6b04cff5b
--- /dev/null
+++ b/Documentation/devicetree/bindings/phy/phy.yaml
@@ -0,0 +1,59 @@ 
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/phy/phy.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Common PHY Provider Generic Binding
+
+description:
+  This is the generic binding for common PHYs providers.
+
+maintainers:
+  - Kishon Vijay Abraham I <[e-mail]>
+  - Vinod Koul <[e-mail]>
+
+select:
+  required:
+    - '#phy-cells'
+
+properties:
+  '#phy-cells':
+    $ref: '/schemas/types.yaml#/definitions/uint32'
+    description:
+      Number of cells in a PHY specifier. The meaning of all those cells is
+      defined by the binding for the PHY node. The PHY provider can use the
+      values in cells to find the appropriate PHY.
+    maximum: 16
+
+  phy-supply:
+    description:
+      Phandle to a regulator that provides power to the PHY. This regulator
+      will be managed during the PHY power on/off sequence.
+
+required:
+  - '#phy-cells'
+
+additionalProperties: true
+
+examples:
+  - |
+    phy_regulator: regulator {
+      compatible = "regulator-fixed";
+      regulator-name = "phy-regulator";
+    };
+
+    phy: phy {
+      #phy-cells = <1>;
+      phy-supply = <&phy_regulator>;
+    };
+
+    ethernet-controller {
+      phys = <&phy 0>;
+      phy-names = "ethphy";
+    };
+
+    usb {
+      phys = <&phy 1>, <&phy 2>;
+      phy-names = "usb2phy", "usb3phy";
+    };