Porting Bochs Sound Output
Author: Josef Drexler
Description: A brief description of how the portable part of the sound subsystem of Bochs works, and how it should or could be ported to other platforms than those already supported.

# Sound Blaster 16 emulation

# About SB16 emulation for bochs

This is Sound Blaster 16 emulation for bochs, written and donated by Josef Drexler. You can see also check out his related web page here. The entire set of his SB16 patches have been integrated into bochs, so you will not need to do so.

It has been tested with several soundcards and versions of Linux. Please give Josef feedback on whether is does or doesn't work on your combination of software and hardware.

### How much does work?

Right now, MPU401 emulation is next to perfect. It supports UART and SBMIDI mode, because the SB16's MPU401 ports can't do anything else as well.

The digital audio basically works, the emulation is too slow for fluent output unless the application doesn't do much in the background (or the foreground, really). The sound tends to looping or crackle on slower computer, but the emulation appears to be correct. Even a MOD player works, although only for lower sampling speeds.

Also, the MIDI data running through the MPU401 ports can be written into a SMF, that is the standard midi file. The wave output can be written into a VOC file, which has a format defined by Creative Labs. This file format can be converted to WAV by sox for example.

### Output to a sound card

Output is supported on Linux and Windows 95 at the moment.

On Linux, the output goes to any file or device. If you have a wavetable synthesizer, midi can go to /dev/midi00, otherwise you may need a midi interpreter. For example, the midid program from the DosEmu project would work. Wave output should go to /dev/dsp. These devices are assumed to be OSS devices, if they're not some of the ioctl's might fail.

On Windows, midi and output goes to the midi mapper and the wave mapper, respectively. A future version might have selectable output devices.

# Installation on Linux

### Prerequisites

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.

### Configuring bochs

    There are a few values in config.h that are relevant to the sound functions.
    Edit config.h after running configure, but before compiling.

    BX_USE_SB16_SMF should be 1 unless you intend to have several sound cards
    running at the same time.

    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.

    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:
            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.

    Setup the SB16 emulation in your .bochsrc, according to instructions
    in that file.

# Runtime configuration

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 executable.

    misc/sb16/ contains a C program that can be run inside the emulator, and the
    executable for DOS. It currently supports the following commands:
    -i : shows the selected emulator info string,
            e.g. sb16ctrl -i 3 to show how many patch translations are active

    -t : 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 "match
            any" and for New values means "don't change",
            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 : 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 : 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.

    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.

    The command line can have any number of commands. However, if none are given,
    "-f -" is assumed, which means commands are taken from stdin.

# Features planned for the future

- Ports to more OS's, but I can't do this myself
- Finishing the OPL3 FM emulation by translating the music to midi data

# 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.

## Overview

### 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.

Constructor and destructor:

- `bx_sound_OS_c(bx_sb16_c *sb16)`
- `~bx_sound_OS_c()`

Midi functions:

- `int openmidioutput(char *device)`
- `int sendmidicommand(int delta, int command, int length, Bit8u data[])`
- `int midiready()`
- `int closemidioutput()`

Wave functions:

- `int openwaveoutput(char *device)`
- `int startwaveplayback(int frequency, int bits, int stereo, int format)`
- `int waveready()`
- `int sendwavepacket(int length, Bit8u data[])`
- `int stopwaveplayback()`
- `int closewaveoutput()`

## Details

### Methods

#### `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

- 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

- 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

- `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

- 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:

- `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).

The bits in `format` are
Bit number | Meaning
--- | ---
0 (LSB) | 0: unsigned data 1: signed data
1..6 | Type of codec
7 | 0: no reference byte 1: with reference byte
8..x | reserved (0)
|  | The codec can be one of the following:
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)`.

#### `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

- 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:

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.

#### `int stopwaveplayback()`

This function is called at the end of a DMA transfer. It should

- 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

- 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.