code:
Texas Instruments DaVinci/Keystone Watchdog Timer (WDT) Controller

Required properties:
- compatible : Should be "ti,davinci-wdt", "ti,keystone-wdt"
- reg : Should contain WDT registers location and length

Optional properties:
- timeout-sec : Contains the watchdog timeout in seconds
- clocks : the clock feeding the watchdog timer.
	   Needed if platform uses clocks.
	   See clock-bindings.txt

Documentation:
Davinci DM646x - https://www.ti.com/lit/ug/spruer5b/spruer5b.pdf
Keystone - https://www.ti.com/lit/ug/sprugv5a/sprugv5a.pdf

Examples:

wdt: wdt@2320000 {
	compatible = "ti,davinci-wdt";
	reg = <0x02320000 0x80>;
	timeout-sec = <30>;
	clocks = <&clkwdtimer0>;
};


code:
Conexant Digicolor SoCs Watchdog timer

The watchdog functionality in Conexant Digicolor SoCs relies on the so called
"Agent Communication" block. This block includes the eight programmable system
timer counters. The first timer (called "Timer A") is the only one that can be
used as watchdog.

Required properties:

- compatible : Should be "cnxt,cx92755-wdt"
- reg : Specifies base physical address and size of the registers
- clocks : phandle; specifies the clock that drives the timer

Optional properties:

- timeout-sec : Contains the watchdog timeout in seconds

Example:

	watchdog@f0000fc0 {
		compatible = "cnxt,cx92755-wdt";
		reg = <0xf0000fc0 0x8>;
		clocks = <&main_clk>;
		timeout-sec = <15>;
	};

repo_name: angery/linux


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

title: Faraday Technology FTWDT010 watchdog

maintainers:
  - Linus Walleij <linus.walleij@linaro.org>
  - Corentin Labbe <clabbe@baylibre.com>

description: |
  This is an IP part from Faraday Technology found in the Gemini
  SoCs and others.

allOf:
  - $ref: "watchdog.yaml#"

properties:
  compatible:
    oneOf:
      - const: faraday,ftwdt010
      - items:
          - enum:
              - cortina,gemini-watchdog
              - moxa,moxart-watchdog
          - const: faraday,ftwdt010

  reg:
    maxItems: 1

  resets:
    maxItems: 1

  clocks:
    maxItems: 1

  clock-names:
    const: PCLK

  interrupts:
    maxItems: 1

required:
  - compatible
  - reg

unevaluatedProperties: false

examples:
  - |
    #include <dt-bindings/interrupt-controller/irq.h>
    watchdog@41000000 {
      compatible = "faraday,ftwdt010";
      reg = <0x41000000 0x1000>;
      interrupts = <3 IRQ_TYPE_LEVEL_HIGH>;
      timeout-sec = <5>;
    };
  - |
    watchdog: watchdog@98500000 {
      compatible = "moxa,moxart-watchdog", "faraday,ftwdt010";
      reg = <0x98500000 0x10>;
      clocks = <&clk_apb>;
      clock-names = "PCLK";
    };
...


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

title: i.MX SCU Client Device Node - Watchdog bindings based on SCU Message Protocol

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

description: i.MX SCU Client Device Node
  Client nodes are maintained as children of the relevant IMX-SCU device node.

allOf:
  - $ref: watchdog.yaml#

properties:
  compatible:
    items:
      - const: fsl,imx8qxp-sc-wdt
      - const: fsl,imx-sc-wdt

required:
  - compatible

unevaluatedProperties: false

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


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

title: Freescale i.MX Watchdog Timer (WDT) Controller

maintainers:
  - Anson Huang <Anson.Huang@nxp.com>

allOf:
  - $ref: "watchdog.yaml#"

properties:
  compatible:
    oneOf:
      - const: fsl,imx21-wdt
      - items:
          - enum:
              - fsl,imx25-wdt
              - fsl,imx27-wdt
              - fsl,imx31-wdt
              - fsl,imx35-wdt
              - fsl,imx50-wdt
              - fsl,imx51-wdt
              - fsl,imx53-wdt
              - fsl,imx6q-wdt
              - fsl,imx6sl-wdt
              - fsl,imx6sll-wdt
              - fsl,imx6sx-wdt
              - fsl,imx6ul-wdt
              - fsl,imx7d-wdt
              - fsl,imx8mm-wdt
              - fsl,imx8mn-wdt
              - fsl,imx8mp-wdt
              - fsl,imx8mq-wdt
              - fsl,ls1012a-wdt
              - fsl,ls1043a-wdt
              - fsl,vf610-wdt
          - const: fsl,imx21-wdt

  reg:
    maxItems: 1

  interrupts:
    maxItems: 1

  clocks:
    maxItems: 1

  fsl,ext-reset-output:
    $ref: /schemas/types.yaml#/definitions/flag
    description: |
      If present, the watchdog device is configured to assert its
      external reset (WDOG_B) instead of issuing a software reset.

required:
  - compatible
  - interrupts
  - reg

unevaluatedProperties: false

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

    watchdog@20bc000 {
        compatible = "fsl,imx21-wdt";
        reg = <0x020bc000 0x4000>;
        interrupts = <0 80 IRQ_TYPE_LEVEL_HIGH>;
        clocks = <&clks IMX6QDL_CLK_IPG>;
    };

...


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

title: Freescale i.MX7ULP Watchdog Timer (WDT) Controller

maintainers:
  - Anson Huang <Anson.Huang@nxp.com>

allOf:
  - $ref: "watchdog.yaml#"

properties:
  compatible:
    oneOf:
      - const: fsl,imx7ulp-wdt
      - items:
          - const: fsl,imx8ulp-wdt
          - const: fsl,imx7ulp-wdt
      - const: fsl,imx93-wdt

  reg:
    maxItems: 1

  interrupts:
    maxItems: 1

  clocks:
    maxItems: 1

  timeout-sec: true

required:
  - compatible
  - interrupts
  - reg
  - clocks

additionalProperties: false

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

    watchdog@403d0000 {
        compatible = "fsl,imx7ulp-wdt";
        reg = <0x403d0000 0x10000>;
        interrupts = <GIC_SPI 55 IRQ_TYPE_LEVEL_HIGH>;
        clocks = <&pcc2 IMX7ULP_CLK_WDG1>;
        assigned-clocks = <&pcc2 IMX7ULP_CLK_WDG1>;
        assigned-clock-parents = <&scg1 IMX7ULP_CLK_FIRC_BUS_CLK>;
        timeout-sec = <40>;
    };

...


code:
* GPIO-controlled Watchdog

Required Properties:
- compatible: Should contain "linux,wdt-gpio".
- gpios: From common gpio binding; gpio connection to WDT reset pin.
- hw_algo: The algorithm used by the driver. Should be one of the
  following values:
  - toggle: Either a high-to-low or a low-to-high transition clears
    the WDT counter. The watchdog timer is disabled when GPIO is
    left floating or connected to a three-state buffer.
  - level: Low or high level starts counting WDT timeout,
    the opposite level disables the WDT. Active level is determined
    by the GPIO flags.
- hw_margin_ms: Maximum time to reset watchdog circuit (milliseconds).

Optional Properties:
- always-running: If the watchdog timer cannot be disabled, add this flag to
  have the driver keep toggling the signal without a client. It will only cease
  to toggle the signal when the device is open and the timeout elapsed.

Example:
	watchdog: watchdog {
		/* ADM706 */
		compatible = "linux,wdt-gpio";
		gpios = <&gpio3 9 GPIO_ACTIVE_LOW>;
		hw_algo = "toggle";
		hw_margin_ms = <1600>;
	};


code:
*ImgTec PowerDown Controller (PDC) Watchdog Timer (WDT)

Required properties:
- compatible : Should be "img,pdc-wdt"
- reg : Should contain WDT registers location and length
- clocks: Must contain an entry for each entry in clock-names.
- clock-names: Should contain "wdt" and "sys"; the watchdog counter
               clock and register interface clock respectively.
- interrupts : Should contain WDT interrupt

Examples:

watchdog@18102100 {
	compatible = "img,pdc-wdt";
	reg = <0x18102100 0x100>;
	clocks = <&pdc_wdt_clk>, <&sys_clk>;
	clock-names = "wdt", "sys";
	interrupts = <0 52 IRQ_TYPE_LEVEL_HIGH>;
};


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

title: Intel Keem Bay SoC non-secure Watchdog Timer

maintainers:
  - Wan Ahmad Zainie <wan.ahmad.zainie.wan.mohamad@intel.com>

properties:
  compatible:
    enum:
      - intel,keembay-wdt

  reg:
    maxItems: 1

  clocks:
    maxItems: 1

  interrupts:
    items:
      - description: interrupt specifier for threshold interrupt line
      - description: interrupt specifier for timeout interrupt line

  interrupt-names:
    items:
      - const: threshold
      - const: timeout

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

additionalProperties: false

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

    watchdog: watchdog@2033009c {
        compatible = "intel,keembay-wdt";
        reg = <0x2033009c 0x10>;
        interrupts = <GIC_SPI 1 IRQ_TYPE_LEVEL_HIGH>,
                     <GIC_SPI 2 IRQ_TYPE_LEVEL_HIGH>;
        interrupt-names = "threshold", "timeout";
        clocks = <&scmi_clk KEEM_BAY_A53_TIM>;
    };

...


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

title: Watchdog driver for the sl28cpld board management controller

maintainers:
  - Michael Walle <michael@walle.cc>

description: |
  This module is part of the sl28cpld multi-function device. For more
  details see ../mfd/kontron,sl28cpld.yaml.

allOf:
  - $ref: watchdog.yaml#

properties:
  compatible:
    const: kontron,sl28cpld-wdt

  reg:
    maxItems: 1

  kontron,assert-wdt-timeout-pin:
    description: The SMARC standard defines a WDT_TIME_OUT# pin. If this
      property is set, this output will be pulsed when the watchdog bites
      and the system resets.
    type: boolean

required:
  - compatible

additionalProperties: false


code:
Lantiq WTD watchdog binding
============================

This describes the binding of the Lantiq watchdog driver.

-------------------------------------------------------------------------------
Required properties:
- compatible		: Should be one of
				"lantiq,wdt"
				"lantiq,xrx100-wdt"
				"lantiq,xrx200-wdt", "lantiq,xrx100-wdt"
				"lantiq,falcon-wdt"
- reg			: Address of the watchdog block
- lantiq,rcu		: A phandle to the RCU syscon (required for
			  "lantiq,falcon-wdt" and "lantiq,xrx100-wdt")

-------------------------------------------------------------------------------
Example for the watchdog on the xRX200 SoCs:
		watchdog@803f0 {
			compatible = "lantiq,xrx200-wdt", "lantiq,xrx100-wdt";
			reg = <0x803f0 0x10>;

			lantiq,rcu = <&rcu0>;
		};


