Mailing List Archive

[PATCH] docs/design: boot domain device tree design
This is a Request For Comments on the adoption of Device Tree as the
format for the Launch Control Module as described in the previously
posted DomB RFC.

For RFC purposes, a rendered of this file can be found here:
https://drive.google.com/file/d/1FUv3U-KSB0H2X2tmBdv5Lt-6_BJm4nF1/view?usp=sharing

Details on the DomB boot domain can be found on Xen wiki:
https://wiki.xenproject.org/wiki/DomB_mode_of_dom0less

Signed-off-by: Daniel P. Smith <dpsmith@apertussolutions.com>
Signed-off-by: Christopher Clark <christopher.clark@starlab.io>
---
docs/designs/boot-domain-device-tree.rst | 163 +++++++++++++++++++++++++++++++
1 file changed, 163 insertions(+)
create mode 100644 docs/designs/boot-domain-device-tree.rst

diff --git a/docs/designs/boot-domain-device-tree.rst b/docs/designs/boot-domain-device-tree.rst
new file mode 100644
index 0000000000..fc3b8b30bf
--- /dev/null
+++ b/docs/designs/boot-domain-device-tree.rst
@@ -0,0 +1,163 @@
+====================================
+Xen Boot Domain Device Tree Bindings
+====================================
+
+The Xen Boot Domain device tree adopts the dom0less device tree structure and
+extends it to meet the requirements for the Boot Domain capability. The primary
+difference is the introduction of the ``xen`` node that is under the ``/chosen``
+node. The move to a dedicated node was driven by:
+
+1. Reduces the need to walk over nodes that are not of interest, e.g. only
+nodes of interest should be in ``/chosen/xen``
+
+2. Enables the use of the ``#address-cells`` and ``#size-cells`` fields on the
+xen node.
+
+Below is an example device tree definition for a xen node followed by an
+explanation of each section and field:
+::
+ xen {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ // Boot Domain definition
+ domain@0 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ compatible = "xen,domain";
+
+ reg = <0x7FF5>;
+ memory = <0x0 0x20000>;
+ cpus = <1>;
+ module@0 {
+ compatible = "multiboot,kernel", "multiboot,module";
+ reg = <1>;
+ };
+
+ module@1 {
+ compatible = "multiboot,ramdisk", "multiboot,module";
+ reg = <2>;
+ };
+ module@3 {
+ compatible = "multiboot,config", "multiboot,module";
+ reg = <3>;
+ };
+
+ // Classic Dom0 definition
+ domain@1 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ reg = <0>;
+
+ // PERMISSION_NONE (0)
+ // PERMISSION_CONTROL (1 << 0)
+ // PERMISSION_HARDWARE (1 << 1)
+ permissions = <3>;
+
+ // FUNCTION_NONE (0)
+ // FUNCTION_BOOT (1 << 1)
+ // FUNCTION_CRASH (1 << 2)
+ // FUNCTION_CONSOLE (1 << 3)
+ // FUNCTION_XENSTORE (1 << 30)
+ // FUNCTION_LEGACY_DOM0 (1 << 31)
+ functions = <0xFFFFFFFF>;
+
+ // MODE_PARAVIRTUALIZED (1 << 0) /* PV | PVH/HVM */
+ // MODE_ENABLE_DEVICE_MODEL (1 << 1) /* PVH | HVM */
+ mode = <1>;
+
+ // UUID
+ domain-handle = [.B3 FB 98 FB 8F 9F 67 A3 8A 6E 62 5A 09 13 F0 8C];
+
+ cpus = <1>;
+ memory = <0x0 0x20000>;
+ security-id = <0>;
+
+ module@0 {
+ compatible = "multiboot,kernel", "multiboot,module";
+ reg = <4>;
+ bootargs = "console=hv0";
+ };
+ module@1 {
+ compatible = "multiboot,ramdisk", "multiboot,module";
+ reg = <5>;
+ };
+ };
+
+The Xen node
+------------
+
+The xen node is a top level container for the domains that will be built by
+hypervisor on start up. On the ``xen`` node the ``#address-cells`` is set to one
+and the ``#size-cells`` is set to zero. This is done to enforce that each domain
+node must define a ``reg`` property and the hypervisor will use it to determine
+the ``domid`` for the domain.
+
+The Domain node
+----------------
+
+A domain node is for describing the construction of a domain. It is free to set
+the ``#address-cells`` and ``#size-cells`` depending on how the multiboot
+modules identified and located. If the multiboot modules will be located by
+index within the module chain, the values should be “1” and “0” respectively. If
+the multiboot module will be located by address, then the values should be “1”
+and “1” respectively.
+
+As previously mentioned a domain node must have a reg property which will be
+used as the requested domain id for the domain with a value of “0” signifying to
+use the next available domain id. After that a domain node may have any of the
+following parameters,
+
+reg
+ Identifies the domid to use for the domain. Required.
+
+permissions
+ This sets what Discretionary Access Control permissions a domain is assigned.
+ Optional, default is none.
+
+functions
+ This identifies what system functions a domain will fulfill. Optional, the
+ default is none.
+
+.. note:: The last two ``functions`` bits are used for ``FUNCTION_XENSTORE`` and ``FUNCTION_LEGACY_DOM0`` such that should these features ever be fully retired, the flags may be dropped without leaving a gap in the flag set.
+
+mode
+ The mode the domain will be executed under. Required.
+
+domain-handle
+ A globally unique identifier for the domain. Optional, the default is NULL.
+
+cpus
+ The number of vCPUs to be assigned to the domain. Optional, the default is
+ “1”.
+
+memory
+ The amount of memory to assign to the domain, in KBs. Required.
+
+security-id
+ The security identity to be assigned to the domain when XSM is the access
+ control mechanism being used. Optional, the default is “domu”.
+
+The Module node
+---------------
+
+This node describes a multiboot module loaded by the boot loader. The required
+``compatible`` property follows the format: ``multiboot, <type>`` where type can
+be “module”, “kernel”, “ramdisk”, “memory-map”, lcm, or “config”. The ``reg``
+property is required and identifies how to locate the multiboot module.
+
+compatible
+ This identifies what the module is and thus what the hypervisor should use the
+ module for during domain construction. Required.
+
+reg
+ This identifies where this module is located within the multiboot module
+ chain. Required.
+
+bootargs
+ This is used to override the boot params carried in multiboot module.
+ Optional.
+
+.. note:: The bootargs property is intended for situations where the same kernel multiboot module is used for more than one domain.
+
--
2.11.0