I Parent topic: I

io-audio

Start one or more audio drivers

Syntax:

io-audio [-c config_file] [-v[v]...]
         [-l level]
         [-m opt[,opt...]]
         [-o opt[,opt...]] 
         [-U string]
         [-d driver[opt[,opt...]]]

Runs on:

QNX Neutrino

Options:

-c config_file
Load the specified audio configuration file. For more information, see “Audio configuration file,” below.
-d driver [opt[,opt...]]
Load the specified driver and pass it the given driver options. The driver name is the name of the shared object without the deva-ctrl- prefix and the .so extension. For example, to load the deva-ctrl-audiopci.so shared object, specify audiopci as the driver name. You can start more than one driver by using multiple -d command-line options. For information on the drivers and any specific options, see the entries for the deva-ctrl-* shared objects.
Note:

If you want to start the driver from a configuration file, all the following driver options can be specified using the options key-value pair in the [CTRL] section, with the exception of the unit option.

All audio drivers support the following card options:

cap_name=name
The symbolic name to assign to the PCM capture device.
config=path_to_file
Tip: This driver option is available if you have Audio component BuildID 387—October 2, 2017 (7.0.387.S201710021920) or a later update installed.

This option allows you specify driver settings in a separate, driver-specific configuration file.

dindex=number
The device number that additional following options apply to.
play_name=name
The symbolic name to assign to the PCM playback device.
restrict_interface=capture|playback|both
Enable restricted access to the capture, playback, or both PCM device interfaces. These restrictions are provided with these io-audio manager-specific process abilities:
  • io-audio/capturerestricted — Restrict applications from capturing audio data. To apply this restriction, set the driver option to capture.
  • io-audio/playbackrestricted — Restrict applications from playing audio data. To apply this restriction, set the driver option to playback.
