File: user.dbk

package info (click to toggle)
bochs 2.3-2etch1
links: PTS
area: main
in suites: etch
size: 14,116 kB
ctags: 16,927
sloc: cpp: 130,524; ansic: 18,822; sh: 7,922; makefile: 3,836; yacc: 1,056; asm: 463; perl: 381; lex: 280; csh: 3
file content (10706 lines) | stat: -rw-r--r-- 380,106 bytes
parent folder | download | duplicates (2)
<!--
================================================================
doc/docbook/user/user.dbk
$Id: user.dbk,v 1.218 2006/08/27 07:06:01 vruppert Exp $

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

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

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

]>

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

<!-- *************************************************************** -->
<chapter id="introduction"><title>Introduction to Bochs</title>
<section id="whatisbochs"><title>What is Bochs?</title>
<para>
Bochs is a program that simulates a complete Intel x86 computer.  It 
can be configured to act like a <!--286,--> 386, 486, Pentium, Pentium Pro, or
x86-64 CPU, including optional MMX, SSE/SSE2/SSE3 and 3DNow! instructions.
Bochs interprets every instruction from power-up to reboot, and has
device models for all of the standard PC peripherals: keyboard, mouse,
VGA card/monitor, disks, timer chips, network card, etc.  Because Bochs
simulates the whole PC environment, the software running in the simulation
"believes" it is running on a real machine.  This approach allows Bochs
to run a wide variety of software with no modification, include most popular
x86 operating systems: Windows 95/98/NT/2000, all Linux flavors, all BSD flavors,
and more.
</para>

<para>
Bochs is written in the C++ programming language, and is designed to run
on many different host platforms<footnote>
<para>
Since Bochs can run on one kind of machine and simulate another machine, we
have to be clear in our terminology to avoid confusion.  The host platform is
the machine that runs the Bochs software.  The guest platform is the operating
system and applications that Bochs is simulating.
</para>
</footnote>, including x86, PPC, Alpha, Sun, and MIPS.  No matter what the
host platform is, Bochs still simulates x86 software.  In other words, it
does not depend on the native instructions of the host machine at all.
This is both a strength and a weakness, and it's the major difference between
Bochs and many other x86 emulation software such as plex86, VMware, etc.
Because Bochs uses software simulation for every single x86 instruction, it
can simulate a Windows application on an Alpha or Sun workstation.  However,
the downside of Bochs' approach is simulation performance.  To model the
processor accurately, Bochs must run many instructions for every simulated x86
instruction, and this makes the simulated machine many times slower than
the physical machine.  Commercial PC emulators (VMware, Connectix, etc.) can
achieve much high emulation speed using a technique called 
virtualization<footnote>
<para>
Virtualization takes advantage of simulating x86 instructions on an
x86 machine, allowing large portions of the simulation to take place
at native hardware speed.  Whenever the simulated machine talks to the
hardware or enters certain privileged modes (such as in kernel code),
the simulator typically takes control and simulates that code in
software at much slower speed, just like Bochs does.
</para>
</footnote>, but they are neither portable to non-x86 platforms nor open
source.  The <ulink url="http://savannah.nongnu.org/projects/plex86">Plex86</ulink> project is
working toward an open-source x86 simulator with virtualization.
</para>

<para>
To do anything interesting in the simulated machine, Bochs needs to interact
with the operating system on the host platform (the host OS).  When you press a
key in the Bochs display window, a key event goes into the device model for the
keyboard.  When the simulated machine needs to read from the simulated hard
disk, Bochs reads from a disk image file on the host machine.  When the
simulated machine sends a network packet to the local network, Bochs uses the
host platform's network card to send the packet out into the real world.  These
interactions between Bochs and the host operating system can be complicated,
and in some cases they are host platform specific.  Sending a network packet in
FreeBSD requires different code than sending the packet in Windows 95, for
example.  For this reason, certain features are supported on some host
platforms and not others.  On GNU/Linux, Bochs can simulate a network card that
communicates with the world, but on BeOS the simulated network card may not
work because the communication code between the device model and the BeOS
operating system has not been written.
</para>

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

Bochs was written by Kevin Lawton starting in 1994.  It began as a 
commercial product, which you could buy with source code for ...
&NEEDHELP; <footnote>
<para>
We need a Bochs historian to help out here.  For background, it would be
interesting to know how much Bochs used to cost and what it was used for.  I
thought I saw an interview out there somewhere where Kevin says why he started
it and some more background information.
</para>
</footnote> Finally, in March 2000, MandrakeSoft (now called
<ulink url="http://www.mandriva.com/">Mandriva</ulink>) bought Bochs
(<ulink url="http://www.linux-mandrake.com/en/announce-bochs-20000323.php3">press release</ulink>)
and made it open source under the GNU LGPL.

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

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

<section id="who-uses-bochs"><title>Who uses Bochs?</title>
<para> It is hard to estimate how many people have tried Bochs or use it on a
regular basis, but a few statistics give an indication.  The <link
linkend="bochs-developers">bochs-developers mailing list</link>, which is the
primary source of news on bugs and releases, has over 400 subscribers.  The
latest version has been downloaded over 150,000 times from SourceForge, not
counting any mirror website or CVS users.
</para>

<para>
Bochs has many possible uses, and different people use it for different 
things.  Many people use it to run applications in a second operating system 
without needing two different computers or dual-booting.  Running 
Windows software on a non-x86 workstation or on an x86 Unix box are common
uses.  Also, because every hardware instruction and every line of simulator
code is accessible, Bochs is used extensively for debugging new operating
systems.  If you were writing boot code for your home-brewed
x86 operating system and it didn't work right, booting it in Bochs could
give you great visibility into what is really going on.  The Bochs 
debugger lets you simulate quickly or slowly, pausing whenever you want
to look at the contents of memory or the CPU registers.  Or, if you 
wanted to study which parts of a program take the most time, you could use
Bochs to measure how often certain pieces of the code were executed.
</para>

<para>
Bochs has been used as a teaching tool in Operating Systems classes, in which
students used and modified it to learn how the PC hardware works.  As a final
project the students had to add a new peripheral device, so they had to learn
all about I/O ports, interrupts, and device drivers.  In industry, it is used
to support legacy applications on modern hardware, and as a reference model
when testing new x86-compatible hardware.  
</para>

<para>
There may be as many uses of Bochs as there are users.  Do you want to run 
your old DOS games?  Or learn how to program under GNU/Linux, without leaving your
Windows desktop?  Or reverse engineer your printer driver?  You decide.
</para>

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


<section id="is-bochs-right-for-me"><title>Is Bochs right for me?</title>
<para>
Bochs is very useful for some applications, and not well suited to others.
This section tries to answer the question, "Is Bochs right for me?"
</para>

<para>Bochs may or may not be right for you, depending on what it is you want to do.  
Perhaps all you want to do is run one or two applications native to Microsoft Windows 
on GNU/Linux, or vice-versa.  Perhaps your biggest concern is speed and performance.  
Maybe you don't mind tweaking a few files here and there when you want another application 
to work in that setting.  
In cases where the objective is to simulate x86 hardware on an x86, Plex86, Wine, and 
VMware might be your best options.</para>

<para>
On the other hand, perhaps you have a vital application running on an older operating 
system that only runs well on old hardware.  You are concerned that the life cycle of 
this hardware is coming to an end, and your backup and restoration hardware and tools 
no longer suffice for the amount of data that you have.  You need to transfer backup 
disk images over a network, and want to use modern procedures for hardware maintenance.  
Perhaps the application is important enough to run on a larger computer, such as a 
64-bit machine, or even a mainframe.  Bochs would be an excellent option in such a scenario.
</para>

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

<para>
Information Technology changes faster than any other field.  
It is very easy to forget transitional software that came and went.  
But history is important to all fields, and to build on the future, 
it is important to understand the past.  Computer programmers, however, 
do not have the same advantage as an architect, who can, for example, 
take a trip to Greece and touch a pillar.  Much of the history of Computer 
Science is left on corroding floppies and malfunctioning hardware.  
Bochs gives you the benefit of having one or more complete environments 
where you can understand firsthand the behavior of operating systems and 
programs.  This cannot be achieved with an "emulator" such as Wine.
</para>

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

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

<para>
Whether Bochs works for you depends on your host hardware, host operating 
system, guest operating system, guest software, and your ability to work in 
a command-line environment using documentation.  There is no gui or wizard 
to help you through the setup process.  You do not get a recovery or installation 
disk to assist you in the process of installing a guest operating system.  
Bochs only provides you with the "virtual hardware", and it is up to you to do the rest.
</para>

<para>Bochs will run on Windows, GNU/Linux, FreeBSD, OpenBSD, or BeOS.  
If you are running on x86 hardware, you have a range of choices.  
Check the installation section for your host platform to see what options 
Bochs supports on your platform.  If the most important factor is speed, 
you may want to try a virtualization product instead of Bochs (VMware, plex86).
</para>

<para>
If you are using a non-x86 machine, then Bochs is one of the few choices for
running x86 software.  Bochs has been known to work on Solaris (Sparc), 
GNU/Linux (PowerPC/Alpha), MacOS (PowerPC), IRIX (MIPS), BeOS (PowerPC), Digital
Unix (Alpha), and AIX (PowerPC).
</para>

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

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

<section id="license"><title>Bochs License</title>
<para>
Bochs is copyrighted by MandrakeSoft S.A.<footnote>
<para>
MandrakeSoft has web sites at
<ulink url="http://mandrakesoft.com">http://mandrakesoft.com</ulink> and
<ulink url="http://www.linux-mandrake.com">http://www.linux-mandrake.com</ulink>.
</para>
</footnote>
and distributed under the
GNU Lesser General Public License<footnote>
<para>
Complete text of the GNU LGPL is included with the source code in a file
called COPYING, and is also <ulink url="http://www.gnu.org/licenses/lgpl.html">here</ulink>.
</para>
</footnote>.  The following text appears at the
top of every source code file in the Bochs distribution:
<programlisting>
  This library is free software; you can redistribute it and/or
  modify it under the terms of the GNU Lesser General Public
  License as published by the Free Software Foundation; either
  version 2 of the License, or (at your option) any later version.

  This library is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  Lesser General Public License for more details.

  You should have received a copy of the GNU Lesser General Public
  License along with this library; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
</programlisting>

</para>

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

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

<para>
Before you install or use any Operating System, BIOS, or other software package
within the Bochs PC emulation environment, make sure you are and will be in
compliance with all the software licenses pertaining to the software you wish
to install.  It is completely your responsibility to provide licenses and records
on all software that you install and/or use.  It is also completely your responsibility to
maintain total compliance with all Software Licenses involved.
</para>

<para>
In the process of installing Software within the Bochs PC emulation environment,
it may be helpful or necessary to copy or convert files from the original distribution
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 id="features"><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 one of several families of Intel hardware. Some Pentium features are unsupported, such as MTRR or SMM (System Management Mode).</entry>
  </row>
  <row>
    <entry>P6 and later CPU Emulation</entry>
    <entry>Yes</entry>
    <entry>Bochs can be configured to emulate any P6 family processor including optional MMX and SSE instructions.
    </entry>
  </row>
  <row>
    <entry>Pentium 4 Emulation</entry>
    <entry>Incomplete</entry>
    <entry>A few Pentium 4 features are incomplete, such as an on-chip APIC extensions (XAPIC) for SMP simulation.
    </entry>
  </row>
  <row>
    <entry>x86-64 Extensions Emulation</entry>
    <entry>Yes</entry>
    <entry>Bochs can be configured to emulate x86-64 with all Intel (CMPXCHG16B instruction) or AMD (RDTSCP instruction) extensions.</entry>
  </row>
  <row>
    <entry>Command 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. Unfortunatelly
    the debugger still lacks x86-64 support and almost unusable for debugging 
    x86-64 workloads.
    </entry>
  </row>
  <row>
    <entry>Floating Point</entry>
    <entry>Yes</entry>
    <entry>Uses software floating point engine based on <ulink url="http://www.jhauser.us/arithmetic/SoftFloat.html">SoftFloat floating point emulation library</ulink>.
    </entry>
  </row>
  <row>
    <entry>Enhanced BIOS</entry>
    <entry>Yes</entry>
    <entry>Implements ElTorito, EDD v3.0, basic APM features, basic PCIBIOS features
    and the PCI interrupt routing table.
    </entry>
  </row>
  <row>
    <entry>VGA</entry>
    <entry>Yes</entry>
    <entry>VGA color graphics emulation in a window.
    </entry>
  </row>
  <row>
    <entry>VBE (VESA) Support</entry>
    <entry>Yes</entry>
    <entry>Currently resolutions up to 1024x768x32bpp are supported.
    You must compile Bochs with VBE enabled and use the LGPL'd VGABIOS.
    For more information see <xref linkend="vesa-notes">.
    </entry>
  </row>
  <row>
    <entry>Cirrus Logic video card</entry>
    <entry>Yes</entry>
    <entry>Cirrus Logic CL-GD5430 ISA or CL-GD5446 PCI video card support.
      For more information see <xref linkend="cirrus-notes">.</entry>
  </row>
  <row>
    <entry>Floppy disk</entry>
    <entry>Yes</entry>
    <entry>Supports floppy disk images on all platforms: 2.88M 3.5", 1.44M 3.5", 1.2M 5.25",
    720K 3.5" and 360K 5.25". On Unix and Windows 9x/NT/2000/XP, Bochs can access the
    physical floppy drive.
    </entry>
  </row>
  <row>
    <entry>Multiple ATA channels</entry>
    <entry>Yes</entry>
    <entry>Emulates up to 4 ATA channels. Up to 8 ATA/ATAPI emulated devices can be attached,
    two per ATA channel.
    So you can have eight hard disks or seven hard disks and a CD-ROM or four hard
    disks and four CD-ROMs, or one hard disk and seven CD-ROMs, etc...
    </entry>
  </row>
  <row>
    <entry>Hard disk</entry>
    <entry>Yes</entry>
    <entry>Emulates ATA-2/IDE hard drives via image files.  Physical
    hard disk access is supported on some architecture, but NOT recommended, primarily for safety reasons.
    Hard disk up to 127GB are supported, on any platform that support large files access.
    </entry>
  </row>
  <row>
    <entry>CD-ROM</entry>
    <entry>Yes</entry>
    <entry>Emulates ATAPI-4/IDE CD-ROM.  The CD-ROMs can read from an ISO disk image
    on any platform. On Windows (9x/ME/NT/2000/XP), Linux, SunOS, FreeBSD,
    NetBSD, OpenBSD, Amiga/MorphOS, MacOSX and BeOS, Bochs can read from the
    physical CD-ROM drive. Starting with version 1.4, Bochs is even able to boot from
    a bootable CD or bootable ISO image.
    </entry>
  </row>
  <row>
    <entry>Keyboard</entry>
    <entry>Yes</entry>
    <entry>Emulates a PS/2 keyboard with North American key mappings. Optional keyboard layout
    remapping files are provided to support localized keyboard in X11 (German, French, Italian, Spanish,
    Danish, Swedish, Russian).
    </entry>
  </row>
  <row>
    <entry>Mouse</entry>
    <entry>Yes</entry>
    <entry>Emulates a serial, PS/2 or USB mouse with 3 buttons + optional mouse
    wheel support.
    </entry>
  </row>
  <row>
    <entry>Sound Blaster</entry>
    <entry>Yes</entry>
    <entry>Emulates a Sound Blaster 16 card. On Windows, Linux, FreeBSD, MacOS 9 and
    MacOSX, the output can be sent to the host computer's sound system, see
    <xref linkend="sb16-emulation"> for details.
    </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, on some platforms the guest OS can talk to any machine on
    the network BUT NOT the host machine.  On Windows and on systems that
    allow the TAP or TUN/TAP interface, there is no such limitation.  Often
    the host machine may be configured so the guest OS has access to the
    internet. On MacOSX, you may download the TUN driver from:
    <ulink url="http://chrisp.de/en/projects/tunnel.html"></ulink>
    </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>Yes</entry>
    <entry>The serial port (single 16550A UART emulation) is usable, on GNU/Linux,
    NetBSD, OpenBSD, FreeBSD and MacOSX as host and guest. On other OSes the
    emulation is present, but the connection to hard- or software of the host is
    not implemented yet. Up to 4 ports are available.
    </entry>
  </row>
  <row>
    <entry>Gameport</entry>
    <entry>Yes</entry>
    <entry>Emulates a standard PC gameport. The connection to a real joystick is
    currently supported on Linux and win32 only.
    </entry>
  </row>
  <row>
    <entry>PCI</entry>
    <entry>Yes</entry>
    <entry>Emulates most of the i440FX PCI chipset. The Host-to-PCI bridge
    (PMC/DBX), the PCI-to-ISA bridge and the PCI IDE controller (PIIX3) are
    available. For PCI cards there are 5 PCI slots supported.
    </entry>
  </row>
  <row>
    <entry>USB</entry>
    <entry>incomplete</entry>
    <entry>The USB root hub is available, USB mouse and keypad are implemented,
    other devices are under construction. Access to real hardware and runtime
    options to plug in or remove devices are not implemented yet.
    </entry>
  </row>
  <row>
    <entry>Plugins</entry>
    <entry>Yes</entry>
    <entry>Plugins are supported on Linux, MacOS X, Solaris, and Cygwin.</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 including optional v8086 mode extensions (VME) 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
    <xref linkend="whatisbochs"> for details.
    </entry>
  </row>
  <row>
    <entry>Simulate a Multiprocessor</entry>
    <entry>Yes</entry>
    <entry>Bochs can be configured to simulate up to 8 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>
  <row>
    <entry>Copy and Paste</entry>
    <entry>Yes</entry>
    <entry>Depending on the host platform, the text-mode screen text can be
    exported to the clipboard. Text in the clipboard can also be pasted, through
    Bochs, to the guest OS, as simulated keystrokes.
    </entry>
  </row>
</tbody>
</tgroup>
</table>
</section><!-- End of Features -->

<section id="supported-platforms"><title>Supported Platforms</title>
<para>
The following table shows the supported platforms with a small description and
the available display libraries on these platforms. The display library is the
code that displays the Bochs VGA screen and handles keyboard and mouse events.
</para>
<table><title>Supported platforms</title>
  <tgroup cols="3" align="left" colsep="1" rowsep="1">
  <thead>
    <row>
      <entry>Platform</entry>
      <entry>Description</entry>
      <entry>Display Libraries</entry>
    </row>
  </thead>
  <tbody>

    <row>
      <entry>Unix/X11</entry>
      <entry>
        X windows has always been well supported because it was
        Kevin Lawton's main development platform. Bryce Denney maintains
        the Unix/X11 platform now. Most features and fixes (not all) are
        tried first in Unix and then ported to the others; see
        <xref linkend="compiling"> for compile instructions.
      </entry>
      <entry>x, sdl, wx, term, rfb</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 Microsoft Visual C++ 5.0 or 6.0,
        see <xref linkend="compiling-win32"> for compile instructions,
        or Cygwin, see <xref linkend="compile-cygwin">.
      </entry>
      <entry>win32, sdl, wx, rfb</entry>
    </row>

    <row>
      <entry>BeOS</entry>
      <entry>
        Kevin Lawton wrote 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, and is working on raw CD-ROM and raw floppy
        support. For compiling, see <xref linkend="compile-beos">.
      </entry>
      <entry>beos, sdl</entry>
    </row>

    <row>
      <entry>MacOS X</entry>
      <entry>
        Emmanuel Mailliard ported the Macintosh code to MacOS X with Carbon API.
        Jeremy Parsons (Br'fin) has been maintaining the MacOS X port since
        March 2002; see <xref linkend="compile-macosx"> for compile instructions.
      </entry>
      <entry>carbon, x, rfb, sdl</entry>
    </row>

    <row>
      <entry>Macintosh</entry>
      <entry>
        David Batterham<!-- <email>drbatter@socs.uts.edu.au</email> or <email>drbatter@yahoo.com</email> -->
        ported Bochs to the Mac. He compiled with CodeWarrior Pro R1 (CW12)
        but has not had time to maintain the Mac port since early 2000.
        If you have Mac development tools and want to contribute, contact
        the &devlist;; see <xref linkend="compile-macos9-codewarrior"> for
        compile instructions.
      </entry>
      <entry>macos</entry>
    </row>

    <row>
      <entry>Amiga/MorphOS</entry>
      <entry>
        This port is written and maintained by Nicholai Benalal, see
        <xref linkend="compile-morphos"> for compile instructions.
      </entry>
      <entry>amigaos</entry>
    </row>

    <row>
      <entry>OS/2</entry>
      <entry>
        Nick Behnken used PE2LX to translate David Ross' Win32
        port to an OS/2 program. This hasn't been updated for a long time,
        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.
        If you want to bring the OS/2 port up to date, contact the &devlist;.
      </entry>
      <entry>???</entry>
    </row>

  </tbody>
  </tgroup>
</table>
</section><!-- end: Supported Platforms -->

<section id="faq"><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.  Recently, Kevin has been working
       on a PC virtualization project called <ulink
       url="http://savannah.nongnu.org/projects/plex86">plex86</ulink>. In Fall 2002, he
       made contributed some major CPU speedups and helped with integration
       and debugging of the x86-64 emulation code.
       </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 admins on this
      project are Greg Alexander, Don Becker, Christophe Bothamy, and Bryce
      Denney.
     </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 software)
     or VMware (proprietary and commercial). Another related project is
     <ulink url="http://fabrice.bellard.free.fr/qemu/">QEMU</ulink>.
     </para></answer>
  </qandaentry>

  <qandaentry>
     <question><para>
     Does Bochs use a disk partition to install the OS?
     </para></question>
     <answer><para>
     No. It uses 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>
     Yes. You will usually find Bochs developers and users on IRC at irc.freenode.net:6667, channel #bochs.
     </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 &bochs-sf-net; or on other Bochs sites.
     </para></answer>
  </qandaentry>

  <qandaentry>
     <question><para>
     Does Bochs support a CD-ROM?
     </para></question>
     <answer><para>
     Yes, a CD-ROM is supported in Linux, Windows, BeOS, and most BSDs.  The
CD-ROM drivers for Bochs allow the guest operating system to access the
host operating system's CD-ROM data directly.
     </para></answer>
  </qandaentry>

  <qandaentry>
     <question><para>
     Does Bochs support a sound device?
     </para></question>
     <answer><para>
       Yes, there is Sound Blaster emulation support for most common operation systems,
       see <xref linkend="sb16-emulation"> for details.
     </para></answer>
  </qandaentry>

  <qandaentry>
     <question><para>
     Does Bochs support a network card?
     </para></question>
     <answer><para>
     Yes.  Bochs contains a model of an NE2000 compatible network card.
     Networking is not supported on all platforms.  See 
     <xref linkend="features"> for details.
     </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 you are asking about Windows programs.
   To give you a few, the following ones from the Winstone'98 tests
   worked: Access 97, CorelDRAW! 7, Excel 97, Lotus 1-2-3 97, Word 97,
   PowerPoint 97, Quattro Pro 7, WordPerfect 7.
</para>

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

  <qandaentry>
    <question><para>
      I am new to Bochs, how do I start?
    </para></question>
    <answer><para>
      You should read <xref linkend="setup"> first. Next, you can check <xref linkend="guests">
      if there are already instructions on how to install your (guest) OS inside of Bochs.
    </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 id="release-notes"><title>Release Notes</title>

<para>
The change log is stored in the Bochs source code in a file called
CHANGES.  Click <ulink url="http://cvs.sourceforge.net/viewcvs.py/bochs/bochs/CHANGES?rev=HEAD&amp;content-type=text/vnd.viewcvs-markup">here</ulink> to see the latest version of the CHANGES file.
</para>
<para>
The link above is provided by Source Forge and might change one day.  If it
stops working, you can download the current source code with CVS and read
the CHANGES file there.
</para>

</chapter>




<!-- *************************************************************** -->
<chapter id="installation"><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@bochs.cvs.sourceforge.net:/cvsroot/bochs login</command>
  (Logging in to anonymous@bochs.cvs.sourceforge.net)
  CVS password:    <replaceable>(there is no password, just press Enter)</replaceable>
  user$ <command>cvs -z3 -d:pserver:anonymous@bochs.cvs.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          bx_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>

<note><para>
  This is just an example output of a checkout of an older version of Bochs.
  You most likely will see more/other files.
</para></note>

<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>
See the <ulink url="../development/resources.html">Developers Guide</ulink>
and/or look at <ulink url="http://sourceforge.net/cvs/?group_id=12580">CVS repository information</ulink>,
section "Developer CVS Access via SSH", for instructions.
</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>patch</entry>
        <entry>
        This does the same as U, but instead of sending the whole file
        (update), only a diff/patch is sent, thus, less bandwidth is used.
        </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>2.3</entry>
        <entry>REL_2_3_FINAL</entry>
      </row>
      <row>
        <entry>2.2.6 (intermediate2)</entry>
        <entry>REL_2_2_6_FINAL</entry>
      </row>
      <row>
        <entry>2.2.5 (intermediate1)</entry>
        <entry>REL_2_2_5_FINAL</entry>
      </row>
      <row>
        <entry>2.2.1 (bugfix1)</entry>
        <entry>REL_2_2_1_FINAL</entry>
      </row>
      <row>
        <entry>2.2</entry>
        <entry>REL_2_2_FINAL</entry>
      </row>
      <row>
        <entry>2.1.1 (bugfix1)</entry>
        <entry>REL_2_1_1_FINAL</entry>
      </row>
      <row>
        <entry>2.1</entry>
        <entry>REL_2_1_FINAL</entry>
      </row>
      <row>
        <entry>2.0.2 (bugfix2)</entry>
        <entry>REL_2_0_2_FINAL</entry>
      </row>
      <row>
        <entry>2.0.1 (bugfix1)</entry>
        <entry>REL_2_0_1_FINAL</entry>
      </row>
      <row>
        <entry>2.0</entry>
        <entry>REL_2_0_FINAL</entry>
      </row>
      <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.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>
The Bochs binaries for Windows are distributed in an EXE installer package.
The Bochs installer can be started like any other Windows program and it brings
up the installation wizard. Here you can select the destination folder and the
installation options. The wizard installs the files and creates the registry
keys, start menu and desktop links.
</para>
<para>
Previous releases of Bochs were distributed as ZIP packages, too. These packages
contained the same set of files as the installer package from the same version.
</para>
<para>
If you are new to Bochs you should try out the DLX Linux demo distributed with
Bochs. The installation wizard has created a link on the desktop if you decided
to install the demo. If you doubleclick the icon two windows will appear:
one is the Bochs Display window, and the other is text window that is used for
the runtime configuration and for log messages if no logfile is specified.
</para>
<para>
You can find more information on the DLX Linux demo in the next section below the
DLX Linux screenshot.
</para>

<table><title>Files in Bochs directory (Windows version)</title>
<tgroup cols="2" align="left" colsep="1" rowsep="1">
<thead> <row> <entry>File</entry> <entry>Description</entry> </row>
</thead>
<tbody>

<row><entry>BIOS-bochs-latest </entry> <entry> ROM BIOS image for Bochs </entry> </row>
<row><entry>bochs.exe </entry> <entry> the main Bochs executable </entry> </row>
<row><entry>bochs.ico </entry> <entry> the Bochs icon (used for links in start menu and on the desktop) </entry> </row>
<row><entry>bochsdbg.exe </entry> <entry> the main Bochs executable with debugger enabled </entry> </row>
<row><entry>bochsrc-sample.txt </entry> <entry> sample Bochs configuration file </entry> </row>
<row><entry>bxcommit.exe </entry> <entry> tool for committing redologs to flat disk images </entry> </row>
<row><entry>bximage.exe </entry> <entry> tool for making new disk images </entry> </row>
<row><entry>CHANGES.txt </entry> <entry> what has changed between versions </entry> </row>
<row><entry>COPYING.txt </entry> <entry> copy of the LGPL license </entry> </row>
<row><entry>README.txt </entry> <entry> the read-me file from the source distribution. </entry> </row>
<row><entry>TODO.txt </entry> <entry> the TODO file from the source distribution. </entry> </row>
<row><entry>niclist.exe </entry> <entry> tool to find out the network interface name </entry> </row>
<row><entry>penguin.ico </entry> <entry> the Linux logo (used for the DLX link in start menu) </entry> </row>
<row><entry>sb16ctrl.exe </entry> <entry> tool to control sb16 in Bochs </entry> </row>
<row><entry>sb16ctrl.txt </entry> <entry> examples of sb16ctrl commands </entry> </row>
<row><entry>VGABIOS-elpin-2.40 </entry> <entry> VGA BIOS image for Bochs </entry> </row>
<row><entry>VGABIOS-elpin-LICENSE.txt </entry> <entry> license for VGA BIOS </entry> </row>
<row><entry>VGABIOS-lgpl-latest </entry> <entry> LGPL'd VGA BIOS image for Bochs </entry> </row>
<row><entry>VGABIOS-lgpl-latest-debug </entry> <entry> LGPL'd VGA BIOS image for Bochs with debug output to the logfile </entry> </row>
<row><entry>VGABIOS-lgpl-latest-cirrus </entry> <entry> LGPL'd VGA BIOS image for Bochs with the Cirrus extension enabled </entry> </row>
<row><entry>VGABIOS-lgpl-latest-cirrus-debug </entry> <entry> LGPL'd VGA BIOS image for Bochs with the Cirrus extension enabled and debug output to the logfile </entry> </row>
<row><entry>VGABIOS-lgpl-README.txt </entry> <entry> readme for the LGPL'd VGA BIOS </entry> </row>
<row><entry>uninstall.exe </entry> <entry> uninstall program for Bochs (created by the installation wizard) </entry> </row>
<row><entry>dlxlinux\ </entry> <entry> directory containing DLX linux sample disk image and configuration files</entry> </row>
<row><entry>dlxlinux\readme.txt </entry> <entry> description of DLX linux</entry> </row>
<row><entry>dlxlinux\bochsrc.txt </entry> <entry> Bochs configuration file for DLX</entry> </row>
<row><entry>dlxlinux/hd10meg.img </entry> <entry> disk image file (10 meg) </entry> </row>
<row><entry>dlxlinux\start.bat </entry> <entry> Run this BAT file to try out DLX Linux inside Bochs! </entry> </row>
<row><entry>dlxlinux\testform.txt </entry> <entry> Form for reporting success or failure </entry> </row>
<row>
  <entry>doc\index.html</entry>
  <entry>a local copy of all Bochs documentation (<ulink url="http://bochs.sourceforge.net/doc/docbook/index.html">online copy</ulink>)</entry>
</row>
<row><entry>keymaps\*.map </entry> <entry>keymap tables (on Windows used for the paste feature only) </entry> </row>
</tbody>
</tgroup>
</table>

</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.  First, download the
Bochs RPM for your architecture to your computer.  For example, if you have an
Intel-compatible computer, be sure to get the RPM that says "for Linux x86
distributions" or "i386".  Once you have the package on your local disk, you
should become the root user and install it as follows<footnote>
<para>
Many distributions have their own RPM installer program, often graphical, and
they should work ok.  It is helpful to be able to see the text output from
RPM, so if you use a fancy RPM installer, be sure to find the text output and
check that it looks correct.
</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>

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

<para>
RPM installation can fail for a few reasons.  It will fail if you already
have a Bochs package installed.  In this case, try upgrading the old package
to the new package with <command>rpm --upgrade NAME.i386.rpm</command>.
Another potential problem is missing RPM dependencies.  If you are getting
errors about missing files or RPMs, then first you should try to 
install the RPMs that provide the missing pieces.  If that cannot be done,
download the source RPM and build a new binary RPM that is appropriate
for your platform.  The command is <command>rpmbuild --rebuild
NAME.src.rpm</command>.  As a last resort, you can run rpm with the
<command>--nodeps</command> option to ignore dependencies and install it
anyway, but if it is missing important pieces it may not run properly.
</para>

<para>
The Bochs RPM installs four new commands and associated manual pages: bochs,
bochs-dlx, bximage and bxcommit.  First, let's try out the DLX Linux demo by typing
<command>bochs-dlx</command>.  

<screen>
  user$ bochs-dlx
  ---------------------------------------------------------------
	      DLX Linux Demo, for Bochs x86 Emulator
  ---------------------------------------------------------------
  Checking for bochs binary...ok
  Checking for DLX linux directory...ok
  Checking for /bin/gzip...ok
  Checking for /usr/users/bryce/.bochsdlx directory...
  ---------------------------------------------------------------
  To run the DLX Linux demo, I need to create a directory called
  /usr/users/bryce/.bochsdlx, and copy some configuration files
  and a 10 megabyte disk image into the directory.
  ---------------------------------------------------------------
  Is that okay? [y/n]
  y
  Copying /usr/share/bochs/dlxlinux/bochsrc.txt -> /usr/users/bryce/.bochsdlx/.
  Copying /usr/share/bochs/dlxlinux/README -> /usr/users/bryce/.bochsdlx/.
  Copying /usr/share/bochs/dlxlinux/testform.txt -> /usr/users/bryce/.bochsdlx/.
  Uncompressing /usr/share/bochs/dlxlinux/hd10meg.img.gz -> /usr/users/bryce/.bochsdlx/hd10meg.img
  Entering /usr/users/bryce/.bochsdlx
  Running bochs
  ========================================================================
			Bochs x86 Emulator 2.0.pre3
		Build from CVS snapshot on December 4, 2002
  ========================================================================
</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>Screenshot of Bochs running DLX Linux</title>
<graphic format="PNG" fileref="../images/dlxlinux-in-linux.png">
</figure>
</para>

<para>
Booting is complete when you see "dlx login:" and a cursor.  At this login
prompt, type "root".  On UNIX systems, root is the system admin user.
There is no password for root on this sample disk image, so it lets you log 
in without typing any password.  Now you should see a UNIX prompt, and you 
can begin to type UNIX commands.
</para>

<screen>
  Welcome to DLX V1.0 (C) 1995-96 Erich Boehm
                      (C) 1995    Hannes Boehm

  dlx login: <command>root</command>
  Linux 1.3.89.
  dlx:~# <command>pwd</command>
  /root
  dlx:~# <command>cd /</command>
  dlx:~# <command>ls</command>
  bin/       etc/       lost+found/       root/       usr/
  boot/      fd/        mnt/              sbin/       var/
  dev/       lib/       proc/             tmp/        zip/
  dlx:/# <command>df</command>
  Filesystem    1024-blocks   Used  Available Capacity Mounted on
  /dev/hda1        10060      2736      6005     29%   /
  dlx:/# _
</screen>

