Re: [Xen-devel] [PATCH] docs/sphinx: Introduction

[George Dunlap <george.dunlap@citrix.com>]

On 8/7/19 8:41 PM, Andrew Cooper 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>
> ---
> CC: George Dunlap <George.Dunlap@eu.citrix.com>
> CC: Ian Jackson <ian.jackson@citrix.com>
> CC: Jan Beulich <JBeulich@suse.com>
> CC: Stefano Stabellini <sstabellini@kernel.org>
> CC: Wei Liu <wl@xen.org>
> CC: Julien Grall <julien.grall@arm.com>
> CC: Roger Pau Monné <roger.pau@citrix.com>
> CC: Lars Kurth <lars.kurth@citrix.com>
> 
> A rendered version is visible here:
> 
>   https://andrewcoop-xen.readthedocs.io/en/docs-devel/admin-guide/introduction.html
> 
> The image is created with https://www.draw.io/ and has the embedded source.
> This means that anyone can open the SVG in Draw.IO, either online or with the
> desktop editor, and modify the image in its original form.  The only
> modification I've made to the SVG as written is to xmllint it.
> 
> RFC to get some feedback on level of technical detail (specifically, it must
> not assume any Xen knowledge at all, but also shouldn't be an overload of
> information), as well as views on the drawing itself.
> ---
>  docs/admin-guide/index.rst               |  1 +
>  docs/admin-guide/introduction.rst        | 38 +++++++++++++
>  docs/admin-guide/xen-overview.drawio.svg | 97 ++++++++++++++++++++++++++++++++
>  docs/glossary.rst                        | 37 ++++++++++++
>  docs/index.rst                           | 12 ++++
>  5 files changed, 185 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<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..a1a3e2f28d
> --- /dev/null
> +++ b/docs/glossary.rst
> @@ -0,0 +1,37 @@
> +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.

What about something like this?

---
Consider the terms "process" and "application".  On Linux systems,
systemd is a process, but it's not an application: You didn't install
Linux on your desktop so that you could run systemd; you installed it so
that you could run Firefox or whatever.

Similarly, on Xen systems, domains can be divided into "guest domains"
and "service domains".  You installed Xen because you wanted to run VMs;
these are guest domains.  Service domains are domains started by the
host in order to enable running guest domains.

Furthermore, "guest" really means a single virtual machine.  Normally a
single virtual machine is implemented by a single domain; but this may
not be the case during, for instance, live migration, where a guest is
comprised of two domains (one running on the sending host, and one being
constructed on the receiving host).

---

We could consider reordering those paragraphs or dropping the process /
application para if you want.

That said, we do normally say "guest user mode" and "guest kernel mode"
for all domains; but that's because "domain user mode" is a bit clunky.

 -George
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel