user.dbk

Bochs is a highly portable open source IA-32 (x86) PC emulator written in C++, that runs on most po

<!--
================================================================
doc/docbook/user/user.dbk
$Id: user.dbk,v 1.175.2.1 2005/07/07 07:25:32 vruppert Exp $

This is the top level file for the Bochs Users Manual.
================================================================
-->

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [

<!-- include definitions that are common to all bochs documentation -->
<!ENTITY % bochsdefs SYSTEM "../include/defs.sgm">
%bochsdefs;

]>

<book>
<bookinfo>
   <title>Bochs User Manual</title>
   <authorgroup>
   <author><firstname>Kevin</firstname><surname>Lawton</surname></author>
   <author><firstname>Bryce</firstname><surname>Denney</surname></author>
   <author><firstname>N. David</firstname><surname>Guarneri</surname></author>
   <author><firstname>Volker</firstname><surname>Ruppert</surname></author>
   <author><firstname>Christophe</firstname><surname>Bothamy</surname></author>
   <editor><firstname>Michael</firstname><surname>Calabrese</surname></editor>
   </authorgroup>
</bookinfo>

<!-- *************************************************************** -->
<chapter id="introduction"><title>Introduction to Bochs</title>
<section id="whatisbochs"><title>What is Bochs?</title>
<para>
Bochs is a program that simulates a complete Intel x86 computer.  It 
can be configured to act like a <!--286,--> 386, 486, Pentium, Pentium Pro, or
AMD64 CPU, including optional MMX, SSE, SSE2 and 3DNow! instructions.
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, all Linux flavors, all BSD flavors,
and more.
</para>

<para>
Bochs is written in the C++ programming language, and is designed to run
on many different host platforms<footnote>
<para>
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.
</para>
</footnote>, including x86, PPC, Alpha, Sun, and MIPS.  No matter what the
host platform is, Bochs still simulates x86 software.  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 plex86, 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<footnote>
<para>
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.
</para>
</footnote>, but they are neither portable to non-x86 platforms nor open
source.  The <ulink url="http://savannah.nongnu.org/projects/plex86">Plex86</ulink> project is
working toward an open-source x86 simulator with virtualization.
</para>

<para>
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 95, 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 BeOS the simulated network card may not
work because the communication code between the device model and the BeOS
operating system has not been written.
</para>

<para>
<!-- really more like Background or Bochs History, but maybe it doesn't need its own section unless it gets to 3 paras or so  -->

Bochs was written by Kevin Lawton starting in 1994.  It began as a 
commercial product, which you could buy with source code for ...
&NEEDHELP; <footnote>
<para>
We need a Bochs historian to help out here.  For background, it would be
interesting to know how much Bochs 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.
</para>
</footnote> Finally, in March 2000, MandrakeSoft (now called
<ulink url="http://www.mandriva.com/">Mandriva</ulink>) bought Bochs
(<ulink url="http://www.linux-mandrake.com/en/announce-bochs-20000323.php3">press release</ulink>)
and made it open source under the GNU LGPL.

<!-- 
we should make it clear that Kevin is not the primary maintainer of Bochs,
but I want to get some more background.  Did he get hired by Mandrakesoft
to do plex86 at the same time as Bochs was bought?  In his linux.com interview
Kevin said: "The only way I can move Bochs to open source is if someone
sponsors that happening. That would be ideal, and would enable me to focus more
on Bochs and FreeMWare, rather than be sidetracked with related consulting
jobs."

The last version of Bochs that he released was 3/25/2000, three days after the
Mandrake press release.
-->
In March 2001, Kevin helped a few developers to move all Bochs activities from
bochs.com to a new site at bochs.sourceforge.net.  Since then the Bochs project
has settled into its new home, and around release times has even hit #1 most
active project of the week at SourceForge.
</para>
</section><!-- end: What is Bochs? -->

<section id="who-uses-bochs"><title>Who uses Bochs?</title>
<para> 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 <link
linkend="bochs-developers">bochs-developers mailing list</link>, 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 CVS users.
</para>

<para>
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.
</para>

<para>
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.  
</para>

<para>
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.
</para>

</section>  <!-- end of Introduction:Who uses Bochs? section -->


<section id="is-bochs-right-for-me"><title>Is Bochs right for me?</title>
<para>
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?"
</para>

<para>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, Plex86, Wine, and 
VMware might be your best options.</para>

<para>
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.
</para>

<para>
Perhaps your objective is to debug software or hardware drivers.  Bochs offers a controlled 
environment that can better assist you in determining cause and effect relationships.  
You can take snapshots that show you what is going on behind the scenes.  
You can isolate the line that caused that crash.  You can have multiple 
images and compare them under a microscope.  
In these situation, Bochs could save you time and resources.
</para>

<para>
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.
</para>

</section>  <!-- end of Introduction:Is Bochs right for me? section -->

<section id="will-it-work-for-me"><title>Will it work for me?</title>

<para>
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 gui or 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.
</para>

<para>Bochs will run on Windows, GNU/Linux, FreeBSD, OpenBSD, or BeOS.  
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, plex86).
</para>

<para>
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), BeOS (PowerPC), Digital
Unix (Alpha), and AIX (PowerPC).
</para>

<para>
You can also find more detailed testing information on the testing
status page on the &bochswebsite;.  
<!-- DISABLED: testing status page has been removed because it was so out of
date...  The testing status page tells which combinations of host platform and
guest platform have been tried by other Bochs users. -->
</para>

</section>  <!-- end of Introduction:Will it work for me? section -->

<section id="license"><title>Bochs License</title>
<para>
Bochs is copyrighted by MandrakeSoft S.A.<footnote>
<para>
MandrakeSoft has web sites at
<ulink url="http://mandrakesoft.com">http://mandrakesoft.com</ulink> and
<ulink url="http://www.linux-mandrake.com">http://www.linux-mandrake.com</ulink>.
</para>
</footnote>
and distributed under the
GNU Lesser General Public License<footnote>
<para>
Complete text of the GNU LGPL is included with the source code in a file
called COPYING, and is also <ulink url="http://www.gnu.org/licenses/lgpl.html">here</ulink>.
</para>
</footnote>.  The following text appears at the
top of every source code file in the Bochs distribution:
<programlisting>
  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., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
</programlisting>

</para>

</section>  <!-- end of Introduction: Bochs License section -->

<section id="thirdparty"><title>Third Party Software Licensing and Temporary Files</title>

<para>
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.
</para>

<para>
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