QAVF 音频共享vdev virtio-snd

Provide audio functionality to guests running in hypervisor VMs

Synopsis

vdev virtio-snd
  [loc addr intr intr]
  [stream type
    [nid node_id]
    [rates audio_rates]
    [formats audio_formats]
    [channels numbers_of_channels | chmap map *]
    [pcmpath host_path]
    [audio_type type] ]*
  [control name
    [nid node_id]
    [ctlpath mixer_control_path]
    [switchname mixer_switch_name]
    [switchdev mixer_switch_device]
    [groupname mixer_group_name]
    [groupindex mixer_group_index]
    [groupcaps mixer_capabilities] ]*

Options

loc addr

Set the base address of the registers. This option, along with intr, is necessary only when you want to present the vdev as an MMIO device. See “Setting the guest interrupt” for more information.

intr intr

Specify the guest interrupt that is generated when the host or another guest sends a notification of an update to shared memory (e.g., gic:44). This option, along with loc, is necessary only when you want to present the vdev as an MMIO device. See “Setting the guest interrupt” for more information.

stream type

Set the type of stream, as a case-sensitive string, to one of:

playback
capture

This option establishes a context: all options that follow are parameters that apply to this context until another stream option, a control option, or the end of the vdev configuration is reached.

If you don’t specify any parameters for this stream, the vdev sets the pcmpath option to either pcmPreferredp for a playback stream or pcmPreferredc for a capture stream. For all other parameters (except for the audio_type option which applies only to playback streams), the vdev defaults to the hardware capabilities of pcmPreferredp and pcmPreferredc for playback and capture PCM streams, respectively, in the host. For playback streams where you don’t specify any parameters, the audio_type option’s default is "" (the empty string), which gets interpreted as the default audio type.

nid node_id

Specify the numeric node ID corresponding to the current entity. This option is used to group multiple entities, where an entity can be a PCM stream or audio control.

rates audio_rates

Define the list of audio rates, in Hertz, that may be exported to the guest. Only the rates from this list that are supported by the host PCM device will be exported.

This can be a list of discreet rates or the minimum and maximum rates. In the first case, the audio_rates string must be a colon-separated list: rate1[:rate2[…]*]. In the second case, it must be a hyphen-separated value pair: min_rate-max_rate.

In either format, the listed values must be among the following valid rates:

8000
11025
12000
16000
18900
22050
24000
32000
44100
48000
64000
88200
96000
176400
192000

For example:

vdev virtio-snd
...
  stream playback
    pcmpath pcmPreferredp
    rates 44100:48000:96000
...

formats audio_formats

Set the audio formats. The audio_format string is a colon-separated list of the formats that may be exported to the guest. Only the formats from this list that are supported by the host PCM device will be exported.

Valid formats are as follows:

ima_adpcm
mulaw
alaw
s8
u8
s16
u16
s24_3
u24_3
s24
u24
s32
u32
float
float64
iec958_subfr

For example:

vdev virtio-snd
...
  stream playback
    pcmpath pcmPreferredp
    formats s16:s32:s24_3:s24
...

channels numbers_of_channels

Set the numbers of channels that may be exported to the guest for the current stream. Only the values indicated by this option that fall within the host PCM device’s channels range will be exported.

This option can contain a list of discreet numbers of channels or a range of channels. In the first case, the numbers_of_channels string must be a colon-separated list: num1[:num2[…]*]. In the second case, it must be a hyphen-separated value pair: min_channels-max_channels.

All host channel maps with a number of channels satisfying this option are exported to the guest. If discreet numbers are given (the first case), then a channel map satifies this option if its number of channel positions matches one of the values in the list. If a range of channels is given (the second case), then a channel map satisfies this option if its number of channel positions falls within the specified range.

If channels is not specified, the full range of minimum and maximum channels of the host PCM device is exported. The channels option may not be used if chmap is defined.

chmap map *

