[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [RFC PATCH v2] 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: ihttps://drive.google.com/file/d/1l3fo4FylvZCQs1V00DcwifyLjl5Jw3W8/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@xxxxxxxxxxxxxxxxxxxx> Signed-off-by: Christopher Clark <christopher.clark@xxxxxxxxxx> Version 2 --------- - cleaned up wording - updated example to reflect a real configuration - add explanation of mb2 modules that would be loaded - add the config node --- docs/designs/boot-domain-device-tree.rst | 235 +++++++++++++++++++++++++++++++ 1 file changed, 235 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..558d75a796 --- /dev/null +++ b/docs/designs/boot-domain-device-tree.rst @@ -0,0 +1,235 @@ +==================================== +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. + +3. Allows for the domain construction information to easily be sanitized by +simple removing the ``/chosen/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>; + + // Configuration container + config@0 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "xen,config"; + + // reg is required but ignored for "xen,config" node + reg = <0>; + + module@1 { + compatible = "multiboot,microcode", "multiboot,module"; + reg = <1>; + }; + + module@2 { + compatible = "multiboot,xsm-policy", "multiboot,module"; + reg = <2>; + }; + }; + + // Boot Domain definition + domain@0x7FF5 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "xen,domain"; + + reg = <0x7FF5>; + memory = <0x0 0x20000>; + cpus = <1>; + module@3 { + compatible = "multiboot,kernel", "multiboot,module"; + reg = <3>; + }; + + module@4 { + compatible = "multiboot,ramdisk", "multiboot,module"; + reg = <4>; + }; + module@5 { + compatible = "multiboot,config", "multiboot,module"; + reg = <5>; + }; + + // Classic Dom0 definition + domain@0 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "xen,domain"; + + 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) /* HVM | PVH */ + // MODE_LONG (1 << 2) /* 64 BIT | 32 BIT */ + mode = <5>; /* 64 BIT, PV */ + + // UUID + domain-handle = [B3 FB 98 FB 8F 9F 67 A3]; + + cpus = <1>; + memory = <0x0 0x20000>; + security-id = <0>; + + module@6 { + compatible = "multiboot,kernel", "multiboot,module"; + reg = <6>; + bootargs = "console=hvc0"; + }; + module@7 { + compatible = "multiboot,ramdisk", "multiboot,module"; + reg = <7>; + }; + }; + +The multiboot modules that would be supplied when using the above config would +be, in order: + - (the above config, compiled) + - CPU microcode + - XSM policy + - kernel for boot domain + - ramdisk for boot domain + - boot domain configuration file + - kernel for the classic dom0 domain + - ramdisk for the classic dom0 domain + +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 Config node +--------------- + +A config node is for detailing any multiboot modules that are of interest to Xen +itself. For example this would be where Xen would be informed of microcode or +XSM policy locations. For locating the multiboot modules, the #address-cells and +#size-cells are set according to how the multiboot modules are 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 physical memory address, then the values should be “1” and +“1” respectively. + + +\#address-cells + Identifies number of fields for address. Required. + +\#size-cells + Identifies number of fields for size. Required. + +compatible + Identifies the type of node. Required. + +reg + Unused. Required. + +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 physical memory 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. A domain configuration is not able to request +a domid of “0”. After that a domain node may have any of the following +parameters, + +\#address-cells + Identifies number of fields for address. Required. + +\#size-cells + Identifies number of fields for size. Required. + +compatible + Identifies the type of node. Required. + +reg + Identifies the domid requested to assign to 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 `functions` bits that have been selected to indicate ``FUNCTION_XENSTORE`` and ``FUNCTION_LEGACY_DOM0`` are the last two bits (30, 31) 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”, “device-tree”, “microcode”, “xsm-policy” 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 with the + multiboot module. + +.. note:: The bootargs property is intended for situations where the same kernel multiboot module is used for more than one domain. + -- 2.11.0
|
Lists.xenproject.org is hosted with RackSpace, monitoring our |