* [Xen-devel] [PATCH] docs/sphinx: Introduction
@ 2019-08-07 19:41 Andrew Cooper
2019-08-07 22:49 ` Hans van Kranenburg
` (2 more replies)
0 siblings, 3 replies; 18+ messages in thread
From: Andrew Cooper @ 2019-08-07 19:41 UTC (permalink / raw)
To: Xen-devel
Cc: Lars Kurth, Stefano Stabellini, Wei Liu, George Dunlap,
Andrew Cooper, Julien Grall, Jan Beulich, Ian Jackson,
Roger Pau Monné
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="<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@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel
^ permalink raw reply related [flat|nested] 18+ messages in thread
* Re: [Xen-devel] [PATCH] docs/sphinx: Introduction
2019-08-07 19:41 [Xen-devel] [PATCH] docs/sphinx: Introduction Andrew Cooper
@ 2019-08-07 22:49 ` Hans van Kranenburg
2019-08-07 23:25 ` Andrew Cooper
2019-08-08 6:22 ` Jan Beulich
2019-08-12 15:36 ` [Xen-devel] " George Dunlap
2 siblings, 1 reply; 18+ messages in thread
From: Hans van Kranenburg @ 2019-08-07 22:49 UTC (permalink / raw)
To: Andrew Cooper, Xen-devel; +Cc: Lars Kurth
Hi, (dropped most of the Cc:)
On 8/7/19 9:41 PM, Andrew Cooper wrote:
> Put together an introduction page for the Sphinx/RST docs, along with a
> glossary which will accumulate over time.
> [...]
I've been using Xen for 13+ years now, so I'm not really able to provide
feedback about how someone new to it would experience things.
But, I think there's some feedback I can provide.
The first page, admin-guide/introduction is very well written, it's
short and it sets a very good frame of reference. Keep it like this.
When writing documentation, you're not only providing information. You
can "steer" a lot of things. By consciously deciding about the exact
technical level of stuff that you provide on the "front page", you'll
automatically cause a selection of audience that you want to stay or
want to browse/scare away because it's not for them.
And, I think this first introduction page exactly does that, but I this
is where I'm of course biased. I think it will "work" for a new user who
already knows what a NIC and a Kernel is, and it will work for an
interested developer, looking to help figuring out to get it running on
$whatever hardware not fully supported.
The other pages already available seem to be developer documentation
instead of user documentation.
One of the things on my wishlist is to help cleaning up the end user
documentation for Xen. Xen itself has a wiki with a lot of horrible
outdated information, there's a Debian wiki with even more horrible
outated information, and so on. As a new user, you completely get lost
because you have no idea what's still relevant or not. It's a shame that
we lose potential new users for which the product would be a good fit
because of that.
(With a group of motivated people, a few with technical knowledge and a
few with decent tech. writer skills we could do a "sprint" getting some
big hammers and chainsaws out to do some huge spring cleaning and
restructure it.) A wiki is a great solution for short-term low-barrier
gathering of information by anyone, but in the long term it's just a big
accumulation of cruft without a clear maintainer.
Instead of fully starting to hijack this thread now, my last feedback
would be: in your git commit message, you don't mention what your target
audience is. I'm interested to hear what it is.
Thanks,
Hans
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [Xen-devel] [PATCH] docs/sphinx: Introduction
2019-08-07 22:49 ` Hans van Kranenburg
@ 2019-08-07 23:25 ` Andrew Cooper
0 siblings, 0 replies; 18+ messages in thread
From: Andrew Cooper @ 2019-08-07 23:25 UTC (permalink / raw)
To: Hans van Kranenburg, Xen-devel; +Cc: Lars Kurth
On 07/08/2019 23:49, Hans van Kranenburg wrote:
> Hi, (dropped most of the Cc:)
>
> On 8/7/19 9:41 PM, Andrew Cooper wrote:
>> Put together an introduction page for the Sphinx/RST docs, along with a
>> glossary which will accumulate over time.
>> [...]
> I've been using Xen for 13+ years now, so I'm not really able to provide
> feedback about how someone new to it would experience things.
>
> But, I think there's some feedback I can provide.
>
> The first page, admin-guide/introduction is very well written, it's
> short and it sets a very good frame of reference. Keep it like this.
I think there are a few other things it should cover. A very brief
history of Xen's major milestones, but I was planning to keep that to a
paragraph of two. (When Xen started, PV guests being modified to know
about Xen, HVM guests with hardware virt so we could run windows, then
expanding into ARM + hardware virt).
> When writing documentation, you're not only providing information. You
> can "steer" a lot of things. By consciously deciding about the exact
> technical level of stuff that you provide on the "front page", you'll
> automatically cause a selection of audience that you want to stay or
> want to browse/scare away because it's not for them.
>
> And, I think this first introduction page exactly does that, but I this
> is where I'm of course biased.
"does exactly that" => you mean scare people away? :)
Yes - getting the right level of detail here is critical, and is going
to need outside feedback.
> I think it will "work" for a new user who
> already knows what a NIC and a Kernel is, and it will work for an
> interested developer, looking to help figuring out to get it running on
> $whatever hardware not fully supported.
>
> The other pages already available seem to be developer documentation
> instead of user documentation.
It is a random mix of small tasks which I've managed to get done in my
distinctly negative free time.
The focus is first and foremost on high-quality documentation, and I am
fully expecting to have to shuffle the exact structure and layout as it
gains more content and it is easier to spot where the logical divisions lie.
For now, the paragraphs on the front page are my best guestimate of how
to structure it, but they are by no means set in stone.
> One of the things on my wishlist is to help cleaning up the end user
> documentation for Xen. Xen itself has a wiki with a lot of horrible
> outdated information, there's a Debian wiki with even more horrible
> outated information, and so on. As a new user, you completely get lost
> because you have no idea what's still relevant or not. It's a shame that
> we lose potential new users for which the product would be a good fit
> because of that.
>
> (With a group of motivated people, a few with technical knowledge and a
> few with decent tech. writer skills we could do a "sprint" getting some
> big hammers and chainsaws out to do some huge spring cleaning and
> restructure it.) A wiki is a great solution for short-term low-barrier
> gathering of information by anyone, but in the long term it's just a big
> accumulation of cruft without a clear maintainer.
>
> Instead of fully starting to hijack this thread now, my last feedback
> would be: in your git commit message, you don't mention what your target
> audience is. I'm interested to hear what it is.
This page is aimed at people who have no knowledge of Xen. I don't
expect people who routinely work on Xen to read it more than once.
However, I also don't think that here is an appropriate place to cover
"my first introduction to a computer". If we were to aim at that level,
noone would read it - its too high level for anyone who knows what a
kernel is, and Xen is far too niche for anyone who doesn't know what a
kernel is to find.
Again, I would welcome feedback here on exactly what level we should aim
"my first introduction to Xen" at.
As for the longterm goal of the docs, I do stand by my initial guestimate.
1) The admin guide for people who aren't programmers but want to run a
Xen system.
2) The guest guide for people wanting to develop against our ABI/APIs.
3) The developer guide for people hacking on the content of xen.git
2 and 3 have a fair overlap, but I think it is important to keep them
distinct. 2 will include things like hypercall and library API/ABI
references, whereas 3 is the only place I'd expect to see information on
how Xen does memory management, or breakdowns of how the boot paths
work, etc.
As I said - everything is subject to improvement as the content grows.
I care far more that we end up with high quality, coherent
documentation, than it ending up looking exactly as I predicted at some
point in the past.
~Andrew
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [Xen-devel] [PATCH] docs/sphinx: Introduction
2019-08-07 19:41 [Xen-devel] [PATCH] docs/sphinx: Introduction Andrew Cooper
2019-08-07 22:49 ` Hans van Kranenburg
@ 2019-08-08 6:22 ` Jan Beulich
2019-08-08 8:43 ` [Xen-devel] Terminology for "guest" - Was: " Andrew Cooper
2019-08-12 15:36 ` [Xen-devel] " George Dunlap
2 siblings, 1 reply; 18+ messages in thread
From: Jan Beulich @ 2019-08-08 6:22 UTC (permalink / raw)
To: Andrew Cooper
Cc: Lars Kurth, Stefano Stabellini, Wei Liu, George Dunlap,
Julien Grall, Ian Jackson, Xen-devel, Roger Pau Monné
On 07.08.2019 21:41, Andrew Cooper wrote:
> --- /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`
I think you want to mention the usual distinction here: Dom0 is,
while a domain, commonly not considered a guest.
Everything else looks okay to me, but I can't reasonably address your
RFC aspect.
Jan
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [Xen-devel] Terminology for "guest" - Was: [PATCH] docs/sphinx: Introduction
2019-08-08 6:22 ` Jan Beulich
@ 2019-08-08 8:43 ` Andrew Cooper
2019-08-08 9:04 ` Jan Beulich
2019-08-08 9:49 ` Roger Pau Monné
0 siblings, 2 replies; 18+ messages in thread
From: Andrew Cooper @ 2019-08-08 8:43 UTC (permalink / raw)
To: Jan Beulich
Cc: Lars Kurth, Stefano Stabellini, Wei Liu, George Dunlap,
Julien Grall, Ian Jackson, Xen-devel, Roger Pau Monné
On 08/08/2019 07:22, Jan Beulich wrote:
> On 07.08.2019 21:41, Andrew Cooper wrote:
>> --- /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`
>
> I think you want to mention the usual distinction here: Dom0 is,
> while a domain, commonly not considered a guest.
To be honest, I had totally forgotten about that. I guess now is the
proper time to rehash it in public.
I don't think the way it currently gets used has a clear or coherent set
of rules, because I can't think of any to describe how it does get used.
Either there are a clear and coherent (and simple!) set of rules for
what we mean by "guest", at which point they can live here in the
glossary, or the fuzzy way it is current used should cease.
~Andrew
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [Xen-devel] Terminology for "guest" - Was: [PATCH] docs/sphinx: Introduction
2019-08-08 8:43 ` [Xen-devel] Terminology for "guest" - Was: " Andrew Cooper
@ 2019-08-08 9:04 ` Jan Beulich
2019-08-08 9:13 ` Julien Grall
2019-08-08 9:49 ` Roger Pau Monné
1 sibling, 1 reply; 18+ messages in thread
From: Jan Beulich @ 2019-08-08 9:04 UTC (permalink / raw)
To: Andrew Cooper
Cc: Lars Kurth, StefanoStabellini, Wei Liu, George Dunlap,
Julien Grall, Xen-devel, Ian Jackson, Roger Pau Monné
On 08.08.2019 10:43, Andrew Cooper wrote:
> On 08/08/2019 07:22, Jan Beulich wrote:
>> On 07.08.2019 21:41, Andrew Cooper wrote:
>>> --- /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`
>>
>> I think you want to mention the usual distinction here: Dom0 is,
>> while a domain, commonly not considered a guest.
>
> To be honest, I had totally forgotten about that. I guess now is the
> proper time to rehash it in public.
>
> I don't think the way it currently gets used has a clear or coherent set
> of rules, because I can't think of any to describe how it does get used.
>
> Either there are a clear and coherent (and simple!) set of rules for
> what we mean by "guest", at which point they can live here in the
> glossary, or the fuzzy way it is current used should cease.
What's fuzzy about Dom0 not being a guest (due to being a part of the
host instead)?
Jan
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [Xen-devel] Terminology for "guest" - Was: [PATCH] docs/sphinx: Introduction
2019-08-08 9:04 ` Jan Beulich
@ 2019-08-08 9:13 ` Julien Grall
2019-08-08 10:30 ` Andrew Cooper
` (2 more replies)
0 siblings, 3 replies; 18+ messages in thread
From: Julien Grall @ 2019-08-08 9:13 UTC (permalink / raw)
To: Jan Beulich, Andrew Cooper
Cc: Lars Kurth, StefanoStabellini, Wei Liu, George Dunlap, Xen-devel,
Ian Jackson, Roger Pau Monné
Hi Jan,
On 08/08/2019 10:04, Jan Beulich wrote:
> On 08.08.2019 10:43, Andrew Cooper wrote:
>> On 08/08/2019 07:22, Jan Beulich wrote:
>>> On 07.08.2019 21:41, Andrew Cooper wrote:
>>>> --- /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`
>>>
>>> I think you want to mention the usual distinction here: Dom0 is,
>>> while a domain, commonly not considered a guest.
>>
>> To be honest, I had totally forgotten about that. I guess now is the
>> proper time to rehash it in public.
>>
>> I don't think the way it currently gets used has a clear or coherent set
>> of rules, because I can't think of any to describe how it does get used.
>>
>> Either there are a clear and coherent (and simple!) set of rules for
>> what we mean by "guest", at which point they can live here in the
>> glossary, or the fuzzy way it is current used should cease.
>
> What's fuzzy about Dom0 not being a guest (due to being a part of the
> host instead)?
Dom0 is not part of the host if you are using an hardware domain. I actually
thought we renamed everything in Xen from Dom0 to hwdom to avoid the confusion.
I also would rather avoid to treat "dom0" as not a guest. In normal setup this
is a more privilege guest, in other setup this may just be a normal guest (think
about partitioning).
Cheers,
--
Julien Grall
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [Xen-devel] Terminology for "guest" - Was: [PATCH] docs/sphinx: Introduction
2019-08-08 8:43 ` [Xen-devel] Terminology for "guest" - Was: " Andrew Cooper
2019-08-08 9:04 ` Jan Beulich
@ 2019-08-08 9:49 ` Roger Pau Monné
1 sibling, 0 replies; 18+ messages in thread
From: Roger Pau Monné @ 2019-08-08 9:49 UTC (permalink / raw)
To: Andrew Cooper
Cc: Lars Kurth, Stefano Stabellini, Wei Liu, George Dunlap,
Julien Grall, Jan Beulich, Ian Jackson, Xen-devel
On Thu, Aug 08, 2019 at 09:43:01AM +0100, Andrew Cooper wrote:
> On 08/08/2019 07:22, Jan Beulich wrote:
> > On 07.08.2019 21:41, Andrew Cooper wrote:
> >> --- /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`
> >
> > I think you want to mention the usual distinction here: Dom0 is,
> > while a domain, commonly not considered a guest.
>
> To be honest, I had totally forgotten about that. I guess now is the
> proper time to rehash it in public.
>
> I don't think the way it currently gets used has a clear or coherent set
> of rules, because I can't think of any to describe how it does get used.
>
> Either there are a clear and coherent (and simple!) set of rules for
> what we mean by "guest", at which point they can live here in the
> glossary, or the fuzzy way it is current used should cease.
I've always referred to dom0 as a privileged guest, but a guest
after all. I think this is one of the differences of Xen vs KVM or
other hosted hypervisors.
Roger.
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [Xen-devel] Terminology for "guest" - Was: [PATCH] docs/sphinx: Introduction
2019-08-08 9:13 ` Julien Grall
@ 2019-08-08 10:30 ` Andrew Cooper
2019-08-08 10:49 ` Jan Beulich
2019-08-12 14:53 ` George Dunlap
2 siblings, 0 replies; 18+ messages in thread
From: Andrew Cooper @ 2019-08-08 10:30 UTC (permalink / raw)
To: Julien Grall, Jan Beulich
Cc: Lars Kurth, StefanoStabellini, Wei Liu, George Dunlap, Xen-devel,
Ian Jackson, Roger Pau Monné
On 08/08/2019 10:13, Julien Grall wrote:
> Hi Jan,
>
> On 08/08/2019 10:04, Jan Beulich wrote:
>> On 08.08.2019 10:43, Andrew Cooper wrote:
>>> On 08/08/2019 07:22, Jan Beulich wrote:
>>>> On 07.08.2019 21:41, Andrew Cooper wrote:
>>>>> --- /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`
>>>>
>>>> I think you want to mention the usual distinction here: Dom0 is,
>>>> while a domain, commonly not considered a guest.
>>>
>>> To be honest, I had totally forgotten about that. I guess now is the
>>> proper time to rehash it in public.
>>>
>>> I don't think the way it currently gets used has a clear or coherent
>>> set
>>> of rules, because I can't think of any to describe how it does get
>>> used.
>>>
>>> Either there are a clear and coherent (and simple!) set of rules for
>>> what we mean by "guest", at which point they can live here in the
>>> glossary, or the fuzzy way it is current used should cease.
>>
>> What's fuzzy about Dom0 not being a guest (due to being a part of the
>> host instead)?
> Dom0 is not part of the host if you are using an hardware domain.
Quite. Even if you are using a hardware domain, dom0 is the control
domain. Is this part of the host or not?
What about device driver domains?
To answer Jan's question, what is "fuzzy" is the fact that there is not
a clear definition.
> I actually thought we renamed everything in Xen from Dom0 to hwdom to
> avoid the
>
> I also would rather avoid to treat "dom0" as not a guest. In normal
> setup this is a more privilege guest, in other setup this may just be
> a normal guest (think about partitioning).
People thinking that dom0 isn't a VM is a massive problem for
understanding Xen's architecture, which is why I phrased some of
introduction the way I did.
It is a mistake which we need to take steps to address in our literature.
~Andrew
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [Xen-devel] Terminology for "guest" - Was: [PATCH] docs/sphinx: Introduction
2019-08-08 9:13 ` Julien Grall
2019-08-08 10:30 ` Andrew Cooper
@ 2019-08-08 10:49 ` Jan Beulich
2019-08-08 11:22 ` Rich Persaud
2019-08-12 14:53 ` George Dunlap
2 siblings, 1 reply; 18+ messages in thread
From: Jan Beulich @ 2019-08-08 10:49 UTC (permalink / raw)
To: Julien Grall
Cc: Lars Kurth, StefanoStabellini, Wei Liu, George Dunlap,
Andrew Cooper, Xen-devel, Ian Jackson, Roger Pau Monné
On 08.08.2019 11:13, Julien Grall wrote:
> Hi Jan,
>
> On 08/08/2019 10:04, Jan Beulich wrote:
>> On 08.08.2019 10:43, Andrew Cooper wrote:
>>> On 08/08/2019 07:22, Jan Beulich wrote:
>>>> On 07.08.2019 21:41, Andrew Cooper wrote:
>>>>> --- /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`
>>>>
>>>> I think you want to mention the usual distinction here: Dom0 is,
>>>> while a domain, commonly not considered a guest.
>>>
>>> To be honest, I had totally forgotten about that. I guess now is the
>>> proper time to rehash it in public.
>>>
>>> I don't think the way it currently gets used has a clear or coherent set
>>> of rules, because I can't think of any to describe how it does get used.
>>>
>>> Either there are a clear and coherent (and simple!) set of rules for
>>> what we mean by "guest", at which point they can live here in the
>>> glossary, or the fuzzy way it is current used should cease.
>>
>> What's fuzzy about Dom0 not being a guest (due to being a part of the
>> host instead)?
> Dom0 is not part of the host if you are using an hardware domain.
It's still the control domain then, and hence still part of the host.
> I actually thought we renamed everything in Xen from Dom0 to hwdom
> to avoid the confusion.
As to variable naming - mostly, I think.
Jan
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [Xen-devel] Terminology for "guest" - Was: [PATCH] docs/sphinx: Introduction
2019-08-08 10:49 ` Jan Beulich
@ 2019-08-08 11:22 ` Rich Persaud
0 siblings, 0 replies; 18+ messages in thread
From: Rich Persaud @ 2019-08-08 11:22 UTC (permalink / raw)
To: Jan Beulich
Cc: Lars Kurth, StefanoStabellini, Wei Liu, George Dunlap,
Andrew Cooper, Christopher Clark, Daniel Smith, Julien Grall,
Ian Jackson, Xen-devel, Roger Pau Monné
[-- Attachment #1.1: Type: text/plain, Size: 2839 bytes --]
On Aug 8, 2019, at 06:49, Jan Beulich <JBeulich@suse.com> wrote:
>
>> On 08.08.2019 11:13, Julien Grall wrote:
>> Hi Jan,
>>
>>> On 08/08/2019 10:04, Jan Beulich wrote:
>>>> On 08.08.2019 10:43, Andrew Cooper wrote:
>>>>> On 08/08/2019 07:22, Jan Beulich wrote:
>>>>>> On 07.08.2019 21:41, Andrew Cooper wrote:
>>>>>> --- /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`
>>>>>
>>>>> I think you want to mention the usual distinction here: Dom0 is,
>>>>> while a domain, commonly not considered a guest.
>>>>
>>>> To be honest, I had totally forgotten about that. I guess now is the
>>>> proper time to rehash it in public.
>>>>
>>>> I don't think the way it currently gets used has a clear or coherent set
>>>> of rules, because I can't think of any to describe how it does get used.
>>>>
>>>> Either there are a clear and coherent (and simple!) set of rules for
>>>> what we mean by "guest", at which point they can live here in the
>>>> glossary, or the fuzzy way it is current used should cease.
>>>
>>> What's fuzzy about Dom0 not being a guest (due to being a part of the
>>> host instead)?
>> Dom0 is not part of the host if you are using an hardware domain.
>
> It's still the control domain then, and hence still part of the host.
With disaggregation and dom0less (how might we describe that term in the intro?) for edge/embedded Xen systems, there could be a mode where the control domain has never had privilege over the domain that handles the physical TPM, or the provider of the virtual TPM:
https://lists.gt.net/xen/devel/557782
Rich
[-- Attachment #1.2: Type: text/html, Size: 13680 bytes --]
[-- Attachment #2: Type: text/plain, Size: 157 bytes --]
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [Xen-devel] Terminology for "guest" - Was: [PATCH] docs/sphinx: Introduction
2019-08-08 9:13 ` Julien Grall
2019-08-08 10:30 ` Andrew Cooper
2019-08-08 10:49 ` Jan Beulich
@ 2019-08-12 14:53 ` George Dunlap
2019-08-12 15:01 ` Andrew Cooper
2 siblings, 1 reply; 18+ messages in thread
From: George Dunlap @ 2019-08-12 14:53 UTC (permalink / raw)
To: Julien Grall, Jan Beulich, Andrew Cooper
Cc: Lars Kurth, StefanoStabellini, Wei Liu, George Dunlap, Xen-devel,
Ian Jackson, Roger Pau Monné
On 8/8/19 10:13 AM, Julien Grall wrote:
> Hi Jan,
>
> On 08/08/2019 10:04, Jan Beulich wrote:
>> On 08.08.2019 10:43, Andrew Cooper wrote:
>>> On 08/08/2019 07:22, Jan Beulich wrote:
>>>> On 07.08.2019 21:41, Andrew Cooper wrote:
>>>>> --- /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`
>>>>
>>>> I think you want to mention the usual distinction here: Dom0 is,
>>>> while a domain, commonly not considered a guest.
>>>
>>> To be honest, I had totally forgotten about that. I guess now is the
>>> proper time to rehash it in public.
>>>
>>> I don't think the way it currently gets used has a clear or coherent set
>>> of rules, because I can't think of any to describe how it does get used.
>>>
>>> Either there are a clear and coherent (and simple!) set of rules for
>>> what we mean by "guest", at which point they can live here in the
>>> glossary, or the fuzzy way it is current used should cease.
>>
>> What's fuzzy about Dom0 not being a guest (due to being a part of the
>> host instead)?
> Dom0 is not part of the host if you are using an hardware domain. I
> actually thought we renamed everything in Xen from Dom0 to hwdom to
> avoid the confusion.
>
> I also would rather avoid to treat "dom0" as not a guest. In normal
> setup this is a more privilege guest, in other setup this may just be a
> normal guest (think about partitioning).
A literal guest is someone who doesn't live in the building (or work in
the buliding, if you're in a hotel). The fact that the staff cleaning
rooms are restricted in their privileges doesn't make them guests of the
hotel.
The toolstack domain, the hardware domain, the driver domain, the
xenstore domain, and so on are all part of the host system, designed to
allow you to use Xen to do the thing you actually want to do: Run guests.
And it's important that we have a word that distinguishes "domains that
we only care about because they make it possible to run other domains",
and "domains that we actually want to run". "guest / host" is a natural
terminology for these.
We already have the word "domain", which includes dom0, driver domains,
toolstack domains, hardware domains, as well as guest domains. We don't
need "guest" to be a synonym for "domain".
-George
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [Xen-devel] Terminology for "guest" - Was: [PATCH] docs/sphinx: Introduction
2019-08-12 14:53 ` George Dunlap
@ 2019-08-12 15:01 ` Andrew Cooper
2019-08-13 2:59 ` Sarah Newman
0 siblings, 1 reply; 18+ messages in thread
From: Andrew Cooper @ 2019-08-12 15:01 UTC (permalink / raw)
To: George Dunlap, Julien Grall, Jan Beulich
Cc: Lars Kurth, StefanoStabellini, Wei Liu, George Dunlap, Xen-devel,
Ian Jackson, Roger Pau Monné
On 12/08/2019 15:53, George Dunlap wrote:
> On 8/8/19 10:13 AM, Julien Grall wrote:
>> Hi Jan,
>>
>> On 08/08/2019 10:04, Jan Beulich wrote:
>>> On 08.08.2019 10:43, Andrew Cooper wrote:
>>>> On 08/08/2019 07:22, Jan Beulich wrote:
>>>>> On 07.08.2019 21:41, Andrew Cooper wrote:
>>>>>> --- /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`
>>>>> I think you want to mention the usual distinction here: Dom0 is,
>>>>> while a domain, commonly not considered a guest.
>>>> To be honest, I had totally forgotten about that. I guess now is the
>>>> proper time to rehash it in public.
>>>>
>>>> I don't think the way it currently gets used has a clear or coherent set
>>>> of rules, because I can't think of any to describe how it does get used.
>>>>
>>>> Either there are a clear and coherent (and simple!) set of rules for
>>>> what we mean by "guest", at which point they can live here in the
>>>> glossary, or the fuzzy way it is current used should cease.
>>> What's fuzzy about Dom0 not being a guest (due to being a part of the
>>> host instead)?
>> Dom0 is not part of the host if you are using an hardware domain. I
>> actually thought we renamed everything in Xen from Dom0 to hwdom to
>> avoid the confusion.
>>
>> I also would rather avoid to treat "dom0" as not a guest. In normal
>> setup this is a more privilege guest, in other setup this may just be a
>> normal guest (think about partitioning).
> A literal guest is someone who doesn't live in the building (or work in
> the buliding, if you're in a hotel). The fact that the staff cleaning
> rooms are restricted in their privileges doesn't make them guests of the
> hotel.
>
> The toolstack domain, the hardware domain, the driver domain, the
> xenstore domain, and so on are all part of the host system, designed to
> allow you to use Xen to do the thing you actually want to do: Run guests.
>
> And it's important that we have a word that distinguishes "domains that
> we only care about because they make it possible to run other domains",
> and "domains that we actually want to run". "guest / host" is a natural
> terminology for these.
>
> We already have the word "domain", which includes dom0, driver domains,
> toolstack domains, hardware domains, as well as guest domains. We don't
> need "guest" to be a synonym for "domain".
So...
Please can someone propose wording simple, clear wording for what
"guest" means.
~Andrew
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [Xen-devel] [PATCH] docs/sphinx: Introduction
2019-08-07 19:41 [Xen-devel] [PATCH] docs/sphinx: Introduction Andrew Cooper
2019-08-07 22:49 ` Hans van Kranenburg
2019-08-08 6:22 ` Jan Beulich
@ 2019-08-12 15:36 ` George Dunlap
2 siblings, 0 replies; 18+ messages in thread
From: George Dunlap @ 2019-08-12 15:36 UTC (permalink / raw)
To: Andrew Cooper, Xen-devel
Cc: Lars Kurth, Stefano Stabellini, Wei Liu, George Dunlap,
Julien Grall, Jan Beulich, Ian Jackson, Roger Pau Monné
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="<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.
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
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [Xen-devel] Terminology for "guest" - Was: [PATCH] docs/sphinx: Introduction
2019-08-12 15:01 ` Andrew Cooper
@ 2019-08-13 2:59 ` Sarah Newman
2019-08-13 8:43 ` George Dunlap
0 siblings, 1 reply; 18+ messages in thread
From: Sarah Newman @ 2019-08-13 2:59 UTC (permalink / raw)
To: Andrew Cooper, George Dunlap, Julien Grall, Jan Beulich
Cc: Lars Kurth, StefanoStabellini, Wei Liu, George Dunlap, Xen-devel,
Ian Jackson, Roger Pau Monné
On 8/12/19 8:01 AM, Andrew Cooper wrote:
> On 12/08/2019 15:53, George Dunlap wrote:
>> On 8/8/19 10:13 AM, Julien Grall wrote:
>>> Hi Jan,
>>>
>>> On 08/08/2019 10:04, Jan Beulich wrote:
>>>> On 08.08.2019 10:43, Andrew Cooper wrote:
>>>>> On 08/08/2019 07:22, Jan Beulich wrote:
>>>>>> On 07.08.2019 21:41, Andrew Cooper wrote:
>>>>>>> --- /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`
>>>>>> I think you want to mention the usual distinction here: Dom0 is,
>>>>>> while a domain, commonly not considered a guest.
>>>>> To be honest, I had totally forgotten about that. I guess now is the
>>>>> proper time to rehash it in public.
>>>>>
>>>>> I don't think the way it currently gets used has a clear or coherent set
>>>>> of rules, because I can't think of any to describe how it does get used.
>>>>>
>>>>> Either there are a clear and coherent (and simple!) set of rules for
>>>>> what we mean by "guest", at which point they can live here in the
>>>>> glossary, or the fuzzy way it is current used should cease.
>>>> What's fuzzy about Dom0 not being a guest (due to being a part of the
>>>> host instead)?
>>> Dom0 is not part of the host if you are using an hardware domain. I
>>> actually thought we renamed everything in Xen from Dom0 to hwdom to
>>> avoid the confusion.
>>>
>>> I also would rather avoid to treat "dom0" as not a guest. In normal
>>> setup this is a more privilege guest, in other setup this may just be a
>>> normal guest (think about partitioning).
>> A literal guest is someone who doesn't live in the building (or work in
>> the buliding, if you're in a hotel). The fact that the staff cleaning
>> rooms are restricted in their privileges doesn't make them guests of the
>> hotel.
>>
>> The toolstack domain, the hardware domain, the driver domain, the
>> xenstore domain, and so on are all part of the host system, designed to
>> allow you to use Xen to do the thing you actually want to do: Run guests.
>>
>> And it's important that we have a word that distinguishes "domains that
>> we only care about because they make it possible to run other domains",
>> and "domains that we actually want to run". "guest / host" is a natural
>> terminology for these.
>>
>> We already have the word "domain", which includes dom0, driver domains,
>> toolstack domains, hardware domains, as well as guest domains. We don't
>> need "guest" to be a synonym for "domain".
>
> So...
>
> Please can someone propose wording simple, clear wording for what
> "guest" means.
A potentially untrusted domain.
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [Xen-devel] Terminology for "guest" - Was: [PATCH] docs/sphinx: Introduction
2019-08-13 2:59 ` Sarah Newman
@ 2019-08-13 8:43 ` George Dunlap
2019-08-13 8:46 ` Lars Kurth
2019-08-13 19:58 ` Sarah Newman
0 siblings, 2 replies; 18+ messages in thread
From: George Dunlap @ 2019-08-13 8:43 UTC (permalink / raw)
To: Sarah Newman
Cc: Lars Kurth, StefanoStabellini, Wei Liu, Andrew Cooper,
George Dunlap, Julien Grall, Jan Beulich, Ian Jackson, Xen-devel,
Roger Pau Monne
> On Aug 13, 2019, at 3:59 AM, Sarah Newman <srn@prgmr.com> wrote:
>
> On 8/12/19 8:01 AM, Andrew Cooper wrote:
>> On 12/08/2019 15:53, George Dunlap wrote:
>>> On 8/8/19 10:13 AM, Julien Grall wrote:
>>>> Hi Jan,
>>>>
>>>> On 08/08/2019 10:04, Jan Beulich wrote:
>>>>> On 08.08.2019 10:43, Andrew Cooper wrote:
>>>>>> On 08/08/2019 07:22, Jan Beulich wrote:
>>>>>>> On 07.08.2019 21:41, Andrew Cooper wrote:
>>>>>>>> --- /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`
>>>>>>> I think you want to mention the usual distinction here: Dom0 is,
>>>>>>> while a domain, commonly not considered a guest.
>>>>>> To be honest, I had totally forgotten about that. I guess now is the
>>>>>> proper time to rehash it in public.
>>>>>>
>>>>>> I don't think the way it currently gets used has a clear or coherent set
>>>>>> of rules, because I can't think of any to describe how it does get used.
>>>>>>
>>>>>> Either there are a clear and coherent (and simple!) set of rules for
>>>>>> what we mean by "guest", at which point they can live here in the
>>>>>> glossary, or the fuzzy way it is current used should cease.
>>>>> What's fuzzy about Dom0 not being a guest (due to being a part of the
>>>>> host instead)?
>>>> Dom0 is not part of the host if you are using an hardware domain. I
>>>> actually thought we renamed everything in Xen from Dom0 to hwdom to
>>>> avoid the confusion.
>>>>
>>>> I also would rather avoid to treat "dom0" as not a guest. In normal
>>>> setup this is a more privilege guest, in other setup this may just be a
>>>> normal guest (think about partitioning).
>>> A literal guest is someone who doesn't live in the building (or work in
>>> the buliding, if you're in a hotel). The fact that the staff cleaning
>>> rooms are restricted in their privileges doesn't make them guests of the
>>> hotel.
>>>
>>> The toolstack domain, the hardware domain, the driver domain, the
>>> xenstore domain, and so on are all part of the host system, designed to
>>> allow you to use Xen to do the thing you actually want to do: Run guests.
>>>
>>> And it's important that we have a word that distinguishes "domains that
>>> we only care about because they make it possible to run other domains",
>>> and "domains that we actually want to run". "guest / host" is a natural
>>> terminology for these.
>>>
>>> We already have the word "domain", which includes dom0, driver domains,
>>> toolstack domains, hardware domains, as well as guest domains. We don't
>>> need "guest" to be a synonym for "domain".
>> So...
>> Please can someone propose wording simple, clear wording for what
>> "guest" means.
>
> A potentially untrusted domain.
But wouldn’t that include both driver domains and stubdomains?
-George
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [Xen-devel] Terminology for "guest" - Was: [PATCH] docs/sphinx: Introduction
2019-08-13 8:43 ` George Dunlap
@ 2019-08-13 8:46 ` Lars Kurth
2019-08-13 19:58 ` Sarah Newman
1 sibling, 0 replies; 18+ messages in thread
From: Lars Kurth @ 2019-08-13 8:46 UTC (permalink / raw)
To: George Dunlap, Sarah Newman
Cc: StefanoStabellini, Wei Liu, Andrew Cooper, Julien Grall,
Jan Beulich, Ian Jackson, Xen-devel, Roger Pau Monne
On 13/08/2019, 09:43, "George Dunlap" <George.Dunlap@citrix.com> wrote:
> On Aug 13, 2019, at 3:59 AM, Sarah Newman <srn@prgmr.com> wrote:
>
> On 8/12/19 8:01 AM, Andrew Cooper wrote:
>> On 12/08/2019 15:53, George Dunlap wrote:
>>> On 8/8/19 10:13 AM, Julien Grall wrote:
>>>> Hi Jan,
>>>>
>>>> On 08/08/2019 10:04, Jan Beulich wrote:
>>>>> On 08.08.2019 10:43, Andrew Cooper wrote:
>>>>>> On 08/08/2019 07:22, Jan Beulich wrote:
>>>>>>> On 07.08.2019 21:41, Andrew Cooper wrote:
>>>>>>>> --- /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`
>>>>>>> I think you want to mention the usual distinction here: Dom0 is,
>>>>>>> while a domain, commonly not considered a guest.
>>>>>> To be honest, I had totally forgotten about that. I guess now is the
>>>>>> proper time to rehash it in public.
>>>>>>
>>>>>> I don't think the way it currently gets used has a clear or coherent set
>>>>>> of rules, because I can't think of any to describe how it does get used.
>>>>>>
>>>>>> Either there are a clear and coherent (and simple!) set of rules for
>>>>>> what we mean by "guest", at which point they can live here in the
>>>>>> glossary, or the fuzzy way it is current used should cease.
>>>>> What's fuzzy about Dom0 not being a guest (due to being a part of the
>>>>> host instead)?
>>>> Dom0 is not part of the host if you are using an hardware domain. I
>>>> actually thought we renamed everything in Xen from Dom0 to hwdom to
>>>> avoid the confusion.
>>>>
>>>> I also would rather avoid to treat "dom0" as not a guest. In normal
>>>> setup this is a more privilege guest, in other setup this may just be a
>>>> normal guest (think about partitioning).
>>> A literal guest is someone who doesn't live in the building (or work in
>>> the buliding, if you're in a hotel). The fact that the staff cleaning
>>> rooms are restricted in their privileges doesn't make them guests of the
>>> hotel.
>>>
>>> The toolstack domain, the hardware domain, the driver domain, the
>>> xenstore domain, and so on are all part of the host system, designed to
>>> allow you to use Xen to do the thing you actually want to do: Run guests.
>>>
>>> And it's important that we have a word that distinguishes "domains that
>>> we only care about because they make it possible to run other domains",
>>> and "domains that we actually want to run". "guest / host" is a natural
>>> terminology for these.
>>>
>>> We already have the word "domain", which includes dom0, driver domains,
>>> toolstack domains, hardware domains, as well as guest domains. We don't
>>> need "guest" to be a synonym for "domain".
>> So...
>> Please can someone propose wording simple, clear wording for what
>> "guest" means.
>
> A potentially untrusted domain.
But wouldn’t that include both driver domains and stubdomains?
I think the definition you provided looks good and is also along the lines which how most people use it
Lars
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [Xen-devel] Terminology for "guest" - Was: [PATCH] docs/sphinx: Introduction
2019-08-13 8:43 ` George Dunlap
2019-08-13 8:46 ` Lars Kurth
@ 2019-08-13 19:58 ` Sarah Newman
1 sibling, 0 replies; 18+ messages in thread
From: Sarah Newman @ 2019-08-13 19:58 UTC (permalink / raw)
To: George Dunlap
Cc: Lars Kurth, StefanoStabellini, Wei Liu, Andrew Cooper,
Julien Grall, Jan Beulich, Xen-devel, Ian Jackson,
Roger Pau Monne
On 8/13/19 1:43 AM, George Dunlap wrote:
>
>
>> On Aug 13, 2019, at 3:59 AM, Sarah Newman <srn@prgmr.com> wrote:
>>
>> On 8/12/19 8:01 AM, Andrew Cooper wrote:
>>> On 12/08/2019 15:53, George Dunlap wrote:
>>>> On 8/8/19 10:13 AM, Julien Grall wrote:
>>>>> Hi Jan,
>>>>>
>>>>> On 08/08/2019 10:04, Jan Beulich wrote:
>>>>>> On 08.08.2019 10:43, Andrew Cooper wrote:
>>>>>>> On 08/08/2019 07:22, Jan Beulich wrote:
>>>>>>>> On 07.08.2019 21:41, Andrew Cooper wrote:
>>>>>>>>> --- /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`
>>>>>>>> I think you want to mention the usual distinction here: Dom0 is,
>>>>>>>> while a domain, commonly not considered a guest.
>>>>>>> To be honest, I had totally forgotten about that. I guess now is the
>>>>>>> proper time to rehash it in public.
>>>>>>>
>>>>>>> I don't think the way it currently gets used has a clear or coherent set
>>>>>>> of rules, because I can't think of any to describe how it does get used.
>>>>>>>
>>>>>>> Either there are a clear and coherent (and simple!) set of rules for
>>>>>>> what we mean by "guest", at which point they can live here in the
>>>>>>> glossary, or the fuzzy way it is current used should cease.
>>>>>> What's fuzzy about Dom0 not being a guest (due to being a part of the
>>>>>> host instead)?
>>>>> Dom0 is not part of the host if you are using an hardware domain. I
>>>>> actually thought we renamed everything in Xen from Dom0 to hwdom to
>>>>> avoid the confusion.
>>>>>
>>>>> I also would rather avoid to treat "dom0" as not a guest. In normal
>>>>> setup this is a more privilege guest, in other setup this may just be a
>>>>> normal guest (think about partitioning).
>>>> A literal guest is someone who doesn't live in the building (or work in
>>>> the buliding, if you're in a hotel). The fact that the staff cleaning
>>>> rooms are restricted in their privileges doesn't make them guests of the
>>>> hotel.
>>>>
>>>> The toolstack domain, the hardware domain, the driver domain, the
>>>> xenstore domain, and so on are all part of the host system, designed to
>>>> allow you to use Xen to do the thing you actually want to do: Run guests.
>>>>
>>>> And it's important that we have a word that distinguishes "domains that
>>>> we only care about because they make it possible to run other domains",
>>>> and "domains that we actually want to run". "guest / host" is a natural
>>>> terminology for these.
>>>>
>>>> We already have the word "domain", which includes dom0, driver domains,
>>>> toolstack domains, hardware domains, as well as guest domains. We don't
>>>> need "guest" to be a synonym for "domain".
>>> So...
>>> Please can someone propose wording simple, clear wording for what
>>> "guest" means.
>>
>> A potentially untrusted domain.
>
> But wouldn’t that include both driver domains and stubdomains?
Then how about: a domain which does not provide Xen-related services.
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel
^ permalink raw reply [flat|nested] 18+ messages in thread
end of thread, other threads:[~2019-08-13 19:59 UTC | newest]
Thread overview: 18+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-08-07 19:41 [Xen-devel] [PATCH] docs/sphinx: Introduction Andrew Cooper
2019-08-07 22:49 ` Hans van Kranenburg
2019-08-07 23:25 ` Andrew Cooper
2019-08-08 6:22 ` Jan Beulich
2019-08-08 8:43 ` [Xen-devel] Terminology for "guest" - Was: " Andrew Cooper
2019-08-08 9:04 ` Jan Beulich
2019-08-08 9:13 ` Julien Grall
2019-08-08 10:30 ` Andrew Cooper
2019-08-08 10:49 ` Jan Beulich
2019-08-08 11:22 ` Rich Persaud
2019-08-12 14:53 ` George Dunlap
2019-08-12 15:01 ` Andrew Cooper
2019-08-13 2:59 ` Sarah Newman
2019-08-13 8:43 ` George Dunlap
2019-08-13 8:46 ` Lars Kurth
2019-08-13 19:58 ` Sarah Newman
2019-08-08 9:49 ` Roger Pau Monné
2019-08-12 15:36 ` [Xen-devel] " George Dunlap
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).