code:
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/cpu/idle-states.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Idle states binding description

maintainers:
  - Lorenzo Pieralisi <lorenzo.pieralisi@arm.com>
  - Anup Patel <anup@brainfault.org>

description: |+
  ==========================================
  1 - Introduction
  ==========================================

  ARM and RISC-V systems contain HW capable of managing power consumption
  dynamically, where cores can be put in different low-power states (ranging
  from simple wfi to power gating) according to OS PM policies. The CPU states
  representing the range of dynamic idle states that a processor can enter at
  run-time, can be specified through device tree bindings representing the
  parameters required to enter/exit specific idle states on a given processor.

  ==========================================
  2 - ARM idle states
  ==========================================

  According to the Server Base System Architecture document (SBSA, [3]), the
  power states an ARM CPU can be put into are identified by the following list:

  - Running
  - Idle_standby
  - Idle_retention
  - Sleep
  - Off

  The power states described in the SBSA document define the basic CPU states on
  top of which ARM platforms implement power management schemes that allow an OS
  PM implementation to put the processor in different idle states (which include
  states listed above; "off" state is not an idle state since it does not have
  wake-up capabilities, hence it is not considered in this document).

  Idle state parameters (e.g. entry latency) are platform specific and need to
  be characterized with bindings that provide the required information to OS PM
  code so that it can build the required tables and use them at runtime.

  The device tree binding definition for ARM idle states is the subject of this
  document.

  ==========================================
  3 - RISC-V idle states
  ==========================================

  On RISC-V systems, the HARTs (or CPUs) [6] can be put in platform specific
  suspend (or idle) states (ranging from simple WFI, power gating, etc). The
  RISC-V SBI v0.3 (or higher) [7] hart state management extension provides a
  standard mechanism for OS to request HART state transitions.

  The platform specific suspend (or idle) states of a hart can be either
  retentive or non-rententive in nature. A retentive suspend state will
  preserve HART registers and CSR values for all privilege modes whereas
  a non-retentive suspend state will not preserve HART registers and CSR
  values.

  ===========================================
  4 - idle-states definitions
  ===========================================

  Idle states are characterized for a specific system through a set of
  timing and energy related properties, that underline the HW behaviour
  triggered upon idle states entry and exit.

  The following diagram depicts the CPU execution phases and related timing
  properties required to enter and exit an idle state:

  ..__[EXEC]__|__[PREP]__|__[ENTRY]__|__[IDLE]__|__[EXIT]__|__[EXEC]__..
              |          |           |          |          |

              |<------ entry ------->|
              |       latency        |
                                                |<- exit ->|
                                                |  latency |
              |<-------- min-residency -------->|
                         |<-------  wakeup-latency ------->|

      Diagram 1: CPU idle state execution phases

  EXEC:  Normal CPU execution.

  PREP:  Preparation phase before committing the hardware to idle mode
    like cache flushing. This is abortable on pending wake-up
    event conditions. The abort latency is assumed to be negligible
    (i.e. less than the ENTRY + EXIT duration). If aborted, CPU
    goes back to EXEC. This phase is optional. If not abortable,
    this should be included in the ENTRY phase instead.

  ENTRY:  The hardware is committed to idle mode. This period must run
    to completion up to IDLE before anything else can happen.

  IDLE:  This is the actual energy-saving idle period. This may last
    between 0 and infinite time, until a wake-up event occurs.

  EXIT:  Period during which the CPU is brought back to operational
    mode (EXEC).

  entry-latency: Worst case latency required to enter the idle state. The
  exit-latency may be guaranteed only after entry-latency has passed.

  min-residency: Minimum period, including preparation and entry, for a given
  idle state to be worthwhile energywise.

  wakeup-latency: Maximum delay between the signaling of a wake-up event and the
  CPU being able to execute normal code again. If not specified, this is assumed
  to be entry-latency + exit-latency.

  These timing parameters can be used by an OS in different circumstances.

  An idle CPU requires the expected min-residency time to select the most
  appropriate idle state based on the expected expiry time of the next IRQ
  (i.e. wake-up) that causes the CPU to return to the EXEC phase.

  An operating system scheduler may need to compute the shortest wake-up delay
  for CPUs in the system by detecting how long will it take to get a CPU out
  of an idle state, e.g.:

  wakeup-delay = exit-latency + max(entry-latency - (now - entry-timestamp), 0)

  In other words, the scheduler can make its scheduling decision by selecting
  (e.g. waking-up) the CPU with the shortest wake-up delay.
  The wake-up delay must take into account the entry latency if that period
  has not expired. The abortable nature of the PREP period can be ignored
  if it cannot be relied upon (e.g. the PREP deadline may occur much sooner than
  the worst case since it depends on the CPU operating conditions, i.e. caches
  state).

  An OS has to reliably probe the wakeup-latency since some devices can enforce
  latency constraint guarantees to work properly, so the OS has to detect the
  worst case wake-up latency it can incur if a CPU is allowed to enter an
  idle state, and possibly to prevent that to guarantee reliable device
  functioning.

  The min-residency time parameter deserves further explanation since it is
  expressed in time units but must factor in energy consumption coefficients.

  The energy consumption of a cpu when it enters a power state can be roughly
  characterised by the following graph:

                 |
                 |
                 |
             e   |
             n   |                                      /---
             e   |                               /------
             r   |                        /------
             g   |                  /-----
             y   |           /------
                 |       ----
                 |      /|
                 |     / |
                 |    /  |
                 |   /   |
                 |  /    |
                 | /     |
                 |/      |
            -----|-------+----------------------------------
                0|       1                              time(ms)

      Graph 1: Energy vs time example

  The graph is split in two parts delimited by time 1ms on the X-axis.
  The graph curve with X-axis values = { x | 0 < x < 1ms } has a steep slope
  and denotes the energy costs incurred while entering and leaving the idle
  state.
  The graph curve in the area delimited by X-axis values = {x | x > 1ms } has
  shallower slope and essentially represents the energy consumption of the idle
  state.

  min-residency is defined for a given idle state as the minimum expected
  residency time for a state (inclusive of preparation and entry) after
  which choosing that state become the most energy efficient option. A good
  way to visualise this, is by taking the same graph above and comparing some
  states energy consumptions plots.

  For sake of simplicity, let's consider a system with two idle states IDLE1,
  and IDLE2:

            |
            |
            |
            |                                                  /-- IDLE1
         e  |                                              /---
         n  |                                         /----
         e  |                                     /---
         r  |                                /-----/--------- IDLE2
         g  |                    /-------/---------
         y  |        ------------    /---|
            |       /           /----    |
            |      /        /---         |
            |     /    /----             |
            |    / /---                  |
            |   ---                      |
            |  /                         |
            | /                          |
            |/                           |                  time
         ---/----------------------------+------------------------
            |IDLE1-energy < IDLE2-energy | IDLE2-energy < IDLE1-energy
                                         |
                                  IDLE2-min-residency

      Graph 2: idle states min-residency example

  In graph 2 above, that takes into account idle states entry/exit energy
  costs, it is clear that if the idle state residency time (i.e. time till next
  wake-up IRQ) is less than IDLE2-min-residency, IDLE1 is the better idle state
  choice energywise.

  This is mainly down to the fact that IDLE1 entry/exit energy costs are lower
  than IDLE2.

  However, the lower power consumption (i.e. shallower energy curve slope) of
  idle state IDLE2 implies that after a suitable time, IDLE2 becomes more energy
  efficient.

  The time at which IDLE2 becomes more energy efficient than IDLE1 (and other
  shallower states in a system with multiple idle states) is defined
  IDLE2-min-residency and corresponds to the time when energy consumption of
  IDLE1 and IDLE2 states breaks even.

  The definitions provided in this section underpin the idle states
  properties specification that is the subject of the following sections.

  ===========================================
  5 - idle-states node
  ===========================================

  The processor idle states are defined within the idle-states node, which is
  a direct child of the cpus node [1] and provides a container where the
  processor idle states, defined as device tree nodes, are listed.

  On ARM systems, it is a container of processor idle states nodes. If the
  system does not provide CPU power management capabilities, or the processor
  just supports idle_standby, an idle-states node is not required.

  ===========================================
  6 - References
  ===========================================

  [1] ARM Linux Kernel documentation - CPUs bindings
      Documentation/devicetree/bindings/arm/cpus.yaml

  [2] ARM Linux Kernel documentation - PSCI bindings
      Documentation/devicetree/bindings/arm/psci.yaml

  [3] ARM Server Base System Architecture (SBSA)
      http://infocenter.arm.com/help/index.jsp

  [4] ARM Architecture Reference Manuals
      http://infocenter.arm.com/help/index.jsp

  [5] ARM Linux Kernel documentation - Booting AArch64 Linux
      Documentation/arm64/booting.rst

  [6] RISC-V Linux Kernel documentation - CPUs bindings
      Documentation/devicetree/bindings/riscv/cpus.yaml

  [7] RISC-V Supervisor Binary Interface (SBI)
      http://github.com/riscv/riscv-sbi-doc/riscv-sbi.adoc

properties:
  $nodename:
    const: idle-states

  entry-method:
    description: |
      Usage and definition depend on ARM architecture version.

      On ARM v8 64-bit this property is required.
      On ARM 32-bit systems this property is optional

      This assumes that the "enable-method" property is set to "psci" in the cpu
      node[5] that is responsible for setting up CPU idle management in the OS
      implementation.
    const: psci

patternProperties:
  "^(cpu|cluster)-":
    type: object
    description: |
      Each state node represents an idle state description and must be defined
      as follows.

      The idle state entered by executing the wfi instruction (idle_standby
      SBSA,[3][4]) is considered standard on all ARM and RISC-V platforms and
      therefore must not be listed.

      In addition to the properties listed above, a state node may require
      additional properties specific to the entry-method defined in the
      idle-states node. Please refer to the entry-method bindings
      documentation for properties definitions.

    properties:
      compatible:
        enum:
          - arm,idle-state
          - riscv,idle-state

      arm,psci-suspend-param:
        $ref: /schemas/types.yaml#/definitions/uint32
        description: |
          power_state parameter to pass to the ARM PSCI suspend call.

          Device tree nodes that require usage of PSCI CPU_SUSPEND function
          (i.e. idle states node with entry-method property is set to "psci")
          must specify this property.

      riscv,sbi-suspend-param:
        $ref: /schemas/types.yaml#/definitions/uint32
        description: |
          suspend_type parameter to pass to the RISC-V SBI HSM suspend call.

          This property is required in idle state nodes of device tree meant
          for RISC-V systems. For more details on the suspend_type parameter
          refer the SBI specifiation v0.3 (or higher) [7].

      local-timer-stop:
        description:
          If present the CPU local timer control logic is
             lost on state entry, otherwise it is retained.
        type: boolean

      entry-latency-us:
        description:
          Worst case latency in microseconds required to enter the idle state.

      exit-latency-us:
        description:
          Worst case latency in microseconds required to exit the idle state.
          The exit-latency-us duration may be guaranteed only after
          entry-latency-us has passed.

      min-residency-us:
        description:
          Minimum residency duration in microseconds, inclusive of preparation
          and entry, for this idle state to be considered worthwhile energy wise
          (refer to section 2 of this document for a complete description).

      wakeup-latency-us:
        description: |
          Maximum delay between the signaling of a wake-up event and the CPU
          being able to execute normal code again. If omitted, this is assumed
          to be equal to:

            entry-latency-us + exit-latency-us

          It is important to supply this value on systems where the duration of
          PREP phase (see diagram 1, section 2) is non-neglibigle. In such
          systems entry-latency-us + exit-latency-us will exceed
          wakeup-latency-us by this duration.

      idle-state-name:
        $ref: /schemas/types.yaml#/definitions/string
        description:
          A string used as a descriptive name for the idle state.

    additionalProperties: false

    required:
      - compatible
      - entry-latency-us
      - exit-latency-us
      - min-residency-us

