Latest revision as of 08:09, 8 January 2019

Detailed changelog between 1.1.6 and 1.1.8 releases

Changelog between 1.1.7 and 1.1.8 releases

alsa-oss

Core

- Release v1.1.8

- fix FTBFS with glibc v3.28

In glibc upstream, libio/libio.h had been deprecated for applications and

became internal header in its v2.28 release. We can see below message in

its release note[1].

* The nonstandard header files <libio.h> and <_G_config.h> are no longer

installed. Software that was using either header should be updated to

use standard <stdio.h> interfaces instead.

This brings FTBFS with glibc v2.28 due to missing <libio.h>. This commit

fixes it.

[1] https://www.sourceware.org/ml/libc-alpha/2018-08/msg00003.html

Reported-by: Adrian Bunk <bunk@debian.org>

Reference: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=916052

Detailed changelog between 1.1.7 and 1.1.8 releases

Changelog between 1.1.7 and 1.1.8 releases

alsa-lib

Core

- Release v1.1.8

- conf: rename snd_conf_load1() to _snd_config_load_with_include()

Always free the include path which must be mallocated by the caller.

- conf/ucm: bytcht-es8316: Add long-name UCM profiles

After recent kernel work, the kernel now sets a long-name for bytcht-es8316

boards which indicates if a single (mono) speaker or stereo speakers are

used and if in1 or in2 is used for the internal mic (the headset mic will

be on the other input).

This commit adds UCM profiles for bytcht-es8316 boards using these new

long-names, based on the generic bytcht-es8316 profile.

- conf/ucm: Add UCM profile for bytcht-es8316 boards

Add an UCM profile for Bay Trail and Cherry Trail boards with an

ES8316 codec.

Re-use the existing platform enable and disable sequences for BYT/CHT SST

support and add a codecs/es8316 dir with codec specific enable / disable

sequences for the various inputs and outputs.

- Create shared {En,Dis}ableSeq.conf components for rt5645 variants

Factor out the common enable and disable sequences used

in rt5645 variants, including the rt5650. Move the sequences

into a new component directory codecs/rt5645/ along with

a Makefile.

Some lines like

cset "name='Stereo1 ADC1 Mux' 1"

and

cset "name='I2S2 Func Switch' on"

are not set set in the chtrt5650 UCM sequences and thus are not present

in the new component, in order to maximize reuse.

- conf/ucm: bytcr-rt5651: Add bytcr-rt5651-stereo-spk-dmic-mic config

Add a config for boards which use a digital mic as internal mic,

combined with having the headset mic on in2.

An example of such a board is the Point of View TAB-P1006W-232 (v1.0) tablet.

- conf/ucm: kblrt5660: Add ucm setting for Dell Edge IoT platform

The new generation of Dell Edge IoT platform is based on Intel

Kabylake platform, and the audio codec is ALC3277 which is 100%

compatible with RT5660 in I2S mode.

The audio design on this IoT platform is as below:

- Intel kabylake platform

- connect the codec ALC3277 via SSP0

- line-out and line-in with Micbias jacks

- line-out mute control and jack detection of line-out and line-in

- two HDMI ports with audio capability

- conf/ucm: chtrt5650: Add UCM config for chtrt5650

Add a UCM configuration for the rt5650 codec. Tested on

a Samsung Chromebook 3. Adapted with minor modifications

from GitHub user evan-a-a's gist:

https://gist.github.com/evan-a-a/86b2a698708074530e2d0ee7c6498767

- ucm: Set default include path

Many UCM profiles include the UCM profile components under ucm/*

subdirectories and thusly put <searchdir:ucm> at each place. This is

rather cumbersome.

This patch makes the UCM parser to set the default include path, so

that each profile no longer needs to set searchdir. All the

<searchdir:ucm> lines currently found in the profiles are removed

gracefully, too.

For the needed implementation, a new helper,

_snd_config_load_with_include() is introduced. It's not exported,

only for the use inside alsa-lib.

- conf: Move UCM profile snippets into components subdirectory

We have placed UCM profile snippets to be included by the main config

files also in the same directory, src/conf/ucm, it confuses alsaucm

program that scans over all subdirectories. It thinks such a file is

also the main config file, and spews errors like:

% alsaucm

ALSA lib utils.c:67:(uc_mgr_config_load) could not open configuration file /usr/share/alsa/ucm/bytcr/bytcr.conf

ALSA lib parser.c:1427:(load_master_config) error: could not parse configuration for card bytcr

alsaucm: unable to obtain card list: No such file or directory

Actually we already defined the subdirectory for such components, and

they are skipped at parsing the main configs. So we just need to move

the files there -- this is what's done here.

One more thing done here is to add a new component subdirectory,

platforms, for definitions bytcr/* that don't match with neither the

existing ones (codecs nor dsps).

Suggested-by: Hans de Goede <hdegoede@redhat.com>

Reviewed-by: Hans de Goede <hdegoede@redhat.com>

Tested-by: Hans de Goede <hdegoede@redhat.com>

- initial version of .travis.yml file

Control API

- control: fix the assert() in snd_ctl_elem_set_bytes

Allow to write to the whole array (512 bytes).

PCM API

- pcm: ioplug: Fix the regression of pulse plugin drain

The recent change to support the drain via polling caused a regression

for pulse plugin; with speaker-test -c2 -twav with pulse, it leads to

either no sounds or stall.

The only sensible behavior change in the commit wrt pulse plugin is

that now it starts the stream before calling drain callback. This

supposed to be correct, but it seems hitting a pulse plugin bug.

The start before drain callback is only a matter of consistency, and

since this doesn't work for the single existing plugin using drain

callback, we don't need to stick with this behavior.

For addressing the regression, we check the presence of the drain

callback and start the stream only when it doesn't exist, i.e. only in

drain-via-poll mode.

Fixes: ce2095c41f28 ("pcm: ioplug: Implement proper drain behavior")

Reported-by: Diego Viola <diego.viola@gmail.com>

- pcm: extplug: Keep format and channels the same if requested

Without this patch it is not possible to link the channel and format

parameter if snd_pcm_extplug_set_param_*() or

snd_pcm_extplug_set_slave_param_*() is called. Therefore the client and

slave parameter can differ. So the extplug has to implement conversion.

To avoid this the new snd_pcm_extplug_set_param_link() function can be

called.

As a reproduction sceanrio the following extplug source code can be used:

===

static snd_pcm_sframes_t my_transfer(snd_pcm_extplug_t *e,

const snd_pcm_channel_area_t *da, snd_pcm_uframes_t dof,

const snd_pcm_channel_area_t *sa, snd_pcm_uframes_t sof,

snd_pcm_uframes_t s) {

return s;

}

static const snd_pcm_extplug_callback_t my_own_callback = {

.transfer = my_transfer

};

SND_PCM_PLUGIN_DEFINE_FUNC(my_plug) {

snd_config_iterator_t i, next;

snd_config_t *slave = NULL;

snd_pcm_extplug_t *myplug;

snd_config_for_each(i, next, conf) {

snd_config_t *n = snd_config_iterator_entry(i);

const char *id;

if (snd_config_get_id(n, &id) < 0)

continue;

if (strcmp(id, "comment") == 0 || strcmp(id, "type") == 0)

continue;

if (strcmp(id, "slave") == 0) {

slave = n;

continue;

}

return -EINVAL;

}

myplug = calloc(1, sizeof(*myplug));

myplug->version = SND_PCM_EXTPLUG_VERSION;

myplug->callback = &my_own_callback;

snd_pcm_extplug_create(myplug, name, root, slave, stream, mode);

snd_pcm_extplug_set_param_minmax(myplug,

SND_PCM_EXTPLUG_HW_CHANNELS, 1, 16);

// snd_pcm_extplug_set_param_link(myplug, SND_PCM_EXTPLUG_HW_CHANNELS, 1);

*pcmp = myplug->pcm;

return 0;

}

SND_PCM_PLUGIN_SYMBOL(my_plug);

===

To use this plugin the following ALSA configuration is required:

pcm.myplug {

type my_plug

slave.pcm hw:Dummy

}

With this configuration without this patch

snd_pcm_hw_params_get_channels_max() will always return 16 channels

independent of the supported channels of the dummy device. Due to that for

example the start up of JACK would fail:

$ modprobe snd_dummy

$ jackd -d alsa -P myplug

ALSA: cannot set channel count to 16 for playback

ALSA: cannot configure playback channel

- pcm: dshare: Fix segfault when not binding channel 0

Configuration to reproduce:

~~~~

pcm.share_right {

type dshare

ipc_key 73

ipc_perm 0666

slave {

pcm "hw:0,0"

}

bindings {

# the seagfault happens when we don't bind channel 0

1 1

}

~~~~

Execute to reproduce:

~~~~

$ aplay -D plug:share_right test.wav

Playing WAVE 'test.wav' : Signed 16 bit Little Endian, Rate 44100 Hz, Stereo

Segmentation fault

~~~~

For channels whithout binding, values are set to UINT_MAX in function

`snd_pcm_direct_parse_bindings()`:

~~~~

for (chn = 0; chn < count; chn++)

bindings[chn] = UINT_MAX; /* don't route */

