From eb2be5fc98b774413197830c7604114f3daa214a Mon Sep 17 00:00:00 2001
From: cl <cl@NetBSD.org>
Date: Thu, 13 May 2004 00:26:25 +0000
Subject: [PATCH] Add NetBSD/xen documentation.

---
 distrib/notes/common/contents    | 24 ++++++++++-
 distrib/notes/common/macros      | 10 ++++-
 distrib/notes/common/main        | 11 ++++-
 distrib/notes/common/postinstall |  9 ++--
 distrib/notes/xen/Makefile       |  3 +-
 distrib/notes/xen/hardware       | 55 +++++++++++++++++++++++++
 distrib/notes/xen/install        | 40 ++++++++++++++++++
 distrib/notes/xen/instopt        | 25 ++++++++++++
 distrib/notes/xen/legal          |  4 ++
 distrib/notes/xen/prep           | 70 ++++++++++++++++++++++++++++++++
 distrib/notes/xen/upgrade        |  7 +++-
 distrib/notes/xen/whatis         | 18 ++++++++
 distrib/notes/xen/xfer           | 34 ++++++++++++++++
 13 files changed, 297 insertions(+), 13 deletions(-)
 create mode 100644 distrib/notes/xen/instopt

diff --git a/distrib/notes/common/contents b/distrib/notes/common/contents
index 4401dcd19714..74a71a013bb9 100644
--- a/distrib/notes/common/contents
+++ b/distrib/notes/common/contents
@@ -1,4 +1,4 @@
-.\"	$NetBSD: contents,v 1.97 2004/01/17 05:30:01 lukem Exp $
+.\"	$NetBSD: contents,v 1.98 2004/05/13 00:26:25 cl Exp $
 .\"
 .\" Copyright (c) 1999-2002 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -283,7 +283,7 @@ Method), below.
 \*M miniroot file system image; see below.
 .\}
 .
-.if !\n[cats]:\n[evbppc]:\n[mvme68k]:\n[macppc]:\n[sgimips]:\n[sparc] \{\
+.if !\n[cats]:\n[evbppc]:\n[mvme68k]:\n[macppc]:\n[sgimips]:\n[sparc]:\n[xen] \{\
 .		It Pa misc/
 .
 .if \n[alpha] \{\
@@ -351,6 +351,16 @@ Two programs needed to boot \*M kernels over the network.
 Tape boot programs, and a RAMDISK kernel.
 .\}
 .
+.if \n[xen-i386] \{\
+.		It Pa xen12load/
+.		(tag xen12load.gz -compact
+.			It Pa xen12load.gz
+The kernel loader needed to boot
+.Nx*M
+as domain-0.
+.		tag)
+.\}
+.
 .	tag)
 .
 .tag)
@@ -499,6 +509,7 @@ everything described below.
 .if \n[sun3] .setsize 17 41
 .if \n[vax] .setsize 17 40
 .if \n[x68k] .setsize 17 41
+.if \n[xen-i386] .setsize 19 45
 .showsize
 .
 .It Sy comp
@@ -552,6 +563,7 @@ system call and library manual pages.
 .if \n[sun3] .setsize 14 52
 .if \n[vax] .setsize 12 45
 .if \n[x68k] .setsize 14 52
+.if \n[xen-i386] .setsize 15 54
 .showsize
 .
 .It Sy etc
@@ -587,6 +599,7 @@ This set includes the games and their manual pages.
 .if \n[sparc64] .setsize 3 8
 .if \n[vax] .setsize 3 7
 .if \n[x86_64] .setsize -unknown- -unknown-
+.if \n[xen-i386] .setsize 3 7
 .showsize
 .
 .\" Kernel set(s)
@@ -690,6 +703,9 @@ install this distribution set.
 .showsize 4 8
 .\}
 .el \{\
+.ie \n[xen] \{\
+.\}
+.el \{\
 .It Sy kern-GENERIC
 This set contains a
 .Nx*M
@@ -735,6 +751,7 @@ that your system may need to boot.
 .if \n[vax] .setsize 1 2
 .if \n[x68k] .setsize 1 2
 .showsize
+.\} \" !\n[xen]
 .\} \" !\n[evbppc]
 .\} \" !\n[sgimips]
 .\} \" !\n[mac68k]
@@ -782,6 +799,7 @@ all related programs, and their manual pages.
 .if \n[sparc64] .setsize 2 6
 .if \n[vax] .setsize 2 6
 .if \n[x86_64] .setsize -unknown- -unknown-
+.if \n[xen] .setsize 2 6
 .showsize
 .
 .tag)
