clock.yaml

# SPDX-License-Identifier: BSD-2-Clause
# Copyright 2018 Linaro Ltd.
# Copyright 2012 Secret Lab Technologies Ltd.
%YAML 1.2
---
$id: http://devicetree.org/schemas/clock/clock.yaml#
$schema: http://devicetree.org/meta-schemas/base.yaml#

title: Clock Common Properties

maintainers:
  - Michael Turquette <mturquette@baylibre.com>
  - Stephen Boyd <sboyd@kernel.org>

description: |
  Sources of clock signal can be represented by any node in the device
  tree.  Those nodes are designated as clock providers.  Clock consumer
  nodes use a phandle and clock specifier pair to connect clock provider
  outputs to clock inputs.  Similar to the gpio specifiers, a clock
  specifier is an array of zero, one or more cells identifying the clock
  output on a device.  The length of a clock specifier is defined by the
  value of a #clock-cells property in the clock provider node.

  Assigned clock parents and rates
  --------------------------------

  Some platforms may require initial configuration of default parent clocks
  and clock frequencies. Such a configuration can be specified in a device tree
  node through assigned-clocks, assigned-clock-parents and assigned-clock-rates
  properties. The assigned-clock-parents property should contain a list of parent
  clocks in the form of a phandle and clock specifier pair and the
  assigned-clock-rates property should contain a list of frequencies in Hz. Both
  these properties should correspond to the clocks listed in the assigned-clocks
  property.

  To skip setting parent or rate of a clock its corresponding entry should be
  set to 0, or can be omitted if it is not followed by any non-zero entry.

      serial@a000 {
          compatible = "fsl,imx-uart";
          reg = <0xa000 0x1000>;
          ...
          clocks = <&osc 0>, <&pll 1>;
          clock-names = "baud", "register";

          assigned-clocks = <&clkcon 0>, <&pll 2>;
          assigned-clock-parents = <&pll 2>;
          assigned-clock-rates = <0>, <460800>;
      };

  In this example the <&pll 2> clock is set as parent of clock <&clkcon 0> and
  the <&pll 2> clock is assigned a frequency value of 460800 Hz.

  Configuring a clock's parent and rate through the device node that consumes
  the clock can be done only for clocks that have a single user. Specifying
  conflicting parent or rate configuration in multiple consumer nodes for
  a shared clock is forbidden.

  Configuration of common clocks, which affect multiple consumer devices can
  be similarly specified in the clock provider node.

# always select the core schema
select: true

properties:
  # Legacy clock properties
  clock-frequency:
    description: Legacy property for single, fixed frequency clocks
    anyOf:
      - $ref: /schemas/types.yaml#/definitions/uint32
      - $ref: /schemas/types.yaml#/definitions/uint64
  bus-frequency:
    description: Legacy property for fixed bus frequencies
    $ref: /schemas/types.yaml#/definitions/uint32

  # Provider properties
  "#clock-cells":
    description: Number of cells in a clock specifier; Typically 0 for
      nodes with a single clock output and 1 for nodes with multiple clock
      outputs.

  clock-output-names:
    description: |
      Recommended to be a list of strings of clock output signal
      names indexed by the first cell in the clock specifier.
      However, the meaning of clock-output-names is domain
      specific to the clock provider, and is only provided to
      encourage using the same meaning for the majority of clock
      providers.  This format may not work for clock providers
      using a complex clock specifier format.  In those cases it
      is recommended to omit this property and create a binding
      specific names property.

      Clock consumer nodes must never directly reference
      the provider\'s clock-output-names property.

  clock-indices:
    $ref: /schemas/types.yaml#/definitions/uint32-array
    description: If the identifying number for the clocks in the node
      is not linear from zero, then this allows the mapping of identifiers
      into the clock-output-names array.

  # Consumer properties
  clocks:
    anyOf:
      - type: object # for nodes named 'clocks'
      - $ref: /schemas/types.yaml#/definitions/phandle-array
    description: |
      List of phandle and clock specifier pairs, one pair
      for each clock input to the device.  Note: if the
      clock provider specifies '0' for #clock-cells, then
      only the phandle portion of the pair will appear.

  clock-names:
    $ref: /schemas/types.yaml#/definitions/string-array
    description: List of clock input name strings sorted in the same order
      as the clocks property.  Consumers drivers will use clock-names
      to match clock input names with clocks specifiers.

  clock-ranges:
    type: boolean
    description: Empty property indicating that child nodes can inherit
      named clocks from this node. Useful for bus nodes to provide a clock
      to their children.

  assigned-clocks:
    $ref: /schemas/types.yaml#/definitions/phandle-array
  assigned-clock-parents:
    $ref: /schemas/types.yaml#/definitions/phandle-array
  assigned-clock-rates:
    $ref: /schemas/types.yaml#/definitions/uint32-array
  assigned-clock-rates-u64:
    $ref: /schemas/types.yaml#/definitions/uint64-array

  protected-clocks:
    $ref: /schemas/types.yaml#/definitions/uint32-array
    description:
      Some platforms or firmwares may not fully expose all the clocks to the OS,
      such as in situations where those clks are used by drivers running in ARM
      secure execution levels. Such a configuration can be specified in
      devicetree with the protected-clocks property in the form of a clock
      specifier list. This property should only be specified in the node that is
      providing the clocks being protected.

dependentRequired:
  clock-names: [clocks]
  clock-output-names: ["#clock-cells"]
  clock-indices: [clock-output-names]
  clock-ranges: [clocks]
  assigned-clock-parents: [assigned-clocks]
  assigned-clock-rates: [assigned-clocks]
  assigned-clock-rates-u64: [assigned-clocks]
  protected-clocks: ["#clock-cells"]

dependentSchemas:
  assigned-clocks:
    anyOf:
      - required: [clocks]
      - required: ["#clock-cells"]

additionalProperties: true