vkernel{,64} - CPU topology support
[dragonfly.git] / share / man / man7 / vkernel.7
CommitLineData
4af18995 1.\"
98b2ba80 2.\" Copyright (c) 2006, 2007
4af18995
SW
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.\"
b96eeefd 32.Dd May 17, 2012
4af18995
SW
33.Dt VKERNEL 7
34.Os
35.Sh NAME
0592e24d 36.Nm vkernel ,
98b2ba80 37.Nm vcd ,
0592e24d
SW
38.Nm vkd ,
39.Nm vke
4af18995
SW
40.Nd virtual kernel architecture
41.Sh SYNOPSIS
b6a66df5
SW
42.Cd "platform vkernel # for 32 bit vkernels"
43.Cd "platform vkernel64 # for 64 bit vkernels"
98b2ba80 44.Cd "device vcd"
c8e7d028
SW
45.Cd "device vkd"
46.Cd "device vke"
47.Pp
1a92ebbb 48.Pa /var/vkernel/boot/kernel/kernel
278c4e67 49.Op Fl hsUv
a72d8a9f 50.Op Fl c Ar file
09b03fff 51.Op Fl e Ar name Ns = Ns Li value : Ns Ar name Ns = Ns Li value : Ns ...
dd54cb3a 52.Op Fl i Ar file
09b03fff 53.Op Fl I Ar interface Ns Op Ar :address1 Ns Oo Ar :address2 Oc Ns Oo Ar /netmask Oc
702acf06 54.Op Fl l Ar cpulock
4af18995 55.Op Fl m Ar size
9bea6114 56.Op Fl n Ar numcpus Ns Op Ar :lbits Ns Oo Ar :cbits Oc
bc3cc25e 57.Op Fl p Ar pidfile
4af18995 58.Op Fl r Ar file
4af18995
SW
59.Sh DESCRIPTION
60The
61.Nm
62architecture allows for running
63.Dx
64kernels in userland.
65.Pp
66The following options are available:
67.Bl -tag -width ".Fl m Ar size"
a72d8a9f 68.It Fl c Ar file
7834fbcc 69Specify a readonly CD-ROM image
a72d8a9f
MD
70.Ar file
71to be used by the kernel, with the first
72.Fl c
73option defining
74.Li vcd0 ,
75the second one
76.Li vcd1 ,
62aea38e
SW
77and so on.
78The first
a72d8a9f
MD
79.Fl r
80or
81.Fl c
82option specified on the command line will be the boot disk.
7834fbcc 83The CD9660 filesystem is assumed when booting from this media.
09b03fff
SW
84.It Fl e Ar name Ns = Ns Li value : Ns Ar name Ns = Ns Li value : Ns ...
85Specify an environment to be used by the kernel.
974f8ffe 86This option can be specified more than once.
278c4e67
SG
87.It Fl h
88Shows a list of available options, each with a short description.
dd54cb3a
SW
89.It Fl i Ar file
90Specify a memory image
91.Ar file
92to be used by the virtual kernel.
93If no
94.Fl i
95option is given, the kernel will generate a name of the form
96.Pa /var/vkernel/memimg.XXXXXX ,
97with the trailing
98.Ql X Ns s
99being replaced by a sequential number, e.g.\&
100.Pa memimg.000001 .
09b03fff
SW
101.It Fl I Ar interface Ns Op Ar :address1 Ns Oo Ar :address2 Oc Ns Oo Ar /netmask Oc
102Create a virtual network device, with the first
103.Fl I
104option defining
0592e24d 105.Li vke0 ,
09b03fff 106the second one
0592e24d 107.Li vke1 ,
09b03fff
SW
108and so on.
109.Pp
110The
111.Ar interface
112argument is the name of a
113.Xr tap 4
bc3cc25e
MD
114device node or the path to a
115.Xr vknetd 8
116socket.
09b03fff
SW
117The
118.Pa /dev/
bc3cc25e
MD
119path prefix does not have to be specified and will be automatically prepended
120for a device node.
09b03fff
SW
121Specifying
122.Cm auto
123will pick the first unused
124.Xr tap 4
125device.
126.Pp
127The
128.Ar address1
129and
130.Ar address2
131arguments are the IP addresses of the
132.Xr tap 4
133and
0592e24d 134.Nm vke
09b03fff
SW
135interfaces.
136Optionally,
137.Ar address1
138may be of the form
139.Li bridge Ns Em X
140in which case the
141.Xr tap 4
142interface is added to the specified
143.Xr bridge 4
144interface.
a8cc122d
SW
145The
146.Nm vke
147address is not assigned until the interface is brought up in the guest.
09b03fff
SW
148.Pp
149The
150.Ar netmask
151argument applies to all interfaces for which an address is specified.
bc3cc25e
MD
152.Pp
153When running multiple vkernels it is often more convenient to simply
154connect to a
155.Xr vknetd 8
156socket and let vknetd deal with the tap and/or bridge. An example of
157this would be '/var/run/vknet:0.0.0.0:10.2.0.2/16'.
702acf06
JT
158.It Fl l Ar cpulock
159Specify which, if any, real CPUs to lock virtual CPUs to.
160.Ar cpulock
161is one of
26ea2793
SW
162.Cm any ,
163.Cm map Ns Op Ns , Ns Ar startCPU ,
164or
165.Ar CPU .
702acf06
JT
166.Pp
167.Cm any
26ea2793
SW
168does not map virtual CPUs to real CPUs.
169This is the default.
702acf06
JT
170.Pp
171.Cm map Ns Op Ns , Ns Ar startCPU
172maps each virtual CPU to a real CPU starting with real CPU 0 or
173.Ar startCPU
174if specified.
175.Pp
176.Ar CPU
26ea2793
SW
177locks all virtual CPUs to the real CPU specified by
178.Ar CPU .
4af18995
SW
179.It Fl m Ar size
180Specify the amount of memory to be used by the kernel in bytes,
181.Cm K
3cea05a4 182.Pq kilobytes ,
4af18995 183.Cm M
3cea05a4
SW
184.Pq megabytes
185or
4af18995 186.Cm G
3cea05a4 187.Pq gigabytes .
09b03fff 188Lowercase versions of
4af18995
SW
189.Cm K , M ,
190and
191.Cm G
192are allowed.
9bea6114
MC
193.It Fl n Ar numcpus Ns Op Ar :lbits Ns Oo Ar :cbits Oc
194.Ar numcpus
195specifies the number of CPUs you wish to emulate.
43cfb771 196Up to 16 CPUs are supported.
8cf87c92
SW
197The virtual kernel must be built with
198.Cd options SMP
199to use this option and will default to 2 CPUs unless otherwise specified.
9bea6114
MC
200.Ar lbits
201specifies the number of bits within APICID(=CPUID) needed for representing
202the logical ID.
203Controls the number of threads/core (0bits - 1 thread, 1bit - 2 threads).
204This parameter is optional (mandatory only if
205.Ar cbits
206is specified).
207.Ar cbits
208specifies the number of bits within APICID(=CPUID) needed for representing
209the core ID.
210Controls the number of core/package (0bits - 1 core, 1bit - 2 cores).
211This parameter is optional.
bc3cc25e
MD
212.It Fl p Ar pidfile
213Specify a pidfile in which to store the process ID.
214Scripts can use this file to locate the vkernel pid for the purpose of
215shutting down or killing it.
216.Pp
217The vkernel will hold a lock on the pidfile while running.
218Scripts may test for the lock to determine if the pidfile is valid or
67cdc5a5 219stale so as to avoid accidentally killing a random process.
bc3cc25e
MD
220Something like '/usr/bin/lockf -ks -t 0 pidfile echo -n' may be used
221to test the lock.
222A non-zero exit code indicates that the pidfile represents a running
223vkernel.
224.Pp
225An error is issued and the vkernel exits if this file cannot be opened for
226writing or if it is already locked by an active vkernel process.
4af18995 227.It Fl r Ar file
a72d8a9f 228Specify a R/W disk image
4af18995 229.Ar file
ec1a8a4d
SW
230to be used by the kernel, with the first
231.Fl r
232option defining
0592e24d 233.Li vkd0 ,
ec1a8a4d 234the second one
0592e24d 235.Li vkd1 ,
62aea38e
SW
236and so on.
237The first
a72d8a9f
MD
238.Fl r
239or
240.Fl c
241option specified on the command line will be the boot disk.
c8e7d028
SW
242.It Fl s
243Boot into single-user mode.
03071031
SW
244.It Fl U
245Enable writing to kernel memory and module loading.
246By default, those are disabled for security reasons.
4af18995
SW
247.It Fl v
248Turn on verbose booting.
249.El
0592e24d
SW
250.Sh DEVICES
251A number of virtual device drivers exist to supplement the virtual kernel.
0592e24d
SW
252.Ss Disk device
253The
254.Nm vkd
255driver allows for up to 16
256.Xr vn 4
257based disk devices.
258The root device will be
259.Li vkd0
260(see
261.Sx EXAMPLES
262for further information on how to prepare a root image).
98b2ba80
SW
263.Ss CD-ROM device
264The
265.Nm vcd
266driver allows for up to 16 virtual CD-ROM devices.
267Basically this is a read only
268.Nm vkd
269device with a block size of 2048.
0592e24d
SW
270.Ss Network interface
271The
272.Nm vke
273driver supports up to 16 virtual network interfaces which are associated with
274.Xr tap 4
275devices on the host.
276For each
277.Nm vke
278device, the per-interface read only
279.Xr sysctl 3
280variable
281.Va hw.vke Ns Em X Ns Va .tap_unit
282holds the unit number of the associated
283.Xr tap 4
284device.
1e4d9fd9 285.Sh SIGNALS
dec8c72c 286The virtual kernel only enables
bb195a01 287.Dv SIGQUIT
dec8c72c
SW
288and
289.Dv SIGTERM
290while operating in regular console mode.
291Sending
1e4d9fd9
SW
292.Ql \&^\e
293.Pq Dv SIGQUIT
bb195a01 294to the virtual kernel causes the virtual kernel to enter its internal
1e4d9fd9 295.Xr ddb 4
dec8c72c 296debugger and re-enable all other terminal signals.
bb195a01 297Sending
dec8c72c
SW
298.Dv SIGTERM
299to the virtual kernel triggers a clean shutdown by passing a
300.Dv SIGUSR2
301to the virtual kernel's
bb195a01
MD
302.Xr init 8
303process.
974b26bf
SW
304.Sh DEBUGGING
305It is possible to directly gdb the virtual kernel's process.
306It is recommended that you do a
307.Ql handle SIGSEGV noprint
4010bf94 308to ignore page faults processed by the virtual kernel itself and
e7c2f376 309.Ql handle SIGUSR1 noprint
4010bf94
NT
310to ignore signals used for simulating inter-processor interrupts (SMP build
311only).
b96eeefd
SW
312.Sh PROFILING
313To compile a vkernel with profiling support, the
314.Va CONFIGARGS
315variable needs to be used to pass
316.Fl p
317to
318.Xr config 8 .
319.Bd -literal
320cd /usr/src
321make -DNO_MODULES CONFIGARGS=-p buildkernel KERNCONF=VKERNEL
322.Ed
a154d422
TN
323.Sh FILES
324.Bl -tag -width ".It Pa /sys/config/VKERNEL" -compact
325.It Pa /sys/config/VKERNEL
163fd4e7
AHJ
326.It Pa /sys/config/VKERNEL64
327.El
328.Pp
329Per architecture
a154d422 330.Nm
163fd4e7 331configuration files, for
a154d422 332.Xr config 8 .
a68e0df0
SW
333.Sh CONFIGURATION FILES
334Your virtual kernel is a complete
335.Dx
336system, but you might not want to run all the services a normal kernel runs.
337Here is what a typical virtual kernel's
338.Pa /etc/rc.conf
339file looks like, with some additional possibilities commented out.
340.Bd -literal
341hostname="vkernel"
342network_interfaces="lo0 vke0"
343ifconfig_vke0="DHCP"
344sendmail_enable="NO"
345#syslog_enable="NO"
346blanktime="NO"
347.Ed
163fd4e7
AHJ
348.Sh DISKLESS OPERATION
349To boot a
350.Nm
351from a NFS root, a number of tunables need to be set:
352.Bl -tag -width indent
353.It Va boot.netif.ip
354IP address to be set in the vkernel interface.
355.It Va boot.netif.netmask
356Netmask for the IP to be set.
357.It Va boot.netif.name
358Network interface name inside the vkernel.
359.It Va boot.nfsroot.server
360Host running
361.Xr nfsd 8 .
362.It Va boot.nfsroot.path
363Host path where a world and distribution
364targets are properly installed.
365.El
366.Pp
367See an example on how to boot a diskless
368.Nm
369in the
370.Sx EXAMPLES
371section.
c8e7d028 372.Sh EXAMPLES
4af18995
SW
373A couple of steps are necessary in order to prepare the system to build and
374run a virtual kernel.
375.Ss Setting up the filesystem
376The
377.Nm
378architecture needs a number of files which reside in
379.Pa /var/vkernel .
380Since these files tend to get rather big and the
381.Pa /var
382partition is usually of limited size, we recommend the directory to be
383created in the
384.Pa /home
385partition with a link to it in
386.Pa /var :
c8e7d028 387.Bd -literal
c009fcfa 388mkdir -p /home/var.vkernel/boot
4af18995
SW
389ln -s /home/var.vkernel /var/vkernel
390.Ed
391.Pp
392Next, a filesystem image to be used by the virtual kernel has to be
62aea38e
SW
393created and populated (assuming world has been built previously).
394If the image is created on a UFS filesystem you might want to pre-zero it.
49802d4e
MD
395On a HAMMER filesystem you should just truncate-extend to the image size
396as HAMMER does not re-use data blocks already present in the file.
c8e7d028 397.Bd -literal
f73862c5 398vnconfig -c -S 2g -T vn0 /var/vkernel/rootimg.01
58c55700 399disklabel -r -w vn0s0 auto
c009fcfa 400disklabel -e vn0s0 # add `a' partition with fstype `4.2BSD'
58c55700
SW
401newfs /dev/vn0s0a
402mount /dev/vn0s0a /mnt
c8e7d028
SW
403cd /usr/src
404make installworld DESTDIR=/mnt
405cd etc
406make distribution DESTDIR=/mnt
7a3238b8 407echo '/dev/vkd0s0a / ufs rw 1 1' >/mnt/etc/fstab
98b2ba80 408echo 'proc /proc procfs rw 0 0' >>/mnt/etc/fstab
7834fbcc
SW
409.Ed
410.Pp
411Edit
412.Pa /mnt/etc/ttys
413and replace the
414.Li console
415entry with the following line and turn off all other gettys.
416.Bd -literal
417console "/usr/libexec/getty Pc" cons25 on secure
418.Ed
419.Pp
eed435dd
SK
420Replace
421.Li \&Pc
422with
423.Li al.Pc
424if you would like to automatically log in as root.
425.Pp
7834fbcc
SW
426Then, unmount the disk.
427.Bd -literal
4af18995
SW
428umount /mnt
429vnconfig -u vn0
430.Ed
431.Ss Compiling the virtual kernel
432In order to compile a virtual kernel use the
433.Li VKERNEL
434kernel configuration file residing in
a154d422 435.Pa /sys/config
4af18995 436(or a configuration file derived thereof):
c8e7d028 437.Bd -literal
4af18995 438cd /usr/src
09b03fff 439make -DNO_MODULES buildkernel KERNCONF=VKERNEL
79b58aae 440make -DNO_MODULES installkernel KERNCONF=VKERNEL DESTDIR=/var/vkernel
4af18995
SW
441.Ed
442.Ss Enabling virtual kernel operation
443A special
444.Xr sysctl 8 ,
445.Va vm.vkernel_enable ,
446must be set to enable
447.Nm
448operation:
c8e7d028 449.Bd -literal
4af18995
SW
450sysctl vm.vkernel_enable=1
451.Ed
09b03fff
SW
452.Ss Configuring the network on the host system
453In order to access a network interface of the host system from the
454.Nm ,
455you must add the interface to a
456.Xr bridge 4
457device which will then be passed to the
458.Fl I
459option:
460.Bd -literal
461kldload if_bridge.ko
462kldload if_tap.ko
463ifconfig bridge0 create
464ifconfig bridge0 addm re0 # assuming re0 is the host's interface
465ifconfig bridge0 up
466.Ed
4af18995
SW
467.Ss Running the kernel
468Finally, the virtual kernel can be run:
c8e7d028 469.Bd -literal
79b58aae 470cd /var/vkernel
1a92ebbb 471\&./boot/kernel/kernel -m 64m -r rootimg.01 -I auto:bridge0
4af18995 472.Ed
c8e7d028 473.Pp
79b58aae
MD
474You can issue the
475.Xr reboot 8 ,
476.Xr halt 8 ,
477or
478.Xr shutdown 8
479commands from inside a virtual kernel.
480After doing a clean shutdown the
c8e7d028 481.Xr reboot 8
79b58aae
MD
482command will re-exec the virtual kernel binary while the other two will
483cause the virtual kernel to exit.
163fd4e7
AHJ
484.Ss Diskless operation
485Booting a
486.Nm
487with a
488.Xr vknetd 8
489network configuration:
490.Bd -literal
491\&./boot/kernel/kernel -m 64m -m -i memimg.0000 -I /var/run/vknet
492 -e boot.netif.ip=172.1.0.4
493 -e boot.netif.netmask=255.255.0.0
494 -e boot.netif.name=vke0
495 -e boot.nfsroot.server=172.1.0.1
496 -e boot.nfsroot.path=/home/vkernel/vkdiskless
497.Ed
34caba04
MD
498.Sh BUILDING THE WORLD UNDER A VKERNEL
499The virtual kernel platform does not have all the header files expected
500by a world build, so the easiest thing to do right now is to specify a
b6a66df5
SW
501pc32 (in a 32 bit vkernel) or pc64 (in a 64 bit vkernel) target when
502building the world under a virtual kernel, like this:
34caba04
MD
503.Bd -literal
504vkernel# make MACHINE_PLATFORM=pc32 buildworld
505vkernel# make MACHINE_PLATFORM=pc32 installworld
506.Ed
4af18995 507.Sh SEE ALSO
666855ca 508.Xr vknet 1 ,
09b03fff
SW
509.Xr bridge 4 ,
510.Xr tap 4 ,
c8e7d028 511.Xr vn 4 ,
a154d422 512.Xr sysctl.conf 5 ,
c8e7d028 513.Xr build 7 ,
b96eeefd 514.Xr config 8 ,
c8e7d028 515.Xr disklabel 8 ,
09b03fff 516.Xr ifconfig 8 ,
dbfd168b 517.Xr vknetd 8 ,
c8e7d028 518.Xr vnconfig 8
c203b6f9
SW
519.Rs
520.%A Aggelos Economopoulos
521.%D March 2007
522.%T "A Peek at the DragonFly Virtual Kernel"
523.Re
4af18995
SW
524.Sh HISTORY
525Virtual kernels were introduced in
526.Dx 1.7 .
527.Sh AUTHORS
528.An -nosplit
529.An Matt Dillon
530thought up and implemented the
531.Nm
0592e24d
SW
532architecture and wrote the
533.Nm vkd
534device driver.
535.An Sepherosa Ziehau
536wrote the
537.Nm vke
538device driver.
4af18995
SW
539This manual page was written by
540.An Sascha Wildner .