| Message ID | 20240524221647.2860711-7-stefano.stabellini@amd.com (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | Remaining patches for dynamic node programming using overlay dtbo | expand |
Hi Stefano, On 24/05/2024 23:16, Stefano Stabellini wrote: > From: Vikram Garhwal <fnu.vikram@xilinx.com> > > Signed-off-by: Vikram Garhwal <fnu.vikram@xilinx.com> > Signed-off-by: Stefano Stabellini <stefano.stabellini@xilinx.com> > Signed-off-by: Henry Wang <xin.wang2@amd.com> > --- > docs/misc/arm/overlay.txt | 82 +++++++++++++++++++++++++++++++++++++++ > 1 file changed, 82 insertions(+) > create mode 100644 docs/misc/arm/overlay.txt > > diff --git a/docs/misc/arm/overlay.txt b/docs/misc/arm/overlay.txt > new file mode 100644 > index 0000000000..ef3ef792f7 > --- /dev/null > +++ b/docs/misc/arm/overlay.txt > @@ -0,0 +1,82 @@ > +# Device Tree Overlays support in Xen > + > +Xen experimentally supports dynamic device assignment to running > +domains, i.e. adding/removing nodes (using .dtbo) to/from Xen device > +tree, and attaching them to a running domain with given $domid. > + > +Dynamic node assignment works in two steps: > + > +## Add/Remove device tree overlay to/from Xen device tree > + > +1. Xen tools check the dtbo given and parse all other user provided arguments > +2. Xen tools pass the dtbo to Xen hypervisor via hypercall. > +3. Xen hypervisor applies/removes the dtbo to/from Xen device tree. > + > +## Attach device from the DT overlay to domain > + > +1. Xen tools check the dtbo given and parse all other user provided arguments > +2. Xen tools pass the dtbo to Xen hypervisor via hypercall. > +3. Xen hypervisor attach the device to the user-provided $domid by > + mapping node resources in the DT overlay. > + > +# Examples > + > +Here are a few examples on how to use it. > + > +## Dom0 device add > + > +For assigning a device tree overlay to Dom0, user should firstly properly > +prepare the DT overlay. More information about device tree overlays can be > +found in [1]. Then, in Dom0, enter the following: > + > + (dom0) xl dt-overlay add overlay.dtbo > + > +This will allocate the devices mentioned in overlay.dtbo to Xen device tree. > + > +To assign the newly added device from the dtbo to Dom0: > + > + (dom0) xl dt-overlay attach overlay.dtbo 0 > + > +Next, if the user wants to add the same device tree overlay to dom0 > +Linux, execute the following: > + > + (dom0) mkdir -p /sys/kernel/config/device-tree/overlays/new_overlay > + (dom0) cat overlay.dtbo > /sys/kernel/config/device-tree/overlays/new_overlay/dtbo > + > +Finally if needed, the relevant Linux kernel drive can be loaded using: > + > + (dom0) modprobe module_name.ko > + > +## DomU device add/remove > + > +All the nodes in dtbo will be assigned to one domain. The user will need > +to prepare a different dtbo for the domU. For example, the > +`interrupt-parent` property of the DomU overlay should be changed to the > +Xen hardcoded value `0xfde8` and the xen,reg property should be added to > +specify the address mappings. If the domain is not 1:1 mapped, xen,reg > +must be present. See the xen,reg format description in > +docs/misc/arm/passthrough.txt. Below assumes the properly written DomU > +dtbo is `overlay_domu.dtbo`. > + > +You need to set the `passthrough` property in the xl config file if you s/You need/The user needs/ to match the rest of the documentation. With that addresed: Reviewed-by: Julien Grall <jgrall@amazon.com> Cheers,
diff --git a/docs/misc/arm/overlay.txt b/docs/misc/arm/overlay.txt new file mode 100644 index 0000000000..ef3ef792f7 --- /dev/null +++ b/docs/misc/arm/overlay.txt @@ -0,0 +1,82 @@ +# Device Tree Overlays support in Xen + +Xen experimentally supports dynamic device assignment to running +domains, i.e. adding/removing nodes (using .dtbo) to/from Xen device +tree, and attaching them to a running domain with given $domid. + +Dynamic node assignment works in two steps: + +## Add/Remove device tree overlay to/from Xen device tree + +1. Xen tools check the dtbo given and parse all other user provided arguments +2. Xen tools pass the dtbo to Xen hypervisor via hypercall. +3. Xen hypervisor applies/removes the dtbo to/from Xen device tree. + +## Attach device from the DT overlay to domain + +1. Xen tools check the dtbo given and parse all other user provided arguments +2. Xen tools pass the dtbo to Xen hypervisor via hypercall. +3. Xen hypervisor attach the device to the user-provided $domid by + mapping node resources in the DT overlay. + +# Examples + +Here are a few examples on how to use it. + +## Dom0 device add + +For assigning a device tree overlay to Dom0, user should firstly properly +prepare the DT overlay. More information about device tree overlays can be +found in [1]. Then, in Dom0, enter the following: + + (dom0) xl dt-overlay add overlay.dtbo + +This will allocate the devices mentioned in overlay.dtbo to Xen device tree. + +To assign the newly added device from the dtbo to Dom0: + + (dom0) xl dt-overlay attach overlay.dtbo 0 + +Next, if the user wants to add the same device tree overlay to dom0 +Linux, execute the following: + + (dom0) mkdir -p /sys/kernel/config/device-tree/overlays/new_overlay + (dom0) cat overlay.dtbo > /sys/kernel/config/device-tree/overlays/new_overlay/dtbo + +Finally if needed, the relevant Linux kernel drive can be loaded using: + + (dom0) modprobe module_name.ko + +## DomU device add/remove + +All the nodes in dtbo will be assigned to one domain. The user will need +to prepare a different dtbo for the domU. For example, the +`interrupt-parent` property of the DomU overlay should be changed to the +Xen hardcoded value `0xfde8` and the xen,reg property should be added to +specify the address mappings. If the domain is not 1:1 mapped, xen,reg +must be present. See the xen,reg format description in +docs/misc/arm/passthrough.txt. Below assumes the properly written DomU +dtbo is `overlay_domu.dtbo`. + +You need to set the `passthrough` property in the xl config file if you +plan to use DT overlay and devices requiring an IOMMU. + +User will also need to modprobe the relevant drivers. For already +running domains, the user can use the xl dt-overlay attach command, +example: + + (dom0) xl dt-overlay add overlay.dtbo # If not executed before + (dom0) xl dt-overlay attach overlay_domu.dtbo $domid + (dom0) xl console $domid # To access $domid console + +Next, if the user needs to modify/prepare the overlay.dtbo suitable for +the domU: + + (domU) mkdir -p /sys/kernel/config/device-tree/overlays/new_overlay + (domU) cat overlay_domu.dtbo > /sys/kernel/config/device-tree/overlays/new_overlay/dtbo + +Finally, if needed, the relevant Linux kernel drive can be probed: + + (domU) modprobe module_name.ko + +[1] https://www.kernel.org/doc/Documentation/devicetree/overlay-notes.txt