[alsa-devel] [PATCH v3 alsa-lib 1/3] snd_pcm_start_at and friends.

[Tim Cussins]

Upcoming audio hardware has the ability to begin playback when the value
of a high-precision free-running counter matches some programmable value.

This patch exposes such capability in a general way, allowing for several
clock sources, including both system clocks and audio hardware clocks.

We define 3 new methods that operate on a snd_pcm_t, and 1 that
operates on a snd_pcm_status_t.

- snd_pcm_start_at()
allows client code to delegate the starting of the stream to the kernel.

- snd_pcm_start_at_abort()
allows client code to cancel a previous call to snd_pcm_start_at().

- snd_pcm_start_at_gettime()
allows client code to query the current time for a given clock.

- snd_pcm_status_get_startat_state()
allows client code to extract information about any pending start_at timer
from a snd_pcm_status_t object.

We define a new enum: snd_pcm_startat_clock_type_t, which reinforces a clean
boundary between the capabilities of the timestamping system and the start_at
system. The clock and audio hw sources are grouped together because the
difference is irrelevant to the use of snd_pcm_start_at().

Signed-off-by: Tim Cussins <timcussins at eml.cc>

diff --git a/include/pcm.h b/include/pcm.h
index 0655e7f..4f4834b 100644
--- a/include/pcm.h
+++ b/include/pcm.h
@@ -330,6 +330,17 @@ typedef enum _snd_pcm_tstamp_type {
 	SND_PCM_TSTAMP_TYPE_LAST = SND_PCM_TSTAMP_TYPE_MONOTONIC_RAW,
 } snd_pcm_tstamp_type_t;
 
+/** PCM start_at clock types */
+typedef enum _snd_pcm_startat_clock_type {
+	/** POSIX CLOCK_REALTIME equivalent */
+	SND_PCM_STARTAT_CLOCK_TYPE_GETTIMEOFDAY = 0,
+	/** POSIX CLOCK_MONOTONIC equivalent */
+	SND_PCM_STARTAT_CLOCK_TYPE_MONOTONIC,
+	/** Default link clock */
+	SND_PCM_STARTAT_CLOCK_TYPE_LINK,
+	SND_PCM_STARTAT_CLOCK_TYPE_LAST = SND_PCM_STARTAT_CLOCK_TYPE_LINK,
+} snd_pcm_startat_clock_type_t;
+
 /** Unsigned frames quantity */
 typedef unsigned long snd_pcm_uframes_t;
 /** Signed frames quantity */
@@ -478,6 +489,9 @@ int snd_pcm_prepare(snd_pcm_t *pcm);
 int snd_pcm_reset(snd_pcm_t *pcm);
 int snd_pcm_status(snd_pcm_t *pcm, snd_pcm_status_t *status);
 int snd_pcm_start(snd_pcm_t *pcm);
+int snd_pcm_start_at(snd_pcm_t *pcm, snd_pcm_startat_clock_type_t clock_type, const snd_htimestamp_t* start_time);
+int snd_pcm_start_at_abort(snd_pcm_t *pcm);
+int snd_pcm_start_at_gettime(snd_pcm_t *pcm, snd_pcm_startat_clock_type_t clock_type, snd_htimestamp_t* current_time);
 int snd_pcm_drop(snd_pcm_t *pcm);
 int snd_pcm_drain(snd_pcm_t *pcm);
 int snd_pcm_pause(snd_pcm_t *pcm, int enable);
@@ -984,6 +998,7 @@ snd_pcm_sframes_t snd_pcm_status_get_delay(const snd_pcm_status_t *obj);
 snd_pcm_uframes_t snd_pcm_status_get_avail(const snd_pcm_status_t *obj);
 snd_pcm_uframes_t snd_pcm_status_get_avail_max(const snd_pcm_status_t *obj);
 snd_pcm_uframes_t snd_pcm_status_get_overrange(const snd_pcm_status_t *obj);
+void snd_pcm_status_get_startat_state(const snd_pcm_status_t *obj, int *pending, snd_pcm_startat_clock_type_t *clock_type, snd_htimestamp_t *start_time);
 
 /** \} */
 
