development.dbk

Bochs这个虚拟机的源代码。学习虚拟机的编写和操作系统的编写有帮助。

</table>
</para>
<para>
Other codecs are not supported by the SB hardware. In fact, most applications will
translate their data into raw data, so that in most cases the codec will be zero.
</para>
<para>
The number of bytes per sample can be calculated from this as (bits / 8) * (stereo + 1).
</para>
</section>


<section>
<title>int waveready()</title>

<para>
This is called whenever the emulator has another output buffer ready
and would like to pass it to the output class. This happens every
<emphasis>BX_SOUND_OUTPUT_WAVEPACKETSIZE</emphasis> bytes, or whenever a DMA transfer
is done or aborted.
</para>

<para>
It should return whether the output device is ready for another buffer
of <emphasis>BX_SOUND_OUTPUT_WAVEPACKETSIZE</emphasis> bytes. 
If <emphasis>BX_SOUND_OUTPUT_ERR</emphasis>
is returned, the emulator waits about 1/(frequency * bytes per sample) seconds 
and then asks again. The DMA transfer is stalled during that time, but
the application keeps running, until the output device becomes ready.
</para>

<para>
As opposed to <emphasis>midiready(), waveready()</emphasis> will <emphasis>not</emphasis> be
called unless the device is open.
</para>
</section>

<section>
<title>int sendwavepacket(int length, Bit8u data[])</title>

<para>
This function is called whenever a data packet of at most <emphasis>BX_SB16_WAVEPACKETSIZE</emphasis>
is ready at the SB16 emulator. It should then do the following:
</para>

<itemizedlist>
<listitem><para>
Send this wave packet to the wave hardware
</para></listitem>
</itemizedlist>

<para>
This function <emphasis>has</emphasis> to be synchronous, meaning that it <emphasis>has</emphasis>
to return immediately, and <emphasis>not</emphasis> wait until the output is done. Also,
this function might be called before the previous output is done. If your
hardware can't append the new output to the old one, you will have to implement
this yourself, or the output will be very chunky, with as much silence
between the blocks as the blocks take to play. This is not what you want.
Instead, <emphasis>waveready()</emphasis> should return <emphasis>BX_SOUND_OUTPUT_ERR</emphasis>
until the device accepts another block of data.
</para>

<para>
Parameters:
</para>

<itemizedlist>
<listitem><para>
<emphasis>length</emphasis> is the number of data bytes in
the data stream. It will never be larger than <emphasis>BX_SB16_WAVEPACKETSIZE</emphasis>.
</para></listitem>

<listitem><para>
<emphasis>data</emphasis> is the array of data bytes.
</para></listitem>
</itemizedlist>

<para>
The order of bytes in the data stream is the same as that in the Wave file format:

<table>   
<title>wave output types</title>
<tgroup cols="2">
<thead>
<row>
<entry>Output type</entry>
<entry>Sequence of data bytes</entry>
</row>
</thead>
<tbody>
<row> <entry> 8 bit mono </entry><entry> Sample 1; Sample 2; Sample 3; etc. </entry> </row>
<row> <entry> 8 bit stereo </entry><entry> Sample 1, Channel 0; Sample 1, Channel 1; Sample 2, Channel 0; Sample 2, Channel 1; etc. </entry> </row>
<row> <entry> 16 bit mono </entry><entry> Sample 1, LSB; Sample 1, MSB; Sample 2, LSB; Sample 2, MSB; etc. </entry> </row>
<row> <entry> 16 bit stereo </entry><entry> Sample 1, LSB, Channel 0; Sample 1, MSB, Channel 0; Sample 1, LSB, Channel 1; Sample 1, MSB, Channel 1; etc. </entry> </row>
</tbody>
</tgroup>
</table>
</para>

<para>
Typically 8 bit data will be unsigned with values from 0 to 255, and
16 bit data will be signed with values from -32768 to 32767, although the
SB16 is not limited to this. For further information on the codecs and
the use of reference bytes please refer to the Creative Labs Sound Blaster
Programmer's Manual, which can be downloaded from the Creative Labs web
site.
</para>
</section>

<section><title>int stopwaveplayback()</title>

<para>
This function is called at the end of a DMA transfer. It should do the following:
</para>

<itemizedlist>
<listitem><para>
Close the output device if it was opened by <emphasis>startwaveplayback()</emphasis>.
and it's not going to be opened soon. Which is almost impossible to tell.
</para></listitem>
</itemizedlist>
</section>

<section><title>int closewaveoutput()</title>

<para>
This function is called just before Bochs exits. It should do the following:
</para>

<itemizedlist>
<listitem><para>
 Close the output device, if this hasn't been done by <emphasis>stopwaveplayback()</emphasis>.
