1Passthrough a device described in the Device Tree to a guest
2============================================================
3
4The example will use the secondary network card for the midway server.
5
61) Mark the device to let Xen know the device will be used for passthrough.
7This is done in the device tree node describing the device by adding the
8property "xen,passthrough". The command to do it in U-Boot is:
9
10    fdt set /soc/ethernet@fff51000 xen,passthrough
11
122) Create a partial device tree describing the device. The IRQ are mapped
131:1 to the guest (i.e VIRQ == IRQ). For MMIO, you will have to find a hole
14in the guest memory layout (see xen/include/public/arch-arm.h, note that
15the layout is not stable and can change between versions of Xen). Please
16be aware that passing a partial device tree to a VM is a powerful tool,
17use it with care. In production, only allow assignment of devices which
18have been previously tested and known to work correctly when given to
19guests.
20
21/dts-v1/;
22
23/ {
24    /* #*cells are here to keep DTC happy */
25    #address-cells = <2>;
26    #size-cells = <2>;
27
28    aliases {
29        net = &mac0;
30    };
31
32    passthrough {
33        compatible = "simple-bus";
34        ranges;
35        #address-cells = <2>;
36        #size-cells = <2>;
37        mac0: ethernet@10000000 {
38            compatible = "calxeda,hb-xgmac";
39            reg = <0 0x10000000 0 0x1000>;
40            interrupts = <0 80 4  0 81 4  0 82 4>;
41        };
42    };
43};
44
45Note:
46    * The interrupt-parent property will be added by the toolstack in the
47    root node;
48    * The following properties are mandatory with the /passthrough node:
49        - compatible: It should always contain "simple-bus"
50        - ranges
51        - #address-cells
52        - #size-cells
53    * See http://www.devicetree.org/Device_Tree_Usage for more
54    information about device tree.
55    * In this example, the device MMIO region is placed at a different
56    address (0x10000000) compared to the host address (0xfff51000)
57
583) Compile the partial guest device with dtc (Device Tree Compiler).
59For our purpose, the compiled file will be called guest-midway.dtb and
60placed in /root in DOM0.
61
623) Add the following options in the guest configuration file:
63
64device_tree = "/root/guest-midway.dtb"
65dtdev = [ "/soc/ethernet@fff51000" ]
66irqs = [ 112, 113, 114 ]
67iomem = [ "0xfff51,1@0x10000" ]
68
69Please refer to your platform docs for the MMIO ranges and interrupts.
70
71They can also be calculated from the original device tree (not
72recommended). You can read about the "interrupts" property format in the
73device tree bindings of the interrupt controller of your platform. For
74example, in the case of GICv2 see [arm,gic.txt]; in the case of GICv3
75see [arm,gic-v3.txt] in the Linux repository. For both GICv2 and GICv3
76the "interrupts" property format is the same: the first cell is the
77interrupt type, and the second cell is the interrupt number.  Given that
78SPI numbers start from 32, in this example 80 + 32 = 112.
79
80See man [xl.cfg] for the iomem format. The reg property is just a pair
81of address, then size numbers, each of them can occupy 1 or 2 cells.
82
83[arm,gic.txt]: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/devicetree/bindings/interrupt-controller/arm,gic.txt
84[arm,gic-v3.txt]: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v3.txt
85[xl.cfg]: https://xenbits.xen.org/docs/unstable/man/xl.cfg.5.html
86