@@ -831,6 +849,7 @@ This does not include the X servers.
 .if \n[sparc64] .setsize 3 9
 .if \n[vax] .setsize 3 7
 .if \n[x86_64] .setsize -unknown- -unknown-
+.if \n[xen-i386] .setsize 5 12
 .showsize
 .
 .It Sy xcomp
@@ -852,6 +871,7 @@ The extra libraries and include files needed to compile X source code.
 .if \n[sparc64] .setsize 2 10
 .if \n[vax] .setsize 2 8
 .if \n[x86_64] .setsize -unknown- -unknown-
+.if \n[xen-i386] .setsize 4 14
 .showsize
 .
 .It Sy xfont
diff --git a/distrib/notes/common/macros b/distrib/notes/common/macros
index 1207062b22ec..cf9ae3ef4b3c 100644
--- a/distrib/notes/common/macros
+++ b/distrib/notes/common/macros
@@ -1,4 +1,4 @@
-.\"	$NetBSD: macros,v 1.26 2004/02/24 15:05:53 wiz Exp $
+.\"	$NetBSD: macros,v 1.27 2004/05/13 00:26:25 cl Exp $
 .\"
 .\" Copyright (c) 1999-2002 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -396,11 +396,12 @@
 .
 .\" Supported MACHINE_ARCHs:
 .ds MACHINE_ARCH_LIST alpha arm hppa i386 m68000 m68k mipseb mipsel ns32k
-.as MACHINE_ARCH_LIST " powerpc sh3eb sh3el sparc sparc64 vax x86_64
+.as MACHINE_ARCH_LIST " powerpc sh3eb sh3el sparc sparc64 vax x86_64 xen
 .
 .\" Define registers for MACHINE_ARCHs with multiple or different MACHINEs
 .
 .ds A \*M
+.ds P \*M
 .if \n[acorn26]:\n[acorn32]:\n[cats]:\n[evbarm]:\n[hpcarm]:\n[netwinder]:\n[shark] .ds A arm
 .if \n[hp700] .ds A hppa
 .if \n[sun2] .ds A m68000
@@ -410,12 +411,17 @@
 .if \n[amigappc]:\n[bebox]:\n[evbppc]:\n[macppc]:\n[mvmeppc]:\n[ofppc]:\n[prep]:\n[sandpoint] .ds A powerpc
 .if \n[evbsh3]:\n[mmeye] .ds A sh3eb
 .if \n[dreamcast]:\n[hpcsh] .ds A sh3el
+.if \n[xen-i386] \{.ds A i386
+.ds P i386
+.nr xen 1
+.\}
 .if !r\*A .nr \*A 1
 .define_all \*[MACHINE_ARCH_LIST]
 .
 .\" Other strings available:
 .\"
 .\"	\*M		${MACHINE} (e.g., `i386')
+.\"	\*P		${MACHINE} for packages (e.g., `i386')
 .\"	\*A		${MACHINE_ARCH} (e.g., `m68k')
 .\"	\*V		Version (e.g., `1.5')
 .\"	\*[.CURDIR]	${.CURDIR}
diff --git a/distrib/notes/common/main b/distrib/notes/common/main
index 80f8f25ccdaf..1522ffc294d7 100644
--- a/distrib/notes/common/main
+++ b/distrib/notes/common/main
@@ -1,4 +1,4 @@
-.\"	$NetBSD: main,v 1.253 2004/02/06 07:47:10 minskim Exp $
+.\"	$NetBSD: main,v 1.254 2004/05/13 00:26:25 cl Exp $
 .\"
 .\" Copyright (c) 1999-2002 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -50,7 +50,7 @@
 .as MACHINE_LIST " mipsco mmeye mvme68k mvmeppc netwinder news68k newsmips
 .as MACHINE_LIST " next68k ofppc pc532 playstation2 pmax pmppc prep sandpoint
 .as MACHINE_LIST " sbmips sgimips shark sparc sparc64 sun2 sun3 vax 
-.as MACHINE_LIST " x68k x86_64 .
+.as MACHINE_LIST " x68k x86_64 xen .
 .so \*[.CURDIR]/../common/macros
 .
 .Dd September 7, 2002
@@ -1116,6 +1116,12 @@ own checksum files, just as the source distribution does.
 .so hardware -----------------------------------------------
 .br_ne 7P
 .
+.if \n[xen] \{.Ss "Installation options"
+.br_ne 7P
+.
+.so instopt -----------------------------------------------
+.\}
+.
 .Ss "Getting the NetBSD System on to Useful Media"
 .
 .so xfer -----------------------------------------------