If you wanted to restrict applications from both capturing and playing audio data, set the driver option to both.
After you apply your restrictions, you may want to grant permissions to capture or play audio data only to specific applications on your system. For example, let's say you restricted all applications on your system from capturing audio data, use this command to start io-audio manager: 
io-audio -d audiopci -dindex=0,
restrict_interface=capture
You could then grant access to a specific application by using another process to grant permission. For example, here we show a way how you can use the on command (which has been granted root privileges on the system) to grant the wave application (which doesn't have root or the io-audio/capturerestricted ability): 
on -u100:100 -A able=io-audio/capturerestricted,
allow,nonroot waverec /temp/test.wav
unit=number
The configuration of the card number to use for the driver.
Tip: If you have Audio component BuildID 387—October 2, 2017 (7.0.387.S201710021920) or a later update installed, the following applies:

When using the mount command to dynamically load a driver, you can use the unit number to specify the [CTRL] section to use from the configuration file. For more information on the different scenarios, see the following “Description” section. .

-l level
Explicitly set the level of output verbosity. You can also use the -v[v...] option to specify verbosity.
-m opt[,opt...]
Memory options. The opt variable can be any of the following:
pool_size=kbytes
The size of the DMA memory pool to create, in KB. The default is 0 KB.
pool_name=string
The name of a shared memory object or typed memory object to map and use as DMA memory pool. This object must be physically contiguous memory.
Note: If the pool name is a reference to a typed memory object, then you must also provide the pool_size. If the pool name is a reference to a shared memory object, then the pool is automatically sized to be the size of the object.
-o opt[,opt...]
Global options to apply to all drivers (specified with the -d option) that follow on the command line. The opt variable can be any of the following:
config_write_delay=time
The time in seconds after the last change before sound card settings are written to disk. The default value is -1, which prevents the settings from ever being written. The settings are written to a file at /etc/system/config/audio, which must be located on a writable filesystem.
data_thread_prio=priority
The priority of the software mixer thread. The default is 25; values that are outside the priority range for the round-robin scheduler are discarded.
disable_sw_mixer
On cards that have only a single channel in hardware, don't use software techniques to increase the maximum number of playing channels. By default, the software mixer is enabled.
intr_thread_prio=priority
Set the priority of the interrupt service threads. The default is 50; values that are outside the priority range for the round-robin scheduler are discarded.
max_dma_buf_size=size
The maximum size, in kilobytes, for the DMA buffer. The default is 256 KB; io-audio uses a minimum size of 16 KB.
policy_conf=path_to_file
The location of the audio policy configuration file, such as audio ducking, volume ramping, and auto-pausing on the system. For more information, see the Audio Management chapter in the QNX Neutrino Audio Developer's Guide.
Tip: If you have Audio component BuildID 594—January 17, 2018 (7.0.594.S201801171044) or a later update installed, this option must be specified in the [AUDIOMGMT] section in the audio configuration file.
sw_mixer_rate=[FAHQ|FA|Lvalue]
Set the method of selecting the sampling frequency used by the PCM software mixing device if the underlying hardware device supports multiple rates:
  • FAHQ (First Active High Quality) — select the highest HW-supported sample rate that best fits the first active clients requested rate (all subsequent subchannels will be locked to the active rate).
  • FA (First Active) — select the sample rate based on the First Active client's requested sample rate; all subsequent subchannels are locked to the active rate.
  • Lvalue — lock the sample rate to the rate specified by value, regardless of the client's requested rate.

The default is FAHQ.

sw_mixer_samples=num
Adjust the fragment size used by the software mixer to something other than the default of 1024 samples. Here's an example of how to calculate the value to pass in with this option:

sw_mixer_samples = sample_rate (in samples per second) * fragment_length (in seconds)

In QNX Neutrino 7.0 or later, sw_mixer_samples is the number of samples per channel.

-U string
(QNX Neutrino 7.0 or later) This option is recognized only if you run as root. Once the utility is running, it will run as the specified user with the proper process abilities so that the program doesn't need to run as root.
The string can be in one of these forms:
  • uid[:gid[,sup_gid]*]
  • user_name[,sup_gid]*

In the second form, the primary group is the one specified for user_name in /etc/passwd.

-v[v...]
Increase the level of output verbosity. Additional v characters increase the verbosity. You can also use the -l option to specify verbosity.

Description:

The io-audio provides support for dynamically loaded audio-driver modules. This utility enables you to load the audio drivers specified by the -d options when you start io-audio.

You can run this command as root or a non-root user. When you run this command as a non-root user, it must be granted the proper process abilities as specified in the “Abilities” section below. The io-audio manager includes custom permissions to restrict capture and playback. For more information, see the restrict_interface driver option for the driver (-d) option.

Note: Graphics drivers run at a higher priority than applications, but they shouldn't run at a higher priority than the audio driver, or else breaks in the audio occur. The resgmr threads inherit their priority from the client, which makes the request. The internal thread's priorities can be adjusted using the intr_thread_prio and data_thread_prio option using this command's options (-o) parameter.

Once io-audio has started, you can dynamically load and unload drivers using the mount and umount commands.

Mounting a driver

Here's how you can use the mount command can be used to dynamically load drivers. For example, this command: 

io-audio -dusb -daudiopci

gives the same result as this sequence: 

io-audio
mount -T io-audio usb
mount -T io-audio audiopci
Note: When searching for shared objects, the io-audio uses the LD_LIBRARY_PATH environment variable.

Unmounting a module

To unload a module, use a command like this: 

umount /dev/snd/controlC0
Tip: If you have Audio component BuildID 387—October 2, 2017 (7.0.387.S201710021920) or a later update installed, the following applies:

Previously, the audio configuration file could be read only when io-audio starts. If you wanted to dynamically load a driver, there was no mechanism available to use driver settings from a configuration file.

In this update, unit (card) numbers are now reserved for drivers defined in the [CTRL] sections of the audio configuration file. The numbers are reserved based on the order that the [CTRL] sections appear in the file. Additionally, the unit key in the [CTRL] section can be used to define a specific card number unrelated to the section's position in the file. This ensures that card numbers are assigned at io-audio startup via the configuration file are deterministic regardless of further runtime loading/unloading of driver DLLs. Card numbers assigned for the lifetime that io-audio runs. Unloading the card (e.g., umount /dev/snd/controlCx) doesn't release the card number back to the system.

When you dynamically load a driver DLL at runtime using the mount command, providing the unit option causes io-audio to first search the audio configuration file for a [CTRL] section that matches the provided unit and driver name. If a [CTRL] section with a matching unit number isn't found, then the driver (DLL) is loaded based solely on the options provided to the mount command. If a [CTRL] section with a matching unit number is found, the driver name is used to validate the use of the [CTRL] section to load the DLL; if the driver name doesn't match, the mount operation will fail. Here's an example of using the unit option to dynamically load a driver DLL: 
# mount -Tio-audio -ounit=2 deva-ctrl-mcasp.so
Note: Card numbers must be unique, any attempt to mount a driver DLL with a unit number that's in use will fail.
A driver DLL can also be dynamically mounted using a driver-specific configuration file by using the config=path_to_file option. If no unit number is provided, then the first [CTRL] section with the matching driver name is used to load the driver. If the unit option is provided, then a [CTRL] section that matches both the unit number and driver name is used. If no match is found, then the attempted mount operation fails. 
#mount -Tio-audio -oconfig=mydriver.conf deva-ctrl-mcasp.so
#mount -Tio-audio -oconfig=mydriver.conf,unit=2 deva-ctrl-mcasp.so
The following driver-specific configuration file (mydriver.conf) has two entries that matches the previous mount commands. The first [CTRL] section would be used when you don't provide the unit option, but if you do as in the second example, then the second [CTRL] section is used: 
[CTRL]
name=mcasp
options=clk_mode=master

[CTRL]
name=mcasp
unit=2
options=clk_mode=master
Note: Unlike the audio configuration file, driver-specific configuration files must explicitly specify the unit key to be used in conjunction with a mount command that includes the unit option.
Note: It's important that you don’t set unit as an option for the options key in the audio configuration file or driver-specific configuration file, instead use the explicit unit key. For example, the following is invalid: 
[CTRL]
name=mcasp
options=unit=2,clk_mode=master
The correct configuration with the explicit unit key is as follows: 
[CTRL]
name=mcasp
unit=2
options=clk_mode=master
Tip: If you have Audio component BuildID 594—January 17, 2018 (7.0.594.S201801171044) or a later update installed, the following applies:
Two special options can be used in conjunction with the audio configuration when you use the mount command:
all
Mounts all currently unmounted (e.g., deferred or previously unmounted) cards that are specified in the audio configuration file. Any other options provided to the mount command are ignored. For example: 
# mount -T io-audio all
acoustics
If the QNX Acoustics Management Platform 2.0 is available, mount all currently unmounted Acoustic Control Server (ACS) and Acoustic Management Platform Functional Modules (AFM) cards specified in the audio configuration file. Any other options provided to the mount command are ignored. 
# mount -T io-audio acoustics

Audio configuration file

The audio configuration file is optional, but is easier to use and more flexible than using the corresponding command-line options. In order to load an audio configuration file, specify the -c configuration_file_path option when you start io-audio. Global and memory options provided on the command line override the corresponding audio configuration file settings. If you specify deva-* shared objects both on the command line (via the -d option) and in the audio configuration file (via [CTRL] sections), each is treated as an individual and independent request to load or mount a driver.

Options from the [CTRL] section take precedence over options defined (and supported) in both the [GLOBAL] and [CTRL] sections. Global options provided via the command line (-o) are also overridden by options defined in the [CTRL] section in the audio configuration file. In general, we recommend that you limit the use of [GLOBAL] options and use the options under the [CTRL] section.

The standard location for this file is /etc/system/config/audio/io-audio_platformVariant.conf. If an error occurs while parsing the audio configuration file, io-audio won't start.

When you're using indexed PCM mixer or input splitter keys, the index is that of the parent PCM device that the mixer/splitter is being created for, not the index of the mixer/splitter PCM device that's being created.

The general syntax is as follows:

#
Anything after a number sign on a line is considered a comment.
[ name ]
A string enclosed in square brackets indicates the start of a section.
  • The name is case-insensitive.
  • Leading and trailing spaces are removed, but white space is allowed within the name.
  • Extra characters other than comments after the closing bracket cause the section to be discarded.
  • Duplicated section names are allowed. However unless the section specifically specifies multiples (see below), in most cases only the keys in the first section of that name in the file are used. The Acoustic Control Server section is an exception to this; multiple ACS sections will cause an error.
key = value
A key-value pair.
  • The key is case-insensitive.
  • The value is case-sensitive.
  • Leading and trailing spaces are removed from the key and value.
  • A key must have a value; a value must have a key.
  • White space within a key or value causes the key-value pair to be discarded.
  • All valid key-value pairs are associated with the section preceding them in the file.
  • If there are multiple keys of the same name within a section, the value of the last key in the section is used.
  • An indexed key is a key with the '_index' suffix appended to the key name (e.g., key_1).
  • Nonindexed key values apply globally for the section that they're defined in. You can override this value on a device-by-device basis with indexed keys.
  • Key/value pairs at the start of the file (before a section has been specified), or after an invalid section are discarded.
  • Tip: If you have Audio component BuildID 594—January 17, 2018 (7.0.594.S201801171044) or a later update installed, the following applies:
    If you specify an ampersand (&) before the key name, the value is appended to the key's current value. For example, the following: 
    options=clkmgmt=0
&options=,dindex=1,play_name=defaultp
&options=,dindex=2,cap_name=defaultc
    Is the same as: 
    options=clkmgmt=0,dindex=1,play_name=defaultp,dindex=2,cap_name=defaultc

[GLOBAL] section

The keys in the [GLOBAL] section include the following:

Key Default Description
config_write_delay -1 The time in seconds after last change before soundcard settings are written to disk. The default value of -1 prevents the settings from ever being written.
max_dma_buf_size 256 The maximum DMA buffer size, in KB. The minimum value for this parameter is 16 KB.
disable_sw_mixer 0 Disable the PCM Software mixer (0 / 1). If 0, a PCM Software mixer is instantiated.

If 1, don't use software techniques to increase the maximum number of playing channels on cards that have only a single channel in hardware.

You should specify this in the [CTRL] section for each card rather than at this point, to simplify enabling/disabling of the PCM software mixer on a card-by-card basis.

policy_conf None The location of the audio policy configuration file for audio policies, such as audio ducking, volume ramping, and auto-pausing on the system. For more information, see the Audio Management chapter in the QNX Neutrino Audio Developer's Guide.
Tip: If you have Audio component BuildID 594—January 17, 2018 (7.0.594.S201801171044) or a later update installed, you can't use this option to specify the location of the audio policy configuration file. Instead, you must use the policy_conf key in the [AUDIOMGMT] section of the audio configuration file.
sw_mixer_ms None. The mixer fragment size, in milliseconds. No default and this isn't used if a value isn't specified. You can also set this in the [CTRL] section for each card.
Tip: If you have the QNX Acoustic Management Platform 2.0 and the Audio component BuildID 594—January 17, 2018 (7.0.594.S201801171044) or a later update installed, you must specify this key to playback through a PCM software mixer if you use AMP Functional Modules (AFMs).

This key overrides sw_mixer_samples. For more information, also see the ms_frag_period key in the [AFM] section.

sw_mixer_samples 1024

The mixer fragment size, in samples per voice. This is the deprecated method of specifying the mixer fragment size (overridden by sw_mixer_ms if specified). The minimum is 64 bytes, and the maximum 512 KB.

Because you cannot use a samples value to specify the fragment size the PCM input splitter uses, if you use the input splitter, you cannot use this option to specify the fragment size the PCM software mixer uses.
sw_mixer_rate FAHQ The method for setting the PCM software mixer sample rate. If the underlying hardware supports multiple sample rates, the rate method is used to select which sample rate used to configure the PCM Software mixer:
  • FAHQ — First Active, High Quality (44.1Khz and above)
  • FA — First Active
  • Lvalue — locked to the specified rate, where value is in the range 100–200000.

Note the “first active” refers to the sample rate requested by the first active client.

intr_thread_prio 50 The interrupt service thread's priority. The value is discarded if it isn't within the valid range of round-robin priorities.
data_thread_prio 25 The minimum thread priority. The value is discarded if it isn't within the valid range of round-robin priorities.
verbosity 0 The logging verbosity level. using a Bit-masked log level:
  • Bit 0 DRIVER — Debug information from drivers. (e.g., you can also use INTERRUPT or CODEC for driver-level debug information).
  • Bit 1 CONTROL — Debug information from the control path, state machine, etc.
  • Bit 2 PCM — Logs control type information.
  • Bit 3 MIXER — Mixer related debug debug information, such as volume and mute controls. Debug information from mixer DLL and codec level deva-* DLLs.
  • Bit 4 IO_ADO — High-level Audio library debug information.
  • Bit 5 RESMGR — Debug information from the resource manager (resmgr_*) callbacks.
  • Bit 6 POWER — Debug information related to power management.
  • Bit 7 MISC — Miscellaneous debug information.
  • Bit 8 CODEC — Codec-level debug information from the PCM software mixer and deva-* DLLs.
  • Bit 30 INTERRUPT — Interrupt handler debug information. (dma_interrupt, deva interrupt callbacks, etc.)
  • Bit 31 MEMORY — Memory allocation debug information.
pool_name None The name of a shared memory or typed memory object to map and use as a DMA memory pool. The object must be physically contiguous memory.

If the pool_name refers to typed memory, then you must also provide the pool_size option. If the pool_name refers to a shared memory object, then the pool is automatically sized to the size of the object (pool_size is ignored if provided). The io-audio service first tries to open the name as typed memory; if this fails, it tries to open the name as a shared memory object.

pool_size   The size of the DMA memory pool to create, in KB. If no pool_name is provided, then an anonymous object is created to the pool_size specified. If the pool_name refers to typed memory, then you must also provide the pool_size.
pcmPreferredp None The name of the preferred playback device; that is, the device opened with snd_pcm_open_preferred() when SND_PCM_OPEN_PLAYBACK is specified

io-audio first parses the file /dev/snd/preferences, if it exists, for the preferred device. If no device is specified in this file or the device can't be found, the io-audio service attempts to set the preferred device using this option. If this option isn't specified or the device cannot be found, the first valid playback device (based on the deva-* load order) is used.

pcmPreferredc None The name of preferred capture device; that is, the device opened with snd_pcm_open_preferred() when SND_PCM_OPEN_CAPTURE is specified.

io-audio first parses the file /dev/snd/preferences, if it exists, for the preferred device. If no device is specified in this file or the device can't be found, the io-audio service attempts to set the preferred device using this option. If this option isn't specified or the device cannot be found, the first valid playback device (based on the deva-* load order) is used.

[CTRL] section(s)

The keys in the [CTRL] section include the following:

Key Default Description
name None The name of the sound card HW interface DLL. Required; omit the deva-ctrl- prefix and the .so suffix when you're specifying the driver name.
options None Driver-specific options as documented for the sound card DLL. Each option can be delimited using a percent sign (%).
As part of the card options, the following options can be specified for each PCM device:
  • dindex — the device number to which the following options apply
  • cap_name — the PCM capture device alias
  • play_name — the PCM playback device alias
  • output_classes — the output class used for DRM purposes.
  • restrict_interface — enable restricted access to the capture, playback, or both PCM device interfaces
For example, the following creates an alias for the capture aand playback PCM device interfaces for device number 2 to devC and devP, respectively. 
options=dindex=2,cap_name=devC,play_name=devP
Tip: If you have Audio component BuildID 594—January 17, 2018 (7.0.594.S201801171044) or a later update installed, don't specify the unit as driver level option with the options key. Instead, use the unit key-value pair specified below in your configuration file.
unit -1
Tip: This key is available if you have Audio component for BuildID 387—October 2, 2017 (7.0.387.S201710021920) or a later update installed.
Card or unit numbers must be unique, non-negative number. This value is used as the card number to mount the card on the filesystem.

If this key isn't provided or if the number is a negative, a unique value is generated with the first available number starting at zero. After io-audio starts, the unit (card) number corresponds to the DLL mounted as specified in the audio configuration file. These numbers are reserved for the life of io-audio and can be reused only if the corresponding DLL has previously been unmounted. For more information, see “ Driver-specific configuration file”.

input_splitter_enable 0 Enable or disable the input splitter on PCM devices that have a capture device (0 / 1). An optional _index suffix can be appended to the key to target the option at a specific PCM device.

If you specify this parameter without an index suffix, the value applies to every capture-capable PCM device under the card created by this section.

If you specify this parameter with an index suffix, then the applied value (0/1) takes effect only for the PCM device specified by the index, overriding the value specified by an instance of the key without an index suffix.

To ensure that the input splitter can route data to a PCM software mixer device, both devices (input_splitter and PCM software mixer) must operate at the same data fragment size, which you set via the sw_mixer_ms option, and thus the sw_mixer_ms option is required when you're using the input splitter (even if the PCM software mixer device isn't being used).

