From b0ec110bdcda4150360ffc8e364bec41c2655801 Mon Sep 17 00:00:00 2001 From: David Guarneri Date: Tue, 19 Nov 2002 14:08:30 +0000 Subject: [PATCH] Moving the "classes" portion of SB16 emulation to the developer documentation. --- bochs/doc/docbook/user/user.dbk | 515 +------------------------------- 1 file changed, 12 insertions(+), 503 deletions(-) diff --git a/bochs/doc/docbook/user/user.dbk b/bochs/doc/docbook/user/user.dbk index 38539aa44..d6a9c26c1 100644 --- a/bochs/doc/docbook/user/user.dbk +++ b/bochs/doc/docbook/user/user.dbk @@ -1,7 +1,7 @@ -Sound Blaster 16 Emulation +Sound Blaster 16 Emulation: Configuring From Source + -This is Sound Blaster 16 (SB16) emulation for Bochs, written and donated by +This section is a detailed description for configuring Sound Blaster 16 from +source. I you have a binary and all you need to know is what to put in your +.bochsrc file, see . + + +Sound Blaster 16 (SB16) emulation for Bochs was written and donated by Josef Drexler, who has a web page on the topic. The entire set of his SB16 patches have been integrated into @@ -3197,508 +3203,11 @@ The command line can have any number of commands. However, if none are given,
Description of the sound output classes - -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, SOUNDLNX.CC -for Linux and SOUNDWIN.CC for Windows and their respective -header files to get an idea about how these things really work. +You can find a description of the sound output classes and more details on +Sound Blaster 16 emulation in the developer documentation.
- -
Files - - -The main include file is bochs.h. It has all definitions -for the system-independent functions that the SB16 emulation uses, which -are defined in sb16.h. - - - -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. - - - -To actually make the emulator use any specific driver, -BX_SOUND_OUTPUT_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 object list in -iodev/Makefile and iodev/Makefile.in. - -
- -
Classes - - -The following classes are involved with the SB16 emulation: - - - -bx_sb16_c 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. - - - -bx_sound_output_c 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. - - - -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 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 virtual if and only if BX_USE_SOUND_VIRTUAL -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. - - -
- - -
Methods - -The following are the methods that the output class has to override. -All but constructor and destructor have to return either -BX_SOUND_OUTPUT_OK (0) if the function was successful, -or BX_SOUND_OUTPUT_ERR (1) if not. If any of the initialization -functions fail, output to that device is disabled until the emulator is restarted. - -
- -
bx_sound_OS_c(bx_sb16_c*sb16) - - -The emulator instantiates the class at the initialization of Bochs. - - - -Description of the parameter: - - - - -sb16 is a pointer to the emulator class. -This pointer can then be used to access for example the writelog function to generate -sound-related log messages. Apart from that, no access to the emulator -should be necessary. - - - -The constructor should not allocate the output devices. -This shouldn't be done until the actual output occurs; in either -initmidioutput() or initwaveoutput(). -Otherwise it would be impossible to have two copies of Bochs running -concurrently (if anybody ever wants to do this). - - -
- -
~bx_sound_OS_c() - - -The instance is destroyed just before Bochs ends. - -
- -
int openmidioutput(char *device) - - - -openmidioutput() 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. - - - -openmidioutput() will always be called before openwaveoutput(), -and closemidioutput()will always be called before closewaveoutput(), but not in all cases will both functions be called. - - -
- -
-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. - - -
- -
int midiready() - - -midiready() is called whenever the applications asks if the -midi queue can accept more data. - - - -Return values: - - - - -BX_SOUND_OUTPUT_OK if the midi output device is ready. - - - -BX_SOUND_OUTPUT_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. - -
- -
int sendmidicommand(int delta, int command, int length, Bit8u data[]) - - -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. - - -
- - -
int closemidioutput() - - -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 - - -
- - -
int openwaveoutput(char *device) - - -openwaveoutput() is called when the first wave output occurs, -and only if the selected wavemode is 1. 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 startplayback(). - - - - -openmidioutput() will always be called before openwaveoutput(), -and closemidioutput()will always be called before closewaveoutput(), but not in all cases will both functions be called. - - - -openwaveoutput() will typically be called once, whereas -startplayback() 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 -startplayback() 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 -WAVE=device -configuration 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. - -
- -
-int startwaveplayback(int frequency, int bits, int stereo, int format) - - -This function is called whenever the application starts a new DMA transfer. 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 SB16, 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). - - -
- -
-Format Bits - -&FIXME; Insert FORMAT BITS table here - -
- - -
-int waveready() - - -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_SOUND_OUTPUT_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_SOUND_OUTPUT_WAVEPACKETSIZE bytes. -If BX_SOUND_OUTPUT_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. - -
- -
-int sendwavepacket(int length, Bit8u data[]) - - -This function is called whenever a data packet of at most BX_SB16_WAVEPACKETSIZE -is ready at the SB16 emulator. 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_SB16_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: - -
- -
-Sequences of Databytes Table - -&FIXME; Insert Sequences of Databytes table here - - - -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. - -
- - -
int stopwaveplayback() - - -This function is called at the end of a DMA 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. - - -
- -
int closewaveoutput() - - -This function is called just before Bochs exits. 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 DMA 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. - -
-
How to write your own keymap table