diff --git a/bochs/doc/docbook/user/user.dbk b/bochs/doc/docbook/user/user.dbk
index ac673649a..9ce6bf97d 100644
--- a/bochs/doc/docbook/user/user.dbk
+++ b/bochs/doc/docbook/user/user.dbk
@@ -1,11290 +1,11289 @@
-
-
-
-
-%bochsdefs;
-
-]>
-
-
-
- Bochs User Manual
-
- KevinLawton
- BryceDenney
- N. DavidGuarneri
- VolkerRuppert
- ChristopheBothamy
- MichaelCalabrese
- StanislavShwartsman
-
-
-
-
-Introduction to Bochs
-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
-
-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.
-
-, 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
-
-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.
-
-, 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.
-&NEEDHELP;
-
-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.
-
- Finally, in March 2000, MandrakeSoft (2005 to 2015 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 . 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.
-
-
-
-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 &devlist;,
-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.
-
-
-
-
-
-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 this situation, Bochs can 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.
-
-
-
-
-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 &bochswebsite;.
-
-
-
-
-
-Bochs License
-
-Bochs is copyrighted by "The Bochs Project" team and distributed under the
-GNU Lesser General Public License
-
-Complete text of the GNU LGPL is included with the source code in a file
-called COPYING, and is also here.
-
-. The following text appears at the
-top of every source code file released under the LGPL in the Bochs distribution:
-
-Parts of Bochs have specific licenses which are compatible with the
-GNU Lesser General Public License. Hence each source file contains its
-own licensing information.
-
-
- 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.
-
- This library is distributed in the hope that it will be useful,
- but WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- Lesser General Public License for more details.
-
- You should have received a copy of the GNU Lesser General Public
- License along with this library; if not, write to the Free Software
- Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
-
-
-
-
-
-
-Third Party Software Licensing and Temporary Files
-
-
-Before you install or use any Operating System, BIOS, or other software package
-within the Bochs PC emulation environment, make sure you are and will be in
-compliance with all the software licenses pertaining to the software you wish
-to install. It is completely your responsibility to provide licenses and records
-on all software that you install and/or use. It is also completely your responsibility
-to maintain total compliance with all software licenses involved.
-
-
-
-In the process of installing Software within the Bochs PC emulation environment,
-it may be helpful or necessary to copy or convert files from the original distribution
-format to a second format to facilitate the installation. You should delete
-the intermediate files after installation, making certain that only the
-original distribution files remain.
-
-
-
-
-
-Features
-
-The following table shows the features of Bochs and which platforms they
-currently work with.
-
-
Bochs Features
-
-
-
- Feature
- Supported?
- Description
-
-
-
-
- configure script
- Yes
- Bochs uses GNU autoconf to configure Makefiles and headers.
- Autoconf helps Bochs to compile on a wide variety of platforms.
-
-
-
- 386,486,Pentium Emulation
- Yes
- Bochs can be configured to emulate one of several families of Intel hardware. Some Pentium features are incomplete, such as SMM (System Management Mode).
-
-
- P6 and later CPU Emulation
- Yes
- Bochs can be configured to emulate any P6 family processor including optional MMX and SSEx instructions.
-
-
-
- x86-64 Extensions Emulation
- Yes
- Bochs can be configured to emulate x86-64 with many recent Intel and AMD extensions.
-
-
- Command Line Debugger
- Yes
- Powerful command line debugger (optional) that lets you stop
- execution and examine registers and memory, set breakpoints, etc.
-
-
-
- GUI Debugger
- Yes
- Chourdakis Michael and Bruce Ewing contributed very powerful GUI
- frontend for Bochs internal debugger. GUI debugger frontend is supported for
- Win32 and GTK2/GTK3 hosts.
-
-
-
- Floating Point
- Yes
- Uses software floating point engine based on SoftFloat floating point emulation library.
-
-
-
- Enhanced BIOS
- Yes
- Implements ElTorito, EDD v3.0, basic APM feature, PCIBIOS features
- and the PCI interrupt routing table. The latest version of the Bochs BIOS
- has a 32-bit init for ACPI, SMM and SMP. Bochs also known to work with recent
- SeaBIOS images.
-
-
-
- VGA
- Yes
- VGA color graphics emulation in a window.
-
-
-
- VBE (VESA) Support
- Yes
- Currently resolutions up to 2560x1600x32bpp are supported.
- You must enable VBE with the VGA extension option and use the LGPL'd VGABIOS.
- For more information see .
-
-
-
- Cirrus Logic video card
- Yes
- Cirrus Logic CL-GD5430 ISA or CL-GD5446 PCI video card support.
- For more information see .
-
-
- 3D video card
- Yes
- Some of the 3dfx Voodoo graphics adapter models are supported now.
- The code is still experimental, but at least the Voodoo1 and the Voodoo
- Banshee PCI are known to work. For more information see
- .
-
-
- Plug&play monitor
- Yes
- VESA DDC is now supported by all VGA compatible display adapters.
- The LGPL'd VGABIOS has been updated use this feature for the Bochs VBE,
- Voodoo Banshee and Cirrus versions. The interface reports a plug&play
- monitor called "Bochs Screen".
-
-
-
- Floppy disk
- Yes
- Supports floppy disk images on all platforms: 2.88M 3.5", 1.44M 3.5", 1.2M 5.25",
- 720K 3.5" and 360K 5.25". On Unix and Windows NT/2000/XP, Bochs can access the
- physical floppy drive. It is also possible to use a local directory as VFAT media
- (1.44M only).
-
-
-
- Multiple ATA channels
- Yes
- Emulates up to 4 ATA channels. Up to 8 ATA/ATAPI emulated devices can be attached,
- two per ATA channel.
- So you can have eight hard disks or seven hard disks and a CD-ROM or four hard
- disks and four CD-ROMs, or one hard disk and seven CD-ROMs, etc...
-
-
-
- Hard disk
- Yes
- Emulates ATA-6/IDE hard drives via image files. Physical
- hard disk access is supported on some architecture, but NOT recommended, primarily for safety reasons.
- With LBA48 support, hard disks up to 255TB are supported, on any platform that support large files access.
- It is also possible to use a local directory as VFAT drive.
-
-
-
- CD-ROM
- Yes
- Emulates ATAPI-4/IDE CD-ROM. The CD-ROMs can read from an ISO disk image
- on any platform. On Windows (NT/2000/XP/Vista), Linux, SunOS, FreeBSD,
- NetBSD, OpenBSD, Amiga/MorphOS and MacOSX, Bochs can read from the
- physical CD-ROM drive. The Bochs BIOS supports booting from the first CD-ROM drive.
-
-
-
- Keyboard
- Yes
- Emulates a PS/2 keyboard with North American key mappings. Optional
- keyboard layout remapping files are provided to support localized keyboard
- in X11 (12 layouts, e.g. French, German, Italian, Russian, Spanish, U.K.)
- and SDL/SDL2 (German).
-
-
-
- Mouse
- Yes
- Emulates a serial, PS/2, bus or USB mouse with 3 buttons + optional mouse
- wheel support. There is also a USB tablet emulation available.
-
-
-
- Sound card
- Yes
- Emulates a Sound Blaster 16 card (ISA, no plug&play) or an
- ES1370 PCI card. The SB16 emulation provides wave input / output, the OPL3
- chip, the external MIDI port and volume control for wave and FM. The ES1370
- provides wave input / output, the MIDI UART port and volume control for
- wave output. On Windows, Linux, FreeBSD, MacOS 9, MacOSX and all platforms
- supported by SDL, the output can be sent to the host computer's sound
- system. For the SB16, see the developer documentation
- for details.
-
-
-
- Network card
- Yes
- Emulates an NE2000 compatible network card (ISA / PCI) or an Intel(R)
- 82540EM Gigabit Ethernet adapter (PCI). On Windows NT/2000, Linux, FreeBSD,
- and NetBSD, Bochs will forward packets to and from the
- operating system so that the guest OS can talk on the physical network.
- Unfortunately, on some platforms the guest OS can talk to any machine on
- the network BUT NOT the host machine. On Windows and on systems that
- allow the TAP or TUN/TAP interface, there is no such limitation. Often
- the host machine may be configured so the guest OS has access to the
- internet. On MacOSX, you may download the TUN driver from:
-
-
-
-
- Parallel Port
- Yes
- Parallel port emulation was added by Volker Ruppert for Bochs 1.3.
- Data that is sent to the parallel port by the guest OS can be saved into a
- file or sent directly into the parallel port device (Unix only).
-
-
-
- Serial Port
- Yes
- The serial port (16550A UART emulation) is usable, on GNU/Linux,
- NetBSD, OpenBSD, FreeBSD and MacOSX as host and guest. On other OSes the
- emulation is present, but the connection to hard- or software of the host is
- not implemented yet. Up to 4 ports are available.
-
-
-
- Gameport
- Yes
- Emulates a standard PC gameport. The connection to a real joystick is
- currently supported on Linux and win32 only.
-
-
-
- PCI
- Yes
- Emulates most of the i430FX, i440FX or i440BX PCI chipset.
- The Host-to-PCI bridge, the PCI-to-ISA bridge and the PCI IDE controller
- (PIIX3/PIIX4) are available. For PCI cards there are 5 PCI slots supported.
- ACPI and HPET features are also available. The i440BX chipset has basic
- support for AGP.
-
-
-
- USB
- Yes
- Four types of host controllers (UHCI, OHCI, EHCI and xHCI) and the
- devices 'mouse', 'tablet', 'keypad', 'keyboard', 'disk', 'cdrom', 'floppy',
- 'hub' and 'printer' are available. Plugging in and removing devices at runtime
- is possible. Access to real hardware is not implemented yet.
-
-
-
- Plugins
- Yes
- Compiling devices, GUI and drivers for network, sound and disk image
- formats as plugins are supported on Linux, MacOS X, Solaris, Cygwin, MinGW/MSYS,
- MSVC nmake and the VS2019 IDE (workspace provided).
-
-
-
- PIC
- Yes
- Master and slave programmable interrupt controller.
-
-
-
- CMOS functions
- Yes
- Real time clock (RTC) and CMOS RAM are available
-
-
- Dynamic Translation/Virtualization
- No
- Because Bochs is designed to be portable, it does not attempt
- to do any dynamic code translation or virtualization. See
- for details.
-
-
-
- Simulate a Multiprocessor
- Yes
- Bochs can be configured to simulate up to 254 processor threads. This
- feature is still experimental, but it can boot several Linux or Windows guests
- with SMP support. Please note that this does NOT mean that Bochs can run
- faster on a physical SMP machine.
-
-
-
- Take advantage of your SMP box
- Minimal
- At present, Bochs only uses threads in some GUIs, in the lowlevel
- sound output code and in the Voodoo graphics adapter code. The simulation
- core itself uses only one thread, so it will not run any faster on
- multiprocessor hardware.
-
-
-
- Copy and Paste
- Yes
- Depending on the host platform, the text-mode screen text can be
- exported to the clipboard. Text in the clipboard can also be pasted, through
- Bochs, to the guest OS, as simulated keystrokes.
-
-
-
-
-
-
-
-Supported Platforms
-
-The following table shows the supported platforms with a small description and
-the available display libraries on these platforms. The display library is the
-code that displays the Bochs VGA screen and handles keyboard and mouse events.
-
-
Supported platforms
-
-
-
- Platform
- Description
- Display Libraries
-
-
-
-
-
- Unix/X11
-
- X windows has always been well supported because it was
- Kevin Lawton's main development platform. Bryce Denney maintains
- the Unix/X11 platform now. Most features and fixes (not all) are
- tried first in Unix and then ported to the others; see
- for compile instructions.
-
- x, sdl, sdl2, wx, term, rfb, vncsrv
-
-
-
- Win32
-
- This port was done by David Ross and is now maintained by
- Don Becker. You can compile with Microsoft Visual C++,
- see for compile instructions,
- or Cygwin, see .
-
- win32, sdl, sdl2, wx, rfb
-
-
-
- MacOS X
-
- Emmanuel Mailliard ported the Macintosh code to MacOS X with Carbon API.
- Jeremy Parsons (Br'fin) has been maintaining the MacOS X port since
- March 2002; see for compile instructions.
-
- carbon, x, rfb, sdl, sdl2
-
-
-
- PowerPC-Macintosh
-
- David Batterham
- ported Bochs to the Mac. He compiled with CodeWarrior Pro R1 (CW12)
- but has not had time to maintain the Mac port since early 2000.
- If you have Mac development tools and want to contribute, contact
- the &devlist;; see for
- compile instructions.
-
- macos
-
-
-
- Amiga/MorphOS
-
- This port is written and maintained by Nicholai Benalal, see
- for compile instructions.
-
- amigaos
-
-
-
-
-
-
-
-FAQ
-
-
-
- Is Bochs Open Source?
-
-
-
- Yes! Bochs is released under the GNU LGPL.
-
-
-
-
-
-
- How do you pronounce "Bochs"?
-
-
-
- Phonetically the same as the English word "box". It's just a play on the word "box", since techies like to call their machines a "Linux box", "Windows box", ... Bochs emulates a box inside a box.
-
-
-
-
-
-
- Who is the author of Bochs?
-
-
-
- Kevin Lawton is the primary author of Bochs. There have been bug fixes,
- enhancements, and code contributions from some few hundred people, so
- it is not possible to list them all. Later, Kevin had been working on a
- PC virtualization project called plex86. In Fall 2002, he
- made contributed some major CPU speedups and helped with integration
- and debugging of the x86-64 emulation code.
-
-
-
-
-
-
- Who maintains Bochs now?
-
-
- With Kevin's help, in April 2001, the members of the &devlist;
- set up a new official Bochs site hosted by Source Forge.
- The admins on this project are Greg Alexander, Don Becker, Christophe Bothamy,
- Bryce Denney, Volker Ruppert and Stanislav Shwartsman.
-
-
-
-
-
- Tell me about performance when running Bochs.
-
-
- Because Bochs emulates every x86 instruction and all the devices in a PC
- system, it does not reach high emulation speeds. Users who have an x86
- processor and want the highest emulation speeds may want to consider PC
- virtualization software such as Vmware or VirtualBox (free software).
- Another related project is QEMU.
-
-
-
-
-
- Does Bochs use a disk partition to install the OS?
-
-
- No. It uses a disk image file, which is simply a large file, like any other file, on your platform's disk.
-
-
-
-
-
- Why can't I use Bochs with my current WinXP installation?
-
-
- Think about this. If you had two different PC's, they would require different
- hardware drivers. So you may not be able to safely move a disk drive with WinXP
- on it, from one to the other. Bochs is no different. It emulates a certain set
- of hardware devices, and requires each OS be configured for those devices.
-
-
-
-
-
- Is there a developer's email list for Bochs?
-
-
- Yes. For instructions on joining, refer to
- .
-
-
-
-
-
- Is there an IRC channel for Bochs?
-
-
- Yes. You will usually find Bochs developers and users on IRC at irc.freenode.net:6667, channel #bochs.
-
-
-
-
-
- Do you know of any snapshots of Bochs running Windows?
-
-
- Yes! Look for "Screen Shots" on &bochs-sf-net; or on other Bochs sites.
-
-
-
-
-
- Does Bochs support a CD-ROM?
-
-
- Yes, the CD-ROM emulation and accessing ISO files is always available.
- Reading from host CD-ROM media is supported in Linux, Windows, and most
- BSDs. The CD-ROM drivers for Bochs allow the guest operating system to
- access the host operating system's CD-ROM data directly.
-
-
-
-
-
- Does Bochs support a sound device?
-
-
- Yes, Bochs emulates a Sound Blaster 16 card (ISA, no plug&play) or
- an ES1370 PCI. Output to the host sound system is implemented for some
- platforms. See for details.
-
-
-
-
-
- Does Bochs support a network card?
-
-
- Yes. Bochs emulates an NE2000 compatible network card (ISA / PCI) or an
- Intel(R) 82540EM Gigabit Ethernet adapter (PCI). Using the host's network
- capabilities is not supported on all platforms. See
- for details.
-
-
-
-
-
- What applications are known to run inside of Bochs?
-
-
- Well, lots of different OS's run inside of Bochs, so
- thousands. I'm assuming you are asking about Windows programs.
- To give you a few, the following ones from the Winstone'98 tests
- worked: Access 97, CorelDRAW! 7, Excel 97, Lotus 1-2-3 97, Word 97,
- PowerPoint 97, Quattro Pro 7, WordPerfect 7.
-
- Also, I've compiled an entire OS kernel inside Bochs before.
- Not to mention, running DOOM, though at then-pathetic speeds.
-
-
-
-
-
- I am new to Bochs, how do I start?
-
-
- You should read first. Next, you can check
- if they are specific instructions on how to install your (guest) OS inside of Bochs.
-
-
-
-
-
- Does Bochs run on my mobile device?
-
-
- Bochs has now minimal support for the Android platform using a special
- version of the SDL library. There are some external projects that use
- the offical sources with some modifications. They also offer a GUI
- for easy Bochs configuration. Other mobile platforms are not officially
- supported yet.
-
-
-
-
-
-
-
-
-
-
-
-Release Notes
-
-
-The change log is stored in the Bochs source code in a file called
-CHANGES. Click here
-to see the latest version of the CHANGES file.
-
-
-The link above is provided by Source Forge and might change one day. If it
-stops working, you can download the current source code with SVN and read
-the CHANGES file there.
-
-
-
-
-
-
-
-
-Installation
-
-Downloading Bochs
-
-
-You can download Bochs from our web site at &bochs-sf-net;. First, you
-need to choose what version to get: a recent release or a development
-version. If you trying to get things working for the first time, a release
-version is recommended since it has been tested the most. The development
-versions (sometimes called SVN snapshots) may have some newer bug fixes and
-new features, but have not been tested as much as the releases.
-
-
-
-Second, you can choose to compile Bochs from source code or install a binary
-(if one is available for your platform). Binary packages will be quicker to
-install, and most include a small demo of a guest operating system called DLX
-Linux to get you started. However, some features can only be enabled if you
-compile Bochs yourself, for example the Bochs debugger. For multiuser systems,
-you will probably need system administrator privileges (root) to install a
-binary package. If you decide to get a binary, download it to your hard disk,
-uncompress it, then go to the section called Installing a Binary for more information.
-
-
-
-If you are going to compile Bochs yourself, you need the gzipped tarball
-containing the source code, called
-bochs-version.tar.gz. For
-Windows and Mac, the prebuilt Makefiles are separate, so also get
-the Makefiles for your platform. To unpack a compressed TAR file
-
-A TAR file is a single file that contains many files packed inside. Bochs
-TAR files are compressed with a program called gzip, and another program
-called gunzip is used to uncompress them.
-
- on a Unix machine
-
-On Windows, look for software called WinZip to unpack the TAR.
-
-
-, type
-
- gunzip -c bochs-version.tar.gz | tar -xvf -
-
-This creates a directory called
-bochs-version full of
-files. This directory will be referred to as &bochsdir;. Go into
-&bochsdir; and you are ready to compile. Instructions for compiling
-Bochs are in the section, Compiling Bochs.
-
-
-
-Alternatively, you can also obtain the sources for any Bochs version using SVN.
-See the SVN instructions for details.
-
-
-
-Tracking the source code with SVN
-
-SVN (Subversion) is a tool used by many software developers to manage changes
-within their source code tree. SVN provides the means to store not only the
-current version of a piece of source code, but a record of all changes (and who
-made those changes) that have occurred to that source code. Use of SVN is
-particularly common on projects with multiple developers, since SVN ensures
-changes made by one developer are not accidentally removed when another
-developer posts their changes to the source tree. The Bochs source code and
-documentation is available using SVN
-
-You can download SVN software and documentation from
-subversion.apache.org.
-
-.
-
-
-Checking out Bochs
-
-When you have SVN installed, the first step is to do a checkout. The initial
-checkout command is long and ugly, but usually you only have to do it
-once. The example below shows the SVN checkout process of the Bochs trunk in Unix.
-On the Windows platform, you can download a SVN client from
-subversion.apache.org,
-or use SVN within Cygwin
-
-Cygwin is an open source Unix-like environment for Windows platforms,
-available at www.cygwin.com.
-
-.
-
-Checking out Bochs in SVN
-
- user$ svn co http://svn.code.sf.net/p/bochs/code/trunk/bochs bochs
- A bochs/ltdl.c
- A bochs/Makefile.in
- A bochs/bochs.h
- .
- . (This might take a few minutes, depending on your network connection.)
- .
- A bochs/install.sh
- U bochs
- Checkout, Revision 10754.
- user$ cd bochs
- user$ ls
- aclocal.m4 cpu logio.cc pc_system.cc
- bios cpudb.h ltdl.c pc_system.h
- bochs.h crc.cc ltdlconf.h.in plugin.cc
- build disasm ltdl.h plugin.h
- bx_debug doc ltmain.sh README
- bxversion.h.in docs-html main.cc README-plugins
- bxversion.rc.in extplugin.h Makefile.in README.rfb
- CHANGES fpu memory README-wxWindows
- config.cc gdbstub.cc misc TESTFORM.txt
- config.guess gui msrs.def TODO
- config.h.in host osdep.cc win32_enh_dbg.rc
- config.sub install-sh osdep.h win32res.rc
- configure instrument param_names.h wxbochs.rc
- configure.in iodev PARAM_TREE.txt
- COPYING load32bitOShack.cc patches
- user$ _
-
-
-
-
-
- This is just an example output of a checkout of specific version of the Bochs
- trunk and folder. Depending on the checkout command and revision, you most
- likely will see more/other files.
-
-
-
-
-If you have write access to the Bochs SVN tree, see the Developers Guide
-
-
-See the Developers Guide
-and/or look at
-SourceForge's Subversion documentation,
-for instructions.
-
- for details.
-
-
-
-
-The SVN checkout process (above) gives you a directory called bochs
-that contains the very latest source code. I will refer to this directory
-as &bochsdir;. In this directory there's also a subdirectory called ".svn"
-which tells the SVN software where the code was checked out, what version
-you have, and where to go for future updates.
-
-
-
-Getting the Latest Version
-
-Most developers use SVN to always give them the latest source code. The minute
-that any developer checks in a change, they are available to everyone else
-through SVN. You just have to type svn update in the
-&bochsdir; directory, and SVN will retrieve any files and directories that have
-been changed since you did a checkout. If you update regularly, each update
-takes a short time because it downloads only the files that changed.
-See also Getting a release version.
-
-
-
-The svn update command tells you if any new files have
-been downloaded from the server, and it also tells you if you have modified any
-of the SVN-controlled files. As it checks through the source directories, it
-will list files that have changed, with a single letter before the name that
-tells the status of that file. The most common status letters are listed
-below.
-
-
-Status letters in a SVN update
-
-
-
- Letter
- Meaning
- Description
-
-
-
-
- ?
- unknown
-
- This file is in your Bochs directory, but SVN does not know anything
- about it. For example, when you compile Bochs, any files created
- during the build process appear as ?.
-
-
-
- U
- update
-
- SVN downloaded a new version of this file because it changed on the
- server, usually because someone else did a checkin.
-
-
-
- A
- added
-
- SVN downloaded a newly added file from the server.
-
-
-
- D
- deleted
-
- This file has been deleted on the server and SVN removed it from your
- local copy.
-
-
-
- C
- conflict
-
- You have changed this file on your disk, but this change conflicts with
- a change that was checked in. Conflicts occur when two people change
- the same line of code in different ways. You need to edit the
- conflicting file(s) and clean it up by hand. Or, sometimes it's
- easiest to discard your own edits and download a fresh copy, by
- deleting the conflicting file and running svn update again.
-
-
-
-
-
-
-
-
-
-Getting a Release Version
-
-You can also use the SVN checkout command to get the Bochs source code for
-any release since March 2000. The command is
-
- user$ svn co http://svn.code.sf.net/p/bochs/code/tags/tagname/bochs bochs
-
-The tagname tells which release you want, and it can be one of the following:
-
-
-
-
-
-
-
-More about SVN
-
-Entire books have been written on SVN, so there's no sense in duplicating
-it all here in the Bochs documentation. Some sources of additional
-information is listed below.
-
-
-The subversion.apache.org
-site has tons of SVN FAQs and documentation.
-
-A German SVN FAQ
-is available at University of Muenster.
-
-
-
-
-
-
-
-
-
-Installing a Binary
-
-
-This section is divided up by platform, since installing a binary package
-is different on different platforms.
-
-
-Windows
-
-The Bochs binaries for Windows are distributed in an EXE installer package.
-The Bochs installer can be started like any other Windows program and it brings
-up the installation wizard. Here you can select the destination folder and the
-installation options. The wizard installs the files and creates the registry
-keys, start menu and desktop links.
-
-
-Previous releases of Bochs were distributed as ZIP packages, too. These packages
-contained the same set of files as the installer package from the same version.
-
-
-If you are new to Bochs you should try out the DLX Linux demo distributed with
-Bochs. The installation wizard has created a link on the desktop if you decided
-to install the demo. If you doubleclick the icon two windows will appear:
-one is the Bochs Display window, and the other is text window that is used for
-the runtime configuration and for log messages if no logfile is specified.
-
-
-You can find more information on the DLX Linux demo in the next section below the
-DLX Linux screenshot.
-
-
-
Files in Bochs directory (Windows version)
-
- FileDescription
-
-
-
-bios.bin-1.13.0 SeaBIOS ROM image
-BIOS-bochs-latest default ROM BIOS image for Bochs
-BIOS-bochs-legacy ROM BIOS image without 32-bit init code
-bochsdbg.exe the main Bochs executable with debugger enabled
-bochs.exe the main Bochs executable
-bochs.ico the Bochs icon (used for links in start menu and on the desktop)
-bochsrc-sample.txt sample Bochs configuration file
-bxhub.exe utility required for the 'socket' networking module
-bximage.exe tool for manipulating disk images
-CHANGES.txt what has changed between versions
-COPYING.txt copy of the LGPL license
-lgban.ico a set of Bochs icons in different sizes
-LICENSE.txt Bochs license information
-logo.ico another set of Bochs icons
-niclist.exe tool to find out the network interface name
-penguin.ico icons for the DLX Linux link
-README.txt the read-me file from the source distribution.
-sb16ctrl.exe tool to control sb16 in Bochs
-sb16ctrl.txt examples of sb16ctrl commands
-SeaBIOS-README.txt README for SeaBIOS ROM image
-SeaVGABIOS-README.txt README for SeaVGABIOS ROM image
-slirp.conf sample config file for the advanced 'slirp' network configuration
-vnet.conf sample config file for the advanced 'vnet' network configuration
-TODO.txt the TODO file from the source distribution.
-unbochs.ico icon for the uninstaller link
-uninstall.exe uninstall program for Bochs (created by the installation wizard)
-vgabios-cirrus.bin-1.13.0 SeaVGABIOS ROM image (for Cirrus adapter)
-VGABIOS-elpin-2.40 VGA BIOS image for Bochs
-VGABIOS-elpin-LICENSE.txt license for VGA BIOS
-VGABIOS-lgpl-latest LGPL'd VGA BIOS image for Bochs
-VGABIOS-lgpl-latest-debug LGPL'd VGA BIOS image for Bochs with debug output to the logfile
-VGABIOS-lgpl-latest-cirrus LGPL'd VGA BIOS image for Bochs with the Cirrus extension enabled
-VGABIOS-lgpl-latest-cirrus-debug LGPL'd VGA BIOS image for Bochs with the Cirrus extension enabled and debug output to the logfile
-VGABIOS-lgpl-latest-banshee LGPL'd VGA BIOS image for Bochs with the Voodoo Banshee extension enabled
-VGABIOS-lgpl-README.txt readme for the LGPL'd VGA BIOS
-dlxlinux\ directory containing DLX linux sample disk image and configuration files
-dlxlinux\bochsrc.bxrc Bochs configuration file for DLX
-dlxlinux/hd10meg.img disk image file (10 meg)
-dlxlinux\readme.txt description of DLX linux
-dlxlinux\run.bat Run this BAT file to try out DLX Linux inside Bochs!
-dlxlinux\testform.txt Form for reporting success or failure
-
- doc\index.html
- a local copy of all Bochs documentation (online copy)
-
-keymaps\*.map keymap tables (on Windows used for the paste feature only)
-
-
-
-
-
-
-
-Linux RPM
-
-RPM stands for "RedHat Package Manager." An RPM is a compressed file
-containing files to be installed on your system. Many Linux distributions,
-not just RedHat ones, can install files from an RPM. First, download the
-Bochs RPM for your architecture to your computer. For example, if you have an
-Intel-compatible computer, be sure to get the RPM that says "for Linux x86
-distributions" or "i386". Once you have the package on your local disk, you
-should become the root user and install it as follows
-
-Many distributions have their own RPM installer program, often graphical, and
-they should work ok. It is helpful to be able to see the text output from
-RPM, so if you use a fancy RPM installer, be sure to find the text output and
-check that it looks correct.
-
-:
-
-Installing an RPM in Linux
-
- user$ su
- Password:
- root# ls -l bochs-2.5.x86_64.rpm
- -rw-r--r-- 1 user users 2628643 Nov 27 17:20 bochs-2.5.x86_64.rpm
- root# rpm -i bochs-2.5.x86_64.rpm
- root# exit
- user$ _
-
-
-
-
-
-All RPM installations are done as the root user because they require
-permission to update system files and directories. If you do not have root
-access you need to compile Bochs in your home directory.
-
-
-
-RPM installation can fail for a few reasons. It will fail if you already
-have a Bochs package installed. In this case, try upgrading the old package
-to the new package with rpm --upgrade NAME.i386.rpm.
-Another potential problem is missing RPM dependencies. If you are getting
-errors about missing files or RPMs, then first you should try to
-install the RPMs that provide the missing pieces. If that cannot be done,
-download the source RPM and build a new binary RPM that is appropriate
-for your platform. The command is rpmbuild --rebuild
-NAME.src.rpm. As a last resort, you can run rpm with the
---nodeps option to ignore dependencies and install it
-anyway, but if it is missing important pieces, it may not run properly.
-
-
-
-The Bochs RPM installs five new commands and associated manual pages: bochs,
-bochs-dlx and bximage. First, let's try out the
-DLX Linux demo by typing bochs-dlx.
-
-
- user$ bochs-dlx
- ---------------------------------------------------------------
- DLX Linux Demo, for Bochs x86 Emulator
- ---------------------------------------------------------------
- Checking for bochs binary...ok
- Checking for DLX linux directory...ok
- Checking for /bin/gzip...ok
- Checking for /usr/users/bryce/.bochsdlx directory...
- ---------------------------------------------------------------
- To run the DLX Linux demo, I need to create a directory called
- /usr/users/bryce/.bochsdlx, and copy some configuration files
- and a 10 megabyte disk image into the directory.
- ---------------------------------------------------------------
- Is that okay? [y/n]
- y
- Copying /usr/share/bochs/dlxlinux/bochsrc.txt -> /usr/users/bryce/.bochsdlx/.
- Copying /usr/share/bochs/dlxlinux/README -> /usr/users/bryce/.bochsdlx/.
- Copying /usr/share/bochs/dlxlinux/testform.txt -> /usr/users/bryce/.bochsdlx/.
- Uncompressing /usr/share/bochs/dlxlinux/hd10meg.img.gz -> /usr/users/bryce/.bochsdlx/hd10meg.img
- Entering /usr/users/bryce/.bochsdlx
- Running bochs
- ========================================================================
- Bochs x86 Emulator 2.4.6.svn
- Build from SVN snapshot, after release 2.4.6
- Compiled on Oct 20 2011 at 19:40:05
- ========================================================================
-
-
-Then you get a new X11 window containing the VGA display of the simulated
-machine. First you see the VGA BIOS screen, then Linux uncompresses and
-boots, and you get a login prompt. Type "root" and ENTER to log in to
-DLX linux.
-
-Screenshot of Bochs running DLX Linux
-
-
-
-
-
-Booting is complete when you see "dlx login:" and a cursor. At this login
-prompt, type "root". On UNIX systems, root is the system admin user.
-There is no password for root on this sample disk image, so it lets you log
-in without typing any password. Now you should see a UNIX prompt, and you
-can begin to type UNIX commands.
-
-
-
- Welcome to DLX V1.0 (C) 1995-96 Erich Boehm
- (C) 1995 Hannes Boehm
-
- dlx login: root
- Linux 1.3.89.
- dlx:~# pwd
- /root
- dlx:~# cd /
- dlx:~# ls
- bin/ etc/ lost+found/ root/ usr/
- boot/ fd/ mnt/ sbin/ var/
- dev/ lib/ proc/ tmp/ zip/
- dlx:/# df
- Filesystem 1024-blocks Used Available Capacity Mounted on
- /dev/hda1 10060 2736 6005 29% /
- dlx:/# _
-
-
-
-When you get tired of playing with DLX Linux, just type "reboot" in the Bochs
-window to shut down the DLX Linux operating system, and when it starts
-to reboot again press the "Power" button at the top of the Bochs display
-to end the application.
-
-
-
-
-Here is a list of the files that are installed by the RPM, and a brief
-description of each one.
-
-
-
Files in RPM package
-
- FileDescription
-
-
-
-/usr/bin/bochs the main Bochs executable
-/usr/bin/bochs-dlx run this script to try out DLX Linux inside Bochs!
-/usr/bin/bxhub utility required for the 'socket' networking module
-/usr/bin/bximage tool for manipulating disk images
-/usr/lib/bochs/plugins/* plugins (devices, guis, etc.) for Bochs (plugin version only)
-/usr/share/doc/bochs/bochsrc-sample.txt sample Bochs configuration file
-/usr/share/man/man1/* man pages for bochs, bochs-dlx and bximage
-/usr/share/man/man5/* man page for bochsrc
-/usr/share/doc/bochs/CHANGES what has changed between versions
-/usr/share/doc/bochs/COPYING copy of the LGPL license
-/usr/share/doc/bochs/LICENSE Bochs license information
-/usr/share/doc/bochs/README the read-me file from the source distribution.
-/usr/share/doc/bochs/TODO the TODO file from the source distribution.
-/usr/share/doc/bochs/index.html a local copy of all Bochs documentation ( Online copy )
-/usr/share/doc/bochs/slirp.conf sample config file for the advanced 'slirp' network configuration
-/usr/share/doc/bochs/vnet.conf sample config file for the advanced 'vnet' network configuration
-/usr/share/bochs/BIOS-bochs-latest default ROM BIOS image for Bochs
-/usr/share/bochs/BIOS-bochs-legacy ROM BIOS image without 32-bit init code
-/usr/share/bochs/SeaBIOS-README README for SeaBIOS ROM image
-/usr/share/bochs/SeaVGABIOS-README README for SeaVGABIOS ROM image
-/usr/share/bochs/VGABIOS-elpin-2.40 VGA BIOS image for Bochs
-/usr/share/bochs/VGABIOS-elpin-LICENSE license for VGA BIOS
-/usr/share/bochs/VGABIOS-lgpl-latest LGPL'd VGA BIOS image for Bochs
-/usr/share/bochs/VGABIOS-lgpl-latest-debug LGPL'd VGA BIOS image for Bochs with debug output to the logfile
-/usr/share/bochs/VGABIOS-lgpl-latest-cirrus LGPL'd VGA BIOS image for Bochs with the Cirrus extension enabled
-/usr/share/bochs/VGABIOS-lgpl-latest-cirrus-debug LGPL'd VGA BIOS image for Bochs with the Cirrus extension enabled and debug output to the logfile
-/usr/share/bochs/VGABIOS-lgpl-latest-banshee LGPL'd VGA BIOS image for Bochs with the Voodoo Banshee extension enabled
-/usr/share/bochs/VGABIOS-lgpl-README readme for the LGPL'd VGA BIOS
-/usr/share/bochs/bios.bin-1.13.0 SeaBIOS ROM image
-/usr/share/bochs/dlxlinux/ directory containing DLX linux sample disk image and configuration files
-/usr/share/bochs/dlxlinux/readme.txt description of DLX linux
-/usr/share/bochs/keymaps/*.map keymap tables for X11, SDL and SDL2
-/usr/share/bochs/vgabios-cirrus.bin-1.13.0 SeaVGABIOS ROM image (for Cirrus adapter)
-
-
-
-
-
-
-
-
-MacOS X DMG
-
-This was contributed by Aard Vark in January 2003
-
-
-The MacOS X binary distribution is a mountable disk
-image (.dmg file). Once you've downloaded the binary
-distribution file, just double click
-on it to automatically unpack the archive and mount
-the volume on the desktop. An icon will appear
-exactly as if you'd inserted a CD-ROM
-or removable storage device, and a finder window
-containing the volume should automatically open.
-It is likely to have an odd name
-such as _dmg_top, but don't worry about that.
-
-
-Copy the Bochs-2.0 (or whatever version) folder from
-the disk image onto your hard disk. Either Home or
-Applications would be sensible places to put it.
-Because the disk image is mounted read only, you
-can't run the included dlxlinux guest OS until
-you've copied it to the hard disk.
-
-
-Once you've installed the binaries, it's probably a
-good idea to drag the _dmg_top volume to trash to
-unmount it, so you don't get confused and try to
-run Bochs from there. Then open
-the Bochs folder from wherever you installed it.
-
-
-The MacOS X version of Bochs requires a terminal
-window to run. If you just double click on the Bochs
-icon, you'll get an error message telling you to
-double click on "bochs.scpt" to start
-Bochs in a new terminal window. You'll need to
-configure Bochs before you will get very far with
-the bochs.scpt in the top folder,
-so to try out Bochs open the dlxlinux folder and
-double click on the bochs.scpt icon inside.
-
-
-This will open a new terminal window which will
-contain the Bochs startup messages, and a
-configuration menu. The default option is
-[5], which starts the simulation, so press enter to
-do so. You will then get a new window containing
-the VGA display of the simulated
-machine. The new window will probably appear behind
-the current terminal window, so either click on the
-Bochs icon in the dock or the simulation window to
-bring it to the front. If you're quick
-enough you'll then see the VGA BIOS screen, then
-Linux uncompresses and boots, and you get a login
-prompt. Type "root" and ENTER to log in to DLX Linux.
-
-
-Once you've finished playing with DLX Linux, just
-type "reboot" in the Bochs window to shut down the
-DLX Linux operating system, and
-when it starts to reboot again press the "Power"
-button in the "MacBochs Hardware Controls" window
-(it's the circle containing a vertical bar at the
-far right - have a look at the Linux screenshots,
-since the Mac version doesn't seem to have
-descriptions or tool-tips).
-
-
-
-
-
-
-Compiling Bochs
-
-Standard Compile
-
-Bochs is written in C++, so you need a C++ compiler on your system. Most
-platforms have been tested with GNU gcc/g++, but other compilers are known
-to work too. By now, you should have unpacked your source TAR file or checked
-out Bochs from SVN. If not, you can return to Downloading Bochs for details. The top level
-directory of the source code will be referred to as &bochsdir;. (&bochsdir;
-contains the files bochs.h and
-main.cc and subdirectories cpu and
-bios.)
-
-
-
-The standard compile process has three basic steps:
-configure, make, and make
-install. Each step is described in a separate section below. The
-standard compile process is used on all Unix machines, MacOS X, and
-Cygwin (win32). There are separate instructions for compiling for Win32 with Microsoft VC++.
-
-
-Configure
-
-
-There is a script called configure which tests your
-machine, C/C++ compiler and libraries to discover what settings should work on
-your system. If you run configure with no arguments after
-it, defaults will be used for all settings. To change the settings, you can
-run configure with options that override the
-defaults. You can get a list of valid configure options by typing
-configure --help. One useful configure option is
---prefix=directory, which sets the directory in
-which Bochs will be installed. All the possible configure options are
-documented in a later section.
-
-
-
-
-
-Among other things, the configure script tries to detect your platform
-and which compile options to use. If you want to control this, set these
-environment variables before running configure: CC,
-CXX, CFLAGS,
-CXXFLAGS. Here is an example that sets the environment
-variables, using bash/ksh
-
-The syntax for bash and ksh is given. In csh and variants, use the syntax
-setenv VARIABLE
-value to change environment variables.
-Do not use an equal sign for csh!
-
-
-syntax:
-
- export CC=egcs
- export CXX="$CC"
- export CFLAGS="-Wall -O2 -m486 -fomit-frame-pointer -pipe"
- export CXXFLAGS="$CFLAGS"
-
-
-
-
-Once the configure script knows what options are selected,
-it creates a Makefile in every source code directory, and creates
-$BOCHS/config.h with all the option values written
-as preprocessor #defines. Now the sources are ready to compile.
-
-
-Configure Shortcut Scripts
-
-In the Bochs source directory, you will see a series of scripts called
-.conf.platform.
-These scripts run the configure script for you, with a set of
-options that are appropriate for that platform. It is not necessary to
-use the shortcut scripts; they are simply there to show you an example that
-the developers have used. Some of these scripts have been used to build official
-binary packages.
-
-
-
-If a shortcut script is "almost right" for you, just edit it and then run it!
-If you run a shortcut script, you don't need to run configure manually.
-
-
-
-Run a shortcut script using Bourne shell, like this:
-
- sh .conf.win32-vcpp
-
-
-These .conf.platform scripts
-have been tested in recent Bochs versions:
-
Shortcut scripts
-
-
-
- Name
- Build environment
-
-
-
-
- .conf.linux
- Linux (32/64 bit)
-
-
- .conf.macosx
- MacOS X
-
-
- .conf.win32-cygwin
- Windows with Cygwin or MinGW/MSYS
-
-
- .conf.win32-vcpp
- Windows with MSVC (32 bit)
-
-
- .conf.win64-vcpp
- Windows with MSVC (64 bit)
-
-
- .conf.win64-cross-mingw32
- Cross compiling on Linux for Windows
-
-
-
-
-
-
-
-
-
-
-
-Make
-
-The make command compiles Bochs. Make is a program
-used by many software projects that reads the &Makefile; in each source
-directory and follows the instructions that it finds there. A &Makefile; tells
-which files depend on which other files, what commands to use to compile and
-link the code, and more. After you have finished the configure step, just type
-make to build the source code.
-
-
-
-The reason that Make is so popular is that it is smart about when to compile
-and when not to compile. If you run make once, it compiles every file. But
-when you run it again, it checks to see if any source files have been modified;
-if not, there's nothing to do! For example, the &Makefile; says that
-main.o depends on main.cc. Knowing
-this, it will only compile main.cc if it is newer than
-main.o.
-
-
-
-Of course, make can only do the right thing if the &Makefile; lists all the
-dependencies correctly, so human error can sometimes lead make astray.
-If make refuses to build something that you think it should, or you
-are getting strange compile errors, try doing make all-clean
-and then make again. All-clean means to clean up
-the compiled files in every subdirectory, while make clean
-means to clean up just the current directory
-
-
-This is different from the terminology of some other projects, and it may cause
-confusion. Sometimes "clean" implies that all subdirectories are affected.
-
-. However, it's important to note that make
-all-clean leaves the configuration intact. You do not have
-to run configure again.
-
-
-
-If you're really in the mood for cleaning, make dist-clean
-erases all the configuration information too. In theory, after a dist-clean
-your directory should look much like when you first untarred it or checked it
-out. There's usually some extra stuff lying around, but the &Makefile; tries
-at least to erase any files that it created.
-
-
-
-
-Make Install
-
-Once the program has been built, the next step is typically to run
-make install to copy the executables, documentation, and
-other required files into a public place so that all users can use it.
-By default, the files are copied to some directories in /usr/local. The following
-tables show the directories and their contents.
-
-
-
-
-Installing the DLX Linux demo
-
-To download and install the DLX Linux demo distributed with Bochs binary release
-packages, use these two make commands:
-
- make unpack_dlx
- make install_dlx
-
-The package will be downloaded from the Bochs website and installed at same
-location as the files of the Bochs base system.
-
-
-
-
-
-Configure Options
-
-This section describes the configure options for Bochs. Perhaps the most
-important option is , since it gives you a list of all
-the other options. The configure script will detect your platform and choose
-the default GUI for your platform. If the default choice is not what you
-want, use the options to override the default. The
-options in the first table tell which GUI library is the default for each
-platform. Starting in version 2.0, you can use multiple
- options at once to compile with multiple
-display libraries, and then choose between them at runtime with the
-display_library option
-in the configuration file. Or, you can
-let the configure script detect which libraries are on your system
-and use them all, by configuring with .
-
-
-
-The concept of platform detection and default GUIs was added in Bochs 1.4.
-In Bochs 1.3 and before, the X11 GUI was always the default.
-
-
-
-
-
Defaults by Platform
-
-
-
- Platform
- Default GUI
- Extra compile flags
-
-
-
-
- win32, Cygwin or MinGW/MSYS
- --with-win32
- If using nmake method, compile using cl /nologo /MT /W3 /EHs-c- /DNDEBUG /DWIN32 /D_WINDOWS /D_CRT_SECURE_NO_WARNINGS.
- If using Visual C++ workspace, see the workspace file for compile settings.
- See Compiling on Win32 with Microsoft VC++ for instructions.
-
-
-
- MacOS X or Darwin
- --with-carbon
- -fpascal-strings -fno-common -arch ppc -Wno-four-char-constants -Wno-unknown-pragmas -Dmacintosh
-
-
-
- MacOS 9 or before
- --with-macos
- none
-
-
-
- AmigaOS
- --with-amigaos
- none
-
-
-
- any other platform
- --with-x11
- none
-
-
-
-
-
-
-
Configure Options to Select the Display Library (optional)
-
-
-
- Option
- Comments
-
-
-
-
- --with-x11
- Use X windows user interface. On many operating systems,
- Bochs will use X windows by default.
-
-
-
- --with-win32
- Use the native Win32 GUI. This is the default on win32 platforms.
-
-
-
- --with-carbon
- Compile for MacOS X with the Carbon GUI. See the
- .conf.macosx file for the correct MacOS X compile options.
- WARNING: This Bochs feature is not maintained yet and may fail.
-
-
-
- --with-amigaos
- Compile for Amiga MorphOS. This code is written by Nicholai
- Benalal.
-
-
-
- --with-rfb
-
- Enable support for the RFB protocol to talk to AT&T's
- VNC Viewer.
- Refer to for details.
-
-
-
- --with-vncsrv
-
- Enable support for an extended RFB(VNC) GUI using the LibVNCServer library.
- Refer to for details.
-
-
-
- --with-sdl
- Enable support for the SDL 1.2.x GUI interface; see .
-
-
- --with-sdl2
- Enable support for the SDL 2.x GUI interface; see .
-
-
- --with-term
- Use text-only GUI with curses library. Almost certainly
- won't work right with the debugger or the textconfig interface.
-
-
-
- --with-macos
- Use Macintosh/CodeWarrior environment. This is for running
- configure on a platform which supports running configure, so that
- you may then transfer the configured code over to the
- real compile environment.
- WARNING: This Bochs feature is not maintained yet and may fail.
-
-
-
- --with-wx
-
- Enable support for wxWidgets configuration and display interface;
- see .
-
-
-
- --with-nogui
- No native GUI; just use blank stubs. This is if you don't
- care about having video output, but are just running tests.
-
-
-
- --with-all-libs
-
- Automatically detect which libraries are installed on your system
- and enable them. This option is still experimental; it might
- enable libraries that are not usable and cause the compile to fail.
- If you have trouble, just list the options
- for the specific display libraries that you want.
-
-
-
-
-
-
-
-The remaining options can generally be used with any GUI. For each option
-such as , you can also write
-to explicitly turn it off. The following 3 tables show the general options
-(.e.g debugger and plugins support), the CPU-related stuff (e.g. cpu level,
-SMP, x86_64 support) and the devices options (e.g. PCI, USB, Cirrus graphics).
-
-
-
Configure Options (General)
-
-
-
- Option
- Default
- Comments
-
-
-
-
- --enable-plugins
- no
-
- Plugins are shared libraries that can be loaded on demand. Example: the
- serial device is implemented as a plugin. In Unix, the serial plugin is
- called libbx_serial.so. When Bochs reads its configuration file, if the
- serial device is enabled it loads libbx_serial.so. See the Features
- section for supported platforms.
-
-
-
- --enable-debugger
- no
-
- Compile in support for Bochs internal command-line debugger. This has
- nothing to do with x86 hardware debug support. It is a more powerful
- and non-intrusive native debugger. Enabling this will of course slow
- down the emulation. You only need this option if you know you need it.
- After you have run ./configure, you may want to edit
- config.h to customize the debugger further;
- see for more information.
-
-
-
- --enable-debugger-gui
- yes if debugger is on
-
- Enable support for the GUI frontend of the Bochs debugger. This feature
- is supported on Windows hosts and on hosts with GTK2/GTK3 installed.
-
-
-
- --enable-readline
- detected by configure
-
- Compile the debugger with the GNU readline library, which gives
- command line editing and history.
-
-
-
- --enable-gdb-stub
- no
-
- Enable support for the remote GDB stub. See Using Bochs and the remote GDB stub.
- NOTE: This feature cannot be used if the Bochs debugger is also enabled.
- WARNING: This Bochs feature is not maintained yet and may fail.
-
-
-
- --enable-docbook
- detected
-
- Build the docbook documentation in doc/docbook. The configure
- script will enable this option automatically if you have a program
- called docbook2html installed.
-
-
-
- --enable-instrumentation=
- no
-
- Compile in support for instrumentation. This allows you to collect
- instrumentation data from Bochs as it executes code. You have to create
- your own instrumentation library and define the instrumentation macros
- (hooks in Bochs) to either call your library functions or not, depending
- upon whether you want to collect each piece of data.
-
-
-
- --enable-xpm
- yes
-
- Enables the check for the XPM library. This option is only valid if the
- x display library is enabled ().
-
-
-
- --enable-show-ips
- yes
-
- Enables logging of measured IPS, see the ips parameter
- of the cpu option.
-
-
-
- --enable-logging
- yes
-
- By default, Bochs generates logfile output that can be configured with
- bochsrc options and at runtime. Use
- to turn off this feature completely.
-
-
-
- --enable-assert-checks
- yes if debugger is on
-
- BX_ASSERT event causes a panic on assertion failure if enabled (logging
- feature must be enabled, too).
-
-
-
- --enable-cpp
- no
-
- Use .cpp as C++ suffix. Renames all the .cc files to .cpp for use with
- compilers which want that, like older MS C++ compilers. Don't use this
- option unless you know you need it.
-
-
-
- --enable-idle-hack
- no
-
- Enables Roland Mainz's experimental idle code, which is intended to
- keep Bochs from always using 100% of CPU time. When Bochs is waiting
- around for an interrupt, the idle code uses a select() loop and some
- X11 tricks to wait until user input arrives. This is designed to
- keep Bochs responsive while still yielding to other processes when
- Bochs is idle. It only works with X11 or term GUI.
-
-
-
-
-
-
-
Configure Options (CPU & Memory)
-
-
-
- Option
- Default
- Comments
-
-
-
-
- --enable-cpu-level={}
- 6
-
- Select which CPU level to emulate. Choices are 3,4,5,6 which mean to
- target 386, 486, Pentium, or Pentium Pro and later emulation.
-
-
-
- --enable-smp
- no
-
- Compile in support for SMP simulation. This allows you to boot Linux and
- maybe other OSes in SMP mode, and Bochs will simulate all the different
- CPUs and communication between them. Do not expect this option to speed
- up your simulation! On the contrary, it has to spend extra time simulating
- the different CPUs (even if they're mostly idle) and the communication
- between them. Use it to try out an SMP OS if you don't have an SMP machine,
- or to debug SMP OS drivers. Refer to for more details
- on SMP in Bochs.
-
-
-
- --enable-fpu
- yes
- If you want to compile Bochs to make use of the FPU emulator
- written by Stanislav Shwartsman, use this option.
-
-
-
- --enable-3dnow
- no
- 3DNow! instruction set support (incomplete)
-
-
- --enable-x86-64
- no
-
- Add support for x86-64 instruction set, written by Peter Tattam and Stanislav Shwartsman.
-
-
-
- --enable-vmx
- no
- Intel Virtualization Extensions (VMX) support
-
-
- --enable-svm
- no
- AMD SVM (Secure Virtual Machine) extensions emulation support
-
-
- --enable-avx
- no
- AVX instructions support
-
-
- --enable-x86-debugger
- no
- X86 debugger support. If the software you run in Bochs
- needs to use the x86 hardware debugging facilities such as
- DR0..DR7, instruction and data breakpoints etc., then you
- should use this option. Otherwise don't use it, as it
- will slow down the emulation.
-
-
-
- --enable-monitor-mwait
- no
- MONITOR/MWAIT instructions support (still experimental)
-
-
- --enable-alignment-check
- yes if cpu level >= 4
- support for alignment check in the CPU and #AC exception
-
-
- --enable-configurable-msrs
- no
- support for user configurations of emulated MSR registers
- (see example in msrs.def)
-
-
- --enable-long-phy-address
- no
- support for guest physical address larger than 32 bit
-
-
- --enable-a20-pin
- yes
- support for the A20 pin
-
-
- --enable-large-ramfile
- yes
- support for guest memory larger than the host supports
-
-
- --enable-repeat-speedups
- no
- enable support repeated I/O and memory copy speedups
-
-
- --enable-fast-function-calls
- no
- enable support for fast function calls (gcc on x86 only)
-
-
- --enable-handlers-chaining
- no
- enable support for handlers chaining optimization
-
-
- --enable-all-optimizations
- no
-
- Turn on the enables for all speed optimizations that the
- developers believe are safe to use:
- --enable-repeat-speedups,
- --enable-fast-function-calls,
- --enable-handlers-chaining.
-
-
-
-
-
-
-
Configure Options (Devices)
-
-
-
- Option
- Default
- Comments
-
-
-
-
- --enable-cdrom
- yes
-
- Enable use of a real CD-ROM/DVD drive. The CD-ROM emulation and the portable
- ISO image file support are always present. You can use this option to
- compile in support for accessing the media in your workstation's CD-ROM
- drive. The supported platforms are Linux, Solaris, FreeBSD, OpenBSD,
- MacOS X and Windows. For other platforms, a small amount of code specific
- to your platform must be written.
-
-
-
- --enable-sb16
- no
-
- Enable Sound Blaster emulation. The available lowlevel sound interfaces
- are autodetected. See section Using Sound
- for supported platforms and more info. This option also enables the standard
- PC gameport which is a part of the SB16. If you don't want to use it, you
- might use .
-
-
-
- --enable-es1370
- no
-
- Enable ES1370 sound emulation. Just like the SB16 option, the available
- lowlevel sound interfaces are autodetected and the gameport is turned on.
-
-
-
- --enable-gameport
- no
-
- Enables the standard PC gameport. This option is only necessary if you want
- to have a gameport, but no SB16 or ES1370 (see above). The connection to a
- real joystick is currently supported on Linux and win32 only.
-
-
-
- --enable-ne2000
- no
- Enable NE2000 network card support. This requires a
- low-level component to be written for each OS (supported on FreeBSD,
- OpenBSD, Linux, and Windows 9x/NT/2K/XP). When enabled and configured,
- the NE2000 device model can talk to any computer on the network
- EXCEPT FOR the local host. Exception: Under most circumstances, Bochs can
- talk to the local host on Windows, and in the ethertap interface for Linux.
-
-
-
- --enable-pnic
- no
- Enable PCI pseudo NIC (network card) support.
-
-
- --enable-e1000
- no
- Enable Intel(R) 82540EM Gigabit Ethernet adapter support.
-
-
- --enable-clgd54xx
- no
- Enable Cirrus Logic GD54xx (CL-GD5430 ISA or CL-GD5446 PCI) video
- card support. For more information see .
-
-
-
- --enable-voodoo
- no
- Enable experimental 3dfx Voodoo Graphics emulation. The Voodoo1 is
- known to work, the Voodoo2 support is not yet complete, but almost usable.
- The Banshee / Voodoo3 support is under construction, but basically usable.
- For more information see .
-
-
-
- --enable-iodebug
- yes if debugger is on
-
- Dave Poirier has written an experimental interface to the debugger
- using I/O ports, so that software running in the guest OS can access
- features of the debugger. You only want this option if you are
- developing guest OS code for use in Bochs. In other words, most people
- don't. Also, it should only be used with .
- See the
- developer documentation for details.
-
-
-
- --enable-pci
- yes
- Enable limited i440FX / i430FX / i440BX PCI support. This is still
- incomplete, but usable.
-
-
-
- --enable-pcidev
- no
-
- Enable PCI host device mapping support. This requires
- to be set as well as Linux 2.4, 2.6 or 3.x as host.
- WARNING: This Bochs feature is not maintained yet and may fail.
-
-
-
- --enable-usb
- no
-
- Enable i440FX / i440BX PCI USB support (UHCI). The host controller with
- 2-port root hub and 9 USB device types are available.
-
-
-
- --enable-usb-ohci
- no
-
- Enable USB OHCI support. The host controller with 2-port
- root hub is available (USB device types: same as UHCI).
-
-
-
- --enable-usb-ehci
- no
-
- Enable USB EHCI support. The host controller with 6-port
- root hub is available (USB device types: same as UHCI).
-
-
-
- --enable-usb-xhci
- no
-
- Enable USB xHCI support. The host controller with 4-port
- root hub is available (USB device types: same as UHCI).
-
-
-
- --enable-raw-serial
- no
-
- Enable support for the serial port emulation to access to the host's
- serial port. This feature is partly implemented for Windows hosts only.
-
-
-
-
-
-
-
-
-
-
-
-Transcript of Successful Compilation
-
-This example shows the output of a compilation and installation on Linux.
-
- user$ ls -l bochs-2.5.tar.gz
- -rw-r--r-- 1 user users 4117999 27. Nov 17:14 bochs-2.5.tar.gz
- user$ gunzip -c bochs-2.5.tar.gz | tar -xvf -
- bochs-2.5/
- bochs-2.5/.conf.sparc
- bochs-2.5/build/
- bochs-2.5/build/macosx/
- bochs-2.5/build/macosx/pbdevelopment.plist
- bochs-2.5/build/macosx/make-dmg.sh
- .
- .
- .
- bochs-2.5/memory/memory.cc
- bochs-2.5/memory/misc_mem.cc
- bochs-2.5/memory/Makefile.in
- user$ cd bochs-2.5
- user$ ./configure --enable-cpu-level=6
- checking build system type... x86_64-unknown-linux-gnu
- checking host system type... x86_64-unknown-linux-gnu
- checking target system type... x86_64-unknown-linux-gnu
- checking if you are configuring for another platform... no
- checking for standard CFLAGS on this platform...
- checking for gcc... gcc
- .
- .
- .
- config.status: creating build/win32/nsis/bochs.nsi
- config.status: creating host/linux/pcidev/Makefile
- config.status: creating config.h
- config.status: creating ltdlconf.h
- user$ make
- cd iodev && \
- make libiodev.a
- make[1]: Entering directory `/home/volker/Archiv/test/bochs-2.5/iodev'
- g++ -c -I.. -I./.. -I../instrument/stubs -I./../instrument/stubs -g -O2 -D_FILE_OFFSET_BITS=64 -D_LARGE_FILES devices.cc -o devices.o
- g++ -c -I.. -I./.. -I../instrument/stubs -I./../instrument/stubs -g -O2 -D_FILE_OFFSET_BITS=64 -D_LARGE_FILES virt_timer.cc -o virt_timer.o
- g++ -c -I.. -I./.. -I../instrument/stubs -I./../instrument/stubs -g -O2 -D_FILE_OFFSET_BITS=64 -D_LARGE_FILES slowdown_timer.cc -o slowdown_timer.o
- g++ -c -I.. -I./.. -I../instrument/stubs -I./../instrument/stubs -g -O2 -D_FILE_OFFSET_BITS=64 -D_LARGE_FILES pic.cc -o pic.o
- .
- .
- .
- echo done
- done
- /bin/sh ./libtool --mode=link g++ -o bochs -g -O2 -D_FILE_OFFSET_BITS=64 -D_LARGE_FILES -DBX_SHARE_PATH='"/usr/local/share/bochs"' -export-dynamic logio.o main.o config.o load32bitOShack.o pc_system.o osdep.o plugin.o crc.o \
- iodev/libiodev.a cpu/libcpu.a cpu/cpudb/libcpudb.a \
- memory/libmemory.a gui/libgui.a \
- disasm/libdisasm.a \
- fpu/libfpu.a \
- -lSM -lICE -lX11 -lXpm -lXrandr \
- \
- \
- \
- \
- -lm
- mkdir .libs
- g++ -o bochs -g -O2 -D_FILE_OFFSET_BITS=64 -D_LARGE_FILES -DBX_SHARE_PATH=\"/usr/local/share/bochs\" logio.o main.o config.o load32bitOShack.o pc_system.o osdep.o plugin.o crc.o -Wl,--export-dynamic iodev/libiodev.a cpu/libcpu.a cpu/cpudb/libcpudb.a memory/libmemory.a gui/libgui.a disasm/libdisasm.a fpu/libfpu.a -lSM -lICE -lX11 -lXpm -lXrandr -lm
- gcc -c -I. -I./. -Iinstrument/stubs -I./instrument/stubs -g -O2 -D_FILE_OFFSET_BITS=64 -D_LARGE_FILES ./misc/bximage.c -o misc/bximage.o
- /bin/sh ./libtool --mode=link g++ -o bximage -g -O2 -D_FILE_OFFSET_BITS=64 -D_LARGE_FILES misc/bximage.o
- g++ -o bximage -g -O2 -D_FILE_OFFSET_BITS=64 -D_LARGE_FILES misc/bximage.o
- gcc -c -I. -I./. -Iinstrument/stubs -I./instrument/stubs -g -O2 -D_FILE_OFFSET_BITS=64 -D_LARGE_FILES ./misc/bxcommit.c -o misc/bxcommit.o
- /bin/sh ./libtool --mode=link g++ -o bxcommit -g -O2 -D_FILE_OFFSET_BITS=64 -D_LARGE_FILES misc/bxcommit.o
- g++ -o bxcommit -g -O2 -D_FILE_OFFSET_BITS=64 -D_LARGE_FILES misc/bxcommit.o
- user$ su
- root# make install
- cd iodev && \
- make libiodev.a
- make[1]: Entering directory `/home/volker/Archiv/test/bochs-2.5/iodev'
- .
- .
- .
- for i in CHANGES COPYING README TODO; do if test -f $i; then install -m 644 $i /usr/local/share/doc/bochs; else install -m 644 ./$i /usr/local/share/doc/bochs; fi; done
- rm -f /usr/local/share/doc/bochs/README
- cat ./build/linux/README.linux-binary ./README > /usr/local/share/doc/bochs/README
- install -m 644 ./.bochsrc /usr/local/share/doc/bochs/bochsrc-sample.txt
- root# exit
- user$ _
-
-
-
-
-
-Compiling on Win32 with Microsoft VC++
-
-The standard compile uses the configure script, but the Windows platform
-cannot run the configure script natively.
-The current solution to this problem is that the Bochs
-configure script must be run on a different platform that does support
-shell scripts, with options that cause it to configure for a Win32
-platform instead of the native one. Many people have access to a UNIX
-machine that could run the configure script, or you can use Cygwin or
-MinGW/MSYS to run the configure script.
-
-
-Because Bochs depends so much on the configure script, if you are doing
-much win32 Bochs development, you should consider downloading Cygwin or
-MinGW/MSYS so that you can run the configure step natively.
-
-.
-
-
-
-Download the Bochs sources on a machine that can run shell scripts.
-Edit the configure shortcut script .conf.win32-vcpp
-if you want to adjust the configure options. Then type these commands
-in the Bochs source directory:
-
- sh .conf.win32-vcpp
- make win32_snap
-
-These commands will run the configure step, produce VC++ makefiles and
-workspace files, and pack it all into a .zip file in the directory above the
-source directory
-
-If the source directory is /home/joe/bochs-win32, the
-resulting .zip file is in /home/joe/bochs-win32-msvc-src.zip.
-
-. The .zip file is all ready to transfer to the target Windows
-machine to be unzipped and compiled. Or, if you run the sh/make steps in
-Cygwin, you are already on the target machine so you don't need the .zip
-file.
-
-
-
-When you have the Win32 sources transferred to a Windows machine with VC++,
-find the workspace file called bochs.sln in the folder
-"vs2013" and load it in VC++. Choose Project:Set Active Project
-and be sure that "bochs" is selected. Then choose Build:Build bochs.exe.
-This will build all the required libraries (iodev, cpu, etc.) and the auxiliary
-programs bximage.exe, bxhub.exe and
-niclist.exe.
-
-
-
-Using workspaces is easy and intuitive, but there is one caveat. The workspaces
-come directly out of a ZIP file in build/win32/vs2013ex-workspace.zip,
-and they are not controlled by the configure script. When you compile with certain
-configure options (e.g. ) you need to link with additional
-libraries. For now you must add them to the VC++ workspace by hand. In version 2.0,
-we have improved the situation considerably by adding #if...#endif around every optional
-file and including nearly every Bochs source file in the workspace. This solves the
-problem of having to manually add source files to the workspace when you turn
-on configure options such as . The problem of adding
-link libraries remains unresolved.
-
-
-
-
-To compile with the Bochs debugger enabled, add
-to the configure line in .conf.win32-vcpp before running it.
-No modifications to the workspace are necessary.
-
-
-
-An alternative way to compile is to run nmake.exe in an
-MS-DOS window. Instead of using the workspace files, nmake uses the Bochs
-makefiles that are generated by configure. The nmake method is currently used
-to build the release binaries.
-
-
-
-The make install doesn't work with nmake yet. Currently
-it must be run inside of Cygwin or MinGW/MSYS and requires the environment
-variable INSTDIR to be set.
-
-
-
-
-Compiling on Win32 with Cygwin or MinGW/MSYS
-Cygwin is a free Unix-like environment for Windows written by
-Steve Chamberlain and now maintained by RedHat, Inc. You can download
-it from www.cygwin.com. Because
-Cygwin supports the configure script and uses GNU gcc/g++, you can use the
-standard compile process. The configure script should automatically detect
-Cygwin and add "-mno-cygwin -DWIN32" to the compiler options. You should
-get a working Bochs if you just type:
-
- configure
- make
-
-
-Optionally, you can use the configure shortcut script for Cygwin,
-.conf.win32-cygwin, instead of running configure
-directly. If this script is close to what you need, just edit the script and
-then run it. To use the configure shortcut script and compile in Cygwin, the
-commands are
-
- sh .conf.win32-cygwin
- make
-
-To find out the options which are known to work in Cygwin, open the file
-.conf.win32-cygwin in any text editor/viewer and have
-a look at the end of that file.
-
-
-When using gcc 4.7 or newer you need to add the switch -mno-ms-bitfields
-to the CFLAGS, to make sure that hdimage and network structures are packed as
-expected.
-
-
-The command make install installs the Bochs files in the directory
-structure of your build environment. To install Bochs into any desired folder you
-need to use the install_win32 target. It requires the environment
-variable INSTDIR to be set.
-
-
-
-Compiling on MacOS 9 with CodeWarrior
-
- It is possible that this hasn't been tried since 1999. In theory, you
- run sh .conf.macos on a Unix box to build the
- makefiles and headers, copy the whole thing over to a Mac, and then
- use CodeWarrior to compile. Since it hasn't been tested in so long,
- it is quite likely that some work is needed to bring the Mac port up
- to date.
-
-
- If you are interested and have the required MacOS development tools, please
- let us know by contacting the &devlist;. Someone requests a MacOS port
- almost once a month, but none of the developers know how to help them.
-
-
-
-Compiling on MacOS X
-
-The port to MacOS X with Carbon API by Emmanuel Mailliard is quite new, and the
-configure and makefile support was added by Bryce Denney. You will need
-the compiler and libraries from the development tools CD. Bochs should
-configure and compile with the Carbon GUI if you simply type:
-
- configure
- make
-
-Optionally, you can use the configure shortcut script for MacOS X,
-.conf.macosx, instead of running configure directly.
-If this script is close to what you need, just edit the script and then
-run it. To use the configure shortcut script and compile, the commands
-are
-
- sh .conf.macosx
- make
-
-
-MacOS X has a special format for an application bundle, which looks like a
-directory that contains the required resource files and binaries. The Makefile
-currently creates this application bundle "by hand" using mkdir and copy, which
-is surely the wrong way to do it. Bryce doesn't know the official way to
-create an application from a Makefile, so this hack will remain until a real
-Mac developer helps to clean it up.
-
-
-
-On MacOS X the default GUI is the Carbon interface, but you can also try other
-Bochs GUIs. Use for X windows,
- for VNC/RFB, for SDL
-or for SDL2.
-
-
-
-Compiling on Amiga/MorphOS
-
- Nicholai Benalal created this port to MorphOS running on Amiga. It should
- compile with:
-
- configure
- make
-
- If the platform is not detected properly, you might need to use
- as a configure option. Optionally, you
- can use the configure shortcut script, .conf.amigaos.
-
-
-
-Compiling with the RFB interface
-
- The RFB code was written by Don Becker x-odus@iname.com,
- who has a Bochs-RFB web page on his site,
- http://www.psyon.org/bochs-rfb/.
-
-
- This interface allows you to view the Bochs display with
- AT&T's VNC Viewer.
- The protocol used between a VNC server and a VNC viewer is called RFB.
- Because the RFB code in Bochs is written with portable network socket
- and POSIX thread code, it can be compiled on many platforms and has
- been tested in Linux and Win32. No additional libraries are required.
- To try it, type:
-
- configure --with-rfb
- make
-
- RFB currently uses this setup:
-
- port range 5900 to 5949 (using the first one available)
- no authentification
- by default 30 seconds waiting for client
- 8 bpp (BGR233 / RGB332) supported only
- if client doesn't support resize: desktop size 720x480 (for text mode and standard VGA)
- if resize supported: maximum resolution 1280x1024
-
-
-
-With the display library option "timeout" the default value of 30 seconds can
-be changed. With a value of 0 it is possible to start the simulation without a
-client connected.
-
-
-
-Compiling with the VNCSRV interface
-
- The LibVNCServer is
- a cross-platform library that allows to implement VNC server functionality easily.
- On platforms supported by LibVNCServer Bochs can be compiled with support for
- it this way:
-
- configure --with-vncsrv
- make
-
-
-
-Unlike the RFB GUI this new implementation is not limited to 8 bpp and it is
-possible to connect a Bochs session with a web browser.
-
-
-
-Compiling with the SDL interface
-
- Dave Poirier has written an SDL interface for Bochs. Simple DirectMedia
- Layer, or SDL, is a cross-platform multimedia library distributed from
- libsdl.org. SDL is available
- for many platforms including Win32, Linux, BSD, IRIX, MacOS, MacOS X,
- and AmigaOS.
-
-
- To compile Bochs with SDL, you must first install the SDL library
- from libsdl.org. You
- can either get the source code and compile it yourself, or install
- the development libraries for your platform (already compiled).
- Then, go into the Bochs directory and type:
-
- configure --with-sdl
- make
-
-
-
- If you are on FreeBSD and have SDL installed using the ports collection, Bochs
- won't be able to find the library automatically, as the SDL config script is
- called sdl11-config in that case (even for version 1.2).
- The easiest way to make Bochs find it, is to create a symlink to that script
- called sdl-config inside a directory which is in the path.
- For example:
-
- ln -s /usr/local/bin/sdl11-config ~/bin/sdl-config
-
-
-
-To compile in Microsoft VS2013Ex, you have to configure on a different system
-(see Compiling on Win32 with Microsoft VC++).
-Before running the configure script, you have to add
-to the shortcut script. If you have already configured, you can set BX_WITH_SDL
- to 1 in config.h.
-
-
-Then you have to set up the project for SDL this way:
-
-- add source file sdl.cc to the module gui
-- add path to the SDL include files to the modules bochs and gui
-- add lbraries SDL.lib and SDLmain.lib to the module bochs
-- change the runtime library for all modules to Multithreaded-DLL (/MD)
-
-Compiling with MSVC nmake is not supported yet.
-
-
-
-Compiling with the SDL version 2 interface
-
-The SDL library version 2 is now also supported by Bochs. For some basic information
-about SDL, see . The configure option to enable SDL2
-support is and the configuration script is called
-sdl2-config. Note that the Bochs GUIs for SDL version 1.2.x
-and 2.x are mutually exclusive. The legacy SDL GUI support will be removed someday.
-When using the GUI library autodetection () the
-configure script probes for SDL version 2 first.
-
-
-
-
-Compiling with the wxWidgets interface
-
- wxWidgets is a cross-platform C++ user interface library which
- you can download for free at wxwidgets.org.
- The wxWidgets port of Bochs provides both a graphical configuration interface for
- editing bochsrc options (see
- config_interface option) and a
- display (see display_library option).
- It was written by Bryce Denney, Don Becker, Dave Poirier, and Volker Ruppert.
-
- configure --with-wx
- make
-
-
-
- If you want Bochs to use a wxWidgets installation not in your path (but installed
- somewhere else), you need to set the WX_CONFIG environment variable to the
- proper wx-config script, before running configure (example for csh):
-
- setenv WX_CONFIG '/home/compile/wx/bin/wx-config'
-
-
-
-
-Building an RPM on Linux
-
-RPM stands for "RedHat Package Manager." An RPM is a compressed file
-containing files to be installed on your system. Bochs
-has a special shell script called make-rpm that helps
-to build an RPM of Bochs. Start with a clean source directory. Edit
-.conf.linux first if you want to adjust the configure options.
-Then, type:
-
-
- ./build/redhat/make-rpm | tee /tmp/build.txt
-
-
-When this command completes, you should have a source RPM and a binary RPM of
-Bochs in the current directory. The tee part of the
-command (optional) saves a transcript of the build process into /tmp/build.txt,
-which is very useful if anything goes wrong. Instructions for installing an
-RPM are here.
-
-
-
-In the past, you had to build rpms as root, but as of version 2.0 you can build
-them as a normal user.
-
-
-
-
-
-
-Compile Problems
-
-The configure script failed
-
-The configure script can fail for various reasons. If the error
-message on the shell doesn't give enough information, it is recommended to review
-the output file config.log to find out what exactly
-happened. The following issues can be fixed by modifying the configure options used:
-
- deprecated option (option from previous Bochs version not needed /
- supported anymore)
- mutually exclusive option (e.g. and )
- dependent option (e.g. USB support requires PCI support)
- incomplete option (e.g. requires an argument)
- development package for library not installed (e.g. for )
-
-If the configure issue cannot be fixed by option changes and / or installing
-development packages / tools it should be reported in the &devlist; or the SF bug
-tracker for the Bochs project.
-
-
-
-Make / compilation failure
-
-The make utility itself can only fail if the specified target
-is not supported by the environment or simply doesn't exist. In most cases the programs
-called from make are causing the failure (e.g. compiler / linker).
-
-
-In some cases it might be useful to rebuild Bochs completely by calling
-make dist-clean and running the configure
-script once again. These steps are recommended if the development sources from
-SVN are used and one of the build system files (e.g. Makefile
-or config.h.in) has been changed.
-
-
-Sometimes it is possible to isolate the failing piece of code by disabling one or
-more configure options. For example, if the compilation fails somewhere in the cpu/avx*
-files, it might help to configure without . The same
-could be done with other Bochs facilities controlled by configure options.
-
-
-
-Runtime issues with self-compiled Bochs
-
-After a successful compilation the self-compiled Bochs can fail if at least one
-library is not installed properly. This can happen if the library consists of a
-development and a runtime package and the second one is missing. Another problem
-can appear on build environments like Cygwin and MinGW/MSYS. Applications built
-there are usually designed to be run inside of the environment. When starting
-them from the Windows shell, it may cause errors like "missing cygwin1.dll"
-or similar. In that case, the missing DLL must be copied from e.g. the Cygwin folder
-to the location of the compiled EXE file.
-
-
-
-
-
-
-
-
-
-Setup
-What does Bochs need?
-
-These are the minimum requirements for running an OS inside of Bochs:
-
-
-
-the Bochs executable
-
-
-
-
-the BIOS image (usually called BIOS-bochs-latest)
-
-
-
-
-the VGA BIOS image (e.g. VGABIOS-lgpl-latest or VGABIOS-elpin-2.40)
-
-
-
-
-at least one bootable media, either as disk image (floppy, hard disk or CD-ROM) or physical disk (floppy or CD-ROM)
-
-
-
-
-
-
-Both VGA BIOS versions as well as the ROM BIOS are part of the Bochs package. No separate download is necessary.
-See for more information.
-
-
-If you want to use the Cirrus SVGA adapter instead of VGA + Bochs VBE, you should
-have a look at .
-
-
-
-In that case you have to pass the configuration options on the command
-line or to use the configuration interface to set up Bochs for the simulation.
-Running Bochs is easier if you use a configuration file (we call it
-bochsrc). See for all supported options.
-
-
-
-The easiest way to setup Bochs for the first time is to use the example configuration
-file called bochsrc-sample.txt. Locate that file (location depends
-on the (host) OS and on the installation facility used) and copy it to a location where
-Bochs looks for that file, see .
-
-
-
-The next step is to change the configuration so that it fits your needs: You most
-likely want to setup a hard disk (see and
-), and install some OS on it using either
-a set of floppy disks (see ) or a CD-ROM
-(see again) as installation media.
-Make sure you boot the emulation from the media you want, using the right setting
-as boot option.
-
-
-
-If your keyboard output inside of Bochs is wrong, you may also need a keymap file
-to remap your keyboard layout to the U.S. layout. A set of keymap files for the
-X window system and SDL (Linux port) is distributed with Bochs. If your
-keyboard layout is not supported yet, you can create your own one by following the
-instructions given in .
-
-
-
-A collection of disk images of different operating systems can be found at
-. Some disk
-images are the size of a floppy disk (1 meg compressed) and others are gigantic
-(160 meg compressed). If you want to create a disk image yourself, please see
-.
-
-
-
-
-
-ROM images
-
-Just like a real PC, Bochs needs a system BIOS and VGA BIOS to initialize the
-machine when it powers on or after a hardware reset. Bochs needs to load them
-from image file into the emulated memory. The Bochs package contains a set of
-system BIOS and VGA BIOS images.
-
System and VGA BIOS images
-
- FileDescription
-
-
-BIOS-bochs-latest default ROM BIOS image for Bochs
-BIOS-bochs-legacy ROM BIOS image without 32-bit init code (for i386 and ISA graphics card emulation)
-bios.bin-1.13.0 SeaBIOS ROM image
-VGABIOS-elpin-2.40 legacy VGA BIOS image for Bochs
-VGABIOS-lgpl-latest LGPL'd VGA BIOS image for Bochs
-VGABIOS-lgpl-latest-debug LGPL'd VGA BIOS image for Bochs with debug output to the logfile
-VGABIOS-lgpl-latest-cirrus LGPL'd VGA BIOS image for Bochs with the Cirrus extension enabled
-VGABIOS-lgpl-latest-cirrus-debug LGPL'd VGA BIOS image for Bochs with the Cirrus extension enabled and debug output to the logfile
-VGABIOS-lgpl-latest-banshee LGPL'd VGA BIOS image for Bochs with the Voodoo Banshee extension enabled
-vgabios-cirrus.bin-1.13.0 SeaVGABIOS ROM image (for Cirrus adapter)
-
-
-
-
-
-
-Bochs must be set up to use system and VGA BIOS like this:
-
- romimage: file=BIOS-bochs-latest, address=0xfffe0000
- vgaromimage: file=VGABIOS-lgpl-latest
-
-We recommend to use the ROM images distributed with Bochs or one of the latest
-SeaBIOS images. BIOS images designed
-for real hardware mostly do not work properly. Please see the
-for more information.
-
-
-
-Bochs supports optional ROM images to be loaded into the ISA ROM space,
-typically between C8000 and EFFFF (see ). The PCI
-versions of the Bochs network adapter emulations support loading a boot ROM into
-the PCI ROM space (see ).
-
-
-
-
-
-The configuration file <filename>bochsrc</filename>
-
-Bochs uses a configuration file called bochsrc to know
-where to look for disk images, how the Bochs emulation layer should work, etc.
-When you first start up Bochs, it looks around for its configuration file
-(see ), and parses it.
-Here are a few lines from a sample file:
-
- ata0-master: type=disk, path="30M.sample", cylinders=615, heads=6, spt=17
- boot: disk
-
-The format is very strict, so be sure to put the right number of spaces and
-use lowercase letters. As you can see, most lines have a keyword telling what
-is being configured, followed by a colon, followed by a few
-property=value pairs, separated by
-commas. For very simple options, sometimes just a single value is needed.
-The source and binary distributions come with a sample
-bochsrc, so you can just copy the sample file and edit the
-settings you need to change.
-
-
-
-The syntax used for bochsrc can also be used as command line arguments for Bochs.
-If you have any spaces in your command line arguments, they should be enclosed
-in single quotes, for example:
-
- bochs 'boot:floppy' 'floppya: 1_44=a.img, status=inserted'
-
-For other arguments, see section Command line arguments.
-
-
-
-You can use environment variables with the dollar sign prefix in the
-bochsrc file, for example:
-
- floppya: 1_44="$IMAGES/bootdisk.img", status=inserted
- boot: floppy
-
-There are two environment variables with a built-in default value which is set
-at compile or installation 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 in the config files of the Bochs 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 to search in for Bochs
-plugins. The paths are separated by colons (on Windows: semicolons).
-A compile-time default is provided if this variable is not defined by the user.
-On Win32 and MacOSX, the default for the share directory is determined by a
-platform-specific specific algorithm. On Win32, we use the registry to see what
-directory Bochs and its support files were installed in. On MacOSX, the share
-directory is the directory where the application is located.
-
-
-
-You can use the #include statement in the bochsrc to read the
-configuration from other files. Now it is possible to put platform or
-installation defaults in a global config file (e.g. location of rom images).
-Put this on top of your config file if the global configuration is stored in /etc:
-
- #include /etc/bochsrc
-
-
-
-
-Bochs now treats an unknown option as optional device plugin if it exists. It
-loads this plugin and then it tries to call the parser function for this
-configuration line which is located in the plugin. This mechanism is implemented
-for the Bochs network, sound, and USB host controller devices. Externally
-developed device plugins (AKA "user plugins") now can also be loaded this way.
-
-
-
-The section below lists all the supported bochsrc options.
-
-
-plugin_ctrl
-
-Example:
-
- plugin_ctrl: unmapped=0, e1000=1 # unload 'unmapped' and load 'e1000'
-
-Controls the presence of optional device plugins. These plugins are loaded
-directly with this option and some of them install a config option that is
-only available when the plugin device is loaded. The value "1" means to load
-the plugin and "0" will unload it (if loaded before).
-
-
-These plugins will be loaded by default (if present): 'biosdev', 'extfpuirq',
-'gameport', 'iodebug','parallel', 'serial', 'speaker' and 'unmapped'.
-
-
-These plugins are also supported, but they are usually loaded directly with
-their bochsrc option: 'e1000', 'es1370', 'ne2k', 'pcidev', 'pcipnic', 'sb16',
-'usb_ehci', 'usb_ohci', 'usb_uhci', 'usb_xhci' and 'voodoo'.
-
-
-Externally developed device plugins (AKA "user plugins") now can also be loaded
-this way.
-
-
-
-config_interface
-
-The configuration interface is a series of menus or dialog boxes that
-allows you to edit all the settings that control Bochs' 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 or
-GUI console (if available / runtime config) and is always compiled in, unless
-Bochs is compiled for wx only. The choice "win32config" is only available on
-win32/win64 and it is the default on these platforms. The choice "wx" is only
-available when Bochs is compiled with wxWidgets support, see .
-If you do not write a config_interface line, Bochs will choose a default for you.
-
-
-
-wxWidgets provides both a configuration interface and a display library.
-So if you use the "wx" configuration interface, you must also use
-the "wx" display library, see
-display_library option.
-
-
-
-Examples:
-
- config_interface: textconfig
- config_interface: win32config
- config_interface: wx
-
-
-
-
-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
-options, the display_library option lets you choose which one you want to run with.
-If you do not use a display_library line, Bochs will choose a default for
-you.
-
-
-
-wxWidgets provides both a configuration interface and a display library.
-So if you use the "wx" display library, you must also use
-the "wx" configuration interface, see
-config_interface option.
-
-
-
-Examples:
-
- display_library: x
- display_library: sdl2, options=fullscreen
- display_library: options=cmdmode
-
-Some display libraries now support specific options to control their
-behaviour. These options are supported by more than one display library:
-
- "cmdmode" - call a headerbar button handler after pressing F7 (sdl, sdl2, win32, x)
- "fullscreen" - startup in fullscreen mode (sdl, sdl2)
- "gui_debug" - use GTK debugger GUI (sdl, x) / Win32 debugger GUI (sdl, sdl2, win32)
- "hideIPS" - disable IPS output in status bar (rfb, sdl, sdl2, term, vncsrv, win32, wx, x)
- "nokeyrepeat" - turn off host keyboard repeat (sdl, sdl2, win32, x)
- "no_gui_console" - use system console instead of builtin GUI console (rfb, sdl, sdl2, vncsrv, x)
- "timeout" - time (in seconds) to wait for client (rfb, vncsrv)
-
-See the examples below for other currently supported options.
-
- # "traphotkeys" - system hotkeys not handled by host OS, but sent to guest
- # (win32 in mouse capture and fullscreen mode: alt-tab, win,
- # alt-space, alt-esc, ctrl-esc)
- # "autoscale" - scale small simulation window by factor 2, 4 or 8 depending
- # on desktop window size
- display_library: win32, options="traphotkeys autoscale"
-
-Setting up options without specifying display library is also supported.
-
-
-
-display_library values
-
-
-
- Option
- Description
-
-
-
-
- x
- use X windows interface, cross platform
-
-
- win32
- use native win32 libraries
-
-
- carbon
- use Carbon library (for MacOS X)
-
-
- macintosh
- use MacOS pre-10
-
-
- amigaos
- use native AmigaOS libraries
-
-
- sdl
- use SDL 1.2.x library, cross platform,
- details in
-
-
- sdl2
- use SDL 2.x library, cross platform,
- details in
-
-
- term
- text only, uses curses/ncurses library, cross platform
-
-
- rfb
- provides an interface to AT&T's VNC viewer, cross platform,
- details in
-
-
- vncsrv
- use LibVNCServer for extended RFB(VNC) support,
- details in
-
-
- wx
- use wxWidgets library, cross platform,
- details in
-
-
- nogui
- no display at all
-
-
-
-
-
-
-cpu
-
-Example:
-
- cpu: count=2, ips=10000000
-
-This defines the parameters of the cpu inside Bochs:
-
-model
-
-Selects CPU configuration to emulate from pre-defined list of all
-supported configurations. When this option is used and the value
-is different from 'bx_generic', the parameters of the CPUID
-option have no effect anymore. See the for supported values.
-
-count
-
-Set the number of processors:cores per processor:threads per core when Bochs
-is compiled for SMP emulation. Bochs currently supports up to 14 threads
-(legacy APIC) or 254 threads (xAPIC or higher) running simultaniosly.
-If Bochs is compiled without SMP support, it won't accept values
-different from 1. For more information on SMP see .
-
-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 a triple fault occurs (highly recommended) rather than PANIC.
-Remember that if you are 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 work around WinNT installation and boot issues.
-
-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 .
-
-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 available 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
- option enabled, to find your workstation's capability.
-Measured IPS value will then be logged into your log file
-or in the 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. The table below lists some typical
-IPS settings for different machinesIPS measurements depend on
-OS and compiler configuration in addition to host processor clock
-speed..
-
-
-
Example IPS Settings
-
-
-
- Bochs
- Speed
- Machine/Compiler
- Typical IPS
-
-
-
-2.4.63.4GhzIntel Core i7 2600 with Win7x64/g++ 4.5.2 85 to 95 MIPS
-2.3.73.2GhzIntel Core 2 Q9770 with WinXP/g++ 3.4 50 to 55 MIPS
-2.3.72.6GhzIntel Core 2 Duo with WinXP/g++ 3.4 38 to 43 MIPS
-2.2.62.6GhzIntel Core 2 Duo with WinXP/g++ 3.4 21 to 25 MIPS
-2.2.62.1GhzAthlon XP with Linux 2.6/g++ 3.4 12 to 15 MIPS
-
-
-
-
-
-cpuid
-
-Example:
-
- cpuid: level=6, mmx=1, sep=1, sse=sse4_2, apic=xapic, aes=1, movbe=1, xsave=1
-
-This defines features and functionality supported by Bochs emulated CPU. These settings
-are only valid and configurable if the cpu model is
-set to the default value 'bx_generic'.
-
-level
-
-Set emulated CPU level information returned by CPUID. Default value is
-determined by configure option --enable-cpu-level.
-Currently supported values are 5 (for Pentium and similar processors) and 6 (for P6 and
-later processors).
-
-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 brand string returned by CPUID(0x80000002 .. 0x80000004]). This should be
-at most a forty-eight-character ASCII string.
-
-mmx
-
-Select MMX instruction set support.
-This option exists only if Bochs compiled with BX_CPU_LEVEL >= 5.
-
-apic
-
-Select APIC configuration (LEGACY/XAPIC/XAPIC_EXT/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.
-
-simd
-
-Select SIMD instructions support.
-Any of NONE/SSE/SSE2/SSE3/SSSE3/SSE4_1/SSE4_2/AVX/AVX2/AVX512 could be selected.
-This option exists only if Bochs compiled with BX_CPU_LEVEL >= 6.
-The AVX choices exists only if Bochs compiled with --enable-avx option.
-
-sse4a
-
-Select AMD SSE4A instructions support.
-This option exists only if Bochs compiled with BX_CPU_LEVEL >= 6.
-
-misaligned_sse
-
-Select AMD Misaligned SSE mode 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.
-
-sha
-
-Select SHA 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.
-
-adx
-
-Select ADCX/ADOX instructions 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_f16c
-
-Select AVX float16 convert instructions support.
-This option exists only if Bochs compiled with option.
-
-avx_fma
-
-Select AVX fused multiply add (FMA) instructions support.
-This option exists only if Bochs compiled with option.
-
-bmi
-
-Select BMI1/BMI2 instructions support.
-This option exists only if Bochs compiled with option.
-
-fma4
-
-Select AMD four operand FMA instructions support.
-This option exists only if Bochs compiled with option.
-
-xop
-
-Select AMD XOP instructions support.
-This option exists only if Bochs compiled with option.
-
-tbm
-
-Select AMD TBM instructions support.
-This option exists only if Bochs compiled with option.
-
-x86_64
-
-Enable x86-64 and long mode support.
-This option exists only if Bochs compiled with x86-64 support.
-
-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.
-
-smap
-
-Enable Supervisor Mode Access Prevention (SMAP) 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 .
-
-vmx
-
-Select VMX extensions emulation support.
-This option exists only if Bochs compiled with option.
-
-svm
-
-Select AMD SVM (Secure Virtual Machine) extensions emulation support.
-This option exists only if Bochs compiled with option.
-
-
-
-memory
-
-Examples:
-
- memory: guest=512, host=256
-
-Set the amount of physical memory you want to emulate.
-
-guest
-
-Set amount of guest physical memory to emulate. The default is 32MB,
-the maximum amount limited only by physical address space limitations.
-
-host
-
-Set amount of host memory you want to allocate for guest RAM emulation.
-It is possible to allocate less memory than you want to emulate in guest
-system. This will fake guest to see the non-existing memory. Once guest
-system touches new memory block it will be dynamically taken from the
-memory pool. You will be warned (by FATAL PANIC) in case guest already
-used all allocated host memory and wants more.
-
-
-Due to limitations in the host OS, Bochs fails to allocate more than 1024MB on most 32-bit systems.
-In order to overcome this problem, configure and build Bochs with
-option.
-
-
-
-megs
-
-Examples:
-
- megs: 32
- megs: 128
-
-This option sets the 'guest' and 'host' memory parameters to the same
-value. In all other cases the 'memory' option should be used instead.
-
-
-
-romimage
-
-Examples:
-
- romimage: file=bios/BIOS-bochs-latest, options=fastboot
- romimage: file=$BXSHARE/BIOS-bochs-legacy
- romimage: file=mybios.bin, address=0xfff80000
-
-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
-BIOS-bochs-latest. The default ROM BIOS is usually loaded
-starting at address 0xfffe0000, and it is exactly 128k long. The legacy version
-of the Bochs BIOS is usually loaded starting at address 0xffff0000, and it is
-exactly 64k long.
-You can 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.
-The Bochs BIOS currently supports only the option "fastboot" to skip the
-boot menu delay.
-
-
-
-vgaromimage
-
-Examples:
-
- vgaromimage: file=bios/VGABIOS-elpin-2.40
- vgaromimage: file=$BXSHARE/VGABIOS-lgpl-latest
- vgaromimage: file=$BXSHARE/VGABIOS-lgpl-latest-cirrus
-
-This tells Bochs what VGA ROM BIOS to load (at 0xC0000).
-
-A VGA BIOS from Elpin Systems, Inc. as well as a free LGPL'd VGA BIOS
-are provided in the source and binary distributions.
-
- Please check with the vga option to decide
- what VGA BIOS to use.
-
-
-
-
-optromimage1, optromimage2, optromimage3 or optromimage4
-
-Example:
-
- optromimage1: file=optionalrom.bin, address=0xd0000
-
-
-This enables Bochs to 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
-
-
-
-
-vga
-
-Examples:
-
- vga: extension=cirrus, update_freq=10, realtime=1, ddc=file:monitor.bin
- vga: extension=vbe
-
-This defines parameters related to the VGA display
-
-
-The 'extension' option can be used to specify the VGA display extension.
-With the value 'none' you can use standard VGA with no extension. Other supported
-values are 'vbe' for Bochs VBE (needs VGABIOS-lgpl-latest as
-VGA BIOS, see vgaromimage option),
-'cirrus' for Cirrus SVGA support (needs VGABIOS-lgpl-latest-cirrus
-as VGA BIOS) and 'voodoo' for Voodoo Graphics support (needs
-VGABIOS-lgpl-latest-banshee as VGA BIOS / see
- for more information).
-
-
-The VGA update frequency specifies the number of display updates per second.
-This parameter can be changed at runtime. The default value is 5.
-
-
-The 'realtime' option specifies the operation mode of the VGA update timer.
-If set to 1, the VGA timer is based on realtime, otherwise it is based on the
-ips setting. If the host is slow (low ips, update_freq) and the guest uses HLT
-appropriately, setting this to 0 and "clock: sync=none" may improve the
-responsiveness of the guest GUI when the guest is otherwise idle. The default
-value is 1.
-
-
-The parameter 'ddc' defines the behaviour of the DDC emulation that returns
-the monitor EDID data. By default, the 'builtin' values for 'Bochs Screen'
-are used. Other choices are 'disabled' (no DDC emulation) and 'file'
-(read monitor EDID from file / path name separated with a colon).
-
-
-
-
-voodoo
-
-Example:
-
- voodoo: enabled=1, model=voodoo1
-
-This defines the Voodoo Graphics emulation (experimental). Currently
-supported models are 'voodoo1', 'voodoo2', 'banshee' and 'voodoo3'.
-The Voodoo2 support is not yet complete, but almost usable. The Banshee /
-Voodoo3 support is under construction, but basically usable. The 2D/3D cards
-require the vga extension option to be set to 'voodoo'. If the i440BX PCI
-chipset is selected, they can be assigned to AGP (slot #5). The GUI screen
-update timing for all models is controlled by the related
-'vga' options. See for more information.
-
-
-
-keyboard
-
-Examples:
-
- keyboard: type=mf, serial_delay=200, paste_delay=100000
- keyboard: keymap=gui/keymaps/x11-pc-de.map
- keyboard: user_shortcut=ctrl-alt-del
-
-This defines parameters related to the emulated keyboard.
-
-type
-
-Type of keyboard return by a "identify keyboard" command to the
-keyboard controller. It must be one of "xt", "at" or "mf".
-Defaults to "mf". It should be ok for almost everybody. A known
-exception is French macs, that do have a "at"-like keyboard.
-
-serial_delay
-
-Approximate time in microseconds that it takes one character to
-be transferred from the keyboard to controller over the serial path.
-
-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.
-
-keymap
-
-This enables a remap of a physical localized keyboard to a
-virtualized us keyboard, as the PC architecture expects.
-
-
-Keyboard mapping is available for the display libraries x, sdl (Linux port) and
-wx (GTK port). For SDL you have to use keymaps designed for SDL, the wxWidgets GUI
-uses the keymaps for X11.
-
-user_shortcut
-
-This defines the keyboard shortcut to be sent when you press the "user" button
-in the headerbar. 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", "power", "print", "right", "scrlck", "shift", "space", "tab", "up"
-and "win".
-
-
-
-
-mouse
-
-Examples:
-
- mouse: enabled=1
- mouse: type=imps2, enabled=1
- mouse: type=serial, enabled=1
- mouse: enabled=0, toggle=ctrl+f10
-
-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', 'serial_msys' (one com port requires
-setting 'mode=mouse', see com option)
-'inport' and 'bus' (if present). To connect a mouse to a USB port, see the
-usb_uhci, 'usb_ohci', 'usb_ehci'
-or 'usb_xhci' options (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 (see headerbar
-and the 'toggle' option 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) or 'ctrl+alt' (like QEMU)
-or 'f12'.
-
-
-
-pci
-
-This defines the parameters to set up the Bochs PCI emulation:
-
-
-Examples:
-
- pci: enabled=1, chipset=i440fx # default if compiled with PCI support
- pci: enabled=1, chipset=i440fx, slot1=pcivga, slot2=ne2k, advopts=noacpi
- pci: enabled=1, chipset=i440bx, slot5=voodoo, slot1=e1000
-
-
-enabled
-
-If Bochs is compiled with PCI support, it is enabled by default.
-
-chipset
-
-Currently the chipsets i430FX, i440FX and i440BX (limited) are supported and
-the default is i440FX.
-
-slotX
-
-It is possible to specify the devices connected to PCI slots. Up to 5 slots
-are available. For combined PCI/ISA devices assigning to slot is mandatory
-if the PCI model should be emulated (cirrus, ne2k and pcivga). Setting up
-slot for PCI-only devices is also supported, but they are auto-assigned if
-not specified (e1000, es1370, pcidev, pcipnic, usb_ehci, usb_ohci, usb_xhci,
-voodoo). All device models except the network devices ne2k and e1000 can be
-used only once in the slot configuration. In case of the i440BX chipset, the
-slot #5 is the AGP slot. Currently only the 'voodoo' device can be assigned
-to AGP.
-
-advopts
-
-With the advanced PCI options, it is possible to control the behaviour of the
-PCI chipset. These options can be specified as comma-separated values.
-By default, the "Bochs i440FX" chipset enables the ACPI and HPET devices, but
-original i440FX doesn't support them. The options 'noacpi' and 'nohpet' make
-it possible to disable them. The option 'noagp' disables the incomplete AGP
-subsystem of the i440BX chipset.
-
-
-
-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.
-
-rtc_sync
-
-If this option is enabled together with the realtime synchronization,
-the RTC runs at realtime speed. This feature is disabled by default.
-
-time0
-
-Specifies the start (boot) time of the virtual machine. Use a time
-value as returned by the time(2) system call or a string as returned
-by the ctime(3) 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]
-
-Examples:
- clock: sync=none, time0=local # Now (localtime)
- clock: sync=slowdown, time0=315529200 # Tue Jan 1 00:00:00 1980
- clock: sync=none, time0="Mon Jan 1 00:00:00 1990" # 631148400
- clock: sync=realtime, time0=938581955 # Wed Sep 29 07:12:35 1999
- clock: sync=realtime, time0="Sat Jan 1 00:00:00 2000" # 946681200
- clock: sync=none, time0=1 # Now (localtime)
- clock: sync=none, time0=utc # Now (utc/gmt)
-
-Default value are sync=none, rtc_sync=0, time0=local
-
-
-
-
-
-cmosimage
-
-Example:
-
- cmosimage: file=cmos.img, rtc_init=time0
-
-This defines a binary image file with size 128 bytes 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.
-
-
-
-private_colormap
-
-Example:
-
- private_colormap: enabled=1
-
-Requests that the GUI creates and uses its 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.
-
-
-
-floppya/floppyb
-
-Examples:
-
-2.88M 3.5" media:
- floppya: 2_88=a:, status=inserted
-1.44M 3.5" media (write protected):
- floppya: 1_44=floppya.img, status=inserted, write_protected=1
-1.2M 5.25" media:
- floppyb: 1_2=/dev/fd0, status=inserted
-720K 3.5" media:
- floppya: 720k=/usr/local/bochs/images/win95.img, status=inserted
-auto-detect floppy media type:
- floppya: image=floppy.img, status=inserted
-use directory as VFAT media:
- floppya: 1_44=vvfat:path, status=inserted
-1.44M 3.5" floppy drive, no media:
- floppya: type=1_44
-
-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. To read from a disk
-image, write the name of the image file. In many operating systems Bochs can
-read directly from a raw floppy drive. For raw disk access, use the device
-name (Unix systems) or the drive letter and a colon (Windows systems).
-
-
-Following floppy media types are supported: 2_88, 1_44, 1_2, 720k, 360k, 320k, 180k,
-160k, as well as "image" to let Bochs auto-detect the type of floppy media (does only
-work with images, not with raw floppy drives). In that case the size must match
-one of the supported types.
-
-
-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.
-
-
-
-ata0, ata1, ata2, ata3
-
-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
-
-
-These options enable 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 above.
-
-
-
-
-ata0-master, ata0-slave, ata1-*, ata2-*, ata3-*
-
-Examples:
-
-ata0-master: type=disk, path=10M.img, mode=flat, cylinders=306, heads=4, spt=17, translation=none
-ata1-master: type=disk, path=2GB.cow, mode=vmware3, cylinders=5242, heads=16, spt=50, translation=echs
-ata1-slave: type=disk, path=3GB.img, mode=sparse, cylinders=6541, heads=16, spt=63, translation=auto
-ata2-master: type=disk, path=7GB.img, mode=undoable, cylinders=14563, heads=16, spt=63, translation=lba
-ata2-slave: type=cdrom, path=iso.sample, status=inserted
-
-
-
-
-
-This defines the type and characteristics of all attached ata devices:
-
-ata devices configuration options
-
-
-
-Option
-Comments
-Possible values
-
-
-
- type type of attached device [disk | cdrom]
- path path of the image
-
- mode
- image type, only valid for disks
- [flat | concat | dll | sparse | vmware3 | vmware4 | undoable | growing | volatile | vpc | vbox | vvfat ]
-
- cylinders only valid for disks
- heads only valid for disks
- spt only valid for disks
- status only valid for CD-ROMs [inserted | ejected]
- biosdetect type of biosdetection [auto | cmos | none]
- translation type of translation done by the BIOS (legacy int13), only for disks [none | lba | large | rechs | auto]
- model string returned by identify device ATA command
- journal optional filename of the redolog for undoable, volatile and vvfat disks
-
-
-
-
-
-
- You have to tell the type of the attached device. For Bochs 2.0 or later, it can be
- disk or cdrom.
-
-
-
-You have to point the "path" at a hard disk image file, CD-ROM iso file,
-or physical CD-ROM device.
-To create a hard disk image, try running bximage (see
-). 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 for safety reasons. In Windows, there is no easy way.
-
-
-
-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. Flat hard disk
-images from other projects might store additional information at the end of the
-file that makes this check fail. Only in this case it is safe to select "continue"
-when Bochs panics.
-
-
-
-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)
-
-
-Please see for a discussion on translation scheme.
-
-
-
-The mode option defines how the disk image is handled. Disks can be defined as:
-
-
-flat : one file flat layout
-
-
-concat : multiple files layout
-
-
-dll : developer's specific, through a DLL
-
-
-sparse : stackable, commitable, rollbackable
-
-
-vmware3 : vmware version 3 disk support
-
-
-vmware4 : vmware version 4 disk support (aka VMDK)
-
-
-undoable : read-only base file with commitable redolog
-
-
-growing : growing file
-
-
-volatile : read-only base file with volatile redolog
-
-
-vpc: fixed / dynamic size VirtualPC image
-
-
-vbox: fixed / dynamic size Oracle(tm) VM VirtualBox image (VDI version 1.1)
-
-
-vvfat: local directory appears as VFAT disk (with volatile redolog / optional commit)
-
-
-Please see for a discussion on disk modes.
-
-
-
-Default values are:
-
- mode=flat, biosdetect=auto, translation=auto, model="Generic 1234"
-
-
-
-
- The biosdetect option has currently no effect on the BIOS.
-
-
-
- Make sure the proper ata option is enabled when
- using a device on that ata channel.
-
-
-
-boot
-
-Examples:
-
- boot: floppy
- boot: cdrom, disk
- boot: network, disk
- boot: cdrom, floppy, disk
-
-This defines the boot sequence. 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.
-
-
-
-floppy_bootsig_check
-
-Example:
-
- floppy_bootsig_check: disabled=1
-
-This disables the 0xaa55 signature check on boot floppies
-The check is enabled by default.
-
-
-
-log
-
-Examples:
-
- log: bochsout.txt
- log: -
- log: /dev/tty (Unix only)
- log: /dev/null (Unix only)
- log: nul (win32 only)
-
-Give the path of the log file you'd like Bochs debug and misc. verbiage to be
-to be written to. If you don't use this option or set the filename to '-'
-the output is written to the console. If you really don't want it,
-make it "/dev/null" (Unix) or "nul" (win32). :^(
-
-
-
-logprefix
-
-Examples:
-
- logprefix: %t-%e-@%i-%d
- logprefix: %i%e%d
-
-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 current cpu eip (ignored in SMP configuration)
- %e : 1 character event type ('i'nfo, 'd'ebug, 'p'anic, 'e'rror)
- %d : 5 characters string of the device, between brackets
-
-
-
-Default is %t%e%d
-
-
-
-debug/info/error/panic
-
-Examples:
-
- debug: action=ignore, pci=report
- info: action=report
- error: action=report
- panic: action=ask
-
-
-During simulation, Bochs encounters certain events that the user might want to
-know about. These events are divided into four levels of importance: debug,
-info, error, and panic. Debug messages are usually only useful when writing
-Bochs code or when trying to locate a problem. There may be thousands of debug
-messages per second, so be careful before turning them on. Info messages tell
-about interesting events that don't happen that frequently. 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. Panic messages mean that
-Bochs cannot simulate correctly and should probably shut down.
-A panic can be a configuration problem (like a misspelled bochsrc line) or an
-emulation problem (like an unsupported video mode).
-
-
-
-The debug, info, error, and panic lines in the bochsrc control what Bochs will
-do when it encounters each type of event. The allowed actions are: fatal
-(terminate Bochs), ask (ask the user what to do), warn (show dialog with message
-and continue), report (print information to the console or log file), or ignore
-(do nothing). The recommended settings are listed in the sample above.
-
-
-
-It is also possible to specify the 'action' to do for each Bochs facility
-separately (e.g. crash on panics from everything except the CD-ROM, and only
-report those). See the log function module table
-for valid module names.
-
-
-
-
-The safest action for panics is "fatal" or "ask". If you are getting lots of
-panics and get tired of telling it to continue each time, 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 after a panic occurs.
-Please report panic messages to the &devlist; unless it is just a configuration
-problem like "could not find hard drive image."
-
-
-
-
-debugger_log
-
-Examples:
-
- debugger_log: debugger.out
- debugger_log: /dev/null (Unix only)
- 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 '-'.
-
-
-
-
-com[1-4]
-
-Examples:
-
- com1: enabled=1, mode=null
- com1: enabled=1, mode=mouse
- com1: enabled=1, mode=term, dev=/dev/ttyp9
- com2: enabled=1, mode=file, dev=serial.out
- com3: enabled=1, mode=raw, dev=com1
- com3: enabled=1, mode=socket-client, dev=localhost:8888
- com3: enabled=1, mode=socket-server, dev=localhost:8888
- com4: enabled=1, mode=pipe-client, dev=\\.\pipe\mypipe
- com4: enabled=1, mode=pipe-server, dev=\\.\pipe\mypipe
-
- This defines a serial port (UART type 16550A).
-
-
- When using the mode '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 of 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.
-
-
- When using socket* and pipe* (win32 only) modes Bochs becomes either
- socket/named pipe client or server. In client mode it connects to an already
- running server (if connection fails Bochs treats com port as not connected).
- In server mode it opens socket/named pipe and waits until a client application
- connects to it before starting simulation. This mode is useful for remote
- debugging (e.g. with gdb's "target remote host:port" command or windbg's command
- line option -k com:pipe,port=\\.\pipe\pipename). Socket modes use simple TCP
- communication, pipe modes use duplex byte mode pipes.
-
-
- Other serial modes are 'null' (no input/output), 'file' (output to a file
- specified as the 'dev' parameter and changeable at runtime), 'raw' (use the
- real serial port - partly implemented on win32), 'mouse' (standard serial
- mouse - requires mouse option setting
- 'type=serial', 'type=serial_wheel' or 'type=serial_msys').
-
-
-
-
-parport[1-2]
-
-Examples:
-
- parport1: enabled=1, file="parport.out"
- parport2: enabled=1, file="/dev/lp0"
- parport1: enabled=0
-
-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, "lpt1" on
-win32 platforms). The output file can be changed at runtime.
-
-
-
-
-sound
-
-Example for one driver (uses platform-default):
-
- sound: driver=default, waveout=/dev/dsp
-
-Example for different drivers:
-
- sound: waveoutdrv=sdl, waveindrv=alsa, midioutdrv=dummy
-
-This defines the lowlevel sound driver(s) for the wave (PCM) input / output
-and the MIDI output feature and (if necessary) the devices to be used.
-It can have several of the following properties. All properties are in the
-format sound: property=value.
-
-
-
- : This defines the driver to be used for the
- waveout feature. Possible values are 'file' (all wave data sent to file),
- 'dummy' (no output) and the platform-dependant drivers 'alsa', 'oss', 'osx',
- 'sdl' and 'win'.
-
-
-
- :
- This defines the device to be used for wave output (if necessary) or the
- output file for the 'file' driver.
-
-
-
- :
- This defines the driver to be used for the wavein feature.
- Possible values are 'dummy' (recording silence) and platform-dependent
- drivers 'alsa', 'oss', 'sdl' and 'win'.
-
-
-
- :
- This defines the device to be used for wave input (if necessary).
-
-
-
- :
- This defines the driver to be used for the MIDI output feature.
- Possible values are 'file' (all MIDI data sent to file), 'dummy' (no
- output) and platform-dependent drivers 'alsa', 'oss', 'osx' and 'win'.
-
-
-
- :
- This defines the device to be used for MIDI output (if necessary).
-
-
-
- :
- This defines the driver to be used for all sound features with one
- property. Possible values are 'default' (platform default) and all
- other choices described above. Overriding one or more settings with
- the specific driver parameter is possible.
-
-
-See for more information.
-
-
-
-
-speaker
-
-Example:
-
- speaker: enabled=1, mode=sound
-
-This defines the PC speaker output mode. In the 'sound' mode the beep
-is generated by the square wave generator which is a part of the
-lowlevel sound support. In this mode the 'volume' parameter can be used
-to set the output volume (0 - 15). The 'system' mode is only available on
-Linux and Windows. On Linux /dev/console is used for output and on Windows
-the Beep() function. The 'gui' mode forwards the beep to the related
-GUI methods (currently only used by the Carbon GUI).
-
-
-
-sb16
-
-Example:
-
- sb16: midimode=2, midifile=output.mid, wavemode=3, wavefile=output.wav
- loglevel=2, log=sb16.log, dmatimer=600000
-
-
-The example is wrapped onto several lines for formatting reasons, but it
-should all be on one line in the actual bochsrc file.
-
-
-This defines the Sound Blaster 16 emulation, see the developer documentation
-for more information. It can have several of the following properties. All properties
-are in the usual "property=value" format.
-
-
-
- :
- This optional property controls the presence of the SB16 emulation.
- The emulation is turned on unless this property is used and set to 0.
-
-
-
- :
- This parameter specifies what to do with the MIDI output.
-
- 0 = no output
- 1 = output to device specified with the sound option (system dependent)
- 2 = MIDI or raw data output to file (depends on file name extension)
- 3 = dual output (mode 1 and 2 at the same time)
-
-
-
-
- :
- This is the file where the midi output is stored (midimode 2 or 3).
-
-
-
- :
- This parameter specifies what to do with the PCM output.
-
- 0 = no output
- 1 = output to device specified with the sound option (system dependent)
- 2 = VOC, WAV or raw data output to file (depends on file name extension)
- 3 = dual output (mode 1 and 2 at the same time)
-
-
-
-
- :
- This is the file where the wave output is stored (wavemode 2 or 3).
-
-
-
- : The file to write the sb16 emulator messages to.
-
-
-
- :
-
- 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.
-
-
-
- :
- 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 value at runtime.
-
-
-
-
-
-es1370
-
-Examples:
-
- es1370: enabled=1, wavemode=1 # use 'sound' parameters
- es1370: enabled=1, wavemode=2, wavefile=output.voc # send output to file
-
-This defines the ES1370 sound emulation (recording and playback - except
-DAC1+DAC2 output at the same time). The parameter 'enabled' controls the
-presence of the device. The wave and MIDI output can be sent to device, file
-or both using the parameters 'wavemode', 'wavefile', 'midimode' and
-'midifile'. See the description of these parameters at the SB16 directive.
-
-
-
-
-ne2k
-
-The ne2k line configures an emulated NE2000-compatible Ethernet adapter,
-which allows the guest machine to communicate on the network. To disable
-the NE2000 just comment out the ne2k line.
-
-
-Examples:
-
-ne2k: ioaddr=0x300, irq=9, mac=b0:c4:20:00:00:00, ethmod=fbsd, ethdev=xl0
-ne2k: ioaddr=0x300, irq=9, mac=b0:c4:20:00:00:00, ethmod=fbsd, ethdev=en0 #macosx
-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=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"
-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: mac=b0:c4:20:00:00:01, ethmod=socket, ethdev=40000 # use localhost
-ne2k: card=0, mac=b0:c4:20:00:00:01, ethmod=socket, ethdev=mymachine:40000
-ne2k: mac=b0:c4:20:00:00:01, ethmod=slirp, script=slirp.conf, bootrom=ne2k_pci.rom
-
-CARD: This is the zero-based card number to configure with this ne2k config
-line. Up to 4 devices are supported now (0...3). If not specified, the
-following parameters apply to card #0.
-
-TYPE: This is the card type to emulate ("isa" or "pci"). If not specified,
-card #0 defaults to "pci" if assigned to a pci slot. For the additional cards
-the type parameter should be set up.
-
-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. You can also specify a network
-simulator or a module with no input/output ("null"). See the table below for
-currently supported values.
-
-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. The 'slirp' module uses this parameter to specify a config
-file for setting up an alternative IP configuration or additional features.
-The 'vnet' module also uses this parameter to specify a config file similar
-to slirp, but with only a few settings.
-
-BOOTROM: The bootrom value is optional, and is the name of the ROM image
-to load. Note that this feature is only implemented for the PCI version of
-the NE2000.
-
-
-
-
-The following table shows the available ethernet modules with description,
-whether the "ethdev" and "script" parameters are used or not and the Bochs
-version where this module was added.
-
-
Ethernet modules
-
-
-
- Module
- Description
- ethdev
- script
- Bochs version
-
-
-
-
- fbsd
- FreeBSD / OpenBSD packetmover.
-
- Yes
- No
- 1.0
-
-
- linux
- Linux packetmover - 'root' privileges required,
- no connection to the host machine.
-
- Yes
- No
- 1.3
-
-
- null
- Null packetmover. All packets are discarded, but logged to a
- few files.
-
- No
- No
- 1.0
-
-
- tap
- TAP packetmover.
-
- Yes
- Yes
- 1.4
-
-
- tuntap
- TUN/TAP packetmover - see
- Configuring and using a tuntap network interface.
-
- Yes
- Yes
- 2.0
-
-
- vde
- Virtual Distributed Ethernet packetmover.
-
- Yes
- Yes
- 2.2
-
-
- vnet
- ARP, ping (ICMP-echo), DHCP, DNS , FTP and TFTP simulation.
- The virtual host uses 192.168.10.1. DHCP assigns 192.168.10.15 to the guest.
- The FTP and TFTP servers use the 'ethdev' value for the root directory.
- TFTP doesn't overwrite files, DNS for server and client only.
-
- Yes, for FTP and TFTP root
- Yes, for log file name
- 2.2
-
-
- slirp
- Built-in Slirp support with DHCP / TFTP servers. Adds user mode
- networking to Bochs - see Using the 'slirp'
- networking module. The 'script' parameter can be used to set up
- an alternative IP configuration or additional features. The TFTP server
- uses the 'ethdev' value for the root directory and doesn't overwrite files.
-
- Yes, for TFTP root
- Yes, for Slirp config
- 2.6.5
-
-
- socket
- Connect up to 6 Bochs instances on the same or other machine
- with external program 'bxhub' (simulating an ethernet hub). It provides
- the same services as the 'vnet' module and assigns IP addresses like
- 'slirp' (10.0.2.x) (see Using the 'socket'
- networking module).
-
- Yes, for base UDP port and (optional) the host to connect
- No
- 2.6.9
-
-
- win32
- Win32 packetmover - WinPCap driver required.
-
- Yes
- No
- 1.3
-
-
-
-
-
-
-pcipnic
-
-Example:
-
- pcipnic: enabled=1, mac=b0:c4:20:00:00:00, ethmod=vnet
-
-To support the Bochs/Etherboot pseudo-NIC, Bochs must be compiled with the
- configure option. It accepts the same syntax (for mac,
-ethmod, ethdev, script, bootrom) and supports the same networking modules as the
-NE2000 adapter.
-
-
-
-e1000
-
-Example:
-
- e1000: enabled=1, mac=52:54:00:12:34:56, ethmod=slirp, script=slirp.conf
-
-To support the Intel(R) 82540EM Gigabit Ethernet adapter, Bochs must be compiled
-with the configure option. It accepts the same syntax
-(for mac, ethmod, ethdev, script, bootrom) and supports the same networking modules
-as the NE2000 adapter.
-
-
-
-usb_uhci
-
-Examples:
-
- usb_uhci: port1=mouse, port2=disk, options2="path:usbstick.img"
- usb_uhci: port1=hub, options1="ports:6, pcap:outfile.pcap"
- usb_uhci: port2=disk, options2="path:undoable:usbdisk.img, journal:u.redolog"
- usb_uhci: port2=disk, options2=""path:usbdisk2.img, sect_size:1024"
- usb_uhci: port2=disk, options2="path:vvfat:vvfat, debug, speed:full"
- usb_uhci: port2=cdrom, options2="path:image.iso"
- usb_uhci: port1=printer, options1="file:printdata.bin"
- usb_uhci: port2=floppy, options2="path:vvfat:diskette, model:teac"
-
-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', 'keyboard',
-'disk', 'cdrom', 'floppy, ''hub' and 'printer').
-See for more information on each device setting.
-
-
-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. If the
-keyboard is selected, all key events are sent to the USB device.
-
-
-To connect a disk image as a USB hardisk you can use the 'disk' device. Use
-the 'path' option in the optionsX parameter to
-specify the path to the image separated with a colon. To use other disk image
-modes similar to ATA disks the syntax 'path:mode:filename' must be used (see
-below).
-
-
-To emulate a USB CD-ROM you can use the 'cdrom' device and the path to an
-ISO image or raw device name can be set with the 'path' option in the
-optionsX parameter also separated with a colon. An
-option to insert/eject media is available in the runtime configuration.
-
-
-To emulate a USB floppy, you can use the 'floppy' device and the path to a
-floppy image can be set with the 'path' option in the optionsX
-parameter separated with a colon. To use the VVFAT image mode similar to the
-legacy floppy the syntax 'path:vvfat:directory' must be used (see below).
-An option to insert/eject media is available in the runtime configuration.
-A well-known, somewhat older, but still widely used Operating System must have
-the Vendor ID as an TEAC external drive. If the VendorID is not the TEAC id,
-this operating system doesn't know what to do with the drive. Therefore, use
-the optionsX="model:teac" option in the bochsrc.txt
-file to set this model. If you do not, a default model will be used.
-
-
-
-The device name 'hub' connects an external hub with a maximum of 8 ports (default: 4)
-to the root hub. To specify the number of ports you have to use the 'ports'
-option in the optionsX parameter with the value
-separated with a colon. Connecting devices to the external hub ports is only
-available in the runtime configuration.
-
-
-The device 'printer' emulates the HP Deskjet 920C printer. The PCL data is
-sent to a file specified in the 'file' option with the optionsX
-parameter. The current code appends the PCL code to the file if the file already
-existed. The output file can be changed at runtime.
-
-
-The optionsX parameter can also be used to assign
-specific options to the device connected to the corresponding USB port.
-The option 'speed' can be used to set the speed reported by device ('low',
-'full', 'high' or 'super'). The available speed choices depend on both HC and
-device. The option 'debug' turns on debug output for the device at connection
-time. The option 'pcap' turns on packet logging in PCAP format. For the USB
-'disk' device the optionsX parameter can be used to
-specify an alternative redolog file (journal) of some image modes. For 'vvfat'
-mode USB disks the optionsX parameter can be used to
-specify the disk size (range 128M ... 128G). If the size is not specified, it
-defaults to 504M. For the USB 'floppy' device the optionsX
-parameter can be used to specify an alternative device ID to be reported. Currently
-only the model "teac" is supported (can fix hw detection in some guest OS). The USB
-floppy also accepts the parameter "write_protected" with valid values 0 and 1 to select
-the access mode (default is 0).
-
-
-For USB disk image emulation using the 'disk' or 'cdrom' type, an optionsX
-parameter of 'proto:bbb' or 'proto:uasp' may be used. The former tells Bochs to
-use the 'Bulk/Bulk/Bulk' protocol, aka the 'Bulk only' protocol. This is the
-standard protocol that most USB disks will use, and is used by default. The latter
-option tells Bochs to use the newer 'USB Attached SCSI' protocol, used on newer,
-more modern USB disks. If the 'proto:' parameter is not given, Bochs will default
-to the 'bbb' protocol. See the 'ehci' and 'xhci' examples below.
-
-
-PCI support must be enabled to use USB UHCI.
-
-
-The BBB protocol must have a speed option of 'full', 'high', or 'super'. The UASP
-protocol can only be used on high- and super-speed devices, therefore must only be
-used with the 'usb_ehci' and 'usb_xhci' configuration options. Full-speed devices
-will default to the BBB protocol.
-
-
-Specifying the UASP option does not guarantee the Guest will use this interface.
-The Bochs emulation still gives both options. It is up to the Guest to choose which
-protocol to use. A modern, widely used OS will default to BBB for various EHCI
-controllers, and controllers that are known to have issues with this type of protocol.
-
-
-The USB emulation now checks many items for accuracy. For example, it will monitor the
-toggle bit in a Transfer Descriptor. If it is not correct, the TD will not be executed.
-If your code use to work in a Bochs emulation, but now it does not, check your toggle
-bit implementation. (This particular check can be disabled using the HANDLE_TOGGLE_CONTROL
-define in 'usb_common.h') Other checks for accuracy are checks for the 'value' and 'index'
-fields of a SETUP packet. For example, a particular request may specify that the 'value'
-field must be zero. Bochs now checks for this. Other checks include the Command Length
-field in a SCSI command request, valid values in an xHCI 'slot' and 'endpoint' context,
-as well as other checks.
-
-
-
-usb_ohci
-
-Example:
-
- usb_ohci: enabled=1, port1=printer:printdata.bin
-
-This option controls the presence of the USB OHCI host controller with a
-2-port hub. The portX parameter accepts the same device types with the same
-syntax as the UHCI controller (see the usb_uhci option).
-The optionsX parameter is also available on OHCI.
-
-
-usb_ehci
-
-Example:
-
- usb_ehci: enabled=1, port1=tablet, options1="speed:high"
- usb_ehci: enabled=1, port1=disk, options1="speed:high, path:hdd.img, proto:bbb"
- usb_ehci: enabled=1, port1=disk, options1="speed:high, path:hdd.img, proto:uasp"
- usb_ehci: enabled=1, port1=cdrom, options1="speed:high, path:bootcd.iso, proto:bbb"
- usb_ehci: enabled=1, port1=cdrom, options1="speed:high, path:bootcd.iso, proto:uasp"
-
-This option controls the presence of the USB EHCI host controller with a
-6-port hub. The portX parameter accepts the same device types with the same
-syntax as the UHCI controller (see the usb_uhci option).
-The optionsX parameter is also available on EHCI.
-
-
-usb_xhci
-
-Example:
-
- usb_xhci: enabled=1, model="uPD720202", n_ports=4
- usb_xhci: enabled=1, port1="disk:usbdisk.img" # defaults to the BBB protocol
- usb_xhci: port1=disk, options1="speed:super, path:usbdisk.img, proto:uasp"
- usb_xhci: port1=disk, options1="speed:super, path:usbdisk.img, proto:bbb"
- usb_xhci: port1=cdrom, options1="speed:super, path:bootcd.iso, proto:uasp"
- usb_xhci: port3=disk, options3="speed:high, path:usbdisk.img, proto:uasp"
- usb_xhci: port3=disk, options3="speed:high, path:usbdisk.img, proto:bbb"
- usb_xhci: port3=floppy, options3="speed:full, path:floppy.img, model:teac"
- usb_xhci: port3=tablet, options3="speed:low"
-
-This option controls the presence of the USB xHCI host controller with a default 4-port
-hub. The portX parameter accepts similar device types with a similar syntax as
-the UHCI controller (see the usb_uhci option).
-The optionsX parameter is also available on xHCI.
-
-
-The xHCI supports up to two models, the NEC uPD720202 and the NEC uPD720201. The former
-defaults to a 4-port hub (two physical sockets), while the latter defaults to an 8-port hub
-(four physical sockets). This was added for future expansion. The 'n_ports=n'
-parameter can be given to override the count of ports used. This count must be at least two
-and not more than USB_XHCI_PORTS_MAX (currently 10), and must be
-an even numbered count.
-
-
-No matter the count of ports, the first half (ports 1, 2, 3, and 4 on an 8-port hub) will
-be the USB3 ports (register sets), while the second half (ports 5, 6, 7, and 8) will be the
-USB2 ports (register sets). When the 'optionsX="speed:" option is
-used, it must contain 'super' for the first half ports (1, 2, 3, and 4) and the second half
-(5, 6, 7, and 8) must use a speed of 'low', 'full', or 'high'.
-
-
-On an xHCI, the number of ports used is the number of port register sets, one set for the USB3
-protocol and a paired set for the USB2 protocol. An 'n_ports=' specification of 4 defines
-two physical sockets.
-
-
-
-pcidev
-
-Example:
-
- pcidev: vendor=0xbabe, device=0x2bad
-
-Enables the mapping of a host PCI hardware device within the virtual PCI
-subsystem of the Bochs x86 emulator. The arguments
-vendor and device
-should contain the PCI vendor ID respectively the PCI
-device ID of the host PCI device you want to map within Bochs.
-
-
-
-The PCI device mapping is still in a very early stage of development and thus it is very experimental.
-This feature requires Linux as a host operating system.
-
-
-
-Besides the pcidev config line you will need to load
-a pcidev kernel module within your Linux host OS. This kernel module is
-located in the bochs/host/linux/pcidev/ directory.
-
-
-
-
-gdbstub
-
-Example:
-
- gdbstub: enabled=1, port=1234, text_base=0, data_base=0, bss_base=0
-
-Default:
-
- gdbstub: enabled=0
-
-This enables the GDB stub. See .
-
-
-
-magic_break
-
-Example:
-
- magic_break: enabled=1
-
-This enables the "magic breakpoint" feature when using the debugger.
-The useless cpu instruction XCHG BX, BX causes Bochs to enter the
-debugger mode. This might be useful for software development.
-
-
-
-debug_symbols
-
-Example:
-
- debug_symbols: file=mysymbols.sym
- debug_symbols: file=mysymbols.sym, offset=0x1000
-
-This loads symbols from the specified file for use in Bochs' internal debugger.
-Symbols are loaded into global context. This is equivalent to issuing ldsym
-debugger command at start up.
-
-
-
-port_e9_hack
-
-Example:
-
- port_e9_hack: enabled=1
-
-The 0xE9 port doesn't exists in normal ISA architecture. However, we
-define a convention here, to display on the console of the system running
-Bochs anything that is written to it. The idea is to provide debug output
-very early when writing BIOS or OS code for example, without having to
-bother with setting up a serial port or etc. Reading from port 0xE9 will
-will return 0xe9 to let you know if the feature is available. Leave
-this 0 unless you have a reason to use it.
-
-
-
-
-
-How to write your own keymap table
-
-Christophe Bothamy wrote the keymapping code for Bochs, and provided this
-documentation for how to create new keymaps. Keymapping was first
-implemented for X windows only, so there are many references to X-specific
-values in this section. In Bochs 2.0 keymapping is also available for SDL
-(Linux port) and wxWidgets (wxGTK port).
-
-
- The standard US Keyboard looks like this:
-
- -------------------------------------------
- Top row Esc F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12
- -------------------------------------------
- 2nd row ` 1 2 3 4 5 6 7 8 9 0 - = \ Back
- -------------------------------------------
- 3rd row Tab Q W E R T Y U I O P [ ] Enter
- -------------------------------------------
- 4rd row Caps A S D F G H J K L ; '
- -------------------------------------------
- 5rd row lShift l\ Z X C V B N M , . / rShift
- -------------------------------------------
- 6rd row lCtrl lAlt Space rAlt rCtrl
- -------------------------------------------
-
-
-
-Each key of the US keyboard maps to a Bochs constant named
-BX_KEY_symbol. You can find the current list of
-BX_KEY_symbol in
-the BX_KEY table, below. Please note that
-there is only one BX_KEY_symbol for each physical
-key.
-
-
-
-Now, for each key of the US keyboard, look at which symbols you can type on your
-real keyboard. Each symbol maps to a X-windows
-XK_symbol constant. In
-X11/keysymdef.h, you will find the list of all possible
-XK_symbol on your system. Alternatively, you can
-use a small utility called "xev" that prints out the symbol names of a pressed
-key. Note that the symbol name given by xev does not contain the XK_ prefix.
-Don't forget to add a line for every symbol you can type on each key. For the
-key BX_KEY_A, you can type both lowercase 'a' and uppercase 'A', so you would
-need two different entries.
-
-
-
-You can then create your own map file. Keymap files are found in the
-"gui/keymaps" directory in the source code, or in the "keymaps" directory in
-binary releases. Look at the existing keymap file as an example, and create a
-file containing one line for each symbol. The first column tells what key or
-combination of keys can be used to produce a given symbol. The second column
-is the ASCII equivalent for that symbol, or a special keyword (none, space,
-return, tab, backslash, or apostrophe). The third column is the X windows
-keysym for that symbol.
-
-
-
-
-For example :
-
-BX_KEY_0 '0' XK_0
-BX_KEY_1 '1' XK_1
-BX_KEY_2 '2' XK_2
-BX_KEY_0+BX_KEY_SHIFT_L ')' XK_parenright
-BX_KEY_1+BX_KEY_SHIFT_L '!' XK_exclam
-BX_KEY_2+BX_KEY_SHIFT_L '@' XK_at
-BX_KEY_A 'a' XK_a
-BX_KEY_B 'b' XK_b
-BX_KEY_A+BX_KEY_SHIFT_L 'A' XK_A
-BX_KEY_B+BX_KEY_SHIFT_L 'B' XK_B
-BX_KEY_TAB tab XK_Tab
-BX_KEY_ENTER return XK_Return
-BX_KEY_F1 none XK_F1
-BX_KEY_F2 none XK_F2
-BX_KEY_F3 none XK_F3
-
-
-
-
-Now that there are several keymap files in the Bochs distribution, it is
-easiest to copy an existing keymap and follow the examples you see. When it
-works, be sure to send it to the mailing list or post it on Source Forge so
-that we can include it in the next release. You may need to look up some of
-your country specific X11 symbols in X11/keysymdef.h.
-
-
-
BX_KEY constants
-
-
-
- BX_KEY constant
- Keyboard Symbol
-
-
-
-
-BX_KEY_CTRL_L left Ctrl
-BX_KEY_SHIFT_L left Shift
-BX_KEY_F1 F1
-BX_KEY_F2 F2
-BX_KEY_F3 F3
-BX_KEY_F4 F4
-BX_KEY_F5 F5
-BX_KEY_F6 F6
-BX_KEY_F7 F7
-BX_KEY_F8 F8
-BX_KEY_F9 F9
-BX_KEY_F10 F10
-BX_KEY_F11 F11
-BX_KEY_F12 F12
-BX_KEY_CTRL_R right Ctrl
-BX_KEY_SHIFT_R right Shift
-BX_KEY_CAPS_LOCK CapsLock
-BX_KEY_NUM_LOCK NumLock
-BX_KEY_ALT_L left Alt
-BX_KEY_ALT_R right Alt
-BX_KEY_A A
-BX_KEY_B B
-BX_KEY_C C
-BX_KEY_D D
-BX_KEY_E E
-BX_KEY_F F
-BX_KEY_G G
-BX_KEY_H H
-BX_KEY_I I
-BX_KEY_J J
-BX_KEY_K K
-BX_KEY_L L
-BX_KEY_M M
-BX_KEY_N N
-BX_KEY_O O
-BX_KEY_P P
-BX_KEY_Q Q
-BX_KEY_R R
-BX_KEY_S S
-BX_KEY_T T
-BX_KEY_U U
-BX_KEY_V V
-BX_KEY_W W
-BX_KEY_X X
-BX_KEY_Y Y
-BX_KEY_Z Z
-BX_KEY_0 0
-BX_KEY_1 1
-BX_KEY_2 2
-BX_KEY_3 3
-BX_KEY_4 4
-BX_KEY_5 5
-BX_KEY_6 6
-BX_KEY_7 7
-BX_KEY_8 8
-BX_KEY_9 9
-BX_KEY_ESC Esc
-BX_KEY_SPACE SpaceBar
-BX_KEY_SINGLE_QUOTE '
-BX_KEY_COMMA ,
-BX_KEY_PERIOD .
-BX_KEY_SLASH /
-BX_KEY_SEMICOLON ;
-BX_KEY_EQUALS =
-BX_KEY_LEFT_BRACKET [
-BX_KEY_BACKSLASH \
-BX_KEY_RIGHT_BRACKET ]
-BX_KEY_MINUS -
-BX_KEY_GRAVE `
-BX_KEY_BACKSPACE BackSpace
-BX_KEY_ENTER Enter
-BX_KEY_TAB Tab
-BX_KEY_LEFT_BACKSLASH left \
-BX_KEY_PRINT PrintScreen
-BX_KEY_SCRL_LOCK ScrollLock
-BX_KEY_PAUSE Pause
-BX_KEY_INSERT Ins
-BX_KEY_DELETE Del
-BX_KEY_HOME Home
-BX_KEY_END End
-BX_KEY_PAGE_UP PageUo
-BX_KEY_PAGE_DOWN PageDown
-BX_KEY_KP_ADD Numeric Keypad +
-BX_KEY_KP_SUBTRACT Numeric Keypad -
-BX_KEY_KP_END Numeric Keypad 1
-BX_KEY_KP_DOWN Numeric Keypad 2
-BX_KEY_KP_PAGE_DOWN Numeric Keypad 3
-BX_KEY_KP_LEFT Numeric Keypad 4
-BX_KEY_KP_5 Numeric Keypad 5
-BX_KEY_KP_RIGHT Numeric Keypad 6
-BX_KEY_KP_HOME Numeric Keypad 7
-BX_KEY_KP_UP Numeric Keypad 8
-BX_KEY_KP_PAGE_UP Numeric Keypad 9
-BX_KEY_KP_INSERT Numeric Keypad 0
-BX_KEY_KP_DELETE Numeric Keypad .
-BX_KEY_KP_ENTER Numeric Keypad Enter
-BX_KEY_KP_MULTIPLY Numeric Keypad *
-BX_KEY_KP_DIVIDE Numeric Keypad /
-BX_KEY_UP UpArrow
-BX_KEY_DOWN DownArrow
-BX_KEY_LEFT LeftArrow
-BX_KEY_RIGHT RightArrow
-BX_KEY_WIN_L Left Windows
-BX_KEY_WIN_R Right Windows
-BX_KEY_MENU Menu
-BX_KEY_ALT_SYSREQ Alt-Sysreq
-BX_KEY_CTRL_BREAK Ctrl-Break
-BX_KEY_INT_BACK Internet - back
-BX_KEY_INT_FORWARD Internet - forward
-BX_KEY_INT_STOP Internet - stop
-BX_KEY_INT_MAIL Internet - mail
-BX_KEY_INT_SEARCH Internet - search
-BX_KEY_INT_FAVInternet - favorites
-BX_KEY_INT_HOME Internet - home
-BX_KEY_POWER_MYCOMP Powerkeys - my computer
-BX_KEY_POWER_CALC Powerkeys - calculator
-BX_KEY_POWER_SLEEP Powerkeys - sleep
-BX_KEY_POWER_POWER Powerkeys - power
-BX_KEY_POWER_WAKE Powerkeys - wake
-
-
-
-
-
-
-
-
-Using Bochs
-
-After starting Bochs either from the command prompt or the OS shell, the following
-steps are done before the simulation is running.
-
-parse command line (except bochsrc options)
-load selected config file (bochsrc) or search for the default one
-parse remaining command line options (bochsrc syntax)
-initialize configuration interface
-enter start menu / dialog (unless quick start mode is enabled)
-initialize all parts of the simulator
-enter debugger prompt / dialog (if present)
-enter the simulation loop
-
-
-
-During simulation, Bochs usually generates more or less log output. By default, it
-is sent to the console, otherwise to the specified log file.
-The amount of output can be controlled with the log options
-in bochsrc, the start menu and the runtime configuration.
-
-
-Under certain conditions Bochs can cause a panic
-and usually asks the user what to do. If such a panic happens during startup, it is
-mostly a configuration or permission problem and we recommend to quit Bochs and to
-review the bochsrc options used.
-
-
-To quit the simulation, the "power" button in the Bochs headerbar
-should be used, unless the guest OS has the capability to turn off the computer (APM or ACPI).
-
-
-If a Bochs runtime issue cannot be fixed by configuration changes and it has not yet
-been reported in the &devlist; or the SF trackers for Bochs, it should be reported in
-the mailing list or the SF bug tracker for the Bochs project.
-
-
-Command line arguments
-
-The following table shows the arguments that can be used on the command line.
-For other arguments, see section bochsrc.
-
-command line arguments
-
-
-
-Argument
-Description
-
-
-
-
- -q
- quick start (skip configuration interface)
-
-
- -f filename
- specify configuration file
-
-
- -log filename
- specify Bochs log file
-
-
- -dbglog filename
- specify Bochs internal debugger log file
-
-
- -n
- don't try to load a configuration file
-
-
- -benchmark N
- run Bochs in benchmark mode for N millions of emulated ticks
-
-
- -dumpstats N
- dump Bochs stats every N millions of emulated ticks
-
-
- -r path
- specify path for restoring state
-
-
- -unlock
- unlock Bochs images leftover from previous session
-
-
- -noconsole
- disable console window (Windows only)
-
-
- --help
- display help message and exit
-
-
- --help features
- display available features / devices and exit
-
-
- --help cpu
- display supported CPU models and exit (CPU level > 4 only)
-
-
-
-
-
-
-These arguments are handled directly after starting Bochs. The next step is to load
-a default or specified configuration file (unless disabled with -n). Then the rest
-of the command line (bochsrc options) is parsed. This is done after reading the
-configuration file so that the command line arguments can override the settings
-from the file.
-
-
-
-Search order for the configuration file
-
-If no configuration file is specified on the command line and config file loading
-is not disabled, Bochs searches for a default configuration file. This is the search order:
-
-
-
-.bochsrc in the current directory
-
-
-
-
-bochsrc in the current directory
-
-
-
-
-bochsrc.txt in the current directory
-
-
-
-
-(win32 only) bochsrc.bxrc in the current directory
-
-
-
-
-(Unix only) .bochsrc in the user's home directory
-
-
-
-
-(Unix only) bochsrc in the /etc directory
-
-
-
-
-
-The configuration interface 'textconfig'
-
-The configuration interface 'textconfig' is the text mode version of the Bochs
-configuration system. It is a series of menus (using stdin/stdout) that allows
-you to edit all the settings that control Bochs' behavior. If you do not write
-a config_interface line, Bochs will choose it as the default for you (unless Bochs
-is compiled for Win32 or wxWidgets only). If the GUI console is available at
-runtime, textconfig switches the display to text mode 80 x 25 and restores the
-simulation screen afterwards.
-
-
-It consists of these three parts:
-
-the start menu
-the headerbar buttons
-the runtime configuration
-
-
-
-On Win32 (without wxWidgets) the default configuration interface 'win32config' is
-very similar, but it presents GUI dialogs instead of text menus.
-
-The start menu
-
-If you start Bochs without the quickstart argument (-q), the Bochs configuration
-main menu appears:
-
-------------------------------
-Bochs Configuration: Main Menu
-------------------------------
-
-This is the Bochs Configuration Interface, where you can describe the
-machine that you want to simulate. Bochs has already searched for a
-configuration file (typically called bochsrc.txt) and loaded it if it
-could be found. When you are satisfied with the configuration, go
-ahead and start the simulation.
-
-You can also start Bochs with the -q option to skip these menus.
-
-1. Restore factory default configuration
-2. Read options from...
-3. Edit options
-4. Save options to...
-5. Restore the Bochs state from...
-6. Begin simulation
-7. Quit now
-
-Please choose one: [5]
-
-
-
-Here you can load, edit and save the configuration and finally start the simulation.
-It is possible to start Bochs without a config file and to edit all the settings using
-the item "Edit options". Don't forget to save the configuration if you want to use this
-setup for another Bochs session.
-
-
-
-The Bochs headerbar
-
-
-
-
-The headerbar appears on top of the Bochs simulation window. Here you can control the
-behavoiur of Bochs at runtime if you click on one of these buttons:
-
-
-floppy buttons
-
- Here you can toggle the status of the floppy media (inserted/ejected). Bochs for
- win32 presents you a small dialog box for changing the floppy image. You can
- setup floppy drives using floppya/floppyb option.
-
-
-
-CD-ROM button
-
- Here you can toggle the media status of the first CD-ROM drive (inserted/ejected).
- CD-ROM drives can be set up using ata(0-3)-master/-slave option.
- On some platforms this button brings a up a small dialog box for changing the
- CD-ROM image.
-
-
-
-mouse button
-
- Here you can enable the creation of mouse events by the host. Once mouse
- events are captured, you cannot reach the button anymore, in order to disable
- capturing again. By default, you can enable and disable the mouse capture pressing
- the CTRL key and the third (middle) mouse button. See the mouse option
- parameter 'toggle' for other methods to toggle the mouse capture.
-
-
- Changing the mouse capture at runtime is not supported by all display libraries,
- but it is already present on RFB, SDL, SDL2, VNCSRV, Win32, wxWidgets and X11.
-
-
- Support for 2 button mouse to toggle the capture mode not yet complete - using
- another toggle method is recommended in that case.
-
-
-
-user button
-
- Press this button if you want to send the keyboard shortcut defined with the
- user_shortcut parameter of the keyboard
- option to the guest. Depending on the used display_library option,
- it may even be possible to edit the shortcut before sending it.
-
-
-
-copy button
-The text mode screen text can be exported to the clipboard after pressing this
-button. The button has no effect in graphics mode.
-
-
-paste button
-Text in the clipboard can also be pasted, through Bochs, to the
-guest OS, as simulated keystrokes. Keyboard mapping must be enabled to make this
-feature work.
-
-
-snapshot button
-Press this button if you want to save a snapshot of the Bochs screen. All
-text and graphics modes are now supported. If GUI dialogs are supported (e.g. on
-win32) Bochs presents you a "Save as..." dialog box to specify the filename. In
-text modes the formats BMP and TXT are supported depending on file extension.
-Platforms without GUI dialogs are using the fixed filenames "snapshot.txt" or
-"snapshot.bmp".
-
-
-config button
-This button stops the Bochs simulation and starts the runtime configuration.
-(see below).
-
-
-reset button
-Press this button to trigger a hardware reset.
-
-
-suspend button
-Press this button to save current simulation state to a disk. The simulation
-could be restored back using bochs -r command. For more details read the
-Save and restore simulation section.
-
-
-power button
-This button stops the simulation and quits Bochs.
-
-
-
-
-Some of these features may not be implemented or work different on your host platform.
-
-
-
-Command mode
-
-When using 'sdl', 'sdl2', 'win32' or 'x' as the display_library, the
-option 'cmdmode' enables the "command mode" support. If enabled, pressing the F7
-key will enter 'command mode' (shown in the info item of the statusbar);
-the next key that is pressed will exit command-mode. When in command-mode,
-if the pressed key is in the list below, the corresponding action will be
-performed. With the exception of F7, any key pressed while in command-mode
-will not be received by the OS running in Bochs.
-
-
-
Supported keys
-
-
-
- Key
- Action
-
-
-
-
- a
- Press the Floppy A button
-
-
- b
- Press the Floppy B button
-
-
- c
- Press the Copy button
-
-
- SHIFT + c
- Press the Config button
-
-
- f
- Toggle windowed / fullscreen mode (sdl, sdl2 and win32 only)
-
-
- p
- Press the Paste button
-
-
- SHIFT + p
- Press the Power button
-
-
- r
- Press the Reset button
-
-
- s
- Press the Snapshot button
-
-
- SHIFT + s
- Press the Suspend button
-
-
- u
- Press the User button
-
-
- F7
- Send F7 keypress to emulation
-
-
-
-
-
-
-In fullscreen mode (sdl, sdl2, win32) some handlers do not bring up a dialog
-box. The floppy buttons just toggle the status, the snapshot feature uses the
-hardcoded file name and the user button sends the configured shortcut.
-
-
-The runtime configuration
-
-If you want to change certain settings at runtime, you have to press the "config" button in
-the headerbar. The simulation stops and the runtime menu appears on the console window / xterm
-or the Bochs GUI console (if available).
-
----------------------
-Bochs Runtime Options
----------------------
-1. Floppy disk 0: /dev/fd0, size=1.44M, inserted
-2. Floppy disk 1: floppyb.img, size=1.44M, inserted
-3. 1st CD-ROM: (master on ata1) /dev/cdrom, ejected
-4. 2nd CD-ROM: (slave on ata1) /dev/cdrecorder, ejected
-5. 3rd CD-ROM: (not present)
-6. 4th CD-ROM: (not present)
-7. (not implemented)
-8. Log options for all devices
-9. Log options for individual devices
-10. Instruction tracing: off (doesn't exist yet)
-11. USB runtime options
-12. Misc runtime options
-13. Continue simulation
-14. Quit now
-
-Please choose one: [13]
-
-
-
-In the runtime configuration you can change the floppy/CD-ROM image or device,
-change the log options or adjust some other settings. If you have trouble with
-a specific device, you can change the log options for this device only to get
-more information (e.g. report debug messages).
-
-
-
-
-Pre-defined CPU models
-
-If Bochs is compiled with cpu level 5 or higher the CPUID opcode is supported
-and it can return some information about the cpu model and its features. When
-using a pre-defined CPU model in Bochs the features reported by CPUID are set up
-according to the model's specification. The following table shows all available
-CPU models with a short description. The amount of choices depends on the CPU
-features enabled at compile time (3rd column).
-
-
Bochs CPU models
-
-
-
- Value
- Description
- Required Features
-
-
-
-
- bx_generic
- Default Bochs CPU configured with CPUID option
- cpu level 5
-
-
- pentium
- Intel Pentium (P54C)
- cpu level 5
-
-
- pentium_mmx
- Intel Pentium MMX
- cpu level 5
-
-
- amd_k6_2_chomper
- AMD-K6(tm) 3D processor (Chomper)
- cpu level 5
-
-
- p2_klamath
- Intel Pentium II (Klamath)
- cpu level 6
-
-
- p3_katmai
- Intel Pentium III (Katmai)
- cpu level 6
-
-
- p4_willamette
- Intel(R) Pentium(R) 4 (Willamette)
- cpu level 6
-
-
- core_duo_t2400_yonah
- Intel(R) Core(TM) Duo CPU T2400 (Yonah)
- cpu level 6
-
-
- atom_n270
- Intel(R) Atom(TM) CPU N270
- cpu level 6
-
-
- p4_prescott_celeron_336
- Intel(R) Celeron(R) 336 (Prescott)
- cpu level 6, x86-64
-
-
- athlon64_clawhammer
- AMD Athlon(tm) 64 Processor 2800+ (Clawhammer)
- cpu level 6, x86-64
-
-
- athlon64_venice
- AMD Athlon(tm) 64 Processor 3000+ (Venice)
- cpu level 6, x86-64
-
-
- turion64_tyler
- AMD Turion(tm) 64 X2 Mobile TL-60 (Tyler)
- cpu level 6, x86-64
-
-
- phenom_8650_toliman
- AMD Phenom X3 8650 (Toliman)
- cpu level 6, x86-64
-
-
- core2_penryn_t9600
- Intel Mobile Core 2 Duo T9600 (Penryn)
- cpu level 6, x86-64
-
-
- corei5_lynnfield_750
- Intel(R) Core(TM) i5 750 (Lynnfield)
- cpu level 6, x86-64
-
-
- corei5_arrandale_m520
- Intel(R) Core(TM) i5 M 520 (Arrandale)
- cpu level 6, x86-64
-
-
- corei7_sandy_bridge_2600k
- Intel(R) Core(TM) i7-2600K (Sandy Bridge)
- cpu level 6, x86-64, avx
-
-
- zambezi
- AMD FX(tm)-4100 Quad-Core Processor (Zambezi)
- cpu level 6, x86-64, avx
-
-
- trinity_apu
- AMD A8-5600K APU (Trinity)
- cpu level 6, x86-64, avx
-
-
- ryzen
- AMD Ryzen 7 1700
- cpu level 6, x86-64, avx
-
-
- corei7_ivy_bridge_3770k
- Intel(R) Core(TM) i7-3770K CPU (Ivy Bridge)
- cpu level 6, x86-64, avx
-
-
- corei7_haswell_4770
- Intel(R) Core(TM) i7-4770 CPU (Haswell)
- cpu level 6, x86-64, avx
-
-
- broadwell_ult
- Intel(R) Processor 5Y70 CPU (Broadwell)
- cpu level 6, x86-64, avx
-
-
- corei7_skylake_x
- Intel(R) Core(TM) i7-7800X CPU (Skylake)
- cpu level 6, x86-64, avx
-
-
- corei3_cnl
- Intel(R) Core(TM) i3-8121U CPU (Cannonlake)
- cpu level 6, x86-64, avx
-
-
- corei7_icelake_u
- QuadCore Intel Core i7-1065G7 (IceLake)
- cpu level 6, x86-64, avx
-
-
- tigerlake
- 11th Gen Intel(R) Core(TM) i5-1135G7 (TigerLake)
- cpu level 6, x86-64, avx
-
-
-
-
-
-
-Save and restore simulation
-
-Bochs has now full save/restore support. The state of cpu(s), memory, devices and
-hard drive images
-
-The disk image mode "vvfat" does not support save/restore. All other disk image modes
-copy the whole image or the file containing changes (journal). This may take some time,
-so be patient when using this feature.
-
-can be saved. When running Bochs there will be a button in the
-header bar called "Suspend". Depending on config interface and GUI there will be a
-prompt where you can enter a path to an existing directory or a GUI folder selection
-dialog box. It is possible to save the state at any time, but we recommend to do it
-when the simulation is idle. After pressing OK/Enter, Bochs will save a set of files
-into the selected folder. It is possible to continue after saving the state, but when
-using the restore function in a new Bochs session, all changes after this checkpoint
-will be lost.
-
-
-To restore the saved simulation state, you can select the restore function in the
-text mode start menu or specify the restore path at the command line:
-
-bochs -r /path/to/save-restore-data
-
-
-
-Then Bochs will start up using the saved configuration and log options, restores
-the state of the hardware and begins the simulation. In the restore mode Bochs
-will ignore bochsrc options from the command line and does not load a normal
-config file.
-
-
-
-Using sound
-Sound basics
-
-Bochs supports two types of soundcards (SB16 ISA and ES1370 PCI) and the legacy
-PC speaker. The lowlevel sound interface provides a set of functions for wave
-(PCM) input / output and MIDI output using the host sound system. A driver must
-not implement all of these functions. The following table shows the supported
-drivers and their features.
-
Sound lowlevel modules
-
-
-
- Name
- Description
- Wave input
- MIDI output
-
-
-
-
- alsa
- use the default ALSA PCM device and the default ALSA sequencer
- on Linux
- Yes
- Yes
-
-
- oss
- use the Open Sound System on Linux and FreeBSD
- Yes
- Yes
-
-
- osx
- for output on Mac OS 9 and Mac OSX
- No
- Yes
-
-
- sdl
- for wave output on platforms supported by SDL (1.2.x or 2.x)
- No
- No
-
-
- win
- for output to the midi and wave mapper of Windows
- Yes
- Yes
-
-
-
-
-
-
-These special values are also valid for the sound driver:
-
- - select platform-default sound driver.
- - wave and MIDI output to file(s)
- - no output at all
-
-
-
-When compiling Bochs, the lowlevel sound support is activated if one of the soundcards
-is enabled ( or ).
-The configure script detects the available drivers and sets up a platform-default
-one.
-
-
-At runtime the lowlevel sound module will be loaded automatically if one of the
-sound devices are enabled in the bochsrc file. The drivers and
-devices for wave input / output and MIDI output must be set up with the
-sound option.
-
-
-The PC speaker
-
-The PC speaker is connected to the PIT 8254 timer #2 and generates a square
-wave beep with a frequency depending on the timer value. In Bochs the
-speaker is a separate plugin that is controlled by the two events "beep on"
-and "beep off". The "beep on" event is also called when the frequency
-changes while turned on.
-
-
-The destination for the speaker output can be selected with the
-parameter of the speaker option. Three choices are available:
-
- : the beep is generated by the square wave
-generator which is a part of the lowlevel sound support.
- : only available on Linux and Windows.
-On Linux /dev/console is used for output and on Windows the Beep() function.
- : forwards the beep to the related GUI methods
-(currently only used by the Carbon GUI).
-
-
-
-SB16 runtime configuration
-
-Most of the SB16 configuration parameters are available in the runtime
-configuration menu or dialog. In addition to this, there is a small program
-called SB16CTRL to change emulation settings from inside
-the simulation.
-
-Runtime options
-
-Unlike other devices, the SB16 emulation has its own logfile and a loglevel parameter
-to control what should be printed there. Both the file and
- parameters can be changed at runtime. See the
-sb16 bochsrc option for details.
-
-
-The output parameters , ,
- and are also available at
-runtime.
-
-
-The parameter controls the DMA timing for wave (PCM)
-input and output. When you get non-continuous sound, this value can be ajusted
-to fix this. This needs a reasonably correct setting for the
-cpu: ips option.
-
-
-SB16CTRL
-
-
-The source for the SB16CTRL program that is used to modify
-the runtime behavior of the SB16 emulation is included in
-misc/sb16/. It is a C
-program that can be run from inside the emulation.
-
-
-
-It currently supports the following commands:
-
-
-
Supported options for <command>sb16ctrl</command>
-
-
-
- Option
- Description
-
-
-
-
-
-
- Show the selected emulator info string,
- e.g. sb16ctrl -i 3 to show how many patch translations are active.
-
-
-
-
-
- Load a translation into the translation table. The numbers are:
- "OldBankMSB,OldBankLSB,OldProgram,NewBankMSB,NewBankLSB,NewProgram".
- All values can be 0..127 or 255. 255 for "Old" values means match
- any and for "New" values means don't change,
- e.g. sb16ctrl -t 255,255,0,255,255,32
- to change patch 0 (Piano) to patch 32 (Acoustic Bass).
-
-
-
-
-
- Reset the patch translation table e.g. sb16ctrl -r.
-
-
-
-
-
- Upload the given numbers to the midi output device. Note
- that it should be a complete midi message, and also that it is
- subject to patch translation,
- e.g. sb16ctrl -m 0x80,64,0
- to send a note-off message to channel 0.
-
-
-
-
-
- Read in a file and execute the commands in it. These have
- the same format as the above commands, except that they don't have
- the dash "-" in front of them.
- Comment lines are supported and start with a hash sign "#".
-
-
-
-
-
- Show a brief summary of the commands.
-
-
-
-
-
-
-
-All numbers can be valid parameters to the strtol() function, so hex and
-octal notation is fine. They have to be delimited by either commas "," or
-slashes "/", spaces are not allowed.
-
-
-
-The command line can have any number of commands. However, if none are given,
-"-f -" is assumed, which means commands are taken from stdin.
-
-
-
-
-
-USB configuration
-
-The USB configuration allows you to add, delete, or modify an existing USB device.
-
-
-The 'device' field may contain one of the following items:
-
-Mouse
-
-This emulates a 3-button mouse. After a reset, it is set up to send the Report
-Protocol report and consists of a 4-byte report:
-
-byte 0: 00000BBB Bits 7:3 are zero
- Bit 2 is button 3
- Bit 1 is button 2
- Bit 0 is button 1
-byte 1: XXXXXXXX 8-bit X Displacement (-127 -> 127)
-byte 2: YYYYYYYY 8-bit Y Displacement (-127 -> 127)
-byte 3: ZZZZZZZZ 8-bit Z Displacement (-127 -> 127)
-
-This device may be used on all Host Controller types using a speed of 'low', 'full',
-or 'high'.
-
-usb_uhci: enabled=1, port1=mouse, options1="speed:low"
-usb_ohci: enabled=1, port1=mouse, options1="speed:full"
-usb_ehci: enabled=1, port1=mouse, options1="speed:high"
-usb_xhci: enabled=3, port3=mouse, options1="speed:full"
-
-
-Please note that most physical USB mice will be 'low-speed' only.
-
-
-
-
-Keyboard
-
-This emulates a standard keyboard. Key press and release codes are translated from
-the Host's keyboard to the Guest as USB Interrupt packets.
-
-
-This device may be used on all Host Controller types using a speed of 'low', 'full',
-or 'high'.
-
-usb_uhci: enabled=1, port1=keyboard, options1="speed:low"
-usb_ohci: enabled=1, port1=keyboard, options1="speed:full"
-usb_ehci: enabled=1, port1=keyboard, options1="speed:high"
-usb_xhci: enabled=3, port3=keyboard, options1="speed:full"
-
-
-Please note that most physical USB keyboards will be 'low-speed' only.
-
-
-
-
-Keypad
-
-This emulates a numeric keypad. Key press and release codes are translated from
-the Host's keyboard to the Guest as USB Interrupt packets.
-
-
-This device may be used on all Host Controller types using a speed of 'low', 'full',
-or 'high'.
-
-usb_uhci: enabled=1, port1=keypad, options1="speed:low"
-usb_ohci: enabled=1, port1=keypad, options1="speed:full"
-usb_ehci: enabled=1, port1=keypad, options1="speed:high"
-usb_xhci: enabled=3, port3=keypad, options1="speed:full"
-
-
-Please note that most physical USB keypads will be 'low-speed' only.
-
-
-
-
-Tablet
-
-This emulates a 3-button mouse. After a reset, it is set up to send the Report
-Protocol report and consists of a 6-byte report:
-
-byte 0: 00000BBB Bits 7:3 are zero
- Bit 2 is button 3
- Bit 1 is button 2
- Bit 0 is button 1
-byte 1: XXXXXXXX 8-bit X Displacement (low byte)
-byte 2: XXXXXXXX 8-bit X Displacement (high byte)
-byte 3: YYYYYYYY 8-bit Y Displacement (low byte)
-byte 4: YYYYYYYY 8-bit Y Displacement (high byte)
-byte 5: ZZZZZZZZ 8-bit Z Displacement
-
-This device may be used on all Host Controller types using a speed of 'low', 'full',
-or 'high'.
-
-usb_uhci: enabled=1, port1=tablet, options1="speed:low"
-usb_ohci: enabled=1, port1=tablet, options1="speed:full"
-usb_ehci: enabled=1, port1=tablet, options1="speed:high"
-usb_xhci: enabled=3, port3=tablet, options1="speed:full"
-
-
-Please note that most physical USB tablets will be 'low-speed' only.
-
-
-
-
-Disk/CD-ROM
-
-This emulates a media device in the form of a hard-drive or CD-ROM. By default,
-the emulation uses the "Bulk-only" transport, also known as "Bulk/Bulk/Bulk". For
-high- and super-speed devices, you can specify the "UASP" protocol, also known as
-"USB Attached SCSI Protocol".
-
-
-This device may be used on all Host Controller types using a speed of 'full', 'high',
-or 'super'.
-
-usb_uhci: enabled=1, port1=disk, options1="speed:full, path:hdd.img" # defaults to the BBB protocol
-usb_ohci: enabled=1, port1=disk, options1="speed:full, path:hdd.img"
-usb_ehci: enabled=1, port1=disk, options1="speed:high, path:hdd.img"
-usb_ehci: enabled=1, port1=disk, options1="speed:high, path:hdd.img, proto:bbb"
-usb_ehci: enabled=1, port1=disk, options1="speed:high, path:hdd.img, proto:uasp"
-usb_xhci: enabled=3, port1=disk, options3="speed:full, path:hdd.img"
-usb_xhci: enabled=3, port1=disk, options3="speed:high, path:hdd.img, proto:bbb"
-usb_xhci: enabled=3, port1=disk, options3="speed:high, path:hdd.img, proto:uasp"
-usb_xhci: enabled=1, port1=disk, options1="speed:super, path:hdd.img, proto:bbb"
-usb_xhci: enabled=1, port1=disk, options1="speed:super, path:hdd.img, proto:uasp"
-
-An image format, similar to the ATA option, can be used. Replace 'mode' below with
-the desired format.
-
-usb_xhci: enabled=3, port1=disk, options3="speed:high, path:mode:hdd.img, proto:bbb"
-usb_xhci: enabled=3, port1=disk, options3="speed:high, path:mode:hdd.img, proto:uasp"
-
-To emuate a CD-ROM, replace 'disk' in the examples above with 'cdrom', and adjust
-the 'path' accordingly.
-
-Specifying 'proto:uasp' does not guarantee that the Guest will use that protocol.
-See a previous section for more information.
-
-
-Please note that this device is not allowed as a low-speed only device. Low-speed should be specified.
-
-
-
-
-Floppy
-
-This emulates a media device in the form of an external Floppy drive. By default,
-the emulation uses the "Control/Bulk/Interrupt" transport, aka "CBI". Bochs can be
-re-compiled to use the "Control/Bulk" transport, aka "CB".
-
-
-This device may be used on all Host Controller types using a speed of 'full'.
-
-usb_uhci: enabled=1, port1=floppy, options1="speed:full, path:floppy.img"
-usb_ohci: enabled=1, port1=floppy, options1="speed:full, path:floppy.img, model:teac"
-usb_ehci: enabled=1, port1=floppy, options1="speed:full, path:floppy.img, model:teac"
-usb_xhci: enabled=1, port3=floppy, options3="speed:full, path:floppy.img"
-
-An image format, similar to the ATA option, can be used. Replace 'mode' below with
-the desired format.
-
-usb_uhci: enabled=1, port1=floppy, options1="speed:full, path:mode:floppy.img"
-
-The 'model:teac' option can be used to emulate that specific model, else a default
-model will be used. If a guest does not see the attached floppy, try specifying the 'teac'
-model.
-
-Please note that this device is a full-speed only device. No other speed should be specified.
-
-
-
-
-Printer
-
-This emulates a simple USB printer. All data sent to the printer will be appended
-to a specified file on the Host.
-
-
-This device may be used on all Host Controller types using a speed of 'full'.
-
-usb_uhci: enabled=1, port1=printer, options1="speed:full, file:printdata.bin"
-usb_ohci: enabled=1, port1=printer, options1="speed:full, file:printdata.bin"
-usb_ehci: enabled=1, port1=printer, options1="speed:full, file:printdata.bin"
-usb_xhci: enabled=1, port3=printer, options3="speed:full, file:printdata.bin"
-
-
-Please note that this device is a full-speed only device. No other speed should be specified.
-
-
-
-
-Hub
-
-This emulates a full-speed 4-port external hub. The number of ports can be
-changed, with a range of 2 to 8.
-
-
-This device may be used on all Host Controller types using a speed of 'full'.
-
-usb_uhci: enabled=1, port1=hub, options1="speed:full"
-usb_ohci: enabled=1, port1=hub, options1="speed:full, ports:4"
-usb_ehci: enabled=1, port1=hub, options1="speed:full, ports:6"
-usb_xhci: enabled=1, port1=hub, options1="speed:full, ports:8"
-
-At startup, no device is attached to this hub. However, after start up, using the
-runtime interface, a device can be attached to any or all of the ports.
-
-
-Any device attached to this hub (via the runtime interface), must be the same as or less than the hub's current speed (which is currently only full-speed). Any device plugged into a hub, no matter its max speed, can only function at or below the speed of the hub it is attached to.
-
-
-Please note that this device is a full-speed only device. No other speed should be specified.
-
-
-
-
-Packet Capture
-
-All devices may use the 'pcap' option to send all data to a Packet Capture formatted
-file.
-
-usb_uhci: enabled=1, port1=hub, options1="speed:full, pcap:outfile.pcap"
-
-This file is formatted to be used with Linux' usbmon and utilities such as
-Wire Shark.
-
-
-Please note that this option will not capture any data that would normally
-flow through an external hub, so if you use the 'pcap' option for a hub,
-as with the example above, only the hub's data is captured, not the device(s) attached
-to it.
-
-
-
-Signaling an Over-Current event
-
-During emulation, using the runtime configuration, you can signal an over-current
-event on any device using the 'over-current' checkbox (GUI) or text configuration
-option. This will signal an over-current event on the Host Controller for that
-port.
-
-
-Over-current is considered undefined on the UHCI, though Intel 430TX and later
-controllers may have implemented over-current via two previously unused bits.
-
-
-
-Notes
-
-
-
-All devices allow the 'debug' option to be used. This turns on the BX_DEBUG() logging
-for that device.
-
-usb_uhci: enabled=1, port1=hub, options1="speed:full, debug"
-
-
-
-
-
-You can wrap options in double-quotes in your bochsrc file. However, the runtime config
-interface has problems when double-quotes are used. Therefore, don't use them in the
-runtime configuration interface.
-
-
-
-
-
-
-
-
-
- Common problems and what to do about them (Troubleshooting)
-
- Bochs panics! What can I do?
-
- Bochs does a very good job in emulating an x86 compatible computer, however,
- it does not (yet) include a full (100%) emulation of every possible instruction,
- (BIOS) function call or (hardware) device. Thus, in case something unusual
- happens, either a not-so-common call to some (BIOS) function or device by
- some software running inside of it, Bochs has two possibilities to react:
- If the command doesn't look important (mainly happens only to non-implemented
- functions in the BIOS), a notice is logged to the log file
- and the emulation continues. If, however, the command looks important, Bochs
- panics, because the software being emulated might depend on the successful
- execution of the given instruction or behavior of the device.
-
-
- A panic does not always mean that the software won't run inside of Bochs,
- as the software might just be probing the computer for the presence of some
- instruction/device, and in case it is not found, it simply won't be used at
- all, by the software.
-
-
- You can tell Bochs what to do in case of a panic, by re-configuring the
- panic option. If
- you change the action to "ask", Bochs reports what has happened and asks
- you what to do. The appearance of the "ask" feature depends on the display
- library used and the platform. Some display libraries don't support it at all.
-
-
- Some of the device names reported in the panic message are abbreviations,
- since the length of the 'prefix' is limited to 6 characters. The
- log function module table may help
- you finding out the name of the device that caused the panic. It also gives
- you a short description of the module.
-
-
-
-
- Mouse behavior, enabling and disabling
-
- Refer to for information on how to enable or
- disable the mouse inside of Bochs at run-time.
-
-
- The mouse cursor movement speed mostly doesn't match the real movement. This
- is caused by the variable emulation speed (from the user's point of view)
- and the relative mouse position data that standard PS/2, serial or USB mice
- are generating. The alternative is the USB tablet emulation that generates
- absolute mouse position data. We recommend to use it with the display
- libraries 'rfb' and 'vncsrv'.
-
-
-
-
- Text-mode is broken in some ancient DOS program
-
-
- If you are using a program written for DOS which seems to use the text-mode but
- doesn't display the text properly, you can try the other VGA BIOS, either
- VGABIOS-lgpl-latest or VGABIOS-elpin-2.40,
- see the vgaromimage option.
-
-
-
- &NEEDHELP; Maybe it is a bug in the LGPL VGA BIOS, but for now, it seems to work.
-
-
-
-
-
-Feedback and Support
-
-The Bochs project on SourceForge
-
-The Bochs project page
-on SourceForge provides these features:
-
-
-Project summary page with screenshots and download statistics
-
-
-Download area for Bochs release packages and disk images
-
-
-Mailing list archives
-
-
-Source code browser
-
-
-Tickets section (bug reports, patches, feature requests etc.)
-
-
-Discussion boards (e.g. "Help" and "Open Discussion")
-
-
-Project news page (used for release announcements)
-
-
-
-
-SourceForge tickets section (bug and patch trackers)
-
-There are some requirements when submitting bug reports, patches, and feature
-requests for Bochs to make it easier to reproduce bugs and test patches.
-
-Reporting errors from Bochs compilation
-
-When reporting errors while building Bochs to the &devlist; or the SF bug
-tracker for the Bochs project, this information is required to fix the issue:
-
- host platorm / build environment
- Bochs release version or SVN revision
- configure options used
- full error message
- config.log output if configure failure
- source file name and line number if compile error
-
-
-
-Before reporting us the issue, make sure that a similar one hasn't been already
-reported or someone created a patch to fix it. If you are familiar with C++
-and you can write some code to fix your problem, you can post it in the &devlist;
-or submit the patch in SF patch tracker for Bochs.
-
-
-Reporting Bochs runtime issues
-
-If Bochs does not work properly (e.g. panic, segfault, malfunction of emulated device)
-we need some information to find out what's going on:
-
- Bochs version used (version number if binary release / SVN revision
- if self-compiled)
- host platorm / build environment (if self-compiled)
- bochsrc options used
- error message (if panic or program termination)
- log file output (related section only if too big)
-
-
-
-Submitting a patch for Bochs
-
-Patches for Bochs should be provided in the "unified diff" format. In addition
-to the patch file and a detailed description this information is required:
-
- patch applies to Bochs release version / SVN revision
- test case (if required)
-
-
-
-When you are are interested in writing a patch to fix bugs or add new features,
-you should have a look at the developer documentation.
-For some parts of the Bochs code we have already written some basic information.
-
-
-
-
-
-Mailing Lists
-
-The Bochs community uses three mailing lists to communicate, called
-bochs-developers, bochs-cvs and bochs-announce.
-
-
-bochs-developers mailing list
-
-Bochs-developers is the forum for all Bochs discussions and questions. On
-average, subscribers get between five and ten messages per day. There are
-about 350 subscribers. If this sounds like too much email, maybe the bochs-announce list is more appropriate for
-you. Anyone may join the list, unless they abuse it of course.
-
-
-To subscribe, go to the Bochs-Developers Info Page and type your email
-address and a password into the web form and click
-Subscribe. In a few minutes you will get a confirmation
-email. Follow the directions in the email to complete the subscription
-process. To unsubscribe, go to the same
-page and type your email address in the blank at the bottom and click
-on Edit Options. Then type your password and click
-Unsubscribe.
-
-
-Once you have subscribed, you can write to
-bochs-developers@lists.sourceforge.net to send a message to
-everyone on the list. While it's possible to post without being a subscriber,
-it's not recommended. If you aren't a subscriber, you might miss the response
-to your question.
-
-
-Archive of bochs-developers messages
-
-
-
-bochs-announce mailing list
-
-Bochs-announce is a moderated, low-traffic list which carries only periodic
-announcements of Bochs releases and important events. If you have a very
-important and truly relevant Bochs announcement, you can try posting it to
-bochs-announce, but the moderator will have to approve it before it will
-go out. On average, bochs-announce subscribers get one or two messages
-per month. There are about 75 subscribers. Anyone may join the list.
-
-
-
-To subscribe, go to the Bochs-Announce Info Page and type your email
-address and a password into the web form and click Subscribe.
-In a few minutes you will get a confirmation email. Follow the directions in
-the email to complete the subscription process. To unsubscribe, go to the
-same
-page and type your email address in the blank at the bottom and click
-on Edit Options. Then type your password and click
-Unsubscribe.
-
-
-
-There is no need to subscribe to both lists, because all bochs-announce
-messages are forwarded to the developers list. If you subscribe to both, you
-will get 2 copies of every announcement.
-
-
-
-Archive of bochs-announce messages
-
-
-
-
-bochs-cvs mailing list
-
-This is the svn commit mailinglist (a unified diff email will be sent
-whenever someone does a checkin in the bochs SVN repository).
-
-
-
-Archive of bochs-cvs messages
-
-
-
-
-Mailing List Etiquette
-
-
-Here are a few guidelines for use of the Bochs mailing lists:
-
-
-
-
-Please check the documentation before asking questions, but on this list you
-are very UNLIKELY to get flamed and insulted for being a Bochs beginner.
-Sending commercial promotions to the list probably will get you some angry
-responses though.
-
-
-
-If you are having difficulty finding what you are looking for, try doing a search on Google. If you are searching for Bochs options, for example, you can use this syntax in the Google search box:
-
-configuration options site:bochs.sourceforge.net
-
-For best results, be sure not to put a space between "site:" and "bochs.sourceforge.net". Be sure to look at more than the first item on the search results.
-
-
-
-
-If you still cannot find what you are looking for, be sure you are prepared when you post your question, and post in the right forum. Be sure you include important details, such as the operating system and version of your host, and what it is you are trying to do. If you are getting errors or something is not working, summarize what you checked and what you changed. This will help isolate the problem.
-
-
-
-
-
-Bochs is for everyone. If you are an experienced Bochs user or developer and are helping someone else, be considerate of the other person's feelings. We share a common interest, and we need to encourage each other and be supportive.
-
-
-
-
-Also, keep in mind that messages are limited to 40K, so if you want to share a
-large screen shot or disk image, put it on a web or FTP site and tell people
-how to find it. Patches are usually small enough that they aren't a problem,
-especially if compressed.
-
-
-
-Distribution of copyrighted material, or even offers to distribute copyrighted
-material WILL NOT be tolerated. The Bochs Project does not distribute
-any software (disk images) in violation of the license agreement, and users who
-do so will be warned first and then blocked from the list if it happens again.
-As an open source project, we rely on donated services from Source Forge and
-other groups, and we can't afford to put them or ourselves at risk of legal
-action.
-
-
-
-It is possible to subscribe and unsubscribe by email. If you do this, you must
-write to bochs-announce-request or bochs-developers-request. Don't forget the
-"-request" part or your subscribe message will go to 300+ people.
-
-
-
-
-
-
-
-The Bochs internal debugger
-Using the command line debugger
-
-
-You can now conditionally compile in a GDB like command line debugger, that
-allows you to set breakpoints, step through instructions, and other
-useful functions. If there isn't a command for something you believe
-is generally useful for the debugger, let me know and I'll implement
-it if possible.
-
-
-
-This section describes how to enable and use the Bochs command line debugger.
-For its builtin graphical front-end please see the debugger gui
-section how to enable it.
-
-
-
-To use the debugger, you must configure Bochs with the
- flag.
-For example:
-
- ./configure --enable-debugger
-
-
-
-
-You must use flex version 2.5.4 or greater. I have heard that
-version 2.5.2 will not work.
-
-
-
-When you first start up Bochs, you will see the command line prompt
-
-
- bochs:1>
-
-
-From here, you may use the following commands:
-
-
-
-Execution Control
-
-
- c continue executing
- cont
- continue
-
- s [count] execute count instructions, default is 1
- step [count]
-
- s [cpu] [count] for SMP simulation, execute count instructions on cpu, default is 1
- step [cpu] [count]
-
- s all [count] for SMP simulation, execute count instructions on all cpus
- step all [count]
-
- Ctrl-C stop execution, and return to command line prompt
- Ctrl-D if at empty line on command line, exit
-
- q quit debugger and execution
- quit
- exit
-
-
-
-
-
-BreakPoints
-
-
- NOTE: The format of 'seg', 'off', and 'addr' in these descriptions,
- are as follows. I don't have any way to set the current radix.
-
- hexidecimal: 0xcdef0123
- decimal: 123456789
- octal: 01234567
-
- vbreak seg:off Set a virtual address instruction breakpoint
- vb seg:off
-
- vbreak seg:off if "expr" Set a conditional virtual address instruction breakpoint
- vb seg:off if "expr"
-
- lbreak addr Set a linear address instruction breakpoint
- lb addr
-
- lbreak addr if "expr" Set a conditional linear address instruction breakpoint
- lb addr if "expr"
-
- pbreak [*] addr Set a physical address instruction breakpoint
- pb [*] addr (the '*' is optional for GDB compatibility)
- break [*] addr
- b [*] addr
-
- pbreak [*] addr if "expr" Set a conditional physical address instruction breakpoint
- pb [*] addr if "expr" (the '*' is optional for GDB compatibility)
- break [*] addr if "expr"
- b [*] addr if "expr"
-
- info break Display state of all current breakpoints
- bpe n Enable a breakpoint
- bpd n Disable a breakpoint
- delete n Delete a breakpoint
- del n
- d n
-
-
-
-
-
-
-Memory WatchPoints
-
-
-
- watch read addr Insert a read watch point at physical address addr
- watch r addr Insert a read watch point at physical address addr
-
- watch write addr Insert a write watch point at physical address addr
- watch w addr Insert a write watch point at physical address addr
-
- watch Display state of current memory watchpoints
-
- watch stop Stop simulation when a watchpoint is encountered (default)
- watch continue Do not stop simulation when a watchpoint is encountered
-
- unwatch addr Remove watchpoint to specific physical address
- unwatch Remove all watch points
-
-
-
-
-
-
-Manipulating Memory
-
-
- x /nuf addr Examine memory at linear address addr
- xp /nuf addr Examine memory at physical address addr
- n Count of how many units to display
- u Unit size; one of
- b Individual bytes
- h Halfwords (2 bytes)
- w Words (4 bytes)
- g Giant words (8 bytes)
- NOTE: these are *not* typical Intel nomenclature sizes,
- but they are consistent with GDB convention.
- f Printing format. one of
- x Print in hexadecimal
- d Print in decimal
- u Print in unsigned decimal
- o Print in octal
- t Print in binary
-
- n, f, and u are optional parameters. u and f default to the last values
- you used, or to w(words) and x(hex) if none have been supplied.
- n currently defaults to 1. If none of these optional parameters are
- used, no slash should be typed. addr is also optional. If you don't
- specify it, it will be the value the next address (as if you had
- specified n+1 in the last x command).
-
- setpmem addr datasize val Set physical memory location of size
- datasize to value val.
-
- writemem filename addr len dump a number of bytes of virtual memory starting from
- the specified linear address into a file
-
- loadmem filename addr initialize virtual memory starting from the specified linear
- address from a file
-
- deref addr deep pointer dereference. For example: get value of [[[rax]]] or ***rax: deref rax 3
-
- crc addr1 addr2 Show CRC32 for physical memory range addr1..addr2
-
-
-
-
-
-
-Info commands
-
-
- r|reg|regs|registers List of CPU integer registers and their contents
- fp|fpu List of all FPU registers and their contents
- mmx List of all MMX registers and their contents
- sse|xmm List of all SSE registers and their contents
- ymm|zmm List of all AVX registers and their contents
- sreg Show segment registers and their contents
- dreg Show debug registers and their contents
- creg Show control registers and their contents
-
- info cpu List of all CPU registers and their contents
- info eflags Show decoded EFLAGS register
- info break Information about current breakpoint status
- info tab Show paging address translation
- info idt Show contents of the IDT
- info gdt Show contents of the GDT
- info ldt Show contents of the LDT
- info device Show state of the specified device
-
-
-
-
-
-Manipulating CPU Registers
-
-
- set reg = expr Change a CPU register to value of expression.
- Currently only general purpose registers and instruction pointer
- are supported. You may not change eflags, segment registers,
- floating point or SIMD registers.
-
- Examples: set eax = 2+2/2
- set esi = 2*eax+ebx
-
- registers List of CPU registers and their contents
- regs
- reg
- r
-
- calc|? expr Evaluate an expression and display the result.
- 'expr' can reference any general-purpose, opmask and segment
- registers, use any arithmetic and logic operations, and also
- special ':' operator which computes the linear address of a
- segment:offset (in real and v86 mode) or of a selector:offset
- (in protected mode) pair. Use $ operator for dereference,
- for example, get value of [[[rax]]] or ***rax: rax$3.
-
-
-
-
-
-
-Disassembly commands
-
-
- disassemble start end Disassemble instructions in given linear address
- range, inclusive of start, exclusive of end.
- Use "set $disassemble_size =" to tell
- debugger desired segment size. Use a value for
- end of less than start (or zero) if you only
- want the first instruction disassembled.
-
- disassemble switch-mode Switch between Intel and AT&T disassembly styles
- for debugger disassembler.
-
- disassemble size = n Tell debugger what segment size to use when
- the "disassemble" command is used. Use values
- of 0, 16 or 32 for n. Value of 0 means
- "use segment size specified by current CS
- segment". Default is 0.
-
- set $auto_disassemble = n Cause debugger to disassemble current instruction
- every time execution stops if n=1. Default is 0.
- Segment size of current CPU context is used for
- disassembly, so the "disassemble size" variable is
- ignored.
-
- set disassemble on The same as 'set $auto_disassemble = 1'
- set disassemble off The same as 'set $auto_disassemble = 0'
-
-
-
-
-
-Instruction tracing
-
-
- trace on Disassemble every executed instruction. Note
- that instructions which caused exceptions are
- not really executed, and therefore not traced.
-
- trace off Disable instruction tracing.
-
- trace-mem on/off Enable/Disable memory access tracing.
-
-
-
-
-
-Instrumentation
-
-
-To use instrumentation features in Bochs, you must compile in support for it.
-You should build a custom instrumentation library in a separate directory in
-the "instrument/" directory. To tell configure which instrumentation library
-you want to use, use the option.
-
-The default library consists of a set of stubs, and the following are
-equivalent:
-
-
- ./configure [...] --enable-instrumentation
- ./configure [...] --enable-instrumentation="instrument/stubs"
-
-
-You could make a separate directory with your custom library,
-for example, "instrument/myinstrument", copy the contents of
-the "instrument/stubs" directory to it, then customize it. Use:
-
-
- ./configure [...] --enable-instrumentation="instrument/myinstrument"
-
-
-
-
-
-Instrumentation commands
-
-
- instrument [command] calls BX_INSTR_DEBUG_CMD instrumentation callback with [command]
- instrument "[command string]" calls BX_INSTR_DEBUG_CMD instrumentation callback with [command string]
-
-
-
-
-
-Other Commands
-
-
-ptime
-
-Print the current time (number of ticks since start of simulation).
-
-sb delta
-
-Insert a time break point "delta" instructions into the future ("delta" is a 64-bit integer followed by "L", for example 1000L).
-
-sba time
-
-Insert a time break point at "time" ("time" is a 64-bit integer followed by "L", for example 1000L).
-
-print-stack [num words]
-
-Print the num words top 16-bit words on the stack. Num
-words defaults to 16. Only works reliably in protected mode when
-the base address of the stack segment is zero.
-
-print-string addr
-
-prints a null-ended string from a linear address.
-
-bt [num_entries]
-
-prints backtrace.
-
-source file
-
-cause debugger to execute a script file
-
-addlyt file
-
-cause debugger to execute a script file every time execution stops.
-
-
-
-Example of use:
-
-
-
-Create a script file (script.txt) with the following content
-
-
- regs
- print-stack 7
- u /10
- (*EMPTY NEW LINE)
-
-
-
-Execute addlyt
-
-
-addlyt "script.txt"
-
-
-
-Then, when you execute a step/DebugBreak... you will see: registers, stack and disasm.
-
-
-remlyt
-
-stops debugger to execute the script file added previously with addlyt command.
-
-lyt
-
-cause debugger to execute script file added previously with addlyt command.
-Use it as a refresh/context.
-
-modebp
-
-Toggles CPU mode switch breakpoint.
-
-ldsym [global] filename [offset]
-
-Load symbols from file filename. If the global keyword is
-added, then the the symbols will be visible in all contexts for which
-symbols have not been loaded. Offset (default is 0) is added to
-every symbol entry. The symbols are loaded in the current (executing)
-context.
-
-
-
-The symbol file consists of zero or more lines of the format "%x %s".
-
-show [string]
-
-
- Toggles show symbolic info (calls to begin with).
- show - shows current show mode
- show mode - show, when processor switch mode
- show int - show, when interrupt is happens
- show call - show, when call is happens
- show ret - show, when iret is happens
- show off - toggles off symbolic info
- show dbg-all - turn on all show flags
- show dbg-none - turn off all show flags
-
-
-
-
-
-Related links
-
-
-&FIXME; For information on advanced debugger usage see the developer documentation
-(under construction).
-
-
-
-
-
-
-The Bochs debugger GUI
-
-
-The graphical front-end for the Bochs command line debugger
-is available for Windows and GTK2/GTK3 hosts.
-
-
-To use the GUI debugger, you must configure Bochs with the
-default debugger switch and the flag.
-For example:
-
- ./configure --enable-debugger --enable-debugger-gui
-
-
-
-At runtime you need to add the value to the
-display_library options parameter
-in order to use the GUI instead of the command line debugger. This example shows
-how to use it with the 'x' GUI:
-
-display_library: x, options="gui_debug"
-
-
-The wxWidgets port of Bochs always uses this debugger GUI. Passing
-the option to the display library is not necessary, since the command line
-interface is not available then.
-
-Overview
-
-The GUI debugger consists of a GUI window with a menu bar, a button bar and some
-child windows for different purposes. Not all windows are visible at the same time.
-
-
-Register window
-Disassembly window
-MemDump window
-Output window: display internal debugger output / log output
-Input window: command prompt for entering debugger commands
-Param tree window: show the Bochs parameter tree (CPU / hardware state)
-Stack window
-Breakpoint / watchpoint window
-Command button row
-CPU button row: only available for SMP emulation
-
-
-The register window
-
-Typically, all the various registers are grouped by color. If you don't like the
-colors, they can be turned off, or modified at compile time. There are options
-to show or hide most register "groups", so that you can focus more strictly on
-the registers you are interested in (probably just the GP registers).
-
-Yes, the XMM display shows hex in the "decimal" column -- there is more
-room there. Deal with it.
-Doubleclicking a register attempts to change its value. Bochs may not
-allow you to change most registers. In future versions, more registers may
-be modifiable.
-
-The disassembly window
-
-Disassembly output that is autoloaded, or generated from the menu, ends up
-here. If the frontend cannot detect the "current instruction" in the list,
-when it reaches the next instruction -- then it will autoload a new list.
-Having a big list will reduce the number of autoloads, and allows you to see
-more. The list can contain up to 2048 lines. However, if you load more than
-1000 lines, you are more likely to see performance problems.
-
-There are two kinds of emulated memory in Bochs: Linear and Physical.
-Emulated Linear memory is mapped onto Physical memory by x86 virtual memory
-methods (paging and segmentation). If paging and segmenataion are "off", or
-"identity mapped", then both "types" of memory mean the same thing. But they
-still work a little differently. With the Internal Debugger, you can set
-breakpoints to either kind of memory, separately. Normally, you would use
-the "b" command to set breakpoints in physical mem, and "lb" to set breakpoints
-in linear mem. This frontend ONLY displays linear breakpoints. It does not
-bother trying to figure out the linear->physical reverse mapping to show
-physical breakpoints. (There are also "virtual" breakpoints that are also
-not shown.) All the types of breakpoints still WORK, it is just that you
-will not see them marked on the screen.
-
-
-It will be obvious to you that the current instruction is marked in green,
-unless it is on a breakpoint, when it turns blue. Breakpoints are red, of
-course.
-
-
-You must click a line in the window, before you can use frontend commands
-to set or clear a linear breakpoint on it. You can doubleclick (which saves
-steps) to set or clear a linear breakpoint.
-
-
-The MemDump window
-
-As of this version, the MemDump window isn't much more than a display of the
-contents of memory. In later versions, hopefully it will be expanded into a
-fairly fully-featured hexeditor. You can dump either physical mem, or linear
-mem. There are breakpoint-like things (that work with physical memory only,
-currently), called "watchpoints". A physical memory address can cause a break
-in the simulation if it is read, or written.
-
-
-The frontend again does NOT try to calculate out the linear -> physical mapping
-in any attempt to display the physical watchpoints while viewing linear mem.
-
-
-You must click a hex byte (on a physical mem dump that shows bytes), in order to
-set or clear a read and/or write watchpoint on that byte. Read watchpoints are
-green (on black), write watchpoints are red, watchpoints that are both write
-and read are blue. There is a hardcoded limit in Bochs of 16 of each type of
-watchpoint.
-
-
-The MemDump window loads/shows 4K of memory at a time.
-
-
-PageUp/Down scrolls the display up or down through mem, 2K at a time
-Doubleclicking a line of memory allows you to change the byte values
-(Works on both linear and physical mem dumps)
-Doubleclicking with the Shift key down sets write watchpoints
-Doubleclicking with Alt sets read watchpoints
-You need to click once on the memory window before you can use its "Find"
-function. The Find function is pretty limited in scope, currently. It can
-only find bytes (or strings of bytes) within each 16byte "line"
-
-
-The output window
-
-The Output window shows anything that the Bochs Internal Debugger tries to send
-to you. The window is scrollable, but only keeps a limited history of output (10K).
-The ID is always spamming you with "Next at t=" and disassembly lines, that would
-tend to fill up the Output window with garbage -- so there are options to ignore
-either of these types of output.
-
-
-The input window
-
-The Input window is for sending user commands directly into the Bochs Internal
-Debugger -- bypassing the frontend. Results will appear in the Output Window.
-The Input window has a history feature for commands, using the Up and Down arrows --
-it remembers 64 commands, 80 bytes each. No matter where you click on the frontend,
-you can always type directly into the Input box without clicking on it.
-
-
-When the Input window is invisible, you should still be able to type into it --
-after taking into account the bug listed at the bottom of this file.
-
-
-Hitting Enter on a blank line will cause a Singlestep.
-
-
-The param tree
-
-The Bochs param_tree shows the internal state of most of Bochs. It will be
-expanded in the future to show even more. You can see the detailed state of
-all cpu registers -- including the "hidden" parts (look in the "bochs" branch).
-Or see the current state of most of the emulated hardware.
-
-
-The stack window
-
-The MemDump windows do not automatically refresh -- except for the Stack
-window. If you leave the stack window active, it will update as the stack
-changes. If you want to update the other MemDump windows with fresh data,
-hit Refresh.
-
-
-The breakpoint/watchpoint window
-
-Doubleclicking will delete a breakpoint or watchpoint.
-
-
-The command button row
-
-Just a (hopefully) convenient way of using the mouse, instead of the keyboard.
-If you don't like them, or they take up too much space, you can turn them off.
-
-
-The CPU button row
-
-This only shows up when you are running a multi-cpu simulation. Click on the
-CPU that you want to view. All CPUs are always stepped together, and they all
-stop the first time one hits some sort of breakpoint.
-
-
-Docking / Resizing
-
-If you grab one of the two vertical "bars" between the lists, you can horizontally
-resize the lists. The cursor will change, but there will be no animation.
-
-
-If you grab the middle of one of the lists, and drag it on top of one of the
-other lists, you can reorder the positions of the lists on the screen. The
-cursor will change, but there will be no animation. You can set an alternate
-"docking order" at compile time, also, if you have a permanent preference.
-(See the top of the wenhdbg_h.h file, for compile-time customization.)
-
-
-Additional Notes
-
-If you have a really big GDT or Paging display in the MemDump window, and you
-select a different display, it may take several seconds to delete the big display
-before it can switch.
-
-
-Uppercase text tends to seem a little annoying, but it really is a lot easier to
-read, especially on a proportional font. If you change to a fixed font, then you
-may want to switch the display to lowercase.
-
-
-Most of the GUI debugger settings are now saved to an INI file on exit and
-restored at the next run.
-
-
-
-
-
-Tips and Techniques
-
-Specify log options by device
-
-This table shows the name used for setting up the log actions per device, the
-prefix that appears in the log file or when a panic occurs and a short description
-of the module. This example shows how to turn on debug messages for a specific
-device in bochsrc.
-
-debug: action=ignore, pci=report
-
-The names can be used in upper case or lower case, since the check is not case
-sensitive. Note that the module names cannot be checked while reading the config
-file, since most of the modules do not exist at this point. Invalid names or names
-of modules not present in the current configuration will cause a panic when the
-simulation is starting.
-
-
-
-
-How to make a simple disk image
-
-This was contributed by Greg Alexander in October 2001 and updated by
-Volker Ruppert in October 2013.
-
-
-What you need:
-
-
-
-An executable version of Bochs. See Downloading Bochs and Compiling Bochs.
-
-
-The bximage program, included with Bochs.
-
-
-A FreeDOS boot disk, or a boot disk from another OS capable of
-producing DOS partitions (e.g. a Linux install disk).
-
-
-(Optional) mtools, a program for manipulating DOS disks/images.
-
-
-
-
-
-
-Create a flat image
-
-
-
-Option 1: Using the Unix dd utility:
-
-
-
-You will need to know the geometry of the disk you want to
-create. You have to compute the disk sector count:
-
-
-Sectors = Cylinders * Heads * SectorsPerTrack
-
-
-
-
-Use the dd command to create your file:
-
-
-dd if=/dev/zero of=teaching.img bs=512 count=sectors
-
-(replace "sectors" with the number you computed at the
-previous step).
-
-
-
-When you update your configuration file, please
-fill in the same cylinders, heads, and sector per
-track values.
-
-
-
-
-Option 2: Run bximage to create a disk image file.
-You will be greeted with the following prompt:
-
-
-========================================================================
- bximage
- Disk Image Creation / Conversion / Resize and Commit Tool for Bochs
- $ID: bximage.cc 11906 2013-10-23 08:35:21Z vruppert $
-========================================================================
-
-1. Create new floppy or hard disk image
-2. Convert hard disk image to other format (mode)
-3. Resize hard disk image
-4. Commit 'undoable' redolog to base image
-
-0. Quit
-
-Please choose one [0]
-
-
-
-
-Since we want to create a new image, we have to type '1'
-and then Enter.
-
-Do you want to create a floppy disk image or a hard disk image?
-Please type hd or fd. [hd]
-
-
-
-
-Since we are creating a hard disk image, accept the default of hd by
-pressing Enter or typing 'hd' and pressing
-Enter. Next, bximage will ask for the type of
-hd to create:
-
-
-What kind of image should I create?
-Please type flat, sparse, growing or vpc. [flat]
-
-
-
-
-
-We want to create a simple flat image, so accept the default
-by pressing Enter. Then, bximage will ask
-for the size of the disk image you want to create, in Megabytes:
-
-
-Enter the hard disk size in megabytes, between 1 and 8257535
-[10]
-
-
-
-
-Enter the size of the hard disk you want to create, and press
-Enter. Then bximage will ask you for a filename to use
-for the file it is creating.
-
-What should be the name of the image?
-[c.img]
-
-
-
-
-At this point, type in the filename you want to use for the image. The
-default of "c.img" is appropriate if this will be your only hard disk
-image. After you have typed in the name of the filename you want to
-use, press Enter. Bximage will tell you it is writing the disk
-and then it will show you a line that should be added to your
-bochsrc when you want to use this disk image. I named my
-10 Megabyte image "teaching.img" and the output of bximage looked like
-this:
-
-
-[c.img] teaching.img
-
-Creating hard disk image 'c.img' with CHS=20/16/63
-
-
-
-
-The following line should appear in your bochsrc:
-
- ata0-master: type=disk, path="teaching.img", mode=flat, cylinders=20, heads=16, spt=63
-
-
-
-
-At this point, a file called "teaching.img" was created in my current
-directory and is ready to be used as an image file for a Bochs session.
-
-
-
-
-You may want to name your image teaching_20-16-63.img
-so that you always know the values to use for CHS.
-
-
-
-
-
-
-Partition and format your image file
-
-
-
-Option 1: Using FreeDOS (Advantage: Creates a MBR on the partition.)
-
-
-
-First, you need to edit the bochsrc file that Bochs uses for
-configuration information (see ). Open bochsrc
-with a text editor. Remove all lines in the file which start with "ata0-master:". Add the "ata0-master:"
-line that was displayed when you ran bximage to bochsrc at the
-same place where you removed the old "ata0-master:" lines from.
-
-
-
-Also, you need to download or create a FreeDOS (or DOS, or Windows, or
-Linux) disk image. Modify the "floppya:" line in your bochsrc to point
-at the downloaded FreeDOS floppy image and change its status to "status=inserted".
-
-
-
-Save and close your bochsrc. Now run Bochs (see ).
-
-
-
-Use the standard FreeDOS commands fdisk and
-format to format your hard
-drive image. You must make the image bootable to be able to boot
-without a floppy disk. However, creating a bootable disk image is best
-done with a boot disk from the OS you intend to install on the image.
-
-
-
-
-Option 2: Using mtools (Disadvantage: Cannot create bootable images
-without a MBR image.)
-
-
-
-Use a text editor to add the following line to the file ~/.mtoolsrc:
-
-
-
-
-drive c: file="path/filename.img" partition=1
-
-
-
-
-Save and close .mtoolsrc. Next, execute the following commands to
-create a partition table for the drive image:
-
-
-
-
-mpartition -I -s spt -t cyl -h heads c:
-mpartition -cpv -s spt -t cyl -h heads c:
-
-
-
-For example, for my 10 meg drive, I used:
-
-mpartition -I -s 63 -t 20 -h 16 c:
-mpartition -cpv -s 63 -t 20 -h 16 c:
-
-
-
-
-
-Next, format the partition you just created using the mformat command:
-
-
-mformat c:
-
-
-
-
-
-And you now have a formatted disk image containing a single DOS
-partition.
-
-
-The mpartition command doesn't handle images larger than 1024 cylinders properly.
-The partition size reported by fdisk is okay, but mformat reports only 504 MB
-(tested with mtools 3.9.9).
-
-
-
-
-Use mtools to manipulate disk images
-
-Mtools is a set of programs that can read, write, and format DOS disk images.
-There are links to the Mtools main page and a Win32 port of Mtools on the
-Bochs Links page,
-under Resources.
-
-
-The mtools web site has a detailed manual. If anyone wants to write
-instructions specific to Bochs, we can add it right here.
-
-
-
-Bochs GNU/Linux DiskTools
-
-Bochs-Tools are a collection of scripts and programs to be used together
-with Bochs developed by Bernhard Bablok. Main goal was to provide a more
-Unix-like interface to the emulator and to enable access to Bochs disk-images
-from outside of Bochs. The latest version is available at
-www.bablokb.de/bochs-tools.
-
-
-
-Win32 only: Tools to manipulate disk images
-
-Winimage
-
-Someone on the &devlist; mentioned that they use a program
-called WinImage, from www.winimage.com
-to read and write disk images (floppy and hard disk). Winimage is a
-commercial product with a 30-day trial.
-
-
-If anyone wants to write a tutorial, send mail to &devlist; and volunteer.
-
-
-
-DiskExplorer
-
-This section was contributed by Luca Cassioli and Stanislav Shwartsman
-
-
-I eventually found what all of you were looking for for a long time: a
-freeware, graphical, win32 compatible HardDisk image editor! It can
-handle a large variety of formats, but the one you need is VMWARE
-2.0 PLAIN DISK: you can import/export to/from Bochs images COMPLETE
-DIRECTORIES!
-
-
-You can find it at
-
-http://hp.vector.co.jp/authors/VA013937/editdisk/index_e.html
-
-
-
-Ben Lunt's 'Ultimate' for Bochs and Win32/64
-
-Ben Lunt wrote a utility for Windows to manipulate flat disk images and their
-included file systems.
-
-
-You can find it at
-https://www.fysnet.net/ultimate/index.htm
-
-
-This is a Windows Dialog based utility, with source, and includes the following items:
-
-
- Partitioning: MBR, PMBR, eMBR, EFI GPT
-
-
- File Systems: FAT, FYSFS, LeanFS, Ext2/3/4, SimpleFS, ExFAT
-
-
- Inserting, extracting, and deleting files from said file systems.
- (some file system support is currently read-only)
-
-
- Checking the integrity of said file systems and other items.
-
-
-
-
-
-
-
-X Windows: Color allocation problems
-
-One common problem in X windows is that the screen colors can be abnormal
-if other X programs have already allocated all the colors. If the colors
-don't look right, try quitting colorful applications such as Netscape,
-clearing any complex images in the background, etc. so that Bochs has a
-chance to allocate the colors it needs.
-
-
-If Bochs continues to have problems, or you want Bochs to have perfect
-colors without having to quit any other application, you can try turning
-on the private_colormap option
-in the configuration file. Using a private
-colormap causes the Bochs window to have its own set of 256 colors to work
-with. When the cursor is over the Bochs display, Bochs will look correct
-and other parts of the screen may change to very strange colors. When the
-cursor goes to any other window, the other windows will look correct
-and Bochs will have strange colors. A better solution, if your hardware
-can support it, is to run your X server with 24-bit or 32-bit color.
-
-
-
-Screen saver turns on too quickly
-
-
-One thing you may notice is that the screen saver turns on (screen goes
-blank) very quickly after you have stopped typing. The reason is that Bochs
-simulates everything as fast as it can. If the CPU is very busy (running
-instructions nonstop), simulated time goes by slowly. If the CPU is idle (just
-waiting for you to type, for example), simulated time speeds up dramatically.
-In any case, if the screen saver blanks out the screen, just press a key (try
-shift or control) to restore the screen.
-
-
-
-There are two strategies to fix this problem. One is to increase the
-ips parameter of the cpu option
-in your configuration file. This will cause the simulation time
-to pass more slowly. The other strategy is to enable the experimental
-realtime PIT, which tries to keep Bochs in sync with real time. See the bochsrc
-option clock.
-
-
-
-
-
-Mounting a disk image using the loop device
-
-
-This section describes how to access a floppy or hard disk image within Linux
-using the loop device. Why would you want to do this? Let's say you have made
-a small Linux disk image for Bochs, and you want to install some more software
-on it. You have already downloaded the software onto your real system, so now
-you want to transfer it to the Bochs disk image. A fast way to transfer
-the files is to mount the disk image using the loop device.
-
-
-...on Linux
-
-
-This section was contributed by Volker Ruppert.
-
-Today I have made some tests with the loop device, because I want to exchange
-files with the Bochs disk images. This is what I found out:
-
-1. Using Floppy images is easy, because there is no partition table:
-
- losetup /dev/loop0 /usr/local/bochs/dlxlinux/floppya.img
-
- Now you can use the image like a real floppy:
-
- - format : mkfs.minix /dev/loop0
- - filesystem check : fsck.minix /dev/loop0
- - mount : mount /dev/loop0 -o loop /mnt/floppy
-
- Before you want to restart Bochs you must do this:
-
- losetup -d /dev/loop0
-
- Don't forget to umount before.
-
-2. If you want access to a hard disk image, you have to calculate the size of
- the first cylinder. This value is the offset argument for losetup.
-
- offset = bytes per sector * sectors per cylinder
-
- The command for dlxlinux image looks like this:
-
- losetup /dev/loop0 /usr/local/bochs/dlxlinux/hd10meg.img -o 8704
-
- For images created by bximage you must use the value 32256.
-
-3. The hard disk image access doesn't work if the image contains more than
- one partition.
-
-4. I have made this test with Linux and I don't know how
- this could be done with other operating systems.
-
-
-
-
-
-...on FreeBSD
-
-
-This section was contributed by Alexander Schuch.
-
-
-The following example mounts a Windows 95 hard disk image called Windows 95 B (2031-16-63)
-into the FreeBSD file system. It is specific to FreeBSD 5.x; for
-hints on how to do the same task on FreeBSD 4.x, or for more information in
-general, check the proper section of the FreeBSD handbook:
-Network, Memory, and File-Backed File Systems.
-You can use the same procedure for mounting floppy disk images.
-
-
-
-
-#mdconfig -a -t vnode -f "Windows 95 B (2031-16-63)"
-md0
-
-mdconfig returns the device, your file now is accessable from.
-
-#mount -t msdosfs /dev/md0s1 /mnt
-
-If you already have other md devices configured, you need to substitute md0s1
-with, for example, md6s1.
-
-
-
-Once you are done working with the image, unmount the md device and detach it.
-
-#umount /mnt
-#mdconfig -d -u 0
-
-And again, if there are other md devices configured, use the proper device
-number. In case you forgot the number, just ask mdconfig, like:
-
-#mdconfig -l
-md7
-#mdconfig -d -u 7
-
-
-
-
-
-
-
-Simulating a Symmetric Multiprocessor (SMP) Machine
-
-Bochs can now simulate an SMP machine when you use in the
-configure command. SMP support was added by Bryce Denney, who
-was very interested in watching a multiprocessor operating system work
-at a low level. It should also be helpful to operating system developers
-who are writing SMP drivers, or just for users who want to test drive
-an SMP machine to see what it looks like.
-
-
-Starting with Bochs 2.2.6 you can set up the number of processors in the
-bochsrc. See how to
-set up the number of processors.
-
-
-It is important to understand that configuring Bochs for 4 processors will NOT
-make your single-threaded applications run faster in general! On the contrary,
-it has to spend time simulating idle processors as well as the ones doing your
-task. The point is to simulate an SMP system, not to speed up a uniprocessor
-application.
-
-
-
-What was required to make SMP work in Bochs?
-
-
- local APIC on each processor with timer
-
- one I/O APIC model
-
- implement RDTSC (read time stamp counter)
-
- a data structure called the Intel Multiprocessor Configuration
-must be present in BIOS memory space. An SMP-aware operating system probes BIOS
-memory to find the structure, which contains information about how many
-processors, their IDs, interrupt sources, etc. Starting with Bochs 2.2.5 these
-structures are dynamically created by Bochs.
-
- ACPI support is required to boot SMP system in most of modern
-operating systems. For example, WinXP 64 bit require ACPI support even for
-single processor configuration.
-
-
-
-
-
-What needs to be done to improve SMP support?
-
-
-
-debugger support is still limited. For example, you can set breakpoints,
-but you can't specify which processor you want to set the breakpoint for.
-
-
-
-test on any possible SMP operating systems. Currently success reported for
-Knoppix 4.0.2, WinNT 4.0 and WinXP SMP.
-
-
-
-several parts of the APIC model which weren't needed before are not
-implemented yet.
-
-
-
-A number of people have suggested using threads to simulate each CPU in
-a different thread. Then on a real SMP machine, the threads can execute
-in parallel. This is a great idea, but it's not done at present.
-
-
-
-
-
-Setting Up Networking in DLX Linux
-
-All Bochs binaries come with a working version of DLX Linux. This section
-describes how to configure networking in Bochs and enable it within
-DLX Linux. First you must add a ne2k line in your bochsrc
-file. Then, when you boot the DLX Linux image, you need to type some Linux
-commands to set up an IP address, a network route, and a name server.
-
-
-
-When you have an ne2k line in your bochsrc file, Bochs
-will emulate a network card called an NE2000. Below are some examples of valid
-ne2k lines for various operating systems. Choose the
-one that's closest to what you need, add it to your bochsrc file, and
-edit the values if necessary.
-
- # sample for Mac OS X
- ne2k: ioaddr=0x300, irq=9, mac=b0:c4:20:00:00:00, ethmod=fbsd, ethdev=en0
- # sample for FreeBSD
- ne2k: ioaddr=0x300, irq=9, mac=b0:c4:20:00:00:00, ethmod=fbsd, ethdev=xl0
- # sample for Linux
- ne2k: ioaddr=0x300, irq=9, mac=b0:c4:20:00:00:00, ethmod=linux, ethdev=eth0
- # sample for Windows
- ne2k: ioaddr=0x300, irq=9, mac=00:c4:3B:00:C3:00, ethmod=win32, ethdev=NE2000
-
-You see the pattern. Usually, you won't need to change the I/O address, IRQ
-number, or MAC address. The ethmod value depends on your
-host operating system, and it must be either null,
-fbsd (for FreeBSD or OpenBSD), linux,
-or win32. The ethdev setting is the
-name of the network interface on your system, and is also OS-dependent. On
-UNIX systems you can get the name of the network interface by running
-ifconfig. (Don't choose the loopback interface.) On
-Windows systems, the correct ethdev setting is not always obvious, so we
-provide a utility called niclist to list the names of
-network interfaces to use. When you run niclist, it will
-suggest an ne2k line which is a very good first try.
-
-
-
-Next, if you are on a UNIX machine you will need to become the root user.
-Since Bochs is sending and receiving raw network packets, you need to be root
-to use the network device. To allow normal users to do this would be a
-security problem.
-
-
-
-Now run Bochs to boot DLX Linux. Press 'enter' a few times to accept the default
-configuration choices. This tells Bochs read the configuration file and then
-begin. DLX Linux should boot in the Bochs window, and you should see
-that Linux detects the NE2000 card. Eventually it gets to a login prompt.
-
- ne.c:v1.10 9/23/94 Donald Becker (becker@cesdis.gsfc.nasa.gov)
- NE*000 ethercard probe at 0x300: b0 c4 20 00 00 00
- eth0: NE2000 found at 0x300, using IRQ 9.
-
-
-
-
-At the login prompt, type "root" to log in as root. Then type the ifconfig and
-route commands to set up networking. The exact IP numbers in the example won't
-work for you; you must choose an IP configuration that is legal on your
-network.
-
-
- dlx login: root
- Linux 1.3.89.
- dlx:~# ifconfig eth0 192.168.0.99 # set bochs IP address
- dlx:~# route add -net 192.168.0.0 # first 3 numbers match IP
- dlx:~# route add default gw 192.168.0.1 # your gateway to the net
- dlx:~# _
-
-
-
-
-
-The Bochs IP address must be an unused IP address on your
-network. If you duplicate someone else's IP address, your network will
-become very confused.
-
-
-
-
-Finally, the network is ready and you can test it out with ping, telnet, or ftp
-to various machines by their numerical IP address. Keep in mind that for all
-UNIX host platforms, Bochs networking cannot talk to the host machine. That
-means the host machine can't be the gateway either. You need another physical
-machine on the network that Bochs can talk to. On Win32 this restriction does
-not apply.
-
-
-
-
-When you have a working network configuration, you can make DLX Linux recreate
-the same settings the next time you boot. Just add the ifconfig and route
-commands to the end of /etc/rc.d/rc.inet1. I won't try to describe how
-to use the vi editor in this limited amount of space...
-
-
-
-
-
-
-To configure a name
-server, set up /etc/resolv.conf with the IP address of
-your name server as shown.
-
- dlx:~# echo 'nameserver 192.168.0.1' > /etc/resolv.conf
-
-
-
-
-Configuring and using a tuntap network interface
-
-If you use linux (optionally FreeBSD and Solaris, not tested),
-you may want to access the network through a tuntap interface. The main
-advantage of this interface, is that the guest has access to the host. The guest can even
-have access to the whole network if the host routes or masquerades the guest requests.
-No extra IP address is needed, all can be done using private IP addresses.
-
-
-
-You'll find here instructions to set up Linux/Bochs to provide network access to the guest OS
-through a tuntap interface and private IP network. We're going to see howto :
-
-enable the tuntap interface in the Linux Kernel
-configure Bochs to use the tuntap interface
-set up the private network between the host and the guest
-set up the host to masquerade the guest network accesses
-
-
-
- Tuntap description
-
-From the
-tuntap.txt file in the Linux kernel tree :
-
- TUN/TAP provides packet reception and transmission for user space programs.
- It can be viewed as a simple Point-to-Point or Ethernet device, which
- instead of receiving packets from a physical media, receives them from
- user space program and instead of sending packets via physical media
- writes them to the user space program.
-
- When a program opens /dev/net/tun, driver creates and registers corresponding
- net device tunX or tapX. After a program closed above devices, driver will
- automatically delete tunXX or tapXX device and all routes corresponding to it.
-
-
-
-
-
- Set up the linux Kernel
- <footnote><para>much of the information of the following section is taken from
- <ulink url="http://maconlinux.org/lists/mol-general/August01/0056.html">
- this email from Samuel Rydh of the Mac-On-Linux list</ulink></para></footnote>
-
-First make sure the tuntap module is included in the kernel :
-
-
- if you use a recent distribution, chances are that the needed modules are already build
- Make sure that "Kernel module loader" - module auto-loading support is enabled in your kernel.
- Add following line to the /etc/modules.conf: alias char-major-10-200 tun
- Run: depmod -a The driver will be automatically loaded when application access /dev/net/tun.
-
-
- Otherwise, recompile the kernel, including the configuration option
- CONFIG_TUN (Network device support -> Universal TUN/TAP device driver support)
-
-
-
-
-
-Make sure there is a /dev/net/tun device.
-(Can be created with 'mkdir /dev/net ; mknod /dev/net/tun c 10 200').
-
-
-
-
-In the same way, to use masquerading, you need a kernel with the following options :
-
- CONFIG_IP_NF_CONNTRACK (Connection tracking)
- CONFIG_IP_NF_IPTABLES (IP tables support)
- CONFIG_IP_NF_NAT (Full NAT)
-
-
-
-Some of the other options in this group is probably also needed,
-(but the default setting should be OK).
-
-
-
-
-
-
- Configure Bochs to use the tuntap interface
- Make sure Bochs has one of the network adapters enabled. If you
- have to recompile Bochs, use or
- when running ./configure
- (see )
-
- edit your .bochsrc configuration file and add something like :
- ne2k: ioaddr=0x300, irq=9, mac=fe:fd:00:00:00:01,
- ethmod=tuntap, ethdev=/dev/net/tun0, script=/path/to/tunconfig
-
-
-
- Since the tuntap interface cannot be configured until a process opens it,
- Bochs may run a script file for you. In this case
- /path/to/tunconfig should be changed to match
- the actual place where you'll create this script.
-
-
-
-
-Set up the private network between the host and the guest
-
- We'll set up a private network between the host and the guest with the following parameters:
-
- Host IP : 192.168.1.1
- Guest IP : 192.168.1.2
-
- If your parameters are different, adapt the rest of the section to suit your needs.
-
-
- Create the /path/to/tunconfig script :
-
- #!/bin/bash
- /sbin/ifconfig ${1##/*/} 192.168.1.1
-
- The script gets the interface name as the first parameter. Linux
- will forward incoming packets between interfaces.
-
-
- Make it executable :chmod 755 /path/to/tunconfig
-
-
- Run Bochs, install the guest OS, and set the following network parameters in the guest OS:
-
- IP: 192.168.1.2
- netmask: 255.255.255.0
- gateway: 192.168.1.1
- nameserver: whatever is used in linux
-
-
-
- Bochs must be started by root (at least for now - the
- script won't have root privileges otherwise).
-
-
- You may also have to edit /etc/hosts.allow in the host OS and add :
-
- ALL: 192.168.1.2
-
- Don't forget to set up the route on the guest.
-
-
- At this point, you should be able to ping/telnet/ftp/ssh the guest from the host
- and vice-versa.
-
-
-
-
-Set up the host to masquerade the guest network accesses
-
- We are going to set up standard masquerading configuration. Edit
- the /path/to/tunconfig script ans add :
-
- /sbin/iptables -D POSTROUTING -t nat -s 192.168.1.0/24 -d ! 192.168.1.0/24 -j MASQUERADE >& /dev/null
- /sbin/iptables -t nat -s 192.168.1.0/24 -d ! 192.168.1.0/24 -A POSTROUTING -j MASQUERADE
- echo 1 > /proc/sys/net/ipv4/ip_forward
-
-
-
- The configuration assumes the default policy is
- ACCEPT (can be examined by doing '/sbin/iptables -L')
-
-
- The iptables package must be installed.
- And voila... The host should forward the packets of the guest to the rest of your network.
- You could even have access to the internet...
-
-
- You may need to load other modules if you want to use other fancy protocols (ftp,etc...)
-
-
-
-
-
-
-Using the 'slirp' networking module
-
-Slirp is a software program that emulates a PPP, SLIP, or CSLIP connection to
-the Internet via a shell account. The original version has been written by
-Danny Gasparovski in 1995. It has been integrated in QEMU to provide user mode
-networking. Now a port of the QEMU Slirp implementation is available in Bochs.
-
-
-Features and limitations:
-
-Access to the internet and host network services without root/Administrator
-privileges or additional libraries.
-Builtin DHCP and TFTP servers
-Optional SMB support on Linux
-ICMP traffic (ping) from guest to the host's network or the internet
-not supported
-guest access from the host or external network disabled by default
-
-
-
-This example shows how to use the 'slirp' module with the NE2000 adapter. The line
-is very similar for the E1000 or PCI Pseudo NIC.
-
-ne2k: mac=52:54:00:12:34:56, ethmod=slirp, ethdev=/home/volker/tests/bochs, script=""
-
-The "ethdev" value specifies the TFTP root directory. All other options for Slirp must
-be set in a config file specified with "script" parameter. If no config file is set up,
-Bochs uses this "classic" Slirp configuration shown in the "Default" column below.
-
-Advanced Slirp setup with config file
-
-An example for a Slirp config file can be found in the Bochs sources and in
-binary packages (misc/slirp.conf).
-
Slirp config file options
-
-
-
- Option
- Description
- Default value
-
-
-
-
- restricted
- if set to 1, only built-in services are available
- 0
-
-
- net
- base IP address of the virtual network
- 10.0.2.0
-
-
- mask
- netmask of the virtual network
- 255.255.255.0
-
-
- host
- IP address of the DHCP and TFTP server
- 10.0.2.2
-
-
- hostname
- DHCP client hostname
- undefined
-
-
- dhcpstart
- start address of DHCP pool
- 10.0.2.15
-
-
- dns
- IP address of the virtual DNS server
- 10.0.2.3
-
-
- bootfile
- boot filename returned by DHCP
- undefined
-
-
- dnssearch
- comma-separated list of DNS suffixes to search (DHCP extension)
- undefined
-
-
- smb_export
- absolute path to the shared folder (non-Windows SMB support)
- undefined
-
-
- smb_srv
- alternative IP address of the SMB server
- 10.0.2.4
-
-
- hostfwd
- map guest port to host port for host-to-guest access
- (see below for details)
- undefined
-
-
- pktlog
- specify log file to enable packet logging in text format
- disabled
-
-
-
-
-
-
-Access to guest services from the host
-
-With the config file option "hostfwd" you can map guest ports to ports on the host
-system. This is the format of the directive:
-
- hostfwd = protocol:hostaddr:hostport-guestaddr:guestport
-
-The host and guest IP addresses are optional. This example shows how to access
-the guest SSH server using the host port 12345.
-
- hostfwd = tcp::12345-:22
-
-Up to 5 port redirection rules are supported per slirp instance.
-
-
-
-Using the 'socket' networking module
-
-The original patch for the 'socket' networking module has been written by
-Mariusz Matuszek in 2003. It supported interconnecting two Bochs sessions
-running on the same machine via UDP using an external program called 'bxhub'.
-
-
-The 'socket' networking module is now integrated in the Bochs code with these
-extensions:
-
-Integrated 'vnet' server features (ARP, ICMP-echo, DHCP, DNS, FTP and TFTP)
-Limited DNS server for 'vnet' and connected clients
-Command line options for 'bxhub' added for base UDP port and 'vnet' server features
-Support for connects from up to 6 Bochs sessions
-Support for connecting 'bxhub' on other machine
-
-
-
-The 'socket' networking module uses two UDP ports per Bochs session. By default,
-the first session receives packets from port 40000 and sends packets to port
-40001. The second session uses then the ports 40002 and 40003. For further
-sessions the port numbers are incremented accordingly. The port number for
-receiving packets is specified with the 'ethdev' parameter of the bochsrc
-line for the network adapter. The format is host:port
-for connecting the 'bxhub' utility. If it runs on the same machine
-('localhost') the host name can be omitted.
-
-
-These examples show how to use the 'socket' module with the NE2000 adapter. The line
-is very similar for the E1000 or PCI Pseudo NIC.
-
-ne2k: mac=52:54:00:12:34:56, ethmod=socket, ethdev=mymachine:40000, script=""
-ne2k: mac=52:54:00:12:34:56, ethmod=socket, ethdev=40000, script=""
-
-
-Using the 'bxhub' utility
-
-If bxhub is started without command line options, these
-default values are used:
-
-UDP base port 40000
-2 client connections
-Server MAC address b0:c4:20:00:00:0f
-FTP / TFTP support disabled
-
-
-
-To change the default settings, these parameters are supported:
-
-Usage: bxhub [options]
-
-Supported options:
- -ports=... number of virtual ethernet ports (2 - 6)
- -base=... base UDP port (bxhub uses 2 ports per Bochs session)
- -mac=... host MAC address (default is b0:c4:20:00:00:0f)
- -tftp=... enable FTP and TFTP support using specified directory as root
- -bootfile=... network bootfile reported by DHCP - located on TFTP server
- -loglev=... set log level (0 - 3, default 1)
- -logfile=... send log output to file
- --help display this help and exit
-
-
-
-The vnet FTP service
-
-The 'vnet' server now provides passive FTP support also using the TFTP directory
-as root. The FTP server name is vnet-ftp. For read only access,
-the username must be set to anonymous with any password.
-This mode supports browsing the directory subtree and downloading files. For
-read/write access, the user must be set to bochs with
-password bochs. This enables support for uploading,
-renaming and deleting files, creating, and removing directories.
-
-
-
-
-
-Using Bochs and the remote GDB stub
-
-This section covers how you can use Bochs with a remote GDB stub to debug your kernel.
-
-
-
-Configuring Bochs
-
-The GDB stub is not active in standard Bochs binary package. So you must recompile Bochs.
-Download the Bochs source package, unpack it and run the configure script
-with the argument.
-
-
- $ ./configure --enable-gdb-stub
-
-
-After that, just run make and you should have a Bochs binary that contain a GDB stub in your directory.
-
-
-
-
-Running Bochs
-
-Enable the gdbstub option in bochsrc, then just start Bochs as normal. Bochs will stop and wait for GDB to connect to the stub.
-
-
-
-
-Running GDB
-
-Bochs GDB stub waits for a connection on TCP port 1234. Just start GDB like this:
-
-
- $ gdb YOUR-KERNEL
- .
- .
- .
- (gdb) target remote localhost:1234
- Remote debugging using localhost:1234
- 0x0000fff0 in ?? ()
- (gdb)
-
-
-You are now connected to the remote GDB stub in Bochs. You are now able to set breakpoints.
-Use the continue (c) command to continue the simulation.
-
-Hitting ^C works. Example:
-
-
- Program received signal 0, Signal 0.
- syscall_testsuite_result (aux=0x1f11fe4) at ../rtmk/syscalls.c:33
- 33 {
- (gdb)
-
-
-
-
-
-
-Using the serial port
-
- This section describes what is possible to do with Bochs serial port emulation.
- These examples use dlxlinux disk image
- (downloaded from
-
- http://bochs.sourceforge.net/guestos/dlxlinux3.tar.gz
- ) running as guest, on a debian x86 linux 2.4.19 host.
-
-
- For the examples to work in dlxlinux, after you login as root, you will need to
- kill the running gpm, as it grabs the serial port.
-
-Welcome to DLX V1.0 (C) 1995-96 Erich Boehm
- (C) 1995 Hannes Boehm
-
-
-dlx login: root
-Linux 1.3.89.
-dlx:~# ps | grep gpm
- 30 S0 S 0:00 /usr/bin/gpm -t bare
- 40 1 S 0:00 grep gpm
-dlx:~# kill -9 30
-dlx:~#
-
-
-
- Logging serial port output to a file
-
- The first example shows how to log information sent to the serial port
- on the guest system into a file on the host system.
-
-
- Update the com1: section of your configuration file:
-
-com1: enabled=1, mode=file, dev=serial.txt
-
- After you've launch dlxlinux, everything sent to the serial port will be
- logged to serial.txt :
-
-dlx:~# echo "logging to the serial port" > /dev/cua0
-
-
-host$ cat serial.txt
-logging to the serial port
-host$
-
-
-
- Interactivity : connecting to a virtual terminal
-
- The second example shows how to connect to the guest OS, using a
- virtual terminal on the host OS.
-
-
- First, you need to find an unused virtual terminal. Typically,
- X uses vt7; vt8 and up are unused. On my system, I can
- switch from X to vt9 by pressing ctrl-alt-f9 : this virtual
- terminal is not used, the screen is all black. Pressing alt-f7
- switches back to X.
-
-
- Once you found an unused vt, update the com1: section of your
- configuration file:
-
-com1: enabled=1, mode=term, dev=/dev/tty9
-
- The number must be set according to the terminal you want to use (here 9).
-
-
- Now, launch dlxlinux. After you log in as root and kill gpm,
- enter the following command:
-
-dlx:~# /sbin/agetty 38400 cua0
-
- If you switch to vt9, you can see dlx welcome banner, and the login prompt:
-
-Welcome to DLX V1.0 (C) 1995-96 Erich Boehm
- (C) 1995 Hannes Boehm
-
-
-dlx login:
-
- Note that dlxlinux is configured so you can not login as root from a
- serial port. If you want to login, you have to create a new user first.
-
-
- Also, if you plan to use this feature, the best would be to deactivate
- gpm in /etc/rc.d/rc.local, and add a agetty line in /etc/inittab,
- for example:
-
-T0:1234:respawn:/bin/agetty 38400 cua0
-
-
-
- Interactivity : connecting to a pseudo terminal
-
- The third example is very similar to the second one, except that we
- connect to the guest OS with kermit as client, and we the connection
- is done through a pseudo terminal.
-
-
- This example uses /dev/ptyp0 and /dev/ttyp0 as pseudo terminal pair.
- We will tie Bochs to the controlling terminal, whereas kermit will
- use the slave terminal.
-
-
- Update the com1: section of your configuration file:
-
-com1: enabled=1, mode=term, dev=/dev/ptyp0
-
- and launch dlxlinux. After you log in as root, enter the command:
-
-dlx:~# /sbin/agetty 38400 cua0
-
- Then in the host OS, launch kermit :
-
-host$ kermit -l /dev/ttyp0
-C-Kermit 7.0.196, 1 Jan 2000, for Linux
- Copyright (C) 1985, 2000,
- Trustees of Columbia University in the City of New York.
-Type ? or HELP for help.
-(/tmp/) C-Kermit>connect
-Connecting to /dev/ttyp0, speed 0.
-The escape character is Ctrl-\ (ASCII 28, FS)
-Type the escape character followed by C to get back,
-or followed by ? to see other options.
-----------------------------------------------------
-
-Welcome to DLX V1.0 (C) 1995-96 Erich Boehm
- (C) 1995 Hannes Boehm
-
-
-dlx login:
-
- The same comments as for example 2 apply here.
-
-
-
-
-
-BIOS Tips
-
- Booting from CD-ROMs
-
-A bootable CD-ROM has a special layout that is detected by the
-BIOS boot loader code, and executed if it conforms the specifications.
-This layout is called "El Torito Bootable CD-ROM Format Specification"
-and has been published by Phoenix and IBM. A copy of this spec is on
-Bochs tech specs page.
-
-
-El Torito specifies 3 ways to have a bootable CD:
-
-
-floppy emulation boot: A standard floppy image is burnt on the CD.
-In this case the BIOS has to redirect all first floppy accesses to this
-image and the real floppy drive becomes the second one.
-
-
-a "no emulation" boot: In this case the BIOS is instructed to load an
-arbitrary number of sectors straight into memory, and execute it.
-
-
-hard disk emulation: A hard disk image is burnt on the CD. The
-BIOS has to redirect all hard disk accesses to that image. The real hard disks
-are still available, with BIOS numbers 81h and up.
-
-
-
-In Bochs 2.0, hard disk emulation is not implemented in the BIOS.
-There are also subtilities about multiple boot-images CD-ROMs, that are
-not handled by Bochs.
-
-
-
-However, our BIOS may be more strict than real PC BIOSes, I don't know.
-But I would definitely be interested to know of any CD that can boot
-on real hardware, but does not in Bochs.
-
-
-
-When failing to boot from CD-ROM, the BIOS outputs
-the reason of the failure as
-an error code, in the log file, and on the screen.
-
-
-
-Here is a summary of what can happen when booting from the CD.
-
-
-
CD Boot error codes
-
-
-
-
- Error code
- Reason
-
-
-
- 0x01 no atapi device found
- 0x02 no atapi CD-ROM found
- 0x03 cannot read cd - BRVD
- 0x04 cd is not eltorito (BRVD)
- 0x05 cd is not eltorito (ISO TAG)
- 0x06 cd is not eltorito (ELTORITO TAG)
- 0x07 cannot read cd - boot catalog
- 0x08 boot catalog : bad header
- 0x09 boot catalog : bad platform
- 0x0A boot catalog : bad signature
- 0x0B boot catalog : bootable flag not set
- 0x0C cannot read cd - boot image
-
-
-
-
-
-
-0x01 no atapi device found
-0x02 no atapi CD-ROM found
-
-
-For the first two errors, an ata-*: type=cdrom is probably missing
-from the configuration file. This is what you get if no CD-ROM has
-been defined in Bochs conf file.
-
-
-
-
-0x03 cannot read cd - BRVD
-
-
-For this error, the CD-ROM support has not been compiled in Bochs,
-or Bochs could not open the file or device. This is what you get if
-Bochs is not able to read the cd.
-
-
-
-
-0x04 cd is not eltorito (BRVD)
-0x05 cd is not eltorito (ISO TAG)
-0x06 cd is not eltorito (ELTORITO TAG)
-
-
-For these errors, the data has been read from the cd, but
-the cd does not conform to the El Torito specification. This
-is what you get if the cd is not bootable.
-
-
-
-
-0x08 boot catalog : bad header
-0x09 boot catalog : bad platform
-0x0A boot catalog : bad signature
-0x0B boot catalog : bootable flag not set
-
-
-now the cd is eltorito, but the boot catalog is corrupted, or
-the cd was made to boot on a ppc system. This should not happen
-for a x86 bootable cd.
-
-
-
-
-0x07 cannot read cd - boot catalog
-0x0C cannot read cd - boot image
-
-here, specific part of the cd could not be read. This should
-definitely not happen.
-
-
-
-
- Disk translation
-
-Since the beginning of the PC era, disks have grown in size by a factor of 10000. Due to
-differences between the ATA specification and BIOSes implementations, when disks reached
-critical sizes, it
-became necessary to translate the CHS geometry (cylinders, heads, sectors per track)
-between the BIOS (int 13h) and the ATA interface. Please refer to the
-ATA-FAQ
-and
-Hale Landis' document
-for a complete discussion of the problem.
-
-
-Unfortunately, there has never been any standard on the translation algorithms.
-
-
-Bochs implements 4 well-known algorithms, selectable in the configuration file
-in the "ataX-xxxx: ..., translation='algorithm'" section.
-
-
-
Disk translation algorithms
-
-
-
- Algorithm
- Maximum disk size
- Maximum logical and physical geometry (CHS)
- Description
-
-
-
-
- none
- 528MB (1032192 sectors)
-
- LCHS:1024/16/63
- PCHS:1024/16/63
-
-
- no translation is done. The CHS received at the int13h interface
- is sent as is to the ATA interface.
-
-
-
- large
- 4.2GB (8257536 sectors)
-
- LCHS:1024/128/63
- PCHS:8192/16/63
-
-
- a standard bitshift algorithm (named Extended-CHS)
- is used to translate the CHS between
- the int13h interface
- and the ATA interface. The translation is achieved by
- multiplying/dividing the cylinder/head count by a power of 2
- (2, 4 or 8).
- (a factor of 16 could not be used because the
- head count would become 256, and MS-DOS thought this was 0)
- Note that the number of sectors per track is not changed, so
- a lower spt value will lead to a lower maximum disk size.
-
-
-
- echs
-
-
- synonym for large
-
-
- rechs
- 7.9GB (15482880 sectors)
-
- LCHS:1024/240/63
- PCHS:15360/16/63
-
-
- a revised bitshift algorithm (called Revised Extended-CHS)
- is used to translate the CHS between
- the int13h interface
- and the ATA interface. First the number of physical heads is forced to
- 15, and the number of cylinders is adjusted accordingly.
- Then, as in the simple extended CHS algorithm, the translation
- is achieved by
- multiplying/dividing the cylinder/head count by a power of 2
- (2, 4, 8 or 16).
- The head count being forced to 15, it can safely be multiplied by 16
- without crashing dos.
- Note that the number of sectors per track is not changed, so
- a lower spt value will lead to a lower maximum disk size.
-
-
-
- lba
- 8.4GB (16450560 sectors)
-
- LCHS:1024/255/63
- PCHS:16320/16/63
-
-
- An LBA-assisted algorithm
- is used to translate the CHS between
- the int13h interface
- and the ATA interface. The translation is achieved by
- first computing the physical size of the disk (LBA=C*H*S).
- Then the sectors per track is forced to 63, and the head count
- to 255. Then the cylinder count is computed (C=LBA/(63*255))
- Note that the number of sectors per track is forced to 63
- in the logical geometry, regardless of the actual geometry
- reported by the disk.
- Also note that the LBA-assisted algorithm has nothing to do with
- LBA access at the ATA interface.
-
-
-
- auto
-
-
- the best suited algorithm between none, large and lba is used
-
-
-
-
-
-
-Setting a specific CHS translation should be done if you use a disk dump
-of an actual disk, or use a real disk as a block device. You need to
-know which geometry was used to format the disk, and which translation
-was used. You must not set the translation to 'auto'.
-
-
-
-
-rechs translation should only be useful for Compaq users who wants to
-use a disk as a block device. Please report if you know any other
-system that uses such translation.
-
-
-
-
-If you plan to create a new disk image (for example with bximage),
-format it and install an OS on it, select the "auto" translation
-for an automatic selection
-of the best algorithm based on the disk image size. Be warned that an image created
-with the "auto" translation might not be readable with previous versions of Bochs.
-Upward compatibility will be maintained.
-
-
-
-
-This translation applies only to int13h BIOS disk accesses. Older OSes (e.g., MS-DOS)
-tend to use them a lot. On modern OSes, disk accesses through BIOS int13h are
-limited to boot loaders.
-The usual rules and tricks of the installed OS still apply (i.e., 1024 cylinders boot limit).
-
-
-
-
-
-
-How to enter special key combination
-
-Your window manager may trap the key combination you want to enter
-in Bochs guest OS, for example controlaltdelete. Here is a work-around:
-
-
-Press and hold controlalt,
-move your mouse cursor outside of the Bochs window. Release them, move
-the cursor back in the Bochs window and press delete.
-
-
-This should work for any key combination.
-
-
-If you need one key combination frequently, set it up as user key combination
-with the keyboard option in your
-configuration file. This key combination is sent to the guest OS when you press
-the user button in the headerbar.
-Depending on the used display_library option,
-it may even be possible to edit the shortcut before sending it.
-
-
-
-
- Notes about VESA usage
-
-
- Since Bochs 1.4 it is possible to use VESA graphics. There are some limitations in
- the current implementation, but in general it should work ok (we have run several test
- programs, the XFree86 VESA display driver, etc.)
-
-
-
- In order to use VESA VBE, you need to enable it in your bochsrc by setting the
- vga option to vbe.
- Finally, you need to use the
- LGPL'd VGABIOS
- as vgaromimage option for
- applications to correctly detect VESA support.
-
-
-
- The VGABIOS is already included in the Bochs release, so no separate download is necessary.
-
-
-
- To take advantage of the VBE, you must tell Bochs to use the LGPL'd VGA BIOS
- version 0.4c or higher. A current version of the VGA BIOS will work.
-
-
-
-Current limitations:
-
- 4bpp modes support is incomplete (8, 15, 16, 24 and 32bpp should work)
- banked mode is very slow (if you can, just use Linear Frame Buffering instead!)
- only 320x200, 640x400, 640x480, 800x600, 1024x768 are currently supported
-
-
-
-
-Interesting Facts:
-
- You need a display driver capable of using the VESA BIOS for this to work
- (a recent XFree86 will do, Windows 9x/NT/2K/XP probably will not work 'out of the box'.
- Currently the VBE2 extension should be supported ok
-
-
-
-Instructions to setup Bochs VBE in Windows Guest OS
-This was contributed by Martin Bochnig in February 2004.
-
-Instructions for Win95/98:
-==========================
-I can only confirm that SciTech finally made a VBE driver
-for Windows. It works out of the box, at least with win95
-as guest OS, provided you use Bochs 2.1 with the LGPL
-vgabios.
-
-Here is how I did it :
-- install win95 with the vga driver.
-- download sdd 7 beta from
-- download pmhelp.vxd from
-- copy pmhelp.vxd to the win95 system directory
-- install sdd7
-
-800x600 and 1024x768 in 16 and 24 bpp modes here.
-I did not try 32bpp.
-
-
-This was contributed by Stanislav Shwartsman in September 2004.
-
-Instructions for Win2000/XP:
-============================
-
-Bochs VBE Display Drivers for Windows NT/2000
-
-
-
-
-
-
- Notes about Cirrus SVGA usage
-
-
- Since Bochs 2.2 it is possible to use Cirrus SVGA graphics. The Cirrus device
- supports both ISA and PCI depending on the bochsrc settings.
- If PCI is disabled or the Cirrus card is not assigned to a PCI slot, it appears
- as a CL-GD5430 ISA with 2MB VRAM. If you assign the Cirrus card to a PCI slot,
- it appears as a CL-GD5446 PCI with 4MB VRAM.
-
-
- In order to use Cirrus SVGA, you need to compile Bochs using the
- option and enable it in your bochsrc by setting the
- vga option to cirrus.
- Finally, you need to use the Cirrus version of the
- LGPL'd VGABIOS
- as vgaromimage option for
- applications to correctly detect Cirrus support.
-
-
- # Enable CL-GD5446 PCI
- vga: extension=cirrus
- vgaromimage: file=$BXSHARE/VGABIOS-lgpl-latest-cirrus
- pci: enabled=1, chipset=i440fx, slot1=cirrus
-
-
-
- The VGABIOS is already included in the Bochs release, so no separate download is necessary.
-
-
-
-
- Notes about Voodoo Graphics usage
-
-
- Bochs supports the emulation of 4 different 3dfx Voodoo Graphics adapter models.
- The Voodoo1 and Voodoo2 models are 3D-only add-on cards and require a VGA
- compatible primary device. The Voodoo Banshee and its successor Voodoo3 have
- both a VGA core and a 2D/3D core, so no other VGA card is required. The 2D/3D
- cards can be assigned to AGP if the i440BX chipset is selected (slot #5).
-
-
- To emulate the Voodoo1 or Voodoo2 device only the "model" parameter of the
- bochsrc option "voodoo" needs to be set. If the vga extension option is set
- to "voodoo" in that case, the primary display adapter is an ISA VGA card.
-
-
- For emulating the Voodoo Banshee or Voodoo3 adapter, the vga extension option
- must be set to "voodoo". Using a different primary display adapter and a
- Banshee compatible device with its VGA interface disabled is not
- implemented yet. For both Banshee and Voodoo3 there is now a specific version
- of the LGPL'd VGABIOS with Voodoo Banshee specific code called
- VGABIOS-lgpl-latest-banshee. The binary file is compiled
- for the Banshee PCI model, but Bochs modifies the VGABIOS data after loading
- to support the Voodoo3 and AGP models properly.
-
-
- These bochsrc settings should be used for Voodoo Banshee PCI:
-
- vga: extension=voodoo
- vgaromimage: file=VGABIOS-lgpl-latest-banshee
- voodoo: model=banshee
-
-
-
- This additional setting is required for Voodoo Banshee AGP:
-
- pci: chipset=i440bx, slot5=voodoo
-
-
-
- To support the Voodoo3 just change the model:
-
- voodoo: model=voodoo3
-
-
-
-
-Disk Image Modes
-
-Bochs can handle independent disk image format for each
-disk present on the ata interfaces.
-
-The disk image type is selected in the configuration file
-by the "mode" option of the ataX-xxx directives.
-Example:
-
-
-ata0-master: type=disk, mode=flat, path=10M.sample, cylinders=306, heads=4, spt=17
-
-
-
-
-
-If unspecified, the default "mode" is flat.
-
-
-
-
-
Supported Disk Modes
-
-
-
- Name
- Description
- Features
-
-
-
- flat one file, flat layout
-
- accessible with mtools or winimage-like tools
-
-
- concat multiple files, concatenated
-
- mappable to contained partitions
-
-
- dll accessed through a DLL
-
- developer specific, win32 / win64 only
-
-
- sparse up to 10 layers stackable files
-
- commitable, rollbackable, growing
-
-
- vmware3 vmware3 disk support
-
- vmware version 3 compatibility
-
-
- vmware4 vmware4 disk support
-
- vmware version 4 (VMDK) compatibility
-
-
- undoable read-only base file with a commitable redolog
-
- commitable, rollbackable
-
-
- growing one growing file
- growing
-
-
- volatile read-only base file with a volatile redolog
-
- always rollbacked
-
-
- vpc VirtualPC disk support
-
- fixed / dynamic size supported
-
-
- vbox Oracle(tm) VM VirtualBox disk support
-
- VDI version 1.1 fixed / dynamic size supported
-
-
- vvfat local directory appears as VFAT disk (with volatile redolog)
-
- optional commit or rollback
-
-
-
-
-
-
-
-flat
-
-
-description
-
-In flat mode, all sectors of the harddisk are stored in one flat file,
-in lba order.
-
-
-image creation
-
-Flat disk images can be created with the bximage utility
-(see for more information).
-
-
-path
-
-The "path" option of the ataX-xxx directive in the configuration file
-must point to the flat image file.
-
-
-external tools
-
-Flat images content can be accessed from the host by the
-following tools :
-
- mtools (see )
- mount with a loopback (see )
- Winimage / DiskExplorer (see )
- Bochs Tools (see )
-
-
-
-typical use
-
-Flat mode is Bochs default harddisk layout. This is also
-the layout of disk images provided on Bochs websites.
-
-
-limitations
-
-On some host OSes, Bochs flat disk images are limited to 2GiB.
-
-
-
-
-
-concat
-
-
-description
-
-In concat mode, all sectors of the harddisk are stored in several flat files,
-in lba order.
-
-
-image creation
-
-Disk images for the usage in 'concat' mode can be created as 'flat' mode image
-files with the bximage utility (see for more
-information).
-
-
-path
-
-The "path" option of the ataX-xxx directive in the configuration file
-must point to the first file (e.g. win95-1). The lower layer files names are
-found by adding 1 to the last character (e.g. win95-2, win95-3, etc.).
-
-
-external tools
-
-If every single file contains a complete partition, they can be accessed
-with same tools as the 'flat' mode images.
-
-
-typical use
-
-If the partition sizes and file sizes are set up correctly, this allows you to
-store each partition in a separate file, which is very convenient if you want
-to operate on a single partition (e.g. mount with loopback, create file system,
-fsck, etc.).
-
-
-limitations
-
-On some host OSes, there is a limit of 2GiB per file.
-
-
-
-
-dll
-
-
-description
-
-This mode is only useful for developers and needs an additional win32 / win64
-DLL loaded by Bochs at runtime.
-
-
-
-
-sparse
-
-
-description
-
- Sparse disk support has been added by JustinSB. Sparse disk features are:
-
-
-
- Large hard drive can be created, and only used space will be stored
- in the file. In practice, on Unix, this is not a large gain as it is
- done anyway.
-
-
-
-
- Multiple sparse drive images can be mounted on top of each other.
- Writes go to the top image. This allows several similar configurations
- to share a master "base" file, and also allows file system rollback or
- no-write options. Up to 10 disk images can be layered on top of each other.
-
-
-
-
-
-image creation
-
-Sparse disk images must be created with the bximage utility
-(see for more information).
-Be sure to enter "sparse" when selecting the image type.
-
-
-path
-
-The "path" option of the ataX-xxx directive in the configuration file
-must point to the top layered file. The lower layer files names are found by
-substracting 1 from the last character (must be a digit)
-
-
-external tools
-
-The bximage utility (see provides convert and
-resize support for "sparse" mode images.
-
-
-typical use
-
- Space Saving
-
- Create a sparse disk image using bximage. Set size to eg 10GB.
- Only allocated space will be stored,
- so your drive image should be only about as large as the files stored on it.
-
-
-
-
- Disk Rollback
-
-
-
-
- Create a sparse disk image called "c.img.0". Point .bochsrc at "c.img.0".
- In Bochs, install your favorite OS. Switch off Bochs.
-
-
-
-
- Create a sparse disk image (of the same size)
- and name it "c.img.1". Point .bochsrc at "c.img.1"
- "c.img.0" is visible, but all writes go to "c.img.1".
- After using Bochs, you can simply delete
- "c.img.1" to undo changes and go back to a clean OS install.
-
-
-
-
-
-
-
- Disk Optional Commit
-
-
-
-
- Create a sparse disk image called "c.img.0". Point .bochsrc at "c.img.0".
- In Bochs, install your favorite OS. Switch off Bochs.
-
-
-
-
- Create a sparse disk image (of the same size) and name it "c.img.1".
- Point .bochsrc at "c.img.1"
- "c.img.0" is visible, but all writes go to "c.img.1".
- After using Bochs, if you want to keep the
- changes, use the (currently non-existent) merge utility
- to make a single unified drive image.
-
-
-
-
- Alternatively, simply create a new partition on top called "c.img.2".
-
-
-
-
-
-
-
- Common Base
-
-
-
- Create a sparse disk image called "base.img". Point .bochsrc at "base.img".
- In Bochs, install your favorite OS. Switch off Bochs.
-
-
-
-
- Create a sparse disk image (of the same size) and name it "www.img.1".
- Make "wwww.img.0" a symlink to
- "base.img". Point .bochsrc at "www.img.1". Using Bochs, install a webserver.
-
-
-
-
- Create a symlink to "base.img" called "db.img.0".
- Create a sparse disk image (of the same size)
- and name it "db.img.1". Point .bochsrc at "db.img.1".
- Using Bochs, install a database server.
-
-
-
-
-
- Now both a database server and webserver can be
- run in separate virtual machines, but they share the common OS image,
- saving drive space.
-
-
-
-
-limitations
-
- There is a need for supporting utilities (yet unwritten) :
-
-
- to merge two sparse disk images into a single image
-
-
- to defragment a sparse disk image and remove unused space
-
-
-
-
-
-
-vmware3 / vmware4
-
-
-description
-
-Sharvil Nanavati has added vmware3/4 disk image support into Bochs
-for Net Integration Technologies, Inc.
-You should be able to use disk images created by vmware version 3 and 4.
-
-
-image creation
-
-Create such disk image with vmware version 3 or 4.
-
-
-path
-
-The "path" option of the ataX-xxx directive in the configuration file
-must point to the vmware3/4 disk image.
-
-
-external tools
-
-&FIXME; In addition to the utilities provided by VMware Inc. some other freeware
-tools are available.
-
-
-typical use
-
-If you want to use an existing vmware3/4 disk image.
-
-
-limitations
-
-Only vmware versions 3 and 4 disk image files are supported.
-
-
-
-
-undoable
-
-
-description
-
- Undoable disks are commitable/rollbackable disk images.
- An undoable disk is based on a read-only image, associated
- with a growing redolog, that contains all changes (writes)
- made to the base image content. Currently, base images of
- types 'flat', 'sparse', 'growing', 'vmware3', 'vmware4' and
- 'vpc' are supported.
-
-
- This redolog is dynamically created at runtime, if it does not
- previously exists.
-
-
- All writes go to the redolog, reads are done from the
- redolog if previously written, or from the base file
- otherwise.
-
-
- If unspecified with the "journal" option of the ataX-xxx directive,
- the redolog file name is created by adding a ".redolog"
- suffix to the base image name.
-
-
- File size of the redolog can grow up to the total disk
- size plus a small overhead due to internal data management
- (about 3% for a 32MiB disk,
- less than 0.5% for a 2GiB disk).
-
-
- After a run, the redolog will still be present, so the changes
- are still visible the next time you run Bochs with this disk image.
-
-
-image creation
-
- The base disk images must be created with the bximage utility
- (see for more information).
- The redolog file is created automatically if it doesn't exist.
-
-
-path
-
- The "path" option of the ataX-xxx directive in the configuration file
- must be the base image name. The redolog name can be set with the "journal"
- option of the same directive. If not set, the redolog name is created by
- adding the ".redolog" suffix to the base image name.
-
-
-external tools
-
- To access the 'flat' mode base disk image content,
- see for available tools.
-
-
-
- The up-to-date content can only be seen after you commit the redolog
- to the flat file with the bximage utility.
-
-
-
-typical use
-
-Commit
-
- After a run, the redolog can be committed (merged)
- to the base image with the bximage utility.
-
-Rollback
-
- After a run, the redolog can be rollbacked (discarded)
- by simply deleting the redolog file.
-
-Common Base
-
- One base disk image with a guest OS installed can be used to install
- different software as described above for the "sparse" disk image mode.
-
-Harddisk Image on a Read-Only Medium
-
- In the 'undoable' mode, the base file is always opened in read-only mode,
- so it can safely be stored on a read-only medium (for example on a CD-ROM).
- In that case it is recommended to specify the redolog file with the
- "journal" option.
-
-
-
-limitations
-
- The "undoable" disk depends on the limitations of base disk image used.
-
-
-
-
-growing
-
-
-description
-
- Growing disk images start as small files, and
- grow whenever new data is written to them.
-
-
- Once a sector is
- written in the growing file, subsequent writes to the same
- sector will happen in place.
-
-
- File size of Growing disk images can go up to the total disk
- size plus a small overhead due to internal data management.
- (about 3% for a 32MiB disk,
- less than 0.5% for a 2GiB disk).
-
-
-image creation
-
-Growing disk images must be created with the bximage utility
-(see for more information).
-Be sure to enter "growing" when selecting the image type.
-
-
-path
-
- The "path" option of the ataX-xxx directive in the configuration file
- must be the growing image name.
-
-
-external tools
-
- The bximage utility (see provides convert
- and resize support for "growing" mode images.
-
-
-typical use
-
- Growing disk images can be used whenever you want to maximize disk space.
- However, please note that Bochs will not check if enough disk space is
- available before writing new data. If no disk space is available, a panic
- will occur.
-
-
-limitations
-
- The size of the virtual disk is currently limited to 8 TB, but the maximum size
- of the image file depends on host OS limitations.
-
-
-
-
-volatile
-
-
-description
-
- Volatile disks are always-rollbacked disk images.
- A volatile disk is based on a read-only image, associated with
- a growing redolog, that contains all changes (writes)
- made to the base image content. Currently, base images of
- types 'flat', 'sparse', 'growing', 'vmware3', 'vmware4', 'vpc' and
- 'vbox' are supported.
-
-
- The redolog is dynamically created at runtime, when
- Bochs starts, and is deleted when Bochs closes (win32)
- or just after it has been created (Unix).
-
-
- All writes go to the redolog, reads are done from the
- redolog if previously written, or from the base file
- otherwise.
-
-
- If unspecified with the "journal" option of the ataX-xxx directive,
- the redolog file name is created by adding a ".redolog"
- suffix to the base image name.
-
-
- File size of the redolog can grow up to the total disk
- size plus a small overhead due to internal data management
- (about 3% for a 32MiB disk,
- less than 0.5% for a 2GiB disk).
-
-
- After a run, the redolog is not any more present, so the changes
- are discarded.
-
-
-image creation
-
- The base disk images must be created with the bximage utility
- (see for more information).
- The temporary redolog file is created automatically.
-
-
-path
-
- The "path" option of the ataX-xxx directive in the configuration file
- must be the base image name. The redolog name can be set with the "journal"
- option of the same directive.
- If not set, the redolog name is created by adding the
- ".redolog" suffix to the base image name.
- A random suffix is also appended to the redolog name.
-
-
-external tools
-
- To access 'flat' mode base disk image content,
- see for available tools.
-
-
-typical use
-
-Repeatable simulations
-
- &FIXME; to be completed
-
-Multiple Bochs instances
-
- &FIXME; to be completed
-
-Harddisk Image on a Read-Only Medium
-
- In the 'volatile' mode, the base file is always opened in read-only mode,
- so it can safely be stored on a read-only medium (for example on a CD-ROM).
- In that case it is recommended to specify the redolog file with the
- "journal" option.
-
-
-
-limitations
-
- The "volatile" disk depends on the limitations of base disk image used.
-
-
-
-
-vpc
-
-
-description
-
- The "vpc" disk image mode is mostly a port of Qemu's "vpc" block
- driver for VirtualPC disk images (written by Alex Beregszaszi and Kevin Wolf).
-
-
-image creation
-
- Create such disk image with Microsoft VirtualPC (tm), Qemu's disk image
- utility (qemu-img) or bximage utility
- (see for more information).
-
-
-path
-
- The "path" option of the ataX-xxx directive in the configuration file
- must point to the VirtualPC disk image.
-
-
-external tools
-
- Use Microsoft VirtualPC (tm) tools to manipulate these disk images.
-
-
-typical use
-
- Share disk images with VirtualPC.
-
-
-limitations
-
- The based on the Qemu code the disk size is limited to 127 GB.
-
-
-
-
-vbox
-
-
-description
-
- The "vbox" disk image mode for VirtualBox disk images (VDI version 1.1)
- has been written by Benjamin D. Lunt.
-
-
-image creation
-
- Create such disk image with Qemu's disk image utility (qemu-img).
-
-
-path
-
- The "path" option of the ataX-xxx directive in the configuration file
- must point to the VirtualBox disk image.
-
-
-external tools
-
- Use VirtualBox tools to manipulate these disk images.
-
-
-typical use
-
- Share disk images with VirtualBox.
-
-
-limitations
-
- &FIXME; to be completed
-
-
-
-
-vvfat
-
-
-description
-
- The "vvfat" disk image mode is mostly a port of Qemu's "virtual VFAT" block
- driver (written by Johannes E. Schindelin). It supports the read-only part
- of this implementation plus some additions. The structures of the
- virtual disk are created from the contents of the specified local directory
- when Bochs is starting. All writes to this virtual disk go to a volatile
- redolog and when closing Bochs, the user can decide whether or not to commit
- the changes. If "No" is seclected, all changes will be lost when Bochs quits
- and the files of the local directory are not modified. Otherwise, the changes
- of files and directories are committed. WARNING: Don't use important data without
- backup in the "vvfat" directory when using this "optional commit" feature.
-
-
- In addition to Qemu's "vvfat" implementation the Bochs one supports configurable
- disk geometry, FAT32 and reading MBR and/or boot sector from file. When using
- the autodetection feature, the CHS values 1024/16/63 (Qemu defaults) are used.
- To use an MBR image file from a real disk it must be named vvfat_mbr.bin
- and placed in the specified directory. Bochs uses the geometry and file system
- type from this file and doesn't show it on the virtual disk. The same applies
- to a boot sector image file, but it must be named vvfat_boot.bin.
- Using both image file is also possible if they match (grabbed from the same disk).
-
-
- FAT32 is enabled for disk with minimum 2 GB size, or if MBR / boot sector image
- enable this filesystem. When using "vvfat" for a floppy, FAT12 is used (1.44M
- media only). In all other cases FAT16 is used. Long filename support
- is always present.
-
-
- Special FAT file attributes are stored in a special file named vvfat_attr.cfg.
- When using the "optional commit" feature, modified attributes are saved to this file.
- The "optional commit" also supports setting the file modification date and time.
-
-
-image creation
-
- Not necessary. The directory must exist before running Bochs.
-
-
-path
-
- The "path" option of the ataX-xxx directive in the configuration file
- must point to an existing local directory. The redolog name can be set
- with the "journal" option of the same directive. If not set, the redolog
- name is created by adding the filename "vvfat.dir.redolog" to the path.
- A random suffix is also appended to the redolog name.
-
-
-external tools
-
- You can use your favourite file manager to copy file to the directory you'd
- like to use. The directory should not be modified while Bochs is running.
-
-
-typical use
-
- Accessing files of the host hard drive is only possible with vvfat.
-
-
-limitations
-
- There is no runtime write support present yet. All changes are written to
- the volatile redolog and they can only be committed on Bochs exit.
-
-
- When using the MBR from image file only the first partition is used and it
- must be of type FAT16 or FAT32. FAT12 can be used for the floppy only.
- An extended partition or other file system types are not supported.
-
-
- The "vvfat" implementation does not support save/restore, since there is no
- check if the host directory tree and all files are unmodified after saving
- the Bochs state.
-
-
-
-
-
-
-
-
-
-Using the bximage tool
-
-Bximage is an easy to use console based tool for creating, converting and
-resizing disk images, particularly for use with Bochs. It also supports
-committing redolog files to their base images. It is completely interactive
-if no command line arguments are used. It can be switched to a non-interactive
-mode if all required parameters are given in the command line.
-
-
-When you run bximage without one of the following options, it will appear in
-interactive mode and ask for all required parameters to manipulate an image.
-
-Usage: bximage [options] [filename1] [filename2]
-
-Supported options:
- -func=... operation to perform (create, convert, resize, commit, info)
- -fd=... create: floppy image with size code
- -hd=... create/resize: hard disk image with size in megabytes (M)
- or gigabytes (G)
- -imgmode=... create/convert: hard disk image mode
- -b convert/resize: create a backup of the source image
- commit: create backups of the base image and redolog file
- -q quiet mode (don't prompt for user input)
- --help display this help and exit
-
-Other arguments:
- filename1 create: new image file
- convert/resize: source image file
- commit: base image file
- filename2 convert/resize: destination image file
- commit: redolog (journal) file
-
-
-
-
-Disk image mode autodetection does not work for the modes concat
-and dll. To use those images as convert source, you have to
-add a prefix ("concat:" or "dll:") to the image path.
-
-Create image
-
-This function can be used to create several disk image formats for the
-use with Bochs. See the table above for supported formats (modes).
-For an example of the usage, refer to .
-
-
-Convert image
-
-With this function a disk image can be converted from one mode (format)
-to another. The type of the source image is auto-detected. For the target
-format it supports the same disk image modes as the create function. If the
-name of the new image file is not specified or identical to the source one
-and you have enabled the backup switch, a backup of the source file will be
-created with its original name plus the suffix ".orig".
-
-
-Resize image
-
-This function can be used to increase the virtual disk size of an image.
-It supports the same disk image modes as the create function.
-Making a disk image smaller is not supported, since it may damage the
-disk and data will be lost. If the name of the new image file is not
-specified or identical to the source one and you have enabled the backup
-switch, a backup of the source file will be created with its original name
-plus the suffix ".orig".
-
-
-Commit 'undoable' redolog to base image
-
-The type of the base image is auto-detected. The name of the redolog
-file only needs to be specified if it is not based on the base image.
-If you have enabled the backup switch, backups of the original base and
-redolog files will still be created with their original name plus the
-suffix ".orig".
-
-
-Disk image info
-
-This function can be used to determine the disk image format, geometry
-and size. Note that Bochs can only detect the formats growing, sparse,
-vmware3, vmware4, vpc and vbox correctly. Other images with a file size
-multiple of 512 are treated as flat ones. If the image doesn't support
-returning the geometry, the cylinders are calculated based on 16 heads
-and 63 sectors per track.
-
-
-
-
-
-
-
-Guest operating systems
-
-In the past several tweaks were necessary to install a guest OS inside of Bochs.
-Nowadays, it is almost the same as installing it on a real machine. There are only
-a few Bochs specific issues you should know about. Note that we cannot give you
-a full installation guide if you don't know how to install an OS in the real
-world. The following remarks apply to all guest OS installations. Some specific
-issues are reported in the next sections.
-
-
-First of all, you need the installation media or image (floppy/CD/DVD).
-For platforms that don't support raw device access it might be necessary to
-create an image from the media. Please read the message regarding software
-licenses in before you install or use a commercial
-guest operating system in Bochs.
-
-Then you need to create a hard drive image with bximage. For the
-required size see the documentation of the OS you'd like to install. See
- how to create the image.
-
-Finally you have to create configuration for your guest OS. You can
-edit the sample configuration distributed with Bochs or use the configuration
-interface to adjust the settings. Check the documentation of your guest OS for
-the required memory size, cpu speed and supported hardware.
-
-
-Now you should be able to run Bochs and start the installation process. Depending
-on the host cpu speed and the size of the guest OS it can take a few minutes or
-even some hours.
-
-
-
-What disk images are available.
-What works
-Known problems
-
-
-
-
- Knoppix
-
-
- Contributed by Alexander Schuch.
-
-
-
- Getting Knoppix
-
-
- Knoppix is a live CD (700M) or live DVD (3.2G) based on Debian GNU/Linux, with lots of
- ready-to-run programs (web browser, office suite, a few games, and more), using
- KDE as desktop environment. It can be booted directly from CD, without
- any installation needed. You can download it from knoppix.org.
-
-
-
-
- Preparing Bochs
-
-
- As Knoppix runs completely from CD/DVD, you don't need to setup a hard disk. You just need to set up
- the location of the downloaded ISO image in your bochsrc, and make Bochs boot
- from it. Because Knoppix contains a graphical user interface, and has no other storage space but
- the emulated RAM, it needs at least 128MB of it, see
- megs option. Furthermore, you need to enable VBE support in
- Bochs (see ).
-
-
-
-
- Using Knoppix
-
-
- There is nothing more to do! Just start Bochs and wait for Knoppix to load...
-
-
-
- You are logged in as normal user, if you want to become super user, just su.
- There is no password needed (empty password).
-
-
-
-
-
-
- FreeBSD 5.2.1
-
-
- Contributed by Alexander Schuch.
-
-
-
- This section describes how to install FreeBSD 5.2.1 (miniinst) inside of Bochs, using an ISO image.
-
-
-
- Getting FreeBSD
-
-
- As 5.2.1-RELEASE-i386-miniinst.iso (240M) is no longer available from
- the FreeBSD FTP server, you might want to ask a (file) search engine of your choice
- for a download location. Once you downloaded the file, you should check its integrity
- using the provided MD5 checksum from the
- FreeBSD 5.2.1 release announcement.
-
-
-
-
- Preparing Bochs
-
-
- Create a new hard disk image using bximage (see
- ) with a size of at least 350M, as the standard
- installation uses 280M on its own.
-
-
-
- Next, you need to setup your bochsrc so that Bochs knows about your
- (still empty) hard disk, as well as about your ISO image. Make Bochs boot from CD-ROM and
- start the emulation.
-
-
-
-
- Installing FreeBSD
-
-
- This is just a very short step-by-step installation guide for FreeBSD in Bochs. It
- doesn't explain what you do nor why you do it, it just tells you how to do it.
- For in-depth information refer to the FreeBSD handbook:
- Installing FreeBSD.
-
-
-
- FreeBSD boots up and shows a nice (text-mode) boot option screen. Just press
- return there, that is, use the default option. After loading the
- kernel and needed device drivers, select 'Standard' in the installation menu.
-
-
-
- A fdisk like partition program is loaded next, where you just press A
- to use the entire disk, followed by Q to finish the selection. The next
- dialog asks for the boot manager you want to use. Select 'Standard' and continue.
-
-
-
- In the Disklabel Editor, you have to setup the layout of your partition. If your (virtual)
- hard disk is large enough, you can press A for auto-layout. However, you
- need to make sure that the /usr partition is at least
- 250M large, or you will end up with a 'disk full' error message during installation. If
- this is not the case, select one partition after another and press D to
- delete it again. After you deleted all partitions, create two new ones. The first one will
- be a swap partition; press C, enter '32M' as size and select 'Swap' from
- the dialog. Press C again, and accept the remaining capacity for your
- filesystem partition. Choose 'FS' as partition type and enter '/' (slash) as mount point.
- Your partition layout is complete now; press Q to leave the editor.
-
-
- This 'all-in-one' partition layout is not recommended for a FreeBSD installation on a
- real box; use 'auto-layout' or something comparable to that there.
-
-
-
-
- You now can choose what set of programs/files (distribution) you want to install. Take
- 'User' (option 8), and select 'No' when asked to install the ports collection. You are
- back in the distribution selection, where you select the first item, called 'Exit'.
- Choose to install from 'CD/DVD' and answer the 'Are you sure?' dialog with 'yes'.
-
-
-
- Now, while FreeBSD installs, it is a very good time to take a look at the
- FreeBSD documentation, especially
- the FreeBSD handbook
- and the FreeBSD FAQ.
-
-
-
-
- Post-installation configuration
-
-
- All files are installed on your (virtual) hard disk now, and FreeBSD is ready for getting set
- up. As this is a very basic FreeBSD installation, you just answer 'no' to nearly all questions,
- but the one about your mouse: Answer 'yes' for PS/2 mouse, and choose 'Exit' at mouse configuration.
- The minimalist FreeBSD ISO image contains nearly no binary packages, so don't browse the package
- collection. Then, when asked to create a new user account, answer 'yes' and create a new user
- called 'bochs' (or whatever you like). You might want to use /bin/csh
- or /bin/tcsh as shell rather than /bin/sh. Next,
- you are asked for the super user (root) password. The installation is finished now, there is
- no need to visit the general configuration menu again - answer 'no' to that question. FreeBSD
- will then reboot. Shutdown Bochs, as soon as the (virtual) computer boots.
-
-
-
-
- Using FreeBSD
-
-
- Open your bochsrc and change the boot sequence, so that Bochs will boot
- from hard disk, rather than from CD-ROM from now on. Start Bochs again and watch the FreeBSD
- boot process.
-
-
-
- Your keyboard might use the wrong keymap, so login (into FreeBSD) as super user and use
- /stand/sysinstall to start the FreeBSD configuration program. Choose
- 'keymap' and select the keymap you want to use.
-
-
-
- You have successfully installed FreeBSD now. You might want to shutdown FreeBSD using
- shutdown -h now, quit Bochs, and create a backup of your hard disk
- image, before you start playing around.
-
-
-
-
- DOS
-Please read the message regarding software licenses in
- before you install or use MS-DOS, DR-DOS, FreeDOS or
-any other DOS as a guest operating system in Bochs.
-Accessing your CD-ROM
-
-To access your CD-ROM in DOS, you must download an IDE CD-ROM driver.
-Bochs emulates a very generic CD-ROM drive, and several drivers are known to
-work. Others don't. This section describes how to set up your
-config.sys and autoexec.bat to enable
-the CD-ROM.
-
-
-
-The drivers that have been reported to work are
-OAKCDROM.SYS that comes with several versions of Windows
-and SBIDE.SYS version 1.21 from Creative
-Labs
-
-To get it, go to Creative Labs web
-site, click on Support, then click Download Files. You get to a screen
-where you must select the operating system and the product for which you want
-the driver. Choose DOS as the operating system, and "CD-ROM: 4x and above" as
-the product. There are several choices, but you want
-sbide121.exe from April 15, 1997. Version 2.0 does not
-work. The download file is a self-extracting ZIP file, so on
-DOS or Windows you just run it; on other platforms you can try using
-the unzip command. The driver is called SBIDE.SYS.
-.
-Copy the driver to your boot disk, and then set up the startup files as follows:
-
-
-config.sys:
- device=himem.sys
- device=oakcdrom.sys /D:CD001
- -or-
- device=sbide.sys /D:CD001 /P:1f0,14,3f6
-
-autoexec.bat:
- mscdex.exe /M:10 /D:CD001
-
-
-
-If the files mentioned in config.sys and
-autoexec.bat are not in the root directory, give the full
-pathname, like c:\windows\himem.sys.
-
-
-
-SB16 driver for DOS
-
-To use the SB16 device in DOS you need to load a driver for it. The file
-SBBASIC.EXE contains a self-extracting archive with all required file.
-After unpacking it to C:\SB16 you can execute INSTALL.EXE
-to install the driver. The file DISK.ID should contain the version
-string SDR-31STD-1-US (Revision 1).
-
-
-Bootdisks of early DOS versions
-
-On the Web, there are bootdisks available for most of the DOS versions ever released,
-but some of them have been reported to fail in Bochs. The bootdisk for MS-DOS 1.25
-contains a boot sector of a newer DOS version, so it would fail on real hardware,
-too. The floppy image for MS-DOS 2.11 has a boot sector that tries to boot from
-hard disk instead of the floppy.
-
-
-
-
-
- Windows 95
-Contributed by Benjamin David Lunt
-Please read the message regarding software licenses in before you install Windows 95 as a guest operating system in Bochs.
-
-Windows 95 has been reported to install from the CD-ROM, and run inside Bochs.
-Here are a few settings that seem to work well when running on a Windows10 host, running at 3.0Ghz.
-
-romimage: file=D:/path/to/your/bios/BIOS-bochs-latest
-cpu: model=broadwell_ult
-cpu: count=1, ips=50000000, reset_on_triple_fault=1, ignore_bad_msrs=1
-cpu: cpuid_limit_winnt=0
-clock: sync=realtime, time0=local
-memory: guest=512, host=512
-vgaromimage: file=D:/path/to/your/bios/VGABIOS-lgpl-latest-cirrus
-vga: extension=cirrus, update_freq=5
-pci: enabled=1, chipset=i440fx, slot1=cirrus
-
-
-
-
-
- Windows 98SE
-Contributed by Benjamin David Lunt
-Please read the message regarding software licenses in before you install Windows 98 as a guest operating system in Bochs.
-
-Windows 98SE has been reported to install from the CD-ROM, and run inside Bochs.
-Here are a few settings that seem to work well when running on a Windows10 host, running at 3.0Ghz.
-
-romimage: file=D:/path/to/your/bios/BIOS-bochs-latest
-cpu: model=corei7_haswell_4770
-cpu: count=1, ips=55000000, reset_on_triple_fault=1, ignore_bad_msrs=1
-cpu: cpuid_limit_winnt=0
-clock: sync=realtime, time0=local
-memory: guest=512, host=512
-vgaromimage: file=D:/path/to/your/bios/VGABIOS-lgpl-latest-cirrus
-vga: extension=cirrus, update_freq=5
-pci: enabled=1, chipset=i440fx, slot1=cirrus
-
-
-
-
-
- Windows NT 4.0
-
-Please read the message regarding software licenses in
- before you install Windows NT 4.0 as a guest operating system in Bochs.
-
-
-Here are the known issues about installing and running Windows NT4.0 :
-
-
-
-
-If you want to use the LGPL'd VGABIOS to install Windows NT 4.0 you'll need
-version 0.4c or higher. With older versions you'll get a black screen after
-first reboot.
-
-
-
-
-to log in you must press ctrl-alt-del, and it is likely that the window manager
-will trap this key combination. You can either use the trick described in
- or define a user short-cut
-(callable through the user short-cut GUI button)
-in you configuration file, for example:
-
-keyboard: user_shortcut=ctrl-alt-del
-
-
-
-
-
-For installing and using Windows NT it is necessary to limit the maximum CPUID
-to 3. In the configuration file you need to add a line like this:
-
-cpuid: cpuid_limit_winnt=1
-
-
-
-
-
-
-
- Windows 2000 / Windows 2000 Server
-Please read the message regarding software licenses in
- before you install Windows 2000 / Windows 2000 Server as a guest operating system in Bochs.
-
-
-
-
-
- Windows XP
-Contributed by Benjamin David Lunt
-Please read the message regarding software licenses in
- before you install Windows XP as a guest operating system in Bochs.
-
-Windows XP has been reported to install from the CD-ROM, and run inside Bochs.
-Here are a few settings that seem to work well when running on a Windows10 host, running at 3.0Ghz.
-
-romimage: file=D:/path/to/your/bios/BIOS-bochs-latest
-cpu: model=broadwell_ult
-cpu: count=1, ips=75000000, reset_on_triple_fault=1, ignore_bad_msrs=1
-cpu: cpuid_limit_winnt=0
-clock: sync=realtime, time0=local
-memory: guest=512, host=512
-vgaromimage: file=D:/path/to/your/bios/VGABIOS-lgpl-latest-cirrus
-vga: extension=cirrus, update_freq=5
-pci: enabled=1, chipset=i440fx, slot1=cirrus
-
-A known issue is to set the IPS value to less than 10,000,000 (minus the commas). WinXP doesn't
-run well at an IPS setting less than 10Mips.
-
-
-Also don't set it to more than 250,000,000. Anything faster and WinXP seems to stall within the CPU loop function. WinXP seems to work well with an IPS setting of 75,000,000 on a 3.0Ghz host.
-
-
-The 64-bit version of WinXP needs Bochs compiled with ACPI support even though you only set to one CPU.
-
-
-For some reason, writing to a USB disk in WinXP, where the write takes a little while, WinXP will think it is an error since it didn't complete fast enough, displaying the error. I don't know why.
-
-
-
-
- Windows 7
-Contributed by Benjamin David Lunt
-Please read the message regarding software licenses in
- before you install Windows 7 as a guest operating system in Bochs.
-Windows 7 has been reported to install from the CD-ROM, and run inside Bochs.
-Here are a few settings that seem to work well when running on a Windows10 host, running at 3.0Ghz.
-
-romimage: file=D:/path/to/your/bios/BIOS-bochs-latest
-cpu: model=broadwell_ult
-cpu: count=1, ips=100000000, reset_on_triple_fault=1, ignore_bad_msrs=1
-cpu: cpuid_limit_winnt=0
-clock: sync=realtime, time0=local
-memory: guest=1024, host=1024
-vgaromimage: file=D:/path/to/your/bios/VGABIOS-lgpl-latest-cirrus
-vga: extension=cirrus, update_freq=5
-pci: enabled=1, chipset=i440fx, slot1=cirrus
-
-
-
-Don't set it to more than 250,000,000. Anything faster and Win7 seems to be sluggish, but seems to work well with an IPS setting of 100,000,000 on a 3.0Ghz host.
-
-
-
-
- Windows 8
-Contributed by Benjamin David Lunt
-Please read the message regarding software licenses in
- before you install Windows 8 as a guest operating system in Bochs.
-Windows 8 has been reported to install from the CD-ROM, and run inside Bochs.
-Here are a few settings that seem to work well when running on a Windows10 host, running at 3.0Ghz.
-
-romimage: file=D:/path/to/your/bios/BIOS-bochs-latest
-cpu: model=broadwell_ult
-cpu: count=1, ips=150000000, reset_on_triple_fault=1, ignore_bad_msrs=1
-cpu: cpuid_limit_winnt=0
-clock: sync=realtime, time0=local
-memory: guest=2048, host=2048
-vgaromimage: file=D:/path/to/your/bios/VGABIOS-lgpl-latest-cirrus
-vga: extension=cirrus, update_freq=5
-pci: enabled=1, chipset=i440fx, slot1=cirrus
-
-
-
-Don't set it to more than 250,000,000. Anything faster and Win8 seems to be sluggish, but seems to work well with an IPS setting of 150,000,000 on a 3.0Ghz host.
-
-
-
-
- Windows 10
-Contributed by Benjamin David Lunt
-Please read the message regarding software licenses in
- before you install Windows 10 as a guest operating system in Bochs.
-Windows 10 has been reported to install from the CD-ROM, and run inside Bochs, though a few hacks where used to do so. For more information, see this thread.
-
-
-I used another emulator to successfully install Windows 10. Then using Bochs, after a considerable amount of time and a few reboots, I finally got Win10 to boot and load in Bochs.
-
-
-Here are the settings I used when running on a Windows10 host, running at 3.0Ghz.
-
-romimage: file=D:/path/to/your/bios/BIOS-bochs-latest
-cpu: model=corei7_sandy_bridge_2600k
-cpu: count=1, ips=325000000, reset_on_triple_fault=1, ignore_bad_msrs=1
-cpu: cpuid_limit_winnt=0
-clock: sync=realtime, time0=local
-memory: guest=2048, host=2048
-vgaromimage: file=D:/path/to/your/bios/VGABIOS-lgpl-latest-cirrus
-vga: extension=cirrus, update_freq=5
-pci: enabled=1, chipset=i440fx, slot1=cirrus
-
-
-
-If you use an IPS value less than 325,000,000, Win10 will BSOD and want you to reboot (Assuming a host at 3.0Ghz).
-
-
-
-
-SCO OpenServer 5.0.5
-
-Contributed by Carl Sopchak
-
-
-
-Please read the message regarding software licenses in
- before you install SCO OpenServer 5.0.5 as a guest operating system in Bochs.
-
-
-
-Back in April and May of 2002, I did some work on Bochs
-in order to get it to install and boot SCO's OpenServer 5.0.5 (OSR5).
-Since that time, I have had several e-mails asking about this error message
-or that. The newsgroup posts done at the time had all of the information that I knew,
-so I pointed people there. (I had not used Bochs since...)
-In February of 2003, I got another such e-mail.
-Since the sender indicated they were willing to pay me to get this going for them,
-I agreed to spend a few hours on it (for free, which is not common :-}). Subsequently,
-I decided to document this once and for all. (I did not charge anyone anything, this time...)
-
-
-
-Note: These steps were originally used with Bochs 1.4.1 (or thereabouts,
-since I was using CVS heavily at the time). It is possible (likely) that later versions of Bochs
-are more tolerant/bug free, and this install may be abbreviated. However, I have not tried
-to streamline it at all.
-
-
-
-These steps were performed and confirmed using Bochs version 2.0.2, and SCO OpenServer version 5.0.5.
-The host OS was Red Hat Linux 8.0.
-
-
-
-First, I downloaded the tarball, and extracted the source tree. I decided to use the tarball
-instead of the RPM so that I knew what options were compiled in, etc.
-
-linux-$ tar -xzvf bochs-2.0.2.tar.gz
-
-
-
-
-Next, I configured and compiled Bochs...
-
-linux-$ cd bochs-2.0.2
-linux-$ ./configure --enable-cdrom --enable-ne2000
-linux-$ make
-
-
-
-
-I then created my disk image:
-
-linux-$ ./bximage
-========================================================================
- bximage
- Disk Image Creation Tool for Bochs
-========================================================================
-
-Do you want to create a floppy disk image or a hard disk image?
-Please type hd or fd. [hd] hd
-
-What kind of image should I create?
-Please type flat, sparse or growing. [flat]
-
-Enter the hard disk size in megabytes, between 1 and 8257535
-[10] 2048
-
-I will create a hard disk image with
- cyl=4161
- heads=16
- sectors per track=63
- total sectors=4194288
- total size=2047.99 megabytes
-
-What should I name the image?
-[c.img] hd0.img
-
-Writing: [] Done.
-
-I wrote 2147475456 bytes to hd0.img.
-
-The following line should appear in your .bochsrc:
- ata0-master: type=disk, path="hd0.img", cylinders=4161, heads=16, spt=63
-
-
-
-
-I then created my .bochsrc file. I did this via the interactive portion of Bochs, with the
-end result as follows:
-
-floppya: 1_44="/dev/fd0", status=inserted
-floppyb: 1_44="b.img", status=inserted
-ata0: enabled=1, ioaddr1=0x1f0, ioaddr2=0x3f0, irq=14
-ata0-master: type=disk, path="hd0.img", cylinders=4161, heads=16, spt=63, translation=auto, biosdetect=auto, model="Generic 1234"
-ata0-slave: type=cdrom, path="/dev/cdrom", status=inserted, biosdetect=auto, model="Generic 1234"
-ata1: enabled=0
-ata2: enabled=0
-ata3: enabled=0
-romimage: file=bios/BIOS-bochs-latest
-vgaromimage: file=bios/VGABIOS-lgpl-latest
-megs: 64
-parport1: enabled=1, file="lp.pipe"
-com1: enabled=0
-# no sb16
-boot: cdrom
-floppy_bootsig_check: disabled=0
-vga: update_freq=5
-keyboard_serial_delay: 250
-keyboard_paste_delay: 100000
-cpu: ips=3000000
-clock: sync=realtime, time0=0
-mouse: enabled=0
-private_colormap: enabled=0
-pci: enabled=0
-# no ne2k
-# no loader
-log: osr5.log
-logprefix: %t-%e-%i%d
-debugger_log: -
-panic: action=ask
-error: action=report
-info: action=report
-debug: action=ignore
-keyboard: type=mf, keymap=, user_shortcut=none
-config_interface: textconfig
-display_library: x
-
-Some important things to note are that you want to boot from the CD-ROM, and you do NOT want the ne2000
-card configured initially. (We'll add that later...)
-
-
-
-At this point, Bochs is ready to roll! Insert the OSR5 install CD into the drive, and start Bochs.
-You should soon see the SCO "boot:" prompt:
-
-SCO OpenServer(TM) Release 5
-
-boot
-: defbootstr disable=fdi,dptr
-
-
-Note the disable= parameter that you need. These two SCO drivers cause the install to fail, so they
-need to be disabled for the install boot. You will not need this once OSR5 is installed.
-
-
-
-During the install of OSR5, there are two default configuration answers that need to be changed.
-For the hard disk setup, you should turn bad tracking off, since it's unnecessary on an emulated disk.
-(It won't hurt to do it, it will just take a VERY long time!)
-For the network setup, change the network card to Deferred. You can change other settings, if you so
-desire. However, I would do the initial install with as little configured as you can get away with, then
-add whatever else is needed (one step at a time) after the initial install completes.
-
-
-
-Let the install copy the files. Go get lunch. Take a nap. Go have dinner...
-This can take a LONG time. On my Pentium 4 1.7GHz system, this
-step took just over eight hours! (BTW, it was MUCH longer in version 1.4.1. Great job, guys!)
-
-
-
-After the install finishes, you will need to change the following lines in .bochsrc file:
-
-ne2k: ioaddr=0x300, irq=10, mac=b0:c4:20:00:00:00, ethmod=linux, ethdev=eth0
-boot: disk
-
-Obviously, if you're not using Linux, the ethmode and ethdev values on the ne2k line will be different.
-Also, since Bochs uses "raw" network card access, you'll have to "setuid root" on the Bochs executable:
-
-linux-$ chown root bochs
-linux-$ chmod u+s bochs
-
-(If there is a way to give a "normal user" CAP_NET_RAW capability, that would be an alternative.
-I don't know how to do that...)
-Restart Bochs. Now, you can just press Enter at the OSR5 boot: prompt, because the offending
-drivers have been linked out of the kernel.
-
-
-
-Before you configure the network card, I'd strongly suggest getting the latest "nat" driver from SCO.
-Version 5.0.5b of this driver, according to the SCO web site, "correct[s] possible system lockup
-under high load due to internal buffer overflow." The driver can be found
-here.
-To get the Disk Image file into SCO, I downloaded the VOL.000.000 file to my linux box,
-and used tar to get it on to a floppy:
-
-linux-$ tar -cvf /dev/fd0 VOL.000.000
-
-I then used tar within OSR5 to move it from the floppy to the /tmp directory:
-
-osr5-# cd /tmp
-osr5-# tar -xvf /dev/fd0135ds18
-
-You can then use 'custom' to install the driver from the image file.
-You will then want to use 'scoadmin network' to configure the network card. Choose
-the Novell NE2000 card, and set the parameters to match the ne2k: line in the .bochsrc file.
-DO NOT have OSR5 look for the card, as Bochs may likely crash. (It did in version 1.4.1.)
-
-
-
-You can also configure a printer, if you want. Using the spoolpipe utility that I wrote
-(which can be found in Bochs' misc directory), you can print from OSR5 through the parallel
-port, and you'll hardly notice
-that the printing is going through an extra layer of operating system!
-(You could also set up a printer using network printing, if the printer is not on the host machine...)
-
-
-
-Obviously, don't forget to apply the release supplements and other patches that are considered
-"must haves" for OSR5: rs505a, oss600a, oss497b (others?).
-
-
-
-That's about as far as I have got. I played around with OSR5 within Bochs a bit, but I
-can by no means say that I did any kind of real testing, let alone exhaustive testing.
-
-
-
-And of course, YMMV! :-)
-
-
-
-
-
-
-
-
+
+
+
+
+%bochsdefs;
+
+]>
+
+
+
+ Bochs User Manual
+
+ KevinLawton
+ BryceDenney
+ N. DavidGuarneri
+ VolkerRuppert
+ ChristopheBothamy
+ MichaelCalabrese
+ StanislavShwartsman
+
+
+
+
+Introduction to Bochs
+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
+
+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.
+
+, 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
+
+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.
+
+, 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.
+&NEEDHELP;
+
+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.
+
+ Finally, in March 2000, MandrakeSoft (2005 to 2015 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 . 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.
+
+
+
+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 &devlist;,
+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.
+
+
+
+
+
+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 this situation, Bochs can 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.
+
+
+
+
+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 &bochswebsite;.
+
+
+
+
+
+Bochs License
+
+Bochs is copyrighted by "The Bochs Project" team and distributed under the
+GNU Lesser General Public License
+
+Complete text of the GNU LGPL is included with the source code in a file
+called COPYING, and is also here.
+
+. The following text appears at the
+top of every source code file released under the LGPL in the Bochs distribution:
+
+Parts of Bochs have specific licenses which are compatible with the
+GNU Lesser General Public License. Hence each source file contains its
+own licensing information.
+
+
+ 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.
+
+ This library is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Lesser General Public License for more details.
+
+ You should have received a copy of the GNU Lesser General Public
+ License along with this library; if not, write to the Free Software
+ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
+
+
+
+
+
+
+Third Party Software Licensing and Temporary Files
+
+
+Before you install or use any Operating System, BIOS, or other software package
+within the Bochs PC emulation environment, make sure you are and will be in
+compliance with all the software licenses pertaining to the software you wish
+to install. It is completely your responsibility to provide licenses and records
+on all software that you install and/or use. It is also completely your responsibility
+to maintain total compliance with all software licenses involved.
+
+
+
+In the process of installing Software within the Bochs PC emulation environment,
+it may be helpful or necessary to copy or convert files from the original distribution
+format to a second format to facilitate the installation. You should delete
+the intermediate files after installation, making certain that only the
+original distribution files remain.
+
+
+
+
+
+Features
+
+The following table shows the features of Bochs and which platforms they
+currently work with.
+
+
Bochs Features
+
+
+
+ Feature
+ Supported?
+ Description
+
+
+
+
+ configure script
+ Yes
+ Bochs uses GNU autoconf to configure Makefiles and headers.
+ Autoconf helps Bochs to compile on a wide variety of platforms.
+
+
+
+ 386,486,Pentium Emulation
+ Yes
+ Bochs can be configured to emulate one of several families of Intel hardware. Some Pentium features are incomplete, such as SMM (System Management Mode).
+
+
+ P6 and later CPU Emulation
+ Yes
+ Bochs can be configured to emulate any P6 family processor including optional MMX and SSEx instructions.
+
+
+
+ x86-64 Extensions Emulation
+ Yes
+ Bochs can be configured to emulate x86-64 with many recent Intel and AMD extensions.
+
+
+ Command Line Debugger
+ Yes
+ Powerful command line debugger (optional) that lets you stop
+ execution and examine registers and memory, set breakpoints, etc.
+
+
+
+ GUI Debugger
+ Yes
+ Chourdakis Michael and Bruce Ewing contributed very powerful GUI
+ frontend for Bochs internal debugger. GUI debugger frontend is supported for
+ Win32 and GTK2/GTK3 hosts.
+
+
+
+ Floating Point
+ Yes
+ Uses software floating point engine based on SoftFloat floating point emulation library.
+
+
+
+ Enhanced BIOS
+ Yes
+ Implements ElTorito, EDD v3.0, basic APM feature, PCIBIOS features
+ and the PCI interrupt routing table. The latest version of the Bochs BIOS
+ has a 32-bit init for ACPI, SMM and SMP. Bochs also known to work with recent
+ SeaBIOS images.
+
+
+
+ VGA
+ Yes
+ VGA color graphics emulation in a window.
+
+
+
+ VBE (VESA) Support
+ Yes
+ Currently resolutions up to 2560x1600x32bpp are supported.
+ You must enable VBE with the VGA extension option and use the LGPL'd VGABIOS.
+ For more information see .
+
+
+
+ Cirrus Logic video card
+ Yes
+ Cirrus Logic CL-GD5430 ISA or CL-GD5446 PCI video card support.
+ For more information see .
+
+
+ 3D video card
+ Yes
+ Some of the 3dfx Voodoo graphics adapter models are supported now.
+ The code is still experimental, but at least the Voodoo1 and the Voodoo
+ Banshee PCI are known to work. For more information see
+ .
+
+
+ Plug&play monitor
+ Yes
+ VESA DDC is now supported by all VGA compatible display adapters.
+ The LGPL'd VGABIOS has been updated use this feature for the Bochs VBE,
+ Voodoo Banshee and Cirrus versions. The interface reports a plug&play
+ monitor called "Bochs Screen".
+
+
+
+ Floppy disk
+ Yes
+ Supports floppy disk images on all platforms: 2.88M 3.5", 1.44M 3.5", 1.2M 5.25",
+ 720K 3.5" and 360K 5.25". On Unix and Windows NT/2000/XP, Bochs can access the
+ physical floppy drive. It is also possible to use a local directory as VFAT media
+ (1.44M only).
+
+
+
+ Multiple ATA channels
+ Yes
+ Emulates up to 4 ATA channels. Up to 8 ATA/ATAPI emulated devices can be attached,
+ two per ATA channel.
+ So you can have eight hard disks or seven hard disks and a CD-ROM or four hard
+ disks and four CD-ROMs, or one hard disk and seven CD-ROMs, etc...
+
+
+
+ Hard disk
+ Yes
+ Emulates ATA-6/IDE hard drives via image files. Physical
+ hard disk access is supported on some architecture, but NOT recommended, primarily for safety reasons.
+ With LBA48 support, hard disks up to 255TB are supported, on any platform that support large files access.
+ It is also possible to use a local directory as VFAT drive.
+
+
+
+ CD-ROM
+ Yes
+ Emulates ATAPI-4/IDE CD-ROM. The CD-ROMs can read from an ISO disk image
+ on any platform. On Windows (NT/2000/XP/Vista), Linux, SunOS, FreeBSD,
+ NetBSD, OpenBSD, Amiga/MorphOS and MacOSX, Bochs can read from the
+ physical CD-ROM drive. The Bochs BIOS supports booting from the first CD-ROM drive.
+
+
+
+ Keyboard
+ Yes
+ Emulates a PS/2 keyboard with North American key mappings. Optional
+ keyboard layout remapping files are provided to support localized keyboard
+ in X11 (12 layouts, e.g. French, German, Italian, Russian, Spanish, U.K.)
+ and SDL/SDL2 (German).
+
+
+
+ Mouse
+ Yes
+ Emulates a serial, PS/2, bus or USB mouse with 3 buttons + optional mouse
+ wheel support. There is also a USB tablet emulation available.
+
+
+
+ Sound card
+ Yes
+ Emulates a Sound Blaster 16 card (ISA, no plug&play) or an
+ ES1370 PCI card. The SB16 emulation provides wave input / output, the OPL3
+ chip, the external MIDI port and volume control for wave and FM. The ES1370
+ provides wave input / output, the MIDI UART port and volume control for
+ wave output. On Windows, Linux, FreeBSD, MacOS 9, MacOSX and all platforms
+ supported by SDL, the output can be sent to the host computer's sound
+ system. For the SB16, see the developer documentation
+ for details.
+
+
+
+ Network card
+ Yes
+ Emulates an NE2000 compatible network card (ISA / PCI) or an Intel(R)
+ 82540EM Gigabit Ethernet adapter (PCI). On Windows NT/2000, Linux, FreeBSD,
+ and NetBSD, Bochs will forward packets to and from the
+ operating system so that the guest OS can talk on the physical network.
+ Unfortunately, on some platforms the guest OS can talk to any machine on
+ the network BUT NOT the host machine. On Windows and on systems that
+ allow the TAP or TUN/TAP interface, there is no such limitation. Often
+ the host machine may be configured so the guest OS has access to the
+ internet. On MacOSX, you may download the TUN driver from:
+
+
+
+
+ Parallel Port
+ Yes
+ Parallel port emulation was added by Volker Ruppert for Bochs 1.3.
+ Data that is sent to the parallel port by the guest OS can be saved into a
+ file or sent directly into the parallel port device (Unix only).
+
+
+
+ Serial Port
+ Yes
+ The serial port (16550A UART emulation) is usable, on GNU/Linux,
+ NetBSD, OpenBSD, FreeBSD and MacOSX as host and guest. On other OSes the
+ emulation is present, but the connection to hard- or software of the host is
+ not implemented yet. Up to 4 ports are available.
+
+
+
+ Gameport
+ Yes
+ Emulates a standard PC gameport. The connection to a real joystick is
+ currently supported on Linux and win32 only.
+
+
+
+ PCI
+ Yes
+ Emulates most of the i430FX, i440FX or i440BX PCI chipset.
+ The Host-to-PCI bridge, the PCI-to-ISA bridge and the PCI IDE controller
+ (PIIX3/PIIX4) are available. For PCI cards there are 5 PCI slots supported.
+ ACPI and HPET features are also available. The i440BX chipset has basic
+ support for AGP.
+
+
+
+ USB
+ Yes
+ Four types of host controllers (UHCI, OHCI, EHCI and xHCI) and the
+ devices 'mouse', 'tablet', 'keypad', 'keyboard', 'disk', 'cdrom', 'floppy',
+ 'hub' and 'printer' are available. Plugging in and removing devices at runtime
+ is possible. Access to real hardware is not implemented yet.
+
+
+
+ Plugins
+ Yes
+ Compiling devices, GUI and drivers for network, sound and disk image
+ formats as plugins are supported on Linux, MacOS X, Solaris, Cygwin, MinGW/MSYS,
+ MSVC nmake and the VS2019 IDE (workspace provided).
+
+
+
+ PIC
+ Yes
+ Master and slave programmable interrupt controller.
+
+
+
+ CMOS functions
+ Yes
+ Real time clock (RTC) and CMOS RAM are available
+
+
+ Dynamic Translation/Virtualization
+ No
+ Because Bochs is designed to be portable, it does not attempt
+ to do any dynamic code translation or virtualization. See
+ for details.
+
+
+
+ Simulate a Multiprocessor
+ Yes
+ Bochs can be configured to simulate up to 254 processor threads. This
+ feature is still experimental, but it can boot several Linux or Windows guests
+ with SMP support. Please note that this does NOT mean that Bochs can run
+ faster on a physical SMP machine.
+
+
+
+ Take advantage of your SMP box
+ Minimal
+ At present, Bochs only uses threads in some GUIs, in the lowlevel
+ sound output code and in the Voodoo graphics adapter code. The simulation
+ core itself uses only one thread, so it will not run any faster on
+ multiprocessor hardware.
+
+
+
+ Copy and Paste
+ Yes
+ Depending on the host platform, the text-mode screen text can be
+ exported to the clipboard. Text in the clipboard can also be pasted, through
+ Bochs, to the guest OS, as simulated keystrokes.
+
+
+
+
+
+
+
+Supported Platforms
+
+The following table shows the supported platforms with a small description and
+the available display libraries on these platforms. The display library is the
+code that displays the Bochs VGA screen and handles keyboard and mouse events.
+
+
Supported platforms
+
+
+
+ Platform
+ Description
+ Display Libraries
+
+
+
+
+
+ Unix/X11
+
+ X windows has always been well supported because it was
+ Kevin Lawton's main development platform. Bryce Denney maintains
+ the Unix/X11 platform now. Most features and fixes (not all) are
+ tried first in Unix and then ported to the others; see
+ for compile instructions.
+
+ x, sdl, sdl2, wx, term, rfb, vncsrv
+
+
+
+ Win32
+
+ This port was done by David Ross and is now maintained by
+ Don Becker. You can compile with Microsoft Visual C++,
+ see for compile instructions,
+ or Cygwin, see .
+
+ win32, sdl, sdl2, wx, rfb
+
+
+
+ MacOS X
+
+ Emmanuel Mailliard ported the Macintosh code to MacOS X with Carbon API.
+ Jeremy Parsons (Br'fin) has been maintaining the MacOS X port since
+ March 2002; see for compile instructions.
+
+ carbon, x, rfb, sdl, sdl2
+
+
+
+ PowerPC-Macintosh
+
+ David Batterham
+ ported Bochs to the Mac. He compiled with CodeWarrior Pro R1 (CW12)
+ but has not had time to maintain the Mac port since early 2000.
+ If you have Mac development tools and want to contribute, contact
+ the &devlist;; see for
+ compile instructions.
+
+ macos
+
+
+
+ Amiga/MorphOS
+
+ This port is written and maintained by Nicholai Benalal, see
+ for compile instructions.
+
+ amigaos
+
+
+
+
+
+
+
+FAQ
+
+
+
+ Is Bochs Open Source?
+
+
+
+ Yes! Bochs is released under the GNU LGPL.
+
+
+
+
+
+
+ How do you pronounce "Bochs"?
+
+
+
+ Phonetically the same as the English word "box". It's just a play on the word "box", since techies like to call their machines a "Linux box", "Windows box", ... Bochs emulates a box inside a box.
+
+
+
+
+
+
+ Who is the author of Bochs?
+
+
+
+ Kevin Lawton is the primary author of Bochs. There have been bug fixes,
+ enhancements, and code contributions from some few hundred people, so
+ it is not possible to list them all. Later, Kevin had been working on a
+ PC virtualization project called plex86. In Fall 2002, he
+ made contributed some major CPU speedups and helped with integration
+ and debugging of the x86-64 emulation code.
+
+
+
+
+
+
+ Who maintains Bochs now?
+
+
+ With Kevin's help, in April 2001, the members of the &devlist;
+ set up a new official Bochs site hosted by Source Forge.
+ The admins on this project are Greg Alexander, Don Becker, Christophe Bothamy,
+ Bryce Denney, Volker Ruppert and Stanislav Shwartsman.
+
+
+
+
+
+ Tell me about performance when running Bochs.
+
+
+ Because Bochs emulates every x86 instruction and all the devices in a PC
+ system, it does not reach high emulation speeds. Users who have an x86
+ processor and want the highest emulation speeds may want to consider PC
+ virtualization software such as Vmware or VirtualBox (free software).
+ Another related project is QEMU.
+
+
+
+
+
+ Does Bochs use a disk partition to install the OS?
+
+
+ No. It uses a disk image file, which is simply a large file, like any other file, on your platform's disk.
+
+
+
+
+
+ Why can't I use Bochs with my current WinXP installation?
+
+
+ Think about this. If you had two different PC's, they would require different
+ hardware drivers. So you may not be able to safely move a disk drive with WinXP
+ on it, from one to the other. Bochs is no different. It emulates a certain set
+ of hardware devices, and requires each OS be configured for those devices.
+
+
+
+
+
+ Is there a developer's email list for Bochs?
+
+
+ Yes. For instructions on joining, refer to
+ .
+
+
+
+
+
+ Is there an IRC channel for Bochs?
+
+
+ Yes. You will usually find Bochs developers and users on IRC at irc.freenode.net:6667, channel #bochs.
+
+
+
+
+
+ Do you know of any snapshots of Bochs running Windows?
+
+
+ Yes! Look for "Screen Shots" on &bochs-sf-net; or on other Bochs sites.
+
+
+
+
+
+ Does Bochs support a CD-ROM?
+
+
+ Yes, the CD-ROM emulation and accessing ISO files is always available.
+ Reading from host CD-ROM media is supported in Linux, Windows, and most
+ BSDs. The CD-ROM drivers for Bochs allow the guest operating system to
+ access the host operating system's CD-ROM data directly.
+
+
+
+
+
+ Does Bochs support a sound device?
+
+
+ Yes, Bochs emulates a Sound Blaster 16 card (ISA, no plug&play) or
+ an ES1370 PCI. Output to the host sound system is implemented for some
+ platforms. See for details.
+
+
+
+
+
+ Does Bochs support a network card?
+
+
+ Yes. Bochs emulates an NE2000 compatible network card (ISA / PCI) or an
+ Intel(R) 82540EM Gigabit Ethernet adapter (PCI). Using the host's network
+ capabilities is not supported on all platforms. See
+ for details.
+
+
+
+
+
+ What applications are known to run inside of Bochs?
+
+
+ Well, lots of different OS's run inside of Bochs, so
+ thousands. I'm assuming you are asking about Windows programs.
+ To give you a few, the following ones from the Winstone'98 tests
+ worked: Access 97, CorelDRAW! 7, Excel 97, Lotus 1-2-3 97, Word 97,
+ PowerPoint 97, Quattro Pro 7, WordPerfect 7.
+
+ Also, I've compiled an entire OS kernel inside Bochs before.
+ Not to mention, running DOOM, though at then-pathetic speeds.
+
+
+
+
+
+ I am new to Bochs, how do I start?
+
+
+ You should read first. Next, you can check
+ if they are specific instructions on how to install your (guest) OS inside of Bochs.
+
+
+
+
+
+ Does Bochs run on my mobile device?
+
+
+ Bochs has now minimal support for the Android platform using a special
+ version of the SDL library. There are some external projects that use
+ the offical sources with some modifications. They also offer a GUI
+ for easy Bochs configuration. Other mobile platforms are not officially
+ supported yet.
+
+
+
+
+
+
+
+
+
+
+
+Release Notes
+
+
+The change log is stored in the Bochs source code in a file called
+CHANGES. Click here
+to see the latest version of the CHANGES file.
+
+
+The link above is provided by Source Forge and might change one day. If it
+stops working, you can download the current source code with SVN and read
+the CHANGES file there.
+
+
+
+
+
+
+
+
+Installation
+
+Downloading Bochs
+
+
+You can download Bochs from our web site at &bochs-sf-net;. First, you
+need to choose what version to get: a recent release or a development
+version. If you trying to get things working for the first time, a release
+version is recommended since it has been tested the most. The development
+versions (sometimes called SVN snapshots) may have some newer bug fixes and
+new features, but have not been tested as much as the releases.
+
+
+
+Second, you can choose to compile Bochs from source code or install a binary
+(if one is available for your platform). Binary packages will be quicker to
+install, and most include a small demo of a guest operating system called DLX
+Linux to get you started. However, some features can only be enabled if you
+compile Bochs yourself, for example the Bochs debugger. For multiuser systems,
+you will probably need system administrator privileges (root) to install a
+binary package. If you decide to get a binary, download it to your hard disk,
+uncompress it, then go to the section called Installing a Binary for more information.
+
+
+
+If you are going to compile Bochs yourself, you need the gzipped tarball
+containing the source code, called
+bochs-version.tar.gz. For
+Windows and Mac, the prebuilt Makefiles are separate, so also get
+the Makefiles for your platform. To unpack a compressed TAR file
+
+A TAR file is a single file that contains many files packed inside. Bochs
+TAR files are compressed with a program called gzip, and another program
+called gunzip is used to uncompress them.
+
+ on a Unix machine
+
+On Windows, look for software called WinZip to unpack the TAR.
+
+
+, type
+
+ gunzip -c bochs-version.tar.gz | tar -xvf -
+
+This creates a directory called
+bochs-version full of
+files. This directory will be referred to as &bochsdir;. Go into
+&bochsdir; and you are ready to compile. Instructions for compiling
+Bochs are in the section, Compiling Bochs.
+
+
+
+Alternatively, you can also obtain the sources for any Bochs version using SVN.
+See the SVN instructions for details.
+
+
+
+Tracking the source code with SVN
+
+SVN (Subversion) is a tool used by many software developers to manage changes
+within their source code tree. SVN provides the means to store not only the
+current version of a piece of source code, but a record of all changes (and who
+made those changes) that have occurred to that source code. Use of SVN is
+particularly common on projects with multiple developers, since SVN ensures
+changes made by one developer are not accidentally removed when another
+developer posts their changes to the source tree. The Bochs source code and
+documentation is available using SVN
+
+You can download SVN software and documentation from
+subversion.apache.org.
+
+.
+
+
+Checking out Bochs
+
+When you have SVN installed, the first step is to do a checkout. The initial
+checkout command is long and ugly, but usually you only have to do it
+once. The example below shows the SVN checkout process of the Bochs trunk in Unix.
+On the Windows platform, you can download a SVN client from
+subversion.apache.org,
+or use SVN within Cygwin
+
+Cygwin is an open source Unix-like environment for Windows platforms,
+available at www.cygwin.com.
+
+.
+
+Checking out Bochs in SVN
+
+ user$ svn co http://svn.code.sf.net/p/bochs/code/trunk/bochs bochs
+ A bochs/ltdl.c
+ A bochs/Makefile.in
+ A bochs/bochs.h
+ .
+ . (This might take a few minutes, depending on your network connection.)
+ .
+ A bochs/install.sh
+ U bochs
+ Checkout, Revision 10754.
+ user$ cd bochs
+ user$ ls
+ aclocal.m4 cpu logio.cc pc_system.cc
+ bios cpudb.h ltdl.c pc_system.h
+ bochs.h crc.cc ltdlconf.h.in plugin.cc
+ build disasm ltdl.h plugin.h
+ bx_debug doc ltmain.sh README
+ bxversion.h.in docs-html main.cc README-plugins
+ bxversion.rc.in extplugin.h Makefile.in README.rfb
+ CHANGES fpu memory README-wxWindows
+ config.cc gdbstub.cc misc TESTFORM.txt
+ config.guess gui msrs.def TODO
+ config.h.in host osdep.cc win32_enh_dbg.rc
+ config.sub install-sh osdep.h win32res.rc
+ configure instrument param_names.h wxbochs.rc
+ configure.in iodev PARAM_TREE.txt
+ COPYING load32bitOShack.cc patches
+ user$ _
+
+
+
+
+
+ This is just an example output of a checkout of specific version of the Bochs
+ trunk and folder. Depending on the checkout command and revision, you most
+ likely will see more/other files.
+
+
+
+
+If you have write access to the Bochs SVN tree, see the Developers Guide
+
+
+See the Developers Guide
+and/or look at
+SourceForge's Subversion documentation,
+for instructions.
+
+ for details.
+
+
+
+
+The SVN checkout process (above) gives you a directory called bochs
+that contains the very latest source code. I will refer to this directory
+as &bochsdir;. In this directory there's also a subdirectory called ".svn"
+which tells the SVN software where the code was checked out, what version
+you have, and where to go for future updates.
+
+
+
+Getting the Latest Version
+
+Most developers use SVN to always give them the latest source code. The minute
+that any developer checks in a change, they are available to everyone else
+through SVN. You just have to type svn update in the
+&bochsdir; directory, and SVN will retrieve any files and directories that have
+been changed since you did a checkout. If you update regularly, each update
+takes a short time because it downloads only the files that changed.
+See also Getting a release version.
+
+
+
+The svn update command tells you if any new files have
+been downloaded from the server, and it also tells you if you have modified any
+of the SVN-controlled files. As it checks through the source directories, it
+will list files that have changed, with a single letter before the name that
+tells the status of that file. The most common status letters are listed
+below.
+
+
+Status letters in a SVN update
+
+
+
+ Letter
+ Meaning
+ Description
+
+
+
+
+ ?
+ unknown
+
+ This file is in your Bochs directory, but SVN does not know anything
+ about it. For example, when you compile Bochs, any files created
+ during the build process appear as ?.
+
+
+
+ U
+ update
+
+ SVN downloaded a new version of this file because it changed on the
+ server, usually because someone else did a checkin.
+
+
+
+ A
+ added
+
+ SVN downloaded a newly added file from the server.
+
+
+
+ D
+ deleted
+
+ This file has been deleted on the server and SVN removed it from your
+ local copy.
+
+
+
+ C
+ conflict
+
+ You have changed this file on your disk, but this change conflicts with
+ a change that was checked in. Conflicts occur when two people change
+ the same line of code in different ways. You need to edit the
+ conflicting file(s) and clean it up by hand. Or, sometimes it's
+ easiest to discard your own edits and download a fresh copy, by
+ deleting the conflicting file and running svn update again.
+
+
+
+
+
+
+
+
+
+Getting a Release Version
+
+You can also use the SVN checkout command to get the Bochs source code for
+any release since March 2000. The command is
+
+ user$ svn co http://svn.code.sf.net/p/bochs/code/tags/tagname/bochs bochs
+
+The tagname tells which release you want, and it can be one of the following:
+
+
+
+
+
+
+
+More about SVN
+
+Entire books have been written on SVN, so there's no sense in duplicating
+it all here in the Bochs documentation. Some sources of additional
+information is listed below.
+
+
+The subversion.apache.org
+site has tons of SVN FAQs and documentation.
+
+A German SVN FAQ
+is available at University of Muenster.
+
+
+
+
+
+
+
+
+
+Installing a Binary
+
+
+This section is divided up by platform, since installing a binary package
+is different on different platforms.
+
+
+Windows
+
+The Bochs binaries for Windows are distributed in an EXE installer package.
+The Bochs installer can be started like any other Windows program and it brings
+up the installation wizard. Here you can select the destination folder and the
+installation options. The wizard installs the files and creates the registry
+keys, start menu and desktop links.
+
+
+Previous releases of Bochs were distributed as ZIP packages, too. These packages
+contained the same set of files as the installer package from the same version.
+
+
+If you are new to Bochs you should try out the DLX Linux demo distributed with
+Bochs. The installation wizard has created a link on the desktop if you decided
+to install the demo. If you doubleclick the icon two windows will appear:
+one is the Bochs Display window, and the other is text window that is used for
+the runtime configuration and for log messages if no logfile is specified.
+
+
+You can find more information on the DLX Linux demo in the next section below the
+DLX Linux screenshot.
+
+
+
Files in Bochs directory (Windows version)
+
+ FileDescription
+
+
+
+bios.bin-1.13.0 SeaBIOS ROM image
+BIOS-bochs-latest default ROM BIOS image for Bochs
+BIOS-bochs-legacy ROM BIOS image without 32-bit init code
+bochsdbg.exe the main Bochs executable with debugger enabled
+bochs.exe the main Bochs executable
+bochs.ico the Bochs icon (used for links in start menu and on the desktop)
+bochsrc-sample.txt sample Bochs configuration file
+bxhub.exe utility required for the 'socket' networking module
+bximage.exe tool for manipulating disk images
+CHANGES.txt what has changed between versions
+COPYING.txt copy of the LGPL license
+lgban.ico a set of Bochs icons in different sizes
+LICENSE.txt Bochs license information
+logo.ico another set of Bochs icons
+niclist.exe tool to find out the network interface name
+penguin.ico icons for the DLX Linux link
+README.txt the read-me file from the source distribution.
+sb16ctrl.exe tool to control sb16 in Bochs
+sb16ctrl.txt examples of sb16ctrl commands
+SeaBIOS-README.txt README for SeaBIOS ROM image
+SeaVGABIOS-README.txt README for SeaVGABIOS ROM image
+slirp.conf sample config file for the advanced 'slirp' network configuration
+vnet.conf sample config file for the advanced 'vnet' network configuration
+TODO.txt the TODO file from the source distribution.
+unbochs.ico icon for the uninstaller link
+uninstall.exe uninstall program for Bochs (created by the installation wizard)
+vgabios-cirrus.bin-1.13.0 SeaVGABIOS ROM image (for Cirrus adapter)
+VGABIOS-elpin-2.40 VGA BIOS image for Bochs
+VGABIOS-elpin-LICENSE.txt license for VGA BIOS
+VGABIOS-lgpl-latest LGPL'd VGA BIOS image for Bochs
+VGABIOS-lgpl-latest-debug LGPL'd VGA BIOS image for Bochs with debug output to the logfile
+VGABIOS-lgpl-latest-cirrus LGPL'd VGA BIOS image for Bochs with the Cirrus extension enabled
+VGABIOS-lgpl-latest-cirrus-debug LGPL'd VGA BIOS image for Bochs with the Cirrus extension enabled and debug output to the logfile
+VGABIOS-lgpl-latest-banshee LGPL'd VGA BIOS image for Bochs with the Voodoo Banshee extension enabled
+VGABIOS-lgpl-README.txt readme for the LGPL'd VGA BIOS
+dlxlinux\ directory containing DLX linux sample disk image and configuration files
+dlxlinux\bochsrc.bxrc Bochs configuration file for DLX
+dlxlinux/hd10meg.img disk image file (10 meg)
+dlxlinux\readme.txt description of DLX linux
+dlxlinux\run.bat Run this BAT file to try out DLX Linux inside Bochs!
+dlxlinux\testform.txt Form for reporting success or failure
+
+ doc\index.html
+ a local copy of all Bochs documentation (online copy)
+
+keymaps\*.map keymap tables (on Windows used for the paste feature only)
+
+
+
+
+
+
+
+Linux RPM
+
+RPM stands for "RedHat Package Manager." An RPM is a compressed file
+containing files to be installed on your system. Many Linux distributions,
+not just RedHat ones, can install files from an RPM. First, download the
+Bochs RPM for your architecture to your computer. For example, if you have an
+Intel-compatible computer, be sure to get the RPM that says "for Linux x86
+distributions" or "i386". Once you have the package on your local disk, you
+should become the root user and install it as follows
+
+Many distributions have their own RPM installer program, often graphical, and
+they should work ok. It is helpful to be able to see the text output from
+RPM, so if you use a fancy RPM installer, be sure to find the text output and
+check that it looks correct.
+
+:
+
+Installing an RPM in Linux
+
+ user$ su
+ Password:
+ root# ls -l bochs-2.5.x86_64.rpm
+ -rw-r--r-- 1 user users 2628643 Nov 27 17:20 bochs-2.5.x86_64.rpm
+ root# rpm -i bochs-2.5.x86_64.rpm
+ root# exit
+ user$ _
+
+
+
+
+
+All RPM installations are done as the root user because they require
+permission to update system files and directories. If you do not have root
+access you need to compile Bochs in your home directory.
+
+
+
+RPM installation can fail for a few reasons. It will fail if you already
+have a Bochs package installed. In this case, try upgrading the old package
+to the new package with rpm --upgrade NAME.i386.rpm.
+Another potential problem is missing RPM dependencies. If you are getting
+errors about missing files or RPMs, then first you should try to
+install the RPMs that provide the missing pieces. If that cannot be done,
+download the source RPM and build a new binary RPM that is appropriate
+for your platform. The command is rpmbuild --rebuild
+NAME.src.rpm. As a last resort, you can run rpm with the
+--nodeps option to ignore dependencies and install it
+anyway, but if it is missing important pieces, it may not run properly.
+
+
+
+The Bochs RPM installs five new commands and associated manual pages: bochs,
+bochs-dlx and bximage. First, let's try out the
+DLX Linux demo by typing bochs-dlx.
+
+
+ user$ bochs-dlx
+ ---------------------------------------------------------------
+ DLX Linux Demo, for Bochs x86 Emulator
+ ---------------------------------------------------------------
+ Checking for bochs binary...ok
+ Checking for DLX linux directory...ok
+ Checking for /bin/gzip...ok
+ Checking for /usr/users/bryce/.bochsdlx directory...
+ ---------------------------------------------------------------
+ To run the DLX Linux demo, I need to create a directory called
+ /usr/users/bryce/.bochsdlx, and copy some configuration files
+ and a 10 megabyte disk image into the directory.
+ ---------------------------------------------------------------
+ Is that okay? [y/n]
+ y
+ Copying /usr/share/bochs/dlxlinux/bochsrc.txt -> /usr/users/bryce/.bochsdlx/.
+ Copying /usr/share/bochs/dlxlinux/README -> /usr/users/bryce/.bochsdlx/.
+ Copying /usr/share/bochs/dlxlinux/testform.txt -> /usr/users/bryce/.bochsdlx/.
+ Uncompressing /usr/share/bochs/dlxlinux/hd10meg.img.gz -> /usr/users/bryce/.bochsdlx/hd10meg.img
+ Entering /usr/users/bryce/.bochsdlx
+ Running bochs
+ ========================================================================
+ Bochs x86 Emulator 2.4.6.svn
+ Build from SVN snapshot, after release 2.4.6
+ Compiled on Oct 20 2011 at 19:40:05
+ ========================================================================
+
+
+Then you get a new X11 window containing the VGA display of the simulated
+machine. First you see the VGA BIOS screen, then Linux uncompresses and
+boots, and you get a login prompt. Type "root" and ENTER to log in to
+DLX linux.
+
+Screenshot of Bochs running DLX Linux
+
+
+
+
+
+Booting is complete when you see "dlx login:" and a cursor. At this login
+prompt, type "root". On UNIX systems, root is the system admin user.
+There is no password for root on this sample disk image, so it lets you log
+in without typing any password. Now you should see a UNIX prompt, and you
+can begin to type UNIX commands.
+
+
+
+ Welcome to DLX V1.0 (C) 1995-96 Erich Boehm
+ (C) 1995 Hannes Boehm
+
+ dlx login: root
+ Linux 1.3.89.
+ dlx:~# pwd
+ /root
+ dlx:~# cd /
+ dlx:~# ls
+ bin/ etc/ lost+found/ root/ usr/
+ boot/ fd/ mnt/ sbin/ var/
+ dev/ lib/ proc/ tmp/ zip/
+ dlx:/# df
+ Filesystem 1024-blocks Used Available Capacity Mounted on
+ /dev/hda1 10060 2736 6005 29% /
+ dlx:/# _
+
+
+
+When you get tired of playing with DLX Linux, just type "reboot" in the Bochs
+window to shut down the DLX Linux operating system, and when it starts
+to reboot again press the "Power" button at the top of the Bochs display
+to end the application.
+
+
+
+
+Here is a list of the files that are installed by the RPM, and a brief
+description of each one.
+
+
+
Files in RPM package
+
+ FileDescription
+
+
+
+/usr/bin/bochs the main Bochs executable
+/usr/bin/bochs-dlx run this script to try out DLX Linux inside Bochs!
+/usr/bin/bxhub utility required for the 'socket' networking module
+/usr/bin/bximage tool for manipulating disk images
+/usr/lib/bochs/plugins/* plugins (devices, guis, etc.) for Bochs (plugin version only)
+/usr/share/doc/bochs/bochsrc-sample.txt sample Bochs configuration file
+/usr/share/man/man1/* man pages for bochs, bochs-dlx and bximage
+/usr/share/man/man5/* man page for bochsrc
+/usr/share/doc/bochs/CHANGES what has changed between versions
+/usr/share/doc/bochs/COPYING copy of the LGPL license
+/usr/share/doc/bochs/LICENSE Bochs license information
+/usr/share/doc/bochs/README the read-me file from the source distribution.
+/usr/share/doc/bochs/TODO the TODO file from the source distribution.
+/usr/share/doc/bochs/index.html a local copy of all Bochs documentation ( Online copy )
+/usr/share/doc/bochs/slirp.conf sample config file for the advanced 'slirp' network configuration
+/usr/share/doc/bochs/vnet.conf sample config file for the advanced 'vnet' network configuration
+/usr/share/bochs/BIOS-bochs-latest default ROM BIOS image for Bochs
+/usr/share/bochs/BIOS-bochs-legacy ROM BIOS image without 32-bit init code
+/usr/share/bochs/SeaBIOS-README README for SeaBIOS ROM image
+/usr/share/bochs/SeaVGABIOS-README README for SeaVGABIOS ROM image
+/usr/share/bochs/VGABIOS-elpin-2.40 VGA BIOS image for Bochs
+/usr/share/bochs/VGABIOS-elpin-LICENSE license for VGA BIOS
+/usr/share/bochs/VGABIOS-lgpl-latest LGPL'd VGA BIOS image for Bochs
+/usr/share/bochs/VGABIOS-lgpl-latest-debug LGPL'd VGA BIOS image for Bochs with debug output to the logfile
+/usr/share/bochs/VGABIOS-lgpl-latest-cirrus LGPL'd VGA BIOS image for Bochs with the Cirrus extension enabled
+/usr/share/bochs/VGABIOS-lgpl-latest-cirrus-debug LGPL'd VGA BIOS image for Bochs with the Cirrus extension enabled and debug output to the logfile
+/usr/share/bochs/VGABIOS-lgpl-latest-banshee LGPL'd VGA BIOS image for Bochs with the Voodoo Banshee extension enabled
+/usr/share/bochs/VGABIOS-lgpl-README readme for the LGPL'd VGA BIOS
+/usr/share/bochs/bios.bin-1.13.0 SeaBIOS ROM image
+/usr/share/bochs/dlxlinux/ directory containing DLX linux sample disk image and configuration files
+/usr/share/bochs/dlxlinux/readme.txt description of DLX linux
+/usr/share/bochs/keymaps/*.map keymap tables for X11, SDL and SDL2
+/usr/share/bochs/vgabios-cirrus.bin-1.13.0 SeaVGABIOS ROM image (for Cirrus adapter)
+
+
+
+
+
+
+
+
+MacOS X DMG
+
+This was contributed by Aard Vark in January 2003
+
+
+The MacOS X binary distribution is a mountable disk
+image (.dmg file). Once you've downloaded the binary
+distribution file, just double click
+on it to automatically unpack the archive and mount
+the volume on the desktop. An icon will appear
+exactly as if you'd inserted a CD-ROM
+or removable storage device, and a finder window
+containing the volume should automatically open.
+It is likely to have an odd name
+such as _dmg_top, but don't worry about that.
+
+
+Copy the Bochs-2.0 (or whatever version) folder from
+the disk image onto your hard disk. Either Home or
+Applications would be sensible places to put it.
+Because the disk image is mounted read only, you
+can't run the included dlxlinux guest OS until
+you've copied it to the hard disk.
+
+
+Once you've installed the binaries, it's probably a
+good idea to drag the _dmg_top volume to trash to
+unmount it, so you don't get confused and try to
+run Bochs from there. Then open
+the Bochs folder from wherever you installed it.
+
+
+The MacOS X version of Bochs requires a terminal
+window to run. If you just double click on the Bochs
+icon, you'll get an error message telling you to
+double click on "bochs.scpt" to start
+Bochs in a new terminal window. You'll need to
+configure Bochs before you will get very far with
+the bochs.scpt in the top folder,
+so to try out Bochs open the dlxlinux folder and
+double click on the bochs.scpt icon inside.
+
+
+This will open a new terminal window which will
+contain the Bochs startup messages, and a
+configuration menu. The default option is
+[5], which starts the simulation, so press enter to
+do so. You will then get a new window containing
+the VGA display of the simulated
+machine. The new window will probably appear behind
+the current terminal window, so either click on the
+Bochs icon in the dock or the simulation window to
+bring it to the front. If you're quick
+enough you'll then see the VGA BIOS screen, then
+Linux uncompresses and boots, and you get a login
+prompt. Type "root" and ENTER to log in to DLX Linux.
+
+
+Once you've finished playing with DLX Linux, just
+type "reboot" in the Bochs window to shut down the
+DLX Linux operating system, and
+when it starts to reboot again press the "Power"
+button in the "MacBochs Hardware Controls" window
+(it's the circle containing a vertical bar at the
+far right - have a look at the Linux screenshots,
+since the Mac version doesn't seem to have
+descriptions or tool-tips).
+
+
+
+
+
+
+Compiling Bochs
+
+Standard Compile
+
+Bochs is written in C++, so you need a C++ compiler on your system. Most
+platforms have been tested with GNU gcc/g++, but other compilers are known
+to work too. By now, you should have unpacked your source TAR file or checked
+out Bochs from SVN. If not, you can return to Downloading Bochs for details. The top level
+directory of the source code will be referred to as &bochsdir;. (&bochsdir;
+contains the files bochs.h and
+main.cc and subdirectories cpu and
+bios.)
+
+
+
+The standard compile process has three basic steps:
+configure, make, and make
+install. Each step is described in a separate section below. The
+standard compile process is used on all Unix machines, MacOS X, and
+Cygwin (win32). There are separate instructions for compiling for Win32 with Microsoft VC++.
+
+
+Configure
+
+
+There is a script called configure which tests your
+machine, C/C++ compiler and libraries to discover what settings should work on
+your system. If you run configure with no arguments after
+it, defaults will be used for all settings. To change the settings, you can
+run configure with options that override the
+defaults. You can get a list of valid configure options by typing
+configure --help. One useful configure option is
+--prefix=directory, which sets the directory in
+which Bochs will be installed. All the possible configure options are
+documented in a later section.
+
+
+
+
+
+Among other things, the configure script tries to detect your platform
+and which compile options to use. If you want to control this, set these
+environment variables before running configure: CC,
+CXX, CFLAGS,
+CXXFLAGS. Here is an example that sets the environment
+variables, using bash/ksh
+
+The syntax for bash and ksh is given. In csh and variants, use the syntax
+setenv VARIABLE
+value to change environment variables.
+Do not use an equal sign for csh!
+
+
+syntax:
+
+ export CC=egcs
+ export CXX="$CC"
+ export CFLAGS="-Wall -O2 -m486 -fomit-frame-pointer -pipe"
+ export CXXFLAGS="$CFLAGS"
+
+
+
+
+Once the configure script knows what options are selected,
+it creates a Makefile in every source code directory, and creates
+$BOCHS/config.h with all the option values written
+as preprocessor #defines. Now the sources are ready to compile.
+
+
+Configure Shortcut Scripts
+
+In the Bochs source directory, you will see a series of scripts called
+.conf.platform.
+These scripts run the configure script for you, with a set of
+options that are appropriate for that platform. It is not necessary to
+use the shortcut scripts; they are simply there to show you an example that
+the developers have used. Some of these scripts have been used to build official
+binary packages.
+
+
+
+If a shortcut script is "almost right" for you, just edit it and then run it!
+If you run a shortcut script, you don't need to run configure manually.
+
+
+
+Run a shortcut script using Bourne shell, like this:
+
+ sh .conf.win32-vcpp
+
+
+These .conf.platform scripts
+have been tested in recent Bochs versions:
+
Shortcut scripts
+
+
+
+ Name
+ Build environment
+
+
+
+
+ .conf.linux
+ Linux (32/64 bit)
+
+
+ .conf.macosx
+ MacOS X
+
+
+ .conf.win32-cygwin
+ Windows with Cygwin or MinGW/MSYS
+
+
+ .conf.win32-vcpp
+ Windows with MSVC (32 bit)
+
+
+ .conf.win64-vcpp
+ Windows with MSVC (64 bit)
+
+
+ .conf.win64-cross-mingw32
+ Cross compiling on Linux for Windows
+
+
+
+
+
+
+
+
+
+
+
+Make
+
+The make command compiles Bochs. Make is a program
+used by many software projects that reads the &Makefile; in each source
+directory and follows the instructions that it finds there. A &Makefile; tells
+which files depend on which other files, what commands to use to compile and
+link the code, and more. After you have finished the configure step, just type
+make to build the source code.
+
+
+
+The reason that Make is so popular is that it is smart about when to compile
+and when not to compile. If you run make once, it compiles every file. But
+when you run it again, it checks to see if any source files have been modified;
+if not, there's nothing to do! For example, the &Makefile; says that
+main.o depends on main.cc. Knowing
+this, it will only compile main.cc if it is newer than
+main.o.
+
+
+
+Of course, make can only do the right thing if the &Makefile; lists all the
+dependencies correctly, so human error can sometimes lead make astray.
+If make refuses to build something that you think it should, or you
+are getting strange compile errors, try doing make all-clean
+and then make again. All-clean means to clean up
+the compiled files in every subdirectory, while make clean
+means to clean up just the current directory
+
+
+This is different from the terminology of some other projects, and it may cause
+confusion. Sometimes "clean" implies that all subdirectories are affected.
+
+. However, it's important to note that make
+all-clean leaves the configuration intact. You do not have
+to run configure again.
+
+
+
+If you're really in the mood for cleaning, make dist-clean
+erases all the configuration information too. In theory, after a dist-clean
+your directory should look much like when you first untarred it or checked it
+out. There's usually some extra stuff lying around, but the &Makefile; tries
+at least to erase any files that it created.
+
+
+
+
+Make Install
+
+Once the program has been built, the next step is typically to run
+make install to copy the executables, documentation, and
+other required files into a public place so that all users can use it.
+By default, the files are copied to some directories in /usr/local. The following
+tables show the directories and their contents.
+
+
+
+
+Installing the DLX Linux demo
+
+To download and install the DLX Linux demo distributed with Bochs binary release
+packages, use these two make commands:
+
+ make unpack_dlx
+ make install_dlx
+
+The package will be downloaded from the Bochs website and installed at same
+location as the files of the Bochs base system.
+
+
+
+
+
+Configure Options
+
+This section describes the configure options for Bochs. Perhaps the most
+important option is , since it gives you a list of all
+the other options. The configure script will detect your platform and choose
+the default GUI for your platform. If the default choice is not what you
+want, use the options to override the default. The
+options in the first table tell which GUI library is the default for each
+platform. Starting in version 2.0, you can use multiple
+ options at once to compile with multiple
+display libraries, and then choose between them at runtime with the
+display_library option
+in the configuration file. Or, you can
+let the configure script detect which libraries are on your system
+and use them all, by configuring with .
+
+
+
+The concept of platform detection and default GUIs was added in Bochs 1.4.
+In Bochs 1.3 and before, the X11 GUI was always the default.
+
+
+
+
+
Defaults by Platform
+
+
+
+ Platform
+ Default GUI
+ Extra compile flags
+
+
+
+
+ win32, Cygwin or MinGW/MSYS
+ --with-win32
+ If using nmake method, compile using cl /nologo /MT /W3 /EHs-c- /DNDEBUG /DWIN32 /D_WINDOWS /D_CRT_SECURE_NO_WARNINGS.
+ If using Visual C++ workspace, see the workspace file for compile settings.
+ See Compiling on Win32 with Microsoft VC++ for instructions.
+
+
+
+ MacOS X or Darwin
+ --with-carbon
+ -fpascal-strings -fno-common -arch ppc -Wno-four-char-constants -Wno-unknown-pragmas -Dmacintosh
+
+
+
+ MacOS 9 or before
+ --with-macos
+ none
+
+
+
+ AmigaOS
+ --with-amigaos
+ none
+
+
+
+ any other platform
+ --with-x11
+ none
+
+
+
+
+
+
+
Configure Options to Select the Display Library (optional)
+
+
+
+ Option
+ Comments
+
+
+
+
+ --with-x11
+ Use X windows user interface. On many operating systems,
+ Bochs will use X windows by default.
+
+
+
+ --with-win32
+ Use the native Win32 GUI. This is the default on win32 platforms.
+
+
+
+ --with-carbon
+ Compile for MacOS X with the Carbon GUI. See the
+ .conf.macosx file for the correct MacOS X compile options.
+ WARNING: This Bochs feature is not maintained yet and may fail.
+
+
+
+ --with-amigaos
+ Compile for Amiga MorphOS. This code is written by Nicholai
+ Benalal.
+
+
+
+ --with-rfb
+
+ Enable support for the RFB protocol to talk to AT&T's
+ VNC Viewer.
+ Refer to for details.
+
+
+
+ --with-vncsrv
+
+ Enable support for an extended RFB(VNC) GUI using the LibVNCServer library.
+ Refer to for details.
+
+
+
+ --with-sdl
+ Enable support for the SDL 1.2.x GUI interface; see .
+
+
+ --with-sdl2
+ Enable support for the SDL 2.x GUI interface; see .
+
+
+ --with-term
+ Use text-only GUI with curses library. Almost certainly
+ won't work right with the debugger or the textconfig interface.
+
+
+
+ --with-macos
+ Use Macintosh/CodeWarrior environment. This is for running
+ configure on a platform which supports running configure, so that
+ you may then transfer the configured code over to the
+ real compile environment.
+ WARNING: This Bochs feature is not maintained yet and may fail.
+
+
+
+ --with-wx
+
+ Enable support for wxWidgets configuration and display interface;
+ see .
+
+
+
+ --with-nogui
+ No native GUI; just use blank stubs. This is if you don't
+ care about having video output, but are just running tests.
+
+
+
+ --with-all-libs
+
+ Automatically detect which libraries are installed on your system
+ and enable them. This option is still experimental; it might
+ enable libraries that are not usable and cause the compile to fail.
+ If you have trouble, just list the options
+ for the specific display libraries that you want.
+
+
+
+
+
+
+
+The remaining options can generally be used with any GUI. For each option
+such as , you can also write
+to explicitly turn it off. The following 3 tables show the general options
+(.e.g debugger and plugins support), the CPU-related stuff (e.g. cpu level,
+SMP, x86_64 support) and the devices options (e.g. PCI, USB, Cirrus graphics).
+
+
+
Configure Options (General)
+
+
+
+ Option
+ Default
+ Comments
+
+
+
+
+ --enable-plugins
+ no
+
+ Plugins are shared libraries that can be loaded on demand. Example: the
+ serial device is implemented as a plugin. In Unix, the serial plugin is
+ called libbx_serial.so. When Bochs reads its configuration file, if the
+ serial device is enabled it loads libbx_serial.so. See the Features
+ section for supported platforms.
+
+
+
+ --enable-debugger
+ no
+
+ Compile in support for Bochs internal command-line debugger. This has
+ nothing to do with x86 hardware debug support. It is a more powerful
+ and non-intrusive native debugger. Enabling this will of course slow
+ down the emulation. You only need this option if you know you need it.
+ After you have run ./configure, you may want to edit
+ config.h to customize the debugger further;
+ see for more information.
+
+
+
+ --enable-debugger-gui
+ yes if debugger is on
+
+ Enable support for the GUI frontend of the Bochs debugger. This feature
+ is supported on Windows hosts and on hosts with GTK2/GTK3 installed.
+
+
+
+ --enable-readline
+ detected by configure
+
+ Compile the debugger with the GNU readline library, which gives
+ command line editing and history.
+
+
+
+ --enable-gdb-stub
+ no
+
+ Enable support for the remote GDB stub. See Using Bochs and the remote GDB stub.
+ NOTE: This feature cannot be used if the Bochs debugger is also enabled.
+ WARNING: This Bochs feature is not maintained yet and may fail.
+
+
+
+ --enable-docbook
+ detected
+
+ Build the docbook documentation in doc/docbook. The configure
+ script will enable this option automatically if you have a program
+ called docbook2html installed.
+
+
+
+ --enable-instrumentation=
+ no
+
+ Compile in support for instrumentation. This allows you to collect
+ instrumentation data from Bochs as it executes code. You have to create
+ your own instrumentation library and define the instrumentation macros
+ (hooks in Bochs) to either call your library functions or not, depending
+ upon whether you want to collect each piece of data.
+
+
+
+ --enable-xpm
+ yes
+
+ Enables the check for the XPM library. This option is only valid if the
+ x display library is enabled ().
+
+
+
+ --enable-show-ips
+ yes
+
+ Enables logging of measured IPS, see the ips parameter
+ of the cpu option.
+
+
+
+ --enable-logging
+ yes
+
+ By default, Bochs generates logfile output that can be configured with
+ bochsrc options and at runtime. Use
+ to turn off this feature completely.
+
+
+
+ --enable-assert-checks
+ yes if debugger is on
+
+ BX_ASSERT event causes a panic on assertion failure if enabled (logging
+ feature must be enabled, too).
+
+
+
+ --enable-cpp
+ no
+
+ Use .cpp as C++ suffix. Renames all the .cc files to .cpp for use with
+ compilers which want that, like older MS C++ compilers. Don't use this
+ option unless you know you need it.
+
+
+
+ --enable-idle-hack
+ no
+
+ Enables Roland Mainz's experimental idle code, which is intended to
+ keep Bochs from always using 100% of CPU time. When Bochs is waiting
+ around for an interrupt, the idle code uses a select() loop and some
+ X11 tricks to wait until user input arrives. This is designed to
+ keep Bochs responsive while still yielding to other processes when
+ Bochs is idle. It only works with X11 or term GUI.
+
+
+
+
+
+
+
Configure Options (CPU & Memory)
+
+
+
+ Option
+ Default
+ Comments
+
+
+
+
+ --enable-cpu-level={}
+ 6
+
+ Select which CPU level to emulate. Choices are 3,4,5,6 which mean to
+ target 386, 486, Pentium, or Pentium Pro and later emulation.
+
+
+
+ --enable-smp
+ no
+
+ Compile in support for SMP simulation. This allows you to boot Linux and
+ maybe other OSes in SMP mode, and Bochs will simulate all the different
+ CPUs and communication between them. Do not expect this option to speed
+ up your simulation! On the contrary, it has to spend extra time simulating
+ the different CPUs (even if they're mostly idle) and the communication
+ between them. Use it to try out an SMP OS if you don't have an SMP machine,
+ or to debug SMP OS drivers. Refer to for more details
+ on SMP in Bochs.
+
+
+
+ --enable-fpu
+ yes
+ If you want to compile Bochs to make use of the FPU emulator
+ written by Stanislav Shwartsman, use this option.
+
+
+
+ --enable-3dnow
+ no
+ 3DNow! instruction set support (incomplete)
+
+
+ --enable-x86-64
+ no
+
+ Add support for x86-64 instruction set, written by Peter Tattam and Stanislav Shwartsman.
+
+
+
+ --enable-vmx
+ no
+ Intel Virtualization Extensions (VMX) support
+
+
+ --enable-svm
+ no
+ AMD SVM (Secure Virtual Machine) extensions emulation support
+
+
+ --enable-avx
+ no
+ AVX instructions support
+
+
+ --enable-x86-debugger
+ no
+ X86 debugger support. If the software you run in Bochs
+ needs to use the x86 hardware debugging facilities such as
+ DR0..DR7, instruction and data breakpoints etc., then you
+ should use this option. Otherwise don't use it, as it
+ will slow down the emulation.
+
+
+
+ --enable-monitor-mwait
+ no
+ MONITOR/MWAIT instructions support (still experimental)
+
+
+ --enable-alignment-check
+ yes if cpu level >= 4
+ support for alignment check in the CPU and #AC exception
+
+
+ --enable-configurable-msrs
+ no
+ support for user configurations of emulated MSR registers
+ (see example in msrs.def)
+
+
+ --enable-long-phy-address
+ no
+ support for guest physical address larger than 32 bit
+
+
+ --enable-a20-pin
+ yes
+ support for the A20 pin
+
+
+ --enable-large-ramfile
+ yes
+ support for guest memory larger than the host supports
+
+
+ --enable-repeat-speedups
+ no
+ enable support repeated I/O and memory copy speedups
+
+
+ --enable-fast-function-calls
+ no
+ enable support for fast function calls (gcc on x86 only)
+
+
+ --enable-handlers-chaining
+ no
+ enable support for handlers chaining optimization
+
+
+ --enable-all-optimizations
+ no
+
+ Turn on the enables for all speed optimizations that the
+ developers believe are safe to use:
+ --enable-repeat-speedups,
+ --enable-fast-function-calls,
+ --enable-handlers-chaining.
+
+
+
+
+
+
+
Configure Options (Devices)
+
+
+
+ Option
+ Default
+ Comments
+
+
+
+
+ --enable-cdrom
+ yes
+
+ Enable use of a real CD-ROM/DVD drive. The CD-ROM emulation and the portable
+ ISO image file support are always present. You can use this option to
+ compile in support for accessing the media in your workstation's CD-ROM
+ drive. The supported platforms are Linux, Solaris, FreeBSD, OpenBSD,
+ MacOS X and Windows. For other platforms, a small amount of code specific
+ to your platform must be written.
+
+
+
+ --enable-sb16
+ no
+
+ Enable Sound Blaster emulation. The available lowlevel sound interfaces
+ are autodetected. See section Using Sound
+ for supported platforms and more info. This option also enables the standard
+ PC gameport which is a part of the SB16. If you don't want to use it, you
+ might use .
+
+
+
+ --enable-es1370
+ no
+
+ Enable ES1370 sound emulation. Just like the SB16 option, the available
+ lowlevel sound interfaces are autodetected and the gameport is turned on.
+
+
+
+ --enable-gameport
+ no
+
+ Enables the standard PC gameport. This option is only necessary if you want
+ to have a gameport, but no SB16 or ES1370 (see above). The connection to a
+ real joystick is currently supported on Linux and win32 only.
+
+
+
+ --enable-ne2000
+ no
+ Enable NE2000 network card support. This requires a
+ low-level component to be written for each OS (supported on FreeBSD,
+ OpenBSD, Linux, and Windows 9x/NT/2K/XP). When enabled and configured,
+ the NE2000 device model can talk to any computer on the network
+ EXCEPT FOR the local host. Exception: Under most circumstances, Bochs can
+ talk to the local host on Windows, and in the ethertap interface for Linux.
+
+
+
+ --enable-pnic
+ no
+ Enable PCI pseudo NIC (network card) support.
+
+
+ --enable-e1000
+ no
+ Enable Intel(R) 82540EM Gigabit Ethernet adapter support.
+
+
+ --enable-clgd54xx
+ no
+ Enable Cirrus Logic GD54xx (CL-GD5430 ISA or CL-GD5446 PCI) video
+ card support. For more information see .
+
+
+
+ --enable-voodoo
+ no
+ Enable experimental 3dfx Voodoo Graphics emulation. The Voodoo1 is
+ known to work, the Voodoo2 support is not yet complete, but almost usable.
+ The Banshee / Voodoo3 support is under construction, but basically usable.
+ For more information see .
+
+
+
+ --enable-iodebug
+ yes if debugger is on
+
+ Dave Poirier has written an experimental interface to the debugger
+ using I/O ports, so that software running in the guest OS can access
+ features of the debugger. You only want this option if you are
+ developing guest OS code for use in Bochs. In other words, most people
+ don't. Also, it should only be used with .
+ See the
+ developer documentation for details.
+
+
+
+ --enable-pci
+ yes
+ Enable limited i440FX / i430FX / i440BX PCI support. This is still
+ incomplete, but usable.
+
+
+
+ --enable-pcidev
+ no
+
+ Enable PCI host device mapping support. This requires
+ to be set as well as Linux 2.4, 2.6 or 3.x as host.
+ WARNING: This Bochs feature is not maintained yet and may fail.
+
+
+
+ --enable-usb
+ no
+
+ Enable i440FX / i440BX PCI USB support (UHCI). The host controller with
+ 2-port root hub and 9 USB device types are available.
+
+
+
+ --enable-usb-ohci
+ no
+
+ Enable USB OHCI support. The host controller with 2-port
+ root hub is available (USB device types: same as UHCI).
+
+
+
+ --enable-usb-ehci
+ no
+
+ Enable USB EHCI support. The host controller with 6-port
+ root hub is available (USB device types: same as UHCI).
+
+
+
+ --enable-usb-xhci
+ no
+
+ Enable USB xHCI support. The host controller with 4-port
+ root hub is available (USB device types: same as UHCI).
+
+
+
+ --enable-raw-serial
+ no
+
+ Enable support for the serial port emulation to access to the host's
+ serial port. This feature is partly implemented for Windows hosts only.
+
+
+
+
+
+
+
+
+
+
+
+Transcript of Successful Compilation
+
+This example shows the output of a compilation and installation on Linux.
+
+ user$ ls -l bochs-2.5.tar.gz
+ -rw-r--r-- 1 user users 4117999 27. Nov 17:14 bochs-2.5.tar.gz
+ user$ gunzip -c bochs-2.5.tar.gz | tar -xvf -
+ bochs-2.5/
+ bochs-2.5/.conf.sparc
+ bochs-2.5/build/
+ bochs-2.5/build/macosx/
+ bochs-2.5/build/macosx/pbdevelopment.plist
+ bochs-2.5/build/macosx/make-dmg.sh
+ .
+ .
+ .
+ bochs-2.5/memory/memory.cc
+ bochs-2.5/memory/misc_mem.cc
+ bochs-2.5/memory/Makefile.in
+ user$ cd bochs-2.5
+ user$ ./configure --enable-cpu-level=6
+ checking build system type... x86_64-unknown-linux-gnu
+ checking host system type... x86_64-unknown-linux-gnu
+ checking target system type... x86_64-unknown-linux-gnu
+ checking if you are configuring for another platform... no
+ checking for standard CFLAGS on this platform...
+ checking for gcc... gcc
+ .
+ .
+ .
+ config.status: creating build/win32/nsis/bochs.nsi
+ config.status: creating host/linux/pcidev/Makefile
+ config.status: creating config.h
+ config.status: creating ltdlconf.h
+ user$ make
+ cd iodev && \
+ make libiodev.a
+ make[1]: Entering directory `/home/volker/Archiv/test/bochs-2.5/iodev'
+ g++ -c -I.. -I./.. -I../instrument/stubs -I./../instrument/stubs -g -O2 -D_FILE_OFFSET_BITS=64 -D_LARGE_FILES devices.cc -o devices.o
+ g++ -c -I.. -I./.. -I../instrument/stubs -I./../instrument/stubs -g -O2 -D_FILE_OFFSET_BITS=64 -D_LARGE_FILES virt_timer.cc -o virt_timer.o
+ g++ -c -I.. -I./.. -I../instrument/stubs -I./../instrument/stubs -g -O2 -D_FILE_OFFSET_BITS=64 -D_LARGE_FILES slowdown_timer.cc -o slowdown_timer.o
+ g++ -c -I.. -I./.. -I../instrument/stubs -I./../instrument/stubs -g -O2 -D_FILE_OFFSET_BITS=64 -D_LARGE_FILES pic.cc -o pic.o
+ .
+ .
+ .
+ echo done
+ done
+ /bin/sh ./libtool --mode=link g++ -o bochs -g -O2 -D_FILE_OFFSET_BITS=64 -D_LARGE_FILES -DBX_SHARE_PATH='"/usr/local/share/bochs"' -export-dynamic logio.o main.o config.o load32bitOShack.o pc_system.o osdep.o plugin.o crc.o \
+ iodev/libiodev.a cpu/libcpu.a cpu/cpudb/libcpudb.a \
+ memory/libmemory.a gui/libgui.a \
+ disasm/libdisasm.a \
+ fpu/libfpu.a \
+ -lSM -lICE -lX11 -lXpm -lXrandr \
+ \
+ \
+ \
+ \
+ -lm
+ mkdir .libs
+ g++ -o bochs -g -O2 -D_FILE_OFFSET_BITS=64 -D_LARGE_FILES -DBX_SHARE_PATH=\"/usr/local/share/bochs\" logio.o main.o config.o load32bitOShack.o pc_system.o osdep.o plugin.o crc.o -Wl,--export-dynamic iodev/libiodev.a cpu/libcpu.a cpu/cpudb/libcpudb.a memory/libmemory.a gui/libgui.a disasm/libdisasm.a fpu/libfpu.a -lSM -lICE -lX11 -lXpm -lXrandr -lm
+ gcc -c -I. -I./. -Iinstrument/stubs -I./instrument/stubs -g -O2 -D_FILE_OFFSET_BITS=64 -D_LARGE_FILES ./misc/bximage.c -o misc/bximage.o
+ /bin/sh ./libtool --mode=link g++ -o bximage -g -O2 -D_FILE_OFFSET_BITS=64 -D_LARGE_FILES misc/bximage.o
+ g++ -o bximage -g -O2 -D_FILE_OFFSET_BITS=64 -D_LARGE_FILES misc/bximage.o
+ gcc -c -I. -I./. -Iinstrument/stubs -I./instrument/stubs -g -O2 -D_FILE_OFFSET_BITS=64 -D_LARGE_FILES ./misc/bxcommit.c -o misc/bxcommit.o
+ /bin/sh ./libtool --mode=link g++ -o bxcommit -g -O2 -D_FILE_OFFSET_BITS=64 -D_LARGE_FILES misc/bxcommit.o
+ g++ -o bxcommit -g -O2 -D_FILE_OFFSET_BITS=64 -D_LARGE_FILES misc/bxcommit.o
+ user$ su
+ root# make install
+ cd iodev && \
+ make libiodev.a
+ make[1]: Entering directory `/home/volker/Archiv/test/bochs-2.5/iodev'
+ .
+ .
+ .
+ for i in CHANGES COPYING README TODO; do if test -f $i; then install -m 644 $i /usr/local/share/doc/bochs; else install -m 644 ./$i /usr/local/share/doc/bochs; fi; done
+ rm -f /usr/local/share/doc/bochs/README
+ cat ./build/linux/README.linux-binary ./README > /usr/local/share/doc/bochs/README
+ install -m 644 ./.bochsrc /usr/local/share/doc/bochs/bochsrc-sample.txt
+ root# exit
+ user$ _
+
+
+
+
+
+Compiling on Win32 with Microsoft VC++
+
+The standard compile uses the configure script, but the Windows platform
+cannot run the configure script natively.
+The current solution to this problem is that the Bochs
+configure script must be run on a different platform that does support
+shell scripts, with options that cause it to configure for a Win32
+platform instead of the native one. Many people have access to a UNIX
+machine that could run the configure script, or you can use Cygwin or
+MinGW/MSYS to run the configure script.
+
+
+Because Bochs depends so much on the configure script, if you are doing
+much win32 Bochs development, you should consider downloading Cygwin or
+MinGW/MSYS so that you can run the configure step natively.
+
+.
+
+
+
+Download the Bochs sources on a machine that can run shell scripts.
+Edit the configure shortcut script .conf.win32-vcpp
+if you want to adjust the configure options. Then type these commands
+in the Bochs source directory:
+
+ sh .conf.win32-vcpp
+ make win32_snap
+
+These commands will run the configure step, produce VC++ makefiles and
+workspace files, and pack it all into a .zip file in the directory above the
+source directory
+
+If the source directory is /home/joe/bochs-win32, the
+resulting .zip file is in /home/joe/bochs-win32-msvc-src.zip.
+
+. The .zip file is all ready to transfer to the target Windows
+machine to be unzipped and compiled. Or, if you run the sh/make steps in
+Cygwin, you are already on the target machine so you don't need the .zip
+file.
+
+
+
+When you have the Win32 sources transferred to a Windows machine with VC++,
+find the workspace file called bochs.sln in the folder
+"vs2013" and load it in VC++. Choose Project:Set Active Project
+and be sure that "bochs" is selected. Then choose Build:Build bochs.exe.
+This will build all the required libraries (iodev, cpu, etc.) and the auxiliary
+programs bximage.exe, bxhub.exe and
+niclist.exe.
+
+
+
+Using workspaces is easy and intuitive, but there is one caveat. The workspaces
+come directly out of a ZIP file in build/win32/vs2013ex-workspace.zip,
+and they are not controlled by the configure script. When you compile with certain
+configure options (e.g. ) you need to link with additional
+libraries. For now you must add them to the VC++ workspace by hand. In version 2.0,
+we have improved the situation considerably by adding #if...#endif around every optional
+file and including nearly every Bochs source file in the workspace. This solves the
+problem of having to manually add source files to the workspace when you turn
+on configure options such as . The problem of adding
+link libraries remains unresolved.
+
+
+
+
+To compile with the Bochs debugger enabled, add
+to the configure line in .conf.win32-vcpp before running it.
+No modifications to the workspace are necessary.
+
+
+
+An alternative way to compile is to run nmake.exe in an
+MS-DOS window. Instead of using the workspace files, nmake uses the Bochs
+makefiles that are generated by configure. The nmake method is currently used
+to build the release binaries.
+
+
+
+The make install doesn't work with nmake yet. Currently
+it must be run inside of Cygwin or MinGW/MSYS and requires the environment
+variable INSTDIR to be set.
+
+
+
+
+Compiling on Win32 with Cygwin or MinGW/MSYS
+Cygwin is a free Unix-like environment for Windows written by
+Steve Chamberlain and now maintained by RedHat, Inc. You can download
+it from www.cygwin.com. Because
+Cygwin supports the configure script and uses GNU gcc/g++, you can use the
+standard compile process. The configure script should automatically detect
+Cygwin and add "-mno-cygwin -DWIN32" to the compiler options. You should
+get a working Bochs if you just type:
+
+ configure
+ make
+
+
+Optionally, you can use the configure shortcut script for Cygwin,
+.conf.win32-cygwin, instead of running configure
+directly. If this script is close to what you need, just edit the script and
+then run it. To use the configure shortcut script and compile in Cygwin, the
+commands are
+
+ sh .conf.win32-cygwin
+ make
+
+To find out the options which are known to work in Cygwin, open the file
+.conf.win32-cygwin in any text editor/viewer and have
+a look at the end of that file.
+
+
+When using gcc 4.7 or newer you need to add the switch -mno-ms-bitfields
+to the CFLAGS, to make sure that hdimage and network structures are packed as
+expected.
+
+
+The command make install installs the Bochs files in the directory
+structure of your build environment. To install Bochs into any desired folder you
+need to use the install_win32 target. It requires the environment
+variable INSTDIR to be set.
+
+
+
+Compiling on MacOS 9 with CodeWarrior
+
+ It is possible that this hasn't been tried since 1999. In theory, you
+ run sh .conf.macos on a Unix box to build the
+ makefiles and headers, copy the whole thing over to a Mac, and then
+ use CodeWarrior to compile. Since it hasn't been tested in so long,
+ it is quite likely that some work is needed to bring the Mac port up
+ to date.
+
+
+ If you are interested and have the required MacOS development tools, please
+ let us know by contacting the &devlist;. Someone requests a MacOS port
+ almost once a month, but none of the developers know how to help them.
+
+
+
+Compiling on MacOS X
+
+The port to MacOS X with Carbon API by Emmanuel Mailliard is quite new, and the
+configure and makefile support was added by Bryce Denney. You will need
+the compiler and libraries from the development tools CD. Bochs should
+configure and compile with the Carbon GUI if you simply type:
+
+ configure
+ make
+
+Optionally, you can use the configure shortcut script for MacOS X,
+.conf.macosx, instead of running configure directly.
+If this script is close to what you need, just edit the script and then
+run it. To use the configure shortcut script and compile, the commands
+are
+
+ sh .conf.macosx
+ make
+
+
+MacOS X has a special format for an application bundle, which looks like a
+directory that contains the required resource files and binaries. The Makefile
+currently creates this application bundle "by hand" using mkdir and copy, which
+is surely the wrong way to do it. Bryce doesn't know the official way to
+create an application from a Makefile, so this hack will remain until a real
+Mac developer helps to clean it up.
+
+
+
+On MacOS X the default GUI is the Carbon interface, but you can also try other
+Bochs GUIs. Use for X windows,
+ for VNC/RFB, for SDL
+or for SDL2.
+
+
+
+Compiling on Amiga/MorphOS
+
+ Nicholai Benalal created this port to MorphOS running on Amiga. It should
+ compile with:
+
+ configure
+ make
+
+ If the platform is not detected properly, you might need to use
+ as a configure option. Optionally, you
+ can use the configure shortcut script, .conf.amigaos.
+
+
+
+Compiling with the RFB interface
+
+ The RFB code was written by Don Becker x-odus@iname.com,
+ who has a Bochs-RFB web page on his site,
+ http://www.psyon.org/bochs-rfb/.
+
+
+ This interface allows you to view the Bochs display with
+ AT&T's VNC Viewer.
+ The protocol used between a VNC server and a VNC viewer is called RFB.
+ Because the RFB code in Bochs is written with portable network socket
+ and POSIX thread code, it can be compiled on many platforms and has
+ been tested in Linux and Win32. No additional libraries are required.
+ To try it, type:
+
+ configure --with-rfb
+ make
+
+ RFB currently uses this setup:
+
+ port range 5900 to 5949 (using the first one available)
+ no authentification
+ by default 30 seconds waiting for client
+ 8 bpp (BGR233 / RGB332) supported only
+ if client doesn't support resize: desktop size 720x480 (for text mode and standard VGA)
+ if resize supported: maximum resolution 1280x1024
+
+
+
+With the display library option "timeout" the default value of 30 seconds can
+be changed. With a value of 0 it is possible to start the simulation without a
+client connected.
+
+
+
+Compiling with the VNCSRV interface
+
+ The LibVNCServer is
+ a cross-platform library that allows to implement VNC server functionality easily.
+ On platforms supported by LibVNCServer Bochs can be compiled with support for
+ it this way:
+
+ configure --with-vncsrv
+ make
+
+
+
+Unlike the RFB GUI this new implementation is not limited to 8 bpp and it is
+possible to connect a Bochs session with a web browser.
+
+
+
+Compiling with the SDL interface
+
+ Dave Poirier has written an SDL interface for Bochs. Simple DirectMedia
+ Layer, or SDL, is a cross-platform multimedia library distributed from
+ libsdl.org. SDL is available
+ for many platforms including Win32, Linux, BSD, IRIX, MacOS, MacOS X,
+ and AmigaOS.
+
+
+ To compile Bochs with SDL, you must first install the SDL library
+ from libsdl.org. You
+ can either get the source code and compile it yourself, or install
+ the development libraries for your platform (already compiled).
+ Then, go into the Bochs directory and type:
+
+ configure --with-sdl
+ make
+
+
+
+ If you are on FreeBSD and have SDL installed using the ports collection, Bochs
+ won't be able to find the library automatically, as the SDL config script is
+ called sdl11-config in that case (even for version 1.2).
+ The easiest way to make Bochs find it, is to create a symlink to that script
+ called sdl-config inside a directory which is in the path.
+ For example:
+
+ ln -s /usr/local/bin/sdl11-config ~/bin/sdl-config
+
+
+
+To compile in Microsoft VS2013Ex, you have to configure on a different system
+(see Compiling on Win32 with Microsoft VC++).
+Before running the configure script, you have to add
+to the shortcut script. If you have already configured, you can set BX_WITH_SDL
+ to 1 in config.h.
+
+
+Then you have to set up the project for SDL this way:
+
+- add source file sdl.cc to the module gui
+- add path to the SDL include files to the modules bochs and gui
+- add lbraries SDL.lib and SDLmain.lib to the module bochs
+- change the runtime library for all modules to Multithreaded-DLL (/MD)
+
+Compiling with MSVC nmake is not supported yet.
+
+
+
+Compiling with the SDL version 2 interface
+
+The SDL library version 2 is now also supported by Bochs. For some basic information
+about SDL, see . The configure option to enable SDL2
+support is and the configuration script is called
+sdl2-config. Note that the Bochs GUIs for SDL version 1.2.x
+and 2.x are mutually exclusive. The legacy SDL GUI support will be removed someday.
+When using the GUI library autodetection () the
+configure script probes for SDL version 2 first.
+
+
+
+
+Compiling with the wxWidgets interface
+
+ wxWidgets is a cross-platform C++ user interface library which
+ you can download for free at wxwidgets.org.
+ The wxWidgets port of Bochs provides both a graphical configuration interface for
+ editing bochsrc options (see
+ config_interface option) and a
+ display (see display_library option).
+ It was written by Bryce Denney, Don Becker, Dave Poirier, and Volker Ruppert.
+
+ configure --with-wx
+ make
+
+
+
+ If you want Bochs to use a wxWidgets installation not in your path (but installed
+ somewhere else), you need to set the WX_CONFIG environment variable to the
+ proper wx-config script, before running configure (example for csh):
+
+ setenv WX_CONFIG '/home/compile/wx/bin/wx-config'
+
+
+
+
+Building an RPM on Linux
+
+RPM stands for "RedHat Package Manager." An RPM is a compressed file
+containing files to be installed on your system. Bochs
+has a special shell script called make-rpm that helps
+to build an RPM of Bochs. Start with a clean source directory. Edit
+.conf.linux first if you want to adjust the configure options.
+Then, type:
+
+
+ ./build/redhat/make-rpm | tee /tmp/build.txt
+
+
+When this command completes, you should have a source RPM and a binary RPM of
+Bochs in the current directory. The tee part of the
+command (optional) saves a transcript of the build process into /tmp/build.txt,
+which is very useful if anything goes wrong. Instructions for installing an
+RPM are here.
+
+
+
+In the past, you had to build rpms as root, but as of version 2.0 you can build
+them as a normal user.
+
+
+
+
+
+
+Compile Problems
+
+The configure script failed
+
+The configure script can fail for various reasons. If the error
+message on the shell doesn't give enough information, it is recommended to review
+the output file config.log to find out what exactly
+happened. The following issues can be fixed by modifying the configure options used:
+
+ deprecated option (option from previous Bochs version not needed /
+ supported anymore)
+ mutually exclusive option (e.g. and )
+ dependent option (e.g. USB support requires PCI support)
+ incomplete option (e.g. requires an argument)
+ development package for library not installed (e.g. for )
+
+If the configure issue cannot be fixed by option changes and / or installing
+development packages / tools it should be reported in the &devlist; or the SF bug
+tracker for the Bochs project.
+
+
+
+Make / compilation failure
+
+The make utility itself can only fail if the specified target
+is not supported by the environment or simply doesn't exist. In most cases the programs
+called from make are causing the failure (e.g. compiler / linker).
+
+
+In some cases it might be useful to rebuild Bochs completely by calling
+make dist-clean and running the configure
+script once again. These steps are recommended if the development sources from
+SVN are used and one of the build system files (e.g. Makefile
+or config.h.in) has been changed.
+
+
+Sometimes it is possible to isolate the failing piece of code by disabling one or
+more configure options. For example, if the compilation fails somewhere in the cpu/avx*
+files, it might help to configure without . The same
+could be done with other Bochs facilities controlled by configure options.
+
+
+
+Runtime issues with self-compiled Bochs
+
+After a successful compilation the self-compiled Bochs can fail if at least one
+library is not installed properly. This can happen if the library consists of a
+development and a runtime package and the second one is missing. Another problem
+can appear on build environments like Cygwin and MinGW/MSYS. Applications built
+there are usually designed to be run inside of the environment. When starting
+them from the Windows shell, it may cause errors like "missing cygwin1.dll"
+or similar. In that case, the missing DLL must be copied from e.g. the Cygwin folder
+to the location of the compiled EXE file.
+
+
+
+
+
+
+
+
+
+Setup
+What does Bochs need?
+
+These are the minimum requirements for running an OS inside of Bochs:
+
+
+
+the Bochs executable
+
+
+
+
+the BIOS image (usually called BIOS-bochs-latest)
+
+
+
+
+the VGA BIOS image (e.g. VGABIOS-lgpl-latest or VGABIOS-elpin-2.40)
+
+
+
+
+at least one bootable media, either as disk image (floppy, hard disk or CD-ROM) or physical disk (floppy or CD-ROM)
+
+
+
+
+
+
+Both VGA BIOS versions as well as the ROM BIOS are part of the Bochs package. No separate download is necessary.
+See for more information.
+
+
+If you want to use the Cirrus SVGA adapter instead of VGA + Bochs VBE, you should
+have a look at .
+
+
+
+In that case you have to pass the configuration options on the command
+line or to use the configuration interface to set up Bochs for the simulation.
+Running Bochs is easier if you use a configuration file (we call it
+bochsrc). See for all supported options.
+
+
+
+The easiest way to setup Bochs for the first time is to use the example configuration
+file called bochsrc-sample.txt. Locate that file (location depends
+on the (host) OS and on the installation facility used) and copy it to a location where
+Bochs looks for that file, see .
+
+
+
+The next step is to change the configuration so that it fits your needs: You most
+likely want to setup a hard disk (see and
+), and install some OS on it using either
+a set of floppy disks (see ) or a CD-ROM
+(see again) as installation media.
+Make sure you boot the emulation from the media you want, using the right setting
+as boot option.
+
+
+
+If your keyboard output inside of Bochs is wrong, you may also need a keymap file
+to remap your keyboard layout to the U.S. layout. A set of keymap files for the
+X window system and SDL (Linux port) is distributed with Bochs. If your
+keyboard layout is not supported yet, you can create your own one by following the
+instructions given in .
+
+
+
+A collection of disk images of different operating systems can be found at
+. Some disk
+images are the size of a floppy disk (1 meg compressed) and others are gigantic
+(160 meg compressed). If you want to create a disk image yourself, please see
+.
+
+
+
+
+
+ROM images
+
+Just like a real PC, Bochs needs a system BIOS and VGA BIOS to initialize the
+machine when it powers on or after a hardware reset. Bochs needs to load them
+from image file into the emulated memory. The Bochs package contains a set of
+system BIOS and VGA BIOS images.
+
System and VGA BIOS images
+
+ FileDescription
+
+
+BIOS-bochs-latest default ROM BIOS image for Bochs
+BIOS-bochs-legacy ROM BIOS image without 32-bit init code (for i386 and ISA graphics card emulation)
+bios.bin-1.13.0 SeaBIOS ROM image
+VGABIOS-elpin-2.40 legacy VGA BIOS image for Bochs
+VGABIOS-lgpl-latest LGPL'd VGA BIOS image for Bochs
+VGABIOS-lgpl-latest-debug LGPL'd VGA BIOS image for Bochs with debug output to the logfile
+VGABIOS-lgpl-latest-cirrus LGPL'd VGA BIOS image for Bochs with the Cirrus extension enabled
+VGABIOS-lgpl-latest-cirrus-debug LGPL'd VGA BIOS image for Bochs with the Cirrus extension enabled and debug output to the logfile
+VGABIOS-lgpl-latest-banshee LGPL'd VGA BIOS image for Bochs with the Voodoo Banshee extension enabled
+vgabios-cirrus.bin-1.13.0 SeaVGABIOS ROM image (for Cirrus adapter)
+
+
+
+
+
+
+Bochs must be set up to use system and VGA BIOS like this:
+
+ romimage: file=BIOS-bochs-latest, address=0xfffe0000
+ vgaromimage: file=VGABIOS-lgpl-latest
+
+We recommend to use the ROM images distributed with Bochs or one of the latest
+SeaBIOS images. BIOS images designed
+for real hardware mostly do not work properly. Please see the
+for more information.
+
+
+
+Bochs supports optional ROM images to be loaded into the ISA ROM space,
+typically between C8000 and EFFFF (see ). The PCI
+versions of the Bochs network adapter emulations support loading a boot ROM into
+the PCI ROM space (see ).
+
+
+
+
+
+The configuration file <filename>bochsrc</filename>
+
+Bochs uses a configuration file called bochsrc to know
+where to look for disk images, how the Bochs emulation layer should work, etc.
+When you first start up Bochs, it looks around for its configuration file
+(see ), and parses it.
+Here are a few lines from a sample file:
+
+ ata0-master: type=disk, path="30M.sample", cylinders=615, heads=6, spt=17
+ boot: disk
+
+The format is very strict, so be sure to put the right number of spaces and
+use lowercase letters. As you can see, most lines have a keyword telling what
+is being configured, followed by a colon, followed by a few
+property=value pairs, separated by
+commas. For very simple options, sometimes just a single value is needed.
+The source and binary distributions come with a sample
+bochsrc, so you can just copy the sample file and edit the
+settings you need to change.
+
+
+
+The syntax used for bochsrc can also be used as command line arguments for Bochs.
+If you have any spaces in your command line arguments, they should be enclosed
+in single quotes, for example:
+
+ bochs 'boot:floppy' 'floppya: 1_44=a.img, status=inserted'
+
+For other arguments, see section Command line arguments.
+
+
+
+You can use environment variables with the dollar sign prefix in the
+bochsrc file, for example:
+
+ floppya: 1_44="$IMAGES/bootdisk.img", status=inserted
+ boot: floppy
+
+There are two environment variables with a built-in default value which is set
+at compile or installation 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 in the config files of the Bochs 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 to search in for Bochs
+plugins. The paths are separated by colons (on Windows: semicolons).
+A compile-time default is provided if this variable is not defined by the user.
+On Win32 and MacOSX, the default for the share directory is determined by a
+platform-specific specific algorithm. On Win32, we use the registry to see what
+directory Bochs and its support files were installed in. On MacOSX, the share
+directory is the directory where the application is located.
+
+
+
+You can use the #include statement in the bochsrc to read the
+configuration from other files. Now it is possible to put platform or
+installation defaults in a global config file (e.g. location of rom images).
+Put this on top of your config file if the global configuration is stored in /etc:
+
+ #include /etc/bochsrc
+
+
+
+
+Bochs now treats an unknown option as optional device plugin if it exists. It
+loads this plugin and then it tries to call the parser function for this
+configuration line which is located in the plugin. This mechanism is implemented
+for the Bochs network, sound, and USB host controller devices. Externally
+developed device plugins (AKA "user plugins") now can also be loaded this way.
+
+
+
+The section below lists all the supported bochsrc options.
+
+
+plugin_ctrl
+
+Example:
+
+ plugin_ctrl: unmapped=0, e1000=1 # unload 'unmapped' and load 'e1000'
+
+Controls the presence of optional device plugins. These plugins are loaded
+directly with this option and some of them install a config option that is
+only available when the plugin device is loaded. The value "1" means to load
+the plugin and "0" will unload it (if loaded before).
+
+
+These plugins will be loaded by default (if present): 'biosdev', 'extfpuirq',
+'gameport', 'iodebug','parallel', 'serial', 'speaker' and 'unmapped'.
+
+
+These plugins are also supported, but they are usually loaded directly with
+their bochsrc option: 'e1000', 'es1370', 'ne2k', 'pcidev', 'pcipnic', 'sb16',
+'usb_ehci', 'usb_ohci', 'usb_uhci', 'usb_xhci' and 'voodoo'.
+
+
+Externally developed device plugins (AKA "user plugins") now can also be loaded
+this way.
+
+
+
+config_interface
+
+The configuration interface is a series of menus or dialog boxes that
+allows you to edit all the settings that control Bochs' 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 or
+GUI console (if available / runtime config) and is always compiled in, unless
+Bochs is compiled for wx only. The choice "win32config" is only available on
+win32/win64 and it is the default on these platforms. The choice "wx" is only
+available when Bochs is compiled with wxWidgets support, see .
+If you do not write a config_interface line, Bochs will choose a default for you.
+
+
+
+wxWidgets provides both a configuration interface and a display library.
+So if you use the "wx" configuration interface, you must also use
+the "wx" display library, see
+display_library option.
+
+
+
+Examples:
+
+ config_interface: textconfig
+ config_interface: win32config
+ config_interface: wx
+
+
+
+
+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
+options, the display_library option lets you choose which one you want to run with.
+If you do not use a display_library line, Bochs will choose a default for
+you.
+
+
+
+wxWidgets provides both a configuration interface and a display library.
+So if you use the "wx" display library, you must also use
+the "wx" configuration interface, see
+config_interface option.
+
+
+
+Examples:
+
+ display_library: x
+ display_library: sdl2, options=fullscreen
+ display_library: options=cmdmode
+
+Some display libraries now support specific options to control their
+behaviour. These options are supported by more than one display library:
+
+ "cmdmode" - call a headerbar button handler after pressing F7 (sdl, sdl2, win32, x)
+ "fullscreen" - startup in fullscreen mode (sdl, sdl2)
+ "gui_debug" - use GTK debugger GUI (sdl, x) / Win32 debugger GUI (sdl, sdl2, win32)
+ "hideIPS" - disable IPS output in status bar (rfb, sdl, sdl2, term, vncsrv, win32, wx, x)
+ "nokeyrepeat" - turn off host keyboard repeat (sdl, sdl2, win32, x)
+ "no_gui_console" - use system console instead of builtin GUI console (rfb, sdl, sdl2, vncsrv, x)
+ "timeout" - time (in seconds) to wait for client (rfb, vncsrv)
+
+See the examples below for other currently supported options.
+
+ # "traphotkeys" - system hotkeys not handled by host OS, but sent to guest
+ # (win32 in mouse capture and fullscreen mode: alt-tab, win,
+ # alt-space, alt-esc, ctrl-esc)
+ # "autoscale" - scale small simulation window by factor 2, 4 or 8 depending
+ # on desktop window size
+ display_library: win32, options="traphotkeys autoscale"
+
+Setting up options without specifying display library is also supported.
+
+
+
+display_library values
+
+
+
+ Option
+ Description
+
+
+
+
+ x
+ use X windows interface, cross platform
+
+
+ win32
+ use native win32 libraries
+
+
+ carbon
+ use Carbon library (for MacOS X)
+
+
+ macintosh
+ use MacOS pre-10
+
+
+ amigaos
+ use native AmigaOS libraries
+
+
+ sdl
+ use SDL 1.2.x library, cross platform,
+ details in
+
+
+ sdl2
+ use SDL 2.x library, cross platform,
+ details in
+
+
+ term
+ text only, uses curses/ncurses library, cross platform
+
+
+ rfb
+ provides an interface to AT&T's VNC viewer, cross platform,
+ details in
+
+
+ vncsrv
+ use LibVNCServer for extended RFB(VNC) support,
+ details in
+
+
+ wx
+ use wxWidgets library, cross platform,
+ details in
+
+
+ nogui
+ no display at all
+
+
+
+
+
+
+cpu
+
+Example:
+
+ cpu: count=2, ips=10000000
+
+This defines the parameters of the cpu inside Bochs:
+
+model
+
+Selects CPU configuration to emulate from pre-defined list of all
+supported configurations. When this option is used and the value
+is different from 'bx_generic', the parameters of the CPUID
+option have no effect anymore. See the for supported values.
+
+count
+
+Set the number of processors:cores per processor:threads per core when Bochs
+is compiled for SMP emulation. Bochs currently supports up to 14 threads
+(legacy APIC) or 254 threads (xAPIC or higher) running simultaniosly.
+If Bochs is compiled without SMP support, it won't accept values
+different from 1. For more information on SMP see .
+
+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 a triple fault occurs (highly recommended) rather than PANIC.
+Remember that if you are 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 work around WinNT installation and boot issues.
+
+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 .
+
+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 available 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
+ option enabled, to find your workstation's capability.
+Measured IPS value will then be logged into your log file
+or in the 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. The table below lists some typical
+IPS settings for different machinesIPS measurements depend on
+OS and compiler configuration in addition to host processor clock
+speed..
+
+
+
Example IPS Settings
+
+
+
+ Bochs
+ Speed
+ Machine/Compiler
+ Typical IPS
+
+
+
+2.4.63.4GhzIntel Core i7 2600 with Win7x64/g++ 4.5.2 85 to 95 MIPS
+2.3.73.2GhzIntel Core 2 Q9770 with WinXP/g++ 3.4 50 to 55 MIPS
+2.3.72.6GhzIntel Core 2 Duo with WinXP/g++ 3.4 38 to 43 MIPS
+2.2.62.6GhzIntel Core 2 Duo with WinXP/g++ 3.4 21 to 25 MIPS
+2.2.62.1GhzAthlon XP with Linux 2.6/g++ 3.4 12 to 15 MIPS
+
+
+
+
+
+cpuid
+
+Example:
+
+ cpuid: level=6, mmx=1, sep=1, sse=sse4_2, apic=xapic, aes=1, movbe=1, xsave=1
+
+This defines features and functionality supported by Bochs emulated CPU. These settings
+are only valid and configurable if the cpu model is
+set to the default value 'bx_generic'.
+
+level
+
+Set emulated CPU level information returned by CPUID. Default value is
+determined by configure option --enable-cpu-level.
+Currently supported values are 5 (for Pentium and similar processors) and 6 (for P6 and
+later processors).
+
+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 brand string returned by CPUID(0x80000002 .. 0x80000004]). This should be
+at most a forty-eight-character ASCII string.
+
+mmx
+
+Select MMX instruction set support.
+This option exists only if Bochs compiled with BX_CPU_LEVEL >= 5.
+
+apic
+
+Select APIC configuration (LEGACY/XAPIC/XAPIC_EXT/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.
+
+simd
+
+Select SIMD instructions support.
+Any of NONE/SSE/SSE2/SSE3/SSSE3/SSE4_1/SSE4_2/AVX/AVX2/AVX512 could be selected.
+This option exists only if Bochs compiled with BX_CPU_LEVEL >= 6.
+The AVX choices exists only if Bochs compiled with --enable-avx option.
+
+sse4a
+
+Select AMD SSE4A instructions support.
+This option exists only if Bochs compiled with BX_CPU_LEVEL >= 6.
+
+misaligned_sse
+
+Select AMD Misaligned SSE mode 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.
+
+sha
+
+Select SHA 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.
+
+adx
+
+Select ADCX/ADOX instructions 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_f16c
+
+Select AVX float16 convert instructions support.
+This option exists only if Bochs compiled with option.
+
+avx_fma
+
+Select AVX fused multiply add (FMA) instructions support.
+This option exists only if Bochs compiled with option.
+
+bmi
+
+Select BMI1/BMI2 instructions support.
+This option exists only if Bochs compiled with option.
+
+fma4
+
+Select AMD four operand FMA instructions support.
+This option exists only if Bochs compiled with option.
+
+xop
+
+Select AMD XOP instructions support.
+This option exists only if Bochs compiled with option.
+
+tbm
+
+Select AMD TBM instructions support.
+This option exists only if Bochs compiled with option.
+
+x86_64
+
+Enable x86-64 and long mode support.
+This option exists only if Bochs compiled with x86-64 support.
+
+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.
+
+smap
+
+Enable Supervisor Mode Access Prevention (SMAP) 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 .
+
+vmx
+
+Select VMX extensions emulation support.
+This option exists only if Bochs compiled with option.
+
+svm
+
+Select AMD SVM (Secure Virtual Machine) extensions emulation support.
+This option exists only if Bochs compiled with option.
+
+
+
+memory
+
+Examples:
+
+ memory: guest=512, host=256
+
+Set the amount of physical memory you want to emulate.
+
+guest
+
+Set amount of guest physical memory to emulate. The default is 32MB,
+the maximum amount limited only by physical address space limitations.
+
+host
+
+Set amount of host memory you want to allocate for guest RAM emulation.
+It is possible to allocate less memory than you want to emulate in guest
+system. This will fake guest to see the non-existing memory. Once guest
+system touches new memory block it will be dynamically taken from the
+memory pool. You will be warned (by FATAL PANIC) in case guest already
+used all allocated host memory and wants more.
+
+
+Due to limitations in the host OS, Bochs fails to allocate more than 1024MB on most 32-bit systems.
+In order to overcome this problem, configure and build Bochs with
+option.
+
+
+
+megs
+
+Examples:
+
+ megs: 32
+ megs: 128
+
+This option sets the 'guest' and 'host' memory parameters to the same
+value. In all other cases the 'memory' option should be used instead.
+
+
+
+romimage
+
+Examples:
+
+ romimage: file=bios/BIOS-bochs-latest, options=fastboot
+ romimage: file=$BXSHARE/BIOS-bochs-legacy
+ romimage: file=mybios.bin, address=0xfff80000
+
+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
+BIOS-bochs-latest. The default ROM BIOS is usually loaded
+starting at address 0xfffe0000, and it is exactly 128k long. The legacy version
+of the Bochs BIOS is usually loaded starting at address 0xffff0000, and it is
+exactly 64k long.
+You can 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.
+The Bochs BIOS currently supports only the option "fastboot" to skip the
+boot menu delay.
+
+
+
+vgaromimage
+
+Examples:
+
+ vgaromimage: file=bios/VGABIOS-elpin-2.40
+ vgaromimage: file=$BXSHARE/VGABIOS-lgpl-latest
+ vgaromimage: file=$BXSHARE/VGABIOS-lgpl-latest-cirrus
+
+This tells Bochs what VGA ROM BIOS to load (at 0xC0000).
+
+A VGA BIOS from Elpin Systems, Inc. as well as a free LGPL'd VGA BIOS
+are provided in the source and binary distributions.
+
+ Please check with the vga option to decide
+ what VGA BIOS to use.
+
+
+
+
+optromimage1, optromimage2, optromimage3 or optromimage4
+
+Example:
+
+ optromimage1: file=optionalrom.bin, address=0xd0000
+
+
+This enables Bochs to 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
+
+
+
+
+vga
+
+Examples:
+
+ vga: extension=cirrus, update_freq=10, realtime=1, ddc=file:monitor.bin
+ vga: extension=vbe
+
+This defines parameters related to the VGA display
+
+
+The 'extension' option can be used to specify the VGA display extension.
+With the value 'none' you can use standard VGA with no extension. Other supported
+values are 'vbe' for Bochs VBE (needs VGABIOS-lgpl-latest as
+VGA BIOS, see vgaromimage option),
+'cirrus' for Cirrus SVGA support (needs VGABIOS-lgpl-latest-cirrus
+as VGA BIOS) and 'voodoo' for Voodoo Graphics support (needs
+VGABIOS-lgpl-latest-banshee as VGA BIOS / see
+ for more information).
+
+
+The VGA update frequency specifies the number of display updates per second.
+This parameter can be changed at runtime. The default value is 5.
+
+
+The 'realtime' option specifies the operation mode of the VGA update timer.
+If set to 1, the VGA timer is based on realtime, otherwise it is based on the
+ips setting. If the host is slow (low ips, update_freq) and the guest uses HLT
+appropriately, setting this to 0 and "clock: sync=none" may improve the
+responsiveness of the guest GUI when the guest is otherwise idle. The default
+value is 1.
+
+
+The parameter 'ddc' defines the behaviour of the DDC emulation that returns
+the monitor EDID data. By default, the 'builtin' values for 'Bochs Screen'
+are used. Other choices are 'disabled' (no DDC emulation) and 'file'
+(read monitor EDID from file / path name separated with a colon).
+
+
+
+
+voodoo
+
+Example:
+
+ voodoo: enabled=1, model=voodoo1
+
+This defines the Voodoo Graphics emulation (experimental). Currently
+supported models are 'voodoo1', 'voodoo2', 'banshee' and 'voodoo3'.
+The Voodoo2 support is not yet complete, but almost usable. The Banshee /
+Voodoo3 support is under construction, but basically usable. The 2D/3D cards
+require the vga extension option to be set to 'voodoo'. If the i440BX PCI
+chipset is selected, they can be assigned to AGP (slot #5). The GUI screen
+update timing for all models is controlled by the related
+'vga' options. See for more information.
+
+
+
+keyboard
+
+Examples:
+
+ keyboard: type=mf, serial_delay=200, paste_delay=100000
+ keyboard: keymap=gui/keymaps/x11-pc-de.map
+ keyboard: user_shortcut=ctrl-alt-del
+
+This defines parameters related to the emulated keyboard.
+
+type
+
+Type of keyboard return by a "identify keyboard" command to the
+keyboard controller. It must be one of "xt", "at" or "mf".
+Defaults to "mf". It should be ok for almost everybody. A known
+exception is French macs, that do have a "at"-like keyboard.
+
+serial_delay
+
+Approximate time in microseconds that it takes one character to
+be transferred from the keyboard to controller over the serial path.
+
+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.
+
+keymap
+
+This enables a remap of a physical localized keyboard to a
+virtualized us keyboard, as the PC architecture expects.
+
+
+Keyboard mapping is available for the display libraries x, sdl (Linux port) and
+wx (GTK port). For SDL you have to use keymaps designed for SDL, the wxWidgets GUI
+uses the keymaps for X11.
+
+user_shortcut
+
+This defines the keyboard shortcut to be sent when you press the "user" button
+in the headerbar. 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", "power", "print", "right", "scrlck", "shift", "space", "tab", "up"
+and "win".
+
+
+
+
+mouse
+
+Examples:
+
+ mouse: enabled=1
+ mouse: type=imps2, enabled=1
+ mouse: type=serial, enabled=1
+ mouse: enabled=0, toggle=ctrl+f10
+
+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', 'serial_msys' (one com port requires
+setting 'mode=mouse', see com option)
+'inport' and 'bus' (if present). To connect a mouse to a USB port, see the
+usb_uhci, 'usb_ohci', 'usb_ehci'
+or 'usb_xhci' options (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 (see headerbar
+and the 'toggle' option 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) or 'ctrl+alt' (like QEMU)
+or 'f12'.
+
+
+
+pci
+
+This defines the parameters to set up the Bochs PCI emulation:
+
+
+Examples:
+
+ pci: enabled=1, chipset=i440fx # default if compiled with PCI support
+ pci: enabled=1, chipset=i440fx, slot1=pcivga, slot2=ne2k, advopts=noacpi
+ pci: enabled=1, chipset=i440bx, slot5=voodoo, slot1=e1000
+
+
+enabled
+
+If Bochs is compiled with PCI support, it is enabled by default.
+
+chipset
+
+Currently the chipsets i430FX, i440FX and i440BX (limited) are supported and
+the default is i440FX.
+
+slotX
+
+It is possible to specify the devices connected to PCI slots. Up to 5 slots
+are available. For combined PCI/ISA devices assigning to slot is mandatory
+if the PCI model should be emulated (cirrus, ne2k and pcivga). Setting up
+slot for PCI-only devices is also supported, but they are auto-assigned if
+not specified (e1000, es1370, pcidev, pcipnic, usb_ehci, usb_ohci, usb_xhci,
+voodoo). All device models except the network devices ne2k and e1000 can be
+used only once in the slot configuration. In case of the i440BX chipset, the
+slot #5 is the AGP slot. Currently only the 'voodoo' device can be assigned
+to AGP.
+
+advopts
+
+With the advanced PCI options, it is possible to control the behaviour of the
+PCI chipset. These options can be specified as comma-separated values.
+By default, the "Bochs i440FX" chipset enables the ACPI and HPET devices, but
+original i440FX doesn't support them. The options 'noacpi' and 'nohpet' make
+it possible to disable them. The option 'noagp' disables the incomplete AGP
+subsystem of the i440BX chipset.
+
+
+
+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.
+
+rtc_sync
+
+If this option is enabled together with the realtime synchronization,
+the RTC runs at realtime speed. This feature is disabled by default.
+
+time0
+
+Specifies the start (boot) time of the virtual machine. Use a time
+value as returned by the time(2) system call or a string as returned
+by the ctime(3) 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]
+
+Examples:
+ clock: sync=none, time0=local # Now (localtime)
+ clock: sync=slowdown, time0=315529200 # Tue Jan 1 00:00:00 1980
+ clock: sync=none, time0="Mon Jan 1 00:00:00 1990" # 631148400
+ clock: sync=realtime, time0=938581955 # Wed Sep 29 07:12:35 1999
+ clock: sync=realtime, time0="Sat Jan 1 00:00:00 2000" # 946681200
+ clock: sync=none, time0=1 # Now (localtime)
+ clock: sync=none, time0=utc # Now (utc/gmt)
+
+Default value are sync=none, rtc_sync=0, time0=local
+
+
+
+
+
+cmosimage
+
+Example:
+
+ cmosimage: file=cmos.img, rtc_init=time0
+
+This defines a binary image file with size 128 bytes 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.
+
+
+
+private_colormap
+
+Example:
+
+ private_colormap: enabled=1
+
+Requests that the GUI creates and uses its 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.
+
+
+
+floppya/floppyb
+
+Examples:
+
+2.88M 3.5" media:
+ floppya: 2_88=a:, status=inserted
+1.44M 3.5" media (write protected):
+ floppya: 1_44=floppya.img, status=inserted, write_protected=1
+1.2M 5.25" media:
+ floppyb: 1_2=/dev/fd0, status=inserted
+720K 3.5" media:
+ floppya: 720k=/usr/local/bochs/images/win95.img, status=inserted
+auto-detect floppy media type:
+ floppya: image=floppy.img, status=inserted
+use directory as VFAT media:
+ floppya: 1_44=vvfat:path, status=inserted
+1.44M 3.5" floppy drive, no media:
+ floppya: type=1_44
+
+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. To read from a disk
+image, write the name of the image file. In many operating systems Bochs can
+read directly from a raw floppy drive. For raw disk access, use the device
+name (Unix systems) or the drive letter and a colon (Windows systems).
+
+
+Following floppy media types are supported: 2_88, 1_44, 1_2, 720k, 360k, 320k, 180k,
+160k, as well as "image" to let Bochs auto-detect the type of floppy media (does only
+work with images, not with raw floppy drives). In that case the size must match
+one of the supported types.
+
+
+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.
+
+
+
+ata0, ata1, ata2, ata3
+
+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
+
+
+These options enable 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 above.
+
+
+
+
+ata0-master, ata0-slave, ata1-*, ata2-*, ata3-*
+
+Examples:
+
+ata0-master: type=disk, path=10M.img, mode=flat, cylinders=306, heads=4, spt=17, translation=none
+ata1-master: type=disk, path=2GB.cow, mode=vmware3, cylinders=5242, heads=16, spt=50, translation=echs
+ata1-slave: type=disk, path=3GB.img, mode=sparse, cylinders=6541, heads=16, spt=63, translation=auto
+ata2-master: type=disk, path=7GB.img, mode=undoable, cylinders=14563, heads=16, spt=63, translation=lba
+ata2-slave: type=cdrom, path=iso.sample, status=inserted
+
+
+
+
+
+This defines the type and characteristics of all attached ata devices:
+
+ata devices configuration options
+
+
+
+Option
+Comments
+Possible values
+
+
+
+ type type of attached device [disk | cdrom]
+ path path of the image
+
+ mode
+ image type, only valid for disks
+ [flat | concat | dll | sparse | vmware3 | vmware4 | undoable | growing | volatile | vpc | vbox | vvfat ]
+
+ cylinders only valid for disks
+ heads only valid for disks
+ spt only valid for disks
+ status only valid for CD-ROMs [inserted | ejected]
+ biosdetect type of biosdetection [auto | cmos | none]
+ translation type of translation done by the BIOS (legacy int13), only for disks [none | lba | large | rechs | auto]
+ model string returned by identify device ATA command
+ journal optional filename of the redolog for undoable, volatile and vvfat disks
+
+
+
+
+
+
+ You have to tell the type of the attached device. For Bochs 2.0 or later, it can be
+ disk or cdrom.
+
+
+
+You have to point the "path" at a hard disk image file, CD-ROM iso file,
+or physical CD-ROM device.
+To create a hard disk image, try running bximage (see
+). 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 for safety reasons. In Windows, there is no easy way.
+
+
+
+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. Flat hard disk
+images from other projects might store additional information at the end of the
+file that makes this check fail. Only in this case it is safe to select "continue"
+when Bochs panics.
+
+
+
+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)
+
+
+Please see for a discussion on translation scheme.
+
+
+
+The mode option defines how the disk image is handled. Disks can be defined as:
+
+
+flat : one file flat layout
+
+
+concat : multiple files layout
+
+
+dll : developer's specific, through a DLL
+
+
+sparse : stackable, commitable, rollbackable
+
+
+vmware3 : vmware version 3 disk support
+
+
+vmware4 : vmware version 4 disk support (aka VMDK)
+
+
+undoable : read-only base file with commitable redolog
+
+
+growing : growing file
+
+
+volatile : read-only base file with volatile redolog
+
+
+vpc: fixed / dynamic size VirtualPC image
+
+
+vbox: fixed / dynamic size Oracle(tm) VM VirtualBox image (VDI version 1.1)
+
+
+vvfat: local directory appears as VFAT disk (with volatile redolog / optional commit)
+
+
+Please see for a discussion on disk modes.
+
+
+
+Default values are:
+
+ mode=flat, biosdetect=auto, translation=auto, model="Generic 1234"
+
+
+
+
+ The biosdetect option has currently no effect on the BIOS.
+
+
+
+ Make sure the proper ata option is enabled when
+ using a device on that ata channel.
+
+
+
+boot
+
+Examples:
+
+ boot: floppy
+ boot: cdrom, disk
+ boot: network, disk
+ boot: cdrom, floppy, disk
+
+This defines the boot sequence. 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.
+
+
+
+floppy_bootsig_check
+
+Example:
+
+ floppy_bootsig_check: disabled=1
+
+This disables the 0xaa55 signature check on boot floppies
+The check is enabled by default.
+
+
+
+log
+
+Examples:
+
+ log: bochsout.txt
+ log: -
+ log: /dev/tty (Unix only)
+ log: /dev/null (Unix only)
+ log: nul (win32 only)
+
+Give the path of the log file you'd like Bochs debug and misc. verbiage to be
+to be written to. If you don't use this option or set the filename to '-'
+the output is written to the console. If you really don't want it,
+make it "/dev/null" (Unix) or "nul" (win32). :^(
+
+
+
+logprefix
+
+Examples:
+
+ logprefix: %t-%e-@%i-%d
+ logprefix: %i%e%d
+
+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 current cpu eip (ignored in SMP configuration)
+ %e : 1 character event type ('i'nfo, 'd'ebug, 'p'anic, 'e'rror)
+ %d : 5 characters string of the device, between brackets
+
+
+
+Default is %t%e%d
+
+
+
+debug/info/error/panic
+
+Examples:
+
+ debug: action=ignore, pci=report
+ info: action=report
+ error: action=report
+ panic: action=ask
+
+
+During simulation, Bochs encounters certain events that the user might want to
+know about. These events are divided into four levels of importance: debug,
+info, error, and panic. Debug messages are usually only useful when writing
+Bochs code or when trying to locate a problem. There may be thousands of debug
+messages per second, so be careful before turning them on. Info messages tell
+about interesting events that don't happen that frequently. 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. Panic messages mean that
+Bochs cannot simulate correctly and should probably shut down.
+A panic can be a configuration problem (like a misspelled bochsrc line) or an
+emulation problem (like an unsupported video mode).
+
+
+
+The debug, info, error, and panic lines in the bochsrc control what Bochs will
+do when it encounters each type of event. The allowed actions are: fatal
+(terminate Bochs), ask (ask the user what to do), warn (show dialog with message
+and continue), report (print information to the console or log file), or ignore
+(do nothing). The recommended settings are listed in the sample above.
+
+
+
+It is also possible to specify the 'action' to do for each Bochs facility
+separately (e.g. crash on panics from everything except the CD-ROM, and only
+report those). See the log function module table
+for valid module names.
+
+
+
+
+The safest action for panics is "fatal" or "ask". If you are getting lots of
+panics and get tired of telling it to continue each time, 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 after a panic occurs.
+Please report panic messages to the &devlist; unless it is just a configuration
+problem like "could not find hard drive image."
+
+
+
+
+debugger_log
+
+Examples:
+
+ debugger_log: debugger.out
+ debugger_log: /dev/null (Unix only)
+ 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 '-'.
+
+
+
+
+com[1-4]
+
+Examples:
+
+ com1: enabled=1, mode=null
+ com1: enabled=1, mode=mouse
+ com1: enabled=1, mode=term, dev=/dev/ttyp9
+ com2: enabled=1, mode=file, dev=serial.out
+ com3: enabled=1, mode=raw, dev=com1
+ com3: enabled=1, mode=socket-client, dev=localhost:8888
+ com3: enabled=1, mode=socket-server, dev=localhost:8888
+ com4: enabled=1, mode=pipe-client, dev=\\.\pipe\mypipe
+ com4: enabled=1, mode=pipe-server, dev=\\.\pipe\mypipe
+
+ This defines a serial port (UART type 16550A).
+
+
+ When using the mode '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 of 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.
+
+
+ When using socket* and pipe* (win32 only) modes Bochs becomes either
+ socket/named pipe client or server. In client mode it connects to an already
+ running server (if connection fails Bochs treats com port as not connected).
+ In server mode it opens socket/named pipe and waits until a client application
+ connects to it before starting simulation. This mode is useful for remote
+ debugging (e.g. with gdb's "target remote host:port" command or windbg's command
+ line option -k com:pipe,port=\\.\pipe\pipename). Socket modes use simple TCP
+ communication, pipe modes use duplex byte mode pipes.
+
+
+ Other serial modes are 'null' (no input/output), 'file' (output to a file
+ specified as the 'dev' parameter and changeable at runtime), 'raw' (use the
+ real serial port - partly implemented on win32), 'mouse' (standard serial
+ mouse - requires mouse option setting
+ 'type=serial', 'type=serial_wheel' or 'type=serial_msys').
+
+
+
+
+parport[1-2]
+
+Examples:
+
+ parport1: enabled=1, file="parport.out"
+ parport2: enabled=1, file="/dev/lp0"
+ parport1: enabled=0
+
+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, "lpt1" on
+win32 platforms). The output file can be changed at runtime.
+
+
+
+
+sound
+
+Example for one driver (uses platform-default):
+
+ sound: driver=default, waveout=/dev/dsp
+
+Example for different drivers:
+
+ sound: waveoutdrv=sdl, waveindrv=alsa, midioutdrv=dummy
+
+This defines the lowlevel sound driver(s) for the wave (PCM) input / output
+and the MIDI output feature and (if necessary) the devices to be used.
+It can have several of the following properties. All properties are in the
+format sound: property=value.
+
+
+
+ : This defines the driver to be used for the
+ waveout feature. Possible values are 'file' (all wave data sent to file),
+ 'dummy' (no output) and the platform-dependant drivers 'alsa', 'oss', 'osx',
+ 'sdl' and 'win'.
+
+
+
+ :
+ This defines the device to be used for wave output (if necessary) or the
+ output file for the 'file' driver.
+
+
+
+ :
+ This defines the driver to be used for the wavein feature.
+ Possible values are 'dummy' (recording silence) and platform-dependent
+ drivers 'alsa', 'oss', 'sdl' and 'win'.
+
+
+
+ :
+ This defines the device to be used for wave input (if necessary).
+
+
+
+ :
+ This defines the driver to be used for the MIDI output feature.
+ Possible values are 'file' (all MIDI data sent to file), 'dummy' (no
+ output) and platform-dependent drivers 'alsa', 'oss', 'osx' and 'win'.
+
+
+
+ :
+ This defines the device to be used for MIDI output (if necessary).
+
+
+
+ :
+ This defines the driver to be used for all sound features with one
+ property. Possible values are 'default' (platform default) and all
+ other choices described above. Overriding one or more settings with
+ the specific driver parameter is possible.
+
+
+See for more information.
+
+
+
+
+speaker
+
+Example:
+
+ speaker: enabled=1, mode=sound
+
+This defines the PC speaker output mode. In the 'sound' mode the beep
+is generated by the square wave generator which is a part of the
+lowlevel sound support. In this mode the 'volume' parameter can be used
+to set the output volume (0 - 15). The 'system' mode is only available on
+Linux and Windows. On Linux /dev/console is used for output and on Windows
+the Beep() function. The 'gui' mode forwards the beep to the related
+GUI methods (currently only used by the Carbon GUI).
+
+
+
+sb16
+
+Example:
+
+ sb16: midimode=2, midifile=output.mid, wavemode=3, wavefile=output.wav
+ loglevel=2, log=sb16.log, dmatimer=600000
+
+
+The example is wrapped onto several lines for formatting reasons, but it
+should all be on one line in the actual bochsrc file.
+
+
+This defines the Sound Blaster 16 emulation, see the developer documentation
+for more information. It can have several of the following properties. All properties
+are in the usual "property=value" format.
+
+
+
+ :
+ This optional property controls the presence of the SB16 emulation.
+ The emulation is turned on unless this property is used and set to 0.
+
+
+
+ :
+ This parameter specifies what to do with the MIDI output.
+
+ 0 = no output
+ 1 = output to device specified with the sound option (system dependent)
+ 2 = MIDI or raw data output to file (depends on file name extension)
+ 3 = dual output (mode 1 and 2 at the same time)
+
+
+
+
+ :
+ This is the file where the midi output is stored (midimode 2 or 3).
+
+
+
+ :
+ This parameter specifies what to do with the PCM output.
+
+ 0 = no output
+ 1 = output to device specified with the sound option (system dependent)
+ 2 = VOC, WAV or raw data output to file (depends on file name extension)
+ 3 = dual output (mode 1 and 2 at the same time)
+
+
+
+
+ :
+ This is the file where the wave output is stored (wavemode 2 or 3).
+
+
+
+ : The file to write the sb16 emulator messages to.
+
+
+
+ :
+
+ 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.
+
+
+
+ :
+ 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 value at runtime.
+
+
+
+
+
+es1370
+
+Examples:
+
+ es1370: enabled=1, wavemode=1 # use 'sound' parameters
+ es1370: enabled=1, wavemode=2, wavefile=output.voc # send output to file
+
+This defines the ES1370 sound emulation (recording and playback - except
+DAC1+DAC2 output at the same time). The parameter 'enabled' controls the
+presence of the device. The wave and MIDI output can be sent to device, file
+or both using the parameters 'wavemode', 'wavefile', 'midimode' and
+'midifile'. See the description of these parameters at the SB16 directive.
+
+
+
+
+ne2k
+
+The ne2k line configures an emulated NE2000-compatible Ethernet adapter,
+which allows the guest machine to communicate on the network. To disable
+the NE2000 just comment out the ne2k line.
+
+
+Examples:
+
+ne2k: ioaddr=0x300, irq=9, mac=b0:c4:20:00:00:00, ethmod=fbsd, ethdev=xl0
+ne2k: ioaddr=0x300, irq=9, mac=b0:c4:20:00:00:00, ethmod=fbsd, ethdev=en0 #macosx
+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=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"
+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: mac=b0:c4:20:00:00:01, ethmod=socket, ethdev=40000 # use localhost
+ne2k: card=0, mac=b0:c4:20:00:00:01, ethmod=socket, ethdev=mymachine:40000
+ne2k: mac=b0:c4:20:00:00:01, ethmod=slirp, script=slirp.conf, bootrom=ne2k_pci.rom
+
+CARD: This is the zero-based card number to configure with this ne2k config
+line. Up to 4 devices are supported now (0...3). If not specified, the
+following parameters apply to card #0.
+
+TYPE: This is the card type to emulate ("isa" or "pci"). If not specified,
+card #0 defaults to "pci" if assigned to a pci slot. For the additional cards
+the type parameter should be set up.
+
+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. You can also specify a network
+simulator or a module with no input/output ("null"). See the table below for
+currently supported values.
+
+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. The 'slirp' module uses this parameter to specify a config
+file for setting up an alternative IP configuration or additional features.
+The 'vnet' module also uses this parameter to specify a config file similar
+to slirp, but with only a few settings.
+
+BOOTROM: The bootrom value is optional, and is the name of the ROM image
+to load. Note that this feature is only implemented for the PCI version of
+the NE2000.
+
+
+
+
+The following table shows the available ethernet modules with description,
+whether the "ethdev" and "script" parameters are used or not and the Bochs
+version where this module was added.
+
+
Ethernet modules
+
+
+
+ Module
+ Description
+ ethdev
+ script
+ Bochs version
+
+
+
+
+ fbsd
+ FreeBSD / OpenBSD packetmover.
+
+ Yes
+ No
+ 1.0
+
+
+ linux
+ Linux packetmover - 'root' privileges required,
+ no connection to the host machine.
+
+ Yes
+ No
+ 1.3
+
+
+ null
+ Null packetmover. All packets are discarded, but logged to a
+ few files.
+
+ No
+ No
+ 1.0
+
+
+ tap
+ TAP packetmover.
+
+ Yes
+ Yes
+ 1.4
+
+
+ tuntap
+ TUN/TAP packetmover - see
+ Configuring and using a tuntap network interface.
+
+ Yes
+ Yes
+ 2.0
+
+
+ vde
+ Virtual Distributed Ethernet packetmover.
+
+ Yes
+ Yes
+ 2.2
+
+
+ vnet
+ ARP, ping (ICMP-echo), DHCP, DNS , FTP and TFTP simulation.
+ The virtual host uses 192.168.10.1. DHCP assigns 192.168.10.15 to the guest.
+ The FTP and TFTP servers use the 'ethdev' value for the root directory.
+ TFTP doesn't overwrite files, DNS for server and client only.
+
+ Yes, for FTP and TFTP root
+ Yes, for log file name
+ 2.2
+
+
+ slirp
+ Built-in Slirp support with DHCP / TFTP servers. Adds user mode
+ networking to Bochs - see Using the 'slirp'
+ networking module. The 'script' parameter can be used to set up
+ an alternative IP configuration or additional features. The TFTP server
+ uses the 'ethdev' value for the root directory and doesn't overwrite files.
+
+ Yes, for TFTP root
+ Yes, for Slirp config
+ 2.6.5
+
+
+ socket
+ Connect up to 6 Bochs instances on the same or other machine
+ with external program 'bxhub' (simulating an ethernet hub). It provides
+ the same services as the 'vnet' module and assigns IP addresses like
+ 'slirp' (10.0.2.x) (see Using the 'socket'
+ networking module).
+
+ Yes, for base UDP port and (optional) the host to connect
+ No
+ 2.6.9
+
+
+ win32
+ Win32 packetmover - WinPCap driver required.
+
+ Yes
+ No
+ 1.3
+
+
+
+
+
+
+pcipnic
+
+Example:
+
+ pcipnic: enabled=1, mac=b0:c4:20:00:00:00, ethmod=vnet
+
+To support the Bochs/Etherboot pseudo-NIC, Bochs must be compiled with the
+ configure option. It accepts the same syntax (for mac,
+ethmod, ethdev, script, bootrom) and supports the same networking modules as the
+NE2000 adapter.
+
+
+
+e1000
+
+Example:
+
+ e1000: enabled=1, mac=52:54:00:12:34:56, ethmod=slirp, script=slirp.conf
+
+To support the Intel(R) 82540EM Gigabit Ethernet adapter, Bochs must be compiled
+with the configure option. It accepts the same syntax
+(for mac, ethmod, ethdev, script, bootrom) and supports the same networking modules
+as the NE2000 adapter.
+
+
+
+usb_uhci
+
+Examples:
+
+ usb_uhci: port1=mouse, port2=disk, options2="path:usbstick.img"
+ usb_uhci: port1=hub, options1="ports:6, pcap:outfile.pcap"
+ usb_uhci: port2=disk, options2="path:undoable:usbdisk.img, journal:u.redolog"
+ usb_uhci: port2=disk, options2=""path:usbdisk2.img, sect_size:1024"
+ usb_uhci: port2=disk, options2="path:vvfat:vvfat, debug, speed:full"
+ usb_uhci: port2=cdrom, options2="path:image.iso"
+ usb_uhci: port1=printer, options1="file:printdata.bin"
+ usb_uhci: port2=floppy, options2="path:vvfat:diskette, model:teac"
+
+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', 'keyboard',
+'disk', 'cdrom', 'floppy, ''hub' and 'printer').
+See for more information on each device setting.
+
+
+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. If the
+keyboard is selected, all key events are sent to the USB device.
+
+
+To connect a disk image as a USB hardisk you can use the 'disk' device. Use
+the 'path' option in the optionsX parameter to
+specify the path to the image separated with a colon. To use other disk image
+modes similar to ATA disks the syntax 'path:mode:filename' must be used (see
+below).
+
+
+To emulate a USB CD-ROM you can use the 'cdrom' device and the path to an
+ISO image or raw device name can be set with the 'path' option in the
+optionsX parameter also separated with a colon. An
+option to insert/eject media is available in the runtime configuration.
+
+
+To emulate a USB floppy, you can use the 'floppy' device and the path to a
+floppy image can be set with the 'path' option in the optionsX
+parameter separated with a colon. To use the VVFAT image mode similar to the
+legacy floppy the syntax 'path:vvfat:directory' must be used (see below).
+An option to insert/eject media is available in the runtime configuration.
+A well-known, somewhat older, but still widely used Operating System must have
+the Vendor ID as an TEAC external drive. If the VendorID is not the TEAC id,
+this operating system doesn't know what to do with the drive. Therefore, use
+the optionsX="model:teac" option in the bochsrc.txt
+file to set this model. If you do not, a default model will be used.
+
+
+
+The device name 'hub' connects an external hub with a maximum of 8 ports (default: 4)
+to the root hub. To specify the number of ports you have to use the 'ports'
+option in the optionsX parameter with the value
+separated with a colon. Connecting devices to the external hub ports is only
+available in the runtime configuration.
+
+
+The device 'printer' emulates the HP Deskjet 920C printer. The PCL data is
+sent to a file specified in the 'file' option with the optionsX
+parameter. The current code appends the PCL code to the file if the file already
+existed. The output file can be changed at runtime.
+
+
+The optionsX parameter can also be used to assign
+specific options to the device connected to the corresponding USB port.
+The option 'speed' can be used to set the speed reported by device ('low',
+'full', 'high' or 'super'). The available speed choices depend on both HC and
+device. The option 'debug' turns on debug output for the device at connection
+time. The option 'pcap' turns on packet logging in PCAP format. For the USB
+'disk' device the optionsX parameter can be used to
+specify an alternative redolog file (journal) of some image modes. For 'vvfat'
+mode USB disks the optionsX parameter can be used to
+specify the disk size (range 128M ... 128G). If the size is not specified, it
+defaults to 504M. For the USB 'floppy' device the optionsX
+parameter can be used to specify an alternative device ID to be reported. Currently
+only the model "teac" is supported (can fix hw detection in some guest OS). The USB
+floppy also accepts the parameter "write_protected" with valid values 0 and 1 to select
+the access mode (default is 0).
+
+
+For USB disk image emulation using the 'disk' or 'cdrom' type, an optionsX
+parameter of 'proto:bbb' or 'proto:uasp' may be used. The former tells Bochs to
+use the 'Bulk/Bulk/Bulk' protocol, aka the 'Bulk only' protocol. This is the
+standard protocol that most USB disks will use, and is used by default. The latter
+option tells Bochs to use the newer 'USB Attached SCSI' protocol, used on newer,
+more modern USB disks. If the 'proto:' parameter is not given, Bochs will default
+to the 'bbb' protocol. See the 'ehci' and 'xhci' examples below.
+
+
+PCI support must be enabled to use USB UHCI.
+
+
+The BBB protocol must have a speed option of 'full', 'high', or 'super'. The UASP
+protocol can only be used on high- and super-speed devices, therefore must only be
+used with the 'usb_ehci' and 'usb_xhci' configuration options. Full-speed devices
+will default to the BBB protocol.
+
+
+Specifying the UASP option does not guarantee the Guest will use this interface.
+The Bochs emulation still gives both options. It is up to the Guest to choose which
+protocol to use. A modern, widely used OS will default to BBB for various EHCI
+controllers, and controllers that are known to have issues with this type of protocol.
+
+
+The USB emulation now checks many items for accuracy. For example, it will monitor the
+toggle bit in a Transfer Descriptor. If it is not correct, the TD will not be executed.
+If your code use to work in a Bochs emulation, but now it does not, check your toggle
+bit implementation. (This particular check can be disabled using the HANDLE_TOGGLE_CONTROL
+define in 'usb_common.h') Other checks for accuracy are checks for the 'value' and 'index'
+fields of a SETUP packet. For example, a particular request may specify that the 'value'
+field must be zero. Bochs now checks for this. Other checks include the Command Length
+field in a SCSI command request, valid values in an xHCI 'slot' and 'endpoint' context,
+as well as other checks.
+
+
+
+usb_ohci
+
+Example:
+
+ usb_ohci: enabled=1, port1=printer:printdata.bin
+
+This option controls the presence of the USB OHCI host controller with a
+2-port hub. The portX parameter accepts the same device types with the same
+syntax as the UHCI controller (see the usb_uhci option).
+The optionsX parameter is also available on OHCI.
+
+
+usb_ehci
+
+Example:
+
+ usb_ehci: enabled=1, port1=tablet, options1="speed:high"
+ usb_ehci: enabled=1, port1=disk, options1="speed:high, path:hdd.img, proto:bbb"
+ usb_ehci: enabled=1, port1=disk, options1="speed:high, path:hdd.img, proto:uasp"
+ usb_ehci: enabled=1, port1=cdrom, options1="speed:high, path:bootcd.iso, proto:bbb"
+ usb_ehci: enabled=1, port1=cdrom, options1="speed:high, path:bootcd.iso, proto:uasp"
+
+This option controls the presence of the USB EHCI host controller with a
+6-port hub. The portX parameter accepts the same device types with the same
+syntax as the UHCI controller (see the usb_uhci option).
+The optionsX parameter is also available on EHCI.
+
+
+usb_xhci
+
+Example:
+
+ usb_xhci: enabled=1, model="uPD720202", n_ports=4
+ usb_xhci: enabled=1, port1="disk:usbdisk.img" # defaults to the BBB protocol
+ usb_xhci: port1=disk, options1="speed:super, path:usbdisk.img, proto:uasp"
+ usb_xhci: port1=disk, options1="speed:super, path:usbdisk.img, proto:bbb"
+ usb_xhci: port1=cdrom, options1="speed:super, path:bootcd.iso, proto:uasp"
+ usb_xhci: port3=disk, options3="speed:high, path:usbdisk.img, proto:uasp"
+ usb_xhci: port3=disk, options3="speed:high, path:usbdisk.img, proto:bbb"
+ usb_xhci: port3=floppy, options3="speed:full, path:floppy.img, model:teac"
+ usb_xhci: port3=tablet, options3="speed:low"
+
+This option controls the presence of the USB xHCI host controller with a default 4-port
+hub. The portX parameter accepts similar device types with a similar syntax as
+the UHCI controller (see the usb_uhci option).
+The optionsX parameter is also available on xHCI.
+
+
+The xHCI supports up to two models, the NEC uPD720202 and the NEC uPD720201. The former
+defaults to a 4-port hub (two physical sockets), while the latter defaults to an 8-port hub
+(four physical sockets). This was added for future expansion. The 'n_ports=n'
+parameter can be given to override the count of ports used. This count must be at least two
+and not more than USB_XHCI_PORTS_MAX (currently 10), and must be
+an even numbered count.
+
+
+No matter the count of ports, the first half (ports 1, 2, 3, and 4 on an 8-port hub) will
+be the USB3 ports (register sets), while the second half (ports 5, 6, 7, and 8) will be the
+USB2 ports (register sets). When the 'optionsX="speed:" option is
+used, it must contain 'super' for the first half ports (1, 2, 3, and 4) and the second half
+(5, 6, 7, and 8) must use a speed of 'low', 'full', or 'high'.
+
+
+On an xHCI, the number of ports used is the number of port register sets, one set for the USB3
+protocol and a paired set for the USB2 protocol. An 'n_ports=' specification of 4 defines
+two physical sockets.
+
+
+
+pcidev
+
+Example:
+
+ pcidev: vendor=0xbabe, device=0x2bad
+
+Enables the mapping of a host PCI hardware device within the virtual PCI
+subsystem of the Bochs x86 emulator. The arguments
+vendor and device
+should contain the PCI vendor ID respectively the PCI
+device ID of the host PCI device you want to map within Bochs.
+
+
+
+The PCI device mapping is still in a very early stage of development and thus it is very experimental.
+This feature requires Linux as a host operating system.
+
+
+
+Besides the pcidev config line you will need to load
+a pcidev kernel module within your Linux host OS. This kernel module is
+located in the bochs/host/linux/pcidev/ directory.
+
+
+
+
+gdbstub
+
+Example:
+
+ gdbstub: enabled=1, port=1234, text_base=0, data_base=0, bss_base=0
+
+Default:
+
+ gdbstub: enabled=0
+
+This enables the GDB stub. See .
+
+
+
+magic_break
+
+Example:
+
+ magic_break: enabled=1
+
+This enables the "magic breakpoint" feature when using the debugger.
+The useless cpu instruction XCHG BX, BX causes Bochs to enter the
+debugger mode. This might be useful for software development.
+
+
+
+debug_symbols
+
+Example:
+
+ debug_symbols: file=mysymbols.sym
+ debug_symbols: file=mysymbols.sym, offset=0x1000
+
+This loads symbols from the specified file for use in Bochs' internal debugger.
+Symbols are loaded into global context. This is equivalent to issuing ldsym
+debugger command at start up.
+
+
+
+port_e9_hack
+
+Example:
+
+ port_e9_hack: enabled=1
+
+The 0xE9 port doesn't exists in normal ISA architecture. However, we
+define a convention here, to display on the console of the system running
+Bochs anything that is written to it. The idea is to provide debug output
+very early when writing BIOS or OS code for example, without having to
+bother with setting up a serial port or etc. Reading from port 0xE9 will
+will return 0xe9 to let you know if the feature is available. Leave
+this 0 unless you have a reason to use it.
+
+
+
+
+
+How to write your own keymap table
+
+Christophe Bothamy wrote the keymapping code for Bochs, and provided this
+documentation for how to create new keymaps. Keymapping was first
+implemented for X windows only, so there are many references to X-specific
+values in this section. In Bochs 2.0 keymapping is also available for SDL
+(Linux port) and wxWidgets (wxGTK port).
+
+
+ The standard US Keyboard looks like this:
+
+ -------------------------------------------
+ Top row Esc F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12
+ -------------------------------------------
+ 2nd row ` 1 2 3 4 5 6 7 8 9 0 - = \ Back
+ -------------------------------------------
+ 3rd row Tab Q W E R T Y U I O P [ ] Enter
+ -------------------------------------------
+ 4rd row Caps A S D F G H J K L ; '
+ -------------------------------------------
+ 5rd row lShift l\ Z X C V B N M , . / rShift
+ -------------------------------------------
+ 6rd row lCtrl lAlt Space rAlt rCtrl
+ -------------------------------------------
+
+
+
+Each key of the US keyboard maps to a Bochs constant named
+BX_KEY_symbol. You can find the current list of
+BX_KEY_symbol in
+the BX_KEY table, below. Please note that
+there is only one BX_KEY_symbol for each physical
+key.
+
+
+
+Now, for each key of the US keyboard, look at which symbols you can type on your
+real keyboard. Each symbol maps to a X-windows
+XK_symbol constant. In
+X11/keysymdef.h, you will find the list of all possible
+XK_symbol on your system. Alternatively, you can
+use a small utility called "xev" that prints out the symbol names of a pressed
+key. Note that the symbol name given by xev does not contain the XK_ prefix.
+Don't forget to add a line for every symbol you can type on each key. For the
+key BX_KEY_A, you can type both lowercase 'a' and uppercase 'A', so you would
+need two different entries.
+
+
+
+You can then create your own map file. Keymap files are found in the
+"gui/keymaps" directory in the source code, or in the "keymaps" directory in
+binary releases. Look at the existing keymap file as an example, and create a
+file containing one line for each symbol. The first column tells what key or
+combination of keys can be used to produce a given symbol. The second column
+is the ASCII equivalent for that symbol, or a special keyword (none, space,
+return, tab, backslash, or apostrophe). The third column is the X windows
+keysym for that symbol.
+
+
+
+
+For example :
+
+BX_KEY_0 '0' XK_0
+BX_KEY_1 '1' XK_1
+BX_KEY_2 '2' XK_2
+BX_KEY_0+BX_KEY_SHIFT_L ')' XK_parenright
+BX_KEY_1+BX_KEY_SHIFT_L '!' XK_exclam
+BX_KEY_2+BX_KEY_SHIFT_L '@' XK_at
+BX_KEY_A 'a' XK_a
+BX_KEY_B 'b' XK_b
+BX_KEY_A+BX_KEY_SHIFT_L 'A' XK_A
+BX_KEY_B+BX_KEY_SHIFT_L 'B' XK_B
+BX_KEY_TAB tab XK_Tab
+BX_KEY_ENTER return XK_Return
+BX_KEY_F1 none XK_F1
+BX_KEY_F2 none XK_F2
+BX_KEY_F3 none XK_F3
+
+
+
+
+Now that there are several keymap files in the Bochs distribution, it is
+easiest to copy an existing keymap and follow the examples you see. When it
+works, be sure to send it to the mailing list or post it on Source Forge so
+that we can include it in the next release. You may need to look up some of
+your country specific X11 symbols in X11/keysymdef.h.
+
+
+
BX_KEY constants
+
+
+
+ BX_KEY constant
+ Keyboard Symbol
+
+
+
+
+BX_KEY_CTRL_L left Ctrl
+BX_KEY_SHIFT_L left Shift
+BX_KEY_F1 F1
+BX_KEY_F2 F2
+BX_KEY_F3 F3
+BX_KEY_F4 F4
+BX_KEY_F5 F5
+BX_KEY_F6 F6
+BX_KEY_F7 F7
+BX_KEY_F8 F8
+BX_KEY_F9 F9
+BX_KEY_F10 F10
+BX_KEY_F11 F11
+BX_KEY_F12 F12
+BX_KEY_CTRL_R right Ctrl
+BX_KEY_SHIFT_R right Shift
+BX_KEY_CAPS_LOCK CapsLock
+BX_KEY_NUM_LOCK NumLock
+BX_KEY_ALT_L left Alt
+BX_KEY_ALT_R right Alt
+BX_KEY_A A
+BX_KEY_B B
+BX_KEY_C C
+BX_KEY_D D
+BX_KEY_E E
+BX_KEY_F F
+BX_KEY_G G
+BX_KEY_H H
+BX_KEY_I I
+BX_KEY_J J
+BX_KEY_K K
+BX_KEY_L L
+BX_KEY_M M
+BX_KEY_N N
+BX_KEY_O O
+BX_KEY_P P
+BX_KEY_Q Q
+BX_KEY_R R
+BX_KEY_S S
+BX_KEY_T T
+BX_KEY_U U
+BX_KEY_V V
+BX_KEY_W W
+BX_KEY_X X
+BX_KEY_Y Y
+BX_KEY_Z Z
+BX_KEY_0 0
+BX_KEY_1 1
+BX_KEY_2 2
+BX_KEY_3 3
+BX_KEY_4 4
+BX_KEY_5 5
+BX_KEY_6 6
+BX_KEY_7 7
+BX_KEY_8 8
+BX_KEY_9 9
+BX_KEY_ESC Esc
+BX_KEY_SPACE SpaceBar
+BX_KEY_SINGLE_QUOTE '
+BX_KEY_COMMA ,
+BX_KEY_PERIOD .
+BX_KEY_SLASH /
+BX_KEY_SEMICOLON ;
+BX_KEY_EQUALS =
+BX_KEY_LEFT_BRACKET [
+BX_KEY_BACKSLASH \
+BX_KEY_RIGHT_BRACKET ]
+BX_KEY_MINUS -
+BX_KEY_GRAVE `
+BX_KEY_BACKSPACE BackSpace
+BX_KEY_ENTER Enter
+BX_KEY_TAB Tab
+BX_KEY_LEFT_BACKSLASH left \
+BX_KEY_PRINT PrintScreen
+BX_KEY_SCRL_LOCK ScrollLock
+BX_KEY_PAUSE Pause
+BX_KEY_INSERT Ins
+BX_KEY_DELETE Del
+BX_KEY_HOME Home
+BX_KEY_END End
+BX_KEY_PAGE_UP PageUo
+BX_KEY_PAGE_DOWN PageDown
+BX_KEY_KP_ADD Numeric Keypad +
+BX_KEY_KP_SUBTRACT Numeric Keypad -
+BX_KEY_KP_END Numeric Keypad 1
+BX_KEY_KP_DOWN Numeric Keypad 2
+BX_KEY_KP_PAGE_DOWN Numeric Keypad 3
+BX_KEY_KP_LEFT Numeric Keypad 4
+BX_KEY_KP_5 Numeric Keypad 5
+BX_KEY_KP_RIGHT Numeric Keypad 6
+BX_KEY_KP_HOME Numeric Keypad 7
+BX_KEY_KP_UP Numeric Keypad 8
+BX_KEY_KP_PAGE_UP Numeric Keypad 9
+BX_KEY_KP_INSERT Numeric Keypad 0
+BX_KEY_KP_DELETE Numeric Keypad .
+BX_KEY_KP_ENTER Numeric Keypad Enter
+BX_KEY_KP_MULTIPLY Numeric Keypad *
+BX_KEY_KP_DIVIDE Numeric Keypad /
+BX_KEY_UP UpArrow
+BX_KEY_DOWN DownArrow
+BX_KEY_LEFT LeftArrow
+BX_KEY_RIGHT RightArrow
+BX_KEY_WIN_L Left Windows
+BX_KEY_WIN_R Right Windows
+BX_KEY_MENU Menu
+BX_KEY_ALT_SYSREQ Alt-Sysreq
+BX_KEY_CTRL_BREAK Ctrl-Break
+BX_KEY_INT_BACK Internet - back
+BX_KEY_INT_FORWARD Internet - forward
+BX_KEY_INT_STOP Internet - stop
+BX_KEY_INT_MAIL Internet - mail
+BX_KEY_INT_SEARCH Internet - search
+BX_KEY_INT_FAVInternet - favorites
+BX_KEY_INT_HOME Internet - home
+BX_KEY_POWER_MYCOMP Powerkeys - my computer
+BX_KEY_POWER_CALC Powerkeys - calculator
+BX_KEY_POWER_SLEEP Powerkeys - sleep
+BX_KEY_POWER_POWER Powerkeys - power
+BX_KEY_POWER_WAKE Powerkeys - wake
+
+
+
+
+
+
+
+
+Using Bochs
+
+After starting Bochs either from the command prompt or the OS shell, the following
+steps are done before the simulation is running.
+
+parse command line (except bochsrc options)
+load selected config file (bochsrc) or search for the default one
+parse remaining command line options (bochsrc syntax)
+initialize configuration interface
+enter start menu / dialog (unless quick start mode is enabled)
+initialize all parts of the simulator
+enter debugger prompt / dialog (if present)
+enter the simulation loop
+
+
+
+During simulation, Bochs usually generates more or less log output. By default, it
+is sent to the console, otherwise to the specified log file.
+The amount of output can be controlled with the log options
+in bochsrc, the start menu and the runtime configuration.
+
+
+Under certain conditions Bochs can cause a panic
+and usually asks the user what to do. If such a panic happens during startup, it is
+mostly a configuration or permission problem and we recommend to quit Bochs and to
+review the bochsrc options used.
+
+
+To quit the simulation, the "power" button in the Bochs headerbar
+should be used, unless the guest OS has the capability to turn off the computer (APM or ACPI).
+
+
+If a Bochs runtime issue cannot be fixed by configuration changes and it has not yet
+been reported in the &devlist; or the SF trackers for Bochs, it should be reported in
+the mailing list or the SF bug tracker for the Bochs project.
+
+
+Command line arguments
+
+The following table shows the arguments that can be used on the command line.
+For other arguments, see section bochsrc.
+
+command line arguments
+
+
+
+Argument
+Description
+
+
+
+
+ -q
+ quick start (skip configuration interface)
+
+
+ -f filename
+ specify configuration file
+
+
+ -log filename
+ specify Bochs log file
+
+
+ -dbglog filename
+ specify Bochs internal debugger log file
+
+
+ -n
+ don't try to load a configuration file
+
+
+ -benchmark N
+ run Bochs in benchmark mode for N millions of emulated ticks
+
+
+ -dumpstats N
+ dump Bochs stats every N millions of emulated ticks
+
+
+ -r path
+ specify path for restoring state
+
+
+ -unlock
+ unlock Bochs images leftover from previous session
+
+
+ -noconsole
+ disable console window (Windows only)
+
+
+ --help
+ display help message and exit
+
+
+ --help features
+ display available features / devices and exit
+
+
+ --help cpu
+ display supported CPU models and exit (CPU level > 4 only)
+
+
+
+
+
+
+These arguments are handled directly after starting Bochs. The next step is to load
+a default or specified configuration file (unless disabled with -n). Then the rest
+of the command line (bochsrc options) is parsed. This is done after reading the
+configuration file so that the command line arguments can override the settings
+from the file.
+
+
+
+Search order for the configuration file
+
+If no configuration file is specified on the command line and config file loading
+is not disabled, Bochs searches for a default configuration file. This is the search order:
+
+
+
+.bochsrc in the current directory
+
+
+
+
+bochsrc in the current directory
+
+
+
+
+bochsrc.txt in the current directory
+
+
+
+
+(win32 only) bochsrc.bxrc in the current directory
+
+
+
+
+(Unix only) .bochsrc in the user's home directory
+
+
+
+
+(Unix only) bochsrc in the /etc directory
+
+
+
+
+
+The configuration interface 'textconfig'
+
+The configuration interface 'textconfig' is the text mode version of the Bochs
+configuration system. It is a series of menus (using stdin/stdout) that allows
+you to edit all the settings that control Bochs' behavior. If you do not write
+a config_interface line, Bochs will choose it as the default for you (unless Bochs
+is compiled for Win32 or wxWidgets only). If the GUI console is available at
+runtime, textconfig switches the display to text mode 80 x 25 and restores the
+simulation screen afterwards.
+
+
+It consists of these three parts:
+
+the start menu
+the headerbar buttons
+the runtime configuration
+
+
+
+On Win32 (without wxWidgets) the default configuration interface 'win32config' is
+very similar, but it presents GUI dialogs instead of text menus.
+
+The start menu
+
+If you start Bochs without the quickstart argument (-q), the Bochs configuration
+main menu appears:
+
+------------------------------
+Bochs Configuration: Main Menu
+------------------------------
+
+This is the Bochs Configuration Interface, where you can describe the
+machine that you want to simulate. Bochs has already searched for a
+configuration file (typically called bochsrc.txt) and loaded it if it
+could be found. When you are satisfied with the configuration, go
+ahead and start the simulation.
+
+You can also start Bochs with the -q option to skip these menus.
+
+1. Restore factory default configuration
+2. Read options from...
+3. Edit options
+4. Save options to...
+5. Restore the Bochs state from...
+6. Begin simulation
+7. Quit now
+
+Please choose one: [5]
+
+
+
+Here you can load, edit and save the configuration and finally start the simulation.
+It is possible to start Bochs without a config file and to edit all the settings using
+the item "Edit options". Don't forget to save the configuration if you want to use this
+setup for another Bochs session.
+
+
+
+The Bochs headerbar
+
+
+
+
+The headerbar appears on top of the Bochs simulation window. Here you can control the
+behavoiur of Bochs at runtime if you click on one of these buttons:
+
+
+floppy buttons
+
+ Here you can toggle the status of the floppy media (inserted/ejected). Bochs for
+ win32 presents you a small dialog box for changing the floppy image. You can
+ setup floppy drives using floppya/floppyb option.
+
+
+
+CD-ROM button
+
+ Here you can toggle the media status of the first CD-ROM drive (inserted/ejected).
+ CD-ROM drives can be set up using ata(0-3)-master/-slave option.
+ On some platforms this button brings a up a small dialog box for changing the
+ CD-ROM image.
+
+
+
+mouse button
+
+ Here you can enable the creation of mouse events by the host. Once mouse
+ events are captured, you cannot reach the button anymore, in order to disable
+ capturing again. By default, you can enable and disable the mouse capture pressing
+ the CTRL key and the third (middle) mouse button. See the mouse option
+ parameter 'toggle' for other methods to toggle the mouse capture.
+
+
+ Changing the mouse capture at runtime is not supported by all display libraries,
+ but it is already present on RFB, SDL, SDL2, VNCSRV, Win32, wxWidgets and X11.
+
+
+ Support for 2 button mouse to toggle the capture mode not yet complete - using
+ another toggle method is recommended in that case.
+
+
+
+user button
+
+ Press this button if you want to send the keyboard shortcut defined with the
+ user_shortcut parameter of the keyboard
+ option to the guest. Depending on the used display_library option,
+ it may even be possible to edit the shortcut before sending it.
+
+
+
+copy button
+The text mode screen text can be exported to the clipboard after pressing this
+button. The button has no effect in graphics mode.
+
+
+paste button
+Text in the clipboard can also be pasted, through Bochs, to the
+guest OS, as simulated keystrokes. Keyboard mapping must be enabled to make this
+feature work.
+
+
+snapshot button
+Press this button if you want to save a snapshot of the Bochs screen. All
+text and graphics modes are now supported. If GUI dialogs are supported (e.g. on
+win32) Bochs presents you a "Save as..." dialog box to specify the filename. In
+text modes the formats BMP and TXT are supported depending on file extension.
+Platforms without GUI dialogs are using the fixed filenames "snapshot.txt" or
+"snapshot.bmp".
+
+
+config button
+This button stops the Bochs simulation and starts the runtime configuration.
+(see below).
+
+
+reset button
+Press this button to trigger a hardware reset.
+
+
+suspend button
+Press this button to save current simulation state to a disk. The simulation
+could be restored back using bochs -r command. For more details read the
+Save and restore simulation section.
+
+
+power button
+This button stops the simulation and quits Bochs.
+
+
+
+
+Some of these features may not be implemented or work different on your host platform.
+
+
+
+Command mode
+
+When using 'sdl', 'sdl2', 'win32' or 'x' as the display_library, the
+option 'cmdmode' enables the "command mode" support. If enabled, pressing the F7
+key will enter 'command mode' (shown in the info item of the statusbar);
+the next key that is pressed will exit command-mode. When in command-mode,
+if the pressed key is in the list below, the corresponding action will be
+performed. With the exception of F7, any key pressed while in command-mode
+will not be received by the OS running in Bochs.
+
+
+
Supported keys
+
+
+
+ Key
+ Action
+
+
+
+
+ a
+ Press the Floppy A button
+
+
+ b
+ Press the Floppy B button
+
+
+ c
+ Press the Copy button
+
+
+ SHIFT + c
+ Press the Config button
+
+
+ f
+ Toggle windowed / fullscreen mode (sdl, sdl2 and win32 only)
+
+
+ p
+ Press the Paste button
+
+
+ SHIFT + p
+ Press the Power button
+
+
+ r
+ Press the Reset button
+
+
+ s
+ Press the Snapshot button
+
+
+ SHIFT + s
+ Press the Suspend button
+
+
+ u
+ Press the User button
+
+
+ F7
+ Send F7 keypress to emulation
+
+
+
+
+
+
+In fullscreen mode (sdl, sdl2, win32) some handlers do not bring up a dialog
+box. The floppy buttons just toggle the status, the snapshot feature uses the
+hardcoded file name and the user button sends the configured shortcut.
+
+
+The runtime configuration
+
+If you want to change certain settings at runtime, you have to press the "config" button in
+the headerbar. The simulation stops and the runtime menu appears on the console window / xterm
+or the Bochs GUI console (if available).
+
+---------------------
+Bochs Runtime Options
+---------------------
+1. Floppy disk 0: /dev/fd0, size=1.44M, inserted
+2. Floppy disk 1: floppyb.img, size=1.44M, inserted
+3. 1st CD-ROM: (master on ata1) /dev/cdrom, ejected
+4. 2nd CD-ROM: (slave on ata1) /dev/cdrecorder, ejected
+5. 3rd CD-ROM: (not present)
+6. 4th CD-ROM: (not present)
+7. (not implemented)
+8. Log options for all devices
+9. Log options for individual devices
+10. Instruction tracing: off (doesn't exist yet)
+11. USB runtime options
+12. Misc runtime options
+13. Continue simulation
+14. Quit now
+
+Please choose one: [13]
+
+
+
+In the runtime configuration you can change the floppy/CD-ROM image or device,
+change the log options or adjust some other settings. If you have trouble with
+a specific device, you can change the log options for this device only to get
+more information (e.g. report debug messages).
+
+
+
+
+Pre-defined CPU models
+
+If Bochs is compiled with cpu level 5 or higher the CPUID opcode is supported
+and it can return some information about the cpu model and its features. When
+using a pre-defined CPU model in Bochs the features reported by CPUID are set up
+according to the model's specification. The following table shows all available
+CPU models with a short description. The amount of choices depends on the CPU
+features enabled at compile time (3rd column).
+
+
Bochs CPU models
+
+
+
+ Value
+ Description
+ Required Features
+
+
+
+
+ bx_generic
+ Default Bochs CPU configured with CPUID option
+ cpu level 5
+
+
+ pentium
+ Intel Pentium (P54C)
+ cpu level 5
+
+
+ pentium_mmx
+ Intel Pentium MMX
+ cpu level 5
+
+
+ amd_k6_2_chomper
+ AMD-K6(tm) 3D processor (Chomper)
+ cpu level 5
+
+
+ p2_klamath
+ Intel Pentium II (Klamath)
+ cpu level 6
+
+
+ p3_katmai
+ Intel Pentium III (Katmai)
+ cpu level 6
+
+
+ p4_willamette
+ Intel(R) Pentium(R) 4 (Willamette)
+ cpu level 6
+
+
+ core_duo_t2400_yonah
+ Intel(R) Core(TM) Duo CPU T2400 (Yonah)
+ cpu level 6
+
+
+ atom_n270
+ Intel(R) Atom(TM) CPU N270
+ cpu level 6
+
+
+ p4_prescott_celeron_336
+ Intel(R) Celeron(R) 336 (Prescott)
+ cpu level 6, x86-64
+
+
+ athlon64_clawhammer
+ AMD Athlon(tm) 64 Processor 2800+ (Clawhammer)
+ cpu level 6, x86-64
+
+
+ athlon64_venice
+ AMD Athlon(tm) 64 Processor 3000+ (Venice)
+ cpu level 6, x86-64
+
+
+ turion64_tyler
+ AMD Turion(tm) 64 X2 Mobile TL-60 (Tyler)
+ cpu level 6, x86-64
+
+
+ phenom_8650_toliman
+ AMD Phenom X3 8650 (Toliman)
+ cpu level 6, x86-64
+
+
+ core2_penryn_t9600
+ Intel Mobile Core 2 Duo T9600 (Penryn)
+ cpu level 6, x86-64
+
+
+ corei5_lynnfield_750
+ Intel(R) Core(TM) i5 750 (Lynnfield)
+ cpu level 6, x86-64
+
+
+ corei5_arrandale_m520
+ Intel(R) Core(TM) i5 M 520 (Arrandale)
+ cpu level 6, x86-64
+
+
+ corei7_sandy_bridge_2600k
+ Intel(R) Core(TM) i7-2600K (Sandy Bridge)
+ cpu level 6, x86-64, avx
+
+
+ zambezi
+ AMD FX(tm)-4100 Quad-Core Processor (Zambezi)
+ cpu level 6, x86-64, avx
+
+
+ trinity_apu
+ AMD A8-5600K APU (Trinity)
+ cpu level 6, x86-64, avx
+
+
+ ryzen
+ AMD Ryzen 7 1700
+ cpu level 6, x86-64, avx
+
+
+ corei7_ivy_bridge_3770k
+ Intel(R) Core(TM) i7-3770K CPU (Ivy Bridge)
+ cpu level 6, x86-64, avx
+
+
+ corei7_haswell_4770
+ Intel(R) Core(TM) i7-4770 CPU (Haswell)
+ cpu level 6, x86-64, avx
+
+
+ broadwell_ult
+ Intel(R) Processor 5Y70 CPU (Broadwell)
+ cpu level 6, x86-64, avx
+
+
+ corei7_skylake_x
+ Intel(R) Core(TM) i7-7800X CPU (Skylake)
+ cpu level 6, x86-64, avx
+
+
+ corei3_cnl
+ Intel(R) Core(TM) i3-8121U CPU (Cannonlake)
+ cpu level 6, x86-64, avx
+
+
+ corei7_icelake_u
+ QuadCore Intel Core i7-1065G7 (IceLake)
+ cpu level 6, x86-64, avx
+
+
+ tigerlake
+ 11th Gen Intel(R) Core(TM) i5-1135G7 (TigerLake)
+ cpu level 6, x86-64, avx
+
+
+
+
+
+
+Save and restore simulation
+
+Bochs has now full save/restore support. The state of cpu(s), memory, devices and
+hard drive images
+
+The disk image mode "vvfat" does not support save/restore. All other disk image modes
+copy the whole image or the file containing changes (journal). This may take some time,
+so be patient when using this feature.
+
+can be saved. When running Bochs there will be a button in the
+header bar called "Suspend". Depending on config interface and GUI there will be a
+prompt where you can enter a path to an existing directory or a GUI folder selection
+dialog box. It is possible to save the state at any time, but we recommend to do it
+when the simulation is idle. After pressing OK/Enter, Bochs will save a set of files
+into the selected folder. It is possible to continue after saving the state, but when
+using the restore function in a new Bochs session, all changes after this checkpoint
+will be lost.
+
+
+To restore the saved simulation state, you can select the restore function in the
+text mode start menu or specify the restore path at the command line:
+
+bochs -r /path/to/save-restore-data
+
+
+
+Then Bochs will start up using the saved configuration and log options, restores
+the state of the hardware and begins the simulation. In the restore mode Bochs
+will ignore bochsrc options from the command line and does not load a normal
+config file.
+
+
+
+Using sound
+Sound basics
+
+Bochs supports two types of soundcards (SB16 ISA and ES1370 PCI) and the legacy
+PC speaker. The lowlevel sound interface provides a set of functions for wave
+(PCM) input / output and MIDI output using the host sound system. A driver must
+not implement all of these functions. The following table shows the supported
+drivers and their features.
+
Sound lowlevel modules
+
+
+
+ Name
+ Description
+ Wave input
+ MIDI output
+
+
+
+
+ alsa
+ use the default ALSA PCM device and the default ALSA sequencer
+ on Linux
+ Yes
+ Yes
+
+
+ oss
+ use the Open Sound System on Linux and FreeBSD
+ Yes
+ Yes
+
+
+ osx
+ for output on Mac OS 9 and Mac OSX
+ No
+ Yes
+
+
+ sdl
+ for wave output on platforms supported by SDL (1.2.x or 2.x)
+ No
+ No
+
+
+ win
+ for output to the midi and wave mapper of Windows
+ Yes
+ Yes
+
+
+
+
+
+
+These special values are also valid for the sound driver:
+
+ - select platform-default sound driver.
+ - wave and MIDI output to file(s)
+ - no output at all
+
+
+
+When compiling Bochs, the lowlevel sound support is activated if one of the soundcards
+is enabled ( or ).
+The configure script detects the available drivers and sets up a platform-default
+one.
+
+
+At runtime the lowlevel sound module will be loaded automatically if one of the
+sound devices are enabled in the bochsrc file. The drivers and
+devices for wave input / output and MIDI output must be set up with the
+sound option.
+
+
+The PC speaker
+
+The PC speaker is connected to the PIT 8254 timer #2 and generates a square
+wave beep with a frequency depending on the timer value. In Bochs the
+speaker is a separate plugin that is controlled by the two events "beep on"
+and "beep off". The "beep on" event is also called when the frequency
+changes while turned on.
+
+
+The destination for the speaker output can be selected with the
+parameter of the speaker option. Three choices are available:
+
+ : the beep is generated by the square wave
+generator which is a part of the lowlevel sound support.
+ : only available on Linux and Windows.
+On Linux /dev/console is used for output and on Windows the Beep() function.
+ : forwards the beep to the related GUI methods
+(currently only used by the Carbon GUI).
+
+
+
+SB16 runtime configuration
+
+Most of the SB16 configuration parameters are available in the runtime
+configuration menu or dialog. In addition to this, there is a small program
+called SB16CTRL to change emulation settings from inside
+the simulation.
+
+Runtime options
+
+Unlike other devices, the SB16 emulation has its own logfile and a loglevel parameter
+to control what should be printed there. Both the file and
+ parameters can be changed at runtime. See the
+sb16 bochsrc option for details.
+
+
+The output parameters , ,
+ and are also available at
+runtime.
+
+
+The parameter controls the DMA timing for wave (PCM)
+input and output. When you get non-continuous sound, this value can be ajusted
+to fix this. This needs a reasonably correct setting for the
+cpu: ips option.
+
+
+SB16CTRL
+
+
+The source for the SB16CTRL program that is used to modify
+the runtime behavior of the SB16 emulation is included in
+misc/sb16/. It is a C
+program that can be run from inside the emulation.
+
+
+
+It currently supports the following commands:
+
+
+
Supported options for <command>sb16ctrl</command>
+
+
+
+ Option
+ Description
+
+
+
+
+
+
+ Show the selected emulator info string,
+ e.g. sb16ctrl -i 3 to show how many patch translations are active.
+
+
+
+
+
+ Load a translation into the translation table. The numbers are:
+ "OldBankMSB,OldBankLSB,OldProgram,NewBankMSB,NewBankLSB,NewProgram".
+ All values can be 0..127 or 255. 255 for "Old" values means match
+ any and for "New" values means don't change,
+ e.g. sb16ctrl -t 255,255,0,255,255,32
+ to change patch 0 (Piano) to patch 32 (Acoustic Bass).
+
+
+
+
+
+ Reset the patch translation table e.g. sb16ctrl -r.
+
+
+
+
+
+ Upload the given numbers to the midi output device. Note
+ that it should be a complete midi message, and also that it is
+ subject to patch translation,
+ e.g. sb16ctrl -m 0x80,64,0
+ to send a note-off message to channel 0.
+
+
+
+
+
+ Read in a file and execute the commands in it. These have
+ the same format as the above commands, except that they don't have
+ the dash "-" in front of them.
+ Comment lines are supported and start with a hash sign "#".
+
+
+
+
+
+ Show a brief summary of the commands.
+
+
+
+
+
+
+
+All numbers can be valid parameters to the strtol() function, so hex and
+octal notation is fine. They have to be delimited by either commas "," or
+slashes "/", spaces are not allowed.
+
+
+
+The command line can have any number of commands. However, if none are given,
+"-f -" is assumed, which means commands are taken from stdin.
+
+
+
+
+
+USB configuration
+
+The USB configuration allows you to add, delete, or modify an existing USB device.
+
+
+The 'device' field may contain one of the following items:
+
+Mouse
+
+This emulates a 3-button mouse. After a reset, it is set up to send the Report
+Protocol report and consists of a 4-byte report:
+
+byte 0: 00000BBB Bits 7:3 are zero
+ Bit 2 is button 3
+ Bit 1 is button 2
+ Bit 0 is button 1
+byte 1: XXXXXXXX 8-bit X Displacement (-127 -> 127)
+byte 2: YYYYYYYY 8-bit Y Displacement (-127 -> 127)
+byte 3: ZZZZZZZZ 8-bit Z Displacement (-127 -> 127)
+
+This device may be used on all Host Controller types using a speed of 'low', 'full',
+or 'high'.
+
+usb_uhci: enabled=1, port1=mouse, options1="speed:low"
+usb_ohci: enabled=1, port1=mouse, options1="speed:full"
+usb_ehci: enabled=1, port1=mouse, options1="speed:high"
+usb_xhci: enabled=3, port3=mouse, options1="speed:full"
+
+
+Please note that most physical USB mice will be 'low-speed' only.
+
+
+
+
+Keyboard
+
+This emulates a standard keyboard. Key press and release codes are translated from
+the Host's keyboard to the Guest as USB Interrupt packets.
+
+
+This device may be used on all Host Controller types using a speed of 'low', 'full',
+or 'high'.
+
+usb_uhci: enabled=1, port1=keyboard, options1="speed:low"
+usb_ohci: enabled=1, port1=keyboard, options1="speed:full"
+usb_ehci: enabled=1, port1=keyboard, options1="speed:high"
+usb_xhci: enabled=3, port3=keyboard, options1="speed:full"
+
+
+Please note that most physical USB keyboards will be 'low-speed' only.
+
+
+
+
+Keypad
+
+This emulates a numeric keypad. Key press and release codes are translated from
+the Host's keyboard to the Guest as USB Interrupt packets.
+
+
+This device may be used on all Host Controller types using a speed of 'low', 'full',
+or 'high'.
+
+usb_uhci: enabled=1, port1=keypad, options1="speed:low"
+usb_ohci: enabled=1, port1=keypad, options1="speed:full"
+usb_ehci: enabled=1, port1=keypad, options1="speed:high"
+usb_xhci: enabled=3, port3=keypad, options1="speed:full"
+
+
+Please note that most physical USB keypads will be 'low-speed' only.
+
+
+
+
+Tablet
+
+This emulates a 3-button mouse. After a reset, it is set up to send the Report
+Protocol report and consists of a 6-byte report:
+
+byte 0: 00000BBB Bits 7:3 are zero
+ Bit 2 is button 3
+ Bit 1 is button 2
+ Bit 0 is button 1
+byte 1: XXXXXXXX 8-bit X Displacement (low byte)
+byte 2: XXXXXXXX 8-bit X Displacement (high byte)
+byte 3: YYYYYYYY 8-bit Y Displacement (low byte)
+byte 4: YYYYYYYY 8-bit Y Displacement (high byte)
+byte 5: ZZZZZZZZ 8-bit Z Displacement
+
+This device may be used on all Host Controller types using a speed of 'low', 'full',
+or 'high'.
+
+usb_uhci: enabled=1, port1=tablet, options1="speed:low"
+usb_ohci: enabled=1, port1=tablet, options1="speed:full"
+usb_ehci: enabled=1, port1=tablet, options1="speed:high"
+usb_xhci: enabled=3, port3=tablet, options1="speed:full"
+
+
+Please note that most physical USB tablets will be 'low-speed' only.
+
+
+
+
+Disk/CD-ROM
+
+This emulates a media device in the form of a hard-drive or CD-ROM. By default,
+the emulation uses the "Bulk-only" transport, also known as "Bulk/Bulk/Bulk". For
+high- and super-speed devices, you can specify the "UASP" protocol, also known as
+"USB Attached SCSI Protocol".
+
+
+This device may be used on all Host Controller types using a speed of 'full', 'high',
+or 'super'.
+
+usb_uhci: enabled=1, port1=disk, options1="speed:full, path:hdd.img" # defaults to the BBB protocol
+usb_ohci: enabled=1, port1=disk, options1="speed:full, path:hdd.img"
+usb_ehci: enabled=1, port1=disk, options1="speed:high, path:hdd.img"
+usb_ehci: enabled=1, port1=disk, options1="speed:high, path:hdd.img, proto:bbb"
+usb_ehci: enabled=1, port1=disk, options1="speed:high, path:hdd.img, proto:uasp"
+usb_xhci: enabled=3, port1=disk, options3="speed:full, path:hdd.img"
+usb_xhci: enabled=3, port1=disk, options3="speed:high, path:hdd.img, proto:bbb"
+usb_xhci: enabled=3, port1=disk, options3="speed:high, path:hdd.img, proto:uasp"
+usb_xhci: enabled=1, port1=disk, options1="speed:super, path:hdd.img, proto:bbb"
+usb_xhci: enabled=1, port1=disk, options1="speed:super, path:hdd.img, proto:uasp"
+
+An image format, similar to the ATA option, can be used. Replace 'mode' below with
+the desired format.
+
+usb_xhci: enabled=3, port1=disk, options3="speed:high, path:mode:hdd.img, proto:bbb"
+usb_xhci: enabled=3, port1=disk, options3="speed:high, path:mode:hdd.img, proto:uasp"
+
+To emuate a CD-ROM, replace 'disk' in the examples above with 'cdrom', and adjust
+the 'path' accordingly.
+
+Specifying 'proto:uasp' does not guarantee that the Guest will use that protocol.
+See a previous section for more information.
+
+
+Please note that this device is not allowed as a low-speed only device. Low-speed should be specified.
+
+
+
+
+Floppy
+
+This emulates a media device in the form of an external Floppy drive. By default,
+the emulation uses the "Control/Bulk/Interrupt" transport, aka "CBI". Bochs can be
+re-compiled to use the "Control/Bulk" transport, aka "CB".
+
+
+This device may be used on all Host Controller types using a speed of 'full'.
+
+usb_uhci: enabled=1, port1=floppy, options1="speed:full, path:floppy.img"
+usb_ohci: enabled=1, port1=floppy, options1="speed:full, path:floppy.img, model:teac"
+usb_ehci: enabled=1, port1=floppy, options1="speed:full, path:floppy.img, model:teac"
+usb_xhci: enabled=1, port3=floppy, options3="speed:full, path:floppy.img"
+
+An image format, similar to the ATA option, can be used. Replace 'mode' below with
+the desired format.
+
+usb_uhci: enabled=1, port1=floppy, options1="speed:full, path:mode:floppy.img"
+
+The 'model:teac' option can be used to emulate that specific model, else a default
+model will be used. If a guest does not see the attached floppy, try specifying the 'teac'
+model.
+
+Please note that this device is a full-speed only device. No other speed should be specified.
+
+
+
+
+Printer
+
+This emulates a simple USB printer. All data sent to the printer will be appended
+to a specified file on the Host.
+
+
+This device may be used on all Host Controller types using a speed of 'full'.
+
+usb_uhci: enabled=1, port1=printer, options1="speed:full, file:printdata.bin"
+usb_ohci: enabled=1, port1=printer, options1="speed:full, file:printdata.bin"
+usb_ehci: enabled=1, port1=printer, options1="speed:full, file:printdata.bin"
+usb_xhci: enabled=1, port3=printer, options3="speed:full, file:printdata.bin"
+
+
+Please note that this device is a full-speed only device. No other speed should be specified.
+
+
+
+
+Hub
+
+This emulates a full-speed 4-port external hub. The number of ports can be
+changed, with a range of 2 to 8.
+
+
+This device may be used on all Host Controller types using a speed of 'full'.
+
+usb_uhci: enabled=1, port1=hub, options1="speed:full"
+usb_ohci: enabled=1, port1=hub, options1="speed:full, ports:4"
+usb_ehci: enabled=1, port1=hub, options1="speed:full, ports:6"
+usb_xhci: enabled=1, port1=hub, options1="speed:full, ports:8"
+
+At startup, no device is attached to this hub. However, after start up, using the
+runtime interface, a device can be attached to any or all of the ports.
+
+
+Any device attached to this hub (via the runtime interface), must be the same as or less than the hub's current speed (which is currently only full-speed). Any device plugged into a hub, no matter its max speed, can only function at or below the speed of the hub it is attached to.
+
+
+Please note that this device is a full-speed only device. No other speed should be specified.
+
+
+
+Packet Capture
+
+All devices may use the 'pcap' option to send all data to a Packet Capture formatted
+file.
+
+usb_uhci: enabled=1, port1=hub, options1="speed:full, pcap:outfile.pcap"
+
+This file is formatted to be used with Linux' usbmon and utilities such as
+Wire Shark.
+
+
+Please note that this option will not capture any data that would normally
+flow through an external hub, so if you use the 'pcap' option for a hub,
+as with the example above, only the hub's data is captured, not the device(s) attached
+to it.
+
+
+
+Signaling an Over-Current event
+
+During emulation, using the runtime configuration, you can signal an over-current
+event on any device using the 'over-current' checkbox (GUI) or text configuration
+option. This will signal an over-current event on the Host Controller for that
+port.
+
+
+Over-current is considered undefined on the UHCI, though Intel 430TX and later
+controllers may have implemented over-current via two previously unused bits.
+
+
+
+Notes
+
+
+
+All devices allow the 'debug' option to be used. This turns on the BX_DEBUG() logging
+for that device.
+
+usb_uhci: enabled=1, port1=hub, options1="speed:full, debug"
+
+
+
+
+
+You can wrap options in double-quotes in your bochsrc file. However, the runtime config
+interface has problems when double-quotes are used. Therefore, don't use them in the
+runtime configuration interface.
+
+
+
+
+
+
+
+
+
+ Common problems and what to do about them (Troubleshooting)
+
+ Bochs panics! What can I do?
+
+ Bochs does a very good job in emulating an x86 compatible computer, however,
+ it does not (yet) include a full (100%) emulation of every possible instruction,
+ (BIOS) function call or (hardware) device. Thus, in case something unusual
+ happens, either a not-so-common call to some (BIOS) function or device by
+ some software running inside of it, Bochs has two possibilities to react:
+ If the command doesn't look important (mainly happens only to non-implemented
+ functions in the BIOS), a notice is logged to the log file
+ and the emulation continues. If, however, the command looks important, Bochs
+ panics, because the software being emulated might depend on the successful
+ execution of the given instruction or behavior of the device.
+
+
+ A panic does not always mean that the software won't run inside of Bochs,
+ as the software might just be probing the computer for the presence of some
+ instruction/device, and in case it is not found, it simply won't be used at
+ all, by the software.
+
+
+ You can tell Bochs what to do in case of a panic, by re-configuring the
+ panic option. If
+ you change the action to "ask", Bochs reports what has happened and asks
+ you what to do. The appearance of the "ask" feature depends on the display
+ library used and the platform. Some display libraries don't support it at all.
+
+
+ Some of the device names reported in the panic message are abbreviations,
+ since the length of the 'prefix' is limited to 6 characters. The
+ log function module table may help
+ you finding out the name of the device that caused the panic. It also gives
+ you a short description of the module.
+
+
+
+
+ Mouse behavior, enabling and disabling
+
+ Refer to for information on how to enable or
+ disable the mouse inside of Bochs at run-time.
+
+
+ The mouse cursor movement speed mostly doesn't match the real movement. This
+ is caused by the variable emulation speed (from the user's point of view)
+ and the relative mouse position data that standard PS/2, serial or USB mice
+ are generating. The alternative is the USB tablet emulation that generates
+ absolute mouse position data. We recommend to use it with the display
+ libraries 'rfb' and 'vncsrv'.
+
+
+
+
+ Text-mode is broken in some ancient DOS program
+
+
+ If you are using a program written for DOS which seems to use the text-mode but
+ doesn't display the text properly, you can try the other VGA BIOS, either
+ VGABIOS-lgpl-latest or VGABIOS-elpin-2.40,
+ see the vgaromimage option.
+
+
+
+ &NEEDHELP; Maybe it is a bug in the LGPL VGA BIOS, but for now, it seems to work.
+
+
+
+
+
+Feedback and Support
+
+The Bochs project on SourceForge
+
+The Bochs project page
+on SourceForge provides these features:
+
+
+Project summary page with screenshots and download statistics
+
+
+Download area for Bochs release packages and disk images
+
+
+Mailing list archives
+
+
+Source code browser
+
+
+Tickets section (bug reports, patches, feature requests etc.)
+
+
+Discussion boards (e.g. "Help" and "Open Discussion")
+
+
+Project news page (used for release announcements)
+
+
+
+
+SourceForge tickets section (bug and patch trackers)
+
+There are some requirements when submitting bug reports, patches, and feature
+requests for Bochs to make it easier to reproduce bugs and test patches.
+
+Reporting errors from Bochs compilation
+
+When reporting errors while building Bochs to the &devlist; or the SF bug
+tracker for the Bochs project, this information is required to fix the issue:
+
+ host platorm / build environment
+ Bochs release version or SVN revision
+ configure options used
+ full error message
+ config.log output if configure failure
+ source file name and line number if compile error
+
+
+
+Before reporting us the issue, make sure that a similar one hasn't been already
+reported or someone created a patch to fix it. If you are familiar with C++
+and you can write some code to fix your problem, you can post it in the &devlist;
+or submit the patch in SF patch tracker for Bochs.
+
+
+Reporting Bochs runtime issues
+
+If Bochs does not work properly (e.g. panic, segfault, malfunction of emulated device)
+we need some information to find out what's going on:
+
+ Bochs version used (version number if binary release / SVN revision
+ if self-compiled)
+ host platorm / build environment (if self-compiled)
+ bochsrc options used
+ error message (if panic or program termination)
+ log file output (related section only if too big)
+
+
+
+Submitting a patch for Bochs
+
+Patches for Bochs should be provided in the "unified diff" format. In addition
+to the patch file and a detailed description this information is required:
+
+ patch applies to Bochs release version / SVN revision
+ test case (if required)
+
+
+
+When you are are interested in writing a patch to fix bugs or add new features,
+you should have a look at the developer documentation.
+For some parts of the Bochs code we have already written some basic information.
+
+
+
+
+
+Mailing Lists
+
+The Bochs community uses three mailing lists to communicate, called
+bochs-developers, bochs-cvs and bochs-announce.
+
+
+bochs-developers mailing list
+
+Bochs-developers is the forum for all Bochs discussions and questions. On
+average, subscribers get between five and ten messages per day. There are
+about 350 subscribers. If this sounds like too much email, maybe the bochs-announce list is more appropriate for
+you. Anyone may join the list, unless they abuse it of course.
+
+
+To subscribe, go to the Bochs-Developers Info Page and type your email
+address and a password into the web form and click
+Subscribe. In a few minutes you will get a confirmation
+email. Follow the directions in the email to complete the subscription
+process. To unsubscribe, go to the same
+page and type your email address in the blank at the bottom and click
+on Edit Options. Then type your password and click
+Unsubscribe.
+
+
+Once you have subscribed, you can write to
+bochs-developers@lists.sourceforge.net to send a message to
+everyone on the list. While it's possible to post without being a subscriber,
+it's not recommended. If you aren't a subscriber, you might miss the response
+to your question.
+
+
+Archive of bochs-developers messages
+
+
+
+bochs-announce mailing list
+
+Bochs-announce is a moderated, low-traffic list which carries only periodic
+announcements of Bochs releases and important events. If you have a very
+important and truly relevant Bochs announcement, you can try posting it to
+bochs-announce, but the moderator will have to approve it before it will
+go out. On average, bochs-announce subscribers get one or two messages
+per month. There are about 75 subscribers. Anyone may join the list.
+
+
+
+To subscribe, go to the Bochs-Announce Info Page and type your email
+address and a password into the web form and click Subscribe.
+In a few minutes you will get a confirmation email. Follow the directions in
+the email to complete the subscription process. To unsubscribe, go to the
+same
+page and type your email address in the blank at the bottom and click
+on Edit Options. Then type your password and click
+Unsubscribe.
+
+
+
+There is no need to subscribe to both lists, because all bochs-announce
+messages are forwarded to the developers list. If you subscribe to both, you
+will get 2 copies of every announcement.
+
+
+
+Archive of bochs-announce messages
+
+
+
+
+bochs-cvs mailing list
+
+This is the svn commit mailinglist (a unified diff email will be sent
+whenever someone does a checkin in the bochs SVN repository).
+
+
+
+Archive of bochs-cvs messages
+
+
+
+
+Mailing List Etiquette
+
+
+Here are a few guidelines for use of the Bochs mailing lists:
+
+
+
+
+Please check the documentation before asking questions, but on this list you
+are very UNLIKELY to get flamed and insulted for being a Bochs beginner.
+Sending commercial promotions to the list probably will get you some angry
+responses though.
+
+
+
+If you are having difficulty finding what you are looking for, try doing a search on Google. If you are searching for Bochs options, for example, you can use this syntax in the Google search box:
+
+configuration options site:bochs.sourceforge.net
+
+For best results, be sure not to put a space between "site:" and "bochs.sourceforge.net". Be sure to look at more than the first item on the search results.
+
+
+
+
+If you still cannot find what you are looking for, be sure you are prepared when you post your question, and post in the right forum. Be sure you include important details, such as the operating system and version of your host, and what it is you are trying to do. If you are getting errors or something is not working, summarize what you checked and what you changed. This will help isolate the problem.
+
+
+
+
+
+Bochs is for everyone. If you are an experienced Bochs user or developer and are helping someone else, be considerate of the other person's feelings. We share a common interest, and we need to encourage each other and be supportive.
+
+
+
+
+Also, keep in mind that messages are limited to 40K, so if you want to share a
+large screen shot or disk image, put it on a web or FTP site and tell people
+how to find it. Patches are usually small enough that they aren't a problem,
+especially if compressed.
+
+
+
+Distribution of copyrighted material, or even offers to distribute copyrighted
+material WILL NOT be tolerated. The Bochs Project does not distribute
+any software (disk images) in violation of the license agreement, and users who
+do so will be warned first and then blocked from the list if it happens again.
+As an open source project, we rely on donated services from Source Forge and
+other groups, and we can't afford to put them or ourselves at risk of legal
+action.
+
+
+
+It is possible to subscribe and unsubscribe by email. If you do this, you must
+write to bochs-announce-request or bochs-developers-request. Don't forget the
+"-request" part or your subscribe message will go to 300+ people.
+
+
+
+
+
+
+
+The Bochs internal debugger
+Using the command line debugger
+
+
+You can now conditionally compile in a GDB like command line debugger, that
+allows you to set breakpoints, step through instructions, and other
+useful functions. If there isn't a command for something you believe
+is generally useful for the debugger, let me know and I'll implement
+it if possible.
+
+
+
+This section describes how to enable and use the Bochs command line debugger.
+For its builtin graphical front-end please see the debugger gui
+section how to enable it.
+
+
+
+To use the debugger, you must configure Bochs with the
+ flag.
+For example:
+
+ ./configure --enable-debugger
+
+
+
+
+You must use flex version 2.5.4 or greater. I have heard that
+version 2.5.2 will not work.
+
+
+
+When you first start up Bochs, you will see the command line prompt
+
+
+ bochs:1>
+
+
+From here, you may use the following commands:
+
+
+
+Execution Control
+
+
+ c continue executing
+ cont
+ continue
+
+ s [count] execute count instructions, default is 1
+ step [count]
+
+ s [cpu] [count] for SMP simulation, execute count instructions on cpu, default is 1
+ step [cpu] [count]
+
+ s all [count] for SMP simulation, execute count instructions on all cpus
+ step all [count]
+
+ Ctrl-C stop execution, and return to command line prompt
+ Ctrl-D if at empty line on command line, exit
+
+ q quit debugger and execution
+ quit
+ exit
+
+
+
+
+
+BreakPoints
+
+
+ NOTE: The format of 'seg', 'off', and 'addr' in these descriptions,
+ are as follows. I don't have any way to set the current radix.
+
+ hexidecimal: 0xcdef0123
+ decimal: 123456789
+ octal: 01234567
+
+ vbreak seg:off Set a virtual address instruction breakpoint
+ vb seg:off
+
+ vbreak seg:off if "expr" Set a conditional virtual address instruction breakpoint
+ vb seg:off if "expr"
+
+ lbreak addr Set a linear address instruction breakpoint
+ lb addr
+
+ lbreak addr if "expr" Set a conditional linear address instruction breakpoint
+ lb addr if "expr"
+
+ pbreak [*] addr Set a physical address instruction breakpoint
+ pb [*] addr (the '*' is optional for GDB compatibility)
+ break [*] addr
+ b [*] addr
+
+ pbreak [*] addr if "expr" Set a conditional physical address instruction breakpoint
+ pb [*] addr if "expr" (the '*' is optional for GDB compatibility)
+ break [*] addr if "expr"
+ b [*] addr if "expr"
+
+ info break Display state of all current breakpoints
+ bpe n Enable a breakpoint
+ bpd n Disable a breakpoint
+ delete n Delete a breakpoint
+ del n
+ d n
+
+
+
+
+
+
+Memory WatchPoints
+
+
+
+ watch read addr Insert a read watch point at physical address addr
+ watch r addr Insert a read watch point at physical address addr
+
+ watch write addr Insert a write watch point at physical address addr
+ watch w addr Insert a write watch point at physical address addr
+
+ watch Display state of current memory watchpoints
+
+ watch stop Stop simulation when a watchpoint is encountered (default)
+ watch continue Do not stop simulation when a watchpoint is encountered
+
+ unwatch addr Remove watchpoint to specific physical address
+ unwatch Remove all watch points
+
+
+
+
+
+
+Manipulating Memory
+
+
+ x /nuf addr Examine memory at linear address addr
+ xp /nuf addr Examine memory at physical address addr
+ n Count of how many units to display
+ u Unit size; one of
+ b Individual bytes
+ h Halfwords (2 bytes)
+ w Words (4 bytes)
+ g Giant words (8 bytes)
+ NOTE: these are *not* typical Intel nomenclature sizes,
+ but they are consistent with GDB convention.
+ f Printing format. one of
+ x Print in hexadecimal
+ d Print in decimal
+ u Print in unsigned decimal
+ o Print in octal
+ t Print in binary
+
+ n, f, and u are optional parameters. u and f default to the last values
+ you used, or to w(words) and x(hex) if none have been supplied.
+ n currently defaults to 1. If none of these optional parameters are
+ used, no slash should be typed. addr is also optional. If you don't
+ specify it, it will be the value the next address (as if you had
+ specified n+1 in the last x command).
+
+ setpmem addr datasize val Set physical memory location of size
+ datasize to value val.
+
+ writemem filename addr len dump a number of bytes of virtual memory starting from
+ the specified linear address into a file
+
+ loadmem filename addr initialize virtual memory starting from the specified linear
+ address from a file
+
+ deref addr deep pointer dereference. For example: get value of [[[rax]]] or ***rax: deref rax 3
+
+ crc addr1 addr2 Show CRC32 for physical memory range addr1..addr2
+
+
+
+
+
+
+Info commands
+
+
+ r|reg|regs|registers List of CPU integer registers and their contents
+ fp|fpu List of all FPU registers and their contents
+ mmx List of all MMX registers and their contents
+ sse|xmm List of all SSE registers and their contents
+ ymm|zmm List of all AVX registers and their contents
+ sreg Show segment registers and their contents
+ dreg Show debug registers and their contents
+ creg Show control registers and their contents
+
+ info cpu List of all CPU registers and their contents
+ info eflags Show decoded EFLAGS register
+ info break Information about current breakpoint status
+ info tab Show paging address translation
+ info idt Show contents of the IDT
+ info gdt Show contents of the GDT
+ info ldt Show contents of the LDT
+ info device Show state of the specified device
+
+
+
+
+
+Manipulating CPU Registers
+
+
+ set reg = expr Change a CPU register to value of expression.
+ Currently only general purpose registers and instruction pointer
+ are supported. You may not change eflags, segment registers,
+ floating point or SIMD registers.
+
+ Examples: set eax = 2+2/2
+ set esi = 2*eax+ebx
+
+ registers List of CPU registers and their contents
+ regs
+ reg
+ r
+
+ calc|? expr Evaluate an expression and display the result.
+ 'expr' can reference any general-purpose, opmask and segment
+ registers, use any arithmetic and logic operations, and also
+ special ':' operator which computes the linear address of a
+ segment:offset (in real and v86 mode) or of a selector:offset
+ (in protected mode) pair. Use $ operator for dereference,
+ for example, get value of [[[rax]]] or ***rax: rax$3.
+
+
+
+
+
+
+Disassembly commands
+
+
+ disassemble start end Disassemble instructions in given linear address
+ range, inclusive of start, exclusive of end.
+ Use "set $disassemble_size =" to tell
+ debugger desired segment size. Use a value for
+ end of less than start (or zero) if you only
+ want the first instruction disassembled.
+
+ disassemble switch-mode Switch between Intel and AT&T disassembly styles
+ for debugger disassembler.
+
+ disassemble size = n Tell debugger what segment size to use when
+ the "disassemble" command is used. Use values
+ of 0, 16 or 32 for n. Value of 0 means
+ "use segment size specified by current CS
+ segment". Default is 0.
+
+ set $auto_disassemble = n Cause debugger to disassemble current instruction
+ every time execution stops if n=1. Default is 0.
+ Segment size of current CPU context is used for
+ disassembly, so the "disassemble size" variable is
+ ignored.
+
+ set disassemble on The same as 'set $auto_disassemble = 1'
+ set disassemble off The same as 'set $auto_disassemble = 0'
+
+
+
+
+
+Instruction tracing
+
+
+ trace on Disassemble every executed instruction. Note
+ that instructions which caused exceptions are
+ not really executed, and therefore not traced.
+
+ trace off Disable instruction tracing.
+
+ trace-mem on/off Enable/Disable memory access tracing.
+
+
+
+
+
+Instrumentation
+
+
+To use instrumentation features in Bochs, you must compile in support for it.
+You should build a custom instrumentation library in a separate directory in
+the "instrument/" directory. To tell configure which instrumentation library
+you want to use, use the option.
+
+The default library consists of a set of stubs, and the following are
+equivalent:
+
+
+ ./configure [...] --enable-instrumentation
+ ./configure [...] --enable-instrumentation="instrument/stubs"
+
+
+You could make a separate directory with your custom library,
+for example, "instrument/myinstrument", copy the contents of
+the "instrument/stubs" directory to it, then customize it. Use:
+
+
+ ./configure [...] --enable-instrumentation="instrument/myinstrument"
+
+
+
+
+
+Instrumentation commands
+
+
+ instrument [command] calls BX_INSTR_DEBUG_CMD instrumentation callback with [command]
+ instrument "[command string]" calls BX_INSTR_DEBUG_CMD instrumentation callback with [command string]
+
+
+
+
+
+Other Commands
+
+
+ptime
+
+Print the current time (number of ticks since start of simulation).
+
+sb delta
+
+Insert a time break point "delta" instructions into the future ("delta" is a 64-bit integer followed by "L", for example 1000L).
+
+sba time
+
+Insert a time break point at "time" ("time" is a 64-bit integer followed by "L", for example 1000L).
+
+print-stack [num words]
+
+Print the num words top 16-bit words on the stack. Num
+words defaults to 16. Only works reliably in protected mode when
+the base address of the stack segment is zero.
+
+print-string addr
+
+prints a null-ended string from a linear address.
+
+bt [num_entries]
+
+prints backtrace.
+
+source file
+
+cause debugger to execute a script file
+
+addlyt file
+
+cause debugger to execute a script file every time execution stops.
+
+
+
+Example of use:
+
+
+
+Create a script file (script.txt) with the following content
+
+
+ regs
+ print-stack 7
+ u /10
+ (*EMPTY NEW LINE)
+
+
+
+Execute addlyt
+
+
+addlyt "script.txt"
+
+
+
+Then, when you execute a step/DebugBreak... you will see: registers, stack and disasm.
+
+
+remlyt
+
+stops debugger to execute the script file added previously with addlyt command.
+
+lyt
+
+cause debugger to execute script file added previously with addlyt command.
+Use it as a refresh/context.
+
+modebp
+
+Toggles CPU mode switch breakpoint.
+
+ldsym [global] filename [offset]
+
+Load symbols from file filename. If the global keyword is
+added, then the the symbols will be visible in all contexts for which
+symbols have not been loaded. Offset (default is 0) is added to
+every symbol entry. The symbols are loaded in the current (executing)
+context.
+
+
+
+The symbol file consists of zero or more lines of the format "%x %s".
+
+show [string]
+
+
+ Toggles show symbolic info (calls to begin with).
+ show - shows current show mode
+ show mode - show, when processor switch mode
+ show int - show, when interrupt is happens
+ show call - show, when call is happens
+ show ret - show, when iret is happens
+ show off - toggles off symbolic info
+ show dbg-all - turn on all show flags
+ show dbg-none - turn off all show flags
+
+
+
+
+
+Related links
+
+
+&FIXME; For information on advanced debugger usage see the developer documentation
+(under construction).
+
+
+
+
+
+
+The Bochs debugger GUI
+
+
+The graphical front-end for the Bochs command line debugger
+is available for Windows and GTK2/GTK3 hosts.
+
+
+To use the GUI debugger, you must configure Bochs with the
+default debugger switch and the flag.
+For example:
+
+ ./configure --enable-debugger --enable-debugger-gui
+
+
+
+At runtime you need to add the value to the
+display_library options parameter
+in order to use the GUI instead of the command line debugger. This example shows
+how to use it with the 'x' GUI:
+
+display_library: x, options="gui_debug"
+
+
+The wxWidgets port of Bochs always uses this debugger GUI. Passing
+the option to the display library is not necessary, since the command line
+interface is not available then.
+
+Overview
+
+The GUI debugger consists of a GUI window with a menu bar, a button bar and some
+child windows for different purposes. Not all windows are visible at the same time.
+
+
+Register window
+Disassembly window
+MemDump window
+Output window: display internal debugger output / log output
+Input window: command prompt for entering debugger commands
+Param tree window: show the Bochs parameter tree (CPU / hardware state)
+Stack window
+Breakpoint / watchpoint window
+Command button row
+CPU button row: only available for SMP emulation
+
+
+The register window
+
+Typically, all the various registers are grouped by color. If you don't like the
+colors, they can be turned off, or modified at compile time. There are options
+to show or hide most register "groups", so that you can focus more strictly on
+the registers you are interested in (probably just the GP registers).
+
+Yes, the XMM display shows hex in the "decimal" column -- there is more
+room there. Deal with it.
+Doubleclicking a register attempts to change its value. Bochs may not
+allow you to change most registers. In future versions, more registers may
+be modifiable.
+
+The disassembly window
+
+Disassembly output that is autoloaded, or generated from the menu, ends up
+here. If the frontend cannot detect the "current instruction" in the list,
+when it reaches the next instruction -- then it will autoload a new list.
+Having a big list will reduce the number of autoloads, and allows you to see
+more. The list can contain up to 2048 lines. However, if you load more than
+1000 lines, you are more likely to see performance problems.
+
+There are two kinds of emulated memory in Bochs: Linear and Physical.
+Emulated Linear memory is mapped onto Physical memory by x86 virtual memory
+methods (paging and segmentation). If paging and segmenataion are "off", or
+"identity mapped", then both "types" of memory mean the same thing. But they
+still work a little differently. With the Internal Debugger, you can set
+breakpoints to either kind of memory, separately. Normally, you would use
+the "b" command to set breakpoints in physical mem, and "lb" to set breakpoints
+in linear mem. This frontend ONLY displays linear breakpoints. It does not
+bother trying to figure out the linear->physical reverse mapping to show
+physical breakpoints. (There are also "virtual" breakpoints that are also
+not shown.) All the types of breakpoints still WORK, it is just that you
+will not see them marked on the screen.
+
+
+It will be obvious to you that the current instruction is marked in green,
+unless it is on a breakpoint, when it turns blue. Breakpoints are red, of
+course.
+
+
+You must click a line in the window, before you can use frontend commands
+to set or clear a linear breakpoint on it. You can doubleclick (which saves
+steps) to set or clear a linear breakpoint.
+
+
+The MemDump window
+
+As of this version, the MemDump window isn't much more than a display of the
+contents of memory. In later versions, hopefully it will be expanded into a
+fairly fully-featured hexeditor. You can dump either physical mem, or linear
+mem. There are breakpoint-like things (that work with physical memory only,
+currently), called "watchpoints". A physical memory address can cause a break
+in the simulation if it is read, or written.
+
+
+The frontend again does NOT try to calculate out the linear -> physical mapping
+in any attempt to display the physical watchpoints while viewing linear mem.
+
+
+You must click a hex byte (on a physical mem dump that shows bytes), in order to
+set or clear a read and/or write watchpoint on that byte. Read watchpoints are
+green (on black), write watchpoints are red, watchpoints that are both write
+and read are blue. There is a hardcoded limit in Bochs of 16 of each type of
+watchpoint.
+
+
+The MemDump window loads/shows 4K of memory at a time.
+
+
+PageUp/Down scrolls the display up or down through mem, 2K at a time
+Doubleclicking a line of memory allows you to change the byte values
+(Works on both linear and physical mem dumps)
+Doubleclicking with the Shift key down sets write watchpoints
+Doubleclicking with Alt sets read watchpoints
+You need to click once on the memory window before you can use its "Find"
+function. The Find function is pretty limited in scope, currently. It can
+only find bytes (or strings of bytes) within each 16byte "line"
+
+
+The output window
+
+The Output window shows anything that the Bochs Internal Debugger tries to send
+to you. The window is scrollable, but only keeps a limited history of output (10K).
+The ID is always spamming you with "Next at t=" and disassembly lines, that would
+tend to fill up the Output window with garbage -- so there are options to ignore
+either of these types of output.
+
+
+The input window
+
+The Input window is for sending user commands directly into the Bochs Internal
+Debugger -- bypassing the frontend. Results will appear in the Output Window.
+The Input window has a history feature for commands, using the Up and Down arrows --
+it remembers 64 commands, 80 bytes each. No matter where you click on the frontend,
+you can always type directly into the Input box without clicking on it.
+
+
+When the Input window is invisible, you should still be able to type into it --
+after taking into account the bug listed at the bottom of this file.
+
+
+Hitting Enter on a blank line will cause a Singlestep.
+
+
+The param tree
+
+The Bochs param_tree shows the internal state of most of Bochs. It will be
+expanded in the future to show even more. You can see the detailed state of
+all cpu registers -- including the "hidden" parts (look in the "bochs" branch).
+Or see the current state of most of the emulated hardware.
+
+
+The stack window
+
+The MemDump windows do not automatically refresh -- except for the Stack
+window. If you leave the stack window active, it will update as the stack
+changes. If you want to update the other MemDump windows with fresh data,
+hit Refresh.
+
+
+The breakpoint/watchpoint window
+
+Doubleclicking will delete a breakpoint or watchpoint.
+
+
+The command button row
+
+Just a (hopefully) convenient way of using the mouse, instead of the keyboard.
+If you don't like them, or they take up too much space, you can turn them off.
+
+
+The CPU button row
+
+This only shows up when you are running a multi-cpu simulation. Click on the
+CPU that you want to view. All CPUs are always stepped together, and they all
+stop the first time one hits some sort of breakpoint.
+
+
+Docking / Resizing
+
+If you grab one of the two vertical "bars" between the lists, you can horizontally
+resize the lists. The cursor will change, but there will be no animation.
+
+
+If you grab the middle of one of the lists, and drag it on top of one of the
+other lists, you can reorder the positions of the lists on the screen. The
+cursor will change, but there will be no animation. You can set an alternate
+"docking order" at compile time, also, if you have a permanent preference.
+(See the top of the wenhdbg_h.h file, for compile-time customization.)
+
+
+Additional Notes
+
+If you have a really big GDT or Paging display in the MemDump window, and you
+select a different display, it may take several seconds to delete the big display
+before it can switch.
+
+
+Uppercase text tends to seem a little annoying, but it really is a lot easier to
+read, especially on a proportional font. If you change to a fixed font, then you
+may want to switch the display to lowercase.
+
+
+Most of the GUI debugger settings are now saved to an INI file on exit and
+restored at the next run.
+
+
+
+
+
+Tips and Techniques
+
+Specify log options by device
+
+This table shows the name used for setting up the log actions per device, the
+prefix that appears in the log file or when a panic occurs and a short description
+of the module. This example shows how to turn on debug messages for a specific
+device in bochsrc.
+
+debug: action=ignore, pci=report
+
+The names can be used in upper case or lower case, since the check is not case
+sensitive. Note that the module names cannot be checked while reading the config
+file, since most of the modules do not exist at this point. Invalid names or names
+of modules not present in the current configuration will cause a panic when the
+simulation is starting.
+
+
+
+
+How to make a simple disk image
+
+This was contributed by Greg Alexander in October 2001 and updated by
+Volker Ruppert in October 2013.
+
+
+What you need:
+
+
+
+An executable version of Bochs. See Downloading Bochs and Compiling Bochs.
+
+
+The bximage program, included with Bochs.
+
+
+A FreeDOS boot disk, or a boot disk from another OS capable of
+producing DOS partitions (e.g. a Linux install disk).
+
+
+(Optional) mtools, a program for manipulating DOS disks/images.
+
+
+
+
+
+
+Create a flat image
+
+
+
+Option 1: Using the Unix dd utility:
+
+
+
+You will need to know the geometry of the disk you want to
+create. You have to compute the disk sector count:
+
+
+Sectors = Cylinders * Heads * SectorsPerTrack
+
+
+
+
+Use the dd command to create your file:
+
+
+dd if=/dev/zero of=teaching.img bs=512 count=sectors
+
+(replace "sectors" with the number you computed at the
+previous step).
+
+
+
+When you update your configuration file, please
+fill in the same cylinders, heads, and sector per
+track values.
+
+
+
+
+Option 2: Run bximage to create a disk image file.
+You will be greeted with the following prompt:
+
+
+========================================================================
+ bximage
+ Disk Image Creation / Conversion / Resize and Commit Tool for Bochs
+ $ID: bximage.cc 11906 2013-10-23 08:35:21Z vruppert $
+========================================================================
+
+1. Create new floppy or hard disk image
+2. Convert hard disk image to other format (mode)
+3. Resize hard disk image
+4. Commit 'undoable' redolog to base image
+
+0. Quit
+
+Please choose one [0]
+
+
+
+
+Since we want to create a new image, we have to type '1'
+and then Enter.
+
+Do you want to create a floppy disk image or a hard disk image?
+Please type hd or fd. [hd]
+
+
+
+
+Since we are creating a hard disk image, accept the default of hd by
+pressing Enter or typing 'hd' and pressing
+Enter. Next, bximage will ask for the type of
+hd to create:
+
+
+What kind of image should I create?
+Please type flat, sparse, growing or vpc. [flat]
+
+
+
+
+
+We want to create a simple flat image, so accept the default
+by pressing Enter. Then, bximage will ask
+for the size of the disk image you want to create, in Megabytes:
+
+
+Enter the hard disk size in megabytes, between 1 and 8257535
+[10]
+
+
+
+
+Enter the size of the hard disk you want to create, and press
+Enter. Then bximage will ask you for a filename to use
+for the file it is creating.
+
+What should be the name of the image?
+[c.img]
+
+
+
+
+At this point, type in the filename you want to use for the image. The
+default of "c.img" is appropriate if this will be your only hard disk
+image. After you have typed in the name of the filename you want to
+use, press Enter. Bximage will tell you it is writing the disk
+and then it will show you a line that should be added to your
+bochsrc when you want to use this disk image. I named my
+10 Megabyte image "teaching.img" and the output of bximage looked like
+this:
+
+
+[c.img] teaching.img
+
+Creating hard disk image 'c.img' with CHS=20/16/63
+
+
+
+
+The following line should appear in your bochsrc:
+
+ ata0-master: type=disk, path="teaching.img", mode=flat, cylinders=20, heads=16, spt=63
+
+
+
+
+At this point, a file called "teaching.img" was created in my current
+directory and is ready to be used as an image file for a Bochs session.
+
+
+
+
+You may want to name your image teaching_20-16-63.img
+so that you always know the values to use for CHS.
+
+
+
+
+
+
+Partition and format your image file
+
+
+
+Option 1: Using FreeDOS (Advantage: Creates a MBR on the partition.)
+
+
+
+First, you need to edit the bochsrc file that Bochs uses for
+configuration information (see ). Open bochsrc
+with a text editor. Remove all lines in the file which start with "ata0-master:". Add the "ata0-master:"
+line that was displayed when you ran bximage to bochsrc at the
+same place where you removed the old "ata0-master:" lines from.
+
+
+
+Also, you need to download or create a FreeDOS (or DOS, or Windows, or
+Linux) disk image. Modify the "floppya:" line in your bochsrc to point
+at the downloaded FreeDOS floppy image and change its status to "status=inserted".
+
+
+
+Save and close your bochsrc. Now run Bochs (see ).
+
+
+
+Use the standard FreeDOS commands fdisk and
+format to format your hard
+drive image. You must make the image bootable to be able to boot
+without a floppy disk. However, creating a bootable disk image is best
+done with a boot disk from the OS you intend to install on the image.
+
+
+
+
+Option 2: Using mtools (Disadvantage: Cannot create bootable images
+without a MBR image.)
+
+
+
+Use a text editor to add the following line to the file ~/.mtoolsrc:
+
+
+
+
+drive c: file="path/filename.img" partition=1
+
+
+
+
+Save and close .mtoolsrc. Next, execute the following commands to
+create a partition table for the drive image:
+
+
+
+
+mpartition -I -s spt -t cyl -h heads c:
+mpartition -cpv -s spt -t cyl -h heads c:
+
+
+
+For example, for my 10 meg drive, I used:
+
+mpartition -I -s 63 -t 20 -h 16 c:
+mpartition -cpv -s 63 -t 20 -h 16 c:
+
+
+
+
+
+Next, format the partition you just created using the mformat command:
+
+
+mformat c:
+
+
+
+
+
+And you now have a formatted disk image containing a single DOS
+partition.
+
+
+The mpartition command doesn't handle images larger than 1024 cylinders properly.
+The partition size reported by fdisk is okay, but mformat reports only 504 MB
+(tested with mtools 3.9.9).
+
+
+
+
+Use mtools to manipulate disk images
+
+Mtools is a set of programs that can read, write, and format DOS disk images.
+There are links to the Mtools main page and a Win32 port of Mtools on the
+Bochs Links page,
+under Resources.
+
+
+The mtools web site has a detailed manual. If anyone wants to write
+instructions specific to Bochs, we can add it right here.
+
+
+
+Bochs GNU/Linux DiskTools
+
+Bochs-Tools are a collection of scripts and programs to be used together
+with Bochs developed by Bernhard Bablok. Main goal was to provide a more
+Unix-like interface to the emulator and to enable access to Bochs disk-images
+from outside of Bochs. The latest version is available at
+www.bablokb.de/bochs-tools.
+
+
+
+Win32 only: Tools to manipulate disk images
+
+Winimage
+
+Someone on the &devlist; mentioned that they use a program
+called WinImage, from www.winimage.com
+to read and write disk images (floppy and hard disk). Winimage is a
+commercial product with a 30-day trial.
+
+
+If anyone wants to write a tutorial, send mail to &devlist; and volunteer.
+
+
+
+DiskExplorer
+
+This section was contributed by Luca Cassioli and Stanislav Shwartsman
+
+
+I eventually found what all of you were looking for for a long time: a
+freeware, graphical, win32 compatible HardDisk image editor! It can
+handle a large variety of formats, but the one you need is VMWARE
+2.0 PLAIN DISK: you can import/export to/from Bochs images COMPLETE
+DIRECTORIES!
+
+
+You can find it at
+
+http://hp.vector.co.jp/authors/VA013937/editdisk/index_e.html
+
+
+
+Ben Lunt's 'Ultimate' for Bochs and Win32/64
+
+Ben Lunt wrote a utility for Windows to manipulate flat disk images and their
+included file systems.
+
+
+You can find it at
+https://www.fysnet.net/ultimate/index.htm
+
+
+This is a Windows Dialog based utility, with source, and includes the following items:
+
+
+ Partitioning: MBR, PMBR, eMBR, EFI GPT
+
+
+ File Systems: FAT, FYSFS, LeanFS, Ext2/3/4, SimpleFS, ExFAT
+
+
+ Inserting, extracting, and deleting files from said file systems.
+ (some file system support is currently read-only)
+
+
+ Checking the integrity of said file systems and other items.
+
+
+
+
+
+
+
+X Windows: Color allocation problems
+
+One common problem in X windows is that the screen colors can be abnormal
+if other X programs have already allocated all the colors. If the colors
+don't look right, try quitting colorful applications such as Netscape,
+clearing any complex images in the background, etc. so that Bochs has a
+chance to allocate the colors it needs.
+
+
+If Bochs continues to have problems, or you want Bochs to have perfect
+colors without having to quit any other application, you can try turning
+on the private_colormap option
+in the configuration file. Using a private
+colormap causes the Bochs window to have its own set of 256 colors to work
+with. When the cursor is over the Bochs display, Bochs will look correct
+and other parts of the screen may change to very strange colors. When the
+cursor goes to any other window, the other windows will look correct
+and Bochs will have strange colors. A better solution, if your hardware
+can support it, is to run your X server with 24-bit or 32-bit color.
+
+
+
+Screen saver turns on too quickly
+
+
+One thing you may notice is that the screen saver turns on (screen goes
+blank) very quickly after you have stopped typing. The reason is that Bochs
+simulates everything as fast as it can. If the CPU is very busy (running
+instructions nonstop), simulated time goes by slowly. If the CPU is idle (just
+waiting for you to type, for example), simulated time speeds up dramatically.
+In any case, if the screen saver blanks out the screen, just press a key (try
+shift or control) to restore the screen.
+
+
+
+There are two strategies to fix this problem. One is to increase the
+ips parameter of the cpu option
+in your configuration file. This will cause the simulation time
+to pass more slowly. The other strategy is to enable the experimental
+realtime PIT, which tries to keep Bochs in sync with real time. See the bochsrc
+option clock.
+
+
+
+
+
+Mounting a disk image using the loop device
+
+
+This section describes how to access a floppy or hard disk image within Linux
+using the loop device. Why would you want to do this? Let's say you have made
+a small Linux disk image for Bochs, and you want to install some more software
+on it. You have already downloaded the software onto your real system, so now
+you want to transfer it to the Bochs disk image. A fast way to transfer
+the files is to mount the disk image using the loop device.
+
+
+...on Linux
+
+
+This section was contributed by Volker Ruppert.
+
+Today I have made some tests with the loop device, because I want to exchange
+files with the Bochs disk images. This is what I found out:
+
+1. Using Floppy images is easy, because there is no partition table:
+
+ losetup /dev/loop0 /usr/local/bochs/dlxlinux/floppya.img
+
+ Now you can use the image like a real floppy:
+
+ - format : mkfs.minix /dev/loop0
+ - filesystem check : fsck.minix /dev/loop0
+ - mount : mount /dev/loop0 -o loop /mnt/floppy
+
+ Before you want to restart Bochs you must do this:
+
+ losetup -d /dev/loop0
+
+ Don't forget to umount before.
+
+2. If you want access to a hard disk image, you have to calculate the size of
+ the first cylinder. This value is the offset argument for losetup.
+
+ offset = bytes per sector * sectors per cylinder
+
+ The command for dlxlinux image looks like this:
+
+ losetup /dev/loop0 /usr/local/bochs/dlxlinux/hd10meg.img -o 8704
+
+ For images created by bximage you must use the value 32256.
+
+3. The hard disk image access doesn't work if the image contains more than
+ one partition.
+
+4. I have made this test with Linux and I don't know how
+ this could be done with other operating systems.
+
+
+
+
+
+...on FreeBSD
+
+
+This section was contributed by Alexander Schuch.
+
+
+The following example mounts a Windows 95 hard disk image called Windows 95 B (2031-16-63)
+into the FreeBSD file system. It is specific to FreeBSD 5.x; for
+hints on how to do the same task on FreeBSD 4.x, or for more information in
+general, check the proper section of the FreeBSD handbook:
+Network, Memory, and File-Backed File Systems.
+You can use the same procedure for mounting floppy disk images.
+
+
+
+
+#mdconfig -a -t vnode -f "Windows 95 B (2031-16-63)"
+md0
+
+mdconfig returns the device, your file now is accessable from.
+
+#mount -t msdosfs /dev/md0s1 /mnt
+
+If you already have other md devices configured, you need to substitute md0s1
+with, for example, md6s1.
+
+
+
+Once you are done working with the image, unmount the md device and detach it.
+
+#umount /mnt
+#mdconfig -d -u 0
+
+And again, if there are other md devices configured, use the proper device
+number. In case you forgot the number, just ask mdconfig, like:
+
+#mdconfig -l
+md7
+#mdconfig -d -u 7
+
+
+
+
+
+
+
+Simulating a Symmetric Multiprocessor (SMP) Machine
+
+Bochs can now simulate an SMP machine when you use in the
+configure command. SMP support was added by Bryce Denney, who
+was very interested in watching a multiprocessor operating system work
+at a low level. It should also be helpful to operating system developers
+who are writing SMP drivers, or just for users who want to test drive
+an SMP machine to see what it looks like.
+
+
+Starting with Bochs 2.2.6 you can set up the number of processors in the
+bochsrc. See how to
+set up the number of processors.
+
+
+It is important to understand that configuring Bochs for 4 processors will NOT
+make your single-threaded applications run faster in general! On the contrary,
+it has to spend time simulating idle processors as well as the ones doing your
+task. The point is to simulate an SMP system, not to speed up a uniprocessor
+application.
+
+
+
+What was required to make SMP work in Bochs?
+
+
+ local APIC on each processor with timer
+
+ one I/O APIC model
+
+ implement RDTSC (read time stamp counter)
+
+ a data structure called the Intel Multiprocessor Configuration
+must be present in BIOS memory space. An SMP-aware operating system probes BIOS
+memory to find the structure, which contains information about how many
+processors, their IDs, interrupt sources, etc. Starting with Bochs 2.2.5 these
+structures are dynamically created by Bochs.
+
+ ACPI support is required to boot SMP system in most of modern
+operating systems. For example, WinXP 64 bit require ACPI support even for
+single processor configuration.
+
+
+
+
+
+What needs to be done to improve SMP support?
+
+
+
+debugger support is still limited. For example, you can set breakpoints,
+but you can't specify which processor you want to set the breakpoint for.
+
+
+
+test on any possible SMP operating systems. Currently success reported for
+Knoppix 4.0.2, WinNT 4.0 and WinXP SMP.
+
+
+
+several parts of the APIC model which weren't needed before are not
+implemented yet.
+
+
+
+A number of people have suggested using threads to simulate each CPU in
+a different thread. Then on a real SMP machine, the threads can execute
+in parallel. This is a great idea, but it's not done at present.
+
+
+
+
+
+Setting Up Networking in DLX Linux
+
+All Bochs binaries come with a working version of DLX Linux. This section
+describes how to configure networking in Bochs and enable it within
+DLX Linux. First you must add a ne2k line in your bochsrc
+file. Then, when you boot the DLX Linux image, you need to type some Linux
+commands to set up an IP address, a network route, and a name server.
+
+
+
+When you have an ne2k line in your bochsrc file, Bochs
+will emulate a network card called an NE2000. Below are some examples of valid
+ne2k lines for various operating systems. Choose the
+one that's closest to what you need, add it to your bochsrc file, and
+edit the values if necessary.
+
+ # sample for Mac OS X
+ ne2k: ioaddr=0x300, irq=9, mac=b0:c4:20:00:00:00, ethmod=fbsd, ethdev=en0
+ # sample for FreeBSD
+ ne2k: ioaddr=0x300, irq=9, mac=b0:c4:20:00:00:00, ethmod=fbsd, ethdev=xl0
+ # sample for Linux
+ ne2k: ioaddr=0x300, irq=9, mac=b0:c4:20:00:00:00, ethmod=linux, ethdev=eth0
+ # sample for Windows
+ ne2k: ioaddr=0x300, irq=9, mac=00:c4:3B:00:C3:00, ethmod=win32, ethdev=NE2000
+
+You see the pattern. Usually, you won't need to change the I/O address, IRQ
+number, or MAC address. The ethmod value depends on your
+host operating system, and it must be either null,
+fbsd (for FreeBSD or OpenBSD), linux,
+or win32. The ethdev setting is the
+name of the network interface on your system, and is also OS-dependent. On
+UNIX systems you can get the name of the network interface by running
+ifconfig. (Don't choose the loopback interface.) On
+Windows systems, the correct ethdev setting is not always obvious, so we
+provide a utility called niclist to list the names of
+network interfaces to use. When you run niclist, it will
+suggest an ne2k line which is a very good first try.
+
+
+
+Next, if you are on a UNIX machine you will need to become the root user.
+Since Bochs is sending and receiving raw network packets, you need to be root
+to use the network device. To allow normal users to do this would be a
+security problem.
+
+
+
+Now run Bochs to boot DLX Linux. Press 'enter' a few times to accept the default
+configuration choices. This tells Bochs read the configuration file and then
+begin. DLX Linux should boot in the Bochs window, and you should see
+that Linux detects the NE2000 card. Eventually it gets to a login prompt.
+
+ ne.c:v1.10 9/23/94 Donald Becker (becker@cesdis.gsfc.nasa.gov)
+ NE*000 ethercard probe at 0x300: b0 c4 20 00 00 00
+ eth0: NE2000 found at 0x300, using IRQ 9.
+
+
+
+
+At the login prompt, type "root" to log in as root. Then type the ifconfig and
+route commands to set up networking. The exact IP numbers in the example won't
+work for you; you must choose an IP configuration that is legal on your
+network.
+
+
+ dlx login: root
+ Linux 1.3.89.
+ dlx:~# ifconfig eth0 192.168.0.99 # set bochs IP address
+ dlx:~# route add -net 192.168.0.0 # first 3 numbers match IP
+ dlx:~# route add default gw 192.168.0.1 # your gateway to the net
+ dlx:~# _
+
+
+
+
+
+The Bochs IP address must be an unused IP address on your
+network. If you duplicate someone else's IP address, your network will
+become very confused.
+
+
+
+
+Finally, the network is ready and you can test it out with ping, telnet, or ftp
+to various machines by their numerical IP address. Keep in mind that for all
+UNIX host platforms, Bochs networking cannot talk to the host machine. That
+means the host machine can't be the gateway either. You need another physical
+machine on the network that Bochs can talk to. On Win32 this restriction does
+not apply.
+
+
+
+
+When you have a working network configuration, you can make DLX Linux recreate
+the same settings the next time you boot. Just add the ifconfig and route
+commands to the end of /etc/rc.d/rc.inet1. I won't try to describe how
+to use the vi editor in this limited amount of space...
+
+
+
+
+
+
+To configure a name
+server, set up /etc/resolv.conf with the IP address of
+your name server as shown.
+
+ dlx:~# echo 'nameserver 192.168.0.1' > /etc/resolv.conf
+
+
+
+
+Configuring and using a tuntap network interface
+
+If you use linux (optionally FreeBSD and Solaris, not tested),
+you may want to access the network through a tuntap interface. The main
+advantage of this interface, is that the guest has access to the host. The guest can even
+have access to the whole network if the host routes or masquerades the guest requests.
+No extra IP address is needed, all can be done using private IP addresses.
+
+
+
+You'll find here instructions to set up Linux/Bochs to provide network access to the guest OS
+through a tuntap interface and private IP network. We're going to see howto :
+
+enable the tuntap interface in the Linux Kernel
+configure Bochs to use the tuntap interface
+set up the private network between the host and the guest
+set up the host to masquerade the guest network accesses
+
+
+
+ Tuntap description
+
+From the
+tuntap.txt file in the Linux kernel tree :
+
+ TUN/TAP provides packet reception and transmission for user space programs.
+ It can be viewed as a simple Point-to-Point or Ethernet device, which
+ instead of receiving packets from a physical media, receives them from
+ user space program and instead of sending packets via physical media
+ writes them to the user space program.
+
+ When a program opens /dev/net/tun, driver creates and registers corresponding
+ net device tunX or tapX. After a program closed above devices, driver will
+ automatically delete tunXX or tapXX device and all routes corresponding to it.
+
+
+
+
+
+ Set up the linux Kernel
+ <footnote><para>much of the information of the following section is taken from
+ <ulink url="http://maconlinux.org/lists/mol-general/August01/0056.html">
+ this email from Samuel Rydh of the Mac-On-Linux list</ulink></para></footnote>
+
+First make sure the tuntap module is included in the kernel :
+
+
+ if you use a recent distribution, chances are that the needed modules are already build
+ Make sure that "Kernel module loader" - module auto-loading support is enabled in your kernel.
+ Add following line to the /etc/modules.conf: alias char-major-10-200 tun
+ Run: depmod -a The driver will be automatically loaded when application access /dev/net/tun.
+
+
+ Otherwise, recompile the kernel, including the configuration option
+ CONFIG_TUN (Network device support -> Universal TUN/TAP device driver support)
+
+
+
+
+
+Make sure there is a /dev/net/tun device.
+(Can be created with 'mkdir /dev/net ; mknod /dev/net/tun c 10 200').
+
+
+
+
+In the same way, to use masquerading, you need a kernel with the following options :
+
+ CONFIG_IP_NF_CONNTRACK (Connection tracking)
+ CONFIG_IP_NF_IPTABLES (IP tables support)
+ CONFIG_IP_NF_NAT (Full NAT)
+
+
+
+Some of the other options in this group is probably also needed,
+(but the default setting should be OK).
+
+
+
+
+
+
+ Configure Bochs to use the tuntap interface
+ Make sure Bochs has one of the network adapters enabled. If you
+ have to recompile Bochs, use or
+ when running ./configure
+ (see )
+
+ edit your .bochsrc configuration file and add something like :
+ ne2k: ioaddr=0x300, irq=9, mac=fe:fd:00:00:00:01,
+ ethmod=tuntap, ethdev=/dev/net/tun0, script=/path/to/tunconfig
+
+
+
+ Since the tuntap interface cannot be configured until a process opens it,
+ Bochs may run a script file for you. In this case
+ /path/to/tunconfig should be changed to match
+ the actual place where you'll create this script.
+
+
+
+
+Set up the private network between the host and the guest
+
+ We'll set up a private network between the host and the guest with the following parameters:
+
+ Host IP : 192.168.1.1
+ Guest IP : 192.168.1.2
+
+ If your parameters are different, adapt the rest of the section to suit your needs.
+
+
+ Create the /path/to/tunconfig script :
+
+ #!/bin/bash
+ /sbin/ifconfig ${1##/*/} 192.168.1.1
+
+ The script gets the interface name as the first parameter. Linux
+ will forward incoming packets between interfaces.
+
+
+ Make it executable :chmod 755 /path/to/tunconfig
+
+
+ Run Bochs, install the guest OS, and set the following network parameters in the guest OS:
+
+ IP: 192.168.1.2
+ netmask: 255.255.255.0
+ gateway: 192.168.1.1
+ nameserver: whatever is used in linux
+
+
+
+ Bochs must be started by root (at least for now - the
+ script won't have root privileges otherwise).
+
+
+ You may also have to edit /etc/hosts.allow in the host OS and add :
+
+ ALL: 192.168.1.2
+
+ Don't forget to set up the route on the guest.
+
+
+ At this point, you should be able to ping/telnet/ftp/ssh the guest from the host
+ and vice-versa.
+
+
+
+
+Set up the host to masquerade the guest network accesses
+
+ We are going to set up standard masquerading configuration. Edit
+ the /path/to/tunconfig script ans add :
+
+ /sbin/iptables -D POSTROUTING -t nat -s 192.168.1.0/24 -d ! 192.168.1.0/24 -j MASQUERADE >& /dev/null
+ /sbin/iptables -t nat -s 192.168.1.0/24 -d ! 192.168.1.0/24 -A POSTROUTING -j MASQUERADE
+ echo 1 > /proc/sys/net/ipv4/ip_forward
+
+
+
+ The configuration assumes the default policy is
+ ACCEPT (can be examined by doing '/sbin/iptables -L')
+
+
+ The iptables package must be installed.
+ And voila... The host should forward the packets of the guest to the rest of your network.
+ You could even have access to the internet...
+
+
+ You may need to load other modules if you want to use other fancy protocols (ftp,etc...)
+
+
+
+
+
+
+Using the 'slirp' networking module
+
+Slirp is a software program that emulates a PPP, SLIP, or CSLIP connection to
+the Internet via a shell account. The original version has been written by
+Danny Gasparovski in 1995. It has been integrated in QEMU to provide user mode
+networking. Now a port of the QEMU Slirp implementation is available in Bochs.
+
+
+Features and limitations:
+
+Access to the internet and host network services without root/Administrator
+privileges or additional libraries.
+Builtin DHCP and TFTP servers
+Optional SMB support on Linux
+ICMP traffic (ping) from guest to the host's network or the internet
+not supported
+guest access from the host or external network disabled by default
+
+
+
+This example shows how to use the 'slirp' module with the NE2000 adapter. The line
+is very similar for the E1000 or PCI Pseudo NIC.
+
+ne2k: mac=52:54:00:12:34:56, ethmod=slirp, ethdev=/home/volker/tests/bochs, script=""
+
+The "ethdev" value specifies the TFTP root directory. All other options for Slirp must
+be set in a config file specified with "script" parameter. If no config file is set up,
+Bochs uses this "classic" Slirp configuration shown in the "Default" column below.
+
+Advanced Slirp setup with config file
+
+An example for a Slirp config file can be found in the Bochs sources and in
+binary packages (misc/slirp.conf).
+
Slirp config file options
+
+
+
+ Option
+ Description
+ Default value
+
+
+
+
+ restricted
+ if set to 1, only built-in services are available
+ 0
+
+
+ net
+ base IP address of the virtual network
+ 10.0.2.0
+
+
+ mask
+ netmask of the virtual network
+ 255.255.255.0
+
+
+ host
+ IP address of the DHCP and TFTP server
+ 10.0.2.2
+
+
+ hostname
+ DHCP client hostname
+ undefined
+
+
+ dhcpstart
+ start address of DHCP pool
+ 10.0.2.15
+
+
+ dns
+ IP address of the virtual DNS server
+ 10.0.2.3
+
+
+ bootfile
+ boot filename returned by DHCP
+ undefined
+
+
+ dnssearch
+ comma-separated list of DNS suffixes to search (DHCP extension)
+ undefined
+
+
+ smb_export
+ absolute path to the shared folder (non-Windows SMB support)
+ undefined
+
+
+ smb_srv
+ alternative IP address of the SMB server
+ 10.0.2.4
+
+
+ hostfwd
+ map guest port to host port for host-to-guest access
+ (see below for details)
+ undefined
+
+
+ pktlog
+ specify log file to enable packet logging in text format
+ disabled
+
+
+
+
+
+
+Access to guest services from the host
+
+With the config file option "hostfwd" you can map guest ports to ports on the host
+system. This is the format of the directive:
+
+ hostfwd = protocol:hostaddr:hostport-guestaddr:guestport
+
+The host and guest IP addresses are optional. This example shows how to access
+the guest SSH server using the host port 12345.
+
+ hostfwd = tcp::12345-:22
+
+Up to 5 port redirection rules are supported per slirp instance.
+
+
+
+Using the 'socket' networking module
+
+The original patch for the 'socket' networking module has been written by
+Mariusz Matuszek in 2003. It supported interconnecting two Bochs sessions
+running on the same machine via UDP using an external program called 'bxhub'.
+
+
+The 'socket' networking module is now integrated in the Bochs code with these
+extensions:
+
+Integrated 'vnet' server features (ARP, ICMP-echo, DHCP, DNS, FTP and TFTP)
+Limited DNS server for 'vnet' and connected clients
+Command line options for 'bxhub' added for base UDP port and 'vnet' server features
+Support for connects from up to 6 Bochs sessions
+Support for connecting 'bxhub' on other machine
+
+
+
+The 'socket' networking module uses two UDP ports per Bochs session. By default,
+the first session receives packets from port 40000 and sends packets to port
+40001. The second session uses then the ports 40002 and 40003. For further
+sessions the port numbers are incremented accordingly. The port number for
+receiving packets is specified with the 'ethdev' parameter of the bochsrc
+line for the network adapter. The format is host:port
+for connecting the 'bxhub' utility. If it runs on the same machine
+('localhost') the host name can be omitted.
+
+
+These examples show how to use the 'socket' module with the NE2000 adapter. The line
+is very similar for the E1000 or PCI Pseudo NIC.
+
+ne2k: mac=52:54:00:12:34:56, ethmod=socket, ethdev=mymachine:40000, script=""
+ne2k: mac=52:54:00:12:34:56, ethmod=socket, ethdev=40000, script=""
+
+
+Using the 'bxhub' utility
+
+If bxhub is started without command line options, these
+default values are used:
+
+UDP base port 40000
+2 client connections
+Server MAC address b0:c4:20:00:00:0f
+FTP / TFTP support disabled
+
+
+
+To change the default settings, these parameters are supported:
+
+Usage: bxhub [options]
+
+Supported options:
+ -ports=... number of virtual ethernet ports (2 - 6)
+ -base=... base UDP port (bxhub uses 2 ports per Bochs session)
+ -mac=... host MAC address (default is b0:c4:20:00:00:0f)
+ -tftp=... enable FTP and TFTP support using specified directory as root
+ -bootfile=... network bootfile reported by DHCP - located on TFTP server
+ -loglev=... set log level (0 - 3, default 1)
+ -logfile=... send log output to file
+ --help display this help and exit
+
+
+
+The vnet FTP service
+
+The 'vnet' server now provides passive FTP support also using the TFTP directory
+as root. The FTP server name is vnet-ftp. For read only access,
+the username must be set to anonymous with any password.
+This mode supports browsing the directory subtree and downloading files. For
+read/write access, the user must be set to bochs with
+password bochs. This enables support for uploading,
+renaming and deleting files, creating, and removing directories.
+
+
+
+
+
+Using Bochs and the remote GDB stub
+
+This section covers how you can use Bochs with a remote GDB stub to debug your kernel.
+
+
+
+Configuring Bochs
+
+The GDB stub is not active in standard Bochs binary package. So you must recompile Bochs.
+Download the Bochs source package, unpack it and run the configure script
+with the argument.
+
+
+ $ ./configure --enable-gdb-stub
+
+
+After that, just run make and you should have a Bochs binary that contain a GDB stub in your directory.
+
+
+
+
+Running Bochs
+
+Enable the gdbstub option in bochsrc, then just start Bochs as normal. Bochs will stop and wait for GDB to connect to the stub.
+
+
+
+
+Running GDB
+
+Bochs GDB stub waits for a connection on TCP port 1234. Just start GDB like this:
+
+
+ $ gdb YOUR-KERNEL
+ .
+ .
+ .
+ (gdb) target remote localhost:1234
+ Remote debugging using localhost:1234
+ 0x0000fff0 in ?? ()
+ (gdb)
+
+
+You are now connected to the remote GDB stub in Bochs. You are now able to set breakpoints.
+Use the continue (c) command to continue the simulation.
+
+Hitting ^C works. Example:
+
+
+ Program received signal 0, Signal 0.
+ syscall_testsuite_result (aux=0x1f11fe4) at ../rtmk/syscalls.c:33
+ 33 {
+ (gdb)
+
+
+
+
+
+
+Using the serial port
+
+ This section describes what is possible to do with Bochs serial port emulation.
+ These examples use dlxlinux disk image
+ (downloaded from
+
+ http://bochs.sourceforge.net/guestos/dlxlinux3.tar.gz
+ ) running as guest, on a debian x86 linux 2.4.19 host.
+
+
+ For the examples to work in dlxlinux, after you login as root, you will need to
+ kill the running gpm, as it grabs the serial port.
+
+Welcome to DLX V1.0 (C) 1995-96 Erich Boehm
+ (C) 1995 Hannes Boehm
+
+
+dlx login: root
+Linux 1.3.89.
+dlx:~# ps | grep gpm
+ 30 S0 S 0:00 /usr/bin/gpm -t bare
+ 40 1 S 0:00 grep gpm
+dlx:~# kill -9 30
+dlx:~#
+
+
+
+ Logging serial port output to a file
+
+ The first example shows how to log information sent to the serial port
+ on the guest system into a file on the host system.
+
+
+ Update the com1: section of your configuration file:
+
+com1: enabled=1, mode=file, dev=serial.txt
+
+ After you've launch dlxlinux, everything sent to the serial port will be
+ logged to serial.txt :
+
+dlx:~# echo "logging to the serial port" > /dev/cua0
+
+
+host$ cat serial.txt
+logging to the serial port
+host$
+
+
+
+ Interactivity : connecting to a virtual terminal
+
+ The second example shows how to connect to the guest OS, using a
+ virtual terminal on the host OS.
+
+
+ First, you need to find an unused virtual terminal. Typically,
+ X uses vt7; vt8 and up are unused. On my system, I can
+ switch from X to vt9 by pressing ctrl-alt-f9 : this virtual
+ terminal is not used, the screen is all black. Pressing alt-f7
+ switches back to X.
+
+
+ Once you found an unused vt, update the com1: section of your
+ configuration file:
+
+com1: enabled=1, mode=term, dev=/dev/tty9
+
+ The number must be set according to the terminal you want to use (here 9).
+
+
+ Now, launch dlxlinux. After you log in as root and kill gpm,
+ enter the following command:
+
+dlx:~# /sbin/agetty 38400 cua0
+
+ If you switch to vt9, you can see dlx welcome banner, and the login prompt:
+
+Welcome to DLX V1.0 (C) 1995-96 Erich Boehm
+ (C) 1995 Hannes Boehm
+
+
+dlx login:
+
+ Note that dlxlinux is configured so you can not login as root from a
+ serial port. If you want to login, you have to create a new user first.
+
+
+ Also, if you plan to use this feature, the best would be to deactivate
+ gpm in /etc/rc.d/rc.local, and add a agetty line in /etc/inittab,
+ for example:
+
+T0:1234:respawn:/bin/agetty 38400 cua0
+
+
+
+ Interactivity : connecting to a pseudo terminal
+
+ The third example is very similar to the second one, except that we
+ connect to the guest OS with kermit as client, and we the connection
+ is done through a pseudo terminal.
+
+
+ This example uses /dev/ptyp0 and /dev/ttyp0 as pseudo terminal pair.
+ We will tie Bochs to the controlling terminal, whereas kermit will
+ use the slave terminal.
+
+
+ Update the com1: section of your configuration file:
+
+com1: enabled=1, mode=term, dev=/dev/ptyp0
+
+ and launch dlxlinux. After you log in as root, enter the command:
+
+dlx:~# /sbin/agetty 38400 cua0
+
+ Then in the host OS, launch kermit :
+
+host$ kermit -l /dev/ttyp0
+C-Kermit 7.0.196, 1 Jan 2000, for Linux
+ Copyright (C) 1985, 2000,
+ Trustees of Columbia University in the City of New York.
+Type ? or HELP for help.
+(/tmp/) C-Kermit>connect
+Connecting to /dev/ttyp0, speed 0.
+The escape character is Ctrl-\ (ASCII 28, FS)
+Type the escape character followed by C to get back,
+or followed by ? to see other options.
+----------------------------------------------------
+
+Welcome to DLX V1.0 (C) 1995-96 Erich Boehm
+ (C) 1995 Hannes Boehm
+
+
+dlx login:
+
+ The same comments as for example 2 apply here.
+
+
+
+
+
+BIOS Tips
+
+ Booting from CD-ROMs
+
+A bootable CD-ROM has a special layout that is detected by the
+BIOS boot loader code, and executed if it conforms the specifications.
+This layout is called "El Torito Bootable CD-ROM Format Specification"
+and has been published by Phoenix and IBM. A copy of this spec is on
+Bochs tech specs page.
+
+
+El Torito specifies 3 ways to have a bootable CD:
+
+
+floppy emulation boot: A standard floppy image is burnt on the CD.
+In this case the BIOS has to redirect all first floppy accesses to this
+image and the real floppy drive becomes the second one.
+
+
+a "no emulation" boot: In this case the BIOS is instructed to load an
+arbitrary number of sectors straight into memory, and execute it.
+
+
+hard disk emulation: A hard disk image is burnt on the CD. The
+BIOS has to redirect all hard disk accesses to that image. The real hard disks
+are still available, with BIOS numbers 81h and up.
+
+
+
+In Bochs 2.0, hard disk emulation is not implemented in the BIOS.
+There are also subtilities about multiple boot-images CD-ROMs, that are
+not handled by Bochs.
+
+
+
+However, our BIOS may be more strict than real PC BIOSes, I don't know.
+But I would definitely be interested to know of any CD that can boot
+on real hardware, but does not in Bochs.
+
+
+
+When failing to boot from CD-ROM, the BIOS outputs
+the reason of the failure as
+an error code, in the log file, and on the screen.
+
+
+
+Here is a summary of what can happen when booting from the CD.
+
+
+
CD Boot error codes
+
+
+
+
+ Error code
+ Reason
+
+
+
+ 0x01 no atapi device found
+ 0x02 no atapi CD-ROM found
+ 0x03 cannot read cd - BRVD
+ 0x04 cd is not eltorito (BRVD)
+ 0x05 cd is not eltorito (ISO TAG)
+ 0x06 cd is not eltorito (ELTORITO TAG)
+ 0x07 cannot read cd - boot catalog
+ 0x08 boot catalog : bad header
+ 0x09 boot catalog : bad platform
+ 0x0A boot catalog : bad signature
+ 0x0B boot catalog : bootable flag not set
+ 0x0C cannot read cd - boot image
+
+
+
+
+
+
+0x01 no atapi device found
+0x02 no atapi CD-ROM found
+
+
+For the first two errors, an ata-*: type=cdrom is probably missing
+from the configuration file. This is what you get if no CD-ROM has
+been defined in Bochs conf file.
+
+
+
+
+0x03 cannot read cd - BRVD
+
+
+For this error, the CD-ROM support has not been compiled in Bochs,
+or Bochs could not open the file or device. This is what you get if
+Bochs is not able to read the cd.
+
+
+
+
+0x04 cd is not eltorito (BRVD)
+0x05 cd is not eltorito (ISO TAG)
+0x06 cd is not eltorito (ELTORITO TAG)
+
+
+For these errors, the data has been read from the cd, but
+the cd does not conform to the El Torito specification. This
+is what you get if the cd is not bootable.
+
+
+
+
+0x08 boot catalog : bad header
+0x09 boot catalog : bad platform
+0x0A boot catalog : bad signature
+0x0B boot catalog : bootable flag not set
+
+
+now the cd is eltorito, but the boot catalog is corrupted, or
+the cd was made to boot on a ppc system. This should not happen
+for a x86 bootable cd.
+
+
+
+
+0x07 cannot read cd - boot catalog
+0x0C cannot read cd - boot image
+
+here, specific part of the cd could not be read. This should
+definitely not happen.
+
+
+
+
+ Disk translation
+
+Since the beginning of the PC era, disks have grown in size by a factor of 10000. Due to
+differences between the ATA specification and BIOSes implementations, when disks reached
+critical sizes, it
+became necessary to translate the CHS geometry (cylinders, heads, sectors per track)
+between the BIOS (int 13h) and the ATA interface. Please refer to the
+ATA-FAQ
+and
+Hale Landis' document
+for a complete discussion of the problem.
+
+
+Unfortunately, there has never been any standard on the translation algorithms.
+
+
+Bochs implements 4 well-known algorithms, selectable in the configuration file
+in the "ataX-xxxx: ..., translation='algorithm'" section.
+
+
+
Disk translation algorithms
+
+
+
+ Algorithm
+ Maximum disk size
+ Maximum logical and physical geometry (CHS)
+ Description
+
+
+
+
+ none
+ 528MB (1032192 sectors)
+
+ LCHS:1024/16/63
+ PCHS:1024/16/63
+
+
+ no translation is done. The CHS received at the int13h interface
+ is sent as is to the ATA interface.
+
+
+
+ large
+ 4.2GB (8257536 sectors)
+
+ LCHS:1024/128/63
+ PCHS:8192/16/63
+
+
+ a standard bitshift algorithm (named Extended-CHS)
+ is used to translate the CHS between
+ the int13h interface
+ and the ATA interface. The translation is achieved by
+ multiplying/dividing the cylinder/head count by a power of 2
+ (2, 4 or 8).
+ (a factor of 16 could not be used because the
+ head count would become 256, and MS-DOS thought this was 0)
+ Note that the number of sectors per track is not changed, so
+ a lower spt value will lead to a lower maximum disk size.
+
+
+
+ echs
+
+
+ synonym for large
+
+
+ rechs
+ 7.9GB (15482880 sectors)
+
+ LCHS:1024/240/63
+ PCHS:15360/16/63
+
+
+ a revised bitshift algorithm (called Revised Extended-CHS)
+ is used to translate the CHS between
+ the int13h interface
+ and the ATA interface. First the number of physical heads is forced to
+ 15, and the number of cylinders is adjusted accordingly.
+ Then, as in the simple extended CHS algorithm, the translation
+ is achieved by
+ multiplying/dividing the cylinder/head count by a power of 2
+ (2, 4, 8 or 16).
+ The head count being forced to 15, it can safely be multiplied by 16
+ without crashing dos.
+ Note that the number of sectors per track is not changed, so
+ a lower spt value will lead to a lower maximum disk size.
+
+
+
+ lba
+ 8.4GB (16450560 sectors)
+
+ LCHS:1024/255/63
+ PCHS:16320/16/63
+
+
+ An LBA-assisted algorithm
+ is used to translate the CHS between
+ the int13h interface
+ and the ATA interface. The translation is achieved by
+ first computing the physical size of the disk (LBA=C*H*S).
+ Then the sectors per track is forced to 63, and the head count
+ to 255. Then the cylinder count is computed (C=LBA/(63*255))
+ Note that the number of sectors per track is forced to 63
+ in the logical geometry, regardless of the actual geometry
+ reported by the disk.
+ Also note that the LBA-assisted algorithm has nothing to do with
+ LBA access at the ATA interface.
+
+
+
+ auto
+
+
+ the best suited algorithm between none, large and lba is used
+
+
+
+
+
+
+Setting a specific CHS translation should be done if you use a disk dump
+of an actual disk, or use a real disk as a block device. You need to
+know which geometry was used to format the disk, and which translation
+was used. You must not set the translation to 'auto'.
+
+
+
+
+rechs translation should only be useful for Compaq users who wants to
+use a disk as a block device. Please report if you know any other
+system that uses such translation.
+
+
+
+
+If you plan to create a new disk image (for example with bximage),
+format it and install an OS on it, select the "auto" translation
+for an automatic selection
+of the best algorithm based on the disk image size. Be warned that an image created
+with the "auto" translation might not be readable with previous versions of Bochs.
+Upward compatibility will be maintained.
+
+
+
+
+This translation applies only to int13h BIOS disk accesses. Older OSes (e.g., MS-DOS)
+tend to use them a lot. On modern OSes, disk accesses through BIOS int13h are
+limited to boot loaders.
+The usual rules and tricks of the installed OS still apply (i.e., 1024 cylinders boot limit).
+
+
+
+
+
+
+How to enter special key combination
+
+Your window manager may trap the key combination you want to enter
+in Bochs guest OS, for example controlaltdelete. Here is a work-around:
+
+
+Press and hold controlalt,
+move your mouse cursor outside of the Bochs window. Release them, move
+the cursor back in the Bochs window and press delete.
+
+
+This should work for any key combination.
+
+
+If you need one key combination frequently, set it up as user key combination
+with the keyboard option in your
+configuration file. This key combination is sent to the guest OS when you press
+the user button in the headerbar.
+Depending on the used display_library option,
+it may even be possible to edit the shortcut before sending it.
+
+
+
+
+ Notes about VESA usage
+
+
+ Since Bochs 1.4 it is possible to use VESA graphics. There are some limitations in
+ the current implementation, but in general it should work ok (we have run several test
+ programs, the XFree86 VESA display driver, etc.)
+
+
+
+ In order to use VESA VBE, you need to enable it in your bochsrc by setting the
+ vga option to vbe.
+ Finally, you need to use the
+ LGPL'd VGABIOS
+ as vgaromimage option for
+ applications to correctly detect VESA support.
+
+
+
+ The VGABIOS is already included in the Bochs release, so no separate download is necessary.
+
+
+
+ To take advantage of the VBE, you must tell Bochs to use the LGPL'd VGA BIOS
+ version 0.4c or higher. A current version of the VGA BIOS will work.
+
+
+
+Current limitations:
+
+ 4bpp modes support is incomplete (8, 15, 16, 24 and 32bpp should work)
+ banked mode is very slow (if you can, just use Linear Frame Buffering instead!)
+ only 320x200, 640x400, 640x480, 800x600, 1024x768 are currently supported
+
+
+
+
+Interesting Facts:
+
+ You need a display driver capable of using the VESA BIOS for this to work
+ (a recent XFree86 will do, Windows 9x/NT/2K/XP probably will not work 'out of the box'.
+ Currently the VBE2 extension should be supported ok
+
+
+
+Instructions to setup Bochs VBE in Windows Guest OS
+This was contributed by Martin Bochnig in February 2004.
+
+Instructions for Win95/98:
+==========================
+I can only confirm that SciTech finally made a VBE driver
+for Windows. It works out of the box, at least with win95
+as guest OS, provided you use Bochs 2.1 with the LGPL
+vgabios.
+
+Here is how I did it :
+- install win95 with the vga driver.
+- download sdd 7 beta from
+- download pmhelp.vxd from
+- copy pmhelp.vxd to the win95 system directory
+- install sdd7
+
+800x600 and 1024x768 in 16 and 24 bpp modes here.
+I did not try 32bpp.
+
+
+This was contributed by Stanislav Shwartsman in September 2004.
+
+Instructions for Win2000/XP:
+============================
+
+Bochs VBE Display Drivers for Windows NT/2000
+
+
+
+
+
+
+ Notes about Cirrus SVGA usage
+
+
+ Since Bochs 2.2 it is possible to use Cirrus SVGA graphics. The Cirrus device
+ supports both ISA and PCI depending on the bochsrc settings.
+ If PCI is disabled or the Cirrus card is not assigned to a PCI slot, it appears
+ as a CL-GD5430 ISA with 2MB VRAM. If you assign the Cirrus card to a PCI slot,
+ it appears as a CL-GD5446 PCI with 4MB VRAM.
+
+
+ In order to use Cirrus SVGA, you need to compile Bochs using the
+ option and enable it in your bochsrc by setting the
+ vga option to cirrus.
+ Finally, you need to use the Cirrus version of the
+ LGPL'd VGABIOS
+ as vgaromimage option for
+ applications to correctly detect Cirrus support.
+
+
+ # Enable CL-GD5446 PCI
+ vga: extension=cirrus
+ vgaromimage: file=$BXSHARE/VGABIOS-lgpl-latest-cirrus
+ pci: enabled=1, chipset=i440fx, slot1=cirrus
+
+
+
+ The VGABIOS is already included in the Bochs release, so no separate download is necessary.
+
+
+
+
+ Notes about Voodoo Graphics usage
+
+
+ Bochs supports the emulation of 4 different 3dfx Voodoo Graphics adapter models.
+ The Voodoo1 and Voodoo2 models are 3D-only add-on cards and require a VGA
+ compatible primary device. The Voodoo Banshee and its successor Voodoo3 have
+ both a VGA core and a 2D/3D core, so no other VGA card is required. The 2D/3D
+ cards can be assigned to AGP if the i440BX chipset is selected (slot #5).
+
+
+ To emulate the Voodoo1 or Voodoo2 device only the "model" parameter of the
+ bochsrc option "voodoo" needs to be set. If the vga extension option is set
+ to "voodoo" in that case, the primary display adapter is an ISA VGA card.
+
+
+ For emulating the Voodoo Banshee or Voodoo3 adapter, the vga extension option
+ must be set to "voodoo". Using a different primary display adapter and a
+ Banshee compatible device with its VGA interface disabled is not
+ implemented yet. For both Banshee and Voodoo3 there is now a specific version
+ of the LGPL'd VGABIOS with Voodoo Banshee specific code called
+ VGABIOS-lgpl-latest-banshee. The binary file is compiled
+ for the Banshee PCI model, but Bochs modifies the VGABIOS data after loading
+ to support the Voodoo3 and AGP models properly.
+
+
+ These bochsrc settings should be used for Voodoo Banshee PCI:
+
+ vga: extension=voodoo
+ vgaromimage: file=VGABIOS-lgpl-latest-banshee
+ voodoo: model=banshee
+
+
+
+ This additional setting is required for Voodoo Banshee AGP:
+
+ pci: chipset=i440bx, slot5=voodoo
+
+
+
+ To support the Voodoo3 just change the model:
+
+ voodoo: model=voodoo3
+
+
+
+
+Disk Image Modes
+
+Bochs can handle independent disk image format for each
+disk present on the ata interfaces.
+
+The disk image type is selected in the configuration file
+by the "mode" option of the ataX-xxx directives.
+Example:
+
+
+ata0-master: type=disk, mode=flat, path=10M.sample, cylinders=306, heads=4, spt=17
+
+
+
+
+
+If unspecified, the default "mode" is flat.
+
+
+
+
+
Supported Disk Modes
+
+
+
+ Name
+ Description
+ Features
+
+
+
+ flat one file, flat layout
+
+ accessible with mtools or winimage-like tools
+
+
+ concat multiple files, concatenated
+
+ mappable to contained partitions
+
+
+ dll accessed through a DLL
+
+ developer specific, win32 / win64 only
+
+
+ sparse up to 10 layers stackable files
+
+ commitable, rollbackable, growing
+
+
+ vmware3 vmware3 disk support
+
+ vmware version 3 compatibility
+
+
+ vmware4 vmware4 disk support
+
+ vmware version 4 (VMDK) compatibility
+
+
+ undoable read-only base file with a commitable redolog
+
+ commitable, rollbackable
+
+
+ growing one growing file
+ growing
+
+
+ volatile read-only base file with a volatile redolog
+
+ always rollbacked
+
+
+ vpc VirtualPC disk support
+
+ fixed / dynamic size supported
+
+
+ vbox Oracle(tm) VM VirtualBox disk support
+
+ VDI version 1.1 fixed / dynamic size supported
+
+
+ vvfat local directory appears as VFAT disk (with volatile redolog)
+
+ optional commit or rollback
+
+
+
+
+
+
+
+flat
+
+
+description
+
+In flat mode, all sectors of the harddisk are stored in one flat file,
+in lba order.
+
+
+image creation
+
+Flat disk images can be created with the bximage utility
+(see for more information).
+
+
+path
+
+The "path" option of the ataX-xxx directive in the configuration file
+must point to the flat image file.
+
+
+external tools
+
+Flat images content can be accessed from the host by the
+following tools :
+
+ mtools (see )
+ mount with a loopback (see )
+ Winimage / DiskExplorer (see )
+ Bochs Tools (see )
+
+
+
+typical use
+
+Flat mode is Bochs default harddisk layout. This is also
+the layout of disk images provided on Bochs websites.
+
+
+limitations
+
+On some host OSes, Bochs flat disk images are limited to 2GiB.
+
+
+
+
+
+concat
+
+
+description
+
+In concat mode, all sectors of the harddisk are stored in several flat files,
+in lba order.
+
+
+image creation
+
+Disk images for the usage in 'concat' mode can be created as 'flat' mode image
+files with the bximage utility (see for more
+information).
+
+
+path
+
+The "path" option of the ataX-xxx directive in the configuration file
+must point to the first file (e.g. win95-1). The lower layer files names are
+found by adding 1 to the last character (e.g. win95-2, win95-3, etc.).
+
+
+external tools
+
+If every single file contains a complete partition, they can be accessed
+with same tools as the 'flat' mode images.
+
+
+typical use
+
+If the partition sizes and file sizes are set up correctly, this allows you to
+store each partition in a separate file, which is very convenient if you want
+to operate on a single partition (e.g. mount with loopback, create file system,
+fsck, etc.).
+
+
+limitations
+
+On some host OSes, there is a limit of 2GiB per file.
+
+
+
+
+dll
+
+
+description
+
+This mode is only useful for developers and needs an additional win32 / win64
+DLL loaded by Bochs at runtime.
+
+
+
+
+sparse
+
+
+description
+
+ Sparse disk support has been added by JustinSB. Sparse disk features are:
+
+
+
+ Large hard drive can be created, and only used space will be stored
+ in the file. In practice, on Unix, this is not a large gain as it is
+ done anyway.
+
+
+
+
+ Multiple sparse drive images can be mounted on top of each other.
+ Writes go to the top image. This allows several similar configurations
+ to share a master "base" file, and also allows file system rollback or
+ no-write options. Up to 10 disk images can be layered on top of each other.
+
+
+
+
+
+image creation
+
+Sparse disk images must be created with the bximage utility
+(see for more information).
+Be sure to enter "sparse" when selecting the image type.
+
+
+path
+
+The "path" option of the ataX-xxx directive in the configuration file
+must point to the top layered file. The lower layer files names are found by
+substracting 1 from the last character (must be a digit)
+
+
+external tools
+
+The bximage utility (see provides convert and
+resize support for "sparse" mode images.
+
+
+typical use
+
+ Space Saving
+
+ Create a sparse disk image using bximage. Set size to eg 10GB.
+ Only allocated space will be stored,
+ so your drive image should be only about as large as the files stored on it.
+
+
+
+
+ Disk Rollback
+
+
+
+
+ Create a sparse disk image called "c.img.0". Point .bochsrc at "c.img.0".
+ In Bochs, install your favorite OS. Switch off Bochs.
+
+
+
+
+ Create a sparse disk image (of the same size)
+ and name it "c.img.1". Point .bochsrc at "c.img.1"
+ "c.img.0" is visible, but all writes go to "c.img.1".
+ After using Bochs, you can simply delete
+ "c.img.1" to undo changes and go back to a clean OS install.
+
+
+
+
+
+
+
+ Disk Optional Commit
+
+
+
+
+ Create a sparse disk image called "c.img.0". Point .bochsrc at "c.img.0".
+ In Bochs, install your favorite OS. Switch off Bochs.
+
+
+
+
+ Create a sparse disk image (of the same size) and name it "c.img.1".
+ Point .bochsrc at "c.img.1"
+ "c.img.0" is visible, but all writes go to "c.img.1".
+ After using Bochs, if you want to keep the
+ changes, use the (currently non-existent) merge utility
+ to make a single unified drive image.
+
+
+
+
+ Alternatively, simply create a new partition on top called "c.img.2".
+
+
+
+
+
+
+
+ Common Base
+
+
+
+ Create a sparse disk image called "base.img". Point .bochsrc at "base.img".
+ In Bochs, install your favorite OS. Switch off Bochs.
+
+
+
+
+ Create a sparse disk image (of the same size) and name it "www.img.1".
+ Make "wwww.img.0" a symlink to
+ "base.img". Point .bochsrc at "www.img.1". Using Bochs, install a webserver.
+
+
+
+
+ Create a symlink to "base.img" called "db.img.0".
+ Create a sparse disk image (of the same size)
+ and name it "db.img.1". Point .bochsrc at "db.img.1".
+ Using Bochs, install a database server.
+
+
+
+
+
+ Now both a database server and webserver can be
+ run in separate virtual machines, but they share the common OS image,
+ saving drive space.
+
+
+
+
+limitations
+
+ There is a need for supporting utilities (yet unwritten) :
+
+
+ to merge two sparse disk images into a single image
+
+
+ to defragment a sparse disk image and remove unused space
+
+
+
+
+
+
+vmware3 / vmware4
+
+
+description
+
+Sharvil Nanavati has added vmware3/4 disk image support into Bochs
+for Net Integration Technologies, Inc.
+You should be able to use disk images created by vmware version 3 and 4.
+
+
+image creation
+
+Create such disk image with vmware version 3 or 4.
+
+
+path
+
+The "path" option of the ataX-xxx directive in the configuration file
+must point to the vmware3/4 disk image.
+
+
+external tools
+
+&FIXME; In addition to the utilities provided by VMware Inc. some other freeware
+tools are available.
+
+
+typical use
+
+If you want to use an existing vmware3/4 disk image.
+
+
+limitations
+
+Only vmware versions 3 and 4 disk image files are supported.
+
+
+
+
+undoable
+
+
+description
+
+ Undoable disks are commitable/rollbackable disk images.
+ An undoable disk is based on a read-only image, associated
+ with a growing redolog, that contains all changes (writes)
+ made to the base image content. Currently, base images of
+ types 'flat', 'sparse', 'growing', 'vmware3', 'vmware4' and
+ 'vpc' are supported.
+
+
+ This redolog is dynamically created at runtime, if it does not
+ previously exists.
+
+
+ All writes go to the redolog, reads are done from the
+ redolog if previously written, or from the base file
+ otherwise.
+
+
+ If unspecified with the "journal" option of the ataX-xxx directive,
+ the redolog file name is created by adding a ".redolog"
+ suffix to the base image name.
+
+
+ File size of the redolog can grow up to the total disk
+ size plus a small overhead due to internal data management
+ (about 3% for a 32MiB disk,
+ less than 0.5% for a 2GiB disk).
+
+
+ After a run, the redolog will still be present, so the changes
+ are still visible the next time you run Bochs with this disk image.
+
+
+image creation
+
+ The base disk images must be created with the bximage utility
+ (see for more information).
+ The redolog file is created automatically if it doesn't exist.
+
+
+path
+
+ The "path" option of the ataX-xxx directive in the configuration file
+ must be the base image name. The redolog name can be set with the "journal"
+ option of the same directive. If not set, the redolog name is created by
+ adding the ".redolog" suffix to the base image name.
+
+
+external tools
+
+ To access the 'flat' mode base disk image content,
+ see for available tools.
+
+
+
+ The up-to-date content can only be seen after you commit the redolog
+ to the flat file with the bximage utility.
+
+
+
+typical use
+
+Commit
+
+ After a run, the redolog can be committed (merged)
+ to the base image with the bximage utility.
+
+Rollback
+
+ After a run, the redolog can be rollbacked (discarded)
+ by simply deleting the redolog file.
+
+Common Base
+
+ One base disk image with a guest OS installed can be used to install
+ different software as described above for the "sparse" disk image mode.
+
+Harddisk Image on a Read-Only Medium
+
+ In the 'undoable' mode, the base file is always opened in read-only mode,
+ so it can safely be stored on a read-only medium (for example on a CD-ROM).
+ In that case it is recommended to specify the redolog file with the
+ "journal" option.
+
+
+
+limitations
+
+ The "undoable" disk depends on the limitations of base disk image used.
+
+
+
+
+growing
+
+
+description
+
+ Growing disk images start as small files, and
+ grow whenever new data is written to them.
+
+
+ Once a sector is
+ written in the growing file, subsequent writes to the same
+ sector will happen in place.
+
+
+ File size of Growing disk images can go up to the total disk
+ size plus a small overhead due to internal data management.
+ (about 3% for a 32MiB disk,
+ less than 0.5% for a 2GiB disk).
+
+
+image creation
+
+Growing disk images must be created with the bximage utility
+(see for more information).
+Be sure to enter "growing" when selecting the image type.
+
+
+path
+
+ The "path" option of the ataX-xxx directive in the configuration file
+ must be the growing image name.
+
+
+external tools
+
+ The bximage utility (see provides convert
+ and resize support for "growing" mode images.
+
+
+typical use
+
+ Growing disk images can be used whenever you want to maximize disk space.
+ However, please note that Bochs will not check if enough disk space is
+ available before writing new data. If no disk space is available, a panic
+ will occur.
+
+
+limitations
+
+ The size of the virtual disk is currently limited to 8 TB, but the maximum size
+ of the image file depends on host OS limitations.
+
+
+
+
+volatile
+
+
+description
+
+ Volatile disks are always-rollbacked disk images.
+ A volatile disk is based on a read-only image, associated with
+ a growing redolog, that contains all changes (writes)
+ made to the base image content. Currently, base images of
+ types 'flat', 'sparse', 'growing', 'vmware3', 'vmware4', 'vpc' and
+ 'vbox' are supported.
+
+
+ The redolog is dynamically created at runtime, when
+ Bochs starts, and is deleted when Bochs closes (win32)
+ or just after it has been created (Unix).
+
+
+ All writes go to the redolog, reads are done from the
+ redolog if previously written, or from the base file
+ otherwise.
+
+
+ If unspecified with the "journal" option of the ataX-xxx directive,
+ the redolog file name is created by adding a ".redolog"
+ suffix to the base image name.
+
+
+ File size of the redolog can grow up to the total disk
+ size plus a small overhead due to internal data management
+ (about 3% for a 32MiB disk,
+ less than 0.5% for a 2GiB disk).
+
+
+ After a run, the redolog is not any more present, so the changes
+ are discarded.
+
+
+image creation
+
+ The base disk images must be created with the bximage utility
+ (see for more information).
+ The temporary redolog file is created automatically.
+
+
+path
+
+ The "path" option of the ataX-xxx directive in the configuration file
+ must be the base image name. The redolog name can be set with the "journal"
+ option of the same directive.
+ If not set, the redolog name is created by adding the
+ ".redolog" suffix to the base image name.
+ A random suffix is also appended to the redolog name.
+
+
+external tools
+
+ To access 'flat' mode base disk image content,
+ see for available tools.
+
+
+typical use
+
+Repeatable simulations
+
+ &FIXME; to be completed
+
+Multiple Bochs instances
+
+ &FIXME; to be completed
+
+Harddisk Image on a Read-Only Medium
+
+ In the 'volatile' mode, the base file is always opened in read-only mode,
+ so it can safely be stored on a read-only medium (for example on a CD-ROM).
+ In that case it is recommended to specify the redolog file with the
+ "journal" option.
+
+
+
+limitations
+
+ The "volatile" disk depends on the limitations of base disk image used.
+
+
+
+
+vpc
+
+
+description
+
+ The "vpc" disk image mode is mostly a port of Qemu's "vpc" block
+ driver for VirtualPC disk images (written by Alex Beregszaszi and Kevin Wolf).
+
+
+image creation
+
+ Create such disk image with Microsoft VirtualPC (tm), Qemu's disk image
+ utility (qemu-img) or bximage utility
+ (see for more information).
+
+
+path
+
+ The "path" option of the ataX-xxx directive in the configuration file
+ must point to the VirtualPC disk image.
+
+
+external tools
+
+ Use Microsoft VirtualPC (tm) tools to manipulate these disk images.
+
+
+typical use
+
+ Share disk images with VirtualPC.
+
+
+limitations
+
+ The based on the Qemu code the disk size is limited to 127 GB.
+
+
+
+
+vbox
+
+
+description
+
+ The "vbox" disk image mode for VirtualBox disk images (VDI version 1.1)
+ has been written by Benjamin D. Lunt.
+
+
+image creation
+
+ Create such disk image with Qemu's disk image utility (qemu-img).
+
+
+path
+
+ The "path" option of the ataX-xxx directive in the configuration file
+ must point to the VirtualBox disk image.
+
+
+external tools
+
+ Use VirtualBox tools to manipulate these disk images.
+
+
+typical use
+
+ Share disk images with VirtualBox.
+
+
+limitations
+
+ &FIXME; to be completed
+
+
+
+
+vvfat
+
+
+description
+
+ The "vvfat" disk image mode is mostly a port of Qemu's "virtual VFAT" block
+ driver (written by Johannes E. Schindelin). It supports the read-only part
+ of this implementation plus some additions. The structures of the
+ virtual disk are created from the contents of the specified local directory
+ when Bochs is starting. All writes to this virtual disk go to a volatile
+ redolog and when closing Bochs, the user can decide whether or not to commit
+ the changes. If "No" is seclected, all changes will be lost when Bochs quits
+ and the files of the local directory are not modified. Otherwise, the changes
+ of files and directories are committed. WARNING: Don't use important data without
+ backup in the "vvfat" directory when using this "optional commit" feature.
+
+
+ In addition to Qemu's "vvfat" implementation the Bochs one supports configurable
+ disk geometry, FAT32 and reading MBR and/or boot sector from file. When using
+ the autodetection feature, the CHS values 1024/16/63 (Qemu defaults) are used.
+ To use an MBR image file from a real disk it must be named vvfat_mbr.bin
+ and placed in the specified directory. Bochs uses the geometry and file system
+ type from this file and doesn't show it on the virtual disk. The same applies
+ to a boot sector image file, but it must be named vvfat_boot.bin.
+ Using both image file is also possible if they match (grabbed from the same disk).
+
+
+ FAT32 is enabled for disk with minimum 2 GB size, or if MBR / boot sector image
+ enable this filesystem. When using "vvfat" for a floppy, FAT12 is used (1.44M
+ media only). In all other cases FAT16 is used. Long filename support
+ is always present.
+
+
+ Special FAT file attributes are stored in a special file named vvfat_attr.cfg.
+ When using the "optional commit" feature, modified attributes are saved to this file.
+ The "optional commit" also supports setting the file modification date and time.
+
+
+image creation
+
+ Not necessary. The directory must exist before running Bochs.
+
+
+path
+
+ The "path" option of the ataX-xxx directive in the configuration file
+ must point to an existing local directory. The redolog name can be set
+ with the "journal" option of the same directive. If not set, the redolog
+ name is created by adding the filename "vvfat.dir.redolog" to the path.
+ A random suffix is also appended to the redolog name.
+
+
+external tools
+
+ You can use your favourite file manager to copy file to the directory you'd
+ like to use. The directory should not be modified while Bochs is running.
+
+
+typical use
+
+ Accessing files of the host hard drive is only possible with vvfat.
+
+
+limitations
+
+ There is no runtime write support present yet. All changes are written to
+ the volatile redolog and they can only be committed on Bochs exit.
+
+
+ When using the MBR from image file only the first partition is used and it
+ must be of type FAT16 or FAT32. FAT12 can be used for the floppy only.
+ An extended partition or other file system types are not supported.
+
+
+ The "vvfat" implementation does not support save/restore, since there is no
+ check if the host directory tree and all files are unmodified after saving
+ the Bochs state.
+
+
+
+
+
+
+
+
+
+Using the bximage tool
+
+Bximage is an easy to use console based tool for creating, converting and
+resizing disk images, particularly for use with Bochs. It also supports
+committing redolog files to their base images. It is completely interactive
+if no command line arguments are used. It can be switched to a non-interactive
+mode if all required parameters are given in the command line.
+
+
+When you run bximage without one of the following options, it will appear in
+interactive mode and ask for all required parameters to manipulate an image.
+
+Usage: bximage [options] [filename1] [filename2]
+
+Supported options:
+ -func=... operation to perform (create, convert, resize, commit, info)
+ -fd=... create: floppy image with size code
+ -hd=... create/resize: hard disk image with size in megabytes (M)
+ or gigabytes (G)
+ -imgmode=... create/convert: hard disk image mode
+ -b convert/resize: create a backup of the source image
+ commit: create backups of the base image and redolog file
+ -q quiet mode (don't prompt for user input)
+ --help display this help and exit
+
+Other arguments:
+ filename1 create: new image file
+ convert/resize: source image file
+ commit: base image file
+ filename2 convert/resize: destination image file
+ commit: redolog (journal) file
+
+
+
+
+Disk image mode autodetection does not work for the modes concat
+and dll. To use those images as convert source, you have to
+add a prefix ("concat:" or "dll:") to the image path.
+
+Create image
+
+This function can be used to create several disk image formats for the
+use with Bochs. See the table above for supported formats (modes).
+For an example of the usage, refer to .
+
+
+Convert image
+
+With this function a disk image can be converted from one mode (format)
+to another. The type of the source image is auto-detected. For the target
+format it supports the same disk image modes as the create function. If the
+name of the new image file is not specified or identical to the source one
+and you have enabled the backup switch, a backup of the source file will be
+created with its original name plus the suffix ".orig".
+
+
+Resize image
+
+This function can be used to increase the virtual disk size of an image.
+It supports the same disk image modes as the create function.
+Making a disk image smaller is not supported, since it may damage the
+disk and data will be lost. If the name of the new image file is not
+specified or identical to the source one and you have enabled the backup
+switch, a backup of the source file will be created with its original name
+plus the suffix ".orig".
+
+
+Commit 'undoable' redolog to base image
+
+The type of the base image is auto-detected. The name of the redolog
+file only needs to be specified if it is not based on the base image.
+If you have enabled the backup switch, backups of the original base and
+redolog files will still be created with their original name plus the
+suffix ".orig".
+
+
+Disk image info
+
+This function can be used to determine the disk image format, geometry
+and size. Note that Bochs can only detect the formats growing, sparse,
+vmware3, vmware4, vpc and vbox correctly. Other images with a file size
+multiple of 512 are treated as flat ones. If the image doesn't support
+returning the geometry, the cylinders are calculated based on 16 heads
+and 63 sectors per track.
+
+
+
+
+
+
+
+Guest operating systems
+
+In the past several tweaks were necessary to install a guest OS inside of Bochs.
+Nowadays, it is almost the same as installing it on a real machine. There are only
+a few Bochs specific issues you should know about. Note that we cannot give you
+a full installation guide if you don't know how to install an OS in the real
+world. The following remarks apply to all guest OS installations. Some specific
+issues are reported in the next sections.
+
+
+First of all, you need the installation media or image (floppy/CD/DVD).
+For platforms that don't support raw device access it might be necessary to
+create an image from the media. Please read the message regarding software
+licenses in before you install or use a commercial
+guest operating system in Bochs.
+
+Then you need to create a hard drive image with bximage. For the
+required size see the documentation of the OS you'd like to install. See
+ how to create the image.
+
+Finally you have to create configuration for your guest OS. You can
+edit the sample configuration distributed with Bochs or use the configuration
+interface to adjust the settings. Check the documentation of your guest OS for
+the required memory size, cpu speed and supported hardware.
+
+
+Now you should be able to run Bochs and start the installation process. Depending
+on the host cpu speed and the size of the guest OS it can take a few minutes or
+even some hours.
+
+
+
+What disk images are available.
+What works
+Known problems
+
+
+
+
+ Knoppix
+
+
+ Contributed by Alexander Schuch.
+
+
+
+ Getting Knoppix
+
+
+ Knoppix is a live CD (700M) or live DVD (3.2G) based on Debian GNU/Linux, with lots of
+ ready-to-run programs (web browser, office suite, a few games, and more), using
+ KDE as desktop environment. It can be booted directly from CD, without
+ any installation needed. You can download it from knoppix.org.
+
+
+
+
+ Preparing Bochs
+
+
+ As Knoppix runs completely from CD/DVD, you don't need to setup a hard disk. You just need to set up
+ the location of the downloaded ISO image in your bochsrc, and make Bochs boot
+ from it. Because Knoppix contains a graphical user interface, and has no other storage space but
+ the emulated RAM, it needs at least 128MB of it, see
+ megs option. Furthermore, you need to enable VBE support in
+ Bochs (see ).
+
+
+
+
+ Using Knoppix
+
+
+ There is nothing more to do! Just start Bochs and wait for Knoppix to load...
+
+
+
+ You are logged in as normal user, if you want to become super user, just su.
+ There is no password needed (empty password).
+
+
+
+
+
+
+ FreeBSD 5.2.1
+
+
+ Contributed by Alexander Schuch.
+
+
+
+ This section describes how to install FreeBSD 5.2.1 (miniinst) inside of Bochs, using an ISO image.
+
+
+
+ Getting FreeBSD
+
+
+ As 5.2.1-RELEASE-i386-miniinst.iso (240M) is no longer available from
+ the FreeBSD FTP server, you might want to ask a (file) search engine of your choice
+ for a download location. Once you downloaded the file, you should check its integrity
+ using the provided MD5 checksum from the
+ FreeBSD 5.2.1 release announcement.
+
+
+
+
+ Preparing Bochs
+
+
+ Create a new hard disk image using bximage (see
+ ) with a size of at least 350M, as the standard
+ installation uses 280M on its own.
+
+
+
+ Next, you need to setup your bochsrc so that Bochs knows about your
+ (still empty) hard disk, as well as about your ISO image. Make Bochs boot from CD-ROM and
+ start the emulation.
+
+
+
+
+ Installing FreeBSD
+
+
+ This is just a very short step-by-step installation guide for FreeBSD in Bochs. It
+ doesn't explain what you do nor why you do it, it just tells you how to do it.
+ For in-depth information refer to the FreeBSD handbook:
+ Installing FreeBSD.
+
+
+
+ FreeBSD boots up and shows a nice (text-mode) boot option screen. Just press
+ return there, that is, use the default option. After loading the
+ kernel and needed device drivers, select 'Standard' in the installation menu.
+
+
+
+ A fdisk like partition program is loaded next, where you just press A
+ to use the entire disk, followed by Q to finish the selection. The next
+ dialog asks for the boot manager you want to use. Select 'Standard' and continue.
+
+
+
+ In the Disklabel Editor, you have to setup the layout of your partition. If your (virtual)
+ hard disk is large enough, you can press A for auto-layout. However, you
+ need to make sure that the /usr partition is at least
+ 250M large, or you will end up with a 'disk full' error message during installation. If
+ this is not the case, select one partition after another and press D to
+ delete it again. After you deleted all partitions, create two new ones. The first one will
+ be a swap partition; press C, enter '32M' as size and select 'Swap' from
+ the dialog. Press C again, and accept the remaining capacity for your
+ filesystem partition. Choose 'FS' as partition type and enter '/' (slash) as mount point.
+ Your partition layout is complete now; press Q to leave the editor.
+
+
+ This 'all-in-one' partition layout is not recommended for a FreeBSD installation on a
+ real box; use 'auto-layout' or something comparable to that there.
+
+
+
+
+ You now can choose what set of programs/files (distribution) you want to install. Take
+ 'User' (option 8), and select 'No' when asked to install the ports collection. You are
+ back in the distribution selection, where you select the first item, called 'Exit'.
+ Choose to install from 'CD/DVD' and answer the 'Are you sure?' dialog with 'yes'.
+
+
+
+ Now, while FreeBSD installs, it is a very good time to take a look at the
+ FreeBSD documentation, especially
+ the FreeBSD handbook
+ and the FreeBSD FAQ.
+
+
+
+
+ Post-installation configuration
+
+
+ All files are installed on your (virtual) hard disk now, and FreeBSD is ready for getting set
+ up. As this is a very basic FreeBSD installation, you just answer 'no' to nearly all questions,
+ but the one about your mouse: Answer 'yes' for PS/2 mouse, and choose 'Exit' at mouse configuration.
+ The minimalist FreeBSD ISO image contains nearly no binary packages, so don't browse the package
+ collection. Then, when asked to create a new user account, answer 'yes' and create a new user
+ called 'bochs' (or whatever you like). You might want to use /bin/csh
+ or /bin/tcsh as shell rather than /bin/sh. Next,
+ you are asked for the super user (root) password. The installation is finished now, there is
+ no need to visit the general configuration menu again - answer 'no' to that question. FreeBSD
+ will then reboot. Shutdown Bochs, as soon as the (virtual) computer boots.
+
+
+
+
+ Using FreeBSD
+
+
+ Open your bochsrc and change the boot sequence, so that Bochs will boot
+ from hard disk, rather than from CD-ROM from now on. Start Bochs again and watch the FreeBSD
+ boot process.
+
+
+
+ Your keyboard might use the wrong keymap, so login (into FreeBSD) as super user and use
+ /stand/sysinstall to start the FreeBSD configuration program. Choose
+ 'keymap' and select the keymap you want to use.
+
+
+
+ You have successfully installed FreeBSD now. You might want to shutdown FreeBSD using
+ shutdown -h now, quit Bochs, and create a backup of your hard disk
+ image, before you start playing around.
+
+
+
+
+ DOS
+Please read the message regarding software licenses in
+ before you install or use MS-DOS, DR-DOS, FreeDOS or
+any other DOS as a guest operating system in Bochs.
+Accessing your CD-ROM
+
+To access your CD-ROM in DOS, you must download an IDE CD-ROM driver.
+Bochs emulates a very generic CD-ROM drive, and several drivers are known to
+work. Others don't. This section describes how to set up your
+config.sys and autoexec.bat to enable
+the CD-ROM.
+
+
+
+The drivers that have been reported to work are
+OAKCDROM.SYS that comes with several versions of Windows
+and SBIDE.SYS version 1.21 from Creative
+Labs
+
+To get it, go to Creative Labs web
+site, click on Support, then click Download Files. You get to a screen
+where you must select the operating system and the product for which you want
+the driver. Choose DOS as the operating system, and "CD-ROM: 4x and above" as
+the product. There are several choices, but you want
+sbide121.exe from April 15, 1997. Version 2.0 does not
+work. The download file is a self-extracting ZIP file, so on
+DOS or Windows you just run it; on other platforms you can try using
+the unzip command. The driver is called SBIDE.SYS.
+.
+Copy the driver to your boot disk, and then set up the startup files as follows:
+
+
+config.sys:
+ device=himem.sys
+ device=oakcdrom.sys /D:CD001
+ -or-
+ device=sbide.sys /D:CD001 /P:1f0,14,3f6
+
+autoexec.bat:
+ mscdex.exe /M:10 /D:CD001
+
+
+
+If the files mentioned in config.sys and
+autoexec.bat are not in the root directory, give the full
+pathname, like c:\windows\himem.sys.
+
+
+
+SB16 driver for DOS
+
+To use the SB16 device in DOS you need to load a driver for it. The file
+SBBASIC.EXE contains a self-extracting archive with all required file.
+After unpacking it to C:\SB16 you can execute INSTALL.EXE
+to install the driver. The file DISK.ID should contain the version
+string SDR-31STD-1-US (Revision 1).
+
+
+Bootdisks of early DOS versions
+
+On the Web, there are bootdisks available for most of the DOS versions ever released,
+but some of them have been reported to fail in Bochs. The bootdisk for MS-DOS 1.25
+contains a boot sector of a newer DOS version, so it would fail on real hardware,
+too. The floppy image for MS-DOS 2.11 has a boot sector that tries to boot from
+hard disk instead of the floppy.
+
+
+
+
+
+ Windows 95
+Contributed by Benjamin David Lunt
+Please read the message regarding software licenses in before you install Windows 95 as a guest operating system in Bochs.
+
+Windows 95 has been reported to install from the CD-ROM, and run inside Bochs.
+Here are a few settings that seem to work well when running on a Windows10 host, running at 3.0Ghz.
+
+romimage: file=D:/path/to/your/bios/BIOS-bochs-latest
+cpu: model=broadwell_ult
+cpu: count=1, ips=50000000, reset_on_triple_fault=1, ignore_bad_msrs=1
+cpu: cpuid_limit_winnt=0
+clock: sync=realtime, time0=local
+memory: guest=512, host=512
+vgaromimage: file=D:/path/to/your/bios/VGABIOS-lgpl-latest-cirrus
+vga: extension=cirrus, update_freq=5
+pci: enabled=1, chipset=i440fx, slot1=cirrus
+
+
+
+
+
+ Windows 98SE
+Contributed by Benjamin David Lunt
+Please read the message regarding software licenses in before you install Windows 98 as a guest operating system in Bochs.
+
+Windows 98SE has been reported to install from the CD-ROM, and run inside Bochs.
+Here are a few settings that seem to work well when running on a Windows10 host, running at 3.0Ghz.
+
+romimage: file=D:/path/to/your/bios/BIOS-bochs-latest
+cpu: model=corei7_haswell_4770
+cpu: count=1, ips=55000000, reset_on_triple_fault=1, ignore_bad_msrs=1
+cpu: cpuid_limit_winnt=0
+clock: sync=realtime, time0=local
+memory: guest=512, host=512
+vgaromimage: file=D:/path/to/your/bios/VGABIOS-lgpl-latest-cirrus
+vga: extension=cirrus, update_freq=5
+pci: enabled=1, chipset=i440fx, slot1=cirrus
+
+
+
+
+
+ Windows NT 4.0
+
+Please read the message regarding software licenses in
+ before you install Windows NT 4.0 as a guest operating system in Bochs.
+
+
+Here are the known issues about installing and running Windows NT4.0 :
+
+
+
+
+If you want to use the LGPL'd VGABIOS to install Windows NT 4.0 you'll need
+version 0.4c or higher. With older versions you'll get a black screen after
+first reboot.
+
+
+
+
+to log in you must press ctrl-alt-del, and it is likely that the window manager
+will trap this key combination. You can either use the trick described in
+ or define a user short-cut
+(callable through the user short-cut GUI button)
+in you configuration file, for example:
+
+keyboard: user_shortcut=ctrl-alt-del
+
+
+
+
+
+For installing and using Windows NT it is necessary to limit the maximum CPUID
+to 3. In the configuration file you need to add a line like this:
+
+cpuid: cpuid_limit_winnt=1
+
+
+
+
+
+
+
+ Windows 2000 / Windows 2000 Server
+Please read the message regarding software licenses in
+ before you install Windows 2000 / Windows 2000 Server as a guest operating system in Bochs.
+
+
+
+
+
+ Windows XP
+Contributed by Benjamin David Lunt
+Please read the message regarding software licenses in
+ before you install Windows XP as a guest operating system in Bochs.
+
+Windows XP has been reported to install from the CD-ROM, and run inside Bochs.
+Here are a few settings that seem to work well when running on a Windows10 host, running at 3.0Ghz.
+
+romimage: file=D:/path/to/your/bios/BIOS-bochs-latest
+cpu: model=broadwell_ult
+cpu: count=1, ips=75000000, reset_on_triple_fault=1, ignore_bad_msrs=1
+cpu: cpuid_limit_winnt=0
+clock: sync=realtime, time0=local
+memory: guest=512, host=512
+vgaromimage: file=D:/path/to/your/bios/VGABIOS-lgpl-latest-cirrus
+vga: extension=cirrus, update_freq=5
+pci: enabled=1, chipset=i440fx, slot1=cirrus
+
+A known issue is to set the IPS value to less than 10,000,000 (minus the commas). WinXP doesn't
+run well at an IPS setting less than 10Mips.
+
+
+Also don't set it to more than 250,000,000. Anything faster and WinXP seems to stall within the CPU loop function. WinXP seems to work well with an IPS setting of 75,000,000 on a 3.0Ghz host.
+
+
+The 64-bit version of WinXP needs Bochs compiled with ACPI support even though you only set to one CPU.
+
+
+For some reason, writing to a USB disk in WinXP, where the write takes a little while, WinXP will think it is an error since it didn't complete fast enough, displaying the error. I don't know why.
+
+
+
+
+ Windows 7
+Contributed by Benjamin David Lunt
+Please read the message regarding software licenses in
+ before you install Windows 7 as a guest operating system in Bochs.
+Windows 7 has been reported to install from the CD-ROM, and run inside Bochs.
+Here are a few settings that seem to work well when running on a Windows10 host, running at 3.0Ghz.
+
+romimage: file=D:/path/to/your/bios/BIOS-bochs-latest
+cpu: model=broadwell_ult
+cpu: count=1, ips=100000000, reset_on_triple_fault=1, ignore_bad_msrs=1
+cpu: cpuid_limit_winnt=0
+clock: sync=realtime, time0=local
+memory: guest=1024, host=1024
+vgaromimage: file=D:/path/to/your/bios/VGABIOS-lgpl-latest-cirrus
+vga: extension=cirrus, update_freq=5
+pci: enabled=1, chipset=i440fx, slot1=cirrus
+
+
+
+Don't set it to more than 250,000,000. Anything faster and Win7 seems to be sluggish, but seems to work well with an IPS setting of 100,000,000 on a 3.0Ghz host.
+
+
+
+
+ Windows 8
+Contributed by Benjamin David Lunt
+Please read the message regarding software licenses in
+ before you install Windows 8 as a guest operating system in Bochs.
+Windows 8 has been reported to install from the CD-ROM, and run inside Bochs.
+Here are a few settings that seem to work well when running on a Windows10 host, running at 3.0Ghz.
+
+romimage: file=D:/path/to/your/bios/BIOS-bochs-latest
+cpu: model=broadwell_ult
+cpu: count=1, ips=150000000, reset_on_triple_fault=1, ignore_bad_msrs=1
+cpu: cpuid_limit_winnt=0
+clock: sync=realtime, time0=local
+memory: guest=2048, host=2048
+vgaromimage: file=D:/path/to/your/bios/VGABIOS-lgpl-latest-cirrus
+vga: extension=cirrus, update_freq=5
+pci: enabled=1, chipset=i440fx, slot1=cirrus
+
+
+
+Don't set it to more than 250,000,000. Anything faster and Win8 seems to be sluggish, but seems to work well with an IPS setting of 150,000,000 on a 3.0Ghz host.
+
+
+
+
+ Windows 10
+Contributed by Benjamin David Lunt
+Please read the message regarding software licenses in
+ before you install Windows 10 as a guest operating system in Bochs.
+Windows 10 has been reported to install from the CD-ROM, and run inside Bochs, though a few hacks where used to do so. For more information, see this thread.
+
+
+I used another emulator to successfully install Windows 10. Then using Bochs, after a considerable amount of time and a few reboots, I finally got Win10 to boot and load in Bochs.
+
+
+Here are the settings I used when running on a Windows10 host, running at 3.0Ghz.
+
+romimage: file=D:/path/to/your/bios/BIOS-bochs-latest
+cpu: model=corei7_sandy_bridge_2600k
+cpu: count=1, ips=325000000, reset_on_triple_fault=1, ignore_bad_msrs=1
+cpu: cpuid_limit_winnt=0
+clock: sync=realtime, time0=local
+memory: guest=2048, host=2048
+vgaromimage: file=D:/path/to/your/bios/VGABIOS-lgpl-latest-cirrus
+vga: extension=cirrus, update_freq=5
+pci: enabled=1, chipset=i440fx, slot1=cirrus
+
+
+
+If you use an IPS value less than 325,000,000, Win10 will BSOD and want you to reboot (Assuming a host at 3.0Ghz).
+
+
+
+
+SCO OpenServer 5.0.5
+
+Contributed by Carl Sopchak
+
+
+
+Please read the message regarding software licenses in
+ before you install SCO OpenServer 5.0.5 as a guest operating system in Bochs.
+
+
+
+Back in April and May of 2002, I did some work on Bochs
+in order to get it to install and boot SCO's OpenServer 5.0.5 (OSR5).
+Since that time, I have had several e-mails asking about this error message
+or that. The newsgroup posts done at the time had all of the information that I knew,
+so I pointed people there. (I had not used Bochs since...)
+In February of 2003, I got another such e-mail.
+Since the sender indicated they were willing to pay me to get this going for them,
+I agreed to spend a few hours on it (for free, which is not common :-}). Subsequently,
+I decided to document this once and for all. (I did not charge anyone anything, this time...)
+
+
+
+Note: These steps were originally used with Bochs 1.4.1 (or thereabouts,
+since I was using CVS heavily at the time). It is possible (likely) that later versions of Bochs
+are more tolerant/bug free, and this install may be abbreviated. However, I have not tried
+to streamline it at all.
+
+
+
+These steps were performed and confirmed using Bochs version 2.0.2, and SCO OpenServer version 5.0.5.
+The host OS was Red Hat Linux 8.0.
+
+
+
+First, I downloaded the tarball, and extracted the source tree. I decided to use the tarball
+instead of the RPM so that I knew what options were compiled in, etc.
+
+linux-$ tar -xzvf bochs-2.0.2.tar.gz
+
+
+
+
+Next, I configured and compiled Bochs...
+
+linux-$ cd bochs-2.0.2
+linux-$ ./configure --enable-cdrom --enable-ne2000
+linux-$ make
+
+
+
+
+I then created my disk image:
+
+linux-$ ./bximage
+========================================================================
+ bximage
+ Disk Image Creation Tool for Bochs
+========================================================================
+
+Do you want to create a floppy disk image or a hard disk image?
+Please type hd or fd. [hd] hd
+
+What kind of image should I create?
+Please type flat, sparse or growing. [flat]
+
+Enter the hard disk size in megabytes, between 1 and 8257535
+[10] 2048
+
+I will create a hard disk image with
+ cyl=4161
+ heads=16
+ sectors per track=63
+ total sectors=4194288
+ total size=2047.99 megabytes
+
+What should I name the image?
+[c.img] hd0.img
+
+Writing: [] Done.
+
+I wrote 2147475456 bytes to hd0.img.
+
+The following line should appear in your .bochsrc:
+ ata0-master: type=disk, path="hd0.img", cylinders=4161, heads=16, spt=63
+
+
+
+
+I then created my .bochsrc file. I did this via the interactive portion of Bochs, with the
+end result as follows:
+
+floppya: 1_44="/dev/fd0", status=inserted
+floppyb: 1_44="b.img", status=inserted
+ata0: enabled=1, ioaddr1=0x1f0, ioaddr2=0x3f0, irq=14
+ata0-master: type=disk, path="hd0.img", cylinders=4161, heads=16, spt=63, translation=auto, biosdetect=auto, model="Generic 1234"
+ata0-slave: type=cdrom, path="/dev/cdrom", status=inserted, biosdetect=auto, model="Generic 1234"
+ata1: enabled=0
+ata2: enabled=0
+ata3: enabled=0
+romimage: file=bios/BIOS-bochs-latest
+vgaromimage: file=bios/VGABIOS-lgpl-latest
+megs: 64
+parport1: enabled=1, file="lp.pipe"
+com1: enabled=0
+# no sb16
+boot: cdrom
+floppy_bootsig_check: disabled=0
+vga: update_freq=5
+keyboard_serial_delay: 250
+keyboard_paste_delay: 100000
+cpu: ips=3000000
+clock: sync=realtime, time0=0
+mouse: enabled=0
+private_colormap: enabled=0
+pci: enabled=0
+# no ne2k
+# no loader
+log: osr5.log
+logprefix: %t-%e-%i%d
+debugger_log: -
+panic: action=ask
+error: action=report
+info: action=report
+debug: action=ignore
+keyboard: type=mf, keymap=, user_shortcut=none
+config_interface: textconfig
+display_library: x
+
+Some important things to note are that you want to boot from the CD-ROM, and you do NOT want the ne2000
+card configured initially. (We'll add that later...)
+
+
+
+At this point, Bochs is ready to roll! Insert the OSR5 install CD into the drive, and start Bochs.
+You should soon see the SCO "boot:" prompt:
+
+SCO OpenServer(TM) Release 5
+
+boot
+: defbootstr disable=fdi,dptr
+
+
+Note the disable= parameter that you need. These two SCO drivers cause the install to fail, so they
+need to be disabled for the install boot. You will not need this once OSR5 is installed.
+
+
+
+During the install of OSR5, there are two default configuration answers that need to be changed.
+For the hard disk setup, you should turn bad tracking off, since it's unnecessary on an emulated disk.
+(It won't hurt to do it, it will just take a VERY long time!)
+For the network setup, change the network card to Deferred. You can change other settings, if you so
+desire. However, I would do the initial install with as little configured as you can get away with, then
+add whatever else is needed (one step at a time) after the initial install completes.
+
+
+
+Let the install copy the files. Go get lunch. Take a nap. Go have dinner...
+This can take a LONG time. On my Pentium 4 1.7GHz system, this
+step took just over eight hours! (BTW, it was MUCH longer in version 1.4.1. Great job, guys!)
+
+
+
+After the install finishes, you will need to change the following lines in .bochsrc file:
+
+ne2k: ioaddr=0x300, irq=10, mac=b0:c4:20:00:00:00, ethmod=linux, ethdev=eth0
+boot: disk
+
+Obviously, if you're not using Linux, the ethmode and ethdev values on the ne2k line will be different.
+Also, since Bochs uses "raw" network card access, you'll have to "setuid root" on the Bochs executable:
+
+linux-$ chown root bochs
+linux-$ chmod u+s bochs
+
+(If there is a way to give a "normal user" CAP_NET_RAW capability, that would be an alternative.
+I don't know how to do that...)
+Restart Bochs. Now, you can just press Enter at the OSR5 boot: prompt, because the offending
+drivers have been linked out of the kernel.
+
+
+
+Before you configure the network card, I'd strongly suggest getting the latest "nat" driver from SCO.
+Version 5.0.5b of this driver, according to the SCO web site, "correct[s] possible system lockup
+under high load due to internal buffer overflow." The driver can be found
+here.
+To get the Disk Image file into SCO, I downloaded the VOL.000.000 file to my linux box,
+and used tar to get it on to a floppy:
+
+linux-$ tar -cvf /dev/fd0 VOL.000.000
+
+I then used tar within OSR5 to move it from the floppy to the /tmp directory:
+
+osr5-# cd /tmp
+osr5-# tar -xvf /dev/fd0135ds18
+
+You can then use 'custom' to install the driver from the image file.
+You will then want to use 'scoadmin network' to configure the network card. Choose
+the Novell NE2000 card, and set the parameters to match the ne2k: line in the .bochsrc file.
+DO NOT have OSR5 look for the card, as Bochs may likely crash. (It did in version 1.4.1.)
+
+
+
+You can also configure a printer, if you want. Using the spoolpipe utility that I wrote
+(which can be found in Bochs' misc directory), you can print from OSR5 through the parallel
+port, and you'll hardly notice
+that the printing is going through an extra layer of operating system!
+(You could also set up a printer using network printing, if the printer is not on the host machine...)
+
+
+
+Obviously, don't forget to apply the release supplements and other patches that are considered
+"must haves" for OSR5: rs505a, oss600a, oss497b (others?).
+
+
+
+That's about as far as I have got. I played around with OSR5 within Bochs a bit, but I
+can by no means say that I did any kind of real testing, let alone exhaustive testing.
+
+
+
+And of course, YMMV! :-)
+
+
+
+
+
+
+
+