1 .. SPDX-License-Identifier: GPL-2.0
2
3 =======================
4 Userspace-driven timers
5 =======================
6
7 :Author: Ivan Orlov <ivan.orlov0322@gmail.com>
8
9 Preface
10 =======
11
12 This document describes the userspace-driven t
13 which could be created and controlled by users
14 IOCTL calls. Such timers could be useful when
15 stream with timer sources which we don't have
16 (e.g. PTP clocks), and when synchronizing the
17 two virtual sound devices using ``snd-aloop``
18 we have a network application sending frames t
19 and another sound application listening on the
20
21 Enabling userspace-driven timers
22 ================================
23
24 The userspace-driven timers could be enabled i
25 ``CONFIG_SND_UTIMER`` configuration option. It
26 ``CONFIG_SND_TIMER`` option, so it also should
27
28 Userspace-driven timers API
29 ===========================
30
31 Userspace application can create a userspace-d
32 executing the ``SNDRV_TIMER_IOCTL_CREATE`` ioc
33 ``/dev/snd/timer`` device file descriptor. The
34 structure should be passed as an ioctl argumen
35
36 ::
37
38 struct snd_timer_uinfo {
39 __u64 resolution;
40 int fd;
41 unsigned int id;
42 unsigned char reserved[16];
43 }
44
45 The ``resolution`` field sets the desired reso
46 the virtual timer. ``resolution`` field simply
47 about the virtual timer, but does not affect t
48 field gets overwritten by the ioctl, and the i
49 field after the call can be used as a timer su
50 passing the timer to ``snd-aloop`` kernel modu
51 applications. There could be up to 128 userspa
52 system at one moment of time, thus the id valu
53
54 Besides from overwriting the ``snd_timer_uinfo
55 a timer file descriptor, which can be used to
56 ``fd`` field of the ``snd_timer_uinfo`` struct
57 descriptor for the timer guarantees that the t
58 by the process which created it. The timer the
59 ``SNDRV_TIMER_IOCTL_TRIGGER`` ioctl call on th
60
61 So, the example code for creating and triggeri
62
63 ::
64
65 static struct snd_timer_uinfo utimer_info
66 /* Timer is going to tick (presumably)
67 .resolution = 1000000ULL,
68 .id = -1,
69 };
70
71 int timer_device_fd = open("/dev/snd/timer
72
73 if (ioctl(timer_device_fd, SNDRV_TIMER_IOC
74 perror("Failed to create the timer");
75 return -1;
76 }
77
78 ...
79
80 /*
81 * Now we want to trigger the timer. Callb
82 * timer instances binded to this timer wi
83 * this call.
84 */
85 ioctl(utimer_info.fd, SNDRV_TIMER_IOCTL_TR
86
87 ...
88
89 /* Now, destroy the timer */
90 close(timer_info.fd);
91
92
93 More detailed example of creating and ticking
94 in the utimer ALSA selftest.
95
96 Userspace-driven timers and snd-aloop
97 -------------------------------------
98
99 Userspace-driven timers could be easily used w
100 when synchronizing two sound applications on b
101 sound loopback. For instance, if one of the ap
102 frames from network and sends them to snd-aloo
103 application listens for frames on the other sn
104 makes sense that the ALSA middle layer should
105 transaction when the new period of data is rec
106 not when the certain amount of jiffies elapses
107 timers could be used to achieve this.
108
109 To use userspace-driven ALSA timer as a timer
110 the following string as the snd-aloop ``timer_
111
112 ::
113
114 # modprobe snd-aloop timer_source="-1.4.<uti
115
116 Where ``utimer_id`` is the id of the timer you
117 ``SNDRV_TIMER_IOCTL_CREATE``, and ``4`` is the
118 userspace-driven timers device (``SNDRV_TIMER_
119
120 ``resolution`` for the userspace-driven ALSA t
121 should be calculated as ``1000000000ULL / fram
122 the timer is going to tick every time a new pe
123
124 After that, each time you trigger the timer wi
125 ``SNDRV_TIMER_IOCTL_TRIGGER`` the new period o
126 from one snd-aloop device to another.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.