code:
* NXP LPC18xx Watchdog Timer (WDT)

Required properties:
- compatible: Should be "nxp,lpc1850-wwdt"
- reg: Should contain WDT registers location and length
- clocks: Must contain an entry for each entry in clock-names.
- clock-names: Should contain "wdtclk" and "reg"; the watchdog counter
               clock and register interface clock respectively.
- interrupts: Should contain WDT interrupt

Examples:

watchdog@40080000 {
	compatible = "nxp,lpc1850-wwdt";
	reg = <0x40080000 0x24>;
	clocks = <&cgu BASE_SAFE_CLK>, <&ccu1 CLK_CPU_WWDT>;
	clock-names = "wdtclk", "reg";
	interrupts = <49>;
};


code:
* Marvell Orion Watchdog Time

Required Properties:

- Compatibility : "marvell,orion-wdt"
		  "marvell,armada-370-wdt"
		  "marvell,armada-xp-wdt"
		  "marvell,armada-375-wdt"
		  "marvell,armada-380-wdt"

- reg		: Should contain two entries: first one with the
		  timer control address, second one with the
		  rstout enable address.

For "marvell,armada-375-wdt" and "marvell,armada-380-wdt":

- reg		: A third entry is mandatory and should contain the
                  shared mask/unmask RSTOUT address.

Clocks required for compatibles = "marvell,orion-wdt",
				  "marvell,armada-370-wdt":
- clocks : Must contain a single entry describing the clock input

Clocks required for compatibles = "marvell,armada-xp-wdt"
				  "marvell,armada-375-wdt"
				  "marvell,armada-380-wdt":
- clocks : Must contain an entry for each entry in clock-names.
- clock-names : Must include the following entries:
  "nbclk" (L2/coherency fabric clock),
  "fixed" (Reference 25 MHz fixed-clock).

Optional properties:

- interrupts	: Contains the IRQ for watchdog expiration
- timeout-sec	: Contains the watchdog timeout in seconds

Example:

	wdt@20300 {
		compatible = "marvell,orion-wdt";
		reg = <0x20300 0x28>, <0x20108 0x4>;
		interrupts = <3>;
		timeout-sec = <10>;
		clocks = <&gate_clk 7>;
	};


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

title: Maxim 63xx Watchdog Timers

allOf:
  - $ref: "watchdog.yaml#"

maintainers:
  - Marc Zyngier <maz@kernel.org>
  - Linus Walleij <linus.walleij@linaro.org>

properties:
  compatible:
    enum:
      - maxim,max6369
      - maxim,max6370
      - maxim,max6371
      - maxim,max6372
      - maxim,max6373
      - maxim,max6374

  reg:
    description: This is a 1-byte memory-mapped address
    maxItems: 1

required:
  - compatible
  - reg

unevaluatedProperties: false

examples:
  - |
    wdt: watchdog@50000000 {
        compatible = "maxim,max6369";
        reg = <0x50000000 0x1>;
        timeout-sec = <10>;
    };

...


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

title: Ralink Watchdog Timers

maintainers:
  - Sergio Paracuellos <sergio.paracuellos@gmail.com>

allOf:
  - $ref: watchdog.yaml#

properties:
  compatible:
    const: mediatek,mt7621-wdt

  reg:
    maxItems: 1

required:
  - compatible
  - reg

additionalProperties: false

examples:
  - |
    watchdog@100 {
      compatible = "mediatek,mt7621-wdt";
      reg = <0x100 0x100>;
    };


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

title: MediaTek SoCs Watchdog timer

maintainers:
  - Matthias Brugger <matthias.bgg@gmail.com>

description:
  The watchdog supports a pre-timeout interrupt that fires
  timeout-sec/2 before the expiry.

allOf:
  - $ref: watchdog.yaml#

properties:
  compatible:
    oneOf:
      - enum:
          - mediatek,mt2712-wdt
          - mediatek,mt6589-wdt
          - mediatek,mt6795-wdt
          - mediatek,mt7986-wdt
          - mediatek,mt8183-wdt
          - mediatek,mt8186-wdt
          - mediatek,mt8188-wdt
          - mediatek,mt8192-wdt
          - mediatek,mt8195-wdt
      - items:
          - enum:
              - mediatek,mt2701-wdt
              - mediatek,mt6582-wdt
              - mediatek,mt6797-wdt
              - mediatek,mt7622-wdt
              - mediatek,mt7623-wdt
              - mediatek,mt7629-wdt
              - mediatek,mt8173-wdt
              - mediatek,mt8516-wdt
          - const: mediatek,mt6589-wdt

  reg:
    maxItems: 1

  interrupts:
    items:
      - description: Watchdog pre-timeout (bark) interrupt

  mediatek,disable-extrst:
    description: Disable sending output reset signal
    type: boolean

  '#reset-cells':
    const: 1

required:
  - compatible
  - reg

unevaluatedProperties: false

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

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

        watchdog: watchdog@10007000 {
            compatible = "mediatek,mt8183-wdt";
            reg = <0 0x10007000 0 0x100>;
            interrupts = <GIC_SPI 139 IRQ_TYPE_LEVEL_LOW>;
            mediatek,disable-extrst;
            timeout-sec = <10>;
            #reset-cells = <1>;
        };
    };


code:
Bindings for MEN A21 Watchdog device connected to GPIO lines

Required properties:
- compatible: "men,a021-wdt"
- gpios: Specifies the pins that control the Watchdog, order:
  1: Watchdog enable
  2: Watchdog fast-mode
  3: Watchdog trigger
  4: Watchdog reset cause bit 0
  5: Watchdog reset cause bit 1
  6: Watchdog reset cause bit 2

Optional properties:
- None

Example:
	watchdog {
		compatible ="men,a021-wdt";
		gpios = <&gpio3 9  1	/* WD_EN */
			 &gpio3 10 1	/* WD_FAST */
			 &gpio3 11 1	/* WD_TRIG */
			 &gpio3 6  1	/* RST_CAUSE[0] */
			 &gpio3 7  1	/* RST_CAUSE[1] */
			 &gpio3 8  1>;	/* RST_CAUSE[2] */
	};


code:
Meson SoCs Watchdog timer

Required properties:

- compatible : depending on the SoC this should be one of:
	"amlogic,meson6-wdt" on Meson6 SoCs
	"amlogic,meson8-wdt" and "amlogic,meson6-wdt" on Meson8 SoCs
	"amlogic,meson8b-wdt" on Meson8b SoCs
	"amlogic,meson8m2-wdt" and "amlogic,meson8b-wdt" on Meson8m2 SoCs
- reg : Specifies base physical address and size of the registers.

Optional properties:
- timeout-sec: contains the watchdog timeout in seconds.

Example:

wdt: watchdog@c1109900 {
	compatible = "amlogic,meson6-wdt";
	reg = <0xc1109900 0x8>;
	timeout-sec = <10>;
};


code:
* Microchip PIC32 Deadman Timer

The deadman timer is used to reset the processor in the event of a software
malfunction. It is a free-running instruction fetch timer, which is clocked
whenever an instruction fetch occurs until a count match occurs.

Required properties:
- compatible: must be "microchip,pic32mzda-dmt".
- reg: physical base address of the controller and length of memory mapped
  region.
- clocks: phandle of source clk. Should be <&rootclk PB7CLK>.

Example:

	watchdog@1f800a00 {
		compatible = "microchip,pic32mzda-dmt";
		reg = <0x1f800a00 0x80>;
		clocks = <&rootclk PB7CLK>;
	};


code:
* Microchip PIC32 Watchdog Timer

When enabled, the watchdog peripheral can be used to reset the device if the
WDT is not cleared periodically in software.

Required properties:
- compatible: must be "microchip,pic32mzda-wdt".
- reg: physical base address of the controller and length of memory mapped
  region.
- clocks: phandle of source clk. Should be <&rootclk LPRCCLK>.

Example:

	watchdog@1f800800 {
		compatible = "microchip,pic32mzda-wdt";
		reg = <0x1f800800 0x200>;
		clocks = <&rootclk LPRCCLK>;
	};


code:
MOXA ART Watchdog timer

Required properties:

- compatible : Must be "moxa,moxart-watchdog"
- reg : Should contain registers location and length
- clocks : Should contain phandle for the clock that drives the counter

Example:

	watchdog: watchdog@98500000 {
		compatible = "moxa,moxart-watchdog";
		reg = <0x98500000 0x10>;
		clocks = <&coreclk>;
	};


code:
* Freescale mpc8xxx watchdog driver (For 83xx, 86xx and 8xx)

Required properties:
- compatible: Shall contain one of the following:
	"mpc83xx_wdt" for an mpc83xx
	"fsl,mpc8610-wdt" for an mpc86xx
	"fsl,mpc823-wdt" for an mpc8xx
- reg: base physical address and length of the area hosting the
       watchdog registers.
		On the 83xx, "Watchdog Timer Registers" area:	<0x200 0x100>
		On the 86xx, "Watchdog Timer Registers" area:	<0xe4000 0x100>
		On the 8xx, "General System Interface Unit" area: <0x0 0x10>

Optional properties:
- reg: additional physical address and length (4) of location of the
       Reset Status Register (called RSTRSCR on the mpc86xx)
		On the 83xx, it is located at offset 0x910
		On the 86xx, it is located at offset 0xe0094
		On the 8xx, it is located at offset 0x288

Example:
		WDT: watchdog@0 {
		    compatible = "fsl,mpc823-wdt";
		    reg = <0x0 0x10 0x288 0x4>;
		};


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

title: MStar Watchdog

maintainers:
  - Daniel Palmer <daniel@0x0f.com>
  - Romain Perier <romain.perier@gmail.com>

allOf:
  - $ref: watchdog.yaml#

properties:
  compatible:
    enum:
      - mstar,msc313e-wdt

  reg:
    maxItems: 1

  clocks:
    maxItems: 1

required:
  - compatible
  - clocks
  - reg

unevaluatedProperties: false

examples:
  - |
    watchdog@6000 {
        compatible = "mstar,msc313e-wdt";
        reg = <0x6000 0x1f>;
        clocks = <&xtal_div2>;
    };


code:
Nuvoton NPCM Watchdog

Nuvoton NPCM timer module provides five 24-bit timer counters, and a watchdog.
The watchdog supports a pre-timeout interrupt that fires 10ms before the
expiry.

Required properties:
- compatible      : "nuvoton,npcm750-wdt" for NPCM750 (Poleg), or
                    "nuvoton,wpcm450-wdt" for WPCM450 (Hermon), or
                    "nuvoton,npcm845-wdt" for NPCM845 (Arbel).
