1 ===================
2 Tracepoints in ALSA
3 ===================
4
5 2017/07/02
6 Takasahi Sakamoto
7
8 Tracepoints in ALSA PCM core
9 ============================
10
11 ALSA PCM core registers ``snd_pcm`` subsystem
12 This subsystem includes two categories of trac
13 and for processing of PCM hardware parameters.
14 when corresponding kernel configurations are e
15 is enabled, the latter tracepoints are availab
16 ``SND_PCM_XRUN_DEBUG`` is enabled too, the for
17
18 Tracepoints for state of PCM buffer
19 ------------------------------------
20
21 This category includes four tracepoints; ``hwp
22 ``hw_ptr_error``.
23
24 Tracepoints for processing of PCM hardware par
25 ----------------------------------------------
26
27 This category includes two tracepoints; ``hw_m
28 ``hw_interval_param``.
29
30 In a design of ALSA PCM core, data transmissio
31 Applications manage PCM substream to maintain
32 Before starting the data transmission, applica
33 substream. In this procedure, PCM hardware par
34 interaction between applications and ALSA PCM
35 the PCM substream keeps the parameters.
36
37 The parameters are described in struct snd_pcm
38 structure includes several types of parameters
39 value to these parameters, then execute ioctl(
40 or SNDRV_PCM_IOCTL_HW_PARAMS. The former is us
41 set of parameters. The latter is used for an a
42
43 The struct snd_pcm_hw_params structure has bel
44
45 ``flags``
46 Configurable. ALSA PCM core and some d
47 convenient parameters or change their
48 ``masks``
49 Configurable. This type of parameter i
50 struct snd_mask and represent mask val
51 v2.0.13, three types are defined.
52
53 - SNDRV_PCM_HW_PARAM_ACCESS
54 - SNDRV_PCM_HW_PARAM_FORMAT
55 - SNDRV_PCM_HW_PARAM_SUBFORMAT
56 ``intervals``
57 Configurable. This type of parameter i
58 struct snd_interval and represent valu
59 PCM protocol v2.0.13, twelve types are
60
61 - SNDRV_PCM_HW_PARAM_SAMPLE_BITS
62 - SNDRV_PCM_HW_PARAM_FRAME_BITS
63 - SNDRV_PCM_HW_PARAM_CHANNELS
64 - SNDRV_PCM_HW_PARAM_RATE
65 - SNDRV_PCM_HW_PARAM_PERIOD_TIME
66 - SNDRV_PCM_HW_PARAM_PERIOD_SIZE
67 - SNDRV_PCM_HW_PARAM_PERIOD_BYTES
68 - SNDRV_PCM_HW_PARAM_PERIODS
69 - SNDRV_PCM_HW_PARAM_BUFFER_TIME
70 - SNDRV_PCM_HW_PARAM_BUFFER_SIZE
71 - SNDRV_PCM_HW_PARAM_BUFFER_BYTES
72 - SNDRV_PCM_HW_PARAM_TICK_TIME
73 ``rmask``
74 Configurable. This is evaluated at ioc
75 SNDRV_PCM_IOCTL_HW_REFINE only. Applic
76 mask/interval parameter can be changed
77 SNDRV_PCM_IOCTL_HW_PARAMS, this mask i
78 are going to be changed.
79 ``cmask``
80 Read-only. After returning from ioctl(
81 struct snd_pcm_hw_params includes resu
82 This mask represents which mask/interv
83 ``info``
84 Read-only. This represents hardware/dr
85 with SNDRV_PCM_INFO_XXX. Typically, ap
86 SNDRV_PCM_IOCTL_HW_REFINE to retrieve
87 of parameters and execute ioctl(2) wit
88 configure PCM substream.
89 ``msbits``
90 Read-only. This value represents avail
91 a PCM sample. When a parameter of SNDR
92 decided as a fixed number, this value
93 it. Else, zero. But this behaviour dep
94 side.
95 ``rate_num``
96 Read-only. This value represents numer
97 notation. Basically, when a parameter
98 decided as a single value, this value
99 it. Else, zero. But this behaviour dep
100 side.
101 ``rate_den``
102 Read-only. This value represents denom
103 fraction notation. Basically, when a p
104 SNDRV_PCM_HW_PARAM_RATE was decided as
105 also calculated according to it. Else,
106 on implementations in driver side.
107 ``fifo_size``
108 Read-only. This value represents the s
109 interface of hardware. Basically, each
110 value to this parameter but some drive
111 a care of hardware design or data tran
112
113 ALSA PCM core handles buffer of struct snd_pcm
114 applications execute ioctl(2) with SNDRV_PCM_H
115 Parameters in the buffer are changed according
116 struct snd_pcm_hardware and rules of constrain
117 structure describes capabilities of handled ha
118 dependencies on which a parameter is decided a
119 A rule has a callback function, and drivers ca
120 to compute the target parameter. ALSA PCM core
121 runtime as a default.
122
123 Each driver can join in the interaction as lon
124 in a callback of struct snd_pcm_ops.open.
125
126 1. In the callback, drivers are expected to ch
127 struct snd_pcm_hardware type in the runtime
128 capacities of corresponding hardware.
129 2. In the same callback, drivers are also expe
130 of constraints into the runtime when severa
131 due to hardware design.
132
133 The driver can refers to result of the interac
134 struct snd_pcm_ops.hw_params, however it shoul
135 content.
136
137 Tracepoints in this category are designed to t
138 mask/interval parameters. When ALSA PCM core c
139 ``hw_interval_param`` event is probed accordin
140
141 ALSA PCM core also has a pretty print format f
142 is an example for ``hw_mask_param``.
143
144 ::
145
146 hw_mask_param: pcmC0D0p 001/023 FORMAT 000
147
148
149 Below is an example for ``hw_interval_param``.
150
151 ::
152
153 hw_interval_param: pcmC0D0p 000/023 BUFFER
154
155 The first three fields are common. They repres
156 device, rules of constraint and name of the ch
157 field for rules of constraint consists of two
158 and total number of rules added to the runtime
159 means that the parameter is changed by ALSA PC
160
161 The rest of field represent state of the param
162 fields are different according to type of the
163 type, the fields represent hexadecimal dump of
164 parameters of interval type, the fields repres
165 ``empty``, ``integer``, ``openmin``, ``min``,
166 struct snd_interval in this order.
167
168 Tracepoints in drivers
169 ======================
170
171 Some drivers have tracepoints for developers'
172 refer to each documentation or implementation.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.