additionalProperties: false

examples:
  - |

    cpus {
        #size-cells = <0>;
        #address-cells = <2>;

        cpu@0 {
            device_type = "cpu";
            compatible = "arm,cortex-a57";
            reg = <0x0 0x0>;
            enable-method = "psci";
            cpu-idle-states = <&CPU_RETENTION_0_0>, <&CPU_SLEEP_0_0>,
                    <&CLUSTER_RETENTION_0>, <&CLUSTER_SLEEP_0>;
        };

        cpu@1 {
            device_type = "cpu";
            compatible = "arm,cortex-a57";
            reg = <0x0 0x1>;
            enable-method = "psci";
            cpu-idle-states = <&CPU_RETENTION_0_0>, <&CPU_SLEEP_0_0>,
                    <&CLUSTER_RETENTION_0>, <&CLUSTER_SLEEP_0>;
        };

        cpu@100 {
            device_type = "cpu";
            compatible = "arm,cortex-a57";
            reg = <0x0 0x100>;
            enable-method = "psci";
            cpu-idle-states = <&CPU_RETENTION_0_0>, <&CPU_SLEEP_0_0>,
                    <&CLUSTER_RETENTION_0>, <&CLUSTER_SLEEP_0>;
        };

        cpu@101 {
            device_type = "cpu";
            compatible = "arm,cortex-a57";
            reg = <0x0 0x101>;
            enable-method = "psci";
            cpu-idle-states = <&CPU_RETENTION_0_0>, <&CPU_SLEEP_0_0>,
                    <&CLUSTER_RETENTION_0>, <&CLUSTER_SLEEP_0>;
        };

        cpu@10000 {
            device_type = "cpu";
            compatible = "arm,cortex-a57";
            reg = <0x0 0x10000>;
            enable-method = "psci";
            cpu-idle-states = <&CPU_RETENTION_0_0>, <&CPU_SLEEP_0_0>,
                    <&CLUSTER_RETENTION_0>, <&CLUSTER_SLEEP_0>;
        };

        cpu@10001 {
            device_type = "cpu";
            compatible = "arm,cortex-a57";
            reg = <0x0 0x10001>;
            enable-method = "psci";
            cpu-idle-states = <&CPU_RETENTION_0_0>, <&CPU_SLEEP_0_0>,
                    <&CLUSTER_RETENTION_0>, <&CLUSTER_SLEEP_0>;
        };

        cpu@10100 {
            device_type = "cpu";
            compatible = "arm,cortex-a57";
            reg = <0x0 0x10100>;
            enable-method = "psci";
            cpu-idle-states = <&CPU_RETENTION_0_0>, <&CPU_SLEEP_0_0>,
                    <&CLUSTER_RETENTION_0>, <&CLUSTER_SLEEP_0>;
        };

        cpu@10101 {
            device_type = "cpu";
            compatible = "arm,cortex-a57";
            reg = <0x0 0x10101>;
            enable-method = "psci";
            cpu-idle-states = <&CPU_RETENTION_0_0>, <&CPU_SLEEP_0_0>,
                    <&CLUSTER_RETENTION_0>, <&CLUSTER_SLEEP_0>;
        };

        cpu@100000000 {
            device_type = "cpu";
            compatible = "arm,cortex-a53";
            reg = <0x1 0x0>;
            enable-method = "psci";
            cpu-idle-states = <&CPU_RETENTION_1_0>, <&CPU_SLEEP_1_0>,
                    <&CLUSTER_RETENTION_1>, <&CLUSTER_SLEEP_1>;
        };

        cpu@100000001 {
            device_type = "cpu";
            compatible = "arm,cortex-a53";
            reg = <0x1 0x1>;
            enable-method = "psci";
            cpu-idle-states = <&CPU_RETENTION_1_0>, <&CPU_SLEEP_1_0>,
                    <&CLUSTER_RETENTION_1>, <&CLUSTER_SLEEP_1>;
        };

        cpu@100000100 {
            device_type = "cpu";
            compatible = "arm,cortex-a53";
            reg = <0x1 0x100>;
            enable-method = "psci";
            cpu-idle-states = <&CPU_RETENTION_1_0>, <&CPU_SLEEP_1_0>,
                    <&CLUSTER_RETENTION_1>, <&CLUSTER_SLEEP_1>;
        };

        cpu@100000101 {
            device_type = "cpu";
            compatible = "arm,cortex-a53";
            reg = <0x1 0x101>;
            enable-method = "psci";
            cpu-idle-states = <&CPU_RETENTION_1_0>, <&CPU_SLEEP_1_0>,
                    <&CLUSTER_RETENTION_1>, <&CLUSTER_SLEEP_1>;
        };

        cpu@100010000 {
            device_type = "cpu";
            compatible = "arm,cortex-a53";
            reg = <0x1 0x10000>;
            enable-method = "psci";
            cpu-idle-states = <&CPU_RETENTION_1_0>, <&CPU_SLEEP_1_0>,
                    <&CLUSTER_RETENTION_1>, <&CLUSTER_SLEEP_1>;
        };

        cpu@100010001 {
            device_type = "cpu";
            compatible = "arm,cortex-a53";
            reg = <0x1 0x10001>;
            enable-method = "psci";
            cpu-idle-states = <&CPU_RETENTION_1_0>, <&CPU_SLEEP_1_0>,
                    <&CLUSTER_RETENTION_1>, <&CLUSTER_SLEEP_1>;
        };

        cpu@100010100 {
            device_type = "cpu";
            compatible = "arm,cortex-a53";
            reg = <0x1 0x10100>;
            enable-method = "psci";
            cpu-idle-states = <&CPU_RETENTION_1_0>, <&CPU_SLEEP_1_0>,
                    <&CLUSTER_RETENTION_1>, <&CLUSTER_SLEEP_1>;
        };

        cpu@100010101 {
            device_type = "cpu";
            compatible = "arm,cortex-a53";
            reg = <0x1 0x10101>;
            enable-method = "psci";
            cpu-idle-states = <&CPU_RETENTION_1_0>, <&CPU_SLEEP_1_0>,
                    <&CLUSTER_RETENTION_1>, <&CLUSTER_SLEEP_1>;
        };

        idle-states {
            entry-method = "psci";

            CPU_RETENTION_0_0: cpu-retention-0-0 {
                compatible = "arm,idle-state";
                arm,psci-suspend-param = <0x0010000>;
                entry-latency-us = <20>;
                exit-latency-us = <40>;
                min-residency-us = <80>;
            };

            CLUSTER_RETENTION_0: cluster-retention-0 {
                compatible = "arm,idle-state";
                local-timer-stop;
                arm,psci-suspend-param = <0x1010000>;
                entry-latency-us = <50>;
                exit-latency-us = <100>;
                min-residency-us = <250>;
                wakeup-latency-us = <130>;
            };

            CPU_SLEEP_0_0: cpu-sleep-0-0 {
                compatible = "arm,idle-state";
                local-timer-stop;
                arm,psci-suspend-param = <0x0010000>;
                entry-latency-us = <250>;
                exit-latency-us = <500>;
                min-residency-us = <950>;
            };

            CLUSTER_SLEEP_0: cluster-sleep-0 {
                compatible = "arm,idle-state";
                local-timer-stop;
                arm,psci-suspend-param = <0x1010000>;
                entry-latency-us = <600>;
                exit-latency-us = <1100>;
                min-residency-us = <2700>;
                wakeup-latency-us = <1500>;
            };

            CPU_RETENTION_1_0: cpu-retention-1-0 {
                compatible = "arm,idle-state";
                arm,psci-suspend-param = <0x0010000>;
                entry-latency-us = <20>;
                exit-latency-us = <40>;
                min-residency-us = <90>;
            };

            CLUSTER_RETENTION_1: cluster-retention-1 {
                compatible = "arm,idle-state";
                local-timer-stop;
                arm,psci-suspend-param = <0x1010000>;
                entry-latency-us = <50>;
                exit-latency-us = <100>;
                min-residency-us = <270>;
                wakeup-latency-us = <100>;
            };

            CPU_SLEEP_1_0: cpu-sleep-1-0 {
                compatible = "arm,idle-state";
                local-timer-stop;
                arm,psci-suspend-param = <0x0010000>;
                entry-latency-us = <70>;
                exit-latency-us = <100>;
                min-residency-us = <300>;
                wakeup-latency-us = <150>;
            };

            CLUSTER_SLEEP_1: cluster-sleep-1 {
                compatible = "arm,idle-state";
                local-timer-stop;
                arm,psci-suspend-param = <0x1010000>;
                entry-latency-us = <500>;
                exit-latency-us = <1200>;
                min-residency-us = <3500>;
                wakeup-latency-us = <1300>;
            };
        };
    };

  - |
    // Example 2 (ARM 32-bit, 8-cpu system, two clusters):

    cpus {
        #size-cells = <0>;
        #address-cells = <1>;

        cpu@0 {
            device_type = "cpu";
            compatible = "arm,cortex-a15";
            reg = <0x0>;
            cpu-idle-states = <&cpu_sleep_0_0>, <&cluster_sleep_0>;
        };

        cpu@1 {
            device_type = "cpu";
            compatible = "arm,cortex-a15";
            reg = <0x1>;
            cpu-idle-states = <&cpu_sleep_0_0>, <&cluster_sleep_0>;
        };

        cpu@2 {
            device_type = "cpu";
            compatible = "arm,cortex-a15";
            reg = <0x2>;
            cpu-idle-states = <&cpu_sleep_0_0>, <&cluster_sleep_0>;
        };

        cpu@3 {
            device_type = "cpu";
            compatible = "arm,cortex-a15";
            reg = <0x3>;
            cpu-idle-states = <&cpu_sleep_0_0>, <&cluster_sleep_0>;
        };

        cpu@100 {
            device_type = "cpu";
            compatible = "arm,cortex-a7";
            reg = <0x100>;
            cpu-idle-states = <&cpu_sleep_1_0>, <&cluster_sleep_1>;
        };

        cpu@101 {
            device_type = "cpu";
            compatible = "arm,cortex-a7";
            reg = <0x101>;
            cpu-idle-states = <&cpu_sleep_1_0>, <&cluster_sleep_1>;
        };

        cpu@102 {
            device_type = "cpu";
            compatible = "arm,cortex-a7";
            reg = <0x102>;
            cpu-idle-states = <&cpu_sleep_1_0>, <&cluster_sleep_1>;
        };

        cpu@103 {
            device_type = "cpu";
            compatible = "arm,cortex-a7";
            reg = <0x103>;
            cpu-idle-states = <&cpu_sleep_1_0>, <&cluster_sleep_1>;
        };

        idle-states {
            cpu_sleep_0_0: cpu-sleep-0-0 {
                compatible = "arm,idle-state";
                local-timer-stop;
                entry-latency-us = <200>;
                exit-latency-us = <100>;
                min-residency-us = <400>;
                wakeup-latency-us = <250>;
            };

            cluster_sleep_0: cluster-sleep-0 {
                compatible = "arm,idle-state";
                local-timer-stop;
                entry-latency-us = <500>;
                exit-latency-us = <1500>;
                min-residency-us = <2500>;
                wakeup-latency-us = <1700>;
            };

            cpu_sleep_1_0: cpu-sleep-1-0 {
                compatible = "arm,idle-state";
                local-timer-stop;
                entry-latency-us = <300>;
                exit-latency-us = <500>;
                min-residency-us = <900>;
                wakeup-latency-us = <600>;
            };

            cluster_sleep_1: cluster-sleep-1 {
                compatible = "arm,idle-state";
                local-timer-stop;
                entry-latency-us = <800>;
                exit-latency-us = <2000>;
                min-residency-us = <6500>;
                wakeup-latency-us = <2300>;
            };
        };
    };

  - |
    // Example 3 (RISC-V 64-bit, 4-cpu systems, two clusters):

    cpus {
        #size-cells = <0>;
        #address-cells = <1>;

        cpu@0 {
            device_type = "cpu";
            compatible = "riscv";
            reg = <0x0>;
            riscv,isa = "rv64imafdc";
            mmu-type = "riscv,sv48";
            cpu-idle-states = <&CPU_RET_0_0>, <&CPU_NONRET_0_0>,
                            <&CLUSTER_RET_0>, <&CLUSTER_NONRET_0>;

            cpu_intc0: interrupt-controller {
                #interrupt-cells = <1>;
                compatible = "riscv,cpu-intc";
                interrupt-controller;
            };
        };

        cpu@1 {
            device_type = "cpu";
            compatible = "riscv";
            reg = <0x1>;
            riscv,isa = "rv64imafdc";
            mmu-type = "riscv,sv48";
            cpu-idle-states = <&CPU_RET_0_0>, <&CPU_NONRET_0_0>,
                            <&CLUSTER_RET_0>, <&CLUSTER_NONRET_0>;

            cpu_intc1: interrupt-controller {
                #interrupt-cells = <1>;
                compatible = "riscv,cpu-intc";
                interrupt-controller;
            };
        };

        cpu@10 {
            device_type = "cpu";
            compatible = "riscv";
            reg = <0x10>;
            riscv,isa = "rv64imafdc";
            mmu-type = "riscv,sv48";
            cpu-idle-states = <&CPU_RET_1_0>, <&CPU_NONRET_1_0>,
                            <&CLUSTER_RET_1>, <&CLUSTER_NONRET_1>;

            cpu_intc10: interrupt-controller {
                #interrupt-cells = <1>;
                compatible = "riscv,cpu-intc";
                interrupt-controller;
            };
        };

        cpu@11 {
            device_type = "cpu";
            compatible = "riscv";
            reg = <0x11>;
            riscv,isa = "rv64imafdc";
            mmu-type = "riscv,sv48";
            cpu-idle-states = <&CPU_RET_1_0>, <&CPU_NONRET_1_0>,
                            <&CLUSTER_RET_1>, <&CLUSTER_NONRET_1>;

            cpu_intc11: interrupt-controller {
                #interrupt-cells = <1>;
                compatible = "riscv,cpu-intc";
                interrupt-controller;
            };
        };

        idle-states {
            CPU_RET_0_0: cpu-retentive-0-0 {
                compatible = "riscv,idle-state";
                riscv,sbi-suspend-param = <0x10000000>;
                entry-latency-us = <20>;
                exit-latency-us = <40>;
                min-residency-us = <80>;
            };

            CPU_NONRET_0_0: cpu-nonretentive-0-0 {
                compatible = "riscv,idle-state";
                riscv,sbi-suspend-param = <0x90000000>;
                entry-latency-us = <250>;
                exit-latency-us = <500>;
                min-residency-us = <950>;
            };

            CLUSTER_RET_0: cluster-retentive-0 {
                compatible = "riscv,idle-state";
                riscv,sbi-suspend-param = <0x11000000>;
                local-timer-stop;
                entry-latency-us = <50>;
                exit-latency-us = <100>;
                min-residency-us = <250>;
                wakeup-latency-us = <130>;
            };

            CLUSTER_NONRET_0: cluster-nonretentive-0 {
                compatible = "riscv,idle-state";
                riscv,sbi-suspend-param = <0x91000000>;
                local-timer-stop;
                entry-latency-us = <600>;
                exit-latency-us = <1100>;
                min-residency-us = <2700>;
                wakeup-latency-us = <1500>;
            };

            CPU_RET_1_0: cpu-retentive-1-0 {
                compatible = "riscv,idle-state";
                riscv,sbi-suspend-param = <0x10000010>;
                entry-latency-us = <20>;
                exit-latency-us = <40>;
                min-residency-us = <80>;
            };

            CPU_NONRET_1_0: cpu-nonretentive-1-0 {
                compatible = "riscv,idle-state";
                riscv,sbi-suspend-param = <0x90000010>;
                entry-latency-us = <250>;
                exit-latency-us = <500>;
                min-residency-us = <950>;
            };

            CLUSTER_RET_1: cluster-retentive-1 {
                compatible = "riscv,idle-state";
                riscv,sbi-suspend-param = <0x11000010>;
                local-timer-stop;
                entry-latency-us = <50>;
                exit-latency-us = <100>;
                min-residency-us = <250>;
                wakeup-latency-us = <130>;
            };

            CLUSTER_NONRET_1: cluster-nonretentive-1 {
                compatible = "riscv,idle-state";
                riscv,sbi-suspend-param = <0x91000010>;
                local-timer-stop;
                entry-latency-us = <600>;
                exit-latency-us = <1100>;
                min-residency-us = <2700>;
                wakeup-latency-us = <1500>;
            };
        };
    };

