bochsrc(5) The Bochs Project bochsrc(5)NAMEbochsrc - Configuration file for Bochs.
DESCRIPTION
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.
OPTIONS
#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
config_interface:
The configuration interface is a series of menus or
dialog boxes that allows you to change all the set-
tings that control Bochs's behavior. There are two
choices of configuration interface: a text mode
version called "textconfig" and a graphical version
called "wx". The text mode version uses stdin/std-
out and is always compiled in. The graphical ver-
sion is only available when you use "--with-wx" on
the configure command. If you do not write a con-
fig_interface line, Bochs will choose a default for
you.
NOTE: if you use the "wx" configuration interface,
you must also use the "wx" display library.
Example:
config_interface: textconfig
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 com-
mand 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)
beos native BeOS libraries
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 wxWindows library, cross platform
nogui no display at all
NOTE: if you use the "wx" configuration interface,
you must also use the "wx" display library.
Example:
display_library: x
romimage:
You need to load a ROM BIOS into F0000-FFFFF.
The BIOS controls what the PC does when it
first powers on. Normally, you can use a pre-
compiled BIOS in the bios/ directory, named BIOS-
bochs-latest.
Example:
romimage: file=bios/BIOS-bochs-latest
megs: Set this to the default number of Megabytes of mem-
ory you want to emulate. You may also pass the
'megs:N' option to bochs. The default is 32MB,
since most OS's won't need more than that.
Example:
megs: 32
optromimage1: , optromimage2: , optromimage3: or optromim-
age4:
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 arbitary
code/data in the simulation, that can be retrieved
by the boot loader
Example:
optromimage1: file=optionalrom.bin,
address=0xd0000
vgaromimage:
You also need to load a VGA ROM BIOS into
C0000.
Examples:
vgaromimage: bios/VGABIOS-elpin-2.40
vgaromimage: bios/VGABIOS-lgpl-latest
floppya: or floppyb:
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 to
use 'inserted'.
Example:
2.88M 3.5" Floppy:
floppya: 2_88=path, status=ejected
1.44M 3.5" Floppy:
floppya: 1_44=path, status=inserted
1.2M 5.25" Floppy:
floppyb: 1_2=path, status=ejected
720K 3.5" Floppy:
floppya: 720k=path, status=inserted
360K 5.25" Floppy:
floppya: 360k=path, status=inserted
ata0: , ata1: , ata2: or ata3:
These options enables up to 4 ata channels. For
each channel the two base io addresses and the irq
must be specified. ata0 is enabled by default,
with ioaddr1=0x1f0, ioaddr2=0x3f0, irq=14
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=0x3e8,
irq=11
ata3: enabled=1, ioaddr1=0x168, ioaddr2=0x368,
irq=9
ata[0-3]-master: or ata[0-3]-slave:
This defines the type and characteristics of all
attached ata devices:
type= type of attached device [disk|cdrom]
path= path of the image
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 transation of the bios, only
for disks [none|lba|large|rechs|auto]
model= string returned by identify device
command
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, cylinders, heads, and spt are mandatory
for type=disk The path is mandatory for type=cdrom
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:
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, cylin-
ders=306, heads=4, spt=17
ata0-slave: type=disk, path=20M.sample, cylin-
ders=615, heads=4, spt=17
ata1-master: type=disk, path=30M.sample, cylin-
ders=615, heads=6, spt=17
ata1-slave: type=disk, path=46M.sample, cylin-
ders=940, heads=6, spt=17
ata2-master: type=disk, path=62M.sample, cylin-
ders=940, heads=8, spt=17
ata2-slave: type=disk, path=112M.sample, cylin-
ders=900, heads=15, spt=17
ata3-master: type=disk, path=483M.sample, cylin-
ders=1024, heads=15, spt=63
ata3-slave: type=cdrom, path=iso.sample, sta-
tus=inserted
diskc: or diskd:
The diskc and diskd options are deprecated. Use
ata* options instead.
Point this at the disk image you want to use as
for a hard disk. If you use bximage(1) to create
the image, it will give you the required
cyl, head, and spt information. diskc is the
first hard drive, and diskd is the second hard
drive.
NOTE: You cannot use both diskd and cdromd
together.
Example:
diskc: file=10M.i, cyl=306, heads=4, spt=17
diskc: file=112M.i, cyl=900, heads=15, spt=17
diskd: file=483.i, cyl=1024, heads=15, spt=63
com1: This defines a serial (COM) port. 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), cre-
ate 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.
Examples:
com1: enabled=1, dev=/dev/ttyp7
com1: enabled=0
parport1:
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
parport1: enabled=1, file="/dev/lp0"
parport1: enabled=0
cdromd:
The cdromd option is deprecated. Use ata* options
instead.
Point this to a pathname of a raw CD-ROM device.
There is no cdromc option, only cdromd.
NOTE: You cannot use both diskd and cdromd
together.
Example:
cdromd: dev=/dev/cdrom, status=inserted
cdromd: dev=/dev/cdrom, status=ejected
newharddrivesupport:
This setting enables support for large hard
disks, better CD recognition, and various
other useful functions. You can set it to
"enabled=1" (on) or "enabled=0" (off). It is rec-
ommended that this setting is left on unless
you are having trouble with it.
Example:
newharddrivesupport: enabled=1
boot: This defines your boot drive. You can either boot
from 'floppy', 'disk' or 'cdrom'. (legacy 'a' and
'c' are also supported)
Example:
boot: disk
floppy_bootsig_check:
This disables the 0xaa55 signature check on boot
floppies The check is enabled by default.
Example:
floppy_bootsig_check: disabled=1
log: Give the path of the log file you'd like Bochs
debug and misc. verbage 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)
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
panic: If Bochs reaches a condition where it cannot emu-
late 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 get-
ting panics, you can try action=report
instead. If you allow Bochs to continue after a
panic, don't be surprised if you get strange behav-
ior or crashes if a panic occurs. Please report
panic messages unless it is just a configura-
tion problem like "could not find hard drive
image."
Example:
panic: action=fatal
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 pro-
duces 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
info: This setting tells Bochs what to do when an
event occurs that generates informational mes-
sages. You can set this to fatal (that would
not be very smart though), report (print informa-
tion to the console), or ignore (do nothing).
For general usage, the "report" option is proba-
bly a good choice.
Example:
info: action=report
debug: This setting tells Bochs what to do with mes-
sages intended to assist in debugging. You can set
this to fatal (but you shouldn't), report (print
information to the console), or ignore (do noth-
ing). You should generally set this to ignore,
unless you are trying to diagnose a particular
problem.
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
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: -
sb16: This defines the SB16 sound emulation. It can have
several of the following properties. All proper-
ties are in this format:
sb16: property=value
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 = Only 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.
dmatimer:
Microseconds per second for a DMA cycle. Make it
smaller to fix non-continous sound. 750000 is
usually a good value. This needs a reason-
ably correct setting for IPS (see below).
Example:
sb16: midimode=1, midi=/dev/midi00,
wavemode=1, wave=/dev/dsp, loglevel=2,
log=sb16.log, dmatimer=600000
NOTE: The example is wrapped onto three lines
for formatting reasons, but it should all be on
one line in the actual bochsrc file.
vga_update_interval:
Video memory is scanned for updates and screen
updated every so many virtual seconds. The
default is 300000, about 3Hz. This is gen-
erally plenty. Keep in mind that you must tweak
the 'ips:' directive to be as close to the number
of emulated instructions-per-second your worksta-
tion can do, for this to be accurate.
Example:
vga_update_interval: 250000
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
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
floppy_command_delay:
Time in microseconds to wait before completing some
floppy commands such as read, write, seek,
etc., which normally have a delay associated.
This was previous hardwired to 50,000.
Example:
floppy_command_delay: 50000
ips: Emulated Instructions Per Second. This is the num-
ber of IPS that bochs is capable of running on your
machine. You can recompile Bochs, using
instructions included in config.h (in the source
code), to find your workstation's capability.
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]
Machine Mips
---------------------------------------------------
650Mhz Athlon K-7 with Linux 2.4.x 2 to 2.5
400Mhz Pentium II with Linux 2.0.x 1 to 1.8
166Mhz 64bit Sparc with Solaris 2.x 0.75
200Mhz Pentium with Linux 2.x 0.5
[1] Mips are dependant on OS and compiler con-
figuration in addition to processor clock speed.
Example:
ips: 1000000
pit: The PIT is the programmable interval timer. It has
an option that tries to keep the PIT in sync with
real time. This feature is still experimental, but
it may be useful if you want to prevent Bochs from
running too fast, for example a DOS video game. Be
aware that with the realtime pit option, your simu-
lation will not be repeatable; this can a problem
if you are debugging.
Example:
pit: realtime=1
mouse: This option prevents Bochs from creating mouse
"events" unless a mouse is enabled. The hard-
ware emulation itself is not disabled by this.
You can turn the mouse on by setting enabled to
1, or turn it off by setting enabled to 0.
Unless you have a particular reason for
enabling the mouse by default, it is recom-
mended that you leave it off.
Example:
mouse: enabled=1
mouse: enabled=0
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
i440fxsupport:
Enables limited i440fx PCI chipset support.
Example:
i440fxsupport: enabled=1
time0: Specifies the start (boot) time of the virtual
machine. Use a time value as returned by the
time(2) system call. Time equal to 1 is a special
case which starts the virtual machine at the cur-
rent time of the simulator host.
Example:
time0: 938581955
ne2k: Defines the characteristics of an attached ne2000
isa card :
ioaddr=IOADDR,
irq=IRQ,
mac=MACADDR,
ethmod=MODULE,
ethdev=DEVICE,
script=SCRIPT
PROPERTIES FOR sb16:
ioaddr, irq: You probably won't need to change
ioaddr and irq, unless there are IRQ conflicts.
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 pysical ether-
net 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 inter-
face
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 Win-
dows 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 optionnal, and is the
name of a script that is executed after bochs ini-
tialize 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 execu-
tion. The network interface name is supplied to the
script as first parameter
Examples:
ne2k: ioaddr=0x280, irq=9, mac=b0:c4:20:00:00:00,
ethmod=fbsd, ethdev=xlo
ne2k: ioaddr=0x280, irq=9, mac=b0:c4:20:00:00:00,
ethmod=linux, ethdev=eth0
ne2k: ioaddr=0x280, irq=9, mac=b0:c4:20:00:00:01,
ethmod=win32, ethdev=MYCARD
ne2k: ioaddr=0x280, irq=9, mac=fe:fd:00:00:00:01,
ethmod=tap, ethdev=tap0
ne2k: ioaddr=0x280, irq=9, mac=fe:fd:00:00:00:01,
ethmod=tuntap, ethdev=tun0, script=./tunconfig
keyboard_mapping:
This enables a remap of a physical localized key-
board 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
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
user_shortcut:
This defines the keyboard shortcut to be sent when
you press the "user" button in the headerbar. The
shortcut string can be a combination of these key
names: "alt", "ctrl", "del", "esc", "f1", "f4",
"tab", "win". Up to 3 keys can be pressed at a
time.
Example:
user_shortcut: keys=ctrlaltdel
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/local/share/doc/bochs/ for details on the license and
the lack of warrantee.
AVAILABILITY
The latest version of this program can be found at:
http://bochs.sourceforge.net/getcurrent.html
SEE ALSObochs(1), bochs-dlx(1), bximage(1)
The Bochs IA-32 Emulator site on the World Wide Web:
http://bochs.sourceforge.net
Online Bochs Documentation
http://bochs.sourceforge.net/doc/docbook
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
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".
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.
bochsrc 08 Dec 2002 bochsrc(5)