From 59d03d28b2bb2fb819db2c1fa2e8dc4f650d3894 Mon Sep 17 00:00:00 2001 From: Andrew Cooper Date: Fri, 19 Jul 2019 08:57:50 +0100 Subject: [PATCH] docs/sphinx: Introduction Put together an introduction page for the Sphinx/RST docs, along with a glossary which will accumulate over time. Signed-off-by: Andrew Cooper Reviewed-by: Lars Kurth Release-acked-by: Juergen Gross --- docs/admin-guide/index.rst | 1 + docs/admin-guide/introduction.rst | 38 ++++++++++ docs/admin-guide/xen-overview.drawio.svg | 97 ++++++++++++++++++++++++ docs/glossary.rst | 50 ++++++++++++ docs/index.rst | 12 +++ 5 files changed, 198 insertions(+) create mode 100644 docs/admin-guide/introduction.rst create mode 100644 docs/admin-guide/xen-overview.drawio.svg create mode 100644 docs/glossary.rst diff --git a/docs/admin-guide/index.rst b/docs/admin-guide/index.rst index 6907d58829..fb5fa363d3 100644 --- a/docs/admin-guide/index.rst +++ b/docs/admin-guide/index.rst @@ -2,4 +2,5 @@ Admin Guide =========== .. toctree:: + introduction microcode-loading diff --git a/docs/admin-guide/introduction.rst b/docs/admin-guide/introduction.rst new file mode 100644 index 0000000000..ea960308ab --- /dev/null +++ b/docs/admin-guide/introduction.rst @@ -0,0 +1,38 @@ +Introduction +============ + +Xen is an open source, bare metal hypervisor. It runs as the most privileged +piece of software, and shares the resources of the hardware between virtual +machines. + +In Xen terminology, there are :term:`domains`, commonly abbreviated to +dom, which are identified by their numeric :term:`domid`. + +When Xen boots, dom0 is automatically started as well. Dom0 is a virtual +machine which, by default, is granted full permissions [1]_. A typical setup +might be: + +.. image:: xen-overview.drawio.svg + +Dom0 takes the role of :term:`control domain`, responsible for creating and +managing other virtual machines, and the role of :term:`hardware domain`, +responsible for hardware and marshalling guest I/O. + +Xen is deliberately minimal, and has no device drivers [2]_. Xen manages RAM, +schedules virtual CPUs on the available physical CPUs, and marshals +interrupts. + +Xen also provides a hypercall interface to guests, including event channels +(virtual interrupts), grant tables (shared memory), on which a lot of higher +level functionality is built. + +.. rubric:: Footnotes + +.. [1] A common misconception with Xen's architecture is that dom0 is somehow + different to other guests. The choice of id 0 is not an accident, and + follows in UNIX heritage. + +.. [2] This definition might be fuzzy. Xen can talk to common serial UARTs, + and knows how to drive various CPU internal devices such as IOMMUs, but + has no knowledge of network cards, disks, etc. All of that is the + hardware domains responsibility. diff --git a/docs/admin-guide/xen-overview.drawio.svg b/docs/admin-guide/xen-overview.drawio.svg new file mode 100644 index 0000000000..f120cdf77a --- /dev/null +++ b/docs/admin-guide/xen-overview.drawio.svg @@ -0,0 +1,97 @@ + + + + + + + + Xen + + + + Dom0 + + + + DomU + + + + DomU + + + + Hardware + + + + NIC + + + + Disk + + + + Systems Services + + + + Applications + + + + Applications + + + + Kernel + + + + Net + + + + Block + + + + Kernel + + + + Kernel + + + + Net + + + + Block + + + + Net + + + + Block + + + + + + + + + + + + + + + + + diff --git a/docs/glossary.rst b/docs/glossary.rst new file mode 100644 index 0000000000..b5ea88b6dc --- /dev/null +++ b/docs/glossary.rst @@ -0,0 +1,50 @@ +Glossary +======== + +.. Terms should appear in alphabetical order + +.. glossary:: + + control domain + A :term:`domain`, commonly dom0, with the permission and responsibility + to create and manage other domains on the system. + + domain + A domain is Xen's unit of resource ownership, and generally has at the + minimum some RAM and virtual CPUs. + + The terms :term:`domain` and :term:`guest` are commonly used + interchangeably, but they mean subtly different things. + + A guest is a single, end user, virtual machine. + + In some cases, e.g. during live migration, one guest will be comprised of + two domains for a period of time, while it is in transit. + + domid + The numeric identifier of a running :term:`domain`. It is unique to a + single instance of Xen, used as the identifier in various APIs, and is + typically allocated sequentially from 0. + + guest + The term 'guest' has two different meanings, depending on context, and + should not be confused with :term:`domain`. + + When discussing a Xen system as a whole, a 'guest' refer to a virtual + machine which is the "useful output" of running the system in the first + place (e.g. an end-user VM). Virtual machines providing system services, + (e.g. the control and/or hardware domains), are not considered guests in + this context. + + In the code, "guest context" and "guest state" is considered in terms of + the CPU architecture, and contrasted against hypervisor context/state. + In this case, it refers to all code running lower privilege privilege + level the hypervisor. As such, it covers all domains, including ones + providing system services. + + hardware domain + A :term:`domain`, commonly dom0, which shares responsibility with Xen + about the system as a whole. + + By default it gets all devices, including all disks and network cards, so + is responsible for multiplexing guest I/O. diff --git a/docs/index.rst b/docs/index.rst index 470541f007..8d402e20a9 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,6 +6,10 @@ The Xen Hypervisor documentation Xen's Sphinx/RST documentation is a work in progress. The existing documentation can be found at https://xenbits.xen.org/docs/ +Xen is an open source, bare metal hypervisor. It runs as the most privileged +piece of software on the system, and shares the resources of the hardware +between virtual machines. See :doc:`admin-guide/introduction` for an +introduction to a Xen system. User documentation ------------------ @@ -45,3 +49,11 @@ kind of development environment. :maxdepth: 2 hypervisor-guide/index + + +Miscellanea +----------- + +.. toctree:: + + glossary -- 2.30.2