[PATCH v5 1/2] dt-bindings: arm: xen: Convert to DT schema

[PATCH v5 1/2] dt-bindings: arm: xen: Convert to DT schema

[Tejas Mutalikdesai]

Convert the Xen ARM device tree binding documentation from the legacy
plain-text format (Documentation/devicetree/bindings/arm/xen.txt) to
the DT schema format, as required by the modern DT binding process.

The "hypervisor" node is named without a unit-address. The name is part
of the Xen ABI and is matched verbatim by the kernel using strcmp() in
arch/arm/xen/enlighten.c and arch/arm64/kernel/acpi.c, so $nodename uses
'const: hypervisor'. The node has a reg but no unit-address, so dtc emits
a non-fatal unit_address_vs_reg warning on the example; this is inherent
to the existing binding and is not introduced by the conversion.

Signed-off-by: Tejas Mutalikdesai <tejasmutalikdesai@gmail.com>
---
The bare node name "hypervisor" (no unit-address) is deliberate:

1. The legacy binding (xen.txt, commit c43cdfbc4ceb, authored by the Xen
   ARM maintainer in 2012) documents the node and its example as a bare
   "hypervisor".

2. The kernel locates the node by exact name, not by unit-address:
     arch/arm/xen/enlighten.c:   strcmp(uname, "hypervisor")
     arch/arm64/kernel/acpi.c:   strcmp(name,  "hypervisor")
   fdt_get_name() returns the full name including any "@unit", so a
   "hypervisor@..." node would fail these comparisons and Xen init would
   silently not find the node.

3. The in-tree template arch/arm/boot/dts/xen/xenvm-4.2.dts uses a bare
   "hypervisor" node and has done so since it was added.

4. The dtc unit_address_vs_reg warning is pre-existing: compiling
   xenvm-4.2.dts today already emits it. Mandating a unit-address in the
   schema would instead regress dtbs_check for that in-tree DTB and
   describe a node form the kernel cannot consume.

Per the DT spec a unit-address is grammatically permitted (node-name is
the part before '@'), but making it mandatory is not viable until the
kernel matchers and the Xen-generated FDT are updated in lockstep, which
is out of scope for this binding conversion.

Changes since v4:
- Revert the v4 $nodename unit-address requirement to 'const: hypervisor'
  (see rationale above).

Changes since v2:
- s/YAML schema/DT schema/ in the commit text
- Drop unnecessary '|' block scalars from descriptions
- Split the arch/arm/xen/enlighten.c doc-reference update into patch 2/2

 Documentation/devicetree/bindings/arm/xen.txt |  62 ----------
 .../devicetree/bindings/arm/xen.yaml          | 109 ++++++++++++++++++
 2 files changed, 109 insertions(+), 62 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/arm/xen.txt
 create mode 100644 Documentation/devicetree/bindings/arm/xen.yaml

