1Dom0 kernel and ramdisk modules
2================================
3
4Xen is passed the dom0 kernel and initrd via a reference in the /chosen
5node of the device tree.
6
7Each node contains the following properties:
8
9- compatible
10
11	Must always include at least the generic compatiblity string:
12
13		"multiboot,module"
14
15	Optionally a more specific compatible string may be used in
16	addition to the above. One of:
17
18	- "multiboot,kernel"	-- the dom0 kernel
19	- "multiboot,ramdisk"	-- the dom0 ramdisk
20	- "xen,xsm-policy"	-- XSM policy blob
21
22	It is normally recommended to include a more specific
23	compatible string (if one applies) in addition to the generic
24	string (which must always be present).
25
26	Xen will assume that the first module which lacks a more
27	specific compatible string is a "multiboot,kernel".
28
29	Xen will examine each module, starting from the second
30	module that lacks a specific compatible string.  Xen will
31	check each such module for the XSM Magic number:
32
33	- For a module which has the XSM Magic number: it will be
34	  treated by Xen as if its compatible string was
35	  "xen,xsm-policy";
36
37	- For a module which does not have the XSM Magic: the second
38	  module lacking a compatible string will be treated by Xen as
39	  if its compatible string was "multiboot,ramdisk"; for the
40	  third and subsequent modules which lack a specific
41	  compatible string, Xen will not apply any special treatment.
42
43	This means if the ramdisk module is present and does not have the
44	compatible string "multiboot,ramdisk", then it must always be the
45	second module.
46
47	Note: This XSM Magic detection behavior was introduced by Xen 4.7.
48	Xen 4.6 (and downwards) still requires the XSM module to have the
49	compatible string "xen,xsm-policy".
50
51	Xen 4.4 supported a different set of legacy compatible strings
52	which remain supported such that systems supporting both 4.4
53	and later can use a single DTB.
54
55	- "xen,multiboot-module" equivalent to "multiboot,module"
56	- "xen,linux-zimage"     equivalent to "multiboot,kernel"
57	- "xen,linux-initrd"     equivalent to "multiboot,ramdisk"
58
59	For compatibility with Xen 4.4 the more specific "xen,linux-*"
60	names are non-optional and must be included.
61
62- reg
63
64	Specifies the physical address of the module in RAM and the
65	length of the module.
66
67- bootargs (optional)
68
69	Command line associated with this module. See below for the
70	priority of this field vs. other mechanisms of specifying the
71	bootargs for the kernel.
72
73Examples
74========
75
76A boot module of unspecified type:
77
78	module@0xc0000000 {
79		compatible = "multiboot,module";
80		reg = <0xc0000000 0x1234>;
81		bootargs = "...";
82	};
83
84A boot module containing a ramdisk:
85
86	module@0xd0000000 {
87		compatible = "multiboot,ramdisk", "multiboot,module";
88		reg = <0xd0000000 0x5678>;
89	};
90
91The previous examples are compatible with Xen 4.5+ only.
92
93To be compatible with Xen 4.4 as well use the legacy names:
94
95	module@0xd0000000 {
96		compatible = "xen,linux-initrd", "xen,multiboot-module";
97		reg = <0xd0000000 0x5678>;
98	};
99
100Command lines
101=============
102
103Xen also checks for properties directly under /chosen to find suitable command
104lines for Xen and Dom0. The logic is the following:
105
106 - If xen,xen-bootargs is present, it will be used for Xen.
107 - If xen,dom0-bootargs is present, it will be used for Dom0.
108 - If xen,xen-bootargs is _not_ present, but xen,dom0-bootargs is,
109   bootargs will be used for Xen.
110 - If a kernel boot module is present and has a bootargs property then
111   the top-level bootargs will used for Xen.
112 - If no Xen specific properties are present, bootargs is for Dom0.
113 - If xen,xen-bootargs is present, but xen,dom0-bootargs is missing,
114   bootargs will be used for Dom0.
115
116Most of these cases is to make booting with Xen-unaware bootloaders easier.
117For those you would hardcode the Xen commandline in the DTB under
118/chosen/xen,xen-bootargs and would let the bootloader set the Dom0 command
119line by writing bootargs (as for native Linux).
120A Xen-aware bootloader would set xen,xen-bootargs for Xen, xen,dom0-bootargs
121for Dom0 and bootargs for native Linux.
122
123
124Creating Multiple Domains directly from Xen
125===========================================
126
127It is possible to have Xen create other domains, in addition to dom0,
128out of the information provided via device tree. A kernel and initrd
129(optional) need to be specified for each guest.
130
131For each domain to be created there needs to be one node under /chosen
132with the following properties:
133
134- compatible
135
136    For domUs: "xen,domain"
137
138- memory
139
140	A 64-bit integer specifying the amount of kilobytes of RAM to
141    allocate to the guest.
142
143- cpus
144
145    An integer specifying the number of vcpus to allocate to the guest.
146
147- vpl011
148
149    An empty property to enable/disable a virtual pl011 for the guest to
150    use. The virtual pl011 uses SPI number 0 (see GUEST_VPL011_SPI).
151    Please note that the SPI used for the virtual pl011 could clash with the
152    physical SPI of a physical device assigned to the guest.
153
154- nr_spis
155
156    Optional. A 32-bit integer specifying the number of SPIs (Shared
157    Peripheral Interrupts) to allocate for the domain. If nr_spis is
158    missing, the max number of SPIs supported by the physical GIC is
159    used, or GUEST_VPL011_SPI+1 if vpl011 is enabled, whichever is
160    greater.
161
162- #address-cells and #size-cells
163
164    Both #address-cells and #size-cells need to be specified because
165    both sub-nodes (described shortly) have reg properties.
166
167Under the "xen,domain" compatible node, one or more sub-nodes are present
168for the DomU kernel and ramdisk.
169
170The kernel sub-node has the following properties:
171
172- compatible
173
174    "multiboot,kernel", "multiboot,module"
175
176- reg
177
178    Specifies the physical address of the kernel in RAM and its
179    length.
180
181- bootargs (optional)
182
183    Command line parameters for the guest kernel.
184
185The ramdisk sub-node has the following properties:
186
187- compatible
188
189    "multiboot,ramdisk", "multiboot,module"
190
191- reg
192
193    Specifies the physical address of the ramdisk in RAM and its
194    length.
195
196
197Example
198=======
199
200chosen {
201    domU1 {
202        compatible = "xen,domain";
203        #address-cells = <0x2>;
204        #size-cells = <0x1>;
205        memory = <0 131072>;
206        cpus = <2>;
207        vpl011;
208
209        module@0x4a000000 {
210            compatible = "multiboot,kernel", "multiboot,module";
211            reg = <0x0 0x4a000000 0xffffff>;
212            bootargs = "console=ttyAMA0 init=/bin/sh";
213        };
214
215        module@0x4b000000 {
216            compatible = "multiboot,ramdisk", "multiboot,module";
217            reg = <0x0 0x4b000000 0xffffff>;
218        };
219    };
220
221    domU2 {
222        compatible = "xen,domain";
223        #address-cells = <0x2>;
224        #size-cells = <0x1>;
225        memory = <0 65536>;
226        cpus = <1>;
227
228        module@0x4c000000 {
229            compatible = "multiboot,kernel", "multiboot,module";
230            reg = <0x0 0x4c000000 0xffffff>;
231            bootargs = "console=ttyAMA0 init=/bin/sh";
232        };
233
234        module@0x4d000000 {
235            compatible = "multiboot,ramdisk", "multiboot,module";
236            reg = <0x0 0x4d000000 0xffffff>;
237        };
238    };
239};
240
241
242Device Assignment
243=================
244
245Device Assignment (Passthrough) is supported by adding another module,
246alongside the kernel and ramdisk, with the device tree fragment
247corresponding to the device node to assign to the guest.
248
249The dtb sub-node should have the following properties:
250
251- compatible
252
253    "multiboot,device-tree" and "multiboot,module"
254
255- reg
256
257    Specifies the physical address of the device tree binary fragment
258    RAM and its length.
259
260As an example:
261
262        module@0xc000000 {
263            compatible = "multiboot,device-tree", "multiboot,module";
264            reg = <0x0 0xc000000 0xffffff>;
265        };
266
267The DTB fragment is loaded at 0xc000000 in the example above. It should
268follow the convention explained in docs/misc/arm/passthrough.txt. The
269DTB fragment will be added to the guest device tree, so that the guest
270kernel will be able to discover the device.
271