- reg             : Offset and length of the register set for the device.
- interrupts      : Contain the timer interrupt with flags for
                    falling edge.

Required clocking property, have to be one of:
- clocks          : phandle of timer reference clock.
- clock-frequency : The frequency in Hz of the clock that drives the NPCM7xx
                    timer (usually 25000000).

Optional properties:
- timeout-sec : Contains the watchdog timeout in seconds

Example:

timer@f000801c {
    compatible = "nuvoton,npcm750-wdt";
    interrupts = <GIC_SPI 47 IRQ_TYPE_LEVEL_HIGH>;
    reg = <0xf000801c 0x4>;
    clocks = <&clk NPCM7XX_CLK_TIMER>;
};


code:
TI Watchdog Timer (WDT) Controller for OMAP

Required properties:
- compatible : "ti,omap3-wdt" for OMAP3 or "ti,omap4-wdt" for OMAP4
- ti,hwmods : Name of the hwmod associated to the WDT

Optional properties:
- timeout-sec : default watchdog timeout in seconds

Examples:

wdt2: wdt@4a314000 {
	compatible = "ti,omap4-wdt", "ti,omap3-wdt";
	ti,hwmods = "wd_timer2";
};


code:
* NXP PNX watchdog timer

Required properties:
- compatible: must be "nxp,pnx4008-wdt"
- reg: physical base address of the controller and length of memory mapped
  region.

Optional properties:
- timeout-sec: contains the watchdog timeout in seconds.

Example:

	watchdog@4003c000 {
		compatible = "nxp,pnx4008-wdt";
		reg = <0x4003C000 0x1000>;
		timeout-sec = <10>;
	};


code:
* Qualcomm Atheros AR7130 Watchdog Timer (WDT) Controller

Required properties:
- compatible: must be "qca,ar7130-wdt"
- reg: physical base address of the controller and length of memory mapped
  region.

Example:

wdt@18060008 {
	compatible = "qca,ar9330-wdt", "qca,ar7130-wdt";
	reg = <0x18060008 0x8>;
};


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

title: Qualcomm PM8916 watchdog timer controller

maintainers:
  - Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>

allOf:
  - $ref: watchdog.yaml#

properties:
  compatible:
    const: qcom,pm8916-wdt

  interrupts:
    maxItems: 1

required:
  - compatible
  - interrupts

unevaluatedProperties: false

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

    pmic@0 {
        compatible = "qcom,pm8916", "qcom,spmi-pmic";
        reg = <0x0 SPMI_USID>;
        #address-cells = <1>;
        #size-cells = <0>;

        pon@800 {
            compatible = "qcom,pm8916-pon";
            reg = <0x800>;
            mode-bootloader = <0x2>;
            mode-recovery = <0x1>;

            watchdog {
                compatible = "qcom,pm8916-wdt";
                interrupts = <0x0 0x8 6 IRQ_TYPE_EDGE_RISING>;
                timeout-sec = <60>;
            };
        };
    };


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

title: Qualcomm Krait Processor Sub-system (KPSS) Watchdog timer

maintainers:
  - Sai Prakash Ranjan <saiprakash.ranjan@codeaurora.org>

allOf:
  - $ref: watchdog.yaml#

properties:
  compatible:
    oneOf:
      - items:
          - enum:
              - qcom,apss-wdt-qcs404
              - qcom,apss-wdt-sc7180
              - qcom,apss-wdt-sc7280
              - qcom,apss-wdt-sc8180x
              - qcom,apss-wdt-sc8280xp
              - qcom,apss-wdt-sdm845
              - qcom,apss-wdt-sdx55
              - qcom,apss-wdt-sdx65
              - qcom,apss-wdt-sm6350
              - qcom,apss-wdt-sm8150
              - qcom,apss-wdt-sm8250
          - const: qcom,kpss-wdt
      - items:
          - enum:
              - qcom,kpss-wdt
              - qcom,kpss-timer
              - qcom,kpss-wdt-apq8064
              - qcom,kpss-wdt-ipq4019
              - qcom,kpss-wdt-ipq8064
              - qcom,kpss-wdt-msm8960
              - qcom,scss-timer

  reg:
    maxItems: 1

  clocks:
    maxItems: 1

required:
  - compatible
  - reg
  - clocks

unevaluatedProperties: false

examples:
  - |
    watchdog@208a038 {
      compatible = "qcom,kpss-wdt-ipq8064";
      reg = <0x0208a038 0x40>;
      clocks = <&sleep_clk>;
      timeout-sec = <10>;
    };


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

title: Realtek Otto watchdog timer

maintainers:
  - Sander Vanheule <sander@svanheule.net>

description: |
  The timer has two timeout phases. Both phases have a maximum duration of 32
  prescaled clock ticks, which is ca. 43s with a bus clock of 200MHz. The
  minimum duration of each phase is one tick. Each phase can trigger an
  interrupt, although the phase 2 interrupt will occur with the system reset.
  - Phase 1: During this phase, the WDT can be pinged to reset the timeout.
  - Phase 2: Starts after phase 1 has timed out, and only serves to give the
    system some time to clean up, or notify others that it's going to reset.
    During this phase, pinging the WDT has no effect, and a reset is
    unavoidable, unless the WDT is disabled.

allOf:
  - $ref: watchdog.yaml#

properties:
  compatible:
    enum:
      - realtek,rtl8380-wdt
      - realtek,rtl8390-wdt
      - realtek,rtl9300-wdt
      - realtek,rtl9310-wdt

  reg:
    maxItems: 1

  clocks:
    maxItems: 1

  interrupts:
    items:
      - description: interrupt specifier for pretimeout
      - description: interrupt specifier for timeout

  interrupt-names:
    items:
      - const: phase1
      - const: phase2

  realtek,reset-mode:
    $ref: /schemas/types.yaml#/definitions/string
    description: |
      Specify how the system is reset after a timeout. Defaults to "cpu" if
      left unspecified.
    oneOf:
      - description: Reset the entire chip
        const: soc
      - description: |
          Reset the CPU and IPsec engine, but leave other peripherals untouched
        const: cpu
      - description: |
          Reset the execution pointer, but don't actually reset any hardware
        const: software

required:
  - compatible
  - reg
  - clocks
  - interrupts

unevaluatedProperties: false

dependencies:
  interrupts: [ interrupt-names ]

examples:
  - |
    watchdog: watchdog@3150 {
        compatible = "realtek,rtl8380-wdt";
        reg = <0x3150 0xc>;

        realtek,reset-mode = "soc";

        clocks = <&lxbus_clock>;
        timeout-sec = <20>;

        interrupt-parent = <&rtlintc>;
        interrupt-names = "phase1", "phase2";
        interrupts = <19>, <18>;
    };

...


code:
Realtek RTD1295 Watchdog
========================

Required properties:

- compatible :  Should be "realtek,rtd1295-watchdog"
- reg        :  Specifies the physical base address and size of registers
- clocks     :  Specifies one clock input

Example:

	watchdog@98007680 {
		compatible = "realtek,rtd1295-watchdog";
		reg = <0x98007680 0x100>;
		clocks = <&osc27M>;
	};


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

title: Renesas Watchdog Timer (WDT) Controller

maintainers:
  - Wolfram Sang <wsa+renesas@sang-engineering.com>
  - Geert Uytterhoeven <geert+renesas@glider.be>

properties:
  compatible:
    oneOf:
      - items:
          - enum:
              - renesas,r7s72100-wdt     # RZ/A1
              - renesas,r7s9210-wdt      # RZ/A2
          - const: renesas,rza-wdt       # RZ/A

      - items:
          - enum:
              - renesas,r9a06g032-wdt    # RZ/N1D
          - const: renesas,rzn1-wdt      # RZ/N1

      - items:
          - enum:
              - renesas,r9a07g043-wdt    # RZ/G2UL
              - renesas,r9a07g044-wdt    # RZ/G2{L,LC}
              - renesas,r9a07g054-wdt    # RZ/V2L
          - const: renesas,rzg2l-wdt

      - items:
          - enum:
              - renesas,r9a09g011-wdt    # RZ/V2M
          - const: renesas,rzv2m-wdt     # RZ/V2M

      - items:
          - enum:
              - renesas,r8a7742-wdt      # RZ/G1H
              - renesas,r8a7743-wdt      # RZ/G1M
              - renesas,r8a7744-wdt      # RZ/G1N
              - renesas,r8a7745-wdt      # RZ/G1E
              - renesas,r8a77470-wdt     # RZ/G1C
              - renesas,r8a7790-wdt      # R-Car H2
              - renesas,r8a7791-wdt      # R-Car M2-W
              - renesas,r8a7792-wdt      # R-Car V2H
              - renesas,r8a7793-wdt      # R-Car M2-N
              - renesas,r8a7794-wdt      # R-Car E2
          - const: renesas,rcar-gen2-wdt # R-Car Gen2 and RZ/G1

      - items:
          - enum:
              - renesas,r8a774a1-wdt     # RZ/G2M
              - renesas,r8a774b1-wdt     # RZ/G2N
              - renesas,r8a774c0-wdt     # RZ/G2E
              - renesas,r8a774e1-wdt     # RZ/G2H
              - renesas,r8a7795-wdt      # R-Car H3
              - renesas,r8a7796-wdt      # R-Car M3-W
              - renesas,r8a77961-wdt     # R-Car M3-W+
              - renesas,r8a77965-wdt     # R-Car M3-N
              - renesas,r8a77970-wdt     # R-Car V3M
              - renesas,r8a77980-wdt     # R-Car V3H
              - renesas,r8a77990-wdt     # R-Car E3
              - renesas,r8a77995-wdt     # R-Car D3
          - const: renesas,rcar-gen3-wdt # R-Car Gen3 and RZ/G2

      - items:
          - enum:
              - renesas,r8a779a0-wdt     # R-Car V3U
              - renesas,r8a779f0-wdt     # R-Car S4-8
              - renesas,r8a779g0-wdt     # R-Car V4H
          - const: renesas,rcar-gen4-wdt # R-Car Gen4

  reg:
    maxItems: 1

  interrupts:
    minItems: 1
    items:
      - description: Timeout
      - description: Parity error

  interrupt-names:
    minItems: 1
    items:
      - const: wdt
      - const: perrout

  clocks:
    minItems: 1
    items:
      - description: Register access clock
      - description: Main clock

  clock-names:
    minItems: 1
    items:
      - const: pclk
      - const: oscclk

  power-domains:
    maxItems: 1

  resets:
    maxItems: 1

  timeout-sec: true

required:
  - compatible
  - reg
  - interrupts
  - clocks