</para></listitem>
</itemizedlist>

<para>
Typically, <emphasis>stopwaveplayback()</emphasis> will be called several times, whenever
a DMA transfer is done, where <emphasis>closewaveoutput()</emphasis> will only be called
once. However, in the future it might be possible that <emphasis>openwaveoutput()</emphasis>
is called again, for example if the user chose to switch devices while
Bochs was running. This is not supported at the moment, but might be in
the future.
</para>
</section>

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

<section id="harddisk-redologs"><title>Harddisk Images based on redologs</title>
<para>
This section describes how the three new disk images "undoable", "growing", and "volatile" are 
implemented in Bochs 2.1 :
</para>
<itemizedlist>
<listitem><para>
undoable -> flat file, plus growing, commitable, rollbackable redolog file
</para></listitem>
<listitem><para>
growing  -> growing files, all previously unwritten sectors go to the end of file
</para></listitem>
<listitem><para>
volatile -> flat file, plus hidden growing redolog
</para></listitem>
</itemizedlist>

<para>
</para>

<section>
<title>
        Description
</title>
<para>
The idea behind volatile and undoable disk images 
is to have a flat file, associated with one redolog file. 
</para>
<para>
Reading a sector is done from the redolog file if it contains 
the sector, or from the flat file otherwise. 
</para>
<para>
Sectors written go to the redolog,
so flat files are opened in read only mode in this configuration.
</para>
<para>
The redolog is designed in a way so it starts as a small file
and grows with every new sectors written to it. Previously written
sectors are done in place. Redolog files can not shrink.
</para>
<para>
The redolog is a growing file that can be created on the fly.
</para>
<para>
Now, it turns out that if you only use a redolog without any 
flat file, you get a "growing" disk image.
</para>
<para>
So "undoable", "volatile" and "growing" harddisk images classes
are implemented on top of a redolog class.
</para>
</section>

<section>
<title>
        How redologs works ?
</title>

<para>
At the start of a redolog file, there is a header, so Bochs can check whether
a file is consistent. 
This header could also be checked when we implement
automatic type and size detection.
</para>
<para>
The generic part of the header contains values like type of image, and
spec version number.
</para>
<para>
The header also has a specific part.
For redologs, the number
of entries of the catalog, the extent, bitmap and disk size are stored.
</para>

<para>
In a redolog, the disk image is divided in a number of equal size "extents".
Each extent is a collection of successive 512-bytes sectors of the disk image,
preceeded by a n*512bytes bitmap. 
</para>

<para>
the n*512bytes bitmap defines the presence (data has been written to it)
of a specific sector in the extent, one bit for each sector.
Therefore with a 512bytes bitmap, each extent can hold up to 4k blocks
</para>

<para>
Typically the catalog can have 256k entries.
With a 256k entries catalog and 512bytes bitmaps, the redolog can hold up to 512GiB
</para>

<note>
<para>
All data is stored on images as little-endian values
</para>
</note>
<section>
<title>
        Header
</title>
<para>
At the start of a redolog file, there is a header. This header is designed
to be reusable by other disk image types.
</para>
<para>
The header length is 512 bytes. It contains :
<table>   
<title>Generic header description</title>
<tgroup cols="5">
<thead>
<row>
<entry>Start position in bytes</entry>
<entry>Length in bytes</entry>
<entry>Data type</entry>
<entry>Description</entry>
<entry>Possible values</entry>
</row>
</thead>
<tbody>
<row> <entry> 0 </entry> <entry> 32 </entry> <entry> string </entry> <entry> magical value </entry> <entry> Bochs Virtual HD Image </entry> </row>
<row> <entry> 32 </entry> <entry> 16 </entry> <entry> string </entry> <entry> type of file </entry> <entry> Redolog </entry> </row>
<row> <entry> 48 </entry> <entry> 16 </entry> <entry> string </entry> <entry> subtype of file </entry> <entry> Undoable, Volatile, Growing </entry> </row>
<row> <entry> 64 </entry> <entry> 4 </entry> <entry> Bit32u </entry> <entry> version of used specification </entry> <entry> 0x00010000 </entry> </row>
<row> <entry> 68 </entry> <entry> 4 </entry> <entry> Bit32u </entry> <entry> header size </entry> <entry> 512 </entry> </row>
</tbody>
</tgroup>
</table>
<table>   
<title>Redolog specific header description</title>
<tgroup cols="5">
<thead>
<row>
<entry>Start position in bytes</entry>
<entry>Length in bytes</entry>
<entry>Data type</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row> <entry> 72 </entry> <entry> 4 </entry> <entry> Bit32u </entry> <entry> number of entries in the catalog </entry> </row>
<row> <entry> 76 </entry> <entry> 4 </entry> <entry> Bit32u </entry> <entry> bitmap size in bytes </entry> </row>
<row> <entry> 80 </entry> <entry> 4 </entry> <entry> Bit32u </entry> <entry> extent size in bytes</entry> </row>
<row> <entry> 84 </entry> <entry> 8 </entry> <entry> Bit64u </entry> <entry> disk size in bytes </entry> </row>
</tbody>
</tgroup>
</table>
</para>
</section>
<section>
<title>
        Catalog
