development.dbk

用于操作系统实现方面的调试工具

</section> <!-- Constants -->

<section> <title>Methods</title>
<para>
<emphasis>redolog_t();</emphasis> instanciates a new redolog.
</para>
<para>
<emphasis>int make_header (const char* type, Bit64u size);</emphasis> creates a header 
structure in memory, and sets its <emphasis>type</emphasis> and parameters based on the
disk image <emphasis>size</emphasis>. Returns 0.
</para>
<para>
<emphasis>int create (const char* filename, const char* type, Bit64u size);</emphasis> 
creates a new empty redolog file, with header and catalog, named <emphasis>filename</emphasis>
of type <emphasis>type</emphasis> for a <emphasis>size</emphasis> bytes image.
Returns 0 for OK or -1 if a problem occured.
</para>
<para>
<emphasis>int create (int filedes, const char* type, Bit64u size);</emphasis>
creates a new empty redolog file, with header and catalog, in a previously 
opened file described by <emphasis>filedes</emphasis>, of type <emphasis>type</emphasis> 
for a <emphasis>size</emphasis> bytes image.
Returns 0 for OK or -1 if a problem occured.
</para>
<para>
<emphasis>int open (const char* filename, const char* type, Bit64u size);</emphasis>
opens a redolog file named <emphasis>filename</emphasis>, and checks
for consistency of header values against a <emphasis>type</emphasis> and
<emphasis>size</emphasis>.
Returns 0 for OK or -1 if a problem occured.
</para>
<para>
<emphasis>void close ();</emphasis>
closes a redolog file.
</para>
<para>
<emphasis>off_t lseek (off_t offset, int whence);</emphasis>
seeks at logical data offset <emphasis>offset</emphasis> in a redolog.
<emphasis>offset</emphasis> must be a multiple of 512.
Only SEEK_SET is supported for <emphasis>whence</emphasis>.
Returns -1 if a problem occured, or the current logical offset in
the redolog.
</para>
<para>
<emphasis>ssize_t read (void* buf, size_t count);</emphasis>
reads <emphasis>count</emphasis> bytes of data of the redolog, from current logical offset,
and copies it into <emphasis>buf</emphasis>.
<emphasis>count</emphasis> must be 512.
Returns the number of bytes read, that can be 0 if the data
has not previously be written to the redolog.
</para>
<para>
<emphasis>ssize_t write (const void* buf, size_t count);</emphasis>
writes <emphasis>count</emphasis> bytes of data from <emphasis>buf</emphasis> 
to the redolog, at current logical offset.
<emphasis>count</emphasis> must be 512.
Returns the number of bytes written.
</para>

</section> 

</section> <!-- Redolog class description -->

<section>
<title>
        Disk image classes description
</title>
<para>
"volatile" and "undoable" disk images are easily implemented
by instanciating a <emphasis>default_image_t</emphasis> object (flat image) 
and a <emphasis>redolog_t</emphasis> object (redolog).
</para>
<para>
"growing" disk images only instanciates a <emphasis>redolog_t</emphasis> object.
</para>
<para>
Classe names are <emphasis>undoable_image_t</emphasis>, <emphasis>volatile_image_t</emphasis>
and <emphasis>growing_image_t</emphasis>.
</para>
<para>
When using these disk images, the underlying data structure and layout
is completely
hidden to the caller. Then, all offset and size values are "logical" values,
as if the disk was a flat file.
</para>
<section>
<title>
        Constants
</title>
<para>
<screen>
#define UNDOABLE_REDOLOG_EXTENSION ".redolog"
#define UNDOABLE_REDOLOG_EXTENSION_LENGTH (strlen(UNDOABLE_REDOLOG_EXTENSION))
#define VOLATILE_REDOLOG_EXTENSION ".XXXXXX"
#define VOLATILE_REDOLOG_EXTENSION_LENGTH (strlen(VOLATILE_REDOLOG_EXTENSION))
</screen>
These constants are used when building redolog file names
</para>
</section>

<section>
<title>
        undoable_image_t methods
</title>
<para>
<emphasis>
undoable_image_t(Bit64u size, const char* redolog_name);
</emphasis>
instanciates a new <emphasis>undoable_image_t</emphasis>
object. This disk image logical length is <emphasis>size</emphasis> bytes and
the redolog filename is <emphasis>redolog_name</emphasis>. 
</para>

