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

title: Maxim MAX77843 MicroUSB and Companion Power Management IC Extcon

maintainers:
  - Chanwoo Choi <cw00.choi@samsung.com>
  - Krzysztof Kozlowski <krzk@kernel.org>

description: |
  This is a part of device tree bindings for Maxim MAX77843 MicroUSB
  Integrated Circuit (MUIC).

  See also Documentation/devicetree/bindings/mfd/maxim,max77843.yaml for
  additional information and example.

properties:
  compatible:
    const: maxim,max77843-muic

  connector:
    $ref: /schemas/connector/usb-connector.yaml#

  ports:
    $ref: /schemas/graph.yaml#/properties/ports
    description:
      Any connector to the data bus of this controller should be modelled using
      the OF graph bindings specified
    properties:
      port:
        $ref: /schemas/graph.yaml#/properties/port

required:
  - compatible
  - connector

additionalProperties: false


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

title: Qualcomm Technologies, Inc. PM8941 USB ID Extcon device

maintainers:
  - Guru Das Srinagesh <gurus@codeaurora.org>

description: |
  Some Qualcomm PMICs have a "misc" module that can be used to detect when
  the USB ID pin has been pulled low or high.

properties:
  compatible:
    items:
      - const: qcom,pm8941-misc

  reg:
    maxItems: 1

  interrupts:
    minItems: 1
    maxItems: 2

  interrupt-names:
    minItems: 1
    items:
      - const: usb_id
      - const: usb_vbus

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

additionalProperties: false

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

    pmic {
            #address-cells = <1>;
            #size-cells = <0>;
            interrupt-controller;
            #interrupt-cells = <4>;

            usb_id: misc@900 {
                    compatible = "qcom,pm8941-misc";
                    reg = <0x900>;
                    interrupts = <0x0 0x9 0 IRQ_TYPE_EDGE_BOTH>;
                    interrupt-names = "usb_id";
            };
    };

    usb-controller {
           extcon = <&usb_id>;
    };

repo_name: angery/linux


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

title: SM5502/SM5504 MUIC (Micro-USB Interface Controller) device

maintainers:
  - Chanwoo Choi <cw00.choi@samsung.com>

description:
  The Silicon Mitus SM5502 is a MUIC (Micro-USB Interface Controller) device
  which can detect the state of external accessory when external accessory is
  attached or detached and button is pressed or released. It is interfaced to
  the host controller using an I2C interface.

properties:
  compatible:
    enum:
      - siliconmitus,sm5502-muic
      - siliconmitus,sm5504-muic
      - siliconmitus,sm5703-muic

  reg:
    maxItems: 1
    description: I2C slave address of the device. Usually 0x25 for SM5502
      and SM5703, 0x14 for SM5504.

  interrupts:
    maxItems: 1

required:
  - compatible
  - reg
  - interrupts

additionalProperties: false

examples:
  - |
    #include <dt-bindings/interrupt-controller/irq.h>
    i2c {
        #address-cells = <1>;
        #size-cells = <0>;

        extcon@25 {
                compatible = "siliconmitus,sm5502-muic";
                reg = <0x25>;
                interrupt-parent = <&msmgpio>;
                interrupts = <12 IRQ_TYPE_EDGE_FALLING>;
        };
    };


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

title: Cirrus Logic/Wolfson Microelectronics Arizona class audio SoCs

maintainers:
  - patches@opensource.cirrus.com

description: |
  These devices are audio SoCs with extensive digital capabilities and a
  range of analogue I/O.

  This document lists Extcon specific bindings, see the primary binding
  document ../mfd/arizona.yaml

properties:
  wlf,hpdet-channel:
    description:
      Headphone detection channel.  ARIZONA_ACCDET_MODE_HPL/1 sets the
      headphone detect mode to HPDETL, ARIZONA_ACCDET_MODE_HPR/2 sets it
      to HPDETR.  If this node is not included or if the value is unknown,
      then headphone detection mode is set to HPDETL.
    $ref: "/schemas/types.yaml#/definitions/uint32"
    minimum: 1
    maximum: 2

  wlf,use-jd2:
    description:
      Use the additional JD input along with JD1 for dual pin jack detection.
    type: boolean

  wlf,use-jd2-nopull:
    description:
      Internal pull on JD2 is disabled when used for jack detection.
    type: boolean

  wlf,jd-invert:
    description:
      Invert the polarity of the jack detection switch.
    type: boolean

  wlf,micd-software-compare:
    description:
      Use a software comparison to determine mic presence.
    type: boolean

  wlf,micd-detect-debounce:
    description:
      Additional software microphone detection debounce specified in
      milliseconds.
    $ref: "/schemas/types.yaml#/definitions/uint32"

  wlf,micd-pol-gpio:
    description:
      GPIO specifier for the GPIO controlling the headset polarity if one
      exists.
    maxItems: 1

  wlf,micd-bias-start-time:
    description:
      Time allowed for MICBIAS to startup prior to performing microphone
      detection, specified as per the ARIZONA_MICD_TIME_XXX defines.
    $ref: "/schemas/types.yaml#/definitions/uint32"
    minimum: 0
    maximum: 12

  wlf,micd-rate:
    description:
      Delay between successive microphone detection measurements, specified
      as per the ARIZONA_MICD_TIME_XXX defines.
    $ref: "/schemas/types.yaml#/definitions/uint32"
    minimum: 0
    maximum: 12

  wlf,micd-dbtime:
    description:
      Microphone detection hardware debounces specified as the number of
      measurements to take.
    $ref: "/schemas/types.yaml#/definitions/uint32"
    enum: [2, 4]

  wlf,micd-timeout-ms:
    description:
      Timeout for microphone detection, specified in milliseconds.

  wlf,micd-force-micbias:
    description:
      Force MICBIAS continuously on during microphone detection.
    type: boolean

  wlf,micd-configs:
    description:
      Headset polarity configurations (generally used for detection of
      CTIA / OMTP headsets), the field can be of variable length but
      should always be a multiple of 3 cells long, each three cell group
      represents one polarity configuration.
    $ref: "/schemas/types.yaml#/definitions/uint32-matrix"
    items:
      items:
        - description:
            The first cell defines the accessory detection pin, zero
            will use MICDET1 and 0x2000 will use MICDET2.
          enum: [ 0, 0x2000 ]
        - description:
            The second cell represents the MICBIAS to be used. Zero
            will use MICVDD, 1-3 will use MICBIASx.
          minimum: 0
          maximum: 3
        - description:
            The third cell represents the value of the micd-pol-gpio
            pin.
          minimum: 0
          maximum: 1

  wlf,gpsw:
    description:
      Settings for the general purpose switch, set as one of the
      ARIZONA_GPSW_XXX defines.
    $ref: "/schemas/types.yaml#/definitions/uint32"
    minimum: 0
    maximum: 3

additionalProperties: true


code:
# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
# Copyright 2021 ARM Ltd.
%YAML 1.2
---
$id: http://devicetree.org/schemas/firmware/arm,scmi.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: System Control and Management Interface (SCMI) Message Protocol bindings

maintainers:
  - Sudeep Holla <sudeep.holla@arm.com>

description: |
  The SCMI is intended to allow agents such as OSPM to manage various functions
  that are provided by the hardware platform it is running on, including power
  and performance functions.

  This binding is intended to define the interface the firmware implementing
  the SCMI as described in ARM document number ARM DEN 0056 ("ARM System Control
  and Management Interface Platform Design Document")[0] provide for OSPM in
  the device tree.

  [0] https://developer.arm.com/documentation/den0056/latest

properties:
  $nodename:
    const: scmi

  compatible:
    oneOf:
      - description: SCMI compliant firmware with mailbox transport
        items:
          - const: arm,scmi
      - description: SCMI compliant firmware with ARM SMC/HVC transport
        items:
          - const: arm,scmi-smc
      - description: SCMI compliant firmware with SCMI Virtio transport.
                     The virtio transport only supports a single device.
        items:
          - const: arm,scmi-virtio
      - description: SCMI compliant firmware with OP-TEE transport
        items:
          - const: linaro,scmi-optee

  interrupts:
    description:
      The interrupt that indicates message completion by the platform
      rather than by the return of the smc call. This should not be used
      except when the platform requires such behavior.
    maxItems: 1

  interrupt-names:
    const: a2p

  mbox-names:
    description:
      Specifies the mailboxes used to communicate with SCMI compliant
      firmware.
    items:
      - const: tx
      - const: rx

  mboxes:
    description:
      List of phandle and mailbox channel specifiers. It should contain
      exactly one or two mailboxes, one for transmitting messages("tx")
      and another optional for receiving the notifications("rx") if supported.
    minItems: 1
    maxItems: 2

  shmem:
    description:
      List of phandle pointing to the shared memory(SHM) area, for each
      transport channel specified.
    minItems: 1
    maxItems: 2

  '#address-cells':
    const: 1

  '#size-cells':
    const: 0

  atomic-threshold-us:
    description:
      An optional time value, expressed in microseconds, representing, on this
      platform, the threshold above which any SCMI command, advertised to have
      an higher-than-threshold execution latency, should not be considered for
      atomic mode of operation, even if requested.
    default: 0

  arm,smc-id:
    $ref: /schemas/types.yaml#/definitions/uint32
    description:
      SMC id required when using smc or hvc transports

  linaro,optee-channel-id:
    $ref: /schemas/types.yaml#/definitions/uint32
    description:
      Channel specifier required when using OP-TEE transport.

  protocol@11:
    type: object
    properties:
      reg:
        const: 0x11

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

    required:
      - '#power-domain-cells'

  protocol@13:
    type: object
    properties:
      reg:
        const: 0x13

      '#clock-cells':
        const: 1

    required:
      - '#clock-cells'

  protocol@14:
    type: object
    properties:
      reg:
        const: 0x14

      '#clock-cells':
        const: 1

    required:
      - '#clock-cells'

  protocol@15:
    type: object
    properties:
      reg:
        const: 0x15

      '#thermal-sensor-cells':
        const: 1

    required:
      - '#thermal-sensor-cells'

  protocol@16:
    type: object
    properties:
      reg:
        const: 0x16

      '#reset-cells':
        const: 1

    required:
      - '#reset-cells'

  protocol@17:
    type: object
    properties:
      reg:
        const: 0x17

      regulators:
        type: object
        description:
          The list of all regulators provided by this SCMI controller.

        patternProperties:
          '^regulators@[0-9a-f]+$':
            type: object
            $ref: "../regulator/regulator.yaml#"

            properties:
              reg:
                maxItems: 1
                description: Identifier for the voltage regulator.

            required:
              - reg

  protocol@18:
    type: object
    properties:
      reg:
        const: 0x18

additionalProperties: false

patternProperties:
  '^protocol@[0-9a-f]+$':
    type: object
    description:
      Each sub-node represents a protocol supported. If the platform
      supports a dedicated communication channel for a particular protocol,
      then the corresponding transport properties must be present.
      The virtio transport does not support a dedicated communication channel.

    properties:
      reg:
        maxItems: 1

      mbox-names:
        items:
          - const: tx
          - const: rx

      mboxes:
        minItems: 1
        maxItems: 2

      shmem:
        minItems: 1
        maxItems: 2

      linaro,optee-channel-id:
        $ref: /schemas/types.yaml#/definitions/uint32
        description:
          Channel specifier required when using OP-TEE transport and
          protocol has a dedicated communication channel.

    required:
      - reg

required:
  - compatible

if:
  properties:
    compatible:
      contains:
        const: arm,scmi
then:
  properties:
    interrupts: false
    interrupt-names: false

  required:
    - mboxes
    - shmem

else:
  if:
    properties:
      compatible:
        contains:
          const: arm,scmi-smc
  then:
    required:
      - arm,smc-id
      - shmem

  else:
    if:
      properties:
        compatible:
          contains:
            const: linaro,scmi-optee
    then:
      required:
        - linaro,optee-channel-id

examples:
  - |
    firmware {
        scmi {
            compatible = "arm,scmi";
            mboxes = <&mhuB 0 0>,
                     <&mhuB 0 1>;
            mbox-names = "tx", "rx";
            shmem = <&cpu_scp_lpri0>,
                    <&cpu_scp_lpri1>;

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

            atomic-threshold-us = <10000>;

            scmi_devpd: protocol@11 {
                reg = <0x11>;
                #power-domain-cells = <1>;
            };

            scmi_dvfs: protocol@13 {
                reg = <0x13>;
                #clock-cells = <1>;

                mboxes = <&mhuB 1 0>,
                         <&mhuB 1 1>;
                mbox-names = "tx", "rx";
                shmem = <&cpu_scp_hpri0>,
                        <&cpu_scp_hpri1>;
            };

            scmi_clk: protocol@14 {
                reg = <0x14>;
                #clock-cells = <1>;
            };

            scmi_sensors: protocol@15 {
                reg = <0x15>;
                #thermal-sensor-cells = <1>;
            };

            scmi_reset: protocol@16 {
                reg = <0x16>;
                #reset-cells = <1>;
            };

            scmi_voltage: protocol@17 {
                reg = <0x17>;
                regulators {
                    #address-cells = <1>;
                    #size-cells = <0>;

                    regulator_devX: regulator@0 {
                        reg = <0x0>;
                        regulator-max-microvolt = <3300000>;
                    };

                    regulator_devY: regulator@9 {
                        reg = <0x9>;
                        regulator-min-microvolt = <500000>;
                        regulator-max-microvolt = <4200000>;
                    };
                };
            };

            scmi_powercap: protocol@18 {
                reg = <0x18>;
            };
        };
    };

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

        sram@50000000 {
            compatible = "mmio-sram";
            reg = <0x0 0x50000000 0x0 0x10000>;

            #address-cells = <1>;
            #size-cells = <1>;
            ranges = <0 0x0 0x50000000 0x10000>;

            cpu_scp_lpri0: scp-sram-section@0 {
                compatible = "arm,scmi-shmem";
                reg = <0x0 0x80>;
            };

            cpu_scp_lpri1: scp-sram-section@80 {
                compatible = "arm,scmi-shmem";
                reg = <0x80 0x80>;
            };

            cpu_scp_hpri0: scp-sram-section@100 {
                compatible = "arm,scmi-shmem";
                reg = <0x100 0x80>;
            };

            cpu_scp_hpri2: scp-sram-section@180 {
                compatible = "arm,scmi-shmem";
                reg = <0x180 0x80>;
            };
        };
    };

  - |
    firmware {
        scmi {
            compatible = "arm,scmi-smc";
            shmem = <&cpu_scp_lpri0>, <&cpu_scp_lpri1>;
            arm,smc-id = <0xc3000001>;

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

            scmi_devpd1: protocol@11 {
                reg = <0x11>;
                #power-domain-cells = <1>;
            };
        };
    };

  - |
    firmware {
        scmi {
            compatible = "linaro,scmi-optee";
            linaro,optee-channel-id = <0>;

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

            scmi_dvfs1: protocol@13 {
                reg = <0x13>;
                linaro,optee-channel-id = <1>;
                shmem = <&cpu_optee_lpri0>;
                #clock-cells = <1>;
            };

            scmi_clk0: protocol@14 {
                reg = <0x14>;
                #clock-cells = <1>;
            };
        };
    };

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

        sram@51000000 {
            compatible = "mmio-sram";
            reg = <0x0 0x51000000 0x0 0x10000>;

            #address-cells = <1>;
            #size-cells = <1>;
            ranges = <0 0x0 0x51000000 0x10000>;

            cpu_optee_lpri0: optee-sram-section@0 {
                compatible = "arm,scmi-shmem";
                reg = <0x0 0x80>;
            };
        };
    };

