Re: [Qemu-devel] [PATCH v2 03/14] audio: add audiodev property to vnc and wav_capture

[Markus Armbruster <armbru@redhat.com>]

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

> On 2019-07-28 15:42, Zoltán Kővágó wrote:
>> On 2019-07-22 16:21, Markus Armbruster wrote:
>>> "Zoltán Kővágó" <dirty.ice.hu@gmail.com> writes:
>>>
>>>> On 2019-07-16 08:23, Markus Armbruster wrote:
[...]
>>>>>> diff --git a/hmp-commands.hx b/hmp-commands.hx
>>>>>> index bfa5681dd2..fa7f009268 100644
>>>>>> --- a/hmp-commands.hx
>>>>>> +++ b/hmp-commands.hx
>>>>>> @@ -819,16 +819,19 @@ ETEXI
>>>>>>          {
>>>>>>            .name       = "wavcapture",
>>>>>> -        .args_type  = "path:F,freq:i?,bits:i?,nchannels:i?",
>>>>>> -        .params     = "path [frequency [bits [channels]]]",
>>>>>> +        .args_type  =
>>>>>> "path:F,freq:i?,bits:i?,nchannels:i?,audiodev:s?",
>>>>>> +        .params     = "path [frequency [bits [channels
>>>>>> [audiodev]]]]",
>>>>>>            .help       = "capture audio to a wave file (default
>>>>>> frequency=44100 bits=16 channels=2)",
>>>>>>            .cmd        = hmp_wavcapture,
>>>>>>        },
>>>>>>    STEXI
>>>>>> -@item wavcapture @var{filename} [@var{frequency} [@var{bits}
>>>>>> [@var{channels}]]]
>>>>>> +@item wavcapture @var{filename} [@var{frequency} [@var{bits}
>>>>>> [@var{channels} [@var{audiodev}]]]]
>>>>>>    @findex wavcapture
>>>>>> -Capture audio into @var{filename}. Using sample rate @var{frequency}
>>>>>> -bits per sample @var{bits} and number of channels @var{channels}.
>>>>>> +Capture audio into @var{filename} from @var{audiodev}, using
>>>>>> sample rate
>>>>>> +@var{frequency} bits per sample @var{bits} and number of channels
>>>>>> +@var{channels}. When not using an -audiodev argument on command line,
>>>>>> +@var{audiodev} must be omitted, otherwise is must specify a valid
>>>>>> +audiodev.
>>>>>
>>>>> I can see the code for "must specify a valid audiodev" in
>>>>> hmp_wavcapture().  Where is "must be omitted" checked?
>>>>
>>>> It's not checked right now, but if the user specifies audiodev, it
>>>> must be a valid audiodev id.  So if the user can guess the id (which
>>>> is not too hard ATM, it's simply the driver's name), it will work even
>>>> in this case.
>>>>
>>>>> Preexisting: the list "sample rate @var{frequency} bits per sample
>>>>> @var{bits} and number of channels @var{channels}" lacks a comma after
>>>>> @var{frequency}, please fix that.  I'd put one after @var{bits}
>>>>> as well,
>>>>> but that's a matter of taste[*]
>>>>>
>>>>> The sentence is of the form "if not COND then A else B".  The
>>>>> less-negated form "if COND then B else A" is commonly easier to read.
>>>>>
>>>>> Documentation says "from @var{audiodev}".  But when "not using an
>>>>> -audiodev argument on command line, +@var{audiodev} must be omitted".
>>>>> Where does it sample from then?  I figure from some default audio
>>>>> device.  Where is that default audio device explained?  I skimmed the
>>>>> -audiodev documentation in qemu-options.hx, but couldn't see it there.
>>>>
>>>> Currently there are two ways to specify audio options, the legacy ones
>>>> using the QEMU_AUDIO_* environment variables, and the new one using
>>>> -audiodev arguments.  The two formats cannot be mixed, and eventually
>>>> we should remove the legacy ones (IIRC my previous patch series
>>>> already deprecated them), then we can get rid of this madness.  Maybe
>>>> something like "When using the legacy environment variable based audio
>>>> config, @var{audiodev} must be omitted." would be better?
>>>
>>> What about effectively de-documenting the deprecated method?  I.e. write
>>> as if it was already gone.  This should result in more readable
>>> documentation.
>>
>> Makes sense.  User will less likely use deprecated methods that way
>> and it simplifies the documentation.
>>
>>> Double-checking: will audiodev become mandatory once the deprecated
>>> method is gone?
>>
>> Yes.
>
> Actually, now that I took a second look at the params, it might be
> problematic.  Currently audiodev is the last parameter, so if it
> becomes mandatory, that will effectively mean other parameters will
> become mandatory too.  And if I were to change the order and move
> audiodev first, that would break backward compatibility during the
> deprecation period.

HMP is not a stable interface.  We can break compatibility there when we
have a reason.

In this case, we can either break it right away (insert audiodev before
the other optional parameters), or later (insert it last, move it when
it becomes mandatory).  Matter of taste.  I'd break it right away.