development.dbk

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

<para>
A wavetable synthesizer on /dev/midi00 and a working /dev/dsp 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 /dev/midi00. 
</para>
</section>

<section><title>Configuring bochs</title>

<para>
There are a few values in config.h that are relevant to the sound functions.
Edit config.h 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 .bochsrc, according to instructions
in that file.
</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 emulator is included in
misc/sb16. You can compile it or download the
<ulink url="http://publish.uwo.ca/~jdrexler/bochs/">executable</ulink>.
</para>

<para>
<emphasis>misc/sb16/</emphasis> contains a C program that can be run inside the emulator, and the
executable for DOS. It currently supports the following commands:
</para>

<para>
&FIXME; number, six numbers, some numbers, and filename below should be in tags
</para>

<programlisting>
-i number: shows the selected emulator info string,
        e.g. sb16ctrl -i 3 to show how many patch translations are active

-t six numbers: loads 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. sb16ctrl -t 255,255,0,255,255,32
        to change patch 0 (Piano) to patch 32 (Acoustic Bass)

-r: Reset the patch translation table
        e.g. sb16ctrl -r

-m some numbers: 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. sb16ctrl -m 0x80,64,0
        to send a note-off message to channel 0.

-f filename: Reads in a file and executes 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 "#".

-h: Show a brief summary of the commands.
</programlisting>

<para>
All numbers can be valid parameters to the strtol() 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><title>Features planned for the future</title>
<itemizedlist>
<listitem><para>Ports to more OS's, but I can't do this myself</para></listitem>
<listitem><para>Finishing 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>
This file is intended for programmers who would like to port the sound
output routines to their platform. It gives a short outline what services
have to be provided.
</para>
<para>
You should also have a look at the exisiting files, <emphasis>SOUNDLNX.CC</emphasis>
for Linux and <emphasis>SOUNDWIN.CC</emphasis> for Windows and their respective
header files to get an idea about how these things really work.
</para>
</section>

<section><title>Files</title>

<para>
The main include file is <emphasis>bochs.h</emphasis>. It has all definitions 
for the system-independent functions that the SB16 emulation uses, which
are defined in <emphasis>sb16.h</emphasis>.
</para>

<para>
Additionally, every output driver will have an include file, which
should be included at the end of sb16.h to allow the emulator
to use that driver.
</para>

<para>
To actually make the emulator use any specific driver, 
<emphasis>BX_SOUND_OUTPUT_C</emphasis> has to be set to the name of the respective
output class.
</para>

<para>
Note that if your class contains any system-specific statements,
include-files and so on, you should enclose both the include-file and
the CC-file in an <emphasis>#if defined</emphasis> (OS-define) construct.
Also don't forget to add your file to the object list in
iodev/Makefile and iodev/Makefile.in.
</para>
</section>

<section><title>Classes</title>

<para>
The following classes are involved with the SB16 emulation:
</para>
<itemizedlist>
<listitem><para>
<emphasis>bx_sb16_c</emphasis> is the class containing the emulator itself, that
is the part acting on port accesses by the application, handling the
DMA transfers and so on. It also prepares the data for the output
classes.
</para></listitem>

<listitem><para>
<emphasis>bx_sound_output_c</emphasis> is the base output class. It has all
the methods used by the emulator, but only as stubs and does not
actually produce any output. These methods are then called by
the emulator whenever output is necessary.
</para></listitem>

<listitem><para>
<emphasis>bx_sound_OS_c</emphasis> is derived from 
<emphasis>bx_sound_output_c</emphasis>. It contains the code to generate 
output for the <emphasis>OS</emphasis> operating system. 
It is necessary to override all
the methods defined in the base class, unless virtual functions
are used. Note that this should remain an option, so try to
override all methods, even if only as stubs. They should be
declared <emphasis>virtual</emphasis> if and only if <emphasis>BX_USE_SOUND_VIRTUAL</emphasis>
is defined, just as in the examples. 
The constructor should call the inherited constructor
as usual, even though the current constructor does not do
anything yet.
</para></listitem>
</itemizedlist>
</section>


