Bochs/bochs/doc/docbook/user/user.dbk

<!--
================================================================
doc/docbook/user/user.dbk
$Id: user.dbk,v 1.50 2002-11-03 20:05:02 ndavidg 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>
   <editor><firstname>Michael</firstname><surname>Calabrese</surname></editor>
   <editor><firstname>Vasudeva</firstname></editor>
   <editor><firstname>N. David</firstname><surname>Guarneri</surname></editor>
   </authorgroup>
</bookinfo>

<!-- *************************************************************** -->
<chapter><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, or Pentium Pro.
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 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, 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's 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.  <ulink url="http://www.plex86.org">Plex86</ulink>, Kevin Lawton's
current project, is working toward an open-source x86 simulator with
virtualization.
</para>

<para>
To do anything interesting in the simulated machine, Bochs needs to communicate
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 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 $25...
&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 bought Bochs and made it open
source under the GNU LGPL.

<!-- 
we should make it clear that Kevin is no longer working on 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 Source Forge.  
</para> </section>  <!-- end of Introduction:What is Bochs? section -->

<section><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 300 subscribers.  The
latest version has been downloaded over 40,000 times from SourceForge, not
counting mirrors 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 often 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.  Also, it has been used as
a reference model to test 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 to program under Linux, without leaving your
Windows desktop?  Or reverse engineer your printer driver?  You decide.
</para>

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


<section><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 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><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, 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), 
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;.  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><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><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
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.
</para>


</section>  <!-- end of Introduction:Third Party Software Licensing -->

<section><title>Features</title>
<para>
The following table shows the features of Bochs and which platforms they
currently work with.
</para>
<table><title>Bochs Features</title>
<tgroup cols=3 align=left colsep=1 rowsep=1>
<thead>
  <row>
    <entry>Feature</entry>
    <entry>Supported?</entry>
    <entry>Description</entry>
  </row>
</thead>
<tbody>
  <row>
    <entry>configure script</entry>
    <entry>Yes</entry>
    <entry>Bochs uses GNU autoconf to configure Makefiles and headers.
    Autoconf helps Bochs to compile on a wide variety of platforms.
    </entry>
  </row>
  <row>
    <entry>386,486,Pentium Emulation</entry>
    <entry>Yes</entry>
    <entry>Bochs can be configured to emulate on of several families of Intel hardware.  Some Pentium features are supported, such as the Time Stamp Counter.</entry>
  </row>
  <row>
    <entry>Pentium Pro Emulation</entry>
    <entry>Incomplete</entry>
    <entry>A few Pentium Pro features are supported, such as an on-chip APIC for SMP simulation.
    </entry>
  </row>
  <row>
    <entry>Cmd Line Debugger</entry>
    <entry>Yes</entry>
    <entry>Powerful command line debugger (optional) that lets you stop
    execution and examine registers and memory, set breakpoints, etc.
    </entry>
  </row>
  <row>
    <entry>Floating Point</entry>
    <entry>Yes</entry>
    <entry>Uses software floating point routines written by Bill Metzenthen
    </entry>
  </row>
  <row>
    <entry>VGA</entry>
    <entry>Yes</entry>
    <entry>VGA color graphics emulation in a window
    </entry>
  </row>
  <row>
    <entry>Floppy disk</entry>
    <entry>Yes</entry>
    <entry>Supports floppy disk images on all platforms: 1.44M 3.5", 1.2M 5.25", and 720K 3.5".  On Unix and Windows NT/2000, Bochs can access the physical floppy drive.
    </entry>
  </row>
  <row>
    <entry>Hard disk</entry>
    <entry>Yes</entry>
    <entry>Emulates one or two AT/IDE hard drives via image files.  No physical
    hard disk access is supported, primarily for safety reasons.  Only two
    IDE devices, total, are supported.  So you can have two hard disks,
    or one hard disk and one CDROM.
    </entry>
  </row>
  <row>
    <entry>Keyboard</entry>
    <entry>Yes</entry>
    <entry>Emulates a PS/2 keyboard with North American key mappings.  Keyboards with other key mappings are reported to have problems with special keys and punctuation.
    </entry>
  </row>
  <row>
    <entry>Mouse</entry>
    <entry>Yes</entry>
    <entry>Emulates a PS/2 mouse with 3 buttons.
    </entry>
  </row>
  <row>
    <entry>Network card</entry>
    <entry>Yes</entry>
    <entry>Emulates an NE2000 compatible network card.  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, with the current implementation, the guest OS can talk
    to any machine on the network BUT NOT the host machine.
    </entry>
  </row>
  <row>
    <entry>CDROM</entry>
    <entry>Yes</entry>
    <entry>Emulates an IDE CDROM.  The CDROM can read from an ISO disk image
    on any platform.  On Windows (95/98/NT/2000), Linux, SunOS, FreeBSD, 
    NetBSD, Amiga/MorphOS, and BeOS<footnote><para>Coming soon, hopefully in
    v1.3</para></footnote>, Bochs can read from the physical cdrom.
    When the CDROM is enabled, only one hard disk can be used.
    </entry>
  </row>
  <row>
    <entry>Parallel Port</entry>
    <entry>Yes</entry>
    <entry>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).
    </entry>
  </row>
  <row>
    <entry>Serial Port</entry>
    <entry>Not quite</entry>
    <entry>The serial port (single 8259 UART emulation) is not really usable
    yet.  The interface to the emulated CPU is mostly working, but it needs
    some work before it can talk to a raw serial port or to a pseudo terminal.
    </entry>
  </row>
  <row>
    <entry>16/32 bit addressing</entry>
    <entry>Yes</entry>
    <entry>16 or 32 bit operand sizes, stack size, and addressing</entry>
  </row>
  <row>
    <entry>v8086/paging</entry>
    <entry>Yes</entry>
    <entry>Virtual-8086 mode and paging</entry>
  </row>
  <row>
    <entry>PIC</entry>
    <entry>Yes</entry>
    <entry>Master and slave programmable interrupt controller.
    </entry>
  </row>
  <row>
    <entry>CMOS functions</entry>
    <entry>Yes</entry>
    <entry>CMOS functions</entry>
  </row>
  <row>
    <entry>Dynamic Translation/Virtualization</entry>
    <entry>No</entry>
    <entry>Because Bochs is designed to be portable, it does not attempt
    to do any dynamic code translation or virtualization.  See 
    <link linkend="whatisbochs">What is Bochs?</link> for details.
    </entry>
  </row>
  <row>
    <entry>Simulate a Multiprocessor</entry>
    <entry>Yes</entry>
    <entry>Bochs can be configured to simulate up to 15 processors.  This
    feature is still experimental, but it can boot Linux 2.2 kernels with SMP
    support.  Please note that this does NOT mean that bochs can run
    faster on a physical SMP machine.
    </entry>
  </row>
  <row>
    <entry>Take advantage of your SMP box</entry>
    <entry>No</entry>
    <entry>At present, Bochs does not use threads or parallel processing, so it
    will not run any faster on multiprocessor hardware.
    </entry>
  </row>
</tbody>
</tgroup>
</table>
</section> <!-- End of Features -->

<section><title>Supported Platforms</title>

<table><title>Supported platforms</title>
   <tgroup cols=2 align=left colsep=1 rowsep=1>
   <tbody>
   <row>
      <entry>Unix/X11</entry>
      <entry>X windows has always been well supported because it was
      Kevin's 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.
      </entry>
   </row>

   <row>
      <entry>Win32</entry>
      <entry>This port was done by David Ross and is now maintained
      by Don Becker.  You can compile with MS Visual C++ 5.0 or 6.0,
      or Cygwin<footnote>
<para>Cygwin is a free Unix-like environment for Windows written by
Steve Chamberlain and now maintained by RedHat.  Download it from--you guessed it--<ulink url="http://www.cygwin.com">www.cygwin.com</ulink></para>
</footnote>.
      See <xref linkend="compiling-win32"> for compile
      instructions.  </entry> 
    </row>

   <row>
      <entry>BeOS</entry>
      <entry>Kevin Lawton did this port, originally to R3/PPC using
      CodeWarrior.  It now works on R4/x86 with egcs. Simon Huet picked up
      maintaining/reworking the BeOS GUI port.  In September 2001, Bernd Korz
      of Yellow Tab, Inc. 
      (<ulink url="http://www.yellowtab.com">www.yellowtab.com</ulink>), took
      over the BeOS/Zeta port.  Use the same compile and install process as
      Unix.
      </entry>
   </row>

   <row>
     <entry>MacOS X</entry>
     <entry>
     Emmanuel Mailliard ported the Macintosh code to MacOS X with Carbon API.
     He has been too busy to maintain it, so if you are interested in working
     on it, contact the &devlist;.
     </entry>
   </row>
   <row>
      <entry>Macintosh</entry>
      <entry>David Batterham drbatter@socs.uts.edu.au or drbatter@yahoo.com
      ported bochs to the Mac.  He compiled with CodeWarrior Pro R1 (CW12).  To
      compile, you have to build headers and Makefiles on a Unix machine using
      "configure --with-macos".  Check out David's MacBochs website.  David has
      not had time to maintain the page or the Mac port since early 2000. If
      you have Mac development tools and want to contribute, contact the
      &devlist;. </entry>
   </row>

   <row>
      <entry>Amiga MorphOS</entry>
      <entry>
      This port is written and maintained by Nicholai Benalal.
      </entry>
   </row>

   <row>
      <entry>OS/2</entry>
      <entry> Nick Behnken used PE2LX to translate David Ross's Win32
      port to an OS/2 program.  This hasn't been updated in more than
      a year, and Nick Behnken's page seems to be inactive.
      Also, Craig Ballantyne ported bochs to OS/2, but his web page has
      disappeared and his port has not been updated since March 2000.
      His latest sources are at <ulink url="http://www.os2world.com/emulator/computer.html">http://www.os2world.com/emulator/computer.html</ulink>.
      If you want to bring the OS/2 port up to date, contact the &devlist;.
      </entry>
   </row>

   </tbody>
   </tgroup>

</table>
</section>  <!-- End Platforms section -->

<!-- *************************************************************** -->
<section><title>FAQ</title>
<qandaset>
  <qandaentry>
     <question>
       <para>Is Bochs Open Source?</para>
     </question>
     <answer>
       <para>
       Yes! Bochs is released under the <ulink url="http://www.gnu.org/copyleft/lesser.html">GNU LGPL</ulink>,
       much thanks to <ulink url="http://www.linux-mandrake.com">MandrakeSoft</ulink>, makers
       of the Linux-Mandrake distribution.
       </para>
     </answer>
  </qandaentry>

  <qandaentry>
     <question>
       <para>How do you pronounce "bochs"?</para>
     </question>
     <answer>
       <para>
       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. 
       </para>
     </answer>
  </qandaentry>

  <qandaentry>
     <question>
       <para>Who is the author of bochs?</para>
     </question>
     <answer>
       <para>
       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. Kevin is presently working on a PC virtualization project called <ulink url="http://www.plex86.org">plex86</ulink> and no longer maintain bochs.
       </para>
     </answer>
  </qandaentry>

  <qandaentry>
     <question><para>
     Who maintains bochs now?
     </para></question>
     <answer><para>
      With Kevin's help, in April 2001, the members of the bochs-developers mailing list set up a new official bochs site hosted by <ulink url="http://sourcefourge.net">Source Forge</ulink>. The current admins on this project are Bryce Denney, Greg Alexander, and Don Becker.
     </para></answer>
  </qandaentry>

  <qandaentry>
     <question><para>
     Tell me about performance when running bochs?
     </para></question>
     <answer><para>
     Because Bochs emulates every x86 instruction and all the devices in a PC system, it does not reach high emulation speeds. Kevin reported approximately 1.5MIPS using bochs on a 400Mhz PII Linux machine. Users who have an x86 processor and want the highest emulation speeds may want to consider PC virtualization software such as plex86 (free) or VMware (commercial). 
     </para></answer>
  </qandaentry>

  <qandaentry>
     <question><para>
     Does bochs use a disk partition to install the OS? 
     </para></question>
     <answer><para>
     No. You use a disk image file, which is simply a large file, like any other file, on your platform's disk. 
     </para></answer>
  </qandaentry>

  <qandaentry>
     <question><para>
     Why can't I use Bochs with my current Win95 installation? 
     </para></question>
     <answer><para>
     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 Win95 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. 
     </para></answer>
  </qandaentry>

  <qandaentry>
     <question><para>
     Is there a developer's email list for bochs?
     </para></question>
     <answer><para>
     Yes.  For instructions on joining, refer to 
     <xref linkend="mailinglist" />
     </para></answer>
  </qandaentry>

  <qandaentry>
     <question><para>
     Is there an irc channel for bochs?
     </para></question>
     <answer><para>
     Not that I am aware of.
     </para></answer>
  </qandaentry>

  <qandaentry>
     <question><para>
     Do you know of any snapshots of Bochs running Win95?
     </para></question>
     <answer><para>
     Yes!  Look for "screen shots" on the <ulink url="http://bochs.sourceforge.net">Bochs home page</ulink> or on other Bochs sites.
     </para></answer>
  </qandaentry>

  <qandaentry>
     <question><para>
     Does bochs support a CDROM?
     </para></question>
     <answer><para>
     Yes, a CDROM is supported in Linux, Windows, and OpenBSD.  The
