diff mbox series

[3/4] docs/sphinx: Introduction

Message ID 20191003205948.21131-1-andrew.cooper3@citrix.com (mailing list archive)
State New, archived
Headers show
Series docs/sphinx | expand

Commit Message

Andrew Cooper Oct. 3, 2019, 8:59 p.m. UTC 
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>
---
CC: Lars Kurth <lars.kurth@citrix.com>
CC: George Dunlap <George.Dunlap@eu.citrix.com>
CC: Ian Jackson <ian.jackson@citrix.com>
CC: Jan Beulich <JBeulich@suse.com>
CC: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
CC: Stefano Stabellini <sstabellini@kernel.org>
CC: Tim Deegan <tim@xen.org>
CC: Wei Liu <wl@xen.org>
CC: Julien Grall <julien@xen.org>
CC: Roger Pau Monné <roger.pau@citrix.com>
CC: Juergen Gross <jgross@suse.com>
---
 docs/admin-guide/index.rst               |  1 +
 docs/admin-guide/introduction.rst        | 40 +++++++++++++
 docs/admin-guide/xen-overview.drawio.svg | 97 ++++++++++++++++++++++++++++++++
 docs/glossary.rst                        | 52 +++++++++++++++++
 docs/index.rst                           | 12 ++++
 5 files changed, 202 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

Comments

Lars Kurth Oct. 8, 2019, 12:34 p.m. UTC | #1 
On 03/10/2019, 21:59, "Andrew Cooper" <andrew.cooper3@citrix.com> wrote:

    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>

There were a few minor improvements which could be made, I am listing these
below, but none are show-stoppers.

    +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
Maybe better: s/software/software on the system/ or s/software/software on the host/
    +machines.

    +   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

This is a little unclear: in particular the 1st paragraph. Earlier you talk about hardware
domain="responsible for hardware and marshalling guest I/O", which is clearer. 

Maybe: 

A :term:`domain`, commonly dom0, which hosts all devices, including disks
and network cards and is responsible for multiplexing guest I/O

is better

Regards
Lars
Andrew Cooper Oct. 19, 2019, 2:19 a.m. UTC | #2 
On 08/10/2019 13:34, Lars Kurth wrote:
>
> On 03/10/2019, 21:59, "Andrew Cooper" <andrew.cooper3@citrix.com> wrote:
>
>     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>

Thanks.

>
> There were a few minor improvements which could be made, I am listing these
> below, but none are show-stoppers.
>
>     +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
> Maybe better: s/software/software on the system/ or s/software/software on the host/

Fixed.

>     +machines.
>
>     +   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
>
> This is a little unclear: in particular the 1st paragraph. Earlier you talk about hardware
> domain="responsible for hardware and marshalling guest I/O", which is clearer. 
>
> Maybe: 
>
> A :term:`domain`, commonly dom0, which hosts all devices, including disks
> and network cards and is responsible for multiplexing guest I/O
>
> is better

Sadly, its not accurate.

Multiplexing of I/O is only in the case that device driver domains
aren't in use.  The other example you cite is a description of the
associated image.

There are things besides I/O which the hardware domain is responsible
for, such as APCI OPSM (but only in x86), and system reboot etc.

I have left the description as-is, for lack of an obviously better way
of expressing things.

~Andrew
diff mbox series

Patch

diff --git a/docs/admin-guide/index.rst b/docs/admin-guide/index.rst
index 1da7c8bf4d..54e6f65de3 100644
--- a/docs/admin-guide/index.rst
+++ b/docs/admin-guide/index.rst
@@ -4,4 +4,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..6da2758d70
--- /dev/null
+++ b/docs/admin-guide/introduction.rst
@@ -0,0 +1,40 @@ 
+.. SPDX-License-Identifier: CC-BY-4.0
+
+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
index 0000000000..f120cdf77a
--- /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
index 0000000000..8ddbdab160
--- /dev/null
+++ b/docs/glossary.rst
@@ -0,0 +1,52 @@ 
+.. SPDX-License-Identifier: CC-BY-4.0
+
+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 7b441c4180..b8ab13178c 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -8,6 +8,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, and shares the resources of the hardware between virtual
+machines.  See :doc:`admin-guide/introduction` for an introduction to a Xen
+system.
 
 User documentation
 ------------------
@@ -47,3 +51,11 @@  kind of development environment.
    :maxdepth: 2
 
    hypervisor-guide/index
+
+
+Miscellanea
+-----------
+
+.. toctree::
+
+   glossary