lib/timer: Add timer infrastructure

Some sources simply fill the buffers passed by the USB subsystem and
return them as quickly as possible. Particularly with compressed
formats operating at superspeed this rapidly results in unrealistic
frame rates.

Add infrastructure that allows us to define a specific
framerate and introduce blocking calls that constrain those sources
to the framerates expected by the host.

Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
Signed-off-by: Daniel Scally <dan.scally@ideasonboard.com>

2 files changed, 60 insertions, 0 deletions

diff --git a/include/uvcgadget/meson.build b/include/uvcgadget/meson.build
index c79ea18..d5aaf17 100644
--- a/include/uvcgadget/meson.build
+++ b/include/uvcgadget/meson.build
@@ -5,6 +5,7 @@ uvcgadget_public_headers = files([
   'events.h',
   'list.h',
   'stream.h',
+  'timer.h',
   'v4l2-source.h',
   'video-source.h',
   ])
diff --git a/include/uvcgadget/timer.h b/include/uvcgadget/timer.h
new file mode 100644
index 0000000..de93287
--- /dev/null
+++ b/include/uvcgadget/timer.h
@@ -0,0 +1,59 @@
+/* SPDX-License-Identifier: LGPL-2.1-or-later */
+/*
+ * libuvcgadget timer utils
+ *
+ * Copyright (C) 2022 Daniel Scally
+ *
+ * Contact: Daniel Scally <dan.scally@ideasonboard.com>
+ */
+
+struct timer;
+
+/*
+ * timer_new - Create a new timer
+ *
+ * Allocates and returns a new struct timer. This must be configured with
+ * timer_set_fps() and then armed with timer_arm(), following which calls to
+ * timer_wait() will block until the expiration of a period as defined by
+ * timer_set_fps().
+ *
+ * Timers allocated with this function should be removed with timer_destroy()
+ */
+struct timer *timer_new(void);
+
+/*
+ * timer_set_fps - Configure the timer's wait period
+ *
+ * Configure the timer to wait for a period of time such that expirations per
+ * second matches @fps
+ */
+void timer_set_fps(struct timer *timer, int fps);
+
+/*
+ * timer_arm
+ *
+ * Arms the timer such that calls to timer_wait() become blocking until the
+ * expiration of a period.
+ */
+int timer_arm(struct timer *timer);
+
+/*
+ * timer_disarm
+ *
+ * Disarms the timer such that calls to timer_wait() return without blocking.
+ */
+int timer_disarm(struct timer *timer);
+
+/*
+ * timer_wait
+ *
+ * If the timer is armed, block until the expiration of a period
+ */
+void timer_wait(struct timer *timer);
+
+/*
+ * timer_destroy
+ *
+ * Close the timer's file descriptor and free the memory
+ */
+void timer_destroy(struct timer *timer);