...


code:
# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
# Copyright 2021 ARM Ltd.
%YAML 1.2
---
$id: http://devicetree.org/schemas/firmware/arm,scpi.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: System Control and Power Interface (SCPI) Message Protocol bindings

maintainers:
  - Sudeep Holla <sudeep.holla@arm.com>

description: |
  Firmware implementing the SCPI described in ARM document number ARM DUI
  0922B ("ARM Compute Subsystem SCP: Message Interface Protocols")[0] can be
  used by Linux to initiate various system control and power operations.

  This binding is intended to define the interface the firmware implementing
  the SCPI provide for OSPM in the device tree.

  [0] http://infocenter.arm.com/help/topic/com.arm.doc.dui0922b/index.html

properties:
  $nodename:
    const: scpi

  compatible:
    description:
      SCPI compliant firmware complying to SCPI v1.0 and above OR
      SCPI compliant firmware complying to all unversioned releases
      prior to SCPI v1.0
    oneOf:
      - const: arm,scpi               # SCPI v1.0 and above
      - const: arm,scpi-pre-1.0       # Unversioned SCPI before v1.0
      - items:
          - enum:
              - amlogic,meson-gxbb-scpi
          - const: arm,scpi-pre-1.0

  mboxes:
    description:
      List of phandle and mailbox channel specifiers. All the channels reserved
      by remote SCP firmware for use by SCPI message protocol should be
      specified in any order.
    minItems: 1
    maxItems: 4

  shmem:
    description:
      List of phandle pointing to the shared memory(SHM) area between the
      processors using these mailboxes for IPC, one for each mailbox SHM can
      be any memory reserved for the purpose of this communication between the
      processors.
    minItems: 1
    maxItems: 4

  power-controller:
    type: object
    description:
      This sub-node represents SCPI power domain controller.

    properties:
      compatible:
        const: arm,scpi-power-domains

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

      num-domains:
        $ref: /schemas/types.yaml#/definitions/uint32
        description:
          Total number of power domains provided by SCPI. This is needed as
          the SCPI message protocol lacks a mechanism to query this
          information at runtime.

    required:
      - compatible
      - '#power-domain-cells'
      - num-domains

    additionalProperties: false

  sensors:
    type: object
    description: |
      This sub-node represents SCPI sensors controller.

    properties:
      compatible:
        oneOf:
          - const: arm,scpi-sensors
          - items:
              - enum:
                  - amlogic,meson-gxbb-scpi-sensors
              - const: arm,scpi-sensors

      '#thermal-sensor-cells':
        const: 1

    required:
      - compatible
      - '#thermal-sensor-cells'

    additionalProperties: false

  clocks:
    type: object
    description:
      This is the container node. Each sub-node represents one of the types
      of clock controller - indexed or full range.

    properties:
      compatible:
        const: arm,scpi-clocks

    patternProperties:
      "^clocks-[0-9a-f]+$":
        type: object
        description: |
          This sub-node represents one of the types of clock controller
          - indexed or full range.

          "arm,scpi-dvfs-clocks" - all the clocks that are variable and index
          based. These clocks don't provide an entire range of values between
          the limits but only discrete points within the range. The firmware
          provides the mapping for each such operating frequency and the index
          associated with it. The firmware also manages the voltage scaling
          appropriately with the clock scaling.

          "arm,scpi-variable-clocks" - all the clocks that are variable and
          provide full range within the specified range. The firmware provides
          the range of values within a specified range.

        properties:
          compatible:
            enum:
              - arm,scpi-dvfs-clocks
              - arm,scpi-variable-clocks

          '#clock-cells':
            const: 1

          clock-output-names: true

          clock-indices:
            $ref: /schemas/types.yaml#/definitions/uint32-array
            description:
              The identifying number for the clocks(i.e.clock_id) in the node.
              It can be non linear and hence provide the mapping of identifiers
              into the clock-output-names array.

        required:
          - compatible
          - '#clock-cells'
          - clock-output-names
          - clock-indices

        additionalProperties: false

    required:
      - compatible

    additionalProperties: false

additionalProperties: false

required:
  - compatible
  - mboxes
  - shmem

examples:
  - |
    firmware {
        scpi {
            compatible = "arm,scpi";
            mboxes = <&mhuA 1>;
            shmem = <&cpu_scp_hpri>; /* HP-NonSecure */

            scpi_devpd: power-controller {
                compatible = "arm,scpi-power-domains";
                num-domains = <2>;
                #power-domain-cells = <1>;
            };

            clocks {
                compatible = "arm,scpi-clocks";

                scpi_dvfs: clocks-0 {
                    compatible = "arm,scpi-dvfs-clocks";
                    #clock-cells = <1>;
                    clock-indices = <0>, <1>, <2>;
                    clock-output-names = "atlclk", "aplclk","gpuclk";
                };

                scpi_clk: clocks-1 {
                    compatible = "arm,scpi-variable-clocks";
                    #clock-cells = <1>;
                    clock-indices = <3>, <4>;
                    clock-output-names = "pxlclk0", "pxlclk1";
                };
            };

            scpi_sensors: sensors {
                compatible = "arm,scpi-sensors";
                #thermal-sensor-cells = <1>;
            };

        };
    };

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

        sram@50000000 {
            compatible = "mmio-sram";
            reg = <0x0 0x50000000 0x0 0x10000>;

            #address-cells = <1>;
            #size-cells = <1>;
            ranges = <0 0x0 0x50000000 0x10000>;

            cpu_scp_lpri: scp-sram-section@0 {
                compatible = "arm,scp-shmem";
                reg = <0x0 0x200>;
            };

            cpu_scp_hpri: scp-sram-section@200 {
                compatible = "arm,scp-shmem";
                reg = <0x200 0x200>;
            };
        };
    };

  - |
    firmware {
        scpi {
            compatible = "amlogic,meson-gxbb-scpi", "arm,scpi-pre-1.0";
            mboxes = <&mailbox 1>, <&mailbox 2>;
            shmem = <&cpu_scp_lpri>, <&cpu_scp_hpri>;

            scpi_sensors1: sensors {
                compatible = "amlogic,meson-gxbb-scpi-sensors", "arm,scpi-sensors";
                #thermal-sensor-cells = <1>;
            };
        };
    };
...


code:
COREBOOT firmware information

The device tree node to communicate the location of coreboot's memory-resident
bookkeeping structures to the kernel. Since coreboot itself cannot boot a
device-tree-based kernel (yet), this node needs to be inserted by a
second-stage bootloader (a coreboot "payload").

Required properties:
 - compatible: Should be "coreboot"
 - reg: Address and length of the following two memory regions, in order:
	1.) The coreboot table. This is a list of variable-sized descriptors
	that contain various compile- and run-time generated firmware
	parameters. It is identified by the magic string "LBIO" in its first
	four bytes.
	See coreboot's src/commonlib/include/commonlib/coreboot_tables.h for
	details.
	2.) The CBMEM area. This is a downward-growing memory region used by
	coreboot to dynamically allocate data structures that remain resident.
	It may or may not include the coreboot table as one of its members. It
	is identified by a root node descriptor with the magic number
	0xc0389481 that resides in the topmost 8 bytes of the area.
	See coreboot's src/include/imd.h for details.

Example:
	firmware {
		ranges;

		coreboot {
			compatible = "coreboot";
			reg = <0xfdfea000 0x264>,
			      <0xfdfea000 0x16000>;
		}
	};


code:
Turris Mox rWTM firmware driver

Required properties:
 - compatible		: Should be "cznic,turris-mox-rwtm"
 - mboxes		: Must contain a reference to associated mailbox

This device tree node should be used on Turris Mox, or potentially another A3700
compatible device running the Mox's rWTM firmware in the secure processor (for
example it is possible to flash this firmware into EspressoBin).

Example:

	firmware {
		turris-mox-rwtm {
			compatible = "cznic,turris-mox-rwtm";
			mboxes = <&rwtm 0>;
			status = "okay";
		};
	};


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

title: NXP i.MX System Controller Firmware (SCFW)

maintainers:
  - Dong Aisheng <aisheng.dong@nxp.com>