allOf:
  - $ref: "watchdog.yaml#"

  - if:
      not:
        properties:
          compatible:
            contains:
              enum:
                - renesas,rza-wdt
                - renesas,rzn1-wdt
    then:
      required:
        - power-domains
        - resets

  - if:
      properties:
        compatible:
          contains:
            enum:
              - renesas,rzg2l-wdt
              - renesas,rzv2m-wdt
    then:
      properties:
        clocks:
          minItems: 2
        clock-names:
          minItems: 2
      required:
        - clock-names
    else:
      properties:
        clocks:
          maxItems: 1

  - if:
      properties:
        compatible:
          contains:
            enum:
              - renesas,rzg2l-wdt
    then:
      properties:
        interrupts:
          minItems: 2
        interrupt-names:
          minItems: 2
      required:
        - interrupt-names
    else:
      properties:
        interrupts:
          maxItems: 1

additionalProperties: false

examples:
  - |
    #include <dt-bindings/clock/r8a7795-cpg-mssr.h>
    #include <dt-bindings/power/r8a7795-sysc.h>
    #include <dt-bindings/interrupt-controller/arm-gic.h>
    wdt0: watchdog@e6020000 {
            compatible = "renesas,r8a7795-wdt", "renesas,rcar-gen3-wdt";
            reg = <0xe6020000 0x0c>;
            interrupts = <GIC_SPI 140 IRQ_TYPE_LEVEL_HIGH>;
            clocks = <&cpg CPG_MOD 402>;
            power-domains = <&sysc R8A7795_PD_ALWAYS_ON>;
            resets = <&cpg 402>;
            timeout-sec = <60>;
    };


code:
Ralink Watchdog Timers

Required properties:
- compatible: must be "ralink,rt2880-wdt"
- reg: physical base address of the controller and length of the register range

Optional properties:
- interrupts: Specify the INTC interrupt number

Example:

	watchdog@120 {
		compatible = "ralink,rt2880-wdt";
		reg = <0x120 0x10>;

		interrupt-parent = <&intc>;
		interrupts = <1>;
	};


code:
# SPDX-License-Identifier: GPL-2.0
%YAML 1.2
---
$id: http://devicetree.org/schemas/watchdog/samsung-wdt.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Samsung SoC Watchdog Timer Controller

maintainers:
  - Krzysztof Kozlowski <krzk@kernel.org>

description: |+
  The Samsung's Watchdog controller is used for resuming system operation
  after a preset amount of time during which the WDT reset event has not
  occurred.

properties:
  compatible:
    enum:
      - samsung,s3c2410-wdt                   # for S3C2410
      - samsung,s3c6410-wdt                   # for S3C6410, S5PV210 and Exynos4
      - samsung,exynos5250-wdt                # for Exynos5250
      - samsung,exynos5420-wdt                # for Exynos5420
      - samsung,exynos7-wdt                   # for Exynos7
      - samsung,exynos850-wdt                 # for Exynos850
      - samsung,exynosautov9-wdt              # for Exynosautov9

  reg:
    maxItems: 1

  clocks:
    minItems: 1
    maxItems: 2

  clock-names:
    minItems: 1
    maxItems: 2

  interrupts:
    maxItems: 1

  samsung,cluster-index:
    $ref: /schemas/types.yaml#/definitions/uint32
    description:
      Index of CPU cluster on which watchdog is running (in case of Exynos850)

  samsung,syscon-phandle:
    $ref: /schemas/types.yaml#/definitions/phandle
    description:
      Phandle to the PMU system controller node (in case of Exynos5250,
      Exynos5420, Exynos7 and Exynos850).

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

allOf:
  - $ref: watchdog.yaml#
  - if:
      properties:
        compatible:
          contains:
            enum:
              - samsung,exynos5250-wdt
              - samsung,exynos5420-wdt
              - samsung,exynos7-wdt
              - samsung,exynos850-wdt
              - samsung,exynosautov9-wdt
    then:
      required:
        - samsung,syscon-phandle
  - if:
      properties:
        compatible:
          contains:
            enum:
              - samsung,exynos850-wdt
              - samsung,exynosautov9-wdt
    then:
      properties:
        clocks:
          items:
            - description: Bus clock, used for register interface
            - description: Source clock (driving watchdog counter)
        clock-names:
          items:
            - const: watchdog
            - const: watchdog_src
        samsung,cluster-index:
          enum: [0, 1]
      required:
        - samsung,cluster-index
    else:
      properties:
        clocks:
          items:
            - description: Bus clock, which is also a source clock
        clock-names:
          items:
            - const: watchdog
        samsung,cluster-index: false

unevaluatedProperties: false

examples:
  - |
    watchdog@101d0000 {
        compatible = "samsung,exynos5250-wdt";
        reg = <0x101D0000 0x100>;
        interrupts = <0 42 0>;
        clocks = <&clock 336>;
        clock-names = "watchdog";
        samsung,syscon-phandle = <&pmu_syscon>;
    };


code:
# SPDX-License-Identifier: GPL-2.0-only
%YAML 1.2
---
$id: http://devicetree.org/schemas/watchdog/snps,dw-wdt.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Synopsys Designware Watchdog Timer

allOf:
  - $ref: "watchdog.yaml#"

maintainers:
  - Jamie Iles <jamie@jamieiles.com>

properties:
  compatible:
    oneOf:
      - const: snps,dw-wdt
      - items:
          - enum:
              - rockchip,px30-wdt
              - rockchip,rk3066-wdt
              - rockchip,rk3128-wdt
              - rockchip,rk3188-wdt
              - rockchip,rk3228-wdt
              - rockchip,rk3288-wdt
              - rockchip,rk3308-wdt
              - rockchip,rk3328-wdt
              - rockchip,rk3368-wdt
              - rockchip,rk3399-wdt
              - rockchip,rk3568-wdt
              - rockchip,rv1108-wdt
          - const: snps,dw-wdt

  reg:
    maxItems: 1

  interrupts:
    description: DW Watchdog pre-timeout interrupt
    maxItems: 1

  clocks:
    minItems: 1
    items:
      - description: Watchdog timer reference clock
      - description: APB3 interface clock

  clock-names:
    minItems: 1
    items:
      - const: tclk
      - const: pclk

  resets:
    description: Phandle to the DW Watchdog reset lane
    maxItems: 1

  snps,watchdog-tops:
    $ref: /schemas/types.yaml#/definitions/uint32-array
    description: |
      DW APB Watchdog custom timer intervals - Timeout Period ranges (TOPs).
      Each TOP is a number loaded into the watchdog counter at the moment of
      the timer restart. The counter decrementing happens each tick of the
      reference clock. Therefore the TOPs array is equivalent to an array of
      the timer expiration intervals supported by the DW APB Watchdog. Note
      DW APB Watchdog IP-core might be synthesized with fixed TOP values,
      in which case this property is unnecessary with default TOPs utilized.
    default: [0x0001000 0x0002000 0x0004000 0x0008000
      0x0010000 0x0020000 0x0040000 0x0080000
      0x0100000 0x0200000 0x0400000 0x0800000
      0x1000000 0x2000000 0x4000000 0x8000000]
    minItems: 16
    maxItems: 16

unevaluatedProperties: false

required:
  - compatible
  - reg
  - clocks

examples:
  - |
    watchdog@ffd02000 {
      compatible = "snps,dw-wdt";
      reg = <0xffd02000 0x1000>;
      interrupts = <0 171 4>;
      clocks = <&per_base_clk>;
      resets = <&wdt_rst>;
    };

  - |
    watchdog@ffd02000 {
      compatible = "snps,dw-wdt";
      reg = <0xffd02000 0x1000>;
      interrupts = <0 171 4>;
      clocks = <&per_base_clk>;
      clock-names = "tclk";
      snps,watchdog-tops = <0x000000FF 0x000001FF 0x000003FF
                            0x000007FF 0x0000FFFF 0x0001FFFF
                            0x0003FFFF 0x0007FFFF 0x000FFFFF
                            0x001FFFFF 0x003FFFFF 0x007FFFFF
                            0x00FFFFFF 0x01FFFFFF 0x03FFFFFF
                            0x07FFFFFF>;
    };
...


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

title: Socionext UniPhier watchdog timer

maintainers:
  - Keiji Hayashibara <hayashibara.keiji@socionext.com>

allOf:
  - $ref: "watchdog.yaml#"

properties:
  compatible:
    const: socionext,uniphier-wdt

required:
  - compatible

unevaluatedProperties: false

examples:
  - |
    // The UniPhier watchdog should be a subnode of a "syscon" compatible node.

    sysctrl@61840000 {
        compatible = "socionext,uniphier-ld11-sysctrl",
                     "simple-mfd", "syscon";
        reg = <0x61840000 0x10000>;

        watchdog {
            compatible = "socionext,uniphier-wdt";
        };
    };


code:
Spreadtrum SoCs Watchdog timer

Required properties:
- compatible : Should be "sprd,sp9860-wdt".
- reg : Specifies base physical address and size of the registers.
- interrupts : Exactly one interrupt specifier.
- timeout-sec : Contain the default watchdog timeout in seconds.
- clock-names : Contain the input clock names.
- clocks : Phandles to input clocks.

Example:
	watchdog: watchdog@40310000 {
		compatible = "sprd,sp9860-wdt";
		reg = <0 0x40310000 0 0x1000>;
		interrupts = <GIC_SPI 61 IRQ_TYPE_LEVEL_HIGH>;
		timeout-sec = <12>;
		clock-names = "enable", "rtc_enable";
		clocks = <&clk_aon_apb_gates1 8>, <&clk_aon_apb_rtc_gates 9>;
	};


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

title: STMicroelectronics STM32 Independent WatchDoG (IWDG) bindings

maintainers:
  - Yannick Fertre <yannick.fertre@foss.st.com>
  - Christophe Roullier <christophe.roullier@foss.st.com>

allOf:
  - $ref: "watchdog.yaml#"

properties:
  compatible:
    enum:
      - st,stm32-iwdg
      - st,stm32mp1-iwdg

  reg:
    maxItems: 1

  clocks:
    items:
      - description: Low speed clock
      - description: Optional peripheral clock
    minItems: 1

  clock-names:
    items:
      enum:
        - lsi
        - pclk
    minItems: 1
    maxItems: 2

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

unevaluatedProperties: false

examples:
  - |
    #include <dt-bindings/clock/stm32mp1-clks.h>
    watchdog@5a002000 {
      compatible = "st,stm32mp1-iwdg";
      reg = <0x5a002000 0x400>;
      clocks = <&rcc IWDG2>, <&rcc CK_LSI>;
      clock-names = "pclk", "lsi";
      timeout-sec = <32>;
    };

...


code:
STMicroelectronics Low Power Controller (LPC) - Watchdog
========================================================