Note: If you use the QNX Acoustic Management Platform 2.0, You must specify this parameter if multiple AFMs are capturing simultaneously from the same capture device on this sound card.
disable_sw_mixer 0 Disable the sw mixer (0 / 1). An optional _index suffix can be appended to the key to target the option at a specific PCM device.

If the value of this parameter is 0, a PCM Software mixer is instantiated.

If it's 1, io-audio doesn't use software techniques to increase the maximum number of playing channels on cards that have only a single channel in hardware.

For a Bluetooth device, this should be 1 (disable the PCM software mixer).

This parameter overrides the corresponding option from the [GLOBAL] section or the command line for this card.

Note: If you use the QNX Acoustic Management Platform 2.0, This parameter must be 0 if AFMs are playing simultaneously to the same playback device on this sound card.
sw_mixer_ms None The mixer fragment size, in milliseconds. No default and this isn't used if a value isn't specified. An optional _index suffix can be appended to the key to target the option at a specific PCM device.

This parameter overrides the corresponding option from the [GLOBAL] section or the command line for this card.

  • You must specify this parameter if any AFMs are configured to play back through the PCM software mixer on this card.
  • This parameter overrides sw_mixer_samples. See also ms_frag_period in the [AFM] section.
sw_mixer_samples 1024 The mixer fragment size, in samples per voice. An optional _index suffix can be appended to the key to target the option at a specific PCM device. This is the deprecated method of specifying the mixer fragment size (overridden by sw_mixer_ms if specified). The minimum is 64 bytes; the maximum 512 KB.

