mirror of https://gitee.com/openkylin/linux.git
ALSA: pcm: add a documentation for tracepoints
In PCM interface/protocol for userspace, parameters of runtime for PCM substream is decided by an interaction between applications and ALSA PCM core. In former commits, some tracepoints were added to probe a part of the interaction. This commit adds a documentation about the interaction and the tracepoints. Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp> Signed-off-by: Takashi Iwai <tiwai@suse.de>
This commit is contained in:
Takashi Sakamoto
Takashi Iwai
parent
7720113516
commit
d8b53bff0a
|
|
@ -9,6 +9,7 @@ Designs and Implementations
|
||||||
compress-offload
|
compress-offload
|
||||||
timestamping
|
timestamping
|
||||||
jack-controls
|
jack-controls
|
||||||
|
tracepoints
|
||||||
procfile
|
procfile
|
||||||
powersave
|
powersave
|
||||||
oss-emulation
|
oss-emulation
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,172 @@
|
||||||
|
===================
|
||||||
|
Tracepoints in ALSA
|
||||||
|
===================
|
||||||
|
|
||||||
|
2017/07/02
|
||||||
|
Takasahi Sakamoto
|
||||||
|
|
||||||
|
Tracepoints in ALSA PCM core
|
||||||
|
============================
|
||||||
|
|
||||||
|
ALSA PCM core registers ``snd_pcm`` subsystem to kernel tracepoint system.
|
||||||
|
This subsystem includes two categories of tracepoints; for state of PCM buffer
|
||||||
|
and for processing of PCM hardware parameters. These tracepoints are available
|
||||||
|
when corresponding kernel configurations are enabled. When ``CONFIG_SND_DEBUG``
|
||||||
|
is enabled, the latter tracepoints are available. When additional
|
||||||
|
``SND_PCM_XRUN_DEBUG`` is enabled too, the former trace points are enabled.
|
||||||
|
|
||||||
|
Tracepoints for state of PCM buffer
|
||||||
|
------------------------------------
|
||||||
|
|
||||||
|
This category includes four tracepoints; ``hwptr``, ``applptr``, ``xrun`` and
|
||||||
|
``hw_ptr_error``.
|
||||||
|
|
||||||
|
Tracepoints for processing of PCM hardware parameters
|
||||||
|
-----------------------------------------------------
|
||||||
|
|
||||||
|
This category includes two tracepoints; ``hw_mask_param`` and
|
||||||
|
``hw_interval_param``.
|
||||||
|
|
||||||
|
In a design of ALSA PCM core, data transmission is abstracted as PCM substream.
|
||||||
|
Applications manage PCM substream to maintain data transmission for PCM frames.
|
||||||
|
Before starting the data transmission, applications need to configure PCM
|
||||||
|
substream. In this procedure, PCM hardware parameters are decided by
|
||||||
|
interaction between applications and ALSA PCM core. Once decided, runtime of
|
||||||
|
the PCM substream keeps the parameters.
|
||||||
|
|
||||||
|
The parameters are described in :c:type:`struct snd_pcm_hw_params`. This
|
||||||
|
structure includes several types of parameters. Applications set preferable
|
||||||
|
value to these parameters, then execute ioctl(2) with SNDRV_PCM_IOCTL_HW_REFINE
|
||||||
|
or SNDRV_PCM_IOCTL_HW_PARAMS. The former is used just for refining available
|
||||||
|
set of parameters. The latter is used for an actual decision of the parameters.
|
||||||
|
|
||||||
|
The :c:type:`struct snd_pcm_hw_params` structure has below members:
|
||||||
|
|
||||||
|
``flags``
|
||||||
|
Configurable. ALSA PCM core and some drivers handle this flag to select
|
||||||
|
convenient parameters or change their behaviour.
|
||||||
|
``masks``
|
||||||
|
Configurable. This type of parameter is described in
|
||||||
|
:c:type:`struct snd_mask` and represent mask values. As of PCM protocol
|
||||||
|
v2.0.13, three types are defined.
|
||||||
|
|
||||||
|
- SNDRV_PCM_HW_PARAM_ACCESS
|
||||||
|
- SNDRV_PCM_HW_PARAM_FORMAT
|
||||||
|
- SNDRV_PCM_HW_PARAM_SUBFORMAT
|
||||||
|
``intervals``
|
||||||
|
Configurable. This type of parameter is described in
|
||||||
|
:c:type:`struct snd_interval` and represent values with a range. As of
|
||||||
|
PCM protocol v2.0.13, twelve types are defined.
|
||||||
|
|
||||||
|
- SNDRV_PCM_HW_PARAM_SAMPLE_BITS
|
||||||
|
- SNDRV_PCM_HW_PARAM_FRAME_BITS
|
||||||
|
- SNDRV_PCM_HW_PARAM_CHANNELS
|
||||||
|
- SNDRV_PCM_HW_PARAM_RATE
|
||||||
|
- SNDRV_PCM_HW_PARAM_PERIOD_TIME
|
||||||
|
- SNDRV_PCM_HW_PARAM_PERIOD_SIZE
|
||||||
|
- SNDRV_PCM_HW_PARAM_PERIOD_BYTES
|
||||||
|
- SNDRV_PCM_HW_PARAM_PERIODS
|
||||||
|
- SNDRV_PCM_HW_PARAM_BUFFER_TIME
|
||||||
|
- SNDRV_PCM_HW_PARAM_BUFFER_SIZE
|
||||||
|
- SNDRV_PCM_HW_PARAM_BUFFER_BYTES
|
||||||
|
- SNDRV_PCM_HW_PARAM_TICK_TIME
|
||||||
|
``rmask``
|
||||||
|
Configurable. This is evaluated at ioctl(2) with
|
||||||
|
SNDRV_PCM_IOCTL_HW_REFINE only. Applications can select which
|
||||||
|
mask/interval parameter can be changed by ALSA PCM core. For
|
||||||
|
SNDRV_PCM_IOCTL_HW_PARAMS, this mask is ignored and all of parameters
|
||||||
|
are going to be changed.
|
||||||
|
``cmask``
|
||||||
|
Read-only. After returning from ioctl(2), buffer in user space for
|
||||||
|
:c:type:`struct snd_pcm_hw_params` includes result of each operation.
|
||||||
|
This mask represents which mask/interval parameter is actually changed.
|
||||||
|
``info``
|
||||||
|
Read-only. This represents hardware/driver capabilities as bit flags
|
||||||
|
with SNDRV_PCM_INFO_XXX. Typically, applications execute ioctl(2) with
|
||||||
|
SNDRV_PCM_IOCTL_HW_REFINE to retrieve this flag, then decide candidates
|
||||||
|
of parameters and execute ioctl(2) with SNDRV_PCM_IOCTL_HW_PARAMS to
|
||||||
|
configure PCM substream.
|
||||||
|
``msbits``
|
||||||
|
Read-only. This value represents available bit width in MSB side of
|
||||||
|
a PCM sample. When a parameter of SNDRV_PCM_HW_PARAM_SAMPLE_BITS was
|
||||||
|
decided as a fixed number, this value is also calculated according to
|
||||||
|
it. Else, zero. But this behaviour depends on implementations in driver
|
||||||
|
side.
|
||||||
|
``rate_num``
|
||||||
|
Read-only. This value represents numerator of sampling rate in fraction
|
||||||
|
notation. Basically, when a parameter of SNDRV_PCM_HW_PARAM_RATE was
|
||||||
|
decided as a single value, this value is also calculated according to
|
||||||
|
it. Else, zero. But this behaviour depends on implementations in driver
|
||||||
|
side.
|
||||||
|
``rate_den``
|
||||||
|
Read-only. This value represents denominator of sampling rate in
|
||||||
|
fraction notation. Basically, when a parameter of
|
||||||
|
SNDRV_PCM_HW_PARAM_RATE was decided as a single value, this value is
|
||||||
|
also calculated according to it. Else, zero. But this behaviour depends
|
||||||
|
on implementations in driver side.
|
||||||
|
``fifo_size``
|
||||||
|
Read-only. This value represents the size of FIFO in serial sound
|
||||||
|
interface of hardware. Basically, each driver can assigns a proper
|
||||||
|
value to this parameter but some drivers intentionally set zero with
|
||||||
|
a care of hardware design or data transmission protocol.
|
||||||
|
|
||||||
|
ALSA PCM core handles buffer of :c:type:`struct snd_pcm_hw_params` when
|
||||||
|
applications execute ioctl(2) with SNDRV_PCM_HW_REFINE or SNDRV_PCM_HW_PARAMS.
|
||||||
|
Parameters in the buffer are changed according to
|
||||||
|
:c:type:`struct snd_pcm_hardware` and rules of constraints in the runtime. The
|
||||||
|
structure describes capabilities of handled hardware. The rules describes
|
||||||
|
dependencies on which a parameter is decided according to several parameters.
|
||||||
|
A rule has a callback function, and drivers can register arbitrary functions
|
||||||
|
to compute the target parameter. ALSA PCM core registers some rules to the
|
||||||
|
runtime as a default.
|
||||||
|
|
||||||
|
Each driver can join in the interaction as long as it prepared for two stuffs
|
||||||
|
in a callback of :c:type:`struct snd_pcm_ops.open`.
|
||||||
|
|
||||||
|
1. In the callback, drivers are expected to change a member of
|
||||||
|
:c:type:`struct snd_pcm_hardware` type in the runtime, according to
|
||||||
|
capacities of corresponding hardware.
|
||||||
|
2. In the same callback, drivers are also expected to register additional rules
|
||||||
|
of constraints into the runtime when several parameters have dependencies
|
||||||
|
due to hardware design.
|
||||||
|
|
||||||
|
The driver can refers to result of the interaction in a callback of
|
||||||
|
:c:type:`struct snd_pcm_ops.hw_params`, however it should not change the
|
||||||
|
content.
|
||||||
|
|
||||||
|
Tracepoints in this category are designed to trace changes of the
|
||||||
|
mask/interval parameters. When ALSA PCM core changes them, ``hw_mask_param`` or
|
||||||
|
``hw_interval_param`` event is probed according to type of the changed parameter.
|
||||||
|
|
||||||
|
ALSA PCM core also has a pretty print format for each of the tracepoints. Below
|
||||||
|
is an example for ``hw_mask_param``.
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
hw_mask_param: pcmC0D0p 001/023 FORMAT 00000000000000000000001000000044 00000000000000000000001000000044
|
||||||
|
|
||||||
|
|
||||||
|
Below is an example for ``hw_interval_param``.
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
hw_interval_param: pcmC0D0p 000/023 BUFFER_SIZE 0 0 [0 4294967295] 0 1 [0 4294967295]
|
||||||
|
|
||||||
|
The first three fields are common. They represent name of ALSA PCM character
|
||||||
|
device, rules of constraint and name of the changed parameter, in order. The
|
||||||
|
field for rules of constraint consists of two sub-fields; index of applied rule
|
||||||
|
and total number of rules added to the runtime. As an exception, the index 000
|
||||||
|
means that the parameter is changed by ALSA PCM core, regardless of the rules.
|
||||||
|
|
||||||
|
The rest of field represent state of the parameter before/after changing. These
|
||||||
|
fields are different according to type of the parameter. For parameters of mask
|
||||||
|
type, the fields represent hexadecimal dump of content of the parameter. For
|
||||||
|
parameters of interval type, the fields represent values of each member of
|
||||||
|
``empty``, ``integer``, ``openmin``, ``min``, ``max``, ``openmax`` in
|
||||||
|
:c:type:`struct snd_interval` in this order.
|
||||||
|
|
||||||
|
Tracepoints in drivers
|
||||||
|
======================
|
||||||
|
|
||||||
|
Some drivers have tracepoints for developers' convenience. For them, please
|
||||||
|
refer to each documentation or implementation.
|
||||||
Loading…
Reference in New Issue