...


code:
# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
%YAML 1.2
---
$id: http://devicetree.org/schemas/cpufreq/apple,cluster-cpufreq.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Apple SoC cluster cpufreq device

maintainers:
  - Hector Martin <marcan@marcan.st>

description: |
  Apple SoCs (e.g. M1) have a per-cpu-cluster DVFS controller that is part of
  the cluster management register block. This binding uses the standard
  operating-points-v2 table to define the CPU performance states, with the
  opp-level property specifying the hardware p-state index for that level.

properties:
  compatible:
    oneOf:
      - items:
          - enum:
              - apple,t8103-cluster-cpufreq
              - apple,t8112-cluster-cpufreq
          - const: apple,cluster-cpufreq
      - items:
          - const: apple,t6000-cluster-cpufreq
          - const: apple,t8103-cluster-cpufreq
          - const: apple,cluster-cpufreq

  reg:
    maxItems: 1

  '#performance-domain-cells':
    const: 0

required:
  - compatible
  - reg
  - '#performance-domain-cells'

additionalProperties: false

examples:
  - |
    // This example shows a single CPU per domain and 2 domains,
    // with two p-states per domain.
    // Shipping hardware has 2-4 CPUs per domain and 2-6 domains.
    cpus {
      #address-cells = <2>;
      #size-cells = <0>;

      cpu@0 {
        compatible = "apple,icestorm";
        device_type = "cpu";
        reg = <0x0 0x0>;
        operating-points-v2 = <&ecluster_opp>;
        performance-domains = <&cpufreq_e>;
      };

      cpu@10100 {
        compatible = "apple,firestorm";
        device_type = "cpu";
        reg = <0x0 0x10100>;
        operating-points-v2 = <&pcluster_opp>;
        performance-domains = <&cpufreq_p>;
      };
    };

    ecluster_opp: opp-table-0 {
      compatible = "operating-points-v2";
      opp-shared;

      opp01 {
        opp-hz = /bits/ 64 <600000000>;
        opp-level = <1>;
        clock-latency-ns = <7500>;
      };
      opp02 {
        opp-hz = /bits/ 64 <972000000>;
        opp-level = <2>;
        clock-latency-ns = <22000>;
      };
    };

    pcluster_opp: opp-table-1 {
      compatible = "operating-points-v2";
      opp-shared;

      opp01 {
        opp-hz = /bits/ 64 <600000000>;
        opp-level = <1>;
        clock-latency-ns = <8000>;
      };
      opp02 {
        opp-hz = /bits/ 64 <828000000>;
        opp-level = <2>;
        clock-latency-ns = <19000>;
      };
    };

    soc {
      #address-cells = <2>;
      #size-cells = <2>;

      cpufreq_e: performance-controller@210e20000 {
        compatible = "apple,t8103-cluster-cpufreq", "apple,cluster-cpufreq";
        reg = <0x2 0x10e20000 0 0x1000>;
        #performance-domain-cells = <0>;
      };

      cpufreq_p: performance-controller@211e20000 {
        compatible = "apple,t8103-cluster-cpufreq", "apple,cluster-cpufreq";
        reg = <0x2 0x11e20000 0 0x1000>;
        #performance-domain-cells = <0>;
      };
    };

repo_name: angery/linux


code:
Broadcom AVS mail box and interrupt register bindings
=====================================================

A total of three DT nodes are required. One node (brcm,avs-cpu-data-mem)
references the mailbox register used to communicate with the AVS CPU[1]. The
second node (brcm,avs-cpu-l2-intr) is required to trigger an interrupt on
the AVS CPU. The interrupt tells the AVS CPU that it needs to process a
command sent to it by a driver. Interrupting the AVS CPU is mandatory for
commands to be processed.

The interface also requires a reference to the AVS host interrupt controller,
so a driver can react to interrupts generated by the AVS CPU whenever a command
has been processed. See [2] for more information on the brcm,l2-intc node.

[1] The AVS CPU is an independent co-processor that runs proprietary
firmware. On some SoCs, this firmware supports DFS and DVFS in addition to
Adaptive Voltage Scaling.

[2] Documentation/devicetree/bindings/interrupt-controller/brcm,l2-intc.yaml

Node brcm,avs-cpu-data-mem
--------------------------

Required properties:
- compatible: must include: brcm,avs-cpu-data-mem and
              should include: one of brcm,bcm7271-avs-cpu-data-mem or
                              brcm,bcm7268-avs-cpu-data-mem
- reg: Specifies base physical address and size of the registers.
- interrupts: The interrupt that the AVS CPU will use to interrupt the host
              when a command completed.
- interrupt-names: The name of the interrupt used to interrupt the host.

Optional properties:
- None

Node brcm,avs-cpu-l2-intr
-------------------------

Required properties:
- compatible: must include: brcm,avs-cpu-l2-intr and
              should include: one of brcm,bcm7271-avs-cpu-l2-intr or
                              brcm,bcm7268-avs-cpu-l2-intr
- reg: Specifies base physical address and size of the registers.

Optional properties:
- None

Example
=======

	avs_host_l2_intc: interrupt-controller@f04d1200 {
		#interrupt-cells = <1>;
		compatible = "brcm,l2-intc";
		interrupt-parent = <&intc>;
		reg = <0xf04d1200 0x48>;
		interrupt-controller;
		interrupts = <0x0 0x19 0x0>;
		interrupt-names = "avs";
	};

	avs-cpu-data-mem@f04c4000 {
		compatible = "brcm,bcm7271-avs-cpu-data-mem",
				"brcm,avs-cpu-data-mem";
		reg = <0xf04c4000 0x60>;
		interrupts = <0x1a>;
		interrupt-parent = <&avs_host_l2_intc>;
		interrupt-names = "sw_intr";
	};

	avs-cpu-l2-intr@f04d1100 {
		compatible = "brcm,bcm7271-avs-cpu-l2-intr",
				"brcm,avs-cpu-l2-intr";
		reg = <0xf04d1100 0x10>;
	};


