development.dbk

bochs : one pc simulator.

<!--
================================================================
doc/docbook/development/development.dbk
$Id: development.dbk,v 1.24 2006/07/11 22:17:28 vruppert Exp $

This is the top level file for the Bochs Developers 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 Developers Guide</title>
   <authorgroup>
   <author><firstname>Kevin</firstname><surname>Lawton</surname></author>
   <author><firstname>Bryce</firstname><surname>Denney</surname></author>
   <author><firstname>Christophe</firstname><surname>Bothamy</surname></author>
   <editor><firstname>Michael</firstname><surname>Calabrese</surname></editor>
   </authorgroup>
</bookinfo>

<!-- *************************************************************** -->
<chapter id="resources"><title>Resources for developers</title>
<para>
The development guide describes resources that are intended for developers
in particular.  Many Bochs resources are also covered in the User Guide,
including compile instructions, bochsrc options, how to find the mailing
lists, etc.
</para>


<section><title>Setting up CVS write access</title>
<para>
If you are an official SourceForge developer, then you can use CVS with write
access.  The CVS contains the most recent copy of the source code, and with
write access you can upload any changes you make to the CVS server for others
to use.  A few extra steps are required the first time you use CVS write
access.
</para>

<section><title>Install ssh and cvs</title>
<para>
First you need to install both cvs (Concurrent Version System) and ssh (Secure
Shell).  These are already installed on many UNIX systems and also Cygwin
(win32 platform).  If not, you can install binaries or compile cvs and ssh
yourself.  The links below should help you get going.
</para>
<itemizedlist>
<listitem> <para> CVS software and instructions are available at <ulink url="http://www.cvshome.org">www.cvshome.org</ulink>. </para> </listitem>
<listitem> <para> A free version of secure shell called OpenSSH is at <ulink url="http://www.openssh.org">www.openssh.org</ulink>. </para> </listitem>
<listitem> <para> OpenSSH requires a library called OpenSSL from <ulink url="http://www.openssl.org">www.openssl.org</ulink>.  Be sure to install OpenSSL before trying to compile OpenSSH. </para> </listitem>
</itemizedlist>
</section> 

<section><title>ssh to cvs.sf.net</title>
<para>
Next, you need to use secure shell to connect to cvs.sf.net.  This step is a
little strange, because you can't actually log in and get a shell prompt.  All
that will happen, when you get the username and password right, is that it
will create a home directory on that machine for you.  That's it!  If you try
it again, it will say "This is a restricted Shell Account.  You cannot execute
anything here."   At this point, you've succeeded and you never have to do
this step again, ever.

<screen>
  ssh <replaceable>sfusername</replaceable>@bochs.cvs.sf.net
</screen>
</para>

<para>
Replace <replaceable>sfusername</replaceable> with your Source Forge username,
of course.  The first time, you will probably get a message like 
<screen>
The authenticity of host 'cvs.sf.net' can't be established.
Are you sure you want to continue?</screen>

Just type yes.  When it asks for a password, be sure to type your source 
forge password.  If you have trouble logging in, be sure to use your SOURCE
FORGE username and password in the ssh line, which isn't necessarily the same
as your local username and password.  Add the "-v" option to ssh to see more
information about what is failing.  If you have ssh version 2, it is possible
that you might need to add "-1" to the ssh command to force it to use the
version 1 protocol.  </para> </section> 

<section><title>Set CVS_RSH environment variable to ssh</title>
<para>
Every time you connect to the Source Forge CVS server (including cvs update,
stat, commit, etc.), you must set the CVS_RSH environment variable to ssh.  So
just take the time now to add one of these lines to your .bashrc/.cshrc, so
that the CVS_RSH setting will be there every time you log in.
</para>

<screen>
  export CVS_RSH=ssh           (bash syntax)
  setenv CVS_RSH ssh           (csh syntax)
</screen>
</section> <!--end of "Set environment variable"-->

<section><title>cvs checkout</title>
<para>
Finally, you should be able to do the checkout!  If you already have a Bochs
subdirectory directory, move it out of the way because the checkout will
overwrite it.
</para>

<screen>
  export CVSROOT=":ext:<replaceable>sfusername</replaceable>@bochs.cvs.sourceforge.net:/cvsroot/bochs"
  cvs -z3 checkout bochs
  <replaceable>sfusername</replaceable>@bochs.cvs.sourceforge.net's password:        <replaceable><--type your password</replaceable>
</screen>

<para>
In the CVSROOT variable, replace <replaceable>sfusername</replaceable> with your SF username.  There's
no need to add CVSROOT to your rc files because CVS will remember it
after the checkout.  The -z3 (optional) just adds some compression to make 
the checkout go faster.  Once all the files have been downloaded, you will
have a Bochs directory which is checked out with write access!
</para>
</section> <!-- end cvs checkout -->

</section> <!-- end setting up cvs write access -->

<section id="using-cvs-write-access"><title>Using CVS write access</title>

