[Qemu-devel] [RFC PATCH] qapi for audio backends

[Kővágó, Zoltán]

This is a proposal to add structures into qapi-schema.json to replace the
existing configuration structures used by audio backends currently. I'm going to
use it to implement a new way to specify audio backend options (an -audiodev
command line option, instead of environment variables. This will also allow us
to use multiple audio backends in one qemu instance), so the structure used here
will be the basis of the command line syntax.

This is currently more or less a direct translation of the current audio backend
options. I've changed some names, trying to accomplish a more consistent naming
scheme. I wouldn't be surprised if there were options that doesn't work if you
set their value to anything other than the default (for example, log to monitor
can crash qemu, QEMU_DSOUND_RESTOURE_RETRIES has a typo, so probably nobody used
it, etc). I've also tried to reduce copy-paste, when the same set of options can
be given to output and input (QEMU_*_DAC_* and QEMU_*_ADC_* options), also using
in and out instead of ADC and DAC, as in the world of SPDIF and HDMI it's
completely possible that your computer has nothing to do with analog converters.
Plus a non technician user probably has no idea what ADC and DAC stands for.

Any comment is appreciated.

Signed-off-by: Kővágó, Zoltán <address@hidden>
---
 qapi-schema.json | 330 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 330 insertions(+)

diff --git a/qapi-schema.json b/qapi-schema.json
index 0662a9b..ff67d5a 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -3769,3 +3769,333 @@
 # Since: 2.1
 ##
 { 'command': 'rtc-reset-reinjection' }