Specify a channel map that is exported to the guest for the current stream. This option allows a subset of the host’s channel map to be exported to a guest and to state how the guest channel positions are mapped to host channel positions.

You may define multiple chmap options, with each on its own line. A chmap option contains a list of mappings of guest and host channel positions. Each mapping is a pair of strings that are separated by an equal sign (=). Different mappings are separated by a colon (:). Thus, the map string is formatted as follows: guest_chpos1=host_chpos1:guest_chpos2=host_chpos2

A guest channel position string contains the prefix guest_ followed by the position substring. Similarly, a host channel position string contains the prefix host_ followed by a position substring. Valid position substrings are:

mono — mono stream
fl — front left
fr — front right
rl — rear left
rr — rear right
fc — front center
lfe — low frequency
sl — side left
sr — side right
rc — rear center
flc — front left center
frc — front right center
rlc — rear left center
rrc — rear right center
rc — rear center
flw — front left wide
frw — front right wide
flh — front left high
fch — front center high
frh — front right high
tc — top center
tfl — top front left
tfr — top front right
tfc — top front center
trl — top rear left
trr — top rear right
trc — top rear center
tflc — top front left center
tfrc — top front right center
tsl — top side left
tsr — top side right
llfe — left LFE
rlfe — right LFE
bc — bottom center
blc — bottom left center
brc — bottom right center

For example, you can define a map in which two channel positions are exported to the guest but both map to the same host channel position:

chmap guest_fl=host_fl:guest_fr=host_fl

In this case, audio playback on both the front left and front right guest positions is mixed and directed to the front left position on the host, while audio capture from the front left host position is presented as audio on both guest positions.

You can also define a map that exports one channel position to the guest but provides two corresponding host channel positions:

chmap guest_mono=host_fl,host_fr

Here, audio playback from the single guest position will be written to both the front left and front right positions on the host, while audio capture from the front left and front right host positions will be mixed and presented to the guest as a single channel position (mono).

If one channel map is specified explicitly for a guest, then all channel maps to be exported to that guest must be specified explicitly, using as many chmap options as needed.

If chmap is not specified, all host channel mappings that satisfy the channels option (if it’s defined) are exported; for details, see above. The chmap option may not be used if channels is defined.

pcmpath host_path

Set the PCM path of the host device to be used by the current stream.

To use the default paths in the guest and the host, specify pcmPreferredp for playback and pcmPreferredc for capture. For example, the following settings:

vdev virtio-snd
...
  stream playback
    pcmpath pcmPreferredp
...
  stream capture
    pcmpath pcmPreferredc
...

will create the following paths for audio playback and capture in the host and the guest:

Host	Host	Guest
Playback	/dev/snd/pcmPreferredp	/dev/snd/pcmC0D0p
Capture	/dev/snd/pcmPreferredc	/dev/snd/pcmC0D0c

In the guest the paths are constructed as follows:

/dev/snd/pcmCcardDdevicetype

where:

card is the number of the physical card in the host with the device; this is usually 0 (zero) because most boards have only one card
device is the device number
type is the stream type: either p for playback or c for capture

audio_type type

This option is not relevant if the host does not use audio management or the host PCM stream does not use a software mixer.

Set the audio type that the host must use for mixed audio that the guest plays in the current audio stream. For playback streams only.

The host must not use any audio types that can be preempted by higher priority audio types. The preemptable audio types are those that have the preemptable property enabled in the audio type definition that is part of the audio policy configuration file.

If you don’t specify this option, an audio type of default is used. For more information on audio types, preemption, and the syntax of the policy configuration file, see the “Audio Concurrency Management” chapter of the Audio Developer’s Guide.

control name

Specify the name that identifies an audio control in the guest space. This option allows guests to access audio switch controls and audio mixers (group controls) in the host. You can specify as many controls as you want.

This option establishes a context: all options that follow are parameters that apply to this context until another control option, a stream option, or the end of the vdev configuration is reached.

