Skip to contentSkip to conversation

Introduce userspace-driven ALSA timers

PATCH In review Ivan Orlov 2 participants 6 messages Aug 13, 2024 – Aug 18, 2024

Subsystems (4)
lore
Share & tools
lore

Ivan Orlov

author
#0 lore raw

v5 cover Introduce userspace-driven ALSA timers

There are multiple possible timer sources which could be useful for the sound stream synchronization: hrtimers, hardware clocks (e.g. PTP), timer wheels (jiffies). Currently, using one of them to synchronize the audio stream of snd-aloop module would require writing a kernel-space driver which exports an ALSA timer through the snd_timer interface.

However, it is not really convenient for application developers, who may want to define their custom timer sources for audio synchronization.

For instance, we could have a network application which receives frames and sends them to snd-aloop pcm device, and another application listening on the other end of snd-aloop. It makes sense to transfer a new period of data only when certain amount of frames is received through the network, but definitely not when a certain amount of jiffies on a local system elapses. Since all of the devices are purely virtual it won't introduce any glitches and will help the application developers to avoid using sample-rate conversion.

This patch series introduces userspace-driven ALSA timers: virtual timers which are created and controlled from userspace. The timer can be created from the userspace using the new ioctl SNDRV_TIMER_IOCTL_CREATE. After creating a timer, it becomes available for use system-wide, so it can be passed to snd-aloop as a timer source (timer_source parameter would be "-1.SNDRV_TIMER_GLOBAL_UDRIVEN.{timer_id}"). When the userspace app decides to trigger a timer, it calls another ioctl SNDRV_TIMER_IOCTL_TRIGGER on the file descriptor of a timer. It initiates a transfer of a new period of data.

Userspace-driven timers are associated with file descriptors. If the application wishes to destroy the timer, it can simply release the file descriptor of a virtual timer.

I believe introducing new ioctl calls is quite inconvenient (as we have a limited amount of them), but other possible ways of app <-> kernel communication (like virtual FS) seem completely inappropriate for this task (but I'd love to discuss alternative solutions).

This patch series also updates the snd-aloop module so the global timers can be used as a timer_source for it (it allows using userspace-driven timers as timer source).

V1 -> V2:
- Fix some problems found by Christophe Jaillet <[email protected]>
V2 -> V3:
- Add improvements suggested by Takashi Iwai <[email protected]> V3 -> V4:
- Address comments from Jaroslav Kysela <[email protected]> and Mark Brown <[email protected]>
V4 -> V5:
- Add missing error processing noticed by Takashi Iwai <[email protected]>
- Return timer file descriptor as part of the snd_timer_uinfo structure. This is a more standard way of using ioctl interface, where the return value of the ioctl is either 0 or an error code.

Please, find the patch-specific changelog in the following patches.

Ivan Orlov (4):
ALSA: aloop: Allow using global timers
Docs/sound: Add documentation for userspace-driven ALSA timers
ALSA: timer: Introduce virtual userspace-driven timers
selftests: ALSA: Cover userspace-driven timers with test

 Documentation/sound/index.rst               |   1 +
 Documentation/sound/utimers.rst             | 126 +++++++++++
 include/uapi/sound/asound.h                 |  17 +-
 sound/core/Kconfig                          |  10 +
 sound/core/timer.c                          | 225 ++++++++++++++++++++
 sound/drivers/aloop.c                       |   2 +
 tools/testing/selftests/alsa/Makefile       |   4 +-
 tools/testing/selftests/alsa/global-timer.c |  87 ++++++++
 tools/testing/selftests/alsa/utimer-test.c  | 164 ++++++++++++++
 9 files changed, 633 insertions(+), 3 deletions(-)
 create mode 100644 Documentation/sound/utimers.rst
 create mode 100644 tools/testing/selftests/alsa/global-timer.c
 create mode 100644 tools/testing/selftests/alsa/utimer-test.c
Signature · 1 line
2.34.1
author
#1 lore raw

PATCH v5 1/4 ALSA: aloop: Allow using global timers

Allow using global timers as a timer source when card id is equal to -1 in the timer_source parameter.

---
V1 -> V2:
- No changes
V2 -> V3:
- No changes
V3 -> V4:
- No changes
V4 -> V5:
- No changes

 sound/drivers/aloop.c | 2 ++
 1 file changed, 2 insertions(+)
sound/drivers/aloop.c +2 -0
index d6dd4b8c750a..a1e5e7fe9c72 100644
@@ -1130,6 +1130,8 @@ static int loopback_parse_timer_id(const char *str,
 			}
 		}
 	}