LPC currently supports Watchdog OR Real Time Clock OR Clocksource
functionality.

[See: ../rtc/rtc-st-lpc.txt for RTC options]
[See: ../timer/st,stih407-lpc for Clocksource options]

Required properties

- compatible 	: Should be: "st,stih407-lpc"
- reg		: LPC registers base address + size
- interrupts    : LPC interrupt line number and associated flags
- clocks	: Clock used by LPC device (See: ../clock/clock-bindings.txt)
- st,lpc-mode	: The LPC can run either one of three modes:
                  ST_LPC_MODE_RTC    [0]
                  ST_LPC_MODE_WDT    [1]
                  ST_LPC_MODE_CLKSRC [2]
		 One (and only one) mode must be selected.

Required properties [watchdog mode]

- st,syscfg	: Phandle to syscfg node used to enable watchdog and configure
		  CPU reset type.
- timeout-sec	: Watchdog timeout in seconds

Optional properties [watchdog mode]

- st,warm-reset	: If present reset type will be 'warm' - if not it will be cold

Example:
	lpc@fde05000 {
		compatible	= "st,stih407-lpc";
		reg		= <0xfde05000 0x1000>;
		clocks 		= <&clk_s_d3_flexgen CLK_LPC_0>;
		st,syscfg	= <&syscfg_core>;
		timeout-sec	= <120>;
		st,lpc-mode	= <ST_LPC_MODE_WDT>;
		st,warm-reset;
	};


code:
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
# Copyright (C) Sunplus Co., Ltd. 2021
%YAML 1.2
---
$id: http://devicetree.org/schemas/watchdog/sunplus,sp7021-wdt.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Sunplus SoCs Watchdog

maintainers:
  - XianTao Hu <xt.hu@cqplus1.com>

allOf:
  - $ref: watchdog.yaml#

properties:
  compatible:
    const: sunplus,sp7021-wdt

  reg:
    items:
      - description: watchdog registers regions
      - description: miscellaneous control registers regions

  clocks:
    maxItems: 1

  resets:
    maxItems: 1

required:
  - compatible
  - reg
  - clocks
  - resets

additionalProperties: false

examples:
  - |
    watchdog: watchdog@9c000630 {
        compatible = "sunplus,sp7021-wdt";
        reg = <0x9c000630 0x08>, <0x9c000274 0x04>;
        clocks = <&clkc 0x24>;
        resets = <&rstc 0x14>;
    };
...


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

title: Texas Instruments K3 SoC Watchdog Timer

maintainers:
  - Tero Kristo <t-kristo@ti.com>

description:
  The TI K3 SoC watchdog timer is implemented via the RTI (Real Time
  Interrupt) IP module. This timer adds a support for windowed watchdog
  mode, which will signal an error if it is pinged outside the watchdog
  time window, meaning either too early or too late. The error signal
  generated can be routed to either interrupt a safety controller or
  to directly reset the SoC.

allOf:
  - $ref: "watchdog.yaml#"

properties:
  compatible:
    enum:
      - ti,j7-rti-wdt

  reg:
    maxItems: 1

  clocks:
    maxItems: 1

  power-domains:
    maxItems: 1

required:
  - compatible
  - reg
  - clocks
  - power-domains

unevaluatedProperties: false

examples:
  - |
    /*
     * RTI WDT in main domain on J721e SoC. Assigned clocks are used to
     * select the source clock for the watchdog, forcing it to tick with
     * a 32kHz clock in this case.
     */
    #include <dt-bindings/soc/ti,sci_pm_domain.h>

    watchdog@2200000 {
        compatible = "ti,j7-rti-wdt";
        reg = <0x2200000 0x100>;
        clocks = <&k3_clks 252 1>;
        power-domains = <&k3_pds 252 TI_SCI_PD_EXCLUSIVE>;
        assigned-clocks = <&k3_clks 252 1>;
        assigned-clock-parents = <&k3_clks 252 5>;
    };


code:
# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
# Copyright 2020 Toshiba Electronic Devices & Storage Corporation
%YAML 1.2
---
$id: "http://devicetree.org/schemas/watchdog/toshiba,visconti-wdt.yaml#"
$schema: "http://devicetree.org/meta-schemas/core.yaml#"

title: Toshiba Visconti SoCs PIUWDT Watchdog timer

maintainers:
  - Nobuhiro Iwamatsu <nobuhiro1.iwamatsu@toshiba.co.jp>

allOf:
  - $ref: watchdog.yaml#

properties:
  compatible:
    enum:
      - toshiba,visconti-wdt

  reg:
    maxItems: 1

  clocks:
    maxItems: 1

  timeout-sec: true

required:
  - compatible
  - reg
  - clocks

additionalProperties: false

examples:
  - |
    #include <dt-bindings/clock/toshiba,tmpv770x.h>

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

        wdt: watchdog@28330000 {
            compatible = "toshiba,visconti-wdt";
            reg = <0 0x28330000 0 0x1000>;
            timeout-sec = <20>;
            clocks = <&pismu TMPV770X_CLK_WDTCLK>;
        };
    };


code:
Technologic Systems Watchdog

Required properties:
- compatible: must be "technologic,ts4800-wdt"
- syscon: phandle / integer array that points to the syscon node which
          describes the FPGA's syscon registers.
          - phandle to FPGA's syscon
          - offset to the watchdog register

Optional property:
- timeout-sec: contains the watchdog timeout in seconds.

Example:

syscon: syscon@b0010000 {
	compatible = "syscon", "simple-mfd";
	reg = <0xb0010000 0x3d>;
	reg-io-width = <2>;

	wdt@e {
		compatible = "technologic,ts4800-wdt";
		syscon = <&syscon 0xe>;
		timeout-sec = <10>;
	};
}


code:
Device tree bindings for twl4030-wdt driver (TWL4030 watchdog)

Required properties:
	compatible = "ti,twl4030-wdt";

Example:

watchdog {
	compatible = "ti,twl4030-wdt";
};


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

title: Watchdog Generic Bindings

maintainers:
  - Guenter Roeck <linux@roeck-us.net>
  - Wim Van Sebroeck <wim@linux-watchdog.org>

description: |
  This document describes generic bindings which can be used to
  describe watchdog devices in a device tree.

properties:
  $nodename:
    pattern: "^watchdog(@.*|-[0-9a-f])?$"

  timeout-sec:
    description:
      Contains the watchdog timeout in seconds.

additionalProperties: true

...


code:
# SPDX-License-Identifier: GPL-2.0-or-later OR BSD-2-Clause
%YAML 1.2
---
$id: http://devicetree.org/schemas/watchdog/xlnx,xps-timebase-wdt.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Xilinx AXI/PLB softcore and window Watchdog Timer

maintainers:
  - Shubhrajyoti Datta <shubhrajyoti.datta@xilinx.com>
  - Srinivas Neeli <srinivas.neeli@xilinx.com>

description:
  The Timebase watchdog timer(WDT) is a free-running 32 bit counter.
  WDT uses a dual-expiration architecture. After one expiration of
  the timeout interval, an interrupt is generated and the WDT state
  bit is set to one in the status register. If the state bit is not
  cleared (by writing a one to the state bit) before the next
  expiration of the timeout interval, a WDT reset is generated.

allOf:
  - $ref: watchdog.yaml#

properties:
  compatible:
    enum:
      - xlnx,xps-timebase-wdt-1.01.a
      - xlnx,xps-timebase-wdt-1.00.a

  reg:
    maxItems: 1

  clocks:
    maxItems: 1

  clock-frequency:
    description: Frequency of clock in Hz

  xlnx,wdt-interval:
    $ref: /schemas/types.yaml#/definitions/uint32
    description: Watchdog timeout interval
    minimum: 8
    maximum: 32

  xlnx,wdt-enable-once:
    $ref: /schemas/types.yaml#/definitions/uint32
    enum: [0, 1]
    description: If watchdog is configured as enable once,
                 then the watchdog cannot be disabled after
                 it has been enabled.

required:
  - compatible
  - reg

unevaluatedProperties: false

examples:
  - |
    watchdog@40100000 {
      compatible = "xlnx,xps-timebase-wdt-1.00.a";
      reg = <0x40100000 0x1000>;
      clock-frequency = <50000000>;
      clocks = <&clkc 15>;
      xlnx,wdt-enable-once = <0x0>;
      xlnx,wdt-interval = <0x1b>;
    };
...


code:
Zodiac Inflight Innovations RAVE Supervisory Processor Watchdog Bindings

RAVE SP watchdog device is a "MFD cell" device corresponding to
watchdog functionality of RAVE Supervisory Processor. It is expected
that its Device Tree node is specified as a child of the node
corresponding to the parent RAVE SP device (as documented in
Documentation/devicetree/bindings/mfd/zii,rave-sp.txt)

Required properties:

- compatible: Depending on wire protocol implemented by RAVE SP
  firmware, should be one of:
	- "zii,rave-sp-watchdog"
	- "zii,rave-sp-watchdog-legacy"

Optional properties:

- wdt-timeout:	Two byte nvmem cell specified as per
		Documentation/devicetree/bindings/nvmem/nvmem.txt

Example:

	rave-sp {
		compatible = "zii,rave-sp-rdu1";
		current-speed = <38400>;

		eeprom {
			wdt_timeout: wdt-timeout@8E {
				reg = <0x8E 2>;
			};
		};

		watchdog {
			compatible = "zii,rave-sp-watchdog";
			nvmem-cells = <&wdt_timeout>;
			nvmem-cell-names = "wdt-timeout";
		};
	}


code:
Zodiac RAVE Watchdog Timer

Required properties:
- compatible: must be "zii,rave-wdt"
- reg: i2c slave address of device, usually 0x38

Optional Properties:
- timeout-sec: Watchdog timeout value in seconds.
- reset-duration-ms: Duration of the pulse generated when the watchdog times
  out. Value in milliseconds.

Example:

	watchdog@38 {
		compatible = "zii,rave-wdt";
		reg = <0x38>;
		timeout-sec = <30>;
		reset-duration-ms = <30>;
	};


code:
.. SPDX-License-Identifier: GPL-2.0

============================================================
DOs and DON'Ts for designing and writing Devicetree bindings
============================================================

This is a list of common review feedback items focused on binding design. With
every rule, there are exceptions and bindings have many gray areas.

For guidelines related to patches, see
Documentation/devicetree/bindings/submitting-patches.rst

Overall design
==============

- DO attempt to make bindings complete even if a driver doesn't support some
  features. For example, if a device has an interrupt, then include the
  'interrupts' property even if the driver is only polled mode.

- DON'T refer to Linux or "device driver" in bindings. Bindings should be
  based on what the hardware has, not what an OS and driver currently support.