CDROM drivers for bochs allow the guest operating system to access the
host operating system's CDROM data directly.
     </para></answer>
  </qandaentry>

  <qandaentry>
     <question><para>
     Does bochs support a sound device?
     </para></question>
     <answer><para>
     Yes, there is Sound Blaster emulation support for Windows and Linux.
     </para></answer>
  </qandaentry>

  <qandaentry>
     <question><para>
     Does bochs support a network card?
     </para></question>
     <answer><para>
     Supposedly yes.  There is emulation for an NE2000 NIC in the current
releases, though I have not heard whether it works or not.  If you try it,
please fill out a testing form or bug report.
     </para></answer>
  </qandaentry>

  <qandaentry>
     <question><para>
     What applications are known to run inside of bochs?
     </para></question>
     <answer><para>
     Well, lot's of different OS's run inside of bochs, so
   thousands.  I'm assuming your asking about Windows programs.
   To give you a few, the following ones from the Winstone'98 tests
   worked:
   </para>
   <itemizedlist>
      <listitem>
      <para>Access 97</para>
      </listitem>
      <listitem>
      <para>CorelDRAW! 7</para>
      </listitem>
      <listitem>
      <para>Excel 97</para>
      </listitem>
      <listitem>
      <para>Lotus 1-2-3 97</para>
      </listitem>
      <listitem>
      <para>Word 97</para>
      </listitem>
      <listitem>
      <para>PowerPoint 97</para>
      </listitem>
      <listitem>
      <para>Quattro Pro 7</para>
      </listitem>
      <listitem>
      <para>WordPerfect 7</para>
      </listitem>
   </itemizedlist>

     <para>Also, I've compiled an entire OS kernel inside bochs before.  Not
to mention, running DOOM, though at then-pathetic speeds.
     </para></answer>
  </qandaentry>

<!-- ......................................................
     A blank question to fill in copy and paste to create
     a new entry (8 lines to yank)
     ......................................................
  <qandaentry>
     <question><para>
     Question is put here
     </para></question>
     <answer><para>
       Answer is put here. 
     </para></answer>
  </qandaentry>
-->

</qandaset>
</section>

</chapter>  <!-- End of Introduction to Bochs -->

<!-- *************************************************************** -->
<chapter><title>Release Notes</title>
<section>
<title>Release Notes by Version</title>
<itemizedlist>
<listitem><para><ulink url="http://bochs.sf.net/docs-html/changelog.html#v1.4">Version 1.4 Change Log</ulink></para></listitem>
<listitem><para><ulink url="http://bochs.sf.net/docs-html/changelog.html#v1.3">Version 1.3 Change Log</ulink></para></listitem>
<listitem><para><ulink url="http://bochs.sf.net/docs-html/changelog.html#v1.2.1">Version 1.2.1 Change Log</ulink></para></listitem>
<listitem><para><ulink url="http://bochs.sf.net/docs-html/changelog.html#v1.2">Version 1.2 Change Log</ulink></para></listitem>
<listitem><para><ulink url="http://bochs.sf.net/docs-html/changelog.html#v1.2.pre1">Version 1.2.pre1 Change Log</ulink></para></listitem>
<listitem><para><ulink url="http://bochs.sf.net/docs-html/changelog.html#v1.1.2">Version 1.1.2 Change Log</ulink></para></listitem>
<listitem><para><ulink url="http://bochs.sf.net/docs-html/changelog.html#v1.1.1">Version 1.1.1 Change Log</ulink></para></listitem>
<listitem><para><ulink url="http://bochs.sf.net/docs-html/changelog.html#v1.1">Version 1.1 Change Log</ulink></para></listitem>
</itemizedlist>

</section>
</chapter>




<!-- *************************************************************** -->
<chapter><title>Installation</title>

<section id="downloading"><title>Downloading Bochs</title>

<para>
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 snapshots) may have some newer bug fixes and new
features, but have not been tested as much as the releases.
</para>

<para>
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 <link
linkend="install-binary">Installing a Binary</link> for more information.
</para>

<para>
If you are going to compile Bochs yourself, you need the gzipped tarball
containing the source code, called
<filename>bochs-<replaceable>version</replaceable>.tar.gz</filename>.  For
Windows and Mac, the prebuilt Makefiles are separate, so also get
the Makefiles for your platform.  To unpack a compressed TAR file<footnote>
<para>
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.
</para>
</footnote> on a Unix machine<footnote>
<para>
On Windows, look for software called WinZip to unpack the TAR.
</para>
</footnote>
, type
<screen>
  gunzip -c bochs-<replaceable>version</replaceable>.tar.gz | tar -xvf -
</screen>
This creates a directory called
<filename>bochs-<replaceable>version</replaceable></filename> 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, <link linkend="compiling">Compiling Bochs</link>.
</para>

<para>
Alternatively, you can also obtain the sources for any Bochs version using CVS.
See the <link linkend="get-src-cvs">CVS instructions</link> for details.
</para>
</section>  <!-- End of Installation:Downloading Bochs section -->

<section id="get-src-cvs"><title>Tracking the source code with CVS</title>
<para>
CVS, or Concurrent Version System, is a software development tool that helps
to keep track of the different revisions of each file.  It is used by many
open source (and commercial) projects to allow multiple developers to share
their changes to the source code.  The Bochs source code and documentation 
are available using CVS<footnote>
<para>
You can download CVS software and documentation from 
<ulink url="http://www.cvshome.org">www.cvshome.org</ulink>.
</para>
</footnote>.
</para>

<section><title>Checking out Bochs</title>
<para>
When you have CVS installed, the first step is to do a login and checkout.  The
initial checkout command is long and ugly, but usually you only have to do it
once.  The example below shows the CVS checkout process in UNIX.  On the
Windows platform, you can download a CVS client from cvshome.com, or
use CVS within Cygwin<footnote>
<para>
Cygwin is an open source UNIX-like environment for Windows platforms,
available at <ulink url="http://www.cygwin.com">www.cygwin.com</ulink>.
</para>
</footnote>.

<figure><title>Checking out Bochs in CVS</title>
<screen>
  user$ <command>cvs -d:pserver:anonymous@cvs.bochs.sourceforge.net:/cvsroot/bochs login</command>
  (Logging in to anonymous@cvs.bochs.sourceforge.net)
  CVS password:    <replaceable>(there is no password, just press Enter)</replaceable>
  user$ <command>cvs -z3 -d:pserver:anonymous@cvs.bochs.sourceforge.net:/cvsroot/bochs checkout bochs</command>
  cvs server: Updating bochs
  U bochs/.bochsrc
  U bochs/.conf.AIX.4.3.1
  U bochs/.conf.beos-x86-R4
  U bochs/.conf.macos
     .
     .   <lineannotation>(This might take a few minutes, depending on your network connection.)</lineannotation>
     .
  U bochs/patches/patch.seg-limit-real
  user$ <command>cd bochs</command>
  user$ <command>ls</command>
  Bochs.proj.hqx  bxversion.h   fpu/                osdep.cc
  CHANGES         config.h.in   gui/                osdep.h
  COPYING         configure*    install-x11-fonts*  patches/
  CVS/            configure.in  instrument/         pc_system.cc
  Makefile.in     cpu/          iodev/              pc_system.h
  README          debug/        load32bitOShack.cc  state_file.cc
  TESTFORM.txt    disasm/       logio.cc            state_file.h
  bios/           doc/          macintosh.txt       win32.txt
  bochs.h         docs-html/    main.cc
  bochs.rsrc.hqx  dynamic/      memory/
  build/          font/         misc/
  user$ _
</screen>
</figure>
</para>


<tip>
<para>
If you have write access to the Bochs CVS tree, the checkout
command is different for you.  See the Developers Guide<footnote>
<para>
&FIXME; not written yet.  For now, look at http://sourceforge.net/cvs/?group_id=12580 for instructions. See "Developer CVS access using SSH."
</para>
</footnote> for details.
</para>
</tip>

<tip>
<para>
If you use remote CVS for other projects, you might have already set
the environment variable <varname>CVS_RSH</varname> in your configuration
files.  For the CVS checkout to work as shown above, the
<varname>CVS_RSH</varname> variable should either be empty or set to
<constant>rsh</constant>.
</para>
</tip>

<para>
The CVS 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 each subdirectory directory there's also a
directory called "CVS" which tells the cvs software where the code was checked
out, what version you have, and where to go for future updates.
</para>
</section>

<section><title>Getting the Latest Version</title>
<para>
Most developers use CVS to always give them the latest source code.  The minute
that any developer checks in a change, they are available to everyone else
through  CVS.  You just have to type <command>cvs update -d -A</command> in the
&bochsdir; directory, and CVS 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.  The
<command>-d</command> option tells cvs to download new directories that
have been checked in, not just files.  The <command>-A</command> option means
to get the most recent version of each file, as opposed to a release version.
See <link linkend="cvs-release-version">Getting a release version</link>
Both <command>-d</command> and <command>-A</command> can be omitted in many
cases, once you are familiar with the process.  </para>

<para>
The <command>cvs update -A -d</command> 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 CVS-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.

<table frame="all">
<title>Status letters in a CVS update</title>
  <tgroup cols="3">
    <thead>
      <row>
	<entry>Letter</entry>
	<entry>Meaning</entry>
	<entry>Description</entry>
      </row>
    </thead>
    <tbody>
      <row>
	<entry>?</entry>
	<entry>unknown</entry>
	<entry>
	This file is in your bochs directory, but CVS does not know anything
	about it.  For example, when you compile Bochs, any files created
	during the build process appear as ?.
	</entry>
      </row>
      <row>
	<entry>U</entry>
	<entry>update</entry>
	<entry>
	cvs downloaded a new version of this file because it changed on the
	server, usually because someone else did a checkin.
	</entry>
      </row>
      <row>
	<entry>P</entry>
	<entry>-</entry>
	<entry>
	P is the same as U, as far as I can tell
	</entry>
      </row>
      <row>
	<entry>M</entry>
	<entry>modified</entry>
	<entry>
	You have changed this file on your disk, so it no longer matches the
	version on the server.  This is not a problem; it's just for your 
	information.  If you want, you can discard your changes and
	get a fresh copy by deleting the file and running cvs update again.
	</entry>
      </row>
      <row>
	<entry>C</entry>
	<entry>conflict</entry>
	<entry>
	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 cvs update again.
	</entry>
      </row>
    </tbody>
   </tgroup>
</table>
</para>

<para>
If you have been using <command>cvs update</command> with "sticky tags" to
retrieve other versions, as described later, cvs will remember which version
you were looking at.  In this case, a <command>cvs update</command> will keep
your sources consistent with that version.  If you want to get back to looking
at the latest code again, be sure to use the <command>-A</command> option to
clears the sticky tags.  </para>

</section>

<section id="cvs-release-version"><title>Getting a Release Version</title>
<para>
Once you have a CVS checkout, you can also use the update command to
get the Bochs source code for any release since March 2000.  The command
is <command>cvs update -d -r <replaceable>tagname</replaceable></command>.
The tag tells which release you want, and it can be one of the following:

<table frame="all">
<title>CVS Release Tags</title>
  <tgroup cols="2">
    <thead>
      <row>
	<entry>Bochs version</entry>
	<entry>Release tag for CVS</entry>
      </row>
    </thead>
    <tbody>
      <row>
	<entry>1.4.1 (bugfix1)</entry>
	<entry>REL_1_4_1_FINAL</entry>
      </row>
      <row>
	<entry>1.4</entry>
	<entry>REL_1_4_FINAL</entry>
      </row>
      <row>
	<entry>1.3</entry>
	<entry>REL_1_3_FINAL</entry>
      </row>
      <row>
	<entry>1.2.1 (bugfix1)</entry>
	<entry>REL_1_2_1_FINAL</entry>
      </row>
      <row>
	<entry>1.2</entry>
	<entry>REL_1_2_FINAL</entry>
      </row>
      <row>
	<entry>1.1 (bugfix1)</entry>
	<entry>REL_1_1_BASE</entry>
      </row>
      <row>
	<entry>1.1.2 (bugfix3)</entry>
	<entry>REL_1_1_2_BASE</entry>
      </row>
      <row>
	<entry>1.1.1 (bugfix2)</entry>
	<entry>REL_1_1_1_BASE</entry>
      </row>
      <row>
	<entry>1.1 (bugfix1)</entry>
	<entry>REL_1_1_BASE</entry>
      </row>
      <row>
	<entry>March 25, 2000</entry>
	<entry>REL-bochs-2000-03-25</entry>
      </row>
    </tbody>
   </tgroup>
