Re: [Qemu-devel] [PATCH v6 01/14] qapi: qapi for audio backends

["Zoltán Kővágó" <dirty.ice.hu@gmail.com>]

On 2019-03-09 10:27, Markus Armbruster wrote:
> "Kővágó, Zoltán" <dirty.ice.hu@gmail.com> writes:
> 
>> 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 <DirtY.iCE.hu@gmail.com>
>> Reviewed-by: Markus Armbruster <armbru@redhat.com>
>> ---
>>
>> Notes:
>>     Changes from v5:
>>     
>>     * documentation fixes
>>     * renamed buffer-len to buffer-length and period-len to period-length
>>     
>>     Changes from v4:
>>     
>>     * documentation fixes
>>     * renamed pa's source/sink to pa-in/pa-out
>>     * per-direction options changed per Markus Armbruster's comments
>>     
>>     Changes from v2:
>>     
>>     * update copyright, version numbers
>>     * remove #optional
>>     * per-direction options are now optional (needed for qobject_object_visitor_new_str)
>>     * removed unnecessary AudiodevNoOptions
>>     * changed integers to unsigned
>>
>>  qapi/audio.json       | 304 ++++++++++++++++++++++++++++++++++++++++++
>>  qapi/qapi-schema.json |   1 +
>>  qapi/Makefile.objs    |   6 +-
>>  3 files changed, 308 insertions(+), 3 deletions(-)
>>  create mode 100644 qapi/audio.json
>>
>> diff --git a/qapi/audio.json b/qapi/audio.json
>> new file mode 100644
>> index 0000000000..97aee37288
>> --- /dev/null
>> +++ b/qapi/audio.json
>> @@ -0,0 +1,304 @@
>> +# -*- mode: python -*-
>> +#
>> +# Copyright (C) 2015-2019 Zoltán Kővágó <DirtY.iCE.hu@gmail.com>
>> +#
>> +# This work is licensed under the terms of the GNU GPL, version 2 or later.
>> +# See the COPYING file in the top-level directory.
>> +
>> +##
>> +# @AudiodevPerDirectionOptions:
>> +#
>> +# General audio backend options that are used for both playback and
>> +# recording.
>> +#
>> +# @fixed-settings: use fixed settings for host input/output. When off,
>> +#                  frequency, channels and format must not be
>> +#                  specified (default true)
>> +#
>> +# @frequency: frequency to use when using fixed settings
>> +#             (default 44100)
>> +#
>> +# @channels: number of channels when using fixed settings (default 2)
>> +#
>> +# @voices: number of voices to use (default 1)
>> +#
>> +# @format: sample format to use when using fixed settings
>> +#          (default s16)
>> +#
>> +# @buffer-length: the buffer length in microseconds
> 
> The name buffer-length suggests bytes rather than microseconds.  That's
> why I suggested @buffer-capacity.  Matter of taste, up to you and Gerd.

@period-length has the same issue.  For me @buffer-capacity and
@period-capacity feels a bit weird.  I'm not 100% familiar with qapi
conventions, but for me 'size' is what's usually in bytes, and 'length'
can be something else (number of characters in a string, length of a
sound file, ...).

> 
>> +#
>> +# Since: 4.0
>> +##
>> +{ 'struct': 'AudiodevPerDirectionOptions',
>> +  'data': {
>> +    '*fixed-settings': 'bool',
>> +    '*frequency':      'uint32',
>> +    '*channels':       'uint32',
>> +    '*voices':         'uint32',
>> +    '*format':         'AudioFormat',
>> +    '*buffer-length':  'uint32' } }
> [...]
> 
> Regardless:
> Reviewed-by: Markus Armbruster <armbru@redhat.com>
> 

Regards,
Zoltan