- DO use node names matching the class of the device. Many standard names are
  defined in the DT Spec. If there isn't one, consider adding it.

- DO check that the example matches the documentation especially after making
  review changes.

- DON'T create nodes just for the sake of instantiating drivers. Multi-function
  devices only need child nodes when the child nodes have their own DT
  resources. A single node can be multiple providers (e.g. clocks and resets).

- DON'T use 'syscon' alone without a specific compatible string. A 'syscon'
  hardware block should have a compatible string unique enough to infer the
  register layout of the entire block (at a minimum).

Properties
==========

- DO make 'compatible' properties specific. DON'T use wildcards in compatible
  strings. DO use fallback compatibles when devices are the same as or a subset
  of prior implementations. DO add new compatibles in case there are new
  features or bugs.

- DO use a vendor prefix on device-specific property names. Consider if
  properties could be common among devices of the same class. Check other
  existing bindings for similar devices.

- DON'T redefine common properties. Just reference the definition and define
  constraints specific to the device.

- DO use common property unit suffixes for properties with scientific units.
  Recommended suffixes are listed at
  https://github.com/devicetree-org/dt-schema/blob/main/dtschema/schemas/property-units.yaml

- DO define properties in terms of constraints. How many entries? What are
  possible values? What is the order?

Typical cases and caveats
=========================

- Phandle entries, like clocks/dmas/interrupts/resets, should always be
  explicitly ordered. Include the {clock,dma,interrupt,reset}-names if there is
  more than one phandle. When used, both of these fields need the same
  constraints (e.g.  list of items).

- For names used in {clock,dma,interrupt,reset}-names, do not add any suffix,
  e.g.: "tx" instead of "txirq" (for interrupt).

- Properties without schema types (e.g. without standard suffix or not defined
  by schema) need the type, even if this is an enum.

- If schema includes other schema (e.g. /schemas/i2c/i2c-controller.yaml) use
  "unevaluatedProperties:false". In other cases, usually use
  "additionalProperties:false".

- For sub-blocks/components of bigger device (e.g. SoC blocks) use rather
  device-based compatible (e.g. SoC-based compatible), instead of custom
  versioning of that component.
  For example use "vendor,soc1234-i2c" instead of "vendor,i2c-v2".

- "syscon" is not a generic property. Use vendor and type, e.g.
  "vendor,power-manager-syscon".

Board/SoC .dts Files
====================

- DO put all MMIO devices under a bus node and not at the top-level.

- DO use non-empty 'ranges' to limit the size of child buses/devices. 64-bit
  platforms don't need all devices to have 64-bit address and size.


code:
.. SPDX-License-Identifier: GPL-2.0

Writing Devicetree Bindings in json-schema
==========================================

Devicetree bindings are written using json-schema vocabulary. Schema files are
written in a JSON-compatible subset of YAML. YAML is used instead of JSON as it
is considered more human readable and has some advantages such as allowing
comments (Prefixed with '#').

Also see :ref:`example-schema`.

Schema Contents
---------------

Each schema doc is a structured json-schema which is defined by a set of
top-level properties. Generally, there is one binding defined per file. The
top-level json-schema properties used are:

$id
  A json-schema unique identifier string. The string must be a valid
  URI typically containing the binding's filename and path. For DT schema, it must
  begin with "http://devicetree.org/schemas/". The URL is used in constructing
  references to other files specified in schema "$ref" properties. A $ref value
  with a leading '/' will have the hostname prepended. A $ref value with only a
  relative path or filename will be prepended with the hostname and path
  components of the current schema file's '$id' value. A URL is used even for
  local files, but there may not actually be files present at those locations.

$schema
  Indicates the meta-schema the schema file adheres to.

title
  A one-line description on the contents of the binding schema.

maintainers
  A DT specific property. Contains a list of email address(es)
  for maintainers of this binding.

description
  Optional. A multi-line text block containing any detailed
  information about this binding. It should contain things such as what the block
  or device does, standards the device conforms to, and links to datasheets for
  more information.

select
  Optional. A json-schema used to match nodes for applying the
  schema. By default, without 'select', nodes are matched against their possible
  compatible-string values or node name. Most bindings should not need select.

allOf
  Optional. A list of other schemas to include. This is used to
  include other schemas the binding conforms to. This may be schemas for a
  particular class of devices such as I2C or SPI controllers.

properties
  A set of sub-schema defining all the DT properties for the
  binding. The exact schema syntax depends on whether properties are known,
  common properties (e.g. 'interrupts') or are binding/vendor-specific
  properties.

A property can also define a child DT node with child properties defined
under it.

For more details on properties sections, see 'Property Schema' section.

patternProperties
  Optional. Similar to 'properties', but names are regex.

required
  A list of DT properties from the 'properties' section that
  must always be present.

examples
  Optional. A list of one or more DTS hunks implementing the
  binding. Note: YAML doesn't allow leading tabs, so spaces must be used instead.

Unless noted otherwise, all properties are required.

Property Schema
---------------

The 'properties' section of the schema contains all the DT properties for a
binding. Each property contains a set of constraints using json-schema
vocabulary for that property. The properties schemas are what are used for
validation of DT files.

For common properties, only additional constraints not covered by the common,
binding schema need to be defined such as how many values are valid or what
possible values are valid.

Vendor-specific properties will typically need more detailed schema. With the
exception of boolean properties, they should have a reference to a type in
schemas/types.yaml. A "description" property is always required.

The Devicetree schemas don't exactly match the YAML-encoded DT data produced by
dtc. They are simplified to make them more compact and avoid a bunch of
boilerplate. The tools process the schema files to produce the final schema for
validation. There are currently 2 transformations the tools perform.

The default for arrays in json-schema is they are variable-sized and allow more
entries than explicitly defined. This can be restricted by defining 'minItems',
'maxItems', and 'additionalItems'. However, for DeviceTree Schemas, a fixed
size is desired in most cases, so these properties are added based on the
number of entries in an 'items' list.

The YAML Devicetree format also makes all string values an array and scalar
values a matrix (in order to define groupings) even when only a single value
is present. Single entries in schemas are fixed up to match this encoding.

Coding style
------------

Use YAML coding style (two-space indentation). For DTS examples in the schema,
preferred is four-space indentation.

Testing
-------

Dependencies
~~~~~~~~~~~~

The DT schema project must be installed in order to validate the DT schema
binding documents and validate DTS files using the DT schema. The DT schema
project can be installed with pip::

    pip3 install dtschema

Note that 'dtschema' installation requires 'swig' and Python development files
installed first. On Debian/Ubuntu systems::

    apt install swig python3-dev

Several executables (dt-doc-validate, dt-mk-schema, dt-validate) will be
installed. Ensure they are in your PATH (~/.local/bin by default).

Recommended is also to install yamllint (used by dtschema when present).

Running checks
~~~~~~~~~~~~~~

The DT schema binding documents must be validated using the meta-schema (the
schema for the schema) to ensure they are both valid json-schema and valid
binding schema. All of the DT binding documents can be validated using the
``dt_binding_check`` target::

    make dt_binding_check

In order to perform validation of DT source files, use the ``dtbs_check`` target::

    make dtbs_check

Note that ``dtbs_check`` will skip any binding schema files with errors. It is
necessary to use ``dt_binding_check`` to get all the validation errors in the
binding schema files.

It is possible to run both in a single command::

    make dt_binding_check dtbs_check

It is also possible to run checks with a subset of matching schema files by
setting the ``DT_SCHEMA_FILES`` variable to a specific schema file or pattern.

::

    make dt_binding_check DT_SCHEMA_FILES=trivial-devices.yaml
    make dt_binding_check DT_SCHEMA_FILES=/gpio/
    make dtbs_check DT_SCHEMA_FILES=trivial-devices.yaml

json-schema Resources
---------------------

`JSON-Schema Specifications <http://json-schema.org/>`_

`Using JSON Schema Book <http://usingjsonschema.com/>`_

.. _example-schema:

Annotated Example Schema
------------------------

Also available as a separate file: :download:`example-schema.yaml`

.. literalinclude:: example-schema.yaml


code:
CE4100 Device Tree Bindings
---------------------------

The CE4100 SoC uses for in core peripherals the following compatible
format: <vendor>,<chip>-<device>.
Many of the "generic" devices like HPET or IO APIC have the ce4100
name in their compatible property because they first appeared in this
SoC.

The CPU nodes
-------------

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

		cpu@0 {
			device_type = "cpu";
			compatible = "intel,ce4100";
			reg = <0x00>;
		};

		cpu@2 {
			device_type = "cpu";
			compatible = "intel,ce4100";
			reg = <0x02>;
		};
	};

A "cpu" node describes one logical processor (hardware thread).

Required properties:

- device_type
	Device type, must be "cpu".

- reg
	Local APIC ID, the unique number assigned to each processor by
	system hardware.

The SoC node
------------

This node describes the in-core peripherals. Required property:
  compatible = "intel,ce4100-cp";

The PCI node
------------
This node describes the PCI bus on the SoC. Its property should be
  compatible = "intel,ce4100-pci", "pci";

If the OS is using the IO-APIC for interrupt routing then the reported
interrupt numbers for devices is no longer true. In order to obtain the
correct interrupt number, the child node which represents the device has
to contain the interrupt property. Besides the interrupt property it has
to contain at least the reg property containing the PCI bus address and
compatible property according to "PCI Bus Binding Revision 2.1".


code:
Timers
------

* High Precision Event Timer (HPET)
  Required property:
     compatible = "intel,ce4100-hpet";


