1081 lines
36 KiB
Groff
1081 lines
36 KiB
Groff
.\"Document Author: Timothy R. Butler - tbutler@uninetsolutions.com"
|
|
.TH bochsrc 5 "31 Jul 2011" "bochsrc" "The Bochs Project"
|
|
.\"SKIP_SECTION"
|
|
.SH NAME
|
|
bochsrc \- Configuration file for Bochs.
|
|
.\"SKIP_SECTION"
|
|
.SH DESCRIPTION
|
|
.LP
|
|
Bochsrc is the configuration file that specifies
|
|
where Bochs should look for disk images, how the Bochs
|
|
emulation layer should work, etc. The syntax used
|
|
for bochsrc can also be used as command line arguments
|
|
for Bochs. The .bochsrc file should be placed either in
|
|
the current directory before running Bochs or in your
|
|
home directory.
|
|
|
|
Starting with Bochs 1.3, you can use environment variables in
|
|
the bochsrc file, for example:
|
|
|
|
floppya: 1_44="$IMAGES/bootdisk.img", status=inserted
|
|
|
|
Starting with version 2.0, two environment variables have a built-in
|
|
default value which is set at compile time. $BXSHARE points to the
|
|
"share" directory which is typically /usr/local/share/bochs on UNIX
|
|
machines. See the $(sharedir) variable in the Makefile for the exact
|
|
value. $BXSHARE is used by disk images to locate the directory where
|
|
the BIOS images and keymaps can be found. If $BXSHARE is not defined, Bochs
|
|
will supply the default value. Also, $LTDL_LIBRARY_PATH points to a list of
|
|
directories (separated by colons if more than one) to search in for Bochs
|
|
plugins. A compile-time default is provided if this variable is not defined
|
|
by the user.
|
|
.\".\"DONT_SPLIT"
|
|
.SH OPTIONS
|
|
|
|
.TP
|
|
.I "#include"
|
|
This option includes another configuration file. It is
|
|
possible to put installation defaults in a global config
|
|
file (e.g. location of rom images).
|
|
|
|
Example:
|
|
#include /etc/bochsrc
|
|
|
|
.TP
|
|
.I "config_interface:"
|
|
The configuration interface is a series of menus or dialog boxes that
|
|
allows you to change all the settings that control Bochs's behavior.
|
|
Depending on the platform there are up to 3 choices of configuration
|
|
interface: a text mode version called "textconfig" and two graphical versions
|
|
called "win32config" and "wx". The text mode version uses stdin/stdout and
|
|
is always compiled in, unless Bochs is compiled for wx only. The choice
|
|
"win32config" is only available on win32 and it is the default there.
|
|
The choice "wx" is only available when you use "--with-wx" on the configure
|
|
command. If you do not write a config_interface line, Bochs will
|
|
choose a default for you.
|
|
|
|
.B NOTE:
|
|
if you use the "wx" configuration interface, you must also use
|
|
the "wx" display library.
|
|
|
|
Example:
|
|
config_interface: textconfig
|
|
|
|
.TP
|
|
.I "display_library:"
|
|
The display library is the code that displays the Bochs VGA screen. Bochs
|
|
has a selection of about 10 different display library implementations for
|
|
different platforms. If you run configure with multiple --with-* options,
|
|
the display_library command lets you choose which one you want to run with.
|
|
If you do not write a display_library line, Bochs will choose a default for
|
|
you.
|
|
|
|
The choices are:
|
|
x X windows interface, cross platform
|
|
win32 native win32 libraries
|
|
carbon Carbon library (for MacOS X)
|
|
macintosh MacOS pre-10
|
|
amigaos native AmigaOS libraries
|
|
sdl SDL library, cross platform
|
|
term text only, uses curses/ncurses library, cross platform
|
|
rfb provides an interface to AT&T's VNC viewer, cross platform
|
|
wx wxWidgets library, cross platform
|
|
nogui no display at all
|
|
|
|
Some display libraries now support specific option to control their
|
|
behaviour. See the examples below for currently supported options.
|
|
|
|
.B NOTE:
|
|
if you use the "wx" configuration interface, you must also use
|
|
the "wx" display library.
|
|
|
|
Examples:
|
|
display_library: x
|
|
display_library: rfb, options="timeout=60" # time to wait for client
|
|
display_library: sdl, options="fullscreen" # startup in fullscreen mode
|
|
display_library: x, options="hideIPS" # disable IPS output in status bar
|
|
display_library: x, options="gui_debug" # use GTK debugger gui
|
|
|
|
|
|
.TP
|
|
.I "romimage:"
|
|
The ROM BIOS controls what the PC does when it first powers on. Normally, you
|
|
can use a precompiled BIOS in the source or binary distribution called
|
|
.B BIOS-bochs-latest.
|
|
The default ROM BIOS is usually loaded starting at address 0xe0000, and it is
|
|
exactly 128k long. The legacy version of the Bochs BIOS is usually loaded starting
|
|
at address 0xf0000, and it is exactly 64k long.
|
|
You can also use the environment variable $BXSHARE to specify the location of the BIOS.
|
|
The usage of external large BIOS images (up to 512k) at memory top is
|
|
now supported, but we still recommend to use the BIOS distributed with Bochs.
|
|
The start address is optional, since it can be calculated from image size.
|
|
|
|
Examples:
|
|
romimage: file=bios/BIOS-bochs-latest
|
|
romimage: file=$BXSHARE/BIOS-bochs-legacy
|
|
romimage: file=mybios.bin, address=0xfff80000
|
|
romimage: file=mybios.bin
|
|
|
|
.TP
|
|
.I "cpu:"
|
|
This defines cpu-related parameters inside Bochs:
|
|
|
|
count:
|
|
|
|
Set the number of processors:cores per processor:threads per core when
|
|
Bochs is compiled for SMP emulation. Bochs currently supports up to
|
|
8 processors. If Bochs is compiled without SMP support, it won't accept
|
|
values different from 1.
|
|
|
|
quantum:
|
|
|
|
Maximum amount of instructions allowed to execute by processor before
|
|
returning control to another cpu. This option exists only in Bochs
|
|
binary compiled with SMP support.
|
|
|
|
reset_on_triple_fault:
|
|
|
|
Reset the CPU when triple fault occur (highly recommended) rather than
|
|
PANIC. Remember that if you trying to continue after triple fault the
|
|
simulation will be completely bogus !
|
|
|
|
cpuid_limit_winnt:
|
|
|
|
Determine whether to limit maximum CPUID function to 2. This mode is
|
|
required to workaround WinNT installation and boot issues.
|
|
|
|
msrs:
|
|
|
|
Define path to user CPU Model Specific Registers (MSRs) specification.
|
|
See example in msrs.def.
|
|
|
|
ignore_bad_msrs:
|
|
|
|
Ignore MSR references that Bochs does not understand; print a warning
|
|
message instead of generating #GP exception. This option is enabled
|
|
by default but will not be avaiable if configurable MSRs are enabled.
|
|
|
|
ips:
|
|
|
|
Emulated Instructions Per Second. This is the
|
|
number of IPS that Bochs is capable of running
|
|
on your machine. You can recompile Bochs with
|
|
--enable-show-ips option enabled, to find your
|
|
workstation's capability. Measured IPS value
|
|
will then be logged into your log file or status
|
|
bar (if supported by the gui).
|
|
|
|
IPS is used to calibrate many time-dependent
|
|
events within the bochs simulation. For
|
|
example, changing IPS affects the frequency of
|
|
VGA updates, the duration of time before a key
|
|
starts to autorepeat, and the measurement of
|
|
BogoMips and other benchmarks.
|
|
|
|
Example Specifications[1]
|
|
Bochs Machine/Compiler Mips
|
|
--------------------------------------------------------------------
|
|
2.4.6 3.4Ghz Intel Core i7 2600 with Win7x64/g++ 4.5.2 85 to 95 Mips
|
|
2.3.7 3.2Ghz Intel Core 2 Q9770 with WinXP/g++ 3.4 50 to 55 Mips
|
|
2.3.7 2.6Ghz Intel Core 2 Duo with WinXP/g++ 3.4 38 to 43 Mips
|
|
2.2.6 2.6Ghz Intel Core 2 Duo with WinXP/g++ 3.4 21 to 25 Mips
|
|
2.2.6 2.1Ghz Athlon XP with Linux 2.6/g++ 3.4 12 to 15 Mips
|
|
|
|
[1] IPS measurements depend on OS and compiler
|
|
configuration in addition to processor clock
|
|
speed.
|
|
|
|
Example:
|
|
cpu: count=2, ips=10000000, msrs="msrs.def"
|
|
|
|
.TP
|
|
.I "cpuid:"
|
|
This defines features and functionality supported by Bochs emulated CPU:
|
|
|
|
mmx:
|
|
|
|
Select MMX instruction set support.
|
|
This option exists only if Bochs compiled with BX_CPU_LEVEL >= 5.
|
|
|
|
apic:
|
|
|
|
Select APIC configuration (LEGACY/XAPIC/X2APIC).
|
|
This option exists only if Bochs compiled with BX_CPU_LEVEL >= 5.
|
|
|
|
sep:
|
|
|
|
Select SYSENTER/SYSEXIT instruction set support.
|
|
This option exists only if Bochs compiled with BX_CPU_LEVEL >= 6.
|
|
|
|
sse:
|
|
|
|
Select SSE instruction set support.
|
|
Any of NONE/SSE/SSE2/SSE3/SSSE3/SSE4_1/SSE4_2 could be selected.
|
|
This option exists only if Bochs compiled with BX_CPU_LEVEL >= 6.
|
|
|
|
sse4a:
|
|
|
|
Select AMD SSE4A instructions support.
|
|
This option exists only if Bochs compiled with BX_CPU_LEVEL >= 6.
|
|
|
|
aes:
|
|
|
|
Select AES instruction set support.
|
|
This option exists only if Bochs compiled with BX_CPU_LEVEL >= 6.
|
|
|
|
movbe:
|
|
|
|
Select MOVBE Intel(R) Atom instruction support.
|
|
This option exists only if Bochs compiled with BX_CPU_LEVEL >= 6.
|
|
|
|
xsave:
|
|
|
|
Select XSAVE extensions support.
|
|
This option exists only if Bochs compiled with BX_CPU_LEVEL >= 6.
|
|
|
|
xsaveopt:
|
|
|
|
Select XSAVEOPT instruction support.
|
|
This option exists only if Bochs compiled with BX_CPU_LEVEL >= 6.
|
|
|
|
avx:
|
|
|
|
Select AVX/AVX2 instruction set support.
|
|
This option exists only if Bochs compiled with --enable-avx option.
|
|
|
|
avx_f16c:
|
|
|
|
Select AVX float16 convert instructions support.
|
|
This option exists only if Bochs compiled with --enable-avx option.
|
|
|
|
bmi:
|
|
|
|
Select BMI1/BMI2 instructions support.
|
|
This option exists only if Bochs compiled with --enable-avx option.
|
|
|
|
1g_pages:
|
|
|
|
Enable 1G page size support in long mode.
|
|
This option exists only if Bochs compiled with x86-64 support.
|
|
|
|
pcid:
|
|
|
|
Enable Process-Context Identifiers (PCID) support in long mode.
|
|
This option exists only if Bochs compiled with x86-64 support.
|
|
|
|
smep:
|
|
|
|
Enable Supervisor Mode Execution Protection (SMEP) support.
|
|
This option exists only if Bochs compiled with BX_CPU_LEVEL >= 6.
|
|
|
|
mwait:
|
|
|
|
Select MONITOR/MWAIT instructions support.
|
|
This option exists only if Bochs compiled with --enable-monitor-mwait.
|
|
|
|
mwait_is_nop:
|
|
|
|
When this option is enabled MWAIT will not put the CPU into a sleep state.
|
|
This option exists only if Bochs compiled with --enable-monitor-mwait.
|
|
|
|
family:
|
|
|
|
Set family information returned by CPUID. Default family value determined
|
|
by configure option --enable-cpu-level.
|
|
|
|
model:
|
|
|
|
Set model information returned by CPUID. Default model value is 3.
|
|
|
|
stepping:
|
|
|
|
Set stepping information returned by CPUID. Default stepping value is 3.
|
|
|
|
vendor_string:
|
|
|
|
Set the CPUID vendor string returned by CPUID(0x0). This should be a
|
|
twelve-character ASCII string.
|
|
|
|
brand_string:
|
|
|
|
Set the CPUID vendor string returned by CPUID(0x80000002 .. 0x80000004).
|
|
This should be at most a forty-eight-character ASCII string.
|
|
|
|
Example:
|
|
cpuid: mmx=1, sep=1, sse=sse4_2, xapic=1, aes=1, movbe=1, xsave=1
|
|
|
|
.TP
|
|
.I "megs:"
|
|
Set the number of Megabytes of physical memory you want to emulate.
|
|
The default is 32MB, most OS's won't need more than that.
|
|
The maximum amount of memory supported is 2048Mb.
|
|
|
|
Example:
|
|
megs: 32
|
|
|
|
.TP
|
|
.I "optromimage1: \fP, \fIoptromimage2: \fP, \fIoptromimage3: \fPor \fIoptromimage4:"
|
|
You may now load up to 4 optional ROM images. Be sure to use a
|
|
read-only area, typically between C8000 and EFFFF. These optional
|
|
ROM images should not overwrite the rombios (located at
|
|
F0000-FFFFF) and the videobios (located at C0000-C7FFF).
|
|
Those ROM images will be initialized by the bios if they contain
|
|
the right signature (0x55AA).
|
|
It can also be a convenient way to upload some arbitrary code/data
|
|
in the simulation, that can be retrieved by the boot loader
|
|
|
|
Example:
|
|
optromimage1: file=optionalrom.bin, address=0xd0000
|
|
|
|
.TP
|
|
.I "vgaromimage:"
|
|
You also need to load a VGA ROM BIOS into 0xC0000.
|
|
|
|
Examples:
|
|
vgaromimage: file=bios/VGABIOS-elpin-2.40
|
|
vgaromimage: file=bios/VGABIOS-lgpl-latest
|
|
vgaromimage: file=$BXSHARE/VGABIOS-lgpl-latest
|
|
|
|
.TP
|
|
.I "vga:"
|
|
Here you can specify the display extension to be used. With the value 'none'
|
|
you can use standard VGA with no extension. Other supported values are 'vbe'
|
|
for Bochs VBE and 'cirrus' for Cirrus SVGA support.
|
|
|
|
Examples:
|
|
vga: extension=cirrus
|
|
vga: extension=vbe
|
|
|
|
.TP
|
|
.I "floppya: \fPor \fIfloppyb:"
|
|
|
|
Point this to the pathname of a floppy image
|
|
file or device. Floppya is the first drive,
|
|
and floppyb is the second drive. If you're
|
|
booting from a floppy, floppya should point to
|
|
a bootable disk.
|
|
|
|
You can set the initial status of the media to
|
|
\&'ejected' or 'inserted'. Usually you will want
|
|
to use 'inserted'.
|
|
|
|
The parameter 'type' can be used to enable the floppy drive without media
|
|
and status specified. Usually the drive type is set up based on the media type.
|
|
|
|
The optional parameter 'write_protected' can be used to control the media
|
|
write protect switch. By default it is turned off.
|
|
|
|
Example:
|
|
|
|
2.88M 3.5" media:
|
|
floppya: 2_88=path, status=ejected
|
|
|
|
1.44M 3.5" media (write protected):
|
|
floppya: 1_44=path, status=inserted, write_protected=1
|
|
|
|
1.2M 5.25" media:
|
|
floppyb: 1_2=path, status=ejected
|
|
|
|
720K 3.5" media:
|
|
floppya: 720k=path, status=inserted
|
|
|
|
360K 5.25" media:
|
|
floppya: 360k=path, status=inserted
|
|
|
|
Autodetect floppy media type:
|
|
floppya: image=path, status=inserted
|
|
|
|
Use directory as 1.44M VFAT media:
|
|
floppya: 1_44=vvfat:path, status=inserted
|
|
|
|
1.44M 3.5" floppy drive, no media:
|
|
floppya: type=1_44
|
|
|
|
.TP
|
|
.I "ata0: \fP, \fIata1: \fP, \fIata2: \fPor \fIata3:"
|
|
|
|
These options enables up to 4 ata channels. For each channel
|
|
the two base io addresses and the irq must be specified.
|
|
ata0 and ata1 are enabled by default, with the values shown below.
|
|
|
|
Examples:
|
|
ata0: enabled=1, ioaddr1=0x1f0, ioaddr2=0x3f0, irq=14
|
|
ata1: enabled=1, ioaddr1=0x170, ioaddr2=0x370, irq=15
|
|
ata2: enabled=1, ioaddr1=0x1e8, ioaddr2=0x3e0, irq=11
|
|
ata3: enabled=1, ioaddr1=0x168, ioaddr2=0x360, irq=9
|
|
|
|
.TP
|
|
.I "ata\fR[\fB0-3\fR]\fI-master: \fPor \fIata\fR[\fB0-3\fR]\fI-slave:"
|
|
|
|
This defines the type and characteristics of all attached ata devices:
|
|
type= type of attached device [disk|cdrom]
|
|
path= path of the image
|
|
mode= image mode [flat|concat|external|dll|sparse|vmware3|undoable|growing|volatile], only valid for disks
|
|
cylinders= only valid for disks
|
|
heads= only valid for disks
|
|
spt= only valid for disks
|
|
status= only valid for cdroms [inserted|ejected]
|
|
biosdetect= type of biosdetection [none|auto], only for disks on ata0 [cmos]
|
|
translation=type of translation of the bios, only for disks [none|lba|large|rechs|auto]
|
|
model= string returned by identify device command
|
|
journal= optional filename of the redolog for undoable, volatile and vvfat disks
|
|
|
|
Point this at a hard disk image file, cdrom iso file,
|
|
or a physical cdrom device.
|
|
To create a hard disk image, try running bximage.
|
|
It will help you choose the size and then suggest a line that
|
|
works with it.
|
|
|
|
In UNIX it is possible to use a raw device as a Bochs hard disk,
|
|
but WE DON'T RECOMMEND IT.
|
|
|
|
The path is mandatory for hard disks. Disk geometry autodetection works with
|
|
images created by bximage if CHS is set to 0/0/0 (cylinders are calculated
|
|
using heads=16 and spt=63). For other hard disk images and modes the
|
|
cylinders, heads, and spt are mandatory. In all cases the disk size reported
|
|
from the image must be exactly C*H*S*512.
|
|
|
|
The mode option defines how the disk image is handled. Disks can be defined as:
|
|
- flat : one file flat layout
|
|
- concat : multiple files layout
|
|
- external : developer's specific, through a C++ class
|
|
- dll : developer's specific, through a DLL
|
|
- sparse : stackable, commitable, rollbackable
|
|
- vmware3 : vmware3 disk support
|
|
- undoable : flat file with commitable redolog
|
|
- growing : growing file
|
|
- volatile : flat file with volatile redolog
|
|
- vvfat: local directory appears as read-only VFAT disk (with volatile redolog)
|
|
|
|
The disk translation scheme (implemented in legacy int13 bios functions, and used by
|
|
older operating systems like MS-DOS), can be defined as:
|
|
- none : no translation, for disks up to 528MB (1032192 sectors)
|
|
- large : a standard bitshift algorithm, for disks up to 4.2GB (8257536 sectors)
|
|
- rechs : a revised bitshift algorithm, using a 15 heads fake physical geometry, for disks up to 7.9GB (15482880 sectors). (don't use this unless you understand what you're doing)
|
|
- lba : a standard lba-assisted algorithm, for disks up to 8.4GB (16450560 sectors)
|
|
- auto : autoselection of best translation scheme. (it should be changed if system does not boot)
|
|
|
|
Default values are:
|
|
mode=flat, biosdetect=auto, translation=auto, model="Generic 1234"
|
|
|
|
The biosdetect option has currently no effect on the bios
|
|
|
|
Examples:
|
|
ata0-master: type=disk, path=10M.sample, cylinders=306, heads=4, spt=17
|
|
ata0-slave: type=disk, path=20M.sample, cylinders=615, heads=4, spt=17
|
|
ata1-master: type=disk, path=30M.sample, cylinders=615, heads=6, spt=17
|
|
ata1-slave: type=disk, path=46M.sample, cylinders=940, heads=6, spt=17
|
|
ata2-master: type=disk, path=62M.sample, cylinders=940, heads=8, spt=17
|
|
ata2-slave: type=disk, path=112M.sample, cylinders=900, heads=15, spt=17
|
|
ata3-master: type=disk, path=483M.sample, cylinders=1024, heads=15, spt=63
|
|
ata3-slave: type=cdrom, path=iso.sample, status=inserted
|
|
|
|
.TP
|
|
.I "com1: \fP, \fIcom2: \fP, \fIcom3: \fPor \fIcom4:"
|
|
This defines a serial port (UART type 16550A). In the 'term' you can specify
|
|
a device to use as com1. This can be a real serial line, or a pty. To use
|
|
a pty (under X/Unix), create two windows (xterms, usually). One of them will
|
|
run bochs, and the other will act as com1. Find out the tty the com1 window
|
|
using the `tty' command, and use that as the `dev' parameter. Then do
|
|
`sleep 1000000' in the com1 window to keep the shell from messing with things,
|
|
and run bochs in the other window. Serial I/O to com1 (port 0x3f8) will all
|
|
go to the other window.
|
|
|
|
Other serial modes are 'null' (no input/output), 'file' (output to a file
|
|
specified as the 'dev' parameter), 'raw' (use the real serial port - under
|
|
construction for win32) and 'mouse' (standard serial mouse - requires
|
|
mouse option setting 'type=serial' or 'type=serial_wheel')
|
|
|
|
Examples:
|
|
com1: enabled=1, mode=term, dev=/dev/ttyp7
|
|
com2: enabled=1, mode=file, dev=serial.out
|
|
com1: enabled=1, mode=mouse
|
|
|
|
.TP
|
|
.I "parport1: \fPor \fIparport2:"
|
|
This defines a parallel (printer) port. When turned on and an output file is
|
|
defined the emulated printer port sends characters printed by the guest
|
|
OS into the output file. On some platforms a device filename can be used to
|
|
send the data to the real parallel port (e.g. "/dev/lp0" on Linux).
|
|
|
|
Examples:
|
|
parport1: enabled=1, file=parport.out
|
|
parport2: enabled=1, file="/dev/lp0"
|
|
parport1: enabled=0
|
|
|
|
.TP
|
|
.I "boot:"
|
|
This defines the boot sequence. Now you can specify up to 3 boot drives,
|
|
which can be 'floppy', 'disk', 'cdrom' or 'network' (boot ROM).
|
|
Legacy 'a' and 'c' are also supported.
|
|
|
|
Example:
|
|
boot: cdrom, floppy, disk
|
|
|
|
.TP
|
|
.I "floppy_bootsig_check:"
|
|
This disables the 0xaa55 signature check on boot floppies
|
|
The check is enabled by default.
|
|
|
|
Example:
|
|
floppy_bootsig_check: disabled=1
|
|
|
|
.TP
|
|
.I "log:"
|
|
Give the path of the log file you'd like Bochs
|
|
debug and misc. verbiage to be written to. If
|
|
you really don't want it, make it /dev/null.
|
|
|
|
Example:
|
|
log: bochs.out
|
|
log: /dev/tty (unix only)
|
|
log: /dev/null (unix only)
|
|
|
|
.TP
|
|
.I "logprefix:"
|
|
This handles the format of the string prepended to each log line :
|
|
You may use those special tokens :
|
|
%t : 11 decimal digits timer tick
|
|
%i : 8 hexadecimal digits of cpu0 current eip
|
|
%e : 1 character event type ('i'nfo, 'd'ebug, 'p'anic, 'e'rror)
|
|
%d : 5 characters string of the device, between brackets
|
|
|
|
Default : %t%e%d
|
|
|
|
Examples:
|
|
logprefix: %t-%e-@%i-%d
|
|
logprefix: %i%e%d
|
|
|
|
.TP
|
|
.I "panic:"
|
|
If Bochs reaches a condition where it cannot
|
|
emulate correctly, it does a panic. This can
|
|
be a configuration problem (like a misspelled
|
|
bochsrc line) or an emulation problem (like an
|
|
unsupported video mode). The "panic" setting
|
|
in bochsrc tells Bochs how to respond to a
|
|
panic. You can set this to fatal (terminate
|
|
the session), report (print information to
|
|
the console), or ignore (do nothing).
|
|
|
|
The safest setting is action=fatal. If you are
|
|
getting panics, you can try action=report
|
|
instead. If you allow Bochs to continue after
|
|
a panic, don't be surprised if you get strange
|
|
behavior or crashes if a panic occurs. Please
|
|
report panic messages unless it is just a
|
|
configuration problem like "could not find
|
|
hard drive image."
|
|
|
|
Example:
|
|
panic: action=fatal
|
|
|
|
|
|
.TP
|
|
.I "error:"
|
|
Bochs produces an error message when it finds
|
|
a condition that really shouldn't happen, but
|
|
doesn't endanger the simulation. An example of
|
|
an error might be if the emulated software
|
|
produces an illegal disk command.
|
|
|
|
The "error" setting tells Bochs how to respond
|
|
to an error condition. You can set this to
|
|
fatal (terminate the session), report (print
|
|
information to the console), or ignore (do
|
|
nothing).
|
|
|
|
Example:
|
|
error: action=report
|
|
|
|
.TP
|
|
.I "info:"
|
|
This setting tells Bochs what to do when an
|
|
event occurs that generates informational
|
|
messages. You can set this to fatal (that
|
|
would not be very smart though), report (print
|
|
information to the console), or ignore (do
|
|
nothing). For general usage, the "report"
|
|
option is probably a good choice.
|
|
|
|
Example:
|
|
info: action=report
|
|
|
|
.TP
|
|
.I "debug:"
|
|
This setting tells Bochs what to do with
|
|
messages intended to assist in debugging. You
|
|
can set this to fatal (but you shouldn't),
|
|
report (print information to the console), or
|
|
ignore (do nothing). You should generally set
|
|
this to ignore, unless you are trying to
|
|
diagnose a particular problem.
|
|
|
|
.B NOTE:
|
|
When action=report, Bochs may spit out
|
|
thousands of debug messages per second, which
|
|
can impact performance and fill up your disk.
|
|
|
|
Example:
|
|
debug: action=ignore
|
|
|
|
.TP
|
|
.I "debugger_log:"
|
|
Give the path of the log file you'd like Bochs to log debugger output.
|
|
If you really don't want it, make it '/dev/null', or '-'.
|
|
|
|
Example:
|
|
log: debugger.out
|
|
log: /dev/null (unix only)
|
|
log: -
|
|
|
|
.TP
|
|
.I "sb16:"
|
|
This defines the SB16 sound emulation. It can
|
|
have several of the following properties. All
|
|
properties are in this format:
|
|
sb16: property=value
|
|
|
|
|
|
.B PROPERTIES FOR sb16:
|
|
|
|
midi:
|
|
|
|
The filename is where the midi data is sent.
|
|
This can be a device or just a file if you
|
|
want to record the midi data.
|
|
|
|
midimode:
|
|
|
|
0 = No data should be output.
|
|
1 = output to device (system dependent - midi
|
|
denotes the device driver).
|
|
2 = SMF file output, including headers.
|
|
3 = Output the midi data stream to the file
|
|
(no midi headers and no delta times, just
|
|
command and data bytes).
|
|
|
|
wave:
|
|
|
|
This is the device/file where wave output is
|
|
stored.
|
|
|
|
wavemode:
|
|
|
|
0 = no data
|
|
1 = output to device (system dependent - wave
|
|
denotes the device driver).
|
|
2 = VOC file output, including headers.
|
|
3 = Output the raw wave stream to the file.
|
|
|
|
log:
|
|
|
|
The file to write the sb16 emulator messages to.
|
|
|
|
loglevel:
|
|
|
|
0 = No log.
|
|
1 = Resource changes, midi program and bank changes.
|
|
2 = Severe errors.
|
|
3 = All errors.
|
|
4 = All errors plus all port accesses.
|
|
5 = All errors and port accesses plus a lot
|
|
of extra information.
|
|
|
|
It is possible to change the loglevel at runtime.
|
|
|
|
dmatimer:
|
|
|
|
Microseconds per second for a DMA cycle. Make it smaller
|
|
to fix non-continuous sound. 750000 is usually a good
|
|
value. This needs a reasonably correct setting for
|
|
the IPS parameter of the CPU option. It is possible to
|
|
adjust the dmatimer at runtime.
|
|
|
|
Example for output to OSS:
|
|
sb16: midimode=1, midi=/dev/midi00,
|
|
wavemode=1, wave=/dev/dsp, loglevel=2,
|
|
log=sb16.log, dmatimer=600000
|
|
|
|
Example for output to ALSA:
|
|
sb16: midimode=1, midi=alsa:128:0,
|
|
wavemode=1, wave=alsa,
|
|
log=sb16.log, dmatimer=600000
|
|
|
|
.B NOTE:
|
|
The examples are wrapped onto three lines for
|
|
formatting reasons, but it should all be on
|
|
one line in the actual bochsrc file.
|
|
|
|
.TP
|
|
.I "es1370:"
|
|
This defines the ES1370 sound emulation. The parameter 'enabled' controls the
|
|
presence of the device. In addition to this, it must be assigned to a PCI
|
|
slot. The 'wavedev' parameter is similar to the 'wave' parameter of the SB16
|
|
soundcard. Currently only the output of the DAC2 is sent to the wave device.
|
|
|
|
Examples:
|
|
es1370: enabled=1, wavedev="" # win32
|
|
es1370: enabled=1, wavedev=alsa # Linux with ALSA
|
|
|
|
.TP
|
|
.I "vga_update_interval:"
|
|
Video memory is scanned for updates and screen updated
|
|
every so many virtual seconds. The default value is
|
|
50000, about 20Hz. Keep in mind that you must tweak
|
|
the 'cpu: ips=N' directive to be as close to the number of
|
|
emulated instructions-per-second your workstation can
|
|
do, for this to be accurate.
|
|
|
|
Example:
|
|
vga_update_interval: 250000
|
|
|
|
|
|
.TP
|
|
.I "keyboard_serial_delay:"
|
|
Approximate time in microseconds that it takes
|
|
one character to be transfered from the
|
|
keyboard to controller over the serial path.
|
|
|
|
Example:
|
|
keyboard_serial_delay: 200
|
|
|
|
.TP
|
|
.I "keyboard_paste_delay:"
|
|
Approximate time in microseconds between attempts to paste
|
|
characters to the keyboard controller. This leaves time for the
|
|
guest os to deal with the flow of characters. The ideal setting
|
|
depends on how your operating system processes characters. The
|
|
default of 100000 usec (.1 seconds) was chosen because it works
|
|
consistently in Windows.
|
|
|
|
If your OS is losing characters during a paste, increase the paste
|
|
delay until it stops losing characters.
|
|
|
|
Example:
|
|
keyboard_paste_delay: 100000
|
|
|
|
.TP
|
|
.I "clock:"
|
|
This defines the parameters of the clock inside Bochs.
|
|
|
|
sync
|
|
|
|
This defines the method how to synchronize the Bochs internal time
|
|
with realtime. With the value 'none' the Bochs time relies on the IPS
|
|
value and no host time synchronization is used. The 'slowdown' method
|
|
sacrifices performance to preserve reproducibility while allowing host
|
|
time correlation. The 'realtime' method sacrifices reproducibility to
|
|
preserve performance and host-time correlation.
|
|
It is possible to enable both synchronization methods.
|
|
|
|
time0
|
|
|
|
Specifies the start (boot) time of the virtual machine. Use a time
|
|
value as returned by the time(2) system call. If no time0 value is
|
|
set or if time0 equal to 1 (special case) or if time0 equal 'local',
|
|
the simulation will be started at the current local host time.
|
|
If time0 equal to 2 (special case) or if time0 equal 'utc',
|
|
the simulation will be started at the current utc time.
|
|
|
|
Syntax:
|
|
clock: sync=[none|slowdown|realtime|both], time0=[timeValue|local|utc]
|
|
|
|
Default value are sync=none, time0=local
|
|
|
|
Example:
|
|
clock: sync=realtime, time0=938581955 # Wed Sep 29 07:12:35 1999
|
|
|
|
.TP
|
|
.I "mouse:"
|
|
This defines parameters for the emulated mouse type, the initial status
|
|
of the mouse capture and the runtime method to toggle it.
|
|
|
|
type
|
|
|
|
With the mouse type option you can select the type of mouse to emulate.
|
|
The default value is 'ps2'. The other choices are 'imps2' (wheel mouse
|
|
on PS/2), 'serial', 'serial_wheel' and 'serial_msys' (one com port requires
|
|
setting 'mode=mouse'). To connect a mouse to an USB port, see the 'usb_uhci'
|
|
or 'usb_ohci' option (requires PCI and USB support).
|
|
|
|
enabled
|
|
|
|
The Bochs gui creates mouse "events" unless the 'enabled' option is
|
|
set to 0. The hardware emulation itself is not disabled by this.
|
|
Unless you have a particular reason for enabling the mouse by default,
|
|
it is recommended that you leave it off. You can also toggle the mouse
|
|
usage at runtime (RFB, SDL, Win32, wxWidgets and X11 - see below).
|
|
|
|
toggle
|
|
|
|
The default method to toggle the mouse capture at runtime is to press the
|
|
CTRL key and the middle mouse button ('ctrl+mbutton'). This option allows
|
|
to change the method to 'ctrl+f10' (like DOSBox), 'ctrl+alt' (like QEMU)
|
|
or 'f12' (replaces win32 'legacyF12' option).
|
|
|
|
Examples:
|
|
mouse: enabled=1
|
|
mouse: type=imps2, enabled=1
|
|
mouse: type=serial, enabled=1
|
|
mouse: enabled=0, toggle=ctrl+f10
|
|
|
|
.TP
|
|
.I "private_colormap:"
|
|
Requests that the GUI create and use it's own
|
|
non-shared colormap. This colormap will be
|
|
used when in the bochs window. If not enabled,
|
|
a shared colormap scheme may be used. Once
|
|
again, enabled=1 turns on this feature and 0
|
|
turns it off.
|
|
|
|
Example:
|
|
private_colormap: enabled=1
|
|
|
|
.TP
|
|
.I "pci:"
|
|
This option controls the presence of the i440FX PCI chipset. You can
|
|
also specify the devices connected to PCI slots. Up to 5 slots are
|
|
available now. These devices are currently supported: cirrus, es1370, ne2k,
|
|
pcivga, pcidev, pcipnic and usb_ohci.
|
|
|
|
Example:
|
|
pci: enabled=1, chipset=i440fx, slot1=pcivga, slot2=ne2k
|
|
|
|
.TP
|
|
.I "pcidev:"
|
|
Enables the mapping of a host PCI hardware device within the PCI subsystem of
|
|
the Bochs x86 emulator. This feature requires Linux as a host OS.
|
|
|
|
Example:
|
|
pcidev: vendor=0x1234, device=0x5678
|
|
|
|
The vendor and device arguments should contain the vendor ID respectively the
|
|
device ID of the PCI device you want to map within Bochs.
|
|
.B The PCI mapping is still very experimental.
|
|
|
|
.TP
|
|
.I "ne2k:"
|
|
Defines the characteristics of an attached ne2000 isa card :
|
|
ioaddr=IOADDR,
|
|
irq=IRQ,
|
|
mac=MACADDR,
|
|
ethmod=MODULE,
|
|
ethdev=DEVICE,
|
|
script=SCRIPT
|
|
|
|
.B PROPERTIES FOR ne2k:
|
|
|
|
ioaddr, irq:
|
|
You probably won't need to change ioaddr and irq, unless there are IRQ conflicts.
|
|
These parameters are ignored if the NE2000 is assigned to a PCI slot.
|
|
|
|
mac:
|
|
The MAC address MUST NOT match the address of any machine on the net.
|
|
Also, the first byte must be an even number (bit 0 set means a multicast
|
|
address), and you cannot use ff:ff:ff:ff:ff:ff because that's the broadcast
|
|
address. For the ethertap module, you must use fe:fd:00:00:00:01. There may
|
|
be other restrictions too. To be safe, just use the b0:c4... address.
|
|
|
|
ethmod:
|
|
The ethmod value defines which low level OS specific module to be used
|
|
to access physical ethernet interface. Current implemented values include
|
|
- fbsd : ethernet on freebsd and openbsd
|
|
- linux : ethernet on linux
|
|
- win32 : ethernet on win32
|
|
- tap : ethernet through a linux tap interface
|
|
- tuntap : ethernet through a linux tuntap interface
|
|
- slirp : ethernet backend for Slirp and a builtin DHCP server
|
|
|
|
If you don't want to make connections to any physical networks,
|
|
you can use the following 'ethmod's to simulate a virtual network.
|
|
- null : All packets are discarded, but logged to a few files
|
|
- vde : Virtual Distributed Ethernet
|
|
- vnet : ARP, ICMP-echo(ping), DHCP and TFTP are simulated
|
|
The virtual host uses 192.168.10.1
|
|
DHCP assigns 192.168.10.2 to the guest
|
|
The TFTP server use ethdev for the root directory and doesn't
|
|
overwrite files
|
|
|
|
ethdev:
|
|
The ethdev value is the name of the network interface on your host
|
|
platform. On UNIX machines, you can get the name by running ifconfig. On
|
|
Windows machines, you must run niclist to get the name of the ethdev.
|
|
Niclist source code is in misc/niclist.c and it is included in Windows
|
|
binary releases.
|
|
|
|
script:
|
|
The script value is optional, and is the name of a script that
|
|
is executed after bochs initialize the network interface. You can use
|
|
this script to configure this network interface, or enable masquerading.
|
|
This is mainly useful for the tun/tap devices that only exist during
|
|
Bochs execution. The network interface name is supplied to the script
|
|
as first parameter
|
|
|
|
Examples:
|
|
ne2k: ioaddr=0x300, irq=9, mac=b0:c4:20:00:00:00, ethmod=fbsd, ethdev=xlo
|
|
ne2k: ioaddr=0x300, irq=9, mac=b0:c4:20:00:00:00, ethmod=linux, ethdev=eth0
|
|
ne2k: ioaddr=0x300, irq=9, mac=b0:c4:20:00:00:01, ethmod=win32, ethdev=MYCARD
|
|
ne2k: ioaddr=0x300, irq=9, mac=fe:fd:00:00:00:01, ethmod=tap, ethdev=tap0
|
|
ne2k: ioaddr=0x300, irq=9, mac=fe:fd:00:00:00:01, ethmod=tuntap, ethdev=/dev/net/tun0, script=./tunconfig
|
|
ne2k: ioaddr=0x300, irq=9, mac=b0:c4:20:00:00:01, ethmod=vde, ethdev="/tmp/vde.ctl"
|
|
ne2k: ioaddr=0x300, irq=9, mac=b0:c4:20:00:00:01, ethmod=vnet, ethdev="c:/temp"
|
|
|
|
.TP
|
|
.I "pnic:"
|
|
To support the Bochs/Etherboot pseudo-NIC, Bochs must be compiled with the
|
|
--enable-pnic configure option. It accepts the same syntax (for mac, ethmod,
|
|
ethdev, script) and supports the same networking modules as the NE2000 adapter.
|
|
In addition to this, it must be assigned to a PCI slot.
|
|
|
|
Example:
|
|
pnic: enabled=1, mac=b0:c4:20:00:00:00, ethmod=vnet
|
|
|
|
.TP
|
|
.I "keyboard_mapping:"
|
|
This enables a remap of a physical localized keyboard to a
|
|
virtualized us keyboard, as the PC architecture expects.
|
|
If enabled, the keymap file must be specified.
|
|
|
|
Examples:
|
|
keyboard_mapping: enabled=1, map=gui/keymaps/x11-pc-de.map
|
|
|
|
.TP
|
|
.I "keyboard_type:"
|
|
Type of emulated keyboard sent back to the OS
|
|
to a "keyboard identify" command. It must be
|
|
one of "xt", "at" or "mf".
|
|
|
|
Example:
|
|
keyboard_type: mf
|
|
|
|
.TP
|
|
.I "user_shortcut:"
|
|
This defines the keyboard shortcut to be sent when you press the "user"
|
|
button in the header bar. The shortcut string is a combination of maximum
|
|
3 key names (listed below) separated with a '-' character.
|
|
|
|
Valid key names:
|
|
|
|
"alt", "bksl", "bksp", "ctrl", "del", "down", "end", "enter", "esc",
|
|
"f1", ... "f12", "home", "ins", "left", "menu", "minus", "pgdwn", "pgup", "plus",
|
|
"right", "shift", "space", "tab", "up", "win", "print" and "power".
|
|
|
|
Example:
|
|
user_shortcut: keys=ctrl-alt-del
|
|
|
|
.TP
|
|
.I "cmosimage:"
|
|
This defines image file that can be loaded into the CMOS RAM at startup.
|
|
The rtc_init parameter controls whether initialize the RTC with values stored
|
|
in the image. By default the time0 argument given to the clock option is used.
|
|
With 'rtc_init=image' the image is the source for the initial time.
|
|
|
|
Example:
|
|
cmosimage: file=cmos.img, rtc_init=time0
|
|
|
|
.TP
|
|
.I "usb_uhci:"
|
|
This option controls the presence of the USB root hub which is a part
|
|
of the i440FX PCI chipset. With the portX option you can connect devices
|
|
to the hub (currently supported: 'mouse', 'tablet', 'keypad', 'disk', 'cdrom',
|
|
'hub' and 'printer').
|
|
|
|
The optionsX parameter can be used to assign specific options to the device
|
|
connected to the corresponding USB port. Currently this feature is only used
|
|
to set the speed reported by device and by the 'disk' device to specify
|
|
an alternative redolog file of some image modes.
|
|
|
|
If you connect the mouse or tablet to one of the ports, Bochs forwards the
|
|
mouse movement data to the USB device instead of the selected mouse type.
|
|
When connecting the keypad to one of the ports, Bochs forwards the input of
|
|
the numeric keypad to the USB device instead of the PS/2 keyboard.
|
|
|
|
To connect a 'flat' mode image as an USB hardisk you can use the 'disk' device
|
|
with the path to the image separated with a colon. To use other disk image modes
|
|
similar to ATA disks the syntax 'disk:mode:filename' must be used (see below).
|
|
|
|
To emulate an USB cdrom you can use the 'cdrom' device name and the path to
|
|
an ISO image or raw device name also separated with a colon. An option to
|
|
insert/eject media is available in the runtime configuration.
|
|
|
|
The device 'printer' emulates the HP Deskjet 920C printer. The PCL data is
|
|
sent to a file specified in bochsrc.txt. The current code appends the PCL
|
|
code to the file if the file already existed. It would probably be nice to
|
|
overwrite the file instead, asking user first.
|
|
|
|
Example:
|
|
usb_uhci: enabled=1, port1=mouse, port2=disk:usbstick.img
|
|
usb_uhci: enabled=1, port1=hub:7, port2=disk:growing:usbdisk.img
|
|
usb_uhci: enabled=1, port1=printer:printdata.bin, port2=cdrom:image.iso
|
|
|
|
.TP
|
|
.I "usb_ohci:"
|
|
This option controls the presence of the USB OHCI host controller with a
|
|
2-port hub. The portX option accepts the same device types with the same
|
|
syntax as the UHCI controller (see above). The OHCI HC must be assigned to
|
|
a PCI slot.
|
|
|
|
Example:
|
|
usb_ohci: enabled=1
|
|
|
|
.TP
|
|
.I "plugin_ctrl:"
|
|
Controls the presence of optional plugins without a separate option.
|
|
By default all existing plugins are enabled. These plugins are currently
|
|
supported: 'acpi', 'biosdev', 'extfpuirq', 'gameport', 'iodebug', 'pci_ide', 'speaker' and 'unmapped'.
|
|
|
|
Example:
|
|
plugin_ctrl: biosdev=0, speaker=0
|
|
|
|
.TP
|
|
.I "user_plugin:"
|
|
Load user-defined plugin. This option is available only if Bochs is
|
|
compiled with plugin support. Maximum 8 different plugins are supported.
|
|
See the example in the Bochs sources how to write a plugin device.
|
|
|
|
Example:
|
|
user_plugin: name=testdev
|
|
|
|
.\"SKIP_SECTION"
|
|
.SH LICENSE
|
|
This program is distributed under the terms of the GNU
|
|
Lesser General Public License as published by the Free
|
|
Software Foundation. See the COPYING file located in
|
|
/usr/share/doc/bochs/ for details on the license and
|
|
the lack of warranty.
|
|
.\"SKIP_SECTION"
|
|
.SH AVAILABILITY
|
|
The latest version of this program can be found at:
|
|
http://bochs.sourceforge.net/getcurrent.html
|
|
.\"SKIP_SECTION"
|
|
.SH SEE ALSO
|
|
bochs(1), bochs-dlx(1), bximage(1), bxcommit(1)
|
|
.PP
|
|
.nf
|
|
The Bochs IA-32 Emulator site on the World Wide Web:
|
|
http://bochs.sourceforge.net
|
|
|
|
Online Bochs Documentation
|
|
http://bochs.sourceforge.net/doc/docbook
|
|
.fi
|
|
.\"SKIP_SECTION"
|
|
.SH AUTHORS
|
|
The Bochs emulator was created by Kevin Lawton
|
|
(kevin@mandrakesoft.com), and is currently maintained
|
|
by the members of the Bochs x86 Emulator Project. You
|
|
can see a current roster of members at:
|
|
http://bochs.sourceforge.net/getinvolved.html
|
|
.\"SKIP_SECTION"
|
|
.SH BUGS
|
|
Please report all bugs to the bug tracker on our web
|
|
site. Just go to http://bochs.sourceforge.net, and click
|
|
"Bug Reports" on the sidebar under "Feedback".
|
|
.PP
|
|
Provide a detailed description of the bug, the version of
|
|
the program you are running, the operating system you are
|
|
running the program on and the operating system you
|
|
are running in the emulator.
|
|
|
|
|