<para>
<emphasis>
int open (const char* pathname);
</emphasis>
opens the flat disk image <emphasis>pathname</emphasis>,
as an undoable disk image. The associated redolog will
be named <emphasis>pathname</emphasis> with a 
<emphasis>UNDOABLE_REDOLOG_EXTENSION</emphasis>
suffix, unless set in the constructor.
Returns 0 for OK or -1 if a problem occured.
</para>

<para>
<emphasis>
void close ();
</emphasis>
closes the flat image and its redolog.
</para>

<para>
<emphasis>
off_t lseek (off_t offset, int whence);
</emphasis>
seeks at logical data position <emphasis>offset</emphasis> in
the undoable disk image. 
Only SEEK_SET is supported for <emphasis>whence</emphasis>.
Returns -1 if a problem occured, or the current logical
offset in the undoable disk image.
</para>

<para>
<emphasis>
ssize_t read (void* buf, size_t count);
</emphasis>
reads <emphasis>count</emphasis> bytes of data 
from the undoable disk image, from current logical offset,
and copies it into <emphasis>buf</emphasis>.
<emphasis>count</emphasis> must be 512.
Returns the number of bytes read.
Data will be read from the redolog if it has
been previously written or from the flat image
otherwise.
</para>

<para>
<emphasis>
ssize_t write (const void* buf, size_t count);
</emphasis>
writes <emphasis>count</emphasis> bytes of data from <emphasis>buf</emphasis> 
to the undoable disk image, at current logical offset.
<emphasis>count</emphasis> must be 512.
Returns the number of bytes written.
Data will always be written to the redolog.
</para>
</section>

<section>
<title>
        volatile_image_t methods
</title>
<para>
<emphasis>
volatile_image_t(Bit64u size, const char* redolog_name);
</emphasis>
instanciates a new <emphasis>volatile_image_t</emphasis>
object. This disk image logical length is <emphasis>size</emphasis> bytes and
the redolog filename is <emphasis>redolog_name</emphasis> plus a 
random suffix. 
</para>

<para>
<emphasis>
int open (const char* pathname);
</emphasis>
opens the flat disk image <emphasis>pathname</emphasis>,
as a volatile disk image. The associated redolog will
be named <emphasis>pathname</emphasis> with a 
random suffix, unless set in the constructor.
Returns 0 for OK or -1 if a problem occured.
</para>

<para>
<emphasis>
void close ();
</emphasis>
closes the flat image and its redolog.
The redolog is deleted/lost after close is called.
</para>

<para>
<emphasis>
off_t lseek (off_t offset, int whence);
</emphasis>
seeks at logical data position <emphasis>offset</emphasis> in
the volatile disk image. 
Only SEEK_SET is supported for <emphasis>whence</emphasis>.
Returns -1 if a problem occured, or the current logical offset in
the volatile disk image.
</para>

<para>
<emphasis>
ssize_t read (void* buf, size_t count);
</emphasis>
reads <emphasis>count</emphasis> bytes of data 
from the volatile disk image, from current logical offset,
and copies it into <emphasis>buf</emphasis>.
<emphasis>count</emphasis> must be 512.
Returns the number of bytes read.
Data will be read from the redolog if it has
been previously written or from the flat image
otherwise.
</para>

<para>
<emphasis>
ssize_t write (const void* buf, size_t count);
</emphasis>
writes <emphasis>count</emphasis> bytes of data from <emphasis>buf</emphasis> 
to the volatile disk image, at current logical offset.
<emphasis>count</emphasis> must be 512.
Returns the number of bytes written.
Data will always be written to the redolog.
</para>
</section>

<section>
<title>
        growing_image_t methods
</title>
<para>
<emphasis>
growing_image_t(Bit64u size);
</emphasis>
instanciates a new <emphasis>growing_image_t</emphasis>
object. This disk image logical length is <emphasis>size</emphasis> bytes.
</para>

<para>
<emphasis>
int open (const char* pathname);
</emphasis>
opens the growing disk image <emphasis>pathname</emphasis>,
Returns 0 for OK or -1 if a problem occured.
</para>