description:
  The System Controller Firmware (SCFW) is a low-level system function
  which runs on a dedicated Cortex-M core to provide power, clock, and
  resource management. It exists on some i.MX8 processors. e.g. i.MX8QM
  (QM, QP), and i.MX8QX (QXP, DX).
  The AP communicates with the SC using a multi-ported MU module found
  in the LSIO subsystem. The current definition of this MU module provides
  5 remote AP connections to the SC to support up to 5 execution environments
  (TZ, HV, standard Linux, etc.). The SC side of this MU module interfaces
  with the LSIO DSC IP bus. The SC firmware will communicate with this MU
  using the MSI bus.

properties:
  compatible:
    const: fsl,imx-scu

  clock-controller:
    description:
      Clock controller node that provides the clocks controlled by the SCU
    $ref: /schemas/clock/fsl,scu-clk.yaml

  gpio:
    description:
      Control the GPIO PINs on SCU domain over the firmware APIs
    $ref: /schemas/gpio/fsl,imx8qxp-sc-gpio.yaml

  ocotp:
    description:
      OCOTP controller node provided by the SCU
    $ref: /schemas/nvmem/fsl,scu-ocotp.yaml

  keys:
    description:
      Keys provided by the SCU
    $ref: /schemas/input/fsl,scu-key.yaml

  mboxes:
    description:
      A list of phandles of TX MU channels followed by a list of phandles of
      RX MU channels. The list may include at the end one more optional MU
      channel for general interrupt. The number of expected tx and rx
      channels is 1 TX and 1 RX channels if MU instance is "fsl,imx8-mu-scu"
      compatible, 4 TX and 4 RX channels otherwise. All MU channels must be
      within the same MU instance. Cross instances are not allowed. The MU
      instance can only be one of LSIO MU0~M4 for imx8qxp and imx8qm. Users
      need to ensure that one is used that does not conflict with other
      execution environments such as ATF.
    oneOf:
      - items:
          - description: TX0 MU channel
          - description: RX0 MU channel
      - items:
          - description: TX0 MU channel
          - description: RX0 MU channel
          - description: optional MU channel for general interrupt
      - items:
          - description: TX0 MU channel
          - description: TX1 MU channel
          - description: TX2 MU channel
          - description: TX3 MU channel
          - description: RX0 MU channel
          - description: RX1 MU channel
          - description: RX2 MU channel
          - description: RX3 MU channel
      - items:
          - description: TX0 MU channel
          - description: TX1 MU channel
          - description: TX2 MU channel
          - description: TX3 MU channel
          - description: RX0 MU channel
          - description: RX1 MU channel
          - description: RX2 MU channel
          - description: RX3 MU channel
          - description: optional MU channel for general interrupt

  mbox-names:
    oneOf:
      - items:
          - const: tx0
          - const: rx0
      - items:
          - const: tx0
          - const: rx0
          - const: gip3
      - items:
          - const: tx0
          - const: tx1
          - const: tx2
          - const: tx3
          - const: rx0
          - const: rx1
          - const: rx2
          - const: rx3
      - items:
          - const: tx0
          - const: tx1
          - const: tx2
          - const: tx3
          - const: rx0
          - const: rx1
          - const: rx2
          - const: rx3
          - const: gip3

  pinctrl:
    description:
      Pin controller provided by the SCU
    $ref: /schemas/pinctrl/fsl,scu-pinctrl.yaml

  power-controller:
    description:
      Power domains controller node that provides the power domains
      controlled by the SCU
    $ref: /schemas/power/fsl,scu-pd.yaml

  rtc:
    description:
      RTC controller provided by the SCU
    $ref: /schemas/rtc/fsl,scu-rtc.yaml

  thermal-sensor:
    description:
      Thermal sensor provided by the SCU
    $ref: /schemas/thermal/fsl,scu-thermal.yaml

  watchdog:
    description:
      Watchdog controller provided by the SCU
    $ref: /schemas/watchdog/fsl,scu-wdt.yaml

required:
  - compatible
  - mbox-names
  - mboxes

additionalProperties: false

examples:
  - |
    #include <dt-bindings/firmware/imx/rsrc.h>
    #include <dt-bindings/input/input.h>
    #include <dt-bindings/pinctrl/pads-imx8qxp.h>

    firmware {
        system-controller {
            compatible = "fsl,imx-scu";
            mbox-names = "tx0", "tx1", "tx2", "tx3",
                         "rx0", "rx1", "rx2", "rx3",
                         "gip3";
            mboxes = <&lsio_mu1 0 0 &lsio_mu1 0 1 &lsio_mu1 0 2 &lsio_mu1 0 3
                      &lsio_mu1 1 0 &lsio_mu1 1 1 &lsio_mu1 1 2 &lsio_mu1 1 3
                      &lsio_mu1 3 3>;

            clock-controller {
                compatible = "fsl,imx8qxp-clk", "fsl,scu-clk";
                #clock-cells = <2>;
            };

            pinctrl {
                compatible = "fsl,imx8qxp-iomuxc";

                pinctrl_lpuart0: lpuart0grp {
                    fsl,pins = <
                        IMX8QXP_UART0_RX_ADMA_UART0_RX   0x06000020
                        IMX8QXP_UART0_TX_ADMA_UART0_TX   0x06000020
                    >;
                };
            };

            ocotp {
                compatible = "fsl,imx8qxp-scu-ocotp";
                #address-cells = <1>;
                #size-cells = <1>;

                fec_mac0: mac@2c4 {
                    reg = <0x2c4 6>;
                };
            };

            power-controller {
                compatible = "fsl,imx8qxp-scu-pd", "fsl,scu-pd";
                #power-domain-cells = <1>;
            };

            rtc {
                compatible = "fsl,imx8qxp-sc-rtc";
            };

            keys {
                compatible = "fsl,imx8qxp-sc-key", "fsl,imx-sc-key";
                linux,keycodes = <KEY_POWER>;
            };

            watchdog {
                compatible = "fsl,imx8qxp-sc-wdt", "fsl,imx-sc-wdt";
                timeout-sec = <60>;
            };

            thermal-sensor {
                compatible = "fsl,imx8qxp-sc-thermal", "fsl,imx-sc-thermal";
                #thermal-sensor-cells = <1>;
            };
        };
    };


code:
# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
# Copyright 2019 Linaro Ltd.
%YAML 1.2
---
$id: "http://devicetree.org/schemas/firmware/intel,ixp4xx-network-processing-engine.yaml#"
$schema: "http://devicetree.org/meta-schemas/core.yaml#"

title: Intel IXP4xx Network Processing Engine

maintainers:
  - Linus Walleij <linus.walleij@linaro.org>

description: |
  On the IXP4xx SoCs, the Network Processing Engine (NPE) is a small
  processor that can load a firmware to perform offloading of networking
  and crypto tasks. It also manages the MDIO bus to the ethernet PHYs
  on the IXP4xx platform. All IXP4xx platforms have three NPEs at
  consecutive memory locations. They are all included in the same
  device node since they are not independent of each other.

properties:
  compatible:
    oneOf:
      - items:
          - const: intel,ixp4xx-network-processing-engine

  reg:
    items:
      - description: NPE0 (NPE-A) register range
      - description: NPE1 (NPE-B) register range
      - description: NPE2 (NPE-C) register range

  crypto:
    $ref: /schemas/crypto/intel,ixp4xx-crypto.yaml#
    type: object
    description: Optional node for the embedded crypto engine, the node
      should be named with the instance number of the NPE engine used for
      the crypto engine.

  "#address-cells":
    const: 1

  "#size-cells":
    const: 0

patternProperties:
  hss@[0-9]+$:
    $ref: /schemas/net/intel,ixp4xx-hss.yaml#
    type: object
    description: Optional node for the High Speed Serial link (HSS), the
      node should be named with the instance number of the NPE engine
      used for the HSS.

required:
  - compatible
  - reg

additionalProperties: false

examples:
  - |
    #include <dt-bindings/gpio/gpio.h>

    npe: npe@c8006000 {
         compatible = "intel,ixp4xx-network-processing-engine";
         reg = <0xc8006000 0x1000>, <0xc8007000 0x1000>, <0xc8008000 0x1000>;
         #address-cells = <1>;
         #size-cells = <0>;

         hss@0 {
             compatible = "intel,ixp4xx-hss";
             reg = <0>;
             intel,npe-handle = <&npe 0>;
             intel,queue-chl-rxtrig = <&qmgr 12>;
             intel,queue-chl-txready = <&qmgr 34>;
             intel,queue-pkt-rx = <&qmgr 13>;
             intel,queue-pkt-tx = <&qmgr 14>, <&qmgr 15>, <&qmgr 16>, <&qmgr 17>;
             intel,queue-pkt-rxfree = <&qmgr 18>, <&qmgr 19>, <&qmgr 20>, <&qmgr 21>;
             intel,queue-pkt-txdone = <&qmgr 22>;
             cts-gpios = <&gpio0 10 GPIO_ACTIVE_LOW>;
             rts-gpios = <&gpio0 14 GPIO_ACTIVE_LOW>;
             dcd-gpios = <&gpio0 6 GPIO_ACTIVE_LOW>;
             dtr-gpios = <&gpio_74 2 GPIO_ACTIVE_LOW>;
             clk-internal-gpios = <&gpio_74 0 GPIO_ACTIVE_HIGH>;
         };

         crypto {
             compatible = "intel,ixp4xx-crypto";
             intel,npe-handle = <&npe 2>;
             queue-rx = <&qmgr 30>;
             queue-txready = <&qmgr 29>;
         };
    };
...


code:
Intel Service Layer Driver for Stratix10 SoC
============================================
Intel Stratix10 SoC is composed of a 64 bit quad-core ARM Cortex A53 hard
processor system (HPS) and Secure Device Manager (SDM). When the FPGA is
configured from HPS, there needs to be a way for HPS to notify SDM the
location and size of the configuration data. Then SDM will get the
configuration data from that location and perform the FPGA configuration.

To meet the whole system security needs and support virtual machine requesting
communication with SDM, only the secure world of software (EL3, Exception
Layer 3) can interface with SDM. All software entities running on other
exception layers must channel through the EL3 software whenever it needs
service from SDM.

Intel Stratix10 service layer driver, running at privileged exception level
(EL1, Exception Layer 1), interfaces with the service providers and provides
the services for FPGA configuration, QSPI, Crypto and warm reset. Service layer
driver also manages secure monitor call (SMC) to communicate with secure monitor
code running in EL3.

Required properties:
-------------------
The svc node has the following mandatory properties, must be located under
the firmware node.

- compatible: "intel,stratix10-svc" or "intel,agilex-svc"
- method: smc or hvc
        smc - Secure Monitor Call
        hvc - Hypervisor Call
- memory-region:
	phandle to the reserved memory node. See
	Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt
	for details

Example:
-------

	reserved-memory {
                #address-cells = <2>;
                #size-cells = <2>;
                ranges;

                service_reserved: svcbuffer@0 {
                        compatible = "shared-dma-pool";
                        reg = <0x0 0x0 0x0 0x1000000>;
                        alignment = <0x1000>;
                        no-map;
                };
        };

	firmware {
		svc {
			compatible = "intel,stratix10-svc";
			method = "smc";
			memory-region = <&service_reserved>;
		};
	};


code:
* Amlogic Secure Monitor

In the Amlogic SoCs the Secure Monitor code is used to provide access to the
NVMEM, enable JTAG, set USB boot, etc...

Required properties for the secure monitor node:
- compatible: Should be "amlogic,meson-gxbb-sm"

Example:

	firmware {
		sm: secure-monitor {
			compatible = "amlogic,meson-gxbb-sm";
		};
	};


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

title: NVIDIA Tegra Boot and Power Management Processor (BPMP)

maintainers:
  - Thierry Reding <thierry.reding@gmail.com>
  - Jon Hunter <jonathanh@nvidia.com>

