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

[Takashi Sakamoto]

The core provides helper functions and structures for handling
transaction requests to local address regions.

Add kerneldoc comments for these symbols.

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

diff --git a/Documentation/driver-api/firewire.rst b/Documentation/driver-api/firewire.rst
index e1120376a31c..695c5f6db045 100644
--- a/Documentation/driver-api/firewire.rst
+++ b/Documentation/driver-api/firewire.rst
@@ -40,6 +40,8 @@ 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
+		 fw_address_callback_t fw_address_handler fw_address_region
+
 .. kernel-doc:: drivers/firewire/core-transaction.c
     :export:
 
diff --git a/drivers/firewire/core-transaction.c b/drivers/firewire/core-transaction.c
index 22cddb736289..0d577fff1577 100644
--- a/drivers/firewire/core-transaction.c
+++ b/drivers/firewire/core-transaction.c
@@ -619,6 +619,12 @@ static struct fw_address_handler *lookup_enclosing_address_handler(
 static DEFINE_SPINLOCK(address_handler_list_lock);
 static LIST_HEAD(address_handler_list);
 
+/**
+ * var fw_high_memory_region - An address range for high memory.
+ *
+ * Represents an address range within the Middle Address Space defined by the 1394 OHCI
+ * specification.
+ */
 const struct fw_address_region fw_high_memory_region =
 	{ .start = FW_MAX_PHYSICAL_RANGE, .end = 0xffffe0000000ULL, };
 EXPORT_SYMBOL(fw_high_memory_region);
@@ -654,21 +660,20 @@ static int put_address_handler(struct fw_address_handler *handler)
 }
 
 /**
- * fw_core_add_address_handler() - register for incoming requests
- * @handler:	callback
- * @region:	region in the IEEE 1212 node space address range
+ * fw_core_add_address_handler() - register a handler for incoming transaction requests to a
+ *				   specific address region.
+ * @handler: The handler including a callback function for an incoming transaction request.
+ * @region: The region in the IEEE 1212 node space address range.
  *
- * region->start, ->end, and handler->length have to be quadlet-aligned.
+ * &fw_address_handler.length, &fw_address_region.start, and &fw_address_region.end are specified
+ * in bytes and must be multiples of a quadlet. &fw_address_handler.offset is available after
+ * successful registration.
  *
  * When a request is received that falls within the specified address range, the specified callback
- * is invoked.  The parameters passed to the callback give the details of the particular request.
- *
- * The start offset of the handler's address region is determined by
- * fw_core_add_address_handler() and is returned in handler->offset.
+ * is invoked. The parameters passed to the callback give the details of the particular request.
  *
  * Address allocations are exclusive, except for the FCP registers.
  *
- * Context: Process context.
  * Returns: 0 on success, non-zero otherwise.
  */
 int fw_core_add_address_handler(struct fw_address_handler *handler,
@@ -710,13 +715,13 @@ int fw_core_add_address_handler(struct fw_address_handler *handler,
 EXPORT_SYMBOL(fw_core_add_address_handler);
 
 /**
- * fw_core_remove_address_handler() - unregister an address handler
- * @handler: callback
+ * fw_core_remove_address_handler() - unregister an address handler for an incoming transaction
+ *				      request.
+ * @handler: The registered handler.
  *
- * To be called in process context.
+ * After this function returns, the handler's callback is guaranteed not to be running on any CPU.
  *
- * When fw_core_remove_address_handler() returns, @handler->callback() is
- * guaranteed to not run on any CPU anymore.
+ * Context: Process context.
  */
 void fw_core_remove_address_handler(struct fw_address_handler *handler)
 {
@@ -951,8 +956,8 @@ __must_not_hold(&card->split_timeout.lock)
  * @request:	firewire request data for the transaction.
  * @rcode:	response code to send.
  *
- * Submit a response packet into the asynchronous response transmission queue. The @request
- * is going to be released when the transmission successfully finishes later.
+ * Submit a response packet into the asynchronous response transmission queue. The contents of
+ * @request are opaque to the caller. The @request is released when the transmission finishes.
  */
 void fw_send_response(struct fw_card *card,
 		      struct fw_request *request, int rcode)
diff --git a/include/linux/firewire.h b/include/linux/firewire.h
index f1cb7569eaa0..9c563fbdbbf0 100644
--- a/include/linux/firewire.h
+++ b/include/linux/firewire.h
@@ -348,7 +348,7 @@ union fw_transaction_callback {
 };
 
 /**
- * typedef fw_address_callback_t - Function to handle the request of the asynchronous transaction.
+ * typedef fw_address_callback_t - Function to handle the request of the incoming transaction.
  * @card: the card instance which receives the request
  * @request: the request instance.
  * @tcode: the transaction code
@@ -362,8 +362,9 @@ union fw_transaction_callback {
  *
  * This callback handles an inbound request subaction.
  *
- * The callback is responsible that fw_send_response() is called on the @request, except for FCP
- * registers for which the core takes care of that.
+ * The contents of @request are opaque to the callback. The callback is responsible for calling
+ * fw_send_response() for @request, except for FCP registers, for which the core handles the
+ * response.
  *
  * Context: Process context.
  */
@@ -434,18 +435,37 @@ struct fw_transaction {
 	u32 response_timestamp;
 };
 
+/**
+ * struct fw_address_handler - A handler for incoming transaction requests to a registered address
+ *			       region.
+ * @offset: The registered offset, available after successful registration.
+ * @length: The length of the address region in bytes, a multiple of a quadlet.
+ * @address_callback: Callback invoked when a transaction request is received for the registered
+ *		      address region.
+ * @callback_data: Data passed to @address_callback.
+ *
+ * This structure represents a handler registered to receive incoming asynchronous requests to a
+ * specific region of the address space on the local node.
+ */
 struct fw_address_handler {
 	u64 offset;
 	u64 length;
 	fw_address_callback_t address_callback;
 	void *callback_data;
 
-	// Only for core functions.
+	/* private: */
 	struct list_head link;
 	struct kref kref;
 	struct completion done;
 };
 
+/**
+ * struct fw_address_region - An address range.
+ * @start: The starting offset in bytes, a multiple of a quadlet.
+ * @end: The ending offset in bytes, a multiple of a quadlet.
+ *
+ * Represents a range of addresses in the local node's address space.
+ */
 struct fw_address_region {
 	u64 start;
 	u64 end;
-- 
2.53.0