Xen project Mailing List

[Xen-devel] [PATCH 3/4] docs/sphinx: Introduction

To: Xen-devel <xen-devel@xxxxxxxxxxxxxxxxxxxx>

From: Andrew Cooper <andrew.cooper3@xxxxxxxxxx>

Date: Thu, 3 Oct 2019 21:59:48 +0100

Authentication-results: esa2.hc3370-68.iphmx.com; dkim=none (message not signed) header.i=none; spf=None smtp.pra=andrew.cooper3@xxxxxxxxxx; spf=Pass smtp.mailfrom=Andrew.Cooper3@xxxxxxxxxx; spf=None smtp.helo=postmaster@xxxxxxxxxxxxxxx

Cc: Juergen Gross <jgross@xxxxxxxx>, Lars Kurth <lars.kurth@xxxxxxxxxx>, Stefano Stabellini <sstabellini@xxxxxxxxxx>, Julien Grall <julien@xxxxxxx>, Wei Liu <wl@xxxxxxx>, Konrad Rzeszutek Wilk <konrad.wilk@xxxxxxxxxx>, George Dunlap <George.Dunlap@xxxxxxxxxxxxx>, Andrew Cooper <andrew.cooper3@xxxxxxxxxx>, Tim Deegan <tim@xxxxxxx>, Jan Beulich <JBeulich@xxxxxxxx>, Ian Jackson <ian.jackson@xxxxxxxxxx>, Roger Pau Monné <roger.pau@xxxxxxxxxx>

Delivery-date: Thu, 03 Oct 2019 20:59:57 +0000

Ironport-sdr: wT10kGGtaRyJ7O5zTM1Qs2c0Jp7spWTRzT5YAW/iUGV2CcwutQMwbmGJco+XApVfCgBYcZ1gCz +GZ7cNnN+R5UWGZ09eBE6DZvqScoFmQ7DTAPS/C0B0PoUt9p3xDNI2rCfPlQ8cAXjlKeL6RkwJ xXpiw6BlWJfVgx2VlH8BZxNUswcl4mfxwDnTr+BjLimLZInXtjeEP7Rh45kgAVYXg1VfYF2dL0 H6tfrrPyb7SVA488pfU4QERXkYRyEroyj1+WgUKfAxnrtgOnPiyiVJwc7V6rxKtM3U9gjehAfa AZ8=

List-id: Xen developer discussion <xen-devel.lists.xenproject.org>

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@xxxxxxxxxx> --- CC: Lars Kurth <lars.kurth@xxxxxxxxxx> CC: George Dunlap <George.Dunlap@xxxxxxxxxxxxx> CC: Ian Jackson <ian.jackson@xxxxxxxxxx> CC: Jan Beulich <JBeulich@xxxxxxxx> CC: Konrad Rzeszutek Wilk <konrad.wilk@xxxxxxxxxx> CC: Stefano Stabellini <sstabellini@xxxxxxxxxx> CC: Tim Deegan <tim@xxxxxxx> CC: Wei Liu <wl@xxxxxxx> CC: Julien Grall <julien@xxxxxxx> CC: Roger Pau Monné <roger.pau@xxxxxxxxxx> CC: Juergen Gross <jgross@xxxxxxxx> --- 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 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="<mxfile modified="2019-08-04T17:05:55.267Z" host="" agent="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" etag="M7ISh4Ny83I7m1UfK1F2" version="11.1.1" type="device"><diagram id="7q-U8ZVDCMAbtjTOF8Vq" name="Page-1">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=</diagram></mxfile>"> + <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 -- 2.11.0 _______________________________________________ Xen-devel mailing list Xen-devel@xxxxxxxxxxxxxxxxxxxx https://lists.xenproject.org/mailman/listinfo/xen-devel

©2013 Xen Project, A Linux Foundation Collaborative Project. All Rights Reserved.
Linux Foundation is a registered trademark of The Linux Foundation.
Xen Project is a trademark of The Linux Foundation.