u-boot/dts/upstream/Bindings/clock/ti/ti,divider-clock.yaml

# SPDX-License-Identifier: GPL-2.0-only
%YAML 1.2
---
$id: http://devicetree.org/schemas/clock/ti/ti,divider-clock.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Texas Instruments divider clock

maintainers:
  - Tero Kristo <kristo@kernel.org>

description: |
  This clock It assumes a register-mapped adjustable clock rate divider
  that does not gate and has only one input clock or parent.  By default the
  value programmed into the register is one less than the actual divisor value.
  E.g:

  register value    actual divisor value
  0                 1
  1                 2
  2                 3

  This assumption may be modified by the following optional properties:

  ti,index-starts-at-one - valid divisor values start at 1, not the default
  of 0.  E.g:
  register value    actual divisor value
  1                 1
  2                 2
  3                 3

  ti,index-power-of-two - valid divisor values are powers of two.  E.g:
  register value    actual divisor value
  0                 1
  1                 2
  2                 4

  Additionally an array of valid dividers may be supplied like so:

  ti,dividers = <4>, <8>, <0>, <16>;

  Which will map the resulting values to a divisor table by their index:
  register value    actual divisor value
  0                 4
  1                 8
  2                 <invalid divisor, skipped>
  3                 16

  Any zero value in this array means the corresponding bit-value is invalid
  and must not be used.

  The binding must also provide the register to control the divider and
  unless the divider array is provided, min and max dividers. Optionally
  the number of bits to shift that mask, if necessary. If the shift value
  is missing it is the same as supplying a zero shift.

  This binding can also optionally provide support to the hardware autoidle
  feature, see [1].

  [1] Documentation/devicetree/bindings/clock/ti/autoidle.txt

properties:
  compatible:
    enum:
      - ti,divider-clock
      - ti,composite-divider-clock

  "#clock-cells":
    const: 0

  clocks:
    maxItems: 1

  clock-output-names:
    maxItems: 1

  reg:
    maxItems: 1

  ti,dividers:
    $ref: /schemas/types.yaml#/definitions/uint32-array
    description:
      array of integers defining divisors

  ti,bit-shift:
    $ref: /schemas/types.yaml#/definitions/uint32
    description:
      number of bits to shift the divider value
    maximum: 31
    default: 0

  ti,min-div:
    $ref: /schemas/types.yaml#/definitions/uint32
    description:
      min divisor for dividing the input clock rate, only
      needed if the first divisor is offset from the default value (1)
    minimum: 1
    default: 1


  ti,max-div:
    $ref: /schemas/types.yaml#/definitions/uint32
    description:
      max divisor for dividing the input clock rate, only needed
      if ti,dividers is not defined.

  ti,index-starts-at-one:
    type: boolean
    description:
      valid divisor programming starts at 1, not zero,
      only valid if ti,dividers is not defined

  ti,index-power-of-two:
    type: boolean
    description:
      valid divisor programming must be a power of two,
      only valid if ti,dividers is not defined.

  ti,autoidle-shift:
    $ref: /schemas/types.yaml#/definitions/uint32
    description:
      bit shift of the autoidle enable bit for the clock,
      see [1].
    maximum: 31
    default: 0

  ti,invert-autoidle-bit:
    type: boolean
    description:
      autoidle is enabled by setting the bit to 0,
      see [1]

  ti,set-rate-parent:
    type: boolean
    description:
      clk_set_rate is propagated to parent            |

  ti,latch-bit:
    $ref: /schemas/types.yaml#/definitions/uint32
    description:
      latch the divider value to HW, only needed if the register
      compatible access requires this. As an example dra76x DPLL_GMAC
      H14 divider implements such behavior.

dependentSchemas:
  ti,dividers:
    properties:
      ti,min-div: false
      ti,max-div: false
      ti,index-power-of-two: false
      ti,index-starts-at-one: false

required:
  - compatible
  - "#clock-cells"
  - clocks
  - reg

additionalProperties: false

examples:
  - |
    bus {
      #address-cells = <1>;
      #size-cells = <0>;

      clock-controller@190 {
        #clock-cells = <0>;
        compatible = "ti,divider-clock";
        clocks = <&dpll_usb_ck>;
        ti,max-div = <127>;
        reg = <0x190>;
        ti,index-starts-at-one;
      };

      clock-controller@528 {
        #clock-cells = <0>;
        compatible = "ti,divider-clock";
        clocks = <&abe_clk>;
        ti,bit-shift = <24>;
        reg = <0x528>;
        ti,max-div = <2>;
      };

      clock-controller@a40 {
        #clock-cells = <0>;
        compatible = "ti,composite-divider-clock";
        clocks = <&corex2_fck>;
        ti,bit-shift = <8>;
        reg = <0x0a40>;
        ti,dividers = <0>, <1>, <2>, <3>, <4>, <0>, <6>, <0>, <8>;
      };
    };