code:
Generic cpufreq driver

It is a generic DT based cpufreq driver for frequency management.  It supports
both uniprocessor (UP) and symmetric multiprocessor (SMP) systems which share
clock and voltage across all CPUs.

Both required and optional properties listed below must be defined
under node /cpus/cpu@0.

Required properties:
- None

Optional properties:
- operating-points: Refer to Documentation/devicetree/bindings/opp/opp-v1.yaml for
  details. OPPs *must* be supplied either via DT, i.e. this property, or
  populated at runtime.
- clock-latency: Specify the possible maximum transition latency for clock,
  in unit of nanoseconds.
- voltage-tolerance: Specify the CPU voltage tolerance in percentage.
- #cooling-cells:
     Please refer to
     Documentation/devicetree/bindings/thermal/thermal-cooling-devices.yaml.

Examples:

cpus {
	#address-cells = <1>;
	#size-cells = <0>;

	cpu@0 {
		compatible = "arm,cortex-a9";
		reg = <0>;
		next-level-cache = <&L2>;
		operating-points = <
			/* kHz    uV */
			792000  1100000
			396000  950000
			198000  850000
		>;
		clock-latency = <61036>; /* two CLK32 periods */
		#cooling-cells = <2>;
	};

	cpu@1 {
		compatible = "arm,cortex-a9";
		reg = <1>;
		next-level-cache = <&L2>;
	};

	cpu@2 {
		compatible = "arm,cortex-a9";
		reg = <2>;
		next-level-cache = <&L2>;
	};

	cpu@3 {
		compatible = "arm,cortex-a9";
		reg = <3>;
		next-level-cache = <&L2>;
	};
};


code:
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/cpufreq/cpufreq-mediatek-hw.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: MediaTek's CPUFREQ Bindings

maintainers:
  - Hector Yuan <hector.yuan@mediatek.com>

description:
  CPUFREQ HW is a hardware engine used by MediaTek SoCs to
  manage frequency in hardware. It is capable of controlling
  frequency for multiple clusters.

properties:
  compatible:
    const: mediatek,cpufreq-hw

  reg:
    minItems: 1
    maxItems: 2
    description:
      Addresses and sizes for the memory of the HW bases in
      each frequency domain. Each entry corresponds to
      a register bank for each frequency domain present.

  "#performance-domain-cells":
    description:
      Number of cells in a performance domain specifier.
      Set const to 1 here for nodes providing multiple
      performance domains.
    const: 1

required:
  - compatible
  - reg
  - "#performance-domain-cells"

additionalProperties: false

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

            cpu0: cpu@0 {
                device_type = "cpu";
                compatible = "arm,cortex-a55";
                enable-method = "psci";
                performance-domains = <&performance 0>;
                reg = <0x000>;
            };
    };

    /* ... */

    soc {
        #address-cells = <2>;
        #size-cells = <2>;

        performance: performance-controller@11bc00 {
            compatible = "mediatek,cpufreq-hw";
            reg = <0 0x0011bc10 0 0x120>, <0 0x0011bd30 0 0x120>;

            #performance-domain-cells = <1>;
        };
    };


code:
Binding for MediaTek's CPUFreq driver
=====================================

Required properties:
- clocks: A list of phandle + clock-specifier pairs for the clocks listed in clock names.
- clock-names: Should contain the following:
	"cpu"		- The multiplexer for clock input of CPU cluster.
	"intermediate"	- A parent of "cpu" clock which is used as "intermediate" clock
			  source (usually MAINPLL) when the original CPU PLL is under
			  transition and not stable yet.
	Please refer to Documentation/devicetree/bindings/clock/clock-bindings.txt for
	generic clock consumer properties.
- operating-points-v2: Please refer to Documentation/devicetree/bindings/opp/opp-v2.yaml
	for detail.
- proc-supply: Regulator for Vproc of CPU cluster.

Optional properties:
- sram-supply: Regulator for Vsram of CPU cluster. When present, the cpufreq driver
	       needs to do "voltage tracking" to step by step scale up/down Vproc and
	       Vsram to fit SoC specific needs. When absent, the voltage scaling
	       flow is handled by hardware, hence no software "voltage tracking" is
	       needed.
- mediatek,cci:
	Used to confirm the link status between cpufreq and mediatek cci. Because
	cpufreq and mediatek cci could share the same regulator in some MediaTek SoCs.
	To prevent the issue of high frequency and low voltage, we need to use this
	property to make sure mediatek cci is ready.
	For details of mediatek cci, please refer to
	Documentation/devicetree/bindings/interconnect/mediatek,cci.yaml
- #cooling-cells:
	For details, please refer to
	Documentation/devicetree/bindings/thermal/thermal-cooling-devices.yaml

Example 1 (MT7623 SoC):

	cpu_opp_table: opp_table {
		compatible = "operating-points-v2";
		opp-shared;

		opp-598000000 {
			opp-hz = /bits/ 64 <598000000>;
			opp-microvolt = <1050000>;
		};

		opp-747500000 {
			opp-hz = /bits/ 64 <747500000>;
			opp-microvolt = <1050000>;
		};

		opp-1040000000 {
			opp-hz = /bits/ 64 <1040000000>;
			opp-microvolt = <1150000>;
		};

		opp-1196000000 {
			opp-hz = /bits/ 64 <1196000000>;
			opp-microvolt = <1200000>;
		};

		opp-1300000000 {
			opp-hz = /bits/ 64 <1300000000>;
			opp-microvolt = <1300000>;
		};
	};

	cpu0: cpu@0 {
		device_type = "cpu";
		compatible = "arm,cortex-a7";
		reg = <0x0>;
		clocks = <&infracfg CLK_INFRA_CPUSEL>,
			 <&apmixedsys CLK_APMIXED_MAINPLL>;
		clock-names = "cpu", "intermediate";
		operating-points-v2 = <&cpu_opp_table>;
		#cooling-cells = <2>;
	};
	cpu@1 {
		device_type = "cpu";
		compatible = "arm,cortex-a7";
		reg = <0x1>;
		operating-points-v2 = <&cpu_opp_table>;
	};
	cpu@2 {
		device_type = "cpu";
		compatible = "arm,cortex-a7";
		reg = <0x2>;
		operating-points-v2 = <&cpu_opp_table>;
	};
	cpu@3 {
		device_type = "cpu";
		compatible = "arm,cortex-a7";
		reg = <0x3>;
		operating-points-v2 = <&cpu_opp_table>;
	};

Example 2 (MT8173 SoC):
	cpu_opp_table_a: opp_table_a {
		compatible = "operating-points-v2";
		opp-shared;

		opp-507000000 {
			opp-hz = /bits/ 64 <507000000>;
			opp-microvolt = <859000>;
		};

		opp-702000000 {
			opp-hz = /bits/ 64 <702000000>;
			opp-microvolt = <908000>;
		};

		opp-1001000000 {
			opp-hz = /bits/ 64 <1001000000>;
			opp-microvolt = <983000>;
		};

		opp-1105000000 {
			opp-hz = /bits/ 64 <1105000000>;
			opp-microvolt = <1009000>;
		};

		opp-1183000000 {
			opp-hz = /bits/ 64 <1183000000>;
			opp-microvolt = <1028000>;
		};

		opp-1404000000 {
			opp-hz = /bits/ 64 <1404000000>;
			opp-microvolt = <1083000>;
		};

		opp-1508000000 {
			opp-hz = /bits/ 64 <1508000000>;
			opp-microvolt = <1109000>;
		};

		opp-1573000000 {
			opp-hz = /bits/ 64 <1573000000>;
			opp-microvolt = <1125000>;
		};
	};

	cpu_opp_table_b: opp_table_b {
		compatible = "operating-points-v2";
		opp-shared;

		opp-507000000 {
			opp-hz = /bits/ 64 <507000000>;
			opp-microvolt = <828000>;
		};

		opp-702000000 {
			opp-hz = /bits/ 64 <702000000>;
			opp-microvolt = <867000>;
		};

		opp-1001000000 {
			opp-hz = /bits/ 64 <1001000000>;
			opp-microvolt = <927000>;
		};

		opp-1209000000 {
			opp-hz = /bits/ 64 <1209000000>;
			opp-microvolt = <968000>;
		};

		opp-1404000000 {
			opp-hz = /bits/ 64 <1007000000>;
			opp-microvolt = <1028000>;
		};

		opp-1612000000 {
			opp-hz = /bits/ 64 <1612000000>;
			opp-microvolt = <1049000>;
		};

		opp-1807000000 {
			opp-hz = /bits/ 64 <1807000000>;
			opp-microvolt = <1089000>;
		};

		opp-1989000000 {
			opp-hz = /bits/ 64 <1989000000>;
			opp-microvolt = <1125000>;
		};
	};

	cpu0: cpu@0 {
		device_type = "cpu";
		compatible = "arm,cortex-a53";
		reg = <0x000>;
		enable-method = "psci";
		cpu-idle-states = <&CPU_SLEEP_0>;
		clocks = <&infracfg CLK_INFRA_CA53SEL>,
			 <&apmixedsys CLK_APMIXED_MAINPLL>;
		clock-names = "cpu", "intermediate";
		operating-points-v2 = <&cpu_opp_table_a>;
	};

	cpu1: cpu@1 {
		device_type = "cpu";
		compatible = "arm,cortex-a53";
		reg = <0x001>;
		enable-method = "psci";
		cpu-idle-states = <&CPU_SLEEP_0>;
		clocks = <&infracfg CLK_INFRA_CA53SEL>,
			 <&apmixedsys CLK_APMIXED_MAINPLL>;
		clock-names = "cpu", "intermediate";
		operating-points-v2 = <&cpu_opp_table_a>;
	};

	cpu2: cpu@100 {
		device_type = "cpu";
		compatible = "arm,cortex-a72";
		reg = <0x100>;
		enable-method = "psci";
		cpu-idle-states = <&CPU_SLEEP_0>;
		clocks = <&infracfg CLK_INFRA_CA72SEL>,
			 <&apmixedsys CLK_APMIXED_MAINPLL>;
		clock-names = "cpu", "intermediate";
		operating-points-v2 = <&cpu_opp_table_b>;
	};

	cpu3: cpu@101 {
		device_type = "cpu";
		compatible = "arm,cortex-a72";
		reg = <0x101>;
		enable-method = "psci";
		cpu-idle-states = <&CPU_SLEEP_0>;
		clocks = <&infracfg CLK_INFRA_CA72SEL>,
			 <&apmixedsys CLK_APMIXED_MAINPLL>;
		clock-names = "cpu", "intermediate";
		operating-points-v2 = <&cpu_opp_table_b>;
	};

	&cpu0 {
		proc-supply = <&mt6397_vpca15_reg>;
	};

	&cpu1 {
		proc-supply = <&mt6397_vpca15_reg>;
	};

	&cpu2 {
		proc-supply = <&da9211_vcpu_reg>;
		sram-supply = <&mt6397_vsramca7_reg>;
	};

	&cpu3 {
		proc-supply = <&da9211_vcpu_reg>;
		sram-supply = <&mt6397_vsramca7_reg>;
	};