description: |
  The BPMP is a specific processor in Tegra chip, which is designed for
  booting process handling and offloading the power management, clock
  management, and reset control tasks from the CPU. The binding document
  defines the resources that would be used by the BPMP firmware driver,
  which can create the interprocessor communication (IPC) between the
  CPU and BPMP.

  This node is a mailbox consumer. See the following files for details
  of the mailbox subsystem, and the specifiers implemented by the
  relevant provider(s):

    - .../mailbox/mailbox.txt
    - .../mailbox/nvidia,tegra186-hsp.yaml

  This node is a clock, power domain, and reset provider. See the
  following files for general documentation of those features, and the
  specifiers implemented by this node:

    - .../clock/clock-bindings.txt
    - <dt-bindings/clock/tegra186-clock.h>
    - ../power/power-domain.yaml
    - <dt-bindings/power/tegra186-powergate.h>
    - .../reset/reset.txt
    - <dt-bindings/reset/tegra186-reset.h>

  The BPMP implements some services which must be represented by
  separate nodes. For example, it can provide access to certain I2C
  controllers, and the I2C bindings represent each I2C controller as a
  device tree node. Such nodes should be nested directly inside the main
  BPMP node.

  Software can determine whether a child node of the BPMP node
  represents a device by checking for a compatible property. Any node
  with a compatible property represents a device that can be
  instantiated. Nodes without a compatible property may be used to
  provide configuration information regarding the BPMP itself, although
  no such configuration nodes are currently defined by this binding.

  The BPMP firmware defines no single global name-/numbering-space for
  such services. Put another way, the numbering scheme for I2C buses is
  distinct from the numbering scheme for any other service the BPMP may
  provide (e.g. a future hypothetical SPI bus service). As such, child
  device nodes will have no reg property, and the BPMP node will have no
  "#address-cells" or "#size-cells" property.

  The shared memory area for the IPC TX and RX between CPU and BPMP are
  predefined and work on top of sysram, which is an SRAM inside the
  chip. See ".../sram/sram.yaml" for the bindings.

properties:
  compatible:
    oneOf:
      - items:
          - enum:
              - nvidia,tegra194-bpmp
              - nvidia,tegra234-bpmp
          - const: nvidia,tegra186-bpmp
      - const: nvidia,tegra186-bpmp

  mboxes:
    description: A phandle and channel specifier for the mailbox used to
      communicate with the BPMP.
    maxItems: 1

  shmem:
    description: List of the phandle to the TX and RX shared memory area
      that the IPC between CPU and BPMP is based on.
    minItems: 2
    maxItems: 2

  "#clock-cells":
    const: 1

  "#power-domain-cells":
    const: 1

  "#reset-cells":
    const: 1

  interconnects:
    items:
      - description: memory read client
      - description: memory write client
      - description: DMA read client
      - description: DMA write client

  interconnect-names:
    items:
      - const: read
      - const: write
      - const: dma-mem # dma-read
      - const: dma-write

  iommus:
    maxItems: 1

  i2c:
    type: object

  thermal:
    type: object

additionalProperties: false

required:
  - compatible
  - mboxes
  - shmem
  - "#clock-cells"
  - "#power-domain-cells"
  - "#reset-cells"

examples:
  - |
    #include <dt-bindings/interrupt-controller/arm-gic.h>
    #include <dt-bindings/mailbox/tegra186-hsp.h>
    #include <dt-bindings/memory/tegra186-mc.h>

    hsp_top0: hsp@3c00000 {
        compatible = "nvidia,tegra186-hsp";
        reg = <0x03c00000 0xa0000>;
        interrupts = <GIC_SPI 176 IRQ_TYPE_LEVEL_HIGH>;
        interrupt-names = "doorbell";
        #mbox-cells = <2>;
    };

    sram@30000000 {
        compatible = "nvidia,tegra186-sysram", "mmio-sram";
        reg = <0x30000000 0x50000>;
        #address-cells = <1>;
        #size-cells = <1>;
        ranges = <0x0 0x30000000 0x50000>;

        cpu_bpmp_tx: sram@4e000 {
            reg = <0x4e000 0x1000>;
            label = "cpu-bpmp-tx";
            pool;
        };

        cpu_bpmp_rx: sram@4f000 {
            reg = <0x4f000 0x1000>;
            label = "cpu-bpmp-rx";
            pool;
        };
    };

    bpmp {
        compatible = "nvidia,tegra186-bpmp";
        interconnects = <&mc TEGRA186_MEMORY_CLIENT_BPMPR &emc>,
                        <&mc TEGRA186_MEMORY_CLIENT_BPMPW &emc>,
                        <&mc TEGRA186_MEMORY_CLIENT_BPMPDMAR &emc>,
                        <&mc TEGRA186_MEMORY_CLIENT_BPMPDMAW &emc>;
        interconnect-names = "read", "write", "dma-mem", "dma-write";
        iommus = <&smmu TEGRA186_SID_BPMP>;
        mboxes = <&hsp_top0 TEGRA_HSP_MBOX_TYPE_DB
                            TEGRA_HSP_DB_MASTER_BPMP>;
        shmem = <&cpu_bpmp_tx>, <&cpu_bpmp_rx>;
        #clock-cells = <1>;
        #power-domain-cells = <1>;
        #reset-cells = <1>;

        i2c {
            compatible = "nvidia,tegra186-bpmp-i2c";
            nvidia,bpmp-bus-id = <5>;
            #address-cells = <1>;
            #size-cells = <0>;
        };

        thermal {
            compatible = "nvidia,tegra186-bpmp-thermal";
            #thermal-sensor-cells = <1>;
        };
    };


code:
NVIDIA Tegra210 Boot and Power Management Processor (BPMP)

The Boot and Power Management Processor (BPMP) is a co-processor found
in Tegra210 SoC. It is designed to handle the early stages of the boot
process as well as to assisting in entering deep low power state
(suspend to ram), and also offloading DRAM memory clock scaling on
some platforms. The binding document defines the resources that would
be used by the BPMP T210 firmware driver, which can create the
interprocessor communication (IPC) between the CPU and BPMP.

Required properties:
- compatible
    Array of strings
    One of:
    - "nvidia,tegra210-bpmp"
- reg: physical base address and length for HW synchornization primitives
       1) base address and length to Tegra 'atomics' hardware
       2) base address and length to Tegra 'semaphore' hardware
- interrupts: specifies the interrupt number for receiving messages ("rx")
              and for triggering messages ("tx")

Optional properties:
- #clock-cells : Should be 1 for platforms where DRAM clock control is
                 offloaded to bpmp.

Example:

bpmp@70016000 {
	compatible = "nvidia,tegra210-bpmp";
	reg = <0x0 0x70016000 0x0 0x2000
	       0x0 0x60001000 0x0 0x1000>;
	interrupts = <GIC_SPI 6 IRQ_TYPE_EDGE_RISING>,
		     <GIC_SPI 4 IRQ_TYPE_EDGE_RISING>;
	interrupt-names = "tx", "rx";
};


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

title: QCOM Secure Channel Manager (SCM)

description: |
  Qualcomm processors include an interface to communicate to the secure firmware.
  This interface allows for clients to request different types of actions.
  These can include CPU power up/down, HDCP requests, loading of firmware,
  and other assorted actions.

maintainers:
  - Bjorn Andersson <bjorn.andersson@linaro.org>
  - Robert Marko <robimarko@gmail.com>
  - Guru Das Srinagesh <quic_gurus@quicinc.com>

properties:
  compatible:
    items:
      - enum:
          - qcom,scm-apq8064
          - qcom,scm-apq8084
          - qcom,scm-ipq4019
          - qcom,scm-ipq6018
          - qcom,scm-ipq806x
          - qcom,scm-ipq8074
          - qcom,scm-mdm9607
          - qcom,scm-msm8226
          - qcom,scm-msm8660
          - qcom,scm-msm8916
          - qcom,scm-msm8953
          - qcom,scm-msm8960
          - qcom,scm-msm8974
          - qcom,scm-msm8976
          - qcom,scm-msm8994
          - qcom,scm-msm8996
          - qcom,scm-msm8998
          - qcom,scm-sc7180
          - qcom,scm-sc7280
          - qcom,scm-sc8280xp
          - qcom,scm-sdm670
          - qcom,scm-sdm845
          - qcom,scm-sdx55
          - qcom,scm-sdx65
          - qcom,scm-sm6115
          - qcom,scm-sm6125
          - qcom,scm-sm6350
          - qcom,scm-sm6375
          - qcom,scm-sm8150
          - qcom,scm-sm8250
          - qcom,scm-sm8350
          - qcom,scm-sm8450
          - qcom,scm-qcs404
      - const: qcom,scm

  clocks:
    minItems: 1
    maxItems: 3

  clock-names:
    minItems: 1
    maxItems: 3

  interconnects:
    maxItems: 1

  interconnect-names:
    maxItems: 1

  '#reset-cells':
    const: 1

  qcom,dload-mode:
    $ref: /schemas/types.yaml#/definitions/phandle-array
    items:
      - items:
          - description: phandle to TCSR hardware block
          - description: offset of the download mode control register
    description: TCSR hardware block

allOf:
  - if:
      properties:
        compatible:
          contains:
            enum:
              - qcom,scm-apq8064
              - qcom,scm-msm8660
              - qcom,scm-msm8960
              - qcom,scm-sm6375
    then:
      properties:
        clock-names:
          items:
            - const: core

        clocks:
          maxItems: 1

      required:
        - clocks
        - clock-names

  - if:
      properties:
        compatible:
          contains:
            enum:
              - qcom,scm-apq8084
              - qcom,scm-mdm9607
              - qcom,scm-msm8916
              - qcom,scm-msm8953
              - qcom,scm-msm8974
              - qcom,scm-msm8976
    then:
      properties:
        clock-names:
          items:
            - const: core
            - const: bus
            - const: iface

        clocks:
          minItems: 3
          maxItems: 3

      required:
        - clocks
        - clock-names

required:
  - compatible

additionalProperties: false

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

    firmware {
        scm {
            compatible = "qcom,scm-msm8916", "qcom,scm";
            clocks = <&gcc GCC_CRYPTO_CLK>,
                     <&gcc GCC_CRYPTO_AXI_CLK>,
                     <&gcc GCC_CRYPTO_AHB_CLK>;
            clock-names = "core", "bus", "iface";
        };
    };


code:
# SPDX-License-Identifier: GPL-2.0
%YAML 1.2
---
$id: http://devicetree.org/schemas/firmware/qemu,fw-cfg-mmio.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: QEMU Firmware Configuration bindings

maintainers:
  - Rob Herring <robh@kernel.org>

description: |
  Various QEMU emulation / virtualization targets provide the following
  Firmware Configuration interface on the "virt" machine type:

  - A write-only, 16-bit wide selector (or control) register,
  - a read-write, 64-bit wide data register.

  QEMU exposes the control and data register to guests as memory mapped
  registers; their location is communicated to the guest's UEFI firmware in the
  DTB that QEMU places at the bottom of the guest's DRAM.

  The authoritative guest-side hardware interface documentation to the fw_cfg
  device can be found in "docs/specs/fw_cfg.txt" in the QEMU source tree.

properties:
  compatible:
    const: qemu,fw-cfg-mmio

  reg:
    maxItems: 1
    description: |
      * Bytes 0x0 to 0x7 cover the data register.
      * Bytes 0x8 to 0x9 cover the selector register.
      * Further registers may be appended to the region in case of future interface
        revisions / feature bits.

  dma-coherent: true

required:
  - compatible
  - reg

additionalProperties: false

examples:
  - |

    fw-cfg@9020000 {
        compatible = "qemu,fw-cfg-mmio";
        reg = <0x9020000 0xa>;
    };
...


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

title: Xilinx firmware driver

maintainers:
  - Nava kishore Manne <nava.manne@xilinx.com>