This parameter overrides the corresponding option from the [GLOBAL] section or the command line for this card.

Note: This key isn't valid when you are using the QNX Acoustics Management Platform 2.0.
sw_mixer_rate FAHQ The PCM software mixer sample rate. An optional _index suffix can be appended to the key to target the option at a specific PCM device. If the underlying hardware supports multiple sample rates, the rate method is used to select which sample rate is used to configure the PCM software mixer:
  • FAHQ — First Active, High Quality (44.1Khz and above)
  • FA — First Active
  • Lvalue — locked to specified rate, where value is in the range 100–200000

Note that First Active refers to the sample rate requested by the first active client.

This parameter overrides the corresponding option from the [GLOBAL] section or the command line for this card.

sw_mixer_cap_name pcmCxDxp_ref The symbolic name for PCM software mixer's reference devices, where x is the numeric index of the card and device. An optional _index suffix can be appended to the key to target the option at a specific PCM device. If you create multiple PCM mixers, and you provide this key without an index suffix, then a name collision occurs, and the PCM mixer creation fails.
Note: If you have the QNX Acoustics Management Platform 2.0 available, you can use the symbolic name instead of the PCM device name in the audio configuration file to simplify AFM device assignments.
sw_mixer_limiter 0 Enable the PCM software mixer limiter. An optional _index suffix can be appended to the key to target the option at a specific PCM device.

