The Bochs IA-32 Emulator Project
Linux Documentation


This file is an introduction to Bochs, written for Linux users. It assumes that you have just downloaded a Bochs binary distribution, and now you want to see it work!

Contents
Where is the most recent version?
All versions of Bochs can be downloaded from the Bochs website at http://bochs.sourceforge.net . In the top-left corner of the web page, there is a link to the latest release. On the web site, in addition to downloading Bochs, you can join the bochs-developers or bochs-announce mailing lists, submit bug reports, view the source code, and much more.

What files were installed?
When you install a Bochs RPM for Linux, you get the Bochs executables and tools, ROM image files, documentation, and a sample disk image that allows Bochs to boot Linux. Here is a list of the files that are installed by the RPM, and a brief description of each one. The files which can be viewed in text form are shown as links.
File name Description
@prefix@/share/doc/bochs/README the ReadMe file from the source distribution.
@prefix@/share/doc/bochs/COPYING copy of the LGPL license
@prefix@/share/doc/bochs/DOC-linux.html this file
/usr/man/man1/* man pages for bochs, bochs-dlx and bximage
/usr/man/man5/* man page for bochsrc
@prefix@/share/doc/bochs/docs-html/* a local copy of all Bochs documentation ( Online copy )
@prefix@/share/doc/bochs/CHANGES what is changed between versions
@prefix@/share/bochs/BIOS-bochs-latest ROM BIOS image for Bochs
@prefix@/share/bochs/VGABIOS-elpin-2.40 VGA BIOS image for Bochs
@prefix@/share/bochs/VGABIOS-elpin-LICENSE license for VGA BIOS
@prefix@/share/doc/bochs/bochsrc-sample.txt sample Bochs configuration file
@prefix@/bin/bochs the main Bochs executable (This is actually a symbolic link to @prefix@/bochs/@VERSION@/bochs)
@prefix@/bin/bximage tool for making new disk images (This is actually a symbolic link to @prefix@/bochs/@VERSION@/bximage)
@prefix@/bin/bochs-docs script to start up browser with this page
@prefix@/bin/bochs-dlx run this script to try out DLX Linux inside Bochs!
@prefix@/share/bochs/dlxlinux/ directory containing DLX linux sample disk image
@prefix@/share/bochs/dlxlinux/README description of DLX linux
@prefix@/share/bochs/dlxlinux/bochsrc.txt Bochs configuration file for DLX
@prefix@/share/bochs/dlxlinux/hd10meg.img disk image file (10 meg)
@prefix@/share/bochs/dlxlinux/testform.txt Form for reporting success or failure

How can I try out Bochs in 10 minutes or less?
This RPM package includes a sample disk image containing DLX Linux, which you can boot within Bochs. To start up DLX linux, just type "bochs-dlx" in an xterm. This will create a Bochs Display window, and print some log messages into the xterm. The display window is the most interesting, but if something goes wrong the log messages should give an idea of what has happened.

One common problem in X windows is that the screen colors can be abnormal if other X programs have already allocated all the colors. (This assumes that you are in 8-bit color mode.) If the colors don't look right, try quitting netscape, clearing any complex images in the background, etc. so that Bochs has a chance to allocate the colors it needs.

Meanwhile, the Bochs display screen looks like a PC booting, and in fact it is! Bochs begins simulating a PC from the time the power turns on. You will see the VGA BIOS message, and it begins loading Linux from the disk image. (The disk image is just a big file that Bochs uses as if it were a real hard drive.) After a while, you see Linux boot messages and eventually a login prompt. You are now running DLX Linux in a window!

Bochs simulates every instruction of an x86 CPU, so it is very memory- and compute-intensive. The speed of your real CPU will make a big difference in how fast the DLX Linux image boots. On a 750MHz Pentium, the sample Linux image takes about 25 seconds to boot.

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 image, so it lets you log in immediately. 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:/# _

One thing you may notice is that the screen saver turns on (screen goes blank) very quickly when you have stopped typing. The reason is that Bochs always simulates 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.

When you get tired of playing with DLX Linux, just type "reboot" in the Bochs window to shut down the DLX Linux operating system. You can also press the "Power" button to stop the simulation.

In this brief introduction you saw how Bochs can boot and run an x86 operating system in a window. It doesn't have to be Linux, of course! Various people have been able to install and run DOS, Windows 3.1, Windows 95, Windows 98, Windows NT, Linux, FreeBSD, NetBSD, OpenBSD, and probably others that we've never even heard of. In fact Bochs is used by many operating system developers to test out their software in a controlled environment without having to reboot their development machine.


What tools are included in this package?
Other than the bochs binary, there is a disk image creation tool called bximage, a script called bochs-docs which calls up this page in a browser, and a script called bochs-dlx which makes it easy to start up DLX Linux.

bochs-dlx
This script makes it quick and easy to start up DLX Linux within bochs. "bochs-dlx" should run as soon as you install the RPM. All the script actually does is to cd into @prefix@/bochs/dlxlinux and then run bochs from there.

bochs-docs
The bochs-docs script starts up your web browser and points it to this HTML file. If you don't have netscape installed, you will have to edit the BROWSER variable in bochs-docs to make it work.

bximage
Bximage is a small program that helps to create empty floppy disk and hard disk images. To use it, you should run bximage in an xterm. Just CD to the directory where you want the disk images to go, and run bximage. Bximage will ask you some questions about what type of disk image you need, and then create one for you.

Here is an example run of bximage, in which I made a 12-meg hard disk image called c.img. The default answer to a question is always printed in brackets. If you want to accept the default choice, you can just press return. Also, you can always quit bximage by pressing Control-C. 

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] 

Enter the hard disk size in megabytes, between 1 and 32255
[10] 12

I will create a hard disk image with
  cyl=24
  heads=16
  sectors per track=63
  total sectors=24192
  total size=11.81 megabytes

What should I name the image?
[c.img] 

Writing: [............] Done.

I wrote 12386304 bytes to c.img.

The following line should appear in your bochsrc:
  diskc: file="c.img", cyl=24, heads=16, spt=63


In order for Bochs to know to use the hard disk image, you should type the diskc line into your bochsrc.txt. You can also change it to diskd if you already have a diskc line, but be careful not to have both diskd and cdromd--these options cannot be used together.


Where can I learn more?
Here are some sources of more information about Bochs: