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

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

On Wed, 12 Jan 2022 19:16:02 +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
> 

My bot found errors running 'make DT_CHECKER_FLAGS=-m dt_binding_check'
on your patch (DT_CHECKER_FLAGS is new in v5.13):

yamllint warnings/errors:
./Documentation/devicetree/bindings/phy/transmit-amplitude.yaml:98:7: [warning] wrong indentation: expected 8 but found 6 (indentation)
./Documentation/devicetree/bindings/phy/transmit-amplitude.yaml:100:7: [warning] wrong indentation: expected 8 but found 6 (indentation)

dtschema/dtc warnings/errors:

doc reference errors (make refcheckdocs):

See https://patchwork.ozlabs.org/patch/1579281

This check can fail if there are any dependencies. The base for a patch
series is generally the most recent rc1.

If you already ran 'make dt_binding_check' and didn't see the above
error(s), then make sure 'yamllint' is installed and dt-schema is up to
date:

pip3 install dtschema --upgrade

Please check and re-submit.

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
> 
>

On Tue, 18 Jan 2022 21:07:09 -0600
Rob Herring <robh@kernel.org> wrote:

> > +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.

Thanks, sent v3. Will you be applying the patch? Or should this be
applied the first time it is needed, by maintainer of the specific
subsystem?

Marek