Add a vkernel(7) manpage which I hacked together from Matt's comments.
[dragonfly.git] / share / man / man7 / vkernel.7
CommitLineData
4af18995
SW
1.\"
2.\" Copyright (c) 2003, 2004, 2005, 2006, 2007
3.\" The DragonFly Project. All rights reserved.
4.\"
5.\" Redistribution and use in source and binary forms, with or without
6.\" modification, are permitted provided that the following conditions
7.\" are met:
8.\"
9.\" 1. Redistributions of source code must retain the above copyright
10.\" notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\" notice, this list of conditions and the following disclaimer in
13.\" the documentation and/or other materials provided with the
14.\" distribution.
15.\" 3. Neither the name of The DragonFly Project nor the names of its
16.\" contributors may be used to endorse or promote products derived
17.\" from this software without specific, prior written permission.
18.\"
19.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
22.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
23.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
24.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
25.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
26.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
27.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
28.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
29.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\" $DragonFly: src/share/man/man7/vkernel.7,v 1.1 2007/01/08 08:55:44 swildner Exp $
33.\"
34.Dd January 8, 2007
35.Dt VKERNEL 7
36.Os
37.Sh NAME
38.Nm vkernel
39.Nd virtual kernel architecture
40.Sh SYNOPSIS
41.Pa /usr/obj/usr/src/sys/VKERNEL/kernel.debug
42.Op Fl e Ar environment
43.\".Op Fl i Ar file
44.Op Fl m Ar size
45.Op Fl r Ar file
46.Op Fl v
47.Sh DESCRIPTION
48The
49.Nm
50architecture allows for running
51.Dx
52kernels in userland.
53.Pp
54The following options are available:
55.Bl -tag -width ".Fl m Ar size"
56.It Fl e Ar environment
57Specify an to be used by the kernel.
58The
59.Ar environment
60argument is a string of the form
61.Li name=value:name=value:...
62.\".It Fl i Ar file
63.\"Specify a memory image
64.\".Ar file
65.\"to be used by the kernel.
66.It Fl m Ar size
67Specify the amount of memory to be used by the kernel in bytes,
68.Cm K
69(kilobytes),
70.Cm M
71(megabytes) or
72.Cm G
73(gigabytes).
74Lowercase version of
75.Cm K , M ,
76and
77.Cm G
78are allowed.
79.It Fl r Ar file
80Specify the root image
81.Ar file
82to be used by the kernel.
83See
84.Sx CONFIGURING AND RUNNING VIRTUAL KERNELS
85for further information on how to prepare a root image.
86.It Fl v
87Turn on verbose booting.
88.El
89.Sh CONFIGURING AND RUNNING VIRTUAL KERNELS
90A couple of steps are necessary in order to prepare the system to build and
91run a virtual kernel.
92.Ss Setting up the filesystem
93The
94.Nm
95architecture needs a number of files which reside in
96.Pa /var/vkernel .
97Since these files tend to get rather big and the
98.Pa /var
99partition is usually of limited size, we recommend the directory to be
100created in the
101.Pa /home
102partition with a link to it in
103.Pa /var :
104.Bd -literal -offset indent
105mkdir /home/var.vkernel
106ln -s /home/var.vkernel /var/vkernel
107.Ed
108.Pp
109Next, a filesystem image to be used by the virtual kernel has to be
110created:
111.Bd -literal -offset indent
112dd if=/dev/zero of=/var/vkernel/rootimg.01 bs=1m count=2048
113vnconfig -c -s labels vn0 /var/vkernel/rootimg.01
114disklabel -r -w vn0 auto
115(edit the label to create a vn0a partition)
116newfs /dev/vn0a
117mount /dev/vn0a /mnt
118cpdup / /mnt
119umount /mnt
120vnconfig -u vn0
121.Ed
122.Ss Compiling the virtual kernel
123In order to compile a virtual kernel use the
124.Li VKERNEL
125kernel configuration file residing in
126.Pa /usr/src/sys/config
127(or a configuration file derived thereof):
128.Bd -literal -offset indent
129cd /usr/src
130make buildkernel KERNCONF=VKERNEL
131.Ed
132.Ss Enabling virtual kernel operation
133A special
134.Xr sysctl 8 ,
135.Va vm.vkernel_enable ,
136must be set to enable
137.Nm
138operation:
139.Bd -literal -offset indent
140sysctl vm.vkernel_enable=1
141.Ed
142.Ss Running the kernel
143Finally, the virtual kernel can be run:
144.Bd -literal -offset indent
145cd /usr/obj/usr/src/sys/VKERNEL
146\&./kernel.debug -m 64m -r /var/vkernel/rootimg.01
147.Ed
148.Sh SEE ALSO
149.Xr build 7
150.Sh HISTORY
151Virtual kernels were introduced in
152.Dx 1.7 .
153.Sh AUTHORS
154.An -nosplit
155.An Matt Dillon
156thought up and implemented the
157.Nm
158architecture.
159This manual page was written by
160.An Sascha Wildner .
161.Sh BUGS
162Virtual kernels are not yet fully operational.