1-------------------------------------
2Xen Hyperlaunch Device Tree Bindings
3-------------------------------------
4
5The Xen Hyperlaunch device tree adopts the dom0less device tree structure and
6extends it to meet the requirements for the Hyperlaunch capability. The primary
7difference is the introduction of the ``hypervisor`` node that is under the
8``/chosen`` node. The move to a dedicated node was driven by:
9
101. Reduces the need to walk over nodes that are not of interest, e.g. only
11   nodes of interest should be in ``/chosen/hypervisor``
12
132. Allows for the domain construction information to easily be sanitized by
14   simple removing the ``/chosen/hypervisor`` node.
15
16Example Configuration
17---------------------
18
19Below are two example device tree definitions for the hypervisor node. The
20first is an example of a multiboot-based configuration for x86 and the second
21is a module-based configuration for Arm.
22
23Multiboot x86 Configuration:
24""""""""""""""""""""""""""""
25
26::
27
28    hypervisor {
29        #address-cells = <1>;
30        #size-cells = <0>;
31        compatible = “hypervisor,xen”
32
33        // Configuration container
34        config {
35            compatible = "xen,config";
36
37            module {
38                compatible = "module,microcode", "multiboot,module";
39                mb-index = <1>;
40            };
41
42            module {
43                compatible = "module,xsm-policy", "multiboot,module";
44                mb-index = <2>;
45            };
46        };
47
48        // Boot Domain definition
49        domain {
50            compatible = "xen,domain";
51
52            domid = <0x7FF5>;
53
54            // FUNCTION_NONE            (0)
55            // FUNCTION_BOOT            (1 << 0)
56            // FUNCTION_CRASH           (1 << 1)
57            // FUNCTION_CONSOLE         (1 << 2)
58            // FUNCTION_XENSTORE        (1 << 30)
59            // FUNCTION_LEGACY_DOM0     (1 << 31)
60            functions = <0x00000001>;
61
62            memory = <0x0 0x20000>;
63            cpus = <1>;
64            module {
65                compatible = "module,kernel", "multiboot,module";
66                mb-index = <3>;
67            };
68
69            module {
70                compatible = "module,ramdisk", "multiboot,module";
71                mb-index = <4>;
72            };
73            module {
74                compatible = "module,config", "multiboot,module";
75                mb-index = <5>;
76            };
77
78        // Classic Dom0 definition
79        domain {
80            compatible = "xen,domain";
81
82            domid = <0>;
83
84            // PERMISSION_NONE          (0)
85            // PERMISSION_CONTROL       (1 << 0)
86            // PERMISSION_HARDWARE      (1 << 1)
87            permissions = <3>;
88
89            // FUNCTION_NONE            (0)
90            // FUNCTION_BOOT            (1 << 0)
91            // FUNCTION_CRASH           (1 << 1)
92            // FUNCTION_CONSOLE         (1 << 2)
93            // FUNCTION_XENSTORE        (1 << 30)
94            // FUNCTION_LEGACY_DOM0     (1 << 31)
95            functions = <0xC0000006>;
96
97            // MODE_PARAVIRTUALIZED     (1 << 0) /* PV | PVH/HVM */
98            // MODE_ENABLE_DEVICE_MODEL (1 << 1) /* HVM | PVH */
99            // MODE_LONG                (1 << 2) /* 64 BIT | 32 BIT */
100            mode = <5>; /* 64 BIT, PV */
101
102            // UUID
103            domain-uuid = [B3 FB 98 FB 8F 9F 67 A3];
104
105            cpus = <1>;
106            memory = <0x0 0x20000>;
107            security-id = “dom0_t;
108
109            module {
110                compatible = "module,kernel", "multiboot,module";
111                mb-index = <6>;
112                bootargs = "console=hvc0";
113            };
114            module {
115                compatible = "module,ramdisk", "multiboot,module";
116                mb-index = <7>;
117            };
118    };
119
120The multiboot modules supplied when using the above config would be, in order:
121
122* (the above config, compiled)
123* CPU microcode
124* XSM policy
125* kernel for boot domain
126* ramdisk for boot domain
127* boot domain configuration file
128* kernel for the classic dom0 domain
129* ramdisk for the classic dom0 domain
130
131Module Arm Configuration:
132"""""""""""""""""""""""""
133
134::
135
136    hypervisor {
137        compatible = “hypervisor,xen”
138
139        // Configuration container
140        config {
141            compatible = "xen,config";
142
143            module {
144                compatible = "module,microcode”;
145                module-addr = <0x0000ff00 0x80>;
146            };
147
148            module {
149                compatible = "module,xsm-policy";
150                module-addr = <0x0000ff00 0x80>;
151
152            };
153        };
154
155        // Boot Domain definition
156        domain {
157            compatible = "xen,domain";
158
159            domid = <0x7FF5>;
160
161            // FUNCTION_NONE            (0)
162            // FUNCTION_BOOT            (1 << 0)
163            // FUNCTION_CRASH           (1 << 1)
164            // FUNCTION_CONSOLE         (1 << 2)
165            // FUNCTION_XENSTORE        (1 << 30)
166            // FUNCTION_LEGACY_DOM0     (1 << 31)
167            functions = <0x00000001>;
168
169            memory = <0x0 0x20000>;
170            cpus = <1>;
171            module {
172                compatible = "module,kernel";
173                module-addr = <0x0000ff00 0x80>;
174            };
175
176            module {
177                compatible = "module,ramdisk";
178                module-addr = <0x0000ff00 0x80>;
179            };
180            module {
181                compatible = "module,config";
182                module-addr = <0x0000ff00 0x80>;
183            };
184
185        // Classic Dom0 definition
186        domain@0 {
187            compatible = "xen,domain";
188
189            domid = <0>;
190
191            // PERMISSION_NONE          (0)
192            // PERMISSION_CONTROL       (1 << 0)
193            // PERMISSION_HARDWARE      (1 << 1)
194            permissions = <3>;
195
196            // FUNCTION_NONE            (0)
197            // FUNCTION_BOOT            (1 << 0)
198            // FUNCTION_CRASH           (1 << 1)
199            // FUNCTION_CONSOLE         (1 << 2)
200            // FUNCTION_XENSTORE        (1 << 30)
201            // FUNCTION_LEGACY_DOM0     (1 << 31)
202            functions = <0xC0000006>;
203
204            // MODE_PARAVIRTUALIZED     (1 << 0) /* PV | PVH/HVM */
205            // MODE_ENABLE_DEVICE_MODEL (1 << 1) /* HVM | PVH */
206            // MODE_LONG                (1 << 2) /* 64 BIT | 32 BIT */
207            mode = <5>; /* 64 BIT, PV */
208
209            // UUID
210            domain-uuid = [B3 FB 98 FB 8F 9F 67 A3];
211
212            cpus = <1>;
213            memory = <0x0 0x20000>;
214            security-id = “dom0_t”;
215
216            module {
217                compatible = "module,kernel";
218                module-addr = <0x0000ff00 0x80>;
219                bootargs = "console=hvc0";
220            };
221            module {
222                compatible = "module,ramdisk";
223                module-addr = <0x0000ff00 0x80>;
224            };
225    };
226
227The modules that would be supplied when using the above config would be:
228
229* (the above config, compiled into hardware tree)
230* CPU microcode
231* XSM policy
232* kernel for boot domain
233* ramdisk for boot domain
234* boot domain configuration file
235* kernel for the classic dom0 domain
236* ramdisk for the classic dom0 domain
237
238The hypervisor device tree would be compiled into the hardware device tree and
239provided to Xen using the standard method currently in use. The remaining
240modules would need to be loaded in the respective addresses specified in the
241`module-addr` property.
242
243
244The Hypervisor node
245-------------------
246
247The hypervisor node is a top level container for the domains that will be built
248by hypervisor on start up. On the ``hypervisor`` node the ``compatible``
249property is used to identify the type of hypervisor node present..
250
251compatible
252  Identifies the type of node. Required.
253
254The Config node
255---------------
256
257A config node is for detailing any modules that are of interest to Xen itself.
258For example this would be where Xen would be informed of microcode or XSM
259policy locations. If the modules are multiboot modules and are able to be
260located by index within the module chain, the ``mb-index`` property should be
261used to specify the index in the multiboot module chain.. If the module will be
262located by physical memory address, then the ``module-addr`` property should be
263used to identify the location and size of the module.
264
265compatible
266  Identifies the type of node. Required.
267
268The Domain node
269---------------
270
271A domain node is for describing the construction of a domain. It may provide a
272domid property which will be used as the requested domain id for the domain
273with a value of “0” signifying to use the next available domain id, which is
274the default behavior if omitted. A domain configuration is not able to request
275a domid of “0”. After that a domain node may have any of the following
276parameters,
277
278compatible
279  Identifies the type of node. Required.
280
281domid
282  Identifies the domid requested to assign to the domain. Required.
283
284permissions
285  This sets what Discretionary Access Control permissions
286  a domain is assigned. Optional, default is none.
287
288functions
289  This identifies what system functions a domain will fulfill.
290  Optional, the default is none.
291
292.. note::  The `functions` bits that have been selected to indicate
293   ``FUNCTION_XENSTORE`` and ``FUNCTION_LEGACY_DOM0`` are the last two bits
294   (30, 31) such that should these features ever be fully retired, the flags may
295   be dropped without leaving a gap in the flag set.
296
297mode
298  The mode the domain will be executed under. Required.
299
300domain-uuid
301  A globally unique identifier for the domain. Optional,
302  the default is NULL.
303
304cpus
305  The number of vCPUs to be assigned to the domain. Optional,
306  the default is “1”.
307
308memory
309  The amount of memory to assign to the domain, in KBs.
310  Required.
311
312security-id
313  The security identity to be assigned to the domain when XSM
314  is the access control mechanism being used. Optional,
315  the default is “domu_t”.
316
317The Module node
318---------------
319
320This node describes a boot module loaded by the boot loader. The required
321compatible property follows the format: module,<type> where type can be
322“kernel”, “ramdisk”, “device-tree”, “microcode”, “xsm-policy” or “config”. In
323the case the module is a multiboot module, the additional property string
324“multiboot,module” may be present. One of two properties is required and
325identifies how to locate the module. They are the mb-index, used for multiboot
326modules, and the module-addr for memory address based location.
327
328compatible
329  This identifies what the module is and thus what the hypervisor
330  should use the module for during domain construction. Required.
331
332mb-index
333  This identifies the index for this module in the multiboot module chain.
334  Required for multiboot environments.
335
336module-addr
337  This identifies where in memory this module is located. Required for
338  non-multiboot environments.
339
340bootargs
341  This is used to provide the boot params to kernel modules.
342
343.. note::  The bootargs property is intended for situations where the same kernel multiboot module is used for more than one domain.
344