[PATCH 0/2] firewire: core: Add kerneldoc for transaction-related symbols

[PATCH 0/2] firewire: core: Add kerneldoc for transaction-related symbols

[Takashi Sakamoto]

The core provides helper functions and structures for handling outbound
and inbound asynchronous transactions, but some of the related symbols
lack sufficient kerneldoc comments.

Add kerneldoc comments for these symbols and document them in the FireWire
driver API documentation.

Takashi Sakamoto (2):
  firewire: core: add kerneldoc for outbound transaction-related symbols
  firewire: core: add kerneldoc for inbound transaction-related symbols

 Documentation/driver-api/firewire.rst |  5 ++
 drivers/firewire/core-transaction.c   | 39 +++++++-----
 include/linux/firewire.h              | 89 +++++++++++++++++++++++++--
 3 files changed, 113 insertions(+), 20 deletions(-)


base-commit: 74706ef1a0c26432ec4d19b540117f83e4b3d206
-- 
2.53.0

[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@sakamocchi.jp>
---
 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

[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@sakamocchi.jp>
---
 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

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

[Takashi Sakamoto]

On Tue, Oct 13, 2026 at 08:15:08PM +0900, Takashi Sakamoto wrote:
> The core provides helper functions and structures for initiating
> asynchronous transactions.
> 
> Add kerneldoc comments for these symbols.
> 
> Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
> ---
>  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/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,

The above should be "Context: Any context.". Let me correct it when merging.


Regards

Takashi Sakamoto

Re: [PATCH 0/2] firewire: core: Add kerneldoc for transaction-related symbols

[Takashi Sakamoto]

On Tue, Oct 13, 2026 at 08:15:07PM +0900, Takashi Sakamoto wrote:
> The core provides helper functions and structures for handling outbound
> and inbound asynchronous transactions, but some of the related symbols
> lack sufficient kerneldoc comments.
> 
> Add kerneldoc comments for these symbols and document them in the FireWire
> driver API documentation.
> 
> Takashi Sakamoto (2):
>   firewire: core: add kerneldoc for outbound transaction-related symbols
>   firewire: core: add kerneldoc for inbound transaction-related symbols
> 
>  Documentation/driver-api/firewire.rst |  5 ++
>  drivers/firewire/core-transaction.c   | 39 +++++++-----
>  include/linux/firewire.h              | 89 +++++++++++++++++++++++++--
>  3 files changed, 113 insertions(+), 20 deletions(-)

Applied to for-next branch, with a small fix for __fw_send_request() context.


Regards

Takashi Sakamoto