[RFC] scf: SCF device tree and configuration documentation

* [RFC] scf: SCF device tree and configuration documentation
@ 2017-05-04  9:32 Andrii Anisov
  2017-05-04 10:03 ` Andrii Anisov
  0 siblings, 1 reply; 20+ messages in thread
From: Andrii Anisov @ 2017-05-04  9:32 UTC (permalink / raw)
  To: xen-devel; +Cc: Andrii Anisov

From: Andrii Anisov <andrii_anisov@epam.com>

Description of SCF specific device tree properties and SCF configuration
using device tree.

Signed-off-by: Andrii Anisov <andrii_anisov@epam.com>
---

Dear All,

I would like to present a concept of SCF [1] configuration using device tree.
The idea is that the framework configuration is too complex to get it passed
using xen command line (for Dom0) or configuration file (for DomU). So the
configuration will be done using device tree with special properties which
will mark a device to be shared by the framework, or a node to describe a
virtual coprocessor.
Please notice that the partial device tree which is used for DomU
configuration is passed to the hypervisor as a binary blob in order to be
processed by SCF.

[1] - Shared coprocessor framework https://lists.xenproject.org/archives/html/xen-devel/2016-10/msg01966.html

---
 docs/misc/arm/device-tree/scf.txt |  16 +++
 docs/misc/arm/scf.txt             | 250 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 266 insertions(+)
 create mode 100644 docs/misc/arm/device-tree/scf.txt
 create mode 100644 docs/misc/arm/scf.txt

diff --git a/docs/misc/arm/device-tree/scf.txt b/docs/misc/arm/device-tree/scf.txt
new file mode 100644
index 0000000..9b9ac14
--- /dev/null
+++ b/docs/misc/arm/device-tree/scf.txt
@@ -0,0 +1,16 @@
+Shared coprocessor framework configuration
+==========================================
+
+Any device with the property "xen,coproc" set will be owned by SCF and will not
+be directly exposed to Dom0. "xen,coproc" property is only meaningful for a
+system device tree which is passed to XEN.
+
+Any device with the property "xen,vcoproc" will be processed by SCF to create
+a virtual coprocessor. If succeed, the device will be injected in the domain's
+device tree with that property wiped. The property value is a stringified path
+or an alias (from a system device tree)  of a physical coproc device the virtual
+coprocessor will run on. That physical coprocessor device node has to be marked
+with "xen,coproc" property.
+"xen,vcoproc" property is meaningful both for a system device tree and a partial
+device tree for DomU.
+
diff --git a/docs/misc/arm/scf.txt b/docs/misc/arm/scf.txt
new file mode 100644
index 0000000..f74e74d
--- /dev/null
+++ b/docs/misc/arm/scf.txt
@@ -0,0 +1,250 @@
+Share a coprocessor to several domains using guest's Device Tree
+================================================================
+
+This example will configure two dummy coprocessors and correspondent virtual
+coprocessors and is based on an RCar Gen3 device tree already adjusted for Dom0.
+Some free iomem range not assigned to any real device will be used for a dummy
+coprocessors definition. One dummy coprocessor would have a single iomem range
+and one irq. Another one will have several named iomem ranges and irqs.
+Two virtual instances of each coprocessor will be configured for Dom0 using a
+system device tree and other two will be configured for DomU using a partial
+device tree.
+
+Let us have two dummy coprocessors defined as following:
+
+\ {
+	...
+	aliases {
+		...
+		pcoproc0 = &coproc0;
+		pcoproc1 = &coproc1;
+		...
+	};
+	...
+	soc {
+		...
+		coproc0: pcoproc0@0xe6110000 {
+			compatible = "vendor_xxx,coproc_xxx";
+			reg = <0x0 0xe6110000 0x0 0x1000>;
+			interrupts = <GIC_SPI 160 IRQ_TYPE_LEVEL_HIGH>;
+			status = "okay";
+		};
+
+		coproc1: pcoproc1@0xe6182000 {
+			compatible = "vendor_xxx,coproc_xxc";
+			reg = <0x0 0xe6182000 0x0 0x1000>,
+			      <0x0 0xe6184000 0x0 0x1000>,
+			      <0x0 0xe6188000 0x0 0x8000>;
+			reg-names = "op", "mmu", "sram";
+			interrupts = <GIC_SPI 132 IRQ_TYPE_LEVEL_HIGH>,
+				     <GIC_SPI 135 IRQ_TYPE_LEVEL_HIGH>;
+			interrupt-names = "op", "mmu";
+			status = "okay";
+		};
+
+		...
+	};
+	...
+};
+
+Notes:
+    * If a coprocessor has several iomem ranges they must be named. Same for
+      interrupts. Names are used for matching both for shared coprocessor
+      platform code probe as well as mapping virtual coprocessors into domains.
+
+1) Mark the coprocessor node to let Xen know it will be used for sharing.
+This is done in the device tree node describing the device by adding the
+property "xen,coproc".
+
+\ {
+	...
+	aliases {
+		...
+		pcoproc0 = &coproc0;
+		pcoproc1 = &coproc1;
+		...
+	};
+	...
+	soc {
+		...
+		coproc0: pcoproc0@0xe6110000 {
+			compatible = "vendor_xxx,coproc_xxx";
+			reg = <0x0 0xe6110000 0x0 0x1000>;
+			interrupts = <GIC_SPI 160 IRQ_TYPE_LEVEL_HIGH>;
+			status = "okay";
++			xen,coproc;
+		};
+
+		coproc1: pcoproc1@0xe6182000 {
+			compatible = "vendor_xxx,coproc_xxc";
+			reg = <0x0 0xe6182000 0x0 0x1000>,
+			      <0x0 0xe6184000 0x0 0x1000>,
+			      <0x0 0xe6188000 0x0 0x8000>;
+			reg-names = "op", "mmu", "sram";
+			interrupts = <GIC_SPI 132 IRQ_TYPE_LEVEL_HIGH>,
+				     <GIC_SPI 135 IRQ_TYPE_LEVEL_HIGH>;
+			interrupt-names = "op", "mmu";
+			status = "okay";
++			xen,coproc;
+		};
+		...
+	};
+	...
+};
+
+2) Create virtual coprocessors nodes. Virtual coprocessor nodes should contain a
+property "xen,vcoproc". The value of this property is a string which reflects a
+full name of a physical coproc node or an alias valid within a system's device
+tree.
+For vcoproc's MMIOs you should find holes of suitable size in a domain memory
+layout. For the first instance of the virtual coprocessor in a domain you freely
+can use MMIO ranges same as a correspondent physical coprocessor uses.
+A virtual coprocessor in a domain will be using the same IRQ(s) as the
+physical coprocessor uses. If several virtual coprocessors baked by one physical
+coprocessor are provided to a domain, they will share the same IRQ(s). 
+
+\ {
+	...
+	aliases {
+		...
+		pcoproc0 = &coproc0;
+		pcoproc1 = &coproc1;
+		...
+	};
+	...
+	soc {
+		...
+		coproc0: pcoproc0@0xe6110000 {
+			compatible = "vendor_xxx,coproc_xxx";
+			reg = <0x0 0xe6110000 0x0 0x1000>;
+			interrupts = <GIC_SPI 160 IRQ_TYPE_LEVEL_HIGH>;
+			status = "okay";
+			xen,coproc;
+		};
++
++		coproc0@e6110000 {
++			reg = <0x0 0xe6110000 0x0 0x1000>;
++			/* reference a pcoproc by a full node name */
++			xen,vcoproc = "/soc/pcoproc0@0xe6110000";
++		};
++		coproc0@e6114000 {
++			/* reference a pcoproc by an alias */
++			reg = <0x0 0xe6114000 0x0 0x1000>;
++			xen,vcoproc = "pcoproc0";
++		};
+
+		coproc1: pcoproc1@0xe6182000 {
+			compatible = "vendor_xxx,coproc_xxc";
+			reg = <0x0 0xe6182000 0x0 0x1000>,
+			      <0x0 0xe6184000 0x0 0x1000>,
+			      <0x0 0xe6188000 0x0 0x8000>;
+			reg-names = "op", "mmu", "sram";
+			interrupts = <GIC_SPI 132 IRQ_TYPE_LEVEL_HIGH>,
+				     <GIC_SPI 135 IRQ_TYPE_LEVEL_HIGH>;
+			interrupt-names = "op", "mmu";
+			status = "okay";
+			xen,coproc;
+		};
+
++		coproc1@0xe6182000 {
++			reg = <0x0 0xe6182000 0x0 0x1000>,
++			      <0x0 0xe6184000 0x0 0x1000>,
++			      <0x0 0xe6188000 0x0 0x8000>;
++			reg-names = "op", "mmu", "sram";
++			xen,vcoproc = "/soc/pcoproc1@0xe6182000";
++		};
++
++		coproc1@0xe619a000 {
++			reg = <0x0 0xe619a000 0x0 0x1000>,
++			      <0x0 0xe6152000 0x0 0x1000>,
++			      <0x0 0xe6058000 0x0 0x8000>;
++			reg-names = "op", "mmu", "sram";
++			xen,vcoproc = "pcoproc1";
+
+		...
+	};
+	...
+};
+
+Notes:
+    * As you could notice virtual coprocessor "coproc1@0xe619a000" has its iomem
+      ranges mapped to arbitrary addresses, their relative offsets are not kept.
+      This does not take us into issues because range name matching is used.
+
+2) Create a partial device tree describing a virtual coprocessors provided to
+DomU:
+
+/dts-v1/;
+
+#include <dt-bindings/interrupt-controller/arm-gic.h>
+
+/ {
+    /* #*cells are here to keep DTC happy */
+    #address-cells = <2>;
+    #size-cells = <2>;
+
+	soc {
+		compatible = "simple-bus";
+		ranges;
+		#address-cells = <2>;
+		#size-cells = <2>;
+
+		coproc0@e6110000 {
+			xen,vcoproc = "/soc/pcoproc0@0xe6110000";
+			compatible = "vendor_xxx,coproc_xxx";
+			reg = <0x0 0xe6110000 0x0 0x1000>;
+			interrupts = <GIC_SPI 160 IRQ_TYPE_LEVEL_HIGH>;
+			status = "okay";
+		};
+		coproc0@e6114000 {
+			xen,vcoproc = "pcoproc0";
+			compatible = "vendor_xxx,coproc_xxx";
+			reg = <0x0 0xe6114000 0x0 0x1000>;
+			interrupts = <GIC_SPI 160 IRQ_TYPE_LEVEL_HIGH>;
+			status = "okay";
+		};
+
+		coproc1@0xe6182000 {
+			xen,vcoproc = "/soc/pcoproc1@0xe6182000";
+			compatible = "vendor_xxx,coproc_xxc";
+			reg = <0x0 0xe6182000 0x0 0x1000>,
+				<0x0 0xe6184000 0x0 0x1000>,
+				<0x0 0xe6188000 0x0 0x8000>;
+			reg-names = "op", "mmu", "sram";
+			interrupts = <GIC_SPI 132 IRQ_TYPE_LEVEL_HIGH>,
+					<GIC_SPI 135 IRQ_TYPE_LEVEL_HIGH>;
+			interrupt-names = "op", "mmu";
+		};
+
+		coproc1@0xe619a000 {
+			xen,vcoproc = "pcoproc1";
+			compatible = "vendor_xxx,coproc_xxc";
+			reg = <0x0 0xe619a000 0x0 0x1000>,
+				<0x0 0xe6152000 0x0 0x1000>,
+				<0x0 0xe6058000 0x0 0x8000>;
+			reg-names = "op", "mmu", "sram";
+			interrupts = <GIC_SPI 132 IRQ_TYPE_LEVEL_HIGH>,
+					<GIC_SPI 135 IRQ_TYPE_LEVEL_HIGH>;
+			interrupt-names = "op", "mmu";
+		};
+};
+
+Notes:
+    * For a Dom0 device tree in vcoproc nodes you should specify only properties
+      you would like to override, other properties would be taken from physical
+      coprocessor node.
+    * In a DomU partial device tree you should provide all needed properties for
+      virtual coprocessor node which you need in a DomU device tree.
+
+3) Compile the partial guest device with dtc (Device Tree Compiler).
+For our purpose, the compiled file will be called domu.dtb and
+placed in /xen/ in Dom0.
+
+3) Specify a partial device tree in a DomU configuration file:
+
+device_tree = "/xen/domu.dts"
+
+4) Nothing else should be specified in a domain configuration file. All SCF
+configuration is described in a system device-tree and partial device tree.
+
+
-- 
2.7.4


_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel

^ permalink raw reply related	[flat|nested] 20+ messages in thread