@@ -1648,6 +1654,7 @@ If you're one of them, and would like to mentioned, tell us!)
 .It Ta S\(/oren J\(/orvang Ta Mt soren@NetBSD.org Ta Sy sgimips
 .It Ta Wayne Knowles Ta Mt wdk@NetBSD.org Ta Sy mipsco
 .It Ta Paul Kranenburg Ta Mt pk@NetBSD.org Ta Sy sparc
+.It Ta Christian Limpach Ta Mt cl@NetBSD.org Ta Sy xen
 .It Ta "Frank van der Linden" Ta Mt fvdl@NetBSD.org Ta Sy i386
 .It Ta "Frank van der Linden" Ta Mt fvdl@NetBSD.org Ta Sy amd64
 .It Ta Anders Magnusson Ta Mt ragge@NetBSD.org Ta Sy vax
diff --git a/distrib/notes/common/postinstall b/distrib/notes/common/postinstall
index 14136a764b3e..3a7940dfbe36 100644
--- a/distrib/notes/common/postinstall
+++ b/distrib/notes/common/postinstall
@@ -1,4 +1,4 @@
-.\"	$NetBSD: postinstall,v 1.54 2003/11/01 03:02:59 grant Exp $
+.\"	$NetBSD: postinstall,v 1.55 2004/05/13 00:26:25 cl Exp $
 .\"
 .\" Copyright (c) 1999-2002 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -189,6 +189,7 @@ For example:
 .if \n[mac68k]  .ds IFname sn0
 .if \n[macppc]  .ds IFname mc0
 .if \n[sgimips] .ds IFname sq0
+.if \n[xen]     .ds IFname xennet0
 .
 .Dl ifconfig_\*[IFname]="inet 123.45.67.89 netmask 255.255.255.0"
 .Pp
@@ -370,13 +371,13 @@ A list of available packages suitable for browsing is at
 Precompiled binaries can be found at
 .Lk ftp://ftp.NetBSD.org/pub/NetBSD/packages/ ,
 usually in the
-.Pa \*V/\*M/All
+.Pa \*V/\*P/All
 subdir.
 You can install them with the following commands under
 .Xr sh 1 :
 .Pp
 .Bd -unfilled
-.Ic # PKG_PATH=ftp://ftp.NetBSD.org/pub/NetBSD/packages/\*V/\*M/All
+.Ic # PKG_PATH=ftp://ftp.NetBSD.org/pub/NetBSD/packages/\*V/\*P/All
 .Ic # export PKG_PATH
 .Ic # pkg_add -v tcsh
 .Ic # pkg_add -v apache
@@ -389,7 +390,7 @@ If you are using
 then replace the first two lines with the following:
 .Pp
 .Bd -unfilled
-.Ic # setenv PKG_PATH ftp://ftp.NetBSD.org/pub/NetBSD/packages/\*V/\*M/All
+.Ic # setenv PKG_PATH ftp://ftp.NetBSD.org/pub/NetBSD/packages/\*V/\*P/All
 \&...
 .Ed
 .Pp
diff --git a/distrib/notes/xen/Makefile b/distrib/notes/xen/Makefile
index 2b2c563afc9a..dedf445509a0 100644
--- a/distrib/notes/xen/Makefile
+++ b/distrib/notes/xen/Makefile
@@ -1,8 +1,9 @@
-#	$NetBSD: Makefile,v 1.1 2004/05/12 16:56:41 cl Exp $
+#	$NetBSD: Makefile,v 1.2 2004/05/13 00:26:25 cl Exp $
 
 MACHINE:=	xen-${MACHINE}
 M=		${MACHINE}
 
+MERGED_SRCS+=	instopt
 MERGED_SRCS+=	${COMMON}/xfer
 
 .include <bsd.man.mk>
diff --git a/distrib/notes/xen/hardware b/distrib/notes/xen/hardware
index e69de29bb2d1..4f755b33d38c 100644
--- a/distrib/notes/xen/hardware
+++ b/distrib/notes/xen/hardware
@@ -0,0 +1,55 @@
+.\"	$NetBSD: hardware,v 1.2 2004/05/13 00:26:25 cl Exp $
+.
+.Nx*M
+runs on the Xen Virtual Machine Monitor (VMM) on 386-family processors.
+.
+Notable hardware requirements for running the Xen VMM are:
+.(bullet -offset indent
+a "P6" or newer processor
+.It
+a relatively modern network card like the Intel e1000, Broadcom BCM
+57xx, 3COM 3c905.
+Older cards are also supported but networking will not be fully
+efficient.
+.It
+at least 64 MB of RAM, preferably more when running multiple domains.
+The Xen VMM uses approximately 32 MB of RAM and each domain should
+have at least 12 MB of RAM.
+.bullet)
+.
+.Nx \*V
+runs on version 1.2 of the Xen VMM.
+.
+.Ss2 Supported devices
+.(bullet -offset indent
+.Te 2 "Block devices."
+.br
+Every hardware block device recognized by the Xen VMM is exported as a
+virtual block device to the virtual machines.
+Depending on the type of the actual hardware block device, the device
+is accessible as a wd, sd or cd device inside the
+.Nx*M -domain.
+.It
+.Te 2 "Network device."
+.br
+The Xen VMM exports a virtual network device to each domain.
+This device is accessible as a xennet0 device inside the
+.Nx*M -domain.
+.It
+.Te 2 "PS/2 keyboard and mouse."
+.br
+Access to a PS/2 keyboard and mouse is supported when
+.Nx*M
+runs as domain-0.
+.It
+.Te 2 "VGA display."
+.br
+Access to the VGA display is supported when
+.Nx*M
+runs as domain-0.
+.It
+.Te 2 "Virtual serial console."
+.br
+Output-only virtual serial consoles are supported.
+.bullet)
+.
diff --git a/distrib/notes/xen/install b/distrib/notes/xen/install
index e69de29bb2d1..84dcac29efab 100644
--- a/distrib/notes/xen/install
+++ b/distrib/notes/xen/install
@@ -0,0 +1,40 @@
+.\"	$NetBSD: install,v 1.2 2004/05/13 00:26:25 cl Exp $
+.
+.(tag instop
+.It Em "Domain-0 / privileged" installation
+Install grub to your disk by running the command:
+.br
+grub-install /dev/wd0d
+.Pp
+You should now be able to reboot your system to
+.Nx*M
+by selecting the
+.Em "Xen / NetBSD"
+entry in the grub boot menu.
+You might have to update your network configuration since the network
+interface has a different name.
+.
+.It Em "non-privileged" installation
+.(bullet
+Create a new or edit the existing domain tool config file for
+.Nx
+domains (/usr/pkg/etc/xc12/netbsd or /etc/xc/netbsd).
+.	(tag
+.It Pa
+add a vbd_list to define a virtual block device for the new domain:
+.br
+vbd_list = [ ('phy:wd0i','hda1','w') ]
+.br
+(replace wd0i with the partition containing the filesystem for the new
+domain)
+.It Pa
+comment out the cmdline_extra line
+.	tag)
+.It
+Now you can start the new domain with the following command:
+.br
+xc_dom_create.py -f netbsd -D 'vmid=1;ip=123.45.67.89' -m 32 -k /path/to/netbsd-GENERIC.gz
+.bullet)
+.
+.tag)
+.
diff --git a/distrib/notes/xen/instopt b/distrib/notes/xen/instopt
new file mode 100644
index 000000000000..826eaeb3635d
--- /dev/null
+++ b/distrib/notes/xen/instopt
@@ -0,0 +1,25 @@
+.\"	$NetBSD: instopt,v 1.1 2004/05/13 00:26:25 cl Exp $
+.
+There are two different installation procedures for
+.Nx*M .
+The first procedure is used when the
+.Nx*M
+installation will run as the privileged domain-0.
+The second procedure is used for preparing a
+.Nx*M
+installation to be run as a non-privileged domain.
+.
+.Pp
+For a privileged domain-0 installation, you have to first install
+.Nx /i386.
+The
+.Nx /i386
+distribution and installation instructions are available at
+.Lk ftp://ftp.NetBSD.org/pub/NetBSD/NetBSD-\*V/i386/
+.
+.Pp
+For a non-privileged installation, you have to first install Xen
+and another OS as domain-0, including the domain tools.  Refer to the
+Xen website at:
+.Lk http://www.cl.cam.ac.uk/Research/SRG/netos/xen/
+.
\ No newline at end of file
diff --git a/distrib/notes/xen/legal b/distrib/notes/xen/legal
index e69de29bb2d1..7322dab9fa2b 100644
--- a/distrib/notes/xen/legal
+++ b/distrib/notes/xen/legal
@@ -0,0 +1,4 @@
+.\"	$NetBSD: legal,v 1.2 2004/05/13 00:26:25 cl Exp $
+.
+.It
+This product includes software developed by Christian Limpach.
diff --git a/distrib/notes/xen/prep b/distrib/notes/xen/prep
index e69de29bb2d1..d1f2654bdb02 100644
--- a/distrib/notes/xen/prep
+++ b/distrib/notes/xen/prep
@@ -0,0 +1,70 @@
+.\"	$NetBSD: prep,v 1.2 2004/05/13 00:26:25 cl Exp $
+.
+.(tag instop
+.It Em "Domain-0 / privileged" installation
+Configure grub to boot the existing
+.Nx /i386
+installation and the new
+.Nx*M
+installation:
+.(bullet
+create the file /grub/menu.lst with the global options like:
+.	(tag
+.It Pa
+default 0
+.br 
+timeout 5
+.br 
+root (hd0,3,a)
+.	tag)
+.It
+add entries to boot
+.Nx /i386 :
+.	(tag
+.It Pa
+title NetBSD
+.br
+kernel -- type=netbsd /netbsd
+.It Pa
+title NetBSD via chain
+.br
+rootnoverrify (hd0,3)
+.br
+chainloader +1
+.br
+boot
+.	tag)
+.It
+add an entry to boot
+.Nx*M :
+.	(tag
+.It Pa
+title Xen / NetBSD
+.br
+kernel /grub/xen-1.2.gz dom0_mem=65536
+.br
+module /grub/xen12load.gz
+.br
+module /grub/netbsd-GENERIC.gz
+.	tag)
+.bullet)
+.Pp
+Note: The example configuration above assumes that the
+.Nx /i386
+installation is on partition wd0a and the
+.Nx
+slice is the third fdisk partition.  Refer to the grub documentation if
+your installation is different.
+.
+.It Em "non-privileged" installation
+.(bullet
+Create a new partition which will be the root filesystem for the new
+installation and mount the newly created partition.
+.It
+Extract the sets you want installed to the newly created partition.
+.It
+Copy the netbsd-GENERIC.gz kernel from the distribution into domain-0's
+filesystem.
+.bullet)
+.tag)
+.
diff --git a/distrib/notes/xen/upgrade b/distrib/notes/xen/upgrade
index 04a3a8587fb4..a90d488b71fe 100644
--- a/distrib/notes/xen/upgrade
+++ b/distrib/notes/xen/upgrade
@@ -1,2 +1,5 @@
-This is the 1st release of
-.Nx*M .
+.\"	$NetBSD: upgrade,v 1.2 2004/05/13 00:26:25 cl Exp $
+.
+A formal upgrade procedure for
+.Nx*M
+hasn't been documented yet.
diff --git a/distrib/notes/xen/whatis b/distrib/notes/xen/whatis
index e69de29bb2d1..187c1e208c52 100644
--- a/distrib/notes/xen/whatis
+++ b/distrib/notes/xen/whatis
@@ -0,0 +1,18 @@
+.\"	$NetBSD: whatis,v 1.2 2004/05/13 00:26:25 cl Exp $
+.
+This is the first major release of
+.Nx*M .
+.Pp
+Some (but not all!) notable features include:
+.(bullet
+Network driver
+.It
+Block device driver
+.It
+Support for domain-0 operations (creation and control of other domains).
+.It
+VGA output and PS/2 keyboard/mouse in domain-0
+.It
+X Window System in domain-0
+.bullet)
+.Pp
diff --git a/distrib/notes/xen/xfer b/distrib/notes/xen/xfer
index e69de29bb2d1..4707c329c473 100644
--- a/distrib/notes/xen/xfer
+++ b/distrib/notes/xen/xfer
@@ -0,0 +1,34 @@
+.\"	$NetBSD: xfer,v 1.2 2004/05/13 00:26:25 cl Exp $
+.
+.(tag instop
+.It Em "Domain-0 / privileged" installation
+On the already installed
+.Nx /i386
+system:
+.(bullet
+install the grub bootloader from pkgsrc (see Installing third
+party packages in the
+.Nx /i386
+installation notes).
+.It
+download the Xen binary from:
+.Lk ftp://ftp.NetBSD.org/pub/NetBSD/arch/xen/misc/xen-1.2-fixed.gz .
+.It
+get a copy of the xen12load kernel loader from the
+.Nx \*V
+release.
+.It
+optionally install the xentools12 package from pkgsrc, if you want to
+create non-privileged domains later.
+.bullet)
+.
+.It Em "non-privileged" installation
+Download the
+.Nx*M
+binary distribution sets to the machine where you have installed Xen
+or have the
+.Nx*M
+binary distribution sets accessible over the network.
+.
+.tag)
+.