code:
# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
%YAML 1.2
---
$id: http://devicetree.org/schemas/cpufreq/cpufreq-qcom-hw.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Qualcomm Technologies, Inc. CPUFREQ

maintainers:
  - Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org>

description: |

  CPUFREQ HW is a hardware engine used by some Qualcomm Technologies, Inc. (QTI)
  SoCs to manage frequency in hardware. It is capable of controlling frequency
  for multiple clusters.

properties:
  compatible:
    oneOf:
      - description: v1 of CPUFREQ HW
        items:
          - const: qcom,cpufreq-hw

      - description: v2 of CPUFREQ HW (EPSS)
        items:
          - enum:
              - qcom,qdu1000-cpufreq-epss
              - qcom,sm6375-cpufreq-epss
              - qcom,sm8250-cpufreq-epss
          - const: qcom,cpufreq-epss

  reg:
    minItems: 2
    items:
      - description: Frequency domain 0 register region
      - description: Frequency domain 1 register region
      - description: Frequency domain 2 register region

  reg-names:
    minItems: 2
    items:
      - const: freq-domain0
      - const: freq-domain1
      - const: freq-domain2

  clocks:
    items:
      - description: XO Clock
      - description: GPLL0 Clock

  clock-names:
    items:
      - const: xo
      - const: alternate

  '#freq-domain-cells':
    const: 1

  '#clock-cells':
    const: 1

required:
  - compatible
  - reg
  - clocks
  - clock-names
  - '#freq-domain-cells'

additionalProperties: false

examples:
  - |
    #include <dt-bindings/clock/qcom,gcc-sdm845.h>
    #include <dt-bindings/clock/qcom,rpmh.h>

    // Example 1: Dual-cluster, Quad-core per cluster. CPUs within a cluster
    // switch DCVS state together.
    cpus {
      #address-cells = <2>;
      #size-cells = <0>;

      CPU0: cpu@0 {
        device_type = "cpu";
        compatible = "qcom,kryo385";
        reg = <0x0 0x0>;
        enable-method = "psci";
        next-level-cache = <&L2_0>;
        qcom,freq-domain = <&cpufreq_hw 0>;
        clocks = <&cpufreq_hw 0>;
        L2_0: l2-cache {
          compatible = "cache";
          cache-unified;
          cache-level = <2>;
          next-level-cache = <&L3_0>;
          L3_0: l3-cache {
            compatible = "cache";
            cache-unified;
            cache-level = <3>;
          };
        };
      };

      CPU1: cpu@100 {
        device_type = "cpu";
        compatible = "qcom,kryo385";
        reg = <0x0 0x100>;
        enable-method = "psci";
        next-level-cache = <&L2_100>;
        qcom,freq-domain = <&cpufreq_hw 0>;
        clocks = <&cpufreq_hw 0>;
        L2_100: l2-cache {
          compatible = "cache";
          cache-unified;
          cache-level = <2>;
          next-level-cache = <&L3_0>;
        };
      };

      CPU2: cpu@200 {
        device_type = "cpu";
        compatible = "qcom,kryo385";
        reg = <0x0 0x200>;
        enable-method = "psci";
        next-level-cache = <&L2_200>;
        qcom,freq-domain = <&cpufreq_hw 0>;
        clocks = <&cpufreq_hw 0>;
        L2_200: l2-cache {
          compatible = "cache";
          cache-unified;
          cache-level = <2>;
          next-level-cache = <&L3_0>;
        };
      };

      CPU3: cpu@300 {
        device_type = "cpu";
        compatible = "qcom,kryo385";
        reg = <0x0 0x300>;
        enable-method = "psci";
        next-level-cache = <&L2_300>;
        qcom,freq-domain = <&cpufreq_hw 0>;
        clocks = <&cpufreq_hw 0>;
        L2_300: l2-cache {
          compatible = "cache";
          cache-unified;
          cache-level = <2>;
          next-level-cache = <&L3_0>;
        };
      };

      CPU4: cpu@400 {
        device_type = "cpu";
        compatible = "qcom,kryo385";
        reg = <0x0 0x400>;
        enable-method = "psci";
        next-level-cache = <&L2_400>;
        qcom,freq-domain = <&cpufreq_hw 1>;
        clocks = <&cpufreq_hw 1>;
        L2_400: l2-cache {
          compatible = "cache";
          cache-unified;
          cache-level = <2>;
          next-level-cache = <&L3_0>;
        };
      };

      CPU5: cpu@500 {
        device_type = "cpu";
        compatible = "qcom,kryo385";
        reg = <0x0 0x500>;
        enable-method = "psci";
        next-level-cache = <&L2_500>;
        qcom,freq-domain = <&cpufreq_hw 1>;
        clocks = <&cpufreq_hw 1>;
        L2_500: l2-cache {
          compatible = "cache";
          cache-unified;
          cache-level = <2>;
          next-level-cache = <&L3_0>;
        };
      };

      CPU6: cpu@600 {
        device_type = "cpu";
        compatible = "qcom,kryo385";
        reg = <0x0 0x600>;
        enable-method = "psci";
        next-level-cache = <&L2_600>;
        qcom,freq-domain = <&cpufreq_hw 1>;
        clocks = <&cpufreq_hw 1>;
        L2_600: l2-cache {
          compatible = "cache";
          cache-unified;
          cache-level = <2>;
          next-level-cache = <&L3_0>;
        };
      };

      CPU7: cpu@700 {
        device_type = "cpu";
        compatible = "qcom,kryo385";
        reg = <0x0 0x700>;
        enable-method = "psci";
        next-level-cache = <&L2_700>;
        qcom,freq-domain = <&cpufreq_hw 1>;
        clocks = <&cpufreq_hw 1>;
        L2_700: l2-cache {
          compatible = "cache";
          cache-unified;
          cache-level = <2>;
          next-level-cache = <&L3_0>;
        };
      };
    };

    soc {
      #address-cells = <1>;
      #size-cells = <1>;

      cpufreq@17d43000 {
        compatible = "qcom,cpufreq-hw";
        reg = <0x17d43000 0x1400>, <0x17d45800 0x1400>;
        reg-names = "freq-domain0", "freq-domain1";

        clocks = <&rpmhcc RPMH_CXO_CLK>, <&gcc GPLL0>;
        clock-names = "xo", "alternate";

        #freq-domain-cells = <1>;
        #clock-cells = <1>;
      };
    };
...


code:
SPEAr cpufreq driver
-------------------

SPEAr SoC cpufreq driver for CPU frequency scaling.
It supports both uniprocessor (UP) and symmetric multiprocessor (SMP) systems
which share clock across all CPUs.

Required properties:
- cpufreq_tbl: Table of frequencies CPU could be transitioned into, in the
  increasing order.

Optional properties:
- clock-latency: Specify the possible maximum transition latency for clock, in
  unit of nanoseconds.

Both required and optional properties listed above must be defined under node
/cpus/cpu@0.

Examples:
--------
cpus {

	<...>

	cpu@0 {
		compatible = "arm,cortex-a9";
		reg = <0>;

		<...>

		cpufreq_tbl = < 166000
				200000
				250000
				300000
				400000
				500000
				600000 >;
	};

	<...>

};


code:
Binding for ST's CPUFreq driver
===============================

ST's CPUFreq driver attempts to read 'process' and 'version' attributes
from the SoC, then supplies the OPP framework with 'prop' and 'supported
hardware' information respectively.  The framework is then able to read
the DT and operate in the usual way.

Frequency Scaling only
----------------------

No vendor specific driver required for this.

Located in CPU's node:

- operating-points		: [See: ../power/opp-v1.yaml]

Example [safe]
--------------

cpus {
	cpu@0 {
				 /* kHz     uV   */
		operating-points = <1500000 0
				    1200000 0
				    800000  0
				    500000  0>;
	};
};

Dynamic Voltage and Frequency Scaling (DVFS)
--------------------------------------------

This requires the ST CPUFreq driver to supply 'process' and 'version' info.

Located in CPU's node:

- operating-points-v2		: [See ../power/opp-v2.yaml]

Example [unsafe]
----------------

cpus {
	cpu@0 {
		operating-points-v2	= <&cpu0_opp_table>;
	};
};

cpu0_opp_table: opp_table {
	compatible = "operating-points-v2";

	/* ############################################################### */
	/* # WARNING: Do not attempt to copy/replicate these nodes,      # */
	/* #          they are only to be supplied by the bootloader !!! # */
	/* ############################################################### */
	opp0 {
		/*			   Major       Minor       Substrate */
		/*			   2           all         all       */
		opp-supported-hw	= <0x00000004  0xffffffff  0xffffffff>;
		opp-hz			= /bits/ 64 <1500000000>;
		clock-latency-ns	= <10000000>;

		opp-microvolt-pcode0	= <1200000>;
		opp-microvolt-pcode1	= <1200000>;
		opp-microvolt-pcode2	= <1200000>;
		opp-microvolt-pcode3	= <1200000>;
		opp-microvolt-pcode4	= <1170000>;
		opp-microvolt-pcode5	= <1140000>;
		opp-microvolt-pcode6	= <1100000>;
		opp-microvolt-pcode7	= <1070000>;
	};

	opp1 {
		/*			   Major       Minor       Substrate */
		/*			   all         all         all       */
		opp-supported-hw	= <0xffffffff  0xffffffff  0xffffffff>;
		opp-hz			= /bits/ 64 <1200000000>;
		clock-latency-ns	= <10000000>;

		opp-microvolt-pcode0	= <1110000>;
		opp-microvolt-pcode1	= <1150000>;
		opp-microvolt-pcode2	= <1100000>;
		opp-microvolt-pcode3	= <1080000>;
		opp-microvolt-pcode4	= <1040000>;
		opp-microvolt-pcode5	= <1020000>;
		opp-microvolt-pcode6	= <980000>;
		opp-microvolt-pcode7	= <930000>;
	};
};


code:
i.MX CPUFreq-DT OPP bindings
================================

Certain i.MX SoCs support different OPPs depending on the "market segment" and
"speed grading" value which are written in fuses. These bits are combined with
the opp-supported-hw values for each OPP to check if the OPP is allowed.

Required properties:
--------------------

For each opp entry in 'operating-points-v2' table:
- opp-supported-hw: Two bitmaps indicating:
  - Supported speed grade mask
  - Supported market segment mask
    0: Consumer
    1: Extended Consumer
    2: Industrial
    3: Automotive

Example:
--------

opp_table {
	compatible = "operating-points-v2";
	opp-1000000000 {
		opp-hz = /bits/ 64 <1000000000>;
		/* grade >= 0, consumer only */
		opp-supported-hw = <0xf>, <0x3>;
	};

	opp-1300000000 {
		opp-hz = /bits/ 64 <1300000000>;
		opp-microvolt = <1000000>;
		/* grade >= 1, all segments */
		opp-supported-hw = <0xe>, <0x7>;
	};
}


code:
Tegra124 CPU frequency scaling driver bindings
----------------------------------------------

Both required and optional properties listed below must be defined
under node /cpus/cpu@0.

Required properties:
- clocks: Must contain an entry for each entry in clock-names.
  See ../clocks/clock-bindings.txt for details.
- clock-names: Must include the following entries:
  - cpu_g: Clock mux for the fast CPU cluster.
  - pll_x: Fast PLL clocksource.
  - pll_p: Auxiliary PLL used during fast PLL rate changes.
  - dfll: Fast DFLL clocksource that also automatically scales CPU voltage.