</table>

<tip>
<para>
To get a complete list of allowed tags, type <command>cvs stat -v README</command>.  Many of the tags are not generally useful.
</para>
</tip>

Once you have done an update with <command>-r <replaceable>tagname</replaceable></command>, you have made a "sticky tag."  The stickiness refers to the fact
that CVS remembers which tag you have used most recently.  The tag is stored
in the CVS subdirectory, so it stays around even if you log off and
return later.  After creating a sticky tag, any future cvs updates will
try to keep your directory in sync with the version you chose.  In other
words, when developers check in changes you will not
see them because your directory is "stuck" looking at an old version.
To clear the sticky tag, use <command>cvs update -A</command>.
</para>

<para>
A variation on the sticky tag concept is a sticky date<footnote>
<para>
According to some sources, this is when you eat dinner with someone, and
accidentally spill a drink on him/her.
</para>
</footnote>.  If some feature was working at some time in the past, but
is no longer working, you can ask CVS to give you the sources from any
date.  <command>cvs update -D 2001-06-14</command> will download the
Bochs source as they were on June 14, 2001.  Again, use <command>-A</command>
to clear the sticky date and track the current sources.
</para>
</section>

<section><title>More about CVS</title>
<para>
Entire books have been written on CVS, so there's no sense in duplicating
it all here in the Bochs documentation.  Some sources of additional
information are listed below.
</para>
<itemizedlist>
<listitem><para>The <ulink url="http://www.cvshome.org">cvshome.com
site</ulink> has tons of CVS FAQs and documentation, including the official CVS
manual by Per Cederqvist.</para></listitem>
<listitem><para>
Another <ulink url="http://www.cs.utah.edu/dept/old/texinfo/cvs/FAQ.txt">CVS FAQ</ulink> is available at University of Utah.
</para></listitem>
</itemizedlist>

</section>


</section> <!-- End of Installation:Getting the source code with CVS -->


<section id="install-binary"><title>Installing a Binary</title>

<para>
This section is divided up by platform, since installing a binary package
is different on different platforms.
</para>

<section><title>Windows</title>
<para>
unzip into some directory.  Look for DOC-win32.html
for more instructions.  Quick start: find dlxlinux/start.bat and
double click
</para>
<para>
&FIXME;
Someone needs to write this.
</para>
</section> <!-- end of Installing a Binary:Windows -->

<section id="linuxrpm">
<title>Linux RPM</title>
<para>
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.  Debian packages are
available for Bochs as well, but this section talks deals with RPMs.  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."  Once you have the package on your local disk, you
should be able to install it as follows<footnote>
<para>
Many distributions have their own RPM installer program, often graphical, and
they should work as well.  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.
</para>
</footnote>:

<figure><title>Installing an RPM in Linux</title>
<screen>
  user$ <command>su</command>
  Password: 
  root# <command>ls -l bochs-1.2.1.i386.rpm</command>
  -rw-rw-r--    1 user     user      1877515 Sep 14 09:02 bochs-1.2.1.i386.rpm
  root# <command>rpm -i bochs-1.2.1.i386.rpm</command>
  Looking for fonts to install... /usr/local/bochs/latest/
  Looking for X11 Font Path... /usr/lib/X11/fonts
  Installing vga.pcf... ok    (it was already there)
  Running mkfontdir...
  Done installing Bochs fonts for X11.
  root# exit
  user$ _
</screen>
</figure>
</para>

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

<tip>
<para>
If RPM installation fails, try running <command>rpm -e bochs</command> first to
erase any old bochs RPMs.  

VGA Font failure?  For now, look at old bochs docs for now for instructions on
installing the VGA font by hand. &FIXME;

Missing RPM dependencies?  Try --nodeps option.
</para>
</tip>

<para>
The Bochs RPM installs three new commands and associated manual pages: bochs,
bochs-dlx, and bximage.  First, let's try out the DLX Linux demo by typing
<command>bochs-dlx</command>.  This command is installed into 
<filename>/usr/local/bin</filename>, so you might need to add that
directory to your <varname>PATH</varname> variable.

<screen>
  user$ bochs-dlx
  Checking for bochs binary...ok
  Checking for DLX linux directory...ok
  Entering /usr/local/bochs/dlxlinux
  Running bochs
  ========================================================================
                         Bochs x86 Emulator 1.2.1
                               June 12, 2001
  ========================================================================
  00000000000 [    ] looking for configuration in .bochsrc
  00000000000 [    ] looking for configuration in bochsrc
  00000000000 [    ] looking for configuration in bochsrc.txt
  00000000000 [    ] reading configuration from bochsrc.txt
  00000000000 [    ] using log file bochsout.txt
</screen>
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.
<figure>
<title>DLX Linux screenshot, running on Linux</title>
<graphic format="GIF" fileref="dlxlinux-in-linux.gif">
</figure>
</para>

<para>
If you get the DLX Linux screen, your Bochs installation is working 
correctly.  This documentation will assume that everything is working
as expected, then there are some tips at the end in case any step goes wrong.
</para>

<para>
&FIXME;
Point to all the files that get installed with the RPM: binaries,
BIOSes, DLX linux, HTML docs and man pages, etc.
</para>

</section> <!-- end of Installing a Binary:Linux section -->

</section> <!-- end of Installing a Binary -->

<section id="compiling"><title>Compiling Bochs</title>

  <section><title>Standard Compile</title>
<para>
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 CVS.  If not, you can return to <link
linkend="downloading">Downloading Bochs</link> for details.  The top level
directory of the source code will be referred to as &bochsdir;.  (&bochsdir;
contains the files <filename>bochs.h</filename> and
<filename>main.cc</filename> and subdirectories <filename>cpu</filename> and
<filename>bios</filename>.) 
</para>

<para>
The standard compile process has three basic steps:
<command>configure</command>, <command>make</command>, and <command>make
install</command>.  Each step is described in a separate section below.  The
standard compile process is used on all Unix machines, MacOS X, BeOS, and 
Cygwin (win32).  There are separate instructions for <link
linkend="compiling-win32">compiling for Win32 with Microsoft VC++</link>.
</para>

<section id="configure"><title>Configure</title>

<para>
There is a script called <command>configure</command> which tests your
machine, C/C++ compiler and libraries to discover what settings should work on
your system.  If you run <command>configure</command> with no arguments after
it, defaults will be used for all settings.  To change the settings, you can
run <command>configure</command> with options that override the 
defaults.  You can get a list of valid configure options by typing
<command>configure --help</command>.  One useful configure option is
--prefix=<replaceable>directory</replaceable>, which sets the directory in
which Bochs will be installed.  All the possible configure options are
documented in a <link linkend="config-opts">later section</link>.  


</para>

<para>
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: <varname>CC</varname>,
<varname>CXX</varname>, <varname>CFLAGS</varname>,
<varname>CXXFLAGS</varname>.  Here is an example that sets the environment
variables, using bash/ksh<footnote>
<para>
The syntax for bash and ksh is given.  In csh and variants, use the syntax
<command>setenv <replaceable>VARIABLE</replaceable>
<replaceable>value</replaceable></command> to change environment variables.
Do not use an equal sign for csh!
</para>
</footnote>
syntax:
<screen>
  export CC=egcs
  export CXX="$CC"
  export CFLAGS="-Wall -O2 -m486 -fomit-frame-pointer -pipe"
  export CXXFLAGS="$CFLAGS"
</screen>
</para>

<para>
Once the configure script knows what options are selected,
it creates a Makefile in every source code directory, and creates 
<filename>$BOCHS/config.h</filename> with all the option values written
as preprocessor #defines.  Now the sources are ready to compile.
</para>

<section><title>Configure Shortcut Scripts</title>
<para>
In the Bochs source directory, you will see a series of scripts called
<filename>.conf.<replaceable>platform</replaceable></filename>.
These scripts run the <command>configure</command> 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.

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

Run a shortcut script using Bourne shell, like this:
<screen>
  sh .conf.win32-vcpp
</screen>

These <filename>.conf.<replaceable>platform</replaceable></filename> have 
been tested in recent Bochs versions:
<screen>
  .conf.linux
  .conf.sparc
  .conf.macosx
  .conf.win32-vcpp
  .conf.win32-cygwin
  .conf.AIX.4.3.1
  .conf.beos-x86-R4
</screen>
</para>

</section> <!-- end of Configure Shortcut Scripts -->

</section> <!-- end of Compiling:Unix:Configure -->


<section><title>Make</title>
<para>
The <command>make</command> 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
<command>make</command> to build the source code.  
</para> 

<para>
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
<filename>main.o</filename> depends on <filename>main.cc</filename>.  Knowing 
this, it will only compile <filename>main.cc</filename> if it is newer than
<filename>main.o</filename>.
</para>

<para>
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 <command>make all-clean</command>
and then <command>make</command> again.  All-clean means to clean up
the compiled files in every subdirectory, while <command>make clean</command>
means to clean up just the current directory<footnote>

<para>
This is different from the terminology of some other projects, and it may cause
confusion.  Sometimes "clean" implies that all subdirectories are affected.
</para>
</footnote>.  However, it's important to note that <command>make
all-clean</command> leaves the configuration intact.  You do not have
to run <command>configure</command> again.
</para>

<para>
If you're really in the mood for cleaning, <command>make dist-clean</command>
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.
</para>

</section>

