[Xen-devel,v4,33/33] docs/misc: arm: Add documentation about non-PCI passthrough

Message ID 1426793399-6283-34-git-send-email-julien.grall@linaro.org
State New
Headers show

Commit Message

Julien Grall March 19, 2015, 7:29 p.m.
Note that the example is done on Midway whose SMMU driver is not
supported on Xen upstream.

Currently, I don't have other platform where I can test non-PCI
passthrough.

Signed-off-by: Julien Grall <julien.grall@linaro.org>

---
    Changes in v4:
        - Patch added
---
 docs/misc/arm/passthrough.txt | 58 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 58 insertions(+)
 create mode 100644 docs/misc/arm/passthrough.txt

Comments

Julien Grall March 31, 2015, 1:03 p.m. | #1
Hi Ian,

On 31/03/15 12:55, Ian Campbell wrote:
> On Thu, 2015-03-19 at 19:29 +0000, Julien Grall wrote:
>> Note that the example is done on Midway whose SMMU driver is not
>> supported on Xen upstream.
>>
>> Currently, I don't have other platform where I can test non-PCI
>> passthrough.
> 
> Please drop references to non-PCI in favour of talking about device tree
> throughout.

Will do.

>>
>> Signed-off-by: Julien Grall <julien.grall@linaro.org>
>>
>> ---
>>     Changes in v4:
>>         - Patch added
>> ---
>>  docs/misc/arm/passthrough.txt | 58 +++++++++++++++++++++++++++++++++++++++++++
>>  1 file changed, 58 insertions(+)
>>  create mode 100644 docs/misc/arm/passthrough.txt
>>
>> diff --git a/docs/misc/arm/passthrough.txt b/docs/misc/arm/passthrough.txt
>> new file mode 100644
>> index 0000000..cf6cc61
>> --- /dev/null
>> +++ b/docs/misc/arm/passthrough.txt
>> @@ -0,0 +1,58 @@
>> +Passthrough a non-pci device to a guest
>> +=======================================
>> +
>> +The example will use the secondary network card for the midway server.
>> +
>> +1) Mark the device to let Xen knowns the device will be used for passthrough.
> 
> s/knowns/know/
> 
>> +This is done in the device tree node describing the device by adding the
>> +property "xen,passthrough". The command to do it in U-Boot is:
>> +
>> +    fdt set /soc/ethernet@fff51000 xen,passthrough
>> +
>> +2) Create the partial device tree describing the device. The IRQ are mapped
> 
> s/the/a/
> 
>> +1:1 to the guest (i.e VIRQ == IRQ). For MMIO will have to find hole in the
> 
> s/MMIO will/MMIO you will/
> s/find hole/find a hole/
> 
>> +guest memory layout (see xen/include/public/arch-arm.h, noted the layout
> 
> s/noted/note that/
> 
>> +is not stable and can change between 2 releases version of Xen).
> 
> s/between 2 releases version/versions/
> 
>> +
>> +/dts-v1/;
>> +
>> +/ {
>> +    /* #*cells are here to keep DTC happy */
>> +    #address-cells = <2>;
>> +    #size-cells = <2>;
>> +
>> +    aliases {
>> +        net = &mac0;
>> +    };
>> +
>> +    passthrough {
>> +        compatible = "simple-bus";
>> +        ranges;
>> +        #address-cells = <2>;
>> +        #size-cells = <2>;
>> +    	mac0: ethernet@10000000 {
>> +	    	compatible = "calxeda,hb-xgmac";
>> +            reg = <0 0x10000000 0 0x1000>;
>> +    		interrupts = <0 80 4  0 81 4  0 82 4>;
> 
> Tabs vs spaces?

I think so. I will fix it.

> 
> Is it worth making reference to looking at the host entry and copying
> some of the relevant bits of that, or would that be more confusing?

I don't understand the question here.

>> +    	};
>> +    };
>> +};
>> +
>> +Note:
>> +    * The interrupt-parent property will be added by the toolstack in the
>> +    root node;
>> +    * The properties compatible, ranges, #address-cells and #size-cells
>> +    in /passthrough are mandatory.
> 
> The following properties are mandatory within the /passthrough node:
>   * compatible
>   * ranges
>   * ...
> 
> Are the values of any of them mandatory, i.e. simply-bus or empty
> ranges?

"simple-bus" is mandatory. The empty ranges not.

> 
>> +
>> +3) Compile the partial guest device with dtc (Device Tree Compiler).
>> +For our purpose, the compiled file will be called guest-midway.dtb and
>> +placed in /root in DOM0.
> 
> Can you give an example of the command line please, and
> s/guest-midway/passthrough/ would be more generic.

I can.

> 
>> +3) Add the following options in the guest configuration file:
> 
> Please expand to say add the dtdev, irqs and iomem options with values
> corresponding to the resources used by the to-be-passedthrough device.
> Perhaps also reference xl.cfg(5).

Ok.

>> +device_tree = "/root/guest-midway.dtb"
>> +dtdev = [ "/soc/ethernet@fff51000" ]
>> +irqs = [ 112, 113, 114 ]
>> +iomem = [ "0xfff51,1@0x10000" ]
>> +

Regards,

Patch

diff --git a/docs/misc/arm/passthrough.txt b/docs/misc/arm/passthrough.txt
new file mode 100644
index 0000000..cf6cc61
--- /dev/null
+++ b/docs/misc/arm/passthrough.txt
@@ -0,0 +1,58 @@ 
+Passthrough a non-pci device to a guest
+=======================================
+
+The example will use the secondary network card for the midway server.
+
+1) Mark the device to let Xen knowns the device will be used for passthrough.
+This is done in the device tree node describing the device by adding the
+property "xen,passthrough". The command to do it in U-Boot is:
+
+    fdt set /soc/ethernet@fff51000 xen,passthrough
+
+2) Create the partial device tree describing the device. The IRQ are mapped
+1:1 to the guest (i.e VIRQ == IRQ). For MMIO will have to find hole in the
+guest memory layout (see xen/include/public/arch-arm.h, noted the layout
+is not stable and can change between 2 releases version of Xen).
+
+/dts-v1/;
+
+/ {
+    /* #*cells are here to keep DTC happy */
+    #address-cells = <2>;
+    #size-cells = <2>;
+
+    aliases {
+        net = &mac0;
+    };
+
+    passthrough {
+        compatible = "simple-bus";
+        ranges;
+        #address-cells = <2>;
+        #size-cells = <2>;
+    	mac0: ethernet@10000000 {
+	    	compatible = "calxeda,hb-xgmac";
+            reg = <0 0x10000000 0 0x1000>;
+    		interrupts = <0 80 4  0 81 4  0 82 4>;
+    	};
+    };
+};
+
+Note:
+    * The interrupt-parent property will be added by the toolstack in the
+    root node;
+    * The properties compatible, ranges, #address-cells and #size-cells
+    in /passthrough are mandatory.
+
+3) Compile the partial guest device with dtc (Device Tree Compiler).
+For our purpose, the compiled file will be called guest-midway.dtb and
+placed in /root in DOM0.
+
+3) Add the following options in the guest configuration file:
+
+device_tree = "/root/guest-midway.dtb"
+dtdev = [ "/soc/ethernet@fff51000" ]
+irqs = [ 112, 113, 114 ]
+iomem = [ "0xfff51,1@0x10000" ]
+
+