[PATCH devicetree 2/2] dt-bindings: phy: Add `tx-amplitude-microvolt` property binding

[Marek Behún <kabel@xxxxxxxxxx>]

Common PHYs often have the possibility to specify peak-to-peak voltage
on the differential pair - the default voltage sometimes needs to be
changed for a particular board.

Add properties `tx-amplitude-microvolt` and
`tx-amplitude-microvolt-names` for this purpose. The second property is
needed to specify

Example usage with only one voltage (it will be used for all supported
PHY modes, the `tx-amplitude-microvolt-names` property is not needed in
this case):

  tx-amplitude-microvolt = <915000>;

Example usage with voltages for multiple modes:

  tx-amplitude-microvolt = <915000>, <1100000>, <1200000>;
  tx-amplitude-microvolt-names = "2500base-x", "usb", "pcie";

Signed-off-by: Marek Behún <kabel@xxxxxxxxxx>
---

I wanted to constrain the values allowed in the
`tx-amplitude-microvolt-names` property to:
- ethernet SerDes modes (sgmii, qsgmii, 10gbase-r, 2500base-x, ...)
- PCIe modes (pattern: ^pcie[1-6]?$)
- USB modes (pattern: ^usb((-host|-device|-otg)?-(ls|fs|hs|ss|ss\+|4))?$)
- DisplayPort modes (pattern: ^dp(-rbr|-hbr[23]?|-uhbr-(10|13.5|20))?$)
- Camera modes (mipi-dphy, mipi-dphy-univ, mipi-dphy-v2.5-univ)
- Storage modes (sata, ufs-hs, ufs-hs-a, ufs-hs-b)

But was unable to. The '-names' suffix implies string-array type, and
string-array type does not allow to specify a type for all items in a
simple way, i.e.:
  items:
    enum:
      - sgmii
      - sata
      - usb
      ...
Such constraint does work when changing ethernet controller's
`phy-connection-type` to array, see
https://lore.kernel.org/netdev/20211123164027.15618-2-kabel@xxxxxxxxxx/

But it seems that string-array type prohibits this.

---
 .../devicetree/bindings/phy/phy.yaml          | 22 +++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/Documentation/devicetree/bindings/phy/phy.yaml b/Documentation/devicetree/bindings/phy/phy.yaml
index a5b6b04cff5b..8915065cf6c2 100644
--- a/Documentation/devicetree/bindings/phy/phy.yaml
+++ b/Documentation/devicetree/bindings/phy/phy.yaml
@@ -31,9 +31,29 @@ properties:
       Phandle to a regulator that provides power to the PHY. This regulator
       will be managed during the PHY power on/off sequence.
 
+  tx-amplitude-microvolt:
+    description:
+      Transmit amplitude voltages in microvolts, peak-to-peak. If this property
+      contains multiple values for various PHY modes, the
+      'tx-amplitude-microvolt-names' property must be provided and contain
+      corresponding mode names.
+
+  tx-amplitude-microvolt-names:
+    description: |
+      Names of the modes corresponding to voltages in the
+      'tx-amplitude-microvolt' property. Required only if multiple voltages
+      are provided.
+
+      If a value of 'default' is provided, the system should use it for any PHY
+      mode that is otherwise not defined here. If 'default' is not provided, the
+      system should use manufacturer default value.
+
 required:
   - '#phy-cells'
 
+dependencies:
+  tx-amplitude-microvolt-names: [ tx-amplitude-microvolt ]
+
 additionalProperties: true
 
 examples:
@@ -46,6 +66,8 @@ examples:
     phy: phy {
       #phy-cells = <1>;
       phy-supply = <&phy_regulator>;
+      tx-amplitude-microvolt = <915000>, <1100000>, <1200000>;
+      tx-amplitude-microvolt-names = "2500base-x", "usb-hs", "usb-ss";
     };
 
     ethernet-controller {
-- 
2.32.0