[PATCH v3 0/5] FireWire: clean up kernel-doc, add Documentation chapter

[PATCH v3 0/5] FireWire: clean up kernel-doc, add Documentation chapter

[Randy Dunlap]

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(-)

[PATCH v3 0/5] FireWire: clean up kernel-doc, add Documentation chapter

[Randy Dunlap]

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

[Randy Dunlap]

From: Randy Dunlap <rdunlap@infradead.org>

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.

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Stefan Richter <stefanr@s5r6.in-berlin.de>
Cc: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Cc: linux-doc@vger.kernel.org
Cc: linux-scsi@vger.kernel.org
Cc: Randy Dunlap <rdunlap@infradead.org>
Cc: Andrew Morton <akpm@linux-foundation.org>
Cc: "James E.J. Bottomley" <jejb@linux.vnet.ibm.com>
Cc: "Martin K. Petersen" <martin.petersen@oracle.com>
Cc: Jonathan Corbet <corbet@lwn.net>
---
 include/uapi/linux/firewire-cdev.h |   22 ++++++++++++++--------
 1 file changed, 14 insertions(+), 8 deletions(-)

--- linux-next-20180904.orig/include/uapi/linux/firewire-cdev.h
+++ linux-next-20180904/include/uapi/linux/firewire-cdev.h
@@ -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.

[PATCH v4 1/5] FireWire: clean up firewire-cdev.h kernel-doc

[Randy Dunlap]

From: Randy Dunlap <rdunlap@infradead.org>

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.

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Stefan Richter <stefanr@s5r6.in-berlin.de>
Cc: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Cc: linux-doc@vger.kernel.org
Cc: linux-scsi@vger.kernel.org
Cc: Randy Dunlap <rdunlap@infradead.org>
Cc: Andrew Morton <akpm@linux-foundation.org>
Cc: "James E.J. Bottomley" <jejb@linux.vnet.ibm.com>
Cc: "Martin K. Petersen" <martin.petersen@oracle.com>
Cc: Jonathan Corbet <corbet@lwn.net>
---
 include/uapi/linux/firewire-cdev.h |   22 ++++++++++++++--------
 1 file changed, 14 insertions(+), 8 deletions(-)

--- linux-next-20180904.orig/include/uapi/linux/firewire-cdev.h
+++ linux-next-20180904/include/uapi/linux/firewire-cdev.h
@@ -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

[Randy Dunlap]

From: Randy Dunlap <rdunlap@infradead.org>

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.

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Stefan Richter <stefanr@s5r6.in-berlin.de>
Cc: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Cc: linux-doc@vger.kernel.org
Cc: linux-scsi@vger.kernel.org
Cc: Randy Dunlap <rdunlap@infradead.org>
Cc: Andrew Morton <akpm@linux-foundation.org>
Cc: "James E.J. Bottomley" <jejb@linux.vnet.ibm.com>
Cc: "Martin K. Petersen" <martin.petersen@oracle.com>
Cc: Jonathan Corbet <corbet@lwn.net>
---
 drivers/firewire/core-iso.c |    7 +++++++
 1 file changed, 7 insertions(+)

--- linux-next-20180904.orig/drivers/firewire/core-iso.c
+++ linux-next-20180904/drivers/firewire/core-iso.c
@@ -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.

[PATCH v4 2/5] FireWire: clean up core-iso.c kernel-doc

[Randy Dunlap]

From: Randy Dunlap <rdunlap@infradead.org>

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.

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Stefan Richter <stefanr@s5r6.in-berlin.de>
Cc: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Cc: linux-doc@vger.kernel.org
Cc: linux-scsi@vger.kernel.org
Cc: Randy Dunlap <rdunlap@infradead.org>
Cc: Andrew Morton <akpm@linux-foundation.org>
Cc: "James E.J. Bottomley" <jejb@linux.vnet.ibm.com>
Cc: "Martin K. Petersen" <martin.petersen@oracle.com>
Cc: Jonathan Corbet <corbet@lwn.net>
---
 drivers/firewire/core-iso.c |    7 +++++++
 1 file changed, 7 insertions(+)