Optional properties:
- clock-latency: Specify the possible maximum transition latency for clock,
  in unit of nanoseconds.

Example:
--------
cpus {
	#address-cells = <1>;
	#size-cells = <0>;

	cpu@0 {
		device_type = "cpu";
		compatible = "arm,cortex-a15";
		reg = <0>;

		clocks = <&tegra_car TEGRA124_CLK_CCLK_G>,
			 <&tegra_car TEGRA124_CLK_PLL_X>,
			 <&tegra_car TEGRA124_CLK_PLL_P>,
			 <&dfll>;
		clock-names = "cpu_g", "pll_x", "pll_p", "dfll";
		clock-latency = <300000>;
	};

	<...>
};


code:
Binding for NVIDIA Tegra20 CPUFreq
==================================

Required properties:
- clocks: Must contain an entry for the CPU clock.
  See ../clocks/clock-bindings.txt for details.
- operating-points-v2: See ../bindings/opp/opp-v2.yaml for details.
- #cooling-cells: Should be 2. See ../thermal/thermal-cooling-devices.yaml for details.

For each opp entry in 'operating-points-v2' table:
- opp-supported-hw: Two bitfields indicating:
	On Tegra20:
	1. CPU process ID mask
	2. SoC speedo ID mask

	On Tegra30:
	1. CPU process ID mask
	2. CPU speedo ID mask

	A bitwise AND is performed against these values and if any bit
	matches, the OPP gets enabled.

- opp-microvolt: CPU voltage triplet.

Optional properties:
- cpu-supply: Phandle to the CPU power supply.

Example:
	regulators {
		cpu_reg: regulator0 {
			regulator-name = "vdd_cpu";
		};
	};

	cpu0_opp_table: opp_table0 {
		compatible = "operating-points-v2";

		opp@456000000 {
			clock-latency-ns = <125000>;
			opp-microvolt = <825000 825000 1125000>;
			opp-supported-hw = <0x03 0x0001>;
			opp-hz = /bits/ 64 <456000000>;
		};

		...
	};

	cpus {
		cpu@0 {
			compatible = "arm,cortex-a9";
			clocks = <&tegra_car TEGRA20_CLK_CCLK>;
			operating-points-v2 = <&cpu0_opp_table>;
			cpu-supply = <&cpu_reg>;
			#cooling-cells = <2>;
		};
	};


code:
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/cpufreq/qcom-cpufreq-nvmem.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Qualcomm Technologies, Inc. NVMEM CPUFreq bindings

maintainers:
  - Ilia Lin <ilia.lin@kernel.org>

description: |
  In certain Qualcomm Technologies, Inc. SoCs such as QCS404, The CPU supply
  voltage is dynamically configured by Core Power Reduction (CPR) depending on
  current CPU frequency and efuse values.
  CPR provides a power domain with multiple levels that are selected depending
  on the CPU OPP in use. The CPUFreq driver sets the CPR power domain level
  according to the required OPPs defined in the CPU OPP tables.

select:
  properties:
    compatible:
      contains:
        enum:
          - qcom,apq8064
          - qcom,apq8096
          - qcom,ipq8064
          - qcom,msm8939
          - qcom,msm8960
          - qcom,msm8974
          - qcom,msm8996
          - qcom,qcs404
  required:
    - compatible

properties:
  cpus:
    type: object

    patternProperties:
      '^cpu@[0-9a-f]+$':
        type: object

        properties:
          power-domains:
            maxItems: 1

          power-domain-names:
            items:
              - const: cpr

        required:
          - power-domains
          - power-domain-names

patternProperties:
  '^opp-table(-[a-z0-9]+)?$':
    if:
      properties:
        compatible:
          const: operating-points-v2-kryo-cpu
    then:
      patternProperties:
        '^opp-?[0-9]+$':
          required:
            - required-opps

additionalProperties: true

examples:
  - |
    / {
        model = "Qualcomm Technologies, Inc. QCS404 EVB 1000";
        compatible = "qcom,qcs404-evb-1000", "qcom,qcs404-evb", "qcom,qcs404";
        #address-cells = <2>;
        #size-cells = <2>;

        cpus {
            #address-cells = <1>;
            #size-cells = <0>;

            CPU0: cpu@100 {
                device_type = "cpu";
                compatible = "arm,cortex-a53";
                reg = <0x100>;
                enable-method = "psci";
                cpu-idle-states = <&CPU_SLEEP_0>;
                next-level-cache = <&L2_0>;
                #cooling-cells = <2>;
                clocks = <&apcs_glb>;
                operating-points-v2 = <&cpu_opp_table>;
                power-domains = <&cpr>;
                power-domain-names = "cpr";
            };

            CPU1: cpu@101 {
                device_type = "cpu";
                compatible = "arm,cortex-a53";
                reg = <0x101>;
                enable-method = "psci";
                cpu-idle-states = <&CPU_SLEEP_0>;
                next-level-cache = <&L2_0>;
                #cooling-cells = <2>;
                clocks = <&apcs_glb>;
                operating-points-v2 = <&cpu_opp_table>;
                power-domains = <&cpr>;
                power-domain-names = "cpr";
            };

            CPU2: cpu@102 {
                device_type = "cpu";
                compatible = "arm,cortex-a53";
                reg = <0x102>;
                enable-method = "psci";
                cpu-idle-states = <&CPU_SLEEP_0>;
                next-level-cache = <&L2_0>;
                #cooling-cells = <2>;
                clocks = <&apcs_glb>;
                operating-points-v2 = <&cpu_opp_table>;
                power-domains = <&cpr>;
                power-domain-names = "cpr";
            };

            CPU3: cpu@103 {
                device_type = "cpu";
                compatible = "arm,cortex-a53";
                reg = <0x103>;
                enable-method = "psci";
                cpu-idle-states = <&CPU_SLEEP_0>;
                next-level-cache = <&L2_0>;
                #cooling-cells = <2>;
                clocks = <&apcs_glb>;
                operating-points-v2 = <&cpu_opp_table>;
                power-domains = <&cpr>;
                power-domain-names = "cpr";
            };
        };

        cpu_opp_table: opp-table-cpu {
            compatible = "operating-points-v2-kryo-cpu";
            opp-shared;

            opp-1094400000 {
                opp-hz = /bits/ 64 <1094400000>;
                required-opps = <&cpr_opp1>;
            };
            opp-1248000000 {
                opp-hz = /bits/ 64 <1248000000>;
                required-opps = <&cpr_opp2>;
            };
            opp-1401600000 {
                opp-hz = /bits/ 64 <1401600000>;
                required-opps = <&cpr_opp3>;
            };
        };

        cpr_opp_table: opp-table-cpr {
            compatible = "operating-points-v2-qcom-level";

            cpr_opp1: opp1 {
                opp-level = <1>;
                qcom,opp-fuse-level = <1>;
            };
            cpr_opp2: opp2 {
                opp-level = <2>;
                qcom,opp-fuse-level = <2>;
            };
            cpr_opp3: opp3 {
                opp-level = <3>;
                qcom,opp-fuse-level = <3>;
            };
        };
    };


code:
TI CPUFreq and OPP bindings
================================

Certain TI SoCs, like those in the am335x, am437x, am57xx, and dra7xx
families support different OPPs depending on the silicon variant in use.
The ti-cpufreq driver can use revision and an efuse value from the SoC to
provide the OPP framework with supported hardware information. This is
used to determine which OPPs from the operating-points-v2 table get enabled
when it is parsed by the OPP framework.

Required properties:
--------------------
In 'cpus' nodes:
- operating-points-v2: Phandle to the operating-points-v2 table to use.

In 'operating-points-v2' table:
- compatible: Should be
	- 'operating-points-v2-ti-cpu' for am335x, am43xx, and dra7xx/am57xx,
	  omap34xx, omap36xx and am3517 SoCs
- syscon: A phandle pointing to a syscon node representing the control module
	  register space of the SoC.

Optional properties:
--------------------
- "vdd-supply", "vbb-supply": to define two regulators for dra7xx
- "cpu0-supply", "vbb-supply": to define two regulators for omap36xx

For each opp entry in 'operating-points-v2' table:
- opp-supported-hw: Two bitfields indicating:
	1. Which revision of the SoC the OPP is supported by
	2. Which eFuse bits indicate this OPP is available

	A bitwise AND is performed against these values and if any bit
	matches, the OPP gets enabled.

Example:
--------

/* From arch/arm/boot/dts/am33xx.dtsi */
cpus {
	#address-cells = <1>;
	#size-cells = <0>;
	cpu@0 {
		compatible = "arm,cortex-a8";
		device_type = "cpu";
		reg = <0>;

		operating-points-v2 = <&cpu0_opp_table>;

		clocks = <&dpll_mpu_ck>;
		clock-names = "cpu";

		clock-latency = <300000>; /* From omap-cpufreq driver */
	};
};

/*
 * cpu0 has different OPPs depending on SoC revision and some on revisions
 * 0x2 and 0x4 have eFuse bits that indicate if they are available or not
 */
cpu0_opp_table: opp-table {
	compatible = "operating-points-v2-ti-cpu";
	syscon = <&scm_conf>;

	/*
	 * The three following nodes are marked with opp-suspend
	 * because they can not be enabled simultaneously on a
	 * single SoC.
	 */
	opp50-300000000 {
		opp-hz = /bits/ 64 <300000000>;
		opp-microvolt = <950000 931000 969000>;
		opp-supported-hw = <0x06 0x0010>;
		opp-suspend;
	};

	opp100-275000000 {
		opp-hz = /bits/ 64 <275000000>;
		opp-microvolt = <1100000 1078000 1122000>;
		opp-supported-hw = <0x01 0x00FF>;
		opp-suspend;
	};

	opp100-300000000 {
		opp-hz = /bits/ 64 <300000000>;
		opp-microvolt = <1100000 1078000 1122000>;
		opp-supported-hw = <0x06 0x0020>;
		opp-suspend;
	};

	opp100-500000000 {
		opp-hz = /bits/ 64 <500000000>;
		opp-microvolt = <1100000 1078000 1122000>;
		opp-supported-hw = <0x01 0xFFFF>;
	};

	opp100-600000000 {
		opp-hz = /bits/ 64 <600000000>;
		opp-microvolt = <1100000 1078000 1122000>;
		opp-supported-hw = <0x06 0x0040>;
	};

	opp120-600000000 {
		opp-hz = /bits/ 64 <600000000>;
		opp-microvolt = <1200000 1176000 1224000>;
		opp-supported-hw = <0x01 0xFFFF>;
	};

	opp120-720000000 {
		opp-hz = /bits/ 64 <720000000>;
		opp-microvolt = <1200000 1176000 1224000>;
		opp-supported-hw = <0x06 0x0080>;
	};

	oppturbo-720000000 {
		opp-hz = /bits/ 64 <720000000>;
		opp-microvolt = <1260000 1234800 1285200>;
		opp-supported-hw = <0x01 0xFFFF>;
	};

	oppturbo-800000000 {
		opp-hz = /bits/ 64 <800000000>;
		opp-microvolt = <1260000 1234800 1285200>;
		opp-supported-hw = <0x06 0x0100>;
	};

	oppnitro-1000000000 {
		opp-hz = /bits/ 64 <1000000000>;
		opp-microvolt = <1325000 1298500 1351500>;
		opp-supported-hw = <0x04 0x0200>;
	};
};


