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

[PATCH v2 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 v3 1/5] FireWire: clean up firewire-cdev.h kernel-doc
[PATCH v3 2/5] FireWire: clean up core-iso.c kernel-doc
[PATCH v3 3/5] FireWire: clean up core-transaction.c kernel-doc
[PATCH v3 4/5] FireWire: add a Documentation driver-api chapter
[PATCH v3 5/5] FireWire: add driver-api Introduction section

 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(-)
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v3 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: linux1394-devel@lists.sourceforge.net
Cc: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Cc: linux-doc@vger.kernel.org
Cc: Randy Dunlap <rdunlap@infradead.org>
---
@linux-doc: The patch that adds Documentation/driver-api/firewire.rst
causes a warning in this header file, but I don't see where it is
coming from (this header file patch does not touch that area of the
file):

../include/uapi/linux/firewire-cdev.h:312: WARNING: Inline literal start-string without end-string.

 include/uapi/linux/firewire-cdev.h |   22 ++++++++++++++--------
 1 file changed, 14 insertions(+), 8 deletions(-)

--- linux-next-20180413.orig/include/uapi/linux/firewire-cdev.h
+++ linux-next-20180413/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.
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v3 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>
To: linux1394-devel@lists.sourceforge.net
Cc: Stefan Richter <stefanr@s5r6.in-berlin.de>
Cc: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Cc: linux-doc@vger.kernel.org
Cc: Randy Dunlap <rdunlap@infradead.org>
---
 drivers/firewire/core-iso.c |    7 +++++++
 1 file changed, 7 insertions(+)

--- linux-next-20180413.orig/drivers/firewire/core-iso.c
+++ linux-next-20180413/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.
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v3 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>
To: linux1394-devel@lists.sourceforge.net
Cc: Stefan Richter <stefanr@s5r6.in-berlin.de>
Cc: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Cc: linux-doc@vger.kernel.org
Cc: Randy Dunlap <rdunlap@infradead.org>
---
 drivers/firewire/core-transaction.c |   10 ++++++++++
 1 file changed, 10 insertions(+)

--- linux-next-20180413.orig/drivers/firewire/core-transaction.c
+++ linux-next-20180413/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)
 {
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v3 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>
To: linux1394-devel@lists.sourceforge.net
Cc: Stefan Richter <stefanr@s5r6.in-berlin.de>
Cc: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Cc: linux-doc@vger.kernel.org
Cc: Randy Dunlap <rdunlap@infradead.org>
---

v2: drop final blank line;
    in Cc:, change tab to space;

 Documentation/driver-api/firewire.rst |   32 ++++++++++++++++++++++++
 Documentation/driver-api/index.rst    |    1 
 2 files changed, 33 insertions(+)

--- /dev/null
+++ linux-next-20180413/Documentation/driver-api/firewire.rst
@@ -0,0 +1,32 @@
+===========================================
+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-20180413.orig/Documentation/driver-api/index.rst
+++ linux-next-20180413/Documentation/driver-api/index.rst
@@ -27,6 +27,7 @@ available subsections can be seen below.
    iio/index
    input
    usb/index
+   firewire
    pci
    spi
    i2c
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v3 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>
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
To: linux1394-devel@lists.sourceforge.net
Cc: Stefan Richter <stefanr@s5r6.in-berlin.de>
Cc: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Cc: linux-doc@vger.kernel.org
Cc: Randy Dunlap <rdunlap@infradead.org>
---
 Documentation/driver-api/firewire.rst |   18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

--- linux-next-20180413.orig/Documentation/driver-api/firewire.rst
+++ linux-next-20180413/Documentation/driver-api/firewire.rst
@@ -5,17 +5,33 @@ 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 the IEEE 1394 bus.
+
+The main purpose of these interfaces is to access address space on each node
+on the 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 the `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:
 
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Takashi Sakamoto]

Hi,

On Apr 14 2018 10:27, Randy Dunlap 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 v3 1/5] FireWire: clean up firewire-cdev.h kernel-doc
> [PATCH v3 2/5] FireWire: clean up core-iso.c kernel-doc
> [PATCH v3 3/5] FireWire: clean up core-transaction.c kernel-doc
> [PATCH v3 4/5] FireWire: add a Documentation driver-api chapter
> [PATCH v3 5/5] FireWire: add driver-api Introduction section
> 
>   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(-)

I reviewed all of the five patches.

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

We're on development cycle for v4.18. Your patchset will be merged into
mainline in next merge window by pull request from Stefan.


Thanks

Takashi Sakamoto
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Randy Dunlap]

On 04/15/2018 07:10 PM, Takashi Sakamoto wrote:
> Hi,
> 
> On Apr 14 2018 10:27, Randy Dunlap 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 v3 1/5] FireWire: clean up firewire-cdev.h kernel-doc
>> [PATCH v3 2/5] FireWire: clean up core-iso.c kernel-doc
>> [PATCH v3 3/5] FireWire: clean up core-transaction.c kernel-doc
>> [PATCH v3 4/5] FireWire: add a Documentation driver-api chapter
>> [PATCH v3 5/5] FireWire: add driver-api Introduction section
>>
>>   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(-)
> 
> I reviewed all of the five patches.
> 
> Reviewed-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
> 
> We're on development cycle for v4.18. Your patchset will be merged into
> mainline in next merge window by pull request from Stefan.

Stefan, are you around?

The merge window for v4.18 just closed today.

thanks,
-- 
~Randy
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Randy Dunlap]

On 06/16/2018 04:55 PM, Randy Dunlap wrote:
> On 04/15/2018 07:10 PM, Takashi Sakamoto wrote:
>> Hi,
>>
>> On Apr 14 2018 10:27, Randy Dunlap 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 v3 1/5] FireWire: clean up firewire-cdev.h kernel-doc
>>> [PATCH v3 2/5] FireWire: clean up core-iso.c kernel-doc
>>> [PATCH v3 3/5] FireWire: clean up core-transaction.c kernel-doc
>>> [PATCH v3 4/5] FireWire: add a Documentation driver-api chapter
>>> [PATCH v3 5/5] FireWire: add driver-api Introduction section
>>>
>>>   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(-)
>>
>> I reviewed all of the five patches.
>>
>> Reviewed-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
>>
>> We're on development cycle for v4.18. Your patchset will be merged into
>> mainline in next merge window by pull request from Stefan.
> 

Hi Stefan,

Do you plan to merge these Firewire documentation patches in the
current merge window?

thanks,
-- 
~Randy