code:
   d) Xilinx IP cores

   The Xilinx EDK toolchain ships with a set of IP cores (devices) for use
   in Xilinx Spartan and Virtex FPGAs.  The devices cover the whole range
   of standard device types (network, serial, etc.) and miscellaneous
   devices (gpio, LCD, spi, etc).  Also, since these devices are
   implemented within the fpga fabric every instance of the device can be
   synthesised with different options that change the behaviour.

   Each IP-core has a set of parameters which the FPGA designer can use to
   control how the core is synthesized.  Historically, the EDK tool would
   extract the device parameters relevant to device drivers and copy them
   into an 'xparameters.h' in the form of #define symbols.  This tells the
   device drivers how the IP cores are configured, but it requires the kernel
   to be recompiled every time the FPGA bitstream is resynthesized.

   The new approach is to export the parameters into the device tree and
   generate a new device tree each time the FPGA bitstream changes.  The
   parameters which used to be exported as #defines will now become
   properties of the device node.  In general, device nodes for IP-cores
   will take the following form:

	(name): (generic-name)@(base-address) {
		compatible = "xlnx,(ip-core-name)-(HW_VER)"
			     [, (list of compatible devices), ...];
		reg = <(baseaddr) (size)>;
		interrupt-parent = <&interrupt-controller-phandle>;
		interrupts = < ... >;
		xlnx,(parameter1) = "(string-value)";
		xlnx,(parameter2) = <(int-value)>;
	};

	(generic-name):   an open firmware-style name that describes the
			generic class of device.  Preferably, this is one word, such
			as 'serial' or 'ethernet'.
	(ip-core-name):	the name of the ip block (given after the BEGIN
			directive in system.mhs).  Should be in lowercase
			and all underscores '_' converted to dashes '-'.
	(name):		is derived from the "PARAMETER INSTANCE" value.
	(parameter#):	C_* parameters from system.mhs.  The C_ prefix is
			dropped from the parameter name, the name is converted
			to lowercase and all underscore '_' characters are
			converted to dashes '-'.
	(baseaddr):	the baseaddr parameter value (often named C_BASEADDR).
	(HW_VER):	from the HW_VER parameter.
	(size):		the address range size (often C_HIGHADDR - C_BASEADDR + 1).

   Typically, the compatible list will include the exact IP core version
   followed by an older IP core version which implements the same
   interface or any other device with the same interface.

   'reg' and 'interrupts' are all optional properties.

   For example, the following block from system.mhs:

	BEGIN opb_uartlite
		PARAMETER INSTANCE = opb_uartlite_0
		PARAMETER HW_VER = 1.00.b
		PARAMETER C_BAUDRATE = 115200
		PARAMETER C_DATA_BITS = 8
		PARAMETER C_ODD_PARITY = 0
		PARAMETER C_USE_PARITY = 0
		PARAMETER C_CLK_FREQ = 50000000
		PARAMETER C_BASEADDR = 0xEC100000
		PARAMETER C_HIGHADDR = 0xEC10FFFF
		BUS_INTERFACE SOPB = opb_7
		PORT OPB_Clk = CLK_50MHz
		PORT Interrupt = opb_uartlite_0_Interrupt
		PORT RX = opb_uartlite_0_RX
		PORT TX = opb_uartlite_0_TX
		PORT OPB_Rst = sys_bus_reset_0
	END

   becomes the following device tree node:

	opb_uartlite_0: serial@ec100000 {
		device_type = "serial";
		compatible = "xlnx,opb-uartlite-1.00.b";
		reg = <ec100000 10000>;
		interrupt-parent = <&opb_intc_0>;
		interrupts = <1 0>; // got this from the opb_intc parameters
		current-speed = <d#115200>;	// standard serial device prop
		clock-frequency = <d#50000000>;	// standard serial device prop
		xlnx,data-bits = <8>;
		xlnx,odd-parity = <0>;
		xlnx,use-parity = <0>;
	};

   That covers the general approach to binding xilinx IP cores into the
   device tree.  The following are bindings for specific devices:

      i) Xilinx ML300 Framebuffer

      Simple framebuffer device from the ML300 reference design (also on the
      ML403 reference design as well as others).

      Optional properties:
       - resolution = <xres yres> : pixel resolution of framebuffer.  Some
                                    implementations use a different resolution.
                                    Default is <d#640 d#480>
       - virt-resolution = <xvirt yvirt> : Size of framebuffer in memory.
                                           Default is <d#1024 d#480>.
       - rotate-display (empty) : rotate display 180 degrees.

      ii) Xilinx SystemACE

      The Xilinx SystemACE device is used to program FPGAs from an FPGA
      bitstream stored on a CF card.  It can also be used as a generic CF
      interface device.

      Optional properties:
       - 8-bit (empty) : Set this property for SystemACE in 8 bit mode

      iii) Xilinx EMAC and Xilinx TEMAC

      Xilinx Ethernet devices.  In addition to general xilinx properties
      listed above, nodes for these devices should include a phy-handle
      property, and may include other common network device properties
      like local-mac-address.

      iv) Xilinx Uartlite

      Xilinx uartlite devices are simple fixed speed serial ports.

      Required properties:
       - current-speed : Baud rate of uartlite

      v) Xilinx hwicap

		Xilinx hwicap devices provide access to the configuration logic
		of the FPGA through the Internal Configuration Access Port
		(ICAP).  The ICAP enables partial reconfiguration of the FPGA,
		readback of the configuration information, and some control over
		'warm boots' of the FPGA fabric.

		Required properties:
		- xlnx,family : The family of the FPGA, necessary since the
                      capabilities of the underlying ICAP hardware
                      differ between different families.  May be
                      'virtex2p', 'virtex4', or 'virtex5'.
		- compatible : should contain "xlnx,xps-hwicap-1.00.a" or
				"xlnx,opb-hwicap-1.00.b".

      vi) Xilinx Uart 16550

      Xilinx UART 16550 devices are very similar to the NS16550 but with
      different register spacing and an offset from the base address.

      Required properties:
       - clock-frequency : Frequency of the clock input
       - reg-offset : A value of 3 is required
       - reg-shift : A value of 2 is required

      vii) Xilinx USB Host controller

      The Xilinx USB host controller is EHCI compatible but with a different
      base address for the EHCI registers, and it is always a big-endian
      USB Host controller. The hardware can be configured as high speed only,
      or high speed/full speed hybrid.

      Required properties:
      - xlnx,support-usb-fs: A value 0 means the core is built as high speed
                             only. A value 1 means the core also supports
                             full speed devices.


code:
* Xillybus driver for generic FPGA interface

Required properties:
- compatible: Should be "xillybus,xillybus-1.00.a"
- reg: Address and length of the register set for the device
- interrupts: Contains one interrupt node, typically consisting of three cells.

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

Example:

	xillybus@ff200400 {
		compatible = "xillybus,xillybus-1.00.a";
		reg = < 0xff200400 0x00000080 >;
		interrupts = < 0 40 1 >;
		interrupt-parent = <&intc>;
	} ;


code:
.. SPDX-License-Identifier: GPL-2.0

=====================
Devicetree Changesets
=====================

A Devicetree changeset is a method which allows one to apply changes
in the live tree in such a way that either the full set of changes
will be applied, or none of them will be. If an error occurs partway
through applying the changeset, then the tree will be rolled back to the
previous state. A changeset can also be removed after it has been
applied.

When a changeset is applied, all of the changes get applied to the tree
at once before emitting OF_RECONFIG notifiers. This is so that the
receiver sees a complete and consistent state of the tree when it
receives the notifier.

The sequence of a changeset is as follows.

1. of_changeset_init() - initializes a changeset

2. A number of DT tree change calls, of_changeset_attach_node(),
   of_changeset_detach_node(), of_changeset_add_property(),
   of_changeset_remove_property, of_changeset_update_property() to prepare
   a set of changes. No changes to the active tree are made at this point.
   All the change operations are recorded in the of_changeset 'entries'
   list.

3. of_changeset_apply() - Apply the changes to the tree. Either the
   entire changeset will get applied, or if there is an error the tree will
   be restored to the previous state. The core ensures proper serialization
   through locking. An unlocked version __of_changeset_apply is available,
   if needed.

If a successfully applied changeset needs to be removed, it can be done
with of_changeset_revert().


code:
.. SPDX-License-Identifier: GPL-2.0

=================================
Devicetree Dynamic Resolver Notes
=================================

This document describes the implementation of the in-kernel
DeviceTree resolver, residing in drivers/of/resolver.c

How the resolver works
----------------------

The resolver is given as an input an arbitrary tree compiled with the
proper dtc option and having a /plugin/ tag. This generates the
appropriate __fixups__ & __local_fixups__ nodes.

In sequence the resolver works by the following steps:

1. Get the maximum device tree phandle value from the live tree + 1.
2. Adjust all the local phandles of the tree to resolve by that amount.
3. Using the __local__fixups__ node information adjust all local references
   by the same amount.
4. For each property in the __fixups__ node locate the node it references
   in the live tree. This is the label used to tag the node.
5. Retrieve the phandle of the target of the fixup.
6. For each fixup in the property locate the node:property:offset location
   and replace it with the phandle value.


code:
.. SPDX-License-Identifier: GPL-2.0

=============================
Open Firmware and Devicetree
=============================

Kernel Devicetree Usage
=======================
.. toctree::
   :maxdepth: 1

   usage-model
   of_unittest
   kernel-api

Devicetree Overlays
===================
.. toctree::
   :maxdepth: 1

   changesets
   dynamic-resolution-notes
   overlay-notes

Devicetree Bindings
===================
.. toctree::
   :maxdepth: 1

   bindings/index


code:
.. SPDX-License-Identifier: GPL-2.0
.. _devicetree:

======================================
DeviceTree Kernel API
======================================

Core functions
--------------

.. kernel-doc:: drivers/of/base.c
   :export:

.. kernel-doc:: include/linux/of.h
   :internal:

.. kernel-doc:: drivers/of/property.c
   :export:

.. kernel-doc:: include/linux/of_graph.h
   :internal:

.. kernel-doc:: drivers/of/address.c
   :export:

.. kernel-doc:: drivers/of/irq.c
   :export:

.. kernel-doc:: drivers/of/fdt.c
   :export:

Driver model functions
----------------------

.. kernel-doc:: include/linux/of_device.h
   :internal:

.. kernel-doc:: drivers/of/device.c
   :export:

.. kernel-doc:: include/linux/of_platform.h
   :internal:

.. kernel-doc:: drivers/of/platform.c
   :export:

Overlay and Dynamic DT functions
--------------------------------

.. kernel-doc:: drivers/of/resolver.c
   :export:

.. kernel-doc:: drivers/of/dynamic.c
   :export:

.. kernel-doc:: drivers/of/overlay.c
   :export:


code:
.. SPDX-License-Identifier: GPL-2.0

=================================
Open Firmware Devicetree Unittest
=================================

Author: Gaurav Minocha <gaurav.minocha.os@gmail.com>

1. Introduction
===============

This document explains how the test data required for executing OF unittest
is attached to the live tree dynamically, independent of the machine's
architecture.

It is recommended to read the following documents before moving ahead.

(1) Documentation/devicetree/usage-model.rst
(2) http://www.devicetree.org/Device_Tree_Usage

OF Selftest has been designed to test the interface (include/linux/of.h)
provided to device driver developers to fetch the device information..etc.
from the unflattened device tree data structure. This interface is used by
most of the device drivers in various use cases.

2. Verbose Output (EXPECT)
==========================

If unittest detects a problem it will print a warning or error message to
the console.  Unittest also triggers warning and error messages from other
kernel code as a result of intentionally bad unittest data.  This has led
to confusion as to whether the triggered messages are an expected result
of a test or whether there is a real problem that is independent of unittest.

'EXPECT \ : text' (begin) and 'EXPECT / : text' (end) messages have been
added to unittest to report that a warning or error is expected.  The
begin is printed before triggering the warning or error, and the end is
printed after triggering the warning or error.

