Re: [PATCH v4 33/33] docs/misc: arm: Add documentation about non-PCI passthrough

[Ian Campbell <ian.campbell@citrix.com>]

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.

> 
> 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?

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?

> +    	};
> +    };
> +};
> +
> +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?

> +
> +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.

> +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).

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