1# Device Tree Overlays support in Xen
2
3Xen experimentally supports dynamic device assignment to running
4domains, i.e. adding/removing nodes (using .dtbo) to/from Xen device
5tree, and attaching them to a running domain with given $domid.
6
7Dynamic node assignment works in two steps:
8
9## Add/Remove device tree overlay to/from Xen device tree
10
111. Xen tools check the dtbo given and parse all other user provided arguments
122. Xen tools pass the dtbo to Xen hypervisor via hypercall.
133. Xen hypervisor applies/removes the dtbo to/from Xen device tree.
14
15## Attach device from the DT overlay to domain
16
171. Xen tools check the dtbo given and parse all other user provided arguments
182. Xen tools pass the dtbo to Xen hypervisor via hypercall.
193. Xen hypervisor attach the device to the user-provided $domid by
20   mapping node resources in the DT overlay.
21
22# Examples
23
24Here are a few examples on how to use it.
25
26## Dom0 device add
27
28For assigning a device tree overlay to Dom0, user should firstly properly
29prepare the DT overlay. More information about device tree overlays can be
30found in [1]. Then, in Dom0, enter the following:
31
32    (dom0) xl dt-overlay add overlay.dtbo
33
34This will allocate the devices mentioned in overlay.dtbo to Xen device tree.
35
36To assign the newly added device from the dtbo to Dom0:
37
38    (dom0) xl dt-overlay attach overlay.dtbo 0
39
40Next, if the user wants to add the same device tree overlay to dom0
41Linux, execute the following:
42
43    (dom0) mkdir -p /sys/kernel/config/device-tree/overlays/new_overlay
44    (dom0) cat overlay.dtbo > /sys/kernel/config/device-tree/overlays/new_overlay/dtbo
45
46Finally if needed, the relevant Linux kernel drive can be loaded using:
47
48    (dom0) modprobe module_name.ko
49
50## DomU device add/remove
51
52All the nodes in dtbo will be assigned to one domain. The user will need
53to prepare a different dtbo for the domU. For example, the
54`interrupt-parent` property of the DomU overlay should be changed to the
55Xen hardcoded value `0xfde8` and the xen,reg property should be added to
56specify the address mappings. If the domain is not 1:1 mapped, xen,reg
57must be present. See the xen,reg format description in
58docs/misc/arm/passthrough.txt. Below assumes the properly written DomU
59dtbo is `overlay_domu.dtbo`.
60
61The user needs to set the `passthrough` property in the xl config file
62if you plan to use DT overlay and devices requiring an IOMMU.
63
64User will also need to modprobe the relevant drivers. For already
65running domains, the user can use the xl dt-overlay attach command,
66example:
67
68    (dom0) xl dt-overlay add overlay.dtbo            # If not executed before
69    (dom0) xl dt-overlay attach overlay_domu.dtbo $domid
70    (dom0) xl console $domid                         # To access $domid console
71
72Next, if the user needs to modify/prepare the overlay.dtbo suitable for
73the domU:
74
75    (domU) mkdir -p /sys/kernel/config/device-tree/overlays/new_overlay
76    (domU) cat overlay_domu.dtbo > /sys/kernel/config/device-tree/overlays/new_overlay/dtbo
77
78Finally, if needed, the relevant Linux kernel drive can be probed:
79
80    (domU) modprobe module_name.ko
81
82[1] https://www.kernel.org/doc/Documentation/devicetree/overlay-notes.txt
83