From aa7f13e25c8003b54726b6e1339ee0fa8a2e99a8 Mon Sep 17 00:00:00 2001 From: Takashi Sakamoto Date: Tue, 13 Oct 2026 20:15:09 +0900 Subject: [PATCH] firewire: core: add kerneldoc for inbound transaction-related symbols The core provides helper functions and structures for handling transaction requests to local address regions. Add kerneldoc comments for these symbols. Link: https://lore.kernel.org/r/20261013111509.612518-3-o-takashi@sakamocchi.jp Signed-off-by: Takashi Sakamoto --- 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 b866c8572392..5038a10f0717 100644 --- a/drivers/firewire/core-transaction.c +++ b/drivers/firewire/core-transaction.c @@ -623,6 +623,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); @@ -658,21 +664,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, @@ -714,13 +719,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) { @@ -955,8 +960,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;