<section><title>Checking in files</title>
<para>
Once you have a Bochs directory with cvs write access, you can compile the
files, edit them, test them, etc.  See the documentation section, "Tracking
the source code with CVS" for more info on CVS, in the User Manual.
(FIXME: add cross reference) But what's new and different is that you can now
do cvs commits.  When a file is all fixed and ready to share with the rest of
the world, you run a commit command to upload your version to the server.
First, it's good to do a cvs update to make sure nobody else has changed it
since you downloaded it last.
</para>

<screen>
  $ cvs update file.cc
  <replaceable>sfusername</replaceable>@bochs.cvs.sf.net's password:        <replaceable><--type your password</replaceable>
  $ cvs commit file.cc
  <replaceable>sfusername</replaceable>@bochs.cvs.sf.net's password:        <replaceable><--type your password</replaceable>
  [editor opens. type log message, save, and exit.]
</screen>

<para>
When CVS starts an editor, The default is usually vi.  If you want a different
editor, set the EDITOR environment variable to the name of your preferred
editor.  When you're done, just save the file and quit the editor.  Unless
there's some problem, you will see a message that says what the new revision
number for the file is, and then "done".  If while you're editing the log
message, you decide that you don't want to commit after all, don't save the
file.  Quit the editor, and when it asks where the log message went, tell it
to abort.
</para>

<para>
Here is an example of a successful checkin:

<screen>
  $ cvs commit misc.txt
  <replaceable>sfusername</replaceable>@bochs.cvs.sf.net's password:        <replaceable><--type your password</replaceable>
  [edit log msg]
  Checking in misc.txt;
  /cvsroot/bochs/bochs/doc/docbook/misc.txt,v  <--  misc.txt
  new revision: 1.6; previous revision: 1.5
  done
</screen>

And here is an aborted one:

<screen>
  $ cvs commit misc.txt
  <replaceable>sfusername</replaceable>@bochs.cvs.sf.net's password:        <replaceable><--type your password</replaceable>
  [quit editor without saving]
  Log message unchanged or not specified
  a)bort, c)ontinue, e)dit, !)reuse this message unchanged for remaining dirs
  Action: a
  cvs [commit aborted]: aborted by user
</screen>

</para>
</section> <!--end of "Checking in Files" -->

</section> <!--end of "Using CVS write access" -->

      <section id="trackers"><title>SourceForge bug, feature, and patch trackers</title>
         <para>
	 &FIXME;
         </para>
      </section>

<section id="other"><title>Ideas for other sections</title>
<para>
<screen>
Ideas:
- how to browse code with cvsweb
- how to find an identifier, variable, or specific text in the code
- how to make patches with CVS
</screen>
</para>
</section>

</chapter>

<chapter id="about-the-code"><title>About the code</title>

