14/12/26 16:13Bochs User Manual
第 1 （共 70 ）file:///Users/syslight/Work/linux/bochs/usermanual/Bochs%20User%20Manual.html#WHATISBOCHS
Bochs User Manual
Kevin Lawton
Bryce Denney
N. David Guarneri
Volker Ruppert
Christophe Bothamy
Edited by
Michael Calabrese
Stanislav Shwartsman
Table of Contents
1. Introduction to Bochs
1.1. What is Bochs?
1.2. Who uses Bochs?
1.3. Is Bochs right for me?
1.4. Will it work for me?
1.5. Bochs License
1.6. Third Party Software Licensing and Temporary Files
1.7. Features
1.8. Supported Platforms
1.9. FAQ
2. Release Notes
3. Installation
3.1. Downloading Bochs
3.2. Tracking the source code with SVN
3.2.1. Checking out Bochs
3.2.2. Getting the Latest Version
3.2.3. Getting a Release Version
3.2.4. More about SVN
3.3. Installing a Binary
3.3.1. Windows
3.3.2. Linux RPM
3.3.3. MacOS X DMG
3.4. Compiling Bochs
3.4.1. Standard Compile
3.4.2. Configure Options
3.4.3. Transcript of Successful Compilation
3.4.4. Compiling on Win32 with Microsoft VC++
3.4.5. Compiling on Win32 with Cygwin or MinGW/MSYS
3.4.6. Compiling on MacOS 9 with CodeWarrior
3.4.7. Compiling on MacOS X
3.4.8. Compiling on Amiga/MorphOS
3.4.9. Compiling with the RFB interface
3.4.10. Compiling with the VNCSRV interface
3.4.11. Compiling with the SDL interface
3.4.12. Compiling with the SDL version 2 interface
3.4.13. Compiling with the wxWidgets interface
3.4.14. Building an RPM on Linux
3.4.15. Compile Problems
4. Setup
4.1. What does Bochs need?
4.2. ROM images
4.3. The configuration file bochsrc
4.3.1. plugin_ctrl
4.3.2. config_interface
4.3.3. display_library
4.3.4. cpu
4.3.5. cpuid
14/12/26 16:13Bochs User Manual
第 2 （共 70 ）file:///Users/syslight/Work/linux/bochs/usermanual/Bochs%20User%20Manual.html#WHATISBOCHS
4.3.6. memory
4.3.7. megs
4.3.8. romimage
4.3.9. vgaromimage
4.3.10. optromimage1, optromimage2, optromimage3 or optromimage4
4.3.11. vga
4.3.12. voodoo
4.3.13. keyboard
4.3.14. mouse
4.3.15. pci
4.3.16. clock
4.3.17. cmosimage
4.3.18. private_colormap
4.3.19. floppya/floppyb
4.3.20. ata0, ata1, ata2, ata3
4.3.21. ata0-master, ata0-slave, ata1-*, ata2-*, ata3-*
4.3.22. boot
4.3.23. floppy_bootsig_check
4.3.24. log
4.3.25. logprefix
4.3.26. debug/info/error/panic
4.3.27. debugger_log
4.3.28. com[1-4]
4.3.29. parport[1-2]
4.3.30. sound
4.3.31. speaker
4.3.32. sb16
4.3.33. es1370
4.3.34. ne2k
4.3.35. pcipnic
4.3.36. e1000
4.3.37. usb_uhci
4.3.38. usb_ohci
4.3.39. usb_xhci
4.3.40. pcidev
4.3.41. gdbstub
4.3.42. magic_break
4.3.43. debug_symbols
4.3.44. port_e9_hack
4.3.45. user_plugin
4.4. How to write your own keymap table
5. Using Bochs
5.1. Command line arguments
5.2. Search order for the configuration file
5.3. The configuration interface 'textconfig'
5.3.1. The start menu
5.3.2. The Bochs headerbar
5.3.3. The runtime configuration
5.4. Pre-defined CPU models
5.5. Save and restore simulation
5.6. Using sound
5.6.1. Sound basics
5.6.2. The PC speaker
5.6.3. SB16 runtime configuration
6. Common problems and what to do about them (Troubleshooting)
6.1. Bochs panics! What can I do?
6.2. Mouse behavior, enabling and disabling
6.3. Text-mode is broken in some ancient DOS program
7. Feedback and Support
7.1. The Bochs project on SourceForge
7.1.1. SourceForge tickets section (bug and patch trackers)
7.2. Mailing Lists
7.2.1. bochs-developers mailing list
7.2.2. bochs-announce mailing list
7.2.3. bochs-cvs mailing list
7.2.4. Mailing List Etiquette
8. Tips and Techniques
8.1. Specify log options by device
14/12/26 16:13Bochs User Manual
第 3 （共 70 ）file:///Users/syslight/Work/linux/bochs/usermanual/Bochs%20User%20Manual.html#WHATISBOCHS
8.2. How to make a simple disk image
8.2.1. Create a flat image
8.2.2. Partition and format your image file
8.3. Use mtools to manipulate disk images
8.4. Bochs GNU/Linux DiskTools
8.5. Win32 only: Tools to manipulate disk images
8.5.1. Winimage
8.5.2. DiskExplorer
8.5.3. Ben Lunt's MTOOLs for Bochs and Win32 and/or DOS
8.6. X Windows: Color allocation problems
8.7. Screen saver turns on too quickly
8.8. Mounting a disk image using the loop device
8.8.1. ...on Linux
8.8.2. ...on FreeBSD
8.9. Simulating a Symmetric Multiprocessor (SMP) Machine
8.10. Setting Up Networking in DLX Linux
8.11. Configuring and using a tuntap network interface
8.11.1. Tuntap description
8.11.2. Set up the linux Kernel [1]
8.11.3. Configure Bochs to use the tuntap interface
8.11.4. Set up the private network between the host and the guest
8.11.5. Set up the host to masquerade the guest network accesses
8.12. Using the 'slirp' networking module
8.12.1. Advanced Slirp setup with config file
8.12.2. Access to guest services from the host
8.13. Using Bochs internal debugger
8.13.1. Execution Control
8.13.2. BreakPoints
8.13.3. Memory WatchPoints
8.13.4. Manipulating Memory
8.13.5. Info commands
8.13.6. Manipulating CPU Registers
8.13.7. Disassembly commands
8.13.8. Instruction tracing
8.13.9. Instrumentation
8.13.10. Instrumentation commands
8.13.11. Other Commands
8.13.12. The Bochs debugger gui
8.13.13. Related links
8.14. Using Bochs and the remote GDB stub
8.14.1. Configuring Bochs
8.14.2. Running Bochs
8.14.3. Running GDB
8.15. Using the serial port
8.15.1. Logging serial port output to a file
8.15.2. Interactivity : connecting to a virtual terminal
8.15.3. Interactivity : connecting to a pseudo terminal
8.16. BIOS Tips
8.16.1. Booting from CD-ROMs
8.16.2. Disk translation
8.17. How to enter special key combination
8.18. Notes about VESA usage
8.18.1. Instructions to setup Bochs VBE in Windows Guest OS
8.19. Notes about Cirrus SVGA usage
8.20. Disk Image Modes
8.20.1. flat
8.20.2. concat
8.20.3. external/dll
8.20.4. sparse
8.20.5. vmware3 / vmware4
8.20.6. undoable
8.20.7. growing
14/12/26 16:13Bochs User Manual
第 4 （共 70 ）file:///Users/syslight/Work/linux/bochs/usermanual/Bochs%20User%20Manual.html#WHATISBOCHS
8.20.8. volatile
8.20.9. vpc
8.20.10. vvfat
8.21. Using the bximage tool
8.21.1. Create image
8.21.2. Convert image
8.21.3. Resize image
8.21.4. Commit 'undoable' redolog to base image
8.21.5. Disk image info
9. Guest operating systems
9.1. Knoppix
9.1.1. Getting Knoppix
9.1.2. Preparing Bochs
9.1.3. Using Knoppix
9.2. FreeBSD 5.2.1
9.2.1. Getting FreeBSD
9.2.2. Preparing Bochs
9.2.3. Installing FreeBSD
9.2.4. Post-installation configuration
9.2.5. Using FreeBSD
9.3. DOS
9.3.1. Accessing your CDROM
9.3.2. SB16 driver for DOS
9.3.3. Bootdisks of early DOS versions
9.4. Windows NT 4.0
9.5. Windows 2000 / Windows 2000 Server
9.6. Windows XP
9.7. Windows 7
9.8. SCO OpenServer 5.0.5
Chapter 1. Introduction to Bochs
1.1. What is Bochs?
Bochs is a program that simulates a complete Intel x86 computer. It includes emulation of the Intel x86 CPU, common I/O devices, and a custom BIOS. Bochs can be
compiled to emulate many different x86 CPUs, from early 386 to the most recent x86-64 Intel and AMD processors which may even not reached the market yet. Bochs
interprets every instruction from power-up to reboot, and has device models for all of the standard PC peripherals: keyboard, mouse, VGA card/monitor, disks, timer chips,
network card, etc. Because Bochs simulates the whole PC environment, the software running in the simulation "believes" it is running on a real machine. This approach
allows Bochs to run a wide variety of software with no modification, include most popular x86 operating systems: Windows 95/98/NT/2000/XP and Vista, all Linux
flavors, all BSD flavors, and more.
Bochs is written in the C++ programming language, and is designed to run on many different host platforms[1], including x86, PPC, Alpha, Sun, and MIPS. No matter
what the host platform is, Bochs still simulates x86 hardware. In other words, it does not depend on the native instructions of the host machine at all. This is both a strength
and a weakness, and it's the major difference between Bochs and many other x86 emulation software such as VirtualBox, VMware, etc. Because Bochs uses software
simulation for every single x86 instruction, it can simulate a Windows application on an Alpha or Sun workstation. However, the downside of Bochs' approach is
simulation performance. To model the processor accurately, Bochs must run many instructions for every simulated x86 instruction, and this makes the simulated machine
many times slower than the physical machine. Commercial PC emulators (VMware, Connectix, etc.) can achieve much high emulation speed using a technique called
virtualization[2], but they are neither portable to non-x86 platforms nor open source.
To do anything interesting in the simulated machine, Bochs needs to interact with the operating system on the host platform (the host OS). When you press a key in the
Bochs display window, a key event goes into the device model for the keyboard. When the simulated machine needs to read from the simulated hard disk, Bochs reads
from a disk image file on the host machine. When the simulated machine sends a network packet to the local network, Bochs uses the host platform's network card to send
the packet out into the real world. These interactions between Bochs and the host operating system can be complicated, and in some cases they are host platform specific.
Sending a network packet in FreeBSD requires different code than sending the packet in Windows XP, for example. For this reason, certain features are supported on some
host platforms and not others. On GNU/Linux, Bochs can simulate a network card that communicates with the world, but on MacOSX the simulated network card may not
work because the communication code between the device model and the MacOSX operating system has not been written.
!Bochs was written by Kevin Lawton starting in 1994. It started as a program with a commercial license, at the price of 25 USD, for use as-is. If a user needed to link it to
other software, that user would have to negotiate a special license. [3] Finally, in March 2000, MandrakeSoft (now called Mandriva) bought Bochs and made it open
source under the GNU LGPL. In March 2001, Kevin helped a few developers to move all Bochs activities from bochs.com to a new site at bochs.sourceforge.net. Since
then the Bochs project has settled into its new home, and around release times has even hit #1 most active project of the week at SourceForge.
Notes
[1]
Since Bochs can run on one kind of machine and simulate another machine, we have to be clear in our terminology to avoid confusion. The host platform is the
machine that runs the Bochs software. The guest platform is the operating system and applications that Bochs is simulating.
14/12/26 16:13Bochs User Manual
第 5 （共 70 ）file:///Users/syslight/Work/linux/bochs/usermanual/Bochs%20User%20Manual.html#WHATISBOCHS
[2]
Virtualization takes advantage of simulating x86 instructions on an x86 machine, allowing large portions of the simulation to take place at native hardware speed.
Whenever the simulated machine talks to the hardware or enters certain privileged modes (such as in kernel code), the simulator typically takes control and
simulates that code in software at much slower speed, just like Bochs does.
[3]
We need a Bochs historian to help out here. For background, it would be interesting to know how much Bochs sources used to cost and what it was used for. I
thought I saw an interview out there somewhere where Kevin says why he started it and some more background information.
1.2. Who uses Bochs?
It is hard to estimate how many people have tried Bochs or use it on a regular basis, but a few statistics give an indication. The bochs-developers mailing list, which is the
primary source of news on bugs and releases, has over 400 subscribers. The latest version has been downloaded over 150,000 times from SourceForge, not counting any
mirror website or SVN users.
Bochs has many possible uses, and different people use it for different things. Many people use it to run applications in a second operating system without needing two
different computers or dual-booting. Running Windows software on a non-x86 workstation or on an x86 Unix box are common uses. Also, because every hardware
instruction and every line of simulator code is accessible, Bochs is used extensively for debugging new operating systems. If you were writing boot code for your home-
brewed x86 operating system and it didn't work right, booting it in Bochs could give you great visibility into what is really going on. The Bochs debugger lets you simulate
quickly or slowly, pausing whenever you want to look at the contents of memory or the CPU registers. Or, if you wanted to study which parts of a program take the most
time, you could use Bochs to measure how often certain pieces of the code were executed.
Bochs has been used as a teaching tool in Operating Systems classes, in which students used and modified it to learn how the PC hardware works. As a final project the
students had to add a new peripheral device, so they had to learn all about I/O ports, interrupts, and device drivers. In industry, it is used to support legacy applications on
modern hardware, and as a reference model when testing new x86-compatible hardware.
There may be as many uses of Bochs as there are users. Do you want to run your old DOS games? Or learn how to program under GNU/Linux, without leaving your
Windows desktop? Or reverse engineer your printer driver? You decide.
1.3. Is Bochs right for me?
Bochs is very useful for some applications, and not well suited to others. This section tries to answer the question, "Is Bochs right for me?"
Bochs may or may not be right for you, depending on what it is you want to do. Perhaps all you want to do is run one or two applications native to Microsoft Windows on
GNU/Linux, or vice-versa. Perhaps your biggest concern is speed and performance. Maybe you don't mind tweaking a few files here and there when you want another
application to work in that setting. In cases where the objective is to simulate x86 hardware on an x86, VirtualBox, Wine, and VMware might be your best options.
On the other hand, perhaps you have a vital application running on an older operating system that only runs well on old hardware. You are concerned that the life cycle of
this hardware is coming to an end, and your backup and restoration hardware and tools no longer suffice for the amount of data that you have. You need to transfer backup
disk images over a network, and want to use modern procedures for hardware maintenance. Perhaps the application is important enough to run on a larger computer, such
as a 64-bit machine, or even a mainframe. Bochs would be an excellent option in such a scenario.
Perhaps your objective is to debug software or hardware drivers. Bochs offers a controlled environment that can better assist you in determining cause and effect
relationships. You can take snapshots that show you what is going on behind the scenes. You can isolate the line that caused that crash. You can have multiple images and
compare them under a microscope. In these situation, Bochs could save you time and resources.
Information Technology changes faster than any other field. It is very easy to forget transitional software that came and went. But history is important to all fields, and to
build on the future, it is important to understand the past. Computer programmers, however, do not have the same advantage as an architect, who can, for example, take a
trip to Greece and touch a pillar. Much of the history of Computer Science is left on corroding floppies and malfunctioning hardware. Bochs gives you the benefit of having
one or more complete environments where you can understand firsthand the behavior of operating systems and programs. This cannot be achieved with an "emulator" such
as Wine.
1.4. Will it work for me?
Whether Bochs works for you depends on your host hardware, host operating system, guest operating system, guest software, and your ability to work in a command-line
environment using documentation. There is no wizard to help you through the setup process. You do not get a recovery or installation disk to assist you in the process of
installing a guest operating system. Bochs only provides you with the "virtual hardware", and it is up to you to do the rest.
Bochs will run on Windows, GNU/Linux, FreeBSD, OpenBSD, or MacOSX. If you are running on x86 hardware, you have a range of choices. Check the installation
section for your host platform to see what options Bochs supports on your platform. If the most important factor is speed, you may want to try a virtualization product
instead of Bochs (VMware, VirtualBox, QEMU).
If you are using a non-x86 machine, then Bochs is one of the few choices for running x86 software. Bochs has been known to work on Solaris (Sparc), GNU/Linux
(PowerPC/Alpha), MacOS (PowerPC), IRIX (MIPS), Digital Unix (Alpha), and AIX (PowerPC).
You can also find more detailed testing information on the testing status page on the Bochs web site.
1.5. Bochs License
Bochs is copyrighted by MandrakeSoft S.A.[1] and distributed under the GNU Lesser General Public License[2]. The following text appears at the top of every source
code file released under the LGPL in the Bochs distribution: [3]
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later version.