description: The zynqmp-firmware node describes the interface to platform
  firmware. ZynqMP has an interface to communicate with secure firmware.
  Firmware driver provides an interface to firmware APIs. Interface APIs
  can be used by any driver to communicate to PMUFW(Platform Management Unit).
  These requests include clock management, pin control, device control,
  power management service, FPGA service and other platform management
  services.

properties:
  compatible:
    oneOf:
      - description: For implementations complying for Zynq Ultrascale+ MPSoC.
        const: xlnx,zynqmp-firmware

      - description: For implementations complying for Versal.
        const: xlnx,versal-firmware

  method:
    description: |
                 The method of calling the PM-API firmware layer.
                 Permitted values are.
                 - "smc" : SMC #0, following the SMCCC
                 - "hvc" : HVC #0, following the SMCCC

    $ref: /schemas/types.yaml#/definitions/string-array
    enum:
      - smc
      - hvc

  versal_fpga:
    $ref: /schemas/fpga/xlnx,versal-fpga.yaml#
    description: Compatible of the FPGA device.
    type: object

  zynqmp-aes:
    $ref: /schemas/crypto/xlnx,zynqmp-aes.yaml#
    description: The ZynqMP AES-GCM hardened cryptographic accelerator is
      used to encrypt or decrypt the data with provided key and initialization
      vector.
    type: object

  clock-controller:
    $ref: /schemas/clock/xlnx,versal-clk.yaml#
    description: The clock controller is a hardware block of Xilinx versal
      clock tree. It reads required input clock frequencies from the devicetree
      and acts as clock provider for all clock consumers of PS clocks.list of
      clock specifiers which are external input clocks to the given clock
      controller.
    type: object

required:
  - compatible

additionalProperties: false

examples:
  - |
    versal-firmware {
      compatible = "xlnx,versal-firmware";
      method = "smc";

      versal_fpga: versal_fpga {
        compatible = "xlnx,versal-fpga";
      };

      xlnx_aes: zynqmp-aes {
        compatible = "xlnx,zynqmp-aes";
      };

      versal_clk: clock-controller {
        #clock-cells = <1>;
        compatible = "xlnx,versal-clk";
        clocks = <&ref>, <&alt_ref>, <&pl_alt_ref>;
        clock-names = "ref", "alt_ref", "pl_alt_ref";
      };
    };

...


code:
Altera FPGA To SDRAM Bridge Driver

Required properties:
- compatible		: Should contain "altr,socfpga-fpga2sdram-bridge"

See Documentation/devicetree/bindings/fpga/fpga-bridge.txt for generic bindings.

Example:
	fpga_bridge3: fpga-bridge@ffc25080 {
		compatible = "altr,socfpga-fpga2sdram-bridge";
		reg = <0xffc25080 0x4>;
		bridge-enable = <0>;
	};


code:
Altera Freeze Bridge Controller Driver

The Altera Freeze Bridge Controller manages one or more freeze bridges.
The controller can freeze/disable the bridges which prevents signal
changes from passing through the bridge.  The controller can also
unfreeze/enable the bridges which allows traffic to pass through the
bridge normally.

Required properties:
- compatible		: Should contain "altr,freeze-bridge-controller"
- regs			: base address and size for freeze bridge module

See Documentation/devicetree/bindings/fpga/fpga-bridge.txt for generic bindings.

Example:
	freeze-controller@100000450 {
		compatible = "altr,freeze-bridge-controller";
		regs = <0x1000 0x10>;
		bridge-enable = <0>;
	};


code:
Altera FPGA/HPS Bridge Driver

Required properties:
- regs		: base address and size for AXI bridge module
- compatible	: Should contain one of:
		  "altr,socfpga-lwhps2fpga-bridge",
		  "altr,socfpga-hps2fpga-bridge", or
		  "altr,socfpga-fpga2hps-bridge"
- resets	: Phandle and reset specifier for this bridge's reset
- clocks	: Clocks used by this module.

See Documentation/devicetree/bindings/fpga/fpga-bridge.txt for generic bindings.

Example:
	fpga_bridge0: fpga-bridge@ff400000 {
		compatible = "altr,socfpga-lwhps2fpga-bridge";
		reg = <0xff400000 0x100000>;
		resets = <&rst LWHPS2FPGA_RESET>;
		clocks = <&l4_main_clk>;
		bridge-enable = <0>;
	};

	fpga_bridge1: fpga-bridge@ff500000 {
		compatible = "altr,socfpga-hps2fpga-bridge";
		reg = <0xff500000 0x10000>;
		resets = <&rst HPS2FPGA_RESET>;
		clocks = <&l4_main_clk>;
		bridge-enable = <1>;
	};

	fpga_bridge2: fpga-bridge@ff600000 {
		compatible = "altr,socfpga-fpga2hps-bridge";
		reg = <0xff600000 0x100000>;
		resets = <&rst FPGA2HPS_RESET>;
		clocks = <&l4_main_clk>;
	};


code:
Altera Passive Serial SPI FPGA Manager

Altera FPGAs support a method of loading the bitstream over what is
referred to as "passive serial".
The passive serial link is not technically SPI, and might require extra
circuits in order to play nicely with other SPI slaves on the same bus.

See https://www.altera.com/literature/hb/cyc/cyc_c51013.pdf

Required properties:
- compatible: Must be one of the following:
	"altr,fpga-passive-serial",
	"altr,fpga-arria10-passive-serial"
- reg: SPI chip select of the FPGA
- nconfig-gpios: config pin (referred to as nCONFIG in the manual)
- nstat-gpios: status pin (referred to as nSTATUS in the manual)

Optional properties:
- confd-gpios: confd pin (referred to as CONF_DONE in the manual)

Example:
	fpga: fpga@0 {
		compatible = "altr,fpga-passive-serial";
		spi-max-frequency = <20000000>;
		reg = <0>;
		nconfig-gpios = <&gpio4 9 GPIO_ACTIVE_LOW>;
		nstat-gpios = <&gpio4 11 GPIO_ACTIVE_LOW>;
		confd-gpios = <&gpio4 12 GPIO_ACTIVE_LOW>;
	};


code:
Altera Arria10 Partial Reconfiguration IP

Required properties:
- compatible : should contain "altr,a10-pr-ip"
- reg        : base address and size for memory mapped io.

Example:

	fpga_mgr: fpga-mgr@ff20c000 {
		compatible = "altr,a10-pr-ip";
		reg = <0xff20c000 0x10>;
	};


code:
Altera SOCFPGA Arria10 FPGA Manager

Required properties:
- compatible : should contain "altr,socfpga-a10-fpga-mgr"
- reg        : base address and size for memory mapped io.
               - The first index is for FPGA manager register access.
               - The second index is for writing FPGA configuration data.
- resets     : Phandle and reset specifier for the device's reset.
- clocks     : Clocks used by the device.

Example:

	fpga_mgr: fpga-mgr@ffd03000 {
		compatible = "altr,socfpga-a10-fpga-mgr";
		reg = <0xffd03000 0x100
		       0xffcfe400 0x20>;
		clocks = <&l4_mp_clk>;
		resets = <&rst FPGAMGR_RESET>;
	};


code:
Altera SOCFPGA FPGA Manager

Required properties:
- compatible : should contain "altr,socfpga-fpga-mgr"
- reg        : base address and size for memory mapped io.
               - The first index is for FPGA manager register access.
               - The second index is for writing FPGA configuration data.
- interrupts : interrupt for the FPGA Manager device.

Example:

	hps_0_fpgamgr: fpgamgr@ff706000 {
		compatible = "altr,socfpga-fpga-mgr";
		reg = <0xFF706000 0x1000
		       0xFFB90000 0x1000>;
		interrupts = <0 175 4>;
	};


code:
FPGA Bridge Device Tree Binding

Optional properties:
- bridge-enable		: 0 if driver should disable bridge at startup
			  1 if driver should enable bridge at startup
			  Default is to leave bridge in current state.

Example:
	fpga_bridge3: fpga-bridge@ffc25080 {
		compatible = "altr,socfpga-fpga2sdram-bridge";
		reg = <0xffc25080 0x4>;
		bridge-enable = <0>;
	};


code:
FPGA Region Device Tree Binding

Alan Tull 2016

 CONTENTS
 - Introduction
 - Terminology
 - Sequence
 - FPGA Region
 - Supported Use Models
 - Device Tree Examples
 - Constraints

Introduction
============

FPGA Regions represent FPGA's and partial reconfiguration regions of FPGA's in
the Device Tree.  FPGA Regions provide a way to program FPGAs under device tree
control.

This device tree binding document hits some of the high points of FPGA usage and
attempts to include terminology used by both major FPGA manufacturers.  This
document isn't a replacement for any manufacturers specifications for FPGA
usage.

Terminology
===========

Full Reconfiguration
 * The entire FPGA is programmed.

Partial Reconfiguration (PR)
 * A section of an FPGA is reprogrammed while the rest of the FPGA is not
   affected.
 * Not all FPGA's support PR.

Partial Reconfiguration Region (PRR)
 * Also called a "reconfigurable partition"
 * A PRR is a specific section of an FPGA reserved for reconfiguration.
 * A base (or static) FPGA image may create a set of PRR's that later may
   be independently reprogrammed many times.
 * The size and specific location of each PRR is fixed.
 * The connections at the edge of each PRR are fixed.  The image that is loaded
   into a PRR must fit and must use a subset of the region's connections.
 * The busses within the FPGA are split such that each region gets its own
   branch that may be gated independently.

Persona
 * Also called a "partial bit stream"
 * An FPGA image that is designed to be loaded into a PRR.  There may be
   any number of personas designed to fit into a PRR, but only one at at time
   may be loaded.
 * A persona may create more regions.

FPGA Bridge
 * FPGA Bridges gate bus signals between a host and FPGA.
 * FPGA Bridges should be disabled while the FPGA is being programmed to
   prevent spurious signals on the cpu bus and to the soft logic.
 * FPGA bridges may be actual hardware or soft logic on an FPGA.
 * During Full Reconfiguration, hardware bridges between the host and FPGA
   will be disabled.
 * During Partial Reconfiguration of a specific region, that region's bridge
   will be used to gate the busses.  Traffic to other regions is not affected.
 * In some implementations, the FPGA Manager transparantly handles gating the
   buses, eliminating the need to show the hardware FPGA bridges in the
   device tree.
 * An FPGA image may create a set of reprogrammable regions, each having its
   own bridge and its own split of the busses in the FPGA.

FPGA Manager
 * An FPGA Manager is a hardware block that programs an FPGA under the control
   of a host processor.

Base Image
 * Also called the "static image"
 * An FPGA image that is designed to do full reconfiguration of the FPGA.
 * A base image may set up a set of partial reconfiguration regions that may
   later be reprogrammed.

    ----------------       ----------------------------------
    |  Host CPU    |       |             FPGA               |
    |              |       |                                |
    |          ----|       |       -----------    --------  |
    |          | H |       |   |==>| Bridge0 |<==>| PRR0 |  |
    |          | W |       |   |   -----------    --------  |
    |          |   |       |   |                            |
    |          | B |<=====>|<==|   -----------    --------  |
    |          | R |       |   |==>| Bridge1 |<==>| PRR1 |  |
    |          | I |       |   |   -----------    --------  |
    |          | D |       |   |                            |
    |          | G |       |   |   -----------    --------  |
    |          | E |       |   |==>| Bridge2 |<==>| PRR2 |  |
    |          ----|       |       -----------    --------  |
    |              |       |                                |
    ----------------       ----------------------------------

Figure 1: An FPGA set up with a base image that created three regions.  Each
region (PRR0-2) gets its own split of the busses that is independently gated by
a soft logic bridge (Bridge0-2) in the FPGA.  The contents of each PRR can be
reprogrammed independently while the rest of the system continues to function.

Sequence
========

When a DT overlay that targets an FPGA Region is applied, the FPGA Region will
do the following:

 1. Disable appropriate FPGA bridges.
 2. Program the FPGA using the FPGA manager.
 3. Enable the FPGA bridges.
 4. The Device Tree overlay is accepted into the live tree.
 5. Child devices are populated.