<section><title>Methods</title>
<para>
The following are the methods that the output class has to override.
All but constructor and destructor have to return either
<emphasis>BX_SOUND_OUTPUT_OK</emphasis> <emphasis>(0)</emphasis> if the function was successful, 
or <emphasis>BX_SOUND_OUTPUT_ERR</emphasis> <emphasis>(1)</emphasis> if not. If any of the initialization
functions fail, output to that device is disabled until the emulator is restarted.
</para>
</section>

<section><title>bx_sound_OS_c(bx_sb16_c*sb16)</title>

<para>
The emulator instantiates the class at the initialization of Bochs.
</para>

<para>
Description of the parameter:
</para>

<itemizedlist>
<listitem><para>
<emphasis>sb16</emphasis> is a pointer to the emulator class. 
This pointer can then be used to access for example the <emphasis>writelog</emphasis> function to generate
sound-related log messages. Apart from that, no access to the emulator
should be necessary.
</para></listitem>

<listitem><para>
The constructor should <emphasis>not</emphasis> allocate the output devices. 
This shouldn't be done until the actual output occurs; in either 
<emphasis>initmidioutput()</emphasis> or <emphasis>initwaveoutput()</emphasis>.
Otherwise it would be impossible to have two copies of Bochs running 
concurrently (if anybody ever wants to do this).
</para></listitem>
</itemizedlist>
</section>

<section><title>~bx_sound_OS_c()</title>

<para>
The instance is destroyed just before Bochs ends.
</para>
</section>

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

<itemizedlist>
<listitem><para>
<emphasis>openmidioutput()</emphasis> is called when the first midi output starts.
It is only called if the midi output mode is 1 (midimode 1). It should
prepare the given MIDI hardware for receiving midi commands.
</para></listitem>

<listitem><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></listitem>
</itemizedlist>
</section>

<section>
<title>Description of the parameters:</title>

<itemizedlist>

<listitem><para>
<emphasis>device</emphasis> is a system-dependent variable.
It contains the value of the <emphasis>MIDI=device</emphasis> configuration option.
</para></listitem>

<listitem><para>
Note that only one midi 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></listitem>
</itemizedlist>
</section>

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

<para>
<emphasis>midiready()</emphasis> is called whenever the applications asks if the
midi queue can accept more data. 
</para>

<para>
Return values:
</para>

<itemizedlist>
<listitem><para>
<emphasis>BX_SOUND_OUTPUT_OK</emphasis> if the midi output device is ready.  
</para></listitem>

<listitem><para>
<emphasis>BX_SOUND_OUTPUT_ERR</emphasis> if it isn't ready.  
</para></listitem>
</itemizedlist>

<para>
<emphasis>Note: </emphasis><emphasis>midiready()</emphasis> will be called a few times
<emphasis>before</emphasis> the device is opened. If this is the case, it should
always report that it is ready, otherwise the application (not Bochs)
will hang.
</para>
</section>

<section><title>int sendmidicommand(int delta, int command, int length, Bit8u data[])</title>

<para>
<emphasis>sendmidicommand()</emphasis>is called whenever a complete midi command has
been written to the emulator. It should then send the given midi command to the midi hardware.
It will only be called after the midi output has been opened. Note that
if at all possible it should not wait for the completion of the command
and instead indicate that the device is not ready during the execution
of the command. This is to avoid delays in the program while it is
generating midi output.
</para>

<para>
Description of the parameters:
</para>

<itemizedlist>
<listitem><para>
<emphasis>delta</emphasis> is the number of delta ticks that
have passed since the last command has been issued. It is always zero for
the first command. There are 24 delta ticks per quarter, and 120 quarters
per minute, thus 48 delta ticks per second.
</para></listitem>

<listitem><para>
<emphasis>command</emphasis> is the midi command byte (sometimes
called status byte), in the usual range of 0x80..0xff. For more information
please see the midi standard specification.
</para></listitem>