1 files changed, 104 insertions, 0 deletions
diff --git a/bsp/meta-arm/meta-arm-autonomy/documentation/xen-devicetree.md b/bsp/meta-arm/meta-arm-autonomy/documentation/xen-devicetree.md
new file mode 100644
index 00000000..a44dca78
--- /dev/null
+++ b/bsp/meta-arm/meta-arm-autonomy/documentation/xen-devicetree.md
@@ -0,0 +1,104 @@
+Xen device tree
+===============
+
+Introduction
+------------
+
+xen-devicetree recipe can be used to modify an existing Device Tree Blob,
+produced by Linux kernel or another recipe, to include in it entries required
+to start Xen and a Dom0 Linux on top of it.
+
+The recipe will do the following processing:
+- generate a xen.dtsi file with entries required for xen based on parameters
+- turn DTBs in ${XEN_DEVICETREE_DTBS} back to dts
+- include in xen.dtsi and all other dtsi from
+  ${XEN_DEVICETREE_DTSI_MERGE} (check Bitbake parameters for more information
+  on this).
+- use dtc to create a new DTB file
+
+The recipe will generate new files in deploy/images and name them with the
+extension "-xen.dtb".
+For example **machine.dtb** will generate **machine-xen.dtb**.
+
+Entries added to the DTBs
+-------------------------
+
+When a DTB is processed by the recipe, the following block is added:
+```
+    chosen {
+        xen,dom0-bootargs = "VAL";
+        xen,xen-bootargs = "VAL";
+
+        modules {
+            #size-cells = <0x00000001>;
+            #address-cells = <0x00000001>;
+
+            module@0 {
+                reg = <VAL VAL>;
+                compatible = "multiboot,module";
+            };
+        };
+    };
+```
+Each occurence of **VAL** is replaced by the content of the variables listed in
+this documentation.
+
+Bitbake parameters
+------------------
+
+Several parameters are available to configure the xen-devicetree during Yocto
+project compilation (those can be set in your project local.conf, for exmple).
+
+The following parameters are available:
+
+- XEN_DEVICETREE_DEPEND: This variable can be used to indicate which recipe
+  task is generating the DTBs that xen-devicetree will modify. This makes sure
+  the xen devicetrees are properly regenerated if the source DTBs are changed.
+  This variable is set by default to "virtual/kernel:do_deploy" to use DTBs
+  generated during the compilation of the Linux kernel. This must be changed
+  if the machine your are using is not using a DTB listed in KERNEL_DEVICETREE.
+
+- XEN_DEVICETREE_DTBS: This should be set to the list of DTBs you want to be
+  modified by xen-devicetree. Those must be files that xen-devicetree can find
+  in the ${DEPLOY_DIR_IMAGE} directory using only the basename of the entries.
+  For example "mydir/board.dtb" will make the recipe look for
+  ${DEPLOY_DIR_IMAGE}/board.dtb.
+  This variable is set by default to "${KERNEL_DEVICETREE}" to process the DTBs
+  generated by the Linux kernel.
+
+- XEN_DEVICETREE_DOM0_MEM: Memory size to allocate to Dom0.
+  This variable is only used if XEN_DEVICETREE_XEN_BOOTARGS has a value
+  containing "dom0_mem=${XEN_DEVICETREE_DOM0_MEM}" as the memory assigned to
+  dom0 is defined using Xen boot arguments.
+  This variable is set by default to "1024M".
+
+- XEN_DEVICETREE_DOM0_BOOTARGS: Boot arguments to pass to Dom0 Linux when
+  booting it.
+  This variable is set by default to "console=hvc0 earlycon=xen".
+
+- XEN_DEVICETREE_XEN_BOOTARGS: this variable should be set with the boot
+  arguments to be passed to Xen on boot.
+  This variable is set by default to
+  "noreboot dom0_mem=${XEN_DEVICETREE_DOM0_MEM}".
+
+- XEN_DEVICETREE_DOM0_ADDR: This is the address from which the Linux kernel to
+  be used for Dom0 will be copied. When using u-boot, this is the address at
+  which you will load the kernel Image before starting Xen.
+  This variable is set by default to "0x80080000".
+
+- XEN_DEVICETREE_DOM0_SIZE: This is the size of the kernel loaded at
+  ${XEN_DEVICETREE_DOM0_ADDR}. Xen will copy this amount of data inside the
+  guest before starting it so the size must be at least equal to the kernel
+  size but can be bigger. You must be careful not to have a value too big as it
+  could slow down boot or copy other parts with it (like the DTB).
+  You might need to increase this if you use a kernel with a bundled initramfs.
+  This variable is set by default to "0x01000000".
+
+- XEN_DEVICETREE_DTSI_MERGE: This variable contains the list of dtsi files that
+  must be included inside the generated DTB file. By default the only one
+  include is the "xen.dtsi" generated by the recipe.
+  If your board or project needs to include more fixes or entries in the DTB,
+  this variable can be appended from a bbappend file to include other dtsi. The
+  files must be inside the recipe workspace during Yocto compilation.
+  You can check xen-devicetree.bbappend for an example.
+