From 4dbfe54674859e67b3564ace6cd8a384dfb997ad Mon Sep 17 00:00:00 2001 From: Tejas Mutalikdesai Date: Thu, 18 Jun 2026 20:41:46 +0530 Subject: [PATCH] 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. Allow a unit-address so this can be addressed and the dtc warnings can be avoided in the example. Signed-off-by: Tejas Mutalikdesai Link: https://patch.msgid.link/20260618151147.9438-1-tejasmutalikdesai@gmail.com [robh: Allow a unit-address] Signed-off-by: Rob Herring (Arm) --- Documentation/devicetree/bindings/arm/xen.txt | 62 ---------- .../devicetree/bindings/arm/xen.yaml | 110 ++++++++++++++++++ 2 files changed, 110 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-", "xen,xen"; - where 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..bad077a112c9 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/xen.yaml @@ -0,0 +1,110 @@ +# 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 + +description: + Xen ARM virtual platforms shall have a top-level "hypervisor" node with + the properties defined below. + +properties: + $nodename: + pattern: '^hypervisor(@[0-9a-f]+)?$' + + compatible: + description: + Specifies the Xen hypervisor. The version of the Xen ABI is encoded + in the first item as "xen,xen-", 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@b0000000 { + 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>; + }; + }; +...