Skip to contentSkip to conversation

dt-bindings: arm: xen: Convert to DT schema

PATCH Superseded Tejas Mutalikdesai 2 participants 2 messages Jun 17

Subsystems (3)

v3 of 5 Superseded Latest is v5 →

lore
Share & tools
lore
#0 lore raw

PATCH v3 1/1 dt-bindings: arm: xen: Convert to DT schema

From: Tejas <[email protected]>

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.

---
Changes since v2:
- Replace 'YAML schema' with 'DT schema' in the commit description
- Drop unnecessary '|' block scalars from description fields that do not need to preserve literal formatting
- Fix unit_address_vs_reg warning: replace $nodename const with a pattern requiring a unit address; update example to hypervisor@b0000000 and drop the root node, GIC, and interrupt-parent
- Update Documentation reference in arch/arm/xen/enlighten.c from xen.txt to xen.yaml

 Documentation/devicetree/bindings/arm/xen.txt |  62 ----------
 .../devicetree/bindings/arm/xen.yaml          | 109 ++++++++++++++++++
 arch/arm/xen/enlighten.c                      |   2 +-
 3 files changed, 110 insertions(+), 63 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/arm/xen.txt
 create mode 100644 Documentation/devicetree/bindings/arm/xen.yaml
Documentation/devicetree/bindings/arm/xen.txt deleted +0 -62
deleted file mode 100644
index f925290d4641..000000000000
@@ -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.
Documentation/devicetree/bindings/arm/xen.yaml new file +109 -0

109 lines not on this page · raw message

arch/arm/xen/enlighten.c +1 -1
index 25a0ce3b4584..0b7b7e3417e3 100644
@@ -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)
Signature · 1 line
2.54.0
#1 lore raw
Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider: - [High] The new DT schema strictly enforces a unit address for the `hypervisor` node name…

Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider:
- [High] The new DT schema strictly enforces a unit address for the hypervisor node name (^hypervisor@[0-9a-f]+$). This causes make dtbs_check validation failures for existing in-tree DTS files and, if fixed in the DTS, will break Xen detection in the Linux kernel. --

commit 8184816dad4691fc686e16cca1b38c8628e65beb
Author: Tejas <[email protected]>

dt-bindings: arm: xen: Convert to DT schema

Convert the Xen ARM device tree binding documentation from the legacy plain-text format to the DT schema format.

Quoted 5 lines
Documentation/devicetree/bindings/arm/xen.yaml new file +0 -0
new file mode 100644
index 0000000000000..a22e950566c23

[ ... ]

Documentation/devicetree/bindings/arm/xen.yaml line 18

Quoted 7 lines
Documentation/devicetree/bindings/arm/xen.yaml new file +7 -0
+description:
+  Xen ARM virtual platforms shall have a top-level "hypervisor" node with
+  the properties defined below.
+
+properties:
+  $nodename:
+    pattern: "^hypervisor@[0-9a-f]+$"

[Severity: High]
Will this strict node name pattern break existing device trees and kernel parsing?

Existing in-tree device trees (like arch/arm/boot/dts/xen/xenvm-4.2.dts) use the node name "hypervisor" without a unit address, which will now fail schema validation under this pattern.

If device trees are updated to include a unit address to satisfy this new schema, will it break Xen paravirtualization on ARM? The kernel's FDT parsing explicitly requires an exact string match without a unit address during early initialization:

arch/arm/xen/enlighten.c:fdt_find_hyper_node() {
    ...
	if (depth != 1 || strcmp(uname, "hypervisor") != 0)
		return 0;
    ...
}
Quoted 3 lines
Documentation/devicetree/bindings/arm/xen.yaml new file +3 -0
+
+  compatible:
+    description:
Signature · 1 line
Sashiko AI review · https://sashiko.dev/#/patchset/[email protected]?part=1