If 1, enable a 1 ms soft look ahead limiter on the main media mixing path through the PCM software mixer.

If 0, audio streams are strictly added and hard-clamped.

Tip: This key is available if you have Audio component BuildID 594—January 17, 2018 (7.0.594.S201801171044) or a later update installed.
sw_mixer_max_references 0 The maximum number of media references available for capture from the PCM software mixer. An optional _index suffix can be appended to the key to target the option at a specific PCM device.
afm_mixer_enable 0 Enable mixing of the AFM outputs separately from the media streams (0 / 1) in the PCM software mixer. An optional _index suffix can be appended to the key to target the option at a specific PCM device. If the value of this parameter is 0, the AFM mixer is disabled; if it's 1, the AFM mixer is enabled. This value is discarded if there are no configured AFMs.
Tip: You can use this key if you have the QNX Acoustic Management Platform 2.0 and the Audio component BuildID 594—January 17, 2018 (7.0.594.S201801171044) or a later update installed.
afm_mixer_max_references 0 The maximum number of AFM references available for capture from the AFM mixer. An optional _index suffix can be appended to the key to target the option at a specific PCM device. This value is discarded unless afm_mixer_enable is 1 and there are configured AFMs. This value should be equal to or greater than the total number of AFM references required by all configured AFMs and ACS.
Tip: You can use this key if you have the QNX Acoustic Management Platform 2.0 and the Audio component BuildID 594—January 17, 2018 (7.0.594.S201801171044) or a later update installed.
afm_mixer_atten_disable 0 Disable AFM mixer attenuation.

This value is discarded unless afm_mixer_enable is set to 1 and there are configured AFMs.

Normally, when the AFM mixer is enabled there is an implicit 6 dB attenuation of both the main (audio stream) and the AFM mixing paths in the PCM mixer, so that the combined output of these two paths with never need to be clamped, avoiding the audio artifacts which could arise when performing acoustic echo cancellation.

This implicit attenuation can be disabled for target systems where it is known that the AFM audio and media playback will never run concurrently. This can be true in systems where only the voice AFM is integrated. However if integrating ASD or ICC, which do typically run concurrently with media playback, this key shouldn't be used.

If set to 1, the AFM mixer attenuation is disabled for all devices on a card; otherwise if set to 0, the AFM mixer attenuation is enabled for all devices. An optional _index suffix can be appended to the key to target the option at a specific PCM device.

Tip: You can use this key if you have the QNX Acoustic Management Platform 2.0 and the Audio component BuildID 594—January 17, 2018 (7.0.594.S201801171044) or a later update installed.
max_concurrent_afms 0 The maximum number of AFMs that are expected to be concurrently active. This value is discarded unless afm_mixer_enable is set to 1 and there are AFMs that are configured.

Normally the AFM mixer gain is 1/afm_cnt to avoid clipping (non-linearity) when mixing, where afm_cnt is the number of AFMs, which have a pcm_local_playback device and an afm (default) sw_mixer_route. If you know that AFMs aren't going to be concurrently used, or if the AFMs are tuned correctly, this restriction can be overridden to a value less than afm_cnt.

If this value is set to 0, the key/value pair is ignored for a all devices. An optional _index suffix can be appended to the key to target the option at a specific PCM device.

Tip: You can use this key if you have the QNX Acoustic Management Platform 2.0 and the Audio component BuildID 594—January 17, 2018 (7.0.594.S201801171044) or a later update installed.
ducking_output None The name of the ducking output to use. An optional _index suffix can be appended to the key to target the option at a specific PCM device.
Tip: This key is no longer available if you have Audio component BuildID 594—January 17, 2018 (7.0.594.S201801171044) or a later update installed. Instead, use the audiomgmt_id key.
audiomgmt_id None Name of the audio management context/output to be used. An optional _index suffix can be appended to the key to target the option at a specific PCM device.
Tip: This key is available if you have Audio component BuildID 594—January 17, 2018 (7.0.594.S201801171044) or a later update installed.
defer_mount 0 Defer mounting of the DLL until a later time.

When set to 0, the card is mounted at startup. When set to 1, mounting of the card is deferred until the mount command is issued. The acoustics option can be used with the mount command to mount all AFM cards that were deferred.

Tip: This key is only available if you have Audio component BuildID 594—January 17, 2018 (7.0.594.S201801171044) or a later update installed.

[AUDIOMGMT] sections includes the following:

Tip: The [AUDIOMGMT] is only available if you have Audio component BuildID 594—January 17, 2018 (7.0.594.S201801171044) or a later update installed.
Key Default Description
audiomgmt_id None (Required) Name of the audio management context or output. PCM devices can attach to the audio management context or output using this identifier.
policy_conf None (Required) Path to the audio policy configuration file. The audio policy file contains audio management policies such as volume ramping and audio ducking for the system. For more information, see the “Audio Management” chapter in the QNX Neutrino Audio Developer's Guide.
unit 0 Card number used in the filesystem mount. The card number (unit) must be unique.
Note: This key is used by the first [AUDIOMGT] section. Subsequent unit keys in other [AUDIOMGMT] sections are ignored.

