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

[Andrew Cooper]

On 08/10/2019 13:34, Lars Kurth wrote:
>
> On 03/10/2019, 21:59, "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 
>
> Reviewed-by: Lars Kurth 

Thanks.

>
> There were a few minor improvements which could be made, I am listing these
> below, but none are show-stoppers.
>
> +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
> Maybe better: s/software/software on the system/ or s/software/software on 
> the host/

Fixed.

> +machines.
>
> +   hardware domain
> + A :term:`domain`, commonly dom0, which shares responsibility with 
> Xen
> + about the system as a whole.
> +
> + By default it gets all devices, including all disks and network 
> cards, so
> + is responsible for multiplexing guest I/O
>
> This is a little unclear: in particular the 1st paragraph. Earlier you talk 
> about hardware
> domain="responsible for hardware and marshalling guest I/O", which is 
> clearer. 
>
> Maybe: 
>
> A :term:`domain`, commonly dom0, which hosts all devices, including disks
> and network cards and is responsible for multiplexing guest I/O
>
> is better

Sadly, its not accurate.

Multiplexing of I/O is only in the case that device driver domains
aren't in use.  The other example you cite is a description of the
associated image.

There are things besides I/O which the hardware domain is responsible
for, such as APCI OPSM (but only in x86), and system reboot etc.

I have left the description as-is, for lack of an obviously better way
of expressing things.

~Andrew

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

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

[Lars Kurth]

On 03/10/2019, 21:59, "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 

Reviewed-by: Lars Kurth 

There were a few minor improvements which could be made, I am listing these
below, but none are show-stoppers.

+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
Maybe better: s/software/software on the system/ or s/software/software on the 
host/
+machines.

+   hardware domain
+ A :term:`domain`, commonly dom0, which shares responsibility with Xen
+ about the system as a whole.
+
+ By default it gets all devices, including all disks and network 
cards, so
+ is responsible for multiplexing guest I/O

This is a little unclear: in particular the 1st paragraph. Earlier you talk 
about hardware
domain="responsible for hardware and marshalling guest I/O", which is clearer. 

Maybe: 

A :term:`domain`, commonly dom0, which hosts all devices, including disks
and network cards and is responsible for multiplexing guest I/O

is better

Regards
Lars
 

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

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

[Andrew Cooper]

Put together an introduction page for the Sphinx/RST docs, along with a
glossary which will accumulate over time.

Signed-off-by: Andrew Cooper 
---
CC: Lars Kurth 
CC: George Dunlap 
CC: Ian Jackson 
CC: Jan Beulich 
CC: Konrad Rzeszutek Wilk 
CC: Stefano Stabellini 
CC: Tim Deegan 
CC: Wei Liu 
CC: Julien Grall 
CC: Roger Pau Monné 
CC: Juergen Gross 
---
 docs/admin-guide/index.rst   |  1 +
 docs/admin-guide/introduction.rst| 40 +
 docs/admin-guide/xen-overview.drawio.svg | 97 
 docs/glossary.rst| 52 +
 docs/index.rst   | 12 
 5 files changed, 202 insertions(+)
 create mode 100644 docs/admin-guide/introduction.rst
 create mode 100644 docs/admin-guide/xen-overview.drawio.svg
 create mode 100644 docs/glossary.rst

diff --git a/docs/admin-guide/index.rst b/docs/admin-guide/index.rst
index 1da7c8bf4d..54e6f65de3 100644
--- a/docs/admin-guide/index.rst
+++ b/docs/admin-guide/index.rst
@@ -4,4 +4,5 @@ Admin Guide
 ===
 
 .. toctree::
+   introduction
microcode-loading
diff --git a/docs/admin-guide/introduction.rst 
b/docs/admin-guide/introduction.rst
new file mode 100644
index 00..6da2758d70
--- /dev/null
+++ b/docs/admin-guide/introduction.rst
@@ -0,0 +1,40 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Introduction
+
+
+Xen is an open source, bare metal hypervisor.  It runs as the most privileged
+piece of software, and shares the resources of the hardware between virtual
+machines.
+
+In Xen terminology, there are :term:`domains`, 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 00..f120cdf77a
--- /dev/null
+++ b/docs/admin-guide/xen-overview.drawio.svg
@@ -0,0 +1,97 @@
+
+http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd;>
+http://www.w3.org/2000/svg; 
xmlns:xlink="http://www.w3.org/1999/xlink; version="1.1" width="701px" 
height="461px" viewBox="-0.5 -0.5 701 461" content="mxfile 
modified=2019-08-04T17:05:55.267Z host= 
agent=Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like 
Gecko) draw.io/11.1.1 Chrome/76.0.3809.88 Electron/6.0.0 Safari/537.36 
etag=M7ISh4Ny83I7m1UfK1F2 version=11.1.1 
type=devicediagram id=7q-U8ZVDCMAbtjTOF8Vq