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.
You should also have a look at the exisiting files, SOUNDMOD.CC and e.g. SOUNDLNX.CC for Linux or SOUNDWIN.CC for Windows and their respective header files to get an idea about how these things really work.
The main include file for a lowlevel sound driver is iodev.h. It has all definitions for the system-independent functions that a sound driver uses. The sound driver also needs to include soundmod.h for the definition of the base class bx_sound_output_c.
Additionally, every output driver will have an include file, which should be included on top of soundmod.cc to allow the emulator to use that driver. A soundcard does not need to include the specific driver header.
To actually make the emulator use any specific driver as the default, BX_SOUND_LOWLEVEL_C has to be set to the name of the respective output class.
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 #if defined (OS-define) construct. Also don't forget to add your file to the list of lowlevel sound object files (SOUNDLOW_OBJS) in the file configure.in and to regenerate the configure script,
The following classes are involved with the sound lowlevel interface:
bx_soundmod_ctl_c is a pseudo device that is used to initialize the sound driver depending on the configuration. In addition to this, it has methods for the PC speaker beep generation and the VOC file output.
bx_sound_output_c is the base output class. It has all the methods used by the soundcard emulation, but only as stubs and does not actually produce any output. These methods are then called by the emulator whenever output is necessary.
bx_sound_OS_c is derived from bx_sound_output_c. It contains the code to generate output for the OS operating system. It is not necessary to override all the methods defined in the base class, since virtual functions are used. The constructor should call the inherited constructor as usual, even though the current constructor does not do anything yet.
class bx_sound_lowlevel_c : public logfunctions {
public:
bx_sound_lowlevel_c();
virtual ~bx_sound_lowlevel_c();
virtual int get_type() {return BX_SOUNDLOW_DUMMY;}
virtual int waveready();
virtual int midiready();
virtual int openmidioutput(const char *mididev);
virtual int sendmidicommand(int delta, int command, int length, Bit8u data[]);
virtual int closemidioutput();
virtual int openwaveoutput(const char *wavedev);
virtual int startwaveplayback(int frequency, int bits, bx_bool stereo, int format);
virtual int sendwavepacket(int length, Bit8u data[]);
virtual int stopwaveplayback();
virtual int closewaveoutput();
virtual int openwaveinput(const char *wavedev, sound_record_handler_t rh);
virtual int startwaverecord(int frequency, int bits, bx_bool stereo, int format);
virtual int getwavepacket(int length, Bit8u data[]);
virtual int stopwaverecord();
virtual int closewaveinput();
static void record_timer_handler(void *);
void record_timer(void);
protected:
int record_timer_index;
int record_packet_size;
sound_record_handler_t record_handler;
};
The base class for sound lowlevel support is derived from the logfunctions
class to make the Bochs logging capabilities available in the sound driver code.
It contains the framework for wave input (recording) support. The base class is
in use if the "dummy" sound driver is selected or in case no platform or library
specific implementation is available.The following are the methods that the sound driver class has to override. All but constructor and destructor have to return either BX_SOUNDLOW_OK (0) if the function was successful, or BX_SOUNDLOW_ERR (1) if not. If any of the initialization functions fail, output to that device is disabled until the emulator is restarted.
The emulator instantiates the class at the initialization of Bochs.
The constructor should not allocate the output devices. This shouldn't be done until the actual output occurs; in either openmidioutput() or openwaveoutput(). Otherwise it would be impossible to have two copies of Bochs running concurrently (if anybody ever wants to do this).
The instance is destroyed just before Bochs ends.
Returns.the ID of the sound driver module. The default value is BX_SOUNDLOW_DUMMY. New values should be added to the list in soundmod.h.
openmidioutput() is called when the first midi output starts. It is only called if the midi output to the driver is active (midimode 1). It should prepare the given MIDI hardware for receiving midi commands.
Description of the parameters:
device is a system-dependent variable. It contains the value of the MIDI=device configuration option.
Note that only one midi output device will be used at any one time. device may not have the same value throughout one session, but it will be closed before it is changed.
midiready() is called whenever the applications asks if the midi queue can accept more data.
Return values:
BX_SOUNDLOW_OK if the midi output device is ready.
BX_SOUNDLOW_ERR if it isn't ready.
Note: midiready() will be called a few times before the device is opened. If this is the case, it should always report that it is ready, otherwise the application (not Bochs) will hang.
sendmidicommand()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.
Description of the parameters:
delta 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.
command 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.
length is the number of data bytes that are contained in the data structure. This does not include the status byte which is not replicated in the data array. It can only be greater than 3 for SysEx messages (commands 0xF0 and 0xF7)
data[] is the array of these data bytes, in the order they have in the standard MIDI specification. Note, it might be NULL if length==0.
closemidioutput() is called before shutting down Bochs or when the emulator gets the stop_output command through the emulator port. After this, no more output will be necessary until openmidioutput() is called again, but midiready() might still be called. It should do the following:
Wait for all remaining messages to be completed
Reset and close the midi output device
openwaveoutput() is called when the sound subsystem initializes. It should do the following:
Open the given device, and prepare it for wave output
or
Store the device name so that the device can be opened in startwaveplayback().
openwaveoutput() will only be called once, whereas startwaveplayback() is called for every new wave output command to the soundcard emulation. If feasible, it could be useful to open and/or lock the output device in startwaveplayback() as opposed to openwaveoutput() to ensure that it can be used by other applications while Bochs doesn't need it.
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 startwaveplayback function will be called very often, and it isn't a good idea to have it reopen the device every time.
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.
The parameters are the following:
device is the wave device selected by the user. It is strictly system-dependent. The value is that of the waveout=device configuration parameter of the sound bochsrc option.
Note that only one wave output device will be used at any one time. device may not have the same value throughout one session, but it will be closed before it is changed.
This function is called whenever the emulator receives a new wave output command. It should do the following:
Open the wave output device, unless openwaveoutput() did that already
Prepare the device for data and set the device parameters to those given in the function call
The parameters are the following:
frequency is the desired frequency of the output. Because of the capabities of the soundcards, it can have any value between 5000 and 44,100.
bits is either 8 or 16, denoting the resolution of one sample.
stereo is either 1 for stereo output, or 0 for mono output.
format is a bit-coded value (see below).
Table 2-4. format bits
| Bit number | Meaning |
|---|---|
| 0 (LSB) | 0: unsigned data 1: signed data |
| 1..6 | Type of codec (see below) |
| 7 | 0: no reference byte 1: with reference byte |
| 8..x | reserved (0) |
Table 2-5. codecs
| Value | Meaning |
|---|---|
| 0 | PCM (raw data) |
| 1 | reserved |
| 2 | 2-bit ADPCM (Creative Labs format) |
| 3 | 2.4-bit (3-bit) ADPCM (Creative Labs format) |
| 4 | 4-bit ADPCM (Creative Labs format) |
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.
The number of bytes per sample can be calculated from this as (bits / 8) * (stereo + 1).
This is called whenever the emulator has another output buffer ready and would like to pass it to the output class. This happens every BX_SOUNDLOW_WAVEPACKETSIZE bytes, or whenever a DMA transfer is done or aborted.
It should return whether the output device is ready for another buffer of BX_SOUNDLOW_WAVEPACKETSIZE bytes. If BX_SOUNDLOW_ERR 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.
As opposed to midiready(), waveready() will not be called unless the device is open.
This function is called whenever a data packet of at most BX_SOUNDLOW_WAVEPACKETSIZE is ready at the soundcard emulation. It should then do the following:
Send this wave packet to the wave hardware
This function has to be synchronous, meaning that it has to return immediately, and not 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, waveready() should return BX_SOUND_OUTPUT_ERR until the device accepts another block of data.
Parameters:
length is the number of data bytes in the data stream. It will never be larger than BX_SOUNDLOW_WAVEPACKETSIZE.
data is the array of data bytes.
The order of bytes in the data stream is the same as that in the Wave file format:
Table 2-6. wave output types
| Output type | Sequence of data bytes |
|---|---|
| 8 bit mono | Sample 1; Sample 2; Sample 3; etc. |
| 8 bit stereo | Sample 1, Channel 0; Sample 1, Channel 1; Sample 2, Channel 0; Sample 2, Channel 1; etc. |
| 16 bit mono | Sample 1, LSB; Sample 1, MSB; Sample 2, LSB; Sample 2, MSB; etc. |
| 16 bit stereo | Sample 1, LSB, Channel 0; Sample 1, MSB, Channel 0; Sample 1, LSB, Channel 1; Sample 1, MSB, Channel 1; etc. |
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.
This function is called at the end of a wave data transfer. It should do the following:
Close the output device if it was opened by startwaveplayback(). and it's not going to be opened soon. Which is almost impossible to tell.
This function is called just before the Bochs simulation quits. It should do the following:
Close the output device, if this hasn't been done by stopwaveplayback().
Typically, stopwaveplayback() will be called several times, whenever a data transfer is done, where closewaveoutput() will only be called once. However, in the future it might be possible that openwaveoutput() 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.
The wave input feature is relatively new in Bochs. If a lowlevel driver does not implement recording, the methods of the base class ("dummy" driver) are used. They return silence to let the input mechanism of the soundcard emulation work. The soundcard emulator object needs to implement a callback function to notifies the emulation about available data. This function usually calls the driver method to get the wave data packet. The driver objects has a periodic timer with an interval of 0.1 emulated seconds that is active during recording. The timer handler processes the wave data recorded with platform or library specific function and finally notifies the emulator.
openwaveinput() is called when the sound emulation first receives a sound recording command. It should do the following:
Open the given device, and prepare it for wave input
or
Store the device name so that the device can be opened in startwaverecord().
In addition to this the record handler value should be stored and the record timer should be registered. This is the definition of record handler callback function:
typedef Bit32u (*sound_record_handler_t)(void *arg, Bit32u len);
openwaveinput() will only be called once, whereas startwaverecord() is called for every new wave input command to the soundcard emulation. If feasible, it could be useful to open and/or lock the input device in startwaverecord() as opposed to openwaveinput() to ensure that it can be used by other applications while Bochs doesn't need it.
The parameters are the following:
device is the wave device selected by the user. It is strictly system-dependent. The value is that of the wavein=device configuration parameter of the sound bochsrc option.
rh is a pointer to the record handler method of the sound emulation. When sound recording is active, this handler is called periodicly to notify the sound emulation about newly available data.
Note that only one wave input device will be used at any one time. device may not have the same value throughout one session, but it will be closed before it is changed.
This method is very similar to the startwaveplayback() method for sound output and it takes the same argument list. It should set up the input device for recording, calculate the size of the recording packet for 0.1 second and start the record timer.
This method is called from the record handler method of the sound emulation device to retrieve the recorded wave data packet.
This function is called to stop the wave recording. It deactivates the timer that calls the method to perform the recording.
This function is called just before the Bochs simulation quits. It is very similar to the closewaveoutput() method.