Android: add makefile and config.h

This is the initial porting of alsa-utils 1.2.1 to Android.
Four tools are built: alsa_amixer, alsa_aplay, alsa_ctl, alsa_ucm.

Signed-off-by: Chih-Wei Huang <cwhuang@linux.org.tw>

alsamixer: add exp10 for Android

Android doesn't have exp10 yet. Define it as before commit 116488e5f2f.

Signed-off-by: Chih-Wei Huang <cwhuang@linux.org.tw>

amixer: remove unnecessary prefix ../include/

All other files include "version.h" don't have the prefix ../include/.
It's unnecessary and causes trouble to Android porting.

Signed-off-by: Chih-Wei Huang <cwhuang@linux.org.tw>

aplay: Limit VUMeter progress bar to 100 for negative as well

While the progress bar cannot be negative, GCC concludes that it can be
and assumes tmp can be written past the end. Fixes this GCC warning:

aplay.c:1747:18: warning: '%02d' directive writing between 2 and 11 bytes
 into a region of size 4 [-Wformat-overflow=]
 1747 |    sprintf(tmp, "%02d%%", maxperc[c]);

Signed-off-by: Rosen Penev <rosenp@gmail.com>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

aplay: Adjust buffer sizes to fix snprintf warnings

It also reduces compiled size slightly.

aplay.c: In function 'capture':
aplay.c:3055:34: error: '-01' directive output may be truncated writing 3
bytes into a region of size between 1 and 4097 [-Werror=format-truncation=
]
 3055 |    snprintf(namebuf, namelen, "%s-01", buf);
      |                                  ^~~
aplay.c:3055:4: note: 'snprintf' output between 4 and 4100 bytes into a
destination of size 4097
 3055 |    snprintf(namebuf, namelen, "%s-01", buf);
      |    ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
aplay.c:3053:34: error: '-01.' directive output may be truncated writing 4
bytes into a region of size between 1 and 4097 [-Werror=format-truncation=
]
 3053 |    snprintf(namebuf, namelen, "%s-01.%s", buf, s);
      |                                  ^~~~
aplay.c:3053:4: note: 'snprintf' output 5 or more bytes (assuming 4101)
into a destination of size 4097
 3053 |    snprintf(namebuf, namelen, "%s-01.%s", buf, s);
      |    ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
aplay.c:3065:34: error: '%02i' directive output may be truncated writing
between 2 and 10 bytes into a region of size between 0 and 4096 [-Werror=
format-truncation=]
 3065 |   snprintf(namebuf, namelen, "%s-%02i", buf, filecount);
      |                                  ^~~~
aplay.c:3065:30: note: directive argument in the range [1, 2147483647]
 3065 |   snprintf(namebuf, namelen, "%s-%02i", buf, filecount);
      |                              ^~~~~~~~~
aplay.c:3065:3: note: 'snprintf' output between 4 and 4108 bytes into a
destination of size 4097
 3065 |   snprintf(namebuf, namelen, "%s-%02i", buf, filecount);
      |   ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
aplay.c:3063:34: error: '%02i' directive output may be truncated writing
between 2 and 10 bytes into a region of size between 0 and 4096 [-Werror=
format-truncation=]
 3063 |   snprintf(namebuf, namelen, "%s-%02i.%s", buf, filecount, s);
      |                                  ^~~~
aplay.c:3063:30: note: directive argument in the range [1, 2147483647]
 3063 |   snprintf(namebuf, namelen, "%s-%02i.%s", buf, filecount, s);
      |                              ^~~~~~~~~~~~
aplay.c:3063:3: note: 'snprintf' output 5 or more bytes (assuming 4109)
into a destination of size 4097
 3063 |   snprintf(namebuf, namelen, "%s-%02i.%s", buf, filecount, s);

Signed-off-by: Rosen Penev <rosenp@gmail.com>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

treewide: Fix printf formats

Found with cppcheck

Signed-off-by: Rosen Penev <rosenp@gmail.com>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

treewide: Fix wrong formats on 32-bit

uint64_t evaluates to unsigned long long on 32-bit, not unsigned long.
Use the proper formats.

Signed-off-by: Rosen Penev <rosenp@gmail.com>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

treewide: sys/poll to poll

Fixes warning on musl:

warning redirecting incorrect #include <sys/poll.h> to <poll.h>

Signed-off-by: Rosen Penev <rosenp@gmail.com>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

Release v1.2.1

Signed-off-by: Jaroslav Kysela <perex@perex.cz>