<section><title>Make Install</title>
<para>
Once the program has been built, the next step is typically to run
<command>make install</command> to copy the executables, documentation, and
other required files into a public place so that all users can use it.
<footnote><para>
&FIXME; We should mention what gets installed, and where.
    /usr/local/bochs/$VERSION/*
    /usr/local/bin/bochs (and bximage)
    /usr/man/man1/bochs*.1 (and bximage.1)
    make install_dlx option
</para></footnote>
</para>
</section>

</section>  <!-- end of Compiling:Unix section -->

<section><title>Transcript of Successful Compilation</title>
<para>
<screen>
  user$ <command>ls -l bochs-1.2.1.tar.gz</command>
  -rw-rw-r--    1 user     user       887993 Sep 15 23:24 bochs-1.2.1.tar.gz
  user$ <command>gunzip -c bochs-1.2.1.tar.gz | tar -xvf -</command>
  bochs-1.2.1/
  bochs-1.2.1/bios/
  bochs-1.2.1/bios/BIOS-bochs-2-processors
  bochs-1.2.1/bios/Makefile.in
    .
    .
    .
  bochs-1.2.1/patches/NOTES
  bochs-1.2.1/patches/patch.4meg-pages
  bochs-1.2.1/patches/patch.goswin-changes
  user$ <command>cd bochs-1.2.1</command>
  user$ <command>./configure --enable-cdrom</command>
  creating cache ./config.cache
  checking for gcc... gcc
  checking whether the C compiler (gcc  ) works... yes
  checking whether the C compiler (gcc  ) is a cross-compiler... no
  checking whether we are using GNU C... yes
  checking whether gcc accepts -g... yes
    .
    .
    .
  creating misc/Makefile
  creating dynamic/Makefile
  creating fpu/Makefile
  creating config.h
  user$ <command>make</command>
  cd iodev && \
  make CC="gcc" CXX="c++" CFLAGS="-g -O2  " CXXFLAGS="-g -O2  " LDFLAGS="" LIBS="" X_LIBS="-L/usr/X11R6/lib" X_PRE_LIBS="-lSM -lICE" prefix="/usr/local" exec_prefix="/usr/local" bindir="/usr/local/bin" infodir="" libiodev.a
  make[1]: Entering directory `/tmp/bochs-1.2.1/iodev'
  c++ -c -g -O2    -I.. -I../instrument/stubs devices.cc -o devices.o
  c++ -c -g -O2    -I.. -I../instrument/stubs pic.cc -o pic.o
  c++ -c -g -O2    -I.. -I../instrument/stubs pit.cc -o pit.o
  c++ -c -g -O2    -I.. -I../instrument/stubs unmapped.cc -o unmapped.o
  c++ -c -g -O2    -I.. -I../instrument/stubs cmos.cc -o cmos.o
    .
    .
    .
  echo done
  done
  c++ -o bochs -g -O2   main.o load32bitOShack.o state_file.o pc_system.o osdep.o \
     iodev/libiodev.a \
     cpu/libcpu.a memory/libmemory.a gui/libgui.a \
     fpu/libfpu.a \
     -L/usr/X11R6/lib -lSM -lICE -lX11
  gcc -c -g -O2    -I. -Iinstrument/stubs misc/bximage.c -o misc/bximage.o
  c++ -o bximage -g -O2   misc/bximage.o
  user$ <command>su</command>
  root# <command>make install</command>
  cd iodev && \
  make CC="gcc" CXX="c++" CFLAGS="-g -O2  " CXXFLAGS="-g -O2  " LDFLAGS="" LIBS="" X_LIBS="-L/usr/X11R6/lib" X_PRE_LIBS="-lSM -lICE" prefix="/usr/local" exec_prefix="/usr/local" bindir="/usr/local/bin" infodir="" libiodev.a
  make[1]: Entering directory `/tmp/bochs-1.2.1/iodev'
    .
    .
    .
  /usr/local/bochs/1.2.1/install-x11-fonts
  Looking for fonts to install... font/
  Looking for X11 Font Path... /usr/lib/X11/fonts
  Installing vga.pcf... ok    (it was already there)
  Running mkfontdir...
  Done installing Bochs fonts for X11.
  root# <command>exit</command>
  user$ _
</screen>
</para>
</section> <!-- end of Transcript -->


<section id="compiling-win32"><title>Compiling on Win32 with Microsoft VC++</title>
<para>
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 to
run the configure script
<footnote>
<para>
Because Bochs depends so much on the configure script, if you are doing
much win32 Bochs development, you should consider downloading Cygwin
so that you can run the configure step natively.
</para>
</footnote>.
</para>

<para>
Download the Bochs sources on a machine that can run shell scripts.
Edit the configure shortcut script <filename>.conf.win32-vcpp</filename>
if you want to adjust configure options.  Then type these commands
in the Bochs source directory:
<screen>
  sh .conf.win32-vcpp
  make win32_snap
</screen>
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 <footnote>
<para>
If the source directory is <filename>/home/joe/bochs-win32</filename>, the
resulting .zip file is in <filename>/home/joe/bochs-win32.zip</filename>.
</para>
</footnote>.  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.
</para>

<para>
The following options are known to work in VC++, so they are enabled in the 
configure shortcut file:
<screen>
  --enable-cdrom 
  --enable-sb16=win 
  --enable-ne2000
  --enable-vbe
</screen>
</para>

<para>
When you have the Win32 sources transferred to a Windows machine with VC++,
find the workspace file called <filename>bochs.dsw</filename> and load it in
VC++.  Choose <command>Project:Set Active Project</command> and be sure that
"bochs" is selected.  Then choose <command>Build:Build bochs.exe</command>.
This will build all the required libraries (iodev, cpu, etc.) and the
auxiliary programs <filename>bximage.exe</filename> and
<filename>niclist.exe</filename>.  Using workspaces is easy and intuitive, but
there is one caveat.  The workspaces come directly out of a ZIP file in
<filename>build/win32/workspace.zip</filename>, and they are not integrated
with configure.  Some configure options such as --enable-debugger need
additional source files to be compiled, and for now you must add them to the
VC++ workspace by hand.  If you add configure options and have compile
problems, try the nmake method (below) instead.  These problems may be fixed
in future versions.  
</para>

<tip>
<para>
To compile with the debugger enabled, add "--enable-debugger" to the
configure line in <filename>.conf.win32-vcpp</filename> before running it.
Then when you have loaded the workspace file, you must add the debug and disasm
libraries to the project dependency list.  Choose
<command>Project:Dependencies</command> and make sure that debug and disasm are
checked.  Then build as usual.
</para> </tip>

<para>
An alternative way to compile is to run <filename>nmake.exe</filename> in an
MS-DOS window.  Instead of using the workspace files, nmake uses the Bochs
makefiles that are generated by configure.  The workspace file is new in
version 1.3; before that, nmake was the only way to compile Bochs in VC++.
If you are having trouble with the workspace, try the nmake compile instead.
</para>

<para>
The <command>make install</command> for Win32 is presently broken.  In the
future, a <command>make install</command> that runs in Cygwin may be provided.
</para>

</section>  <!-- end of Compiling:win32 -->

<section id="compile-cygwin"><title>Compiling on Win32 with Cygwin</title>
<para>Cygwin is a free Unix-like environment for Windows written by
Steve Chamberlain and now maintained by RedHat, Inc.  You can download
it from <ulink url="http://www.cygwin.com">www.cygwin.com</ulink>.  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:
<screen>
  configure
  make
</screen>

Optionally, you can use the configure shortcut script for Cygwin,
<filename>.conf.win32-cygwin</filename>, 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
<screen>
  sh .conf.win32-cygwin
  make
</screen>
These options are known to work in Cygwin, so they are enabled in the configure
shortcut file:
<screen>
  --enable-cdrom 
  --enable-sb16=win 
  --enable-ne2000
  --enable-vbe
</screen>
</para>
</section>  <!-- end of cygwin -->

<section><title>Compiling on MacOS 9 with CodeWarrior</title>
<para>
It is possible that this hasn't been tried since 1999.  In theory, you run
<filename>sh .conf.macos</filename> 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.
</para>

<para>
If you are interested and have the required MacOS development tools, please
let use know.  Someone requests a MacOS port almost once a month, but none of
the developers know how to help them.
</para>
</section>

<section><title>Compiling on MacOS X</title>
<para>
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:
<screen>
  configure
  make
</screen>
Optionally, you can use the configure shortcut script for MacOS X,
<filename>.conf.macosx</filename>, 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
<screen> 
  sh .conf.macosx
  make
</screen>

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

<para>
On MacOS X the default GUI is the Carbon interface, but you can also try other
Bochs GUIs.  Use --enable-x11 for X windows, --enable-rfb for VNC/RFB, or
--enable-sdl for SDL.
</para>
</section>

<section><title>Compiling on BeOS</title>
<para>
Kevin Lawton ported Bochs to BeOS.  Bernd Korz has taken over the port,
and is working on raw cdrom and raw floppy support.  As of Bochs 1.4, it should
compile if you just type "configure && make", because configure will
detect the BeOS platform and assume you want the BeOS GUI.  Optionally,
you can use the configure shortcut script for BeOS,
<filename>.conf.beos-x86-R4</filename>.
</para>
</section> <!-- end BeOS -->

<section><title>Compiling on Amiga/MorphOS</title>
<para>
Nicholai Benalal created this port to MorphOS running on Amiga.  It should
compile with 
<screen>
  configure && make
</screen>
If the platform is not detected properly, you might need to use
--enable-amigaos as a configure option.  Optionally, you can use
the configure shortcut script, <filename>.conf.amigaos</filename>.
</para>
</section> <!-- end Amiga/MorphOS -->

<section><title>Compiling with the RFB interface</title>
<para>
Don Becker's RFB interface allows you to view the Bochs display with the
AT&amp;T's <ulink url="http://www.uk.research.att.com/vnc/">VNC Viewer</ulink>.
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.  No additional libraries
are required.  To try it, type:
<screen>
  configure --with-rfb
  make
</screen>
</para>
</section>

<section><title>Compiling with the SDL interface</title>
<para>
Dave Poirier has written an SDL interface for Bochs.  Simple DirectMedia
Layer, or SDL, is a cross-platform multimedia library distributed from
<ulink url="http://libsdl.org">libsdl.org</ulink>.  SDL supports 
Win32, Linux, IRIX, MacOS, MacOS X, BeOS, and AmigaOS.
</para>

<para>
To compile Bochs with the SDL interface you need to download the SDL
development library.  Either get the development library for your platform,
or download the sources and compile it yourself.  Then, go into the 
Bochs directory and type:
<screen>
  configure --with-sdl
  make
</screen>
</para>
<note><para>
This has only been tested on Linux at the time this documentation was written.
</para></note>

<para>
To compile in Microsoft VC++, you have to configure on a different system.
Here's the procedure:
<screen>
- On a machine that can run shell scripts, such as Cygwin, run
    configure --target=pentium-windows --with-sdl
    make win32_snap
- Copy the resulting ZIP file to your Windows box and unzip it.
- Load up workspace called bochs.dsw in VC++ 6.0
- Double click "gui files"
- Remove gui/win32.cpp from the project, and add gui/sdl.cpp instead.
- Edit the settings of "gui files".  Under C/C++ tab, category=preprocessor,
  additional include directories, add the directory where SDL/SDL.h can be
  found.
- Edit the settings of the "bochs files" project.  Under the Link tab,
  category=General, add SDL.lib to object/library modules list.  Then in
  category=Input, add the path of SDL.lib to additional library path.  Click
  ok.
- Select Build:Build Bochs.exe
</screen>
</para>
</section>

<section><title>Building an RPM on Linux</title>
<para>
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 <filename>make-rpm</filename> 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:

<screen>
  su root
  Password:     <replaceable>type root password</replaceable>
  ./build/redhat/make-rpm
</screen>

When this command completes, you will have a source RPM and a binary RPM
of Bochs, probably under <filename>/usr/src/redhat/RPMS</filename>.  The
output of the <command>make rpm</command> will tell you the exact location
of these new files.  Instructions for installing an RPM are <link
linkend="linuxrpm">here</link>.
</para>

</section> <!-- end of Building an RPM -->



<section id="config-opts"><title>Configure Options</title>
<para>
This section describes the configure options for Bochs.  Perhaps the most
important option is <option>--help</option>, 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 a <option>--with-*</option> option to override the default.  The options in
the first table tell which GUI library is the default for each platform.
</para>
<note>
<para>
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.
</para>
</note>


<table><title>Defaults by Platform</title>
<tgroup cols=3 align=left colsep=1 rowsep=1>
<thead>
  <row>
    <entry>Platform</entry>
    <entry>Default GUI</entry>
    <entry>Extra compile flags</entry>
  </row>
</thead>
<tbody>
  <row>
    <entry>win32 or Cygwin</entry>
    <entry>--with-win32</entry>
    <entry>If using nmake method, compile using cl /nologo /G6 /MT /W3 /GX /DNDEBUG /DWIN32 /D_WINDOWS /O2.  If using Visual C++ workspace, see the workspace file for compile settings.  See <link linkend="compiling-win32">Compiling on Win32 with Microsoft VC++</link> for instructions.
    </entry>
  </row>
  <row>
    <entry>MacOS X or Darwin</entry>
    <entry>--with-carbon</entry>
    <entry>-fpascal-strings -fno-common -arch ppc -Wno-four-char-constants -Wno-unknown-pragmas -Dmacintosh
    </entry>
  </row>
  <row>
    <entry>MacOS 9 or before</entry>
    <entry>--with-macos</entry>
    <entry>none
    </entry>
  </row>
  <row>
    <entry>BeOS</entry>
    <entry>--with-beos</entry>
    <entry>none
    </entry>
  </row>
  <row>
    <entry>AmigaOS</entry>
    <entry>--with-amigaos</entry>
    <entry>none
    </entry>
  </row>
  <row>
    <entry>any other platform</entry>
    <entry>--with-x11</entry>
    <entry>none
    </entry>
  </row>
</tbody>
</tgroup>
</table>

<table><title>Configure Options to Select the GUI (optional)</title>
<tgroup cols=3>
  <thead>
    <row>
      <entry>Option</entry>
      <entry>Comments</entry>
   </row>
  </thead>
  <tbody>
    <row>
      <entry>--with-x11</entry>
      <entry>Use X windows user interface.  On many operating systems,
      Bochs will use X windows by default.
       </entry>
    </row>
    <row>
      <entry>--with-win32-vcpp</entry>
      <entry>Use Win32 GUI/Visual C++ environment.  This is for running
	  configure on a platform which supports running configure, so
	  that you may then transfer the configured code over to
	  an MS Win32/Visual C++ environment.  See 
	  <xref linkend="compiling-win32"> for details.
	  </entry>
    </row>
    <row>
      <entry>--with-win32</entry>
      <entry>Use Win32 GUI, but compile with a Win32/gcc
      environment such as Cygwin.  For Cygwin, see .conf.win32-cygwin
      for the correct compile options.
      </entry>
    </row>
    <row>
      <entry>--with-carbon</entry>
      <entry>Compile for MacOS X with the Carbon GUI.  See the
      .conf.macosx file for the correct MacOS X compile options.
      </entry>
    </row>
    <row>
      <entry>--with-amigaos</entry>
      <entry>Compile for Amiga MorphOS.  This code is written by Nicholai
      Benalal.</entry>
    </row>

    <row>
      <entry>--with-rfb</entry>
      <entry>Use RFB protocol to talk to AT&amp;T's <ulink
      url="http://www.uk.research.att.com/vnc/">VNC Viewer</ulink>.  The RFB
      code was written by Don Becker <email>x-odus@iname.com</email>,
      who has a Bochs-RFB web page on his site, 
      <ulink url="http://www.psyon.org/bochs-rfb/">http://www.psyon.org/bochs-rfb</ulink>.
      RFB mode has been tested in Linux and Win32.
      </entry>
      </row>
    <row>
      <entry>--with-sdl</entry>
      <entry>This option enables Dave Poirier's SDL gui interface.  To
      compile with SDL, you must first install the SDL library
      from <ulink url="http://libsdl.org/">libsdl.org</ulink>.  You
      can either get the source code and compile it yourself, or install
      the development libraries for your platform (already compiled).
      SDL is available for many platforms including Win32, Linux, IRIX,
      MacOS, MacOS X, and BeOS.
      </entry>
      </row>
    <row>
      <entry>--with-beos</entry>
      <entry>Use BeOS GUI.  The configure script will run natively
       on BeOS; use this option when doing so.</entry>
    </row>
    <row>
      <entry>--with-term</entry>
      <entry>Use text-only gui with curses library.  Almost certainly
      won't work right with the debugger or the control panel.
      </entry>
    </row>
    <row>
      <entry>--with-macos</entry>
      <entry>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.  (Hasn't been tested in a long time.)
	</entry>
    </row>
    <row>
      <entry>--with-nogui</entry>
      <entry>No native GUI; just use blank stubs.  This is if you don't
	  care about having video output, but are just running tests. 
      </entry>
    </row>
  </tbody>
</tgroup>
</table>

<para>
The remaining options can generally be used with any GUI.  For each option
such as --enable-cdrom, you can also write --disable-cdrom to explicitly
turn it off.
</para>

<table><title>Frequently Used Configure Options</title>
<tgroup cols=3>
  <thead>
    <row>
      <entry>Option</entry>
      <entry>Default</entry>
      <entry>Comments</entry>
   </row>
  </thead>
  <tbody>
    <row>
      <entry>--enable-cpu-level={<option>3,4,5,6</option>}</entry>
      <entry>5</entry>
      <entry>
      Select which CPU level to emulate.  Choices are 3,4,5,6 which mean to
      target 386, 486, Pentium, or Pentium Pro emulation.  Pentium Pro support
      is quite incomplete, so level 5 is the best choice for now.
      </entry>
    </row>
    <row>
      <entry>--enable-cdrom</entry>
      <entry>no</entry>
      <entry>
      Enable use of a real CDROM.  The cdrom emulation is always present, and
      emulates a drive without media by default.  You can use this option to
      compile in support for accessing the media in your workstation's cdrom
      drive.  The supported platforms are Linux, Solaris, OpenBSD, and Windows.
      For other platforms, a small amount of code specific to your platform
      must be written.  The module iodev/cdrom.cc is the place to add more
      support.  For the most part, you need to figure out the right set of
      ioctl() calls.
      </entry>
    </row>
    <row>
      <entry>--enable-sb16={<option>dummy, win, linux</option>}</entry>
      <entry>no</entry>
      <entry>
      Enable Sound Blaster emulation.  SB16 output is only supported for
      Windows or Linux.  The <constant>dummy</constant> option means to support
      an SB16, but don't use an output device.  So for example, you might use
      <option>--enable-sb16=linux</option>. Check out &FIXME; sound.html for
      more info.
      </entry>
    </row>
    <row>
      <entry>--enable-control-panel</entry>
      <entry>yes</entry>
      <entry>
      Enables text-mode configuration menus when you first start Bochs.  The
      menus let you read in a bochsrc file, edit some options, and save the new
      bochsrc before starting the simulation.  Also enables a runtime
      menu (controlled by a Config button on the Bochs display) which
      lets you change certain settings during simulation.  The control panel
      was added by Bryce Denney.
      </entry>
    </row>
    <row>
      <entry>--enable-new-pit</entry>
      <entry>yes</entry>
      <entry>
      Enables Greg Alexander's PIT model, written during Summer 2001.  This
      model was written from scratch to be much more complete than the old
      Bochs PIT model, which was missing many registers and features.
      If you disable this option, the old PIT model will be used instead.
      </entry>
    </row>
    <row>
      <entry>--enable-slowdown</entry>
      <entry>no</entry>
      <entry>
      Enables Greg Alexander's experimental "slowdown timer" which tries to
      keep the Bochs simulation time in sync with real time.  When Bochs
      is executing many instructions, the slowdown timer will have no effect.
      When Bochs is idle, or just waiting around for an interrupt, the 
      slowdown timer kicks in to prevent Bochs time from speeding ahead.
      This should solve problems like, "Why does my screen saver turn on
      after 30 seconds?"
      </entry>
    </row>
    <row>
      <entry>--enable-idle-hack</entry>
      <entry>no</entry>
      <entry>
      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.
      </entry>
    </row>
    <row>
      <entry>--enable-ne2000</entry>
      <entry>no</entry>
      <entry>Enable NE2000 network card support.  This requires a
      low-level component to be written for each OS.  The NE2000
      option is only supported on FreeBSD, OpenBSD, Linux, and Windows 
      95/98/NT/2K.  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.
      </entry>
    </row>
    <row>
      <entry>--enable-vga</entry>
      <entry>yes</entry>
      <entry>Use VGA emulation.  VGA is the only supported option and
	  since it's the default, you don't need to include this option.</entry>
    </row>
    <row>
      <entry>--enable-vbe</entry>
      <entry>yes</entry>
      <entry>Use VGA BIOS Extensions (VBE) by Jeroen Janssen.  To take
      advantage of the VBE, you must tell Bochs to use the LGPL VGA BIOS
      version 0.3a or higher in the vgaromimage line of your bochsrc file.
      </entry>
    </row>
    <row>
      <entry>--enable-fpu</entry>
      <entry>yes</entry>
      <entry>If you want to compile bochs to make use of the FPU emulator
	  written by Bill Metzenthen (the one used by the Linux kernel),
	  use this option.
      </entry>
    </row>
    <row>
      <entry>--enable-split-hd</entry>
      <entry>yes</entry>
      <entry>
      When enabled, this allows a series of partial hard disk image files to be
      treated as if it was one large file.  The .bochsrc specifies the first
      partial HD image (example win95-1) and then bochs searches for the other
      partial images in as a sequence (win95-2, win95-3, etc.) and opens them
      all.  Then, it treats the series as if there was a single large file
      created by "cat win95-1 win95-2 win95-3".  This trick works for both
      diskc and diskd.  All files must be a multiple of 512 bytes.
      </entry>
    </row>
    <row>
      <entry>--enable-debugger</entry>
      <entry>no</entry>
      <entry>
	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.  Look at the section entitled 'OPTIONAL
	DEBUGGER SECTION'.  &FIXME; add cross references
      </entry>
    </row>
    <row>
      <entry>--enable-disasm</entry>
      <entry>no</entry>
      <entry>Compile in support for built-in disassembler.  Bochs has
	  a built-in disassembler, which is useful if you either
	  run the built-in debugger (--enable-debugger), or want
	  disassembly of the current instruction when there is a
	  panic in bochs.  You don't need this option.</entry>
    </row>
    <row>
      <entry>--enable-cpp</entry>
      <entry>no</entry>
      <entry>
      Use .cpp as C++ suffix.  Renames all the .cc files to .cpp for use with
      compilers which want that, like MS C++ compilers.  Don't use this option
      unless you know you need it.  The configure shortcut script for
      Win32 uses this option.
      </entry>
    </row>
  </tbody>
</tgroup>
</table>

<table>
<title>Less Used Configure Options</title>
<tgroup cols=3>
  <thead>
    <row>
      <entry>Option</entry>
      <entry>Default</entry>
      <entry>Comments</entry>
    </row>
  </thead>
  <tbody>
    <row>
      <entry>--enable-iodebug</entry>
      <entry>yes if debugger is on</entry>
      <entry>
      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 --enable-debugger.  See section
      &FIXME; in the Developer's Guide for details.
      </entry>
    </row>
    <row>
      <entry>--enable-x86-debugger</entry>
      <entry>no</entry>
      <entry>X86 debugger support.  If the software you run in bochs
	  needs to use the x86 hardware debugging facilities such as
	  DR0..DR8, instruction and data breakpoints etc., then you
	  should use this option.  Otherwise don't use it, as it
	  will slow down the emulation.</entry>
    </row>
    <row>
      <entry>--enable-pci</entry>
      <entry>no</entry>
      <entry>Enable limited i440FX PCI support.  This is not complete.
	  Don't use this option.</entry>
    </row>
    <row>
      <entry>--enable-port-e9-hack</entry>
      <entry>no</entry>
      <entry>Writes to port e9 go to console.  Unless you know you want
	  this option, you don't.</entry>
    </row>
    <row>
      <entry>--enable-processors={<option>1,2,3,...,15</option>}</entry>
      <entry>1</entry>
      <entry>
      By changing to more than 1 processor, you enable 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.  Click
      <link linkend="SMP">here</link> for more details on SMP in Bochs.
      </entry>
    </row>
    <row>
      <entry>--enable-apic</entry>
      <entry>no</entry>
      <entry>
      In an SMP machine, there is an APIC (Advanced Programmable Interrupt
      Controller) built into each processor and a separate I/O APIC.  The
      APICs are used for inter-processor communication, so they must be
      enabled for SMP to work.  The default is "no" when there is one
      processor and "yes" when there is more than one processor.  Normally,
      the default is correct and you would never need to type this option.
      </entry>
    </row>
    <row>
      <entry>--enable-instrumentation=<option>directory</option></entry>
      <entry>no</entry>
      <entry>
      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.  [Kevin wrote: I
      broke some of the hooks when I recoded the fetch/decode loop.]
      </entry>
    </row>
    <row>
      <entry>--enable-simid={0, 1}</entry>
      <entry>0</entry>
      <entry>
      CPU simulator ID.  You likely don't need this option.  If you are using
      bochs to cosimulate, that is to run multiple simulators in parallel so
      that you can compare results and check for divergence, each simulator
      needs an ID.  When you only have one CPU simulator (as usual) the default
      of 0 is fine.  [Kevin wrote: I use this option occasionally to run 2
      versions of bochs against each other and check for divergence, to find
      bugs etc.  This option gets broken more than not due to architectural
      changes, and I usually end of fixing it each time I use it.]
      </entry>
    </row>
    <row>
      <entry>--enable-num-sim={1, 2}</entry>
      <entry>1</entry>
      <entry>
      Number of CPU simulators.  The default of 1 is likely what you want, so
      don't use this option.  It is for assigning an ID to the simulator, for
      cosimulation described above.
      </entry>
    </row>
    <row>
      <entry>--enable-time0=n</entry>
      <entry>no</entry>
      <entry>
      Start CMOS clock at at time0 of n instead of using time().  You likely
      don't want this option.  When debugging, it is very helpful to have
      deterministic execution, and the clock is something that can skew
      determinism.  If you supply this option, pass it a value returned by the
      time(NULL) call, relating to the time you want bochs to start the CMOS
      clock from.  For instance, '--enable-time0=917385580'.  If you use this
      option but don't provide a value, configure uses a default value.  Note
      that the time0 option in .bochsrc will override this value.  Without this
      option, the CMOS clock uses a time0 based on the value of time(NULL),
      which is probably what you want.
      </entry>
    </row>
    <row>
      <entry>--enable-hga-dumps=<option>Nmicroseconds</option></entry>
      <entry>no</entry>
      <entry>Copy memory to HGA video buffer every N useconds.  A
	  deprecated option, don't use.</entry>
    </row>
  </tbody>
</tgroup>
</table>

</section> <!-- end of Configure Options -->

<section><title>Compile Problems</title>
<para>
&FIXME;
</para>
<para>
<screen>
what if configure fails?
- tar up config.* and send to bochs-testing@tlw.com
- report the problem with a source forge bug report.

what if make fails?
- try make dist-clean, and run configure and make again
- use configure options to disable options.  For example, if errors in 
fpu/fpu_system.h, you could try --disable-fpu.
- search for the error on the Bochs website (bug reports, patches)
- if familiar with C++, many minor problems can be corrected
- move to more stable code.  if it's CVS, see if a release version will
  compile.  Report problem to bochs-developers.
- report the problem with a source forge bug report.
</screen>

</para>
</section>



</section> <!-- end of Compiling Bochs -->

</chapter>

<chapter><title>Setup</title>
   <section><title>What does Bochs need?</title>
     <para> &FIXME; </para>
      <para>
	<screen>
        - bochsrc, BIOS, VGABIOS, VGA font, disk images.
	- (DONE) table of bochsrc options and what they do
	- BIOS/VGABIOS, what do they do?
	- VGA font, how to install it
	- disk images
	  - where to find one pre-made
	  - make a blank one with bximage
	  - grab one from a real hard disk
      </screen>
      </para>
   </section>
   <section>
   <title>bochsrc</title>
<para>
Bochs uses a configuration file called a <filename>bochsrc</filename> 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, and
parses it.  Here are a few lines from a sample file:
<screen>
  diskc: file="30M.sample", cyl=615, heads=6, spt=17
  boot: c
</screen>
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
<varname>variable</varname>=<varname>value</varname> pairs, separated by
commas.  For very simple options, sometimes just a single value is needed.  
The source and binary distributions come with a sample
<filename>bochsrc</filename>, so you can just copy the sample file and edit the
settings you need to change.
</para>

<para>

</para>

<para>
The section below lists all the supported bochsrc options.
</para>

<section><title>romimage</title>
<para>
Examples:
<screen>
  romimage: file=bios/BIOS-bochs-latest, address=0xf0000
</screen>
You need to load a ROM BIOS into addresses 0xf0000-0xfffff.  The 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
<filename>BIOS-bochs-latest</filename>.
</para>
</section>

<section><title>megs</title>
<para>
Examples:
<screen>
  megs: 32
  megs: 128
</screen>
Set this to the default number of megabytes of memory you want to emulate.  The
default is 32, since most operating systems won't need more than that.
</para>
</section>

<section><title>vgaromimage</title>
<para>
Examples:
<screen>
  vgaromimage: bios/VGABIOS-elpin-2.40
</screen>
You also need to load a VGA ROM BIOS at 0xC0000.  A VGA BIOS file from
Elpin Systems, Inc. is provided in the source and binary distributions.
</para>
</section>

<section><title>floppya/floppyb</title>
<para>
Examples:
<screen>
2.88M 3.5" Floppy:
  floppya: 2_88=a:, status=inserted
1.44M 3.5" Floppy:
  floppya: 1_44=floppya.img, status=inserted
1.2M  5.25" Floppy:
  floppyb: 1_2=/dev/fd0, status=inserted
720K  3.5" Floppy:
  floppya: 720k=/usr/local/bochs/images/win95.img, status=inserted
</screen>

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).

You can set the initial status of the media to <constant>ejected</constant> 
or <constant>inserted</constant>.  Usually you will want to use 
<constant>inserted</constant>.  In fact Bryce can't think of any reason
to ever write <constant>ejected</constant> in your bochsrc.
</para>
</section>

<section><title>diskc/diskd</title>
<para>
Examples:
<screen>
  diskc: file=10M.img, cyl=306, heads=4, spt=17
  diskc: file=112M.img, cyl=900, heads=15, spt=17
  diskd: file=483.img, cyl=1024, heads=15, spt=63
</screen>

The diskc/diskd lines tell Bochs what disk image file to use as the constants
of the emulated hard drive, and what geometry it should have.  Diskc is the
first hard drive, and diskd is the second hard drive.  At present, using a raw
hard drive is NOT SUPPORTED and dangerous to your data.  The file should be a
disk image file, which must be exactly 512*cyl*heads*spt bytes long.  The
geometry settings are cylinder (cyl), heads, and sectors per track (spt).  If
you  use bximage  to create   the  image,  it  will give  you  the required
cyl,  head, and spt information.

<note><para>
You cannot use both diskd and cdromd together.
</para></note>

</para>
</section>

<section><title>cdromd</title>
<para>
Examples:
<screen>
  cdromd: dev=/dev/cdrom, status=inserted         (Unix only)
  cdromd: dev=e:, status=inserted                 (Windows only)
  cdromd: dev=cdromimage.iso, status=inserted
</screen>

The cdromd line tells Bochs to emulate a CD-ROM device.  You cannot have
both a diskd and a cdromd, and there is no cdromc option.  

<note><para>
You cannot use both diskd and cdromd together.
</para></note>

</para>
</section>

<section><title>newharddrivesupport</title>
<para>
Examples:
<screen>
  newharddrivesupport: enabled=1
</screen>
This  setting enables  support for large  hard disks,  better  CD  recognition,
and  various other  useful  functions.  You  can set it  to "enabled=1" (on)
or "enabled=0" (off).  It is recommended  that  this  setting  is  left  on
unless you are having trouble with it.
</para>
</section>

<section><title>boot</title>
<para>
Examples:
<screen>
  boot: a
  boot: c
</screen>
This defines  your boot drive. You can  either boot from 'a' or 'c'.
</para>
</section>

<section><title>log</title>
<para>
Examples:
<screen>
  log: bochs.out
  log: /dev/tty               (unix only)
  log: /dev/null              (unix only)
</screen>
Give the path of the log file you'd like Bochs debug and misc. verbage to be
written to.   If you really don't want it, make it /dev/null.
</para>
</section>

<section><title>debug/info/error/panic</title>
<para>
Examples:
<screen>
  debug: action=ignore
  info: action=report
  error: action=report
  panic: action=ask
</screen>

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


<para>
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), report (print information to
the console or log file), or ignore (do nothing).  The recommended settings are
listed in the sample above.
</para>

<tip>
<para>
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 bochs-developers mailing list unless it is
just a configuration problem like "could not find hard drive image."
</para>
</tip>
</section>

<section><title>com1</title>
<para>
Specifies the 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 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.
</para>
<para>
Examples:
<screen>
com1: dev=/dev/ttyp9
com1: dev=/dev/cua0
</screen>
</para>
</section>

<section><title>parport1</title>
<para>
This defines a parallel (printer) port. When turned on and an output file is
defined 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).
</para>
<para>
Examples:
<screen>
parport1: enabled=1, file="parport.out"
parport1: enabled=1, file="/dev/lp0"
parport1: enabled=0
</screen>
</para>
</section>

<section><title>sb16</title>
<para>
Examples:
<screen>
  sb16: midimode=1, midi=/dev/midi00, wavemode=1, wave=/dev/dsp, 
        loglevel=2, log=sb16.log, dmatimer=600000
</screen>
<note><para>
The  example is  wrapped onto several lines for formatting  reasons, but  it
should all be on one line in the actual bochsrc file.
</para></note>

The sb16 line defines Sound Blaster 16 emulation.  It can have several of
the following properties.  All properties are in the usual "property=value"
format.

 <itemizedlist>
   <listitem><para>
   midi: The  filename is where the midi data is  sent.  This
   can  be  a device  or just a file if  you want to record the midi data.
   </para></listitem>
   
   <listitem><para>
   midimode:
   <screen>
   0 = No data should be output.
   1 = output to device (system dependent - midi denotes the device driver).
   2 = SMF file output, including headers.
   3 = Output the midi data stream to the file (no midi headers and no
       delta times, just command and data bytes).
   </screen>
   </para></listitem>
   
   <listitem><para>
   wave: This is the device/file where wave output is stored.
   </para></listitem>
   
   <listitem><para>
   wavemode:
   <screen>
   0 = no data
   1 = output to device (system dependent - wave denotes the device driver).
   2 = VOC file output, including headers.
   3 = Output the raw wave stream to the file.
   </screen>
   </para></listitem>

   <listitem><para>
   log: The file to write the sb16 emulator messages to.
   </para></listitem>

   <listitem><para>
   loglevel: 
   <screen>
   0 = No log.
   1 = Only 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.
   </screen>
   </para></listitem>

   <listitem><para>
   dmatimer: 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 IPS (see below).
   </para></listitem>
 </itemizedlist>  

</para>
</section>

<section><title>vga_update_interval</title>
<para>
Examples:
<screen>
  vga_update_interval: 250000
</screen>
Video memory is scanned for updates and screen updated every so many virtual
seconds. The default is 300000, about 3Hz. This is generally plenty.
Keep in mind that you must tweak the 'ips:' directive to be as close to the
number of emulated instructions-per-second your workstation can do, for
this to be accurate.
</para>
</section>

<section><title>keyboard_serial_delay</title>
<para>
Example:
  keyboard_serial_delay: 200
<screen>
</screen>
Approximate time in microseconds that it takes one character to be
transfered from the keyboard to controller over the serial path.
</para>
</section>

<section><title>keyboard_paste_delay</title>
<para>
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.
</para>
<para>
Example:
  keyboard_paste_delay: 100000
<screen>
</screen>
</para>
</section>

<section><title>floppy_command_delay</title>
<para>
Examples:
<screen>
  floppy_command_delay: 50000
</screen>
Time in microseconds to wait before completing some  floppy  commands  such  as
read,  write, seek,  etc.,   which  normally  have  a  delay associated.  This
was  once  hardwired  to 50000 but now you can adjust it.
</para>
</section>

<section><title>ips</title>
<para>
Examples:
<screen>
  ips: 1000000
</screen>
Emulated Instructions Per Second.  This is the number of IPS that bochs is
capable of running on your  machine.  You  can  recompile  Bochs, using
instructions  included in  config.h (in the source code),  to find  your
workstation's capability.
</para>

<para>
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 machines<footnote><para>IPS measurements depend on
OS and compiler configuration  in addition  to processor clock
speed.</para></footnote>.  
</para>

<table><title>Example IPS Settings</title>
  <tgroup cols=3 align=left colsep=1 rowsep=1>
<thead>
  <row>
    <entry>Speed</entry>
    <entry>Machine</entry>
    <entry>Typical IPS</entry>
  </row>
</thead>
  <tbody>
<row><entry>650Mhz</entry><entry>Athlon K-7 with Linux 2.4.x  </entry><entry> 2 to 2.5</entry></row>
<row><entry>400Mhz</entry><entry>Pentium II with Linux 2.0.x  </entry><entry> 1 to 1.8</entry></row>
<row><entry>166Mhz</entry><entry>64bit Sparc with Solaris 2.x  </entry><entry>    0.75</entry></row>
<row><entry>200Mhz</entry><entry>Pentium with Linux 2.x        </entry><entry>          0.5</entry></row>
</tbody>
</tgroup>
</table>

</section>

<section><title>mouse</title>
<para>
Examples:
<screen>
  mouse: enabled=1
  mouse: enabled=0
</screen>
This option prevents Bochs from creating mouse "events"  unless  a  mouse  is
enabled.  The hardware emulation  itself is not disabled  by this. You  can
turn the mouse on  by  setting enabled to  1,  or  turn  it  off  by  setting
enabled to 0. 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 (middle mouse button on X11 and SDL, F12 on Win32).
</para>
</section>

<section><title>private_colormap</title>
<para>
Examples:
<screen>
  private_colormap: enabled=1
</screen>
Requests that the GUI create and use 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.
</para>
</section>

<section><title>ne2k</title>
<para>
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.
</para>
<para>
Examples:
<screen>
ne2k: ioaddr=0x280, irq=9, mac=b0:c4:20:00:00:00, ethmod=fbsd, ethdev=xl0
ne2k: ioaddr=0x280, irq=9, mac=b0:c4:20:00:00:00, ethmod=linux, ethdev=eth0
ne2k: ioaddr=0x280, irq=9, mac=b0:c4:20:00:00:01, ethmod=win32, ethdev=<replaceable>MYCARD</replaceable>
ne2k: ioaddr=0x280, irq=9, mac=fe:fd:00:00:00:01, ethmod=tap, ethdev=tap0

ioaddr, irc: You probably won't need to change ioaddr and irq, unless there
are IRQ conflicts.

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.

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

<section><title>keyboard_mapping</title>
<para>
Examples:
<screen>
  keyboard_mapping: enabled=0, map=
  keyboard_mapping: enabled=1, map=gui/keymaps/x11-pc-de.map
</screen>
This enables a remap of a physical localized keyboard to a
virtualized U.S. keyboard, as the PC architecture expects.
If enabled, the keymap file must be specified.
</para>
</section>

<section><title>keyboard_type</title>
<para>
Examples:
<screen>
  keyboard_type: xt
  keyboard_type: at
  keyboard_type: mf
</screen>
Type of keyboard returned 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.
</para>
</section>

</section> <!--end of bochsrc section-->

<section id="keymap"><title>How to write your own keymap table</title>
<para>
Christophe Bothamy wrote the keymapping code for Bochs, and provided this
documentation for how to create new keymaps.  Keymapping is currently 
implemented for X windows only, so there are many references to X-specific
values in this section.
</para>
<screen>
  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
          -------------------------------------------
</screen>  

<para>
Each key of the US keyboard maps to a Bochs constant named
BX_KEY_<replaceable>symbol</replaceable>. You can find the current list of
BX_KEY_<replaceable>symbol</replaceable> in 
<link linkend="bx-key-table">the BX_KEY table</link>, below. Please note that
there is only one BX_KEY_<replaceable>symbol</replaceable> for each physical
key.
</para>

<para>
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_<replaceable>symbol</replaceable> constant.  In 
<filename>X11/keysymdef.h</filename>, you will find the list of all possible
XK_<replaceable>symbol</replaceable> 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. 
</para>

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


<para>
For example :
<screen>
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
</screen>
</para>

<para>
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 <filename>X11/keysymdef.h</filename>.
</para>

<table id="bx-key-table"><title>BX_KEY constants</title>
<tgroup cols=2 align=center colsep=1 rowsep=1>
<thead>
  <row>
    <entry> BX_KEY constant </entry>
    <entry> Keyboard Symbol </entry>
  </row>
</thead>
<tbody>

<row><entry>BX_KEY_CTRL_L</entry><entry> left Ctrl </entry></row>
<row><entry>BX_KEY_SHIFT_L</entry><entry> left Shift </entry></row>
<row><entry>BX_KEY_F1</entry><entry> F1 </entry></row>
<row><entry>BX_KEY_F2</entry><entry> F2 </entry></row>
<row><entry>BX_KEY_F3</entry><entry> F3 </entry></row>
<row><entry>BX_KEY_F4</entry><entry> F4 </entry></row>
<row><entry>BX_KEY_F5</entry><entry> F5 </entry></row>
<row><entry>BX_KEY_F6</entry><entry> F6 </entry></row>
<row><entry>BX_KEY_F7</entry><entry> F7 </entry></row>
<row><entry>BX_KEY_F8</entry><entry> F8 </entry></row>
<row><entry>BX_KEY_F9</entry><entry> F9 </entry></row>
<row><entry>BX_KEY_F10</entry><entry> F10 </entry></row>
<row><entry>BX_KEY_F11</entry><entry> F11 </entry></row>
<row><entry>BX_KEY_F12</entry><entry> F12 </entry></row>
<row><entry>BX_KEY_CTRL_R</entry><entry> right Ctrl </entry></row>
<row><entry>BX_KEY_SHIFT_R</entry><entry> right Shift </entry></row>
<row><entry>BX_KEY_CAPS_LOCK</entry><entry> CapsLock </entry></row>
<row><entry>BX_KEY_NUM_LOCK</entry><entry> NumLock </entry></row>
<row><entry>BX_KEY_ALT_L</entry><entry> left Alt </entry></row>
<row><entry>BX_KEY_ALT_R</entry><entry> right Alt </entry></row>
<row><entry>BX_KEY_A</entry><entry> A </entry></row>
<row><entry>BX_KEY_B</entry><entry> B </entry></row>
<row><entry>BX_KEY_C</entry><entry> C </entry></row>
<row><entry>BX_KEY_D</entry><entry> D </entry></row>
<row><entry>BX_KEY_E</entry><entry> E </entry></row>
<row><entry>BX_KEY_F</entry><entry> F </entry></row>
<row><entry>BX_KEY_G</entry><entry> G </entry></row>
<row><entry>BX_KEY_H</entry><entry> H </entry></row>
<row><entry>BX_KEY_I</entry><entry> I </entry></row>
<row><entry>BX_KEY_J</entry><entry> J </entry></row>
<row><entry>BX_KEY_K</entry><entry> K </entry></row>
<row><entry>BX_KEY_L</entry><entry> L </entry></row>
<row><entry>BX_KEY_M</entry><entry> M </entry></row>
<row><entry>BX_KEY_N</entry><entry> N </entry></row>
<row><entry>BX_KEY_O</entry><entry> O </entry></row>
<row><entry>BX_KEY_P</entry><entry> P </entry></row>
<row><entry>BX_KEY_Q</entry><entry> Q </entry></row>
<row><entry>BX_KEY_R</entry><entry> R </entry></row>
<row><entry>BX_KEY_S</entry><entry> S </entry></row>
<row><entry>BX_KEY_T</entry><entry> T </entry></row>
<row><entry>BX_KEY_U</entry><entry> U </entry></row>
<row><entry>BX_KEY_V</entry><entry> V </entry></row>
<row><entry>BX_KEY_W</entry><entry> W </entry></row>
<row><entry>BX_KEY_X</entry><entry> X </entry></row>
<row><entry>BX_KEY_Y</entry><entry> Y </entry></row>
<row><entry>BX_KEY_Z</entry><entry> Z </entry></row>
<row><entry>BX_KEY_0</entry><entry> 0 </entry></row>
<row><entry>BX_KEY_1</entry><entry> 1 </entry></row>
<row><entry>BX_KEY_2</entry><entry> 2 </entry></row>
<row><entry>BX_KEY_3</entry><entry> 3 </entry></row>
<row><entry>BX_KEY_4</entry><entry> 4 </entry></row>
<row><entry>BX_KEY_5</entry><entry> 5 </entry></row>
<row><entry>BX_KEY_6</entry><entry> 6 </entry></row>
<row><entry>BX_KEY_7</entry><entry> 7 </entry></row>
<row><entry>BX_KEY_8</entry><entry> 8 </entry></row>
<row><entry>BX_KEY_9</entry><entry> 9 </entry></row>
<row><entry>BX_KEY_ESC</entry><entry> Esc </entry></row>
<row><entry>BX_KEY_SPACE</entry><entry> SpaceBar </entry></row>
<row><entry>BX_KEY_SINGLE_QUOTE</entry><entry> ' </entry></row>
<row><entry>BX_KEY_COMMA</entry><entry> , </entry></row>
<row><entry>BX_KEY_PERIOD</entry><entry> . </entry></row>
<row><entry>BX_KEY_SLASH</entry><entry> / </entry></row>
<row><entry>BX_KEY_SEMICOLON</entry><entry> ; </entry></row>
<row><entry>BX_KEY_EQUALS</entry><entry> = </entry></row>
<row><entry>BX_KEY_LEFT_BRACKET</entry><entry> [ </entry></row>
<row><entry>BX_KEY_BACKSLASH</entry><entry> \ </entry></row>
<row><entry>BX_KEY_RIGHT_BRACKET</entry><entry> ] </entry></row>
<row><entry>BX_KEY_MINUS</entry><entry> - </entry></row>
<row><entry>BX_KEY_GRAVE</entry><entry> ` </entry></row>
<row><entry>BX_KEY_BACKSPACE</entry><entry> BackSpace </entry></row>
<row><entry>BX_KEY_ENTER</entry><entry> Enter </entry></row>
<row><entry>BX_KEY_TAB</entry><entry> Tab </entry></row>
<row><entry>BX_KEY_LEFT_BACKSLASH</entry><entry> left \ </entry></row>
<row><entry>BX_KEY_PRINT</entry><entry> PrintScreen </entry></row>
<row><entry>BX_KEY_SCRL_LOCK</entry><entry> ScrollLock </entry></row>
<row><entry>BX_KEY_PAUSE</entry><entry> Pause </entry></row>
<row><entry>BX_KEY_INSERT</entry><entry> Ins </entry></row>
<row><entry>BX_KEY_DELETE</entry><entry> Del </entry></row>
<row><entry>BX_KEY_HOME</entry><entry> Home </entry></row>
<row><entry>BX_KEY_END</entry><entry> End </entry></row>
<row><entry>BX_KEY_PAGE_UP</entry><entry> PageUo </entry></row>
<row><entry>BX_KEY_PAGE_DOWN</entry><entry> PageDown </entry></row>
<row><entry>BX_KEY_KP_ADD</entry><entry> Numeric Keypad + </entry></row>
<row><entry>BX_KEY_KP_SUBTRACT</entry><entry> Numeric Keypad - </entry></row>
<row><entry>BX_KEY_KP_END</entry><entry> Numeric Keypad 1 </entry></row>
<row><entry>BX_KEY_KP_DOWN</entry><entry> Numeric Keypad 2 </entry></row>
<row><entry>BX_KEY_KP_PAGE_DOWN</entry><entry> Numeric Keypad 3 </entry></row>
<row><entry>BX_KEY_KP_LEFT</entry><entry> Numeric Keypad 4 </entry></row>
<row><entry>BX_KEY_KP_5</entry><entry> Numeric Keypad 5 </entry></row>
<row><entry>BX_KEY_KP_RIGHT</entry><entry> Numeric Keypad 6 </entry></row>
<row><entry>BX_KEY_KP_HOME</entry><entry> Numeric Keypad 7 </entry></row>
<row><entry>BX_KEY_KP_UP</entry><entry> Numeric Keypad 8 </entry></row>
<row><entry>BX_KEY_KP_PAGE_UP</entry><entry> Numeric Keypad 9 </entry></row>
<row><entry>BX_KEY_KP_INSERT</entry><entry> Numeric Keypad 0 </entry></row>
<row><entry>BX_KEY_KP_DELETE</entry><entry> Numeric Keypad . </entry></row>
<row><entry>BX_KEY_KP_ENTER</entry><entry> Numeric Keypad Enter </entry></row>
<row><entry>BX_KEY_KP_MULTIPLY</entry><entry> Numeric Keypad * </entry></row>
<row><entry>BX_KEY_KP_DIVIDE</entry><entry> Numeric Keypad / </entry></row>
<row><entry>BX_KEY_UP</entry><entry> UpArrow </entry></row>
<row><entry>BX_KEY_DOWN</entry><entry> DownArrow </entry></row>
<row><entry>BX_KEY_LEFT</entry><entry> LeftArrow </entry></row>
<row><entry>BX_KEY_RIGHT</entry><entry> RightArrow </entry></row>
<row><entry>BX_KEY_WIN_L</entry><entry> Left Windows </entry></row>
<row><entry>BX_KEY_WIN_R</entry><entry> Right Windows </entry></row>
<row><entry>BX_KEY_MENU</entry><entry> Menu </entry></row>
<row><entry>BX_KEY_ALT_SYSREQ</entry><entry> Alt-Sysreq </entry></row>
<row><entry>BX_KEY_CTRL_BREAK</entry><entry> Ctrl-Break </entry></row>
<row><entry>BX_KEY_INT_BACK</entry><entry> Internet - back </entry></row>
<row><entry>BX_KEY_INT_FORWARD</entry><entry> Internet - forward </entry></row>
<row><entry>BX_KEY_INT_STOP</entry><entry> Internet - stop </entry></row>
<row><entry>BX_KEY_INT_MAIL</entry><entry> Internet - mail </entry></row>
<row><entry>BX_KEY_INT_SEARCH</entry><entry> Internet - search </entry></row>
<row><entry>BX_KEY_INT_FAV</entry><entry> Internet - fovorites </entry></row>
<row><entry>BX_KEY_INT_HOME</entry><entry> Internet - home </entry></row>
<row><entry>BX_KEY_POWER_MYCOMP</entry><entry> Powerkeys - my computer </entry></row>
<row><entry>BX_KEY_POWER_CALC</entry><entry> Powerkeys - calculator </entry></row>
<row><entry>BX_KEY_POWER_SLEEP</entry><entry> Powerkeys - sleep </entry></row>
<row><entry>BX_KEY_POWER_POWER</entry><entry> Powerkeys - power </entry></row>
<row><entry>BX_KEY_POWER_WAKE</entry><entry> Powerkeys - wake </entry></row>

</tbody>
</tgroup>
</table>
</section>

</chapter>

<chapter><title>Using Bochs</title>
    <para>
    <screen>
Resources for users
testing status page: tells what has been tried and who got it working
search on bochs web site
SourceForge
  look for bug reports
  how to report problems, make feature requests
    </screen>
    </para>
</chapter>

<chapter><title>Common problems and what to do about them (Troubleshooting)</title>
    <para>
    <screen>
        What's a panic?  How to report it to bug tracker, how to make
	  it non-fatal.
        Mouse behavior, enabling and disabling
	Keyboard mapping problems
	[...]
    </screen>
    </para>
</chapter>

<chapter id="mailinglist">
<title>Mailing Lists</title>
<para>
The Bochs community uses three mailing lists to communicate, called
bochs-developers, bochs-cvs and bochs-announce.
</para>

<section id="bochs-developers"><title>bochs-developers mailing list</title>
<para>
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 <link
linkend="bochs-announce">bochs-announce list</link> is more appropriate for
you.  Anyone may join the list, unless they abuse it of course.
</para>
<para>
To subscribe, go to the <ulink url="http://lists.sourceforge.net/lists/listinfo/bochs-developers">Bochs-Developers Info Page</ulink> and type your email
address and a password into the web form and click
<command>Subscribe</command>.  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 <ulink
url="http://lists.sourceforge.net/lists/listinfo/bochs-developers">same
page</ulink> and type your email address in the blank at the bottom and click
on <command>Edit Options</command>.  Then type your password and click
<command>Unsubscribe</command>.
</para>
<para>
Once you have subscribed, you can write to
<email>bochs-developers@lists.sourceforge.net</email> 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.
</para>
<para>
<ulink url="http://marc.theaimsgroup.com/?l=bochs-dev">Archive of bochs-developers messages</ulink>
</para>
</section>  <!-- End of bochs-developers mailing list -->

<section id="bochs-announce"><title>bochs-announce mailing list</title>
<para>
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.
</para>

<para>
To subscribe, go to the <ulink url="http://lists.sourceforge.net/lists/listinfo/bochs-announce">Bochs-Announce Info Page</ulink> and type your email
address and a password into the web form and click <command>Subscribe</command>.
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
<ulink url="http://lists.sourceforge.net/lists/listinfo/bochs-announce">same
page</ulink> and type your email address in the blank at the bottom and click
on <command>Edit Options</command>.  Then type your password and click
<command>Unsubscribe</command>.
</para>

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

<para>
<ulink url="http://bochs.sourceforge.net/cgi-bin/topper.pl?name=Bochs+Announce+Archive&amp;url=http://sourceforge.net/mailarchive/forum.phpqmrkforum_ideq1855">Archive of bochs-announce messages</ulink>
</para>

</section>  <!-- End of bochs-announce mailing list -->

<section id="bochs-cvs"><title>bochs-cvs mailing list</title>
<para>
This is the cvs commit mailinglist (a unified diff email will be sent
whenever someone does a checkin in the bochs cvs repository).
</para>

<para>
<ulink url="http://bochs.sourceforge.net/cgi-bin/topper.pl?name=Bochs+CVS+Mailing+List+Archive&amp;url=http://sourceforge.net/mailarchive/forum.phpqmrkforum_ideq8301">Archive of bochs-cvs messages</ulink>
</para>

</section>  <!-- End of bochs-cvs mailing list -->

<section><title>Mailing List Etiquette</title>

<para>
Here are a few guidelines for use of the Bochs mailing lists:
</para>

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

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

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

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

</section>
</chapter>

<chapter><title>Tips and Techniques</title>
    <para>
      <screen>
Ideas for new sections:
- Using two hard disks
- How to install Windows 95
- etc.
      </screen>
    </para>

<section><title>How to make a disk image</title>
<para>
This was contributed by Greg Alexander in October 2001.
</para>
<para>
What you need:

<itemizedlist>
<listitem><para>
An executable version of bochs.  See <link linkend="downloading">Downloading Bochs</link> and <link linkend="compiling">Compiling Bochs</link>.
</para></listitem>
<listitem><para>
The bximage program, included with bochs
</para></listitem>
<listitem><para>
A FreeDOS boot disk, or a boot disk from another OS capable of
producing DOS partitions (i.e. a linux install disk.)
</para></listitem>
<listitem><para>
(optional) mtools, a program for manipulating DOS disks/images.
</para></listitem>
</itemizedlist>

</para>

<screen>

Run `bximage` to create a disk image file.  You will be greeted with the
following prompt:

========================================================================
                                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] 


Since we are creating a hard disk image, accept the default of hd by
pressing <command>Enter</command> or typing 'hd' and pressing
<command>Enter</command>.  Next, 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 32255
[10] 


Enter the size of the hard disk you want to create, and press
<command>Enter</command>. 
Bochs will give you some information about the image it is creating, and
ask you for a filename to use for the file it is creating.  I told it to
use the default of 10 megabytes, and was given the following information
along with the prompt for a filename:


[10] 10

I will create a hard disk image with
  cyl=20
  heads=16
  sectors per track=63
  total sectors=20160
  total size=9.84 megabytes

What should I name 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 <command>Enter</command>.  Bximage will tell you it is writing the disk and
will display a status bar as you wait.  When it is finished, it will
give you a final status report and tell you a line that should be added
to your .bochsrc file 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

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

I wrote 10321920 bytes to teaching.img.

The following line should appear in your bochsrc:
  diskc: file="teaching.img", cyl=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.


2.) Partition and format your image file.

Option 1: Using FreeDOS (Advantages: Creates a MBR on the partition.)

First, you need to edit the .bochsrc file that bochs uses for
configuration information.  Open the file .bochsrc with a text editor. 
Remove any lines in the file beginning with "diskc:".  Add the "diskc:"
line that was displayed when you ran bximage to the .bochsrc file in the
same place that you removed the old "diskc:" 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 file to point
at the downloaded FreeDOS image and change its status to "status=inserted".

Save and close your .bochsrc.  Now run bochs.  (see: "Running bochs from
the command line.")

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 hard drive.  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 (Disadvantages: cannot create bootable images
without a MBR image)

Use a text editor to add the following line to the file ~/.mtoolsrc:


drive c: file="<replaceable>path</replaceable>/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 <replaceable>spt</replaceable> -t <replaceable>cyl</replaceable> -h <replaceable>heads</replaceable> c:
mpartition -cpv -s <replaceable>spt</replaceable> -t <replaceable>cyl</replaceable> -h <replaceable>heads</replaceable> 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.
</screen>
</section> <!-- end of Unix: How to make a disk image -->

<section><title>Use mtools to manipulate disk images</title>
<para>
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
<ulink url="http://bochs.sourceforge.net/links.html">Bochs Links page</ulink>,
under Resources.  
</para>
<para>
The mtools web site has a detailed manual.  If anyone wants to write
instructions specific to Bochs, we can add it right here.
</para>
</section>

<section><title>Win32 only: Use winimage to manipulate disk images</title>
<para>
Someone on the bochs-developers list mentioned that they use a program
called WinImage, from <ulink url="www.winimage.com">www.winimage.com</ulink>
to read and write disk images (floppy and hard disk).  Winimage is a
commercial product with a 30-day trial.
</para>
<para>
If anyone wants to write a tutorial, send mail to &devlist; and volunteer.
</para>
</section>


<section> <title>Linux: Mounting a disk image using the loop device</title>
<para>
This section was contributed by Volker Ruppert.  It 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.
</para>
<para>
Here is what Volker writes:
<screen>
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 tests with linux and I don't know how
    this could be done with other operating systems.
</screen>
</para>
</section>  <!-- end of Linux: Mounting a disk image using the loop device -->

<section id="SMP"><title>Simulating a Symmetric Multiprocessor (SMP) Machine</title>
<para>
Bochs can now simulate an SMP machine when you use "--enable-processors=N" 
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.
</para>

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

<para>
What was required to make SMP work in Bochs?  (Note that only Linux 2.2
has been tested so far.)
<itemizedlist>
<listitem><para> local APIC on each processor with timer
</para></listitem>
<listitem><para> one I/O APIC model
</para></listitem>
<listitem><para> implement RDTSC feature (read time stamp counter)
</para></listitem>
<listitem><para> modifications to rombios.c to add a data structure called the Intel
Multiprocessor Configuration.  An SMP-aware operating system 
probes BIOS memory to find the structure, which contains information about
how many processors, their IDs, interrupt sources, etc.
</para></listitem>
</itemizedlist>
</para>

<para>
What needs to be done to improve SMP support?

<itemizedlist>
<listitem><para>
still needs work on rombios.c to allow you to configure the number of
processors in the .bochsrc.  Presently you have to choose the number
of processors at compile time.
</para></listitem>

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

<listitem><para>
 test on SMP systems other than linux 2.2.14
</para></listitem>

<listitem><para>
several parts of the APIC model which weren't needed for linux 2.2.14
are not implemented yet and cause a panic.  If you boot linux 2.4.3 for 
example, it says "panic: cluster model addressing not implemented".   See
<ulink url="http://sourceforge.net/tracker/index.php?func=detail&amp;aid=421938&amp;group_id=12580&amp;atid=362580">bug report #421938</ulink> for tips on getting linux 2.4 to boot.
(The apic is not the only problem!)
</para></listitem>

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


</section>
<section><title>Setting Up Networking in DLX Linux</title>
<para>
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 <varname>ne2k</varname> 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.
</para>

<para>
When you have an <varname>ne2k</varname> line in your bochsrc file, Bochs 
will emulate a network card called an NE2000.  Below are some examples of valid
<varname>ne2k</varname> 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.
<screen>
  # sample for FreeBSD
  ne2k: ioaddr=0x280, irq=9, mac=b0:c4:20:00:00:00, ethmod=fbsd, ethdev=xl0
  # sample for Linux
  ne2k: ioaddr=0x280, irq=9, mac=b0:c4:20:00:00:00, ethmod=linux, ethdev=eth0
  # sample for Windows
  ne2k: ioaddr=0x280, irq=9, mac=00:c4:3B:00:C3:00, ethmod=win32, ethdev=NE2000
</screen>
You see the pattern.  Usually you won't need to change the I/O address, IRQ
number, or MAC address.  The <varname>ethmod</varname> value depends on your
host operating system, and it must be either <constant>null</constant>,
<constant>fbsd</constant> (for FreeBSD or OpenBSD), <constant>linux</constant>,
or <constant>win32</constant>.  The <varname>ethdev</varname> 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
<command>ifconfig</command>.  (Don't choose the loopback interface.)  On
Windows systems, the correct ethdev setting is not always obvious, so we
provide a utility called <command>niclist</command> to list the names of
network interfaces to use.  When you run <command>niclist</command>, it will
suggest an <varname>ne2k</varname> line which is a very good first try.
</para>

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

<para>
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.
<screen>
  ne.c:v1.10 9/23/94 Donald Becker (becker@cesdis.gsfc.nasa.gov)
  NE*000 ethercard probe at 0x280: b0 c4 20 00 00 00
  eth0: NE2000 found at 0x280, using IRQ 9.
</screen>
</para>

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

<screen>
  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:~# _
</screen>
</para>

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

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

<note>
<para>
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 <command>vi</command> editor in this limited amount of space...
</para>
</note>



<para>
To configure a name 
server, set up <filename>/etc/resolv.conf</filename> with the IP address of
your name server as shown.
<screen>
   dlx:~# echo 'nameserver 192.168.0.1' > /etc/resolv.conf
</screen>
</para>
</section>

</chapter>




<chapter><title>Guest operating systems</title>
	<section><title>Linux</title>
           <para>
	    What disk images are available.
	    Installing from scratch.
	    What works
	    Known problems
            </para>
          </section>
	  <section><title>OpenBSD</title>
             <para>
             </para>
          </section>
	  <section><title>FreeBSD</title>
             <para>
             </para>
          </section>
	  <section><title>FreeDOS</title>
             <para>
             </para>
          </section>
	  <section><title>DOS</title>
<section><title>Accessing your CDROM</title>
<para>
To access your CDROM in DOS, you must download an IDE CDROM driver.  
Bochs emulates a very generic CDROM drive, and several drivers are known to
work.  Others don't.  This section describes how to set up your
<filename>config.sys</filename> and <filename>autoexec.bat</filename> to enable
the CDROM.
</para>

<para>
The drivers that have been reported to work are
<filename>OAKCDROM.SYS</filename> that comes with several versions of Windows
and <filename>SBIDE.SYS</filename> version 1.21 from Creative
Labs<footnote>
<para>
To get it, go to <ulink url="http://creative.com">Creative Labs web
site</ulink>, 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
<filename>sbide121.exe</filename> from April 15, 1997.  Version 2.0 does not
work.  The download file is a self-extracting ZIP file, so you will need to run
it in DOS or Windows.  If you can copy it onto the DOS floppy disk image, you
can even boot DOS inside Bochs and run <filename>sbide121.exe</filename> to
extract it.  The driver is called SBIDE.SYS.  </para>
</footnote> and OAKCDROM.SYS that comes with several versions of Windows.
Copy the driver to your boot disk, and then set up the startup files as follows.
</para>
<screen>
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
</screen>

<para>
If the files mentioned in <filename>config.sys</filename> and
<filename>autoexec.bat</filename> are not in the root directory, give the full
pathname, like <filename>c:\windows\himem.sys</filename>.
</para>

</section>
          </section>
	  <section><title>Windows *</title>
             <para>
             </para>
          </section>
	  <section><title>Minix</title>
             <para>
             </para>
          </section>
	  <section><title>[...]</title>
             <para>
             </para>
          </section>
</chapter>


</book>