The EXPECT messages result in very noisy console messages that are difficult
to read.  The script scripts/dtc/of_unittest_expect was created to filter
this verbosity and highlight mismatches between triggered warnings and
errors vs expected warnings and errors.  More information is available
from 'scripts/dtc/of_unittest_expect --help'.

3. Test-data
============

The Device Tree Source file (drivers/of/unittest-data/testcases.dts) contains
the test data required for executing the unit tests automated in
drivers/of/unittest.c. Currently, following Device Tree Source Include files
(.dtsi) are included in testcases.dts::

    drivers/of/unittest-data/tests-interrupts.dtsi
    drivers/of/unittest-data/tests-platform.dtsi
    drivers/of/unittest-data/tests-phandle.dtsi
    drivers/of/unittest-data/tests-match.dtsi

When the kernel is build with OF_SELFTEST enabled, then the following make
rule::

    $(obj)/%.dtb: $(src)/%.dts FORCE
	    $(call if_changed_dep, dtc)

is used to compile the DT source file (testcases.dts) into a binary blob
(testcases.dtb), also referred as flattened DT.

After that, using the following rule the binary blob above is wrapped as an
assembly file (testcases.dtb.S)::

    $(obj)/%.dtb.S: $(obj)/%.dtb
	    $(call cmd, dt_S_dtb)

The assembly file is compiled into an object file (testcases.dtb.o), and is
linked into the kernel image.

3.1. Adding the test data
-------------------------

Un-flattened device tree structure:

Un-flattened device tree consists of connected device_node(s) in form of a tree
structure described below::

    // following struct members are used to construct the tree
    struct device_node {
	...
	struct  device_node *parent;
	struct  device_node *child;
	struct  device_node *sibling;
	...
    };

Figure 1, describes a generic structure of machine's un-flattened device tree
considering only child and sibling pointers. There exists another pointer,
``*parent``, that is used to traverse the tree in the reverse direction. So, at
a particular level the child node and all the sibling nodes will have a parent
pointer pointing to a common node (e.g. child1, sibling2, sibling3, sibling4's
parent points to root node)::

    root ('/')
    |
    child1 -> sibling2 -> sibling3 -> sibling4 -> null
    |         |           |           |
    |         |           |          null
    |         |           |
    |         |        child31 -> sibling32 -> null
    |         |           |          |
    |         |          null       null
    |         |
    |      child21 -> sibling22 -> sibling23 -> null
    |         |          |            |
    |        null       null         null
    |
    child11 -> sibling12 -> sibling13 -> sibling14 -> null
    |           |           |            |
    |           |           |           null
    |           |           |
    null        null       child131 -> null
			    |
			    null

Figure 1: Generic structure of un-flattened device tree

Before executing OF unittest, it is required to attach the test data to
machine's device tree (if present). So, when selftest_data_add() is called,
at first it reads the flattened device tree data linked into the kernel image
via the following kernel symbols::

    __dtb_testcases_begin - address marking the start of test data blob
    __dtb_testcases_end   - address marking the end of test data blob

Secondly, it calls of_fdt_unflatten_tree() to unflatten the flattened
blob. And finally, if the machine's device tree (i.e live tree) is present,
then it attaches the unflattened test data tree to the live tree, else it
attaches itself as a live device tree.

attach_node_and_children() uses of_attach_node() to attach the nodes into the
live tree as explained below. To explain the same, the test data tree described
in Figure 2 is attached to the live tree described in Figure 1::

    root ('/')
	|
    testcase-data
	|
    test-child0 -> test-sibling1 -> test-sibling2 -> test-sibling3 -> null
	|               |                |                |
    test-child01      null             null             null

Figure 2: Example test data tree to be attached to live tree.

According to the scenario above, the live tree is already present so it isn't
required to attach the root('/') node. All other nodes are attached by calling
of_attach_node() on each node.

In the function of_attach_node(), the new node is attached as the child of the
given parent in live tree. But, if parent already has a child then the new node
replaces the current child and turns it into its sibling. So, when the testcase
data node is attached to the live tree above (Figure 1), the final structure is
as shown in Figure 3::

    root ('/')
    |
    testcase-data -> child1 -> sibling2 -> sibling3 -> sibling4 -> null
    |               |          |           |           |
    (...)             |          |           |          null
		    |          |         child31 -> sibling32 -> null
		    |          |           |           |
		    |          |          null        null
		    |          |
		    |        child21 -> sibling22 -> sibling23 -> null
		    |          |           |            |
		    |         null        null         null
		    |
		    child11 -> sibling12 -> sibling13 -> sibling14 -> null
		    |          |            |            |
		    null       null          |           null
					    |
					    child131 -> null
					    |
					    null
    -----------------------------------------------------------------------

    root ('/')
    |
    testcase-data -> child1 -> sibling2 -> sibling3 -> sibling4 -> null
    |               |          |           |           |
    |             (...)      (...)       (...)        null
    |
    test-sibling3 -> test-sibling2 -> test-sibling1 -> test-child0 -> null
    |                |                   |                |
    null             null                null         test-child01

Figure 3: Live device tree structure after attaching the testcase-data.

Astute readers would have noticed that test-child0 node becomes the last
sibling compared to the earlier structure (Figure 2). After attaching first
test-child0 the test-sibling1 is attached that pushes the child node
(i.e. test-child0) to become a sibling and makes itself a child node,
as mentioned above.

If a duplicate node is found (i.e. if a node with same full_name property is
already present in the live tree), then the node isn't attached rather its
properties are updated to the live tree's node by calling the function
update_node_properties().

3.2. Removing the test data
---------------------------

Once the test case execution is complete, selftest_data_remove is called in
order to remove the device nodes attached initially (first the leaf nodes are
detached and then moving up the parent nodes are removed, and eventually the
whole tree). selftest_data_remove() calls detach_node_and_children() that uses
of_detach_node() to detach the nodes from the live device tree.

To detach a node, of_detach_node() either updates the child pointer of given
node's parent to its sibling or attaches the previous sibling to the given
node's sibling, as appropriate. That is it :)


code:
.. SPDX-License-Identifier: GPL-2.0

========================
Devicetree Overlay Notes
========================

This document describes the implementation of the in-kernel
device tree overlay functionality residing in drivers/of/overlay.c and is a
companion document to Documentation/devicetree/dynamic-resolution-notes.rst[1]

How overlays work
-----------------

A Devicetree's overlay purpose is to modify the kernel's live tree, and
have the modification affecting the state of the kernel in a way that
is reflecting the changes.
Since the kernel mainly deals with devices, any new device node that result
in an active device should have it created while if the device node is either
disabled or removed all together, the affected device should be deregistered.

Lets take an example where we have a foo board with the following base tree::

    ---- foo.dts ---------------------------------------------------------------
	/* FOO platform */
	/dts-v1/;
	/ {
		compatible = "corp,foo";

		/* shared resources */
		res: res {
		};

		/* On chip peripherals */
		ocp: ocp {
			/* peripherals that are always instantiated */
			peripheral1 { ... };
		};
	};
    ---- foo.dts ---------------------------------------------------------------

The overlay bar.dts,
::

    ---- bar.dts - overlay target location by label ----------------------------
	/dts-v1/;
	/plugin/;
	&ocp {
		/* bar peripheral */
		bar {
			compatible = "corp,bar";
			... /* various properties and child nodes */
		};
	};
    ---- bar.dts ---------------------------------------------------------------

when loaded (and resolved as described in [1]) should result in foo+bar.dts::

    ---- foo+bar.dts -----------------------------------------------------------
	/* FOO platform + bar peripheral */
	/ {
		compatible = "corp,foo";

		/* shared resources */
		res: res {
		};

		/* On chip peripherals */
		ocp: ocp {
			/* peripherals that are always instantiated */
			peripheral1 { ... };

			/* bar peripheral */
			bar {
				compatible = "corp,bar";
				... /* various properties and child nodes */
			};
		};
	};
    ---- foo+bar.dts -----------------------------------------------------------

As a result of the overlay, a new device node (bar) has been created
so a bar platform device will be registered and if a matching device driver
is loaded the device will be created as expected.

If the base DT was not compiled with the -@ option then the "&ocp" label
will not be available to resolve the overlay node(s) to the proper location
in the base DT. In this case, the target path can be provided. The target
location by label syntax is preferred because the overlay can be applied to
any base DT containing the label, no matter where the label occurs in the DT.

The above bar.dts example modified to use target path syntax is::

    ---- bar.dts - overlay target location by explicit path --------------------
	/dts-v1/;
	/plugin/;
	&{/ocp} {
		/* bar peripheral */
		bar {
			compatible = "corp,bar";
			... /* various properties and child nodes */
		}
	};
    ---- bar.dts ---------------------------------------------------------------

Overlay in-kernel API
--------------------------------

The API is quite easy to use.

1) Call of_overlay_fdt_apply() to create and apply an overlay changeset. The
   return value is an error or a cookie identifying this overlay.

2) Call of_overlay_remove() to remove and cleanup the overlay changeset
   previously created via the call to of_overlay_fdt_apply(). Removal of an
   overlay changeset that is stacked by another will not be permitted.

Finally, if you need to remove all overlays in one-go, just call
of_overlay_remove_all() which will remove every single one in the correct
order.

There is the option to register notifiers that get called on
overlay operations. See of_overlay_notifier_register/unregister and
enum of_overlay_notify_action for details.

A notifier callback for OF_OVERLAY_PRE_APPLY, OF_OVERLAY_POST_APPLY, or
OF_OVERLAY_PRE_REMOVE may store pointers to a device tree node in the overlay
or its content but these pointers must not persist past the notifier callback
for OF_OVERLAY_POST_REMOVE.  The memory containing the overlay will be
kfree()ed after OF_OVERLAY_POST_REMOVE notifiers are called.  Note that the
memory will be kfree()ed even if the notifier for OF_OVERLAY_POST_REMOVE
returns an error.

The changeset notifiers in drivers/of/dynamic.c are a second type of notifier
that could be triggered by applying or removing an overlay.  These notifiers
are not allowed to store pointers to a device tree node in the overlay
or its content.  The overlay code does not protect against such pointers
remaining active when the memory containing the overlay is freed as a result
of removing the overlay.

Any other code that retains a pointer to the overlay nodes or data is
considered to be a bug because after removing the overlay the pointer
will refer to freed memory.

Users of overlays must be especially aware of the overall operations that
occur on the system to ensure that other kernel code does not retain any
pointers to the overlay nodes or data.  Any example of an inadvertent use
of such pointers is if a driver or subsystem module is loaded after an
overlay has been applied, and the driver or subsystem scans the entire
devicetree or a large portion of it, including the overlay nodes.