[PATCH 1/2] firewire: core: add kerneldoc for outbound transaction-related symbols

[Takashi Sakamoto]

The core provides helper functions and structures for initiating
asynchronous transactions.

Add kerneldoc comments for these symbols.

Signed-off-by: Takashi Sakamoto <o-takashi@xxxxxxxxxxxxx>
---
 Documentation/driver-api/firewire.rst |  3 ++
 drivers/firewire/core-transaction.c   |  2 +
 include/linux/firewire.h              | 61 +++++++++++++++++++++++++++
 3 files changed, 66 insertions(+)

diff --git a/Documentation/driver-api/firewire.rst b/Documentation/driver-api/firewire.rst
index 28a32410f7d2..e1120376a31c 100644
--- a/Documentation/driver-api/firewire.rst
+++ b/Documentation/driver-api/firewire.rst
@@ -37,6 +37,9 @@ Firewire device probing and sysfs interfaces
 Firewire core transaction interfaces
 ====================================
 
+.. kernel-doc:: include/linux/firewire.h
+   :identifiers: fw_transaction fw_transaction_callback_t fw_transaction_callback_with_tstamp_t
+		 fw_transaction_callback fw_send_request fw_send_request_with_tstamp
 .. kernel-doc:: drivers/firewire/core-transaction.c
     :export:
 
diff --git a/drivers/firewire/core-transaction.c b/drivers/firewire/core-transaction.c
index 33c4ea48c6c9..22cddb736289 100644
--- a/drivers/firewire/core-transaction.c
+++ b/drivers/firewire/core-transaction.c
@@ -396,6 +396,8 @@ __must_hold(&card->transactions.lock)
  * than when the request packet actually hits the wire.  On the other hand,
  * transaction completion and hence execution of @callback may happen even
  * before fw_send_request() returns.
+ *
+ * Context: Process context.
  */
 void __fw_send_request(struct fw_card *card, struct fw_transaction *t, int tcode,
 		int destination_id, int generation, int speed, unsigned long long offset,
diff --git a/include/linux/firewire.h b/include/linux/firewire.h
index b55c2fdd739d..f1cb7569eaa0 100644
--- a/include/linux/firewire.h
+++ b/include/linux/firewire.h
@@ -286,13 +286,62 @@ struct fw_request;
 
 typedef void (*fw_packet_callback_t)(struct fw_packet *packet,
 				     struct fw_card *card, int status);
+
+/**
+ * typedef fw_transaction_callback_t - Function to handle the result of outgoing transaction.
+ * @card: the interface to send the request at
+ * @rcode: the response code
+ * @data: the data for the response subaction
+ * @length: the length of data
+ * @callback_data: the data registered with this callback
+ *
+ * This callback is called from a workqueue in process context after the outgoing transaction is
+ * completed successfully or unsuccessfully.
+ *
+ * Among its parameters is the response code which is either one of the rcodes per IEEE 1394 or, in
+ * case of internal errors, the firewire-core specific %RCODE_SEND_ERROR. The other firewire-core
+ * specific rcodes (%RCODE_CANCELLED, %RCODE_BUSY, %RCODE_GENERATION, %RCODE_NO_ACK) denote
+ * transaction timeout, busy responder, stale request generation, or missing ACK respectively.
+ *
+ * Context: Process context.
+ */
 typedef void (*fw_transaction_callback_t)(struct fw_card *card, int rcode,
 					  void *data, size_t length,
 					  void *callback_data);
+
+/**
+ * typedef fw_transaction_callback_with_tstamp_t - Function to handle the result of outgoing
+ *						   transaction with hardware time stamps.
+ * @card: the interface to send the request at
+ * @rcode: the response code
+ * @request_tstamp: the time stamp at which the request subaction finished
+ * @response_tstamp: the time stamp at which the response subaction finished
+ * @data: the data for the response subaction
+ * @length: the length of data
+ * @callback_data: the data registered with this callback
+ *
+ * This callback is called from a workqueue in process context after the outgoing transaction is
+ * completed successfully or unsuccessfully.
+ *
+ * Among its parameters is the response code which is either one of the rcodes per IEEE 1394 or, in
+ * case of internal errors, the firewire-core specific %RCODE_SEND_ERROR. The other firewire-core
+ * specific rcodes (%RCODE_CANCELLED, %RCODE_BUSY, %RCODE_GENERATION, %RCODE_NO_ACK) denote
+ * transaction timeout, busy responder, stale request generation, or missing ACK respectively.
+ *
+ * The timestamp consists of the low order 3 bits of second field and the full 13 bits of count
+ * field of isochronous cycle time register.
+ *
+ * Context: Process context.
+ */
 typedef void (*fw_transaction_callback_with_tstamp_t)(struct fw_card *card, int rcode,
 					u32 request_tstamp, u32 response_tstamp, void *data,
 					size_t length, void *callback_data);
 
+/**
+ * union fw_transaction_callback - A union to store the outgoing transaction callback.
+ * @without_tstamp: Callback without hardware timestamps.
+ * @with_tstamp: Callback with hardware timestamps.
+ */
 union fw_transaction_callback {
 	fw_transaction_callback_t without_tstamp;
 	fw_transaction_callback_with_tstamp_t with_tstamp;
@@ -352,7 +401,15 @@ struct fw_packet {
 	void *driver_data;
 };
 
+/**
+ * struct fw_transaction - A structure to hold outgoing transaction state.
+ *
+ * All structure members are for internal use only. Once passed to __fw_send_request(), this
+ * structure holds the state of an outgoing transaction. It must not be freed until the callback
+ * reports the transaction result.
+ */
 struct fw_transaction {
+	/* private: */
 	int node_id; /* The generation is implied; it is always the current. */
 	int tlabel;
 	struct list_head link;
@@ -429,6 +486,8 @@ void __fw_send_request(struct fw_card *card, struct fw_transaction *t, int tcode
  *
  * After the transaction is completed successfully or unsuccessfully, the @callback will be called
  * in process context.
+ *
+ * Context: Any context.
  */
 static inline void fw_send_request(struct fw_card *card, struct fw_transaction *t, int tcode,
 				   int destination_id, int generation, int speed,
@@ -461,6 +520,8 @@ static inline void fw_send_request(struct fw_card *card, struct fw_transaction *
  *
  * After the transaction is completed successfully or unsuccessfully, the @callback will be called
  * in process context.
+ *
+ * Context: Any context.
  */
 static inline void fw_send_request_with_tstamp(struct fw_card *card, struct fw_transaction *t,
 	int tcode, int destination_id, int generation, int speed, unsigned long long offset,
-- 
2.53.0