alsaucm: fix the implicit card open

Signed-off-by: Jaroslav Kysela <perex@perex.cz>

alsaucm, topology: LDADD cleanups and add support for libatopology

Signed-off-by: Jaroslav Kysela <perex@perex.cz>

alsaucm: do the implicit ucm open only when the command requires it

Signed-off-by: Jaroslav Kysela <perex@perex.cz>

alsaucm: call snd_config_update_free_global() to make valgrind more happy

Signed-off-by: Jaroslav Kysela <perex@perex.cz>

amixer: do not double LF for container type

Signed-off-by: Jaroslav Kysela <perex@perex.cz>

axfer: handle -ETIMEDOUT before non-block I/O operation

When running for IRQ-based scheduling model, transmission backend is
expected to queue PCM event in different context from the main thread.
When queueing no events during time equivalent to one period of PCM
buffer, the backend has problems.

This commit outputs report it for non-blocking operation for IRQ-based
scheduling model. The timeout is equivalent to all frames in buffer,
instead of period for safe.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Jaroslav Kysela <perex@perex.cz>

axfer: code refactoring for a helper function to wait for avail buffer space

This commit applies code refactoring for waiting PCM event queued
per period of PCM buffer in copying operation for IRQ-based scheduling
model.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Jaroslav Kysela <perex@perex.cz>

axfer: handle -ETIMEDOUT before handle mmap I/O operation

When running for IRQ-based scheduling model, transmission backend is
expected to queue PCM event in different context from the main thread.
When queueing no events during time equivalent to one period of PCM
buffer, the backend has problems.

This commit outputs report it for mmap operation for IRQ-based
scheduling model. The timeout is equivalent to all frames in buffer,
instead of period for safe.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Jaroslav Kysela <perex@perex.cz>

axfer: return ETIMEDOUT when no event occurs after waiter expiration

Although the waiter abstraction handles timeout as success, it should
report for callers to know timeout.

This commit takes the waiter to return -ETIMEDOUT when timeout expires.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Jaroslav Kysela <perex@perex.cz>

axfer: fix to return error code when a call of select(2) fails

A call of select(2) returns negative code and report errors via errno
local variable, howver current waiter implementation for select(2)
returns the negative code instead of errno.

This commit fixes it.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Jaroslav Kysela <perex@perex.cz>

axfer: return the number of file descriptors for I/O events from select(2) waiter

A call of select(2) returns error code at failure, the number of file
descriptors available I/O at success. Current implementation of
waiter abstraction for select(2) returns 0 at success and callers
can't get the number.

This commit fixes it.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Jaroslav Kysela <perex@perex.cz>

aplay: fix memory leak when setup_chmap() fail

setup_chmap() will return with error number if hw_map calloc fail or
channels doesn't match with hw_params, but memory free was ignored when
error occurs.

Signed-off-by: chunxu.li <chunxuxiao@gmail.com>
Reviewed-by: Takashi Sakamoto o-takashi@sakamocchi.jp
Signed-off-by: Jaroslav Kysela <perex@perex.cz>

alsamixer: Remove exp10 usage

exp10 is a GNU extension and not available everywhere (eg. uClibc-ng).

Signed-off-by: Rosen Penev <rosenp@gmail.com>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

axfer: test: fix invalid comparison of 64 bit storage in ILP32 data type

In system V ABIs with ILP32 data model, bit shift for '1ul' can brings
undefined behaviour when the calculation result is over 32 bit width.

This commit fixes the bug.

Reported-by: Rolf Eike Beer <eike@sf-mail.de>
Reference: https://bugs.gentoo.org/681652
Reference: https://github.com/alsa-project/alsa-utils/issues/23
Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

axfer: mapper: fix parameter check for demuxer

Each container should be configured to store one saple per frame in
demuxer case. This commit fixes the bug.

Fixes: 25c8e3bebb53 ('axfer: add support for a mapper for multiple target')
Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

axfer: remove unused variable warnings

Signed-off-by: Jaroslav Kysela <perex@perex.cz>

Release v1.1.9

Signed-off-by: Jaroslav Kysela <perex@perex.cz>

axfer/test: fix uninitialized warning

This commit fixes uninitialized return value from a call of test_mux() and
text_demux() to suppress warnings below:

$ make check
...
gcc -DHAVE_CONFIG_H -I. -I../../include     -O2 -Wall -pipe -g -MT mapper-test.o -MD -MP -MF .deps/mapper-test.Tpo -c -o mapper-test.o mapper-test.c
mapper-test.c: In function ‘test_mapper’:
mapper-test.c:241:9: warning: ‘err’ may be used uninitialized in this function [-Wmaybe-uninitialized]
  return err;
         ^~~
