# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/clock/arm,syscon-icst.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: ARM System Controller ICST Clocks

maintainers:
  - Linus Walleij <linusw@kernel.org>

description: |
  The ICS525 and ICS307 oscillators are produced by Integrated
  Devices Technology (IDT). ARM integrated these oscillators deeply into their
  reference designs by adding special control registers that manage such
  oscillators to their system controllers.

  The various ARM system controllers contain logic to serialize and initialize
  an ICST clock request after a write to the 32 bit register at an offset
  into the system controller. Furthermore, to even be able to alter one of
  these frequencies, the system controller must first be unlocked by
  writing a special token to another offset in the system controller.

  Some ARM hardware contain special versions of the serial interface that only
  connects the low 8 bits of the VDW (missing one bit), hard-wires RDW to
  different values and sometimes also hard-wires the output divider. They
  therefore have special compatible strings as per this table (the OD value is
  the value on the pins, not the resulting output divider).

  In the core modules and logic tiles, the ICST is a configurable clock fed
  from a 24 MHz clock on the motherboard (usually the main crystal) used for
  generating e.g. video clocks. It is located on the core module and there is
  only one of these. This clock node must be a subnode of the core module.

  Hardware variant         RDW     OD          VDW

  Integrator/AP            22      1           Bit 8 0, rest variable
  integratorap-cm

  Integrator/AP            46      3           Bit 8 0, rest variable
  integratorap-sys

  Integrator/AP            22 or   1           17 or (33 or 25 MHz)
  integratorap-pci         14      1           14

  Integrator/CP            22      variable    Bit 8 0, rest variable
  integratorcp-cm-core

  Integrator/CP            22      variable    Bit 8 0, rest variable
  integratorcp-cm-mem

  The ICST oscillator must be provided inside a system controller node.

properties:
  "#clock-cells":
    const: 0

  compatible:
    enum:
      - arm,syscon-icst525
      - arm,syscon-icst307
      - arm,syscon-icst525-integratorap-cm
      - arm,syscon-icst525-integratorap-sys
      - arm,syscon-icst525-integratorap-pci
      - arm,syscon-icst525-integratorcp-cm-core
      - arm,syscon-icst525-integratorcp-cm-mem
      - arm,integrator-cm-auxosc
      - arm,versatile-cm-auxosc
      - arm,impd1-vco1
      - arm,impd1-vco2

  reg:
    maxItems: 1
    description: The VCO register

  clocks:
    description: Parent clock for the ICST VCO
    maxItems: 1

  clock-output-names:
    maxItems: 1

  lock-offset:
    $ref: /schemas/types.yaml#/definitions/uint32
    description: Offset to the unlocking register for the oscillator

  vco-offset:
    $ref: /schemas/types.yaml#/definitions/uint32
    description: Offset to the VCO register for the oscillator
    deprecated: true

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

additionalProperties: false

examples:
  - |
    vco1: clock {
      compatible = "arm,impd1-vco1";
      #clock-cells = <0>;
      lock-offset = <0x08>;
      vco-offset = <0x00>;
      clocks = <&sysclk>;
      clock-output-names = "IM-PD1-VCO1";
    };

...