Re: [Qemu-devel] [PATCH 07/25] qapi: qapi for audio backends

[Marc-André Lureau]

On Thu, Aug 6, 2015 at 8:28 PM, Kővágó, Zoltán <address@hidden> wrote:
> This patch adds structures into qapi to replace the existing
> configuration structures used by audio backends currently. This qapi
> will be the base of the -audiodev command line parameter (that replaces
> the old environment variables based config).
>
> This is not a 1:1 translation of the old options, I've tried to make
> them much more consistent (e.g. almost every backend had an option to
> specify buffer size, but the name was different for every backend, and
> some backends required usecs, while some other required frames, samples
> or bytes). Also tried to reduce the number of abbreviations used by the
> config keys.
>
> Some of the more important changes:
> * use `in` and `out` instead of `ADC` and `DAC`, as the former is more
>   user friendly imho
> * moved buffer settings into the global setting area (so it's the same
>   for all backends that support it. Backends that can't change buffer
>   size will simply ignore them). Also using usecs, as it's probably more
>   user friendly than samples or bytes.
> * try-poll is now an alsa backend specific option (as all other backends
>   currently ignore it)
>
> Signed-off-by: Kővágó, Zoltán <address@hidden>
> ---
>  Makefile         |   4 +-
>  qapi-schema.json |   3 +
>  qapi/audio.json  | 263 
> +++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  3 files changed, 268 insertions(+), 2 deletions(-)
>  create mode 100644 qapi/audio.json
>
> diff --git a/Makefile b/Makefile
> index 340d9c8..bdd0bc6 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -262,8 +262,8 @@ $(SRC_PATH)/qga/qapi-schema.json 
> $(SRC_PATH)/scripts/qapi-commands.py $(qapi-py)
>                 "  GEN   $@")
>
>  qapi-modules = $(SRC_PATH)/qapi-schema.json $(SRC_PATH)/qapi/common.json \
> -               $(SRC_PATH)/qapi/block.json $(SRC_PATH)/qapi/block-core.json \
> -               $(SRC_PATH)/qapi/event.json
> +               $(SRC_PATH)/qapi/audio.json  $(SRC_PATH)/qapi/block.json \
> +               $(SRC_PATH)/qapi/block-core.json $(SRC_PATH)/qapi/event.json
>
>  qapi-types.c qapi-types.h :\
>  $(qapi-modules) $(SRC_PATH)/scripts/qapi-types.py $(qapi-py)
> diff --git a/qapi-schema.json b/qapi-schema.json
> index c9d9263..e9cbe15 100644
> --- a/qapi-schema.json
> +++ b/qapi-schema.json
> @@ -5,6 +5,9 @@
>  # QAPI common definitions
>  { 'include': 'qapi/common.json' }
>
> +# QAPI audio definitions
> +{ 'include': 'qapi/audio.json' }
> +
>  # QAPI block definitions
>  { 'include': 'qapi/block.json' }
>
> diff --git a/qapi/audio.json b/qapi/audio.json
> new file mode 100644
> index 0000000..b57b215
> --- /dev/null
> +++ b/qapi/audio.json
> @@ -0,0 +1,263 @@
> +# -*- mode: python -*-
> +#
> +# Copyright (C) 2015 Zoltán Kővágó <address@hidden>
> +#
> +# This work is licensed under the terms of the GNU GPL, version 2 or later.
> +# See the COPYING file in the top-level directory.
> +
> +##
> +# @AudiodevNoOptions
> +#
> +# The none, coreaudio, sdl and spice audio backend have no options.
> +#
> +# Since: 2.5
> +##
> +{ 'struct': 'AudiodevNoOptions',
> +  '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 (default 'default')
> +#
> +# @try-poll: #optional attempt to use poll mode, falling back to non polling
> +#            access on failure (default on)
> +#
> +# Since: 2.5
> +##
> +{ 'struct': 'AudiodevAlsaPerDirectionOptions',
> +  'data': {
> +    '*dev':      'str',
> +    '*try-poll': 'bool' } }
> +
> +##
> +# @AudiodevAlsaOptions
> +#
> +# Options of the alsa audio backend.
> +#
> +# @alsa-in: options of the capture stream
> +#
> +# @alsa-out: options of the playback stream
> +#
> +# @threshold: #optional set the threshold (in microsecods) when playback 
> starts

microseconds.

> +#
> +# Since: 2.5
> +##
> +{ 'struct': 'AudiodevAlsaOptions',
> +  'data': {
> +    'alsa-in':    'AudiodevAlsaPerDirectionOptions',
> +    'alsa-out':   'AudiodevAlsaPerDirectionOptions',
> +    '*threshold': 'int' } }
> +
> +##
> +# @AudiodevDsoundOptions
> +#
> +# Options of the dsound audio backend.
> +#
> +# @latency: #optional add extra latency to playback in microseconds (default
> +#           10000)
> +#
> +# Since: 2.5
> +##
> +{ 'struct': 'AudiodevDsoundOptions',
> +  'data': {
> +    '*latency': 'int' } }
> +
> +##
> +# @AudiodevOssPerDirectionOptions
> +#
> +# Options of the oss backend that are used for both playback and recording.
> +#
> +# @dev: #optional file name of the oss device (default '/dev/dsp')
> +#
> +# @try-poll: #optional attempt to use poll mode, falling back to non polling
> +#            access on failure (default on)
> +#
> +# Since: 2.5
> +##
> +{ 'struct': 'AudiodevOssPerDirectionOptions',
> +  'data': {
> +    '*dev':      'str',
> +    '*try-poll': 'bool' } }
> +
> +##
> +# @AudiodevOssOptions
> +#
> +# Options of the oss audio backend.
> +#
> +# @oss-in: options of the capture stream
> +#
> +# @oss-out: options of the playback stream
> +#
> +# @try-mmap: #optional try using memory mapped access, falling back to non
> +#            memory mapped access on failure (default off)
> +#
> +# @exclusive: #optional open device in exclusive mode (vmix won't work)
> +#             (default off)
> +#
> +# @dsp-policy: #optional set the timing policy of the device (between 0 and 
> 10,
> +#              where smaller number means smaller latency but higher CPU 
> usage)
> +#              or -1 to use fragment mode (option ignored on some platforms)
> +#              (default 5)
> +#
> +# Since: 2.5
> +##
> +{ 'struct': 'AudiodevOssOptions',
> +  'data': {
> +    'oss-in':      'AudiodevOssPerDirectionOptions',
> +    'oss-out':     'AudiodevOssPerDirectionOptions',
> +    '*try-mmap':   'bool',
> +    '*exclusive':  'bool',
> +    '*dsp-policy': 'int' } }
> +
> +##
> +# @AudiodevPaPerDirectionOptions
> +#
> +# Options of the pa backend that are used for both playback and recording.
> +#
> +# @name: #optional name of the sink/source to use
> +#
> +# Since: 2.5
> +##
> +{ 'struct': 'AudiodevPaPerDirectionOptions',
> +  'data': {
> +    '*name': 'str' } }
> +
> +##
> +# @AudiodevPaOptions
> +#
> +# Options of the pa (PulseAudio) audio backend.
> +#
> +# @server: #optional PulseAudio server address (default: let PulseAudio 
> choose)
> +#
> +# @sink: sink specific options
> +#
> +# @source: source specific options
> +#
> +# Since: 2.5
> +##
> +{ 'struct': 'AudiodevPaOptions',
> +  'data': {
> +    '*server': 'str',
> +    'sink':    'AudiodevPaPerDirectionOptions',
> +    'source':  'AudiodevPaPerDirectionOptions' } }
> +
> +##
> +# @AudiodevWavOptions
> +#
> +# Options of the wav audio backend.
> +#
> +# @path: #optional name of the wav file to record (default 'qemu.wav')
> +#
> +# Since: 2.5
> +##
> +{ 'struct': 'AudiodevWavOptions',
> +  'data': {
> +    '*path': 'str' } }
> +
> +
> +##
> +# @AudioFormat
> +#
> +# An enumeration of possible audio formats.
> +#
> +# Since: 2.5
> +##
> +{ 'enum': 'AudioFormat',
> +  'data': [ 'u8', 's8', 'u16', 's16', 'u32', 's32' ] }
> +
> +##
> +# @AudiodevDriver
> +#
> +# An enumeration of possible audio backend drivers.
> +#
> +# Since: 2.5
> +##
> +{ 'enum': 'AudiodevDriver',
> +  'data': [ 'none', 'alsa', 'coreaudio', 'dsound', 'oss', 'pa', 'sdl', 
> 'spice',
> +            'wav' ] }
> +
> +##
> +# @AudiodevPerDirectionOptions
> +#
> +# General audio backend options that are used for both playback and 
> recording.
> +#
> +# @fixed-settings: #optional use fixed settings for host input/output.  When
> +#                  off, frequency, channels and format must not be specified
> +#                  (default on)
> +#
> +# @frequency: #optional frequency to use when using fixed settings
> +#             (default 44100)
> +#
> +# @channels: #optional number of channels when using fixed settings
> +#            (default 2)
> +#
> +# @voices: #optional number of voices to use (default 1)
> +#
> +# @format: #optional sample format to use when using fixed settings
> +#          (default s16)
> +#
> +# @buffer-len: #optional the buffer size in microseconds
> +#
> +# @buffer-count: #optional number of buffers
> +#
> +# Since: 2.5
> +##
> +{ 'struct': 'AudiodevPerDirectionOptions',
> +  'data': {
> +    '*fixed-settings': 'bool',
> +    '*frequency':      'int',
> +    '*channels':       'int',
> +    '*voices':         'int',
> +    '*format':         'AudioFormat',
> +    '*buffer-len':     'int',
> +    '*buffer-count':   'int' } }
> +
> +##
> +# @AudiodevCommonOptions
> +#
> +# Captures the common configuration of an audio backend.
> +#
> +# @id: identifier of the backend
> +#
> +# @driver: the backend driver to use
> +#
> +# @in: options of the capture stream
> +#
> +# @out: options of the playback stream
> +#
> +# @timer-period: #optional timer period (in microseconds, 0: use lowest
> +#                possible)
> +#
> +# Since: 2.5
> +##
> +{ 'struct': 'AudiodevCommonOptions',
> +  'data': {
> +    'id':            'str',
> +    'driver':        'AudiodevDriver',
> +    'in':            'AudiodevPerDirectionOptions',
> +    'out':           'AudiodevPerDirectionOptions',
> +    '*timer-period': 'int' } }
> +
> +##
> +# @AudiodevBackendOptions
> +#
> +# Options of an audio backend.
> +#
> +# Since: 2.5
> +##
> +{ 'union': 'Audiodev',
> +  'base': 'AudiodevCommonOptions',
> +  'discriminator': 'driver',
> +  'data': {
> +    'none':      'AudiodevNoOptions',
> +    'alsa':      'AudiodevAlsaOptions',
> +    'coreaudio': 'AudiodevNoOptions',
> +    'dsound':    'AudiodevDsoundOptions',
> +    'oss':       'AudiodevOssOptions',
> +    'pa':        'AudiodevPaOptions',
> +    'sdl':       'AudiodevNoOptions',
> +    'spice':     'AudiodevNoOptions',
> +    'wav':       'AudiodevWavOptions' } }
> --
> 2.4.5
>
>



-- 
Marc-André Lureau