<!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>Userspace-driven timers — 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="GPU Driver Developer’s Guide" href="../gpu/index.html" />
<link rel="prev" title="Audio drivers for Cirrus Logic CS35L54/56/57/63 Boosted Smart Amplifiers" href="codecs/cs35l56.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/utimers.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="userspace-driven-timers">
<h1>Userspace-driven timers<a class="headerlink" href="#userspace-driven-timers" title="Link to this heading">¶</a></h1>
<dl class="field-list simple">
<dt class="field-odd">Author<span class="colon">:</span></dt>
<dd class="field-odd"><p>Ivan Orlov <<a class="reference external" href="mailto:ivan.orlov0322%40gmail.com">ivan<span>.</span>orlov0322<span>@</span>gmail<span>.</span>com</a>></p>
</dd>
</dl>
<section id="preface">
<h2>Preface<a class="headerlink" href="#preface" title="Link to this heading">¶</a></h2>
<p>This document describes the userspace-driven timers: virtual ALSA timers
which could be created and controlled by userspace applications using
IOCTL calls. Such timers could be useful when synchronizing audio
stream with timer sources which we don’t have ALSA timers exported for
(e.g. PTP clocks), and when synchronizing the audio stream going through
two virtual sound devices using <code class="docutils literal notranslate"><span class="pre">snd-aloop</span></code> (for instance, when
we have a network application sending frames to one snd-aloop device,
and another sound application listening on the other end of snd-aloop).</p>
</section>
<section id="enabling-userspace-driven-timers">
<h2>Enabling userspace-driven timers<a class="headerlink" href="#enabling-userspace-driven-timers" title="Link to this heading">¶</a></h2>
<p>The userspace-driven timers could be enabled in the kernel using the
<code class="docutils literal notranslate"><span class="pre">CONFIG_SND_UTIMER</span></code> configuration option. It depends on the
<code class="docutils literal notranslate"><span class="pre">CONFIG_SND_TIMER</span></code> option, so it also should be enabled.</p>
</section>
<section id="userspace-driven-timers-api">
<h2>Userspace-driven timers API<a class="headerlink" href="#userspace-driven-timers-api" title="Link to this heading">¶</a></h2>
<p>Userspace application can create a userspace-driven ALSA timer by
executing the <code class="docutils literal notranslate"><span class="pre">SNDRV_TIMER_IOCTL_CREATE</span></code> ioctl call on the
<code class="docutils literal notranslate"><span class="pre">/dev/snd/timer</span></code> device file descriptor. The <code class="docutils literal notranslate"><span class="pre">snd_timer_uinfo</span></code>
structure should be passed as an ioctl argument:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>struct snd_timer_uinfo {
__u64 resolution;
int fd;
unsigned int id;
unsigned char reserved[16];
}
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">resolution</span></code> field sets the desired resolution in nanoseconds for
the virtual timer. <code class="docutils literal notranslate"><span class="pre">resolution</span></code> field simply provides an information
about the virtual timer, but does not affect the timing itself. <code class="docutils literal notranslate"><span class="pre">id</span></code>
field gets overwritten by the ioctl, and the identifier you get in this
field after the call can be used as a timer subdevice number when
passing the timer to <code class="docutils literal notranslate"><span class="pre">snd-aloop</span></code> kernel module or other userspace
applications. There could be up to 128 userspace-driven timers in the
system at one moment of time, thus the id value ranges from 0 to 127.</p>
<p>Besides from overwriting the <code class="docutils literal notranslate"><span class="pre">snd_timer_uinfo</span></code> struct, ioctl stores
a timer file descriptor, which can be used to trigger the timer, in the
<code class="docutils literal notranslate"><span class="pre">fd</span></code> field of the <code class="docutils literal notranslate"><span class="pre">snd_timer_uinfo</span></code> struct. Allocation of a file
descriptor for the timer guarantees that the timer can only be triggered
by the process which created it. The timer then can be triggered with
<code class="docutils literal notranslate"><span class="pre">SNDRV_TIMER_IOCTL_TRIGGER</span></code> ioctl call on the timer file descriptor.</p>
<p>So, the example code for creating and triggering the timer would be:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>static struct snd_timer_uinfo utimer_info = {
/* Timer is going to tick (presumably) every 1000000 ns */
.resolution = 1000000ULL,
.id = -1,
};
int timer_device_fd = open("/dev/snd/timer", O_RDWR | O_CLOEXEC);
if (ioctl(timer_device_fd, SNDRV_TIMER_IOCTL_CREATE, &utimer_info)) {
perror("Failed to create the timer");
return -1;
}
...
/*
* Now we want to trigger the timer. Callbacks of all of the
* timer instances binded to this timer will be executed after
* this call.
*/
ioctl(utimer_info.fd, SNDRV_TIMER_IOCTL_TRIGGER, NULL);
...
/* Now, destroy the timer */
close(timer_info.fd);
</pre></div>
</div>
<p>More detailed example of creating and ticking the timer could be found
in the utimer ALSA selftest.</p>
<section id="userspace-driven-timers-and-snd-aloop">
<h3>Userspace-driven timers and snd-aloop<a class="headerlink" href="#userspace-driven-timers-and-snd-aloop" title="Link to this heading">¶</a></h3>
<p>Userspace-driven timers could be easily used with <code class="docutils literal notranslate"><span class="pre">snd-aloop</span></code> module
when synchronizing two sound applications on both ends of the virtual
sound loopback. For instance, if one of the applications receives sound
frames from network and sends them to snd-aloop pcm device, and another
application listens for frames on the other snd-aloop pcm device, it
makes sense that the ALSA middle layer should initiate a data
transaction when the new period of data is received through network, but
not when the certain amount of jiffies elapses. Userspace-driven ALSA
timers could be used to achieve this.</p>
<p>To use userspace-driven ALSA timer as a timer source of snd-aloop, pass
the following string as the snd-aloop <code class="docutils literal notranslate"><span class="pre">timer_source</span></code> parameter:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span># modprobe snd-aloop timer_source="-1.4.<utimer_id>"
</pre></div>
</div>
<p>Where <code class="docutils literal notranslate"><span class="pre">utimer_id</span></code> is the id of the timer you created with
<code class="docutils literal notranslate"><span class="pre">SNDRV_TIMER_IOCTL_CREATE</span></code>, and <code class="docutils literal notranslate"><span class="pre">4</span></code> is the number of
userspace-driven timers device (<code class="docutils literal notranslate"><span class="pre">SNDRV_TIMER_GLOBAL_UDRIVEN</span></code>).</p>
<p><code class="docutils literal notranslate"><span class="pre">resolution</span></code> for the userspace-driven ALSA timer used with snd-aloop
should be calculated as <code class="docutils literal notranslate"><span class="pre">1000000000ULL</span> <span class="pre">/</span> <span class="pre">frame_rate</span> <span class="pre">*</span> <span class="pre">period_size</span></code> as
the timer is going to tick every time a new period of frames is ready.</p>
<p>After that, each time you trigger the timer with
<code class="docutils literal notranslate"><span class="pre">SNDRV_TIMER_IOCTL_TRIGGER</span></code> the new period of data will be transferred
from one snd-aloop device to another.</p>
</section>
</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/utimers.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>