fsl,ptp.yaml

  1# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
  2%YAML 1.2
  3---
  4$id: http://devicetree.org/schemas/ptp/fsl,ptp.yaml#
  5$schema: http://devicetree.org/meta-schemas/core.yaml#
  6
  7title: Freescale QorIQ 1588 timer based PTP clock
  8
  9maintainers:
 10  - Frank Li <Frank.Li@nxp.com>
 11
 12properties:
 13  compatible:
 14    oneOf:
 15      - enum:
 16          - fsl,etsec-ptp
 17          - fsl,fman-ptp-timer
 18          - fsl,dpaa2-ptp
 19      - items:
 20          - const: pci1957,ee02
 21          - const: fsl,enetc-ptp
 22
 23  reg:
 24    maxItems: 1
 25
 26  interrupts:
 27    maxItems: 1
 28
 29  clocks:
 30    maxItems: 1
 31
 32  fsl,cksel:
 33    $ref: /schemas/types.yaml#/definitions/uint32
 34    description: |
 35      Timer reference clock source.
 36
 37      Reference clock source is determined by the value, which is holded
 38      in CKSEL bits in TMR_CTRL register. "fsl,cksel" property keeps the
 39      value, which will be directly written in those bits, that is why,
 40      according to reference manual, the next clock sources can be used:
 41
 42      For eTSEC,
 43      <0> - external high precision timer reference clock (TSEC_TMR_CLK
 44            input is used for this purpose);
 45      <1> - eTSEC system clock;
 46      <2> - eTSEC1 transmit clock;
 47      <3> - RTC clock input.
 48
 49      For DPAA FMan,
 50      <0> - external high precision timer reference clock (TMR_1588_CLK)
 51      <1> - MAC system clock (1/2 FMan clock)
 52      <2> - reserved
 53      <3> - RTC clock oscillator
 54
 55  fsl,tclk-period:
 56    $ref: /schemas/types.yaml#/definitions/uint32
 57    description: Timer reference clock period in nanoseconds.
 58
 59  fsl,tmr-prsc:
 60    $ref: /schemas/types.yaml#/definitions/uint32
 61    description: Prescaler, divides the output clock.
 62
 63  fsl,tmr-add:
 64    $ref: /schemas/types.yaml#/definitions/uint32
 65    description: Frequency compensation value.
 66
 67  fsl,tmr-fiper1:
 68    $ref: /schemas/types.yaml#/definitions/uint32
 69    description: Fixed interval period pulse generator.
 70
 71  fsl,tmr-fiper2:
 72    $ref: /schemas/types.yaml#/definitions/uint32
 73    description: Fixed interval period pulse generator.
 74
 75  fsl,tmr-fiper3:
 76    $ref: /schemas/types.yaml#/definitions/uint32
 77    description:
 78      Fixed interval period pulse generator.
 79      Supported only on DPAA2 and ENETC hardware.
 80
 81  fsl,max-adj:
 82    $ref: /schemas/types.yaml#/definitions/uint32
 83    description: |
 84      Maximum frequency adjustment in parts per billion.
 85
 86      These properties set the operational parameters for the PTP
 87      clock. You must choose these carefully for the clock to work right.
 88      Here is how to figure good values:
 89
 90      TimerOsc     = selected reference clock   MHz
 91      tclk_period  = desired clock period       nanoseconds
 92      NominalFreq  = 1000 / tclk_period         MHz
 93      FreqDivRatio = TimerOsc / NominalFreq     (must be greater that 1.0)
 94      tmr_add      = ceil(2^32 / FreqDivRatio)
 95      OutputClock  = NominalFreq / tmr_prsc     MHz
 96      PulseWidth   = 1 / OutputClock            microseconds
 97      FiperFreq1   = desired frequency in Hz
 98      FiperDiv1    = 1000000 * OutputClock / FiperFreq1
 99      tmr_fiper1   = tmr_prsc * tclk_period * FiperDiv1 - tclk_period
100      max_adj      = 1000000000 * (FreqDivRatio - 1.0) - 1
101
102      The calculation for tmr_fiper2 is the same as for tmr_fiper1. The
103      driver expects that tmr_fiper1 will be correctly set to produce a 1
104      Pulse Per Second (PPS) signal, since this will be offered to the PPS
105      subsystem to synchronize the Linux clock.
106
107      When this attribute is not used, the IEEE 1588 timer reference clock
108      will use the eTSEC system clock (for Gianfar) or the MAC system
109      clock (for DPAA).
110
111  fsl,extts-fifo:
112    $ref: /schemas/types.yaml#/definitions/flag
113    description:
114      The presence of this property indicates hardware
115      support for the external trigger stamp FIFO
116
117  little-endian:
118    $ref: /schemas/types.yaml#/definitions/flag
119    description:
120      The presence of this property indicates the 1588 timer
121      support for the external trigger stamp FIFO.
122      IP block is little-endian mode. The default endian mode
123      is big-endian.
124
125required:
126  - compatible
127  - reg
128
129allOf:
130  - if:
131      properties:
132        compatible:
133          contains:
134            const: fsl,enetc-ptp
135    then:
136      $ref: /schemas/pci/pci-device.yaml
137
138additionalProperties: false
139
140examples:
141  - |
142    #include <dt-bindings/interrupt-controller/irq.h>
143
144    phc@24e00 {
145        compatible = "fsl,etsec-ptp";
146        reg = <0x24e00 0xb0>;
147        interrupts = <12 IRQ_TYPE_LEVEL_LOW>;
148        interrupt-parent = <&ipic>;
149        fsl,cksel       = <1>;
150        fsl,tclk-period = <10>;
151        fsl,tmr-prsc    = <100>;
152        fsl,tmr-add     = <0x999999a4>;
153        fsl,tmr-fiper1  = <0x3b9ac9f6>;
154        fsl,tmr-fiper2  = <0x00018696>;
155        fsl,max-adj     = <659999998>;
156    };