From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:47523) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Z5DXD-0001m8-8r for qemu-devel@nongnu.org; Wed, 17 Jun 2015 09:37:47 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Z5DX8-0005n4-8Y for qemu-devel@nongnu.org; Wed, 17 Jun 2015 09:37:43 -0400 Received: from mx1.redhat.com ([209.132.183.28]:54978) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Z5DX8-0005ms-1G for qemu-devel@nongnu.org; Wed, 17 Jun 2015 09:37:38 -0400 From: Markus Armbruster References: <87si9qg4kt.fsf@blackfin.pond.sub.org> <558151FC.9000703@gmail.com> <87zj3y7dyk.fsf@blackfin.pond.sub.org> <5581630F.1070701@gmail.com> Date: Wed, 17 Jun 2015 15:37:33 +0200 In-Reply-To: <5581630F.1070701@gmail.com> (=?utf-8?B?IkvFkXbDoWfDsyBab2x0?= =?utf-8?B?w6FuIidz?= message of "Wed, 17 Jun 2015 14:07:43 +0200") Message-ID: <87fv5q317m.fsf@blackfin.pond.sub.org> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Subject: Re: [Qemu-devel] [PATCH v2 1/6] qapi: qapi for audio backends List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: =?utf-8?B?S8WRdsOhZ8OzIFpvbHTDoW4=?= Cc: qemu-devel@nongnu.org, Michael Roth , Gerd Hoffmann "K=C5=91v=C3=A1g=C3=B3 Zolt=C3=A1n" writes: > 2015-06-17 13:48 keltez=C3=A9ssel, Markus Armbruster =C3=ADrta: >> "K=C5=91v=C3=A1g=C3=B3 Zolt=C3=A1n" writes: >> >>> 2015-06-17 09:46 keltez=C3=A9ssel, Markus Armbruster =C3=ADrta: >>>> Copying Eric for additional QAPI schema expertise. >>>> >>>> My questions inline, pretty sure they show my ignorance. >>>> >>>> "K=C5=91v=C3=A1g=C3=B3, Zolt=C3=A1n" writes: [...] >>>>> +## >>>>> +# @AudiodevPaOptions >>>>> +# >>>>> +# Options of the pa (PulseAudio) audio backend. >>>>> +# >>>>> +# @server: #optional PulseAudio server address >>>>> +# >>>>> +# @sink: #optional sink device name >>>>> +# >>>>> +# @source: #optional source device name >>>> >>>> Who picks the defaults, QEMU or PA? >>> >>> PA >> >> Is there a way to explicitly ask for the PA default? Something like >> source=3Ddefault? > > Not really right now. The default is a NULL pointer (pulseaudio api > wise), so unless we add an arbitrary keyword (like default), it's not > possible to ask explicitly for the default. (But omitting them will > choose the default, of course.) Treating an empty string like NULL should get us a way to ask for the default, and a way to document the default concisely, like (default '') plus a suitable explanation what '' means. I'm not saying you should do that. I'm saying whatever you do, document what happens when an optional parameter is absent :) >>>>> +# >>>>> +# Since: 2.4 >>>>> +## >>>>> +{ 'struct': 'AudiodevPaOptions', >>>>> + 'data': { >>>>> + '*server': 'str', >>>>> + '*sink': 'str', >>>>> + '*source': 'str' } } >>>>> + >>>>> +## >>>>> +# @AudiodevWavOptions >>>>> +# >>>>> +# Options of the wav audio backend. >>>>> +# >>>>> +# @path: #optional path of the wav file to record >>>>> +# >>>>> +# Since: 2.4 >>>>> +## >>>>> +{ 'struct': 'AudiodevWavOptions', >>>>> + 'data': { >>>>> + '*path': 'str' } } >>>> >>>> Who picks the default? >>> >>> It defaults to "qemu.wav" >> >> Make it >> >> # @path: #optional path of the wav file to record (default 'qemu.wa= v') >> >>>>> + >>>>> + >>>>> +## >>>>> +# @AudiodevBackendOptions >>>>> +# >>>>> +# A discriminated record of audio backends. >>>>> +# >>>>> +# Since: 2.4 >>>>> +## >>>>> +{ 'union': 'AudiodevBackendOptions', >>>>> + 'data': { >>>>> + 'none': 'AudiodevNoOptions', >>>>> + 'alsa': 'AudiodevAlsaOptions', >>>>> + 'coreaudio': 'AudiodevNoOptions', >>>>> + 'dsound': 'AudiodevDsoundOptions', >>>>> + 'oss': 'AudiodevOssOptions', >>>>> + 'pa': 'AudiodevPaOptions', >>>>> + 'sdl': 'AudiodevNoOptions', >>>>> + 'spice': 'AudiodevNoOptions', >>>>> + 'wav': 'AudiodevWavOptions' } } >>>>> + >>>>> +## >>>>> +# @AudioFormat >>>>> +# >>>>> +# An enumeration of possible audio formats. >>>>> +# >>>>> +# Since: 2.4 >>>>> +## >>>>> +{ '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 format to use when using fixed settings >>>> >>>> Are these guys used when @fixed-settings is off? >>> >>> No. >> >> If @fixed-settings, are the other three all required? If not, what are >> their defaults? > > No, they all have defaults: 44100 Hz, 2 channels and s16 format. Okay, this sort of explains why you have @fixed-settings. My first thought was that @fixed-settings is redundant, because we can have any of @frequency, @channels, @format imply fixed settings. Except that doesn't let you ask for the *default* fixed settings, as you have to specify at least one. What's the default for @fixed-settings? What if I specify frequency, channels or format together with explicit fixed-settings: false? > I > guess I should also document it... Yes, please. >>>>> +# >>>>> +# @buffer: #optional the buffer size (in microseconds) >>>> >>>> @buffer suggests this is a buffer, not a buffer length given as time >>>> span. @buffer-len? >>> >>> Ok. (It used to be called buffer-usecs before I changed everything to >>> microseconds.) >>> >>>> >>>>> +# >>>>> +# @buffer-count: #optional number of buffers >>>>> +# >>>>> +# Since: 2.4 >>>>> +## >>>>> +{ 'struct': 'AudiodevPerDirectionOptions', >>>>> + 'data': { >>>>> + '*fixed-settings': 'bool', >>>>> + '*frequency': 'int', >>>>> + '*channels': 'int', >>>>> + '*voices': 'int', >>>>> + '*format': 'AudioFormat', >>>>> + '*buffer': 'int', >>>>> + '*buffer-count': 'int' } } [...]