Skip to contentSkip to conversation

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

PATCH In review Tejas Mutalikdesai 3 participants 4 messages Jun 18 – Jun 30

Subsystems (3)
lore
Share & tools
lore
#0 lore raw

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

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.

---
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
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

Signature · 1 line
2.54.0
#1 lore raw

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

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

---
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(-)
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
#2 lore raw
In reply to Tejas Mutalikdesai
Quoted 8 lines · 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

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

maintainer
#3 lore raw
Quoted 29 lines · Krzysztof Kozlowski
Quoted 8 lines · 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

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.

Quoted 6 lines

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.

Quoted 3 lines

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