+	if (card_idx == -1)
+		tid->dev_class = SNDRV_TIMER_CLASS_GLOBAL;
 	if (!err && tid) {
 		tid->card = card_idx;
 		tid->device = dev;
Signature · 1 line
2.34.1
author
#2 lore raw

PATCH v5 2/4 Docs/sound: Add documentation for userspace-driven ALSA timers

In reply to Ivan Orlov

Add the documentation which describes the new userspace-driven timers API introduced in this patch series. The documentation contains:

- Description of userspace-driven ALSA timers, what they are for
- Description of the timers API
- Example of how the timers can be created and triggered
- How the timers can be used as a timer sources for snd-aloop module

---
V1 -> V2:
- No changes
V2 -> V3:
- No changes
V3 -> V4:
- Update the userspace-driver ALSA timer structure name and fields in correspondence with the latest changes (remove pcm-specific fields from the structure description)
- Update the snd-aloop paragraph to provide a way to calculate the timer resolution from frame rate and period size
V4 -> V5:
- Update the documentation in correspondence with snd_timer_uinfo struct change (timer file descriptor is now returned in one of the fields of the userspace-driven timer info structure).

 Documentation/sound/index.rst   |   1 +
 Documentation/sound/utimers.rst | 126 ++++++++++++++++++++++++++++++++
 2 files changed, 127 insertions(+)
 create mode 100644 Documentation/sound/utimers.rst
Documentation/sound/index.rst +1 -0
index 7e67e12730d3..c437f2a4bc85 100644
@@ -13,6 +13,7 @@ Sound Subsystem Documentation
    alsa-configuration
    hd-audio/index
    cards/index
+   utimers
 
 .. only::  subproject and html
 
Documentation/sound/utimers.rst new file +126 -0

126 lines not on this page · raw message

Signature · 1 line
2.34.1
author
#3 lore raw

PATCH v5 3/4 ALSA: timer: Introduce virtual userspace-driven timers

In reply to Ivan Orlov

Implement two ioctl calls in order to support virtual userspace-driven ALSA timers.

The first ioctl is SNDRV_TIMER_IOCTL_CREATE, which gets the snd_timer_uinfo struct as a parameter and puts a file descriptor of a virtual timer into the fd field of the snd_timer_unfo structure. It also updates the id field of the snd_timer_uinfo struct, which provides a unique identifier for the timer (basically, the subdevice number which can be used when creating timer instances).

This patch also introduces a tiny id allocator for the userspace-driven timers, which guarantees that we don't have more than 128 of them in the system.

Another ioctl is SNDRV_TIMER_IOCTL_TRIGGER, which allows us to trigger the virtual timer (and calls snd_timer_interrupt for the timer under the hood), causing all of the timer instances binded to this timer to execute their callbacks.

The maximum amount of ticks available for the timer is 1 for the sake of simplicity of the userspace API. 'start', 'stop', 'open' and 'close' callbacks for the userspace-driven timers are empty since we don't really do any hardware initialization here.

---
V1 -> V2:
- Add missing kfree for the utimer name in snd_utimer_free
- Remove extra newline in sound core Kconfig
- Use IDA allocator API to allocate utimer ids
- Use kasprintf for the timer name instead of kzalloc + sprintf V2 -> V3:
- Use __u64 instead of snd_pcm_uframes_t in snd_utimer_info struct
- Add 16 reserved bytes to snd_utimer_info struct just in case we decide to add some other fields to this struct
- Bump the timer protocol version in SNDRV_TIMER_VERSION to 2.0.8
- Make the 'snd_utimer_ids' variable static
- Add sanity checks to the 'snd_utimer_create' function: 0-check for period size and frame rate, overflow and 0- checks for resolution
- Use automatic cleanup in 'snd_utimer_ioctl_create'
- Return -ENOTTY instead of -EINVAL from ioctl if userspace-driven timers are disabled
V3 -> V4:
- Remove pcm-specific fields (frame_rate, period_size) from the userspace-driven ALSA timer info structure. Replace them with a timer-specific resolution field
- Rename the structure to snd_timer_uinfo
- Remove a part of sanity checks and resolution calculation from the timer creating function. It should be done in userspace instead V4 -> V5:
- Add missing error processing for the anon_inode_getfd structure
- Return the timer file descriptor in one of the fields of the snd_timer_uinfo structure instead of passing it as a return value from ioctl. This is a more standard way of using ioctl interface, where the return value of ioctl is either 0 or an error code.

 include/uapi/sound/asound.h |  17 ++-
 sound/core/Kconfig          |  10 ++
 sound/core/timer.c          | 225 ++++++++++++++++++++++++++++++++++++
 3 files changed, 251 insertions(+), 1 deletion(-)
include/uapi/sound/asound.h +16 -1
index 8bf7e8a0eb6f..4cd513215bcd 100644
@@ -869,7 +869,7 @@ struct snd_ump_block_info {
  *  Timer section - /dev/snd/timer
  */
 
-#define SNDRV_TIMER_VERSION		SNDRV_PROTOCOL_VERSION(2, 0, 7)
+#define SNDRV_TIMER_VERSION		SNDRV_PROTOCOL_VERSION(2, 0, 8)
 
 enum {
 	SNDRV_TIMER_CLASS_NONE = -1,
@@ -894,6 +894,7 @@ enum {
 #define SNDRV_TIMER_GLOBAL_RTC		1	/* unused */
 #define SNDRV_TIMER_GLOBAL_HPET		2
 #define SNDRV_TIMER_GLOBAL_HRTIMER	3
+#define SNDRV_TIMER_GLOBAL_UDRIVEN	4
 
 /* info flags */
 #define SNDRV_TIMER_FLG_SLAVE		(1<<0)	/* cannot be controlled */
@@ -974,6 +975,18 @@ struct snd_timer_status {
 };
 #endif
 
+/*
+ * This structure describes the userspace-driven timer. Such timers are purely virtual,
+ * and can only be triggered from software (for instance, by userspace application).
+ */
+struct snd_timer_uinfo {
+	/* To pretend being a normal timer, we need to know the resolution in ns. */
+	__u64 resolution;
+	int fd;
+	unsigned int id;
+	unsigned char reserved[16];
+};
+
 #define SNDRV_TIMER_IOCTL_PVERSION	_IOR('T', 0x00, int)
 #define SNDRV_TIMER_IOCTL_NEXT_DEVICE	_IOWR('T', 0x01, struct snd_timer_id)
 #define SNDRV_TIMER_IOCTL_TREAD_OLD	_IOW('T', 0x02, int)
@@ -990,6 +1003,8 @@ struct snd_timer_status {
 #define SNDRV_TIMER_IOCTL_CONTINUE	_IO('T', 0xa2)
 #define SNDRV_TIMER_IOCTL_PAUSE		_IO('T', 0xa3)
 #define SNDRV_TIMER_IOCTL_TREAD64	_IOW('T', 0xa4, int)
+#define SNDRV_TIMER_IOCTL_CREATE	_IOWR('T', 0xa5, struct snd_timer_uinfo)
+#define SNDRV_TIMER_IOCTL_TRIGGER	_IO('T', 0xa6)
 
 #if __BITS_PER_LONG == 64
 #define SNDRV_TIMER_IOCTL_TREAD SNDRV_TIMER_IOCTL_TREAD_OLD
sound/core/Kconfig +10 -0
index b970a1734647..670b26cf3065 100644
@@ -251,6 +251,16 @@ config SND_JACK_INJECTION_DEBUG
 	  Say Y if you are debugging via jack injection interface.
 	  If unsure select "N".
 
+config SND_UTIMER
+	bool "Enable support for userspace-controlled virtual timers"
+	depends on SND_TIMER
+	help
+	  Say Y to enable the support of userspace-controlled timers. These
+	  timers are purely virtual, and they are supposed to be triggered
+	  from userspace. They could be quite useful when synchronizing the
+	  sound timing with userspace applications (for instance, when sending
+	  data through snd-aloop).
+
 config SND_VMASTER
 	bool
 
sound/core/timer.c +225 -0

249 lines not on this page · raw message

Signature · 1 line
2.34.1
author
#4 lore raw

PATCH v5 4/4 selftests: ALSA: Cover userspace-driven timers with test

In reply to Ivan Orlov

Add a test for the new functionality of userspace-driven timers and the tool which allows us to count timer ticks in a certain time period. The test:

1. Creates a userspace-driven timer with ioctl to /dev/snd/timer
2. Starts the global-timer application to count the ticks of the timer from step 1.
3. Asynchronously triggers the timer multiple times with some interval
4. Compares the amount of caught ticks with the amount of trigger calls.

Since we can't include <alsa/asoundlib.h> and <sound/asound.h> in one file due to overlapping declarations, I have to split the test into two
applications: one of them counts the amount of timer ticks in the defined time period, and another one is the actual test which creates the timer, triggers it periodically and starts the first app to count the amount of ticks in a separate thread.

Besides from testing the functionality itself, the test represents a sample application showing userspace-driven ALSA timers API.

Also, the timer test includes a test case which tries to create a timer with invalid resolution (=0), and NULL as a timer info structure.

---
V1 -> V2:
- Return NULL in the pthreaded function (ticking_func)
- Process TIMER_NO_EVENT enum in the timer app output processing loop V2 -> V3:
- Add new test case to cover invalid period sizes and frame rates for the userspace-driven timers (to test the sanity checks in snd_utimer_create)
V3 -> V4:
- Use the new structure declarations to define timer info
- Calculate the timer resolution in userspace from frame rate and period size
- Remove majority of test-cases for invalid timer test as we don't do many sanity checks in the kernel anymore
- Move global-timer into the TEST_GEN_PROGS_EXTENDED list as it is not a standalone test but an app called from utimer-test.c
- Add test case which tries to pass NULL as a timer info structure for the timer creation ioctl
V4 -> V5:
- Update the test to use snd_timer_uinfo fd field when getting the timer file descriptor

 tools/testing/selftests/alsa/Makefile       |   4 +-
 tools/testing/selftests/alsa/global-timer.c |  87 +++++++++++
 tools/testing/selftests/alsa/utimer-test.c  | 164 ++++++++++++++++++++
 3 files changed, 253 insertions(+), 2 deletions(-)
 create mode 100644 tools/testing/selftests/alsa/global-timer.c
 create mode 100644 tools/testing/selftests/alsa/utimer-test.c
tools/testing/selftests/alsa/Makefile +2 -2
index c1ce39874e2b..25be68025290 100644
@@ -12,9 +12,9 @@ LDLIBS+=-lpthread
 
 OVERRIDE_TARGETS = 1
 
-TEST_GEN_PROGS := mixer-test pcm-test test-pcmtest-driver
+TEST_GEN_PROGS := mixer-test pcm-test test-pcmtest-driver utimer-test
 
-TEST_GEN_PROGS_EXTENDED := libatest.so
+TEST_GEN_PROGS_EXTENDED := libatest.so global-timer
 
 TEST_FILES := conf.d pcm-test.conf
 
tools/testing/selftests/alsa/global-timer.c new file +87 -0

87 lines not on this page · raw message

tools/testing/selftests/alsa/utimer-test.c new file +164 -0

164 lines not on this page · raw message

Signature · 1 line
2.34.1
#5 lore raw
In reply to Ivan Orlov
Quoted 57 lines · Ivan Orlov

There are multiple possible timer sources which could be useful for the sound stream synchronization: hrtimers, hardware clocks (e.g. PTP), timer wheels (jiffies). Currently, using one of them to synchronize the audio stream of snd-aloop module would require writing a kernel-space driver which exports an ALSA timer through the snd_timer interface.

However, it is not really convenient for application developers, who may want to define their custom timer sources for audio synchronization.

For instance, we could have a network application which receives frames and sends them to snd-aloop pcm device, and another application listening on the other end of snd-aloop. It makes sense to transfer a new period of data only when certain amount of frames is received through the network, but definitely not when a certain amount of jiffies on a local system elapses. Since all of the devices are purely virtual it won't introduce any glitches and will help the application developers to avoid using sample-rate conversion.

This patch series introduces userspace-driven ALSA timers: virtual timers which are created and controlled from userspace. The timer can be created from the userspace using the new ioctl SNDRV_TIMER_IOCTL_CREATE. After creating a timer, it becomes available for use system-wide, so it can be passed to snd-aloop as a timer source (timer_source parameter would be "-1.SNDRV_TIMER_GLOBAL_UDRIVEN.{timer_id}"). When the userspace app decides to trigger a timer, it calls another ioctl SNDRV_TIMER_IOCTL_TRIGGER on the file descriptor of a timer. It initiates a transfer of a new period of data.

Userspace-driven timers are associated with file descriptors. If the application wishes to destroy the timer, it can simply release the file descriptor of a virtual timer.

I believe introducing new ioctl calls is quite inconvenient (as we have a limited amount of them), but other possible ways of app <-> kernel communication (like virtual FS) seem completely inappropriate for this task (but I'd love to discuss alternative solutions).

This patch series also updates the snd-aloop module so the global timers can be used as a timer_source for it (it allows using userspace-driven timers as timer source).

V1 -> V2:
- Fix some problems found by Christophe Jaillet <[email protected]>
V2 -> V3:
- Add improvements suggested by Takashi Iwai <[email protected]> V3 -> V4:
- Address comments from Jaroslav Kysela <[email protected]> and Mark Brown <[email protected]>
V4 -> V5:
- Add missing error processing noticed by Takashi Iwai <[email protected]>
- Return timer file descriptor as part of the snd_timer_uinfo structure. This is a more standard way of using ioctl interface, where the return value of the ioctl is either 0 or an error code.

Quoted 7 lines

Please, find the patch-specific changelog in the following patches.

Ivan Orlov (4):
ALSA: aloop: Allow using global timers
Docs/sound: Add documentation for userspace-driven ALSA timers
ALSA: timer: Introduce virtual userspace-driven timers
selftests: ALSA: Cover userspace-driven timers with test

Now applied to for-next branch.

thanks,

Takashi