fw_fcp: add variations of method for FCP transaction

In IEC 61883-1, FCP transaction consists of a pair of asynchronous
transaction, therefore three types of time stamp are available:

 a Asynchronous transaction for request of FCP transaction
    a.1 when the packet was sent for request subaction
    a.2 when the packet arrived for response subaction
 b Asynchronous transaction for response of FCP transaction
    b.1 when the packet arrived for request subaction
    b.2 when the packet was sent for response subaction

Current implementation of Hinawa.FwReq and Hinawa.FwResp make a.1, a.2
and b.1 available. This commit implements new variations of method with
time stamps for FCP transaction.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>

4 files changed, 95 insertions, 0 deletions

diff --git a/src/fw_fcp.c b/src/fw_fcp.c
index 9dcf2cb..b2d7a2b 100644
--- a/src/fw_fcp.c
+++ b/src/fw_fcp.c
@@ -290,6 +290,7 @@ static gboolean complete_command_transaction(HinawaFwFcp *self, const guint8 *cm
  * signal is emitted.
  *
  * Since: 2.1.
+ * Deprecated: 2.6: Use [method@FwFcp.command_with_tstamp], instead.
  */
 void hinawa_fw_fcp_command(HinawaFwFcp *self, const guint8 *cmd, gsize cmd_size,
 			   guint timeout_ms, GError **error)
@@ -302,6 +303,38 @@ void hinawa_fw_fcp_command(HinawaFwFcp *self, const guint8 *cmd, gsize cmd_size,
 	(void)complete_command_transaction(self, cmd, cmd_size, &tstamp_ptr, timeout_ms, error);
 }
 
+/**
+ * hinawa_fw_fcp_command_with_tstamp:
+ * @self: A [class@FwFcp].
+ * @cmd: (array length=cmd_size): An array with elements for request byte data. The value of this
+ *	 argument should point to the array and immutable.
+ * @cmd_size: The size of array for request in byte unit.
+ * @tstamp: (array fixed-size=2)(inout): The array with two elements for time stamps. The first
+ *	    element is for the isochronous cycle at which the request arrived. The second element
+ *	    is for the isochronous cycle at which the response was sent.
+ * @timeout_ms: The timeout to wait for response subaction of transaction for command frame.
+ * @error: A [struct@GLib.Error]. Error can be generated with four domains; Hinoko.FwNodeError and
+ *	   Hinoko.FwReqError.
+ *
+ * Transfer command frame for FCP. When receiving response frame for FCP, [signal@FwFcp::responded]
+ * signal is emitted.
+ *
+ * Each value of @tstamp is unsigned 16 bit integer including higher 3 bits for three low order bits
+ * of second field and the rest 13 bits for cycle field in the format of IEEE 1394 CYCLE_TIMER register.
+ *
+ * If the version of kernel ABI for Linux FireWire subsystem is less than 6, each element of @tstamp
+ * has invalid value (=G_MAXUINT16).
+ *
+ * Returns: TRUE if the overall operation finishes successfully, otherwise FALSE.
+ * Since: 2.6.
+ */
+gboolean hinawa_fw_fcp_command_with_tstamp(HinawaFwFcp *self, const guint8 *cmd, gsize cmd_size,
+					   guint **tstamp, guint timeout_ms, GError **error)
+{
+	// Finish transaction for command frame.
+	return complete_command_transaction(self, cmd, cmd_size, tstamp, timeout_ms, error);
+}
+
 struct waiter {
 	guint8 *frame;
 	guint frame_size;
@@ -425,6 +458,7 @@ end:
  * advance for the case.
  *
  * Since: 2.1.
+ * Deprecated: 2.6: Use [method@FwFcp.avc_transaction_with_tstamp], instead.
  */
 void hinawa_fw_fcp_avc_transaction(HinawaFwFcp *self, const guint8 *cmd, gsize cmd_size,
 				   guint8 *const *resp, gsize *resp_size, guint timeout_ms,
@@ -440,6 +474,57 @@ void hinawa_fw_fcp_avc_transaction(HinawaFwFcp *self, const guint8 *cmd, gsize c
 }
 
 /**
+ * hinawa_fw_fcp_avc_transaction_with_tstamp:
+ * @self: A [class@FwFcp].
+ * @cmd: (array length=cmd_size)(in): An array with elements for request byte data. The value of
+ *	 this argument should point to the array and immutable.
+ * @cmd_size: The size of array for request in byte unit.
+ * @resp: (array length=resp_size)(inout): An array with elements for response byte data. Callers
+ *	  should give it for buffer with enough space against the request since this library
+ *	  performs no reallocation. Due to the reason, the value of this argument should point to
+ *	  the pointer to the array and immutable. The content of array is mutable.
+ * @resp_size: The size of array for response in byte unit. The value of this argument should point to
+ *	       the numerical number and mutable.
+ * @tstamp: (array fixed-size=3)(inout): The array with three elements for time stamps. The first
+ *	    element is for the isochronous cycle at which the request was sent for the command of
+ *	    FCP transaction. The second element is for the isochronous cycle at which the response
+ *	    arrived for the command of FCP transaction. The third element is for the isochronous
+ *	    cycle at which the request was sent for the response of FCP transaction.
+ * @timeout_ms: The timeout to wait for response transaction since command transactions finishes.
+ * @error: A [struct@GLib.Error]. Error can be generated with four domains; Hinawa.FwNodeError,
+ *	   Hinawa.FwReqError, and Hinawa.FwFcpError.
+ *
+ * Finish the pair of asynchronous transaction for AV/C command and response transactions. The
+ * timeout_ms parameter is used to wait for response transaction since the command transaction is
+ * initiated, ignoring [property@FwFcp:timeout] property of instance. The timeout is not expanded in
+ * the case that AV/C INTERIM status is arrived, thus the caller should expand the timeout in
+ * advance for the case.
+ *
+ * Returns: TRUE if the overall operation finishes successfully, otherwise FALSE.
+ * Since: 2.1.
+ */
+gboolean hinawa_fw_fcp_avc_transaction_with_tstamp(HinawaFwFcp *self,
+				const guint8 *cmd, gsize cmd_size, guint8 **resp, gsize *resp_size,
+				guint **tstamp, guint timeout_ms, GError **error)
+{
+	struct waiter w;
+	gboolean result;
+
+	g_return_val_if_fail(tstamp != NULL && *tstamp != NULL, FALSE);
+
+	(*tstamp)[0] = G_MAXUINT;
+	(*tstamp)[1] = G_MAXUINT;
+
+	result = complete_avc_transaction(self, cmd, cmd_size, resp, resp_size, timeout_ms, &w,
+					  tstamp, error);
+
+	if (result)
+		(*tstamp)[2] = w.tstamp;
+
+	return result;
+}
+
+/**
  * hinawa_fw_fcp_transaction:
  * @self: A [class@FwFcp].
  * @req_frame: (array length=req_frame_size)(in): An array with elements for request byte data. The
diff --git a/src/fw_fcp.h b/src/fw_fcp.h
index 56659a1..fe777e6 100644
--- a/src/fw_fcp.h
+++ b/src/fw_fcp.h
@@ -58,10 +58,15 @@ void hinawa_fw_fcp_unbind(HinawaFwFcp *self);
 
 void hinawa_fw_fcp_command(HinawaFwFcp *self, const guint8 *cmd, gsize cmd_size,
 			   guint timeout_ms, GError **error);
+gboolean hinawa_fw_fcp_command_with_tstamp(HinawaFwFcp *self, const guint8 *cmd, gsize cmd_size,
+					   guint **tstamp, guint timeout_ms, GError **error);
 
 void hinawa_fw_fcp_avc_transaction(HinawaFwFcp *self, const guint8 *cmd, gsize cmd_size,
 				   guint8 *const *resp, gsize *resp_size, guint timeout_ms,
 				   GError **error);
+gboolean hinawa_fw_fcp_avc_transaction_with_tstamp(HinawaFwFcp *self, const guint8 *cmd,
+					gsize cmd_size, guint8 **resp, gsize *resp_size,
+					guint **tstamp, guint timeout_ms, GError **error);
 
 G_END_DECLS
 
diff --git a/src/hinawa.map b/src/hinawa.map
index aae19c5..f0d1d92 100644
--- a/src/hinawa.map
+++ b/src/hinawa.map
@@ -173,4 +173,7 @@ HINAWA_2_6_0 {
     "hinawa_fw_node_read_cycle_time";
 
     "hinawa_fw_req_transaction_with_tstamp_sync";
+
+    "hinawa_fw_fcp_command_with_tstamp";
+    "hinawa_fw_fcp_avc_transaction_with_tstamp";
 } HINAWA_2_5_0;
diff --git a/tests/fw-fcp b/tests/fw-fcp
index beb1177..2d601a4 100755
--- a/tests/fw-fcp
+++ b/tests/fw-fcp
@@ -20,7 +20,9 @@ methods = (
     'bind',
     'unbind',
     'command',
+    'command_with_tstamp',
     'avc_transaction',
+    'avc_transaction_with_tstamp',
 )
 vmethods = (
     'do_responded',