sound/designs/tracepoints.rst

12 This subsystem includes two categories of tracepoints; for state of PCM buffer
13 and for processing of PCM hardware parameters. These tracepoints are available
18 Tracepoints for state of PCM buffer
24 Tracepoints for processing of PCM hardware parameters
30 In a design of ALSA PCM core, data transmission is abstracted as PCM substream.
34 interaction between applications and ALSA PCM core. Once decided, runtime of
38 structure includes several types of parameters. Applications set preferable
41 set of parameters. The latter is used for an actual decision of the parameters.
49         Configurable. This type of parameter is described in
50         struct snd_mask and represent mask values. As of PCM protocol
57         Configurable. This type of parameter is described in
58         struct snd_interval and represent values with a range. As of
77         SNDRV_PCM_IOCTL_HW_PARAMS, this mask is ignored and all of parameters
81         struct snd_pcm_hw_params includes result of each operation.
87         of parameters and execute ioctl(2) with SNDRV_PCM_IOCTL_HW_PARAMS to
90         Read-only. This value represents available bit width in MSB side of
91         a PCM sample. When a parameter of SNDRV_PCM_HW_PARAM_SAMPLE_BITS was
96         Read-only. This value represents numerator of sampling rate in fraction
97         notation. Basically, when a parameter of SNDRV_PCM_HW_PARAM_RATE was
102         Read-only. This value represents denominator of sampling rate in
103         fraction notation. Basically, when a parameter of
108         Read-only. This value represents the size of FIFO in serial sound
109         interface of hardware. Basically, each driver can assigns a proper
111         a care of hardware design or data transmission protocol.
113 ALSA PCM core handles buffer of struct snd_pcm_hw_params when
116 struct snd_pcm_hardware and rules of constraints in the runtime. The
117 structure describes capabilities of handled hardware. The rules describes
124 in a callback of struct snd_pcm_ops.open.
126 1. In the callback, drivers are expected to change a member of
128    capacities of corresponding hardware.
130    of constraints into the runtime when several parameters have dependencies
133 The driver can refers to result of the interaction in a callback of
137 Tracepoints in this category are designed to trace changes of the
139 ``hw_interval_param`` event is probed according to type of the changed parameter.
141 ALSA PCM core also has a pretty print format for each of the tracepoints. Below
155 The first three fields are common. They represent name of ALSA PCM character
156 device, rules of constraint and name of the changed parameter, in order. The
157 field for rules of constraint consists of two sub-fields; index of applied rule
158 and total number of rules added to the runtime. As an exception, the index 000
159 means that the parameter is changed by ALSA PCM core, regardless of the rules.
161 The rest of field represent state of the parameter before/after changing. These
162 fields are different according to type of the parameter. For parameters of mask
163 type, the fields represent hexadecimal dump of content of the parameter. For
164 parameters of interval type, the fields represent values of each member of