When the overlay is removed, the child nodes will be removed and the FPGA Region
will disable the bridges.

FPGA Region
===========

FPGA Regions represent FPGA's and FPGA PR regions in the device tree.  An FPGA
Region brings together the elements needed to program on a running system and
add the child devices:

 * FPGA Manager
 * FPGA Bridges
 * image-specific information needed to to the programming.
 * child nodes

The intended use is that a Device Tree overlay (DTO) can be used to reprogram an
FPGA while an operating system is running.

An FPGA Region that exists in the live Device Tree reflects the current state.
If the live tree shows a "firmware-name" property or child nodes under an FPGA
Region, the FPGA already has been programmed.  A DTO that targets an FPGA Region
and adds the "firmware-name" property is taken as a request to reprogram the
FPGA.  After reprogramming is successful, the overlay is accepted into the live
tree.

The base FPGA Region in the device tree represents the FPGA and supports full
reconfiguration.  It must include a phandle to an FPGA Manager.  The base
FPGA region will be the child of one of the hardware bridges (the bridge that
allows register access) between the cpu and the FPGA.  If there are more than
one bridge to control during FPGA programming, the region will also contain a
list of phandles to the additional hardware FPGA Bridges.

For partial reconfiguration (PR), each PR region will have an FPGA Region.
These FPGA regions are children of FPGA bridges which are then children of the
base FPGA region.  The "Full Reconfiguration to add PRR's" example below shows
this.

If an FPGA Region does not specify an FPGA Manager, it will inherit the FPGA
Manager specified by its ancestor FPGA Region.  This supports both the case
where the same FPGA Manager is used for all of an FPGA as well the case where
a different FPGA Manager is used for each region.

FPGA Regions do not inherit their ancestor FPGA regions' bridges.  This prevents
shutting down bridges that are upstream from the other active regions while one
region is getting reconfigured (see Figure 1 above).  During PR, the FPGA's
hardware bridges remain enabled.  The PR regions' bridges will be FPGA bridges
within the static image of the FPGA.

Required properties:
- compatible : should contain "fpga-region"
- fpga-mgr : should contain a phandle to an FPGA Manager.  Child FPGA Regions
	inherit this property from their ancestor regions.  An fpga-mgr property
	in a region will override any inherited FPGA manager.
- #address-cells, #size-cells, ranges : must be present to handle address space
	mapping for child nodes.

Optional properties:
- firmware-name : should contain the name of an FPGA image file located on the
	firmware search path.  If this property shows up in a live device tree
	it indicates that the FPGA has already been programmed with this image.
	If this property is in an overlay targeting an FPGA region, it is a
	request to program the FPGA with that image.
- fpga-bridges : should contain a list of phandles to FPGA Bridges that must be
	controlled during FPGA programming along with the parent FPGA bridge.
	This property is optional if the FPGA Manager handles the bridges.
        If the fpga-region is  the child of an fpga-bridge, the list should not
        contain the parent bridge.
- partial-fpga-config : boolean, set if partial reconfiguration is to be done,
	otherwise full reconfiguration is done.
- external-fpga-config : boolean, set if the FPGA has already been configured
	prior to OS boot up.
- encrypted-fpga-config : boolean, set if the bitstream is encrypted
- region-unfreeze-timeout-us : The maximum time in microseconds to wait for
	bridges to successfully become enabled after the region has been
	programmed.
- region-freeze-timeout-us : The maximum time in microseconds to wait for
	bridges to successfully become disabled before the region has been
	programmed.
- config-complete-timeout-us : The maximum time in microseconds time for the
	FPGA to go to operating mode after the region has been programmed.
- child nodes : devices in the FPGA after programming.

In the example below, when an overlay is applied targeting fpga-region0,
fpga_mgr is used to program the FPGA.  Two bridges are controlled during
programming: the parent fpga_bridge0 and fpga_bridge1.  Because the region is
the child of fpga_bridge0, only fpga_bridge1 needs to be specified in the
fpga-bridges property.  During programming, these bridges are disabled, the
firmware specified in the overlay is loaded to the FPGA using the FPGA manager
specified in the region.  If FPGA programming succeeds, the bridges are
reenabled and the overlay makes it into the live device tree.  The child devices
are then populated.  If FPGA programming fails, the bridges are left disabled
and the overlay is rejected.  The overlay's ranges property maps the lwhps
bridge's region (0xff200000) and the hps bridge's region (0xc0000000) for use by
the two child devices.

Example:
Base tree contains:

	fpga_mgr: fpga-mgr@ff706000 {
		compatible = "altr,socfpga-fpga-mgr";
		reg = <0xff706000 0x1000
		       0xffb90000 0x20>;
		interrupts = <0 175 4>;
	};

	fpga_bridge0: fpga-bridge@ff400000 {
		compatible = "altr,socfpga-lwhps2fpga-bridge";
		reg = <0xff400000 0x100000>;
		resets = <&rst LWHPS2FPGA_RESET>;
		clocks = <&l4_main_clk>;

		#address-cells = <1>;
		#size-cells = <1>;
		ranges;

		fpga_region0: fpga-region0 {
			compatible = "fpga-region";
			fpga-mgr = <&fpga_mgr>;
		};
	};

	fpga_bridge1: fpga-bridge@ff500000 {
		compatible = "altr,socfpga-hps2fpga-bridge";
		reg = <0xff500000 0x10000>;
		resets = <&rst HPS2FPGA_RESET>;
		clocks = <&l4_main_clk>;
	};

Overlay contains:

/dts-v1/;
/plugin/;

&fpga_region0 {
	#address-cells = <1>;
	#size-cells = <1>;

	firmware-name = "soc_system.rbf";
	fpga-bridges = <&fpga_bridge1>;
	ranges = <0x20000 0xff200000 0x100000>,
		 <0x0 0xc0000000 0x20000000>;

	gpio@10040 {
		compatible = "altr,pio-1.0";
		reg = <0x10040 0x20>;
		altr,ngpio = <4>;
		#gpio-cells = <2>;
		clocks = <2>;
		gpio-controller;
	};

	onchip-memory {
		device_type = "memory";
		compatible = "altr,onchipmem-15.1";
		reg = <0x0 0x10000>;
	};
};

Supported Use Models
====================

In all cases the live DT must have the FPGA Manager, FPGA Bridges (if any), and
a FPGA Region.  The target of the Device Tree Overlay is the FPGA Region.  Some
uses are specific to an FPGA device.

 * No FPGA Bridges
   In this case, the FPGA Manager which programs the FPGA also handles the
   bridges behind the scenes.  No FPGA Bridge devices are needed for full
   reconfiguration.

 * Full reconfiguration with hardware bridges
   In this case, there are hardware bridges between the processor and FPGA that
   need to be controlled during full reconfiguration.  Before the overlay is
   applied, the live DT must include the FPGA Manager, FPGA Bridges, and a
   FPGA Region.  The FPGA Region is the child of the bridge that allows
   register access to the FPGA.  Additional bridges may be listed in a
   fpga-bridges property in the FPGA region or in the device tree overlay.

 * Partial reconfiguration with bridges in the FPGA
   In this case, the FPGA will have one or more PRR's that may be programmed
   separately while the rest of the FPGA can remain active.  To manage this,
   bridges need to exist in the FPGA that can gate the buses going to each FPGA
   region while the buses are enabled for other sections.  Before any partial
   reconfiguration can be done, a base FPGA image must be loaded which includes
   PRR's with FPGA bridges.  The device tree should have an FPGA region for each
   PRR.

Device Tree Examples
====================

The intention of this section is to give some simple examples, focusing on
the placement of the elements detailed above, especially:
 * FPGA Manager
 * FPGA Bridges
 * FPGA Region
 * ranges
 * target-path or target

For the purposes of this section, I'm dividing the Device Tree into two parts,
each with its own requirements.  The two parts are:
 * The live DT prior to the overlay being added
 * The DT overlay

The live Device Tree must contain an FPGA Region, an FPGA Manager, and any FPGA
Bridges.  The FPGA Region's "fpga-mgr" property specifies the manager by phandle
to handle programming the FPGA.  If the FPGA Region is the child of another FPGA
Region, the parent's FPGA Manager is used.  If FPGA Bridges need to be involved,
they are specified in the FPGA Region by the "fpga-bridges" property.  During
FPGA programming, the FPGA Region will disable the bridges that are in its
"fpga-bridges" list and will re-enable them after FPGA programming has
succeeded.

The Device Tree Overlay will contain:
 * "target-path" or "target"
   The insertion point where the contents of the overlay will go into the
   live tree.  target-path is a full path, while target is a phandle.
 * "ranges"
    The address space mapping from processor to FPGA bus(ses).
 * "firmware-name"
   Specifies the name of the FPGA image file on the firmware search
   path.  The search path is described in the firmware class documentation.
 * "partial-fpga-config"
   This binding is a boolean and should be present if partial reconfiguration
   is to be done.
 * child nodes corresponding to hardware that will be loaded in this region of
   the FPGA.

Device Tree Example: Full Reconfiguration without Bridges
=========================================================

Live Device Tree contains:
	fpga_mgr0: fpga-mgr@f8007000 {
		compatible = "xlnx,zynq-devcfg-1.0";
		reg = <0xf8007000 0x100>;
		interrupt-parent = <&intc>;
		interrupts = <0 8 4>;
		clocks = <&clkc 12>;
		clock-names = "ref_clk";
		syscon = <&slcr>;
	};

	fpga_region0: fpga-region0 {
		compatible = "fpga-region";
		fpga-mgr = <&fpga_mgr0>;
		#address-cells = <0x1>;
		#size-cells = <0x1>;
		ranges;
	};

DT Overlay contains:

/dts-v1/;
/plugin/;

&fpga_region0 {
	#address-cells = <1>;
	#size-cells = <1>;

	firmware-name = "zynq-gpio.bin";

	gpio1: gpio@40000000 {
		compatible = "xlnx,xps-gpio-1.00.a";
		reg = <0x40000000 0x10000>;
		gpio-controller;
		#gpio-cells = <0x2>;
		xlnx,gpio-width= <0x6>;
	};
};

Device Tree Example: Full Reconfiguration to add PRR's
======================================================

The base FPGA Region is specified similar to the first example above.

This example programs the FPGA to have two regions that can later be partially
configured.  Each region has its own bridge in the FPGA fabric.

DT Overlay contains:

/dts-v1/;
/plugin/;

&fpga_region0 {
	#address-cells = <1>;
	#size-cells = <1>;

	firmware-name = "base.rbf";

	fpga-bridge@4400 {
		compatible = "altr,freeze-bridge-controller";
		reg = <0x4400 0x10>;

		fpga_region1: fpga-region1 {
			compatible = "fpga-region";
			#address-cells = <0x1>;
			#size-cells = <0x1>;
			ranges;
		};
	};

	fpga-bridge@4420 {
		compatible = "altr,freeze-bridge-controller";
		reg = <0x4420 0x10>;

		fpga_region2: fpga-region2 {
			compatible = "fpga-region";
			#address-cells = <0x1>;
			#size-cells = <0x1>;
			ranges;
		};
	};
};

Device Tree Example: Partial Reconfiguration
============================================

This example reprograms one of the PRR's set up in the previous example.

The sequence that occurs when this overlay is similar to the above, the only
differences are that the FPGA is partially reconfigured due to the
"partial-fpga-config" boolean and the only bridge that is controlled during
programming is the FPGA based bridge of fpga_region1.

/dts-v1/;
/plugin/;

&fpga_region1 {
	#address-cells = <1>;
	#size-cells = <1>;

	firmware-name = "soc_image2.rbf";
	partial-fpga-config;

	gpio@10040 {
		compatible = "altr,pio-1.0";
		reg = <0x10040 0x20>;
		clocks = <0x2>;
		altr,ngpio = <0x4>;
		#gpio-cells = <0x2>;
		gpio-controller;
	};
};

