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 <andrew.cooper3@citrix.com>
Reviewed-by: Lars Kurth <lars.kurth@citrix.com>
Release-acked-by: Juergen Gross <jgross@suse.com>

diff --git a/docs/admin-guide/index.rst b/docs/admin-guide/index.rst
index 6907d5882965c3982a28f6f883e14850e41ca1d0..fb5fa363d3e6c353ae4bba8f80dd0e77eea6f33a 100644 (file)
--- 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 (file)
index 0000000..ea96030
--- /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<domain>`, 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 (file)
index 0000000..f120cdf
--- /dev/null
+++ b/docs/admin-guide/xen-overview.drawio.svg
@@ -0,0 +1,97 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="701px" height="461px" viewBox="-0.5 -0.5 701 461" content="&lt;mxfile modified=&quot;2019-08-04T17:05:55.267Z&quot; host=&quot;&quot; agent=&quot;Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/11.1.1 Chrome/76.0.3809.88 Electron/6.0.0 Safari/537.36&quot; etag=&quot;M7ISh4Ny83I7m1UfK1F2&quot; version=&quot;11.1.1&quot; type=&quot;device&quot;&gt;&lt;diagram id=&quot;7q-U8ZVDCMAbtjTOF8Vq&quot; name=&quot;Page-1&quot;&gt;7Zpbd5s4EMc/jR/Tw/3y6FuadNu0jde72X3pwSAua4w4smzjfPoVRhiD5DvGbM42D0WDkMRv5q8ZDB25P0s+Iyv2v0EHhB1JcJKOPOhIkigKEvkvtawziyGamcFDgUM7FYZR8A6oUaDWReCAeakjhjDEQVw22jCKgI1LNgshuCp3c2FYnjW2PMAYRrYVstY/Awf79C5UobA/gcDz8faG6ZmZlXemhrlvOXC1Y5KHHbmPIMTZ0SzpgzCFl3PJrnvcc3a7MAQifMoFySP67j/+MuJ+8nUIfo3D/it4oN5ZWuGC3vAbiOh68TqHgOAickA6jtCRe24Qhn0YQrQ5KbuGDWyb2OcYwSnYOTMxVEXdXAEjTF0rpe0lQDggjLth4EXEOAscJ52rZ1EDyoj2fIiCd3KxFRKjmM4RW3YQea+UuFqYaIulQkGlc4Jkx0QpfQZwBjBaky40RGWZemxVOFzP3ervOFujNovGmLcdqnADOaCeOMMrCuOVAZwJ57nFUYHhKDy3GNJE1rQd2iFwMccrGMYc310DeAfoVha7QCXjVkRVHtFxR9IID7G4rb1wT0NV8YAFDJcrDM02wMStGS49Kyls9N4OtjcZP78mzz/hj/fk53T8Pv2+/v1BZHeVj0pbMZqk/fJtjKDyNogfu8/CQDKXttV9kBnYTxZyVuSujm0Yl+7K1QTguhI/ATjaRFO1enZlRWhwV+aC1hjQL8/9MxnnKG0CAqCaFE9vOAclsqAMDiflVpx0Vv3BfNoCUOIdSRlfxoH79OWP0Ys2nI49bRz+veJUX6P1HIPZnBhHAC0Dm5S+14k42yvrgFdhx9n3eGoUxVvBY/e9bhyH5N5xAKPWYJPUtnFji8s2clPMtnFjS8jfAIrSx90aiJ3/TFWpkepXuKg1iZxbSLLIXwA+nbeoNZNxt+0G8giXE1uZ9EJon5Fyb0aqmnKbRMVVMYvqg6m4mnCalTGXOVsQfjDm1WTVgq2TrY5asnVqLds72XKoLXun3DZUIsuqHUGlCm0jxVYubYkqrXWsRIYVgwk4HhjRJkTYhx6MrHBYWHtlkEWfrzDNEpt3B/8AjNcUr7XAkJNi5r4Vpw03BEk3fXtEbAQ1Wr+lA39S8+ZfdMhNY5DQWbPWusN/TaKmf9zfJzf/NmcshOm0g8kmXsigSYCz2XWVNrezk+Ni8rSRz71913TwZ845XCAbHHANjWKyLA/g48km9dLBEEQgJE+ZS1BaBS+g6KU/YECWXGyIRjl0lWr2zBZKryrCkhmoMo5aje0MDDMOcY213ukWpx3m+9dbmUYyhYOrkqvKLPcnB9kCCqlt0V6hPrY4a5X67qmiS5V/mvqOqipPtzeXVTXuqr+gXygrZpz7yGqr7iZlJbGlUqtkVVNSA6KjAp0nR1PTZateOe5V0s0FYpqfdFMWBVlRDElXjXI8qeWzpnyZekSdP86J09QkLrGiLlk8krRM81D/G6mLLa9bpa57quRSZd9NXZr8v7r2rVpTDva/Wl3c97dmY1ry8SzcieEsaqWLYl0qBbtwJNhLFdopZacLtD2fOOjmRBD2KXivqC559Dr0UUJ9Ir3q1X/+QHZW7PD4/6fjiRcJ5wfU5bGjnRg7ekOxQ5rFZ67ZLlV8LCwP/wU=&lt;/diagram&gt;&lt;/mxfile&gt;">
+  <defs/>
+  <g>
+    <rect x="0" y="330" width="700" height="60" fill="#f8cecc" stroke="#b85450" pointer-events="none"/>
+    <g fill="#000000" font-family="Helvetica" text-anchor="end" font-size="20px">
+      <text x="688.5" y="367.5">Xen</text>
+    </g>
+    <rect x="0" y="0" width="220" height="280" fill="#d5e8d4" stroke="#82b366" pointer-events="none"/>
+    <g fill="#000000" font-family="Helvetica" font-size="20px">
+      <text x="2.5" y="26.5">Dom0</text>
+    </g>
+    <rect x="240" y="0" width="220" height="280" fill="#dae8fc" stroke="#6c8ebf" pointer-events="none"/>
+    <g fill="#000000" font-family="Helvetica" font-size="20px">
+      <text x="242.5" y="26.5">DomU</text>
+    </g>
+    <rect x="480" y="0" width="220" height="280" fill="#dae8fc" stroke="#6c8ebf" pointer-events="none"/>
+    <g fill="#000000" font-family="Helvetica" font-size="20px">
+      <text x="482.5" y="26.5">DomU</text>
+    </g>
+    <rect x="0" y="400" width="700" height="60" fill="#fff2cc" stroke="#d6b656" pointer-events="none"/>
+    <g fill="#000000" font-family="Helvetica" text-anchor="end" font-size="20px">
+      <text x="696.5" y="437.5">Hardware</text>
+    </g>
+    <rect x="20" y="410" width="80" height="40" fill="#ffffff" stroke="#000000" pointer-events="none"/>
+    <g fill="#000000" font-family="Helvetica" text-anchor="middle" font-size="20px">
+      <text x="59.5" y="437.5">NIC</text>
+    </g>
+    <rect x="120" y="410" width="80" height="40" fill="#ffffff" stroke="#000000" pointer-events="none"/>
+    <g fill="#000000" font-family="Helvetica" text-anchor="middle" font-size="20px">
+      <text x="159.5" y="437.5">Disk</text>
+    </g>
+    <rect x="10" y="40" width="200" height="110" fill="#ffffff" stroke="#000000" pointer-events="none"/>
+    <g fill="#000000" font-family="Helvetica" text-anchor="middle" font-size="20px">
+      <text x="109.5" y="66.5">Systems Services</text>
+    </g>
+    <rect x="250" y="40" width="200" height="110" fill="#ffffff" stroke="#000000" pointer-events="none"/>
+    <g fill="#000000" font-family="Helvetica" text-anchor="middle" font-size="20px">
+      <text x="349.5" y="66.5">Applications</text>
+    </g>
+    <rect x="490" y="40" width="200" height="110" fill="#ffffff" stroke="#000000" pointer-events="none"/>
+    <g fill="#000000" font-family="Helvetica" text-anchor="middle" font-size="20px">
+      <text x="589.5" y="66.5">Applications</text>
+    </g>
+    <rect x="10" y="160" width="200" height="110" fill="#f8cecc" stroke="#b85450" pointer-events="none"/>
+    <g fill="#000000" font-family="Helvetica" font-size="20px">
+      <text x="12.5" y="186.5">Kernel</text>
+    </g>
+    <rect x="20" y="220" width="80" height="40" fill="#ffffff" stroke="#000000" pointer-events="none"/>
+    <g fill="#000000" font-family="Helvetica" text-anchor="middle" font-size="16px">
+      <text x="59.5" y="245.5">Net</text>
+    </g>
+    <rect x="120" y="220" width="80" height="40" fill="#ffffff" stroke="#000000" pointer-events="none"/>
+    <g fill="#000000" font-family="Helvetica" text-anchor="middle" font-size="16px">
+      <text x="159.5" y="245.5">Block</text>
+    </g>
+    <rect x="250" y="160" width="200" height="110" fill="#f8cecc" stroke="#b85450" pointer-events="none"/>
+    <g fill="#000000" font-family="Helvetica" font-size="20px">
+      <text x="252.5" y="186.5">Kernel</text>
+    </g>
+    <rect x="490" y="160" width="200" height="110" fill="#f8cecc" stroke="#b85450" pointer-events="none"/>
+    <g fill="#000000" font-family="Helvetica" font-size="20px">
+      <text x="492.5" y="186.5">Kernel</text>
+    </g>
+    <rect x="260" y="220" width="80" height="40" fill="#ffffff" stroke="#000000" pointer-events="none"/>
+    <g fill="#000000" font-family="Helvetica" text-anchor="middle" font-size="16px">
+      <text x="299.5" y="245.5">Net</text>
+    </g>
+    <rect x="360" y="220" width="80" height="40" fill="#ffffff" stroke="#000000" pointer-events="none"/>
+    <g fill="#000000" font-family="Helvetica" text-anchor="middle" font-size="16px">
+      <text x="399.5" y="245.5">Block</text>
+    </g>
+    <rect x="500" y="220" width="80" height="40" fill="#ffffff" stroke="#000000" pointer-events="none"/>
+    <g fill="#000000" font-family="Helvetica" text-anchor="middle" font-size="16px">
+      <text x="539.5" y="245.5">Net</text>
+    </g>
+    <rect x="600" y="220" width="80" height="40" fill="#ffffff" stroke="#000000" pointer-events="none"/>
+    <g fill="#000000" font-family="Helvetica" text-anchor="middle" font-size="16px">
+      <text x="639.5" y="245.5">Block</text>
+    </g>
+    <path d="M 75 279.5 L 64.5 279.5 L 80 260.5 L 95.5 279.5 L 85 279.5 L 85 285 L 295 285 L 295 279.5 L 284.5 279.5 L 300 260.5 L 315.5 279.5 L 305 279.5 L 305 295 L 75 295 Z" fill="#f5f5f5" stroke="#666666" stroke-miterlimit="1.42" pointer-events="none"/>
+    <path d="M 75 279.5 L 64.5 279.5 L 80 260.5 L 95.5 279.5 L 85 279.5" fill="none" stroke="#666666" stroke-miterlimit="4" pointer-events="none"/>
+    <path d="M 295 279.5 L 284.5 279.5 L 300 260.5 L 315.5 279.5 L 305 279.5" fill="none" stroke="#666666" stroke-miterlimit="4" pointer-events="none"/>
+    <path d="M 75 279.5 L 64.5 279.5 L 80 260.5 L 95.5 279.5 L 85 279.5 L 85 285 L 535 285 L 535 279.5 L 524.5 279.5 L 540 260.5 L 555.5 279.5 L 545 279.5 L 545 295 L 75 295 Z" fill="#f5f5f5" stroke="#666666" stroke-miterlimit="1.42" pointer-events="none"/>
+    <path d="M 75 279.5 L 64.5 279.5 L 80 260.5 L 95.5 279.5 L 85 279.5" fill="none" stroke="#666666" stroke-miterlimit="4" pointer-events="none"/>
+    <path d="M 535 279.5 L 524.5 279.5 L 540 260.5 L 555.5 279.5 L 545 279.5" fill="none" stroke="#666666" stroke-miterlimit="4" pointer-events="none"/>
+    <path d="M 175 279.5 L 164.5 279.5 L 180 260.5 L 195.5 279.5 L 185 279.5 L 185 305 L 395 305 L 395 279.5 L 384.5 279.5 L 400 260.5 L 415.5 279.5 L 405 279.5 L 405 315 L 175 315 Z" fill="#e1d5e7" stroke="#9673a6" stroke-miterlimit="1.42" pointer-events="none"/>
+    <path d="M 175 279.5 L 164.5 279.5 L 180 260.5 L 195.5 279.5 L 185 279.5" fill="none" stroke="#9673a6" stroke-miterlimit="4" pointer-events="none"/>
+    <path d="M 395 279.5 L 384.5 279.5 L 400 260.5 L 415.5 279.5 L 405 279.5" fill="none" stroke="#9673a6" stroke-miterlimit="4" pointer-events="none"/>
+    <path d="M 175 279.5 L 164.5 279.5 L 180 260.5 L 195.5 279.5 L 185 279.5 L 185 305 L 635 305 L 635 279.5 L 624.5 279.5 L 640 260.5 L 655.5 279.5 L 645 279.5 L 645 315 L 175 315 Z" fill="#e1d5e7" stroke="#9673a6" stroke-miterlimit="1.42" pointer-events="none"/>
+    <path d="M 175 279.5 L 164.5 279.5 L 180 260.5 L 195.5 279.5 L 185 279.5" fill="none" stroke="#9673a6" stroke-miterlimit="4" pointer-events="none"/>
+    <path d="M 635 279.5 L 624.5 279.5 L 640 260.5 L 655.5 279.5 L 645 279.5" fill="none" stroke="#9673a6" stroke-miterlimit="4" pointer-events="none"/>
+    <path d="M 35 279.5 L 24.5 279.5 L 40 260.5 L 55.5 279.5 L 45 279.5 L 45 390.5 L 55.5 390.5 L 40 409.5 L 24.5 390.5 L 35 390.5 Z" fill="#ffe6cc" stroke="#d79b00" stroke-miterlimit="10" pointer-events="none"/>
+    <path d="M 135 279.5 L 124.5 279.5 L 140 260.5 L 155.5 279.5 L 145 279.5 L 145 390.5 L 155.5 390.5 L 140 409.5 L 124.5 390.5 L 135 390.5 Z" fill="#ffe6cc" stroke="#d79b00" stroke-miterlimit="10" pointer-events="none"/>
+  </g>
+</svg>

diff --git a/docs/glossary.rst b/docs/glossary.rst
new file mode 100644 (file)
index 0000000..b5ea88b
--- /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 470541f007cc8ecf7823fbe398186a5136cdd1b2..8d402e20a97cd9c3d2c5f65cf4d2d20755e750d1 100644 (file)
--- 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