<para>
<emphasis>
void close ();
</emphasis>
closes the growing disk image.
</para>

<para>
<emphasis>
off_t lseek (off_t offset, int whence);
</emphasis>
seeks at logical data position <emphasis>offset</emphasis> in
the growable disk image. 
Only SEEK_SET is supported for <emphasis>whence</emphasis>.
Returns -1 if a problem occured, or the current logical offset in
the grwoing image.
</para>

<para>
<emphasis>
ssize_t read (void* buf, size_t count);
</emphasis>
reads <emphasis>count</emphasis> bytes of data 
from the growing disk image, from current logical offset,
and copies it into <emphasis>buf</emphasis>.
<emphasis>count</emphasis> must be 512.
Returns the number of bytes read.
The buffer will be filled with null bytes if data
has not been previously written to the growing image.
</para>

<para>
<emphasis>
ssize_t write (const void* buf, size_t count);
</emphasis>
writes <emphasis>count</emphasis> bytes of data from <emphasis>buf</emphasis> 
to the growing disk image, at current logical offset.
<emphasis>count</emphasis> must be 512.
Returns the number of bytes written.
</para>
</section>

</section>

</section>

<section id="add-keymapping"><title>How to add keymapping in a GUI client</title>
<para>
Christophe Bothamy, wrote the keymapping code for Bochs, provided these
instructions to help developers to add keymapping to a GUI.
</para>

<screen>
Bochs creates a bx_keymap_c object named bx_keymap.
This object allows you to :
  - load the configuration specified keymap file
  - get the translated BX_KEY_* from your GUI key

You have to provide a translation function from string to your Bit32u key
constant. Casting will be necessary if your key constants are not Bit32u typed.
The function must be "static Bit32u (*)(const char *)" typed, and must return
BX_KEYMAP_UNKNOWN if it can not translate the parameter string.

What you have to do is :
  - call once "void loadKeymap(Bit32u (*)(const char*))", 
    providing your translation function, to load the keymap
  - call "Bit32u getBXKey(Bit32u)" that returns the BX_KEY_*
    constant, for each key you want to map.

The file gui/x.cc implements this architecture, so you can refer to it
as an example.
</screen>

</section>

</chapter>

<chapter id="debugger"><title>Debugger</title>
      <section><title>compile with debugger support</title>
      <para>
      &FIXME;
      </para>
      </section>
      <section id="debugger-get-started"><title>get started in debugger</title>
      <para>
      &FIXME;
      </para>
      </section>
      <section id="debugger-commands"><title>command reference</title>
      <para>
      &FIXME;
      </para>
      </section>
      <section id="debugger-techniques"><title>techniques</title>
      <para>
      &FIXME;
      </para>
      </section>
</chapter>

<chapter id="coding"><title>Coding</title>
<section><title>Coding guidelines</title>
<para>
<itemizedlist>
<listitem><para><command>Don't make use of any external C++ classes.</command></para>
<para>They are not offered on all platforms and this would make bochs non-portable.
There is use of such classes in the optional debugger. I plan on removing this use.
</para></listitem>
<listitem><para><command>Don't use fancy C++ features.</command></para>
<para>Bochs is incredibly performance sensitive, and will be increasingly so as
more speed enhancements are added. There's a time and place for most everything
and this is not it. Some advanced features create overhead in the generated code
that you don't see. They also convolute the code, and sometimes occlude that is
really going on.
<itemizedlist>
<listitem><para>Don't use templates</para></listitem>
<listitem><para>Don't use virtual functions if not strictly required</para></listitem>
<listitem><para>Don't use C++ exceptions</para></listitem>
<listitem><para>Don't use overloading of any kind</para></listitem>
</itemizedlist></para></listitem>
<listitem><para><command>Use soft tabs.</command></para>
<para>At least when you submit code, convert all hard tabs to spaces.
There is no uniform way to handle tabs properly.</para></listitem>
<listitem><para><command>Please do compile with all warnings turned on.</command></para>
<para>It's really difficult to spot interesting warnings when a compile is littered
with non-interesting ones.</para></listitem>
<listitem><para><command>Don't use signed ints where unsigned will do.</command></para></listitem>
<listitem><para><command>Make sure that contributed code / patches are LGPL compatible.</command></para></li