dt-bindings: clock: Create YAML schema for ICST clocks

# 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,impd-vco1

      - arm,impd-vco2

  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

required:

  - "#clock-cells"

  - compatible

  - clocks

examples:

  - |

    vco1: clock@00 {

      compatible = "arm,impd1-vco1";

      #clock-cells = <0>;

      lock-offset = <0x08>;

      vco-offset = <0x00>;

      clocks = <&sysclk>;

      clock-output-names = "IM-PD1-VCO1";

    };

...

Clock bindings for ARM Integrator and Versatile Core Module clocks

Auxiliary Oscillator Clock

This is a configurable clock fed from a 24 MHz chrystal,

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, since

it obtains the base address for it's address range from its

parent node.

Required properties:

- compatible: must be "arm,integrator-cm-auxosc" or "arm,versatile-cm-auxosc"

- #clock-cells: must be <0>

Optional properties:

- clocks: parent clock(s)

Example:

core-module@10000000 {

	xtal24mhz: xtal24mhz@24M {

		#clock-cells = <0>;

		compatible = "fixed-clock";

		clock-frequency = <24000000>;

	};

	auxosc: cm_aux_osc@25M {

		#clock-cells = <0>;

		compatible = "arm,integrator-cm-auxosc";

		clocks = <&xtal24mhz>;

	};

};

ARM System Controller ICST clocks

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), hardwires RDW to

different values and sometimes also hardwire 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):

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.

Required properties:

- compatible: must be one of

  "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"

- lock-offset: the offset address into the system controller where the

  unlocking register is located

- vco-offset: the offset address into the system controller where the

  ICST control register is located (even 32 bit address)

- #clock-cells: must be <0>

- clocks: parent clock, since the ICST needs a parent clock to derive its

  frequency from, this attribute is compulsory.

Example:

syscon: syscon@10000000 {

	compatible = "syscon";

	reg = <0x10000000 0x1000>;

	oscclk0: osc0@c {

		compatible = "arm,syscon-icst307";

		#clock-cells = <0>;

		lock-offset = <0x20>;

		vco-offset = <0x0c>;

		clocks = <&xtal24mhz>;

	};

	(...)

};