173 lines · plain
1===================2Tracepoints in ALSA3===================4 52017/07/026Takasahi Sakamoto7 8Tracepoints in ALSA PCM core9============================10 11ALSA PCM core registers ``snd_pcm`` subsystem to kernel tracepoint system.12This subsystem includes two categories of tracepoints; for state of PCM buffer13and for processing of PCM hardware parameters. These tracepoints are available14when corresponding kernel configurations are enabled. When ``CONFIG_SND_DEBUG``15is enabled, the latter tracepoints are available. When additional16``SND_PCM_XRUN_DEBUG`` is enabled too, the former trace points are enabled.17 18Tracepoints for state of PCM buffer19------------------------------------20 21This category includes four tracepoints; ``hwptr``, ``applptr``, ``xrun`` and22``hw_ptr_error``.23 24Tracepoints for processing of PCM hardware parameters25-----------------------------------------------------26 27This category includes two tracepoints; ``hw_mask_param`` and28``hw_interval_param``.29 30In a design of ALSA PCM core, data transmission is abstracted as PCM substream.31Applications manage PCM substream to maintain data transmission for PCM frames.32Before starting the data transmission, applications need to configure PCM33substream. In this procedure, PCM hardware parameters are decided by34interaction between applications and ALSA PCM core. Once decided, runtime of35the PCM substream keeps the parameters.36 37The parameters are described in struct snd_pcm_hw_params. This38structure includes several types of parameters. Applications set preferable39value to these parameters, then execute ioctl(2) with SNDRV_PCM_IOCTL_HW_REFINE40or SNDRV_PCM_IOCTL_HW_PARAMS. The former is used just for refining available41set of parameters. The latter is used for an actual decision of the parameters.42 43The struct snd_pcm_hw_params structure has below members:44 45``flags``46 Configurable. ALSA PCM core and some drivers handle this flag to select47 convenient parameters or change their behaviour.48``masks``49 Configurable. This type of parameter is described in50 struct snd_mask and represent mask values. As of PCM protocol51 v2.0.13, three types are defined.52 53 - SNDRV_PCM_HW_PARAM_ACCESS54 - SNDRV_PCM_HW_PARAM_FORMAT55 - SNDRV_PCM_HW_PARAM_SUBFORMAT56``intervals``57 Configurable. This type of parameter is described in58 struct snd_interval and represent values with a range. As of59 PCM protocol v2.0.13, twelve types are defined.60 61 - SNDRV_PCM_HW_PARAM_SAMPLE_BITS62 - SNDRV_PCM_HW_PARAM_FRAME_BITS63 - SNDRV_PCM_HW_PARAM_CHANNELS64 - SNDRV_PCM_HW_PARAM_RATE65 - SNDRV_PCM_HW_PARAM_PERIOD_TIME66 - SNDRV_PCM_HW_PARAM_PERIOD_SIZE67 - SNDRV_PCM_HW_PARAM_PERIOD_BYTES68 - SNDRV_PCM_HW_PARAM_PERIODS69 - SNDRV_PCM_HW_PARAM_BUFFER_TIME70 - SNDRV_PCM_HW_PARAM_BUFFER_SIZE71 - SNDRV_PCM_HW_PARAM_BUFFER_BYTES72 - SNDRV_PCM_HW_PARAM_TICK_TIME73``rmask``74 Configurable. This is evaluated at ioctl(2) with75 SNDRV_PCM_IOCTL_HW_REFINE only. Applications can select which76 mask/interval parameter can be changed by ALSA PCM core. For77 SNDRV_PCM_IOCTL_HW_PARAMS, this mask is ignored and all of parameters78 are going to be changed.79``cmask``80 Read-only. After returning from ioctl(2), buffer in user space for81 struct snd_pcm_hw_params includes result of each operation.82 This mask represents which mask/interval parameter is actually changed.83``info``84 Read-only. This represents hardware/driver capabilities as bit flags85 with SNDRV_PCM_INFO_XXX. Typically, applications execute ioctl(2) with86 SNDRV_PCM_IOCTL_HW_REFINE to retrieve this flag, then decide candidates87 of parameters and execute ioctl(2) with SNDRV_PCM_IOCTL_HW_PARAMS to88 configure PCM substream.89``msbits``90 Read-only. This value represents available bit width in MSB side of91 a PCM sample. When a parameter of SNDRV_PCM_HW_PARAM_SAMPLE_BITS was92 decided as a fixed number, this value is also calculated according to93 it. Else, zero. But this behaviour depends on implementations in driver94 side.95``rate_num``96 Read-only. This value represents numerator of sampling rate in fraction97 notation. Basically, when a parameter of SNDRV_PCM_HW_PARAM_RATE was98 decided as a single value, this value is also calculated according to99 it. Else, zero. But this behaviour depends on implementations in driver100 side.101``rate_den``102 Read-only. This value represents denominator of sampling rate in103 fraction notation. Basically, when a parameter of104 SNDRV_PCM_HW_PARAM_RATE was decided as a single value, this value is105 also calculated according to it. Else, zero. But this behaviour depends106 on implementations in driver side.107``fifo_size``108 Read-only. This value represents the size of FIFO in serial sound109 interface of hardware. Basically, each driver can assigns a proper110 value to this parameter but some drivers intentionally set zero with111 a care of hardware design or data transmission protocol.112 113ALSA PCM core handles buffer of struct snd_pcm_hw_params when114applications execute ioctl(2) with SNDRV_PCM_HW_REFINE or SNDRV_PCM_HW_PARAMS.115Parameters in the buffer are changed according to116struct snd_pcm_hardware and rules of constraints in the runtime. The117structure describes capabilities of handled hardware. The rules describes118dependencies on which a parameter is decided according to several parameters.119A rule has a callback function, and drivers can register arbitrary functions120to compute the target parameter. ALSA PCM core registers some rules to the121runtime as a default.122 123Each driver can join in the interaction as long as it prepared for two stuffs124in a callback of struct snd_pcm_ops.open.125 1261. In the callback, drivers are expected to change a member of127 struct snd_pcm_hardware type in the runtime, according to128 capacities of corresponding hardware.1292. In the same callback, drivers are also expected to register additional rules130 of constraints into the runtime when several parameters have dependencies131 due to hardware design.132 133The driver can refers to result of the interaction in a callback of134struct snd_pcm_ops.hw_params, however it should not change the135content.136 137Tracepoints in this category are designed to trace changes of the138mask/interval parameters. When ALSA PCM core changes them, ``hw_mask_param`` or139``hw_interval_param`` event is probed according to type of the changed parameter.140 141ALSA PCM core also has a pretty print format for each of the tracepoints. Below142is an example for ``hw_mask_param``.143 144::145 146 hw_mask_param: pcmC0D0p 001/023 FORMAT 00000000000000000000001000000044 00000000000000000000001000000044147 148 149Below is an example for ``hw_interval_param``.150 151::152 153 hw_interval_param: pcmC0D0p 000/023 BUFFER_SIZE 0 0 [0 4294967295] 0 1 [0 4294967295]154 155The first three fields are common. They represent name of ALSA PCM character156device, rules of constraint and name of the changed parameter, in order. The157field for rules of constraint consists of two sub-fields; index of applied rule158and total number of rules added to the runtime. As an exception, the index 000159means that the parameter is changed by ALSA PCM core, regardless of the rules.160 161The rest of field represent state of the parameter before/after changing. These162fields are different according to type of the parameter. For parameters of mask163type, the fields represent hexadecimal dump of content of the parameter. For164parameters of interval type, the fields represent values of each member of165``empty``, ``integer``, ``openmin``, ``min``, ``max``, ``openmax`` in166struct snd_interval in this order.167 168Tracepoints in drivers169======================170 171Some drivers have tracepoints for developers' convenience. For them, please172refer to each documentation or implementation.173