code:
# SPDX-License-Identifier: GPL-2.0
%YAML 1.2
---
$id: http://devicetree.org/schemas/crypto/allwinner,sun4i-a10-crypto.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Allwinner A10 Security System

maintainers:
  - Chen-Yu Tsai <wens@csie.org>
  - Maxime Ripard <mripard@kernel.org>

properties:
  compatible:
    oneOf:
      - const: allwinner,sun4i-a10-crypto
      - items:
          - const: allwinner,sun5i-a13-crypto
          - const: allwinner,sun4i-a10-crypto
      - items:
          - const: allwinner,sun6i-a31-crypto
          - const: allwinner,sun4i-a10-crypto
      - items:
          - const: allwinner,sun7i-a20-crypto
          - const: allwinner,sun4i-a10-crypto
      - const: allwinner,sun8i-a33-crypto
      - items:
          - const: allwinner,sun8i-v3s-crypto
          - const: allwinner,sun8i-a33-crypto

  reg:
    maxItems: 1

  interrupts:
    maxItems: 1

  clocks:
    items:
      - description: Bus Clock
      - description: Module Clock

  clock-names:
    items:
      - const: ahb
      - const: mod

  dmas:
    items:
      - description: RX DMA Channel
      - description: TX DMA Channel

  dma-names:
    items:
      - const: rx
      - const: tx

  resets:
    maxItems: 1

  reset-names:
    const: ahb

required:
  - compatible
  - reg
  - interrupts
  - clocks
  - clock-names

if:
  properties:
    compatible:
      contains:
        enum:
          - allwinner,sun6i-a31-crypto
          - allwinner,sun8i-a33-crypto

then:
  required:
    - resets
    - reset-names

additionalProperties: false

examples:
  - |
    crypto: crypto-engine@1c15000 {
      compatible = "allwinner,sun4i-a10-crypto";
      reg = <0x01c15000 0x1000>;
      interrupts = <86>;
      clocks = <&ahb_gates 5>, <&ss_clk>;
      clock-names = "ahb", "mod";
    };

...


code:
# SPDX-License-Identifier: GPL-2.0
%YAML 1.2
---
$id: http://devicetree.org/schemas/crypto/allwinner,sun8i-ce.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Allwinner Crypto Engine driver

maintainers:
  - Corentin Labbe <clabbe.montjoie@gmail.com>

properties:
  compatible:
    enum:
      - allwinner,sun8i-h3-crypto
      - allwinner,sun8i-r40-crypto
      - allwinner,sun50i-a64-crypto
      - allwinner,sun50i-h5-crypto
      - allwinner,sun50i-h6-crypto

  reg:
    maxItems: 1

  interrupts:
    maxItems: 1

  clocks:
    items:
      - description: Bus clock
      - description: Module clock
      - description: MBus clock
    minItems: 2

  clock-names:
    items:
      - const: bus
      - const: mod
      - const: ram
    minItems: 2

  resets:
    maxItems: 1

if:
  properties:
    compatible:
      const: allwinner,sun50i-h6-crypto
then:
  properties:
    clocks:
      minItems: 3
    clock-names:
      minItems: 3
else:
  properties:
    clocks:
      maxItems: 2
    clock-names:
      maxItems: 2

required:
  - compatible
  - reg
  - interrupts
  - clocks
  - clock-names
  - resets

additionalProperties: false

examples:
  - |
    #include <dt-bindings/interrupt-controller/arm-gic.h>
    #include <dt-bindings/clock/sun50i-a64-ccu.h>
    #include <dt-bindings/reset/sun50i-a64-ccu.h>

    crypto: crypto@1c15000 {
      compatible = "allwinner,sun8i-h3-crypto";
      reg = <0x01c15000 0x1000>;
      interrupts = <GIC_SPI 94 IRQ_TYPE_LEVEL_HIGH>;
      clocks = <&ccu CLK_BUS_CE>, <&ccu CLK_CE>;
      clock-names = "bus", "mod";
      resets = <&ccu RST_BUS_CE>;
    };


code:
# SPDX-License-Identifier: GPL-2.0
%YAML 1.2
---
$id: http://devicetree.org/schemas/crypto/allwinner,sun8i-ss.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Allwinner Security System v2 driver

maintainers:
  - Corentin Labbe <corentin.labbe@gmail.com>

properties:
  compatible:
    enum:
      - allwinner,sun8i-a83t-crypto
      - allwinner,sun9i-a80-crypto

  reg:
    maxItems: 1

  interrupts:
    maxItems: 1

  clocks:
    items:
      - description: Bus clock
      - description: Module clock

  clock-names:
    items:
      - const: bus
      - const: mod

  resets:
    maxItems: 1

required:
  - compatible
  - reg
  - interrupts
  - clocks
  - clock-names
  - resets

additionalProperties: false

examples:
  - |
    #include <dt-bindings/interrupt-controller/arm-gic.h>
    #include <dt-bindings/clock/sun8i-a83t-ccu.h>
    #include <dt-bindings/reset/sun8i-a83t-ccu.h>

    crypto: crypto@1c15000 {
      compatible = "allwinner,sun8i-a83t-crypto";
      reg = <0x01c15000 0x1000>;
      interrupts = <GIC_SPI 94 IRQ_TYPE_LEVEL_HIGH>;
      resets = <&ccu RST_BUS_SS>;
      clocks = <&ccu CLK_BUS_SS>, <&ccu CLK_SS>;
      clock-names = "bus", "mod";
    };


code:
* AMD Cryptographic Coprocessor driver (ccp)

Required properties:
- compatible: Should be "amd,ccp-seattle-v1a"
- reg: Address and length of the register set for the device
- interrupts: Should contain the CCP interrupt

Optional properties:
- dma-coherent: Present if dma operations are coherent

Example:
	ccp@e0100000 {
		compatible = "amd,ccp-seattle-v1a";
		reg = <0 0xe0100000 0 0x10000>;
		interrupt-parent = <&gic>;
		interrupts = <0 3 4>;
	};


code:
# SPDX-License-Identifier: GPL-2.0
%YAML 1.2
---
$id: http://devicetree.org/schemas/crypto/amlogic,gxl-crypto.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Amlogic GXL Cryptographic Offloader

maintainers:
  - Corentin Labbe <clabbe@baylibre.com>

properties:
  compatible:
    items:
      - const: amlogic,gxl-crypto

  reg:
    maxItems: 1

  interrupts:
    items:
      - description: "Interrupt for flow 0"
      - description: "Interrupt for flow 1"

  clocks:
    maxItems: 1

  clock-names:
    const: blkmv

required:
  - compatible
  - reg
  - interrupts
  - clocks
  - clock-names

additionalProperties: false

examples:
  - |
    #include <dt-bindings/interrupt-controller/irq.h>
    #include <dt-bindings/interrupt-controller/arm-gic.h>
    #include <dt-bindings/clock/gxbb-clkc.h>

    crypto: crypto-engine@c883e000 {
        compatible = "amlogic,gxl-crypto";
        reg = <0xc883e000 0x36>;
        interrupts = <GIC_SPI 188 IRQ_TYPE_EDGE_RISING>, <GIC_SPI 189 IRQ_TYPE_EDGE_RISING>;
        clocks = <&clkc CLKID_BLKMV>;
        clock-names = "blkmv";
    };


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

title: Arm TrustZone CryptoCell cryptographic engine

maintainers:
  - Gilad Ben-Yossef <gilad@benyossef.com>

properties:
  compatible:
    enum:
      - arm,cryptocell-713-ree
      - arm,cryptocell-703-ree
      - arm,cryptocell-712-ree
      - arm,cryptocell-710-ree
      - arm,cryptocell-630p-ree

  reg:
    maxItems: 1

  interrupts:
    maxItems: 1

  clocks:
    maxItems: 1

  power-domains:
    maxItems: 1

  resets:
    maxItems: 1

  dma-coherent: true

required:
  - compatible
  - reg
  - interrupts

additionalProperties: false

examples:
  - |
    #include <dt-bindings/interrupt-controller/arm-gic.h>

    arm_cc712: crypto@80000000 {
            compatible = "arm,cryptocell-712-ree";
            reg = <0x80000000 0x10000>;
            interrupts = <GIC_SPI 30 IRQ_TYPE_LEVEL_HIGH>;
    };


code:
Axis crypto engine with PDMA interface.

Required properties:
- compatible : Should be one of the following strings:
	"axis,artpec6-crypto" for the version in the Axis ARTPEC-6 SoC
	"axis,artpec7-crypto" for the version in the Axis ARTPEC-7 SoC.
- reg: Base address and size for the PDMA register area.
- interrupts: Interrupt handle for the PDMA interrupt line.

Example:

crypto@f4264000 {
	compatible = "axis,artpec6-crypto";
	reg = <0xf4264000 0x1000>;
	interrupts = <GIC_SPI 19 IRQ_TYPE_LEVEL_HIGH>;
};


code:
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/crypto/aspeed,ast2500-hace.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: ASPEED HACE hash and crypto Hardware Accelerator Engines

maintainers:
  - Neal Liu <neal_liu@aspeedtech.com>

description: |
  The Hash and Crypto Engine (HACE) is designed to accelerate the throughput
  of hash data digest, encryption, and decryption. Basically, HACE can be
  divided into two independently engines - Hash Engine and Crypto Engine.

properties:
  compatible:
    enum:
      - aspeed,ast2500-hace
      - aspeed,ast2600-hace

  reg:
    maxItems: 1

  clocks:
    maxItems: 1

  interrupts:
    maxItems: 1

  resets:
    maxItems: 1

required:
  - compatible
  - reg
  - clocks
  - interrupts
  - resets

additionalProperties: false

examples:
  - |
    #include <dt-bindings/clock/ast2600-clock.h>
    hace: crypto@1e6d0000 {
        compatible = "aspeed,ast2600-hace";
        reg = <0x1e6d0000 0x200>;
        interrupts = <4>;
        clocks = <&syscon ASPEED_CLK_GATE_YCLK>;
        resets = <&syscon ASPEED_RESET_HACE>;
    };


code:
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
# Copyright (C) 2022 Microchip Technology, Inc. and its subsidiaries
%YAML 1.2
---
$id: http://devicetree.org/schemas/crypto/atmel,at91sam9g46-aes.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Atmel Advanced Encryption Standard (AES) HW cryptographic accelerator

maintainers:
  - Tudor Ambarus <tudor.ambarus@microchip.com>

properties:
  compatible:
    const: atmel,at91sam9g46-aes

  reg:
    maxItems: 1

  interrupts:
    maxItems: 1

  clocks:
    maxItems: 1

  clock-names:
    const: aes_clk

  dmas:
    items:
      - description: TX DMA Channel
      - description: RX DMA Channel

  dma-names:
    items:
      - const: tx
      - const: rx

required:
  - compatible
  - reg
  - interrupts
  - clocks
  - clock-names
  - dmas
  - dma-names

additionalProperties: false

