From patchwork Wed Aug 21 03:53:15 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Stefano Stabellini X-Patchwork-Id: 11105339 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 88D7D14F7 for ; Wed, 21 Aug 2019 03:54:54 +0000 (UTC) Received: from lists.xenproject.org (lists.xenproject.org [192.237.175.120]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 5CE6D22DD3 for ; Wed, 21 Aug 2019 03:54:54 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=fail reason="signature verification failed" (1024-bit key) header.d=kernel.org header.i=@kernel.org header.b="1h4DiN7i" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 5CE6D22DD3 Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=kernel.org Authentication-Results: mail.kernel.org; spf=none smtp.mailfrom=xen-devel-bounces@lists.xenproject.org Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.89) (envelope-from ) id 1i0Hga-0007Xa-9U; Wed, 21 Aug 2019 03:53:24 +0000 Received: from all-amaz-eas1.inumbo.com ([34.197.232.57] helo=us1-amaz-eas2.inumbo.com) by lists.xenproject.org with esmtp (Exim 4.89) (envelope-from ) id 1i0HgZ-0007XV-HN for xen-devel@lists.xen.org; Wed, 21 Aug 2019 03:53:23 +0000 X-Inumbo-ID: 3897caee-c3c7-11e9-adbf-12813bfff9fa Received: from mail.kernel.org (unknown [198.145.29.99]) by us1-amaz-eas2.inumbo.com (Halon) with ESMTPS id 3897caee-c3c7-11e9-adbf-12813bfff9fa; Wed, 21 Aug 2019 03:53:23 +0000 (UTC) Received: from localhost.localdomain (c-67-164-102-47.hsd1.ca.comcast.net [67.164.102.47]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPSA id 01BD7233A1; Wed, 21 Aug 2019 03:53:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1566359602; bh=cwxXDnVPL4zXfRZjxiRXC0qdOTfTGc+Wr/gkO4W2NMI=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=1h4DiN7iS9x85yZOWiF35Vqq5f4rPRYS7nbjRAGiEAeNFaCYXvqDlV2sW6y4fFCgf M/MRjdADr8RwHiGtQiCMqvXzrsjkGUCYcoVujUYjVrnRUFelyw84g+D2EIVApoX4P7 mYKKEgp07/7+KJ9X/e1Q+aeLG9mZSti6e4byNkPs= From: Stefano Stabellini To: julien.grall@arm.com Date: Tue, 20 Aug 2019 20:53:15 -0700 Message-Id: <20190821035315.12812-8-sstabellini@kernel.org> X-Mailer: git-send-email 2.17.1 In-Reply-To: References: Subject: [Xen-devel] [PATCH v4 8/8] xen/arm: add dom0-less device assignment info to docs X-BeenThere: xen-devel@lists.xenproject.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: Xen developer discussion List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Cc: Stefano Stabellini , sstabellini@kernel.org, andrii_anisov@epam.com, Achin.Gupta@arm.com, xen-devel@lists.xen.org, Volodymyr_Babchuk@epam.com MIME-Version: 1.0 Errors-To: xen-devel-bounces@lists.xenproject.org Sender: "Xen-devel" Add info about the SPI used for the virtual pl011. Signed-off-by: Stefano Stabellini --- Changes in v4: - fix spelling - add "multiboot,module" - improve commit message - improve doc - expand the nr_spis and vpl011 sections and include information about the vpl011 SPI - move passthrough information to docs/misc/arm/passthrough.txt Changes in v3: - add nr_spis - change description of interrupts and interrupt-parent Changes in v2: - device tree fragment loaded in cacheable memory - rename multiboot,dtb to multiboot,device-tree - rename "path" to "xen,path" - add a note about device memory mapping - introduce xen,reg - specify only the GIC is supported --- docs/misc/arm/device-tree/booting.txt | 44 ++++++++++- docs/misc/arm/passthrough.txt | 105 ++++++++++++++++++++++++++ 2 files changed, 148 insertions(+), 1 deletion(-) diff --git a/docs/misc/arm/device-tree/booting.txt b/docs/misc/arm/device-tree/booting.txt index 317a9e962a..0b850c0591 100644 --- a/docs/misc/arm/device-tree/booting.txt +++ b/docs/misc/arm/device-tree/booting.txt @@ -146,7 +146,18 @@ with the following properties: - vpl011 - An empty property to enable/disable a virtual pl011 for the guest to use. + An empty property to enable/disable a virtual pl011 for the guest to + use. The virtual pl011 uses SPI number 32 (see GUEST_VPL011_SPI). + Please note that the SPI used for the virtual pl011 could clash with the + physical SPI of a physical device assigned to the guest. + +- nr_spis + + Optional. A 32-bit integer specifying the number of SPIs (Shared + Peripheral Interrupts) to allocate for the domain. If nr_spis is + missing, the max number of SPIs supported by the physical GIC is + used. If both vpl011 and nr_spis are set, nr_spis should be at least + 1 to account for the SPI used by the virtual pl011. - #address-cells and #size-cells @@ -226,3 +237,34 @@ chosen { }; }; }; + + +Device Assignment +================= + +Device Assignment (Passthrough) is supported by adding another module, +alongside the kernel and ramdisk, with the device tree fragment +corresponding to the device node to assign to the guest. + +The dtb sub-node should have the following properties: + +- compatible + + "multiboot,device-tree" and "multiboot,module" + +- reg + + Specifies the physical address of the device tree binary fragment + RAM and its length. + +As an example: + + module@0xc000000 { + compatible = "multiboot,device-tree", "multiboot,module"; + reg = <0x0 0xc000000 0xffffff>; + }; + +The DTB fragment is loaded at 0xc000000 in the example above. It should +follow the convention explained in docs/misc/arm/passthrough.txt. The +DTB fragment will be added to the guest device tree, so that the guest +kernel will be able to discover the device. diff --git a/docs/misc/arm/passthrough.txt b/docs/misc/arm/passthrough.txt index 0efbd122de..8084f2e31b 100644 --- a/docs/misc/arm/passthrough.txt +++ b/docs/misc/arm/passthrough.txt @@ -80,6 +80,111 @@ SPI numbers start from 32, in this example 80 + 32 = 112. See man [xl.cfg] for the iomem format. The reg property is just a pair of address, then size numbers, each of them can occupy 1 or 2 cells. + +Dom0-less Device Passthrough +============================ + +The partial device tree for dom0-less guests should have the following +properties for each node corresponding to a physical device to assign to +the guest: + +- xen,reg + + The xen,reg property is an array of: + + + + They specify the physical address and size of the device memory + ranges together with the corresponding guest address to map them to. + The size of `phys_addr' and `guest_addr' is determined by + #address_cells; the size of `size' is determined by #size_cells. + The memory will be mapped as device memory in the guest + (p2m_mmio_direct_dev). + +- xen,path + + A string property representing the path in the host device tree to the + corresponding device node. + +In addition, a special /gic node is expected as a placeholder for the +full GIC node that will be added by Xen for the guest. /gic can be +referenced by other properties in the device tree fragment. For +instance, it can be referenced by interrupt-parent under a device node. +Xen will take care of substituting the "gic" placeholder node for a +complete GIC node while retaining all the references correctly. + + gic: gic { + #interrupt-cells = <0x3>; + interrupt-controller; + }; + +Note that the #interrupt-cells and interrupt-controller properties are +not actually required, however, DTC expects them to be present if gic is +referenced by interrupt-parent or similar. + + +Example +======= + +The following is a real-world example of a device tree fragment to +assign a network card to a dom0-less guest on Xilinx Ultrascale+ MPSoC: + +/dts-v1/; + +/ { + #address-cells = <0x2>; + #size-cells = <0x1>; + + gic: gic { + #interrupt-cells = <0x3>; + interrupt-controller; + }; + + passthrough { + compatible = "simple-bus"; + ranges; + #address-cells = <0x2>; + #size-cells = <0x1>; + + misc_clk { + #clock-cells = <0x0>; + clock-frequency = <0x7735940>; + compatible = "fixed-clock"; + linux,phandle = <0x1>; + phandle = <0x1>; + }; + + ethernet@ff0e0000 { + compatible = "cdns,zynqmp-gem"; + status = "okay"; + reg = <0x0 0xff0e0000 0x1000>; + clock-names = "pclk", "hclk", "tx_clk", "rx_clk"; + #address-cells = <0x1>; + #size-cells = <0x0>; + clocks = <0x1 0x1 0x1 0x1>; + phy-mode = "rgmii-id"; + xlnx,ptp-enet-clock = <0x0>; + local-mac-address = [00 0a 35 00 22 01]; + phy-handle = <0x2>; + interrupt-parent = <&gic>; + interrupts = <0x0 0x3f 0x4 0x0 0x3f 0x4>; + xen,path = "/amba/ethernet@ff0e0000"; + xen,reg = <0x0 0xff0e0000 0x1000 0x0 0xff0e0000>; + + phy@c { + reg = <0xc>; + ti,rx-internal-delay = <0x8>; + ti,tx-internal-delay = <0xa>; + ti,fifo-depth = <0x1>; + ti,rxctrl-strap-worka; + linux,phandle = <0x2>; + phandle = <0x2>; + }; + }; + }; +}; + + [arm,gic.txt]: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/devicetree/bindings/interrupt-controller/arm,gic.txt [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 [xl.cfg]: https://xenbits.xen.org/docs/unstable/man/xl.cfg.5.html