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

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

[Marek Behún]

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,
which should be referenced by any binding that uses it.

Signed-off-by: Marek Behún <kabel@kernel.org>
---
Change since v2:
- removed 'select:' as requested by Rob. Instead the schema should be
  referenced by any binding that uses it. This also fixed indentation
  warnings from Rob's bot, since they warned about lines in the select
  statement
---
 .../bindings/phy/transmit-amplitude.yaml      | 103 ++++++++++++++++++
 1 file changed, 103 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..51492fe738ec
--- /dev/null
+++ b/Documentation/devicetree/bindings/phy/transmit-amplitude.yaml
@@ -0,0 +1,103 @@
+# 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 ]
+
+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

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

[Marc Kleine-Budde]

[-- Attachment #1: Type: text/plain, Size: 1982 bytes --]

On 19.01.2022 14:11:17, 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,
> which should be referenced by any binding that uses it.

If I understand your use-case correctly, you need different voltage p2p
levels in the connection between the Ethernet MAC and the Ethernet
switch or Ethernet-PHY?

Some of the two wire Ethernet standards (10base-T1S, 10base-T1L,
100base-T1, 1000base-T1) defines several p2p voltage levels on the wire,
i.e. between the PHYs. Alexandru has posed a series where you can
specify the between-PHY voltage levels:

| https://lore.kernel.org/all/20211210110509.20970-8-alexandru.tachici@analog.com/

Can we make clear that your binding specifies the voltage level on the
MII interface, in contrast Alexandru's binding?

regards,
Marc

-- 
Pengutronix e.K.                 | Marc Kleine-Budde           |
Embedded Linux                   | https://www.pengutronix.de  |
Vertretung West/Dortmund         | Phone: +49-231-2826-924     |
Amtsgericht Hildesheim, HRA 2686 | Fax:   +49-5121-206917-5555 |

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

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

[Marek Behún]

On Thu, 20 Jan 2022 09:49:14 +0100
Marc Kleine-Budde <mkl@pengutronix.de> wrote:

> On 19.01.2022 14:11:17, 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,
> > which should be referenced by any binding that uses it.  
> 
> If I understand your use-case correctly, you need different voltage p2p
> levels in the connection between the Ethernet MAC and the Ethernet
> switch or Ethernet-PHY?

This is a SerDes differential pair amplitude. So yes to your question,
if the MII interface uses differential pair, like sgmii, 10gbase-r, ...

> Some of the two wire Ethernet standards (10base-T1S, 10base-T1L,
> 100base-T1, 1000base-T1) defines several p2p voltage levels on the wire,
> i.e. between the PHYs. Alexandru has posed a series where you can
> specify the between-PHY voltage levels:
> 
> | https://lore.kernel.org/all/20211210110509.20970-8-alexandru.tachici@analog.com/

Copper ethernet is something different, so no conflict

> Can we make clear that your binding specifies the voltage level on the
> MII interface, in contrast Alexandru's binding?

The binding explicitly says "common PHY", not ethernet PHY. I don't
thing there will be any confusion. It can also be specified for USB3+
differential pairs, or PCIe differential pairs, or DisplayPort
differential pairs...

Marek

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

[Marc Kleine-Budde]

[-- Attachment #1: Type: text/plain, Size: 2755 bytes --]

On 20.01.2022 19:01:55, Marek Behún wrote:
> On Thu, 20 Jan 2022 09:49:14 +0100
> Marc Kleine-Budde <mkl@pengutronix.de> wrote:
> 
> > On 19.01.2022 14:11:17, 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,
> > > which should be referenced by any binding that uses it.  
> > 
> > If I understand your use-case correctly, you need different voltage p2p
> > levels in the connection between the Ethernet MAC and the Ethernet
> > switch or Ethernet-PHY?
> 
> This is a SerDes differential pair amplitude. So yes to your question,
> if the MII interface uses differential pair, like sgmii, 10gbase-r, ...
> 
> > Some of the two wire Ethernet standards (10base-T1S, 10base-T1L,
> > 100base-T1, 1000base-T1) defines several p2p voltage levels on the wire,
> > i.e. between the PHYs. Alexandru has posed a series where you can
> > specify the between-PHY voltage levels:
> > 
> > | https://lore.kernel.org/all/20211210110509.20970-8-alexandru.tachici@analog.com/
> 
> Copper ethernet is something different, so no conflict
> 
> > Can we make clear that your binding specifies the voltage level on the
> > MII interface, in contrast Alexandru's binding?
> 
> The binding explicitly says "common PHY", not ethernet PHY. I don't
> thing there will be any confusion. It can also be specified for USB3+
> differential pairs, or PCIe differential pairs, or DisplayPort
> differential pairs...

Thanks for the clarification.

regards,
Marc

-- 
Pengutronix e.K.                 | Marc Kleine-Budde           |
Embedded Linux                   | https://www.pengutronix.de  |
Vertretung West/Dortmund         | Phone: +49-231-2826-924     |
Amtsgericht Hildesheim, HRA 2686 | Fax:   +49-5121-206917-5555 |

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

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

[Florian Fainelli]

On 1/19/22 5:11 AM, 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,
> which should be referenced by any binding that uses it.

p2p commonly means peer to peer which incidentally could be confusing,
can you spell out the property entire:

tx-peaktopeak-microvolt or:

tx-pk2pk-microvolt for a more compact name maybe?
-- 
Florian

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

[Rob Herring]

On Fri, Jan 21, 2022 at 11:18:09AM -0800, Florian Fainelli wrote:
> On 1/19/22 5:11 AM, 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,
> > which should be referenced by any binding that uses it.
> 
> p2p commonly means peer to peer which incidentally could be confusing,
> can you spell out the property entire:
> 
> tx-peaktopeak-microvolt or:
> 
> tx-pk2pk-microvolt for a more compact name maybe?

Peer to peer makes little sense in terms of a voltage. I think this is 
fine as-is.

Rob

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

[Florian Fainelli]

On 2/4/2022 6:18 PM, Rob Herring wrote:
> On Fri, Jan 21, 2022 at 11:18:09AM -0800, Florian Fainelli wrote:
>> On 1/19/22 5:11 AM, 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,
>>> which should be referenced by any binding that uses it.
>>
>> p2p commonly means peer to peer which incidentally could be confusing,
>> can you spell out the property entire:
>>
>> tx-peaktopeak-microvolt or:
>>
>> tx-pk2pk-microvolt for a more compact name maybe?
> 
> Peer to peer makes little sense in terms of a voltage. I think this is
> fine as-is.

Understood, my point was that peer is a word that is commonly used in an 
environment where you are talking about networking equipment at large. 
Anyway, feel free to ignore it.
-- 
Florian

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

[Marek Behún]

On Fri, 4 Feb 2022 20:18:40 -0600
Rob Herring <robh@kernel.org> wrote:

> On Fri, Jan 21, 2022 at 11:18:09AM -0800, Florian Fainelli wrote:
> > On 1/19/22 5:11 AM, 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,
> > > which should be referenced by any binding that uses it.  
> > 
> > p2p commonly means peer to peer which incidentally could be confusing,
> > can you spell out the property entire:
> > 
> > tx-peaktopeak-microvolt or:
> > 
> > tx-pk2pk-microvolt for a more compact name maybe?  
> 
> Peer to peer makes little sense in terms of a voltage. I think this is 
> fine as-is.

Cool. Should this get merged via devicetree, or via phy maintainers?
Or should I resend this together with patches that make use of this
property? (In that case can you add your Ack?)

Thanks.

Marek

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

[Vinod Koul]

On 06-02-22, 18:54, Marek Behún wrote:
> On Fri, 4 Feb 2022 20:18:40 -0600
> Rob Herring <robh@kernel.org> wrote:
> 
> > On Fri, Jan 21, 2022 at 11:18:09AM -0800, Florian Fainelli wrote:
> > > On 1/19/22 5:11 AM, 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,
> > > > which should be referenced by any binding that uses it.  
> > > 
> > > p2p commonly means peer to peer which incidentally could be confusing,
> > > can you spell out the property entire:
> > > 
> > > tx-peaktopeak-microvolt or:
> > > 
> > > tx-pk2pk-microvolt for a more compact name maybe?  
> > 
> > Peer to peer makes little sense in terms of a voltage. I think this is 
> > fine as-is.
> 
> Cool. Should this get merged via devicetree, or via phy maintainers?
> Or should I resend this together with patches that make use of this
> property? (In that case can you add your Ack?)

Sending with patches using this would be better.. It can go thru phy
tree

-- 
~Vinod

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

[Rob Herring]

On Wed, 19 Jan 2022 14:11:17 +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,
> which should be referenced by any binding that uses it.
> 
> Signed-off-by: Marek Behún <kabel@kernel.org>
> ---
> Change since v2:
> - removed 'select:' as requested by Rob. Instead the schema should be
>   referenced by any binding that uses it. This also fixed indentation
>   warnings from Rob's bot, since they warned about lines in the select
>   statement
> ---
>  .../bindings/phy/transmit-amplitude.yaml      | 103 ++++++++++++++++++
>  1 file changed, 103 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/phy/transmit-amplitude.yaml
> 

Reviewed-by: Rob Herring <robh@kernel.org>