Add raw1394_read_cycle_timer_and_clock() API

This is an extension relative to raw1394_read_cycle_timer().
It lets the client choose a system clock other than CLOCK_REALTIME.

Use case: http://subversion.ffado.org/ticket/242

The underlying ioctl supports reading the system clock with nanoseconds
resolution.  The new libraw1394 call sticks with microseconds resolution
though.  This makes transition from (or parallel use with)
raw1394_read_cycle_timer() easier.  Besides, the call itself takes longer
than a  microsecond, primarily due to a costly MMIO read (on many
controllers even three or more MMIO reads).

Unit tests with CLOCK_MONOTONIC and CLOCK_MONOTONIC_RAW are added to
testlibraw as well.

Signed-off-by: Stefan Richter <stefanr@s5r6.in-berlin.de>

src/dispatch.c

@@ -791,3 +791,19 @@ int raw1394_read_cycle_timer(raw1394handle_t handle,
 		return ieee1394_read_cycle_timer(handle->mode.ieee1394,
 			cycle_timer, local_time);
 }
+
+int raw1394_read_cycle_timer_and_clock(raw1394handle_t handle,
+	u_int32_t *cycle_timer, u_int64_t *local_time, clockid_t clk_id)
+{
+	if (!handle) {
+		errno = EINVAL;
+		return -1;
+	}
+	if (handle->is_fw)
+		return fw_read_cycle_timer_and_clock(handle->mode.fw,
+			cycle_timer, local_time, clk_id);
+	else {
+		errno = ENOSYS;
+		return -1;
+	}
+}

src/fw-iso.c

@@ -648,8 +648,8 @@ void fw_iso_shutdown(fw_handle_t handle)
 	handle->iso.fd = -1;
 }
 
-int fw_read_cycle_timer(fw_handle_t handle,
+int fw_read_cycle_timer(fw_handle_t handle, u_int32_t *cycle_timer,
-			u_int32_t *cycle_timer, u_int64_t *local_time)
+			  u_int64_t *local_time)
 {
 	int err;
 	struct fw_cdev_get_cycle_timer ctr = { 0 };
@@ -661,3 +661,18 @@ int fw_read_cycle_timer(fw_handle_t handle,
 	}
 	return err;
 }
+
+int fw_read_cycle_timer_and_clock(fw_handle_t handle, u_int32_t *cycle_timer,
+			  u_int64_t *local_time, clockid_t clk_id)
+{
+	int err;
+	struct fw_cdev_get_cycle_timer2 ctr = {.clk_id = clk_id};
+
+	err = ioctl(handle->ioctl_fd, FW_CDEV_IOC_GET_CYCLE_TIMER2, &ctr);
+	if (!err) {
+		*cycle_timer = ctr.cycle_timer;
+		*local_time  = ctr.tv_sec * 1000000ULL +
+			       ctr.tv_nsec / 1000;
+	}
+	return err;
+}

src/fw.h

