<!DOCTYPE html>
<html lang="en" data-content_root="../../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Tracepoints in ALSA — The Linux Kernel documentation</title>
<link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="../../_static/alabaster.css?v=3918102e" />
<script src="../../_static/documentation_options.js?v=5929fcd5"></script>
<script src="../../_static/doctools.js?v=9bcbadda"></script>
<script src="../../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="index" title="Index" href="../../genindex.html" />
<link rel="search" title="Search" href="../../search.html" />
<link rel="next" title="Proc Files of ALSA Drivers" href="procfile.html" />
<link rel="prev" title="ALSA Jack Controls" href="jack-controls.html" />
<link rel="stylesheet" href="../../_static/custom.css" type="text/css" />
</head><body>
<div class="document">
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../../index.html">
<img class="logo" src="../../_static/logo.svg" alt="Logo of The Linux Kernel"/>
</a></p>
<h1 class="logo"><a href="../../index.html">The Linux Kernel</a></h1>
<p class="blurb">6.18.50</p>
<search id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script>
<p>
<h3 class="kernel-toc-contents">Contents</h3>
<input type="checkbox" class="kernel-toc-toggle" id = "kernel-toc-toggle" checked>
<label class="kernel-toc-title" for="kernel-toc-toggle"></label>
<div class="kerneltoc" id="kerneltoc">
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../process/development-process.html">Development process</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../process/submitting-patches.html">Submitting patches</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../process/code-of-conduct.html">Code of conduct</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../maintainer/index.html">Maintainer handbook</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../process/index.html">All development-process docs</a></li>
</ul>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../core-api/index.html">Core API</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../driver-api/index.html">Driver APIs</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../../subsystem-apis.html">Subsystems</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../../subsystem-apis.html#core-subsystems">Core subsystems</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../../subsystem-apis.html#human-interfaces">Human interfaces</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="../../input/index.html">Input Documentation</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../hid/index.html">Human Interface Devices (HID)</a></li>
<li class="toctree-l3 current"><a class="reference internal" href="../index.html">Sound Subsystem Documentation</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../gpu/index.html">GPU Driver Developer’s Guide</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../fb/index.html">Frame Buffer</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../leds/index.html">LEDs</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../../subsystem-apis.html#networking-interfaces">Networking interfaces</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../subsystem-apis.html#storage-interfaces">Storage interfaces</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../subsystem-apis.html#other-subsystems">Other subsystems</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../locking/index.html">Locking</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../process/license-rules.html">Licensing rules</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../doc-guide/index.html">Writing documentation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../dev-tools/index.html">Development tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../dev-tools/testing-overview.html">Testing guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../kernel-hacking/index.html">Hacking guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../trace/index.html">Tracing</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../fault-injection/index.html">Fault injection</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../livepatch/index.html">Livepatching</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../rust/index.html">Rust</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../admin-guide/index.html">Administration</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../kbuild/index.html">Build system</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../admin-guide/reporting-issues.html">Reporting issues</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../tools/index.html">Userspace tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../userspace-api/index.html">Userspace API</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../firmware-guide/index.html">Firmware</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../devicetree/index.html">Firmware and Devicetree</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../arch/index.html">CPU architectures</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../staging/index.html">Unsorted documentation</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../translations/index.html">Translations</a></li>
</ul>
</div>
<script type="text/javascript"> <!--
var sbar = document.getElementsByClassName("sphinxsidebar")[0];
let currents = document.getElementsByClassName("current")
if (currents.length) {
sbar.scrollTop = currents[currents.length - 1].offsetTop;
}
--> </script>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../../_sources/sound/designs/tracepoints.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
</div>
</div>
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="tracepoints-in-alsa">
<h1>Tracepoints in ALSA<a class="headerlink" href="#tracepoints-in-alsa" title="Link to this heading">¶</a></h1>
<p>2017/07/02
Takasahi Sakamoto</p>
<section id="tracepoints-in-alsa-pcm-core">
<h2>Tracepoints in ALSA PCM core<a class="headerlink" href="#tracepoints-in-alsa-pcm-core" title="Link to this heading">¶</a></h2>
<p>ALSA PCM core registers <code class="docutils literal notranslate"><span class="pre">snd_pcm</span></code> 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 <code class="docutils literal notranslate"><span class="pre">CONFIG_SND_DEBUG</span></code>
is enabled, the latter tracepoints are available. When additional
<code class="docutils literal notranslate"><span class="pre">SND_PCM_XRUN_DEBUG</span></code> is enabled too, the former trace points are enabled.</p>
<section id="tracepoints-for-state-of-pcm-buffer">
<h3>Tracepoints for state of PCM buffer<a class="headerlink" href="#tracepoints-for-state-of-pcm-buffer" title="Link to this heading">¶</a></h3>
<p>This category includes four tracepoints; <code class="docutils literal notranslate"><span class="pre">hwptr</span></code>, <code class="docutils literal notranslate"><span class="pre">applptr</span></code>, <code class="docutils literal notranslate"><span class="pre">xrun</span></code> and
<code class="docutils literal notranslate"><span class="pre">hw_ptr_error</span></code>.</p>
</section>
<section id="tracepoints-for-processing-of-pcm-hardware-parameters">
<h3>Tracepoints for processing of PCM hardware parameters<a class="headerlink" href="#tracepoints-for-processing-of-pcm-hardware-parameters" title="Link to this heading">¶</a></h3>
<p>This category includes two tracepoints; <code class="docutils literal notranslate"><span class="pre">hw_mask_param</span></code> and
<code class="docutils literal notranslate"><span class="pre">hw_interval_param</span></code>.</p>
<p>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.</p>
<p>The parameters are described in <code class="xref c c-struct broken_xref docutils literal notranslate"><span class="pre">struct</span> <span class="pre">snd_pcm_hw_params</span></code>. 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.</p>
<p>The <code class="xref c c-struct broken_xref docutils literal notranslate"><span class="pre">struct</span> <span class="pre">snd_pcm_hw_params</span></code> structure has below members:</p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">flags</span></code></dt><dd><p>Configurable. ALSA PCM core and some drivers handle this flag to select
convenient parameters or change their behaviour.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">masks</span></code></dt><dd><p>Configurable. This type of parameter is described in
<code class="xref c c-struct broken_xref docutils literal notranslate"><span class="pre">struct</span> <span class="pre">snd_mask</span></code> and represent mask values. As of PCM protocol
v2.0.13, three types are defined.</p>
<ul class="simple">
<li><p>SNDRV_PCM_HW_PARAM_ACCESS</p></li>
<li><p>SNDRV_PCM_HW_PARAM_FORMAT</p></li>
<li><p>SNDRV_PCM_HW_PARAM_SUBFORMAT</p></li>
</ul>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">intervals</span></code></dt><dd><p>Configurable. This type of parameter is described in
<code class="xref c c-struct broken_xref docutils literal notranslate"><span class="pre">struct</span> <span class="pre">snd_interval</span></code> and represent values with a range. As of
PCM protocol v2.0.13, twelve types are defined.</p>
<ul class="simple">
<li><p>SNDRV_PCM_HW_PARAM_SAMPLE_BITS</p></li>
<li><p>SNDRV_PCM_HW_PARAM_FRAME_BITS</p></li>
<li><p>SNDRV_PCM_HW_PARAM_CHANNELS</p></li>
<li><p>SNDRV_PCM_HW_PARAM_RATE</p></li>
<li><p>SNDRV_PCM_HW_PARAM_PERIOD_TIME</p></li>
<li><p>SNDRV_PCM_HW_PARAM_PERIOD_SIZE</p></li>
<li><p>SNDRV_PCM_HW_PARAM_PERIOD_BYTES</p></li>
<li><p>SNDRV_PCM_HW_PARAM_PERIODS</p></li>
<li><p>SNDRV_PCM_HW_PARAM_BUFFER_TIME</p></li>
<li><p>SNDRV_PCM_HW_PARAM_BUFFER_SIZE</p></li>
<li><p>SNDRV_PCM_HW_PARAM_BUFFER_BYTES</p></li>
<li><p>SNDRV_PCM_HW_PARAM_TICK_TIME</p></li>
</ul>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">rmask</span></code></dt><dd><p>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.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">cmask</span></code></dt><dd><p>Read-only. After returning from ioctl(2), buffer in user space for
<code class="xref c c-struct broken_xref docutils literal notranslate"><span class="pre">struct</span> <span class="pre">snd_pcm_hw_params</span></code> includes result of each operation.
This mask represents which mask/interval parameter is actually changed.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">info</span></code></dt><dd><p>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.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">msbits</span></code></dt><dd><p>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.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">rate_num</span></code></dt><dd><p>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.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">rate_den</span></code></dt><dd><p>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.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">fifo_size</span></code></dt><dd><p>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.</p>
</dd>
</dl>
<p>ALSA PCM core handles buffer of <code class="xref c c-struct broken_xref docutils literal notranslate"><span class="pre">struct</span> <span class="pre">snd_pcm_hw_params</span></code> when
applications execute ioctl(2) with SNDRV_PCM_HW_REFINE or SNDRV_PCM_HW_PARAMS.
Parameters in the buffer are changed according to
<code class="xref c c-struct broken_xref docutils literal notranslate"><span class="pre">struct</span> <span class="pre">snd_pcm_hardware</span></code> 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.</p>
<p>Each driver can join in the interaction as long as it prepared for two stuffs
in a callback of <code class="xref c c-struct broken_xref docutils literal notranslate"><span class="pre">struct</span> <span class="pre">snd_pcm_ops</span></code>.open.</p>
<ol class="arabic simple">
<li><p>In the callback, drivers are expected to change a member of
<code class="xref c c-struct broken_xref docutils literal notranslate"><span class="pre">struct</span> <span class="pre">snd_pcm_hardware</span></code> type in the runtime, according to
capacities of corresponding hardware.</p></li>
<li><p>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.</p></li>
</ol>
<p>The driver can refers to result of the interaction in a callback of
<code class="xref c c-struct broken_xref docutils literal notranslate"><span class="pre">struct</span> <span class="pre">snd_pcm_ops</span></code>.hw_params, however it should not change the
content.</p>
<p>Tracepoints in this category are designed to trace changes of the
mask/interval parameters. When ALSA PCM core changes them, <code class="docutils literal notranslate"><span class="pre">hw_mask_param</span></code> or
<code class="docutils literal notranslate"><span class="pre">hw_interval_param</span></code> event is probed according to type of the changed parameter.</p>
<p>ALSA PCM core also has a pretty print format for each of the tracepoints. Below
is an example for <code class="docutils literal notranslate"><span class="pre">hw_mask_param</span></code>.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>hw_mask_param: pcmC0D0p 001/023 FORMAT 00000000000000000000001000000044 00000000000000000000001000000044
</pre></div>
</div>
<p>Below is an example for <code class="docutils literal notranslate"><span class="pre">hw_interval_param</span></code>.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>hw_interval_param: pcmC0D0p 000/023 BUFFER_SIZE 0 0 [0 4294967295] 0 1 [0 4294967295]
</pre></div>
</div>
<p>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.</p>
<p>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
<code class="docutils literal notranslate"><span class="pre">empty</span></code>, <code class="docutils literal notranslate"><span class="pre">integer</span></code>, <code class="docutils literal notranslate"><span class="pre">openmin</span></code>, <code class="docutils literal notranslate"><span class="pre">min</span></code>, <code class="docutils literal notranslate"><span class="pre">max</span></code>, <code class="docutils literal notranslate"><span class="pre">openmax</span></code> in
<code class="xref c c-struct broken_xref docutils literal notranslate"><span class="pre">struct</span> <span class="pre">snd_interval</span></code> in this order.</p>
</section>
</section>
<section id="tracepoints-in-drivers">
<h2>Tracepoints in drivers<a class="headerlink" href="#tracepoints-in-drivers" title="Link to this heading">¶</a></h2>
<p>Some drivers have tracepoints for developers’ convenience. For them, please
refer to each documentation or implementation.</p>
</section>
</section>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
©The kernel development community.
|
Powered by <a href="https://www.sphinx-doc.org/">Sphinx 8.1.3</a>
& <a href="https://alabaster.readthedocs.io">Alabaster 0.7.16</a>
|
<a href="../../_sources/sound/designs/tracepoints.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>