<!--================================================================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, orAMD64 CPU, including optional MMX, SSE, SSE2 and 3DNow! instructions.Bochs interprets every instruction from power-up to reboot, and hasdevice models for all of the standard PC peripherals: keyboard, mouse,VGA card/monitor, disks, timer chips, network card, etc.  Because Bochssimulates the whole PC environment, the software running in the simulation"believes" it is running on a real machine.  This approach allows Bochsto run a wide variety of software with no modification, include most popularx86 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 runon many different host platforms<footnote><para>Since Bochs can run on one kind of machine and simulate another machine, wehave to be clear in our terminology to avoid confusion.  The host platform isthe machine that runs the Bochs software.  The guest platform is the operatingsystem and applications that Bochs is simulating.</para></footnote>, including x86, PPC, Alpha, Sun, and MIPS.  No matter what thehost platform is, Bochs still simulates x86 software.  In other words, itdoes 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 betweenBochs and many other x86 emulation software such as plex86, VMware, etc.Because Bochs uses software simulation for every single x86 instruction, itcan simulate a Windows application on an Alpha or Sun workstation.  However,the downside of Bochs' approach is simulation performance.  To model theprocessor accurately, Bochs must run many instructions for every simulated x86instruction, and this makes the simulated machine many times slower thanthe physical machine.  Commercial PC emulators (VMware, Connectix, etc.) canachieve much high emulation speed using a technique called virtualization<footnote><para>Virtualization takes advantage of simulating x86 instructions on anx86 machine, allowing large portions of the simulation to take placeat native hardware speed.  Whenever the simulated machine talks to thehardware or enters certain privileged modes (such as in kernel code),the simulator typically takes control and simulates that code insoftware at much slower speed, just like Bochs does.</para></footnote>, but they are neither portable to non-x86 platforms nor opensource.  The <ulink url="http://savannah.nongnu.org/projects/plex86">Plex86</ulink> project isworking toward an open-source x86 simulator with virtualization.</para><para>To do anything interesting in the simulated machine, Bochs needs to interactwith the operating system on the host platform (the host OS).  When you press akey in the Bochs display window, a key event goes into the device model for thekeyboard.  When the simulated machine needs to read from the simulated harddisk, Bochs reads from a disk image file on the host machine.  When thesimulated machine sends a network packet to the local network, Bochs uses thehost platform's network card to send the packet out into the real world.  Theseinteractions between Bochs and the host operating system can be complicated,and in some cases they are host platform specific.  Sending a network packet inFreeBSD requires different code than sending the packet in Windows 95, forexample.  For this reason, certain features are supported on some hostplatforms and not others.  On GNU/Linux, Bochs can simulate a network card thatcommunicates with the world, but on BeOS the simulated network card may notwork because the communication code between the device model and the BeOSoperating 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 beinteresting to know how much Bochs used to cost and what it was used for.  Ithought I saw an interview out there somewhere where Kevin says why he startedit 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 Mandrakesoftto do plex86 at the same time as Bochs was bought?  In his linux.com interviewKevin said: "The only way I can move Bochs to open source is if someonesponsors that happening. That would be ideal, and would enable me to focus moreon Bochs and FreeMWare, rather than be sidetracked with related consultingjobs."The last version of Bochs that he released was 3/25/2000, three days after theMandrake press release.-->In March 2001, Kevin helped a few developers to move all Bochs activities frombochs.com to a new site at bochs.sourceforge.net.  Since then the Bochs projecthas settled into its new home, and around release times has even hit #1 mostactive 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 aregular basis, but a few statistics give an indication.  The <linklinkend="bochs-developers">bochs-developers mailing list</link>, which is theprimary source of news on bugs and releases, has over 400 subscribers.  Thelatest version has been downloaded over 150,000 times from SourceForge, notcounting 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 commonuses.  Also, because every hardware instruction and every line of simulatorcode is accessible, Bochs is used extensively for debugging new operatingsystems.  If you were writing boot code for your home-brewedx86 operating system and it didn't work right, booting it in Bochs couldgive you great visibility into what is really going on.  The Bochs debugger lets you simulate quickly or slowly, pausing whenever you wantto 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 useBochs 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 whichstudents used and modified it to learn how the PC hardware works.  As a finalproject the students had to add a new peripheral device, so they had to learnall about I/O ports, interrupts, and device drivers.  In industry, it is usedto support legacy applications on modern hardware, and as a reference modelwhen 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 yourWindows 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 forrunning x86 software.  Bochs has been known to work on Solaris (Sparc), GNU/Linux (PowerPC/Alpha), MacOS (PowerPC), IRIX (MIPS), BeOS (PowerPC), DigitalUnix (Alpha), and AIX (PowerPC).</para><para>You can also find more detailed testing information on the testingstatus page on the &bochswebsite;.  <!-- DISABLED: testing status page has been removed because it was so out ofdate...  The testing status page tells which combinations of host platform andguest 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 theGNU Lesser General Public License<footnote><para>Complete text of the GNU LGPL is included with the source code in a filecalled COPYING, and is also <ulink url="http://www.gnu.org/licenses/lgpl.html">here</ulink>.</para></footnote>.  The following text appears at thetop 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 packagewithin the Bochs PC emulation environment, make sure you are and will be incompliance with all the software licenses pertaining to the software you wishto install.  It is completely your responsibility to provide licenses and recordson all software that you install and/or use.  It is also completely your responsibility tomaintain 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