nid node_id

When used after a control option, this option has the same meaning as when it’s used after a stream option. For details, see the previous nid description.

ctlpath mixer_control_path

Specify the path of the exposed audio control in the host. For a switch control, the device name will be in the form controlCcard. For a group control, it will be in the form mixerCcardDdevice. (Here, card and device are numeric indexes.) The device directory is expected to be /dev/snd. If you don’t specify this exact directory at the start of the full path, the vdev adds it.

switchname mixer_switch_name

Indicate the name for the host mixer switch.

If you set this option for a control, you can’t set any group* options.

switchdev mixer_switch_device

Specify the device number for the host mixer switch. This must be a 32-bit, positive number. This option is required only if the host card has more than one mixer device. If you omit this option, the default value is 0.

If you set this option for a control, you can’t set any group* options.

groupname mixer_group_name

Indicate the name for the host mixer group.

If you set this option for a control, you can’t set any switch* options.

groupindex mixer_group_index

Specify the index for the host mixer group. This must be a 32-bit, positive number. This option is required only if the host mixer device has more than one group with the same name. If you omit this option, the default value is 0.

If you set this option for a control, you can’t set any switch* options.

groupcaps mixer_capabilities

Indicate the audio capabilities (i.e., functions) supported by the host mixer group. The option argument must be a list of strings separated by colons (:), with no spaces. At least one of the following strings, which correspond to specific capabilities, must be specified: volume, mute, gain, balance, and fade.

If you set this option for a control, you can’t set any switch* options.

Description

(ARM and x86) This audio vdev provides guests with access to audio functionality in the host. The vdev configuration can include any number of stream options, which allow the guest to access playback and/or capture streams for PCM devices in the host.

The options that immediately follow a stream option configure properties of that audio stream. If you specify the pcmpath option, but don’t provide any further options, the configuration uses the hardware capabilities of the specified host PCM device.

To take advantage of the audio management capabilities of the host, you can configure the vdev, through the audio_type option, to replicate any host playback PCM channel for any audio type supported on the host.

Use the other channel configuration options (rates, formats, etc.) to restrict the capabilities made available to the guest’s VirtIO sound driver; this allows the guest driver to use only a subset of the capabilities provided by the PCM channel in the host. For example, if the PCM channel supports rates of 48000:44100:32000, but the audio vdev’s rates option is set to 44100, the driver advertises only this particular rate to clients in the guest. Using this strategy, you can lock the sample rate used in the guest to a single value.

The vdev configuration can include control options, and related options that immediately follow, to configure properties of audio controls. These options are virtio-snd extensions. For Android guests, Automotive Android requires the host to expose audio controls specific to the use of Bluetooth HFP voice; these controls can be made available to the guest through the audio controls extensions.

For a given audio control, you must provide its device path on the host, and you must name either a host mixer switch or host mixer group and configure its properties. For groups, you can indicate the audio capabilities available to the guest, such as volume setting, muting, and fading.

Setting the guest interrupt

If the host is an x86-based platform, or if a PCI server is set up in a guest, you can omit the loc and intr options. The vdev then presents itself to the guest via the PCI bus, with the vendor ID/device ID pair 0x1C05/0xF000, where 0x1C05 is the BlackBerry vendor ID and 0xF000 is the device ID.

Otherwise, you need to specify these options as part of the VM configuration file (.qvmconf) for the guest; the values you specify are passed to the guest driver, deva-ctrl-virtio. For more information, see “Common vdev options” in the “Virtual Device Reference” chapter in the *QNX Hypervisor User’s Guide.

Example

The following configuration example makes the virtio-snd vdev present itself as an MMIO device, and defines streams for audio playback and capture from a PCM device in the host:

vdev virtio-snd
    loc 0x20020000
    intr gic:47
    stream playback
        nid 0
        pcmpath pcmPreferredp
    stream capture
        nid 0
        pcmpath pcmPreferredc
        formats s16