Constraints
===========

It is beyond the scope of this document to fully describe all the FPGA design
constraints required to make partial reconfiguration work[1] [2] [3], but a few
deserve quick mention.

A persona must have boundary connections that line up with those of the partion
or region it is designed to go into.

During programming, transactions through those connections must be stopped and
the connections must be held at a fixed logic level.  This can be achieved by
FPGA Bridges that exist on the FPGA fabric prior to the partial reconfiguration.

--
[1] www.altera.com/content/dam/altera-www/global/en_US/pdfs/literature/ug/ug_partrecon.pdf
[2] tspace.library.utoronto.ca/bitstream/1807/67932/1/Byma_Stuart_A_201411_MAS_thesis.pdf
[3] https://www.xilinx.com/support/documentation/sw_manuals/xilinx14_1/ug702.pdf


code:
Intel Stratix10 SoC FPGA Manager

Required properties:
The fpga_mgr node has the following mandatory property, must be located under
firmware/svc node.

- compatible : should contain "intel,stratix10-soc-fpga-mgr" or
	       "intel,agilex-soc-fpga-mgr"

Example:

	firmware {
		svc {
			fpga_mgr: fpga-mgr {
				compatible = "intel,stratix10-soc-fpga-mgr";
			};
		};
	};


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

title: Lattice Slave SPI sysCONFIG FPGA manager

maintainers:
  - Ivan Bornyakov <i.bornyakov@metrotek.ru>

description: |
  Lattice sysCONFIG port, which is used for FPGA configuration, among others,
  have Slave Serial Peripheral Interface. Only full reconfiguration is
  supported.

  Programming of ECP5 is done by writing uncompressed bitstream image in .bit
  format into FPGA's SRAM configuration memory.

properties:
  compatible:
    enum:
      - lattice,sysconfig-ecp5

  reg:
    maxItems: 1

  program-gpios:
    description:
      A GPIO line connected to PROGRAMN (active low) pin of the device.
      Initiates configuration sequence.
    maxItems: 1

  init-gpios:
    description:
      A GPIO line connected to INITN (active low) pin of the device.
      Indicates that the FPGA is ready to be configured.
    maxItems: 1

  done-gpios:
    description:
      A GPIO line connected to DONE (active high) pin of the device.
      Indicates that the configuration sequence is complete.
    maxItems: 1

required:
  - compatible
  - reg

allOf:
  - $ref: /schemas/spi/spi-peripheral-props.yaml

  - if:
      properties:
        compatible:
          contains:
            const: lattice,sysconfig-ecp5
    then:
      properties:
        spi-max-frequency:
          maximum: 60000000

unevaluatedProperties: false

examples:
  - |
    #include <dt-bindings/gpio/gpio.h>

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

        fpga-mgr@0 {
            compatible = "lattice,sysconfig-ecp5";
            reg = <0>;
            spi-max-frequency = <20000000>;
            program-gpios = <&gpio3 4 GPIO_ACTIVE_LOW>;
            init-gpios = <&gpio3 3 GPIO_ACTIVE_LOW>;
            done-gpios = <&gpio3 2 GPIO_ACTIVE_HIGH>;
        };
    };


code:
Lattice iCE40 FPGA Manager

Required properties:
- compatible:		Should contain "lattice,ice40-fpga-mgr"
- reg:			SPI chip select
- spi-max-frequency:	Maximum SPI frequency (>=1000000, <=25000000)
- cdone-gpios:		GPIO input connected to CDONE pin
- reset-gpios:		Active-low GPIO output connected to CRESET_B pin. Note
			that unless the GPIO is held low during startup, the
			FPGA will enter Master SPI mode and drive SCK with a
			clock signal potentially jamming other devices on the
			bus until the firmware is loaded.

Example:
	fpga: fpga@0 {
		compatible = "lattice,ice40-fpga-mgr";
		reg = <0>;
		spi-max-frequency = <1000000>;
		cdone-gpios = <&gpio 24 GPIO_ACTIVE_HIGH>;
		reset-gpios = <&gpio 22 GPIO_ACTIVE_LOW>;
	};


code:
Lattice MachXO2 Slave SPI FPGA Manager

Lattice MachXO2 FPGAs support a method of loading the bitstream over
'slave SPI' interface.

See 'MachXO2ProgrammingandConfigurationUsageGuide.pdf' on www.latticesemi.com

Required properties:
- compatible: should contain "lattice,machxo2-slave-spi"
- reg: spi chip select of the FPGA

Example for full FPGA configuration:

	fpga-region0 {
		compatible = "fpga-region";
		fpga-mgr = <&fpga_mgr_spi>;
		#address-cells = <0x1>;
		#size-cells = <0x1>;
	};

	spi1: spi@2000 {
        ...

		fpga_mgr_spi: fpga-mgr@0 {
			compatible = "lattice,machxo2-slave-spi";
			spi-max-frequency = <8000000>;
			reg = <0>;
		};
	};


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

title: Microchip Polarfire FPGA manager.

maintainers:
  - Ivan Bornyakov <i.bornyakov@metrotek.ru>

description:
  Device Tree Bindings for Microchip Polarfire FPGA Manager using slave SPI to
  load the bitstream in .dat format.

properties:
  compatible:
    enum:
      - microchip,mpf-spi-fpga-mgr

  reg:
    description: SPI chip select
    maxItems: 1

required:
  - compatible
  - reg

allOf:
  - $ref: /schemas/spi/spi-peripheral-props.yaml#

unevaluatedProperties: false

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

            fpga_mgr@0 {
                    compatible = "microchip,mpf-spi-fpga-mgr";
                    spi-max-frequency = <20000000>;
                    reg = <0>;
            };
    };


code:
Xilinx LogiCORE Partial Reconfig Decoupler Softcore

The Xilinx LogiCORE Partial Reconfig Decoupler manages one or more
decouplers / fpga bridges.
The controller can decouple/disable the bridges which prevents signal
changes from passing through the bridge.  The controller can also
couple / enable the bridges which allows traffic to pass through the
bridge normally.

Xilinx LogiCORE Dynamic Function eXchange(DFX) AXI shutdown manager
Softcore is compatible with the Xilinx LogiCORE pr-decoupler.

The Dynamic Function eXchange AXI shutdown manager prevents AXI traffic
from passing through the bridge. The controller safely handles AXI4MM
and AXI4-Lite interfaces on a Reconfigurable Partition when it is
undergoing dynamic reconfiguration, preventing the system deadlock
that can occur if AXI transactions are interrupted by DFX

The Driver supports only MMIO handling. A PR region can have multiple
PR Decouplers which can be handled independently or chained via decouple/
decouple_status signals.

Required properties:
- compatible		: Should contain "xlnx,pr-decoupler-1.00" followed by
                          "xlnx,pr-decoupler" or
                          "xlnx,dfx-axi-shutdown-manager-1.00" followed by
                          "xlnx,dfx-axi-shutdown-manager"
- regs			: base address and size for decoupler module
- clocks		: input clock to IP
- clock-names		: should contain "aclk"

See Documentation/devicetree/bindings/fpga/fpga-region.txt and
Documentation/devicetree/bindings/fpga/fpga-bridge.txt for generic bindings.

Example:
Partial Reconfig Decoupler:
	fpga-bridge@100000450 {
		compatible = "xlnx,pr-decoupler-1.00",
			     "xlnx-pr-decoupler";
		regs = <0x10000045 0x10>;
		clocks = <&clkc 15>;
		clock-names = "aclk";
		bridge-enable = <0>;
	};

Dynamic Function eXchange AXI shutdown manager:
	fpga-bridge@100000450 {
		compatible = "xlnx,dfx-axi-shutdown-manager-1.00",
			     "xlnx,dfx-axi-shutdown-manager";
		regs = <0x10000045 0x10>;
		clocks = <&clkc 15>;
		clock-names = "aclk";
		bridge-enable = <0>;
	};


code:
Xilinx Slave Serial SPI FPGA Manager

Xilinx Spartan-6 and 7 Series FPGAs support a method of loading the
bitstream over what is referred to as "slave serial" interface.
The slave serial link is not technically SPI, and might require extra
circuits in order to play nicely with other SPI slaves on the same bus.

See:
- https://www.xilinx.com/support/documentation/user_guides/ug380.pdf
- https://www.xilinx.com/support/documentation/user_guides/ug470_7Series_Config.pdf
- https://www.xilinx.com/support/documentation/application_notes/xapp583-fpga-configuration.pdf

Required properties:
- compatible: should contain "xlnx,fpga-slave-serial"
- reg: spi chip select of the FPGA
- prog_b-gpios: config pin (referred to as PROGRAM_B in the manual)
- done-gpios: config status pin (referred to as DONE in the manual)

Optional properties:
- init-b-gpios: initialization status and configuration error pin
                (referred to as INIT_B in the manual)

Example for full FPGA configuration:

	fpga-region0 {
		compatible = "fpga-region";
		fpga-mgr = <&fpga_mgr_spi>;
		#address-cells = <0x1>;
		#size-cells = <0x1>;
	};

	spi1: spi@10680 {
		compatible = "marvell,armada-xp-spi", "marvell,orion-spi";
		pinctrl-0 = <&spi0_pins>;
		pinctrl-names = "default";
		#address-cells = <1>;
		#size-cells = <0>;
		cell-index = <1>;
		interrupts = <92>;
		clocks = <&coreclk 0>;

		fpga_mgr_spi: fpga-mgr@0 {
			compatible = "xlnx,fpga-slave-serial";
			spi-max-frequency = <60000000>;
			spi-cpha;
			reg = <0>;
			prog_b-gpios = <&gpio0 29 GPIO_ACTIVE_LOW>;
			init-b-gpios = <&gpio0 28 GPIO_ACTIVE_LOW>;
			done-gpios = <&gpio0 9 GPIO_ACTIVE_HIGH>;
		};
	};


code:
# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/fpga/xilinx-zynq-fpga-mgr.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Xilinx Zynq FPGA Manager

maintainers:
  - Michal Simek <michal.simek@xilinx.com>

properties:
  compatible:
    const: xlnx,zynq-devcfg-1.0

  reg:
    maxItems: 1

  interrupts:
    maxItems: 1

  clocks:
    maxItems: 1

  clock-names:
    items:
      - const: ref_clk

  syscon:
    $ref: /schemas/types.yaml#/definitions/phandle
    description:
      Phandle to syscon block which provide access to SLCR registers

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

additionalProperties: false

examples:
  - |
    devcfg: devcfg@f8007000 {
      compatible = "xlnx,zynq-devcfg-1.0";
      reg = <0xf8007000 0x100>;
      interrupts = <0 8 4>;
      clocks = <&clkc 12>;
      clock-names = "ref_clk";
      syscon = <&slcr>;
    };


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

title: Xilinx Versal FPGA driver.

maintainers:
  - Nava kishore Manne <nava.manne@xilinx.com>

description: |
  Device Tree Versal FPGA bindings for the Versal SoC, controlled
  using firmware interface.

properties:
  compatible:
    items:
      - enum:
          - xlnx,versal-fpga

required:
  - compatible

additionalProperties: false

examples:
  - |
    versal_fpga: versal_fpga {
         compatible = "xlnx,versal-fpga";
    };

...


code:
# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/fpga/xlnx,zynqmp-pcap-fpga.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Xilinx Zynq Ultrascale MPSoC FPGA Manager

maintainers:
  - Nava kishore Manne <navam@xilinx.com>

description: |
  Device Tree Bindings for Zynq Ultrascale MPSoC FPGA Manager.
  The ZynqMP SoC uses the PCAP (Processor Configuration Port) to
  configure the Programmable Logic (PL). The configuration uses the
  firmware interface.

properties:
  compatible:
    const: xlnx,zynqmp-pcap-fpga