<para>
When you get tired of playing with DLX Linux, just type "reboot" in the Bochs
window to shut down the DLX Linux operating system, and when it starts
to reboot again press the "Power" button at the top of the Bochs display
to end the application.
</para>


<para>
Here is a list of the files that are installed by the RPM, and a brief
description of each one.
</para>

<table><title>Files in RPM package</title>
<tgroup cols="2" align="left" colsep="1" rowsep="1">
<thead> <row> <entry>File</entry> <entry>Description</entry> </row>
</thead>
<tbody>

<row><entry>/usr/share/doc/bochs/CHANGES</entry> <entry> what has changed between versions </entry> </row>
<row><entry>/usr/share/doc/bochs/COPYING</entry> <entry> copy of the LGPL license </entry> </row>
<row><entry>/usr/share/doc/bochs/README</entry> <entry> the read-me file from the source distribution. </entry> </row>
<row><entry>/usr/share/doc/bochs/TODO</entry> <entry> the TODO file from the source distribution. </entry> </row>
<row><entry>/usr/bin/bochs </entry> <entry> the main Bochs executable </entry> </row>
<row><entry>/usr/bin/bximage </entry> <entry> tool for making new disk images </entry> </row>
<row><entry>/usr/bin/bxcommit </entry> <entry> tool for committing redologs to flat disk images </entry> </row>
<row><entry>/usr/lib/bochs/plugins/* </entry> <entry> device and gui plugins for Bochs (plugin version only) </entry> </row>
<row><entry>/usr/share/doc/bochs/bochsrc-sample.txt</entry> <entry> sample Bochs configuration file </entry> </row>
<row><entry>/usr/share/man/man1/* </entry> <entry> man pages for bochs, bochs-dlx, bximage and bxcommit</entry> </row>
<row><entry>/usr/share/man/man5/* </entry> <entry> man page for bochsrc </entry> </row>
<row><entry>/usr/share/doc/bochs/index.html</entry> <entry> a local copy of all Bochs documentation ( <ulink url="http://bochs.sourceforge.net/doc/docbook/index.html">Online copy</ulink> )</entry> </row>
<row><entry>/usr/share/bochs/BIOS-bochs-latest </entry> <entry> ROM BIOS image for Bochs </entry> </row>
<row><entry>/usr/share/bochs/VGABIOS-elpin-2.40 </entry> <entry> VGA BIOS image for Bochs </entry> </row>
<row><entry>/usr/share/bochs/VGABIOS-elpin-LICENSE </entry> <entry> license for VGA BIOS </entry> </row>
<row><entry>/usr/share/bochs/VGABIOS-lgpl-latest </entry> <entry> LGPL'd VGA BIOS image for Bochs </entry> </row>
<row><entry>/usr/share/bochs/VGABIOS-lgpl-latest-debug </entry> <entry> LGPL'd VGA BIOS image for Bochs with debug output to the logfile </entry> </row>
<row><entry>/usr/share/bochs/VGABIOS-lgpl-latest-cirrus </entry> <entry> LGPL'd VGA BIOS image for Bochs with the Cirrus extension enabled </entry> </row>
<row><entry>/usr/share/bochs/VGABIOS-lgpl-latest-cirrus-debug </entry> <entry> LGPL'd VGA BIOS image for Bochs with the Cirrus extension enabled and debug output to the logfile </entry> </row>
<row><entry>/usr/share/bochs/VGABIOS-lgpl-README </entry> <entry> readme for the LGPL'd VGA BIOS </entry> </row>
<row><entry>/usr/bin/bochs-dlx </entry> <entry> run this script to try out DLX Linux inside Bochs!</entry> </row>
<row><entry>/usr/share/bochs/dlxlinux/ </entry> <entry> directory containing DLX linux sample disk image and configuration files</entry> </row>
<row><entry>/usr/share/bochs/dlxlinux/readme.txt</entry> <entry> description of DLX linux</entry> </row>
<row><entry>/usr/share/bochs/keymaps/*.map </entry> <entry>keymap tables for X11 and SDL </entry> </row>
</tbody>
</tgroup>
</table>


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

<section id="macosxdmg">
<title>MacOS X DMG</title>
<para>
This was contributed by Aard Vark in January 2003
</para>
<para>
The MacOS X binary distribution is a mountable disk
image (.dmg file). Once you've downloaded the binary 
distribution file, just double click
on it to automatically unpack the archive and mount
the volume on the desktop.  An icon will appear 
exactly as if you'd inserted a CD-ROM
or removable storage device, and a finder window
containing the volume should automatically open.  
It is likely to have an odd name
such as _dmg_top, but don't worry about that.
</para>
<para>
Copy the Bochs-2.0 (or whatever version) folder from
the disk image onto your hard disk.  Either Home or 
Applications would be sensible places to put it.  
Because the disk image is mounted read only, you
can't run the included dlxlinux guest OS until
you've copied it to the hard disk.  
</para>
<para>
Once you've installed the binaries, it's probably a
good idea to drag the _dmg_top volume to trash to
unmount it, so you don't get confused and try to 
run bochs from there.  Then open
the bochs folder from wherever you installed it.
</para>
<para>
The MacOS X version of bochs requires a terminal
window to run. If you just double click on the Bochs 
icon, you'll get an error message telling you to 
double click on "bochs.scpt" to start
Bochs in a new terminal window.  You'll need to
configure Bochs before you will get very far with 
the bochs.scpt in the top folder,
so to try out bochs open the dlxlinux folder and
double click on the bochs.scpt icon inside.
</para>
<para>
This will open a new terminal window which will
contain the Bochs startup messages, and a 
configuration menu.  The default option is
[5], which starts the simulation, so press enter to
do so.  You will then get a new window containing 
the VGA display of the simulated
machine.  The new window will probably appear behind
the current terminal window, so either click on the
bochs icon in the dock or the simulation window to 
bring it to the front.  If you're quick
enough you'll then see the VGA BIOS screen, then
Linux  uncompresses and boots, and you get a login 
prompt.  Type "root" and ENTER to log in to DLX Linux.
</para>
<para>
Once you've finished playing with DLX Linux, just
type "reboot" in the Bochs window to shut down the 
DLX Linux operating system, and 
when it starts to reboot again press the "Power"
button in the "MacBochs Hardware Controls" window 
(it's the circle containing a vertical bar at the 
far right - have a look at the Linux screenshots,
since the Mac version doesn't seem to have
descriptions or tool-tips).
</para>

</section> <!-- end of Installing a Binary:MacOS X 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. Some of these scripts have been used to build official
binary packages.

<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.macos
  .conf.macosx
  .conf.win32-vcpp
  .conf.win32-cygwin
  .conf.AIX.4.3.1
  .conf.beos
</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.
By default the files are copied to some directories in /usr/local. The following
tables shows the directories and their contents.
<footnote><para>
&FIXME;
    make install_dlx option
</para></footnote>
</para>
<table><title>Installed files</title>
  <tgroup cols="2" align="left" colsep="1" rowsep="1">
  <tbody>
    <row>
      <entry>bin</entry>
      <entry>binary executables (bochs, bxcommit, bximage)</entry>
    </row>
    <row>
      <entry>lib/bochs/plugins</entry>
      <entry>plugins (if present)</entry>
    </row>
    <row>
      <entry>man/man1</entry>
      <entry>manpages for installed binaries</entry>
    </row>
    <row>
      <entry>man/man5</entry>
      <entry>manpage for the config file (bochsrc)</entry>
    </row>
    <row>
      <entry>share/bochs</entry>
      <entry>BIOS images, VGABIOS images, keymaps</entry>
    </row>
    <row>
      <entry>share/doc/bochs</entry>
      <entry>HTML docs, license, readme, changes, bochsrc sample</entry>
    </row>
  </tbody>
  </tgroup>
</table>
</section>

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

<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 the <option>--with-*</option> options to override the default.  The
options in the first table tell which GUI library is the default for each
platform.  Starting in version 2.0, you can use multiple
<option>--with-*</option> options at once to compile with multiple
display libraries, and then choose between them at runtime with the
<link linkend="bochsopt-displaylibrary">display_library option</link>
in the configuration file. Or, you can
let the configure script detect which libraries are on your system
and use them all, by configuring with --with-all-libs.
</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 Display Library (optional)</title>
<tgroup cols="2" align="left" colsep="1" rowsep="1">
  <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</entry>
      <entry>Use the native Win32 GUI. This is the default on win32 platforms.
      </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>
        Enable support for the RFB protocol to talk to AT&amp;T's
        <ulink url="http://www.realvnc.com/">VNC Viewer</ulink>.
        Refer to <xref linkend="compile-rfb"> for details.
      </entry>
    </row>
    <row>
      <entry>--with-sdl</entry>
      <entry>Enable support for the SDL GUI interface; see <xref linkend="compile-sdl">.</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.
        </entry>
    </row>
    <row>
      <entry>--with-wx</entry>
      <entry>
        Enable support for wxWidgets configuration and display interface;
        see <xref linkend="compile-wx">.
      </entry>
    </row>
    <row>
      <entry>--with-svga</entry>
      <entry>Use SVGALIB library for Linux.  This allows a full-screen
        text and graphics display without X windows.  The SVGALIB port
	was written by Igor Popik.
        </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>
    <row>
      <entry>--with-all-libs</entry>
      <entry>
      Automatically detect which libraries are installed on your system
      and enable them.  This option is still experimental; it might
      enable libraries that are not usable and cause the compile to fail.
      If you have trouble, just list the --with-* options for the specific
      display libraries that you want.
      </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>

<para>
&NEEDHELP; Link CPU link to the proper row, not to the beginning of the whole table, as it is now.
</para>

<table><title>Configure Options</title>
<tgroup cols="3" align="left" colsep="1" rowsep="1">
  <thead>
    <row>
      <entry>Option</entry>
      <entry>Default</entry>
      <entry>Comments</entry>
   </row>
  </thead>
  <tbody>
    <row id="configure-enable-cpu-level">
      <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>yes</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, FreeBSD, 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</option>}</entry>
      <entry>no</entry>
      <entry>
      Enable Sound Blaster emulation.
      The <constant>dummy</constant> option means to support an SB16, but don't
      use an output device. By default (without a parameter) the lowlevel sound interface is autodetected.
      See section <link linkend="sb16-emulation">Sound Blaster 16 Emulation</link>
      for supported platforms and more info. This option also enables the standard PC gameport which is a
      part of the SB16. If you don't want to use it, you might use
      <option>--disable-gameport</option>.
      </entry>
    </row>
    <row>
      <entry>--enable-gameport</entry>
      <entry>no</entry>
      <entry>
      Enables the standard PC gameport. This option is only necessary if you want to
      have a gameport, but no SB16 (see above). The connection to a real joystick is
      currently supported on Linux and win32 only.
      </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-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. It only works with X11 or term GUI.
      </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-pnic</entry>
      <entry>no</entry>
      <entry>Enable PCI pseudo NIC (network card) support.</entry>
    </row>
    <row>
      <entry>--enable-vbe</entry>
      <entry>no</entry>
      <entry>Use VGA BIOS Extensions (VBE) by Jeroen Janssen, see <xref linkend="vesa-notes">
      for more information.
      </entry>
    </row>
    <row>
      <entry>--enable-clgd54xx</entry>
      <entry>no</entry>
      <entry>Enable Cirrus Logic GD54xx (CL-GD5430 ISA or CL-GD5446 PCI) video
      card support. For more information see <xref linkend="cirrus-notes">.
      </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 Stanislav Shwartsman, use this option.
      </entry>
    </row>
    <row>
      <entry>--enable-plugins</entry>
      <entry>no</entry>
      <entry>
      Plugins are shared libraries that can be loaded on demand.  Example: the
      serial device is implemented as a plugin.  In Unix, the serial plugin is
      called libbx_serial.so.  When Bochs reads its configuration file, if the
      serial device is enabled it loads libbx_serial.so.  See the Features
      section for supported platforms.
      </entry>
    </row>
    <row>
      <entry>--enable-guest2host-tlb</entry>
      <entry>no</entry>
      <entry>support guest to host address TLB for speed</entry>
    </row>
    <row>
      <entry>--enable-repeat-speedups</entry>
      <entry>no</entry>
      <entry>support repeated I/O and memory copy speedups</entry>
    </row>
    <row>
      <entry>--enable-icache</entry>
      <entry>no</entry>
      <entry>support instruction cache for faster execution</entry>
    </row>
    <row>
      <entry>--enable-host-specific-asms</entry>
      <entry>yes</entry>
      <entry>support for running native x86 instructions on an x86 machine</entry>
    </row>
    <row>
      <entry>--enable-fast-function-calls</entry>
      <entry>no</entry>
      <entry>support for fast function calls (gcc on x86 only)</entry>
    </row>
    <row>
      <entry>--enable-all-optimizations</entry>
      <entry>no</entry>
      <entry>
        Turn on the enables for all speed optimizations that the
        developers believe are safe to use:
         --enable-guest2host-tlb,
         --enable-repeat-speedups,
         --enable-icache,
         --enable-host-specific-asms,
         --enable-fast-function-calls.
      </entry>
    </row>
    <row>
      <entry>--enable-ignore-bad-msr</entry>
      <entry>yes</entry>
      <entry>ignore MSR references that Bochs does not understand, instead of doing a panic</entry>
    </row>
    <row>
      <entry>--enable-x86-64</entry>
      <entry>no</entry>
      <entry>
      Add support for AMD's x86-64 instruction set, written by Peter Tattam.
      The AMD x86-64 support is about 90% complete and is still experimental.
      The code has been tested on a limited number of test programs.
      </entry>
    </row>
    <row>
      <entry>--enable-mmx</entry>
      <entry>no (yes for <link linkend="configure-enable-cpu-level">CPU</link> >= 5)</entry>
      <entry>
      Add support for MMX instructions, written by Stanislav Shwartsman.
      </entry>
    </row>
    <row>
      <entry>--enable-sse=LEVEL</entry>
      <entry>no</entry>
      <entry>
      Add support for SSE instructions, written by Stanislav Shwartsman.
      Any of SSE/SSE2/SSE3 instruction sets are supported.
      </entry>
    </row>
    <row>
      <entry>--enable-sep</entry>
      <entry>no</entry>
      <entry>SYSENTER/SYSEXIT support</entry>
    </row>
    <row>
      <entry>--enable-vme</entry>
      <entry>no (yes for <link linkend="configure-enable-cpu-level">CPU</link> >= 5)</entry>
      <entry>Add support for VME (v8086 mode extensions)</entry>
    </row>
    <row>
      <entry>--enable-compressed-hd</entry>
      <entry>no</entry>
      <entry>
      Add support for compressed disk (not implemented yet).
      zlib must be installed on your system, as it will be dynamically linked to Bochs.
      </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 <command>./configure</command>, you may want to edit
        <filename>config.h</filename> to customize the debugger further;
        see <xref linkend="internal-debugger"> for more information.
      </entry>
    </row>
    <row>
      <entry>--enable-readline</entry>
      <entry>detected by configure</entry>
      <entry>
      Compile the debugger with the GNU readline library, which gives
      command line editing and history.
      </entry>
    </row>
    <row>
      <entry>--enable-disasm</entry>
      <entry>yes</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.</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>
    <row>
      <entry>--enable-docbook</entry>
      <entry>detected</entry>
      <entry>
      Build the docbook documentation in doc/docbook.  The configure
      script will enable this option automatically if you have a program
      called docbook2html installed.
      </entry>
    </row>
    <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 the
      <ulink url="http://bochs.sourceforge.net/docs-html/iodebug.html">old documentation</ulink> for
      details.
      <footnote><para>&FIXME; move iodebug.html to the new developer docs</para></footnote>
      </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-external-debugger</entry>
      <entry>no</entry>
      <entry>Enable external debugger support (only available on Win32).</entry>
    </row>
    <row>
      <entry>--enable-pci</entry>
      <entry>no</entry>
      <entry>Enable limited i440FX PCI support. This is still incomplete, but usable.
      </entry>
    </row>
    <row>
      <entry>--enable-pcidev</entry>
      <entry>no</entry>
      <entry>
        Enable PCI host device mapping support. This requires --enable-pci
        to be set as well as Linux 2.4 or 2.6 as host.
      </entry>
    </row>
    <row>
      <entry>--enable-usb</entry>
      <entry>no</entry>
      <entry>
        Enable limited i440FX PCI USB support. This is not yet complete.
      </entry>
    </row>
    <row>
      <entry>--enable-4meg-pages</entry>
      <entry>no (yes for <link linkend="configure-enable-cpu-level">CPU</link> > 4)</entry>
      <entry>support 4 megabyte page extensions (PSE, page size extension)</entry>
    </row>
    <row>
      <entry>--enable-pae</entry>
      <entry>no (yes for <link linkend="configure-enable-cpu-level">CPU</link> > 5)</entry>
      <entry>support physical address extensions</entry>
    </row>
    <row>
      <entry>--enable-global-pages</entry>
      <entry>no (yes for <link linkend="configure-enable-cpu-level">CPU</link> > 5)</entry>
      <entry>support global pages</entry>
    </row>
    <row>
      <entry>--enable-port-e9-hack</entry>
      <entry>yes</entry>
      <entry>Writes to port e9 go to console.  Unless you know you want
          this option, you don't.</entry>
    </row>
    <row>
      <entry>--enable-smp</entry>
      <entry>no</entry>
      <entry>
      Compile in support for SMP simulation.  This allows you to boot Linux and
      maybe other OSes in SMP mode, and bochs will simulate all the different
      CPUs and communication between them.  Do not expect this option to speed
      up your simulation!  On the contrary, it has to spend extra time simulating
      the different CPUs (even if they're mostly idle) and the communication
      between them. Use it to try out an SMP OS if you don't have an SMP machine,
      or to debug SMP OS drivers. Refer to <xref linkend="SMP"> 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-xpm</entry>
      <entry>yes</entry>
      <entry>
      Enables the check for the XPM library. This option is only valid if the
      x display library is enabled (<option>--with-x11</option>).
      </entry>
    </row>
    <row>
      <entry>--enable-show-ips</entry>
      <entry>no</entry>
      <entry>
      Enables logging of measured IPS, see the <command>ips</command> parameter
      of the <link linkend="bochsopt-cpu">cpu option</link>.
      </entry>
    </row>
    <row>
      <entry>--enable-save-restore</entry>
      <entry>no</entry>
      <entry>
      Enables limited save/restore support. The state of CPU, memory and all
      devices can be saved now (state of harddisk images not handled yet).
      See <link linkend="using-save-restore">Save and restore simulation</link>
      for more information.
      </entry>
    </row>
  </tbody>
</tgroup>
</table>

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




<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 the 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>
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>, <filename>bxcommit.exe</filename> 
and <filename>niclist.exe</filename>.
</para>

<para>
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 controlled by
the configure script.  When you compile with certain configure options (e.g.
--with-sdl) you need to link with additional libraries.  For now you must
add them to the VC++ workspace by hand.  In version 2.0, we have improved 
the situation considerably by adding #if...#endif around every optional file
and including nearly every Bochs source file in the workspace.  This solves the
problem of having to manually add source files to the workspace when you turn
on configure options such as --enable-debugger.  The problem of adding
link libraries remains unresolved.
</para>

<tip>
<para>
To compile with the Bochs debugger enabled, add "--enable-debugger" to the
configure line in <filename>.conf.win32-vcpp</filename> before running it.
No modifications to the workspace are necessary.
</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 was new in
version 1.3; before that, nmake was the only way to compile Bochs in VC++.
Starting with version 1.4, the workspace is used to build the release 
binaries.
</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>
To find out the options which are known to work in Cygwin, open the file
<filename>.conf.win32-cygwin</filename> in any text editor/viewer and have
a look at the end of that file.
</para>
</section>  <!-- end of cygwin -->

<section id="compile-macos9-codewarrior"><title>Compiling on MacOS 9 with CodeWarrior</title>
<para>
  It is possible that this hasn't been tried since 1999. In theory, you
  run <command>sh .conf.macos</command> 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 us know by contacting the &devlist;. Someone requests a MacOS port
  almost once a month, but none of the developers know how to help them.
</para>
</section><!-- end: Compiling on MacOS 9 with CodeWarrior -->

<section id="compile-macosx"><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 <option>--with-x11</option> for X windows,
<option>--with-rfb</option> for VNC/RFB, or <option>--with-sdl</option> for SDL.
</para>
</section><!-- end: Compiling on MacOS X -->

<section id="compile-beos"><title>Compiling on BeOS</title>
<para>
  Kevin Lawton ported Bochs to BeOS. Bernd Korz has taken over the port.
  Since Bochs 1.4, you can use the same compile and install process as on
  Unix, that is, configure will detect the BeOS platform and assume you
  want the BeOS GUI.
<screen>
  configure
  make
</screen>
  Optionally, you can use the configure shortcut script for BeOS,
  <filename>.conf.beos</filename>, which uses the SDL GUI by default.
</para>
</section><!-- end: Compiling on BeOS -->

<section id="compile-morphos"><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
  <option>--enable-amigaos</option> as a configure option. Optionally, you
  can use the configure shortcut script, <filename>.conf.amigaos</filename>.
</para>
</section><!-- end: Compiling on Amiga/MorphOS -->

<section id="compile-rfb"><title>Compiling with the RFB interface</title>
<para>
  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>.
</para>
<para>
  This interface allows you to view the Bochs display with
  AT&amp;T's <ulink url="http://www.realvnc.com/">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 and has
  been tested in Linux and Win32. No additional libraries are required.
  To try it, type:
<screen>
  configure --with-rfb
  make
</screen>
  RFB currently uses this setup:
<itemizedlist>
  <listitem><para>port range 5900 to 5949 (using the first one available)</para></listitem>
  <listitem><para>no authentification</para></listitem>
  <listitem><para>30 seconds waiting for client</para></listitem>
  <listitem><para>8 bpp (BGR233) supported only</para></listitem>
  <listitem><para>desktop size 720x480 (for text mode and standard VGA)</para></listitem>
</itemizedlist>
</para>
</section><!-- end compile-rfb -->

<section id="compile-sdl"><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 is available
  for many platforms including Win32, Linux, BSD, IRIX, MacOS, MacOS X, BeOS,
  and AmigaOS.
</para>
<para>
  To compile Bochs 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).
  Then, go into the Bochs directory and type:
<screen>
  configure --with-sdl
  make
</screen>
</para>
<para>
  If you are on FreeBSD and have SDL installed using the ports collection, Bochs
  won't be able to find the library automatically, as the SDL config script is
  called <filename>sdl11-config</filename> in that case (even for version 1.2).
  The easiest way to make Bochs find it, is to create a symlink to that script
  called <filename>sdl-config</filename> inside a directory which is in the path.
  For example:
<screen>
  ln -s /usr/local/bin/sdl11-config ~/bin/sdl-config
</screen>
</para>
<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><!-- end compile-sdl -->

<section id="compile-wx">
<title>Compiling with the wxWidgets interface</title>
<para>
  wxWidgets is a cross-platform C++ user interface library which
  you can download for free at <ulink url="http://wxwidgets.org/">wxwidgets.org</ulink>.
  The wxWidgets port of Bochs provides both a graphical configuration interface for
  editing <filename>bochsrc</filename> options (see
  <link linkend="bochsopt-configinterface">config_interface option</link>) and a
  display (see <link linkend="bochsopt-displaylibrary">display_library option</link>).
  It was written by Bryce Denney, Don Becker, Dave Poirier, and Volker Ruppert.
<screen>
  configure --with-wx
  make
</screen>
</para>
<para>
  If you want Bochs to use a wxWidgets installation not in your path (but installed
  somewhere else), you need to set the WX_CONFIG environment variable to the
  proper wx-config script, before running configure (example for csh):
<screen>
  setenv WX_CONFIG '/home/compile/wx/bin/wx-config'
</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>
  ./build/redhat/make-rpm | tee /tmp/build.txt
</screen>

When this command completes, you should have a source RPM and a binary RPM of
Bochs in the current directory.  The <command>tee</command> part of the 
command (optional) saves a transcript of the build process into /tmp/build.txt,
which is very useful if anything goes wrong.  Instructions for installing an
RPM are <link linkend="linuxrpm">here</link>.
</para>

<note><para>
In the past, you had to build rpms as root, but as of version 2.0 you can build
them as a normal user.
</para></note>

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



<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.cc, 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 id="setup"><title>Setup</title>
<section><title>What does Bochs need?</title>
<para>
These are the minimum requirements for running an OS inside of Bochs:
<itemizedlist>
<listitem>
<para>
the Bochs executable
</para>
</listitem>
<listitem>
<para>
the BIOS image (usually called <filename>BIOS-bochs-latest</filename>)
</para>
</listitem>
<listitem>
<para>
the VGA BIOS image (e.g. <filename>VGABIOS-lgpl-latest</filename> or <filename>VGABIOS-elpin-2.40</filename>)
</para>
</listitem>
<listitem>
<para>
at least one bootable media, either as disk image (floppy, hard disk or CD-ROM) or physical disk (floppy or CD-ROM)
</para>
</listitem>
</itemizedlist>
</para>

<note><para>
Both VGA BIOS versions as well as the ROM BIOS are part of Bochs. No separate download is necessary.
</para></note>

<note><para>
If you want to use the Cirrus SVGA adapter instead of VGA + Bochs VBE, you should
have a look at <xref linkend="cirrus-notes">.
</para></note>

<para>
In that case you have to pass the configuration options on the command
line or to use the configuration interface to set up Bochs for the simulation.
Running Bochs is easier if you use a configuration file (we call it
<filename>bochsrc</filename>). See <xref linkend="bochsrc"> for all supported options.
</para>

<para>
The easiest way to setup Bochs for the first time is to use the example configuration
file called <filename>bochsrc-sample.txt</filename>. Locate that file (location depends
on the (host) OS and on the installation facility used) and copy it to a location where
Bochs looks for that file, see <xref linkend="search-order">.
</para>

<para>
The next step is to change the configuration so that it fits your needs: You most
likely want to setup a hard disk (see <xref linkend="using-bximage"> and
<xref linkend="bochsopt-ata-master-slave">), and install some OS on it using either
a set of floppy disks (see <xref linkend="bochsopt-floppyab">) or a CD-ROM
(see <xref linkend="bochsopt-ata-master-slave"> again) as installation media.
Make sure you boot the emulation from the media you want, using the right setting
as <link linkend="bochsopt-boot">boot option</link>.
</para>

<para>
If your keyboard output inside of Bochs is wrong, you may also need a keymap file
to remap your keyboard layout to the U.S. layout. A set of keymap files for the
X window system and SDL (Linux port) is distributed with Bochs. If your
keyboard layout is not supported yet, you can create your own one by following the
instructions given in <xref linkend="keymap">.
</para>

<para>
A collection of disk images  of different operating systems can be found at
<ulink url="http://bochs.sourceforge.net/diskimages.html"></ulink>. Some disk
images are the size of a floppy disk (1 meg compressed) and others are gigantic
(160 meg compressed). If you want to create a disk image yourself, please see
<xref linkend="diskimagehowto">.
</para>

<para> &FIXME; This should be completed </para>
<para>
<screen>
  - (DONE )bochsrc, BIOS, VGABIOS, disk images.
  - BIOS/VGABIOS, what do they do?
  - disk images
    - (DONE) where to find one pre-made
    - grab one from a real hard disk
</screen>
</para>
</section>


<section id="bochsrc">
<title>bochsrc</title>
<para>
Bochs uses a configuration file called <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
(see <xref linkend="search-order">), and parses it.
Here are a few lines from a sample file:
<screen>
  ata0-master: type=disk, path="30M.sample", cylinders=615, heads=6, spt=17
  boot: disk
</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>
The syntax used for <filename>bochsrc</filename> can also be used as command line arguments for Bochs.
If you have any spaces in your command line arguments, they should be enclosed
in single quotes, for example:
<screen>
  bochs 'boot:floppy' 'floppya: 1_44=a.img, status=inserted'
</screen>
For other arguments, see section <link linkend="commandline">Command line arguments</link>.
</para>

<para>
Starting with version 1.3, you can use environment variables in
the <filename>bochsrc</filename> file, for example:
<screen>
  floppya: 1_44="$IMAGES/bootdisk.img", status=inserted
  boot: floppy
</screen>
Starting with version 2.0, two environment variables have a built-in
default value which is set at compile time.  $BXSHARE points to the
"share" directory which is typically /usr/local/share/bochs on UNIX
machines.  See the $(sharedir) variable in the Makefile for the exact
value.  $BXSHARE is used by disk images to locate the directory where 
the BIOS images and keymaps can be found.  If $BXSHARE is not defined, Bochs
will supply the default value.  Also, $LTDL_LIBRARY_PATH points to a list of
directories (separated by colons if more than one) to search in for Bochs
plugins.  A compile-time default is provided if this variable is not defined
by the user.  On Win32 and MacOSX, the default for the share directory is
determined by a platform-specific specific algorithm.  On Win32, we use the
registry to see what directory Bochs and its support files were installed in.
On MacOSX, the share directory is the directory where the application is
located.
</para>

<para>
Starting with version 2.0, you can can use #include in the bochsrc to read the
configuration from other files. Now it is possible to put platform or
installation defaults in a global config file (e.g. location of rom images).
Put this on top of your config file if the global configuration is stored in /etc:
<screen>
 #include /etc/bochsrc
</screen>
</para>

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

<section id="bochsopt-megs"><title>megs</title>
<para>
Examples:
<screen>
  megs: 32
  megs: 128
</screen>
Set the number of megabytes of physical memory you want to emulate. The default
is 32MB; most OS's won't need more than that. The maximum amount of memory
supported is 2048MB.
</para>

<note><para>
Due to limitations in the host OS, Bochs fails to allocated even 1024MB on most systems.
</para></note>
</section>

<section id="bochsopt-cpu"><title>cpu</title>
<para>
Example:
<screen>
  cpu: count=2, ips=10000000
</screen>
This defines the parameters of the cpu inside Bochs:
</para>
<para><command>count</command></para>
<para>
Set the number of processors:cores per processor:threads per core when Bochs
is compiled for SMP emulation. Bochs currently supports up to 8 processors.
If Bochs is compiled without SMP support, it won't accept values different from 1.
For more information on SMP see <xref linkend="SMP">.
</para>
<para><command>quantum</command></para>
<para>
Maximum amount of instructions allowed to execute by processor before
returning control to another cpu. This option exists only in Bochs 
binary compiled with SMP support.
</para>
<para><command>reset-on-triple-fault</command></para>
<para>
Reset the CPU when triple fault occur (highly recommended) rather than PANIC.
Remember that if you are trying to continue after triple fault the simulation 
will be completely bogus !
</para>
<para><command>ips</command></para>
<para>
Emulated Instructions Per Second.  This is the number of IPS that Bochs is
capable of running on your machine.  You can recompile Bochs with
<option>--enable-show-ips</option> option enabled, to find your workstation's capability.
Measured IPS value will then be logged into your <link linkend="bochsopt-log">log file</link>
or in the status bar (if supported by the gui).
</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>Bochs</entry>
    <entry>Speed</entry>
    <entry>Machine/Compiler</entry>
    <entry>Typical IPS</entry>
  </row>
</thead>
  <tbody>
<row><entry>2.2.6</entry><entry>2.6Ghz</entry><entry>Intel Core 2 Duo with WinXP/g++ 3.4 </entry><entry> 21 to 25 million</entry></row>
<row><entry>2.2.6</entry><entry>2.1Ghz</entry><entry>Athlon XP with Linux 2.6/g++ 3.4 </entry><entry> 12 to 15 million</entry></row>
<row><entry>2.0.1</entry><entry>1.6Ghz</entry><entry>Intel P4 with Win2000/g++ 3.3 </entry><entry> 5 to  7 million</entry></row>
<row><entry>1.4  </entry><entry>650MHz</entry><entry>Athlon K-7 with Linux 2.4.x  </entry><entry> 2 to 2.5 million</entry></row>
<row><entry>1.4  </entry><entry>400MHz</entry><entry>Pentium II with Linux 2.0.x  </entry><entry> 1 to 1.8 million</entry></row>
</tbody>
</tgroup>
</table>
</section>

<section><title>romimage</title>
<para>
Examples:
<screen>
  romimage: file=bios/BIOS-bochs-latest, address=0xf0000
  romimage: file=$BXSHARE/BIOS-bochs-latest, address=0xf0000
  romimage: file=mybios.bin, address=0xfff80000
  romimage: file=mybios.bin
</screen>
The ROM BIOS controls what the PC does when it first powers on.  Normally, you
can use a precompiled BIOS in the source or binary distribution called
<filename>BIOS-bochs-latest</filename>.  The ROM BIOS is usually loaded
starting at address 0xf0000, and it is exactly 64k long.
You can also use the environment variable $BXSHARE to specify the location of the BIOS.
The usage of external large BIOS images (up to 512k) at memory top is
now supported, but we still recommend to use the BIOS distributed with Bochs.
Now the start address can be calculated from image size.
</para>
</section>

<section><title>optromimage1, optromimage2, optromimage3 or optromimage4</title>
<para>
Example:
<screen>
   optromimage1: file=optionalrom.bin, address=0xd0000
</screen>

This enables Bochs to load up to 4 optional ROM images.
</para>
<para>
Be sure to use a
read-only area, typically between C8000 and EFFFF. These optional
ROM images should not overwrite the rombios (located at
F0000-FFFFF) and the videobios (located at C0000-C7FFF).
</para>
<para>
Those ROM images will be initialized by the BIOS if they contain
the right signature (0x55AA).
</para>
<para>
It can also be a convenient way to upload some arbitrary code/data
in the simulation, that can be retrieved by the boot loader
</para>
</section>

<section id="bochsopt-vgaromimage"><title>vgaromimage</title>
<para>
Examples:
<screen>
  vgaromimage: file=bios/VGABIOS-elpin-2.40
  vgaromimage: file=$BXSHARE/VGABIOS-lgpl-latest
  vgaromimage: file=$BXSHARE/VGABIOS-lgpl-latest-cirrus
</screen>
This tells Bochs what VGA ROM BIOS to load (at 0xC0000).
</para>
<para>A VGA BIOS from Elpin Systems, Inc. as well as a free LGPL'd VGA BIOS 
are provided in the source and binary distributions.</para>
<note><para>
  Please check with the <link linkend="bochsopt-vga">vga option</link> to decide
  what VGA BIOS to use.
</para></note>
</section>

<section id="bochsopt-vga">
<title>vga</title>
<para>
Examples:
<screen>
  vga: extension=cirrus
  vga: extension=vbe
</screen>
Here you can specify the display extension to be used. With the value
'none' you can use standard VGA with no extension. Other supported
values are 'vbe' for Bochs VBE (needs <filename>VGABIOS-lgpl-latest</filename> as
VGA BIOS, see <link linkend="bochsopt-vgaromimage">vgaromimage option</link>)
and 'cirrus' for Cirrus SVGA support (needs
<filename>VGABIOS-lgpl-latest-cirrus</filename> as VGA BIOS).
</para>
</section>

<section id="bochsopt-floppyab"><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
auto-detect:
  floppya: image=floppy.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).
</para>
<para>
Following floppy disk types are supported: 2_88, 1_44, 1_2, 720k, 360k, 320k, 180k,
160k, as well as "image" to let Bochs auto-detect the type of floppy disk (does only
work with images, not with raw floppy drives).
</para>
<para>
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 <filename>bochsrc</filename>.
</para>
</section>

<section id="bochsopt-ata"><title>ata0, ata1, ata2, ata3</title>
<para>
Examples:
<screen>
ata0: enabled=1, ioaddr1=0x1f0, ioaddr2=0x3f0, irq=14
ata1: enabled=1, ioaddr1=0x170, ioaddr2=0x370, irq=15
ata2: enabled=1, ioaddr1=0x1e8, ioaddr2=0x3e0, irq=11
ata3: enabled=1, ioaddr1=0x168, ioaddr2=0x360, irq=9
</screen>

These options enables up to 4 ata channels. For each channel
the two base io addresses and the irq must be specified.
ata0 and ata1 areenabled by default, with the values shown above.

</para>
</section>

<section id="bochsopt-ata-master-slave"><title>ata0-master, ata0-slave, ata1-*, ata2-*, ata3-*</title>
<para>
Examples:
<screen>
ata0-master: type=disk, path=10M.img, mode=flat, cylinders=306, heads=4, spt=17, translation=none
ata1-master: type=disk, path=2GB.cow, mode=vmware3, cylinders=5242, heads=16, spt=50, translation=echs
ata1-slave:  type=disk, path=3GB.img, mode=sparse, cylinders=6541, heads=16, spt=63, translation=auto
ata2-master: type=disk, path=7GB.img, mode=undoable, cylinders=14563, heads=16, spt=63, translation=lba
ata2-slave:  type=cdrom, path=iso.sample, status=inserted
</screen>
</para>

<para>

This defines the type and characteristics of all attached ata devices:
<table>   
<title>ata devices configuration options</title>
<tgroup cols="3">
<thead>
<row>
<entry>Option</entry>
<entry>Comments</entry>
<entry>Possible values</entry>
</row>
</thead>
<tbody>
<row> <entry> type </entry> <entry> type of attached device </entry> <entry> [disk | cdrom] </entry> </row>
<row> <entry> path  </entry> <entry> path of the image </entry> </row>
<row> 
  <entry> mode  </entry> 
  <entry> image type, only valid for disks </entry> 
  <entry> [flat | concat | external | dll | sparse | vmware3 | undoable | growing | volatile ]</entry> 
</row>
<row> <entry> cylinders </entry> <entry> only valid for disks </entry> </row>
<row> <entry> heads </entry> <entry> only valid for disks </entry> </row>
<row> <entry> spt </entry> <entry> only valid for disks </entry> </row>
<row> <entry> status </entry> <entry> only valid for cdroms </entry> <entry> [inserted | ejected] </entry> </row>
<row> <entry> biosdetect </entry> <entry> type of biosdetection </entry> <entry> [none | auto], only for disks on ata0 [cmos] </entry> </row>
<row> <entry> translation </entry> <entry> type of translation done by the BIOS (legacy int13), only for disks </entry> <entry> [none | lba | large | rechs | auto] </entry> </row>
<row> <entry> model </entry> <entry> string returned by identify device ATA command </entry> </row>
</tbody>
</tgroup>
</table>
</para>

<para>
  You have to tell the type of the attached device. For Bochs 2.0 or later, it can be
  <parameter>disk</parameter> or <parameter>cdrom</parameter>.
</para>

<para>
You have to point the "path" at a hard disk image file, cdrom iso file,
or physical cdrom device.
To create a hard disk image, try running bximage (see
<xref linkend="diskimagehowto">). It will help you choose the size and
then suggest a line that works with it.
</para>

<para>
In Unix it is possible to use a raw device as a Bochs hard disk,
but <emphasis>we don't recommend it</emphasis> for safety reasons. In Windows, there is no easy way.
</para>

<para>
Disk geometry autodetection works with images created by bximage if CHS is set
to 0/0/0 (cylinders are calculated using heads=16 and spt=63). For other hard
disk images and modes the cylinders, heads, and spt are mandatory.
</para>

<para>
The disk translation scheme 
(implemented in legacy int13 BIOS functions, and used by
older operating systems like MS-DOS), can be defined as:
<itemizedlist>
<listitem><para>
none : no translation, for disks up to 528MB (1032192 sectors)
</para></listitem>
<listitem><para>
large : a standard bitshift algorithm, for disks up to 4.2GB (8257536 sectors)
</para></listitem>
<listitem><para>
rechs : a revised bitshift algorithm, using a 15 heads fake physical geometry, for disks up to 7.9GB (15482880 sectors). (don't use this unless you understand what you're doing)
</para></listitem>
<listitem><para>
lba : a standard lba-assisted algorithm, for disks up to 8.4GB (16450560 sectors)
</para></listitem>
<listitem><para>
auto : autoselection of best translation scheme. (it should be changed if system does not boot)
</para></listitem>
</itemizedlist>
Please see <xref linkend="bios-disk-translation"> for a discussion on translation scheme.
</para>

<para>
The mode option defines how the disk image is handled. Disks can be defined as:
<itemizedlist>
<listitem><para>
flat : one file flat layout
</para></listitem>
<listitem><para>
concat : multiple files layout
</para></listitem>
<listitem><para>
external : developer's specific, through a C++ class
</para></listitem>
<listitem><para>
dll : developer's specific, through a DLL
</para></listitem>
<listitem><para>
sparse : stackable, commitable, rollbackable
</para></listitem>
<listitem><para>
vmware3 : vmware3 disk support
</para></listitem>
<listitem><para>
undoable : flat file with commitable redolog
</para></listitem>
<listitem><para>
growing : growing file
</para></listitem>
<listitem><para>
volatile : flat file with volatile redolog
</para></listitem>
</itemizedlist>
Please see <xref linkend="harddisk-modes"> for a discussion on disk modes.
</para>

<para>
Default values are:
<screen>
   mode=flat, biosdetect=auto, translation=auto, model="Generic 1234"
</screen>
</para>

<para>
  The <parameter>biosdetect</parameter> option has currently no effect on the BIOS.
</para>

<note><para>
  Make sure the proper <link linkend="bochsopt-ata">ata option</link> is enabled when
  using a device on that ata channel.
</para></note>
</section>

<section id="bochsopt-boot"><title>boot</title>
<para>
Examples:
<screen>
  boot: floppy
  boot: disk
  boot: cdrom
  boot: cdrom, floppy, disk
</screen>
This defines the boot sequence. You can specify up to 3 boot drives,
which can be 'floppy', 'disk' or 'cdrom'.
'a' and 'c' are also accepted for historical reasons.
</para>
</section>

<section><title>floppy_bootsig_check</title>
<para>
Example:
<screen>
  floppy_bootsig_check: disabled=1
</screen>
This disables the 0xaa55 signature check on boot floppies
The check is enabled by default.
</para>
</section>

<section id="bochsopt-configinterface"><title>config_interface</title>
<para>
The configuration interface is a series of menus or dialog boxes that
allows you to edit all the settings that control Bochs' behavior.
There are two choices of configuration interface: a text mode version
called "textconfig" and a graphical version called "wx".  The text
mode version uses stdin/stdout and is always available while the graphical
version is only available when Bochs is compiled with wxWidgets support, see
<xref linkend="compile-wx">. If you do not use a config_interface line, Bochs
will choose a default for you (usually textconfig).
</para>

<note><para>
wxWidgets provides both a configuration interface and a display library.
So if you use the "wx" configuration interface, you must also use
the "wx" display library, see
<link linkend="bochsopt-displaylibrary">display_library option</link>.
</para></note>

<para>
Examples:
<screen>
  config_interface: textconfig
  config_interface: wx
</screen>
</para>
</section>

<section id="bochsopt-displaylibrary"><title>display_library</title>
<para>
The display library is the code that displays the Bochs VGA screen.  Bochs 
has a selection of about 10 different display library implementations for 
different platforms.  If you run configure with multiple --with-* options, 
the display_library option lets you choose which one you want to run with.
If you do not use a display_library line, Bochs will choose a default for
you.
</para>

<note><para>
wxWidgets provides both a configuration interface and a display library.
So if you use the "wx" display library, you must also use
the "wx" configuration interface, see
<link linkend="bochsopt-configinterface">config_interface option</link>.
</para></note>

<para>
Examples:
<screen>
  display_library: x
  display_library: sdl
</screen>
Starting with version 2.2, some display libraries support specific options:
<screen>
  display_library: rfb, options="timeout=60"  # time to wait for client
  display_library: sdl, options="fullscreen"  # startup in fullscreen mode
  display_library: win32, options="legacyF12" # use F12 to toggle mouse
</screen>
</para>

<table>
<title>display_library values</title>
<tgroup cols="2">
<thead>
<row>
  <entry>Option</entry>
  <entry>Description</entry>
</row>
</thead>
<tbody>
<row>
  <entry>x</entry>
  <entry>use X windows interface, cross platform</entry>
</row>
<row>
  <entry>win32</entry>
  <entry>use native win32 libraries</entry>
</row>
<row>
  <entry>carbon</entry>
  <entry>use Carbon library (for MacOS X)</entry>
</row>
<row>
  <entry>beos</entry>
  <entry>use native BeOS libraries</entry>
</row>
<row>
  <entry>macintosh</entry>
  <entry>use MacOS pre-10</entry>
</row>
<row>
  <entry>amigaos</entry>
  <entry>use native AmigaOS libraries</entry>
</row>
<row>
  <entry>sdl</entry>
  <entry>use SDL library, cross platform,
    details in <xref linkend="compile-sdl"></entry>
</row>
<row>
  <entry>svga</entry>
  <entry>use SVGALIB library for Linux, allows graphics without X windows</entry>
</row>
<row>
  <entry>term</entry>
  <entry>text only, uses curses/ncurses library, cross platform</entry>
</row>
<row>
  <entry>rfb</entry>
  <entry>provides an interface to AT&amp;T's VNC viewer, cross platform,
    details in <xref linkend="compile-rfb"></entry>
</row>
<row>
  <entry>wx</entry>
  <entry>use wxWidgets library, cross platform,
    details in <xref linkend="compile-wx"></entry>
</row>
<row>
  <entry>nogui</entry>
  <entry>no display at all</entry>
</row>
</tbody>
</tgroup>
</table>
</section>

<section id="bochsopt-log"><title>log</title>
<para>
Examples:
<screen>
  log: bochsout.txt
  log: -
  log: /dev/tty               (Unix only)
  log: /dev/null              (Unix only)
  log: nul                    (win32 only)
</screen>
Give the path of the log file you'd like Bochs debug and misc. verbiage to be
to be written to. If you don't use this option or set the filename to '-'
the output is written to the console. If you really don't want it,
make it "/dev/null" (Unix) or "nul" (win32). :^(
</para>
</section>

<section><title>logprefix</title>
<para>
Examples:
<screen>
   logprefix: %t-%e-@%i-%d
   logprefix: %i%e%d
</screen>
This handles the format of the string prepended to each log line.
You may use those special tokens :
  <screen>
  %t : 11 decimal digits timer tick
  %i : 8 hexadecimal digits of current cpu eip (ignored in SMP configuration)
  %e : 1 character event type ('i'nfo, 'd'ebug, 'p'anic, 'e'rror)
  %d : 5 characters string of the device, between brackets
  </screen>
</para>
<para>
Default is %t%e%d
</para>
</section>

<section id="bochsopt-debug-info-error-panic"><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>debugger_log</title>
<para>
Examples:
<screen>
  debugger_log: debugger.out
  debugger_log: /dev/null              (Unix only)
  debugger_log: -
</screen>
Give the path of the log file you'd like Bochs to log debugger output.
If you really don't want it, make it '/dev/null', or '-'.
</para>
</section>

<section id="bochsopt-com">
<title>com[1-4]</title>
<para>
Examples:
<screen>
  com1: enabled=1, mode=null
  com1: enabled=1, mode=mouse
  com1: enabled=1, mode=term, dev=/dev/ttyp9
  com2: enabled=1, mode=file, dev=serial.out
  com3: enabled=1, mode=raw, dev=com1
  com3: enabled=1, mode=socket, dev=localhost:8888
</screen>
  This defines a serial port (UART type 16550A).
</para>
<para>
  When using the mode 'term', you can specify a device to use as com1.
  This can be a real serial line, or a pty.  To use a pty (under X/Unix),
  create two windows (xterms, usually).  One of them will run Bochs, and
  the other will act as com1. Find out the tty of the com1 window using
  the `tty' command, and use that as the `dev' parameter.  Then do
  `sleep 1000000' in the com1 window to keep the shell from messing with
  things, and run Bochs in the other window. Serial I/O to com1 (port 0x3f8)
  will all go to the other window.
</para>
<para>
  Other serial modes are 'null' (no input/output), 'file' (output to a file
  specified as the 'dev' parameter), 'raw' (use the real serial port - under
  construction for win32), 'mouse' (standard serial mouse - requires
  <link linkend="bochsopt-mouse">mouse option</link> setting 'type=serial'
  or 'type=serial_wheel') and 'socket' (connect a networking socket).
</para>
</section>

<section>
<title>parport[1-2]</title>
<para>
Examples:
<screen>
  parport1: enabled=1, file="parport.out"
  parport2: enabled=1, file="/dev/lp0"
  parport1: enabled=0
</screen>
This defines a parallel (printer) port. When turned on and an output file is
defined, the emulated printer port sends characters printed by the guest OS
into the output file. On some platforms, a device filename can be used to
send the data to the real parallel port (e.g. "/dev/lp0" on Linux, "lpt1" on
win32 platforms).
</para>
</section>

<section id="sb16line"><title>sb16</title>
<para>
Example:
<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 <filename>bochsrc</filename> file.
</para></note>

This defines the Sound Blaster 16 emulation, see <xref linkend="sb16-emulation">
for more information. 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 to. This
   can be a device or just a file if you want to record the midi data.
   On a Windows host, you should use "midi" as filename.
   </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.
   On a Windows host, you should use "wave" as filename.
   </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 = Resource changes, midi program and bank changes.
   2 = Severe errors.
   3 = All errors.
   4 = All errors plus all port accesses.
   5 = All errors and port accesses plus a lot of extra information.
   </screen>
   It is possible to change the loglevel at runtime.
   </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 the <command>ips</command> paramter of the
   <link linkend="bochsopt-cpu">cpu option</link>. It is possible to adjust the
   dmatimer value at runtime.
   </para></listitem>
 </itemizedlist>
</para>
</section>

<section><title>vga_update_interval</title>
<para>
Examples:
<screen>
  vga_update_interval: 40000 # default
  vga_update_interval: 250000
</screen>
Video memory is scanned for updates and screen updated every so many virtual
microseconds. Keep in mind that you must tweak the <command>ips</command>
parameter of the <link linkend="bochsopt-cpu">cpu option</link> 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:
<screen>
  keyboard_serial_delay: 250 # default
</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>
Example:
<screen>
  keyboard_paste_delay: 100000 # default
</screen>
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>
</section>

<section><title>ips</title>
<para>
Examples:
<screen>
  ips: 2000000 # default
  ips: 10000000
</screen>
Emulated Instructions Per Second.  This option is deprecated. Use the <command>ips</command>
parameter of the <link linkend="bochsopt-cpu">cpu option</link> instead.
</para>
</section>

<section id="bochsopt-clock"><title>clock</title>
<para>
This defines the parameters of the clock inside Bochs:
</para>
<para><command>sync</command></para>
<para>
TO BE COMPLETED (see Greg's explanation in <ulink url="http://sourceforge.net/tracker/?group_id=12580&amp;atid=362580&amp;func=detail&amp;aid=536329">feature request #536329</ulink>)
</para>
<para><command>time0</command></para>
<para>
Specifies the start (boot) time of the virtual machine. Use a time 
value as returned by the time(2) system call. If no time0 value is 
set or if time0 equal to 1 (special case) or if time0 equal 'local', 
the simulation will be started at the current local host time.
If time0 equal to 2 (special case) or if time0 equal 'utc',
the simulation will be started at the current utc time.
</para>
<para>
<screen>
Syntax:
  clock: sync=[none|slowdown|realtime|both], time0=[timeValue|local|utc]

Examples:
  clock: sync=none,     time0=local       # Now (localtime)
  clock: sync=slowdown, time0=315529200   # Tue Jan  1 00:00:00 1980
  clock: sync=none,     time0=631148400   # Mon Jan  1 00:00:00 1990
  clock: sync=realtime, time0=938581955   # Wed Sep 29 07:12:35 1999
  clock: sync=realtime, time0=946681200   # Sat Jan  1 00:00:00 2000
  clock: sync=none,     time0=1           # Now (localtime)
  clock: sync=none,     time0=utc         # Now (utc/gmt)

Default value are sync=none, time0=local
</screen>
</para>

</section>

<section id="bochsopt-mouse">
<title>mouse</title>
<para>
Examples:
<screen>
  mouse: enabled=1
  mouse: enabled=1, type=imps2
  mouse: enabled=1, type=serial
  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 (see <link linkend="headerbar">headerbar</link>).
</para>
<para>
  With the mouse type option you can select the type of mouse to emulate.
  The default value is 'ps2'. The other choices are 'imps2' (wheel mouse
  on PS/2), 'serial', 'serial_wheel' (one com port requires setting
  'mode=mouse', see <link linkend="bochsopt-com">com option</link>) and
  'usb' (3-button mouse - one of the USB ports must be connected with the
  'mouse' device, see <link linkend="bochsopt-usb1">usb1 option</link> -
  requires PCI and USB support).
</para>
</section>

<section id="bochsopt-private-colormap"><title>private_colormap</title>
<para>
Example:
<screen>
  private_colormap: enabled=1
</screen>
Requests that the GUI creates and uses its own non-shared colormap. This
colormap will be used when in the Bochs window. If not enabled, a shared
colormap scheme may be used. Once again, <varname>enabled=1</varname>
turns on this feature and 0 turns it off.
</para>
</section>

<section><title>i440fxsupport</title>
<para>
Examples:
<screen>
  i440fxsupport: enabled=1 # default if compiled with PCI support
  i440fxsupport: enabled=1, slot1=pcivga, slot2=ne2k
</screen>
This option controls the presence of the i440FX PCI chipset. You can also
specify the devices connected to PCI slots. Up to 5 slots are available.
These devices are currently supported: ne2k, pcivga, pcidev and pcipnic.
If Bochs is compiled with Cirrus SVGA support you'll have the additional
choice 'cirrus'.
</para>
</section>

<section><title>pcidev</title>
<para>
Example:
<screen>
  pcidev: vendor=0xbabe, device=0x2bad
</screen>
Enables the mapping of a host PCI hardware device within the virtual PCI
subsystem of the Bochs x86 emulator. The arguments
<varname>vendor</varname> and <varname>device</varname>
should contain the PCI vendor ID respectively the PCI
device ID of the host PCI device you want to map within Bochs.
</para>
<note>
<para>
The PCI device mapping is still in a very early stage of development and thus it is very experimental.
This feature requires Linux as a host operating system.
</para>
</note>
<para>
Besides the <varname>pcidev</varname> config line you will need to load
a pcidev kernel module within your Linux host OS. This kernel module is
located in the <constant>bochs/host/linux/pcidev/</constant> directory.
</para>
</section>

<section id="bochsopt-usb1"><title>usb1</title>
<para>
Example:
<screen>
  usb1: enabled=1, port1=mouse, port2=keypad
</screen>
This option controls the presence of the USB root hub which is a part of the
i440FX PCI chipset.
</para>
<para>
With the port<replaceable>X</replaceable> option you can connect devices
to the hub (currently supported: 'mouse' and 'keypad'). If you connect
the mouse to one of the ports and use the <link linkend="bochsopt-mouse">mouse option</link>
'type=usb' you'll have a 3-button USB mouse.
</para>
<note><para>
PCI support must be enabled.
</para></note>
</section>

<section id="bochsopt-gdbstub">
<title>gdbstub</title>
<para>
Example:
<screen>
  gdbstub: enabled=1, port=1234, text_base=0, data_base=0, bss_base=0
</screen>
Default:
<screen>
  gdbstub: enabled=0
</screen>
This enables the GDB stub. See <xref linkend="debugging-with-gdb">.
</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=0x240, irq=9, mac=b0:c4:20:00:00:00, ethmod=fbsd, ethdev=xl0
ne2k: ioaddr=0x240, irq=9, mac=b0:c4:20:00:00:00, ethmod=fbsd, ethdev=en0 #macosx
ne2k: ioaddr=0x240, irq=9, mac=b0:c4:20:00:00:00, ethmod=linux, ethdev=eth0
ne2k: ioaddr=0x240, irq=9, mac=b0:c4:20:00:00:01, ethmod=win32, ethdev=<replaceable>MYCARD</replaceable>
ne2k: ioaddr=0x240, irq=9, mac=b0:c4:20:00:00:01, ethmod=vde, ethdev="/tmp/vde.ctl"
ne2k: ioaddr=0x240, irq=9, mac=b0:c4:20:00:00:01, ethmod=vnet, ethdev="c:/temp"
ne2k: ioaddr=0x240, irq=9, mac=fe:fd:00:00:00:01, ethmod=tap, ethdev=tap0
ne2k: ioaddr=0x240, irq=9, mac=fe:fd:00:00:00:01, ethmod=tuntap, ethdev=/dev/net/tun0, script=./tunconfig

ioaddr, irq: You probably won't need to change ioaddr and irq, unless there
are IRQ conflicts. These parameters are ignored if the NE2000 is assigned to
a PCI slot.

mac: The MAC address MUST NOT match the address of any machine on the net.
Also, the first byte must be an even number (bit 0 set means a multicast
address), and you cannot use ff:ff:ff:ff:ff:ff because that's the broadcast
address.  For the ethertap module, you must use fe:fd:00:00:00:01.  There may
be other restrictions too.  To be safe, just use the b0:c4... address.

ethmod: The ethmod value defines which low level OS specific module to be 
used to access physical ethernet interface. You can also specify a network
simulator or a module with no input/output ("null"). See the table below for
currently supported values.

ethdev: The ethdev value is the name of the network interface on your host
platform.  On UNIX machines, you can get the name by running ifconfig.  On
Windows machines, you must run niclist to get the name of the ethdev.
Niclist source code is in misc/niclist.c and it is included in Windows 
binary releases.

script: The script value is optional, and is the name of a script that
is executed after bochs initialize the network interface. You can use
this script to configure this network interface, or enable masquerading.
This is mainly useful for the tun/tap devices that only exist during
Bochs execution. The network interface name is supplied to the script
as first parameter
</screen>
</para>

<para>
The following table shows the available ethernet modules with description,
whether the "ethdev" and "script" parameters are used or not and the Bochs
version where this module was added.
</para>
<table><title>Ethernet modules</title>
<tgroup cols="5" align="left" colsep="1" rowsep="1">
<thead>
  <row>
    <entry>Module</entry>
    <entry>Description</entry>
    <entry>ethdev</entry>
    <entry>script</entry>
    <entry>Bochs version</entry>
  </row>
</thead>
<tbody>
  <row>
    <entry>arpback</entry>
    <entry>ARP simulator - disabled by default.
    </entry>
    <entry>No</entry>
    <entry>No</entry>
    <entry>1.3</entry>
  </row>
  <row>
    <entry>fbsd</entry>
    <entry>FreeBSD / OpenBSD packetmover.
    </entry>
    <entry>Yes</entry>
    <entry>No</entry>
    <entry>1.0</entry>
  </row>
  <row>
    <entry>linux</entry>
    <entry>Linux packetmover - 'root' privileges required,
    no connection to the host machine.
    </entry>
    <entry>Yes</entry>
    <entry>No</entry>
    <entry>1.3</entry>
  </row>
  <row>
    <entry>null</entry>
    <entry>Null packetmover. All packets are discarded, but logged to a
    few files.
    </entry>
    <entry>No</entry>
    <entry>No</entry>
    <entry>1.0</entry>
  </row>
  <row>
    <entry>tap</entry>
    <entry>TAP packetmover.
    </entry>
    <entry>Yes</entry>
    <entry>Yes</entry>
    <entry>1.4</entry>
  </row>
  <row>
    <entry>tuntap</entry>
    <entry>TUN/TAP packetmover - see <link linkend="config-tuntap">
    Configuring and using a tuntap network interface</link>.
    </entry>
    <entry>Yes</entry>
    <entry>Yes</entry>
    <entry>2.0</entry>
  </row>
  <row>
    <entry>vde</entry>
    <entry>Virtual Distributed Ethernet packetmover.
    </entry>
    <entry>Yes</entry>
    <entry>Yes</entry>
    <entry>2.2</entry>
  </row>
  <row>
    <entry>vnet</entry>
    <entry>ARP, ping (ICMP-echo), DHCP and read/write TFTP simulation. The virtual
    host uses 192.168.10.1. DHCP assigns 192.168.10.2 to the guest. The TFTP server
    uses the ethdev value for the root directory and doesn't overwrite files.
    </entry>
    <entry>Yes, for TFTP</entry>
    <entry>No</entry>
    <entry>2.2</entry>
  </row>
  <row>
    <entry>win32</entry>
    <entry>Win32 packetmover - WinPCap driver required.
    </entry>
    <entry>Yes</entry>
    <entry>No</entry>
    <entry>1.3</entry>
  </row>
</tbody>
</tgroup>
</table>
</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. Keyboard mapping is 
available for X windows, SDL (Linux port) and wxWidgets (GTK port).
For SDL you have to use keymaps designed for SDL, the wxWidgets GUI
uses the keymaps for X windows.
</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 id="bochsopt-user-shortcut"><title>user_shortcut</title>
<para>
Examples:
<screen>
  user_shortcut: keys=ctrl-alt-del
  user_shortcut: keys=ctrl-alt-esc
</screen>
This defines the keyboard shortcut to be sent when you press the "user" button
in the <link linkend="headerbar">headerbar</link>. The shortcut string is a
combination of maximum 3 key names (listed below) separated with a '-' character.
The old-style syntax (without the '-') still works for the key combinations
supported in Bochs 2.2.1.
</para>
<para>
Valid key names:
</para>
<para>
"alt", "bksl", "bksp", "ctrl", "del", "down", "end", "enter", "esc",
"f1", ... "f12", "home", "ins", "left", "menu", "minus", "pgdwn", "pgup", "plus",
"right", "shift", "space", "tab", "up", and "win".
</para>
</section>

<section><title>cmosimage</title>
<para>
Example:
<screen>
  cmosimage: file=cmos.img, rtc_init=time0
</screen>
This defines image file that can be loaded into the CMOS RAM at startup.
The rtc_init parameter controls whether initialize the RTC with values stored
in the image. By default the time0 argument given to the
<link linkend="bochsopt-clock">clock option</link> is used. With 'rtc_init=image'
the image is the source for the initial time.
</para>
</section>

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

<section id="sb16-emulation"> <!-- start of SB16 section-->

<title>Sound Blaster 16 Emulation</title>

<para>
This section is a detailed description for configuring Sound Blaster 16 from
source. If you have a binary and all you want to know is what to put in your
<filename>bochsrc</filename> file, see <link linkend="sb16line">sb16 option</link>.
</para>

<para>
Sound Blaster 16 (SB16) emulation for Bochs was written and donated by
Josef Drexler, who has a
<ulink url="http://publish.uwo.ca/~jdrexler/bochs/">web page</ulink> on the topic.
The entire set of his SB16 patches have been integrated into
Bochs, however, so you can find everything you need here.
</para>

<para>
SB16 Emulation has been tested with several soundcards and versions of Linux.  Please give
Josef <ulink url="mailto:jdrexler@julian.uwo.ca">feedback</ulink> on
whether is does or doesn't work on your combination of software and hardware.
</para>

<section><title>How well does it work?</title>
<para>
Right now, MPU401 emulation is next to perfect. It supports UART
and SBMIDI mode, because the SB16's MPU401 ports can't do anything else as well.
</para>

<para>
The digital audio basically works, but the emulation is too slow for fluent
output unless the application doesn't do much in the background (or the
foreground, really). The sound tends to looping or crackle on slower
computer, but the emulation appears to be correct. Even a MOD
player works, although only for lower sampling speeds.
</para>
<para>
Also, the MIDI data running through the MPU401 ports can be written
into a SMF, that is the standard midi file. The wave output
can be written into a VOC file, which has a format defined by
Creative Labs. This file format can be converted to WAV by
sox for example.
</para>
</section>

<section><title>Output to a sound card</title>

<para>
Output is supported on Windows, Linux, FreeBSD, MacOS 9 and MacOSX at the moment.
</para>
<para>
On Linux, the output goes to any file or device. If you have a wavetable synthesizer,
midi can go to <filename class="devicefile">/dev/midi00</filename>, otherwise you may need
a midi interpreter. For example, the midid program from the DosEmu project would work.
Wave output should go to <filename class="devicefile">/dev/dsp</filename>. These devices
are assumed to be OSS devices, if they're not some of the ioctl's might fail.
</para>
<para>
On Windows, midi and (wave) output go to the midi mapper and the wave mapper,
respectively. A future version might have selectable output devices.
</para>
</section>

<section><title>Installation on Linux</title>

<section><title>Prerequisites</title>

<para>
A wavetable synthesizer on <filename class="devicefile">/dev/midi00</filename>
and a working <filename class="devicefile">/dev/dsp</filename> if you want real
time music and sound, otherwise output to midi and wave files is also possible.
Optionally, you can use a software midi interpreter, such as the midid program
from the DosEmu project instead of <filename class="devicefile">/dev/midi00</filename>.
</para>
</section>

<section><title>Configuring Bochs</title>

<para>
You need to <command>configure</command> Bochs using the <option>--enable-sb16</option>
option.
There are a few values in <filename>config.h</filename> that are relevant to the sound functions.
Edit <filename>config.h</filename> after running configure, but before compiling.
</para>

<para>
BX_USE_SB16_SMF should be 1 unless you intend to have several sound cards
running at the same time.
</para>

<para>
BX_USE_SOUND_VIRTUAL can be 0 or 1, and determines whether the output class
uses virtual functions or not. The former is more versatile and allows to
select the class at runtime (not supported at the moment), while the latter
is slightly faster.
</para>

<para>
BX_SOUND_OUTPUT_C is the name of the class used for output.  The default is
to have no output functions, so you need to change this if you want any sound.
The following are supported at the moment:
</para>

<programlisting>
        bx_sound_linux_c    for output to /dev/dsp and /dev/midi00 on Linux
                            (and maybe other OSes that use the OSS driver)
        bx_sound_windows_c  for output to the midi and wave mapper of
                            Windows 3.1 and higher.
        bx_sound_output_c   for no output at all.
</programlisting>

<para>
Setup the SB16 emulation in your <filename>bochsrc</filename>, according to instructions
in that file (see <link linkend="sb16line">sb16 option</link>).
</para>
</section>

<section><title>Runtime configuration</title>

<para>
The source for the SB16CTRL program that is used to modify
the runtime behaviour of the SB16 emulation is included in
<filename class="directory">misc/sb16/</filename>. It is a C
program that can be run from inside the emulation.
<!-- You can compile it or download the
<ulink url="http://publish.uwo.ca/~jdrexler/bochs/">executable</ulink>. -->
</para>

<para>
It currently supports the following commands:
</para>

<table><title>Supported options for <command>sb16ctl</command></title>
<tgroup cols="2">
  <thead>
    <row>
      <entry>Option</entry>
      <entry>Description</entry>
   </row>
  </thead>
  <tbody>
    <row>
      <entry><option>-i <replaceable>number</replaceable></option></entry>
      <entry>
        Show the selected emulator info string,
        e.g. <command>sb16ctrl -i 3</command> to show how many patch translations are active.
      </entry>
    </row>
    <row>
      <entry><option>-t <replaceable>six numbers</replaceable></option></entry>
      <entry>
        Load a translation into the translation table. The numbers are:
        "OldBankMSB,OldBankLSB,OldProgram,NewBankMSB,NewBankLSB,NewProgram".
        All values can be 0..127 or 255. 255 for "Old" values means <emphasis>match
        any</emphasis> and for "New" values means <emphasis>don't change</emphasis>,
        e.g. <command>sb16ctrl -t 255,255,0,255,255,32</command>
        to change patch 0 (Piano) to patch 32 (Acoustic Bass).
      </entry>
    </row>
    <row>
      <entry><option>-r</option></entry>
      <entry>
        Reset the patch translation table e.g. <command>sb16ctrl -r</command>.
      </entry>
    </row>
    <row>
      <entry><option>-m <replaceable>some numbers</replaceable></option></entry>
      <entry>
        Upload the given numbers to the midi output device. Note
        that it should be a complete midi message, and also that it is
        subject to patch translation,
        e.g. <command>sb16ctrl -m 0x80,64,0</command>
        to send a note-off message to channel 0.
      </entry>
    </row>
    <row>
      <entry><option>-f <replaceable>filename</replaceable></option></entry>
      <entry>
        Read in a file and execute the commands in it. These have
        the same format as the above commands, except that they don't have
        the dash "-" in front of them.
        Comment lines are supported and start with a hash sign "#".
      </entry>
    </row>
    <row>
      <entry><option>-h</option></entry>
      <entry>
        Show a brief summary of the commands.
      </entry>
    </row>
  </tbody>
</tgroup>
</table>

<para>
All numbers can be valid parameters to the <function>strtol()</function> function, so hex and
octal notation is fine. They have to be delimited by either commas "," or
slashes "/", spaces are not allowed.
</para>

<para>
The command line can have any number of commands. However, if none are given,
"-f -" is assumed, which means commands are taken from stdin.
</para>
</section>
</section>

<section><title>Features planned for the future</title>
<itemizedlist>
<listitem><para>Port it to more OS's, but I can't do this myself.</para></listitem>
<listitem><para>Finish the OPL3 FM emulation by translating the music to midi data.</para></listitem>
</itemizedlist>
</section>

<section>
<title>Description of the sound output classes</title>
<para>
You can find a description of the sound output classes and more details on
Sound Blaster 16 emulation in the
<ulink url="../development/sb16-emulation-basics.html">developer documentation</ulink>.
</para>
</section>
</section> <!-- end of SB16 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 was first 
implemented for X windows only, so there are many references to X-specific
values in this section. In Bochs 2.0 keymapping is also available for SDL 
(Linux port) and wxWidgets (wxGTK port).
</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 - favorites</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 id="using-bochs"><title>Using Bochs</title>
<para>
&FIXME;
<screen>
- using plugins?
- 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 (present as FIXME request in chapter 6 as well)
  - How to make feature requests?
</screen>
</para>
    
<section id="commandline"><title>Command line arguments</title>
<para>
The following table shows the arguments that can be used on the command line.
For other arguments, see section <link linkend="bochsrc">bochsrc</link>.
<table>   
<title>command line arguments</title>
<tgroup cols="2">
<thead>
<row>
<entry>Argument</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
  <entry>-q</entry>
  <entry>quick start (skip configuration interface)</entry>
</row>
<row>
  <entry>-f <replaceable>filename</replaceable></entry>
  <entry>specify configuration file</entry>
</row>
<row>
  <entry>-n</entry>
  <entry>don't try to load a configuration file</entry>
</row>
<row>
  <entry>-r <replaceable>path</replaceable></entry>
  <entry>specify path for restoring state (if save/restore support is compiled in)</entry>
</row>
<row>
  <entry>--help</entry>
  <entry>display help message and exit</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
These arguments are handled directly after starting Bochs. The next step is to load
a default or specified configuration file (unless disabled with -n). Then the rest
of the command line (<filename>bochsrc</filename> options) is parsed. This is done after reading the
configuration file so that the command line arguments can override the settings
from the file.
</para>
</section>

<section id="search-order"><title>Search order for the configuration file</title>
<para>
If no configuration file is specified on the command line and config file loading
is not disabled, Bochs searches for a default configuration file. This is the search order:
<orderedlist>
<listitem>
<para>
<filename>.bochsrc</filename> in the current directory
</para>
</listitem>
<listitem>
<para>
<filename>bochsrc</filename> in the current directory
</para>
</listitem>
<listitem>
<para>
<filename>bochsrc.txt</filename> in the current directory
</para>
</listitem>
<listitem>
<para>
(win32 only) <filename>bochsrc.bxrc</filename> in the current directory
</para>
</listitem>
<listitem>
<para>
(Unix only) <filename>.bochsrc</filename> in the user's home directory
</para>
</listitem>
<listitem>
<para>
(Unix only) <filename>bochsrc</filename> in the <filename class="directory">/etc</filename> directory
</para>
</listitem>
</orderedlist>
</para>
</section>
<section id="textconfig"><title>The configuration interface 'textconfig'</title>
<para>
The configuration interface 'textconfig' is the text mode version of the Bochs
configuration system. It is a series of menus (using stdin/stdout) that allows
you to edit all the settings that control Bochs' behavior. If you do not write
a config_interface line, Bochs will choose it as the default for you (unless Bochs
is compiled for wxWidgets only).
</para>
<para>
It consists of these three parts:
<itemizedlist>
<listitem><para>the start menu</para></listitem>
<listitem><para>the headerbar buttons</para></listitem>
<listitem><para>the runtime configuration</para></listitem>
</itemizedlist>
</para>
<section><title>The start menu</title>
<para>
If you start Bochs without the quickstart argument (-q), the Bochs configuration
main menu appears:
<screen>
------------------------------
Bochs Configuration: Main Menu
------------------------------

This is the Bochs Configuration Interface, where you can describe the
machine that you want to simulate.  Bochs has already searched for a
configuration file (typically called bochsrc.txt) and loaded it if it
could be found.  When you are satisfied with the configuration, go
ahead and start the simulation.

You can also start bochs with the -q option to skip these menus.

1. Restore factory default configuration
2. Read options from...
3. Edit options
4. Save options to...
5. Begin simulation
6. Quit now

Please choose one: [5]
</screen>
</para>
<para>
Here you can load, edit and save the configuration and finally start the simulation.
It is possible to start Bochs without a config file and to edit all the settings using
the item "Edit options". Don't forget to save the configuration if you want to use this
setup for another Bochs session.
</para>
</section>

<section id="headerbar"><title>The Bochs headerbar</title>
<para>
<graphic format="PNG" fileref="../images/headerbar.png">
</para>
<para>
The headerbar appears on top of the Bochs simulation window. Here you can control the
behavoiur of Bochs at runtime if you click on one of these buttons:
<itemizedlist>
<listitem>
<para>floppy buttons</para>
<para>
  Here you can toggle the status of the floppy media (inserted/ejected). Bochs for
  win32 presents you a small dialog box for changing the floppy image. You can
  setup floppy drives using <link linkend="bochsopt-floppyab">floppya/floppyb option</link>.
</para>
</listitem>
<listitem>
<para>cdrom button</para>
<para>
  Here you can toggle the status of the cdrom media (inserted/ejected). CD-ROM drives
  can be set up using <link linkend="bochsopt-ata-master-slave">ata(0-3)-master/-slave option</link>.
</para>
</listitem>
<listitem>
<para>mouse button</para>
<para>
  Here you can enable the creation of mouse events by the host. Once mouse
  events are captured, you cannot reach the button anymore, in order to disable
  capturing again. In this case, use "Ctrl+3rd mouse button" to disable it.
</para>
<para>&FIXME; Support for 2 button mouse to toggle the capture mode not yet complete.
  Some display libraries still don't support the new feature, but
  it is already supported on X11, SDL, wxWidgets and Win32.</para>
</listitem>
<listitem>
<para>user button</para>
<para>
  Press this button if you want to send the keyboard shortcut defined with the
  <link linkend="bochsopt-user-shortcut">user_shortcut option</link> to the guest.
  Depending on the used <link linkend="bochsopt-displaylibrary">display_library option</link>,
  it may even be possible to edit the shortcut before sending it.
</para>
</listitem>
<listitem>
<para>copy button</para>
<para>The text mode screen text can be exported to the clipboard after pressing this
button. The button has no effect in graphics mode.</para>
</listitem>
<listitem>
<para>paste button</para>
<para>Text in the clipboard can also be pasted, through Bochs, to the
guest OS, as simulated keystrokes. Keyboard mapping must be enabled to make this
feature work.</para>
</listitem>
<listitem>
<para>snapshot button</para>
<para>Press this button if you want to save a snapshot of the text mode screen.
Bochs for win32 presents you a "Save as..." dialog box. All other platforms are
using the fixed filename "snapshot.txt".</para>
</listitem>
<listitem><para>config button</para>
<para>This button stops the Bochs simulation and starts the runtime configuration.
(see below).</para>
</listitem>
<listitem>
<para>reset button</para>
<para>Press this button to trigger a hardware reset.</para>
</listitem>
<listitem>
<para>power button</para>
<para>This button stops the simulation and quits bochs.</para>
</listitem>
</itemizedlist>
</para>
<para>
Some of this features may not be implemented or work different on your host platform.
</para>
</section>
<section><title>The runtime configuration</title>
<para>
If you want to change certain settings at runtime, you have to press the "config" button in
the headerbar. The simulation stops and the runtime menu appears on the console window / xterm.
<screen>
---------------------
Bochs Runtime Options
---------------------
1. Floppy disk 0: /dev/fd0, size=1.44M, inserted
2. Floppy disk 1: floppyb.img, size=1.44M, inserted
3. 1st CDROM: (master on ata1) /dev/cdrom, ejected
4. 2nd CDROM: (slave on ata1) /dev/cdrecorder, ejected
5. 3rd CDROM: (not present)
6. 4th CDROM: (not present)
7. (not implemented)
8. Log options for all devices
9. Log options for individual devices
10. VGA Update Interval: 100000
11. Mouse: disabled
12. Keyboard paste delay: 100000
13. Userbutton shortcut: ctrlaltdel
14. Instruction tracing: off (doesn't exist yet)
15. Continue simulation
16. Quit now

Please choose one:  [15] 
</screen>
</para>
<para>
In the runtime configuration you can change the floppy/cdrom image or device,
change the log options or adjust some other settings. If you have trouble with
a specific device, you can change the log options for this device only to get
more information (e.g. report debug messages). This cannot be done in the configuration
file yet.
</para>
</section>
</section>
<section id="using-save-restore"><title>Save and restore simulation</title>
<para>
Starting with version 2.3, Bochs has limited save/restore support. The state of
cpu(s), memory and all devices can be saved now. To enable this feature, Bochs
must be compiled with the <option>--enable-save-restore</option> option. When running
Bochs with save/restore support there will be a new button in the header bar called
"Suspend". Depending on config interface and gui there will be a prompt where you
can enter a path or a gui folder selection dialog box. It is possible to save the
state at any time, but we recommend to do it when the simulation is idle. After
pressing OK/Enter, Bochs will save a set of files into the selected folder.
The state of hard disk images is not handled yet, so Bochs will ask you if you
want to continue after saving state. We don't recommend to continue unless you
are running a read-only guest system (e.g. Live-CD).
</para>
<para>
To restore the saved simulation state you can select the restore function in the
text mode start menu or specify the restore path at the command line:
<screen>
bochs -r /path/to/save-restore-data
</screen>
</para>
<para>
Then Bochs will start up using the saved configuration and log options, restores
the state of the hardware and begins the simulation. In the restore mode Bochs
will ignore bochsrc options from the command line and does not load a normal
config file.
</para>
</section>
</chapter>

<chapter id="common-problems">
  <title>Common problems and what to do about them (Troubleshooting)</title>
  <para>
    &FIXME;
    <screen>
      How to report a panic to the bug tracker?
      Keyboard mapping problems
      [...]
    </screen>
  </para>

  <section>
    <title>Bochs panics! What can I do?</title>
    <para>
      Bochs does a very good job in emulating an x86 compatible computer, however,
      it does not (yet) include a full (100%) emulation of every possible instruction,
      (BIOS) function call or (hardware) device. Thus, in case something unusual
      happens, either a not-so-common call to some (BIOS) function or device by
      some software running inside of it, Bochs has two possibilities to react:
      If the command doesn't look important (mainly happens only to non-implemented
      functions in the BIOS), a notice is logged to the <link linkend="bochsopt-log">log file</link>
      and the emulation continues. If, however, the command looks important, Bochs
      panics, because the software being emulated might depend on the successful
      execution of the given instruction or behaviour of the device.
    </para>
    <para>
      A panic does not always mean that the software won't run inside of Bochs,
      as the software might just be probing the computer for the presence of some
      instruction/device, and in case it is not found, it simply won't be used at
      all, by the software.
    </para>
    <para>
      You can tell Bochs what to do in case of a panic, by re-configuring the
      <link linkend="bochsopt-debug-info-error-panic">panic option</link>. If
      you change the action to "ask", Bochs reports what has happened and asks
      you what to do. The appearance of the "ask" feature depends on the display
      library used and the platform. Some display libraries don't support it at all.
    </para>
    <para>
      Some of the device names reported in the panic message are abbreviations,
      since the length of the names is limited to 5 characters. This small list
      may help you finding out the name of the device that caused the panic.
    </para>
    <table><title>Device prefixes</title>
      <tgroup cols="2" align="left" colsep="1" rowsep="1">
      <thead>
        <row>
          <entry>Prefix</entry>
          <entry>Description</entry>
        </row>
      </thead>
      <tbody>
        <row>
          <entry>CLVGA</entry>
          <entry>Cirrus SVGA</entry>
        </row>
        <row>
          <entry>EFIRQ</entry>
          <entry>External FPU IRQ</entry>
        </row>
        <row>
          <entry>IOAP</entry>
          <entry>I/O APIC</entry>
        </row>
        <row>
          <entry>KMAP</entry>
          <entry>Keyboard mapping</entry>
        </row>
        <row>
          <entry>P2I</entry>
          <entry>PCI-to-ISA bridge</entry>
        </row>
        <row>
          <entry>PIDE</entry>
          <entry>PCI IDE controller</entry>
        </row>
        <row>
          <entry>PLGIN</entry>
          <entry>Plugin interface</entry>
        </row>
        <row>
          <entry>STIME</entry>
          <entry>Slowdown timer</entry>
        </row>
        <row>
          <entry>UNMP</entry>
          <entry>Unmapped I/O handler</entry>
        </row>
        <row>
          <entry>VTIME</entry>
          <entry>Virtual timer</entry>
        </row>
      </tbody>
      </tgroup>
    </table>
  </section>

  <section id="mouse-toggle">
    <title>Mouse behavior, enabling and disabling</title>
    <para>
      Refer to <xref linkend="headerbar"> for information on how to enable or
      disable the mouse inside of Bochs at run-time. 
    </para>
    <para>
      &FIXME; Mouse behavior
    </para>
  </section>

  <section id="textmode-problems">
    <title>Text-mode is broken in some ancient DOS program</title>

    <para>
      If you are using a program written for DOS which seems to use the text-mode but
      doesn't display the text properly, you can try the other VGA BIOS, either
      <filename>VGABIOS-lgpl-latest</filename> or <filename>VGABIOS-elpin-2.40</filename>,
      see the <link linkend="bochsopt-vgaromimage">vgaromimage option</link>.
    </para>

    <para>
      &NEEDHELP; Maybe it is a bug in the LGPL VGA BIOS, but for now, it seems to work.
    </para>
  </section>
</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 id="mailinglist-etiquette"><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>
If you are having difficulty finding what you are looking for, try doing a search on <ulink url="http://www.google.com">Google</ulink>.  If you are searching for Bochs options, for example, you can use this syntax in the Google search box:
<programlisting>
configuration options site:bochs.sourceforge.net
</programlisting>
For best results, be sure not to put a space between "site:" and "bochs.sourceforge.net".  Be sure to look at more than the first item on the search results.
</para></listitem>

<listitem>
<para>
If you still cannot find what you are looking for, be sure you are prepared when you post your question, and post in the right forum.  Be sure you include important details, such as the operating system and version of your host, and what it is you are trying to do.   If you are getting errors or something is not working, summarize what you checked and what you changed.  This will help isolate the problem.
</para>
</listitem>

<listitem>
<para>
Bochs is for everyone.  If you are an experienced Bochs user or developer and are helping someone else, be considerate of the other person's feelings.  We share a common interest, and we need to encourage each other and be supportive.
</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 id="howto"><title>Tips and Techniques</title>

<section id="diskimagehowto"><title>How to make a simple 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 (e.g. a Linux install disk).
</para></listitem>
<listitem><para>
(Optional) mtools, a program for manipulating DOS disks/images.
</para></listitem>
</itemizedlist>

</para>

<section><title>
Create a flat image
</title>

<para>
Option 1: Using the Unix <command>dd</command> utility:
</para>

<para>
You will need to know the geometry of the disk you want to
create. You have to compute the disk sector count:

<screen>
Sectors = Cylinders * Heads * SectorsPerTrack
</screen>
</para>

<para>
Use the dd command to create your file:

<screen>
dd if=/dev/zero of=teaching.img bs=512 count=<replaceable>sectors</replaceable>
</screen>
(replace "sectors" with the number you computed at the
previous step).
</para>

<para>
When you'll update your configuration file, please
fill in the same cylinders, heads and sector per
track values.
</para>


<para>
Option 2: Run <command>bximage</command> to create a disk image file.  
You will be greeted with the following prompt:

<screen>
========================================================================
                                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] 
</screen>
</para>


<para>
Since we are creating a hard disk image, accept the default of hd by
pressing <keycap>Enter</keycap> or typing 'hd' and pressing
<keycap>Enter</keycap>. Next, bximage will ask for the type of
hd to create:

<screen>
What kind of image should I create?
Please type flat, sparse or growing. [flat] 
</screen>
</para>


<para>
We want to create a simple flat image, so accept the default
by pressing <keycap>Enter</keycap>. Then, bximage will ask 
for the size of the disk image you want to create, in Megabytes:

<screen>
Enter the hard disk size in megabytes, between 1 and 32255
[10] 
</screen>
</para>


<para>
Enter the size of the hard disk you want to create, and press
<keycap>Enter</keycap>. 
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:

<screen>
[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] 
</screen>
</para>


<para>
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 <keycap>Enter</keycap>.  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 <filename>bochsrc</filename> when you want to use this disk image. I named my
10 Megabyte image "teaching.img" and the output of bximage looked like
this:

<screen>
[c.img] teaching.img

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

I wrote 10321920 bytes to teaching.img.
</screen>
</para>

<para>
The following line should appear in your <filename>bochsrc</filename>:
<screen>
  <link linkend="bochsopt-ata-master-slave">ata0-master</link>: type=disk, path="teaching.img", mode=flat, cylinders=20, heads=16, spt=63
</screen>
</para>


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

<tip>
<para>
You may want to name your image <filename>teaching_20-16-63.img</filename>
so that you always know the values to use for CHS.
</para>
</tip>
</section>

<section>
<title>
Partition and format your image file
</title>

<para>
Option 1: Using FreeDOS (Advantage: Creates a MBR on the partition.)
</para>

<para>
First, you need to edit the <filename>bochsrc</filename> file that Bochs uses for
configuration information (see <xref linkend="search-order">). Open <filename>bochsrc</filename>
with a text editor. Remove all lines in the file which start with "ata0-master:". Add the "ata0-master:"
line that was displayed when you ran bximage to <filename>bochsrc</filename> at the
same place where you removed the old "ata0-master:" lines from.
</para>

<para>
Also, you need to download or create a FreeDOS (or DOS, or Windows, or
Linux) disk image. Modify the "floppya:" line in your <filename>bochsrc</filename> to point
at the downloaded FreeDOS floppy image and change its status to "status=inserted".
</para>

<para>
Save and close your <filename>bochsrc</filename>. Now run Bochs (see <xref linkend="using-bochs">).
</para>

<para>
Use the standard FreeDOS commands <command>fdisk</command> and
<command>format</command> to format your hard
drive image. You must make the image bootable to be able to boot
without a floppy disk. However, creating a bootable disk image is best
done with a boot disk from the OS you intend to install on the image.
</para>


<para>
Option 2: Using mtools (Disadvantage: Cannot create bootable images
without a MBR image.)
</para>

<para>
Use a text editor to add the following line to the file <filename>~/.mtoolsrc</filename>:
</para>


<screen>
drive c: file="<replaceable>path</replaceable>/filename.img" partition=1
</screen>


<para>
Save and close <filename>.mtoolsrc</filename>. Next, execute the following commands to
create a partition table for the drive image:
</para>


<screen>
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:
</screen>

<para>
For example, for my 10 meg drive, I used:
<screen>
mpartition -I -s 63 -t 20 -h 16 c:
mpartition -cpv -s 63 -t 20 -h 16 c:
</screen>
</para>


<para>
Next, format the partition you just created using the mformat command:

<screen>
mformat c:
</screen>
</para>


<para>
And you now have a formatted disk image containing a single DOS
partition.
</para>
<note><para>
The mpartition command doesn't handle images larger than 1024 cylinders properly.
The partition size reported by fdisk is okay, but mformat reports only 504 MB
(tested with mtools 3.9.9).
</para></note>
</section>
</section> <!-- end of Unix: How to make a disk image -->

<section id="mtools"><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 id="bochs-linux-disktools"><title>Bochs GNU/Linux DiskTools</title>
<para>
&FIXME;
Bochs tools are external tools developped by ..., and useful to copy
to / from guest partition from a GNU/Linux host.
</para>
</section>

<section id="winimage"><title>Win32 only: Tools to manipulate disk images</title>

<section> <title>Winimage</title>
<para>
Someone on the bochs-developers list mentioned that they use a program
called WinImage, from <ulink url="http://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>DiskExplorer</title>
<para>
This section was contributed by Luca Cassioli and Stanislav Shwartsman
</para>
<para>
I eventually found what all of you were looking for for a long time: a
freeware, graphical, win32 compatible HardDisk image editor! It can 
handle a large variety of formats, but the one you need is VMWARE
2.0 PLAIN DISK: you can import/export to/from Bochs images COMPLETE
DIRECTORIES! 
</para>
<para>
You can find it at 
<ulink url="http://hp.vector.co.jp/authors/VA013937/editdisk/index_e.html">
http://hp.vector.co.jp/authors/VA013937/editdisk/index_e.html</ulink>
</para>
</section>

<section> <title>Ben Lunt's MTOOLs for Bochs and Win32 and/or DOS</title>
<para>
Ben Lunt wrote a set of utilities for Dos/Win32 to manipulate flat disk images.
</para>
<para>
You can find it at 
<ulink url="http://www.frontiernet.net/~fys/mtools.htm">
http://www.frontiernet.net/~fys/mtools.htm</ulink>
</para>
<para>
These utilities includes :
<itemizedlist>
<listitem><para> 
        BOCHSRC.EXE "Bochs Resource"  
        A utility to create/modify a Bochs resource file.
</para></listitem>
<listitem><para> 
        MKDOSFS.EXE  "Make DOS FS" 
        A utility to create a FAT disk image of specified size.
</para></listitem>
<listitem><para> 
        MCOPYF.EXE  "Copy From"
        A utility to copy an existing file from a FAT disk image to the current
        directory.  
</para></listitem>
<listitem><para> 
        MDEL.EXE  "Delete file"
        A utility to delete an existing file from a FAT disk image.
</para></listitem>
<listitem><para> 
        MDIREX.EXE  "Directory Extended"
        A utility to view a FAT disk images directory and FAT contents.
</para></listitem>
<listitem><para> 
        MGETIMG.EXE  "Get Disk Image"
        A utility to create a disk image from a floppy (multiple formats).
</para></listitem>
<listitem><para> 
        MBOOTCD.EXE  "Create a CDROM Image with boot options"
        Create a CDROM image capable of booting with only a ROOT and a single file.
</para></listitem>
<listitem><para> 
        MGETCD.EXE  "Get Disk Image of Physical CD"
        A utility to create a disk image from a CD.
</para></listitem>
<listitem><para> 
        MCDINFO.EXE  "Get CD Info"  
        A utility to the info from a CD.  Not much yet, but a little.
</para></listitem>
</itemizedlist>

</para>
</section>

</section>

<section id="xcolormap"><title>X Windows: Color allocation problems</title>
<para>
One common problem in X windows is that the screen colors can be abnormal
if other X programs have already allocated all the colors.  If the colors
don't look right, try quitting colorful applications such as Netscape,
clearing any complex images in the background, etc. so that Bochs has a
chance to allocate the colors it needs.
</para>
<para>
If Bochs continues to have problems, or you want Bochs to have perfect
colors without having to quit any other application, you can try turning
on the <link linkend="bochsopt-private-colormap">private_colormap option</link>
in the configuration file.  Using a private
colormap causes the Bochs window to have its own set of 256 colors to work
with.  When the cursor is over the Bochs display, Bochs will look correct
and other parts of the screen may change to very strange colors.  When the
cursor goes to any other window, the other windows will look correct
and Bochs will have strange colors.  A better solution, if your hardware
can support it, is to run your X server with 24-bit or 32-bit color.
</para>
</section>

<section id="screensaver"><title>Screen saver turns on too quickly</title>

<para>
One thing you may notice is that the screen saver turns on (screen goes
blank) very quickly after you have stopped typing.  The reason is that Bochs
simulates everything as fast as it can.  If the CPU is very busy (running
instructions nonstop), simulated time goes by slowly.  If the CPU is idle (just
waiting for you to type, for example), simulated time speeds up dramatically.
In any case, if the screen saver blanks out the screen, just press a key (try
shift or control) to restore the screen.
</para>

<para>
There are two strategies to fix this problem.  One is to increase the
<command>ips</command> parameter of the <link linkend="bochsopt-cpu">cpu option</link>
in your configuration file. This will cause the simulation time
to pass more slowly.  The other strategy is to enable the experimental
realtime PIT, which tries to keep Bochs in sync with real time. See the <filename>bochsrc</filename>
option <link linkend="bochsopt-clock">clock</link>.
</para>

</section>


<section id="loop-device-usage"><title>Mounting a disk image using the loop device</title>

<para>
This section describes how to access a floppy or hard disk image within Linux
using the loop device. Why would you want to do this?  Let's say you have made
a small Linux disk image for Bochs, and you want to install some more software
on it. You have already downloaded the software onto your real system, so now
you want to transfer it to the Bochs disk image.  A fast way to transfer
the files is to mount the disk image using the loop device.
</para>

<section><title>...on Linux</title>

<para>
This section was contributed by Volker Ruppert.
<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>

<section><title>...on FreeBSD</title>

<para>
This section was contributed by Alexander Schuch.
</para>
<para>
The following example mounts a Windows 95 hard disk image called <filename>Windows 95 B (2031-16-63)</filename>
into the FreeBSD file system. It is specific to FreeBSD 5.x; for
hints on how to do the same task on FreeBSD 4.x, or for more information in
general, check the proper section of the FreeBSD handbook:
<ulink url="http://www.freebsd.org/doc/en/books/handbook/disks-virtual.html">Network, Memory, and File-Backed File Systems</ulink>.
You can use the same procedure for mounting floppy disk images.
</para>

<para>
<screen>
<prompt>#</prompt> <userinput>mdconfig -a -t vnode -f "Windows 95 B (2031-16-63)"</userinput>
md0
</screen>
mdconfig returns the device, your file now is accessable from.
<screen>
<prompt>#</prompt> <userinput>mount -t msdosfs /dev/md0s1 /mnt</userinput>
</screen>
If you already have other md devices configured, you need to substitute md0s1
with, for example, md6s1.
</para>

<para>
Once you are done working with the image, unmount the md device and detach it.
<screen>
<prompt>#</prompt> <userinput>umount /mnt</userinput>
<prompt>#</prompt> <userinput>mdconfig -d -u 0</userinput>
</screen>
And again, if there are other md devices configured, use the proper device
number. In case you forgot the number, just ask <command>mdconfig</command>, like:
<screen>
<prompt>#</prompt> <userinput>mdconfig -l</userinput>
md7
<prompt>#</prompt> <userinput>mdconfig -d -u 7</userinput>
</screen>
</para>

</section>

</section>  <!-- end of 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-smp" 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>
Starting with Bochs 2.2.6 you can set up the number of processors in the
<filename>bochsrc</filename>. See <xref linkend="bochsopt-cpu"> how to
set up the number of processors.
</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?

<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 (read time stamp counter)
</para></listitem>
<listitem><para> a data structure called the Intel Multiprocessor Configuration
must be present in BIOS memory space. An SMP-aware operating system probes BIOS
memory to find the structure, which contains information about how many
processors, their IDs, interrupt sources, etc. Starting with Bochs 2.2.5 these
structures are dynamicly created by Bochs.
</para></listitem>
<listitem><para> ACPI support is required to boot SMP system in most of modern
operating systems. For example WinXP 64 bit require ACPI support even for 
single processor configuration. Still not supported by Bochs.
</para></listitem>
</itemizedlist>
</para>

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

<itemizedlist>
<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 any possible SMP operating systems. Currently success reported for
Knoppix 4.0.2 and WinNT 4.0 SMP.
</para></listitem>

<listitem><para>
several parts of the APIC model which weren't needed before 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".
</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 id="dlxlinux-networking"><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 Mac OS X
  ne2k: ioaddr=0x240, irq=9, mac=b0:c4:20:00:00:00, ethmod=fbsd, ethdev=en0
  # sample for FreeBSD
  ne2k: ioaddr=0x240, irq=9, mac=b0:c4:20:00:00:00, ethmod=fbsd, ethdev=xl0
  # sample for Linux
  ne2k: ioaddr=0x240, irq=9, mac=b0:c4:20:00:00:00, ethmod=linux, ethdev=eth0
  # sample for Windows
  ne2k: ioaddr=0x240, 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>

<section id="config-tuntap"><title>Configuring and using a tuntap network interface</title>
<para>
If you use linux (optionally FreeBSD and Solaris, not tested), 
you may want to access the network through a tuntap interface. The main
advantage of this interface, is that the guest has access to the host. The guest can even
have access to the whole network if the host routes or masquerades the guest requests.
No extra IP address is needed, all can be done using private IP addresses.
</para>

<para>
You'll find here instructions to set up Linux/Bochs to provide network access to the guest OS
through a tuntap interface and private IP network. We're going to see howto :
<itemizedlist>
<listitem> <para>enable the tuntap interface in the Linux Kernel </para> </listitem>
<listitem> <para>configure Bochs to use the tuntap interface </para> </listitem>
<listitem> <para>set up the private network between the host and the guest </para> </listitem>
<listitem> <para>set up the host to masquerade the guest network accesses </para> </listitem>
</itemizedlist>
</para>
<section>
        <title>Tuntap description</title>
<para>
From the <ulink url="http://www.kernel.org/pub/linux/kernel/people/marcelo/linux-2.4/Documentation/networking/tuntap.txt">
tuntap.txt</ulink> file in the Linux kernel tree :
<screen>
  TUN/TAP provides packet reception and transmission for user space programs. 
  It can be viewed as a simple Point-to-Point or Ethernet device, which 
  instead of receiving packets from a physical media, receives them from 
  user space program and instead of sending packets via physical media 
  writes them to the user space program. 

  When a program opens /dev/net/tun, driver creates and registers corresponding
  net device tunX or tapX. After a program closed above devices, driver will 
  automatically delete tunXX or tapXX device and all routes corresponding to it.
</screen>
</para>
</section> <!-- Tuntap description -->

<section>
        <title>Set up the linux Kernel
        <footnote><para>much of the information of the following section is taken from 
        <ulink url="http://maconlinux.org/lists/mol-general/August01/0056.html">
        this email from Samuel Rydh of the Mac-On-Linux list</ulink></para></footnote></title>
<para>
First make sure the tuntap module is included in the kernel :
<itemizedlist>
<listitem> 
        <para>if you use a recent distribution, chances are that the needed modules are already build</para> 
        <para>Make sure that "Kernel module loader" - module auto-loading support is enabled in your kernel.</para>
        <para>Add following line to the /etc/modules.conf: <screen> alias char-major-10-200 tun </screen> </para>
        <para>Run: <screen> depmod -a</screen> The driver will be automatically loaded when application access /dev/net/tun.</para>
</listitem>
<listitem> 
        <para>Otherwise, recompile the kernel, including the configuration option
        <screen> CONFIG_TUN (Network device support -> Universal TUN/TAP device driver support) </screen>
        </para> 
</listitem>
</itemizedlist>
<note>
<para>
Make sure there is a /dev/net/tun device.
(Can be created with '<command>mkdir /dev/net ; mknod /dev/net/tun c 10 200'</command>).
</para>
</note>
</para>
<para>
In the same way, to use masquerading, you need a kernel with the following options :
<screen>
 CONFIG_IP_NF_CONNTRACK (Connection tracking)
 CONFIG_IP_NF_IPTABLES (IP tables support)
 CONFIG_IP_NF_NAT (Full NAT)
</screen>
<note>
<para>
Some of the other options in this group is probably also needed,
(but the default setting should be OK).
</para>
</note>
</para>
</section> <!-- Set up the linux Kernel -->
 
<section>
        <title>Configure Bochs to use the tuntap interface</title>
        <para>Make sure Bochs has ne2000 support. If you have to recompile Bochs, 
                <command>--enable-ne2000</command> when running <command>./configure</command> 
                (see <xref linkend="compiling">)
        </para>
        <para>edit your <replaceable>.bochsrc</replaceable> configuration file and add something like :
                <screen>  ne2k: ioaddr=0x240, irq=9, mac=fe:fd:00:00:00:01, 
                          ethmod=tuntap, ethdev=/dev/net/tun0, script=<replaceable>/path/to/tunconfig</replaceable>
                </screen>
        </para>
        <para>
                Since the tuntap interface cannot be configured until a process opens it,
                Bochs may run a script file for you. In this case 
                <replaceable>/path/to/tunconfig</replaceable> should be changed to match
                the actual place where you'll create this script.
        </para>
</section> <!-- Configure Bochs to use the tuntap interface -->

<section> 
<title>Set up the private network between the host and the guest </title> 
        <para>
        We'll set up a private network between the host and the guest with the following parameters:
        <screen>
                Host IP : 192.168.1.1
                Guest IP : 192.168.1.2
        </screen>
        If your parameters are different, adapt the rest of the section to suit your needs.
        </para>
        <para>
        Create the <replaceable>/path/to/tunconfig</replaceable> script :
        <screen>
        #!/bin/bash
        /sbin/ifconfig ${1##/*/} 192.168.1.1
        </screen>
        The script get the interface name as the first parameter. Linux
        will forward incoming packets between interfaces.
        </para>
        <para>
        Make it executable :<screen>chmod 755 <replaceable>/path/to/tunconfig</replaceable></screen>
        </para>
        <para>
        Run Bochs, install the guest OS, and set the following network parameters in the guest OS:
        <screen>
        IP: 192.168.1.2
        netmask: 255.255.255.0
        gateway: 192.168.1.1
        nameserver: whatever is used in linux
        </screen>
        <note>
        <para>
        Bochs must be started by root (at least for now - the
        script won't have root privileges otherwise).
        </para>
        </note>
        You may also have to edit /etc/hosts.allow in the host OS and add :
        <screen>
        ALL: 192.168.1.2
        </screen>
        Don't forget to set up the route on the guest.
        </para>
        <para>
        At this point, you should be able to ping/telnet/ftp/ssh the guest from the host
        and vice-versa.
        </para>
</section> <!-- Set up the private network between the host and the guest -->

<section> 
<title>Set up the host to masquerade the guest network accesses</title>
        <para>
        We are going to set up standard masquerading configuration. Edit
        the  <replaceable>/path/to/tunconfig</replaceable> script ans add :
        <screen>
        /sbin/iptables -D POSTROUTING -t nat -s 192.168.1.0/24 -d ! 192.168.1.0/24 -j MASQUERADE >& /dev/null
        /sbin/iptables -t nat -s 192.168.1.0/24 -d ! 192.168.1.0/24 -A POSTROUTING -j MASQUERADE
        echo 1 > /proc/sys/net/ipv4/ip_forward
        </screen>
        <note>
        <para>
        The configuration assumes the default policy is
        ACCEPT (can be examined by doing '<command>/sbin/iptables -L</command>')
        </para>
        </note>
        <note><para> The iptables package must be installed. </para> </note>
        And voila... The host should forward the packets of the guest to the rest of your network.
        You could even have acces to the internet...
        &FIXME; add nice screenshot
        <note>
        <para>
        You may need to load other modules if you want to use other fancy protocols (ftp,etc...)
        </para>
        </note>
        </para>
</section> <!-- Set up the host to masquerade the guest network accesses -->
</section>

<section id="internal-debugger">
<title>Using Bochs internal debugger</title>

<para>
Note, if you are looking for a graphical front-end for the
bochs debugger, you may want to check out
<ulink url="http://bfe.sourceforge.net/">BFE</ulink>. This is a
package written by a Bochs user which can interface with
the text based Bochs debugger.  No linking is necessary.
It's not part of Bochs, but you may find it useful.
</para>

<para>
You can now conditionally compile in a GDB like command line debugger, that
allows you to set breakpoints, step through instructions, and other
useful functions.  If there isn't a command for something you believe
is generally useful for the debugger, let me know and I'll implement
it if possible.
</para>

<para>
To use the debugger, you must configure Bochs with the
<option>--enable-debugger</option> and <option>--enable-disasm</option> flags.
For example:
<screen>
  ./configure --enable-debugger --enable-disasm
</screen>
</para>

<note><para>
You must use flex version 2.5.4 or greater.  I have heard that
version 2.5.2 will not work.
</para></note>

<para>
When you first start up Bochs, you will see the command line prompt

<screen>
  bochs:1>
</screen>

From here, you may use the following commands:
</para>

<section>
<title>Execution Control</title>
<para>
<screen>
  c                           continue executing
  continue

  s     [count]               execute count instructions, default is 1
  step  [count]
  stepi [count]

  Ctrl-C                      stop execution, and return to command line prompt
  Ctrl-D                      if at empty line on command line, exit

  q                           quit debugger and execution
  quit
  exit
</screen>
</para>
</section>

<section>
<title>BreakPoints</title>
<para>
<screen>
  NOTE: The format of 'seg', 'off', and 'addr' in these descriptions,
        are as follows.  I don't have any way to set the current radix.

        hexidecimal:    0xcdef0123
        decimal:        123456789
        octal:          01234567

  vbreak seg:off              Set a virtual address instruction breakpoint
  vb     seg:off

  lbreak addr                 Set a linear address instruction breakpoint
  lb     addr

  pbreak [*] addr             Set a physical address instruction breakpoint
  pb     [*] addr             (the '*' is optional for GDB compatibility)
  break  [*] addr
  b      [*] addr

  info break                  Display state of all current breakpoints
  bpe    n                    Enable a breakpoint
  bpd    n                    Disable a breakpoint
  delete n                    Delete a breakpoint
  del    n
  d      n

</screen>
</para>
</section>

<section>
<title>Manipulating Memory</title>
<para>
<screen>
  x  /nuf addr      Examine memory at linear address addr
  xp /nuf addr      Examine memory at physical address addr
     n              Count of how many units to display
     u              Unit size; one of
                      b Individual bytes
                      h Halfwords (2 bytes)
                      w Words (4 bytes)
                      g Giant words (8 bytes)
                      NOTE: these are *not* typical Intel nomenclature sizes,
                            but they are consistent with GDB convention.
     f              Printing format.  one of
                      x Print in hexadecimal
                      d Print in decimal
                      u Print in unsigned decimal
                      o Print in octal
                      t Print in binary

    n, f, and u are optional parameters.  u and f default to the last values
    you used, or to w(words) and x(hex) if none have been supplied.
    n currently defaults to 1.  If none of these optional parameters are
    used, no slash should be typed.  addr is also optional.  If you don't
    specify it, it will be the value the next address (as if you had
    specified n+1 in the last x command).

  setpmem addr datasize val    Set physical memory location of size
                               datasize to value val.

  crc  addr1  addr2            Show CRC32 for physical memory range addr1..addr2
  info dirty                   Show physical pages dirtied (written to) since last display
                               Values displayed are the top 20 bits only (page addresses)

</screen>
</para>
</section>

<section>
<title>Info commands</title>
<para>
<screen>
  info r|reg|regs|registers    List of CPU integer registers and their contents
  info cpu                     List of all CPU registers and their contents
  info fpu                     List of all FPU registers and their contents
  info sse                     List of all SSE registers and their contents
  info cr                      Show CR0-4 registers and their contents
  info eflags                  Show decoded EFLAGS register
  info break                   Information about current breakpoint status
  info tab                     Show paging address translation
</screen>
</para>
</section>

<section>
<title>Manipulating CPU Registers</title>
<para>
<screen>
  set reg = expr    Change a CPU register to value of expression.
                    Currently only general purpose registers are supported,
                    you may not change:
                      eflags, eip, cs, ss, ds, es, fs, gs.

    Examples: set eax = 2+2/2
              set esi = 2*eax+ebx

  registers         List of CPU registers and their contents
  regs
  reg
  r

  dump_cpu          Dump complete CPU state
  set_cpu           Set  complete CPU state

    Format of "dump_cpu" and "set_cpu":
    "eax:0x%x\n"
    "ebx:0x%x\n"
    "ecx:0x%x\n"
    "edx:0x%x\n"
    "ebp:0x%x\n"
    "esi:0x%x\n"
    "edi:0x%x\n"
    "esp:0x%x\n"
    "eflags:0x%x\n"
    "eip:0x%x\n"
    "cs:s=0x%x, dl=0x%x, dh=0x%x, valid=%u\n"
    "ss:s=0x%x, dl=0x%x, dh=0x%x, valid=%u\n"
    "ds:s=0x%x, dl=0x%x, dh=0x%x, valid=%u\n"
    "es:s=0x%x, dl=0x%x, dh=0x%x, valid=%u\n"
    "fs:s=0x%x, dl=0x%x, dh=0x%x, valid=%u\n"
    "gs:s=0x%x, dl=0x%x, dh=0x%x, valid=%u\n"
    "ldtr:s=0x%x, dl=0x%x, dh=0x%x, valid=%u\n"
    "tr:s=0x%x, dl=0x%x, dh=0x%x, valid=%u\n"
    "gdtr:base=0x%x, limit=0x%x\n"
    "idtr:base=0x%x, limit=0x%x\n"
    "dr0:0x%x\n"
    "dr1:0x%x\n"
    "dr2:0x%x\n"
    "dr3:0x%x\n"
    "dr4:0x%x\n"
    "dr5:0x%x\n"
    "dr6:0x%x\n"
    "dr7:0x%x\n"
    "cr0:0x%x\n"
    "cr1:0x%x\n"
    "cr2:0x%x\n"
    "cr3:0x%x\n"
    "cr4:0x%x\n"
    "inhibit_int:%u\n"
    "done\n"

    Notes:
      - s is the selector
      - dl is the shadow descriptor low  dword (4 byte quantitiy)
      - dh is the shadow descriptor high dword (4 byte quantitiy)
      - valid denotes if the segment register holds a validated shadow descriptor
      - inhibit_int is set if the previous instruction was one which delays the
          acceptance of interrupts by one instruction (STI, MOV SS)
      - any errors encountered by the set_cpu command, are reported by
        "Error: ...".  They may be reported after any of the input lines,
        or after the "done" line, during limit checks.
      - A successful set_cpu command ends with the separate line:
        "OK".
</screen>
</para>
</section>

<section>
<title>Disassembly commands</title>
<para>
<screen>
  disassemble start end       Disassemble instructions in given linear address
                              range, inclusive of start, exclusive of end.
                              Use "set $disassemble_size =" to tell
                              debugger desired segment size.  Use a value for
                              end of less than start (or zero) if you only
                              want the first instruction disassembled.

  disassemble switch-mode     Switch between Intel and AT&amp;T disassebly styles
                              for debugger disassembler.

  disassemble size = n        Tell debugger what segment size to use when
                              the "disassemble" command is used.  Use values
                              of 0, 16 or 32 for n.  Value of 0 means
			      "use segment size specified by current CS
			      segment". Default is 0.

  set $auto_disassemble = n   Cause debugger to disassemble current instruction
                              every time execution stops if n=1.  Default is 0.
                              Segment size of current CPU context is used for
                              disassembly, so the "disassemble size" variable is
                              ignored.

  set disassemble on          The same as 'set $auto_disassemble = 1'
  set disassemble off         The same as 'set $auto_disassemble = 0'
</screen>
</para>
</section>

<section>
<title>Instruction tracing</title>
<para>
<screen>
  trace on                    Disassemble every executed instruction. Note
                              that instructions which caused exceptions are
                              not really executed, and therefore not traced.

  trace off                   Disable instruction tracing.
</screen>
</para>
</section>

<section>
<title>Instrumentation</title>
<para>

To use instrumentation features in bochs, you must compile in support for it.
You should build a custom instrumentation library in a separate directory in
the "instrument/" directory.  To tell configure which instrumentation library
you want to use, use the "--enable-instrumentation" option.

The default library consists of a set of stubs, and the following are
equivalent:

<screen>
  ./configure [...] --enable-instrumentation
  ./configure [...] --enable-instrumentation="instrument/stubs"
</screen>

You could make a separate directory with your custom library,
for example "instrument/myinstrument", copy the contents of
the "instrument/stubs" directory to it, then customize it.  Use:

<screen>
  ./configure [...] --enable-instrumentation="instrument/myinstrument"
</screen>
</para>
</section>

<section>
<title>Instrumentation commands</title>
<para>
<screen>
  instrument start            calls bx_instr_start()
  instrument stop             calls bx_instr_stop()
  instrument reset            calls bx_instr_reset()
  instrument print            calls bx_instr_print()
</screen>
</para>
</section>

<section>
<title>Other Commands</title>
<para>

<screen>ptime</screen>

Print the current time (number of ticks since start of simulation).

<screen>sb <varname>delta</varname></screen>

Insert a time break point "delta" instructions into the future ("delta" is a 64-bit integer followed by "L", for example 1000L).

<screen>sba <varname>time</varname></screen>

Insert a time break point at "time" ("time" is a 64-bit integer followed by "L", for example 1000L).

<screen>record <varname>filename</varname></screen>

Record console input to file <varname>filename</varname>. The file consists of
zero or more lines of the form "%s %d %x", where the first word is the
event type, the second is a time stamp and the third is event specific
data.

<screen>playback <varname>filename</varname></screen>

Playback console input from file <varname>filename</varname>. Additional input can
be given directly in the console window. Events in the file will be
played back at times relative to the time when the playback command
was executed.

<screen>print-stack [<varname>num words</varname>]</screen>

Print the <varname>num words</varname> top 16-bit words on the stack. <varname>Num
words</varname> defaults to 16. Only works reliably in protected mode when
the base address of the stack segment is zero.

<screen>watch stop</screen>

Stop the simulation (and return to prompt) when a watch point is
encountered.

<screen>watch continue</screen>

Do not stop the simulation when watch points are encountered. They will
still be logged.

<screen>watch</screen>

Print current watch point status.

<screen>unwatch</screen>

Remove all watch points.

<screen>watch read <varname>address</varname></screen>

Insert a read watch point at physical address <varname>address</varname>.

<screen>watch write address</screen>

Insert a write watch point at physical address <varname>address</varname>.

<screen>unwatch read <varname>address</varname></screen>

Remove read watch point from physical address <varname>address</varname>.

<screen>unwatch write <varname>address</varname></screen>

Remove write watch point from physical address <varname>address</varname>.

<screen>modebp</screen>

Toggles CPU mode switch breakpoint.

<screen>load-symbols [global] <varname>filename</varname> [<varname>offset</varname>]</screen>

Load symbols from file <varname>filename</varname>. If the global keyword is
added, then the the symbols will be visible in all contexts for which
symbols have not been loaded. <varname>Offset</varname> (default is 0) is added to
every symbol entry. The symbols are loaded in the current (executing)
context.
</para>

<para>
The symbol file consists of zero or more lines of the format <screen>"%x %s"</screen>.

<screen>show [<varname>string</varname>]</screen>

<screen>
  Toggles show symbolic info (calls to begin with).
  show - shows current show mode
  show mode     - show, when processor switch mode
  show int      - show, when interrupt is happens
  show call     - show, when call is happens
  show ret      - show, when iret is happens
  show off      - toggles off symbolic info
  show dbg-all  - turn on all show flags
  show dbg-none - turn off all show flags
</screen>
</para>
</section>

<section>
<title>
Related links
</title>
<para>
&FIXME; add links
<itemizedlist>
<listitem> <para> Cosimulation </para> </listitem>
<listitem> <para> Instrumentation </para> </listitem>
</itemizedlist>
</para>
</section> 
</section><!-- end: Using Bochs internal debugger -->

<section id="debugging-with-gdb">
<title>Using Bochs and the remote GDB stub</title>
<para>
This section covers how you can use Bochs with a remote GDB stub to debug your kernel.
</para>

<section>
<title>Configuring Bochs</title>
<para>
The GDB stub is not active in standard Bochs binary package.  So you must recompile Bochs.
Download the Bochs source package, unpack it and run the configure script
with the <command>--enable-gdb-stub</command> argument.

<screen>
  $ ./configure --enable-gdb-stub
</screen>

After that, just run make and you should have a Bochs binary that contain a GDB stub in your directory.
</para>
</section>

<section>
<title>Running Bochs</title>
<para>
Enable the <link linkend="bochsopt-gdbstub">gdbstub option</link> in <filename>bochsrc</filename>, then just start Bochs as normal. Bochs will stop and wait for GDB to connect to the stub.
</para>
</section>

<section>
<title>Running GDB</title>
<para>
Bochs GDB stub waits for a connection on port 1234 on localhost (127.0.0.1). Just start GDB like this:

<screen>
  $ gdb YOUR-KERNEL
  .
  .
  .
  (gdb) target remote localhost:1234
  Remote debugging using localhost:1234
  0x0000fff0 in ?? ()
  (gdb)
</screen>

You are now connected to the remote GDB stub in Bochs. You are now able to set breakpoints.
Use the continue (c) command to continue the simulation.

Hitting ^C works. Example:

<screen>
  Program received signal 0, Signal 0.
  syscall_testsuite_result (aux=0x1f11fe4) at ../rtmk/syscalls.c:33
  33     {
  (gdb)
</screen>
</para>
</section>

</section>

<section id="serial-port"><title>Using the serial port</title>
<para>
        This section describes what is possible to do with Bochs serial port emulation.
        These examples use dlxlinux disk image 
        (downloaded from 
        <ulink url="http://bochs.sourceforge.net/guestos/dlxlinux4.tar.gz">
        http://bochs.sourceforge.net/guestos/dlxlinux3.tar.gz</ulink>
        ) running as guest, on a debian x86 linux 2.4.19 host.
</para>
<para>
        For the examples to work in dlxlinux, after you login as root, you will need to 
        kill the running gpm, as it grabs the serial port.
<screen>
Welcome to DLX V1.0 (C) 1995-96 Erich Boehm
                    (C) 1995    Hannes Boehm


dlx login: root
Linux 1.3.89.
dlx:~# ps | grep gpm
   30  S0 S     0:00 /usr/bin/gpm -t bare
   40   1 S     0:00 grep gpm
dlx:~# kill -9 30
dlx:~#
</screen>
</para>

        <section><title>Logging serial port output to a file</title>
        <para>
        The first example shows how to log information sent to the serial port
        on the guest system into a file on the host system.
        </para>
        <para>
        Update the com1: section of your configuration file:
        <screen>
com1: enabled=1, mode=file, dev=serial.txt
        </screen>
        After you've launch dlxlinux, everything sent to the serial port will be
        logged to serial.txt :
        <screen>
dlx:~# echo "logging to the serial port" > /dev/cua0
        </screen>
        <screen>
host$ cat serial.txt
logging to the serial port
host$
        </screen>
        </para>
        </section>
        <section><title>Interactivity : connecting to a virtual terminal</title>
        <para>
        The second example shows how to connect to the guest OS, using a 
        virtual terminal on the host OS.
        </para>
        <para>
        First, you need to find an unused virtual terminal. Typically, 
        X uses vt7; vt8 and up are unused. On my system, I can 
        switch from X to vt9 by pressing ctrl-alt-f9 : this virtual
        terminal is not used, the screen is all black. Pressing alt-f7 
        switches back to X.
        </para>
        <para>
        Once you found an unused vt, update the com1: section of your
        configuration file:
        <screen>
com1: enabled=1, mode=term, dev=/dev/tty9
        </screen>
        The number must be set according to the terminal you want to use (here 9).
        </para>
        <para>
        Now, launch dlxlinux. After you log in as root and kill gpm, 
        enter the following command:
        <screen>
dlx:~# /sbin/agetty 38400 cua0
        </screen>
        If you switch to vt9, you can see dlx welcome banner, and the login prompt:
<screen>
Welcome to DLX V1.0 (C) 1995-96 Erich Boehm
                    (C) 1995    Hannes Boehm


dlx login: 
</screen>
        Note that dlxlinux is configured so you can not login as root from a
        serial port. If you want to login, you have to create a new user first.
        </para>
        <para>
        Also, if you plan to use this feature, the best would be to deactivate
        gpm in /etc/rc.d/rc.local, and add a agetty line in /etc/inittab,
        for example: 
<screen>
T0:1234:respawn:/bin/agetty 38400 cua0
</screen>
        </para>
        </section>
        <section><title>Interactivity : connecting to a pseudo terminal</title>
        <para>
        The third example is very similar to the second one, except that we
        connect to the guest OS with kermit as client, and we the connection
        is done through a pseudo terminal.
        </para>
        <para>
        This example uses /dev/ptyp0 and /dev/ttyp0 as pseudo terminal pair.
        We will tie Bochs to the controlling terminal, whereas kermit will
        use the slave terminal.
        </para>
        <para>
        Update the com1: section of your configuration file:
        <screen>
com1: enabled=1, mode=term, dev=/dev/ptyp0
        </screen>
        and lauch dlxlinux. After you log in as root, enter the command:
        <screen>
dlx:~# /sbin/agetty 38400 cua0
        </screen>
        Then in the host OS, launch kermit :
        <screen>
host$ kermit -l /dev/ttyp0
C-Kermit 7.0.196, 1 Jan 2000, for Linux
 Copyright (C) 1985, 2000,
  Trustees of Columbia University in the City of New York.
Type ? or HELP for help.
(/tmp/) C-Kermit>connect
Connecting to /dev/ttyp0, speed 0.
The escape character is Ctrl-\ (ASCII 28, FS)
Type the escape character followed by C to get back,
or followed by ? to see other options.
----------------------------------------------------

Welcome to DLX V1.0 (C) 1995-96 Erich Boehm
                    (C) 1995    Hannes Boehm


dlx login: 
        </screen>
        The same comments as for example 2 apply here.
        </para>
        </section>
</section>

<section id="bios-tips"> 
<title>BIOS Tips</title>
        <section> 
        <title>Booting from CD-ROMs</title>
        <para>
A bootable CD-ROM has a special layout that is detected by the
BIOS boot loader code, and executed if it conforms the specifications.
This layout is called "El Torito Bootable CD-ROM Format Specification"
and has been published by Phoenix and IBM. A copy of this spec is on
<ulink url="http://bochs.sourceforge.net/techdata.html">Bochs tech specs page</ulink>.
        </para>
        <para>
El Torito specifies 3 ways to have a bootable CD:
<itemizedlist>
<listitem>
<para>floppy emulation boot: A standard floppy image is burnt on the CD.
In this case the BIOS has to redirect all first floppy accesses to this
image and the real floppy drive becomes the second one.
</para></listitem>
<listitem><para>
a "no emulation" boot: In this case the BIOS is instructed to load an
arbitrary number of sectors straight into memory, and execute it.
</para></listitem>
<listitem><para>
hard disk emulation: A hard disk image is burnt on the CD. The
BIOS has to redirect all hard disk accesses to that image. The real hard disks
are still available, with BIOS numbers 81h and up.
</para></listitem>
</itemizedlist>

In Bochs 2.0, hard disk emulation is not implemented in the BIOS.
There are also subtilities about multiple boot-images CD-ROMs, that are
not handled by Bochs.
        </para>

        <para>
However, our BIOS may be more strict than real PC BIOSes, I don't know.
But I would definitely be interested to know of any CD that can boot
on real hardware, but does not in Bochs.
        </para>

        <para>
When failing to boot from CD-ROM, the BIOS outputs
the reason of the failure as
an error code, in the log file, and on the screen.
        </para>

        <para>
Here is a summary of what can happen when booting from the CD.
        </para>

<table><title>CD Boot error codes</title>

<tgroup cols="2" align="left" colsep="1" rowsep="1">
<thead>
 <row>
 <entry>Error code</entry>
 <entry>Reason</entry>
 </row>
</thead>
<tbody>
<row> <entry> 0x01 </entry> <entry> no atapi device found </entry> </row>
<row> <entry> 0x02 </entry> <entry> no atapi cdrom found </entry> </row>
<row> <entry> 0x03 </entry> <entry> can not read cd - BRVD </entry> </row>
<row> <entry> 0x04 </entry> <entry> cd is not eltorito (BRVD) </entry> </row>
<row> <entry> 0x05 </entry> <entry> cd is not eltorito (ISO TAG) </entry> </row>
<row> <entry> 0x06 </entry> <entry> cd is not eltorito (ELTORITO TAG) </entry> </row>
<row> <entry> 0x07 </entry> <entry> can not read cd - boot catalog </entry> </row>
<row> <entry> 0x08 </entry> <entry> boot catalog : bad header </entry> </row>
<row> <entry> 0x09 </entry> <entry> boot catalog : bad platform </entry> </row>
<row> <entry> 0x0A </entry> <entry> boot catalog : bad signature </entry> </row>
<row> <entry> 0x0B </entry> <entry> boot catalog : bootable flag not set </entry> </row>
<row> <entry> 0x0C </entry> <entry> can not read cd - boot image </entry> </row>
</tbody>
</tgroup>
</table>

<para>
<screen>
0x01 no atapi device found
0x02 no atapi cdrom found
</screen>

For the first two errors, an ata-*: type=cdrom is probably missing
from the configuration file. This is what you get if no cdrom has
been defined in Bochs conf file.
</para>

<para>
<screen>
0x03 can not read cd - BRVD
</screen>

For this error, the cdrom support has not been compiled in Bochs, 
or Bochs could not open the file or device. This is what you get if
Bochs is not able to read the cd.
</para>

<para>
<screen>
0x04 cd is not eltorito (BRVD)
0x05 cd is not eltorito (ISO TAG)
0x06 cd is not eltorito (ELTORITO TAG)
</screen>

For these errors, the data has been read from the cd, but
the cd does not conform to the El Torito specification. This
is what you get if the cd is not bootable.
</para>

<para>
<screen>
0x08 boot catalog : bad header
0x09 boot catalog : bad platform
0x0A boot catalog : bad signature
0x0B boot catalog : bootable flag not set
</screen>

now the cd is eltorito, but the boot catalog is currupt, or
the cd was made to boot on a ppc system. This should not happen
for a x86 bootable cd.
</para>

<para>
<screen>
0x07 can not read cd - boot catalog
0x0C can not read cd - boot image
</screen>
here, specific part of the cd could not be read. This should
definitely not happen.
</para>
        </section>

        <section id="bios-disk-translation"> 
        <title>Disk translation</title>
        <para>
Since the beginning of the PC era, disks have grown in size by a factor of 10000. Due to 
differences between the ATA specification and BIOSes implementations, when disks reached
critical sizes, it
became necessary to translate the CHS geometry (cylinders, heads, sectors per track)
between the BIOS (int 13h) and the ATA interface. Please refer to the 
<ulink url="http://burks.brighton.ac.uk/burks/pcinfo/hardware/atafaq/atafq.htm">ATA-FAQ</ulink> 
and 
<ulink url="http://www.ata-atapi.com/hiwchs.htm">Hale Landis' document</ulink> 
for a complete discussion of the problem.
        </para>
        <para>
Unfortunately, there has never been any standard on the translation algorithms. 
        </para>
        <para>
Bochs implements 4 well-known algorithms, selectable in the configuration file
in the "<command>ataX-xxxx: ..., translation='algorithm'</command>" section.
        </para>

<table><title>Disk translation algorithms</title>
<tgroup cols="4" align="left" colsep="1" rowsep="1">
<thead>
  <row>
    <entry>Algorithm</entry>
    <entry>Maximum disk size</entry>
    <entry>Maximum logical and physical geometry (CHS)</entry>
    <entry>Description</entry>
  </row>
</thead>
<tbody>
  <row>
    <entry>none</entry>
    <entry>528MB (1032192 sectors)</entry>
    <entry>
    LCHS:1024/16/63
    PCHS:1024/16/63
    </entry>
    <entry>
    no translation is done. The CHS received at the int13h interface 
    is sent as is to the ATA interface. 
    </entry>
  </row>
  <row>
    <entry>large</entry>
    <entry>4.2GB (8257536 sectors)</entry>
    <entry>
    LCHS:1024/128/63
    PCHS:8192/16/63
    </entry>
    <entry>
    a standard bitshift algorithm (named Extended-CHS)
    is used to translate the CHS between 
    the int13h interface 
    and the ATA interface. The translation is acheived by 
    multiplying/dividing the cylinder/head count by a power of 2
    (2, 4 or 8).
    (a factor of 16 could not be used because the
    head count would become 256, and MS-DOS thought this was 0)
    Note that the number of sectors per track is not changed, so
    a lower spt value will lead to a lower maximum disk size.
    </entry>
  </row>
  <row>
    <entry>echs</entry>
    <entry> </entry>
    <entry> </entry>
    <entry>synonym for large</entry>
  </row>
  <row>
    <entry>rechs</entry>
    <entry>7.9GB (15482880 sectors)</entry>
    <entry>
    LCHS:1024/240/63
    PCHS:15360/16/63
    </entry>
    <entry>
    a revised bitshift algorithm (called Revised Extended-CHS)
    is used to translate the CHS between 
    the int13h interface 
    and the ATA interface. First the number of physical heads is forced to
    15, and the number of cylinders is adjusted accordingly.
    Then, as in the simple extended CHS algorithm, the translation 
    is acheived by 
    multiplying/dividing the cylinder/head count by a power of 2
    (2, 4, 8 or 16).
    The head count being forced to 15, it can safely be multiplied by 16 
    without crashing dos.
    Note that the number of sectors per track is not changed, so
    a lower spt value will lead to a lower maximum disk size.
    </entry>
  </row>
  <row>
    <entry>lba</entry>
    <entry>8.4GB (16450560 sectors)</entry>
    <entry>
    LCHS:1024/255/63
    PCHS:16320/16/63
    </entry>
    <entry>
    a LBA-assisted algorithm
    is used to translate the CHS between 
    the int13h interface 
    and the ATA interface. The translation is acheived by 
    first computing the physical size of the disk (LBA=C*H*S).
    Then the sectors per track is forced to 63, and the head count
    to 255. Then the cylinder count is computed (C=LBA/(63*255))
    Note that the number of sectors per track is forced to 63
    in the logical geometry, regardless of the actual geometry
    reported by the disk.
    Also note that the LBA-assisted algorithm has nothing to do with
    LBA access at the ATA interface.
    </entry>
  </row>
  <row>
    <entry>auto</entry>
    <entry> </entry>
    <entry> </entry>
    <entry>the best suited algorithm between none, large and lba is used</entry>
  </row>
</tbody>
</tgroup>
</table>

        <para>
Setting a specific CHS translation should be done if you use a disk dump
of an actual disk, or use a real disk as a block device. You need to
know which geometry was used to format the disk, and which translation 
was used. You must not set the translation to 'auto'.
        </para>

        <note>
        <para>
rechs translation should only be useful for compaq users who wants to
use a disk as a block device. Please report if you know any other
system that use such translation.
        </para>
        </note>

        <para>
If you plan to create a new disk image (for example with bximage),
format it and install an OS on it, select the "auto" translation
for an automatic selection
of the best algorithm based on the disk image size. Be warned that an image created
with the "auto" translation might not be readable with previous versions of Bochs.
Upward compatibility will be maintained.
        </para>

<note>
<para>
This translation applies only to int13h BIOS disk accesses. Older OSes (e.g. MS-DOS)
tend to use them a lot.  On modern OSes, disk accesses through BIOS int13h are 
limited to boot loaders.
The usual rules and tricks of the installed OS still apply (ie 1024 cylinders boot limit).
</para>
</note>

        </section>
</section>

<section id="enter-special-keys"><title>How to enter special key combination</title>
<para>
Your window manager may trap the key combination you want to enter
in Bochs guest OS, for example <keycombo action="simul"><keycap>control</keycap><keycap>alt</keycap><keycap>delete</keycap></keycombo>. Here is a work-around:
</para>
<para>
Press and hold <keycombo action="simul"><keycap>control</keycap><keycap>alt</keycap></keycombo>,
move your mouse cursor outside of the Bochs window.  Release them, move
the cursor back in the Bochs window and press <keycap>delete</keycap>.
</para>
<para>
This should work for any key combination.
</para>
<para>
If you need one key combination frequently, set it up as <link linkend="bochsopt-user-shortcut">user key combination</link>
in your configuration file.  This key combination is sent to the guest OS
when you press the user button in the <link linkend="headerbar">headerbar</link>.
Depending on the used <link linkend="bochsopt-displaylibrary">display_library option</link>,
it may even be possible to edit the shortcut before sending it.
</para>
</section>

<section id="vesa-notes">
  <title>Notes about VESA usage</title>

  <para>
    Since Bochs 1.4 it is possible to use VESA graphics. There are some limitations in
    the current implementation, but in general it should work ok (we have run several test
    programs, the XFree86 VESA display driver, etc.)
  </para>

  <para>
    In order to use VESA VBE, you need to compile Bochs using the <option>--enable-vbe</option>
    option and enable it in your <filename>bochsrc</filename> by setting the
    <link linkend="bochsopt-vga">vga option</link> to <parameter>vbe</parameter>.
    Finally, you need to use the
    <ulink url="http://savannah.nongnu.org/projects/vgabios/">LGPL'd VGABIOS</ulink>
    as <link linkend="bochsopt-vgaromimage">vgaromimage option</link> for
    applications to correctly detect VESA support.
  </para>

  <note><para>
    The VGABIOS is already included in the Bochs release, so no separate download is necessary.
  </para></note>

  <note><para>
    To take advantage of the VBE, you must tell Bochs to use the LGPL'd VGA BIOS
    version 0.4c or higher. A current version of the VGA BIOS will work.
  </para></note>

<para>
Current limitations:
<itemizedlist>
	<listitem> <para> 4bpp modes support is incomplete (8, 15, 16, 24 and 32bpp should work)</para> </listitem>
	<listitem> <para> banked mode is very slow (if you can, just use Linear Frame Buffering instead!) </para> </listitem>
	<listitem> <para> only 320x200, 640x400, 640x480, 800x600, 1024x768 are currently supported</para> </listitem>
</itemizedlist>
</para>

<para>
Interesting Facts:
<itemizedlist>
	<listitem> <para> You need a display driver capable of using the VESA BIOS for this to work 
	                  (a recent XFree86 will do, Windows 9x/NT/2K/XP probably will not work 'out of the box'. </para> </listitem>
	<listitem> <para> Currently the VBE2 extension should be supported ok </para> </listitem>
</itemizedlist>
</para>

<section><title>Instructions to setup Bochs VBE in Windows Guest OS</title>
<para>This was contributed by Martin Bochnig in February 2004.</para>
<screen>
Instructions for Win95/98:
==========================
I can only confirm that SciTech finally made a VBE driver
for Windows. It works out of the box, at least with win95
as guest OS, provided you use Bochs 2.1 with the LGPL 
vgabios.

Here is how I did it :
- install win95 with the vga driver.
- download sdd 7 beta from <ulink url="http://www.majorgeeks.com/download382.html"></ulink>
- download pmhelp.vxd from <ulink url="http://unununium.org/viewcvs/snap/redist/release/pmhelp.vxd"></ulink>
- copy pmhelp.vxd to the win95 system directory
- install sdd7

800x600 and 1024x768 in 16 and 24 bpp modes here.
I did not try 32bpp.

</screen>
<para>This was contributed by Stanislav Shwartsman in September 2004.</para>
<screen>
Instructions for Win2000/XP:
============================

Bochs VBE Display Drivers for Windows NT/2000
<ulink url="http://dhenriq.en.eresmas.com/"></ulink>
</screen>
</section>
</section>

<section id="cirrus-notes">
  <title>Notes about Cirrus SVGA usage</title>

  <para>
    Since Bochs 2.2 it is possible to use Cirrus SVGA graphics. The Cirrus device
    supports both ISA and PCI depending on the <filename>bochsrc</filename> settings.
    If PCI is disabled or the Cirrus card is not assigned to a PCI slot, it appears
    as a CL-GD5430 ISA with 2MB VRAM. If you assign the Cirrus card to a PCI slot,
    it appears as a CL-GD5446 PCI with 4MB VRAM.
  </para>
  <para>
    In order to use Cirrus SVGA, you need to compile Bochs using the <option>--enable-clgd54xx</option>
    option and enable it in your <filename>bochsrc</filename> by setting the
    <link linkend="bochsopt-vga">vga option</link> to <parameter>cirrus</parameter>.
    Finally, you need to use the Cirrus version of the
    <ulink url="http://savannah.nongnu.org/projects/vgabios/">LGPL'd VGABIOS</ulink>
    as <link linkend="bochsopt-vgaromimage">vgaromimage option</link> for
    applications to correctly detect Cirrus support.
  </para>
  <screen>
  # Enable CL-GD5446 PCI
  vga: extension=cirrus
  vgaromimage: file=$BXSHARE/VGABIOS-lgpl-latest-cirrus
  i440fxsupport: enabled=1, slot1=cirrus
  </screen>

  <note><para>
    The VGABIOS is already included in the Bochs release, so no separate download is necessary.
  </para></note>
</section>

<section id="harddisk-modes"><title>Disk Image Modes</title>
<para>
Bochs can handle independent disk image format for each
disk present on the ata interfaces. 

The disk image type is selected in the configuration file 
by the "mode" option of the ataX-xxx directives. 
Example:

<screen>
ata0-master: type=disk, mode=flat, path=10M.sample, cylinders=306, heads=4, spt=17
</screen>
</para>

<note>
<para>
If unspecified, the default "mode" is flat. 
</para>
</note>

<para>
<table><title>Supported Disk Modes</title>
<tgroup cols="3" align="left" colsep="1" rowsep="1">
<thead>
 <row>
  <entry>Name</entry>
  <entry>Description</entry>
  <entry>Features</entry>
 </row>
</thead>
<tbody>
 <row> <entry> flat </entry> <entry> one file, flat layout </entry> 
       <entry> 
       accessible with mtools or winimage-like tools
       </entry>
 </row>
 <row> <entry> concat </entry> <entry> multiple files, concatenated </entry> 
       <entry> 
       mappable to contained partitions
       </entry>
 </row>
 <row> <entry> external </entry> <entry> accessed through an external C++ class </entry> 
       <entry> 
       developer specific, needs a C++ class at compile time
       </entry>
 </row>
 <row> <entry> dll </entry> <entry> accessed through a DLL </entry> 
       <entry> 
       developer specific, windows only
       </entry>
 </row>
 <row> <entry> sparse </entry> <entry> up to 10 layers stackable files </entry> 
       <entry> 
       commitable, rollbackable, growing
       </entry>
 </row>
 <row> <entry> vmware3 </entry> <entry> vmware3 disk support </entry> 
       <entry> 
       vmware3 compatibility
       </entry>
 </row>
 <row> <entry> undoable </entry> <entry> flat file with a commitable redolog </entry> 
       <entry> 
       commitable, rollbackable
       </entry>
 </row>
 <row> <entry> growing </entry> <entry>  one growing file </entry> 
       <entry> growing
       </entry>
 </row>
 <row> <entry> volatile </entry> <entry> flat file with a volatile redolog </entry> 
       <entry> 
       always rollbacked
       </entry>
 </row>
</tbody>
</tgroup>
</table>
</para>

<!--
<note>
<para>
z-undoable and z-volatile modes are only available if the "- -enable-compressed-hd" parameter
was set at compile time.
</para>
</note>
-->

<section id="harddisk-mode-flat"><title>flat</title>
<para>
</para>
<section><title>description</title>
<para>
In flat mode, all sectors of the harddisk are stored in one flat file,
in lba order. 
</para>
</section>
<section><title>image creation</title>
<para>
Flat disk images can be created with the bximage utility
(see <xref linkend="using-bximage"> for more information).
</para>
</section>
<section><title>path</title>
<para>
The "path" option of the ataX-xxx directive in the configuration file
must point to the flat image file.
</para>
</section>
<section id="harddisk-mode-flat-tools"><title>external tools</title>
<para>
Flat images content can be accessed from the host by the
following tools :
<itemizedlist>
<listitem> <para> mtools (see <xref linkend="mtools">)</para> </listitem>
<listitem> <para> mount with a loopback (see <xref linkend="loop-device-usage">) </para> </listitem>
<listitem> <para> Winimage / DiskExplorer (see <xref linkend="winimage">) </para> </listitem>
<listitem> <para> Bochs Tools (see <xref linkend="bochs-linux-disktools">) </para> </listitem>
</itemizedlist>
</para>
</section>
<section><title>typical use</title>
<para>
Flat mode is Bochs default harddisk layout. This is also
the layout of disk images provided on Bochs websites.
</para>
</section>
<section><title>limitations</title>
<para>
On some host OSes, Bochs flat disk images are limited to 2GiB.
</para>
</section>
</section>


<section><title>concat</title>
<para>
</para>
<section><title>description</title>
<para>
In concat mode, all sectors of the harddisk are stored in several flat files,
in lba order. 
</para>
</section>
<section><title>image creation</title>
<para>
Disk images for the usage in 'concat' mode can be created with the bximage
utility (see <xref linkend="using-bximage"> for more information).
</para>
</section>
<section><title>path</title>
<para>
The "path" option of the ataX-xxx directive in the configuration file
must point to the first file (e.g. win95-1). The lower layer files names are
found by adding 1 to the last character (e.g. win95-2, win95-3, etc.).
</para>
</section>
<section><title>external tools</title>
<para>
If every single file contains a complete partition, they can be accessed
with same tools as the 'flat' mode images.
</para>
</section>
<section><title>typical use</title>
<para>
If the partition sizes and file sizes are set up correctly, this allows you to
store each partition in a separate file, which is very convenient if you want
to operate on a single partition (e.g. mount with loopback, create filesystem,
fsck, etc.).
</para>
</section>
<section><title>limitations</title>
<para>
On some host OSes, there is a limit of 2GiB per file.
</para>
</section>
</section>

<section><title>external/dll</title>
<para>
</para>
<section><title>description</title>
<para>
This mode is only useful for developers and needs an additional C++ class
compiled in, or an additional DLL linked to Bochs.
</para>
</section>
</section>

<section><title>sparse</title>
<para>
</para>
<section><title>description</title>
<para>
    Sparse disk support has been added by JustinSB. Sparse disk features are:
    <itemizedlist>
      <listitem>
        <para>
        Large hard drive can be created, and only used space will be stored
        in the file.  In practice, on Unix, this is not a large gain as it is
        done anyway.
        </para>
      </listitem>
      <listitem>
        <para>
        Multiple sparse drive images can be mounted on top of each other.
        Writes go to the top image.  This allows several similar configurations
        to share a master "base" file, and also allows filesystem rollback or
        no-write options.  Up to 10 disk images can be layered on top of each other.
        </para>
      </listitem>
    </itemizedlist>
</para>
</section>
<section><title>image creation</title>
<para>
Sparse disk images must be created with the bximage utility
(see <xref linkend="using-bximage"> for more information).
Be sure to enter "sparse" when selecting the image type.
</para>
</section>
<section><title>path</title>
<para>
The "path" option of the ataX-xxx directive in the configuration file
must point to the top layered file. The lower layer files names are found by
substracting 1 from the last character (must be a digit)
</para>
</section>
<section><title>external tools</title>
<para>
No external tool support Sparse disk images yet.
</para>
</section>
<section><title>typical use</title>
  <section>
  <title>Space Saving</title>
  <para>
    Create a sparse disk image using bximage.  Set size to eg 10GB.  
    Only allocated space will be stored,
    so your drive image should be only about as large as the files stored on it.
  </para>
  </section>

  <section>
  <title>Disk Rollback</title>
  <para>
    <itemizedlist>
      <listitem>
        <para>
          Create a sparse disk image called "c.img.0".  Point .bochsrc at "c.img.0".
          In bochs, install your favourite OS.  Switch off bochs.
        </para>
      </listitem>
      <listitem>
        <para>
          Create a sparse disk image (of the same size) 
          and name it "c.img.1".  Point .bochsrc at "c.img.1"
          "c.img.0" is visible, but all writes go to "c.img.1".  
          After using bochs, you can simply delete
          "c.img.1" to undo changes and go back to a clean OS install.
        </para>
      </listitem>
    </itemizedlist>
  </para>
  </section>

  <section>
  <title>Disk Optional Commit</title>
  <para>
    <itemizedlist>
      <listitem>
        <para>
          Create a sparse disk image called "c.img.0".  Point .bochsrc at "c.img.0".
          In bochs, install your favourite OS.  Switch off bochs.
        </para>
      </listitem>
      <listitem>
        <para>
          Create a sparse disk image (of the same size) and name it "c.img.1".  
          Point .bochsrc at "c.img.1"
          "c.img.0" is visible, but all writes go to "c.img.1".  
          After using bochs, if you want to keep the
          changes, use the (currently non-existant) merge utility 
          to make a single unified drive image.
        </para>
      </listitem>
      <listitem>
        <para>
          Alternatively simply create a new partition on top called "c.img.2".
        </para>
      </listitem>
    </itemizedlist>
  </para>
  </section>

  <section>
  <title>Common Base</title>
    <itemizedlist>
      <listitem>
        <para>
          Create a sparse disk image called "base.img".  Point .bochsrc at "base.img".
          In bochs, install your favourite OS.  Switch off bochs.
        </para>
      </listitem>
      <listitem>
        <para>
          Create a sparse disk image (of the same size) and name it "www.img.1".  
          Make "wwww.img.0" a symlink to
          "base.img".  Point .bochsrc at "www.img.1". Using bochs, install a webserver.
        </para>
      </listitem>
      <listitem>
        <para>
          Create a symlink to "base.img" called "db.img.0".  
          Create a sparse disk image (of the same size)
          and name it "db.img.1".  Point .bochsrc at "db.img.1".  
          Using bochs, install a database server.
        </para>
      </listitem>
    </itemizedlist>

    <para>
     Now both a database server and webserver can be 
     run in separate virtual machines, but they share the common OS image, 
     saving drive space.
    </para>
  </section>

</section>
<section><title>limitations</title>
<para>
  There is a need for supporting utilities (yet unwritten) :
  <itemizedlist>
    <listitem>
    <para>to merge two sparse disk images into a single image </para>
    </listitem>
    <listitem>
    <para>to defragment a sparse disk image and remove unused space </para>
    </listitem>
  </itemizedlist>
</para>
</section>
</section>

<section><title>vmware3</title>
<para>
</para>
<section><title>description</title>
<para>
Sharvil Nanavati has added vmware3 disk image support into Bochs
for Net Integration Technologies, Inc. 
You should be able to use disk images created by vmware3.
</para>
</section>
<section><title>image creation</title>
<para>
Create such disk image with vmware3.
</para>
</section>
<section><title>path</title>
<para>
The "path" option of the ataX-xxx directive in the configuration file
must point to the vmware3 disk image.
</para>
</section>
<section><title>external tools</title>
<para>
&FIXME; give a look at vmware3 tools : disk image creation, etc.
</para>
</section>
<section><title>typical use</title>
<para>
If you want to use an existing vmware3 disk image.
</para>
</section>
<section><title>limitations</title>
<para>
Only vmware version 3 disk image files are supported.
</para>
</section>
</section>

<section><title>undoable</title>
<para>
</para>
<section><title>description</title>
<para>
    Undoable disks are commitable/rollbackable disk images. 
    An undoable disk is based on a read-only flat image
    (see <xref linkend="harddisk-mode-flat">), associated with 
    a growing redolog, that contains all changes (writes)
    made to the flat image content. 
</para>
<para>
    This redolog is dynamically created at runtime, if it does not
    previously exists.
</para>
<para>
    All writes go to the redolog, reads are done from the 
    redolog if previously written, or from the flat file
    otherwise.
</para>
<para>
    If unspecified with the "journal" option of the ataX-xxx directive,
    the redolog file name is created by adding a ".redolog" 
    suffix to the flat image name.
</para>
<para>
    File size of the redolog can grow up to the total disk
    size plus a small overhead due to internal data managment
    (about 3% for a 32MiB disk, 
    less than 0.5% for a 2GiB disk).
</para>
<para>
    After a run, the redolog will still be present, so the changes 
    are still visible the next time you run Bochs with this disk image.
</para>
<para>
    After a run, the redolog can be committed (merged) 
    to the flat image with the bxcommit utility.
</para>
<para>
    After a run, the redolog can be rollbacked (discarded) 
    by simply deleting the redolog file.
</para>
<note>
<para>
    In this mode, the flat file is always open in read-only mode,
    so it can safely be stored on a read-only medium (for example on a cdrom).
</para>
</note>
</section>
<section><title>image creation</title>
<para>
The flat disk images must be created with the bximage utility
(see <xref linkend="using-bximage"> for more information).
    The growing redolog is created automatically if needed.
</para>
</section>
<section><title>path</title>
<para>
    The "path" option of the ataX-xxx directive in the configuration file
    must be the flat image name. The redolog name can be set with the "journal"
    option of the same directive.
    If not set, the redolog name is created by adding the
    ".redolog" suffix to the flat image name.
</para>
</section>
<section><title>external tools</title>
<para>
    See <xref linkend="harddisk-mode-flat-tools"> for tools
    to access the flat disk image content.
</para>
<note>
<para>
    The up-to-date content can only be seen after you commit the redolog
    to the flat file with the bxcommit utility.
</para>
</note>
</section>
<section><title>typical use</title>
<para>
&FIXME; to be completed
</para>
<section><title>Commit</title>
<para>
&FIXME; to be completed
</para>
</section>
<section><title>Rollback</title>
<para>
&FIXME; to be completed
</para>
</section>
<section><title>Common Base</title>
<para>
&FIXME; to be completed
</para>
</section>
<section><title>Harddisk Image on a Read-Only Medium</title>
<para>
&FIXME; to be completed
</para>
</section>
</section>
<section><title>limitations</title>
<para>
&FIXME; to be completed
</para>
</section>
</section>

<section><title>growing</title>
<para>
</para>
<section><title>description</title>
    <para>
    Growing disk images start as a small files, and 
    grow whenever new data is written to them. 
    </para>
    <para>
    Once a sector is 
    written in the growing file, subsequent writes to the same
    sector will happen in place.
    </para>
    <para>
    File size of Growing disk images can go up to the total disk
    size plus a small overhead due to internal data managment.
    (about 3% for a 32MiB disk, 
    less than 0.5% for a 2GiB disk).
    </para>
</section>
<section><title>image creation</title>
<para>
Growing disk images must be created with the bximage utility
(see <xref linkend="using-bximage"> for more information).
Be sure to enter "growing" when selecting the image type.
</para>
</section>
<section><title>path</title>
<para>
    The "path" option of the ataX-xxx directive in the configuration file
    must be the growing image name. 
</para>
</section>
<section><title>external tools</title>
<para>
No external tool support Growing disk images yet.
</para>
</section>
<section><title>typical use</title>
<para>
Growing disk images can be used whenever you want to maximize disk space. 
However, please note that Bochs will not check if enough disk space is available
before writing new data. If no disk space is available, a panic will occur.
</para>
</section>
<section><title>limitations</title>
<para>
&FIXME; to be completed
</para>
</section>
</section>

<section><title>volatile</title>
<para>
</para>
<section><title>description</title>
<para>
    Volatile disks are always-rollbacked disk images. 
    An volatile disk is based on a read-only flat image
    (see <xref linkend="harddisk-mode-flat">), associated with 
    a growing temporary redolog, that contains all changes (writes)
    made to the flat image content. All data written to
    the  disk image are lost at the end of the Bochs
    session.
</para>
<para>
    The redolog is dynamically created at runtime, when
    Bochs starts, and is deleted when Bochs closes (win32)
    or just after it has been created (Unix).
</para>
<para>
    All writes go to the redolog, reads are done from the 
    redolog if previously written, or from the flat file
    otherwise.
</para>
<para>
    If unspecified with the "journal" option of the ataX-xxx directive,
    the redolog file name is created by adding a ".redolog" 
    suffix to the flat image name.
</para>
<para>
    File size of the redolog can grow up to the total disk
    size plus a small overhead due to internal data managment
    (about 3% for a 32MiB disk, 
    less than 0.5% for a 2GiB disk).
</para>
<para>
    After a run, the redolog is not any more present, so the changes 
    are discarded.
</para>
<note>
<para>
    In this mode, the flat file is always open in read-only mode,
    so it can safely be stored on a read-only medium (for example on a cdrom).
</para>
</note>
</section>
<section><title>image creation</title>
<para>
The flat disk images must be created with the bximage utility
(see <xref linkend="using-bximage"> for more information).
    The growing redolog is created automatically.
</para>
</section>
<section><title>path</title>
<para>
    The "path" option of the ataX-xxx directive in the configuration file
    must be the flat image name. The redolog name can be set with the "journal"
    option of the same directive.
    If not set, the redolog name is created by adding the
    ".redolog" suffix to the flat image name.
    A random suffix is also appended to the redolog name.
</para>
</section>
<section><title>external tools</title>
<para>
    See <xref linkend="harddisk-mode-flat-tools"> for tools
    to access the flat disk image content.
</para>
</section>
<section><title>typical use</title>
<para>
&FIXME; can be completed
</para>
<section><title>Repeatable simulations</title>
<para>
&FIXME; to be completed
</para>
</section>
<section><title>Multiple Bochs instances</title>
<para>
&FIXME; to be completed
</para>
</section>
<section><title>Harddisk Image on a Read-Only Medium</title>
<para>
&FIXME; to be completed
</para>
</section>
</section>
<section><title>limitations</title>
<para>
&FIXME; to be completed
</para>
</section>
</section>

<!--
<section><title>generic</title>
<para>
</para>
<section><title>description</title>
<para>
</para>
</section>
<section><title>image creation</title>
<para>
</para>
</section>
<section><title>path</title>
<para>
</para>
</section>
<section><title>external tools</title>
<para>
</para>
</section>
<section><title>typical use</title>
<para>
</para>
</section>
<section><title>limitations</title>
<para>
</para>
</section>
</section>
-->

<!--
<section><title>z-undoable</title>
<para>
</para>
<section><title>description</title>
<para>
</para>
</section>
<section><title>image creation</title>
<para>
</para>
</section>
<section><title>path</title>
<para>
</para>
</section>
<section><title>external tools</title>
<para>
</para>
</section>
<section><title>typical use</title>
<para>
</para>
</section>
<section><title>limitations</title>
<para>
</para>
</section>
</section>

<section><title>z-volatile</title>
<para>
</para>
<section><title>description</title>
<para>
</para>
</section>
<section><title>image creation</title>
<para>
</para>
</section>
<section><title>path</title>
<para>
</para>
</section>
<section><title>external tools</title>
<para>
</para>
</section>
<section><title>typical use</title>
<para>
</para>
</section>
<section><title>limitations</title>
<para>
</para>
</section>
</section>
-->

</section>

<section id="using-bximage"><title>Using the bximage tool</title>
<para>
Bximage is an easy to use console based tool for creating disk images,
particularly for use with Bochs. It is completely  interactive if no command
line arguments are used. It can be switched to a non-interactive mode if all
required parameters are given in the command line.
</para>
<para>
When you run bximage without one of the following options,
it will  appear  in  interactive  mode and  ask   for  all
required parameters to create an image.
<screen>
-fd        Create a floppy image.
-hd        Create a hard disk image.
-mode=...  Image mode (for hard disks only - see the bochsrc sample for
           supported options).
-size=...  Image size in megabytes (e.g. 1.44 for floppy image, 10 for hard
           disk image).
-q         Quiet  mode (don't prompt for user input). Without this option bximage
           uses the command line parameters as defaults for the interactive mode.
           If this option is given and one of the required parameters is missing,
           bximage will fall back to interactive mode.
--help     Print  a  summary  of  the command line options for bximage and exit.

The filename parameter specifies the name of the image to be created.
</screen>
</para>
<para>
For an example of the usage, refer to <xref linkend="diskimagehowto">.
</para>
</section>

<section id="using-bxcommit"><title>Using the bxcommit tool</title>
<para>
This tool can commit redologs into flat images. 
</para>
<para>
For now, only "undoable" redologs to flat image commits are supported. 
<!--
"z-undoable" redologs can also be used, but you have to manually 
decompress the gzipped flat file before using bxcommit.
-->
Sparse disk image commits may be added in the future. 
</para>
<para>
This tool is completely interactive, and does not need any command line parameter.
Bxcommit asks for the flat image name, the redolog name, and whether to remove
to redolog file after it commits it.
</para>
<para>
Session example :
<screen>
$ ./bxcommit 
========================================================================
                               bxcommit
              Undoable Disk Image Commit Tool for Bochs
========================================================================

What is the flat image name?
[c.img] myfile.img

What is the redolog name?
[myfile.img.redolog] toapply.redolog

Shall I remove the redolog afterwards?
[yes] 
</screen>
</para>
</section>

</chapter>



<chapter id="guests"><title>Guest operating systems</title>
<para>
<screen>
What disk images are available.
Installing from scratch.
What works
Known problems
</screen>
</para>

<section id="guest-linux"><title>Linux</title>
  <para>
  </para>
</section>

<section id="guest-knoppix">
  <title>Knoppix</title>

  <para>
    Contributed by Alexander Schuch.
  </para>

  <section>
    <title>Getting Knoppix</title>

    <para>
      Knoppix is a live CD (700M) or live DVD (3.2G) based on Debian GNU/Linux, with lots of
      ready-to-run programs (web browser, office suite, a few games, and more), using
      <abbrev>KDE</abbrev> as desktop environment. It can be booted directly from CD, without
      any installation needed. You can download it from <ulink url="http://www.knoppix.org/">knoppix.org</ulink>.
    </para>
  </section>

  <section>
    <title>Preparing Bochs</title>

    <para>
      As Knoppix runs completely from CD/DVD, you don't need to setup a hard disk. You just need to set up
      the location of the downloaded ISO image in your <filename>bochsrc</filename>, and make Bochs boot
      from it. Because Knoppix contains a graphical user interface, and has no other storage space but
      the emulated RAM, it needs at least 128MB of it, see
      <link linkend="bochsopt-megs">megs option</link>. Furthermore, you need to enable VBE support in
      Bochs (see <xref linkend="vesa-notes">).
    </para>
  </section>

  <section>
    <title>Using Knoppix</title>

    <para>
      There is nothing more to do! Just start Bochs and wait for Knoppix to load...
    </para>

    <note><para>
      You are logged in as normal user, if you want to become super user, just <command>su</command>.
      There is no password needed (empty password).
    </para></note>
  </section>
</section>

<section id="guest-minix"><title>Minix</title>
<para>
Please see the <ulink url="http://minix1.hampshire.edu/faq/bxmxhowto.html">Minix on Bochs on Windows How-To</ulink> by Al Woodhull.
</para>
</section>

<section id="guest-openbsd"><title>OpenBSD</title>
  <para>
  </para>
</section>

<section id="guest-freebsd">
<!--
  <sectioninfo>
    <authorgroup>
      <author>
        <firstname>Alexander</firstname>
        <surname>Schuch</surname>
        <contrib>Contributed by </contrib>
      </author>
    </authorgroup>
  </sectioninfo>
-->
  <title>FreeBSD 5.2.1</title>

  <para>
    Contributed by Alexander Schuch.
  </para>

  <para>
    This section describes how to install FreeBSD 5.2.1 (miniinst) inside of Bochs, using an ISO image.
  </para>

  <section>
    <title>Getting FreeBSD</title>

    <para>
      As <filename>5.2.1-RELEASE-i386-miniinst.iso</filename> (240M) is no longer available from
      the FreeBSD FTP server, you might want to ask a (file) search engine of your choice
      for a download location. Once you downloaded the file, you should check its integrity
      using the provided MD5 checksum from the
      <ulink url="http://www.freebsd.org/releases/5.2.1R/announce.html">FreeBSD 5.2.1 release announcement</ulink>.
    </para>
  </section>

  <section>
    <title>Preparing Bochs</title>

    <para>
      Create a new hard disk image using <command>bximage</command> (see
      <xref linkend="using-bximage">) with a size of at least 350M, as the standard
      installation uses 280M on its own.
    </para>

    <para>
      Next, you need to setup your <filename>bochsrc</filename> so that Bochs knows about your
     (still empty) hard disk, as well as about your ISO image. Make Bochs boot from CD-ROM and
     start the emulation.
    </para>
  </section>

  <section>
    <title>Installing FreeBSD</title>

    <para>
      This is just a very short step-by-step installation guide for FreeBSD in Bochs. It
      doesn't explain what you do nor why you do it, it just tells you how to do it.
      For in-deepth information refer to the FreeBSD handbook:
      <ulink url="http://www.freebsd.org/doc/handbook/install.html">Installing FreeBSD</ulink>.
    </para>

    <para>
      FreeBSD boots up and shows a nice (text-mode) boot option screen. Just press
      <keycap>return</keycap> there, that is, use the default option. After loading the
      kernel and needed device drivers, select 'Standard' in the installation menu.
    </para>

    <para>
      A fdisk like partition program is loaded next, where you just press <keycap>A</keycap>
      to use the entire disk, followed by <keycap>Q</keycap> to finish the selection. The next
      dialog asks for the boot manager you want to use. Select 'Standard' and continue.
    </para>

    <para>
      In the Disklabel Editor, you have to setup the layout of your partition. If your (virtual)
      hard disk is large enough, you can press <keycap>A</keycap> for auto-layout. However, you
      need to make sure that the <filename class="directory">/usr</filename> partition is at least
      250M large, or you will end up with a 'disk full' error message during installation. If
      this is not the case, select one partition after another and press <keycap>D</keycap> to
      delete it again. After you deleted all partitions, create two new ones. The first one will
      be a swap partition; press <keycap>C</keycap>, enter '32M' as size and select 'Swap' from
      the dialog. Press <keycap>C</keycap> again, and accept the remaining capacity for your
      filesystem partition. Choose 'FS' as partition type and enter '/' (slash) as mount point.
      Your partition layout is complete now; press <keycap>Q</keycap> to leave the editor.

      <note><para>
        This 'all-in-one' partition layout is not recommended for a FreeBSD installation on a
        real box; use 'auto-layout' or something comparable to that there.
      </para></note>
    </para>

    <para>
      You now can choose what set of programs/files (distribution) you want to install. Take
      'User' (option 8), and select 'No' when asked to install the ports collection. You are
      back in the distribution selection, where you select the first item, called 'Exit'.
      Choose to install from 'CD/DVD' and answer the 'Are you sure?' dialog with 'yes'.
    </para>

    <para>
      Now, while FreeBSD installs, it is a very good time to take a look at the
      <ulink url="http://www.freebsd.org/docs.html">FreeBSD documentation</ulink>, especially
      the <ulink url="http://www.freebsd.org/doc/handbook/index.html">FreeBSD handbook</ulink>
      and the <ulink url="http://www.freebsd.org/doc/faq/index.html">FreeBSD FAQ</ulink>.
    </para>
  </section>

  <section>
    <title>Post-installation configuration</title>

    <para>
      All files are installed on your (virtual) hard disk now, and FreeBSD is ready for getting set
      up. As this is a very basic FreeBSD installation, you just answer 'no' to nearly all questions,
      but the one about your mouse: Answer 'yes' for PS/2 mouse, and choose 'Exit' at mouse configuration.
      The miniinst FreeBSD ISO image contains nearly no binary packages, so don't browse the package
      collection. Then, when asked to create a new user account, answer 'yes' and create a new user
      called 'bochs' (or whatever you like). You might want to use <filename>/bin/csh</filename>
      or <filename>/bin/tcsh</filename> as shell rather than <filename>/bin/sh</filename>. Next,
      you are asked for the super user (root) password. The installation is finished now, there is
      no need to visit the general configuration menu again - answer 'no' to that question. FreeBSD
      will then reboot. Shutdown Bochs, as soon as the (virtual) computer boots.
    </para>
  </section>

  <section>
    <title>Using FreeBSD</title>

    <para>
      Open your <filename>bochsrc</filename> and change the boot sequence, so that Bochs will boot
      from hard disk, rather than from CD-ROM from now on. Start Bochs again and watch the FreeBSD
      boot process.
    </para>

    <para>
      Your keyboard might use the wrong keymap, so login (into FreeBSD) as super user and use
      <command>/stand/sysinstall</command> to start the FreeBSD configuration program. Choose
      'keymap' and select the keymap you want to use.
    </para>

    <para>
      You have successfully installed FreeBSD now. You might want to shutdown FreeBSD using
      <command>shutdown -h now</command>, quit Bochs, and create a backup of your hard disk
      image, before you start playing around.
    </para>
  </section>
</section>

<section id="guest-freedos"><title>FreeDOS Beta 8</title>
<para>
This has been contributed by Volker Ruppert.

<screen>
1. Download FDB8_144.DSK and base1.zip from www.freedos.org
2. Unpack base1.zip to a local directory
3. Create harddisk image with bximage (e.g. c.img with 10 MB)
4. Create floppy image 'base1.img' with bximage
5. Set up mtools.conf to access the new floppy image
6. Copy the installation files from the local directory to the floppy using mcopy

7. Set up Bochs for the FreeDOS installation:

   boot: floppy
   floppya: 1_44=FDB8_144.DSK, status=inserted
   floppyb: 1_44=base1.img, status=inserted
   ata0-master: type=disk, path=c.img, cylinders=20, heads=16, spt=63

8. Unfortunately the format command fails here if it is called from the install
   program. So I chose this way to prepare the main installation:

   a. Start bochs and select 'Clean Boot [4]' in the install menu
   b. Partition the harddisk with fdisk
   c. After the reboot select 'Clean Boot [4]' again
   d. Format the harddisk with 'format c: /s'
   e. Press the reset button to reboot and select 'Mini Install [0]'

7. Follow the instructions of the installation program. The source for the
   installation is 'b:\'. After completing the installation you have to copy
   the config.sys and autoexec.bat from the FreeDOS directory (e.g. C:\FDOS)
   to 'c:\'.

8. Quit Bochs and change the boot drive to 'c'. FreeDOS should boot from harddisk
   without errors.

9. I haven't tried the mouse or cdrom features inside of FreeDOS yet.
</screen>
</para>
</section>

<section id="guest-gnu"><title>GNU (Also known as GNU/Hurd)</title>

<section>
<title>Installing GNU</title>
<para>
This has been contributed by Bruno Bonfils (asyd at debian-fr dot org) 
</para>

<section>
<title>Introduction</title>
<para>
Since I don't have enough computers to dedicate a box to GNU, I'm trying
to do my own harddrive image disk. I thougt there was
some documentation about how to do that. But since I didn't find
anything and I decided to write a small doc. I hope this document will be
useful for some people who wants to try the GNU/Hurd.
</para>
</section>

<section> 
<title>The testing box</title>
<para>
<screen>
Debian (Sid) GNU/Linux 2.4.19 

ii  bochs          1.4.1.no.elpin IA-32 (x86) PC emulator
ii  bochs-x        1.4.1.no.elpin Bochs binary with X interface.
ii  grub           0.92+cvs200209 GRand Unified Bootloader
ii  gcc-i386-gnu   1.7-8          Cheap cross-compiler for GNU/Hurd.
ii  mig-i386-gnu   1.2-1          The GNU distribution of the Mach 3.0 interface
</screen>

If you don't have time and if you trust me, you can download here
<footnote>
<para>
<ulink url="http://plouc.net/~asyd/hurd/hurd.img.gz">My own harddisk Image File (~20Mo)</ulink>
</para>
</footnote>
my own image file. (You don't need to run native-install)
</para>
</section>

<section>
<title> Creating the image</title>

<note>
<para>
In this example, I use a 112 MB image disk, but I think you
can use any size without some problem.
</para>
</note>

<para>
Use createdisk command like this :

<screen>
# createdisk gnu.img 112 

Disk Geometry:
C: 227
H: 16
S: 63
Total size: 117153792 bytes
</screen>
</para>

<para>
Note on a paper or on your memory the disk geometry. Then, use the
losetup command to create a loopback on the whole disk.
<screen>
# losetup /dev/loop1 gnu.img
</screen>
</para>

<para>
Now, call fdisk on /dev/loop1. Go into expert mode, and modify the
disk geometry using the c, h, s commands. Return in normal mode, and
create an unique primary partition which uses the whole disk. Then,
detach the /dev/loop1 using :

<screen># losetup -d /dev/loop1</screen>
</para>
</section>

<section>
<title> Installing GNU</title>

<itemizedlist>
<listitem>
<para> Attach the partition</para>

<para> 
First of all, you need to create a filesystem on the disk. Use the
command losetup and -o &lt;offset&gt; option to attach /dev/loop1 on the first
partition of an image disk. Offset is computed like this :
</para> 

<para> 
offset = sector * block_size (512)

<screen># losetup -o 32256 /dev/loop1 gnu.img</screen>
</para>
</listitem>

<listitem>
<para> Preparing the filesystem</para>

<para>According to the GNU/Hurd Installation Guide
<footnote>
<para>
<ulink url="http://web.walfield.org/papers/hurd-installation-guide/english/hurd-install-guide.html">GNU/Hurd Installation guide</ulink>
</para>
</footnote>
, use mke2fs to create a filesystem.

<screen># mke2fs -o hurd /dev/loop1</screen>

Just mount /dev/loop1 like a typical dev.

<screen># mount /dev/loop1 /mnt/gnu</screen>
</para>
</listitem>

<listitem>
<para> Finish the installation</para>

<para>
Download a GNU archive as indicated in the Hurd Installation Guide, and decompress it in /mnt/gnu.

<screen>
# cd /mnt/gnu
# tar --same-owner -xvzpf ~/gnu-latest.tar.gz
</screen>
</para>
</listitem>

</itemizedlist>
</section>

<section>
<title>Bochs Configuration</title>

<para>
Copy default configuration (<replaceable>/usr/share/doc/bochs/examples/bochsrc.gz</replaceable> on debian) 
on your home directory and edit it with your favorite editor (GNU Emacs, i hope ;).
</para>

<para>For my image file I have the following configuration :

<screen>
romimage: file=/usr/share/bochs/BIOS-bochs-latest, address=0xf0000
megs: 128
vgaromimage: file=/usr/share/bochs/VGABIOS-lgpl-latest
floppya: 1_44=/dev/fd0, status=ejected
ata0-master: type=disk, path="/home/asyd/travail/hurd/gnu.img", cylinders=227, heads=16, spt=63 # edit me
ata0-slave: type=cdrom, path=/dev/cdrom, status=inserted
boot: disk
log: /dev/stdout
panic: action=ask
error: action=report
info: action=report
debug: action=ignore
vga_update_interval: 300000
keyboard_serial_delay: 250
keyboard_paste_delay: 100000
cpu: ips=1000000
mouse: enabled=0
private_colormap: enabled=0
fullscreen: enabled=0
screenmode: name="sample"
ne2k: ioaddr=0x280, irq=9, mac=fe:fd:00:00:00:01, ethmod=tap, ethdev=tap0
keyboard_mapping: enabled=0, map=
keyboard_type: xt
i440fxsupport: enabled=0
</screen>

note most of them are actually in the default Debian example file. If you use
these lines, don't forget to read the Networking section.
</para>
</section>

<section>
<title> Note on GNU Mach</title>

<para>
Remember that the Hurd is not a kernel, it's just a collection of libraries
and programs, so we can't actually boot the Hurd. We boot GNU Mach, and
then launch the base servers.
</para>

<para>
The default GNU Mach which is provided by the default GNU archive 
contains some modules / drivers which are not needed in bochs 
environment. If you use it, you'll probably have some kernel panic 
while booting. Don't be afraid and just say alwayscont.
</para>

<note>
<para>
in my archive, I use a recompiled GNU Mach which contains only the
drivers which are needed (--enable-floppy --enable-ide --enable-kmsg
--enable-ne2000). If you want more informations on how to compile your own
GNU Mach, just send me a mail and I'll add the section in this
document.
</para>
</note>

</section>

<section>
<title> Final Step</title>

<para>
Create a grub floppy disk or use my floppy image 
<footnote>
<para>
Grub Floppy image : (coming soon)
</para>
</footnote>
Adapt your bochsrc
file according to your choice. If you want install Grub on the image disk,
remember to copy stage1, stage2 Grub's files into /mnt/gnu/boot/grub.
</para>
<para>Launch bochs - as root if you want networking (using sudo for example).</para>

<para>If you have stage1 and stage2 file, you can install Grub on the MBR.
<screen>
&lt;grub&gt; root (hd0,0)
&lt;grub&gt; setup (hd0)
</screen>
</para>

<para>Finally, booting GNU mach

<screen>
&lt;grub&gt; root (hd0,0)
&lt;grub&gt; kernel /boot/gnumach.gz root=hd0s1
&lt;grub&gt; module /boot/serverboot.gz
&lt;grub&gt; boot
</screen>

Now, you can read the official GNU/Hurd Installation Guide
<footnote>
<para>
<ulink url="http://web.walfield.org/papers/hurd-installation-guide/english/hurd-install-guide.html">GNU/Hurd Installation guide</ulink>
</para>
</footnote>
.
</para>
</section>

<section>
<title>Networking</title>

<para>
You can try to test networking between the GNU/Linux (host OS) and the GNU/Hurd.
First of all, please read 
<footnote>
<para>
<ulink url="http://www.geocrawler.com/archives/3/11758/2002/3/350/8049674/">new ethertap interface for linux, by Bryce Denney</ulink>
</para>
</footnote>
, I currently have the *same* problem.
<footnote>
<para>
This can be solved by using the tuntap interface (see <xref linkend="config-tuntap">)
</para>
</footnote>
</para>

<para>
Verify your kernel configuration, you need to have :

<screen>
CONFIG_NETLINK_DEV=m
CONFIG_ETHERTAP=m
</screen>

(or y instead or m). Check if /dev/tap0 file exist, else create it
with

<screen>
# mknod /dev/tap0 c 36 16
</screen>

and run this command on the guest os :

<screen>
# ifconfig tap0 192.168.100.1 netmask 255.255.255.0
</screen>

Use ip 196.168.100.10 on the GNU/Hurd and you can ping 192.168.100.1
</para>

</section>

<section>
<title> Thanks</title>

<para>
<itemizedlist>
<listitem> <para> Mmenal</para> </listitem>
<listitem> <para> #hurdfr, #hurd, #bochs channels (Freenode network)</para> </listitem>
<listitem> <para> All people who help me everyday on IRC</para> </listitem>
</itemizedlist>
</para>

<para> Copyright (c) Bruno Bonfils</para>
<para>
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1
or any later version published by the Free Software Foundation.
</para>
</section>

</section> <!-- Installing GNU -->

          </section> <!-- GNU -->

          <section id="guest-dos"><title>DOS</title>
<para>You must read the message regarding software licenses in 
<xref linkend="thirdparty"> before you install or use MS-DOS, OS/2, DR-DOS, or any other DOS as a guest operating system in Bochs.</para>
<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 on
DOS or Windows you just run it; on other platforms you can try using
the unzip command.  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 id="guest-win95">
  <title>Windows 95</title>

  <para>
    You must read the message regarding software licenses in <xref linkend="thirdparty">
    before you install Windows 95 as a guest operating system in Bochs.
  </para>

  <tip><para>
    If you want to use higher screen resolutions than 640x480 with more than 16 colours,
    you should enable the Cirrus video card, see <xref linkend="cirrus-notes">, as Windows 95
    comes with drivers for that video card.
  </para></tip>

<section><title>How to Install Windows 95 with floppies</title>
<para>Using Windows95 for PCs without Windows, 1.44M floppy distribution</para>

<para>Preparing for the install</para>

<para>
Copy the floppies to files on your workstation.  Keep in mind,
they are of 2 formats - 1.44M & 1.680M.  The boot disk and
disk#1 are 1.44M.  The rest of them (disk#2..disk#13) are
1.680M format.  You may need a Linux workstation to do this
part, though it should be possible on others if the OS provides
a way to specify alternate floppy media geometries.
</para>

<programlisting>
  format   tracks   heads  sectors/track
  1.44M:     80       2        18
  1.680M:    80       2        21


+- On linux, you achieve this, via the 'setfdprm' command, and
|  associated parameters in the '/etc/fdprm' file.  Here's an
|  excerpt from that file:
|
|    # /etc/fdprm  -  floppy disk parameter table
|    1440/1440	2880    18   2  80    0 0x1B 0x00 0xCF     0x6C
|    1680/1440	3360	21   2  80    0 0x0C 0x00 0xCF     0x6C # ?????
|
|  To copy the floppies, you would do something like:
|
|    linux-> cp /dev/fd0 win95_boot (after inserting the boot diskette)
|    linux-> cp /dev/fd0 win95_d1   (after inserting disk #1)
|
|  Then switch to the alternate 1.680M geometry:
|
|    linux-> setfdprm -p /dev/fd0 1680/1440
|    linux-> cp /dev/fd0 win95_d2   (after inserting disk #2)
|    linux-> cp /dev/fd0 win95_d3   (after inserting disk #3)
|    ...
|    linux-> cp /dev/fd0 win95_d13  (after inserting disk #13)
|
|  And revert back to the default 1.44M geometry if desired
|
+-   linux-> setfdprm -p /dev/fd0 1440/1440

</programlisting>

<para>
You should end up with something similar to the following listing:
</para>

<programlisting>
  -rw-r--r--   1 user     group    1474560 Oct 31 12:04 win95_boot
  -rw-r--r--   1 user     group    1474560 Jul 15  1997 win95_d1

  -rw-r--r--   1 user     group    1720320 Jul 15  1997 win95_d2
  -rw-r--r--   1 user     group    1720320 Jul 15  1997 win95_d3
  -rw-r--r--   1 user     group    1720320 Jul 15  1997 win95_d4
  -rw-r--r--   1 user     group    1720320 Jul 15  1997 win95_d5
  -rw-r--r--   1 user     group    1720320 Jul 15  1997 win95_d6
  -rw-r--r--   1 user     group    1720320 Jul 15  1997 win95_d7
  -rw-r--r--   1 user     group    1720320 Jul 15  1997 win95_d8
  -rw-r--r--   1 user     group    1720320 Jul 15  1997 win95_d9
  -rw-r--r--   1 user     group    1720320 Jul 15  1997 win95_d10
  -rw-r--r--   1 user     group    1720320 Jul 15  1997 win95_d11
  -rw-r--r--   1 user     group    1720320 Jul 15  1997 win95_d12
  -rw-r--r--   1 user     group    1720320 Jul 15  1997 win95_d13
</programlisting>

<para>
Create a hard disk image file.  For example, for a 62M disk with
the following settings in <filename>bochsrc</filename>:
</para>

<programlisting>
  ata0-master: type=disk, path=62M.img, cylinders=940, heads=8, spt=17

use (940 * 8 * 17 * 512bytes-per-sector = 127840):

  unix-> dd if=/dev/zero of=62M.img bs=512 count=127840
</programlisting>

<para>
Setup your <filename>bochsrc</filename> file. For example:
</para>

<programlisting>
  megs: 16
  boot: disk
  ata0-master: type=disk, path=62M.img, cylinders=940, heads=8, spt=17
  floppya: 1_44=1.44, status=inserted
  vgaromimage: file=bios/VGABIOS-lgpl-latest
  romimage: file=bios/BIOS-bochs-latest, address=0xf0000
  log: ./bochs.out
  vga_update_interval: 300000
  keyboard_serial_delay: 200
</programlisting>

<para>
You'll also need a floppy image file, sort of a working file,
which you copy the distribution files into, one by one, as
they are needed.  This is the file you point the 'floppya:'
directive in the <filename>bochsrc</filename> file to.  Copy the Win'95 boot disk
to your floppy working file ('1.44' in the <filename>bochsrc</filename> example):
</para>

<programlisting>
  unix-> /bin/cp -f win95_boot 1.44
</programlisting>

<para> Beginning the install</para>

<para>
Fire up bochs and boot the Win'95 boot diskette:
</para>

<programlisting>
  unix-> bochs boot:floppy

  Microsoft Windows 95 Setup
</programlisting>

<para>
Quit Setup to DOS to use FDISK.
</para>

<programlisting>
  '[F3]', '[F3]'
</programlisting>

<para>
FDISK C: to use the whole disk for the primary partition.
</para>

<programlisting>
  A:\> fdisk
  '[Return]'
  '[Return]'
  '[Return]'
</programlisting>

<para>
Power down Bochs - click the mouse on the 'Power' button
in the GUI toolbar.  Fire up bochs again.
</para>

<programlisting>
  unix-> bochs boot:floppy

  Microsoft Windows 95 Setup

</programlisting>

<para>Quit Setup to DOS to use FORMAT.</para>

<programlisting>
  '[F3]', '[F3]'
  A:\> format /u c:
</programlisting>

<para>
  (answer 'Y' and enter a volume label as desired)
</para>

<para>
Click on the floppy A icon in the GUI toolbar.  You should
see an 'X' through it signifying it's logically ejected.
Now we're ready for Disk1:
</para>

<programlisting>
  unix-> /bin/cp -f win95_d1 1.44
</programlisting>

<para>
Click on the floppy A icon again to logically insert
disk1.  The 'X' should go away.  Now run SETUP.EXE which is
on disk1.
</para>

<programlisting>
  A:\> setup /C
  To continue ...
  '[Return]'
  Welcome to Windows 95 Setup!...
  '[Return]'  (to select Continue button)
  Please insert "Disk2"...
</programlisting>

<para>
From now on, keep in mind that you must click the floppy A
icon to tell bochs you're ejecting the floppy (in theory)
BEFORE you copy over your floppy working file on your
workstation, and click on it again AFTERWARDS, to insert it.
This is most critical, if you transition from images of
floppies with different format. (disk1=1.44M, disk2=1.680M)
You're giving bochs a chance to look at the size of the
image file, and switch to a different sectors-per-track.
</para>

<programlisting>
  (Click the floppyA icon to eject)
  unix-> /bin/cp -f win95_d2 1.44
  (Click the floppyA icon to insert)

  '[Return]'  (select OK button)
  Software License Agreement
  '[Tab]'
  '[Return]'  (select Yes button)
  Windows 95 Setup Wizard
  '[Return]'  (select Next button)
  Choose Directory
  '[Return]'  (select Next button)
  Setup Options
  '[Down-Arrow]', '[Down-Arrow]', '[Down-Arrow]' (selects custom)
  '[Return]'  (select Next button)
  User Information
  Name:
  "Your name here"
  '[Tab]'
  Company:
  "Your company here"
  '[Return]'
  Key Identification
  Key:
  "123-4567890"  (from your Certificate of Authenticity)
  '[Return]'  (select Next button)
  Product Identification
  '[Return]'  (select Next button)
  Analyzing Your Computer
  '[Down-Arrow]'  (No, I want to modify the hardware list)
  '[Return]'  (select Next button)
  Analyzing Your Computer
</programlisting>

<para>
Let me just note that you can get around in this screen,
by the Down-Arrow key, Tab to move to a different area,
and space to toggle selection.  For some options, it's
much easier to first unselect every device of that
type, than select the one you want.
</para>

<para>
The ultimate selection you're trying to achieve is:
</para>

<programlisting>
  CD-ROM Drive                    (none)
  Display                         Default Standard VGA Display Adapter
  Floppy Disk Controllers         Standard Floppy Controller
  Hard Disk Controllers           Standard IDE/ESDI Hard Disk Controller
  Keyboard                        Keyboard
  Mouse                           (none)
  Network Adapter                 (none)
  PCMCIA Socket                   (none)
  Ports                           (none)
  SCSI Controllers                (none)
  Sound, MIDI, or Video...        (none)
</programlisting>

<para>
The exact sequence I used was:
</para>

<programlisting>
  [Space]  (unselect all CD-ROMs)
  [Down-Arrow]
  [Space]  (unselect all Displays)
  [Tab]  (move to Manufacturer and model section)
  13 [Down-Arrows] (Default Standard VGA Display Adapter)
  [Space] (to select this adapter)
  4 [Tabs] (get back to Hardware types section)
  2 [Down-Arrows] (get to Hard Disk Controllers)
  [Space] (to unselect all Hard Disk Controllers)
  [Tab]   (to get to Manufacturer and model section)
  3 [Down-Arrows] (get to Standard IDE/...)
  [Space] (to select this device)
  4 [Tabs] (get back to Hardware types section)
  2 [Down-Arrows] (get to Mouse)
  [Space] (to unselect all Mouse types)
  [Down-Arrow] (get to Network Adapter)
  [Space] (to unselect all Network Adapters)
  [Down-Arrow] (get to PCMCIA Socket)
  [Space] (to unselect all PCMCIA Socket types)
  [Down-Arrow] (get to Ports)
  [Space] (to unselect all Ports)
  [Down-Arrow] (get to SCSI Controllers)
  [Space] (to unselect all SCSI Controllers)
  [Down-Arrow] (get to Sound, MIDI...)
  [Space] (to unselect all Sound, MIDI...)
  3 [Tabs] (get to Next button)
  [Return]  (select Next button)

  Analyzing Your Computer
  [Return] (select Next button)

  Get Connected
  [Return] (select Next button)

  Select Components
</programlisting>

<para>
Well, you have to decide this one.  Remember, use [Down-Arrow],
[Tab], and [Space].  [Tab] to the Next button when you're done
and type [Return].
</para>

<programlisting>
  Network Configuration
  '[Return]' (to take default config, or change it as you want)

  Computer Settings
  '[Return]' (to take current settings)

  Startup Disk
</programlisting>

<para>
If you do NOT want to create a Startup Disk, you could type
</para>

<programlisting>
  '[Down-Arrow]'  (select No, I do not want a startup disk)
  '[Return]'      (select Next button)
</programlisting>

<para>
If you DO want to create a Startup disk.
</para>

<programlisting>
  '[Return]'      (select Next button)
</programlisting>

<para>
It is possible to create a startup disk after the installation, so you may skip the creation of a startup disk if it becomes problematic.
</para>

<para>
Either way, the following appears,
</para>

<programlisting>
  Start Copying Files
  '[Return]'

+- If you optioned to create a Startup Disk, the following appears:
|
|    Label a disk "Windows 95 Startup Disk"...
|
|  Click the floppyA icon to eject.  Now copy any floppy image file
|  which has a 1.44M format on it, onto your floppy working file.
|  Win '95 will erase any files on it.  Use the 'win95_boot' file,
|  since it's a 1.44M format.
|
|    unix-> /bin/cp -f win95_boot 1.44
|
|  Click on floppyA to insert.
|
|    '[Return]'
|    Setup has finished creating your startup disk...
|    '[Return]'  (select OK button)
|
|    Please insert the disk labeled 'Windows 95 Disk 2'...
|
|  Click the floppyA icon to eject.
|  Copy the working floppy disk image file to something signifying
|  it's the startup disk.  Then copy the disk#2 image file onto the
|  working file.
|
|    unix-> cp 1.44 win95_startup
|    unix-> /bin/cp -f win95_d2 1.44
|
|  Click on floppyA to insert.
|
+-   '[Return]'  (select OK button)

In any case (startup disk or not), the rest is very methodical.

+->  Please insert the disk labeled 'Windows 95 Disk 3'...
|
|    (Click the floppyA icon to eject.)
|      unix-> /bin/cp -f win95_d3 1.44
|    (Click the floppyA icon to insert.)
|
|    '[Return]'  (select OK button)
|
|  Just repeat this process, until SETUP has asked for all
+- 13 floppies in the distribution.  Of course, change
   'win95_d3' to each number in the succession; win95_d4,
   win95_d4, ... , win95_d13.
</programlisting>

<para>
After asking for all the floppy disks in the distribution,
Windows '95 will let you know it's going to restart your
computer.  Acknowledge this, and then bochs will bomb upon
attempt to reboot.
</para>

<para>
Fire up bochs again.  The 'boot:disk' is not necessary if
you have the 'boot: disk' directive in your '.bochsrc' file.
</para>

<programlisting>
  unix-> bochs boot:disk
</programlisting>

<para>
You'll get a screen full of garbage text for a while Win '95
updates your configuration files.  I'm not handling that
text screen mode correctly.  Then the window switches to
a blank graphics screen (say 2 to 5 minutes).
</para>

<programlisting>
  Windows 95 is now setting up your hardware and any Plug
  and Play devices you may have.
</programlisting>

<para>
You'll see the magnifying glass circulating about the
picture (icon) representing your computer for quite
awhile.
</para>

<programlisting>
  Windows is now setting up the following items...

  Setting up Control Panel
  Programs on the Start menu
  Windows Help
  MS-DOS program settings
  Time zone
</programlisting>

<para>
You can play with the Time Zone if you want.  I just
accept the one that comes up.  I like being on Tijuana
time anyhow!
</para>

<programlisting>
  '[Return]'

  Set up printer
</programlisting>

<para>
Bochs printing support varies from host OS to host OS.  Parallel port emulation was added in Bochs 1.3 for Unix platforms.  Check to see if printing is supported for your host OS in <xref linkend="features"> or the forums.  You can skip this part during installation and set up printing features later.  Cancel print setup in this manner:
</para>

<programlisting>
  '[Tab]'
  '[Return]'  (select Cancel button)

  Windows 95 is now finalizing settings for your computer
</programlisting>

<para>
Windows '95 should now display the 'Welcome to Windows 95'
screen, and give you one of it's helpful 'Did you know' tips.
My suggestion, is for you to shutdown Win '95 at this point,
and make a backup copy of your hard drive image file.
Otherwise, you are done, though you may want to check
out the section on getting rid of the 'splash' screen upon
boot.  In that case, shutdown is necessary also.
</para>

<programlisting>
  '[Return]'  (selects Close button)
  '[Ctrl]', '[Esc]', '[^Esc]', '[^Ctrl]'
</programlisting>

<para>
It's helpful to give slight intentional delays when typing
multi-key sequences like the one above.  The '^' means a
release of that key.
</para>

<programlisting>
  'u'  (shortcut for Shut Down)

  Shut down Windows...
  '[Return]'  (select Yes button)
</programlisting>

<para>
Your window changes to a different size graphics mode.  The
message 'It is now safe to shutdown your computer' will be
displayed briefly, but then the screen goes blank due to
bochs not handling something in that graphics mode correctly.

Power down by clicking on the 'Power' button in the bochs
GUI toolbar.  The bochs window disappears as bochs stops
execution.  Make a backup copy.
</para>

<programlisting>
  unix-> cp 62M.img 62M.win95.installedOK
</programlisting>

<para>
Getting rid of Win '95 'splash' screen upon bootup.
</para>

<para>
When Win '95 boots up, it typically displays the intro
screen while it boots (splash screen).  It uses a graphics
mode I don't handle well, mostly because it's not important
enough to spend the time on it.  You can tell Win '95
not to display this screen anyways, which I prefer.
</para>

<para>
Using the MTOOLS package, if you have a drive letter
associated with your hard disk image file, for example:
</para>

<programlisting>
  ~/.mtoolsrc: drive c: file="/path/62M.img" partition=1
</programlisting>

<para>
You can look at and modify the contents of your drive
image file, using commands on your workstation.
</para>


<note>
<para>
WARNING: You MUST power down bochs if you are running any software that does any kind of disk caching!!!  Yes, Windows '95 does disk caching.
</para>
</note>

<para>
Look at the attributes associated with c:/MSDOS.SYS.
</para>

<programlisting>
  unix-> mattrib c:/MSDOS.SYS
</programlisting>

<para>
Copy it to your workstation, with the text mode translation
flag.
</para>

<programlisting>
  unix-> mcopy -t c:/MSDOS.SYS .
</programlisting>

<para>
Edit the file, adding "Logo=0" under the Options section.  Save the file.
</para>

<programlisting>
  [Options]
  BootMulti=1
  BootGUI=1
  Network=0
  Logo=0      <------- add this line
</programlisting>

<para>
Copy it back to your disk image.  Restore proper
attributes to what they were before.  For example.
</para>

<programlisting>
  unix-> mcopy -t MSDOS.SYS c:/
  unix-> mattrib -a +s +h +r c:/MSDOS.SYS
</programlisting>

<para>Finishing up after the install</para>

<para>
You should now delete any temporary copies of the floppy disk
image files, used to facilitate installation.
</para>

<programlisting>
  unix-> /bin/rm -i win95_boot win95_d*
</programlisting>

<para>
OK, you're done!!!  Make sure you tell bochs to boot the
hard drive either in '.bochsrc' or by the 'boot:disk' option,
and fire it up.
</para>

<programlisting>
  unix-> bochs
</programlisting>

</section><!-- end of Installing Windows 95 with floppies -->

<section>
  <title>Installing a Japanese version of Windows 95</title>
<para>
The following has been contributed by  dohzono at hf dot rim dot or dot jpa :

<screen>
Here is a tip for installing Japanese win95.

                    *

I made a boot floppy and installed the W95 disk image. I used "CD for
new machines" (not an upgrade version). Host OS is FreeBSD-4.0R. It
seems working.

When you make a boot floppy with W95(J), there is a line containing

  DEVICE=JDISP.SYS /HS=LC

in the config.sys (Highspeed Scroll?). jdisp.sys can have options:

        /HS=ON
        /HS=LC
        /HS=OFF

and bochs runs with /HS=OFF option (I've heard that VMware requires
/HS=LC option).

# If you choose /HS=ON, you can read usual Japanese messages on the
# screen, but it doesn't scroll (the cursor goes downward and out of
# the screen). If you choose /HS=LC, you can see some images
# (corrupted messages), and also it doesn't scroll.

Here is my boot floppy's config.sys. I just changed the option like
above (/HS=OFF), and added a line for the CD driver.

  DEVICE=BILING.SYS
  DEVICE=JFONT.SYS /MSG=OFF
  DEVICE=JDISP.SYS /HS=OFF
  DEVICE=JKEYB.SYS
  device=gscdrom.sys /d:mscd000 /v

After installing to the HD image, I made a change to the line of
c:/config.sys

  DEVICE=JDISP.SYS

to

  DEVICE=JDISP.SYS /HS=OFF
                   ^^^^^^^
</screen>
</para>
</section>
</section>

<section id="guest-winnt4">
        <title>Windows NT 4.0</title>
<para>
You must read the message regarding software licenses in 
<xref linkend="thirdparty"> before you install Windows NT 4.0 as a guest operating system in Bochs.
</para>
<para>
Here are the known issues about installing and running Windows NT4.0 :
</para>
<itemizedlist>
<listitem>
<para>
If you want to use the LGPL'd VGABIOS to install Windows NT 4.0 you'll need
version 0.4c or higher. With older versions you'll get a black screen after
first reboot.
</para>
</listitem>
<listitem>
<para>
to log in you must press ctrl-alt-del, and it is likely that the window manager
will trap this key combination. You can either use the trick described in 
<xref linkend="enter-special-keys"> or define a user short-cut 
(callable through the user short-cut gui button)
in you configuration file, for example:
<programlisting>
user_shortcut: keys=ctrl-alt-del
</programlisting>
</para>
</listitem>
</itemizedlist>
</section>


<!-- Win98 Section Starts Here -->

<section id="guest-win98"><title>Windows 98</title>

<para>
You must read the message regarding software licenses in
<xref linkend="thirdparty"> before you install Windows 98 as a guest operating system in Bochs.
</para>

<tip><para>
If you want to use higher screen resolutions than 640x480 with more than 16 colours,
you should enable the Cirrus video card, see <xref linkend="cirrus-notes">, as Windows 98
comes with drivers for that video card.
</para></tip>

<para>
There are two ways to get Windows 98 running as a guest operating system in Bochs:
</para>

<itemizedlist>
<listitem><para><emphasis><link linkend="win98method1">
mcopy Windows 98</link></emphasis> - The first method is to copy files from a functional
Windows 98 installation partition.  This initially will be less time consuming, as you will
not have to install the OS or the applications running on it.  On the other
hand, you do not have the benefit of having an new installation especially
geared for Bochs.  You will need mtools and your Windows 98 CD-ROM.
</para></listitem>
<listitem><para><emphasis><link linkend="win98method2">
Classic Install</link></emphasis> - The second method is to do a fresh installation of Windows 98 on your virtual
hardware.  This is a slow, tedious process.  You will have the benefits,
however, of having a clean registry and a slimmer installation running only the
components you need.  All you need for this method is your Windows 98 CD-ROM
and your license key.
</para></listitem>
</itemizedlist>

<para>
You should <emphasis>NOT</emphasis> use your existing Windows 98 installation
for both your real hardware and as a guest OS in Bochs.  When Windows 98
detects changes in hardware, it will make changes in the installation.  It will
deactivate certain drivers and devices and activate or install others.  This is
what happens when you run an existing installation for the first time in Bochs.
</para>

<section id="win98method1"><title>Windows 98 Method 1: mcopy Windows 98 into Hard Disk Image (Linux Host)</title>
<para>
In this method, files will simply be copied from a functional Windows
98 partition. For the impatient, here is a short summary:
</para>

<itemizedlist>
<listitem><para>
Remove unnecessary files from your Windows partition.
</para></listitem>
<listitem><para>
Create a disk image with <command>bximage</command>.
</para></listitem>
<listitem><para>
Update your <filename>.bochsrc</filename> configuration file for the diskimage.
</para></listitem>
<listitem><para>
Use <command>mtools</command> to partition and format the image; the 
copy all the windows files to the image.
</para></listitem>
<listitem><para>
Finally, start the simulation and let Windows reconfigure itself.
</para></listitem>
</itemizedlist>

</section>

<section><title>Locating Your Partitions</title>
<para>
Make sure that your MS Windows partition is mounted.  Check
<emphasis>/etc/fstab</emphasis> to see if and where it is mounted.  For more
information on fstab, type <emphasis>man fstab</emphasis> at the command
prompt.  You may also very carefully type <emphasis>fdisk -l</emphasis> and
<emphasis>df</emphasis> as root for more information on the partitions of your
computer.  For example:
</para>

<programlisting>
# cat /etc/fstab
/dev/hda7       /              reiserfs     defaults 1 1
/dev/hda5       /boot          ext2         defaults 1 2
/dev/cdrom      /media/cdrom   auto         ro,noauto,user,exec 0 0
devpts          /dev/pts       devpts       defaults 0 0
/dev/hda3       /home          reiserfs     defaults 1 2
/dev/hda1       /home2         ext2         defaults 1 2
/dev/fd0        /media/floppy  auto         noauto,user,sync 0 0
proc            /proc          proc         defaults 0 0
usbdevfs        /proc/bus/usb  usbdevfs     defaults,noauto 0 0
/dev/hda6       swap           swap         pri=42 0 0

# fdisk -l
Disk /dev/hda: 255 heads, 63 sectors, 1247 cylinders
Units = cylinders of 16065 * 512 bytes

   Device Boot    Start       End    Blocks   Id  System
/dev/hda1   *         1       510   4096543+   b  Win95 FAT32
/dev/hda2           511       794   2281230    5  Extended
/dev/hda3           795      1247   3638722+  83  Linux
/dev/hda5           511       513     24066   83  Linux
/dev/hda6           514       539    208813+  82  Linux swap
/dev/hda7           540       794   2048256   83  Linux

# df
Filesystem           1k-blocks      Used Available Use% Mounted on
/dev/hda7              2048188   1844552    203636  91% /
/dev/hda5                23302      3584     18515  17% /boot
/dev/hda3              3638604    549220   3089384  16% /home
shmfs                    63240         0     63240   0% /dev/shm
//server/C$            4096512   3808000    288512  93% /shares/SERVER1/c
//server/D$           13823744   3854848   9968896  28% /shares/SERVER1/d
/dev/hda1              4032092   1897220   3794432  50% /windows/c
</programlisting>

<para>
In this example, the Windows partition is on
<emphasis>/dev/hda1</emphasis>.  It is mounted as
<emphasis>/windows/c</emphasis> and is it taking up 1,897,220 bytes, or roughly 2 gigabytes.  This
means that the disk image you would need to create in this instance would need to be
at least that size if you plan to put all the files from your Windows
partition there.
</para>  
</section>

<section><title>Cleaning Up Your MS Windows Partition</title>
<para>
You will save some space if you omit what is in your <emphasis>My Documents</emphasis> and <emphasis>Windows Update</emphasis> directory.  You may also want to use the Windows <emphasis>Disk Cleanup</emphasis> to delete all your temporary files:
</para>

<itemizedlist>
<listitem><para>Reboot into Windows 98</para></listitem>
<listitem><para>Double click on "My Computer"</para></listitem>
<listitem><para>Right click on your "C" drive.  A small menu should appear.</para></listitem>
<listitem><para>Click on "Properties"</para></listitem>
<listitem><para>Click on "Disk Cleanup"</para></listitem>
<listitem><para>Make sure "Temporary Internet Files", "Temporary Files", "Downloaded Program Files", and "Recycle Bin" are all selected.</para></listitem>
<listitem><para>Click on the "OK" button.</para></listitem>
<listitem><para>When it says "Are you sure you want to delete files?", click "Yes"</para></listitem>
</itemizedlist>

<para>
You will want to minimize the amount of files you will have to transfer to your new disk image.
Before you reboot into Linux, you may want to do a search for <emphasis>*.tiff,
*.jpg, *.avi, *.mov, *.mpg, *.mp3, *.wav, *.ra, *.rm, *.ram, and *.wmf</emphasis> files.
Move these somewhere under the <emphasis>My
Documents</emphasis> hierarchy.  Do so only if it does not disrupt your setup,
 and if the files are not already there:
</para>


<itemizedlist>
<listitem><para>Open up <emphasis>My Documents</emphasis></para></listitem>
<listitem><para>From the File Menu, click on <emphasis>File => New =>
Folder</emphasis></para></listitem>
<listitem><para>Type <emphasis>big_files</emphasis> in the folder name box.</para></listitem>
<listitem><para>Double Click on the <emphasis>big_files</emphasis> folder.
Leave this window open.</para></listitem>
<listitem><para>Click on <emphasis>Start => Find => Files or Folders</emphasis></para></listitem>
<listitem><para>In the <emphasis>Named:</emphasis> input box, type <emphasis>*.tiff, *.jpg, *.avi, *.mov, *.mpg, *.mp3 *.wav *.ra *.rm *.ram *.wmf</emphasis></para></listitem>
<listitem><para>The <emphasis>Look In</emphasis> field should be <emphasis>C:\</emphasis>, and the <emphasis>Inlcude Subfolders</emphasis> checkbox should be checked.</para></listitem>
<listitem><para>Press <emphasis>Enter</emphasis>.</para></listitem>
<listitem><para>Drag and drop files that are NOT part of a program, NOT in the
<emphasis>Program Files Directory</emphasis>, and NOT in the
<emphasis>Windows</emphasis> directory into an empty space in your
<emphasis>big_files</emphasis> folder.  Be sure you know what you are
moving.</para></listitem>
<listitem><para>When the files are done moving, reboot into Linux:
<emphasis>Start => Shutdown => OK</emphasis></para></listitem>
</itemizedlist>
</section>

<section><title>Mounting Your Windows Partition</title>
<para>
If you have a Network File System (NFS) mounted, you
could also use these files as source files.  In example shown in the previous
section, the filesystem
mounted on <emphasis>/share/SERVER1/c</emphasis> is from a Windows 2000 server.
</para>

<para>If your Windows 98 partition is not mounted, and it lives on 
/dev/hda1, type the following as root:
</para>

<programlisting>
mkdir /windows
mkdir /windows/c
mount -t vfat /dev/hda1 /windows/c/
ls /windows/c/
</programlisting>

<para>
You should now see the Windows 98 partition's directories, to include <emphasis>Windows</emphasis> and <emphasis>Program Files</emphasis> these two directories are key to your new guest installation.
</para>
</section>

<section><title>Choosing the Size of Your Disk Image</title>
<para>
You are going to prepare two disk images,
the primary hard disk image, and the backup image.  The backup image will save you from
disaster when you make a change that makes your first image unusable.  This 
backup image is not required, but it is highly recommended.  The primary disk image will
be called <emphasis>c.img</emphasis>
The backup image will be called
<emphasis>c.img.bak</emphasis> .
  You must consider several things when
choosing the size of the disk image:

</para>

<itemizedlist>
<listitem><para>The size of your Windows installation.</para></listitem>

<listitem><para>The amount of free space you have available in your home
directory.  If you do not have enough free space in your home directory, find
another partition to put this image on, and ensure that you have the proper
permissions for this file (type <emphasis>man
chmod</emphasis>).</para></listitem>

<listitem><para>Whether or not you choose to have a concurrent backup image in your home
directory (<emphasis>c.img.bak</emphasis>).  If you do this, you will need
twice as much space.</para></listitem>

</itemizedlist>

<para>
It is important to keep your guest OS image independent of your office files so that you can easily restore your setup to a previous state without changing your office files, in case something did not go right.  I cannot stress enough the importance of doing this.
</para>
</section>

<section><title>Setting Up the Disk Image</title>
<para>
Once you have decided on the size of your hard disk image, follow
the instructions in 
<xref linkend="diskimagehowto"> using the mtools method. Start by making a
directory called ~/win98 . 
</para>

<programlisting>
[david@domain]$ mkdir ~/win98
[david@domain]$ cd ~/win98
[david@domain]$ bximage
========================================================================
                                bximage
                  Disk Image Creation Tool for Bochs
========================================================================

Do you want to create a floppy disk image or a hard disk image?
Please type hd or fd. [hd] hd

What kind of image should I create?
Please type flat, sparse or growing. [flat] 

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

I will create a hard disk image with
  cyl=2
  heads=16
  sectors per track=63
  total sectors=2016
  total size=0.98 megabytes

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

Writing: [] Done.

I wrote 1032192 bytes to c.img.

The following line should appear in your bochsrc:
  ata0-master: type=disk, path="c.img", cylinders=2, heads=16, spt=63
[david@domain]$  
</programlisting>

<para>
If you are creating a 2 gig image, you will want to type
<emphasis>2000</emphasis> when it asks you for the size, instead of
<emphasis>1</emphasis>, as I did in this example.
</para>
</section>

<section><title>Create the .bochsrc Configuration File</title>

<para>
Now that you have the disk image information, it is time to create the
~/win98/.bochsrc file.  In the following example, you will need to replace all
instances of <emphasis>/home/david/</emphasis> with your own home directory.
All paths in the ~/win98/.bochsrc file must be absolute.
</para>

<programlisting>
# .bochsrc FILE FOR WINDOWS 98 AS GUEST OS IN LINUX

# Set aside the RAM for bochs and make sure you have enough RAM left over for your system.
# Type "cat /proc/meminfo" at the prompt to find out how much RAM you have.
megs: 64

# Filename of ROM images go here.  Be sure to check your installation for the location
# of these two files (type: man find).  Paths must be absolute.
romimage: file=/usr/local/etc/bochs/bios/BIOS-bochs-latest, address=0xf0000
vgaromimage: file=/usr/local/etc/bochs/bios/VGABIOS-lgpl-latest

# Floppies are commented out, but you may need them later.
# floppya: 1_44=/dev/fd0, status=inserted
# floppyb: 1_44=/home/david/win98/floppyb.img, status=inserted

# Cylinder, head, and spt info taken from bximage program output
ata0-master: type=disk, path="/home/david/win98/c.img", cylinders=3657, heads=16, spt=63

# Have your Windows 98 CD in the drive, but always boot from hard disk.
# Comment this line out if you are using a disk image for the CD-ROM
# (See next comment).
ata0-slave: type=cdrom, path=/dev/cdrom, status=inserted

# You can optionally run the following command:
# dd if=/dev/cdrom of=/home/david/win98/win98.iso
# and uncomment the next line
# ata0-slave: type=cdrom, path=/home/david/win98/win98.iso, status=inserted

# choose the boot disk.
boot: disk

# where do we send log messages?
log: bochsout.txt

# enable mouse
mouse: enabled=1

# enable SB16
sb16: midimode=1, midi=/dev/midi00, wavemode=1, wave=/dev/dsp, loglevel=2, log=sb16.log, dmatimer=600000
</programlisting>
</section>


<section><title>Make Hard Disk Image Acessible by Mtools</title>

<para>
Now that you have your disk image, you want to make it accessible by mtools.
Add the following line to the <emphasis>~/.mtoolsrc</emphasis> file:
</para>

<programlisting>
drive c: file="/home/david/win98/c.img" partition=1
</programlisting>

<para>
Replace <emphasis>/home/david</emphasis> with your home directory.
</para>

<para>
Save and close .mtoolsrc.  Next, execute the following commands to
create a partition table for the drive image:
</para>


<programlisting>
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:
</programlisting>

<para>
For example, for my 2 gig virtual drive, I used:
</para>


<programlisting>
mpartition -I -s 63 -t 3657 -h 16 c:
mpartition -cpv -s 63 -t 3657 -h 16 c:
</programlisting>

</section>

<section><title>Format Partition and Copy Files</title>

<para>
Next, format the partition you just created using the mformat command:
</para>


<programlisting>
mformat c:
</programlisting>

<para>
You may want to set your <emphasis>My Documents</emphasis> directory aside:
</para>

<programlisting>
mkdir ~/mydocsbak
cd ~/mydocsbak
tar cfvz mydocs.tar.gz '/windows/d/My Documents'
mv '/windows/d/My Documents' .
</programlisting>

<para>
Now you are ready to copy the files!
</para>


<programlisting>
cd ~/win98
mcopy -s /windows/d/* c:
mmd "c:/My Documents"
</programlisting>

<para>
Put your <emphasis>My Documents</emphasis> folder back where it belongs:
</para>


<programlisting>
cd /windows/d
mv '/home/david/mydocsbak/My Documents' .
</programlisting>

<para>
Make a backup copy of your c.img:
</para>


<programlisting>
cd ~/win98
cp c.img c.img.bak
</programlisting>
</section>

<section><title>The Fun Begins</title>

<para>
Now it is time to fire up Bochs.  Windows will initially freak out when it notices its environment has changed completely (and wouldn't you?).  You may have to reboot your guest OS a few times as Windows deactivates certain devices and drivers and installs others.  Since installations vary, there are no step-by-step instructions for this process.  Just remember that you can always restore with your backup image if things go wrong:
</para>


<programlisting>
cd ~/win98
cp -f c.img.bak c.img
</programlisting>

<para>
Make sure you get the order right.  When you boot Bochs again, you will see everything as it was when you last did a <emphasis>cp c.img c.img.bak</emphasis>.  If you have a large disk image, such as two Gigs, it might take a few minutes for the file to copy.
</para>
</section>

<section id="win98method2"><title>Windows 98 Method 2: Classic Install (Linux Host)</title>
<para>
In this method, Windows 98 is installed using the CD-ROM, much the same way one
would install Windows 98 into a real computer with no operating system.  This
process could take up to 12 hours, so I recommended that you begin at the end of
your day.  You could check on it once or twice when you get up for the midnight
snack, and continue in the morning.
</para>

<para>
Here's a summary for the impatient:
</para>

<itemizedlist>
<listitem><para>
Copy the cdimage to harddisk to increase speed.
</para></listitem>
<listitem><para>
Create a disk image with <command>bximage</command>.
</para></listitem>
<listitem><para>
Update your <filename>.bochsrc</filename> configuration file for the 
diskimage and the cdimage. Make sure that to disable the 
<command>IPS</command> parameter for full speed, unless you really need
it to slow down the boot prompts.
</para></listitem>
<listitem><para>
Boot from CD, then use <command>fdisk</command> to partition the image
and <command>format c: /s</command> to format it.
</para></listitem>
<listitem><para>
Start the installation with <command>setup</command> from the commandline.
Enter information as necessary.
</para></listitem>
<listitem><para>
You can either use the keyboard only to give information, or enable and
disable the mouse with the middle button or <keysym>F12</keysym>.
</para></listitem>
<listitem><para>
When there are CPU panics, choose <command>alwayscont</command> to ignore
them. Amazingly, the install will work in spite of them.
</para></listitem>
</itemizedlist>

</section>

<section id="makewin98image"><title>Saving Your Windows 98 CD as a Disk
Image</title> <para>Since this second method involves installing from the Windows 98
CD-ROM, you will speed things up considerably if you put an image of this
disc on you hard drive.  These days, some computers are shipped with "Recovery
Disks" that have the Original Equipment Manufacturer (OEM) label on the MS
Windows 98 disk.  In these cases, it is not always easy to tell which CD-ROM
contains the operating system.  These types of disks may or may not work for
this purpose; more than likely it will be problematic.  Make sure you have a
disk that is labeled "Windows 98" with the Microsoft logo.  You will find the
product key on the "Certificate of Authenticity" provided to you by Microsoft.
This can be either on the aqua/purle/white book titled <emphasis>Microsoft
Windows 98: Getting Started</emphasis>, or on your PC.  You may also find it in
the CD-ROM packaging.  The product key is in squarish typeset next to a bar code.
</para>

<para>
Under Linux, insert your Windows 98 CD in your CD-ROM drive.  Make a directory called <emphasis>win98</emphasis> under your home directory.  Copy the image using the <emphasis>dd</emphasis> command:
</para>

<programlisting>
[david@host david]$ mkdir ~/win98
[david@host david]$ dd if=/dev/cdrom of=~/win98/win98.iso
</programlisting>

<para>The appropriate line to the configuration file will be added after the hard disk image is made.</para>

</section>

<section><title>Making the Windows 98 Hard Disk Image</title>

<para>
Since you can select what components you want with MS Windows and which ones
you do not, you have the option of having a slim installation that requires  
less disk space.  The actual Windows portion can be as little as 150 megabytes.
If you only plan to run Microsoft Word plus a couple of programs,
one Gigabyte will be more than sufficient.</para>

<para>
It is recommended that you put your office and personal files on a separate image.
This allows for easier backup and restoration of your installation as you go along.
</para>

<para>
Type "df" at the command prompt to see how much disk space you have:
</para>

<programlisting>
[david@host david]$ df
Filesystem           1k-blocks      Used Available Use% Mounted on
/dev/hda6              5580848   3328772   1968580  63% /
/dev/hda2                21958      5763     15061  28% /boot
/dev/hda5              4464560   1350568   2887200  32% /home
none                    192272         0    192272   0% /dev/shm
/dev/hda1              7054136   3037024   3658772  46% /home2
/dev/hda3              4142332   1843132   2299200  45% /windows/d
[david@192 user]$
</programlisting>

<para>
In this case, <emphasis>/home</emphasis> is mounted on <emphasis>/dev/hda5</emphasis>.  There is 2,887,200 bytes, or roughly 2.8 Gigabytes available.  There is enough space for the primary 1 Gigabyte image (c.img) and the backup image (c.img.bak).  You will now create the image using bximage:
</para>

<programlisting>
[david@host david]$ bximage
========================================================================
                                bximage
                  Disk Image Creation Tool for Bochs
========================================================================

Do you want to create a floppy disk image or a hard disk image?
Please type hd or fd. [hd] hd

What kind of image should I create?
Please type flat, sparse or growing. [flat] 

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

I will create a hard disk image with
  cyl=2031
  heads=16
  sectors per track=63
  total sectors=2047248
  total size=999.63 megabytes

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

Writing: [] Done.

I wrote 1048190976 bytes to c.img.

The following line should appear in your bochsrc:
  ata0-master: type=disk, path="c.img", cylinders=2031, heads=16, spt=63
</programlisting>

<para>
You will need the output of bximage for your ~/win98/.bochsrc file.  Be sure to
copy down the line that begins with <emphasis>ata0-master</emphasis>, etc. onto
a piece of paper or onto your desktop clibpoard.  See the example provided below
for details on the syntax.
</para>

</section>

<section><title>Create the .bochsrc Configuration File</title>

<para>
Now that you have the disk image information, it is time to create the
~/win98/.bochsrc file.  In the following example, you will need to replace all
instances of <emphasis>/home/david/</emphasis> with your own home directory.
All paths in the ~/win98/.bochsrc file must be absolute.
</para>

<programlisting>
# .bochsrc FILE FOR WINDOWS 98 AS GUEST OS IN LINUX

# Set aside the RAM for bochs and make sure you have enough RAM left over for your system.
# Type "cat /proc/meminfo" at the prompt to find out how much RAM you have.
megs: 64

# Filename of ROM images go here.  Be sure to check your installation for the location
# of these two files (type: man find).  Paths must be absolute.
romimage: file=/usr/local/etc/bochs/bios/BIOS-bochs-latest, address=0xf0000
vgaromimage: file=/usr/local/etc/bochs/bios/VGABIOS-lgpl-latest

# Floppies are commented out, but you may need them later.
# floppya: 1_44=/dev/fd0, status=inserted
# floppyb: 1_44=/home/david/win98/floppyb.img, status=inserted

# Cylinder, head, and spt info taken from bximage program output
ata0-master: type=disk, path="/home/david/win98/c.img", cylinders=2031, heads=16, spt=63

# If you ran the following command:
#      dd if=/dev/cdrom of=/home/david/win98/win98.iso
#   you can use the CD-ROM image on your hard drive:
ata0-slave: type=cdrom, path=/home/david/win98/win98.iso, status=inserted

# Optionally, if you have your Windows 98 CD in the drive
#   you can uncomment the next line, but the installation
#   process will be slower.
# ata0-slave: type=cdrom, path=/dev/cdrom, status=inserted

# choose the boot disk.
boot: cdrom

# where do we send log messages?
log: bochsout.txt

# enable mouse
mouse: enabled=1

# enable SB16
sb16: midimode=1, midi=/dev/midi00, wavemode=1, wave=/dev/dsp, loglevel=2, log=sb16.log, dmatimer=600000
</programlisting>
</section>

<section><title>Create the Primary DOS Partition and set it Active</title>
<para>Change into the ~/win98 directory.  Fire up Bochs.  (If Bochs does not
start, double check your .bochsrc file and make sure there are no mispellings).
Choose "CD-ROM" when Windows prompts you to choose hard disk or CD-ROM.  You
can use your arrow keys to select your option, or type the number "2".
</para>

<programlisting>
Microsoft Windows 98 CD-ROM Startu Menu
============================================

1.  Boot From Hard Disk
2.  Boot From CD-ROM

Enter your choice: _
</programlisting>

<tip>

<para>
If you are not given enough time to make this choice, close Bochs, and
add the following line to your <filename>.bochsrc</filename>:
</para>

<programlisting>
cpu: ips=1000000
</programlisting>

<para>
Fire up Bochs again.  If you have a 1 Gigahertz processor, an ips setting of 1 million
will keep you on your toes when it comes time to select the CD-ROM.
Just be sure to comment this line out or delete it before you begin the actual
installation, otherwise it will take too long to complete this project.
</para>

<para>
However, if you can manage to press quickly any key before the time is up,
you don't need to do use this trick.
</para>
</tip>


<para>
After you select the CD-ROM as your boot method, you will now see a menu with three choices:
</para>

<programlisting>

Microsoft Windows 98 CD-ROM Startu Menu
============================================

1.  Start Windows 98 setup from CD-ROM.
2.  Start computer with CD-ROM support.
3.  Start computer without CD-ROM support.

Enter a choice: _
</programlisting>

<para>
Type "2" and press "Enter" to <emphasis>Start computer with CD-ROM support</emphasis>.  This will take you to a DOS prompt.  At the DOS prompt, type <emphasis>fdisk</emphasis> and press "Enter".
</para>

<programlisting>
A:\>fdisk
</programlisting>

<para>
You will now be taken to a screen asking you if you would like to enable large disk support.  Type "Y" and press "Enter".  You will now see the following menu: 
</para>

<programlisting>
                            Microsoft Windows 98
                          Fixed Disk Setup Program

                                 FDISK Options

Current fixed disk drive: 1

Choose one of the following:

1. Create DOS partition or Logical DOS Drive
2. Set active partition
3. Delete partition or Logical DOS Drive
4. Display partition information


Enter choice: [1]




Press Esc to exit FDISK
</programlisting>

<para>
Type "1" and press "Enter" to select <emphasis>Create DOS partition or Logical DOS Drive</emphasis>.  You will be taken to another menu:
</para>

<programlisting>
                 Create DOS Partition or Logical DOS Drive

Current fixed disk drive: 1

Choose one of the following:

1.  Create Primary DOS Partition
2.  Create Extended DOS Partition
3.  Create Logical DOS Drive(s) in the Extended DOS Partition


Enter choice: [1]




Press Esc to return to FDISK Options
</programlisting>

<para>
Type "1" and press enter to select <emphasis>Create Primary DOS Partition</emphasis>.  You will then be asked the following:
</para>

<programlisting>
Do you wish to use the maximum available size for a Primary DOS partition
and make the partition active (Y/N).................? [Y]
</programlisting>

<para>
Type "Y" and press "Enter".  You should then see the following message:
</para>

<programlisting>
You MUST restart your system for your changes to take effect.
Any drives you have created or changed must be formatted
AFTER you restart.

Shut down Windows before restarting.




Pres Esc to exit FDISK_
</programlisting>

<para>
Type "Esc" to exit FDISK.  You should be back at the DOS prompt.  Click
on the Bochs "Power" button.
</para>

</section>

<section><title>Formatting the Disk Image</title>
<para>We now need to format the virtual "C" drive for your guest OS.</para>
<para>Fire up Bochs from the ~/win98 directory.  Type "2" and press "Enter" to
select booting from the Windows 98 CD-ROM.  Then Type "2" and press "Enter" to select
booting with CD-ROM support.  You should be at the DOS prompt once again.  Select the "D" drive, change to the "WIN98" directory, and type "format c:".  You will then be asked the following:
</para>

<programlisting>
A:/>D:

D:/>cd WIN98

D:/WIN98>format c: /s

WARNING, ALL DATA ON NON-REMOVABLE DISK
DRIVE C: WILL BE LOST!
Proceed with Format (Y/N)?_
</programlisting>

<para>
Type "Y" and press "Enter" to format.  The process should take no more
than a minute on a modern computer.  You will then be asked for the disk
label.  Hit "Enter".  If you are successful, you should see output
similar to the following:
</para>

<programlisting>
Formatting 999.1M
Format complete.
Writing out file allocation table
Complete.
Calculating free space (this may take several minutes)...
Complete.

Volume label (11 characters, ENTER for none)?

1,045,577,728 bytes total disk space
1,045,577,728 bytes available on disk

        4,096 bytes in each allocation unit.
      255,267 allocation units available on disk.

Volume Serial Number is 555D-1F23


D:\WIN98>
</programlisting>

<para>
It is now time to comment out the "cpu: ips=1000000" line in your ~/win98/.bochsrc file.
Close Bochs by clicking the Bochs power button with your mouse. Open up ~/win98/.bochsrc
with your favorite editor and put a hash (#) mark in front of the cpu line.
</para>

<para>
You are now ready to begin the installation.
</para>
</section>

<section><title>Starting the Installation</title>

<para>Fire up Bochs from the ~/win98 directory.  Type "2" and press "Enter" to
select booting from the Windows 98 CD-ROM.  Then Type "2" and press "Enter" to select
booting with CD-ROM support.  You should be at the DOS prompt once again.  Select the "D" drive, change to the "WIN98" directory, and type "setup":
</para>

<programlisting>
A:\>D:
D:\>cd WIN98
D:\WIN98>setup
</programlisting>

<tip>
<para>
You can also use <command>setup /is</command> to bypass scandisk.
</para>
</tip>

<tip><para>
If Windows 98 setup complains about the (emulated) computer being too slow or about
a missing co-processor (in case you compiled Bochs without support for that), you can
use the undocumented <option>/nm</option> switch to bypass the hardware check:
<command>setup /nm</command>.
</para></tip>

<para>
Answer the question of the Windows 98 installer. You can either supply
answers with the keyboard including the arrow keys, or activate the 
mouse with the middle mouse button or <keysym>F12</keysym>.
</para>

<para>
I choose a minimal installation to save space on the harddisk image,
but others should probably also work.
</para>

<para>
&FIXME; (Add additional detailed step-by-step information here if really
necessary)
</para>

<para>
At some stage during the installation, the simulation will stop with
an audible beep and notify you about a CPU panic. Don't worry, choose
<command>alwayscont</command> to ignore all such future panics (there
will be several others). Windows will install properly in spite of those
errors.
</para>

<para>
If you want, you can create checkpoints of your harddisk image at 
apropriate times (before a reboot, for example). Stop the simulation
by clicking on the <command>Tool</command> icon, copy the image file,
and continue by pressing return in the bochs terminal window.
Optionally, <command>gzip</command> the copied disk image to conserve
some space.
</para>

<para>
&FIXME; Add more details, if needed.
</para>

</section>


</section>
<!-- Win98 Section Ends Here -->



<section id="guest-winme">
        <title>Windows ME</title>
        <para>
</para>
        
                <section><title>Installing Windows ME</title>
<para>You must read the message regarding software licenses in 
<xref linkend="thirdparty"> before you install Windows ME as a guest operating system in Bochs.</para>
<para>
This has been contributed by Sancho Roberto :
</para>

<para>
<screen>
Date: Sun, 21 Oct 2001 02:24:22 -0700 (PDT)
From: Sancho Roberto (rsanchov at yahoo dot com)
To: bochs-developers@lists.sourceforge.net
Subject: [Bochs-developers] WinMe install tips
Parts/Attachments:

1) Install Win98 

   My Windows Me is an update version, that is, it upgrades over Win98.
   So the first think I have to do is to install on a HD image a
   Win98

   It is not necessary to do the full install. What I've done is
     - Create a HD image (Win98.img) with 500MB
     - Format It, install MSDOS6 on it so I can boot from c
     - Make a W98 directory.
     - Copy using mtools the instalation directory from the original
       Win98 CD
     - Run bochs
     - run the setup program into the W98 directory
     - Select WIN98 as Windows directory. All other setup options
       are left by default.
     - I don't care about HW detection, etc. Just uncompressing
       the cab files to the WIN98 directory es enought for WinMe.
       (Note that Win98 is not functional and cannot boot)
       
2) Copy the WinMe install files to the HD

   In Win98.img, with mtools, I create a directory called WinMe.
   Again, I copy the contents of the Win9x directory from the original
   WinMe CD. Note that I copy the CD to my HD, and then with mtools
   from my HD to win98.img. I also delete then W98 directory.

3) Create WinMe.img   

   Now, I created another blank HD called WinMe.img with 500MB.
   I format it and install MSDOS6 so I an boot using it.

4) Prepare the instalation Bochs

   I edit the bochsrc.txt file so
   - WinMe.img is ata0-master
   - Win98.img is ata0-slave

5) Running setup

   I start bochs: the C: drive is empty (it only contains the
   MSDOS6 command.com, IO.SYS, etc). The D: drive has: 
      D:\W98 - The "installed" Windows 98
      D:\WINME - Windows Me setup files

   I go to the WINME directory and run:

      SETUP xxxx 

   The description of the setup options can be found in the Microsoft Knowledge page as
   Q186111 - Description of the Windows 95, Windows 98, and Windows Me Setup Switches

   I've done a lot of trials with this setup options until I finally
   found a correct way to finnish the installation. These are the setup
   options I used. I've copied a brief description (from the KB) and added
   my comments.

   /m - bypass the playing of the Setup sound (.wav) files.
        Not necessary as my Bochs has no sound device activated 

   /nf - Do not prompt to remove the floppy disk from the drive
         Maybe not necessary. Just in case

   /nh - This switch bypasses running the Hwinfo.exe program at 0 
         percent files and RunOnce.

         If not present, freezes on HW detection

   /ie - This switch bypasses the Windows 98 Startup Disk wizard screens. 
         To speed things up - I allways can create a Statup disk latter

   /iv - This switch bypasses displaying the Setup screens during 
         an upgrade within Windows.
         To speed things up 

   /c - This switch bypasses running SMARTDrive.
        Maybe not necessary. Just in case

   /im - Causes setup to ignore the conventional memory check.
         Maybe not necessary. Just in case

   /is - This switch causes Setup not to run ScanDisk.
         Very important as SCANDISK freezed bochs

   /iq - If you use the /is switch to bypass ScanDisk or if ScanDisk 
         does not complete successfully, Setup checks your drive for cross-linked files. 
         The /iq switch prevents Setup from doing this.

         Very important. If not used, Setup stop the installation 
         with a message "error found in C:, run scandisk and setup again"
         (or something like this). Of course, there is no errors in C:
         because is an empty, just formatted disk, but the WinMe setup
         thinks so. The only way to progress from this point is
         with this switch

   /it - This switch bypasses checking for the presence of "dirty" or "deadly" 
         terminate-and-stay-resident programs (TSRs) that are known to 
         cause problems with Windows Setup.
         Maybe not necessary. Just in case

   /p b;g=3

      b: This switch enables Prompt Before mode. It prompts 
         you before a detection module is called so that you can 
         step through each detection module manually and decide 
         if you want to skip it. 

         Very important. See bellow

      g: This switch controls how verbose the built-in progress bar is


   There is another main issue that must be handled

   WinMe requires a 150MHz computer as a minimum. If you try to run
   the WinMe setup, you will receive a message telling you so, and the
   installation will stop.

   The only way I found to solve this problem is to change the IPS
   value in bochsrc.txt. I raised the IPS value until setup stop
   complaining. In my machine (P3 @ 450MHz), I achieved this with

      cpu: ips=500000000

   This this IPS value, the keyboard and mouse are updated each
   100 seconds. This makes very difficult to type the CD-KEY numbers,
   select type of instalation, etc.

   One way to solve this is to lower the vga_update_interval and
   the keyboard_serial_delay. I lower the value until 
      - I have a minimum response from keyboard and mouse (say 
        1 second delay between keypress/mousemove and the
        screen update)
      - I still pass the 150 MHz check 
   
   The values I used are    
   
      vga_update_interval: 10000
      keyboard_serial_delay: 200

   They may be diferent for other computers.
   Note that bochs, on starting up complains about vga_update_interval
   with the message "bochsrc.txt: vga_update_interval not big enough!":
   ignore it.

6) Follow the Windows Me setup instruction ...

   Just a warning: it is very, very, very, *VERY* (very) slow ...
   Two days running non stop on my PC.
   Don't wait ... enjoy yourself during the process ... you that the time.

7) Hardware nightmare

   At a given moment, you are prompted to detect the hardware.
   There is a prompt for each type of device: Bus, keyboard, mouse, 
   HD, CDROM, etc. 

   Say NO to everything.

   If you say YES, sometimes setup will detect your HW, but normaly
   it will crash with GPF on COMMCTRL.DLL (setup crash, but bochs 
   still alive. Nice!).

   If you sat CANCEL, setup will stay in this screen forever (ok, ok,
   I have just wait 10 hours).

8) Configuring 

   Setup will configure you PC. You can set your timezone, etc.

   Then Setup will create the Statup menu icons. Here, time to time,
   you will get a GPF in PIFMGR.DLL. Just press Ok and continue.

   Again this procedure is very very very very very very slow.
   Worse of all, you cannot leave it running by night. You must
   press Ok a lot of times to clean the GPF.

9) Restart.

   At last, setup will restart the PC. Exit Bochs. I recomend to make
   a copy of WinMe.img just to save all your time.

10) Run bochs again

   Setup will do some stuff ... just wait

   After a while, the Start button appearch on the lower left corner
   of the screen!

   Just for safe, I executed within WinMe msconfig.exe, and in the
   advanced tab set the Disk Compatibility mode". Also, I've turned 
   of the menu and windows animations, to speed thinks up a bit. Also
   it may be a good idea to turn off scandisk on setup.

   Do not forget to exit from Windows with the Shutdown menu ...

11) That's all

   Now you can comment out the ata0-slave line in the bochsrc.txt. WinMe.img
   contains a working WinMe.

   NOTE: if you lower the IPS, WinMe will be unstable ... surelly 
         a timing issue. But even if IPS is high, lowering 
         vga_update_interval and keyboard_serial_delay will help
         on getting an acceptable usability.

         DO not forget to use your Pentium 10 at 500 GHz to get a
         good speed within Windows.

Some bugs i've found

- MSDOS Scandisk freeze
- Hw detection is very problematic
- If bochs is visible when it switchs from text mode to graphic mode,
  the size of the window is correct. But if Bochs is minimized when
  doing so, the size of the Bochs window is incorrect. It does not
  take into account the height of the top banner (the one with the 
  disk icons, mouse, snapshot, etc), so the botton of the screen 
  is clipped.
- Dont expect to run WinMe at full speed unless you use your Pentium10 at 1500 GHz
- (not a bug, but a comment) The splash screen when booting/shutdown 
  WinMe is double height. I personally prefer to see the full image
  as it was time ago.
</screen>

                </para>
                </section> <!-- end of Installing Windows ME -->
</section>
<section id="guest-win2k">
        <title>Windows 2000</title>
<para>You must read the message regarding software licenses in 
<xref linkend="thirdparty"> before you install Windows 2000 as a guest operating system in Bochs.</para>
        <para>
        </para>

</section>
<section id="guest-win2k-server">
<title>Windows 2000 Server</title>
<para>You must read the message regarding software licenses in 
<xref linkend="thirdparty"> before you install Windows 2000 Server as a guest operating system in Bochs.</para>
</section>

<section id="guest-winxp">
        <title>Windows XP</title>
<para>You must read the message regarding software licenses in 
<xref linkend="thirdparty"> before you install Windows XP as a guest operating system in Bochs.</para>
        <para>
        Windows XP has been reported to install from the cd, and run inside Bochs. 
        The only known issue is to set the IPS to, at least, a value of 10000000.
        </para>
</section>


<section id="guest-osr5">
<title>SCO OpenServer 5.0.5</title>
<para>
Contributed by Carl Sopchak
</para>

<para>
You must read the message regarding software licenses in
<xref linkend="thirdparty"> before you install SCO OpenServer 5.0.5 as a guest operating system in Bochs.
</para>

<para>
Back in April and May of 2002, I did some work on Bochs 
in order to get it to install and boot SCO's OpenServer 5.0.5 (OSR5).
Since that time, I have had several e-mails asking about this error message
or that.  The newsgroup posts done at the time had all of the information that I knew,
so I pointed people there.  (I had not used Bochs since...) 
In February of 2003, I got another such e-mail.
Since the sender indicated they were willing to pay me to get this going for them,
I agreed to spend a few hours on it (for free, which is not common :-}).  Subsequently,
I decided to document this once and for all.  (I did not charge anyone anything, this time...)
</para>

<para>
Note: These steps were originally used with Bochs 1.4.1 (or thereabouts, 
since I was using CVS heavily at the time).  It is possible (likely) that later versions of Bochs
are more tolerant/bug free, and this install may be abbreviated.  However, I have not tried
to streamline it at all.
</para>

<para>
These steps were performed and confirmed using Bochs version 2.0.2, and SCO OpenServer version 5.0.5.
The host OS was Red Hat Linux 8.0.
</para>

<para>
First, I downloaded the tarball, and extracted the source tree.  I decided to use the tarball
instead of the RPM so that I knew what options were compiled in, etc.
<screen>
linux-$ tar -xzvf bochs-2.0.2.tar.gz
</screen>
</para>

<para>
Next, I configured and compiled Bochs...
<screen>
linux-$ cd bochs-2.0.2
linux-$ ./configure --enable-cdrom --enable-ne2000 --enable-host-specific-asms
linux-$ make
</screen>
The --enable-host-specific-asms should only be used if the host OS is an Intel x86 based OS.
</para>

<para>
I then created my disk image:
<screen>
linux-$ ./bximage
========================================================================
                                bximage
                  Disk Image Creation Tool for Bochs
========================================================================

Do you want to create a floppy disk image or a hard disk image?
Please type hd or fd. [hd] hd

What kind of image should I create?
Please type flat, sparse or growing. [flat] 

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

I will create a hard disk image with
  cyl=4161
  heads=16
  sectors per track=63
  total sectors=4194288
  total size=2047.99 megabytes

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

Writing: [] Done.

I wrote 2147475456 bytes to hd0.img.

The following line should appear in your .bochsrc:
  ata0-master: type=disk, path="hd0.img", cylinders=4161, heads=16, spt=63
</screen>
</para>

<para>
I then created my .bochsrc file.  I did this via the interactive portion of Bochs, with the
end result as follows:
<programlisting>
floppya: 1_44="/dev/fd0", status=inserted
floppyb: 1_44="b.img", status=inserted
ata0: enabled=1, ioaddr1=0x1f0, ioaddr2=0x3f0, irq=14
ata0-master: type=disk, path="hd0.img", cylinders=4161, heads=16, spt=63, translation=auto, biosdetect=auto, model="Generic 1234"
ata0-slave: type=cdrom, path="/dev/cdrom", status=inserted, biosdetect=auto, model="Generic 1234"
ata1: enabled=0
ata2: enabled=0
ata3: enabled=0
romimage: file=bios/BIOS-bochs-latest, address=0xf0000
vgaromimage: file=bios/VGABIOS-lgpl-latest
megs: 64
parport1: enabled=1, file="lp.pipe"
com1: enabled=0
# no sb16
boot: cdrom
floppy_bootsig_check: disabled=0
vga_update_interval: 300000
keyboard_serial_delay: 250
keyboard_paste_delay: 100000
cpu: ips=3000000
clock: sync=realtime, time0=0
text_snapshot_check: 0
mouse: enabled=0
private_colormap: enabled=0
i440fxsupport: enabled=0
# no ne2k
# no loader
log: osr5.log
logprefix: %t-%e-%i%d
debugger_log: -
panic: action=ask
error: action=report
info: action=report
debug: action=ignore
pass: action=fatal
keyboard_mapping: enabled=0, map=
keyboard_type: mf
user_shortcut: keys=none
config_interface: textconfig
display_library: x
</programlisting>
Some important things to note are that you want to boot from the cdrom, and you do NOT want the ne2000
card configured initially.  (We'll add that later...)
</para>

<para>
At this point, Bochs is ready to roll!  Insert the OSR5 install CD into the drive, and start Bochs.
You should soon see the SCO "boot:" prompt:
<screen>
SCO OpenServer(TM) Release 5

boot
: defbootstr disable=fdi,dptr
</screen>

Note the disable= parameter that you need.  These two SCO drivers cause the install to fail, so they
need to be disabled for the install boot.  You will not need this once OSR5 is installed.
</para>

<para>
During the install of OSR5, there are two default configuration answers that need to be changed.
For the hard disk setup, you should turn bad tracking off, since it's unnecessary on an emulated disk.
(It won't hurt to do it, it will just take a VERY long time!)
For the network setup, change the network card to Deferred.  You can change other settings, if you so
desire.  However, I would do the initial install with as little configured as you can get away with, then
add whatever else is needed (one step at a time) after the initial install completes.
</para>

<para>
Let the install copy the files.  Go get lunch.  Take a nap.  Go have dinner... 
This can take a LONG time.  On my Pentium 4 1.7GHz system, this
step took just over eight hours!  (BTW, it was MUCH longer in version 1.4.1.  Great job, guys!)
</para>

<para>
After the install finishes, you will need to change the following lines in .bochsrc file:
<programlisting>
ne2k: ioaddr=0x280, irq=10, mac=b0:c4:20:00:00:00, ethmod=linux, ethdev=eth0
boot: disk
</programlisting>
Obviously, if you're not using Linux, the ethmode and ethdev values on the ne2k line will be different.
Also, since Bochs uses "raw" network card access, you'll have to "setuid root" on the Bochs executable:
<screen>
linux-$ chown root bochs
linux-$ chmod u+s bochs
</screen>
(If there is a way to give a "normal user" CAP_NET_RAW capability, that would be an alternative.
I don't know how to do that...)
Restart Bochs.  Now, you can just press Enter at the OSR5 boot: prompt, because the offending
drivers have been linked out of the kernel.
</para>

<para>
Before you configure the network card,  I'd strongly suggest getting the latest "nat" driver from SCO.  
Version 5.0.5b of this driver, according to the SCO web site, "correct[s] possible system lockup 
under high load due to internal buffer overflow."  The driver can be found 
<ulink url="ftp://ftp.caldera.com/pub/openserver5/drivers/OSR505/network/nat">here</ulink>.
To get the Disk Image file into SCO, I downloaded the VOL.000.000 file to my linux box,
and used tar to get it on to a floppy:
<screen>
linux-$ tar -cvf /dev/fd0 VOL.000.000
</screen>
I then used tar within OSR5 to move it from the floppy to the /tmp directory:
<screen>
osr5-# cd /tmp
osr5-# tar -xvf /dev/fd0135ds18
</screen>
You can then use 'custom' to install the driver from the image file.
You will then want to use 'scoadmin network' to configure the network card.  Choose 
the Novell NE2000 card, and set the parameters to match the ne2k: line in the .bochsrc file.
DO NOT have OSR5 look for the card, as Bochs may likely crash. (It did in version 1.4.1.)
</para>

<para>
You can also configure a printer, if you want.  Using the spoolpipe utility that I wrote
(which can be found in Bochs' misc directory), you can print from OSR5 through the parallel 
port, and you'll hardly notice
that the printing is going through an extra layer of operating system!  
(You could also set up a printer using network printing, if the printer is not on the host machine...)
</para>

<para>
Obviously, dont forget to apply the release supplements and other patches that are considered 
"must haves" for OSR5: rs505a, oss600a, oss497b (others?).  
</para>

<para>
That's about as far as I have got.  I played around with OSR5 within Bochs a bit, but I 
can by no means say that I did any kind of real testing, let alone exhaustive testing.
</para>

<para>
And of course, YMMV!  :-)
</para>

</section>

</chapter>


</book>