HOW AUDIO EMULATION WORKS IN QEMU:
==================================
Things are a bit tricky, but here's a rough description:
QEMUSoundCard: models a given emulated sound card
SWVoiceOut: models an audio output from a QEMUSoundCard
SWVoiceIn: models an audio input from a QEMUSoundCard
HWVoiceOut: models an audio output (backend) on the host.
HWVoiceIn: models an audio input (backend) on the host.
Each voice can have its own settings in terms of sample size, endianess, rate, etc...
Emulation for a given soundcard typically does:
1/ Create a QEMUSoundCard object and register it with AUD_register_card()
2/ For each emulated output, call AUD_open_out() to create a SWVoiceOut object.
3/ For each emulated input, call AUD_open_in() to create a SWVoiceIn object.
Note that you must pass a callback function to AUD_open_out() and AUD_open_in();
more on this later.
Each SWVoiceOut is associated to a single HWVoiceOut, each SWVoiceIn is
associated to a single HWVoiceIn.
However you can have several SWVoiceOut associated to the same HWVoiceOut
(same thing for SWVoiceIn/HWVoiceIn).
SOUND PLAYBACK DETAILS:
=======================
Each HWVoiceOut has the following too:
- A fixed-size circular buffer of stereo samples (for stereo).
whose format is either floats or int64_t per sample (depending on build
configuration).
- A 'samples' field giving the (constant) number of sample pairs in the stereo buffer.
- A target conversion function, called 'clip()' that is used to read from the stereo
buffer and write into a platform-specific sound buffers (e.g. WinWave-managed buffers
on Windows).
- A 'rpos' offset into the circular buffer which tells where to read the next samples
from the stereo buffer for the next conversion through 'clip'.
|<----------------- samples ----------------------->|
| |
| rpos |
|
|_______v___________________________________________|
| | |
| | |
|_______|___________________________________________|
- A 'run_out' method that is called each time to tell the output backend to
send samples from the stereo buffer to the host sound card/server. This method
shall also modify 'rpos' and returns the number of samples 'played'. A more detailed
description of this process appears below.
- A 'write' method callback used to write a buffer of emulated sound samples from
a SWVoiceOut into the stereo buffer. Currently all backends simply call the generic
function audio_pcm_sw_write() to implement this.
According to malc, the audio sub-system's original author, this is to allow
a backend to use a platform-specific function to do the same thing if available.
(Similarly, all input backends have a 'read' methods which simply calls 'audio_pcm_sw_read')
Each SWVoiceOut has the following:
- a 'conv()' function used to read sound samples from the emulated sound card and
copy/mix them to the corresponding HWVoiceOut's stereo buffer.
- a 'total_hw_samples_mixed' which correspond to the number of samples that have
already been mixed into the target HWVoiceOut stereo buffer (starting from the
HWVoiceOut's 'rpos' offset). NOTE: this is a count of samples in the HWVoiceOut
stereo buffer, not emulated hardware sound samples, which can have different
properties (frequency, size, endianess).
______________
| |
| SWVoiceOut2 |
|______________|
______________ |
| | |
| SWVoiceOut1 | | thsm<N> := total_hw_samples_mixed
|______________| | for SWVoiceOut<N>
| |
| |
|<-----|------------thsm2-->|
| | |
|<---thsm1-------->| |
_______|__________________v________|_______________
| |111111111111111111| v |
| |222222222222222222222222222| |
|_______|___________________________________________|
^
| HWVoiceOut stereo buffer
rpos
- a 'ratio' value, which is the ratio of the target HWVoiceOut's frequency by
the SWVoiceOut's frequency, multiplied by (1 << 32), as a 64-bit integer.
So, if the HWVoiceOut has a frequency of 44kHz, and the SWVoiceOut has a frequency
of 11kHz, then ratio will be (44/11*(1 << 32)) = 0x4_0000_0000
- a callback provided by the emulated hardware when the SWVoiceOut is created.
This function is used to mix the SWVoiceOut's samples into the target
HWVoiceOut stereo buffer (it must also perform frequency interpolation,
volume adjustment, etc..).
This callback normally calls another helper functions in the audio subsystem
(AUD_write()) to to the mixing/volume-adjustment from emulated hardware sample
buffers.
Here's a small graphics that explains it better:
SWVoiceOut: emulated hardware sound buffers:
|
| (mixed through AUD_write() called from user-provided
| callback which is itself called on each audio timer
| tick).
v
HWVoiceOut: stereo sample circular buffer
|
| (sent through HWVoiceOut's 'clip' function, which is
| invoked from the 'run_out' method, also called on each
| audio timer tick)
v
backend-specific sound buffers
The function audio_timer() in audio/audio.c is called periodically and it is used as
a pulse to perform sound buffer transfers and mixing. More specifically for audio
output voices:
- For each HWVoiceOut, find the number of active SWVoiceOut, and the minimum number
of 'total_hw_samples_mixed' that have already been written to the buffer. We will
call this value the number of 'live' samples in the stereo buffer.
- if 'live' is 0, call the callback of each active SWVoiceOut to fill the stereo
buffer, if needed, then exit.
- otherwise, call the 'run_out' method of the HWVoiceOut object. This will change
the value of 'rpos' and return the number of samples played. Then the
'total_hw_samples_mixed' field of all active SWVoiceOuts is decremented by
'played', and the callback is called to re-fill the stereo buffer.
It's important to note that the SWVoiceOut callback:
- takes a 'free' parameter which is the number of stereo sound samples that can
be sent to the hardware stereo buffer (before rate adjustment, i.e. not the number
of sound samples in the SWVoiceOut emulated hardware sound buffer).
- must call AUD_write(sw, buff, count), where 'buff' points to emulated sound
samples, and their 'count', which must be <= the 'free' parameter.
- the implementation of AUD_write() will call the 'write' method of the target
HWVoiceOut, which in turns calls the function audio_pcm_sw_write() which does
standard rate/volume adjustment before mixing the conversion into the target
stereo buffer. It also increases the 'total_hw_samples_mixed' value of the
SWVoiceOut.
- audio_pcm_sw_write() returns the number of sound sample *bytes* that have
been mixed into the stereo buffer, and so does AUD_write().
So, in the end, we have the pseudo-code:
every sound timer ticks:
for hw in list_HWVoiceOut:
live = MIN([sw.total_hw_samples_mixed for sw in hw.list_SWVoiceOut ])
if live > 0:
played = hw.run_out(live)
for sw in hw.list_SWVoiceOut:
sw.total_hw_samples_mixed -= played
for sw in hw.list_SWVoiceOut:
free = hw.samples - sw.total_hw_samples_mixed
if free > 0:
sw.callback(sw, free)
SOUND RECORDING DETAILS:
========================
Things are similar but in reverse order. I.e. the HWVoiceIn acquires sound samples
in its stereo sound buffer, and the SWVoiceIn objects must consume them as soon as
they can.