examples:
  - |
    #include <dt-bindings/interrupt-controller/irq.h>
    #include <dt-bindings/interrupt-controller/arm-gic.h>
    #include <dt-bindings/clock/at91.h>
    #include <dt-bindings/dma/at91.h>

    aes: crypto@e1810000 {
      compatible = "atmel,at91sam9g46-aes";
      reg = <0xe1810000 0x100>;
      interrupts = <GIC_SPI 27 IRQ_TYPE_LEVEL_HIGH>;
      clocks = <&pmc PMC_TYPE_PERIPHERAL 27>;
      clock-names = "aes_clk";
      dmas = <&dma0 AT91_XDMAC_DT_PERID(1)>,
             <&dma0 AT91_XDMAC_DT_PERID(2)>;
      dma-names = "tx", "rx";
    };


code:
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
# Copyright (C) 2022 Microchip Technology, Inc. and its subsidiaries
%YAML 1.2
---
$id: http://devicetree.org/schemas/crypto/atmel,at91sam9g46-sha.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Atmel Secure Hash Algorithm (SHA) HW cryptographic accelerator

maintainers:
  - Tudor Ambarus <tudor.ambarus@microchip.com>

properties:
  compatible:
    const: atmel,at91sam9g46-sha

  reg:
    maxItems: 1

  interrupts:
    maxItems: 1

  clocks:
    maxItems: 1

  clock-names:
    const: sha_clk

  dmas:
    maxItems: 1
    description: TX DMA Channel

  dma-names:
    const: tx

required:
  - compatible
  - reg
  - interrupts
  - clocks
  - clock-names

additionalProperties: false

examples:
  - |
    #include <dt-bindings/interrupt-controller/irq.h>
    #include <dt-bindings/interrupt-controller/arm-gic.h>
    #include <dt-bindings/clock/at91.h>
    #include <dt-bindings/dma/at91.h>

    sha: crypto@e1814000 {
      compatible = "atmel,at91sam9g46-sha";
      reg = <0xe1814000 0x100>;
      interrupts = <GIC_SPI 83 IRQ_TYPE_LEVEL_HIGH>;
      clocks = <&pmc PMC_TYPE_PERIPHERAL 83>;
      clock-names = "sha_clk";
      dmas = <&dma0 AT91_XDMAC_DT_PERID(48)>;
      dma-names = "tx";
    };


code:
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
# Copyright (C) 2022 Microchip Technology, Inc. and its subsidiaries
%YAML 1.2
---
$id: http://devicetree.org/schemas/crypto/atmel,at91sam9g46-tdes.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Atmel Triple Data Encryption Standard (TDES) HW cryptographic accelerator

maintainers:
  - Tudor Ambarus <tudor.ambarus@microchip.com>

properties:
  compatible:
    const: atmel,at91sam9g46-tdes

  reg:
    maxItems: 1

  interrupts:
    maxItems: 1

  clocks:
    maxItems: 1

  clock-names:
    const: tdes_clk

  dmas:
    items:
      - description: TX DMA Channel
      - description: RX DMA Channel

  dma-names:
    items:
      - const: tx
      - const: rx

required:
  - compatible
  - reg
  - interrupts
  - clocks
  - clock-names

additionalProperties: false

examples:
  - |
    #include <dt-bindings/interrupt-controller/irq.h>
    #include <dt-bindings/interrupt-controller/arm-gic.h>
    #include <dt-bindings/clock/at91.h>
    #include <dt-bindings/dma/at91.h>

    tdes: crypto@e2014000 {
      compatible = "atmel,at91sam9g46-tdes";
      reg = <0xe2014000 0x100>;
      interrupts = <GIC_SPI 96 IRQ_TYPE_LEVEL_HIGH>;
      clocks = <&pmc PMC_TYPE_PERIPHERAL 96>;
      clock-names = "tdes_clk";
      dmas = <&dma0 AT91_XDMAC_DT_PERID(54)>,
             <&dma0 AT91_XDMAC_DT_PERID(53)>;
      dma-names = "tx", "rx";
    };


code:
The Broadcom Secure Processing Unit (SPU) hardware supports symmetric
cryptographic offload for Broadcom SoCs. A SoC may have multiple SPU hardware
blocks.

Required properties:
- compatible: Should be one of the following:
  brcm,spum-crypto - for devices with SPU-M hardware
  brcm,spu2-crypto - for devices with SPU2 hardware
  brcm,spu2-v2-crypto - for devices with enhanced SPU2 hardware features like SHA3
  and Rabin Fingerprint support
  brcm,spum-nsp-crypto - for the Northstar Plus variant of the SPU-M hardware

- reg: Should contain SPU registers location and length.
- mboxes: The mailbox channel to be used to communicate with the SPU.
  Mailbox channels correspond to DMA rings on the device.

Example:
	crypto@612d0000 {
		compatible = "brcm,spum-crypto";
		reg = <0 0x612d0000 0 0x900>;
		mboxes = <&pdc0 0>;
	};


code:
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/crypto/cortina,sl3516-crypto.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: SL3516 cryptographic offloader driver

maintainers:
  - Corentin Labbe <clabbe@baylibre.com>

properties:
  compatible:
    enum:
      - cortina,sl3516-crypto

  reg:
    maxItems: 1

  interrupts:
    maxItems: 1

  clocks:
    maxItems: 1

  resets:
    maxItems: 1

required:
  - compatible
  - reg
  - interrupts
  - clocks
  - resets

additionalProperties: false

examples:
  - |
    #include <dt-bindings/interrupt-controller/irq.h>
    #include <dt-bindings/clock/cortina,gemini-clock.h>
    #include <dt-bindings/reset/cortina,gemini-reset.h>

    crypto@62000000 {
        compatible = "cortina,sl3516-crypto";
        reg = <0x62000000 0x10000>;
        interrupts = <7 IRQ_TYPE_EDGE_RISING>;
        resets = <&syscon GEMINI_RESET_SECURITY>;
        clocks = <&syscon GEMINI_CLK_GATE_SECURITY>;
    };


code:
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/crypto/fsl-dcp.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Freescale DCP (Data Co-Processor) found on i.MX23/i.MX28

maintainers:
  - Marek Vasut <marex@denx.de>

properties:
  compatible:
    enum:
      - fsl,imx23-dcp
      - fsl,imx28-dcp

  reg:
    maxItems: 1

  interrupts:
    description: Should contain MXS DCP interrupt numbers, VMI IRQ and DCP IRQ
      must be supplied, optionally Secure IRQ can be present, but is currently
      not implemented and not used.
    items:
      - description: MXS DCP VMI interrupt
      - description: MXS DCP DCP interrupt
      - description: MXS DCP secure interrupt
    minItems: 2

  clocks:
    maxItems: 1

  clock-names:
    const: dcp

required:
  - compatible
  - reg
  - interrupts

additionalProperties: false

examples:
  - |
    crypto@80028000 {
        compatible = "fsl,imx23-dcp";
        reg = <0x80028000 0x2000>;
        interrupts = <53>, <54>;
    };


code:
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/crypto/fsl-imx-sahara.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Freescale SAHARA Cryptographic Accelerator included in some i.MX chips

maintainers:
  - Steffen Trumtrar <s.trumtrar@pengutronix.de>

properties:
  compatible:
    enum:
      - fsl,imx27-sahara
      - fsl,imx53-sahara

  reg:
    maxItems: 1

  interrupts:
    maxItems: 1

required:
  - compatible
  - reg
  - interrupts

additionalProperties: false

examples:
  - |
    crypto@10025000 {
        compatible = "fsl,imx27-sahara";
        reg = < 0x10025000 0x800>;
        interrupts = <75>;
    };


code:
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/crypto/fsl-imx-scc.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Freescale Security Controller (SCC)

maintainers:
  - Steffen Trumtrar <s.trumtrar@pengutronix.de>

properties:
  compatible:
    const: fsl,imx25-scc

  reg:
    maxItems: 1

  interrupts:
    items:
      - description: SCC SCM interrupt
      - description: SCC SMN interrupt

  interrupt-names:
    items:
      - const: scm
      - const: smn

  clocks:
    maxItems: 1

  clock-names:
    const: ipg

required:
  - compatible
  - reg
  - interrupts
  - interrupt-names
  - clocks
  - clock-names

additionalProperties: false

examples:
  - |
    crypto@53fac000 {
        compatible = "fsl,imx25-scc";
        reg = <0x53fac000 0x4000>;
        clocks = <&clks 111>;
        clock-names = "ipg";
        interrupts = <49>, <50>;
        interrupt-names = "scm", "smn";
    };


code:
Freescale SoC SEC Security Engines versions 1.x-2.x-3.x

Required properties:

- compatible : Should contain entries for this and backward compatible
  SEC versions, high to low, e.g., "fsl,sec2.1", "fsl,sec2.0" (SEC2/3)
                             e.g., "fsl,sec1.2", "fsl,sec1.0" (SEC1)
    warning: SEC1 and SEC2 are mutually exclusive
- reg : Offset and length of the register set for the device
- interrupts : the SEC's interrupt number
- fsl,num-channels : An integer representing the number of channels
  available.
- fsl,channel-fifo-len : An integer representing the number of
  descriptor pointers each channel fetch fifo can hold.
- fsl,exec-units-mask : The bitmask representing what execution units
  (EUs) are available. It's a single 32-bit cell. EU information
  should be encoded following the SEC's Descriptor Header Dword
  EU_SEL0 field documentation, i.e. as follows:

	bit 0  = reserved - should be 0
	bit 1  = set if SEC has the ARC4 EU (AFEU)
	bit 2  = set if SEC has the DES/3DES EU (DEU)
	bit 3  = set if SEC has the message digest EU (MDEU/MDEU-A)
	bit 4  = set if SEC has the random number generator EU (RNG)
	bit 5  = set if SEC has the public key EU (PKEU)
	bit 6  = set if SEC has the AES EU (AESU)
	bit 7  = set if SEC has the Kasumi EU (KEU)
	bit 8  = set if SEC has the CRC EU (CRCU)
	bit 11 = set if SEC has the message digest EU extended alg set (MDEU-B)

remaining bits are reserved for future SEC EUs.

- fsl,descriptor-types-mask : The bitmask representing what descriptors
  are available. It's a single 32-bit cell. Descriptor type information
  should be encoded following the SEC's Descriptor Header Dword DESC_TYPE
  field documentation, i.e. as follows:

	bit 0  = set if SEC supports the aesu_ctr_nonsnoop desc. type
	bit 1  = set if SEC supports the ipsec_esp descriptor type
	bit 2  = set if SEC supports the common_nonsnoop desc. type
	bit 3  = set if SEC supports the 802.11i AES ccmp desc. type
	bit 4  = set if SEC supports the hmac_snoop_no_afeu desc. type
	bit 5  = set if SEC supports the srtp descriptor type
	bit 6  = set if SEC supports the non_hmac_snoop_no_afeu desc.type
	bit 7  = set if SEC supports the pkeu_assemble descriptor type
	bit 8  = set if SEC supports the aesu_key_expand_output desc.type
	bit 9  = set if SEC supports the pkeu_ptmul descriptor type
	bit 10 = set if SEC supports the common_nonsnoop_afeu desc. type
	bit 11 = set if SEC supports the pkeu_ptadd_dbl descriptor type

  ..and so on and so forth.

Example:

	/* MPC8548E */
	crypto@30000 {
		compatible = "fsl,sec2.1", "fsl,sec2.0";
		reg = <0x30000 0x10000>;
		interrupts = <29 2>;
		interrupt-parent = <&mpic>;
		fsl,num-channels = <4>;
		fsl,channel-fifo-len = <24>;
		fsl,exec-units-mask = <0xfe>;
		fsl,descriptor-types-mask = <0x12b0ebf>;
	};