~~~~

But, these values are not checked when playing, which causes the segfault.

This commit fixes the issue.

- pcm: dmix: Add option to allow alignment of slave pointers

These changes are required due to the kernel

commit 07b7acb51d283d8469696c906b91f1882696a4d4

("ASoC: rsnd: update pointer more accurate")

Issue is that snd_pcm_wait() goes back to waiting because the hw_ptr

is not period aligned. Therefore snd_pcm_wait() will block for a longer

time as required.

With these rcar driver changes the exact position of the dma is returned.

During snd_pcm_start they read hw_ptr as reference, and this hw_ptr

is now not period aligned, and is a little ahead over the period while it

is read. Therefore when the avail is calculated during snd_pcm_wait(),

it is missing the avail_min by a few frames.

An additional option hw_ptr_alignment is provided to dmix configuration,

to allow the user to configure the slave application and hw pointer

alignment at startup

[ Slight indentation and parentheses removals by tiwai ]

- pcm: interval: Interpret (x x+1] correctly and return x+1

Without this change an interval of (x x+1] will be interpreted as an

empty interval but the right value would be x+1.

This leads to a failing snd_pcm_hw_params() call which returns -EINVAL.

An example issue log is given in the following:

snd_pcm_hw_params failed with err -22 (Invalid argument)

ACCESS: MMAP_NONINTERLEAVED

FORMAT: S16_LE

SUBFORMAT: STD

SAMPLE_BITS: 16

FRAME_BITS: 16

CHANNELS: 1

RATE: 16000

PERIOD_TIME: (15999 16000]

PERIOD_SIZE: (255 256]

PERIOD_BYTES: (510 512]

PERIODS: [2 3)

BUFFER_TIME: 32000

BUFFER_SIZE: 512

BUFFER_BYTES: 1024

In case of (x x+1) we have to interpret it anyway as a single value of x to

compensate rounding issues.

For example the period size will result in an interval of (352 353) when

the period time is 16ms and the sample rate 22050 Hz

(16ms * 22,05 kHz = 352,8 frames). But 352 has to be chosen to allow a

buffer size of 705 (32ms * 22,05 kHz = 705,6 frames) which has to be >= 2x

period size to avoid Xruns. The buffer size will not end up with an

interval of (705 706) simular to the period size because

snd_pcm_rate_hw_refine_cchange() calls snd_interval_floor() for the buffer

size. Therefore this value will be interpreted as an integer interval

instead of a real interval further on.

