dts/upstream/Bindings/net/ti,k3-am654-cpts.yaml

# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/net/ti,k3-am654-cpts.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: The TI AM654x/J721E Common Platform Time Sync (CPTS) module

maintainers:
  - Siddharth Vadapalli <s-vadapalli@ti.com>
  - Ravi Gunasekaran <r-gunasekaran@ti.com>
  - Roger Quadros <rogerq@kernel.org>

description: |+
  The TI AM654x/J721E CPTS module is used to facilitate host control of time
  sync operations.
  Main features of CPTS module are
  - selection of multiple external clock sources
  - Software control of time sync events via interrupt or polling
  - 64-bit timestamp mode in ns with PPM and nudge adjustment.
  - hardware timestamp push inputs (HWx_TS_PUSH)
  - timestamp counter compare output (TS_COMP)
  - timestamp counter bit output (TS_SYNC)
  - periodic Generator function outputs (TS_GENFx)
  - Ethernet Enhanced Scheduled Traffic Operations (CPTS_ESTFn) (TSN)
  - external hardware timestamp push inputs (HWx_TS_PUSH) timestamping

   Depending on integration it enables compliance with the IEEE 1588-2008
   standard for a precision clock synchronization protocol, Ethernet Enhanced
   Scheduled Traffic Operations (CPTS_ESTFn) and PCIe Subsystem Precision Time
   Measurement (PTM).

  TI AM654x/J721E SoCs has several similar CPTS modules integrated into the
  different parts of the system which could be synchronized with each other
  - Main CPTS
  - MCU CPSW CPTS with IEEE 1588-2008 support
  - PCIe subsystem CPTS for PTM support

  Depending on CPTS module integration and when CPTS is integral part of
  another module (MCU CPSW for example) "compatible" and "reg" can
  be omitted - parent module is fully responsible for CPTS enabling and
  configuration.

properties:
  $nodename:
    pattern: "^cpts@[0-9a-f]+$"

  compatible:
    enum:
      - ti,am65-cpts
      - ti,j721e-cpts

  reg:
    maxItems: 1
    description:
      The physical base address and size of CPTS IO range

  reg-names:
    items:
      - const: cpts

  clocks:
    maxItems: 1
    description: CPTS reference clock

  clock-names:
    items:
      - const: cpts

  interrupts:
    items:
      - description: CPTS events interrupt

  interrupt-names:
    items:
      - const: cpts

  assigned-clock-parents: true

  assigned-clocks: true

  power-domains:
    maxItems: 1

  ti,cpts-ext-ts-inputs:
    $ref: /schemas/types.yaml#/definitions/uint32
    maximum: 8
    description:
      Number of hardware timestamp push inputs (HWx_TS_PUSH)

  ti,cpts-periodic-outputs:
    $ref: /schemas/types.yaml#/definitions/uint32
    maximum: 8
    description:
      Number of timestamp Generator function outputs (TS_GENFx)

  ti,pps:
    $ref: /schemas/types.yaml#/definitions/uint32-array
    minItems: 2
    maxItems: 2
    description: |
      The pair of HWx_TS_PUSH input and TS_GENFy output indexes used for
      PPS events generation. Platform/board specific.

  refclk-mux:
    type: object
    additionalProperties: false
    description: CPTS reference clock multiplexer clock
    properties:
      '#clock-cells':
        const: 0

      clocks:
        maxItems: 8

    required:
      - clocks

required:
  - compatible
  - reg
  - clocks
  - clock-names
  - interrupts
  - interrupt-names

additionalProperties: false

examples:
  - |
    #include <dt-bindings/interrupt-controller/irq.h>
    #include <dt-bindings/interrupt-controller/arm-gic.h>

    cpts@310d0000 {
         compatible = "ti,am65-cpts";
         reg = <0x310d0000 0x400>;
         reg-names = "cpts";
         clocks = <&main_cpts_mux>;
         clock-names = "cpts";
         interrupts-extended = <&k3_irq 163 0 IRQ_TYPE_LEVEL_HIGH>;
         interrupt-names = "cpts";
         ti,cpts-periodic-outputs = <6>;
         ti,cpts-ext-ts-inputs = <8>;

         main_cpts_mux: refclk-mux {
               #clock-cells = <0>;
               clocks = <&k3_clks 118 5>, <&k3_clks 118 11>,
                        <&k3_clks 157 91>, <&k3_clks 157 77>,
                        <&k3_clks 157 102>, <&k3_clks 157 80>,
                        <&k3_clks 120 3>, <&k3_clks 121 3>;
               assigned-clocks = <&main_cpts_mux>;
               assigned-clock-parents = <&k3_clks 118 11>;
         };
    };