+
+##
+# @AudiodevNoneOptions
+#
+# The dummy audio backend has no options.
+#
+# Since: XXX
+##
+{ 'struct': 'AudiodevNoneOptions',
+  'data': { } }
+
+##
+# @AudiodevAlsaPerDirectionOptions
+#
+# Options of the alsa backend that are used for both playback and recording.
+#
+# @dev: #optional the name of the alsa device to use.
+#
+# @period_size_usec: #optional the period size in microseconds. Must not be
+#                    specified with @period_size_frames.
+#
+# @period_size_frames: #optional the period size in frames. Must not be
+#                      specified with @period_size_usec.
+#
+# @buffer_size_usec: #optional the buffer size in microseconds. Must not be
+#                    specified with @buffer_size_frames.
+#
+# @buffer_size_frames: #optional the buffer size in frames. Must not be
+#                      specified with @buffer_size_usec.
+#
+# Since: XXX
+##
+{ 'struct': 'AudiodevAlsaPerDirectionOptions',
+  'data': {
+    '*dev':                'str',
+    '*period_size_usec':   'int',
+    '*period_size_frames': 'int',
+    '*buffer_size_usec':   'int',
+    '*buffer_size_frames': 'int' } }
+
+##
+# @AudiodevAlsaOptions
+#
+# Options of the alsa audio backend.
+#
+# @in: #optional options of the capture stream.
+#
+# @out: #optional options of the playback stream.
+#
+# @threshold: #optional
+#
+# @verbose: #optional behave in a more verbose way
+#
+# Since: XXX
+##
+{ 'struct': 'AudiodevAlsaOptions',
+  'data': {
+    '*in':  'AudiodevAlsaPerDirectionOptions',
+    '*out': 'AudiodevAlsaPerDirectionOptions',
+    '*threshold': 'int',
+    '*verbose':   'bool' } }
+
+##
+# @AudiodevCoreaudioOptions
+#
+# Options of the coreaudio backend.
+#
+# @buffer_size: #optional size of the buffer in frames
+#
+# @buffer_count: #optional number of buffers
+#
+# Since: XXX
+##
+{ 'struct': 'AudiodevCoreaudioOptions',
+  'data': {
+    '*buffer_size':  'int',
+    '*buffer_count': 'int' } }
+
+##
+# @AudiodevDsoundPerDirectionOptions
+#
+# Options of the dsound backend that are used for both playback and recording.
+#
+# @bufsize: #optional
+#
+# Since: XXX
+##
+{ 'struct': 'AudiodevDsoundPerDirectionOptions',
+  'data' : {
+    '*bufsize': 'int' } }
+
+##
+# @AudiodevDsoundOptions
+#
+# Options of the dsound audio backend.
+#
+# @in: #optional options of the capture stream.
+#
+# @out: #optional options of the playback stream.
+#
+# @lock_retries: #optional number of times to attempt locking the buffer
+#
+# @restore_retries: #optional number of times to attempt restoring the buffer
+#
+# @getstatus_retries: #optional number of times to attempt getting status of 
the
+#                     buffer
+#
+# @set_primary: #optional set the parameters of primary buffer
+#
+# @latency_millis: #optional
+#
+# @primary_freq: #optional primary buffer frequency
+#
+# @primary_channels: #optional primary buffer number of channels
+#
+# @primary_format: #optional primary buffer format
+#
+# Since: XXX
+##
+{ 'struct': 'AudiodevDsoundOptions',
+  'data': {
+    '*in':                'AudiodevDsoundPerDirectionOptions',
+    '*out':               'AudiodevDsoundPerDirectionOptions',
+    '*lock_retries':      'int',
+    '*restore_retries':   'int',
+    '*getstatus_retries': 'int',
+    '*set_primary':       'bool',
+    '*latency_millis':    'int',
+    '*primary_freq':      'int',
+    '*primary_channels':  'int',
+    '*primary_format':    'AudioFormat' } }
+
+##
+# @AudiodevOssPerDirectionOptions
+#
+# Options of the oss backend that are used for both playback and recording.
+#
+# @dev: #optional path of the oss device
+#
+# Since: XXX
+##
+{ 'struct': 'AudiodevOssPerDirectionOptions',
+  'data': {
+    '*dev': 'str' } }
+
+##
+# @AudiodevOssOptions
+#
+# Options of the oss audio backend.
+#
+# @in: #optional options of the capture stream.
+#
+# @out: #optional options of the playback stream.
+#
+# @fragsize: #optional fragment size in bytes
+#
+# @frags: #optional number of fragments
+#
+# @mmap: #optional try using memory mapped access
+#
+# @exclusive: #optional open device in exclusive mode (vmix wont work)
+#
+# @dsp_policy: #optional set the timing policy of the device, -1 to use 
fragment
+#              mode (option ignored on some platforms)
+#
+# @debug: #optional turn on some debugging messages
+#
+# Since: XXX
+##
+{ 'struct': 'AudiodevOssOptions',
+  'data': {
+    '*in':         'AudiodevOssPerDirectionOptions',
+    '*out':        'AudiodevOssPerDirectionOptions',
+    '*fragsize':   'int',
+    '*frags':      'int',
+    '*mmap':       'bool',
+    '*exclusive':  'bool',
+    '*dsp_policy': 'int',
+    '*debug':      'bool' } }
+
+##
+# @AudiodevPaOptions
+#
+# Options of the pa audio backend.
+#
+# @samples: #optional buffer size in samples
+#
+# @server: #optional PulseAudio server address
+#
+# @sink: #optional sink device name
+#
+# @source: #optional source device name
+#
+# Since: XXX
+##
+{ 'struct': 'AudiodevPaOptions',
+  'data': {
+    '*samples': 'int',
+    '*server':  'str',
+    '*sink':    'str',
+    '*source':  'str' } }
+
+##
+# @AudiodevSdlOptions
+#
+# Options of the sdl audio backend. (Note that most options are only changeable
+# through SDL's environment variables).
+#
+# @samples: #optional size of SDL buffer in samples
+#
+# Since: XXX
+##
+{ 'struct': 'AudiodevSdlOptions',
+  'data': {
+    '*samples': 'int' } }
+
+##
+# @AudiodevSpiceOptions
+#
+# The spice audio backend has no options.
+#
+# Since: XXX
+##
+{ 'struct': 'AudiodevSpiceOptions',
+  'data': { } }
+
+##
+# @AudiodevWavOptions
+#
+# Options of the wav audio backend.
+#
+# @frequency: #optional frequency of the wav file
+#
+# @format: #optional sample format of the wav file
+#
+# @channels: #optional number of channels of the wav file
+#
+# @path: #optional path of the wav file to record.
+#
+# Since: XXX
+##
+{ 'struct': 'AudiodevWavOptions',
+  'data': {
+    '*frequency': 'int',
+    '*format':    'AudioFormat',
+    '*channels':  'int',
+    '*path':       'str' } }
+
+
+##
+# @AudiodevBackendOptions
+#
+# A discriminated record of audio backends.
+#
+# Since: XXX
+##
+{ 'union': 'AudiodevBackendOptions',
+  'data': {
+    'none':      'AudiodevNoneOptions',
+    'alsa':      'AudiodevAlsaOptions',
+    'coreaudio': 'AudiodevCoreaudioOptions',
+    'dsound':    'AudiodevDsoundOptions',
+    'oss':       'AudiodevOssOptions',
+    'pa':        'AudiodevPaOptions',
+    'sdl':       'AudiodevSdlOptions',
+    'spice':     'AudiodevSpiceOptions',
+    'wav':       'AudiodevWavOptions' } }
+
+##
+# @AudioFormat
+#
+# An enumeration of possible audio formats.
+#
+# Since: XXX
+##
+{ 'enum': 'AudioFormat',
+  'data': [ 'u8', 's8', 'u16', 's16', 'u32', 's32' ] }
+
+##
+# @AudiodevPerDirectionOptions
+#
+# General audio backend options that are used for both playback and recording.
+#
+# @fixed_settings: #optional use fixed settings for host DAC/ADC
+#
+# @frequency: #optional frequency to use when using fixed settings
+#
+# @channels: #optional number of channels when using fixed settings
+#
+# @format: #optional sample fortmat to use when using fixed settings
+#
+# @try_poll: #optional attempt to use poll mode
+#
+# Since: XXX
+##
+{ 'struct': 'AudiodevPerDirectionOptions',
+  'data': {
+    '*fixed_settings': 'bool',
+    '*frequency':      'int',
+    '*channels':       'int',
+    '*format':         'AudioFormat',
+    '*try_poll':       'bool' } }
+
+##
+# @Audiodev
+#
+# Captures the configuration of an audio backend.
+#
+# @id: identifier of the backend.
+#
+# @in: #optional options of the capture stream.
+#
+# @out: #optional options of the playback stream.
+#
+# @timer_period: #optional timer period in HZ (0 - use lowest possible)
+#
+# @plive: #optional
+#
+# @opts: audio backend specific options
+#
+# Since XXX
+##
+{ 'struct': 'Audiodev',
+  'data': {
+    'id':            'str',
+    '*in':           'AudiodevPerDirectionOptions',
+    '*out':          'AudiodevPerDirectionOptions',
+    '*timer_period': 'int',
+    '*plive':        'bool',
+    'opts':          'AudiodevBackendOptions' } }
-- 
2.4.2