diff --git a/Documentation/devicetree/bindings/arm/xen.txt b/Documentation/devicetree/bindings/arm/xen.txt
deleted file mode 100644
index f925290d4641..000000000000
--- a/Documentation/devicetree/bindings/arm/xen.txt
+++ /dev/null
@@ -1,62 +0,0 @@
-* Xen hypervisor device tree bindings
-
-Xen ARM virtual platforms shall have a top-level "hypervisor" node with
-the following properties:
-
-- compatible:
-	compatible = "xen,xen-<version>", "xen,xen";
-  where <version> is the version of the Xen ABI of the platform.
-
-- reg: specifies the base physical address and size of the regions in memory
-  where the special resources should be mapped to, using an HYPERVISOR_memory_op
-  hypercall.
-  Region 0 is reserved for mapping grant table, it must be always present.
-  The memory region is large enough to map the whole grant table (it is larger
-  or equal to gnttab_max_grant_frames()).
-  Regions 1...N are extended regions (unused address space) for mapping foreign
-  GFNs and grants, they might be absent if there is nothing to expose.
-
-- interrupts: the interrupt used by Xen to inject event notifications.
-  A GIC node is also required.
-
-To support UEFI on Xen ARM virtual platforms, Xen populates the FDT "uefi" node
-under /hypervisor with following parameters:
-
-________________________________________________________________________________
-Name                      | Size   | Description
-================================================================================
-xen,uefi-system-table     | 64-bit | Guest physical address of the UEFI System
-			  |	   | Table.
---------------------------------------------------------------------------------
-xen,uefi-mmap-start       | 64-bit | Guest physical address of the UEFI memory
-			  |	   | map.
---------------------------------------------------------------------------------
-xen,uefi-mmap-size        | 32-bit | Size in bytes of the UEFI memory map
-                          |        | pointed to in previous entry.
---------------------------------------------------------------------------------
-xen,uefi-mmap-desc-size   | 32-bit | Size in bytes of each entry in the UEFI
-                          |        | memory map.
---------------------------------------------------------------------------------
-xen,uefi-mmap-desc-ver    | 32-bit | Version of the mmap descriptor format.
---------------------------------------------------------------------------------
-
-Example (assuming #address-cells = <2> and #size-cells = <2>):
-
-hypervisor {
-	compatible = "xen,xen-4.3", "xen,xen";
-	reg = <0 0xb0000000 0 0x20000>;
-	interrupts = <1 15 0xf08>;
-	uefi {
-		xen,uefi-system-table = <0xXXXXXXXX>;
-		xen,uefi-mmap-start = <0xXXXXXXXX>;
-		xen,uefi-mmap-size = <0xXXXXXXXX>;
-		xen,uefi-mmap-desc-size = <0xXXXXXXXX>;
-		xen,uefi-mmap-desc-ver = <0xXXXXXXXX>;
-        };
-};
-
-The format and meaning of the "xen,uefi-*" parameters are similar to those in
-Documentation/arch/arm/uefi.rst, which are provided by the regular UEFI stub. However
-they differ because they are provided by the Xen hypervisor, together with a set
-of UEFI runtime services implemented via hypercalls, see
-http://xenbits.xen.org/docs/unstable/hypercall/x86_64/include,public,platform.h.html.
diff --git a/Documentation/devicetree/bindings/arm/xen.yaml b/Documentation/devicetree/bindings/arm/xen.yaml
new file mode 100644
index 000000000000..4eeadb8ae106
--- /dev/null
+++ b/Documentation/devicetree/bindings/arm/xen.yaml
@@ -0,0 +1,109 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/arm/xen.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Xen hypervisor
+
+maintainers:
+  - Stefano Stabellini <sstabellini@kernel.org>
+
+description:
+  Xen ARM virtual platforms shall have a top-level "hypervisor" node with
+  the properties defined below.
+
+properties:
+  $nodename:
+    const: hypervisor
+
+  compatible:
+    description:
+      Specifies the Xen hypervisor. The version of the Xen ABI is encoded
+      in the first item as "xen,xen-<version>", followed by the generic
+      "xen,xen" string.
+    items:
+      - pattern: "^xen,xen-[0-9]+\\.[0-9]+$"
+      - const: xen,xen
+
+  reg:
+    description: |
+      Base physical address and size of the regions in memory where special
+      resources should be mapped to, using a HYPERVISOR_memory_op hypercall.
+
+      Region 0 is reserved for mapping the grant table and must always be
+      present. The memory region must be large enough to map the whole grant
+      table (it is larger or equal to gnttab_max_grant_frames()).
+
+      Regions 1...N are extended regions (unused address space) for mapping
+      foreign GFNs and grants. They might be absent if there is nothing to
+      expose.
+    minItems: 1
+
+  interrupts:
+    description:
+      The interrupt used by Xen to inject event notifications.
+      A GIC node is also required.
+    maxItems: 1
+
+  uefi:
+    type: object
+    description:
+      Node populated by Xen to support UEFI on Xen ARM virtual platforms.
+      The format and meaning of the "xen,uefi-*" parameters are similar to
+      those in Documentation/arch/arm/uefi.rst, but are provided by the Xen
+      hypervisor together with a set of UEFI runtime services implemented via
+      hypercalls.
+    properties:
+      xen,uefi-system-table:
+        description: Guest physical address of the UEFI System Table.
+        $ref: /schemas/types.yaml#/definitions/uint64
+
+      xen,uefi-mmap-start:
+        description: Guest physical address of the UEFI memory map.
+        $ref: /schemas/types.yaml#/definitions/uint64
+
+      xen,uefi-mmap-size:
+        description: Size in bytes of the UEFI memory map pointed to by xen,uefi-mmap-start.
+        $ref: /schemas/types.yaml#/definitions/uint32
+
+      xen,uefi-mmap-desc-size:
+        description: Size in bytes of each entry in the UEFI memory map.
+        $ref: /schemas/types.yaml#/definitions/uint32
+
+      xen,uefi-mmap-desc-ver:
+        description: Version of the mmap descriptor format.
+        $ref: /schemas/types.yaml#/definitions/uint32
+
+    required:
+      - xen,uefi-system-table
+      - xen,uefi-mmap-start
+      - xen,uefi-mmap-size
+      - xen,uefi-mmap-desc-size
+      - xen,uefi-mmap-desc-ver
+
+    additionalProperties: false
+
+required:
+  - compatible
+  - reg
+  - interrupts
+
+additionalProperties: false
+
+examples:
+  - |
+    hypervisor {
+        compatible = "xen,xen-4.3", "xen,xen";
+        reg = <0xb0000000 0x20000>;
+        interrupts = <1 15 0xf08>;
+
+        uefi {
+            xen,uefi-system-table = /bits/ 64 <0x1301415>;
+            xen,uefi-mmap-start = /bits/ 64 <0x7591400>;
+            xen,uefi-mmap-size = <0x1800>;
+            xen,uefi-mmap-desc-size = <0x30>;
+            xen,uefi-mmap-desc-ver = <1>;
+        };
+    };
+...
-- 
2.54.0

[PATCH v5 2/2] arm/xen: Update DT binding documentation reference

[Tejas Mutalikdesai]

Update the comment in xen_early_init() to reference the new xen.yaml
schema after xen.txt was converted to the DT schema format.

Signed-off-by: Tejas Mutalikdesai <tejasmutalikdesai@gmail.com>
---
Split from patch 1/2 since v4 to keep the binding conversion separate
from the driver comment fix.

 arch/arm/xen/enlighten.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/arch/arm/xen/enlighten.c b/arch/arm/xen/enlighten.c
index 25a0ce3b4584..0b7b7e3417e3 100644
--- a/arch/arm/xen/enlighten.c
+++ b/arch/arm/xen/enlighten.c
@@ -251,7 +251,7 @@ static int __init fdt_find_hyper_node(unsigned long node, const char *uname,
 }
 
 /*
- * see Documentation/devicetree/bindings/arm/xen.txt for the
+ * see Documentation/devicetree/bindings/arm/xen.yaml for the
  * documentation of the Xen Device Tree format.
  */
 void __init xen_early_init(void)
-- 
2.54.0

Re: [PATCH v5 1/2] dt-bindings: arm: xen: Convert to DT schema

[Krzysztof Kozlowski]

On Thu, Jun 18, 2026 at 08:41:46PM +0530, Tejas Mutalikdesai wrote:
> Convert the Xen ARM device tree binding documentation from the legacy
> plain-text format (Documentation/devicetree/bindings/arm/xen.txt) to
> the DT schema format, as required by the modern DT binding process.
> 
> The "hypervisor" node is named without a unit-address. The name is part
> of the Xen ABI and is matched verbatim by the kernel using strcmp() in
> arch/arm/xen/enlighten.c and arch/arm64/kernel/acpi.c, so $nodename uses
> 'const: hypervisor'. The node has a reg but no unit-address, so dtc emits

Honestly, this is a violation of DT spec, chapter 2.2.1.1:

"The unit-address must match the first address specified in the reg
property of the node."

I understand that you did not introduce this, but you do introduce DTC
warning into bindings, which I think we do not allow. dt_binding_check
must be warning free.

If I understood correctly this broken behavior was introduced in commit
9b08aaa3199a4dffca73c7cdec813b483b5b2d3b. Without any explanation why a
correct method of matching/finding by compatible is changed into
INCORRECT (nodename is not proper ABI) finding by node name and ignoring
DT Spec.

That commit message is simply terrible. Tells one thing - move some code
- but does something completely different - introduces ABI for node
name! ABI which is heavily discouraged and plain wrong.

I don't have enough of words to express the poor quality of that commit.

That said, IMO, the Xen/driver code should be changed to conform to DT
spec. If Xen is not interested in conforming to DT spec, then we should
not have in it upstream Linux kernel. This is that simple. Xen does not
get exceptions.

I also get that task might be something more than you signed up for,
thus the binding should stay unconverted till someone wants to fixup
this broken Xen code.

Best regards,
Krzysztof

Re: [PATCH v5 1/2] dt-bindings: arm: xen: Convert to DT schema

[Rob Herring]

On Mon, Jun 22, 2026 at 09:48:08AM +0200, Krzysztof Kozlowski wrote:
> On Thu, Jun 18, 2026 at 08:41:46PM +0530, Tejas Mutalikdesai wrote:
> > Convert the Xen ARM device tree binding documentation from the legacy
> > plain-text format (Documentation/devicetree/bindings/arm/xen.txt) to
> > the DT schema format, as required by the modern DT binding process.
> > 
> > The "hypervisor" node is named without a unit-address. The name is part
> > of the Xen ABI and is matched verbatim by the kernel using strcmp() in
> > arch/arm/xen/enlighten.c and arch/arm64/kernel/acpi.c, so $nodename uses
> > 'const: hypervisor'. The node has a reg but no unit-address, so dtc emits
> 
> Honestly, this is a violation of DT spec, chapter 2.2.1.1:
> 
> "The unit-address must match the first address specified in the reg
> property of the node."
> 
> I understand that you did not introduce this, but you do introduce DTC
> warning into bindings, which I think we do not allow. dt_binding_check
> must be warning free.
> 
> If I understood correctly this broken behavior was introduced in commit
> 9b08aaa3199a4dffca73c7cdec813b483b5b2d3b. Without any explanation why a
> correct method of matching/finding by compatible is changed into
> INCORRECT (nodename is not proper ABI) finding by node name and ignoring
> DT Spec.
> 
> That commit message is simply terrible. Tells one thing - move some code
> - but does something completely different - introduces ABI for node
> name! ABI which is heavily discouraged and plain wrong.
> 
> I don't have enough of words to express the poor quality of that commit.
> 
> That said, IMO, the Xen/driver code should be changed to conform to DT
> spec. If Xen is not interested in conforming to DT spec, then we should
> not have in it upstream Linux kernel. This is that simple. Xen does not
> get exceptions.

The kernel has lots of things which are exceptions now (see PowerMac 
or anything older than 15 years). It's our fault for not having tools 
to check anything back then.
 
> I also get that task might be something more than you signed up for,
> thus the binding should stay unconverted till someone wants to fixup
> this broken Xen code.

I think we just update the nodename in the schema to allow (but not 
require) a unit-address and add one to the example and move on. It's not 
clear to me how much this is being used.

I've updated the schema to do that and applied. Patch 2 will need to go 
in Russell's patch system.

Rob