ALSA의 Tracepoint

ALSA PCM core tracepoint와 활성화 조건

이 문서는 2017년 7월 2일 Takasahi Sakamoto가 작성한 ALSA tracepoint 설명입니다. `Documentation/sound/designs/tracepoints.rst`의 PCM core tracepoint를 buffer 상태와 PCM hardware parameter 처리라는 두 범주로 나눕니다.

ALSA PCM core는 kernel tracepoint system에 `snd_pcm` subsystem을 등록합니다. PCM hardware parameter 처리 tracepoint는 `CONFIG_SND_DEBUG`를 켰을 때 사용할 수 있습니다. PCM buffer 상태 tracepoint는 여기에 `SND_PCM_XRUN_DEBUG`까지 추가로 켜야 사용할 수 있습니다.

PCM buffer 상태 범주에는 `hwptr`, `applptr`, `xrun`, `hw_ptr_error` 네 event가 있습니다. PCM hardware parameter 처리 범주에는 `hw_mask_param`, `hw_interval_param` 두 event가 있습니다.

===================
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``.

PCM hardware parameter 협상

ALSA PCM core 설계에서 data 전송은 PCM substream으로 추상화됩니다. Application은 PCM frame 전송을 유지하기 위해 substream을 관리하며, 전송을 시작하기 전에 substream을 구성해야 합니다. 이 과정에서 application과 ALSA PCM core가 상호작용해 hardware parameter를 결정하고, 결정된 값은 substream runtime에 보관됩니다.

Parameter는 `struct snd_pcm_hw_params`에 표현됩니다. Application은 선호 값을 넣은 뒤 `SNDRV_PCM_IOCTL_HW_REFINE` 또는 `SNDRV_PCM_IOCTL_HW_PARAMS`로 `ioctl(2)`를 실행합니다. 전자는 사용 가능한 parameter 집합을 좁히기만 하고, 후자는 parameter를 실제로 확정합니다.

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

struct snd_pcm_hw_params 필드

`flags`는 구성 가능한 field입니다. ALSA PCM core와 일부 driver는 편리한 parameter를 고르거나 동작을 바꾸는 데 이 flag를 사용합니다.

`masks`도 구성 가능합니다. 각 parameter는 `struct snd_mask`로 표현되며 PCM protocol v2.0.13에는 access, format, subformat 세 종류가 정의되어 있습니다.

`intervals` 역시 구성 가능하며 `struct snd_interval`의 범위 값으로 표현됩니다. PCM protocol v2.0.13에는 다음 12종이 정의되어 있습니다.

`rmask`는 `SNDRV_PCM_IOCTL_HW_REFINE`에만 평가되는 구성 가능 mask입니다. Application은 ALSA PCM core가 바꿀 수 있는 mask/interval parameter를 선택할 수 있습니다. `SNDRV_PCM_IOCTL_HW_PARAMS`에서는 이 mask를 무시하고 모든 parameter를 변경 대상으로 삼습니다.

`cmask`는 읽기 전용입니다. `ioctl(2)`가 반환된 뒤 userspace의 `struct snd_pcm_hw_params` buffer에는 연산 결과가 들어 있으며, 이 mask는 실제로 변경된 mask/interval parameter를 나타냅니다.

`info`는 읽기 전용이며 `SNDRV_PCM_INFO_XXX` bit flag로 hardware/driver capability를 나타냅니다. 일반적으로 application은 `SNDRV_PCM_IOCTL_HW_REFINE`으로 이 flag를 가져온 뒤 parameter 후보를 정하고, `SNDRV_PCM_IOCTL_HW_PARAMS`로 PCM substream을 구성합니다.

`msbits`는 PCM sample의 MSB 쪽에서 사용할 수 있는 bit width를 나타내는 읽기 전용 값입니다. `SNDRV_PCM_HW_PARAM_SAMPLE_BITS`가 하나의 고정값으로 정해지면 그에 따라 계산되고, 그렇지 않으면 0입니다. 세부 동작은 driver 구현에 따라 달라집니다.

