[RESEND PATCH v2 18/18] doc: xen: Add Xen guest ARM64 board documentation

Anastasiia Lukianenko
2020-08-06T09:43:01Z

From: Anastasiia Lukianenko <anastasiia_lukianenko@epam.com>

Signed-off-by: Anastasiia Lukianenko <anastasiia_lukianenko@epam.com>
---

Changes since v1:
- this patch appeared in the second version of patch series for describing
new board specification

doc/board/index.rst | 1 +
doc/board/xen/index.rst | 9 ++++
doc/board/xen/xenguest_arm64.rst | 81 ++++++++++++++++++++++++++++++++
3 files changed, 91 insertions(+)
create mode 100644 doc/board/xen/index.rst
create mode 100644 doc/board/xen/xenguest_arm64.rst

diff --git a/doc/board/index.rst b/doc/board/index.rst
index 0a15899180..63935abcd7 100644
--- a/doc/board/index.rst
+++ b/doc/board/index.rst
@@ -22,4 +22,5 @@ Board-specific doc
st/index
tbs/index
toradex/index
+ xen/index
xilinx/index
diff --git a/doc/board/xen/index.rst b/doc/board/xen/index.rst
new file mode 100644
index 0000000000..e58fe9e351
--- /dev/null
+++ b/doc/board/xen/index.rst
@@ -0,0 +1,9 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+XenGuestARM64
+=============
+
+.. toctree::
+ :maxdepth: 2
+
+ xenguest_arm64
diff --git a/doc/board/xen/xenguest_arm64.rst b/doc/board/xen/xenguest_arm64.rst
new file mode 100644
index 0000000000..1327f88f99
--- /dev/null
+++ b/doc/board/xen/xenguest_arm64.rst
@@ -0,0 +1,81 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Xen guest ARM64 board
+=====================
+
+This board specification
+------------------------
+
+This board is to be run as a virtual Xen [1] guest with U-boot as its primary
+bootloader. Xen is a type 1 hypervisor that allows multiple operating systems
+to run simultaneously on a single physical server. Xen is capable of running
+virtual machines in both full virtualization and para-virtualization (PV)
+modes. Xen runs virtual machines, which are called ?domains?.
+
+Paravirtualized drivers are a special type of device drivers that are used in
+a guest system in the Xen domain and perform I/O operations using a special
+interface provided by the virtualization system and the host system.
+
+Xen support for U-boot is implemented by introducing a new Xen guest ARM64
+board and porting essential drivers from MiniOS [3] as well as some of the work
+previously done by NXP [4]:
+
+- PV block device frontend driver with XenStore based device enumeration and
+ UCLASS_PVBLOCK class;
+- PV serial console device frontend driver;
+- Xen hypervisor support with minimal set of the essential headers adapted from
+ the Linux kernel;
+- Xen grant table support;
+- Xen event channel support in polling mode;
+- XenBus support;
+- dynamic RAM size as defined in the device tree instead of the statically
+ defined values;
+- position-independent pre-relocation code is used as we cannot statically
+ define any start addresses at compile time which is up to Xen to choose at
+ run-time;
+- new defconfig introduced: xenguest_arm64_defconfig.
+
+
+Board limitations
+-----------------
+
+1. U-boot runs without MMU enabled at the early stages.
+ According to Xen on ARM ABI (xen/include/public/arch-arm.h): all memory
+ which is shared with other entities in the system (including the hypervisor
+ and other guests) must reside in memory which is mapped as Normal Inner
+ Write-Back Outer Write-Back Inner-Shareable.
+ Thus, page attributes must be equally set for all the entities working with
+ that page.
+ Before MMU is set up the data cache is turned off and pages are seen by the
+ vCPU and Xen in different ways - cacheable by Xen and non-cacheable by vCPU.
+ So it means that manual data cache maintenance is required at the early
+ stages.
+
+2. No serial console until MMU is up.
+ Because data cache maintenance is required until the MMU setup the
+ early/debug serial console is not implemented. Therefore, we do not have
+ usual prints like U-boot?s banner etc. until the serial driver is
+ initialized.
+
+3. Single RAM bank supported.
+ If a Xen guest is given much memory it is possible that Xen allocates two
+ memory banks for it. The first one is allocated under 4GB address space and
+ in some cases may represent the whole guest?s memory. It is assumed that
+ U-boot most likely won?t require high memory bank for its work andlaunching
+ OS, so it is enough to take the first one.
+
+
+Board default configuration
+---------------------------
+
+One can select the configuration as follows:
+
+ - make xenguest_arm64_defconfig
+
+[1] - https://xenproject.org/
+
+[2] - https://wiki.xenproject.org/wiki/Paravirtualization_(PV)
+
+[3] - https://wiki.xenproject.org/wiki/Mini-OS
+
+[4] - https://source.codeaurora.org/external/imx/uboot-imx/tree/?h=imx_v2018.03_4.14.98_2.0.0_ga
--
2.17.1