mapper-test.c:231:5: warning: ‘err’ may be used uninitialized in this function [-Wmaybe-uninitialized]
  if (err < 0)
     ^

Fixes: 39d1ab8a0cb4: ('axfer: add a unit test for mapper interface')
Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Jaroslav Kysela <perex@perex.cz>

axfer/test: fix uninitialized warning

This commit fixes uninitialized return value from a call of test_vector()
to suppress a warning below.

gcc -DHAVE_CONFIG_H -I. -I../../include     -O2 -Wall -pipe -g -MT mapper-test.o -MD -MP -MF .deps/mapper-test.Tpo -c -o mapper-test.o mapper-test.c
mapper-test.c: In function ‘test_vector’:
mapper-test.c:293:6: warning: ‘err’ may be used uninitialized in this function [-Wmaybe-uninitialized]
  int err;
      ^~~

Fixes: 39d1ab8a0cb4: ('axfer: add a unit test for mapper interface')
Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Jaroslav Kysela <perex@perex.cz>

axfer: Declare global variables as 'extern' in header

This avoids multiple definitions of the same global variable (one in
each file that includes this header), and fixes a linking error when
compiled with -fno-common.

Fixes: 96110793b3e5 ("axfer: add support for a container of raw data")

Signed-off-by: Samuel Holland <samuel@sholland.org>
Reviewed-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Jaroslav Kysela <perex@perex.cz>

axfer: Fix creation of v1.2 headers on big-endian systems

struct block_v120_format defines these members as uint8_t. On
little-endian systems, no swapping is done, and the generated block
header is fine. However, on big-endian machines, the value is swapped to
the high byte and then truncated by the assignment, causing both
bits_per_sample and samples_per_frame to be zero.

This fixes an assertion failure in container-test when later
parsing the header ["assert(*samples_per_frame > 0);" in
container_context_pre_process()].

Fixes: 4ab7510f3a18: ("axfer: add support for a container of Creative Tech. voice format")

Signed-off-by: Samuel Holland <samuel@sholland.org>
Reviewed-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Jaroslav Kysela <perex@perex.cz>

amixer: define _GNU_SOURCE to get exp10

Get rid of a warning about implicit declaration of exp10, which is
behind _GNU_SOURCE as a non-standard feature. The same problem was fixed
for alsamixer in commit 116488e5f2f1b897084bd151381ee254e1cc177d.

Signed-off-by: Milton Vandersloot <miltonvandersloot@fake-box.com>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

xfer: fix possible minor memory leak in xfer_options_parse_args() (coverity)

Signed-off-by: Jaroslav Kysela <perex@perex.cz>

axfer: return back unsigned avail variable, do proper retype in xfer-libasound-irq-mmap.c

Signed-off-by: Jaroslav Kysela <perex@perex.cz>

alsaloop: remove unused assignment warning (coverity)

Signed-off-by: Jaroslav Kysela <perex@perex.cz>

alsactl: monitor - remove dead code in run_dispatcher() (coverity)

Signed-off-by: Jaroslav Kysela <perex@perex.cz>

aplay: check the return value for snd_pcm_sw_params_current() (coverity)

Signed-off-by: Jaroslav Kysela <perex@perex.cz>

axfer: coverity fixes

- container-voc.c - out of array access
- container-voc.c - handle correctly eof
- frame_cache.c - correct memory allocation
- container.c - byte_count might be used uninitialized
- xfer-libasound-irq-mmap.c - fix avail signess
- xfer-options.c - fix potential 32-bit wrap for duration

Signed-off-by: Jaroslav Kysela <perex@perex.cz>

aplay: fix the multiple open file descriptors for the raw capture

Signed-off-by: Jaroslav Kysela <perex@perex.cz>

arecordmidi: simple coverity fix

Signed-off-by: Jaroslav Kysela <perex@perex.cz>

alsactl: simple coverity fix

Signed-off-by: Jaroslav Kysela <perex@perex.cz>

alsa-info.sh: cleanups

- fix awk arguments
- backticks/gravemarks removal
- some cosmetic and indentation changes
- add REQUIRES to check the basic tools

Signed-off-by: Jaroslav Kysela <perex@perex.cz>

seq: arecordmidi: Add num-events option

