From nobody Thu Apr 18 09:48:47 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; spf=none (zoho.com: 192.237.175.120 is neither permitted nor denied by domain of lists.xenproject.org) smtp.mailfrom=xen-devel-bounces@lists.xenproject.org ARC-Seal: i=1; a=rsa-sha256; t=1565207003; cv=none; d=zoho.com; s=zohoarc; b=PDaMEU+AblKXMt3JqmYDRHbwHEIe3zautLw3VYfVjjwxBX67/kS1GYgqg/9btWHBBSNo9D3oObMXPMbxvDoa7tc46YqXDub9IpQFK9RTnru4NHYU/DCQrQXA6LVF0NoSK3/U4NLbEnEkCCtlhchFfNzCmPAacoNAHV3smC8GLZ0= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zoho.com; s=zohoarc; t=1565207003; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:List-Subscribe:List-Post:List-Id:List-Help:List-Unsubscribe:MIME-Version:Message-ID:Sender:Subject:To:ARC-Authentication-Results; bh=MgdG8QvRg20Fk4NjVmrSccQZhbJoWM6CLCHwdOdrL8E=; b=SkB5anGk/jlLOLuJsh8CF7Wd8C+i5DcxVwgvN4ZULYLZimB1Cv4vpg6xW5SwQsz/M54kWMa2a7Lf+Ztcl2yuAHBjJ54cL+R9jjdaYlUHgiWUFM6wcOaKCKSqG1hJ4gwQBTA15m4lC/yMTmTOlTRzmu4tqJCa9fRZafKsHW/JbtU= ARC-Authentication-Results: i=1; mx.zoho.com; spf=none (zoho.com: 192.237.175.120 is neither permitted nor denied by domain of lists.xenproject.org) smtp.mailfrom=xen-devel-bounces@lists.xenproject.org Return-Path: Received: from lists.xenproject.org (lists.xenproject.org [192.237.175.120]) by mx.zohomail.com with SMTPS id 156520700356318.938564295129822; Wed, 7 Aug 2019 12:43:23 -0700 (PDT) Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.89) (envelope-from ) id 1hvRoq-0004ZC-DS; Wed, 07 Aug 2019 19:41:56 +0000 Received: from us1-rack-dfw2.inumbo.com ([104.130.134.6]) by lists.xenproject.org with esmtp (Exim 4.89) (envelope-from ) id 1hvRoo-0004Z7-R9 for xen-devel@lists.xenproject.org; Wed, 07 Aug 2019 19:41:54 +0000 Received: from esa2.hc3370-68.iphmx.com (unknown [216.71.145.153]) by us1-rack-dfw2.inumbo.com (Halon) with ESMTPS id 67a1c89a-b94b-11e9-8980-bc764e045a96; Wed, 07 Aug 2019 19:41:52 +0000 (UTC) X-Inumbo-ID: 67a1c89a-b94b-11e9-8980-bc764e045a96 Authentication-Results: esa2.hc3370-68.iphmx.com; dkim=none (message not signed) header.i=none; spf=None smtp.pra=andrew.cooper3@citrix.com; spf=Pass smtp.mailfrom=Andrew.Cooper3@citrix.com; spf=None smtp.helo=postmaster@mail.citrix.com Received-SPF: none (zoho.com: 192.237.175.120 is neither permitted nor denied by domain of lists.xenproject.org) client-ip=192.237.175.120; envelope-from=xen-devel-bounces@lists.xenproject.org; helo=lists.xenproject.org; Received-SPF: None (esa2.hc3370-68.iphmx.com: no sender authenticity information available from domain of andrew.cooper3@citrix.com) identity=pra; client-ip=162.221.158.21; receiver=esa2.hc3370-68.iphmx.com; envelope-from="Andrew.Cooper3@citrix.com"; x-sender="andrew.cooper3@citrix.com"; x-conformance=sidf_compatible Received-SPF: Pass (esa2.hc3370-68.iphmx.com: domain of Andrew.Cooper3@citrix.com designates 162.221.158.21 as permitted sender) identity=mailfrom; client-ip=162.221.158.21; receiver=esa2.hc3370-68.iphmx.com; envelope-from="Andrew.Cooper3@citrix.com"; x-sender="Andrew.Cooper3@citrix.com"; x-conformance=sidf_compatible; x-record-type="v=spf1"; x-record-text="v=spf1 ip4:209.167.231.154 ip4:178.63.86.133 ip4:195.66.111.40/30 ip4:85.115.9.32/28 ip4:199.102.83.4 ip4:192.28.146.160 ip4:192.28.146.107 ip4:216.52.6.88 ip4:216.52.6.188 ip4:162.221.158.21 ip4:162.221.156.83 ~all" Received-SPF: None (esa2.hc3370-68.iphmx.com: no sender authenticity information available from domain of postmaster@mail.citrix.com) identity=helo; client-ip=162.221.158.21; receiver=esa2.hc3370-68.iphmx.com; envelope-from="Andrew.Cooper3@citrix.com"; x-sender="postmaster@mail.citrix.com"; x-conformance=sidf_compatible IronPort-SDR: AlcqojCeUTjh6PAF6BWD6VPyV3g0TDNyBXThLQEihZDAqGATN5UZ2mW817K3ISJQaT3oKRqH/w zwFJBV4srnI6vaxa+s2VuDfj70y+h27+ViMtK8YOLn729XE1HuSQ1RWCdxhSvGW1eHqqfJ7axw YoWXk0tRaxj2nKRb/pg7Vx3Tzvgl2vHUhDdqk/CAVJbMF5XMHg+CCxKvN+gP61uf6jwQUhFU1E mKZeQdN0GCofvLAlgXfYdW2o1X/4EBfWtLOzWz7eIMJ5L4WI7ulZf2jU6O+7lNa6cKHLU98pXy MBo= X-SBRS: 2.7 X-MesageID: 3993816 X-Ironport-Server: esa2.hc3370-68.iphmx.com X-Remote-IP: 162.221.158.21 X-Policy: $RELAYED X-IronPort-AV: E=Sophos;i="5.64,358,1559534400"; d="scan'208";a="3993816" From: Andrew Cooper To: Xen-devel Date: Wed, 7 Aug 2019 20:41:43 +0100 Message-ID: <20190807194143.1351-1-andrew.cooper3@citrix.com> X-Mailer: git-send-email 2.11.0 MIME-Version: 1.0 Subject: [Xen-devel] [PATCH] docs/sphinx: Introduction X-BeenThere: xen-devel@lists.xenproject.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: Xen developer discussion List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Cc: Lars Kurth , Stefano Stabellini , Wei Liu , George Dunlap , Andrew Cooper , Julien Grall , Jan Beulich , Ian Jackson , =?UTF-8?q?Roger=20Pau=20Monn=C3=A9?= Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Errors-To: xen-devel-bounces@lists.xenproject.org Sender: "Xen-devel" 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: George Dunlap CC: Ian Jackson CC: Jan Beulich CC: Stefano Stabellini CC: Wei Liu CC: Julien Grall CC: Roger Pau Monn=C3=A9 CC: Lars Kurth A rendered version is visible here: https://andrewcoop-xen.readthedocs.io/en/docs-devel/admin-guide/introduct= ion.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 t= he 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 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 .. toctree:: + introduction microcode-loading diff --git a/docs/admin-guide/introduction.rst b/docs/admin-guide/introduct= ion.rst new file mode 100644 index 0000000000..ea960308ab --- /dev/null +++ b/docs/admin-guide/introduction.rst @@ -0,0 +1,38 @@ +Introduction +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Xen is an open source, bare metal hypervisor. It runs as the most privile= ged +piece of software, and shares the resources of the hardware between virtual +machines. + +In Xen terminology, there are :term:`domains`, commonly abbreviate= d 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 se= tup +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 high= er +level functionality is built. + +.. rubric:: Footnotes + +.. [1] A common misconception with Xen's architecture is that dom0 is some= how + 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 UART= s, + 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/xe= n-overview.drawio.svg new file mode 100644 index 0000000000..f120cdf77a --- /dev/null +++ b/docs/admin-guide/xen-overview.drawio.svg @@ -0,0 +1,97 @@ + + + + + + + + Xen + + + + Dom0 + + + + DomU + + + + DomU + + + + Hardware + + + + NIC + + + + Disk + + + + Systems Services + + + + Applications + + + + Applications + + + + Kernel + + + + Net + + + + Block + + + + Kernel + + + + Kernel + + + + Net + + + + Block + + + + Net + + + + Block + + + + + + + + + + + + + + + + + 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 +=3D=3D=3D=3D=3D=3D=3D=3D + +.. Terms should appear in alphabetical order + +.. glossary:: + + control domain + A :term:`domain`, commonly dom0, with the permission and responsibili= ty + 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/ =20 +Xen is an open source, bare metal hypervisor. It runs as the most privile= ged +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. =20 User documentation ------------------ @@ -45,3 +49,11 @@ kind of development environment. :maxdepth: 2 =20 hypervisor-guide/index + + +Miscellanea +----------- + +.. toctree:: + + glossary --=20 2.11.0 _______________________________________________ Xen-devel mailing list Xen-devel@lists.xenproject.org https://lists.xenproject.org/mailman/listinfo/xen-devel