This issue seems to exist since the change of 9bb985c38 ("pcm:

snd_interval_refine_first/last: exclude value only if also excluded

before")

Use Case Manager API

- conf: rename snd_conf_load1() to _snd_config_load_with_include()

Always free the include path which must be mallocated by the caller.

- ucm: Set default include path

Many UCM profiles include the UCM profile components under ucm/*

subdirectories and thusly put <searchdir:ucm> at each place. This is

rather cumbersome.

This patch makes the UCM parser to set the default include path, so

that each profile no longer needs to set searchdir. All the

<searchdir:ucm> lines currently found in the profiles are removed

gracefully, too.

For the needed implementation, a new helper,

_snd_config_load_with_include() is introduced. It's not exported,

only for the use inside alsa-lib.

- conf: Move UCM profile snippets into components subdirectory

We have placed UCM profile snippets to be included by the main config

files also in the same directory, src/conf/ucm, it confuses alsaucm

program that scans over all subdirectories. It thinks such a file is

also the main config file, and spews errors like:

% alsaucm

ALSA lib utils.c:67:(uc_mgr_config_load) could not open configuration file /usr/share/alsa/ucm/bytcr/bytcr.conf

ALSA lib parser.c:1427:(load_master_config) error: could not parse configuration for card bytcr

alsaucm: unable to obtain card list: No such file or directory

Actually we already defined the subdirectory for such components, and

they are skipped at parsing the main configs. So we just need to move

the files there -- this is what's done here.

One more thing done here is to add a new component subdirectory,

platforms, for definitions bytcr/* that don't match with neither the

existing ones (codecs nor dsps).

Suggested-by: Hans de Goede <hdegoede@redhat.com>

Reviewed-by: Hans de Goede <hdegoede@redhat.com>

Tested-by: Hans de Goede <hdegoede@redhat.com>

Configuration

- conf: rename snd_conf_load1() to _snd_config_load_with_include()

Always free the include path which must be mallocated by the caller.

- conf/ucm: bytcht-es8316: Add long-name UCM profiles

After recent kernel work, the kernel now sets a long-name for bytcht-es8316

boards which indicates if a single (mono) speaker or stereo speakers are

used and if in1 or in2 is used for the internal mic (the headset mic will

be on the other input).

This commit adds UCM profiles for bytcht-es8316 boards using these new

long-names, based on the generic bytcht-es8316 profile.

- conf/ucm: Add UCM profile for bytcht-es8316 boards

Add an UCM profile for Bay Trail and Cherry Trail boards with an

ES8316 codec.

Re-use the existing platform enable and disable sequences for BYT/CHT SST

support and add a codecs/es8316 dir with codec specific enable / disable

sequences for the various inputs and outputs.

- Create device component for rt5645 Internal Analog Mic UCM

Since the Internal Analog Microphone device configuration is

identical for the rt5645 and rt5645 mono speaker UCMs, move

the entire definition to a component.

- Factor out rt5645 variants Headset+Digital Mic UCM shared {en,dis}able sequences

- Factor out rt5645 variants Speaker+Headphones shared UCM enable sequences

Move common enable sequences for rt5645 variants and rt5650

UCM configurations into a shared component. The corresponding

disable sequences are only two lines each and do not seem worth

creating components for.

- Create shared {En,Dis}ableSeq.conf components for rt5645 variants

Factor out the common enable and disable sequences used

in rt5645 variants, including the rt5650. Move the sequences

into a new component directory codecs/rt5645/ along with

a Makefile.

Some lines like

cset "name='Stereo1 ADC1 Mux' 1"

and

cset "name='I2S2 Func Switch' on"

are not set set in the chtrt5650 UCM sequences and thus are not present

in the new component, in order to maximize reuse.

- Update chtrt5645 ucm variants to use bytcr/PlatformEnableSeq.conf component

The Lenovo Ideapad Miix 320, Asus T100HA, and chtrt5645 mono variant

UCM configurations have not been updated to make use of the shared

bytcr/PlatfromEnableSeq.conf sequence. This commit deletes those

command sequences and loads the shared component directly.

- conf/ucm: bytcr-rt5651: Document mono speaker wiring

During my recent work on the bytcht-es8316 UCM profile I realized that the

bytcr-rt5651 devices with a single speaker use a differential setup just

like the es8316 does. The tell-tale here is the speaker going quiet when

playing the exact same sound on both channels when things are configured

for stereo speakers.

I've run some tests and the rt5651 does have a special mono balanced out

mode for its line-out but using this results in the same sound (and the

same loudness / volume of the sound) as our current solution, so adding

support for this to the kernel buys us nothing.

This commit makes no changes, it just documents my findings in a big

comment for future reference.

- conf/ucm: bytcr-rt5651: Add bytcr-rt5651-stereo-spk-dmic-mic config

Add a config for boards which use a digital mic as internal mic,

combined with having the headset mic on in2.

An example of such a board is the Point of View TAB-P1006W-232 (v1.0) tablet.

- conf/ucm: bytcr-rt5651: Add digital mic support

Add a new ucm/codecs/rt5651/DigitalMic.conf snippet for digital mic support

and include this in the default non board-specific bytcr-rt5651.conf.

- conf/ucm: bytcr-rt5651: Add support for a headset-mic on IN2

The first design with the headset-mic on IN2 rather then the

default / reference-design IN3 has shown up.

Add a new ucm/codecs/rt5651/IN2-HeadsetMic.conf snippet to deal with this

and include this in the default non board-specific bytcr-rt5651.conf.

- conf/ucm: bytcr-rt5651: Enable Stereo? ADC MIXL ADC? switches when enabling inputs

Explicitly enable the right 'Stereo? ADC MIXL ADC?' when selecting an input,

rather then just enabling them all in ucm/codecs/rt5651/EnableSeq.conf .

This is a preparation patch for adding digital mic support.

- conf/ucm: kblrt5660: Add ucm setting for Dell Edge IoT platform

The new generation of Dell Edge IoT platform is based on Intel

Kabylake platform, and the audio codec is ALC3277 which is 100%

compatible with RT5660 in I2S mode.

The audio design on this IoT platform is as below:

- Intel kabylake platform

- connect the codec ALC3277 via SSP0

- line-out and line-in with Micbias jacks

- line-out mute control and jack detection of line-out and line-in

- two HDMI ports with audio capability

- conf/ucm: chtrt5650: Add UCM config for chtrt5650

Add a UCM configuration for the rt5650 codec. Tested on

a Samsung Chromebook 3. Adapted with minor modifications

from GitHub user evan-a-a's gist:

https://gist.github.com/evan-a-a/86b2a698708074530e2d0ee7c6498767

- ucm: Set default include path

Many UCM profiles include the UCM profile components under ucm/*

subdirectories and thusly put <searchdir:ucm> at each place. This is

rather cumbersome.

This patch makes the UCM parser to set the default include path, so

that each profile no longer needs to set searchdir. All the

<searchdir:ucm> lines currently found in the profiles are removed

gracefully, too.

For the needed implementation, a new helper,

_snd_config_load_with_include() is introduced. It's not exported,

only for the use inside alsa-lib.

- conf: Move UCM profile snippets into components subdirectory

We have placed UCM profile snippets to be included by the main config

files also in the same directory, src/conf/ucm, it confuses alsaucm

program that scans over all subdirectories. It thinks such a file is

also the main config file, and spews errors like:

% alsaucm

ALSA lib utils.c:67:(uc_mgr_config_load) could not open configuration file /usr/share/alsa/ucm/bytcr/bytcr.conf

ALSA lib parser.c:1427:(load_master_config) error: could not parse configuration for card bytcr

alsaucm: unable to obtain card list: No such file or directory

Actually we already defined the subdirectory for such components, and

they are skipped at parsing the main configs. So we just need to move

the files there -- this is what's done here.

One more thing done here is to add a new component subdirectory,

platforms, for definitions bytcr/* that don't match with neither the

existing ones (codecs nor dsps).

Suggested-by: Hans de Goede <hdegoede@redhat.com>

Reviewed-by: Hans de Goede <hdegoede@redhat.com>

Tested-by: Hans de Goede <hdegoede@redhat.com>

- conf: USB-Audio: Add Dell WD19 Dock in the IEC958 blacklist

This Dock doesn't have IEC958 physical output, so add it to the

blacklist to prevent it being opened.

[ Also adding WD15 Dock entry that has the same problem -- tiwai ]

- conf/ucm/Dell-WD15-Dock: Fix incorrect device names

The device name string for Dell WD15 (and its variants) dock is set as

"WD15Dock", while the actual device name to be used is "Dock".

Bugzilla: https://bugzilla.suse.com/show_bug.cgi?id=1112292

Fixes: 8ebb40c96970 ("conf/ucm: Add a UCM profile for Dell WD15 Dock USB-audio")

Documentation

- README.md: add link to www.alsa-project.org

- initial version of README.md for github

External PCM Filter Plugin SDK

- pcm: extplug: Keep format and channels the same if requested

Without this patch it is not possible to link the channel and format

parameter if snd_pcm_extplug_set_param_*() or

snd_pcm_extplug_set_slave_param_*() is called. Therefore the client and

slave parameter can differ. So the extplug has to implement conversion.

To avoid this the new snd_pcm_extplug_set_param_link() function can be

called.

As a reproduction sceanrio the following extplug source code can be used:

===

static snd_pcm_sframes_t my_transfer(snd_pcm_extplug_t *e,

const snd_pcm_channel_area_t *da, snd_pcm_uframes_t dof,

const snd_pcm_channel_area_t *sa, snd_pcm_uframes_t sof,

snd_pcm_uframes_t s) {

return s;

}

static const snd_pcm_extplug_callback_t my_own_callback = {

.transfer = my_transfer

};

SND_PCM_PLUGIN_DEFINE_FUNC(my_plug) {

snd_config_iterator_t i, next;

snd_config_t *slave = NULL;

snd_pcm_extplug_t *myplug;

snd_config_for_each(i, next, conf) {

snd_config_t *n = snd_config_iterator_entry(i);

const char *id;

if (snd_config_get_id(n, &id) < 0)

continue;

if (strcmp(id, "comment") == 0 || strcmp(id, "type") == 0)

continue;

if (strcmp(id, "slave") == 0) {

slave = n;

continue;

}

return -EINVAL;

}

myplug = calloc(1, sizeof(*myplug));

myplug->version = SND_PCM_EXTPLUG_VERSION;

myplug->callback = &my_own_callback;

snd_pcm_extplug_create(myplug, name, root, slave, stream, mode);

snd_pcm_extplug_set_param_minmax(myplug,

SND_PCM_EXTPLUG_HW_CHANNELS, 1, 16);

// snd_pcm_extplug_set_param_link(myplug, SND_PCM_EXTPLUG_HW_CHANNELS, 1);

*pcmp = myplug->pcm;

return 0;

}

SND_PCM_PLUGIN_SYMBOL(my_plug);

===

To use this plugin the following ALSA configuration is required:

pcm.myplug {

type my_plug

slave.pcm hw:Dummy

}

With this configuration without this patch

snd_pcm_hw_params_get_channels_max() will always return 16 channels

independent of the supported channels of the dummy device. Due to that for

example the start up of JACK would fail:

$ modprobe snd_dummy

$ jackd -d alsa -P myplug

ALSA: cannot set channel count to 16 for playback

ALSA: cannot configure playback channel

Test/Example code

- test/audio_time: remove unused variables

- test: rename code to more approriate mixtest

- test/code: make it work again

- test/latecy: fix typo in tstamp compare

Utils

- utils/alsa.m4: conditionally enable libdl in AM_PATH_ALSA m4 macro

The AM_PATH_ALSA macro in utils/alsa.m4 unconditionally uses

-ldl. This breaks compilation of alsa-utils (and probably other

packages using this macro) for targets that do not support dynamic

loading.

This patch updates the macro to check if dlopen is available, and use

that result to conditionally add -ldl to the list of libraries.

alsa-utils

Core

- Release v1.1.8

- Makefile.am: add README.md to EXTRA_DIST

- axfer: add support for libffado transmission backend

At present, axfer is designed to use several types of backend for

transmission of data frames. This commit is an implementation

example of the backend.

Libffado is a userspace library for transmission of data frames according

to protocols similar to IEC 61883-1/6. This library handles audio and

music units on IEEE 1394 bus.

Unfortunately, this library executes ctor/dtor of instances for some

objects in startup/finish routines of C runtime. As a result, it outputs

some superfluous messages even if the backend is not actually used.

Furthermore, this library brings memory leak internally. Therefore,

it's not practical to build this backend for generic purposes. Although

the backend implementation works fine, this commit is just for technical

preview.

- axfer: add unit test for container interface

In former commits, container module gets supports of parser/builder for

several types of file format. This commit adds a unit test for them.

This includes positive test cases only. The test cases actually generate

I/O to file systems for many test cases. It takes a long time to finish.

- axfer: add an entry point for this command

This commit adds a new command, 'axfer' ('ALSA transfer'), to transfer data

frames described in asound.h. This command is intended to replace current

aplay. The most of features and command line parameters come from aplay as

much as possible, while it has more better feature and code to maintain.

This commit adds an entry point for this command. Current option system of

aplay is still available, while this command has a sub-command system like

commands in iproute2.

Currently, two sub-commands are supported; 'list' and 'transfer'. The

'list' sub-command has the same effect as '-l' and '-L' options of aplay.

The 'transfer' sub-command has the same effect as the main feature of

aplay. For the sub-command system, an option for stream direction is

required; '-P' for playback and '-C' for capture. If you create symbolic

links to this binary for aplay/arecord, please execute:

$ ln -s axfer aplay

$ ln -s axfer arecord

Actual code for each sub-command will be implemented in later commits.

- initial version of .travis.yml

- rename and update README.md

Audio Transfer utility

- axfer: add an explanation about advantages/issues of Timer-based scheduling model

Timer-based scheduling model has some merits against IRQ-based

scheduling model. However, as of Linux kernel v4.21, ALSA PCM interface

between kernel/userspace has a lack of some features.

This commit adds a subsection to describe it.

- axfer: add an explanation about Timer-based scheduling model

This commit fulfills a subsection titled as 'Timer-based scheduling model'.

This scheduling model is introduced in a recent decade. In this model,

applications should take care of its timing to operate sampled data

according to any timer. This is an optional behaviour of runtime of

PCM substream.

- axfer: add an explanation about IRQ-based scheduling model

This commit adds a section titled as 'SCHEDULING MODEL' and fulfill a

subsection titled as 'IRQ-based scheduling model'.

This scheduling model is for a typical applications to operate a kind of

data sampled against actual time. In this model, ALSA PCM core maintains

timing of the applications with notification of hardware by

blocking/waking up their processes. This is a default behaviour of

runtime of PCM substream.

- axfer: add text for compatibility loss of sw parameter in libasound backend

At present, some options for software parameters have actual effects in

cases neither mmap operation nor timer-based scheduling model is used.

For mmap operation, backward compatibility to aplay(1) is lost.

This commit adds descriptions about it.

- axfer: fulfill manual section for libasound backend

This commit attempts to describe purpose of each option with more texts

than aplay(1).

I note that a section for scheduling model will be prepared near future.

This commit just adds a placeholder for the section.

- axfer: print help for libasound backend

This commit attempts to categorise existing options to four parts;

basics, software features, libasound plugin options and debug assistant.

These categories will assist users to get purpose of each option.

- axfer: fulfill manual section for libffado backend

I note that libffado backend has no support for suspend/resume because

libffado has enough implementation for these features even if it exports

some symbols for them. For this backend, reception of signals for the

features brings abortion of runtime.

- axfer: print help for libffado backend

This commit adds help texts for libffado backend.

- axfer: correct description about signal handling

Some items in a section for POSIX SIGNALS includes wrong texts.

- axfer: fix typo in axfer(1) manual

A line has meaningless 'H' letter in its end.

Fixes: c5b2beebfdc2 ('axfer: add a manual for entry point')

- axfer: fix no return statement in print_help() function

A function, print_help() in xfer module is defined to return integer

value, however this is useledd.

This commit fixes it.

Fixes: 908ff69be246 ('axfer: print help text of transfer subcommand just for common options')

- axfer: enable each backend to print own help

This commit adds an operation for xfer backend to print help text.

In this time, content of the help is not implemented yet.

- axfer: print help text of transfer subcommand just for common options

This commit adds help text of transfer subcommand.

In this time, backend options are not described. They will be added in

future commits.

- axfer: print help text of list subcommand

This commit adds help text of list subcommand.

This help text can not be in execution of alias (aplay/arecord) due to

program design.

- axfer: print help text of command entry

This commit adds help text of command entry. This is printed when

help subcommand is given, or a valid subcommand or a valid direction

are not given.

Unfortunately, at present, execution of alias (aplay/arecord) with help

options prints the added help text. It should print help options in

transfer subcommand. This bug will fixed in future commits.

- axfer: add a section about design of transfer subcommand

An implementation of transfer subcommand is the most large part and

complicated somehow. This commit adds a section titled 'DESIGN' to

manual to overall design of the subcommand.

- axfer: add a section to describe compatibility to aplay(1)

The axfer(1) is designed to keep backward compatibility to aplay(1)

as much as possible, however some changes are added to its behaviour.

This commit adds a section titles 'COMPATIBILITY TO APLAY' to each

manuals.

- axfer: add a manual for transfer subcommand

This commit adds a manual for transfer subcommand in axfer(1). This

subcommand is a main feature of this command, to transfer audio data

frame between device/node and file/stdio.

This subcommand is designed to have several transmission backend.

Detail explanation about these backends is added in future commits.

- axfer: add a manual for list subcommand

This commit adds a manual for list subcommand of axfer(1). At present,

this subcommand prints helpful information to transfer subcommand in

libasound backend.

- axfer: add a manual for entry point

This commit adds a manual for axfer(1). This command is an entry point

to supported subcommand.

I note that axfer(1) has renewed option system against aplay(1). The

command get positional two options for subcommand and direction. In

short:

$ axfer transfer capture|playback [options for transfer subcommand]

$ axfer list capture|playback [options for list subcommand]

$ axfer version

$ axfer help

Manuals to subcommands are added later separately.

- axfer: check whether a terminal is referred for stdio

A reference to a terminal for standard input/output brings some

troubles. For capture transmission, it can bring some terminal

control codes and it's possible to make the terminal in disorder.

For playback transmission, it can bring endless loop to read

data for detection of type of container.

This commit checks whether a terminal is referred for the standard

input/output by a call isatty(3). When detecting a terminal,

axfer run time prints message and goes to finish.

Suggested-by: Takashi Iwai <tiwai@suse.com>

- axfer: truncate parsed arguments before operating subcommand

When subcommands are operated, top-most two arguments are already

parsed in renewed command system, thus they're useless. Besides,

they're possible to be parsed by getopt_long(3).

This commit truncates these options before entering subcommand

operation.

- axfer: use transfer subcommand as a default for compatibility mode to aplay(1)

At present, both of help and transfer subcommands are used when options

are missing in compatibility mode to aplay(1). However, in a view of

users, it should be transfer subcommand.

This commit uses transfer subcommand as a default for the mode.

- axfer: use second argument in command line for transmission direction

In renewed command system, axfer uses first argument for subcommand. In

popular subcommand such as transfer, transmission direction is required.

At present, some options in aplay(1) are used for this purpose however

it's understandable to use second argument for this purpose.

This commit uses second argument as fixed position to indicate

direction for renewed command system.

- axfer: apply refactoring in list subcommand for new command system

This commit splits option parser for new command system into a function

for readability.

- axfer: apply refactoring to list subcommand for backward compatibility to aplay(1)

This commit splits option parser for backward compatibility to aplay(1)

in list subcommand. Supported operations are listed in local enumeration.

- axfer: add support for libffado transmission backend

At present, axfer is designed to use several types of backend for

transmission of data frames. This commit is an implementation

example of the backend.

Libffado is a userspace library for transmission of data frames according

to protocols similar to IEC 61883-1/6. This library handles audio and

music units on IEEE 1394 bus.

Unfortunately, this library executes ctor/dtor of instances for some

objects in startup/finish routines of C runtime. As a result, it outputs

some superfluous messages even if the backend is not actually used.

Furthermore, this library brings memory leak internally. Therefore,

it's not practical to build this backend for generic purposes. Although

the backend implementation works fine, this commit is just for technical

preview.

- axfer: obsolete some unimplemented options

Althogh many options are actually supported by aplay, some of them are

not enough good in practical points. For example, '--test-position'

option is meaningless for some use cases. Furthermore, due to practical

reasons, some options are not implemented well; e.g. vumeter.

This commit marks such options as 'obsoleted'.

- axfer: add support for timer-based scheduling model with MMAP operation

In 2010, ALSA PCM interface got an flag of hardware parameters to suppress

periodical interrupts, according to a request from PulseAudio developer.

In typical PCM operation for usual hardware, PCM drivers configure the

hardware to generate the periodical interrupts to notify that the same

amount of data frames as a period of PCM buffer is actually transferred

via serial sound interface. The flag can suppress this if the driver

support it.

There's some merits of this configuration:

- No interrupt context run for PCM substream. The PCM substream is

handled in any process context only. No need to care of race

conditions between interrupt/process contexts. This is good for

developers of drivers and applications.

- CPU time is not used for handlers on the interrupt context. The CPU

time can be dedicated for the other tasks. This is good in a point

of Time Sharing System.

- Hardware is not configured to generate interrupts. This is good in a

point of reduction of overall power consumption.

Disabling period interrupt is used for 'Timer-based scheduling' to

consume data frames on PCM buffer independently of interrupt context. As

noted, no interrupt context runs for PCM substream, thus any blocking

operation is not released. Furthermore, system calls for multiplexed I/O

is not also released without timeout.

In this scheduling model, applications need to care of available space on

PCM buffer by lapse of time, typically by yielding CPU and wait for

rescheduling. For the yielding, timeout is calculated for preferable

amount of PCM frames to process. This is an additional merit for

applications, like sound servers. when an I/O thread of the server wait

for the timeout, the other threads can process data frames for server

clients. Furthermore, with usage of rewinding/forwarding, applications

can achieve low latency between transmission position and handling

position even if they uses large size of PCM buffers.

But the timeout should be calculated with enough care of hardware

capabilities. To disable period interrupt, used hardware should satisfy

some requirements for data transmission:

1. Even if drivers don't handle interrupts to queue next data transmission,

hardware voluntarily perform the data transmission when needed

(typically by requesting DMA automatically).

2. hardware has a capability to report current position of data

transmission with enough accuracy against the data transmission.

developers refer this as 'granularity'. If hardware can always

reports updated position after the data transmission finishes, the

granularity equals to the size of period of PCM buffer.

3. a fine size of data transmission in one time. This size is decided

depending on configuration of hardware or DMA controller, but for

efficiency it may not be one byte. Thus some amount of data frame is

transferred by one data transmission. Developers refer this as

'burst-ness'.

The timeout should be calculated according to the item 2 and 3, however

in current ALSA PCM interface supplemental information is not delivered

from drivers to applications. Although at present userspace applications

should be written by a speculative way for this point, there's few

problems because there're a few hardware which satisfy the above items.

However, when more drivers supports this feature, the problem may largely

be exposed and bothers application developers.

This commit adds an option to use 'timer-based scheduling' for data

transmission. This commit adds '--sched-model' option, and the scheduling

mode is enabled when 'timer' is assigned to the option by equal sign.

Although there's some TODOs, you can see the scheduling mode in this

simple program, like:

$ axfer transfer --sched-model=timer -P -d 2 -D hw:0,3 /dev/urandom -f dat -vvv

$ axfer transfer --sched-model=timer -C -d 2 -D hw:1,0 /dev/null -r 48000 -vvv

- axfer: add an implementation of waiter for epoll(7)

This commit adds support of waiter for Linux specific epoll(7) system call.

For portability to the other Unix-like systems such as xBSD, modification

of Makefile.am may be required for conditional build, but this commit

includes no changes for it.

Below lines are examples to use this option:

$ axfer transfer --waiter-type=epoll -M -P -d 2 -D hw:0,3 /dev/urandom -f dat -vvv

$ axfer transfer --waiter-type=epoll -M -C -d 2 -D hw:1,0 /dev/null -r 48000 -vvv

- axfer: add an implementation of waiter for select(2)

This commit adds support of waiter for select(2) system call.

Below lines are examples to use this option:

$ axfer transfer --waiter-type=select -M -P -d 2 -D hw:0,3 /dev/urandom -f dat -vvv

$ axfer transfer --waiter-type=select -M -C -d 2 -D hw:1,0 /dev/null -r 48000 -vvv

- axfer: add an implementation of waiter for poll(2)

This commit adds support of waiter for poll(2) system call.

Below lines are examples to use this option:

$ axfer transfer --waiter-type=poll -M -P -d 2 -D hw:0,3 /dev/urandom -f dat -vvv

$ axfer transfer --waiter-type=poll -M -C -d 2 -D hw:1,0 /dev/null -r 48000 -vvv

- axfer: add an option for waiter type

This commit is an integration to add an option for users to choose waiter

type. Users give the type to value to '--waiter-type' ('-w') option to

choose it. Currently, 'snd_pcm_wait()' is just supported as a default.

This alsa-lib API is implemented with a call of poll(2).

- axfer: add a common interface of waiter for I/O event notification

There're several types of system calls for multiplexed I/O. They're used to

receive notifications of I/O events. Typically, userspace applications call

them against file descriptor to yield CPU. When I/O is enabled on any of

the descriptors, a task of the application is rescheduled, then the

application execute I/O calls.

This commit adds a common interface for this type of system calls, named as

'waiter'. This is expected to be used with non-blocking file operation and

operations on mapped page frame.

- axfer: add options for plugins in alsa-lib

As of 2017, two userspace library implementations are known; alsa-lib and

tinyalsa. The latter is simple I/O library to use ALSA PCM interface. On

the other hand, alsa-lib is more complicated than it. This is because it's

designed to add features to transmission of data frames; e.g. sample

resampling. To achieve this, alsa-lib has its configuration space and

plugin system.

In aplay, some options are implemented as a flag for the plugins in

alsa-lib. The flag is given to snd_pcm_open(). This commit adds support

for the flags.

- axfer: add options for software parameters of PCM substream

In ALSA PCM interface, some parameters are used to configure runtime of

PCM substream independently of actual hardware. These parameters are

mainly used to decide the detailed timing to start/stop PCM substream and

release I/O blocking state of application. These parameters are

represented and delivered by a structure.

In alsa-lib PCM API, the structure is hidden from userspace applications.

The applications can set/get actual parameters by helper functions.

In aplay, three of the parameters are configurable. This commit adds

support for them. When no options are given, default values are used.

- axfer: add options for buffer arrangement

In ALSA PCM interface, two parameters are used for size of intermediate

buffer for data frames; period size and buffer size. Actual effects of

these sizes differs depending on hardware, but basically the size of

period is used for intervals of hardware interrupts and the size of buffer

is used to maintain the intermediate buffer as ring buffer. These

parameters can be configured as a part of hardware parameters by

data frame unit or micro second. PCM API in alsa-lib also includes

helper functions to configure them by the two units.

This commit adds support for options to the parameters by both units. When

no options are given, default values are applied according to current

aplay; available maximum size of buffer up to 500msec, a quarter of the

size of buffer for period size. However, these calculation should be

reconsidered somehow.

- axfer: add an option to suppress event waiting

In aplay, '--test-nowait' is used to suppress calls of snd_pcm_wait()

when I/O operations return -EAGAIN or process truncated number of data

frames. This seems to be for debugging purpose. In this program, this

option is equivalent to suppress event waiting.

This commit adds support for this option.

- axfer: add support for MMAP PCM operation

In alsa-lib PCM API, data frames can be handled in mapped page frame,

instead of calling any system calls.

This commit support for this type of operation. To reduce CPU usage,

this commit uses 'snd_pcm_wait()' to wait for event notification.

Below lines are examples to execute:

$ axfer transfer -M -P -d 2 -D hw:0,3 /dev/urandom -f dat -vvv

$ axfer transfer -M -C -d 2 -D hw:1,0 /dev/null -r 48000 -vvv

- axfer: add support for non-blocking operation

In alsa-lib PCM API, snd_pcm_read[i|n]() and snd_pcm_write[i|n] can be

used with non-blocking mode. This is available when SND_PCM_NONBLOCK is

used as 'mode' argument for a call of snd_pcm_open().

This commit adds support this type of operation. To reduce CPU usage, this

commit uses 'snd_pcm_wait()' to wait for event notification.

Below lines are examples to execute:

$ axfer transfer -N -P -d 2 -D hw:0,3 /dev/urandom -f dat -vvv

$ axfer transfer -N -C -d 2 -D hw:1,0 /dev/null -r 48000 -vvv

- axfer: add an option to finish transmission at XRUN

In aplay, '--fatal-errors' option has an effect to give up recovery of PCM

substream from XRUN state. This commit adds support for this option.

In original implementation, this option brings program abort. This seems

to generate core dump of process VMA. However, typically, XRUN comes from

timing mismatch between hardware and application, therefore core dump has

less helpful. This commit finishes this program in usual way with this

option at XRUN.

- axfer: add options related to duration and obsolete '--max-file-size' option

In aplay, some options are available to stop data transmission by frame

unit. This commit adds support for the options below:

* --duration (-d)

* For duration seconds. The number of data frames transferred in this

* runtime is calculated by this value and sampling rate.

* --samples (-s)

* For the number of data frames to handle in this runtime.

An original aplay has a similar option; '--max-file-time'. This option

is used for capture data transmission to switch file to write data frame

up to maximum number of frames which container format supports, instead

of terminating. However, this may brings complicated file handling to

this program. To reduce maintaining cost, this option is obsoleted.

Additionally, a handler for SIGUSR1 Unix signal has similar feature to

switch the file. For the same reason, the handler is also obsoleted.

- axfer: add an option to dump available hardware parameters

In ALSA PCM interface, before configuring hardware actually, applications

can request available set of hardware parameters for runtime of PCM

substream. The set of parameters are represented and delivered by a

structure.

In alsa-lib PCM API, the above design is abstracted by a series of

snd_pcm_hw_params_xxx() functions. An actual layout of the structure is

hidden from applications by an opaque pointer.

In aplay, '--dump-hw-params' option is for this purpose. With this option,

the command output available set of the hardware parameters.

This commit adds support for the option. Unlike aplay, this commit takes

this program to finish after dumping the parameters for simplicity of

usage.

I note that all of combinations in the set are not necessarily available

when the PCM substream includes dependencies of parameters described by

constraints and rules.

- axfer: add informative output and an option to suppress it

In current aplay, some informative output is available as a default. This

can be suppressed by a quiet option. This commit adds support for it.

An original aplay implementation has no effect of this option in a case

to handle multiple files. However, in a point of usability, this commit

support this case.

- axfer: add a sub-command to transfer data frames

In current aplay, default action is to transfer data frames from/to

devices. This commit adds support for this functionality.

Event loop is included in an added file. In the loop, the number of

handled data frames is manipulated by an appropriate way. As a result, users

can stop data transmission frames by frame.

Unlike aplay, when catching SIGSTP, this application performs to suspend

PCM substream. When catching SIGCONT, it performs to resume the PCM

substream. The aim of this design is to avoid XRUN state of the PCM

substream. If users/developers need to any XRUN-recovery test, it's

better to work for the other ways.

Below lines are examples to execute:

$ axfer transfer -P -D hw:0,3 /dev/urandom -f dat -vvv

$ axfer transfer -C -D hw:1,0 /dev/null -r 48000 -vvv

- axfer: add support for blocking data transmission operation of alsa-lib PCM API

In alsa-lib PCM API, snd_pcm_read[i|n]() and snd_pcm_write[i|n]() are used

to transfer data frames from/to hardware. When a handler is not opened with

specific flags, these functions perform blocking operation; i.e. the

function call doesn't return till all of request number of data frames are

actually handled, or call is interrupted by Unix signals, or PCM substeam

corrupts due to hardware reasons.

This commit adds support for this type of data transmission. For cases that

requested data frames are not processed by container interface, this commit

adds internal cache mechanism to handle rest of data frames in next timing.

- axfer: add support to transfer data frames by alsa-lib PCM APIs

This commit adds support fo alsa-lib PCM API as a backend of 'xfer'

module. In a set of alsa-lib PCM API, there're two ways to handle data

frames; by calling ioctl(2) with some specific commands with buffer in

user space, or copying data frames on mapped page frames. To support

both ways, this commit adds an operation structure as abstraction.

- axfer: add a parser for command-line options

In aplay, many command-line options are supported. Some of them have

dependency or conflicts. Furthemore, some of them are just for

runtime configuration of alsa-lib(libasound), and some options can

be used by several xfer backends commonly; e.g. options for file name,

sample format and sampling rate.

This commit adds a parser for the common options below.

* --help (-h)

* Just output 'help' string (not written yet).

* --verbose (-v)

* For verbose output, including information about xfer, mapper and

container.

* --format (-f): string. format literals or one of ['cd'|'cdr'|'dat']

* For sample format supported by ALSA PCM interface. Special format

can be used. For playback, this is auto-detected according to actual

file format.

* --channels (-c)

* For the number of samples included in one data frame. For playback,

this is auto-detected according to actual file format, except for

'raw' format. This option can conflict to above format option.

* --rate (-r)

* For the number of data frames transferred in one second. For playback,

this is auto-detected according to actual file format, except for

'raw' format. This option can conflict to format option above.

* --file-type (-f): string. one of ['wav'|'au'|'voc'|'raw']

* For format of files of given paths. For playback, this is optional

because the format is auto-detected. For capture, this is optional too

because the format is decided according to suffix of given path.

Anyway, this option is used for cases to fail to detect or decide.

* --separate-channels (-I)

* When using several files as source or destination for transmission

of data frame, this option can be used with several file paths.

When '--separate-channels' option is used, users can give several file

paths to source/destination of data transmission, else they can give single

file path for the purpose. When multiple files are handled by this option,

for playback, data frames in first channel is used to construct buffer for

data transmission with multi channel. For capture, data frames in each

channel of buffer are written to each of given path. Furthermore, when a

single path is given for capture, file paths are auto-generated according

to available number of channels. For example, 'name.wav' is given for

2 channels capture, 'name-0.wav' and 'name-1.wav' are generated. In a

case of no suffix, 'name-0' and 'name-1' are generated.

- axfer: add a common interface to transfer data frames

ALSA has PCM interface to transfer data frames. In userspace, there're

some implementation to utilize this interface to produce application

programming interface; alsa-lib (libasound) and tinyalsa. However, it's

possible to use the interface with raw I/O operations.

This commit adds an common interface to transfer data frames for this

program, named as 'xfer'. This internal interface is designed for users

to select several backend for data transmission. This includes some

functions expected to be called by main program just for data

transmission. In an aspect to maintain PCM substream, suspend feature is

required to handle a pair of SIGTSTP/SIGCONT UNIX signals.

- axfer: add a unit test for mapper interface

In former commits, mapper module gets supports of muxer/demuxer for

single/multiple targets for playback source or capture destination. This

commit adds a unit test for them. This includes positive test cases only.

The test cases actually generate I/O to file systems for many test cases.

It takes a bit long time to finish.

- axfer: add support for a mapper for multiple target

This commit adds support of mapper for 'multiple' target. This handles

several files via 'container' functions, and constructs data frame buffer

for playback, or splits data frames from data frame buffer for capture.

When playback source files includes data frames with several channels, the

first channel is used to construct buffer. For capture direction, each of

channel of data frame is stored in one file, thus the file includes one

channel of data frame. When handling non-interleaved buffer, a caller

should use an array of buffer for each of channels with non-interleaved

data frames.

- axfer: add support for a mapper for single target

In usual use case of aplay, single file is used to playback or capture data

frames.

This commit adds support of single type mapper for this use case. All of

supported file format can include data frame with interleaved alignment,

thus this mapper have a functionality to convert from several types of

data frame alignment to interleaved alignment or vise versa. When

handling non-interleaved buffer, a caller should use an array of buffer

for each of channels with non-interleaved data frames.

- axfer: add a common interface to align data frames on different layout

In current aplay, several files can be handled as source of data frames for

playback, or destination of captured data frames by an option

'--separate-channels' (-I).

On the other hand, in ALSA PCM kernel/user interface, several types of

buffer are used to communicate between application/hardware;

- mapped page frame for data frames with interleaved alignment

- mapped page frame for data frames with non-interleaved alignment

- buffer in user space for data frames with interleaved alignment

- a list of buffer in user space for data frames with non-interleaved

alignment

This commit adds a common interface, named as 'mapper' to convert frame

alignment between these two sides. This interface includes two types;

'muxer' and 'demuxer'. The 'muxer' is for playback direction, to

construct playback buffer with PCM frames from several files. The 'demuxer'

is for capture direction, to split PCM frames from capture buffer to

each of file. Unlike multimedia containers such as MPEG 2/4 Systems,

the 'muxer' and 'demuxer' are for playback/capture buffer, not for file

contents.

- axfer: add unit test for container interface

In former commits, container module gets supports of parser/builder for

several types of file format. This commit adds a unit test for them.

This includes positive test cases only. The test cases actually generate

I/O to file systems for many test cases. It takes a long time to finish.

- axfer: add support for a container of raw data

This commit adds support for raw data without any headers/chunks/blocks.

A parser of container cannot recognize format of sample without

supplemental information.

Additionally, it includes no magic bytes. A parser of container should

process first several bytes as a part of PCM frames, instead of magic

bytes.

- axfer: add support for a container of Creative Tech. voice format

This commit adds support for data of Creative Tech. voice format. In this

data format, values in each of field are represented in little-endian byte

order and available formats of data sample are restricted in little-endian

byte order.

In version 1.10 of this format, sampling rate is represented with

reciprocal number of the rate, thus we cannot calculate original sampling

rate precisely just from its header. For example at 44.1kHz, file header

includes 233 (=256-1,000,000/44,100), but we cannot recover the value just

from the code (43478.2...). For my convenience, this commit adds a

pre-computed table and lookup major rates from the table.

Additionally, this format can includes several blocks with different

sample format. When handling this type of file, we need to start/stop

substream for each of the block, while this brings complicated code.

This type of format is enough ancient and presently quite minor. This

commit takes a compromise and handles a first sample block only.

- axfer: add support for a container of Sparc AU format

This commit adds support for data of Sparc AU format. In this data format,

values in each of field are encoded in big-endian byte order and available

formats of data sample are restricted in big-endian byte order.

- axfer: add support for a container of Microsoft/IBM RIFF/Wave format

This commit adds support for data of Microsoft/IBM RIFF/Wave format. In

this data format, values in each of field are encoded in both bit/little

byte order but inner a file the same order is used. Magic bytes in the

beginning of data indicated which byte order is used for the file.

- axfer: add a common interface to handle a file with audio-specific data format

Current aplay supports several types of data format for file; Microsoft/IBM

RIFF/Wave (.wav), Sparc AU (.au) and Creative Tech. voice (.voc). These

formats were designed to handle audio-related data with interleaved frame

alignment.

This commit adds a common interface to handle the file format, named as

'container' module. This includes several functions to build/parse

the format data from any file descriptors. Furthermore, this includes

several helper functions for implementations of each builder/parser.

- axfer: add a sub-command to print list of PCMs/devices

Original aplay implementation has a feature to output two types of list;

devices and PCMs. The list of devices is a result to query sound card and

pcm component structured maintained in kernel land. The list of PCMs is a

result to parse runtime configuration files in alsa-lib. Entries in the

former list is corresponding to ALSA PCM character device

('/dev/snd/pcm%uC%uD[p|c]'), while entries in the latter list includes

some 'virtual' instances in application runtime.

This commit adds an implementation for the above functionality. This is

executed by taking 'list' sub-command. A 'device' option has the same

effect as '--list-devices' and '-L' of aplay. A 'pcm' option has the same

effect as '--list-pcms' and '-l' of aplay. In both cases, an additional

option is required for stream direction. Below is examples of new command

system for this sub-command.

$ axfer list device -C (= arecord --list-devices)

$ axfer list pcm -P (= aplay -l)

- axfer: add an entry point for this command

This commit adds a new command, 'axfer' ('ALSA transfer'), to transfer data

frames described in asound.h. This command is intended to replace current

aplay. The most of features and command line parameters come from aplay as

much as possible, while it has more better feature and code to maintain.

This commit adds an entry point for this command. Current option system of

aplay is still available, while this command has a sub-command system like

commands in iproute2.

Currently, two sub-commands are supported; 'list' and 'transfer'. The

'list' sub-command has the same effect as '-l' and '-L' options of aplay.

The 'transfer' sub-command has the same effect as the main feature of

aplay. For the sub-command system, an option for stream direction is

required; '-P' for playback and '-C' for capture. If you create symbolic

links to this binary for aplay/arecord, please execute:

$ ln -s axfer aplay

$ ln -s axfer arecord

Actual code for each sub-command will be implemented in later commits.

alsaloop

- alsaloop: more avail_min cleanups

1) do not increase avail_min forever

It seems that there are broken plugins like pulse which returns from poll()

immediately regardless avail_min settings.

2) remove ommited debug printf()

alsatplg (topology)

- topology/topology.c: drop unneeded <dlfcn.h> include

This include is not used/needed and prevents building on systems that

don't provide <dlfcn.h>.

aplay/arecord

- aplay: improve available conditions for '--samples' and '--duration' options

Either '--samples' ('-s') and '--duration' ('-d') option is available

exclusively, according to its semantics and actual implementation.

This commit improves description of manual at this point.

Reviewed-by: Daniel Baluta daniel.baluta@nxp.com

- aplay: add a paragraph for '--samples' ('-s') option to aplay manual

A '--samples' ('-s') option was added so that record/playback process is

terminated after handling the same number of PCM frames as a value of the

option. However this option is not described in aplay manual.

This commit adds a paragraph for the option.

Fixes: 3d44e2bc159e ('aplay: Add samples argument for playing/recording a given number of samples')

Reviewed-by: Daniel Baluta daniel.baluta@nxp.com

- aplay: delete paragraph for obsoleted '--sleep-min' ('-s') option from aplay manual

A '--sleep-min' option was already obsoleted for aplay. On the other hand,

a paragraph for the option was left as is.

This commit deletes the paragraph.

Fixes: 4cb74aed89f1 ('Remove sleep_min from aplay')

Reviewed-by: Daniel Baluta daniel.baluta@nxp.com

alsa-plugins

Core

- Release v1.1.8

- aaf: AVTPDU transmission periodicity

When operating in playback mode (i.e. AVTP talker) the plugin is

expected to transmit the AVTPDUs in a periodical manner. The AVTPDU

period is defined by the number of audio frames per AVTPDU and the

sampling rate (see section 7.7 from AVTP spec [1] for further

information).

To enforce the AVTPDU periodicity, this patch leverages the SO_TXTIME

sockopt recently added to socket interface which enables the userspace

to specify when a given packet should be transmitted. The plugin

configures the transmission time from each AVTPDU so the expected

transmission interval is maintained.

The SO_TXTIME feature works in conjunction with the Earliest TxTime

First (ETF) qdisc. The ETF qdisc sorts packets from multiple sockets by

the earliest transmission time and sends them to the network controller.

It also enables offloading packet transmission to hardware in case the

NIC supports it, providing more time accuracy. For further information

about ETF qdisc, see tc-etf(8). The qdisc can be configured many ways,

in doc/aaf.txt we provide an example.

Below follows some implementation highlights:

The packet transmission time is configured through socket control

message interface so we now use sendmsg() to transmit AVTPDUs, instead

of sendto().

sendmsg() API requires a msghdr struct which is initialized during

device setup time. Strictly speaking, that struct is only required when

operating in playback mode but we initialize it always, no matter if

running in playback or capture mode. This makes hw_params() and

hw_free() callbacks implementation way more simpler, specially on

handling error cases.

[1] 1722-2016 - IEEE Standard for a Transport Protocol for Time-Sensitive

Applications in Bridged Local Area Networks

- aaf: Implement Playback mode support

This patch implements the playback mode support from the AAF plugin.

Simply put, this mode works as follows: PCM samples provided by alsa-lib

layer are encapsulated into AVTPDUs and transmitted through the network.

In summary, the playback mode implements a typical AVTP Talker.

When the AAF device is put in running state, its media clock is started.

At every tick from the media clock, audio frames are consumed from the

audio buffer, encapsulated into an AVTPDU, and transmitted to the

network. The presentation time from each AVTPDU is calculated taking in

consideration the maximum transit time and time uncertainty values

configured by the user.

Below follows some discussion about implementation details:

AVTP protocol doesn't support all formats and rates available in ALSA so

the plugin sets some constraints to ensure only supported configurations

are used (see aaf_set_hw_constraint function).

The plugin implements a media clock which is the source from AVTP

timestamps. The AVTP timestamp is based on PTP time which uses

International Atomic Time (TAI) coordinate system. The media clock is

implemented through a periodic timer using timerfd infrastructure so the

plugin requires that system clock and PTP clock are synchronized

(instructions on how to sync these clocks are provided in doc/aaf.txt).

CLOCK_TAI clockid isn't currently supported by timerfd so the timer fd

is created using CLOCK_REALTIME and the start time is converted from TAI

to UTC.

Even though only one file descriptor is used to implement the playback

mode, this patch doesn't leverage ioplug->poll_fd but defines poll

callbacks instead. The reason is these callbacks will be required to

support capture mode (to be implemented by upcoming patch).

The TSN data plane interface is the AF_PACKET socket family so the

plugin uses an AF_PACKET socket to send/receive AVTPDUs. Linux requires

CAP_NET_RAW capability in order to open an AF_PACKET socket so the

application that instantiates the plugin must have it. For further info

about AF_PACKET socket family see packet(7).

- aaf: Load configuration parameters

This patch implements the infrastructure to load the plugin

configuration from ALSA configuration file. The configuration

is loaded in open() callback.

All configuration parameters are described in details in doc/aaf.txt

file.

- aaf: Introduce plugin skeleton

The patch introduces the skeleton code from the AAF plugin as well as

the buildsystem bits in order to get the plugin built. Following the

approach from other plugins, the AAF plugin is only built if its

dependency (libavtp) is detected by configure.

Follow-up patches implement support for both playback and capture modes.

/Makefile.am

- aaf: Introduce plugin skeleton

The patch introduces the skeleton code from the AAF plugin as well as

the buildsystem bits in order to get the plugin built. Following the

approach from other plugins, the AAF plugin is only built if its

dependency (libavtp) is detected by configure.

Follow-up patches implement support for both playback and capture modes.

A52 Output plugin

- a52_close: set slave to NULL to avoid double pcm free in open fcn

AVTP Audio Format (AAF) PCM plugin

- aaf: AVTPDU transmission periodicity

When operating in playback mode (i.e. AVTP talker) the plugin is

expected to transmit the AVTPDUs in a periodical manner. The AVTPDU

period is defined by the number of audio frames per AVTPDU and the

sampling rate (see section 7.7 from AVTP spec [1] for further

information).

To enforce the AVTPDU periodicity, this patch leverages the SO_TXTIME

sockopt recently added to socket interface which enables the userspace

to specify when a given packet should be transmitted. The plugin

configures the transmission time from each AVTPDU so the expected

transmission interval is maintained.

The SO_TXTIME feature works in conjunction with the Earliest TxTime

First (ETF) qdisc. The ETF qdisc sorts packets from multiple sockets by

the earliest transmission time and sends them to the network controller.

It also enables offloading packet transmission to hardware in case the

NIC supports it, providing more time accuracy. For further information

about ETF qdisc, see tc-etf(8). The qdisc can be configured many ways,

in doc/aaf.txt we provide an example.

Below follows some implementation highlights:

The packet transmission time is configured through socket control

message interface so we now use sendmsg() to transmit AVTPDUs, instead

of sendto().

sendmsg() API requires a msghdr struct which is initialized during

device setup time. Strictly speaking, that struct is only required when

operating in playback mode but we initialize it always, no matter if

running in playback or capture mode. This makes hw_params() and

hw_free() callbacks implementation way more simpler, specially on

handling error cases.

[1] 1722-2016 - IEEE Standard for a Transport Protocol for Time-Sensitive

Applications in Bridged Local Area Networks

- aaf: Tx multiple AVTPDUs per media clock tick

In order to implement the transmission offload mechanism, we need to

change the way the plugin behaves so, instead of sending only one

AVTPDU, it sends several AVTPDUs at every media clock tick.

To achieve that, this patch changes the plugin so it consumes the audio

buffer in chunks of period size instead of in frames_per_pdu. The number

of AVTPDUs sent at every media clock tick is calculated by dividing the

period size by the number of frames per AVTPDU. To ensure that number is

not fractional, the plugin requires that the period size is multiple of

the plugin configuration 'frames_per_pdu'.

For the sake of consistency, the capture mode is also changed so the

plugin presents audio frames to the alsa-lib layer in chunks of period

size as well.

- aaf: Refactor timeout routines

The functions aaf_mclk_timeout_playback() and aaf_mclk_timeout_capture()

have some common code so this patch does a code refactoring by moving

the shared code into a new function called aaf_timer_timeout().

After the refactoring, aaf_mclk_timeout_playback() and aaf_mclk_timeout_

capture() ended up having no code related to timeout so they were

renamed to better represent what they really do (send frames and present

frames, respectively).

- aaf: Refactor AVTPDU reception routines

This patch does some code refactoring in the AVTPDU reception

routines in order to prepare the code to support the transmission

offload mechanism that will be added by upcoming patches. No

functionality is added or removed by this patch.

In summary, the function aaf_rx_pdu() is broken down into smaller, new

functions and some code is moved to is_pdu_valid(). Below follows more

details about the code refactoring.

The function aaf_rx_pdu() was renamed to aaf_socket_new_data() which

reads the socket and dispatches the AVTPDU in case the PCM device isn't

in DRAIN state. Function aaf_dispatch_pdu() simply reads the subtype

field from the AVTPDU and dispatches it according. For now, only AAF

PDUs are supported. Finally, the aaf_dispatch_pdu_aaf() handles AAF

AVTPDUs which means to check if the AVTPDU is valid, copies the PCM

samples from the payload to the audio buffer, and start the media clock

in case it hasn't been started already.

The function is_pdu_valid() is moved around to avoid forward

declaration. Code to validate the sequence number and presentation time

from the AVTPDU which used to be in aaf_rx_pdu() is moved into

is_pdu_valid().

- aaf: Refactor AVTPDU transmission routines

This patch does some code refactoring in the AVTPDU transmission

routines in order to prepare the code to support the transmission

offload mechanism that will be added by upcoming patches. No

functionality is added or removed by this patch.

In summary, code from aaf_tx_pdu() is moved into aaf_mclk_timeout_

playback() and into a new function introduced by this patch called

aaf_tx_pdus(). Below follows more details about the code refactoring.

The function aaf_tx_pdu() is modified so it only takes care of setting

the payload, sequence number and presentation time from the AVTPDU, and

sending it to the kernel.

The new function aaf_tx_pdus() calculates the presentation time from

each AVTPDU and calls aaf_tx_pdu() multiple times, according to the pdu

count argument.

Finally, the function aaf_mclk_timeout_playback() now checks if there

are frames available to the "hardware" and takes care of moving the

hardware pointer forward.

- aaf: Add presentation time tolerance

Different AVTP applications have different presentation time tolerance.

The current version of the plugin doesn't support any tolerance so this

patch extends the AAF plugin in order to enable the user to configure

that tolerance value.

The presentation time tolerance is specified in microseconds and it is

relevant only when the plugin is operating in capture mode. For more

information see the 'Plugin Configuration' session in doc/aaf.txt

This patch also does some code refactoring and encapsulates all

presentation time validation code in the new is_ptime_valid() helper

function.

- aaf: do not free twice aaf - snd_pcm_close() is called from snd_pcm_ioplug_delete()

- aaf: Add support for direct read/write transfers

This patch adds support for direct read/write transfers (i.e. mmap

access mode) to the AAF plugin.

In order to enable direct read/write transfers, the AAF plugin is

required to implement ioplug's pseudo mmap mode. In this mode, the audio

buffer management (e.g. areas allocation, clean up, and data copy) is

handled at upper layers, making the AAF plugin simpler. So this patch

removes all code related to audio buffer management as well as the

transfer() callback from the AAF plugin.

- aaf: Implement dump() ioplug callback

This patch introduces the aaf_dump() function which prints information

about both PCM and AVTP setup.

- aaf: Implement Capture mode support

This patch implements the capture mode support from the AAF plugin.

Simply put, this mode works as follows: AVTPDUs are received from the

network, the PCM samples are retrieved and presented to the alsa-lib

layer at the presentation time. In summary, the capture mode implements

a typical AVTP Listener.

Once the AAF device is put in running state, packet reception is

started. Every time an AVTPDU is received, the plugin checks if it is

valid (according to the stream configuration provided by the user) and

copies the PCM samples to the audio buffer. Note that at this moment,

the samples are not presented to the alsa-lib layer yet (i.e. hw_ptr is

not incremented).

The media clock starts at the presentation time from the first AVTPDU.

At every tick from the media clock, PCM samples are presented to the

alsa-lib layer.

Below follows some secondary discussion about this patch:

The functions aaf_mclk_start_playback() and aaf_mclk_start_capture()

have some common code. This patch does some code refactoring so the

common code is put in a new function (aaf_mclk_start) which is called

by both aaf_mclk_start_playback() and aaf_mclk_start_capture().

Also, the helper function aaf_inc_hw_ptr() is refactored so it can be

used to increment both aaf->hw_ptr and aaf->hw_virt_ptr.

- aaf: Prepare for Capture mode support

The plugin code assumes only Playback mode is supported. This patch

prepares the code to support both Playback and Capture mode. Capture

mode support is implemented by a follow-up patch.