FireWire: clean up kernel-doc, add Documentation chapter
Subsystems (3)
v3 cover FireWire: clean up kernel-doc, add Documentation chapter
This patch series cleans up kernel-doc warnings in several FireWire source files and then adds a Documentation driver-api chapter for FireWire.
[PATCH v4 1/5] FireWire: clean up firewire-cdev.h kernel-doc [PATCH v4 2/5] FireWire: clean up core-iso.c kernel-doc [PATCH v4 3/5] FireWire: clean up core-transaction.c kernel-doc [PATCH v4 4/5] FireWire: add a Documentation driver-api chapter [PATCH v4 5/5] FireWire: add driver-api Introduction section
The only changes in v4 are (a) respin against current -next and
(b) add more Cc:s so that someone will please merge the series.(*)
I think that Jon is the best choice to merge this series, but someone please do so. It has already missed 2 merge windows.
(*): Stefan hasn't replied to patches in the linux1394-devel mailing list recently. E.g., see:
https://sourceforge.net/p/linux1394/mailman/message/36406886/
Documentation/driver-api/firewire.rst | 50 +++++++++++++++++++++++- Documentation/driver-api/index.rst | 1 drivers/firewire/core-iso.c | 7 +++ drivers/firewire/core-transaction.c | 10 ++++ include/uapi/linux/firewire-cdev.h | 22 ++++++---- 5 files changed, 81 insertions(+), 9 deletions(-)
------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most engaging tech sites, Slashdot.org! http://sdm.link/slashdot
PATCH v4 1/5 FireWire: clean up firewire-cdev.h kernel-doc
From: Randy Dunlap <[email protected]>
Clean up kernel-doc warnings in <linux/firewire-cdev.h> so that it can be added to a Firewire/IEEE 1394 driver-api chapter without adding lots of noisy warnings to the documentation build.
--- include/uapi/linux/firewire-cdev.h | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-)
include/uapi/linux/firewire-cdev.h +14 -8
@@ -47,11 +47,11 @@#define FW_CDEV_EVENT_ISO_INTERRUPT_MULTICHANNEL 0x09/** -* struct fw_cdev_event_common - Common part of all fw_cdev_event_ types +* struct fw_cdev_event_common - Common part of all fw_cdev_event_* types * @closure: For arbitrary use by userspace -* @type: Discriminates the fw_cdev_event_ types +* @type: Discriminates the fw_cdev_event_* types * -* This struct may be used to access generic members of all fw_cdev_event_ +* This struct may be used to access generic members of all fw_cdev_event_* * types regardless of the specific type. * * Data passed in the @closure field for a request will be returned in the
@@ -123,7 +123,13 @@ struct fw_cdev_event_response {/** * struct fw_cdev_event_request - Old version of &fw_cdev_event_request2 +* @closure: See &fw_cdev_event_common; set by %FW_CDEV_IOC_ALLOCATE ioctl * @type: See &fw_cdev_event_common; always %FW_CDEV_EVENT_REQUEST +* @tcode: Transaction code of the incoming request +* @offset: The offset into the 48-bit per-node address space +* @handle: Reference to the kernel-side pending request +* @length: Data length, i.e. the request's payload size in bytes +* @data: Incoming data, if any * * This event is sent instead of &fw_cdev_event_request2 if the kernel or * the client implements ABI version <= 3. &fw_cdev_event_request lacks
@@ -353,7 +359,7 @@ struct fw_cdev_event_phy_packet { };/** -* union fw_cdev_event - Convenience union of fw_cdev_event_ types +* union fw_cdev_event - Convenience union of fw_cdev_event_* types * @common: Valid for all types * @bus_reset: Valid if @common.type == %FW_CDEV_EVENT_BUS_RESET * @response: Valid if @common.type == %FW_CDEV_EVENT_RESPONSE
@@ -735,7 +741,7 @@ struct fw_cdev_set_iso_channels {* @header: Header and payload in case of a transmit context. * * &struct fw_cdev_iso_packet is used to describe isochronous packet queues. -* Use the FW_CDEV_ISO_ macros to fill in @control. +* Use the FW_CDEV_ISO_* macros to fill in @control. * The @header array is empty in case of receive contexts. * * Context type %FW_CDEV_ISO_CONTEXT_TRANSMIT:
@@ -842,7 +848,7 @@ struct fw_cdev_queue_iso {* the %FW_CDEV_ISO_SYNC bit set * @tags: Tag filter bit mask. Only valid for isochronous reception. * Determines the tag values for which packets will be accepted. -* Use FW_CDEV_ISO_CONTEXT_MATCH_ macros to set @tags. +* Use FW_CDEV_ISO_CONTEXT_MATCH_* macros to set @tags. * @handle: Isochronous context handle within which to transmit or receive */ struct fw_cdev_start_iso {
@@ -1009,8 +1015,8 @@ struct fw_cdev_send_stream_packet {* on the same card as this device. After transmission, an * %FW_CDEV_EVENT_PHY_PACKET_SENT event is generated. * -* The payload @data[] shall be specified in host byte order. Usually, -* @data[1] needs to be the bitwise inverse of @data[0]. VersaPHY packets +* The payload @data\[\] shall be specified in host byte order. Usually, +* @data\[1\] needs to be the bitwise inverse of @data\[0\]. VersaPHY packets * are an exception to this rule. * * The ioctl is only permitted on device files which represent a local node.
------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most engaging tech sites, Slashdot.org! http://sdm.link/slashdot
PATCH v4 2/5 FireWire: clean up core-iso.c kernel-doc
In reply to Randy DunlapFrom: Randy Dunlap <[email protected]>
Clean up kernel-doc warnings in <drivers/firewire/core-iso.c> so that it can be added to a Firewire/IEEE 1394 driver-api chapter without adding lots of noisy warnings to the documentation build.
--- drivers/firewire/core-iso.c | 7 +++++++ 1 file changed, 7 insertions(+)
drivers/firewire/core-iso.c +7 -0
@@ -337,9 +337,16 @@ static void deallocate_channel(struct fw/** * fw_iso_resource_manage() - Allocate or deallocate a channel and/or bandwidth +* @card: card interface for this action +* @generation: bus generation +* @channels_mask: bitmask for channel allocation +* @channel: pointer for returning channel allocation result +* @bandwidth: pointer for returning bandwidth allocation result +* @allocate: whether to allocate (true) or deallocate (false) * * In parameters: card, generation, channels_mask, bandwidth, allocate * Out parameters: channel, bandwidth +* * This function blocks (sleeps) during communication with the IRM. * * Allocates or deallocates at most one channel out of channels_mask.
------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most engaging tech sites, Slashdot.org! http://sdm.link/slashdot
PATCH v4 3/5 FireWire: clean up core-transaction.c kernel-doc
In reply to Randy DunlapFrom: Randy Dunlap <[email protected]>
Clean up kernel-doc warnings in <drivers/firewire/core-transaction.c> so that it can be added to a Firewire/IEEE 1394 driver-api chapter without adding lots of noisy warnings to the documentation build.
--- drivers/firewire/core-transaction.c | 10 ++++++++++ 1 file changed, 10 insertions(+)
drivers/firewire/core-transaction.c +10 -0
@@ -410,6 +410,14 @@ static void transaction_callback(struct/** * fw_run_transaction() - send request and sleep until transaction is completed +* @card: card interface for this request +* @tcode: transaction code +* @destination_id: destination node ID, consisting of bus_ID and phy_ID +* @generation: bus generation in which request and response are valid +* @speed: transmission speed +* @offset: 48bit wide offset into destination's address space +* @payload: data payload for the request subaction +* @length: length of the payload, in bytes * * Returns the RCODE. See fw_send_request() for parameter documentation. * Unlike fw_send_request(), @data points to the payload of the request or/and
@@ -604,6 +612,7 @@ EXPORT_SYMBOL(fw_core_add_address_handle/** * fw_core_remove_address_handler() - unregister an address handler +* @handler: callback * * To be called in process context. *
@@ -828,6 +837,7 @@ EXPORT_SYMBOL(fw_send_response);/** * fw_get_request_speed() - returns speed at which the @request was received +* @request: firewire request data */ int fw_get_request_speed (struct fw_request *request) {
------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most engaging tech sites, Slashdot.org! http://sdm.link/slashdot
PATCH v4 4/5 FireWire: add a Documentation driver-api chapter
In reply to Randy DunlapFrom: Randy Dunlap <[email protected]>
Add a basic Firewire/IEEE 1394 driver API chapter to the Linux kernel documentation.
--- Documentation/driver-api/firewire.rst | 33 ++++++++++++++++++++++++ Documentation/driver-api/index.rst | 1 2 files changed, 34 insertions(+)
Documentation/driver-api/firewire.rst new file +33 -0
@@ -0,0 +1,33 @@ +=========================================== +Firewire (IEEE 1394) driver Interface Guide +=========================================== + +Introduction and Overview +========================= + +TBD + +Firewire char device data structures +==================================== + +.. kernel-doc:: include/uapi/linux/firewire-cdev.h + :internal: + +Firewire device probing and sysfs interfaces +============================================ + +.. kernel-doc:: drivers/firewire/core-device.c + :export: + +Firewire core transaction interfaces +==================================== + +.. kernel-doc:: drivers/firewire/core-transaction.c + :export: + +Firewire Isochronous I/O interfaces +=================================== + +.. kernel-doc:: drivers/firewire/core-iso.c + :export: +
Documentation/driver-api/index.rst +1 -0
@@ -29,6 +29,7 @@ available subsections can be seen below. iio/index input usb/index + firewire pci spi i2c
------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most engaging tech sites, Slashdot.org! http://sdm.link/slashdot
PATCH v4 5/5 FireWire: add driver-api Introduction section
In reply to Randy DunlapFrom: Takashi Sakamoto <[email protected]>
Replace the Introduction section's TBD with some useful overview text.
--- Documentation/driver-api/firewire.rst | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-)
Documentation/driver-api/firewire.rst +16 -1
@@ -5,17 +5,32 @@ Firewire (IEEE 1394) driver Interface Gu Introduction and Overview ========================= -TBD +The Linux FireWire subsystem adds some interfaces into the Linux system to + use/maintain+any resource on IEEE 1394 bus. + +The main purpose of these interfaces is to access address space on each node +on IEEE 1394 bus by ISO/IEC 13213 (IEEE 1212) procedure, and to control +isochronous resources on the bus by IEEE 1394 procedure. + +Two types of interfaces are added, according to consumers of the interface. A +set of userspace interfaces is available via `firewire character devices`. A set +of kernel interfaces is available via exported symbols in `firewire-core` module. Firewire char device data structures ==================================== +.. include:: /ABI/stable/firewire-cdev + :literal: + .. kernel-doc:: include/uapi/linux/firewire-cdev.h :internal: Firewire device probing and sysfs interfaces ============================================ +.. include:: /ABI/stable/sysfs-bus-firewire + :literal: + .. kernel-doc:: drivers/firewire/core-device.c :export:
------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most engaging tech sites, Slashdot.org! http://sdm.link/slashdot
Jonathan Corbet
maintainerQuoted 10 lines · On Tue, 4 Sep 2018 17:02:20 -0700 Randy Dunlap <[email protected]> wrote:
This patch series cleans up kernel-doc warnings in several FireWire source files and then adds a Documentation driver-api chapter for FireWire.
[PATCH v4 1/5] FireWire: clean up
firewire-cdev.hkernel-doc [PATCH v4 2/5] FireWire: clean upcore-iso.ckernel-doc [PATCH v4 3/5] FireWire: clean upcore-transaction.ckernel-doc [PATCH v4 4/5] FireWire: add a Documentation driver-api chapter [PATCH v4 5/5] FireWire: add driver-api Introduction section
Quoted 5 lines
The only changes in v4 are (a) respin against current -next and
(b) add more Cc:s so that someone will please merge the series.(*)I think that Jon is the best choice to merge this series, but someone please do so. It has already missed 2 merge windows.
I think this is the first time I've received this... Through the FireWire maintainer seems like the best path, but it seems that's not happening. The patches look good to me, so I've just applied them.
Thanks,
jon
------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most engaging tech sites, Slashdot.org! http://sdm.link/slashdot
Quoted 7 lines · On Sep 06 Jonathan Corbet wrote:
Quoted 5 lines · On Tue, 4 Sep 2018 17:02:20 -0700 Randy Dunlap <[email protected]> wrote:
[PATCH v4 1/5] FireWire: clean up
firewire-cdev.hkernel-doc [PATCH v4 2/5] FireWire: clean upcore-iso.ckernel-doc [PATCH v4 3/5] FireWire: clean upcore-transaction.ckernel-doc [PATCH v4 4/5] FireWire: add a Documentation driver-api chapter [PATCH v4 5/5] FireWire: add driver-api Introduction section
[...]
Quoted 6 lines
Quoted 2 lines
I think that Jon is the best choice to merge this series, but someone please do so. It has already missed 2 merge windows.
I think this is the first time I've received this... Through the FireWire maintainer seems like the best path, but it seems that's not happening. The patches look good to me, so I've just applied them.
Thanks for taking care of this. I only read superficially through the v1 posting and Takashi Sakamoto's initial responses; sorry to all for not following up on this then.
Signature · 3 lines
Stefan Richter -======---=- =--= -==== http://arcgraph.de/sr/