[AFM] section(s)

Tip: The [AFM] section is only available for use if you have the QNX Acoustic Management Platform 2.0 and the Audio component BuildID 594—January 17, 2018 (7.0.594.S201801171044) or a later update installed.
Note: The keys in this section that are prefixed with ap_ only apply to acoustic AFMs. Acoustic AFMs are associated with an acoustic processing library, such as Voice(QNX Acoustics for Voice), ICC (QNX In-Car Communication), and ASD (QNX Active Sound Design).

The keys in the [AFM] section include the following:

Key Default Description
name None The name of the DLL, which is usually an AMP (Acoustic Management Platform) functional module (AFM); this parameter is required and must be one of the following modular libraries:
  • icc — QNX In-Car Communications (ICC) that provides algorithms to improve the ease of communication between passengers within a vehicle.
  • voice — QNX Acoustics for Voice (Voice) that provides algorithms to detect and extract voice from conditions that have lots of noise (wind, road, etc.).
  • asd — QNX Active Sound Design (ASD) to use active-noise cancellation to reduce engine tones, as well as, synthesize sound to support a manufacturer's vision of what their vehicle should sound like.
  • bridge — bridges audio inputs to audio outputs and assumes the clocking for the inputs and outputs is synchronized
Omit the deva-afm- prefix and the .so suffix when specifying the module name (e.g., icc corresponds to deva-afm-icc.so.
unit -1 Card number used in the filesystem mount. Card numbers must be unique. If this key isn't provided or if the value is a negative number, the first available, unique number after zero is generated for the AFM.
audio_type None Audio type that's used by the system to handle audio ducking.
pcm_local_capture None The name of the local capture device. Required for all AFMS.
pcm_local_playback None The name of the local playback device. Required for all AFMs.
pcm_remote_capture None The name of the remote capture device. Required for the Voice AFM.
pcm_remote_playback None The name of the remote playback device. Required for the Voice AFM.
pcm_ref_capture None The name of the acoustic reference capture device. For ICC, if the value is loopback rather than a PCM device name, the ICC output is routed internally to the ICC reference input. Required for the ICC AFM; optional for the Voice AFM.
pcm_media_capture None The name of the media reference capture device. Optional for the ICC AFM.
map_mic_X A 1:1 mapping of the capture voice to library input (e.g., map_mic_0 = 0, map_mic_1 = 1, etc.) Map the capture voice to the acoustic processing microphone input X.
  • Library inputs and capture voices are 0-based.
  • Only one map to a single capture voice is allowed per library input.
  • You must map all library inputs or none.
  • Maps for unused library inputs are ignored.

The Bridge AFM is a special case, since this is a mapping from capture voice to playback voice (rather than library input), so there are exceptions to the above:

  • Maps to multiple playback voices are allowed per capture voice.
  • Not all capture voices need to be mapped.
map_spk_X A 1:1 mapping of library output to playback voice (e.g., map_spk_0=0,map_spk_1=1, etc.). Map acoustic processing speaker output X to playback voice(s); you can specify multiple voices, delimited by commas.
  • Library outputs and playback voices are 0-based.
  • Maps to multiple voices are allowed per library output.
  • You must map all library outputs or none.
  • Maps for unused library outputs are ignored.
  • Maps for non-existent playback voices are ignored.
Note: When acoustic library volume and mute control is enabled (enable_vol_ctl) for an AFM, these keys are used to instantiate the corresponding mixer controls, so they are parsed when io-audio starts and when the AFM is loaded. If there are errors, io-audio won't start. If there isn't acoustic volume control, these keys are parsed when the AFM is started. If there are errors, the AFM won't start.
map_ref_X A 1:1 mapping of acoustic reference voice to library reference input (e.g., map_ref_0=0, map_ref_1=1, etc.) Map the acoustic reference voice to acoustic processing reference input X. ICC and Voice AFMs only.
  • Library inputs and capture voices are 0-based.
  • Only one map to a single capture voice is allowed per library input.
  • You must map all library inputs or none.
  • Maps for unused library inputs are ignored.

These keys are parsed when the AFM is started; if there are errors, the AFM won't start.
map_media_ref_X A 1:1 mapping of media reference voice to library external reference input (i.e., map_media_ref_0=0, map_media_ref_1=1, etc.) Map media reference voice to acoustic processing external reference input X. ICC AFM only.
  • Library inputs and capture voices are 0-based.
  • Maps for unused library inputs are ignored.

These keys are parsed when the AFM is started; if there are errors, the AFM won't start.
ap_dlname The acoustic processing DLL name corresponding to the AFM type:
  • voice: libqwa_qvp.so
  • icc: libqwa_icc.so
  • asd: libqwa_asd.so
 Acoustic processing library .so name
ap_qcf_default None The path to the default acoustic tuning file; /etc/acoustic is the recommended directory for the tuning file (e.g., ap_qcf_default=/etc/acoustic/handsfree.qcf).
ap_qcf_mode None The path to the acoustic tuning file when the mode string is set with snd_afm_set_audio_mode()
ap_gran_syn_dir_default None The path to the directory that contains the acoustic granular synthesis files. ASD AFM only.
ap_gran_syn_dir_mode None The path to the directory that contains the acoustic granular synthesis files when the mode string is set with snd_afm_set_audio_mode(). ASD AFM only
ap_calib_default None The path to the acoustic calibration file. ASD AFM only.
ap_calib_mode None The path to the acoustic calibration file when the mode string is set with snd_afm_set_audio_mode(). ASD AFM only.
ap_dataset_qcf_name None The path to the dataset QCF to apply when the dataset name string set with snd_afm_load_ap_dataset().
ap_enable_diagnostics 0 Enable acoustic library diagnostics; ICC and Voice AFMs only.

If 0, the baseline settings don't turn on diagnostics in the acoustic library. If 1, the baseline settings enable the diagnostics module in the acoustic library. Note that the baseline settings can be overridden by the QCF file.

enable_pass_through 0 Enable pass through (0 / 1). If 0, the acoustic processing library is used. If 1, the acoustic processing library isn't loaded nor used and the audio data is copied from the input to the output of the AFMs.
Note: This option can result in extreme feedback in the case of the ICC and Bridge AFMs.
pcm_play_name voicep The symbolic name for the PCM interface published for playback. Voice AFM only.
pcm_cap_name voicec The symbolic name for the PCM interface published for capture. Voice AFM only.
pcm_disable 0 Disable PCM interface (0 / 1). Voice AFM only. If 0, the voice PCM interface is enabled; if 1, it's disabled.
sw_mixer_route afm The route to use when mixing playback audio (main or afm) in the PCM softare mixer.
  • When the value is afm, playback audio is through the AFM mixer path in the PCM software mixer.
  • When the value is main, playback audio is through the main (media) path in the PCM software mixer.

Normally this value would not be specified and default to afm. You typically use main with the Bridge AFM, where acoustic processing isn't performed and the output is expected to be included in the main (media) reference.

ms_frag_period sw_mixer_ms (when the local playback device is a PCM Software Mixer device) The fragment size, in milliseconds, to use for audio hardware interfacing. You must specify this parameter if the local playback device isn't a PCM Software Mixer device.

When the local playback device is a PCM Software Mixer device, must be a multiple of sw_mixer_ms.

You must always specify this parameter for the Bridge AFM.

The acoustic library fragment period must be a multiple of this value (and implicitly of sw_mixer_ms).

slip_guard_frags 1 Extra frags to ensure consistent startup timing without slippage. 1 frag = maximum of ms_frag_period or acoustic library fragment period.
enable_vol_ctl 0 Enable acoustic library volume and mute control; ICC and Voice AFMs only.

If 0, volume control, that uses the acoustic library gain and mute controls is disabled. If 1, a mixer group that uses the acoustic library gain and mute controls (ICC gain or Voice Receive Gain) to adjust the volume is published.

Note: If both enable_vol_ctrl and enable_mute_ctrl_only are set to 1, enable_vol_ctl takes precedence.
enable_mute_ctl_only 0 Only enable acoustic library mute control; ICC and Voice AFMs only.

If 0, mute control using the acoustic library and gain control is disabled. If 1, a mixer interface that uses the acoustic library mute controls to perform muting is published. This key is used if mute control is required, but the library QCF (.qcf) configuration file is used to set a fixed library gain value.

Note: If both enable_vol_ctrl and enable_mute_ctrl_only are set to 1, enable_vol_ctl takes precedence.
max_vol_db_X
  • ICC: 20 dB
  • Voice: 10 dB
 The maximum output fixed gain setting for speaker output X corresponding to 100% volume set with mix_ctl. This key is ignored if enable_vol_ctl is set to 0. ICC and Voice AFMs only.

This parameter must be >= min_vol_db. If this value is set beyond the ICC/QVP library maximum of 40 dB, a warning is logged, but the value is accepted.

min_vol_db_X
  • ICC: -10 dB
  • Voice: -20 dB
 The minimum output fixed gain setting for speaker output X corresponding to 0% volume set with mix_ctl. This key is ignored if enable_vol_ctl is set to 0. ICC and Voice AFMs only;

This parameter must be <= max_vol_db. If this value is set beyond the ICC/QVP library minimum of -30 dB, a warning is logged, but the value is accepted.

init_vol_X
  • ICC: 35
  • Voice:100
 The initial mix_ctl volume setting at boot (0-100) for speaker output X.This key is ignored if enable_vol_ctl is set to 0. ICC and Voice AFMs only. The value is clamped between 0 and 100 if out of range.
start_on_boot 0 If 1, start the AFM when io-audio starts, after all cards and AFMs have been successfully loaded; if 0, the AFM is idle after io-audio starts.
master capture Master channel for bridge audio transfer; Bridge AFM only.

The Bridge is an AFM that connects audio between two devices. For example, it captures audio from a microphone input and plays it out to a speaker output. It times itself on the hardware capture and playback interrupts.

The Bridge can use only capture interrupts, playback interrupts, or both for timing. When capture or playback is specified as a value for this key, input is captured and played out when an interrupt occurs on a specified channel. When both is specified, both capture and playback interrupts are used. Audio is input when a capture interrupt occurs and played out when a playback interrupt occurs.

resync_on_xrun 0 Force audio resynchronization when an overrun or an underrun occurs; Bridge AFM only.

When set to 1, audio is restarted when overrun or underrun is detected. When set to 0, no correction will be performed if an overrun or underrun is detected.

artifact_protection 0 Clear the capture buffer before advancing internal references (pointers) to it. Bridge AFM only.

When set to 1, once capture audio is written to the playback buffer, clear and silence the capture buffer. This prevents stale data from being left behind. When set to 0, the capture buffer isn't overwritten with silence.

cardname_override 0 String override for the card name (e.g., icc, voice, bridge) used by the snd_card_name() in utilities such as afm_ctl or mix_ctl to access the AFM.

This key can be used to differentiate between AFMs if there are multiple AFMs of the same type configured. For example, if there are multiple bridges, their names could be overwritten to bridge1, bridge2 and so forth, and accessed with afm_ctl -a bridge1 or afm_ctl -a bridge2.

Overriding the cardname also impacts the name of the resource file used to store the card mixer settings when deva-util-restore.so is being used. By default, the restore files are named Afm cardname @ cardnumberio-ado-cfg. For example, Afm Icc @ 4.io-ado-cfg. If you override the cardname to my_newname, the restore file would be renamed to my_newname @ 4.io-ado-cfg.

pcm_mode_remote_frags 1 Number of remote fragments used for Voice PCM mode, which are used to compensate for variable-interrupt timing. Voice AFM only.

This key/value fair can be used to compensate for variable interrupt timing. For example, if local card interrupts occurs in a cycle of 12ms/18ms/18ms, instead of 16 ms, data may be dropped. Increasing the number of remote fragments to be 2 (or higher) compensates for this inconsistency at a the cost of a higher round trip latency.

defer_mount 0 Defer mounting of the DLL until a later time.

When set to 0, the card is mounted at startup. When set to 1, mounting of the card is deferred until the mount command is issued. The acoustics option can be used with the mount command to mount all AFM cards that were deferred.

[ACS] section(s)

Tip: The [ACS] section is only available for use if you have the QNX Acoustic Management Platform 2.0 and the Audio component BuildID 594—January 17, 2018 (7.0.594.S201801171044) or a later update installed.

The keys in the [ACS] section include the following:

Key Default Description
name None The name of the link. This is a required key.

The deva-acs- prefix and the .so suffix are omitted when specifying the module name. For example, link corrsponds to deva-acs-link.so. The link module is a special type of AFM that integrates the Acoustic Control Server (ACS) for tuning purposes; it performs no acoustic processing.
unit -1 Card number used in the filesystem mount. Card numbers must be unique. If this key isn't provided or if the value is a negative number, the first available, unique number after zero is generated.
enable_acs None (Required) Enable the ACS link.

When set to 1, the Link AFM is available to be started. When set to 0, the link AFM isn't available and can't be started.
server_port 4000 The ACS TCP/IP server port.
ms_frag_period None (Required) Fragment size to use for ACS audio tapping. When the local playback device is a PCM Software Mixer device, this period must be a multiple of the value set for sw_mixer_ms.
tap_split_cap None The name of the splitter PCM device for ACS audio tapping; normally the same as the pcm_local_capture device used by the acoustic AFMs.
tap_media_ref None The name of the media PCM device for ACS audio tapping; normally the same as the pcm_media_capture device used by ICC.
defer_mount 0 Defer mounting of the DLL until a later time.

When set to 0, the card is mounted at startup. When set to 1, mounting of the card is deferred until the mount command is issued. The acoustics option can be used with the mount command to mount all AFM cards that were deferred.

Here's an example of a audio configuration file: 

[global]
verbosity=3
sw_mixer_ms=2

########################################
# Audio Management Output Context
########################################
[audiomgmt]
audiomgmt_id=Zone1
policy_conf=/etc/system/config/audio/audio_policy_zone1.conf

########################################
# On-board audio
########################################
# This card's PCM software mixer and input splitter will be the preferred devices
[ctrl]
name= your_driver_name
options= your_driver_specific_options
input_splitter_enable=1
sw_mixer_ms=16
audiomgmt_id=Zone1

Driver-specific configuration file

Tip: Driver-specific configuration files are available only if you have Audio component BuildID 387—October 2, 2017 (7.0.387.S201710021920) or a later update installed. Prior updates don't support the use of this configuration file.
The driver-specific configuration uses [CTRL] sections as defined in the “Audio configuration file” section. For more information, see the “Description” section above. For example, if you wanted to use the configuration for a mcasp driver (deva-ctrl-mcasp.so), you could dynamically mount driver with the following mount command: 
mount -oconfig=mydriver.conf deva-ctrl-mcasp.so
Here's the example mydriver.conf file that corresponds to the above command: 
[CTRL]
name=mcasp
options=clk_mode=master

Abilities:

The io-audio manager may require the following abilities to run:

Use secpolmonitor to determine which abilities io-audio is using on your specific system.

For more information on abilities, see procmgr_ability() in the C Library Reference.

Examples:

Start io-audio and load the audio configuration from a file: 

io-audio -c /etc/system/config/audio/io-audio.conf

Load the AudioPCI driver, specifying the size of the DMA memory pool as 512 KB: 

io-audio -vv -m pool_size=512 -d audiopci

Lock the sample rate to 8 KHz (if the hardware supports 8 KHz natively): 

io-audio -o sw_mixer_rate=L8000 -d my_audio_driver

Start an audio driver, specifying the card options: 

io-audio -d my_audio_driver \
cap_name=capture,play_name=playback

The /dev/snd directory will look something like this: 

# ls -l /dev/snd
total 0
lrw-rw-rw- 1 root root 0 May 31 11:11 capture -> pcmC0D0c
-rw-rw-rw- 1 root root 0 May 31 11:11 controlC0
-rw-rw-rw- 1 root root 0 May 31 11:11 mixerC0D0
-rw-rw-rw- 1 root root 0 May 31 11:11 pcmC0D0c
-rw-rw-rw- 1 root root 0 May 31 11:11 pcmC0D0p
lrw-rw-rw- 1 root root 0 May 31 11:11 pcmPreferredc -> pcmC0D0c
lrw-rw-rw- 1 root root 0 May 31 11:11 pcmPreferredp -> pcmC0D0p
lrw-rw-rw- 1 root root 0 May 31 11:11 playback -> pcmC0D0p

Files:

In addition to the deva-ctrl-* drivers, the io-audio command can load the following shared objects:

deva-mixer-ac97.so
Mixer DLL for the AC97 codec.
deva-mixer-ak4531.so
Mixer DLL for the AK4531 codec.
deva-mixer-hda.so
Mixer DLL for High Definition Audio codecs.
deva-util-restore.so
Shared object used to restore an audio driver's state.
Related reference
deva-ctrl-audiopci.so
deva-ctrl-intel_hda.so
deva-ctrl-usb.so
deva-mixer-ac97.so
deva-mixer-ak4531.so
deva-mixer-hda.so
deva-util-restore.so
mix_ctl
deva-*
Connecting Hardware
in the QNX Neutrino User's Guide
Parent topic: I