</title>
<para>
Immediately following the header, there is a catalog containing
the position number (in extents) where each extent is located in the file.
</para>
<para>
Each position is a Bit32u entity.
</para>

</section>
<section>
<title>
        Extent
</title>
<para>
	 &FIXME;
</para>
</section>
</section>

<section>
<title>Parameters
</title>
<para>
The following tables shows what paremeters are used when creating redologs or creating 間rowing" images :
<table>   
<title>
        How number of entries in the catalog and number of blocks by extents are computed
</title>
<tgroup cols="5">
<thead>
<row>
<entry>Catalog entries</entry> <entry>Catalog size(KiB)</entry> <entry>Bitmap size (B)</entry> <entry>Extent size (KiB)</entry> <entry>Disk Max Size</entry>
</row>
</thead>

<tbody>
<row>
<entry>512</entry> <entry>2</entry> <entry>1</entry> <entry>4</entry> <entry>2MiB</entry>
</row>
<row>
<entry>512</entry> <entry>2</entry> <entry>2</entry> <entry>8</entry> <entry>4MiB</entry>
</row>
<row>
<entry>1k</entry> <entry>4</entry> <entry>2</entry> <entry>8</entry> <entry>8MiB</entry>
</row>
<row>
<entry>1k</entry> <entry>4</entry> <entry>4</entry> <entry>16</entry> <entry>16MiB</entry>
</row>
<row>
<entry>2k</entry> <entry>8</entry> <entry>4</entry> <entry>16</entry> <entry>32MiB</entry>
</row>
<row>
<entry>2k</entry> <entry>8</entry> <entry>8</entry> <entry>32</entry> <entry>64MiB</entry>
</row>
<row>
<entry>4k</entry> <entry>16</entry> <entry>8</entry> <entry>32</entry> <entry>128MiB</entry>
</row>
<row>
<entry>4k</entry> <entry>16</entry> <entry>16</entry> <entry>64</entry> <entry>256MiB</entry>
</row>
<row>
<entry>8k</entry> <entry>32</entry> <entry>16</entry> <entry>64</entry> <entry>512MiB</entry>
</row>
<row>
<entry>8k</entry> <entry>32</entry> <entry>32</entry> <entry>128</entry> <entry>1GiB</entry>
</row>
<row>
<entry>16k</entry> <entry>64</entry> <entry>32</entry> <entry>128</entry> <entry>2GiB</entry>
</row>
<row>
<entry>16k</entry> <entry>64</entry> <entry>64</entry> <entry>256</entry> <entry>4GiB</entry>
</row>
<row>
<entry>32k</entry> <entry>128</entry> <entry>64</entry> <entry>256</entry> <entry>8GiB</entry>
</row>
<row>
<entry>32k</entry> <entry>128</entry> <entry>128</entry> <entry>512</entry> <entry>16GiB</entry>
</row>
<row>
<entry>64k</entry> <entry>256</entry> <entry>128</entry> <entry>512</entry> <entry>32GiB</entry>
</row>
<row>
<entry>64k</entry> <entry>256</entry> <entry>256</entry> <entry>1024</entry> <entry>64GiB</entry>
</row>
<row>
<entry>128k</entry> <entry>512</entry> <entry>256</entry> <entry>1024</entry> <entry>128GiB</entry>
</row>
<row>
<entry>128k</entry> <entry>512</entry> <entry>512</entry> <entry>2048</entry> <entry>256GiB</entry>
</row>
<row>
<entry>256k</entry> <entry>1024</entry> <entry>512</entry> <entry>2048</entry> <entry>512GiB</entry>
</row>
<row>
<entry>256k</entry> <entry>1024</entry> <entry>1024</entry> <entry>4096</entry> <entry>1TiB</entry>
</row>
<row>
<entry>512k</entry> <entry>2048</entry> <entry>1024</entry> <entry>4096</entry> <entry>2TiB</entry>
</row>
<row>
<entry>512k</entry> <entry>2048</entry> <entry>2048</entry> <entry>8192</entry> <entry>4TiB</entry>
</row>
<row>
<entry>1024k</entry> <entry>4096</entry> <entry>2048</entry> <entry>8192</entry> <entry>8TiB</entry>
</row>
<row>