Xen-Devel Archive on lore.kernel.org
 help / color / Atom feed
* [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="&lt;mxfile modified=&quot;2019-08-04T17:05:55.267Z&quot; host=&quot;&quot; agent=&quot;Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/11.1.1 Chrome/76.0.3809.88 Electron/6.0.0 Safari/537.36&quot; etag=&quot;M7ISh4Ny83I7m1UfK1F2&quot; version=&quot;11.1.1&quot; type=&quot;device&quot;&gt;&lt;diagram id=&quot;7q-U8ZVDCMAbtjTOF8Vq&quot; name=&quot;Page-1&quot;&gt;7Zpbd5s4EMc/jR/Tw/3y6FuadNu0jde72X3pwSAua4w4smzjfPoVRhiD5DvGbM42D0WDkMRv5q8ZDB25P0s+Iyv2v0EHhB1JcJKOPOhIkigKEvkvtawziyGamcFDgUM7FYZR8A6oUaDWReCAeakjhjDEQVw22jCKgI1LNgshuCp3c2FYnjW2PMAYRrYVstY/Awf79C5UobA/gcDz8faG6ZmZlXemhrlvOXC1Y5KHHbmPIMTZ0SzpgzCFl3PJrnvcc3a7MAQifMoFySP67j/+MuJ+8nUIfo3D/it4oN5ZWuGC3vAbiOh68TqHgOAickA6jtCRe24Qhn0YQrQ5KbuGDWyb2OcYwSnYOTMxVEXdXAEjTF0rpe0lQDggjLth4EXEOAscJ52rZ1EDyoj2fIiCd3KxFRKjmM4RW3YQea+UuFqYaIulQkGlc4Jkx0QpfQZwBjBaky40RGWZemxVOFzP3ervOFujNovGmLcdqnADOaCeOMMrCuOVAZwJ57nFUYHhKDy3GNJE1rQd2iFwMccrGMYc310DeAfoVha7QCXjVkRVHtFxR9IID7G4rb1wT0NV8YAFDJcrDM02wMStGS49Kyls9N4OtjcZP78mzz/hj/fk53T8Pv2+/v1BZHeVj0pbMZqk/fJtjKDyNogfu8/CQDKXttV9kBnYTxZyVuSujm0Yl+7K1QTguhI/ATjaRFO1enZlRWhwV+aC1hjQL8/9MxnnKG0CAqCaFE9vOAclsqAMDiflVpx0Vv3BfNoCUOIdSRlfxoH79OWP0Ys2nI49bRz+veJUX6P1HIPZnBhHAC0Dm5S+14k42yvrgFdhx9n3eGoUxVvBY/e9bhyH5N5xAKPWYJPUtnFji8s2clPMtnFjS8jfAIrSx90aiJ3/TFWpkepXuKg1iZxbSLLIXwA+nbeoNZNxt+0G8giXE1uZ9EJon5Fyb0aqmnKbRMVVMYvqg6m4mnCalTGXOVsQfjDm1WTVgq2TrY5asnVqLds72XKoLXun3DZUIsuqHUGlCm0jxVYubYkqrXWsRIYVgwk4HhjRJkTYhx6MrHBYWHtlkEWfrzDNEpt3B/8AjNcUr7XAkJNi5r4Vpw03BEk3fXtEbAQ1Wr+lA39S8+ZfdMhNY5DQWbPWusN/TaKmf9zfJzf/NmcshOm0g8kmXsigSYCz2XWVNrezk+Ni8rSRz71913TwZ845XCAbHHANjWKyLA/g48km9dLBEEQgJE+ZS1BaBS+g6KU/YECWXGyIRjl0lWr2zBZKryrCkhmoMo5aje0MDDMOcY213ukWpx3m+9dbmUYyhYOrkqvKLPcnB9kCCqlt0V6hPrY4a5X67qmiS5V/mvqOqipPtzeXVTXuqr+gXygrZpz7yGqr7iZlJbGlUqtkVVNSA6KjAp0nR1PTZateOe5V0s0FYpqfdFMWBVlRDElXjXI8qeWzpnyZekSdP86J09QkLrGiLlk8krRM81D/G6mLLa9bpa57quRSZd9NXZr8v7r2rVpTDva/Wl3c97dmY1ry8SzcieEsaqWLYl0qBbtwJNhLFdopZacLtD2fOOjmRBD2KXivqC559Dr0UUJ9Ir3q1X/+QHZW7PD4/6fjiRcJ5wfU5bGjnRg7ekOxQ5rFZ67ZLlV8LCwP/wU=&lt;/diagram&gt;&lt;/mxfile&gt;">
+  <defs/>
+  <g>
+    <rect x="0" y="330" width="700" height="60" fill="#f8cecc" stroke="#b85450" pointer-events="none"/>
+    <g fill="#000000" font-family="Helvetica" text-anchor="end" font-size="20px">
+      <text x="688.5" y="367.5">Xen</text>
+    </g>
+    <rect x="0" y="0" width="220" height="280" fill="#d5e8d4" stroke="#82b366" pointer-events="none"/>
+    <g fill="#000000" font-family="Helvetica" font-size="20px">
+      <text x="2.5" y="26.5">Dom0</text>
+    </g>
+    <rect x="240" y="0" width="220" height="280" fill="#dae8fc" stroke="#6c8ebf" pointer-events="none"/>
+    <g fill="#000000" font-family="Helvetica" font-size="20px">
+      <text x="242.5" y="26.5">DomU</text>
+    </g>
+    <rect x="480" y="0" width="220" height="280" fill="#dae8fc" stroke="#6c8ebf" pointer-events="none"/>
+    <g fill="#000000" font-family="Helvetica" font-size="20px">
+      <text x="482.5" y="26.5">DomU</text>
+    </g>
+    <rect x="0" y="400" width="700" height="60" fill="#fff2cc" stroke="#d6b656" pointer-events="none"/>
+    <g fill="#000000" font-family="Helvetica" text-anchor="end" font-size="20px">
+      <text x="696.5" y="437.5">Hardware</text>
+    </g>
+    <rect x="20" y="410" width="80" height="40" fill="#ffffff" stroke="#000000" pointer-events="none"/>
+    <g fill="#000000" font-family="Helvetica" text-anchor="middle" font-size="20px">
+      <text x="59.5" y="437.5">NIC</text>
+    </g>
+    <rect x="120" y="410" width="80" height="40" fill="#ffffff" stroke="#000000" pointer-events="none"/>
+    <g fill="#000000" font-family="Helvetica" text-anchor="middle" font-size="20px">
+      <text x="159.5" y="437.5">Disk</text>
+    </g>
+    <rect x="10" y="40" width="200" height="110" fill="#ffffff" stroke="#000000" pointer-events="none"/>
+    <g fill="#000000" font-family="Helvetica" text-anchor="middle" font-size="20px">
+      <text x="109.5" y="66.5">Systems Services</text>
+    </g>
+    <rect x="250" y="40" width="200" height="110" fill="#ffffff" stroke="#000000" pointer-events="none"/>
+    <g fill="#000000" font-family="Helvetica" text-anchor="middle" font-size="20px">
+      <text x="349.5" y="66.5">Applications</text>
+    </g>
+    <rect x="490" y="40" width="200" height="110" fill="#ffffff" stroke="#000000" pointer-events="none"/>
+    <g fill="#000000" font-family="Helvetica" text-anchor="middle" font-size="20px">
+      <text x="589.5" y="66.5">Applications</text>
+    </g>
+    <rect x="10" y="160" width="200" height="110" fill="#f8cecc" stroke="#b85450" pointer-events="none"/>
+    <g fill="#000000" font-family="Helvetica" font-size="20px">
+      <text x="12.5" y="186.5">Kernel</text>
+    </g>
+    <rect x="20" y="220" width="80" height="40" fill="#ffffff" stroke="#000000" pointer-events="none"/>
+    <g fill="#000000" font-family="Helvetica" text-anchor="middle" font-size="16px">
+      <text x="59.5" y="245.5">Net</text>
+    </g>
+    <rect x="120" y="220" width="80" height="40" fill="#ffffff" stroke="#000000" pointer-events="none"/>
+    <g fill="#000000" font-family="Helvetica" text-anchor="middle" font-size="16px">
+      <text x="159.5" y="245.5">Block</text>
+    </g>
+    <rect x="250" y="160" width="200" height="110" fill="#f8cecc" stroke="#b85450" pointer-events="none"/>
+    <g fill="#000000" font-family="Helvetica" font-size="20px">
+      <text x="252.5" y="186.5">Kernel</text>
+    </g>
+    <rect x="490" y="160" width="200" height="110" fill="#f8cecc" stroke="#b85450" pointer-events="none"/>
+    <g fill="#000000" font-family="Helvetica" font-size="20px">
+      <text x="492.5" y="186.5">Kernel</text>
+    </g>
+    <rect x="260" y="220" width="80" height="40" fill="#ffffff" stroke="#000000" pointer-events="none"/>
+    <g fill="#000000" font-family="Helvetica" text-anchor="middle" font-size="16px">
+      <text x="299.5" y="245.5">Net</text>
+    </g>
+    <rect x="360" y="220" width="80" height="40" fill="#ffffff" stroke="#000000" pointer-events="none"/>
+    <g fill="#000000" font-family="Helvetica" text-anchor="middle" font-size="16px">
+      <text x="399.5" y="245.5">Block</text>
+    </g>
+    <rect x="500" y="220" width="80" height="40" fill="#ffffff" stroke="#000000" pointer-events="none"/>
+    <g fill="#000000" font-family="Helvetica" text-anchor="middle" font-size="16px">
+      <text x="539.5" y="245.5">Net</text>
+    </g>
+    <rect x="600" y="220" width="80" height="40" fill="#ffffff" stroke="#000000" pointer-events="none"/>
+    <g fill="#000000" font-family="Helvetica" text-anchor="middle" font-size="16px">
+      <text x="639.5" y="245.5">Block</text>
+    </g>
+    <path d="M 75 279.5 L 64.5 279.5 L 80 260.5 L 95.5 279.5 L 85 279.5 L 85 285 L 295 285 L 295 279.5 L 284.5 279.5 L 300 260.5 L 315.5 279.5 L 305 279.5 L 305 295 L 75 295 Z" fill="#f5f5f5" stroke="#666666" stroke-miterlimit="1.42" pointer-events="none"/>
+    <path d="M 75 279.5 L 64.5 279.5 L 80 260.5 L 95.5 279.5 L 85 279.5" fill="none" stroke="#666666" stroke-miterlimit="4" pointer-events="none"/>
+    <path d="M 295 279.5 L 284.5 279.5 L 300 260.5 L 315.5 279.5 L 305 279.5" fill="none" stroke="#666666" stroke-miterlimit="4" pointer-events="none"/>
+    <path d="M 75 279.5 L 64.5 279.5 L 80 260.5 L 95.5 279.5 L 85 279.5 L 85 285 L 535 285 L 535 279.5 L 524.5 279.5 L 540 260.5 L 555.5 279.5 L 545 279.5 L 545 295 L 75 295 Z" fill="#f5f5f5" stroke="#666666" stroke-miterlimit="1.42" pointer-events="none"/>
+    <path d="M 75 279.5 L 64.5 279.5 L 80 260.5 L 95.5 279.5 L 85 279.5" fill="none" stroke="#666666" stroke-miterlimit="4" pointer-events="none"/>
+    <path d="M 535 279.5 L 524.5 279.5 L 540 260.5 L 555.5 279.5 L 545 279.5" fill="none" stroke="#666666" stroke-miterlimit="4" pointer-events="none"/>
+    <path d="M 175 279.5 L 164.5 279.5 L 180 260.5 L 195.5 279.5 L 185 279.5 L 185 305 L 395 305 L 395 279.5 L 384.5 279.5 L 400 260.5 L 415.5 279.5 L 405 279.5 L 405 315 L 175 315 Z" fill="#e1d5e7" stroke="#9673a6" stroke-miterlimit="1.42" pointer-events="none"/>
+    <path d="M 175 279.5 L 164.5 279.5 L 180 260.5 L 195.5 279.5 L 185 279.5" fill="none" stroke="#9673a6" stroke-miterlimit="4" pointer-events="none"/>
+    <path d="M 395 279.5 L 384.5 279.5 L 400 260.5 L 415.5 279.5 L 405 279.5" fill="none" stroke="#9673a6" stroke-miterlimit="4" pointer-events="none"/>
+    <path d="M 175 279.5 L 164.5 279.5 L 180 260.5 L 195.5 279.5 L 185 279.5 L 185 305 L 635 305 L 635 279.5 L 624.5 279.5 L 640 260.5 L 655.5 279.5 L 645 279.5 L 645 315 L 175 315 Z" fill="#e1d5e7" stroke="#9673a6" stroke-miterlimit="1.42" pointer-events="none"/>
+    <path d="M 175 279.5 L 164.5 279.5 L 180 260.5 L 195.5 279.5 L 185 279.5" fill="none" stroke="#9673a6" stroke-miterlimit="4" pointer-events="none"/>
+    <path d="M 635 279.5 L 624.5 279.5 L 640 260.5 L 655.5 279.5 L 645 279.5" fill="none" stroke="#9673a6" stroke-miterlimit="4" pointer-events="none"/>
+    <path d="M 35 279.5 L 24.5 279.5 L 40 260.5 L 55.5 279.5 L 45 279.5 L 45 390.5 L 55.5 390.5 L 40 409.5 L 24.5 390.5 L 35 390.5 Z" fill="#ffe6cc" stroke="#d79b00" stroke-miterlimit="10" pointer-events="none"/>
+    <path d="M 135 279.5 L 124.5 279.5 L 140 260.5 L 155.5 279.5 L 145 279.5 L 145 390.5 L 155.5 390.5 L 140 409.5 L 124.5 390.5 L 135 390.5 Z" fill="#ffe6cc" stroke="#d79b00" stroke-miterlimit="10" pointer-events="none"/>
+  </g>
+</svg>
diff --git a/docs/glossary.rst b/docs/glossary.rst
new file mode 100644
index 0000000000..a1a3e2f28d
--- /dev/null
+++ b/docs/glossary.rst
@@ -0,0 +1,37 @@
+Glossary
+========
+
+.. Terms should appear in alphabetical order
+
+.. glossary::
+
+   control domain
+     A :term:`domain`, commonly dom0, with the permission and responsibility
+     to create and manage other domains on the system.
+
+   domain
+     A domain is Xen's unit of resource ownership, and generally has at the
+     minimum some RAM and virtual CPUs.
+
+     The terms :term:`domain` and :term:`guest` are commonly used
+     interchangeably, but they mean subtly different things.
+
+     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	[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 --]

<html><head><meta http-equiv="content-type" content="text/html; charset=utf-8"></head><body dir="auto"><div dir="ltr"></div><div dir="ltr">On Aug 8, 2019, at 06:49, Jan Beulich &lt;<a href="mailto:JBeulich@suse.com">JBeulich@suse.com</a>&gt; wrote:</div><div dir="ltr"><br></div><blockquote type="cite"><div dir="ltr"><span>On 08.08.2019 11:13, Julien Grall wrote:</span><br><blockquote type="cite"><span>Hi Jan,</span><br></blockquote><blockquote type="cite"><span></span><br></blockquote><blockquote type="cite"><span>On 08/08/2019 10:04, Jan Beulich wrote:</span><br></blockquote><blockquote type="cite"><blockquote type="cite"><span>On 08.08.2019 10:43, Andrew Cooper wrote:</span><br></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>On 08/08/2019 07:22, Jan Beulich wrote:</span><br></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>On 07.08.2019 21:41, Andrew Cooper wrote:</span><br></blockquote></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>--- /dev/null</span><br></blockquote></blockquote></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>+++ b/docs/glossary.rst</span><br></blockquote></blockquote></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>@@ -0,0 +1,37 @@</span><br></blockquote></blockquote></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>+Glossary</span><br></blockquote></blockquote></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>+========</span><br></blockquote></blockquote></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>+</span><br></blockquote></blockquote></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>+.. Terms should appear in alphabetical order</span><br></blockquote></blockquote></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>+</span><br></blockquote></blockquote></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>+.. glossary::</span><br></blockquote></blockquote></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>+</span><br></blockquote></blockquote></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>+&nbsp;&nbsp; control domain</span><br></blockquote></blockquote></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>+&nbsp;&nbsp;&nbsp;&nbsp; A :term:`domain`, commonly dom0, with the permission and</span><br></blockquote></blockquote></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>responsibility</span><br></blockquote></blockquote></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>+&nbsp;&nbsp;&nbsp;&nbsp; to create and manage other domains on the system.</span><br></blockquote></blockquote></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>+</span><br></blockquote></blockquote></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>+&nbsp;&nbsp; domain</span><br></blockquote></blockquote></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>+&nbsp;&nbsp;&nbsp;&nbsp; A domain is Xen's unit of resource ownership, and generally has</span><br></blockquote></blockquote></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>at the</span><br></blockquote></blockquote></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>+&nbsp;&nbsp;&nbsp;&nbsp; minimum some RAM and virtual CPUs.</span><br></blockquote></blockquote></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>+</span><br></blockquote></blockquote></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>+&nbsp;&nbsp;&nbsp;&nbsp; The terms :term:`domain` and :term:`guest` are commonly used</span><br></blockquote></blockquote></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>+&nbsp;&nbsp;&nbsp;&nbsp; interchangeably, but they mean subtly different things.</span><br></blockquote></blockquote></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>+</span><br></blockquote></blockquote></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>+&nbsp;&nbsp;&nbsp;&nbsp; A guest is a single virtual machine.</span><br></blockquote></blockquote></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>+</span><br></blockquote></blockquote></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>+&nbsp;&nbsp;&nbsp;&nbsp; Consider the case of live migration where, for a period of</span><br></blockquote></blockquote></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>time, one</span><br></blockquote></blockquote></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>+&nbsp;&nbsp;&nbsp;&nbsp; guest will be comprised of two domains, while it is in transit.</span><br></blockquote></blockquote></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>+</span><br></blockquote></blockquote></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>+&nbsp;&nbsp; domid</span><br></blockquote></blockquote></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>+&nbsp;&nbsp;&nbsp;&nbsp; The numeric identifier of a running :term:`domain`.&nbsp; It is</span><br></blockquote></blockquote></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>unique to a</span><br></blockquote></blockquote></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>+&nbsp;&nbsp;&nbsp;&nbsp; single instance of Xen, used as the identifier in various APIs,</span><br></blockquote></blockquote></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>and is</span><br></blockquote></blockquote></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>+&nbsp;&nbsp;&nbsp;&nbsp; typically allocated sequentially from 0.</span><br></blockquote></blockquote></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>+</span><br></blockquote></blockquote></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>+&nbsp;&nbsp; guest</span><br></blockquote></blockquote></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>+&nbsp;&nbsp;&nbsp;&nbsp; See :term:`domain`</span><br></blockquote></blockquote></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span></span><br></blockquote></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>I think you want to mention the usual distinction here: Dom0 is,</span><br></blockquote></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>while a domain, commonly not considered a guest.</span><br></blockquote></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span></span><br></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>To be honest, I had totally forgotten about that.&nbsp; I guess now is the</span><br></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>proper time to rehash it in public.</span><br></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span></span><br></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>I don't think the way it currently gets used has a clear or coherent set</span><br></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>of rules, because I can't think of any to describe how it does get used.</span><br></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span></span><br></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>Either there are a clear and coherent (and simple!) set of rules for</span><br></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>what we mean by "guest", at which point they can live here in the</span><br></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><span>glossary, or the fuzzy way it is current used should cease.</span><br></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><span></span><br></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><span>What's fuzzy about Dom0 not being a guest (due to being a part of the</span><br></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><span>host instead)?</span><br></blockquote></blockquote><blockquote type="cite"><span>Dom0 is not part of the host if you are using an hardware domain.</span><br></blockquote><span></span><br><span>It's still the control domain then, and hence still part of the host.</span></div></blockquote><br><div>With disaggregation and dom0less (how might we describe that term in the intro?) for edge/embedded Xen systems, there could be a mode where&nbsp;<span style="background-color: rgba(255, 255, 255, 0);">the control domain has&nbsp;</span><span style="background-color: rgba(255, 255, 255, 0);">never had privilege over the domain that handles the physical TPM, or the</span><span style="background-color: rgba(255, 255, 255, 0);">&nbsp;</span><span style="background-color: rgba(255, 255, 255, 0);">provider of the virtual TPM: &nbsp;</span></div><div><br></div><div>&nbsp;&nbsp;<a href="https://lists.gt.net/xen/devel/557782">https://lists.gt.net/xen/devel/557782</a></div><div><br></div><div>Rich</div></body></html>

[-- 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="&lt;mxfile modified=&quot;2019-08-04T17:05:55.267Z&quot; host=&quot;&quot; agent=&quot;Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/11.1.1 Chrome/76.0.3809.88 Electron/6.0.0 Safari/537.36&quot; etag=&quot;M7ISh4Ny83I7m1UfK1F2&quot; version=&quot;11.1.1&quot; type=&quot;device&quot;&gt;&lt;diagram id=&quot;7q-U8ZVDCMAbtjTOF8Vq&quot; name=&quot;Page-1&quot;&gt;7Zpbd5s4EMc/jR/Tw/3y6FuadNu0jde72X3pwSAua4w4smzjfPoVRhiD5DvGbM42D0WDkMRv5q8ZDB25P0s+Iyv2v0EHhB1JcJKOPOhIkigKEvkvtawziyGamcFDgUM7FYZR8A6oUaDWReCAeakjhjDEQVw22jCKgI1LNgshuCp3c2FYnjW2PMAYRrYVstY/Awf79C5UobA/gcDz8faG6ZmZlXemhrlvOXC1Y5KHHbmPIMTZ0SzpgzCFl3PJrnvcc3a7MAQifMoFySP67j/+MuJ+8nUIfo3D/it4oN5ZWuGC3vAbiOh68TqHgOAickA6jtCRe24Qhn0YQrQ5KbuGDWyb2OcYwSnYOTMxVEXdXAEjTF0rpe0lQDggjLth4EXEOAscJ52rZ1EDyoj2fIiCd3KxFRKjmM4RW3YQea+UuFqYaIulQkGlc4Jkx0QpfQZwBjBaky40RGWZemxVOFzP3ervOFujNovGmLcdqnADOaCeOMMrCuOVAZwJ57nFUYHhKDy3GNJE1rQd2iFwMccrGMYc310DeAfoVha7QCXjVkRVHtFxR9IID7G4rb1wT0NV8YAFDJcrDM02wMStGS49Kyls9N4OtjcZP78mzz/hj/fk53T8Pv2+/v1BZHeVj0pbMZqk/fJtjKDyNogfu8/CQDKXttV9kBnYTxZyVuSujm0Yl+7K1QTguhI/ATjaRFO1enZlRWhwV+aC1hjQL8/9MxnnKG0CAqCaFE9vOAclsqAMDiflVpx0Vv3BfNoCUOIdSRlfxoH79OWP0Ys2nI49bRz+veJUX6P1HIPZnBhHAC0Dm5S+14k42yvrgFdhx9n3eGoUxVvBY/e9bhyH5N5xAKPWYJPUtnFji8s2clPMtnFjS8jfAIrSx90aiJ3/TFWpkepXuKg1iZxbSLLIXwA+nbeoNZNxt+0G8giXE1uZ9EJon5Fyb0aqmnKbRMVVMYvqg6m4mnCalTGXOVsQfjDm1WTVgq2TrY5asnVqLds72XKoLXun3DZUIsuqHUGlCm0jxVYubYkqrXWsRIYVgwk4HhjRJkTYhx6MrHBYWHtlkEWfrzDNEpt3B/8AjNcUr7XAkJNi5r4Vpw03BEk3fXtEbAQ1Wr+lA39S8+ZfdMhNY5DQWbPWusN/TaKmf9zfJzf/NmcshOm0g8kmXsigSYCz2XWVNrezk+Ni8rSRz71913TwZ845XCAbHHANjWKyLA/g48km9dLBEEQgJE+ZS1BaBS+g6KU/YECWXGyIRjl0lWr2zBZKryrCkhmoMo5aje0MDDMOcY213ukWpx3m+9dbmUYyhYOrkqvKLPcnB9kCCqlt0V6hPrY4a5X67qmiS5V/mvqOqipPtzeXVTXuqr+gXygrZpz7yGqr7iZlJbGlUqtkVVNSA6KjAp0nR1PTZateOe5V0s0FYpqfdFMWBVlRDElXjXI8qeWzpnyZekSdP86J09QkLrGiLlk8krRM81D/G6mLLa9bpa57quRSZd9NXZr8v7r2rVpTDva/Wl3c97dmY1ry8SzcieEsaqWLYl0qBbtwJNhLFdopZacLtD2fOOjmRBD2KXivqC559Dr0UUJ9Ir3q1X/+QHZW7PD4/6fjiRcJ5wfU5bGjnRg7ekOxQ5rFZ67ZLlV8LCwP/wU=&lt;/diagram&gt;&lt;/mxfile&gt;">
> +  <defs/>
> +  <g>
> +    <rect x="0" y="330" width="700" height="60" fill="#f8cecc" stroke="#b85450" pointer-events="none"/>
> +    <g fill="#000000" font-family="Helvetica" text-anchor="end" font-size="20px">
> +      <text x="688.5" y="367.5">Xen</text>
> +    </g>
> +    <rect x="0" y="0" width="220" height="280" fill="#d5e8d4" stroke="#82b366" pointer-events="none"/>
> +    <g fill="#000000" font-family="Helvetica" font-size="20px">
> +      <text x="2.5" y="26.5">Dom0</text>
> +    </g>
> +    <rect x="240" y="0" width="220" height="280" fill="#dae8fc" stroke="#6c8ebf" pointer-events="none"/>
> +    <g fill="#000000" font-family="Helvetica" font-size="20px">
> +      <text x="242.5" y="26.5">DomU</text>
> +    </g>
> +    <rect x="480" y="0" width="220" height="280" fill="#dae8fc" stroke="#6c8ebf" pointer-events="none"/>
> +    <g fill="#000000" font-family="Helvetica" font-size="20px">
> +      <text x="482.5" y="26.5">DomU</text>
> +    </g>
> +    <rect x="0" y="400" width="700" height="60" fill="#fff2cc" stroke="#d6b656" pointer-events="none"/>
> +    <g fill="#000000" font-family="Helvetica" text-anchor="end" font-size="20px">
> +      <text x="696.5" y="437.5">Hardware</text>
> +    </g>
> +    <rect x="20" y="410" width="80" height="40" fill="#ffffff" stroke="#000000" pointer-events="none"/>
> +    <g fill="#000000" font-family="Helvetica" text-anchor="middle" font-size="20px">
> +      <text x="59.5" y="437.5">NIC</text>
> +    </g>
> +    <rect x="120" y="410" width="80" height="40" fill="#ffffff" stroke="#000000" pointer-events="none"/>
> +    <g fill="#000000" font-family="Helvetica" text-anchor="middle" font-size="20px">
> +      <text x="159.5" y="437.5">Disk</text>
> +    </g>
> +    <rect x="10" y="40" width="200" height="110" fill="#ffffff" stroke="#000000" pointer-events="none"/>
> +    <g fill="#000000" font-family="Helvetica" text-anchor="middle" font-size="20px">
> +      <text x="109.5" y="66.5">Systems Services</text>
> +    </g>
> +    <rect x="250" y="40" width="200" height="110" fill="#ffffff" stroke="#000000" pointer-events="none"/>
> +    <g fill="#000000" font-family="Helvetica" text-anchor="middle" font-size="20px">
> +      <text x="349.5" y="66.5">Applications</text>
> +    </g>
> +    <rect x="490" y="40" width="200" height="110" fill="#ffffff" stroke="#000000" pointer-events="none"/>
> +    <g fill="#000000" font-family="Helvetica" text-anchor="middle" font-size="20px">
> +      <text x="589.5" y="66.5">Applications</text>
> +    </g>
> +    <rect x="10" y="160" width="200" height="110" fill="#f8cecc" stroke="#b85450" pointer-events="none"/>
> +    <g fill="#000000" font-family="Helvetica" font-size="20px">
> +      <text x="12.5" y="186.5">Kernel</text>
> +    </g>
> +    <rect x="20" y="220" width="80" height="40" fill="#ffffff" stroke="#000000" pointer-events="none"/>
> +    <g fill="#000000" font-family="Helvetica" text-anchor="middle" font-size="16px">
> +      <text x="59.5" y="245.5">Net</text>
> +    </g>
> +    <rect x="120" y="220" width="80" height="40" fill="#ffffff" stroke="#000000" pointer-events="none"/>
> +    <g fill="#000000" font-family="Helvetica" text-anchor="middle" font-size="16px">
> +      <text x="159.5" y="245.5">Block</text>
> +    </g>
> +    <rect x="250" y="160" width="200" height="110" fill="#f8cecc" stroke="#b85450" pointer-events="none"/>
> +    <g fill="#000000" font-family="Helvetica" font-size="20px">
> +      <text x="252.5" y="186.5">Kernel</text>
> +    </g>
> +    <rect x="490" y="160" width="200" height="110" fill="#f8cecc" stroke="#b85450" pointer-events="none"/>
> +    <g fill="#000000" font-family="Helvetica" font-size="20px">
> +      <text x="492.5" y="186.5">Kernel</text>
> +    </g>
> +    <rect x="260" y="220" width="80" height="40" fill="#ffffff" stroke="#000000" pointer-events="none"/>
> +    <g fill="#000000" font-family="Helvetica" text-anchor="middle" font-size="16px">
> +      <text x="299.5" y="245.5">Net</text>
> +    </g>
> +    <rect x="360" y="220" width="80" height="40" fill="#ffffff" stroke="#000000" pointer-events="none"/>
> +    <g fill="#000000" font-family="Helvetica" text-anchor="middle" font-size="16px">
> +      <text x="399.5" y="245.5">Block</text>
> +    </g>
> +    <rect x="500" y="220" width="80" height="40" fill="#ffffff" stroke="#000000" pointer-events="none"/>
> +    <g fill="#000000" font-family="Helvetica" text-anchor="middle" font-size="16px">
> +      <text x="539.5" y="245.5">Net</text>
> +    </g>
> +    <rect x="600" y="220" width="80" height="40" fill="#ffffff" stroke="#000000" pointer-events="none"/>
> +    <g fill="#000000" font-family="Helvetica" text-anchor="middle" font-size="16px">
> +      <text x="639.5" y="245.5">Block</text>
> +    </g>
> +    <path d="M 75 279.5 L 64.5 279.5 L 80 260.5 L 95.5 279.5 L 85 279.5 L 85 285 L 295 285 L 295 279.5 L 284.5 279.5 L 300 260.5 L 315.5 279.5 L 305 279.5 L 305 295 L 75 295 Z" fill="#f5f5f5" stroke="#666666" stroke-miterlimit="1.42" pointer-events="none"/>
> +    <path d="M 75 279.5 L 64.5 279.5 L 80 260.5 L 95.5 279.5 L 85 279.5" fill="none" stroke="#666666" stroke-miterlimit="4" pointer-events="none"/>
> +    <path d="M 295 279.5 L 284.5 279.5 L 300 260.5 L 315.5 279.5 L 305 279.5" fill="none" stroke="#666666" stroke-miterlimit="4" pointer-events="none"/>
> +    <path d="M 75 279.5 L 64.5 279.5 L 80 260.5 L 95.5 279.5 L 85 279.5 L 85 285 L 535 285 L 535 279.5 L 524.5 279.5 L 540 260.5 L 555.5 279.5 L 545 279.5 L 545 295 L 75 295 Z" fill="#f5f5f5" stroke="#666666" stroke-miterlimit="1.42" pointer-events="none"/>
> +    <path d="M 75 279.5 L 64.5 279.5 L 80 260.5 L 95.5 279.5 L 85 279.5" fill="none" stroke="#666666" stroke-miterlimit="4" pointer-events="none"/>
> +    <path d="M 535 279.5 L 524.5 279.5 L 540 260.5 L 555.5 279.5 L 545 279.5" fill="none" stroke="#666666" stroke-miterlimit="4" pointer-events="none"/>
> +    <path d="M 175 279.5 L 164.5 279.5 L 180 260.5 L 195.5 279.5 L 185 279.5 L 185 305 L 395 305 L 395 279.5 L 384.5 279.5 L 400 260.5 L 415.5 279.5 L 405 279.5 L 405 315 L 175 315 Z" fill="#e1d5e7" stroke="#9673a6" stroke-miterlimit="1.42" pointer-events="none"/>
> +    <path d="M 175 279.5 L 164.5 279.5 L 180 260.5 L 195.5 279.5 L 185 279.5" fill="none" stroke="#9673a6" stroke-miterlimit="4" pointer-events="none"/>
> +    <path d="M 395 279.5 L 384.5 279.5 L 400 260.5 L 415.5 279.5 L 405 279.5" fill="none" stroke="#9673a6" stroke-miterlimit="4" pointer-events="none"/>
> +    <path d="M 175 279.5 L 164.5 279.5 L 180 260.5 L 195.5 279.5 L 185 279.5 L 185 305 L 635 305 L 635 279.5 L 624.5 279.5 L 640 260.5 L 655.5 279.5 L 645 279.5 L 645 315 L 175 315 Z" fill="#e1d5e7" stroke="#9673a6" stroke-miterlimit="1.42" pointer-events="none"/>
> +    <path d="M 175 279.5 L 164.5 279.5 L 180 260.5 L 195.5 279.5 L 185 279.5" fill="none" stroke="#9673a6" stroke-miterlimit="4" pointer-events="none"/>
> +    <path d="M 635 279.5 L 624.5 279.5 L 640 260.5 L 655.5 279.5 L 645 279.5" fill="none" stroke="#9673a6" stroke-miterlimit="4" pointer-events="none"/>
> +    <path d="M 35 279.5 L 24.5 279.5 L 40 260.5 L 55.5 279.5 L 45 279.5 L 45 390.5 L 55.5 390.5 L 40 409.5 L 24.5 390.5 L 35 390.5 Z" fill="#ffe6cc" stroke="#d79b00" stroke-miterlimit="10" pointer-events="none"/>
> +    <path d="M 135 279.5 L 124.5 279.5 L 140 260.5 L 155.5 279.5 L 145 279.5 L 145 390.5 L 155.5 390.5 L 140 409.5 L 124.5 390.5 L 135 390.5 Z" fill="#ffe6cc" stroke="#d79b00" stroke-miterlimit="10" pointer-events="none"/>
> +  </g>
> +</svg>
> diff --git a/docs/glossary.rst b/docs/glossary.rst
> new file mode 100644
> index 0000000000..a1a3e2f28d
> --- /dev/null
> +++ b/docs/glossary.rst
> @@ -0,0 +1,37 @@
> +Glossary
> +========
> +
> +.. Terms should appear in alphabetical order
> +
> +.. glossary::
> +
> +   control domain
> +     A :term:`domain`, commonly dom0, with the permission and responsibility
> +     to create and manage other domains on the system.
> +
> +   domain
> +     A domain is Xen's unit of resource ownership, and generally has at the
> +     minimum some RAM and virtual CPUs.
> +
> +     The terms :term:`domain` and :term:`guest` are commonly used
> +     interchangeably, but they mean subtly different things.

What about something like this?

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

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

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

---

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

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

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

^ 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, back to index

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

Xen-Devel Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/xen-devel/0 xen-devel/git/0.git
	git clone --mirror https://lore.kernel.org/xen-devel/1 xen-devel/git/1.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 xen-devel xen-devel/ https://lore.kernel.org/xen-devel \
		xen-devel@lists.xenproject.org xen-devel@archiver.kernel.org
	public-inbox-index xen-devel


Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.xenproject.lists.xen-devel


AGPL code for this site: git clone https://public-inbox.org/ public-inbox