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.
conf=path_to_file

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.

When you use the mount command to dynamically load a driver, you can use the unit number to specify which [CTRL] section in the configuration file to use. For more information on the different scenarios, see the 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.
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 sample rate that the hardware supports and is a multiple of the rate requested by the first active client (all subsequent subchannels are locked to this rate).
  • FA (First Active) — Select the sample rate based on the first active client's requested sample rate; all subsequent subchannels are locked to this 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 service allows you to dynamically load audio drivers when you start io-audio. You use the -d options to specify the drivers to load.

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: Although graphics drivers run at a higher priority than applications, to prevent breaks in the audio, they shouldn't run at a higher priority than the audio driver. The resgmr threads inherit their priority from the client that 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 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.

Unit (card) numbers are 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 that are assigned at io-audio startup via the configuration file are deterministic regardless of further runtime loading/unloading of driver DLLs.

If a device is defined in the audio configuration file, its card number is assigned for the lifetime that io-audio runs. If you unload a card (e.g., umount /dev/snd/controlCx) and its number is reserved for a driver in the configuration file, the card number is not released back to the system. However, if a driver is dynamically loaded at runtime (and does not match a number reserved in the configuration file), unloading the card releases its number.

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 fails. 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 conf=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 -oconf=mydriver.conf deva-ctrl-mcasp.so
#mount -Tio-audio -oconf=mydriver.conf,unit=2 deva-ctrl-mcasp.so
The following driver-specific configuration file (mydriver.conf) has two entries that match the previous mount commands. The first [CTRL] section is used when you don't provide the unit option. If you do provide the option (as in the second example [CTRL] section), 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: 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 example section is invalid:
[CTRL]
name=mcasp
options=unit=2,clk_mode=master
The following section with the explicit unit key is correct:
[CTRL]
name=mcasp
unit=2
options=clk_mode=master
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

Unmounting a module

To unload a module, use a command like this:

umount /dev/snd/controlC0

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.
  • 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.

sw_mixer_ms None. The mixer fragment size, in milliseconds. No default and this key isn't used if a value isn't specified. You can also set this in the [CTRL] section for each card.
Note:

If you have the QNX Acoustic Management Platform 2.0, you must specify this key to playback through a PCM software mixer if you use acoustic AFMs (either here, in the [CTRL] section, or at the command line).