--- linux-next-20180904.orig/drivers/firewire/core-iso.c
+++ linux-next-20180904/drivers/firewire/core-iso.c
@@ -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

[Randy Dunlap]

From: Randy Dunlap <rdunlap@infradead.org>

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.

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Stefan Richter <stefanr@s5r6.in-berlin.de>
Cc: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Cc: linux-doc@vger.kernel.org
Cc: linux-scsi@vger.kernel.org
Cc: Randy Dunlap <rdunlap@infradead.org>
Cc: Andrew Morton <akpm@linux-foundation.org>
Cc: "James E.J. Bottomley" <jejb@linux.vnet.ibm.com>
Cc: "Martin K. Petersen" <martin.petersen@oracle.com>
Cc: Jonathan Corbet <corbet@lwn.net>
---
 drivers/firewire/core-transaction.c |   10 ++++++++++
 1 file changed, 10 insertions(+)

--- linux-next-20180904.orig/drivers/firewire/core-transaction.c
+++ linux-next-20180904/drivers/firewire/core-transaction.c
@@ -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)
 {

[PATCH v4 3/5] FireWire: clean up core-transaction.c kernel-doc

[Randy Dunlap]

From: Randy Dunlap <rdunlap@infradead.org>

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.

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Stefan Richter <stefanr@s5r6.in-berlin.de>
Cc: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Cc: linux-doc@vger.kernel.org
Cc: linux-scsi@vger.kernel.org
Cc: Randy Dunlap <rdunlap@infradead.org>
Cc: Andrew Morton <akpm@linux-foundation.org>
Cc: "James E.J. Bottomley" <jejb@linux.vnet.ibm.com>
Cc: "Martin K. Petersen" <martin.petersen@oracle.com>
Cc: Jonathan Corbet <corbet@lwn.net>
---
 drivers/firewire/core-transaction.c |   10 ++++++++++
 1 file changed, 10 insertions(+)

--- linux-next-20180904.orig/drivers/firewire/core-transaction.c
+++ linux-next-20180904/drivers/firewire/core-transaction.c
@@ -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

[Randy Dunlap]

From: Randy Dunlap <rdunlap@infradead.org>

Add a basic Firewire/IEEE 1394 driver API chapter to the Linux
kernel documentation.

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Stefan Richter <stefanr@s5r6.in-berlin.de>
Cc: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Cc: linux-doc@vger.kernel.org
Cc: linux-scsi@vger.kernel.org
Cc: Randy Dunlap <rdunlap@infradead.org>
Cc: Andrew Morton <akpm@linux-foundation.org>
Cc: "James E.J. Bottomley" <jejb@linux.vnet.ibm.com>
Cc: "Martin K. Petersen" <martin.petersen@oracle.com>
Cc: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/driver-api/firewire.rst |   33 ++++++++++++++++++++++++
 Documentation/driver-api/index.rst    |    1 
 2 files changed, 34 insertions(+)

--- /dev/null
+++ linux-next-20180904/Documentation/driver-api/firewire.rst
@@ -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:
+
--- linux-next-20180904.orig/Documentation/driver-api/index.rst
+++ linux-next-20180904/Documentation/driver-api/index.rst
@@ -29,6 +29,7 @@ available subsections can be seen below.
    iio/index
    input
    usb/index
+   firewire
    pci
    spi
    i2c

[PATCH v4 4/5] FireWire: add a Documentation driver-api chapter

[Randy Dunlap]

From: Randy Dunlap <rdunlap@infradead.org>

Add a basic Firewire/IEEE 1394 driver API chapter to the Linux
kernel documentation.

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Stefan Richter <stefanr@s5r6.in-berlin.de>
Cc: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Cc: linux-doc@vger.kernel.org
Cc: linux-scsi@vger.kernel.org
Cc: Randy Dunlap <rdunlap@infradead.org>
Cc: Andrew Morton <akpm@linux-foundation.org>
Cc: "James E.J. Bottomley" <jejb@linux.vnet.ibm.com>
Cc: "Martin K. Petersen" <martin.petersen@oracle.com>
Cc: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/driver-api/firewire.rst |   33 ++++++++++++++++++++++++
 Documentation/driver-api/index.rst    |    1 
 2 files changed, 34 insertions(+)

--- /dev/null
+++ linux-next-20180904/Documentation/driver-api/firewire.rst
@@ -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:
+
--- linux-next-20180904.orig/Documentation/driver-api/index.rst
+++ linux-next-20180904/Documentation/driver-api/index.rst
@@ -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

[Randy Dunlap]

From: Takashi Sakamoto <o-takashi@sakamocchi.jp>

Replace the Introduction section's TBD with some useful overview text.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Stefan Richter <stefanr@s5r6.in-berlin.de>
Cc: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Cc: linux-doc@vger.kernel.org
Cc: linux-scsi@vger.kernel.org
Cc: Randy Dunlap <rdunlap@infradead.org>
Cc: Andrew Morton <akpm@linux-foundation.org>
Cc: "James E.J. Bottomley" <jejb@linux.vnet.ibm.com>
Cc: "Martin K. Petersen" <martin.petersen@oracle.com>
Cc: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/driver-api/firewire.rst |   17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

--- linux-next-20180904.orig/Documentation/driver-api/firewire.rst
+++ linux-next-20180904/Documentation/driver-api/firewire.rst
@@ -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:
 

[PATCH v4 5/5] FireWire: add driver-api Introduction section

[Randy Dunlap]

From: Takashi Sakamoto <o-takashi@sakamocchi.jp>

Replace the Introduction section's TBD with some useful overview text.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Stefan Richter <stefanr@s5r6.in-berlin.de>
Cc: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Cc: linux-doc@vger.kernel.org
Cc: linux-scsi@vger.kernel.org
Cc: Randy Dunlap <rdunlap@infradead.org>
Cc: Andrew Morton <akpm@linux-foundation.org>
Cc: "James E.J. Bottomley" <jejb@linux.vnet.ibm.com>
Cc: "Martin K. Petersen" <martin.petersen@oracle.com>
Cc: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/driver-api/firewire.rst |   17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

--- linux-next-20180904.orig/Documentation/driver-api/firewire.rst
+++ linux-next-20180904/Documentation/driver-api/firewire.rst
@@ -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

Re: [PATCH v3 0/5] FireWire: clean up kernel-doc, add Documentation chapter

[Jonathan Corbet]

On Tue,  4 Sep 2018 17:02:20 -0700
Randy Dunlap <rd.dunlab@gmail.com> 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.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.

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

Re: [PATCH v3 0/5] FireWire: clean up kernel-doc, add Documentation chapter

[Jonathan Corbet]

On Tue,  4 Sep 2018 17:02:20 -0700
Randy Dunlap <rd.dunlab@gmail.com> 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.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.

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

Re: [PATCH v3 0/5] FireWire: clean up kernel-doc, add Documentation chapter

[Stefan Richter]

On Sep 06 Jonathan Corbet wrote:
> On Tue,  4 Sep 2018 17:02:20 -0700
> Randy Dunlap <rd.dunlab@gmail.com> wrote:
> > [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
[...]
> > 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.
-- 
Stefan Richter
-======---=- =--= -====
http://arcgraph.de/sr/

Re: [PATCH v3 0/5] FireWire: clean up kernel-doc, add Documentation chapter

[Stefan Richter]

On Sep 06 Jonathan Corbet wrote:
> On Tue,  4 Sep 2018 17:02:20 -0700
> Randy Dunlap <rd.dunlab@gmail.com> wrote:
> > [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
[...]
> > 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.
-- 
Stefan Richter
-======---=- =--= -====
http://arcgraph.de/sr/