diff --git a/src/pcm/pcm.c b/src/pcm/pcm.c
index e74e02f..f2cbd8e 100644
--- a/src/pcm/pcm.c
+++ b/src/pcm/pcm.c
@@ -1085,6 +1085,74 @@ int snd_pcm_start(snd_pcm_t *pcm)
 }
 
 /**
+ * \brief Start a PCM at a specified point in the future
+ * \param pcm PCM handle
+ * \param clock_type Specifies the start_at clock with which to interpret \p start_time
+ * \param start_time Absolute time at which to start the stream
+ * \return 0 on success otherwise a negative error code
+ * \retval -ENOSYS operation not supported for the current timestamp type
+ * \retval -EINVAL timespec, tstamp_class or tstamp_type is invalid
+ * \retval -ETIME requested start_time cannot be satisfied
+ *
+ * This method is non-blocking: It establishes an appropriate timer in the kernel
+ * that will start the stream on expiry.
+ *
+ * Any pending timer is unconditionally cancelled.
+ */
+int snd_pcm_start_at(snd_pcm_t *pcm, snd_pcm_startat_clock_type_t clock_type, const snd_htimestamp_t *start_time)
+{
+	assert(pcm);
+	assert(start_time);
+	if (CHECK_SANITY(! pcm->setup)) {
+		SNDMSG("PCM not set up");
+		return -EIO;
+	}
+	if (pcm->fast_ops->start_at) {
+		return pcm->fast_ops->start_at(pcm->fast_op_arg, clock_type, start_time);
+	}
+	return -EINVAL;
+}
+
+/**
+ * \brief Abort the pending PCM start_at timer
+ * \param pcm PCM handle
+ * \return 0 on success otherwise a negative error code
+ *
+ * If a start_at timer is pending, it is cancelled.
+ */
+int snd_pcm_start_at_abort(snd_pcm_t *pcm)
+{
+	assert(pcm);
+	if (CHECK_SANITY(! pcm->setup)) {
+		SNDMSG("PCM not set up");
+		return -EIO;
+	}
+	if (pcm->fast_ops->start_at_abort) {
+		return pcm->fast_ops->start_at_abort(pcm->fast_op_arg);
+	}
+	return -EINVAL;
+}
+
+/**
+ * \brief Get current time for a given start_at clock
+ * \param pcm PCM handle
+ * \param clock_type Start_at clock type e.g. SND_PCM_STARTAT_CLOCK_TYPE_GETTIMEOFDAY
+ * \return 0 on success otherwise a negative error code
+ */
+int snd_pcm_start_at_gettime(snd_pcm_t *pcm, snd_pcm_startat_clock_type_t clock_type, snd_htimestamp_t *current_time)
+{
+	assert(pcm);
+	if (CHECK_SANITY(! pcm->setup)) {
+		SNDMSG("PCM not set up");
+		return -EIO;
+	}
+	if (pcm->fast_ops->start_at_gettime) {
+		return pcm->fast_ops->start_at_gettime(pcm->fast_op_arg, clock_type, current_time);
+	}
+	return -EINVAL;
+}
+
+/**
  * \brief Stop a PCM dropping pending frames
  * \param pcm PCM handle
  * \return 0 on success otherwise a negative error code
@@ -6380,6 +6448,20 @@ snd_pcm_uframes_t snd_pcm_status_get_overrange(const snd_pcm_status_t *obj)
 }
 
 /**
+ * \brief Get status of a pending start_at timer, if any.
+ * \param pending output param: 1 if start_at timer pending, 0 otherwise
+ * \param clock_type output param: if pending == 1, is updated with current start_at timer clock_type
+ * \param start_time output param: if pending == 1, is updated with current start_at timer start_time
+ */
+void snd_pcm_status_get_startat_state(const snd_pcm_status_t *obj, int *pending, snd_pcm_startat_clock_type_t *clock_type, snd_htimestamp_t *start_time)
+{
+	assert(obj);
+	*pending = obj->start_at_pending;
+	*clock_type = obj->start_at_clock_type;
+	*start_time = obj->start_at_start_time;
+}
+
+/**
  * \brief get size of #snd_pcm_info_t
  * \return size in bytes
  */
-- 
1.9.1