|
Packit |
229ac0 |
.TH AXFER\-TRANSFER 1 "28 November 2018" "alsa\-utils"
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.SH NAME
|
|
Packit |
229ac0 |
axfer\-transfer \- transferrer of audio data frame for sound devices and nodes.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.SH SYNOPSIS
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.B axfer transfer
|
|
Packit |
229ac0 |
.I direction
|
|
Packit |
229ac0 |
[
|
|
Packit |
229ac0 |
.I common\-options
|
|
Packit |
229ac0 |
] [
|
|
Packit |
229ac0 |
.I backend\-options
|
|
Packit |
229ac0 |
] [
|
|
Packit |
229ac0 |
.I filepath
|
|
Packit |
229ac0 |
]
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.B axfer transfer
|
|
Packit |
229ac0 |
.I direction
|
|
Packit |
229ac0 |
[
|
|
Packit |
229ac0 |
.I common\-options
|
|
Packit |
229ac0 |
] [
|
|
Packit |
229ac0 |
.I backend\-options
|
|
Packit |
229ac0 |
]
|
|
Packit |
229ac0 |
.I \-I
|
|
Packit |
229ac0 |
|
|
|
Packit |
229ac0 |
.I \-\-separate\-channels filepath ...
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
direction =
|
|
Packit |
229ac0 |
.B capture
|
|
Packit |
229ac0 |
|
|
|
Packit |
229ac0 |
.B playback
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
common\-options = ( read
|
|
Packit |
229ac0 |
.I OPTIONS
|
|
Packit |
229ac0 |
section )
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
backend\-options = ( read
|
|
Packit |
229ac0 |
.I OPTIONS
|
|
Packit |
229ac0 |
section )
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
filepaths = ( read
|
|
Packit |
229ac0 |
.I OPTIONS
|
|
Packit |
229ac0 |
section )
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.SH DESCRIPTION
|
|
Packit |
229ac0 |
The
|
|
Packit |
229ac0 |
.B transfer
|
|
Packit |
229ac0 |
subcommand of
|
|
Packit |
229ac0 |
.B axfer
|
|
Packit |
229ac0 |
performs transmission of audio data frames for devices available in supported
|
|
Packit |
229ac0 |
backends. This program is essentially designed to use alsa\-lib APIs
|
|
Packit |
229ac0 |
(libasound backend) to handle sound devices supported by Linux sound subsystem
|
|
Packit |
229ac0 |
(ALSA).
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.SH OPTIONS
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.SS Direction
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.B capture
|
|
Packit |
229ac0 |
Operates for capture transmission.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.B playback
|
|
Packit |
229ac0 |
Operates for playback transmission.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.SS Filepath
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
Filepath is handled as a path relative to current working directory of run time
|
|
Packit |
229ac0 |
if it\(aqs not full path from root directory.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
The standard input or output is used if filepath is not specified or given as
|
|
Packit |
229ac0 |
.I \(aq\-\(aq
|
|
Packit |
229ac0 |
\&.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
For playback transmission, container format of given
|
|
Packit |
229ac0 |
.I filepath
|
|
Packit |
229ac0 |
is detected automatically and metadata is used for parameters of sample format,
|
|
Packit |
229ac0 |
channels, rate, duration. If nothing detected, content of given file path is
|
|
Packit |
229ac0 |
handled as raw data. In this case, the parameters should be indicated as
|
|
Packit |
229ac0 |
options.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
Multiple
|
|
Packit |
229ac0 |
.I filepaths
|
|
Packit |
229ac0 |
are allowed with
|
|
Packit |
229ac0 |
.I \-I
|
|
Packit |
229ac0 |
|
|
|
Packit |
229ac0 |
.I \-\-separate\-channels
|
|
Packit |
229ac0 |
option. In this case, standard input and output is not available. The same
|
|
Packit |
229ac0 |
.I filepath
|
|
Packit |
229ac0 |
is not allowed except for paths listed below:
|
|
Packit |
229ac0 |
\- /dev/null
|
|
Packit |
229ac0 |
\- /dev/zero
|
|
Packit |
229ac0 |
\- /dev/full
|
|
Packit |
229ac0 |
\- /dev/random
|
|
Packit |
229ac0 |
\- /dev/urandom
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.SS Common options
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.B \-h, \-\-help
|
|
Packit |
229ac0 |
Print help messages and finish run time.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.B \-q, \-\-quiet
|
|
Packit |
229ac0 |
Quiet mode. Suppress messages (not sound :))
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.B \-v, \-\-verbose
|
|
Packit |
229ac0 |
Verbose mode. Runtime dumps supplemental information according to the number of
|
|
Packit |
229ac0 |
this option given in command line.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.B \-d, \-\-duration=#
|
|
Packit |
229ac0 |
Interrupt after # seconds. A value of zero means infinity. The default is zero,
|
|
Packit |
229ac0 |
so if this option is omitted then the transmission process will run until it is
|
|
Packit |
229ac0 |
killed. Either
|
|
Packit |
229ac0 |
.I \-d
|
|
Packit |
229ac0 |
or
|
|
Packit |
229ac0 |
.I \-s
|
|
Packit |
229ac0 |
option is available exclusively.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.B \-s, \-\-samples=#
|
|
Packit |
229ac0 |
Interrupt after transmission of # number of data frames. A value of zero means
|
|
Packit |
229ac0 |
infinity. The default is zero, so if this options is omitted then the
|
|
Packit |
229ac0 |
transmission process will run until it is killed. Either
|
|
Packit |
229ac0 |
.I \-d
|
|
Packit |
229ac0 |
or
|
|
Packit |
229ac0 |
.I \-s
|
|
Packit |
229ac0 |
option is available exclusively.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.B \-f, \-\-format=FORMAT
|
|
Packit |
229ac0 |
Indicate format of audio sample. This is required for capture transmission, or
|
|
Packit |
229ac0 |
playback transmission with files including raw audio data.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
Available sample format is listed below:
|
|
Packit |
229ac0 |
- [S8|U8|S16|U16|S32|U32][_LE|_BE]
|
|
Packit |
229ac0 |
- [S24|U24][_LE|_BE]
|
|
Packit |
229ac0 |
- FLOAT[_LE|_BE]
|
|
Packit |
229ac0 |
- FLOAT64[_LE|_BE]
|
|
Packit |
229ac0 |
- IEC958_SUBFRAME[_LE|_BE]
|
|
Packit |
229ac0 |
- MU_LAW
|
|
Packit |
229ac0 |
- A_LAW
|
|
Packit |
229ac0 |
- [S20|U20][_LE|_BE]
|
|
Packit |
229ac0 |
- [S24|U24][_3LE|_3BE]
|
|
Packit |
229ac0 |
- [S20|U20][_3LE|_3BE]
|
|
Packit |
229ac0 |
- [S18|U18][_3LE|_3BE]
|
|
Packit |
229ac0 |
- DSD_U8
|
|
Packit |
229ac0 |
- DSD_[U16|U32][_LE|_BE]
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
If endian\-ness is omitted, host endian\-ness is used.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
Some special formats are available:
|
|
Packit |
229ac0 |
- cd (16 bit little endian, 44100, stereo) [= \-f S16_LE \-c 2 \-r 44100]
|
|
Packit |
229ac0 |
- cdr (16 bit big endian, 44100, stereo) [= \-f S16_BE \-c 2 \-f 44100]
|
|
Packit |
229ac0 |
- dat (16 bit little endian, 48000, stereo) [= \-f S16_LE \-c 2 \-r 48000]
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
If omitted,
|
|
Packit |
229ac0 |
.I U8
|
|
Packit |
229ac0 |
is used as a default. Actual available formats are restricted by each
|
|
Packit |
229ac0 |
transmission backend.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
Unavailable sample format is listed below. These format has size of data frame
|
|
Packit |
229ac0 |
unaligned to byte unit.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
- IMA_ADPCM
|
|
Packit |
229ac0 |
- MPEG
|
|
Packit |
229ac0 |
- GSM
|
|
Packit |
229ac0 |
- SPECIAL
|
|
Packit |
229ac0 |
- G723_24
|
|
Packit |
229ac0 |
- G723_24_1B
|
|
Packit |
229ac0 |
- G723_40
|
|
Packit |
229ac0 |
- G723_40_1B
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.B \-c, \-\-channels=#
|
|
Packit |
229ac0 |
Indicate the number of audio data samples per frame. This is required for
|
|
Packit |
229ac0 |
capture transmission, or playback transmission with files including raw audio
|
|
Packit |
229ac0 |
data. The value should be between
|
|
Packit |
229ac0 |
.I 1 to
|
|
Packit |
229ac0 |
.I 256
|
|
Packit |
229ac0 |
\&. If omitted,
|
|
Packit |
229ac0 |
.I 1
|
|
Packit |
229ac0 |
is used as a default.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.B \-r, \-\-rate=#
|
|
Packit |
229ac0 |
Indicate the number of audio data frame per second. This is required for
|
|
Packit |
229ac0 |
capture transmission, or playback transmission with files including raw audio
|
|
Packit |
229ac0 |
data. If the value is less than
|
|
Packit |
229ac0 |
.I 1000
|
|
Packit |
229ac0 |
, it\(aqs interpreted by
|
|
Packit |
229ac0 |
.I kHz
|
|
Packit |
229ac0 |
unit. The value should be between
|
|
Packit |
229ac0 |
.I 2000
|
|
Packit |
229ac0 |
and
|
|
Packit |
229ac0 |
.I 192000
|
|
Packit |
229ac0 |
\&. If omitted,
|
|
Packit |
229ac0 |
.I 8000
|
|
Packit |
229ac0 |
is used as a default.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.B \-t, \-\-file\-type=TYPE
|
|
Packit |
229ac0 |
Indicate the type of file. This is required for capture transmission. Available
|
|
Packit |
229ac0 |
types are listed below:
|
|
Packit |
229ac0 |
- wav: Microsoft/IBM RIFF/Wave format
|
|
Packit |
229ac0 |
- au, sparc: Sparc AU format
|
|
Packit |
229ac0 |
- voc: Creative Tech. voice format
|
|
Packit |
229ac0 |
- raw: raw data
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
When nothing is indicated, for capture transmission, the type is decided
|
|
Packit |
229ac0 |
according to suffix of
|
|
Packit |
229ac0 |
.I filepath
|
|
Packit |
229ac0 |
, and
|
|
Packit |
229ac0 |
.I raw
|
|
Packit |
229ac0 |
type is used for fallback.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.B \-I, \-\-separate\-channels
|
|
Packit |
229ac0 |
Indicate this option when several files are going to be handled. For capture
|
|
Packit |
229ac0 |
transmission, if one filepath is given as
|
|
Packit |
229ac0 |
.I filepath
|
|
Packit |
229ac0 |
, a list of
|
|
Packit |
229ac0 |
.I filepaths
|
|
Packit |
229ac0 |
is generated in a formula \(aq<filepath>\-<sequential number>[.suffix]\(aq.
|
|
Packit |
229ac0 |
The suffix is omitted when raw format of container is used.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.B \-\-dump\-hw\-params
|
|
Packit |
229ac0 |
Dump hardware parameters and finish run time if backend supports it.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.B \-\-xfer\-backend=BACKEND
|
|
Packit |
229ac0 |
Select backend of transmission from a list below. The default is libasound.
|
|
Packit |
229ac0 |
.br
|
|
Packit |
229ac0 |
- libasound
|
|
Packit |
229ac0 |
- libffado (optional if compiled)
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.SS Backend options for libasound
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.B \-D, \-\-device=NODE
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
This option is used to select PCM node in libasound configuration space.
|
|
Packit |
229ac0 |
Available nodes are listed by
|
|
Packit |
229ac0 |
.I pcm
|
|
Packit |
229ac0 |
operation of
|
|
Packit |
229ac0 |
.I list
|
|
Packit |
229ac0 |
subcommand.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.B \-N, \-\-nonblock
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
With this option, PCM substream is opened in non\-blocking mode. When audio
|
|
Packit |
229ac0 |
data frame is not available in buffer of the PCM substream, I/O operation
|
|
Packit |
229ac0 |
immediately returns without blocking process. This option implicitly uses
|
|
Packit |
229ac0 |
.I \-\-waiter\-type
|
|
Packit |
229ac0 |
option as well to prevent heavy consumption of CPU time.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.B \-M, \-\-mmap
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
With this option, audio data frame is processed directly in buffer of PCM
|
|
Packit |
229ac0 |
substream if selected node supports this operation. Without the option,
|
|
Packit |
229ac0 |
temporary buffers are used to copy audio data frame for buffer of PCM substream.
|
|
Packit |
229ac0 |
This option implicitly uses
|
|
Packit |
229ac0 |
.I \-\-waiter\-type
|
|
Packit |
229ac0 |
option as well to prevent heavy consumption of CPU time.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.B \-F, \-\-period\-size=#
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
This option configures given value to
|
|
Packit |
229ac0 |
.I period_size
|
|
Packit |
229ac0 |
hardware parameter of PCM substream. The parameter indicates the number of audio
|
|
Packit |
229ac0 |
data frame per period in buffer of the PCM substream. Actual number is decided
|
|
Packit |
229ac0 |
as a result of interaction between each implementation of PCM plugin chained
|
|
Packit |
229ac0 |
from the selected PCM node, and in\-kernel driver or PCM I/O plugins.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
Ideally, the same amount of audio data frame as the value should be handled in
|
|
Packit |
229ac0 |
one I/O operation. Actually, it is not, depending on implementation of the PCM
|
|
Packit |
229ac0 |
plugins, in\-kernel driver, PCM I/O plugins and scheduling model. For \(aqhw\(aq
|
|
Packit |
229ac0 |
PCM plugin in \(aqirq\(aq scheduling model, the value is used to decide
|
|
Packit |
229ac0 |
intervals of hardware interrupt, thus the same amount of audio data frame as
|
|
Packit |
229ac0 |
the value is expected to be available for one I/O operation.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.B \-\-period\-time=#
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
This option configures given value to
|
|
Packit |
229ac0 |
.I period_time
|
|
Packit |
229ac0 |
hardware parameter of PCM substream. This option is similar to
|
|
Packit |
229ac0 |
.I \-\-period\-size
|
|
Packit |
229ac0 |
option, however its unit is micro\-second.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.B \-B, \-\-buffer\-size=#
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
This option configures given value to
|
|
Packit |
229ac0 |
.I buffer_size
|
|
Packit |
229ac0 |
hardware parameter of PCM substream. The parameter indicates the number of audio
|
|
Packit |
229ac0 |
data frame in buffer of PCM substream. Actual number is decided as a result of
|
|
Packit |
229ac0 |
interaction between each implementation of PCM plugin chained from the selected
|
|
Packit |
229ac0 |
PCM node, and in\-kernel driver or PCM I/O plugins.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
Ideally, this is multiples of the number of audio data frame per period, thus
|
|
Packit |
229ac0 |
the size of period. Actually, it is not, depending on implementation of the PCM
|
|
Packit |
229ac0 |
plugins, in\-kernel driver and PCM I/O plugins.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.B \-\-buffer\-time=#
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
This option configures given value to
|
|
Packit |
229ac0 |
.I buffer_time
|
|
Packit |
229ac0 |
hardware parameter of PCM substream. This option is similar to
|
|
Packit |
229ac0 |
.I \-\-buffer\-size
|
|
Packit |
229ac0 |
option, however its unit is micro\-second.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.B \-\-waiter\-type=TYPE
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
This option indicates the type of waiter for event notification. At present,
|
|
Packit |
229ac0 |
four types are available;
|
|
Packit |
229ac0 |
.I default
|
|
Packit |
229ac0 |
,
|
|
Packit |
229ac0 |
.I select
|
|
Packit |
229ac0 |
,
|
|
Packit |
229ac0 |
.I poll
|
|
Packit |
229ac0 |
and
|
|
Packit |
229ac0 |
.I epoll
|
|
Packit |
229ac0 |
\&. With
|
|
Packit |
229ac0 |
.I default
|
|
Packit |
229ac0 |
type, \(aqsnd_pcm_wait()\(aq is used. With
|
|
Packit |
229ac0 |
.I select
|
|
Packit |
229ac0 |
type, \(aqselect(2)\(aq system call is used. With
|
|
Packit |
229ac0 |
.I poll
|
|
Packit |
229ac0 |
type, \(aqpoll(2)\(aq system call is used. With
|
|
Packit |
229ac0 |
.I epoll
|
|
Packit |
229ac0 |
type, Linux\-specific \(aqepoll(7)\(aq system call is used.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
This option should correspond to one of
|
|
Packit |
229ac0 |
.I \-\-nonblock
|
|
Packit |
229ac0 |
or
|
|
Packit |
229ac0 |
.I \-\-mmap
|
|
Packit |
229ac0 |
options, or
|
|
Packit |
229ac0 |
.I timer
|
|
Packit |
229ac0 |
value of
|
|
Packit |
229ac0 |
.I \-\-sched\-model
|
|
Packit |
229ac0 |
option.
|
|
Packit |
229ac0 |
Neither this option nor
|
|
Packit |
229ac0 |
.I \-\-test\-nowait
|
|
Packit |
229ac0 |
is available at the same time.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.B \-\-sched\-model=MODEL
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
This option selects scheduling model for process of this program. One of
|
|
Packit |
229ac0 |
.I irq
|
|
Packit |
229ac0 |
or
|
|
Packit |
229ac0 |
.I timer
|
|
Packit |
229ac0 |
is available. In detail, please read \(aqSCHEDULING MODEL\(aq section.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
When nothing specified,
|
|
Packit |
229ac0 |
.I irq
|
|
Packit |
229ac0 |
model is used.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.B \-A, \-\-avail\-min=#
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
This option configures given value to
|
|
Packit |
229ac0 |
.I avail\-min
|
|
Packit |
229ac0 |
software parameter of PCM substream. In blocking mode, the value is used as
|
|
Packit |
229ac0 |
threshold of the number of available audio data frames in buffer of PCM
|
|
Packit |
229ac0 |
substream to wake up process blocked by I/O operation. In non\-blocking mode,
|
|
Packit |
229ac0 |
any I/O operation returns \-EAGAIN untill the available number of audio data frame reaches the threshold.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
This option has an effect in cases neither
|
|
Packit |
229ac0 |
.I \-\-mmap
|
|
Packit |
229ac0 |
nor
|
|
Packit |
229ac0 |
.I timer
|
|
Packit |
229ac0 |
value of
|
|
Packit |
229ac0 |
.I \-\-sched\-model
|
|
Packit |
229ac0 |
option is used.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.B \-R, \-\-start\-delay=#
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
This option configures given value to
|
|
Packit |
229ac0 |
.I start_threshold
|
|
Packit |
229ac0 |
software parameter of PCM substream. The value is used as threshold to start
|
|
Packit |
229ac0 |
PCM substream automatically. At present, this option has an effect in cases
|
|
Packit |
229ac0 |
neither
|
|
Packit |
229ac0 |
.I \-\-mmap
|
|
Packit |
229ac0 |
nor
|
|
Packit |
229ac0 |
.I timer
|
|
Packit |
229ac0 |
value of
|
|
Packit |
229ac0 |
.I \-\-sched\-model
|
|
Packit |
229ac0 |
option is used.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
For playback transmission, when the number of accumulated audio data frame
|
|
Packit |
229ac0 |
in buffer of PCM substream to which this program writes out reaches the
|
|
Packit |
229ac0 |
threshold, the PCM substream starts automatically without an explicit call of
|
|
Packit |
229ac0 |
.I snd_pcm_start()
|
|
Packit |
229ac0 |
to the PCM substream.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
For capture transmission, this option is useless. The number of
|
|
Packit |
229ac0 |
accumulated audio data frame is not increased without an explicit call of
|
|
Packit |
229ac0 |
.I snd_pcm_start()
|
|
Packit |
229ac0 |
to the PCM substream.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
This option has an effect in cases neither
|
|
Packit |
229ac0 |
.I \-\-mmap
|
|
Packit |
229ac0 |
nor
|
|
Packit |
229ac0 |
.I timer
|
|
Packit |
229ac0 |
value of
|
|
Packit |
229ac0 |
.I \-\-sched\-model
|
|
Packit |
229ac0 |
option is used.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.B \-T, \-\-stop\-delay=#
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
This option configures given value to
|
|
Packit |
229ac0 |
.I stop_threshold
|
|
Packit |
229ac0 |
software parameter of PCM substream. The value is used as threshold to stop PCM
|
|
Packit |
229ac0 |
substream automatically. At present, this option has an effect in cases neither
|
|
Packit |
229ac0 |
.I \-\-mmap
|
|
Packit |
229ac0 |
nor
|
|
Packit |
229ac0 |
.I timer
|
|
Packit |
229ac0 |
value of
|
|
Packit |
229ac0 |
.I \-\-sched\-model
|
|
Packit |
229ac0 |
option is used.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
For capture transmission, when the number of accumulated audio data frame
|
|
Packit |
229ac0 |
in buffer of PCM substream to which a driver or alsa\-lib PCM plugins write
|
|
Packit |
229ac0 |
reaches the threshold, the PCM substream stops automatically without an explicit
|
|
Packit |
229ac0 |
call of
|
|
Packit |
229ac0 |
.I snd_pcm_stop()
|
|
Packit |
229ac0 |
to the PCM substream. This is a case that this program leaves the audio data
|
|
Packit |
229ac0 |
frames without reading for a while.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
For playback transmission, when the number available audio data frame in buffer
|
|
Packit |
229ac0 |
of PCM substream from which a driver or alsa\-lib PCM plugins read reaches the
|
|
Packit |
229ac0 |
threshold, the PCM substream stops automatically without an explicit call of
|
|
Packit |
229ac0 |
.I snd_pcm_stop()
|
|
Packit |
229ac0 |
to the PCM substream. This is a case that this program leaves the audio data
|
|
Packit |
229ac0 |
frames without writing for a while.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
This option has an effect in cases neither
|
|
Packit |
229ac0 |
.I \-\-mmap
|
|
Packit |
229ac0 |
nor
|
|
Packit |
229ac0 |
.I timer
|
|
Packit |
229ac0 |
value of
|
|
Packit |
229ac0 |
.I \-\-sched\-model
|
|
Packit |
229ac0 |
option is used.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.B \-\-disable\-resample
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
This option has an effect for \(aqplug\(aq plugin in alsa\-lib to suppress
|
|
Packit |
229ac0 |
conversion of sampling rate for audio data frame.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.B \-\-disable\-channels
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
This option has an effect for \(aqplug\(aq plugin in alsa\-lib to suppress
|
|
Packit |
229ac0 |
conversion of channels for audio data frame.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.B \-\-disable\-format
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
This option has an effect for \(aqplug\(aq plugin in alsa\-lib to suppress
|
|
Packit |
229ac0 |
conversion of sample format for audio data frame.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.B \-\-disable\-softvol
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
This option has an effect for \(aqsoftvol\(aq plugin in alsa\-lib to suppress
|
|
Packit |
229ac0 |
conversion of samples for audio data frame via additional control element.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.B \-\-fatal\-errors
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
This option suppresses recovery operation from XRUN state of running PCM
|
|
Packit |
229ac0 |
substream, then process of this program is going to finish as usual.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.B \-\-test\-nowait
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
This option disables any waiter for I/O event notification. I/O operations are
|
|
Packit |
229ac0 |
iterated till any of audio data frame is available. The option brings heavy
|
|
Packit |
229ac0 |
load in consumption of CPU time.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.SS Backend options for libffado
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
This backend is automatically available when configure script detects
|
|
Packit |
229ac0 |
.I ffado_streaming_init()
|
|
Packit |
229ac0 |
symbol in libffado shared object.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.B \-p, \-\-port=#
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
This option uses given value to decide which 1394 OHCI controller is used to
|
|
Packit |
229ac0 |
communicate. When Linux system has two 1394 OHCI controllers,
|
|
Packit |
229ac0 |
.I 0
|
|
Packit |
229ac0 |
or
|
|
Packit |
229ac0 |
.I 1
|
|
Packit |
229ac0 |
are available. Neither this option nor
|
|
Packit |
229ac0 |
.I \-g
|
|
Packit |
229ac0 |
is available at the same time. If nothing specified, libffado performs to
|
|
Packit |
229ac0 |
communicate to units on IEEE 1394 bus managed by all of 1394 OHCI controller available in Linux system.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.B \-n, \-\-node=#
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
This option uses given value to decide which unit is used to communicate. This
|
|
Packit |
229ac0 |
option requires
|
|
Packit |
229ac0 |
.I \-p
|
|
Packit |
229ac0 |
option to indicate which 1394 OHCI controller is used to communicate to the
|
|
Packit |
229ac0 |
specified unit.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.B \-g, \-\-guid=HEXADECIMAL
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
This option uses given value to decide a target unit to communicate. The value
|
|
Packit |
229ac0 |
should be prefixed with '0x' and consists of hexadecimal literal letters
|
|
Packit |
229ac0 |
(0\-9, a\-f, A\-F). Neither this option nor
|
|
Packit |
229ac0 |
.I \-p
|
|
Packit |
229ac0 |
is available at the same time. If nothing specified, libffado performs to
|
|
Packit |
229ac0 |
communicate to units on IEEE 1394 bus managed by all of 1394 OHCI controller
|
|
Packit |
229ac0 |
available in Linux system.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.B \-\-frames\-per\-period=#
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
This option uses given value to decide the number of audio data frame in one
|
|
Packit |
229ac0 |
read/write operation. The operation is blocked till the number of available
|
|
Packit |
229ac0 |
audio data frame exceeds the given value. As a default, 512 audio data frames
|
|
Packit |
229ac0 |
is used.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.B \-\-periods\-per\-buffer=#
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
This option uses given value to decide the size of intermediate buffer between
|
|
Packit |
229ac0 |
this program and libffado. As a default, 2 periods per buffer is used.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.B \-\-slave
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
This option allows this program to run slave mode. In this mode, libffado
|
|
Packit |
229ac0 |
adds unit directory into configuration ROM of 1394 OHCI controller where Linux
|
|
Packit |
229ac0 |
system runs. The unit directory can be found by the other node on the same bus.
|
|
Packit |
229ac0 |
Linux system running on the node can transfer isochronous packet with audio
|
|
Packit |
229ac0 |
data frame to the unit. This program can receive the packet and demultiplex the
|
|
Packit |
229ac0 |
audio data frame.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.B \-\-snoop
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
This option allows this program to run snoop mode. In this mode, libffado
|
|
Packit |
229ac0 |
listens isochronous channels to which device transfers isochronous packet. When
|
|
Packit |
229ac0 |
isochronous communication starts by any unit on the same bus, the packets can
|
|
Packit |
229ac0 |
be handled by this program.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.B \-\-sched\-priority=#
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
This option executes
|
|
Packit |
229ac0 |
.I pthread_setschedparam()
|
|
Packit |
229ac0 |
in a call of
|
|
Packit |
229ac0 |
.I ffado_streaming_init()
|
|
Packit |
229ac0 |
to configure
|
|
Packit |
229ac0 |
scheduling policy and given value as its priority for threads related to
|
|
Packit |
229ac0 |
isochronous communication.
|
|
Packit |
229ac0 |
The given value should be within
|
|
Packit |
229ac0 |
.I RLIMIT_RTPRIO
|
|
Packit |
229ac0 |
parameter of process. Please read
|
|
Packit |
229ac0 |
.I getrlimit(2)
|
|
Packit |
229ac0 |
for details.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.SH POSIX SIGNALS
|
|
Packit |
229ac0 |
During transmission,
|
|
Packit |
229ac0 |
.I SIGINT
|
|
Packit |
229ac0 |
and
|
|
Packit |
229ac0 |
.I SIGTERM
|
|
Packit |
229ac0 |
will close handled files and PCM substream to be going to finish run time.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.I SIGTSTP
|
|
Packit |
229ac0 |
will suspend PCM substream and
|
|
Packit |
229ac0 |
.I SIGCONT
|
|
Packit |
229ac0 |
will resume it. No XRUNs are expected. With libffado backend, the suspend/resume
|
|
Packit |
229ac0 |
is not supported and runtime is aboeted immediately.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
The other signals perform default behaviours.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.SH EXAMPLES
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.PP
|
|
Packit |
229ac0 |
.in +4n
|
|
Packit |
229ac0 |
.EX
|
|
Packit |
229ac0 |
.B $ axfer transfer playback \-d 1 something
|
|
Packit |
229ac0 |
.EE
|
|
Packit |
229ac0 |
.in
|
|
Packit |
229ac0 |
.PP
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
The above will transfer audio data frame in \(aqsomething\(aq file for playback
|
|
Packit |
229ac0 |
during 1 second. The sample format is detected automatically as a result to
|
|
Packit |
229ac0 |
parse \(aqsomething\(aq as long as it\(aqs compliant to one of Microsoft/IBM
|
|
Packit |
229ac0 |
RIFF/Wave, Sparc AU, Creative Tech. voice formats. If nothing detected,
|
|
Packit |
229ac0 |
.I \-r
|
|
Packit |
229ac0 |
,
|
|
Packit |
229ac0 |
.I \-c
|
|
Packit |
229ac0 |
and
|
|
Packit |
229ac0 |
.I \-f
|
|
Packit |
229ac0 |
should be given,
|
|
Packit |
229ac0 |
or
|
|
Packit |
229ac0 |
.I \-f
|
|
Packit |
229ac0 |
should be given with special format.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.PP
|
|
Packit |
229ac0 |
.in +4n
|
|
Packit |
229ac0 |
.EX
|
|
Packit |
229ac0 |
.B $ axfer transfer playback \-r 22050 \-c 1 \-f S16_LE \-t raw something
|
|
Packit |
229ac0 |
.EE
|
|
Packit |
229ac0 |
.in
|
|
Packit |
229ac0 |
.PP
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
The above will transfer audio data frame in \(aqsomething\(aq file including no
|
|
Packit |
229ac0 |
information of sample format, as sample format of 22050 Hz, monaural, signed 16
|
|
Packit |
229ac0 |
bit little endian PCM for playback. The transmission continues till catching
|
|
Packit |
229ac0 |
.I SIGINT
|
|
Packit |
229ac0 |
from keyboard or
|
|
Packit |
229ac0 |
.I SIGTERM
|
|
Packit |
229ac0 |
by
|
|
Packit |
229ac0 |
.I kill(1)
|
|
Packit |
229ac0 |
\&.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.PP
|
|
Packit |
229ac0 |
.in +4n
|
|
Packit |
229ac0 |
.EX
|
|
Packit |
229ac0 |
.B $ axfer transfer capture \-d 10 \-f cd something.wav
|
|
Packit |
229ac0 |
.EE
|
|
Packit |
229ac0 |
.in
|
|
Packit |
229ac0 |
.PP
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
The above will transfer audio data frame to \(aqsomething.wav\(aq file as
|
|
Packit |
229ac0 |
sample format of 44.1 kHz, 2 channels, signed 16 bit little endian PCM, during
|
|
Packit |
229ac0 |
10 seconds. The file format is Microsoft/IBM RIFF/Wave according to suffix of
|
|
Packit |
229ac0 |
the given
|
|
Packit |
229ac0 |
.I filepath
|
|
Packit |
229ac0 |
\&.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.PP
|
|
Packit |
229ac0 |
.in +4n
|
|
Packit |
229ac0 |
.EX
|
|
Packit |
229ac0 |
.B $ axfer transfer capture \-s 1024 \-r 48000 \-c 2 \-f S32_BE \-I \-t au channels
|
|
Packit |
229ac0 |
.EE
|
|
Packit |
229ac0 |
.in
|
|
Packit |
229ac0 |
.PP
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
The above will transfer audio data frame as sample format of 48.0 kHz, 2
|
|
Packit |
229ac0 |
channels, signed 32 bit big endian PCM for 1,024 number of data frames to files
|
|
Packit |
229ac0 |
named \(aqchannels\-1.au\(aq and \(aqchannels\-2.au\(aq.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.SH SCHEDULING MODEL
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
In a design of ALSA PCM core, runtime of PCM substream supports two modes;
|
|
Packit |
229ac0 |
.I period\-wakeup
|
|
Packit |
229ac0 |
and
|
|
Packit |
229ac0 |
.I no\-period\-wakeup.
|
|
Packit |
229ac0 |
These two modes are for different scheduling models.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.SS IRQ\-based scheduling model
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
As a default,
|
|
Packit |
229ac0 |
.I period\-wakeup
|
|
Packit |
229ac0 |
mode is used. In this mode, in\-kernel drivers should operate hardware to
|
|
Packit |
229ac0 |
generate periodical notification for transmission of audio data frame. The
|
|
Packit |
229ac0 |
interval of notification is equivalent to the same amount of audio data frame
|
|
Packit |
229ac0 |
as one period of buffer, against actual time.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
In a handler assigned to the notification, a helper function of ALSA PCM core
|
|
Packit |
229ac0 |
is called to update a position to head of hardware transmission, then compare
|
|
Packit |
229ac0 |
it with a position to head of application operation to judge overrun/underrun
|
|
Packit |
229ac0 |
(XRUN) and to wake up blocked processes.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
For this purpose, hardware IRQ of controller for serial audio bus such as
|
|
Packit |
229ac0 |
Inter\-IC sound is typically used. In this case, the controller generates the
|
|
Packit |
229ac0 |
IRQ according to transmission on the serial audio bus. In the handler assigned
|
|
Packit |
229ac0 |
to the IRQ, direct media access (DMA) transmission is requested between
|
|
Packit |
229ac0 |
dedicated host memory and device memory.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
If target hardware doesn't support this kind of mechanism, the periodical
|
|
Packit |
229ac0 |
notification should be emulated by any timer; e.g. hrtimer, kernel timer.
|
|
Packit |
229ac0 |
External PCM plugins generated by PCM plugin SDK in alsa\-lib should also
|
|
Packit |
229ac0 |
emulate the above behaviour.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
In this mode, PCM applications are programmed according to typical way of I/O
|
|
Packit |
229ac0 |
operations. They execute blocking system calls to read/write audio data frame
|
|
Packit |
229ac0 |
in buffer of PCM substream, or blocking system calls to wait until any audio
|
|
Packit |
229ac0 |
data frame is available. In
|
|
Packit |
229ac0 |
.I axfer
|
|
Packit |
229ac0 |
, this is called
|
|
Packit |
229ac0 |
.I IRQ\-based
|
|
Packit |
229ac0 |
scheduling model and a default behaviour. Users can explicitly configure this
|
|
Packit |
229ac0 |
mode by usage of
|
|
Packit |
229ac0 |
.I \-\-sched\-model
|
|
Packit |
229ac0 |
option with
|
|
Packit |
229ac0 |
.I irq
|
|
Packit |
229ac0 |
value.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.SS Timer\-based scheduling model
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
The
|
|
Packit |
229ac0 |
.I no\-period\-wakeup
|
|
Packit |
229ac0 |
mode is an optional mode of runtime of PCM substream. The mode assumes a
|
|
Packit |
229ac0 |
specific feature of hardware and assist of in\-kernel driver and PCM
|
|
Packit |
229ac0 |
applications. In this mode, in\-kernel drivers don't operate hardware to
|
|
Packit |
229ac0 |
generate periodical notification for transmission of audio data frame.
|
|
Packit |
229ac0 |
The hardware should automatically continue transmission of audio data frame
|
|
Packit |
229ac0 |
without periodical operation of the drivers; e.g. according to auto\-triggered
|
|
Packit |
229ac0 |
DMA transmission, a chain of registered descriptors.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
In this mode, nothing wakes up blocked processes, therefore PCM applications
|
|
Packit |
229ac0 |
should be programmed without any blocking operation. For this reason, this mode
|
|
Packit |
229ac0 |
is enabled when the PCM applications explicitly configure hardware parameter to
|
|
Packit |
229ac0 |
runtime of PCM substream, to prevent disorder of existing applications.
|
|
Packit |
229ac0 |
Additionally, nothing maintains timing for transmission of audio data frame,
|
|
Packit |
229ac0 |
therefore the PCM applications should voluntarily handle any timer to queue
|
|
Packit |
229ac0 |
audio data frame in buffer of the PCM substream for lapse of time. Furthermore,
|
|
Packit |
229ac0 |
instead of driver, the PCM application should call a helper function of ALSA
|
|
Packit |
229ac0 |
PCM core to update a position to head of hardware transmission and to check
|
|
Packit |
229ac0 |
XRUN.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
In
|
|
Packit |
229ac0 |
.I axfer
|
|
Packit |
229ac0 |
, this is called
|
|
Packit |
229ac0 |
.I timer\-based
|
|
Packit |
229ac0 |
scheduling model and available as long as hardware/driver assists
|
|
Packit |
229ac0 |
.I no\-period\-wakeup
|
|
Packit |
229ac0 |
runtime. Users should explicitly set this mode by usage of
|
|
Packit |
229ac0 |
.I \-\-sched\-model
|
|
Packit |
229ac0 |
option with
|
|
Packit |
229ac0 |
.I timer
|
|
Packit |
229ac0 |
value.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
In the scheduling model, PCM applications need to care of available space on
|
|
Packit |
229ac0 |
PCM buffer by lapse of time, typically by yielding CPU and wait for
|
|
Packit |
229ac0 |
rescheduling. For the yielding, timeout is calculated for preferable amount of
|
|
Packit |
229ac0 |
PCM frames to process. This is convenient to a kind of applications, like sound
|
|
Packit |
229ac0 |
servers. when an I/O thread of the server wait for the timeout, the other
|
|
Packit |
229ac0 |
threads can process audio data frames for server clients. Furthermore, with
|
|
Packit |
229ac0 |
usage of rewinding/forwarding, applications can achieve low latency between
|
|
Packit |
229ac0 |
transmission position and handling position even if they uses large size of
|
|
Packit |
229ac0 |
PCM buffers.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.SS Advantages and issues
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
Ideally, timer\-based scheduling model has some advantages than IRQ\-based
|
|
Packit |
229ac0 |
scheduling model. At first, no interrupt context runs for PCM substream. The
|
|
Packit |
229ac0 |
PCM substream is handled in any process context only. No need to care of race
|
|
Packit |
229ac0 |
conditions between IRQ and process contexts. This reduces some concerns for
|
|
Packit |
229ac0 |
some developers of drivers and applications. Secondary, CPU time is not used
|
|
Packit |
229ac0 |
for handlers on the interrupt context. The CPU time can be dedicated for the
|
|
Packit |
229ac0 |
other tasks. This is good in a point of Time Sharing System. Thirdly, hardware
|
|
Packit |
229ac0 |
is not configured to generate interrupts. This is good in a point of reduction
|
|
Packit |
229ac0 |
of overall power consumption possibly.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
In either scheduling model, the hardware should allow drivers to read the
|
|
Packit |
229ac0 |
number of audio data frame transferred between the dedicated memory and the
|
|
Packit |
229ac0 |
device memory for audio serial bus. However, in timer\-based scheduling model,
|
|
Packit |
229ac0 |
fine granularity and accuracy of the value is important. Actually hardware
|
|
Packit |
229ac0 |
performs transmission between dedicated memory and device memory for a small
|
|
Packit |
229ac0 |
batch of audio data frames or bytes. In a view of PCM applications, the
|
|
Packit |
229ac0 |
granularity in current transmission is required to decide correct timeout for
|
|
Packit |
229ac0 |
each I/O operation. As of Linux kernel v4.21, ALSA PCM interface between
|
|
Packit |
229ac0 |
kernel/userspace has no feature to report it.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.SH COMPATIBILITY TO APLAY
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
The
|
|
Packit |
229ac0 |
.B transfer
|
|
Packit |
229ac0 |
subcommand of
|
|
Packit |
229ac0 |
.B axfer
|
|
Packit |
229ac0 |
is designed to keep compatibility to aplay(1). However some options below are
|
|
Packit |
229ac0 |
not compatible due to several technical reasons.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.I \-I, \-\-separate\-channels
|
|
Packit |
229ac0 |
This option is supported just for files to store audio data frames corresponding
|
|
Packit |
229ac0 |
to each channel. In aplay(1) implementation, this option has an additional
|
|
Packit |
229ac0 |
effect to use PCM buffer aligned to non\-interleaved order if a target device
|
|
Packit |
229ac0 |
supports. As of 2018, PCM buffer of non\-interleaved order is hardly used by
|
|
Packit |
229ac0 |
sound devices.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.I \-A, \-\-avail\-min=#
|
|
Packit |
229ac0 |
This option indicates threshold to wake up blocked process in a unit of
|
|
Packit |
229ac0 |
audio data frame. Against aplay(1) implementation, this option has no effect
|
|
Packit |
229ac0 |
with
|
|
Packit |
229ac0 |
.I \-\-mmap
|
|
Packit |
229ac0 |
option as well as
|
|
Packit |
229ac0 |
.I timer
|
|
Packit |
229ac0 |
of
|
|
Packit |
229ac0 |
.I \-\-sched\-model
|
|
Packit |
229ac0 |
option.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.I \-R, \-\-start\-delay=#
|
|
Packit |
229ac0 |
This option indicates threshold to start prepared PCM substream in a unit of
|
|
Packit |
229ac0 |
audio data frame. Against aplay(1) implementation, this option has no effect
|
|
Packit |
229ac0 |
with
|
|
Packit |
229ac0 |
.I \-\-mmap
|
|
Packit |
229ac0 |
option as well as
|
|
Packit |
229ac0 |
.I timer
|
|
Packit |
229ac0 |
of
|
|
Packit |
229ac0 |
.I \-\-sched\-model
|
|
Packit |
229ac0 |
option.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.I \-T, \-\-stop\-delay=#
|
|
Packit |
229ac0 |
This option indicates threshold to stop running PCM substream in a unit of
|
|
Packit |
229ac0 |
audio data frame. Against aplay(1) implementation, this option has no effect
|
|
Packit |
229ac0 |
with
|
|
Packit |
229ac0 |
.I \-\-mmap
|
|
Packit |
229ac0 |
option as well as
|
|
Packit |
229ac0 |
.I timer
|
|
Packit |
229ac0 |
of
|
|
Packit |
229ac0 |
.I \-\-sched\-model
|
|
Packit |
229ac0 |
option.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.I \-\-max\-file\-time=#
|
|
Packit |
229ac0 |
This option is unsupported. In aplay(1) implementation, the option has an
|
|
Packit |
229ac0 |
effect for capture transmission to save files up to the same number of data
|
|
Packit |
229ac0 |
frames as the given value by second unit, or the maximum number of data frames
|
|
Packit |
229ac0 |
supported by used file format. When reaching to the limitation, used file is
|
|
Packit |
229ac0 |
closed, then new file is opened and audio data frames are written. However, this
|
|
Packit |
229ac0 |
option requires extra handling of files and shall increase complexity of main
|
|
Packit |
229ac0 |
loop of axfer.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.I \-\-use\-strftime=FORMAT
|
|
Packit |
229ac0 |
This option is unsupported. In aplay(1) implementation, the option has an effect
|
|
Packit |
229ac0 |
for capture transmission to generate file paths according to given format in
|
|
Packit |
229ac0 |
which some extra formats are available as well as formats supported by
|
|
Packit |
229ac0 |
strftime(3). However, this option requires extra string processing for file
|
|
Packit |
229ac0 |
paths and it\(aqs bothersome if written in C language.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.I \-\-process\-id\-file=FILEPATH
|
|
Packit |
229ac0 |
This option is unsupported. In aplay(1) implementation, the option has an effect
|
|
Packit |
229ac0 |
to create a file for given value and write out process ID to it. This file
|
|
Packit |
229ac0 |
allows users to get process ID and send any POSIX signal to aplay process.
|
|
Packit |
229ac0 |
However, this idea has some troubles for file locking when multiple aplay
|
|
Packit |
229ac0 |
processes run with the same file.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.I \-V, \-\-vumeter=TYPE
|
|
Packit |
229ac0 |
This option is not supported at present. In aplay(1) implementation, this option
|
|
Packit |
229ac0 |
has an effect to occupy stdout with some terminal control characters and display
|
|
Packit |
229ac0 |
vumeter for monaural and stereo channels. However, some problems lay; this
|
|
Packit |
229ac0 |
feature is just for audio data frames with PCM format, this feature brings
|
|
Packit |
229ac0 |
disorder of terminal after aborting, stdout is not available for pipeline.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.I \-i, \-\-interactive
|
|
Packit |
229ac0 |
This option is not supported at present. In aplay(1) implementation, this option
|
|
Packit |
229ac0 |
has an effect to occupy stdin for key input and suspend/resume PCM substream
|
|
Packit |
229ac0 |
according to pushed enter key. However, this feature requires an additional
|
|
Packit |
229ac0 |
input handling in main loop and leave bothersome operation to maintain PCM
|
|
Packit |
229ac0 |
substream.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.I \-m, \-\-chmap=CH1,CH2,...
|
|
Packit |
229ac0 |
ALSA PCM core and control core doesn't support this feature, therefore
|
|
Packit |
229ac0 |
remapping should be done in userspace. This brings overhead to align audio
|
|
Packit |
229ac0 |
data frames, especially for mmap operation. Furthermore, as of alsa-lib v1.1.8,
|
|
Packit |
229ac0 |
some plugins don't support this feature expectedly, thus this option is a lack
|
|
Packit |
229ac0 |
of transparent operation. At present, this option is not supported yet not to
|
|
Packit |
229ac0 |
confuse users.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.I SIGTSTP, SIGCONT
|
|
Packit |
229ac0 |
This performs suspend/resume of PCM substream. In aplay(1) implementation,
|
|
Packit |
229ac0 |
these operations bring XRUN state to the substream, and suspend/resume is done
|
|
Packit |
229ac0 |
in interactive mode in the above. Some developers use the signal for recovery
|
|
Packit |
229ac0 |
test from XRUN. At present, no alternative is supported for the test.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.TP
|
|
Packit |
229ac0 |
.I SIGUSR1
|
|
Packit |
229ac0 |
This is not supported. In aplay(1) implementation, this signal is assigned to a
|
|
Packit |
229ac0 |
handler to close a current file to store audio data frame and open a new file
|
|
Packit |
229ac0 |
to continue processing. However, as well as
|
|
Packit |
229ac0 |
.I \-\-max\-file\-time
|
|
Packit |
229ac0 |
option, this option should increase complexity of main loop of axfer.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.SH DESIGN
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.SS Modular structure
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
This program consists of three modules;
|
|
Packit |
229ac0 |
.I xfer
|
|
Packit |
229ac0 |
,
|
|
Packit |
229ac0 |
.I mapper
|
|
Packit |
229ac0 |
and
|
|
Packit |
229ac0 |
.I container
|
|
Packit |
229ac0 |
\&.
|
|
Packit |
229ac0 |
Each module has an abstraction layer to enable actual implementation.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.nf
|
|
Packit |
229ac0 |
-------- ---------- -------------
|
|
Packit |
229ac0 |
device <-> | xfer | <-> | mapper | <-> | container | <-> file
|
|
Packit |
229ac0 |
-------- ---------- -------------
|
|
Packit |
229ac0 |
libasound single wav
|
|
Packit |
229ac0 |
libffado multiple au
|
|
Packit |
229ac0 |
voc
|
|
Packit |
229ac0 |
raw
|
|
Packit |
229ac0 |
.fi
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
The
|
|
Packit |
229ac0 |
.I xfer
|
|
Packit |
229ac0 |
module performs actual transmission to devices and nodes. The module can have
|
|
Packit |
229ac0 |
several transmission backends. As a default backend,
|
|
Packit |
229ac0 |
.I libasound
|
|
Packit |
229ac0 |
backend is used to perform transmission via alsa\-lib APIs. The module allows
|
|
Packit |
229ac0 |
each backend to parse own command line options.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
The
|
|
Packit |
229ac0 |
.I container
|
|
Packit |
229ac0 |
module performs to read/write audio data frame via descriptor for file/stream
|
|
Packit |
229ac0 |
of multimedia container or raw data. The module automatically detect type of
|
|
Packit |
229ac0 |
multimedia container and parse parameters in its metadata of data header. At
|
|
Packit |
229ac0 |
present, three types of multimedia containers are supported; Microsoft/IBM
|
|
Packit |
229ac0 |
RIFF/Wave (
|
|
Packit |
229ac0 |
.I wav
|
|
Packit |
229ac0 |
), Sparc AU (
|
|
Packit |
229ac0 |
.I au
|
|
Packit |
229ac0 |
) and Creative Technology voice (
|
|
Packit |
229ac0 |
.I voc
|
|
Packit |
229ac0 |
). Additionally, a special container is prepared for raw audio data (
|
|
Packit |
229ac0 |
.I raw
|
|
Packit |
229ac0 |
).
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
The
|
|
Packit |
229ac0 |
.I mapper
|
|
Packit |
229ac0 |
module handles buffer layout and alignment for transmission of audio data frame.
|
|
Packit |
229ac0 |
The module has two implementations;
|
|
Packit |
229ac0 |
.I single
|
|
Packit |
229ac0 |
and
|
|
Packit |
229ac0 |
.I multiple
|
|
Packit |
229ac0 |
\&.
|
|
Packit |
229ac0 |
The
|
|
Packit |
229ac0 |
.I single
|
|
Packit |
229ac0 |
backend uses one container to construct the buffer. The
|
|
Packit |
229ac0 |
.I multiple
|
|
Packit |
229ac0 |
backend uses several containers to construct it.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.SS Care of copying audio data frame
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
Between the
|
|
Packit |
229ac0 |
.I xfer
|
|
Packit |
229ac0 |
module and
|
|
Packit |
229ac0 |
.I mapper
|
|
Packit |
229ac0 |
module, a pointer to buffer including audio data frames is passed. This buffer
|
|
Packit |
229ac0 |
has two shapes for interleaved and non\-interleaved order. For the former, the
|
|
Packit |
229ac0 |
pointer points to one buffer. For the latter, the pointer points to an array in
|
|
Packit |
229ac0 |
which each element points to one buffer. Between the
|
|
Packit |
229ac0 |
.I mapper
|
|
Packit |
229ac0 |
module and
|
|
Packit |
229ac0 |
.I container
|
|
Packit |
229ac0 |
module, a pointer to one buffer is passed because supported media containers
|
|
Packit |
229ac0 |
including raw type store audio data frames in interleaved order.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
In passing audio data frame between the modules, axfer is programmed to avoid
|
|
Packit |
229ac0 |
copying between a buffer to another buffer as much as possible. For example, in
|
|
Packit |
229ac0 |
some scenarios below, no copying occurs between modules.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
- xfer(mmap/interleaved), mapper(single), container(any)
|
|
Packit |
229ac0 |
- xfer(mmap/non\-interleaved), mapper(multiple), containers(any)
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.SS Unit test
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
For each of the
|
|
Packit |
229ac0 |
.I mapper
|
|
Packit |
229ac0 |
and
|
|
Packit |
229ac0 |
.I container
|
|
Packit |
229ac0 |
module, unit test is available. To run the tests, execute below command:
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.nf
|
|
Packit |
229ac0 |
$ make test
|
|
Packit |
229ac0 |
.fi
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
Each test iterates writing to file and reading to the file for many times and it
|
|
Packit |
229ac0 |
takes long time to finish. Please take care of the execution time if running on
|
|
Packit |
229ac0 |
any CI environment.
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.SH SEE ALSO
|
|
Packit |
229ac0 |
\fB
|
|
Packit |
229ac0 |
axfer(1),
|
|
Packit |
229ac0 |
axfer\-list(1),
|
|
Packit |
229ac0 |
alsamixer(1),
|
|
Packit |
229ac0 |
amixer(1)
|
|
Packit |
229ac0 |
\fP
|
|
Packit |
229ac0 |
|
|
Packit |
229ac0 |
.SH AUTHOR
|
|
Packit |
229ac0 |
Takashi Sakamoto <o\-takashi@sakamocchi.jp>
|