development.dbk

通过对一个教学操作系统GEEKOS的编译过程

<listitem><para>
<emphasis>length</emphasis> is the number of data bytes that
are contained in the data structure. This does <emphasis>not</emphasis> include the status
byte which is not replicated in the data array. It can only be greater
than 3 for SysEx messages (commands <emphasis>0xF0</emphasis> and <emphasis>0xF7</emphasis>)
</para></listitem>

<listitem><para>
<emphasis>data[]</emphasis> is the array of these data bytes,
in the order they have in the standard MIDI specification.
Note, it might be <emphasis>NULL</emphasis> if length==0.
</para></listitem>
</itemizedlist>
</section>


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

<para>
<emphasis>closemidioutput()</emphasis> is called before shutting down Bochs or 
when the
emulator gets the <emphasis>stop_output</emphasis> command through the emulator port.
After this, no more output will be necessary until <emphasis>openmidioutput()</emphasis>
is called again, but <emphasis>midiready()</emphasis> might still be called. It should do the following:
</para>

<itemizedlist>
<listitem><para>
Wait for all remaining messages to be completed
</para></listitem>
<listitem><para>
Reset and close the midi output device
</para></listitem>
</itemizedlist>
</section>


<section><title>int openwaveoutput(char *device)</title>

<para>
<emphasis>openwaveoutput()</emphasis> is called when the first wave output occurs,
and only if the selected wavemode is 1. It should do the following:
</para>

<itemizedlist>
<listitem><para>
Open the given device, and prepare it for wave output
</para></listitem>
</itemizedlist>
<para>
<emphasis>or</emphasis>
</para>
<itemizedlist>
<listitem><para>
Store the device name so that the device can be opened in <emphasis>startplayback()</emphasis>.
</para></listitem>
</itemizedlist>

<para>
<emphasis>openmidioutput()</emphasis> will always be called before <emphasis>openwaveoutput()</emphasis>,
and <emphasis>closemidioutput()</emphasis>will always be called before <emphasis>closewaveoutput()</emphasis>, but not in all cases will both functions be called.
</para>

<para>
<emphasis>openwaveoutput()</emphasis> will typically be called once, whereas
<emphasis>startplayback()</emphasis> is called for every new DMA transfer to the SB16 emulation. If feasible,
it could be useful to open and/or lock the output device in
<emphasis>startplayback()</emphasis> as opposed to <emphasis>openwaveoutput()</emphasis>
to ensure that it can be used by other applications while Bochs doesn't
need it.
</para>

<para>
However, many older applications don't use the auto-init DMA
mode, which means that they start a new DMA transfer for every single
block of output, which means usually for every 2048 bytes or so.
Unfortunately there is no way of knowing whether the application will
restart an expired DMA transfer soon, so that in these cases the
<emphasis>startwaveplayback</emphasis> function will be called very often, and it
isn't a good idea to have it reopen the device every time.
</para>

<para>The buffer when writing to the device should not be overly large.
Usually about four buffers of 4096 bytes produce best results. Smaller
buffers could mean too much overhead, while larger buffers contribute
to the fact that the actual output will always be late when the application
tries to synchronize it with for example graphics.
</para>

<para>The parameters are the following: </para>

<itemizedlist>
<listitem><para>
<emphasis>device</emphasis> is the wave device selected by
the user. It is strictly system-dependent. The value is that of the
<emphasis>WAVE=device</emphasis>
configuration option.
</para></listitem>
</itemizedlist>

<para>
Note that only one wave output device will be used at any one time.
<emphasis>device</emphasis> may not have the same value throughout one session, but it will be closed
before it is changed.
</para>
</section>

<section>
<title>int startwaveplayback(int frequency, int bits, int stereo, int format)</title>

<para>
This function is called whenever the application starts a new DMA transfer.  It should do the following:
</para>

<itemizedlist>
<listitem><para>
Open the wave output device, unless <emphasis>openwaveoutput()</emphasis> did that
already
</para></listitem>

<listitem><para>
Prepare the device for data and set the device parameters to those given
in the function call
</para></listitem>
</itemizedlist>

<para>
The parameters are the following:
</para>

<itemizedlist>
<listitem><para>
<emphasis>frequency</emphasis> is the desired frequency of the
output. Because of the capabities of the SB16, it can have any value between
5000 and 44,100.
</para></listitem>

<listitem><para>
<emphasis>bits</emphasis> is either 8 or 16, denoting the resolution
of one sample.
</para></listitem>

<listitem><para>
<emphasis>stereo</emphasis> is either 1 for stereo output, or 0 for mono output.
</para></listitem>

<listitem><para>
<emphasis>format</emphasis> is a bit-coded value (see below).
</para></listitem>
</itemizedlist>
</section>

<section>
<title>Format Bits</title>
<para>
&FIXME; Insert FORMAT BITS table here 
</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:
</para>
</section>

<section>
<title>Sequences of Databytes Table</title>
<para>
&FIXME; Insert Sequences of Databytes table here
</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-->

</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 conventions</title>
      <para>
      &FIXME;
      </para>
      </section>
      <section id="patches"><title>patches:</title>
      <para>
      &FIXME;
      how to make, where to submit, what happens then?
      </para
      </section>

      <section id="cvs-release"><title>life cycle of a CVS release</title>
      <para>
      &FIXME;
      </para>
      </section>

</chapter>
</book>