@@ -251,7 +251,9 @@ int fw_iso_recv_unlisten_channel(fw_handle_t handle,
 int fw_iso_recv_set_channel_mask(fw_handle_t handle, u_int64_t mask);
 void fw_iso_stop(fw_handle_t handle);
 void fw_iso_shutdown(fw_handle_t handle);
-int fw_read_cycle_timer(fw_handle_t handle,
+int fw_read_cycle_timer(fw_handle_t handle, u_int32_t *cycle_timer,
-			u_int32_t *cycle_timer, u_int64_t *local_time);
+			  u_int64_t *local_time);
+int fw_read_cycle_timer_and_clock(fw_handle_t handle, u_int32_t *cycle_timer,
+			  u_int64_t *local_time, clockid_t clk_id);
 
 #endif

src/raw1394.h

@@ -14,6 +14,7 @@
 #define _LIBRAW1394_RAW1394_H
 
 #include <sys/types.h>
+#include <time.h> /* for clockid_t */
 
 #define RAW1394_ARM_READ  1
 #define RAW1394_ARM_WRITE 2
@@ -334,7 +335,22 @@ void raw1394_iso_shutdown(raw1394handle_t handle);
  * @cycle_timer: buffer for Isochronous Cycle Timer
  * @local_time: buffer for local system time in microseconds since Epoch
  *
- * Simultaneously reads the cycle timer register together with the system clock.
+ * Same as raw1394_read_cycle_timer_and_clock() with clk_id = CLOCK_REALTIME,
+ * i.e. the non-monotonic system-wide clock.
+ *
+ * History: New function in libraw1394 v1.3.0.
+ **/
+int raw1394_read_cycle_timer(raw1394handle_t handle,
+			     u_int32_t *cycle_timer, u_int64_t *local_time);
+
+/**
+ * raw1394_read_cycle_timer_and_clock - get the current value of the cycle timer
+ * @handle: libraw1394 handle
+ * @cycle_timer: buffer for Isochronous Cycle Timer
+ * @local_time: buffer for local system time in microseconds
+ * @clk_id: clock from which to get the system time
+ *
+ * Simultaneously reads the cycle timer register together with a system clock.
  *
  * Format of @cycle_timer, from MSB to LSB: 7 bits cycleSeconds (seconds, or
  * number of cycleCount rollovers), 13 bits cycleCount (isochronous cycles, or
@@ -342,10 +358,20 @@ void raw1394_iso_shutdown(raw1394handle_t handle);
  * provided on some hardware). The union of cycleSeconds and cycleCount is the
  * current cycle number. The nominal duration of a cycle is 125 microseconds.
  *
+ * @clk_id chooses the system clock as in the clock_gettime() function.
+ * At least the clocks CLOCK_REALTIME, CLOCK_MONOTONIC, and CLOCK_MONOTONIC_RAW
+ * are supported by the underlying kernel call.
+ *
+ * In case of CLOCK_REALTIME, @local_time are microseconds since the Epoch.
+ * CLOCK_REALTIME is subject to resets; CLOCK_MONOTONIC is subject to gradual
+ * adjustments; CLOCK_MONOTONIC_RAW is the bare hardware clock.
+ *
  * Returns: the error code of the ioctl, or 0 if successful.
+ *
+ * History: New function in libraw1394 v2.1.0.
  **/
-int raw1394_read_cycle_timer(raw1394handle_t handle,
+int raw1394_read_cycle_timer_and_clock(raw1394handle_t handle,
-                             u_int32_t *cycle_timer, u_int64_t *local_time);
+	u_int32_t *cycle_timer, u_int64_t *local_time, clockid_t clk_id);
 
 typedef int raw1394_errcode_t;
 #define raw1394_make_errcode(ack, rcode) (((ack) << 16) | rcode)

tools/testlibraw.c

@@ -194,12 +194,33 @@ read_cycle_timer(raw1394handle_t handle)
 		perror("\n  - raw1394_read_cycle_timer failed with error");
 		return;
 	}
-
 	printf("\n  - cycle timer: %d seconds, %d cycles, %d sub-cycles\n",
 	       ct >> 25, (ct >> 12) & 0x1fff, ct & 0xfff);
 	seconds = local_time / 1000000;
-	printf("    local time: %lld us = %s",
+	printf("    local time from CLOCK_REALTIME: %lld us = %s",
 	       (unsigned long long)local_time, ctime(&seconds));
+
+	retval = raw1394_read_cycle_timer_and_clock(handle, &ct, &local_time,
+						    CLOCK_MONOTONIC);
+	if (retval < 0) {
+		perror("\n    raw1394_read_cycle_timer_and_clock failed with error");
+		return;
+	}
+	printf("    cycle timer: %d seconds, %d cycles, %d sub-cycles\n",
+	       ct >> 25, (ct >> 12) & 0x1fff, ct & 0xfff);
+	printf("    local time from CLOCK_MONOTONIC: %lld us\n",
+	       (unsigned long long)local_time);
+
+	retval = raw1394_read_cycle_timer_and_clock(handle, &ct, &local_time,
+						    CLOCK_MONOTONIC_RAW);
+	if (retval < 0) {
+		perror("\n    raw1394_read_cycle_timer_and_clock failed with error");
+		return;
+	}
+	printf("    cycle timer: %d seconds, %d cycles, %d sub-cycles\n",
+	       ct >> 25, (ct >> 12) & 0x1fff, ct & 0xfff);
+	printf("    local time from CLOCK_MONOTONIC_RAW: %lld us\n",
+	       (unsigned long long)local_time);
 }
 
 int test_card(int card)