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 wxWidgets interface
3.4.13. Building an RPM on Linux
3.4.14. 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
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
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. 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
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
8.22. Using the bxcommit tool
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
List of Tables
1-1. Bochs Features
1-2. Supported platforms
3-1. Status letters in a SVN update
3-2. Bochs Release Tags
3-3. Files in Bochs directory (Windows version)
3-4. Files in RPM package
3-5. Installed files
3-6. Defaults by Platform
3-7. Configure Options to Select the Display Library (optional)
3-8. Configure Options
4-1. System and VGA BIOS images
4-2. display_library values
4-3. Example IPS Settings
4-4. ata devices configuration options
4-5. Ethernet modules
4-6. BX_KEY constants
5-1. command line arguments
5-2. Bochs CPU models
5-3. Sound lowlevel modules
5-4. Supported options for sb16ctl
8-1. Log function module names and prefixes
8-2. Slirp config file options
8-3. CD Boot error codes
8-4. Disk translation algorithms
8-5. Supported Disk Modes
8-6. Bximage: supported disk images modes (formats)
List of Figures
3-1. Checking out Bochs in SVN
3-2. Installing an RPM in Linux
3-3. Screenshot of Bochs running DLX Linux