* [PATCH 1/2] firewire: core: add kerneldoc for outbound transaction-related symbols
2026-10-13 11:15 [PATCH 0/2] firewire: core: Add kerneldoc for transaction-related symbols Takashi Sakamoto
@ 2026-10-13 11:15 ` Takashi Sakamoto
2026-10-14 2:27 ` Takashi Sakamoto
2026-10-13 11:15 ` [PATCH 2/2] firewire: core: add kerneldoc for inbound " Takashi Sakamoto
2026-10-14 2:28 ` [PATCH 0/2] firewire: core: Add kerneldoc for " Takashi Sakamoto
2 siblings, 1 reply; 5+ messages in thread
From: Takashi Sakamoto @ 2026-10-13 11:15 UTC (permalink / raw)
To: linux1394-devel; +Cc: linux-kernel
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
^ permalink raw reply [flat|nested] 5+ messages in thread* [PATCH 2/2] firewire: core: add kerneldoc for inbound transaction-related symbols
2026-10-13 11:15 [PATCH 0/2] firewire: core: Add kerneldoc for transaction-related symbols Takashi Sakamoto
2026-10-13 11:15 ` [PATCH 1/2] firewire: core: add kerneldoc for outbound " Takashi Sakamoto
@ 2026-10-13 11:15 ` Takashi Sakamoto
2026-10-14 2:28 ` [PATCH 0/2] firewire: core: Add kerneldoc for " Takashi Sakamoto
2 siblings, 0 replies; 5+ messages in thread
From: Takashi Sakamoto @ 2026-10-13 11:15 UTC (permalink / raw)
To: linux1394-devel; +Cc: linux-kernel
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
^ permalink raw reply [flat|nested] 5+ messages in thread