<section id="code-overview"><title>Overview</title>
<para>
The initial versions of some sections in this chapter are based on a document
written by Peter "Firefly" Lund. It was added and updated in January 2006.
</para>
<para>
The Bochs virtual PC consists of many pieces of hardware. At a bare minimum
there are always a CPU, a PIT (Programmable Interval Timer), a PIC
(Programmable Interrupt Controller), a DMA controller, some memory (this
includes both RAM and BIOS ROMs), a video card (usually VGA), a keyboard port
(also handles the mouse), an RTC with battery backed NVRAM, and some extra
motherboard circuitry.
</para>
<para>
There might also be a NE2K ethernet card, a PCI controller, a Sound Blaster 16,
an IDE controller (+ harddisks/CDROM), a SCSI controller (+ harddisks), a
floppy controller, an APIC ..
</para>
<para>
There may also be more than one CPU.
</para>
<para>
Most of these pieces of hardware have their own C++ class - and if Bochs is
configured to have more than one piece of a type of hardware, each will have
its own object.
</para>
<para>
The pieces of hardware communicates over a couple of buses with each other -
some of the things that the buses carry are reads and writes in memory space,
reads and writes in I/O space, interrupt requests, interrupt acknowledges, DMA
requests, DMA acknowledges, and NMI request/acknowledge. How that is simulated
is explained later.&FIXME;
</para>
<para>
Other important pieces of the puzzle are: the options object (reads/writes
configuration files, can be written to and queried while Bochs is running) and
the GUI object. There are many different but compatible implementations of the
GUI object, depending on whether you compile for X (Unix/Linux), Win32,
Macintosh (two versions: one for Mac OS X and one for older OS's), BeOS, Amiga,
etc.
</para>
<para>
And then there is the supporting cast: debugger, config menu, panic handler,
disassembler, tracer, instrumentation.
</para>
</section>

<section id="directory-structure"><title>Directory Structure</title>
<para>
<table>   
<title>Directory structure</title>
<tgroup cols="2">
<thead>
<row>
<entry>Location</entry>
<entry>Meaning</entry>
</row>
</thead>
<tbody>
<row><entry>bios</entry><entry>System and VGA BIOS images, system BIOS sources and makefile</entry></row>
<row><entry>build</entry><entry>additional stuff required for building Bochs on different platforms</entry></row>
<row><entry>bx_debug</entry><entry>the builtin Bochs debugger</entry></row>
<row><entry>cpu</entry><entry>the cpu emulation sources</entry></row>
<row><entry>disasm</entry><entry>the disassembler for the Bochs debugger</entry></row>
<row><entry>doc/docbook</entry><entry>the Bochs documentation in DocBook format</entry></row>
<row><entry>doc/man</entry><entry>Bochs manual pages</entry></row>
<row><entry>docs-html</entry><entry>old Bochs documentation in HTML (will be replaced by DocBook)</entry></row>
<row><entry>dynamic</entry><entry>empty directory (reserved for dynamic translation code)</entry></row>
<row><entry>font</entry><entry>the default VGA font used by most of the display libraries</entry></row>
<row><entry>fpu</entry><entry>the fpu emulation sources</entry></row>
<row><entry>gui</entry><entry>display libraries (guis), the simulator interface and text mode config interface</entry></row>
<row><entry>gui/bitmaps</entry><entry>bitmaps for the headerbar</entry></row>
<row><entry>gui/keymaps</entry><entry>keymaps for the keyboard mapping feature</entry></row>
<row><entry>host</entry><entry>host specific drivers (currently only used by the pcidev kernel module for Linux)</entry></row>
<row><entry>instrument</entry><entry>directory tree for the instrumentation feature</entry></row>
<row><entry>iodev</entry><entry>standard PC devices, PCI devices, lowlevel networking and sound drivers</entry></row>
<row><entry>memory</entry><entry>memory management and ROM loader</entry></row>
<row><entry>misc</entry><entry>useful utilities (e.g. bximage, bxcommit, niclist)</entry></row>
<row><entry>misc/sb16</entry><entry>tool to control the SB16 emulation from the guest side</entry></row>
<row><entry>patches</entry><entry>pending patches</entry></row>
<row><entry>plex86</entry><entry>plex86 directory structure (possibly outdated)</entry></row>
</tbody>
</tgroup>
</table>
</para>
</section>

<section id="emulator-objects"><title>Emulator Objects</title>
<section><title>Weird macros and other mysteries</title>
<para>
Bochs has many macros with inscrutable names. One might even go as far as to
say that Bochs is macro infested.
Some of them are gross speed hacks, to cover up the slow speed that C++ causes.
Others paper over differences between the simulated PC configurations.
Many of the macros exhibit the same problem as C++ does: too much stuff happens
behind the programmer's back. More explicitness would be a big win.
</para>
</section>
<section id="static-methods-hack"><title>Static methods hack</title>
<para>
C++ methods have an invisible parameter called the this pointer - otherwise the
method wouldn't know which object to operate on. In many cases in Bochs, there
will only ever be one object - so this flexibility is unnecessary. There is a
hack that can be enabled by #defining BX_USE_CPU_SMF to 1 in <filename>config.h
</filename> that makes most methods static, which means they have a "special
relationship" with the class they are declared in but apart from that are
normal C functions with no hidden parameters. Of course they still need access
to the internals of an object, so the single object of their class has a globally
visible name that these functions use. It is all hidden with macros.
</para>
<para>
Declaration of a class, from iodev/pic.h:
</para>
<screen>
...
#if BX_USE_PIC_SMF
#  define BX_PIC_SMF  static
#  define BX_PIC_THIS thePic->
#else
#  define BX_PIC_SMF
#  define BX_PIC_THIS this->
#endif
...
class bx_pic_c : public bx_pic_stub_c {

public:
  bx_pic_c(void);
  ~bx_pic_c(void);
...
  BX_PIC_SMF void   service_master_pic(void);
  BX_PIC_SMF void   service_slave_pic(void);
  BX_PIC_SMF void   clear_highest_interrupt(bx_pic_t *pic);
  };
</screen>
<para>
And iodev/pic.cc:
</para>
<screen>
...
#define LOG_THIS thePic->
...
bx_pic_c *thePic = NULL;
...
  void
bx_pic_c::service_master_pic(void)
{
  Bit8u unmasked_requests;
  int irq;
  Bit8u isr, max_irq;
  Bit8u highest_priority = BX_PIC_THIS s.master_pic.lowest_priority + 1;
  if(highest_priority > 7)
    highest_priority = 0;

  if (BX_PIC_THIS s.master_pic.INT) { /* last interrupt still not acknowleged */
    return;
    }

  if (BX_PIC_THIS s.master_pic.special_mask) {
    /* all priorities may be enabled.  check all IRR bits except ones
     * which have corresponding ISR bits set
     */
    max_irq = highest_priority;
    }
  else { /* normal mode */
    /* Find the highest priority IRQ that is enabled due to current ISR */
    isr = BX_PIC_THIS s.master_pic.isr;
...
}
...
</screen>
<para>
Ugly, isn't it? If we use static methods, methods prefixed with BX_PIC_SMF are
declared static and references to fields inside the object, which are prefixed
with BX_PIC_THIS, will use the globally visible object, thePic->. If we don't
use static methods, BX_PIC_SMF evaluates to nothing and BX_PIC_THIS becomes this->.