Re: [PATCH devicetree v2] dt-bindings: phy: Add `tx-p2p-microvolt` property binding

[Rob Herring <robh@kernel.org>]

On Wed, Jan 12, 2022 at 07:16:02PM +0100, Marek Behún wrote:
> Common PHYs and network PCSes 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-p2p-microvolt` and `tx-p2p-microvolt-names` for this
> purpose. The second property is needed to specify the mode for the
> corresponding voltage in the `tx-p2p-microvolt` property, if the voltage
> is to be used only for speficic mode. More voltage-mode pairs can be
> specified.
> 
> Example usage with only one voltage (it will be used for all supported
> PHY modes, the `tx-p2p-microvolt-names` property is not needed in this
> case):
> 
>   tx-p2p-microvolt = <915000>;
> 
> Example usage with voltages for multiple modes:
> 
>   tx-p2p-microvolt = <915000>, <1100000>, <1200000>;
>   tx-p2p-microvolt-names = "2500base-x", "usb", "pcie";
> 
> Add these properties into a separate file phy/transmit-amplitude.yaml,
> selecting it for validation if either of the `tx-p2p-microvolt`,
> `tx-p2p-microvolt-names` properties is set for a node.
> 
> Signed-off-by: Marek Behún <kabel@kernel.org>
> ---
>  .../bindings/phy/transmit-amplitude.yaml      | 110 ++++++++++++++++++
>  1 file changed, 110 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/phy/transmit-amplitude.yaml
> 
> diff --git a/Documentation/devicetree/bindings/phy/transmit-amplitude.yaml b/Documentation/devicetree/bindings/phy/transmit-amplitude.yaml
> new file mode 100644
> index 000000000000..90a491b75f61
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/phy/transmit-amplitude.yaml
> @@ -0,0 +1,110 @@
> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/phy/transmit-amplitude.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Common PHY and network PCS transmit amplitude property binding
> +
> +description:
> +  Binding describing the peak-to-peak transmit amplitude for common PHYs
> +  and network PCSes.
> +
> +maintainers:
> +  - Marek Behún <kabel@kernel.org>
> +
> +properties:
> +  tx-p2p-microvolt:
> +    description:
> +      Transmit amplitude voltages in microvolts, peak-to-peak. If this property
> +      contains multiple values for various PHY modes, the
> +      'tx-p2p-microvolt-names' property must be provided and contain
> +      corresponding mode names.
> +
> +  tx-p2p-microvolt-names:
> +    description: |
> +      Names of the modes corresponding to voltages in the 'tx-p2p-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.
> +    minItems: 1
> +    maxItems: 16
> +    items:
> +      enum:
> +        - default
> +
> +        # ethernet modes
> +        - sgmii
> +        - qsgmii
> +        - xgmii
> +        - 1000base-x
> +        - 2500base-x
> +        - 5gbase-r
> +        - rxaui
> +        - xaui
> +        - 10gbase-kr
> +        - usxgmii
> +        - 10gbase-r
> +        - 25gbase-r
> +
> +        # PCIe modes
> +        - pcie
> +        - pcie1
> +        - pcie2
> +        - pcie3
> +        - pcie4
> +        - pcie5
> +        - pcie6
> +
> +        # USB modes
> +        - usb
> +        - usb-ls
> +        - usb-fs
> +        - usb-hs
> +        - usb-ss
> +        - usb-ss+
> +        - usb-4
> +
> +        # storage modes
> +        - sata
> +        - ufs-hs
> +        - ufs-hs-a
> +        - ufs-hs-b
> +
> +        # display modes
> +        - lvds
> +        - dp
> +        - dp-rbr
> +        - dp-hbr
> +        - dp-hbr2
> +        - dp-hbr3
> +        - dp-uhbr-10
> +        - dp-uhbr-13.5
> +        - dp-uhbr-20
> +
> +        # camera modes
> +        - mipi-dphy
> +        - mipi-dphy-univ
> +        - mipi-dphy-v2.5-univ
> +
> +dependencies:
> +  tx-p2p-microvolt-names: [ tx-p2p-microvolt ]
> +
> +select:

This should be omitted and this schema should be referenced by any 
binding that uses it. That is necessary so all properties get evaluated.

> +  anyOf:
> +    - required:
> +      - 'tx-p2p-microvolt'
> +    - required:
> +      - 'tx-p2p-microvolt-names'
> +
> +additionalProperties: true
> +
> +examples:
> +  - |
> +    phy: phy {
> +      #phy-cells = <1>;
> +      tx-p2p-microvolt = <915000>, <1100000>, <1200000>;
> +      tx-p2p-microvolt-names = "2500base-x", "usb-hs", "usb-ss";
> +    };
> -- 
> 2.34.1
> 
>