`rate_num`과 `rate_den`은 sampling rate를 분수로 나타내는 분자와 분모입니다. 일반적으로 `SNDRV_PCM_HW_PARAM_RATE`가 단일 값으로 정해지면 함께 계산되고, 그렇지 않으면 0입니다. 이 동작도 driver 구현에 따라 달라집니다.

`fifo_size`는 hardware serial sound interface의 FIFO 크기를 나타내는 읽기 전용 값입니다. Driver가 적절한 값을 지정할 수 있지만, hardware 설계나 data 전송 protocol을 고려해 일부 driver는 의도적으로 0을 설정합니다.

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

Runtime constraint와 driver 참여

Application이 `SNDRV_PCM_HW_REFINE` 또는 `SNDRV_PCM_HW_PARAMS`로 `ioctl(2)`를 실행하면 ALSA PCM core가 `struct snd_pcm_hw_params` buffer를 처리합니다. Buffer의 parameter는 `struct snd_pcm_hardware`와 runtime의 constraint rule에 따라 바뀝니다.

`struct snd_pcm_hardware`는 대상 hardware의 capability를 설명합니다. Constraint rule은 여러 parameter 사이의 의존 관계를 설명하며 target parameter를 계산하는 callback을 가집니다. Driver는 임의의 callback을 등록할 수 있고 ALSA PCM core도 기본 rule 몇 가지를 runtime에 등록합니다.

Driver가 이 상호작용에 참여하려면 `struct snd_pcm_ops.open` callback에서 두 가지를 준비해야 합니다. 첫째, 해당 hardware capability에 맞춰 runtime의 `struct snd_pcm_hardware` member를 변경합니다. 둘째, hardware 설계 때문에 parameter 사이에 의존성이 있다면 추가 constraint rule을 runtime에 등록합니다.

Driver는 `struct snd_pcm_ops.hw_params` callback에서 협상 결과를 참조할 수 있지만 그 내용을 변경해서는 안 됩니다.

이 범주의 tracepoint는 mask/interval parameter의 변경을 추적합니다. ALSA PCM core가 parameter를 바꾸면 변경된 parameter type에 따라 `hw_mask_param` 또는 `hw_interval_param` event가 probe됩니다.

ALSA PCM core handles buffer of 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
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 struct snd_pcm_ops.open.

1. In the callback, drivers are expected to change a member of
   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
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.

Trace 출력 형식과 필드 해석

ALSA PCM core는 두 tracepoint 각각에 읽기 쉬운 출력 형식을 제공합니다. `hw_mask_param`의 예는 다음과 같습니다.

hw_mask_param: pcmC0D0p 001/023 FORMAT 00000000000000000000001000000044 00000000000000000000001000000044

`hw_interval_param`의 예는 다음과 같습니다.

hw_interval_param: pcmC0D0p 000/023 BUFFER_SIZE 0 0 [0 4294967295] 0 1 [0 4294967295]

첫 세 field는 공통입니다. 순서대로 ALSA PCM character device 이름, constraint rule 정보, 변경된 parameter 이름을 나타냅니다. Rule field는 적용된 rule index와 runtime에 추가된 전체 rule 수의 두 하위 field로 구성됩니다. 예외적으로 index `000`은 rule과 무관하게 ALSA PCM core가 parameter를 변경했음을 뜻합니다.

나머지 field는 변경 전과 변경 후의 parameter 상태입니다. Mask type은 parameter 내용의 16진수 dump를 표시합니다. Interval type은 `struct snd_interval`의 `empty`, `integer`, `openmin`, `min`, `max`, `openmax` member 값을 이 순서로 표시합니다.

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
struct snd_interval in this order.

Driver별 tracepoint

일부 ALSA driver는 개발 편의를 위한 자체 tracepoint를 제공합니다. 구체적인 event와 출력 형식은 각 driver 문서 또는 구현을 확인해야 합니다.

Tracepoints in drivers
======================

Some drivers have tracepoints for developers' convenience. For them, please
refer to each documentation or implementation.