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
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_ehci
4.3.40. usb_xhci
4.3.41. pcidev
4.3.42. gdbstub
4.3.43. magic_break
4.3.44. debug_symbols
4.3.45. port_e9_hack
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. Command mode
5.3.4. 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. The Bochs internal debugger
8.1. Using the command line debugger
8.1.1. Execution Control
8.1.2. BreakPoints
8.1.3. Memory WatchPoints
8.1.4. Manipulating Memory
8.1.5. Info commands
8.1.6. Manipulating CPU Registers
8.1.7. Disassembly commands
8.1.8. Instruction tracing
8.1.9. Instrumentation
8.1.10. Instrumentation commands
8.1.11. Other Commands
8.1.12. Related links
8.2. The Bochs debugger gui
8.2.1. Overview
8.2.2. The register window
8.2.3. The disassembly window
8.2.4. The MemDump window
8.2.5. The output window
8.2.6. The input window
8.2.7. The param tree
8.2.8. The stack window
8.2.9. The breakpoint/watchpoint window
8.2.10. The command button row
8.2.11. The CPU button row
8.2.12. Docking / Resizing
8.2.13. Additional Notes
9. Tips and Techniques
9.1. Specify log options by device
9.2. How to make a simple disk image
9.2.1. Create a flat image
9.2.2. Partition and format your image file
9.3. Use mtools to manipulate disk images
9.4. Bochs GNU/Linux DiskTools
9.5. Win32 only: Tools to manipulate disk images
9.5.1. Winimage
9.5.2. DiskExplorer
9.5.3. Ben Lunt's MTOOLs for Bochs and Win32 and/or DOS
9.6. X Windows: Color allocation problems
9.7. Screen saver turns on too quickly
9.8. Mounting a disk image using the loop device
9.8.1. ...on Linux
9.8.2. ...on FreeBSD
9.9. Simulating a Symmetric Multiprocessor (SMP) Machine
9.10. Setting Up Networking in DLX Linux
9.11. Configuring and using a tuntap network interface
9.11.1. Tuntap description
9.11.2. Set up the linux Kernel [1]
9.11.3. Configure Bochs to use the tuntap interface
9.11.4. Set up the private network between the host and the guest
9.11.5. Set up the host to masquerade the guest network accesses
9.12. Using the 'slirp' networking module
9.12.1. Advanced Slirp setup with config file
9.12.2. Access to guest services from the host
9.13. Using the 'socket' networking module
9.13.1. Using the 'bxhub' utility
9.13.2. The vnet FTP service
9.14. Using Bochs and the remote GDB stub
9.14.1. Configuring Bochs
9.14.2. Running Bochs
9.14.3. Running GDB
9.15. Using the serial port
9.15.1. Logging serial port output to a file
9.15.2. Interactivity : connecting to a virtual terminal
9.15.3. Interactivity : connecting to a pseudo terminal
9.16. BIOS Tips
9.16.1. Booting from CD-ROMs
9.16.2. Disk translation
9.17. How to enter special key combination
9.18. Notes about VESA usage
9.18.1. Instructions to setup Bochs VBE in Windows Guest OS
9.19. Notes about Cirrus SVGA usage
9.20. Notes about Voodoo Graphics usage
9.21. Disk Image Modes
9.21.1. flat
9.21.2. concat
9.21.3. dll
9.21.4. sparse
9.21.5. vmware3 / vmware4
9.21.6. undoable
9.21.7. growing
9.21.8. volatile
9.21.9. vpc
9.21.10. vbox
9.21.11. vvfat
9.22. Using the bximage tool
9.22.1. Create image
9.22.2. Convert image
9.22.3. Resize image
9.22.4. Commit 'undoable' redolog to base image
9.22.5. Disk image info
10. Guest operating systems
10.1. Knoppix
10.1.1. Getting Knoppix
10.1.2. Preparing Bochs
10.1.3. Using Knoppix
10.2. FreeBSD 5.2.1
10.2.1. Getting FreeBSD
10.2.2. Preparing Bochs
10.2.3. Installing FreeBSD
10.2.4. Post-installation configuration
10.2.5. Using FreeBSD
10.3. DOS
10.3.1. Accessing your CDROM
10.3.2. SB16 driver for DOS
10.3.3. Bootdisks of early DOS versions
10.4. Windows NT 4.0
10.5. Windows 2000 / Windows 2000 Server
10.6. Windows XP
10.7. Windows 7
10.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 (General)
3-9. Configure Options (CPU & Memory)
3-10. Configure Options (Devices)
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. Supported keys
5-3. Bochs CPU models
5-4. Sound lowlevel modules
5-5. Supported options for sb16ctrl
9-1. Log function module names and prefixes
9-2. Slirp config file options
9-3. CD Boot error codes
9-4. Disk translation algorithms
9-5. Supported Disk Modes
9-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
  Next
  Introduction to Bochs