To route data to the PCM software mixer via an acoustic AFM, the mixer must use a data fragment size that can be divided exactly into the AFM’s fragment period. (You can use ms_frag_period to set the AFM's fragment period.)

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_sample_size None Specifies one of the following sample sizes for the PCM software mixer to use:
  • 16 — 16-bit signed, native endian
  • 32 — 32-bit signed, native endian

If you do not use this key, the sample size is determined by the sample size the underlying hardware uses:

  • If the hardware is 8- or 16-bit, the mixer uses 16-bit signed, native endian.
  • For 24- or 32-bit hardware, the mixer uses 32-bit signed, native endian.
To specify the sample size for a specific PCM software mixer, append an underscore and the device name to the key. For example, sw_mixer_sample_size_0.
sw_mixer_rate FAHQ The method for setting the PCM software mixer sample rate. If the underlying hardware supports multiple sample rates, the specified method determines which rate the mixer uses:
  • FAHQ — First active, high quality; the highest quality sample rate that the hardware supports and is a multiple of the rate requested by the first active client (44.1Khz and above).
  • FA — First active; the sample rate requested by the first active client.
  • Lvalue — Lock to the specified rate, where value is in the range 100–200000.
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 snd_pcm_open_preferred() opens when SND_PCM_OPEN_PLAYBACK is specified.

For more information on how io-audio sets the preferred device, see Preferred device selection.

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.

For more information on how io-audio sets the preferred device, see Preferred device selection.

[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
unit -1 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.
input_splitter_ms None

The input splitter fragment size, in milliseconds. No default.

To specify the fragment size for a specific PCM device, add an underscore and the device name to the key. For example, input_splitter_ms_0.

If this key is not specified, the sw_mixer_ms value from the current [CTRL] section determines the size. If the current [CTRL] section has no sw_mixer_ms key, sw_mixer_ms from the [GLOBAL] section or the command line for this card determines the size.

You must specify either this parameter or sw_mixer_ms (at the command-line, or in the [GLOBAL] or [CTRL] sections) if any AFMs are configured to capture through the PCM input splitter on this card.

To route data between the PCM input splitter and the PCM software mixer via an AFM, both the splitter and mixer must use a data fragment size that can be divided exactly into the AFM’s fragment period. (You can use ms_frag_period to set the AFM's fragment period.)

For example, to configure a Bridge AFM to operate with 8 millisecond fragments, specify ms_frag_period=8. To configure a QNX Acoustics for Voice AFM to use smaller but compatible mixer and splitter fragment sizes, specify sw_mixer_ms=1 and input_splitter_ms=2.

For more information, see ms_frag_period in the [AFM] section.

input_splitter_rate FAHQ

The method for setting the PCM input splitter sample rate.

To specify the method for a specific PCM device, add an underscore and the device name to the key. For example, input_splitter_rate_0.

If the underlying hardware supports multiple sample rates, the specified method determines which sample rate applies to the splitter:

  • FAHQ — First active, high quality; the highest quality sample rate that the hardware supports and is a multiple of the rate requested by the first active client (44.1Khz and above).
  • FA — First active; the sample rate requested by the first active client.
  • Lvalue — A specified, locked rate, where value is in the range 100–200000.
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 key isn't used if a value isn't specified.

To specify the fragment size for a specific PCM device, add an underscore and the device name to the key. For example, sw_mixer_ms_0.

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.
  • To route data to the PCM software mixer via an acoustic AFM, the mixer must use a data fragment size that can be divided exactly into the AFM’s fragment period. (You can use ms_frag_period to set the AFM's fragment period.)
  • 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; the highest quality sample rate that the hardware supports and is a multiple of the rate requested by the first active client (44.1Khz and above).
  • FA — First active; the sample rate requested by the first active client.
  • Lvalue — Lock to the specified rate, where value is in the range 100–200000.

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

sw_mixer_sample_size None Specifies one of the following sample sizes for the PCM software mixer to use:
  • 16 — 16-bit signed, native endian
  • 32 — 32-bit signed, native endian

If you do not use this key, the sample size is determined by the sample size the underlying hardware uses.

  • If the hardware is 8- or 16-bit, the mixer uses signed, native endian
  • For 24- or 32-bit hardware, the mixer uses 32-bit signed, native endian

To specify the sample size for a specific PCM software mixer, append an underscore and the device name to the key. For example, sw_mixer_sample_size_0.

This parameter overrides the corresponding key 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 QNX Acoustics Management Platform 2.0, 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.

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.
Note: You can use this key if you have QNX Acoustic Management Platform 2.0.
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.
Note: You can use this key if you have QNX Acoustic Management Platform 2.0.
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.

Note: You can use this key if you have QNX Acoustic Management Platform 2.0.
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 all devices. An optional _index suffix can be appended to the key to target the option at a specific PCM device.

Note: You can use this key if you have QNX Acoustic Management Platform 2.0.
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.
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.

[AUDIOMGMT] sections includes the following:
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)

Note: The [AFM] section is only available if you have installed QNX Acoustic Management Platform 2.0.
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. Currently, the available acoustic AFMs are QAV (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 (e.g., 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 acoustic tuning file when in the default audio mode. QNX recommends that you store tuning files in the directory /etc/acoustic (for example, ap_qcf_default=/etc/acoustic/handsfree.qcf).

The default audio mode is used when a mode is not set using the libasound library snd_afm_set_audio_mode() function.

ap_qcf_mode None The path to the acoustic tuning file to use when in the specified mode.

mode is a string set using the libasound library snd_afm_set_audio_mode() function. It specifies an audio mode that corresponds to a particular audio environment. For example, for Bluetooth hands-free phone calls that operate at 8kHZ (narrowband) and 16 KHz (wideband), you can create the corresponding modes "nb" and "wb". To apply sample rates other than the default to these modes, create keys ap_qcf_wb and ap_qcf_nb.

ap_gran_syn_dir_default None The path to the acoustic granular synthesis files to use when in the default mode. ASD AFM only.

The default audio mode is used when a mode is not set using the libasound library snd_afm_set_audio_mode() function.

ap_gran_syn_dir_mode None The path to the acoustic granular synthesis files to use when in the specified mode. ASD AFM only.

mode is a string set using the libasound library snd_afm_set_audio_mode() function. It specifies an audio mode that corresponds to a particular audio environment.

ap_calib_default None The path to the acoustic calibration file to use when in the default mode. ASD AFM only.

The default audio mode is used when a mode is not set using the libasound library snd_afm_set_audio_mode() function.

ap_calib_mode None The path to the acoustic calibration file to use when in the specified mode. ASD AFM only.

mode is a string set using the libasound library snd_afm_set_audio_mode() function. It specifies an audio mode that corresponds to a particular audio environment.

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 software mixer.
  • When the value is afm, playback audio is routed through the AFM mixer path in the PCM software mixer.
  • When the value is main, playback audio is routed through the main (media) path in the PCM software mixer.
Normally, you do not specify this value and it defaults to afm. You typically use main with the Bridge AFM, which does not perform acoustic processing, and the output is expected to be included in the main (media) reference.

This setting changes the effect that audio ducking can have on the Bridge AFM playback audio. See Understanding audio ducking in the “Audio Management” chapter in the QNX Neutrino Audio Developer's Guide.

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.

local_rate_default 0 Sample rate to use when you open pcm_local_capture and pcm_local_playback when in the default audio mode. If you do not specify this key, the highest sample rate that the underlying hardware supports is used.

The default audio mode is used when a mode is not set using the libasound library snd_afm_set_audio_mode() function.

Applies to acoustic AFMs only.

  • 0 — Open the devices at the highest supported sample rate.
  • Non-zeroOpen the devices at the specified rate.
local_rate_mode 0 Sample rate to use when you open pcm_local_capture and pcm_local_playback devices when in the specified audio mode. If you do not specify this key, the highest sample rate that the underlying hardware supports is used.

mode is a string set using the libasound library snd_afm_set_audio_mode() function. It specifies an audio mode that corresponds to a particular audio environment. For example, for Bluetooth hands-free phone calls that operate at 8kHZ (narrowband) and 16 KHz (wideband), you can create the corresponding modes "nb" and "wb". To apply sample rates other than the default to these modes, create keys local_rate_wb and local_rate_nb.

Applies to acoustic AFMs only.
  • 0 — Open the devices at the highest supported sample rate.
  • Non-zeroOpen the devices at the specified rate.
remote_rate_default 0 Sample rate to use when you open pcm_remote_capture and pcm_remote_playback when in the default audio mode. If you do not specify this key, the highest sample rate that the underlying hardware supports is used.

The default audio mode is used when a mode is not set using the libasound library snd_afm_set_audio_mode() function.

Applies to the QAV AFM only.

  • 0 — Open the devices at the highest supported sample rate.
  • Non-zeroOpen the devices at the specified rate.
remote_rate_mode 0 Sample rate to use when you open pcm_remote_capture and pcm_remote_playback devices when in the specified audio mode.

mode is a string set using the libasound library snd_afm_set_audio_mode() function. It specifies an audio mode that corresponds to a particular audio environment. For example, for Bluetooth hands-free phone calls that operate at 8kHZ (narrowband) and 16 KHz (wideband), you can create the corresponding modes "nb" and "wb". To apply sample rates other than the default to these modes, create keys remote_rate_wb and remote_rate_nb.

Applies to the QAV AFM only.

  • 0 — Open the devices at the highest supported sample rate.
  • Non-zeroOpen the devices at the specified rate.

[ACS] section(s)

Note: The [ACS] section is only available if you have installed QNX Acoustic Management Platform 2.0.
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

Preferred device selection

When you use snd_pcm_open_preferred() to open an audio interface, the function attempts to open the device configured as the preferred device.

The io-audio service searches for the preferred device to use in the following system resources and order:

  1. The /etc/system/config/audio/preferences file. This file uses the following format, with a tab character between the fields:
    pcmPreferredp    card_name    device_number
    pcmPreferredc    card_name    device_number
      

    The io-audio service compares available card names to the preferred card name in the following order and selects the first card name that matches:

    1. the card long name, as an exact match
    2. the card short name, as an exact match
    3. a substring that matches the start of the card name

    (The card name is set by the driver code and can be queried via card_get_longname(), card_get_name(), and so on.)

  2. In the [GLOBAL] section of the audio configuration file, the device specified by pcmPreferredp, pcmPreferredc, or both.
  3. The first valid playback or capture device. (The order of devices is based on the deva-* load order.)

Whenever a new device is mounted or unmounted, io-audio repeats the search and updates the preferred device if it finds a better match.

Driver-specific 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 -oconf=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.