Re: [RFC PATCH net-next] dt-bindings: dpll: Add per-channel Ethernet reference property

[Rob Herring <robh@kernel.org>]

On Fri, Aug 29, 2025 at 8:29 AM Ivan Vecera <ivecera@redhat.com> wrote:
>
> Hi Rob,
>
> On 20. 08. 25 11:13 odp., Rob Herring wrote:
> > On Fri, Aug 15, 2025 at 04:47:35PM +0200, Ivan Vecera wrote:
> >> In case of SyncE scenario a DPLL channels generates a clean frequency
> >> synchronous Ethernet clock (SyncE) and feeds it into the NIC transmit
> >> path. The DPLL channel can be locked either to the recovered clock
> >> from the NIC's PHY (Loop timing scenario) or to some external signal
> >> source (e.g. GNSS) (Externally timed scenario).
> >>
> >> The example shows both situations. NIC1 recovers the input SyncE signal
> >> that is used as an input reference for DPLL channel 1. The channel locks
> >> to this signal, filters jitter/wander and provides holdover. On output
> >> the channel feeds a stable, phase-aligned clock back into the NIC1.
> >> In the 2nd case the DPLL channel 2 locks to a master clock from GNSS and
> >> feeds a clean SyncE signal into the NIC2.
> >>
> >>                 +-----------+
> >>              +--|   NIC 1   |<-+
> >>              |  +-----------+  |
> >>              |                 |
> >>              | RxCLK     TxCLK |
> >>              |                 |
> >>              |  +-----------+  |
> >>              +->| channel 1 |--+
> >> +------+        |-- DPLL ---|
> >> | GNSS |---------->| channel 2 |--+
> >> +------+  RefCLK   +-----------+  |
> >>                                |
> >>                          TxCLK |
> >>                                |
> >>                 +-----------+  |
> >>                 |   NIC 2   |<-+
> >>                 +-----------+
> >>
> >> In the situations above the DPLL channels should be registered into
> >> the DPLL sub-system with the same Clock Identity as PHCs present
> >> in the NICs (for the example above DPLL channel 1 uses the same
> >> Clock ID as NIC1's PHC and the channel 2 as NIC2's PHC).
> >>
> >> Because a NIC PHC's Clock ID is derived from the NIC's MAC address,
> >> add a per-channel property 'ethernet-handle' that specifies a reference
> >> to a node representing an Ethernet device that uses this channel
> >> to synchronize its hardware clock. Additionally convert existing
> >> 'dpll-types' list property to 'dpll-type' per-channel property.
> >>
> >> Suggested-by: Andrew Lunn <andrew@lunn.ch>
> >> Signed-off-by: Ivan Vecera <ivecera@redhat.com>
> >> ---
> >>   .../devicetree/bindings/dpll/dpll-device.yaml | 40 ++++++++++++++++---
> >>   .../bindings/dpll/microchip,zl30731.yaml      | 29 +++++++++++++-
> >>   2 files changed, 62 insertions(+), 7 deletions(-)
> >>
> >> diff --git a/Documentation/devicetree/bindings/dpll/dpll-device.yaml b/Documentation/devicetree/bindings/dpll/dpll-device.yaml
> >> index fb8d7a9a3693f..798c5484657cf 100644
> >> --- a/Documentation/devicetree/bindings/dpll/dpll-device.yaml
> >> +++ b/Documentation/devicetree/bindings/dpll/dpll-device.yaml
> >> @@ -27,11 +27,41 @@ properties:
> >>     "#size-cells":
> >>       const: 0
> >>
> >> -  dpll-types:
> >> -    description: List of DPLL channel types, one per DPLL instance.
> >> -    $ref: /schemas/types.yaml#/definitions/non-unique-string-array
> >> -    items:
> >> -      enum: [pps, eec]
> >
> > Dropping this is an ABI change. You can't do that unless you are
> > confident there are no users both in existing DTs and OSs.
>
> Get it, will keep.
>
> >> +  channels:
> >> +    type: object
> >> +    description: DPLL channels
> >> +    unevaluatedProperties: false
> >> +
> >> +    properties:
> >> +      "#address-cells":
> >> +        const: 1
> >> +      "#size-cells":
> >> +        const: 0
> >> +
> >> +    patternProperties:
> >> +      "^channel@[0-9a-f]+$":
> >> +        type: object
> >> +        description: DPLL channel
> >> +        unevaluatedProperties: false
> >> +
> >> +        properties:
> >> +          reg:
> >> +            description: Hardware index of the DPLL channel
> >> +            maxItems: 1
> >> +
> >> +          dpll-type:
> >> +            description: DPLL channel type
> >> +            $ref: /schemas/types.yaml#/definitions/string
> >> +            enum: [pps, eec]
> >> +
> >> +          ethernet-handle:
> >> +            description:
> >> +              Specifies a reference to a node representing an Ethernet device
> >> +              that uses this channel to synchronize its hardware clock.
> >> +            $ref: /schemas/types.yaml#/definitions/phandle
> >
> > Seems a bit odd to me that the ethernet controller doesn't have a link
> > to this node instead.
>
> Do you mean to add a property (e.g. dpll-channel or dpll-device) into
> net/network-class.yaml ? If so, yes, it would be possible, and the way
> I look at it now, it would probably be better. The DPLL driver can
> enumerate all devices across the system that has this specific property
> and check its value.

Yes. Or into ethernet-controller.yaml. Is a DPLL used with wifi,
bluetooth, etc.?

>
> See the proposal below...
>
> Thanks,
> Ivan
>
> ---
>   Documentation/devicetree/bindings/dpll/dpll-device.yaml  | 6 ++++++
>   Documentation/devicetree/bindings/net/network-class.yaml | 7 +++++++
>   2 files changed, 13 insertions(+)
>
> diff --git a/Documentation/devicetree/bindings/dpll/dpll-device.yaml
> b/Documentation/devicetree/bindings/dpll/dpll-device.yaml
> index fb8d7a9a3693f..560351df1bec3 100644
> --- a/Documentation/devicetree/bindings/dpll/dpll-device.yaml
> +++ b/Documentation/devicetree/bindings/dpll/dpll-device.yaml
> @@ -27,6 +27,12 @@ properties:
>     "#size-cells":
>       const: 0
>
> +  "#dpll-cells":
> +    description: |
> +      Number of cells in a dpll specifier. The cell specifies the index
> +      of the channel within the DPLL device.
> +    const: 1

If it is 1 for everyone, then you don't need a property for it. The
question is whether it would need to vary. Perhaps some configuration
flags/info might be needed? Connection type or frequency looking at
the existing configuration setting?

> +
>     dpll-types:
>       description: List of DPLL channel types, one per DPLL instance.
>       $ref: /schemas/types.yaml#/definitions/non-unique-string-array
> diff --git a/Documentation/devicetree/bindings/net/network-class.yaml
> b/Documentation/devicetree/bindings/net/network-class.yaml
> index 06461fb92eb84..144badb3b7ff1 100644
> --- a/Documentation/devicetree/bindings/net/network-class.yaml
> +++ b/Documentation/devicetree/bindings/net/network-class.yaml
> @@ -17,6 +17,13 @@ properties:
>       default: 48
>       const: 48
>
> +  dpll:
> +    description:
> +      Specifies DPLL device phandle and index of the DPLL channel within
> +      this device used by this network device to synchronize its hardware
> +      clock.
> +    $ref: /schemas/types.yaml#/definitions/phandle

If you have cells, then this should be phandle-array.

> +
>     local-mac-address:
>       description:
>         Specifies MAC address that was assigned to the network device
> described by
>