|
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [Xen-devel] [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 <andrew.cooper3@xxxxxxxxxx> --- CC: George Dunlap <George.Dunlap@xxxxxxxxxxxxx> CC: Ian Jackson <ian.jackson@xxxxxxxxxx> CC: Jan Beulich <JBeulich@xxxxxxxx> CC: Stefano Stabellini <sstabellini@xxxxxxxxxx> CC: Wei Liu <wl@xxxxxxx> CC: Julien Grall <julien.grall@xxxxxxx> CC: Roger Pau Monné <roger.pau@xxxxxxxxxx> CC: Lars Kurth <lars.kurth@xxxxxxxxxx> 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="<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..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. + + A guest is a single virtual machine. + + Consider the case of live migration where, for a period of time, one + guest will be comprised of two domains, 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 + See :term:`domain` + + hardware domain + A :term:`domain`, commonly dom0, which shares reponsibility 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..675da617be 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, 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.11.0 _______________________________________________ Xen-devel mailing list Xen-devel@xxxxxxxxxxxxxxxxxxxx https://lists.xenproject.org/mailman/listinfo/xen-devel
|
 |
Lists.xenproject.org is hosted with RackSpace, monitoring our |