1d8b53bffSTakashi Sakamoto=================== 2d8b53bffSTakashi SakamotoTracepoints in ALSA 3d8b53bffSTakashi Sakamoto=================== 4d8b53bffSTakashi Sakamoto 5d8b53bffSTakashi Sakamoto2017/07/02 6d8b53bffSTakashi SakamotoTakasahi Sakamoto 7d8b53bffSTakashi Sakamoto 8d8b53bffSTakashi SakamotoTracepoints in ALSA PCM core 9d8b53bffSTakashi Sakamoto============================ 10d8b53bffSTakashi Sakamoto 11d8b53bffSTakashi SakamotoALSA PCM core registers ``snd_pcm`` subsystem to kernel tracepoint system. 12d8b53bffSTakashi SakamotoThis subsystem includes two categories of tracepoints; for state of PCM buffer 13d8b53bffSTakashi Sakamotoand for processing of PCM hardware parameters. These tracepoints are available 14d8b53bffSTakashi Sakamotowhen corresponding kernel configurations are enabled. When ``CONFIG_SND_DEBUG`` 15d8b53bffSTakashi Sakamotois enabled, the latter tracepoints are available. When additional 16d8b53bffSTakashi Sakamoto``SND_PCM_XRUN_DEBUG`` is enabled too, the former trace points are enabled. 17d8b53bffSTakashi Sakamoto 18d8b53bffSTakashi SakamotoTracepoints for state of PCM buffer 19d8b53bffSTakashi Sakamoto------------------------------------ 20d8b53bffSTakashi Sakamoto 21d8b53bffSTakashi SakamotoThis category includes four tracepoints; ``hwptr``, ``applptr``, ``xrun`` and 22d8b53bffSTakashi Sakamoto``hw_ptr_error``. 23d8b53bffSTakashi Sakamoto 24d8b53bffSTakashi SakamotoTracepoints for processing of PCM hardware parameters 25d8b53bffSTakashi Sakamoto----------------------------------------------------- 26d8b53bffSTakashi Sakamoto 27d8b53bffSTakashi SakamotoThis category includes two tracepoints; ``hw_mask_param`` and 28d8b53bffSTakashi Sakamoto``hw_interval_param``. 29d8b53bffSTakashi Sakamoto 30d8b53bffSTakashi SakamotoIn a design of ALSA PCM core, data transmission is abstracted as PCM substream. 31d8b53bffSTakashi SakamotoApplications manage PCM substream to maintain data transmission for PCM frames. 32d8b53bffSTakashi SakamotoBefore starting the data transmission, applications need to configure PCM 33d8b53bffSTakashi Sakamotosubstream. In this procedure, PCM hardware parameters are decided by 34d8b53bffSTakashi Sakamotointeraction between applications and ALSA PCM core. Once decided, runtime of 35d8b53bffSTakashi Sakamotothe PCM substream keeps the parameters. 36d8b53bffSTakashi Sakamoto 37*9303c9d5SMauro Carvalho ChehabThe parameters are described in struct snd_pcm_hw_params. This 38d8b53bffSTakashi Sakamotostructure includes several types of parameters. Applications set preferable 39d8b53bffSTakashi Sakamotovalue to these parameters, then execute ioctl(2) with SNDRV_PCM_IOCTL_HW_REFINE 40d8b53bffSTakashi Sakamotoor SNDRV_PCM_IOCTL_HW_PARAMS. The former is used just for refining available 41d8b53bffSTakashi Sakamotoset of parameters. The latter is used for an actual decision of the parameters. 42d8b53bffSTakashi Sakamoto 43*9303c9d5SMauro Carvalho ChehabThe struct snd_pcm_hw_params structure has below members: 44d8b53bffSTakashi Sakamoto 45d8b53bffSTakashi Sakamoto``flags`` 46d8b53bffSTakashi Sakamoto Configurable. ALSA PCM core and some drivers handle this flag to select 47d8b53bffSTakashi Sakamoto convenient parameters or change their behaviour. 48d8b53bffSTakashi Sakamoto``masks`` 49d8b53bffSTakashi Sakamoto Configurable. This type of parameter is described in 50*9303c9d5SMauro Carvalho Chehab struct snd_mask and represent mask values. As of PCM protocol 51d8b53bffSTakashi Sakamoto v2.0.13, three types are defined. 52d8b53bffSTakashi Sakamoto 53d8b53bffSTakashi Sakamoto - SNDRV_PCM_HW_PARAM_ACCESS 54d8b53bffSTakashi Sakamoto - SNDRV_PCM_HW_PARAM_FORMAT 55d8b53bffSTakashi Sakamoto - SNDRV_PCM_HW_PARAM_SUBFORMAT 56d8b53bffSTakashi Sakamoto``intervals`` 57d8b53bffSTakashi Sakamoto Configurable. This type of parameter is described in 58*9303c9d5SMauro Carvalho Chehab struct snd_interval and represent values with a range. As of 59d8b53bffSTakashi Sakamoto PCM protocol v2.0.13, twelve types are defined. 60d8b53bffSTakashi Sakamoto 61d8b53bffSTakashi Sakamoto - SNDRV_PCM_HW_PARAM_SAMPLE_BITS 62d8b53bffSTakashi Sakamoto - SNDRV_PCM_HW_PARAM_FRAME_BITS 63d8b53bffSTakashi Sakamoto - SNDRV_PCM_HW_PARAM_CHANNELS 64d8b53bffSTakashi Sakamoto - SNDRV_PCM_HW_PARAM_RATE 65d8b53bffSTakashi Sakamoto - SNDRV_PCM_HW_PARAM_PERIOD_TIME 66d8b53bffSTakashi Sakamoto - SNDRV_PCM_HW_PARAM_PERIOD_SIZE 67d8b53bffSTakashi Sakamoto - SNDRV_PCM_HW_PARAM_PERIOD_BYTES 68d8b53bffSTakashi Sakamoto - SNDRV_PCM_HW_PARAM_PERIODS 69d8b53bffSTakashi Sakamoto - SNDRV_PCM_HW_PARAM_BUFFER_TIME 70d8b53bffSTakashi Sakamoto - SNDRV_PCM_HW_PARAM_BUFFER_SIZE 71d8b53bffSTakashi Sakamoto - SNDRV_PCM_HW_PARAM_BUFFER_BYTES 72d8b53bffSTakashi Sakamoto - SNDRV_PCM_HW_PARAM_TICK_TIME 73d8b53bffSTakashi Sakamoto``rmask`` 74d8b53bffSTakashi Sakamoto Configurable. This is evaluated at ioctl(2) with 75d8b53bffSTakashi Sakamoto SNDRV_PCM_IOCTL_HW_REFINE only. Applications can select which 76d8b53bffSTakashi Sakamoto mask/interval parameter can be changed by ALSA PCM core. For 77d8b53bffSTakashi Sakamoto SNDRV_PCM_IOCTL_HW_PARAMS, this mask is ignored and all of parameters 78d8b53bffSTakashi Sakamoto are going to be changed. 79d8b53bffSTakashi Sakamoto``cmask`` 80d8b53bffSTakashi Sakamoto Read-only. After returning from ioctl(2), buffer in user space for 81*9303c9d5SMauro Carvalho Chehab struct snd_pcm_hw_params includes result of each operation. 82d8b53bffSTakashi Sakamoto This mask represents which mask/interval parameter is actually changed. 83d8b53bffSTakashi Sakamoto``info`` 84d8b53bffSTakashi Sakamoto Read-only. This represents hardware/driver capabilities as bit flags 85d8b53bffSTakashi Sakamoto with SNDRV_PCM_INFO_XXX. Typically, applications execute ioctl(2) with 86d8b53bffSTakashi Sakamoto SNDRV_PCM_IOCTL_HW_REFINE to retrieve this flag, then decide candidates 87d8b53bffSTakashi Sakamoto of parameters and execute ioctl(2) with SNDRV_PCM_IOCTL_HW_PARAMS to 88d8b53bffSTakashi Sakamoto configure PCM substream. 89d8b53bffSTakashi Sakamoto``msbits`` 90d8b53bffSTakashi Sakamoto Read-only. This value represents available bit width in MSB side of 91d8b53bffSTakashi Sakamoto a PCM sample. When a parameter of SNDRV_PCM_HW_PARAM_SAMPLE_BITS was 92d8b53bffSTakashi Sakamoto decided as a fixed number, this value is also calculated according to 93d8b53bffSTakashi Sakamoto it. Else, zero. But this behaviour depends on implementations in driver 94d8b53bffSTakashi Sakamoto side. 95d8b53bffSTakashi Sakamoto``rate_num`` 96d8b53bffSTakashi Sakamoto Read-only. This value represents numerator of sampling rate in fraction 97d8b53bffSTakashi Sakamoto notation. Basically, when a parameter of SNDRV_PCM_HW_PARAM_RATE was 98d8b53bffSTakashi Sakamoto decided as a single value, this value is also calculated according to 99d8b53bffSTakashi Sakamoto it. Else, zero. But this behaviour depends on implementations in driver 100d8b53bffSTakashi Sakamoto side. 101d8b53bffSTakashi Sakamoto``rate_den`` 102d8b53bffSTakashi Sakamoto Read-only. This value represents denominator of sampling rate in 103d8b53bffSTakashi Sakamoto fraction notation. Basically, when a parameter of 104d8b53bffSTakashi Sakamoto SNDRV_PCM_HW_PARAM_RATE was decided as a single value, this value is 105d8b53bffSTakashi Sakamoto also calculated according to it. Else, zero. But this behaviour depends 106d8b53bffSTakashi Sakamoto on implementations in driver side. 107d8b53bffSTakashi Sakamoto``fifo_size`` 108d8b53bffSTakashi Sakamoto Read-only. This value represents the size of FIFO in serial sound 109d8b53bffSTakashi Sakamoto interface of hardware. Basically, each driver can assigns a proper 110d8b53bffSTakashi Sakamoto value to this parameter but some drivers intentionally set zero with 111d8b53bffSTakashi Sakamoto a care of hardware design or data transmission protocol. 112d8b53bffSTakashi Sakamoto 113*9303c9d5SMauro Carvalho ChehabALSA PCM core handles buffer of struct snd_pcm_hw_params when 114d8b53bffSTakashi Sakamotoapplications execute ioctl(2) with SNDRV_PCM_HW_REFINE or SNDRV_PCM_HW_PARAMS. 115d8b53bffSTakashi SakamotoParameters in the buffer are changed according to 116*9303c9d5SMauro Carvalho Chehabstruct snd_pcm_hardware and rules of constraints in the runtime. The 117d8b53bffSTakashi Sakamotostructure describes capabilities of handled hardware. The rules describes 118d8b53bffSTakashi Sakamotodependencies on which a parameter is decided according to several parameters. 119d8b53bffSTakashi SakamotoA rule has a callback function, and drivers can register arbitrary functions 120d8b53bffSTakashi Sakamototo compute the target parameter. ALSA PCM core registers some rules to the 121d8b53bffSTakashi Sakamotoruntime as a default. 122d8b53bffSTakashi Sakamoto 123d8b53bffSTakashi SakamotoEach driver can join in the interaction as long as it prepared for two stuffs 124*9303c9d5SMauro Carvalho Chehabin a callback of struct snd_pcm_ops.open. 125d8b53bffSTakashi Sakamoto 126d8b53bffSTakashi Sakamoto1. In the callback, drivers are expected to change a member of 127*9303c9d5SMauro Carvalho Chehab struct snd_pcm_hardware type in the runtime, according to 128d8b53bffSTakashi Sakamoto capacities of corresponding hardware. 129d8b53bffSTakashi Sakamoto2. In the same callback, drivers are also expected to register additional rules 130d8b53bffSTakashi Sakamoto of constraints into the runtime when several parameters have dependencies 131d8b53bffSTakashi Sakamoto due to hardware design. 132d8b53bffSTakashi Sakamoto 133d8b53bffSTakashi SakamotoThe driver can refers to result of the interaction in a callback of 134*9303c9d5SMauro Carvalho Chehabstruct snd_pcm_ops.hw_params, however it should not change the 135d8b53bffSTakashi Sakamotocontent. 136d8b53bffSTakashi Sakamoto 137d8b53bffSTakashi SakamotoTracepoints in this category are designed to trace changes of the 138d8b53bffSTakashi Sakamotomask/interval parameters. When ALSA PCM core changes them, ``hw_mask_param`` or 139d8b53bffSTakashi Sakamoto``hw_interval_param`` event is probed according to type of the changed parameter. 140d8b53bffSTakashi Sakamoto 141d8b53bffSTakashi SakamotoALSA PCM core also has a pretty print format for each of the tracepoints. Below 142d8b53bffSTakashi Sakamotois an example for ``hw_mask_param``. 143d8b53bffSTakashi Sakamoto 144d8b53bffSTakashi Sakamoto:: 145d8b53bffSTakashi Sakamoto 146d8b53bffSTakashi Sakamoto hw_mask_param: pcmC0D0p 001/023 FORMAT 00000000000000000000001000000044 00000000000000000000001000000044 147d8b53bffSTakashi Sakamoto 148d8b53bffSTakashi Sakamoto 149d8b53bffSTakashi SakamotoBelow is an example for ``hw_interval_param``. 150d8b53bffSTakashi Sakamoto 151d8b53bffSTakashi Sakamoto:: 152d8b53bffSTakashi Sakamoto 153d8b53bffSTakashi Sakamoto hw_interval_param: pcmC0D0p 000/023 BUFFER_SIZE 0 0 [0 4294967295] 0 1 [0 4294967295] 154d8b53bffSTakashi Sakamoto 155d8b53bffSTakashi SakamotoThe first three fields are common. They represent name of ALSA PCM character 156d8b53bffSTakashi Sakamotodevice, rules of constraint and name of the changed parameter, in order. The 157d8b53bffSTakashi Sakamotofield for rules of constraint consists of two sub-fields; index of applied rule 158d8b53bffSTakashi Sakamotoand total number of rules added to the runtime. As an exception, the index 000 159d8b53bffSTakashi Sakamotomeans that the parameter is changed by ALSA PCM core, regardless of the rules. 160d8b53bffSTakashi Sakamoto 161d8b53bffSTakashi SakamotoThe rest of field represent state of the parameter before/after changing. These 162d8b53bffSTakashi Sakamotofields are different according to type of the parameter. For parameters of mask 163d8b53bffSTakashi Sakamototype, the fields represent hexadecimal dump of content of the parameter. For 164d8b53bffSTakashi Sakamotoparameters of interval type, the fields represent values of each member of 165d8b53bffSTakashi Sakamoto``empty``, ``integer``, ``openmin``, ``min``, ``max``, ``openmax`` in 166*9303c9d5SMauro Carvalho Chehabstruct snd_interval in this order. 167d8b53bffSTakashi Sakamoto 168d8b53bffSTakashi SakamotoTracepoints in drivers 169d8b53bffSTakashi Sakamoto====================== 170d8b53bffSTakashi Sakamoto 171d8b53bffSTakashi SakamotoSome drivers have tracepoints for developers' convenience. For them, please 172d8b53bffSTakashi Sakamotorefer to each documentation or implementation. 173