Re: [PATCH v6 7/7] docs: Add device tree overlay documentation

[Julien Grall <julien@xxxxxxx>]

Hi Stefano,

On 24/05/2024 23:16, Stefano Stabellini wrote:
> From: Vikram Garhwal <fnu.vikram@xxxxxxxxxx>
>
> Signed-off-by: Vikram Garhwal <fnu.vikram@xxxxxxxxxx>
> Signed-off-by: Stefano Stabellini <stefano.stabellini@xxxxxxxxxx>
> Signed-off-by: Henry Wang <xin.wang2@xxxxxxx>
> ---
>   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@xxxxxxxxxx>

Cheers,

--
Julien Grall