Add a command line option to automatically exit after recording a fixed
number of MIDI events. This allows a program using arecordmidi to expect
a MIDI file to be written automatically when the specified number of
events have been received, instead of having to send a SIGINT or SIGTERM
programmatically.

It also avoids the need to have the arecordmidi process running in the
background, and then constantly stat the output file to check if any
bytes have been written to it (this makes for less predictable and
longer-running tests).

This functionality finds use in Chrome OS functional testing, since
having to send SIGTERM/SIGINT programmatically and then wait for the
output file adds unpredictability and delay to the tests.

The addition of this command-line option should (hopefully) not break
any existing usage.

Signed-off-by: Prashant Malani <pmalani@chromium.org>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

axfer: add missing header file of unit test to distribution

The file 'axfer/test/generator.h' is missing in distribution and brings
FTBFS for unit tests of axfer.

This commit fixes to add it.

Reported-by: Elimar Riesebieter <riesebie@lxtec.de>
Fixes: b878df1ff0b0: ('axfer: add unit test for container interface')
Fixes: 39d1ab8a0cb4: ('axfer: add a unit test for mapper interface')
Signed-off-by: Takashi Iwai <tiwai@suse.de>

axfer: allow to be compiled with glibc-2.11 or former

The program, axfer, was developed in userspace with glibc-2.28. This
userspace is mostly compliant to POSIX:2008 and some additional macros
for poll event are officially available. The glibc supports them as a
default since its v2.12 release. It will be failed to be compiled with
old glibc or the other libraries for C standard APIs.

One of the purpose of axfer is an better alternative of aplay. In a
point of the purpose, it's preferable to be compiled with the old
libraries.

This commit adds conditional macros to be compiled with libraries for
old compliance level of POSIX.

Reported-by: Jay Foster <jay@systech.com>
Fixes: fce16d9279b6 ('axfer: add an implementation of waiter for select(2)')
Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

axfer: add an entry of axfer to README

Axfer has beed added as a rework of aplay with robust design to
support recent features of Linux sound subsystem.

This commit adds an entry to README.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

axfer: correct invalid usage of escape of itaric text

A dot sign is valid for a prefix of instruction.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

axfer: supplement value of options for the manual of transfer subcommand

This commit supplements value of options for the manual of transfer
subcommand.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

axfer: correct message to notice that help text is implemented

Now help message is available to give help option to command line.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

axfer: correct description about snoop mode of libffado

The libffado library can listen to isochronous channels to which unit on
IEEE 1394 bus transfers packets as long as the unit allows software to
read the channel from its register.

This commit corrects description about snoop mode.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

axfer: fulfill section for backward compatibitity for chmap option

At present, axfer losts backward compatibility to aplay in a point of
'chmap' option.

This commit filfills a section to describe lose of backward compatibility
of chmap option.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

axfer: add a section about unit test

Two unit tests are available to check internal implementation of axfer.
They perform file I/O for many times and take much time to finish.

This commit adds a section about it.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

alsamixer: define _GNU_SOURCE to get exp10

Fixes Master, Headphones and Speaker stuck at -8 percentage after
building with Clang 7.0.1 and getting warned about implicit declaration
of exp10, which is behind _GNU_SOURCE as a non-standard feature. Thanks
Takashi Iwai for the CFLAGS suggestion on the mailing list. GCC build is
not affected, so not adding a compiler check to the configure script.

uClibc-ng has got exp10 since 1.0.12, so the fallback macro is no longer
needed. However, alsa-utils relies on gettext so might need further
patches to actually work on uClibc systems.

Signed-off-by: makepost <makepost@firemail.cc>
Signed-off-by: Jaroslav Kysela <perex@perex.cz>

Release v1.1.8

Signed-off-by: Jaroslav Kysela <perex@perex.cz>

Makefile.am: add README.md to EXTRA_DIST

Signed-off-by: Jaroslav Kysela <perex@perex.cz>

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.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

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.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

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.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

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.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

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.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

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.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

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.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

axfer: print help for libffado backend

This commit adds help texts for libffado backend.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

axfer: correct description about signal handling

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

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

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')
Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

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')
Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

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.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

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.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

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.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

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.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

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.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

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.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

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.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

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.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

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.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

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>
Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

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.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

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.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

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.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

axfer: apply refactoring in list subcommand for new command system

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

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

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.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

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.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

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

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

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

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

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

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

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

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

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

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

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

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

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.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

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.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

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.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

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.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

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.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

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

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

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

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

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.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

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.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

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.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

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.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

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

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

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.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>