required:
  - compatible

additionalProperties: false

examples:
  - |
    firmware {
      zynqmp_firmware: zynqmp-firmware {
        zynqmp_pcap: pcap {
          compatible = "xlnx,zynqmp-pcap-fpga";
        };
      };
    };
...


code:
Device-tree bindings for AST2600 FSI master
-------------------------------------------

The AST2600 contains two identical FSI masters. They share a clock and have a
separate interrupt line and output pins.

Required properties:
 - compatible: "aspeed,ast2600-fsi-master"
 - reg: base address and length
 - clocks: phandle and clock number
 - interrupts: platform dependent interrupt description
 - pinctrl-0: phandle to pinctrl node
 - pinctrl-names: pinctrl state

Optional properties:
 - cfam-reset-gpios: GPIO for CFAM reset

 - fsi-routing-gpios: GPIO for setting the FSI mux (internal or cabled)
 - fsi-mux-gpios: GPIO for detecting the desired FSI mux state

Examples:

    fsi-master {
        compatible = "aspeed,ast2600-fsi-master", "fsi-master";
        reg = <0x1e79b000 0x94>;
	interrupts = <GIC_SPI 100 IRQ_TYPE_LEVEL_HIGH>;
	pinctrl-names = "default";
	pinctrl-0 = <&pinctrl_fsi1_default>;
	clocks = <&syscon ASPEED_CLK_GATE_FSICLK>;

	fsi-routing-gpios = <&gpio0 ASPEED_GPIO(Q, 7) GPIO_ACTIVE_HIGH>;
	fsi-mux-gpios = <&gpio0 ASPEED_GPIO(B, 0) GPIO_ACTIVE_HIGH>;

	cfam-reset-gpios = <&gpio0 ASPEED_GPIO(Q, 0) GPIO_ACTIVE_LOW>;
    };


code:
Device-tree bindings for ColdFire offloaded gpio-based FSI master driver
------------------------------------------------------------------------

Required properties:
 - compatible =
	"aspeed,ast2400-cf-fsi-master" for an AST2400 based system
   or
	"aspeed,ast2500-cf-fsi-master" for an AST2500 based system

 - clock-gpios = <gpio-descriptor>;	: GPIO for FSI clock
 - data-gpios = <gpio-descriptor>;	: GPIO for FSI data signal
 - enable-gpios = <gpio-descriptor>;	: GPIO for enable signal
 - trans-gpios = <gpio-descriptor>;	: GPIO for voltage translator enable
 - mux-gpios = <gpio-descriptor>;	: GPIO for pin multiplexing with other
                                          functions (eg, external FSI masters)
 - memory-region = <phandle>;		: Reference to the reserved memory for
                                          the ColdFire. Must be 2M aligned on
					  AST2400 and 1M aligned on AST2500
 - aspeed,sram = <phandle>;		: Reference to the SRAM node.
 - aspeed,cvic = <phandle>;		: Reference to the CVIC node.

Examples:

    fsi-master {
        compatible = "aspeed,ast2500-cf-fsi-master", "fsi-master";

	clock-gpios = <&gpio 0>;
        data-gpios = <&gpio 1>;
        enable-gpios = <&gpio 2>;
        trans-gpios = <&gpio 3>;
        mux-gpios = <&gpio 4>;

	memory-region = <&coldfire_memory>;
	aspeed,sram = <&sram>;
	aspeed,cvic = <&cvic>;
    }


code:
Device-tree bindings for gpio-based FSI master driver
-----------------------------------------------------

Required properties:
 - compatible = "fsi-master-gpio";
 - clock-gpios = <gpio-descriptor>;	: GPIO for FSI clock
 - data-gpios = <gpio-descriptor>;	: GPIO for FSI data signal

Optional properties:
 - enable-gpios = <gpio-descriptor>;	: GPIO for enable signal
 - trans-gpios = <gpio-descriptor>;	: GPIO for voltage translator enable
 - mux-gpios = <gpio-descriptor>;	: GPIO for pin multiplexing with other
                                          functions (eg, external FSI masters)
 - no-gpio-delays;			: Don't add extra delays between GPIO
                                          accesses. This is useful when the HW
					  GPIO block is running at a low enough
					  frequency.

Examples:

    fsi-master {
        compatible = "fsi-master-gpio", "fsi-master";
        clock-gpios = <&gpio 0>;
        data-gpios = <&gpio 1>;
        enable-gpios = <&gpio 2>;
        trans-gpios = <&gpio 3>;
        mux-gpios = <&gpio 4>;
    }


code:
FSI bus & engine generic device tree bindings
=============================================

The FSI bus is probe-able, so the OS is able to enumerate FSI slaves, and
engines within those slaves. However, we have a facility to match devicetree
nodes to probed engines. This allows for fsi engines to expose non-probeable
busses, which are then exposed by the device tree. For example, an FSI engine
that is an I2C master - the I2C bus can be described by the device tree under
the engine's device tree node.

FSI masters may require their own DT nodes (to describe the master HW itself);
that requirement is defined by the master's implementation, and is described by
the fsi-master-* binding specifications.

Under the masters' nodes, we can describe the bus topology using nodes to
represent the FSI slaves and their slave engines. As a basic outline:

  fsi-master {
      /* top-level of FSI bus topology, bound to an FSI master driver and
       * exposes an FSI bus */

      fsi-slave@<link,id> {
          /* this node defines the FSI slave device, and is handled
           * entirely with FSI core code */

          fsi-slave-engine@<addr> {
              /* this node defines the engine endpoint & address range, which
               * is bound to the relevant fsi device driver */
               ...
          };

          fsi-slave-engine@<addr> {
              ...
          };

      };
  };

Note that since the bus is probe-able, some (or all) of the topology may
not be described; this binding only provides an optional facility for
adding subordinate device tree nodes as children of FSI engines.

FSI masters
-----------

FSI master nodes declare themselves as such with the "fsi-master" compatible
value. It's likely that an implementation-specific compatible value will
be needed as well, for example:

    compatible = "fsi-master-gpio", "fsi-master";

Since the master nodes describe the top-level of the FSI topology, they also
need to declare the FSI-standard addressing scheme. This requires two cells for
addresses (link index and slave ID), and no size:

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

An optional boolean property can be added to indicate that a particular master
should not scan for connected devices at initialization time.  This is
necessary in cases where a scan could cause arbitration issues with other
masters that may be present on the bus.

    no-scan-on-init;

FSI slaves
----------

Slaves are identified by a (link-index, slave-id) pair, so require two cells
for an address identifier. Since these are not a range, no size cells are
required. For an example, a slave on link 1, with ID 2, could be represented
as:

    cfam@1,2 {
        reg = <1 2>;
	[...];
    }

Each slave provides an address-space, under which the engines are accessible.
That address space has a maximum of 23 bits, so we use one cell to represent
addresses and sizes in the slave address space:

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

Optionally, a slave can provide a global unique chip ID which is used to
identify the physical location of the chip in a system specific way

    chip-id = <0>;

FSI engines (devices)
---------------------

Engines are identified by their address under the slaves' address spaces. We
use a single cell for address and size. Engine nodes represent the endpoint
FSI device, and are passed to those FSI device drivers' ->probe() functions.

For example, for a slave using a single 0x400-byte page starting at address
0xc00:

    engine@c00 {
        reg = <0xc00 0x400>;
    };

Full example
------------

Here's an example that illustrates:
 - an FSI master
   - connected to an FSI slave
     - that contains an engine that is an I2C master
       - connected to an I2C EEPROM

The FSI master may be connected to additional slaves, and slaves may have
additional engines, but they don't necessarily need to be describe in the
device tree if no extra platform information is required.

    /* The GPIO-based FSI master node, describing the top level of the
     * FSI bus
     */
    gpio-fsi {
        compatible = "fsi-master-gpio", "fsi-master";
        #address-cells = <2>;
        #size-cells = <0>;

        /* A FSI slave (aka. CFAM) at link 0, ID 0. */
        cfam@0,0 {
            reg = <0 0>;
            #address-cells = <1>;
            #size-cells = <1>;
	    chip-id = <0>;

            /* FSI engine at 0xc00, using a single page. In this example,
             * it's an I2C master controller, so subnodes describe the
             * I2C bus.
             */
            i2c-controller@c00 {
                reg = <0xc00 0x400>;

                /* Engine-specific data. In this case, we're describing an
                 * I2C bus, so we're conforming to the generic I2C binding
                 */
                compatible = "some-vendor,fsi-i2c-controller";
                #address-cells = <1>;
                #size-cells = <1>;

                /* I2C endpoint device: an Atmel EEPROM */
                eeprom@50 {
                    compatible = "atmel,24c256";
                    reg = <0x50>;
                    pagesize = <64>;
                };
            };
        };
    };


code:
# SPDX-License-Identifier: (GPL-2.0-or-later)
%YAML 1.2
---
$id: http://devicetree.org/schemas/fsi/ibm,fsi2spi.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: IBM FSI-attached SPI controllers

maintainers:
  - Eddie James <eajames@linux.ibm.com>

description: |
  This binding describes an FSI CFAM engine called the FSI2SPI. Therefore this
  node will always be a child of an FSI CFAM node; see fsi.txt for details on
  FSI slave and CFAM nodes. This FSI2SPI engine provides access to a number of
  SPI controllers.

properties:
  compatible:
    enum:
      - ibm,fsi2spi

  reg:
    items:
      - description: FSI slave address

required:
  - compatible
  - reg

additionalProperties: false

examples:
  - |
    fsi2spi@1c00 {
        compatible = "ibm,fsi2spi";
        reg = <0x1c00 0x400>;
    };


code:
Device-tree bindings for FSI-attached POWER9/POWER10 On-Chip Controller (OCC)
-----------------------------------------------------------------------------

This is the binding for the P9 or P10 On-Chip Controller accessed over FSI from
a service processor. See fsi.txt for details on bindings for FSI slave and CFAM
nodes. The OCC is not an FSI slave device itself, rather it is accessed
through the SBE FIFO.

Required properties:
 - compatible = "ibm,p9-occ" or "ibm,p10-occ"

Examples:

    occ {
        compatible = "ibm,p9-occ";
    };


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

title: NVIDIA Tegra FUSE block

maintainers:
  - Thierry Reding <thierry.reding@gmail.com>
  - Jon Hunter <jonathanh@nvidia.com>

properties:
  compatible:
    oneOf:
      - enum:
          - nvidia,tegra20-efuse
          - nvidia,tegra30-efuse
          - nvidia,tegra114-efuse
          - nvidia,tegra124-efuse
          - nvidia,tegra210-efuse
          - nvidia,tegra186-efuse
          - nvidia,tegra194-efuse
          - nvidia,tegra234-efuse

      - items:
          - const: nvidia,tegra132-efuse
          - const: nvidia,tegra124-efuse

  reg:
    maxItems: 1

  clocks:
    maxItems: 1

  clock-names:
    items:
      - const: fuse

  resets:
    maxItems: 1

  reset-names:
    items:
      - const: fuse

  operating-points-v2:
    $ref: "/schemas/types.yaml#/definitions/phandle"

  power-domains:
    items:
      - description: phandle to the core power domain

additionalProperties: false

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

if:
  properties:
    compatible:
      contains:
        enum:
          - nvidia,tegra20-efuse
          - nvidia,tegra30-efuse
          - nvidia,tegra114-efuse
          - nvidia,tegra124-efuse
          - nvidia,tegra132-efuse
          - nvidia,tegra210-efuse
then:
  required:
    - resets
    - reset-names

examples:
  - |
    #include <dt-bindings/clock/tegra20-car.h>

    fuse@7000f800 {
        compatible = "nvidia,tegra20-efuse";
        reg = <0x7000f800 0x400>;
        clocks = <&tegra_car TEGRA20_CLK_FUSE>;
        clock-names = "fuse";
        resets = <&tegra_car 39>;
        reset-names = "fuse";
    };