Re: [PATCH] scsi_transport_srp: Fix kernel-doc warnings

2014-01-06 Thread Sebastian Riemer 
On 06.01.2014 07:39, Bart Van Assche wrote:
 On 01/05/14 21:39, Randy Dunlap wrote:
 On 01/05/14 01:13, Bart Van Assche wrote:
 The following command has been used to verify that the kernel-doc
 tool no longer complains about undocumented fields:

 scripts/kernel-doc -html drivers/scsi/scsi_transport_srp.c \
   include/scsi/scsi_transport_srp.h srp-transport-doc.html

 Thanks for the patch.
 I guess that your tree is different from mine.  Using 3.13-rc7, I still get
 3 warnings:

 Warning(drivers/scsi/scsi_transport_srp.c:620): No description found for 
 parameter 'scmd'
 Warning(drivers/scsi/scsi_transport_srp.c:688): No description found for 
 parameter 'rport'
 Warning(drivers/scsi/scsi_transport_srp.c:697): No description found for 
 parameter 'rport'

 I also had some trouble with the patch itself -- looks like some of its 
 longer
 lines were broken (split) by your mail app (I'm guessing).
 The first split line is marked below.
 
 Sorry but it seems like my e-mail client line-wrapped the patch. Does
 the attached patch work better ? The attached patch should be identical
 to what I posted except for the line wrapping. I do not see the warnings
 mentioned above - maybe these were introduced by the line wrapping ?

Hi Bart,

the patch you've attached works fine and looks good. Thanks!
Great work with the ib_srp code in 3.13 by the way!

Acked-by: Sebastian Riemer sebastian.rie...@profitbricks.com

Cheers,
Sebastian
--
To unsubscribe from this list: send the line unsubscribe linux-scsi in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] scsi_transport_srp: Fix kernel-doc warnings

2014-01-06 Thread Randy Dunlap 
On 01/05/14 22:39, Bart Van Assche wrote:
 On 01/05/14 21:39, Randy Dunlap wrote:
 On 01/05/14 01:13, Bart Van Assche wrote:
 The following command has been used to verify that the kernel-doc
 tool no longer complains about undocumented fields:

 scripts/kernel-doc -html drivers/scsi/scsi_transport_srp.c \
   include/scsi/scsi_transport_srp.h srp-transport-doc.html

 Thanks for the patch.
 I guess that your tree is different from mine.  Using 3.13-rc7, I still get
 3 warnings:

 Warning(drivers/scsi/scsi_transport_srp.c:620): No description found for 
 parameter 'scmd'
 Warning(drivers/scsi/scsi_transport_srp.c:688): No description found for 
 parameter 'rport'
 Warning(drivers/scsi/scsi_transport_srp.c:697): No description found for 
 parameter 'rport'

 I also had some trouble with the patch itself -- looks like some of its 
 longer
 lines were broken (split) by your mail app (I'm guessing).
 The first split line is marked below.
 
 Sorry but it seems like my e-mail client line-wrapped the patch. Does
 the attached patch work better ? The attached patch should be identical
 to what I posted except for the line wrapping. I do not see the warnings
 mentioned above - maybe these were introduced by the line wrapping ?

Yes, that patch works for me.  Thanks.

Acked-by: Randy Dunlap rdun...@infradead.org



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

[PATCH] scsi_transport_srp: Fix kernel-doc warnings

2014-01-05 Thread Bart Van Assche 
The following command has been used to verify that the kernel-doc
tool no longer complains about undocumented fields:

scripts/kernel-doc -html drivers/scsi/scsi_transport_srp.c \
  include/scsi/scsi_transport_srp.h srp-transport-doc.html

Signed-off-by: Bart Van Assche bvanass...@acm.org
Cc: David Dillow dillo...@ornl.gov
Cc: Vu Pham v...@mellanox.com
Cc: Sebastian Riemer sebastian.rie...@profitbricks.com
Cc: James Bottomley jbottom...@parallels.com
Cc: Randy Dunlap rdun...@infradead.org
---
 drivers/scsi/scsi_transport_srp.c | 12 
 include/scsi/scsi_transport_srp.h | 32 
 2 files changed, 40 insertions(+), 4 deletions(-)

diff --git a/drivers/scsi/scsi_transport_srp.c
b/drivers/scsi/scsi_transport_srp.c
index 2700a5a..96ffc46 100644
--- a/drivers/scsi/scsi_transport_srp.c
+++ b/drivers/scsi/scsi_transport_srp.c
@@ -64,6 +64,9 @@ static inline struct Scsi_Host *rport_to_shost(struct
srp_rport *r)
 
 /**
  * srp_tmo_valid() - check timeout combination validity
+ * @reconnect_delay: Reconnect delay in seconds.
+ * @fast_io_fail_tmo: Fast I/O fail timeout in seconds.
+ * @dev_loss_tmo: Device loss timeout in seconds.
  *
  * The combination of the timeout parameters must be such that SCSI
commands
  * are finished in a reasonable time. Hence do not allow the fast I/O fail
@@ -368,6 +371,7 @@ invalid:
 
 /**
  * srp_reconnect_work() - reconnect and schedule a new attempt if necessary
+ * @work: Work structure used for scheduling this operation.
  */
 static void srp_reconnect_work(struct work_struct *work)
 {
@@ -408,6 +412,7 @@ static void __rport_fail_io_fast(struct srp_rport
*rport)
 
 /**
  * rport_fast_io_fail_timedout() - fast I/O failure timeout handler
+ * @work: Work structure used for scheduling this operation.
  */
 static void rport_fast_io_fail_timedout(struct work_struct *work)
 {
@@ -426,6 +431,7 @@ static void rport_fast_io_fail_timedout(struct
work_struct *work)
 
 /**
  * rport_dev_loss_timedout() - device loss timeout handler
+ * @work: Work structure used for scheduling this operation.
  */
 static void rport_dev_loss_timedout(struct work_struct *work)
 {
@@ -488,6 +494,7 @@ static void __srp_start_tl_fail_timers(struct
srp_rport *rport)
 
 /**
  * srp_start_tl_fail_timers() - start the transport layer failure timers
+ * @rport: SRP target port.
  *
  * Start the transport layer fast I/O failure and device loss timers.
Do not
  * modify a timer that was already started.
@@ -502,6 +509,7 @@ EXPORT_SYMBOL(srp_start_tl_fail_timers);
 
 /**
  * scsi_request_fn_active() - number of kernel threads inside
scsi_request_fn()
+ * @shost: SCSI host for which to count the number of scsi_request_fn()
callers.
  */
 static int scsi_request_fn_active(struct Scsi_Host *shost)
 {
@@ -522,6 +530,7 @@ static int scsi_request_fn_active(struct Scsi_Host
*shost)
 
 /**
  * srp_reconnect_rport() - reconnect to an SRP target port
+ * @rport: SRP target port.
  *
  * Blocks SCSI command queueing before invoking reconnect() such that
  * queuecommand() won't be invoked concurrently with reconnect() from
outside
@@ -599,6 +608,7 @@ EXPORT_SYMBOL(srp_reconnect_rport);
 
 /**
  * srp_timed_out() - SRP transport intercept of the SCSI timeout EH
+ * @scmd: SCSI command.
  *
  * If a timeout occurs while an rport is in the blocked state, ask the SCSI
  * EH to continue waiting (BLK_EH_RESET_TIMER). Otherwise let the SCSI core
@@ -674,6 +684,7 @@ static int srp_host_match(struct attribute_container
*cont, struct device *dev)
 
 /**
  * srp_rport_get() - increment rport reference count
+ * @rport: SRP target port.
  */
 void srp_rport_get(struct srp_rport *rport)
 {
@@ -683,6 +694,7 @@ EXPORT_SYMBOL(srp_rport_get);
 
 /**
  * srp_rport_put() - decrement rport reference count
+ * @rport: SRP target port.
  */
 void srp_rport_put(struct srp_rport *rport)
 {
diff --git a/include/scsi/scsi_transport_srp.h
b/include/scsi/scsi_transport_srp.h
index 4ebf691..69eb021 100644
--- a/include/scsi/scsi_transport_srp.h
+++ b/include/scsi/scsi_transport_srp.h
@@ -29,10 +29,26 @@ enum srp_rport_state {
 };
 
 /**
- * struct srp_rport
- * @lld_data: LLD private data.
- * @mutex:Protects against concurrent rport reconnect / fast_io_fail /
- *   dev_loss_tmo activity.
+ * struct srp_rport - SRP initiator or target port
+ *
+ * Fields that are relevant for SRP initiator and SRP target drivers:
+ * @dev:   Device associated with this rport.
+ * @port_id:   16-byte port identifier.
+ * @roles: Role of this port - initiator or target.
+ *
+ * Fields that are only relevant for SRP initiator drivers:
+ * @lld_data:  LLD private data.
+ * @mutex: Protects against concurrent rport reconnect /
+ * fast_io_fail / dev_loss_tmo activity.
+ * @state: rport state.
+ * @deleted:   Whether or not srp_rport_del() has already been
invoked.
+ * @reconnect_delay:   Reconnect delay in seconds.
+ * @failed_reconnects: Number

Re: [PATCH] scsi_transport_srp: Fix kernel-doc warnings

2014-01-05 Thread Randy Dunlap 
On 01/05/14 01:13, Bart Van Assche wrote:
 The following command has been used to verify that the kernel-doc
 tool no longer complains about undocumented fields:
 
 scripts/kernel-doc -html drivers/scsi/scsi_transport_srp.c \
   include/scsi/scsi_transport_srp.h srp-transport-doc.html

Thanks for the patch.
I guess that your tree is different from mine.  Using 3.13-rc7, I still get
3 warnings:

Warning(drivers/scsi/scsi_transport_srp.c:620): No description found for 
parameter 'scmd'
Warning(drivers/scsi/scsi_transport_srp.c:688): No description found for 
parameter 'rport'
Warning(drivers/scsi/scsi_transport_srp.c:697): No description found for 
parameter 'rport'


I also had some trouble with the patch itself -- looks like some of its longer
lines were broken (split) by your mail app (I'm guessing).
The first split line is marked below.


 Signed-off-by: Bart Van Assche bvanass...@acm.org
 Cc: David Dillow dillo...@ornl.gov
 Cc: Vu Pham v...@mellanox.com
 Cc: Sebastian Riemer sebastian.rie...@profitbricks.com
 Cc: James Bottomley jbottom...@parallels.com
 Cc: Randy Dunlap rdun...@infradead.org
 ---
  drivers/scsi/scsi_transport_srp.c | 12 
  include/scsi/scsi_transport_srp.h | 32 
  2 files changed, 40 insertions(+), 4 deletions(-)
 
 diff --git a/drivers/scsi/scsi_transport_srp.c
 b/drivers/scsi/scsi_transport_srp.c
 index 2700a5a..96ffc46 100644
 --- a/drivers/scsi/scsi_transport_srp.c
 +++ b/drivers/scsi/scsi_transport_srp.c
 @@ -64,6 +64,9 @@ static inline struct Scsi_Host *rport_to_shost(struct
 srp_rport *r)
  
  /**
   * srp_tmo_valid() - check timeout combination validity
 + * @reconnect_delay: Reconnect delay in seconds.
 + * @fast_io_fail_tmo: Fast I/O fail timeout in seconds.
 + * @dev_loss_tmo: Device loss timeout in seconds.
   *
   * The combination of the timeout parameters must be such that SCSI
 commands

^^^ commands should be at the end of the line above.
I corrected about 8 (or more) lines like this so that the patch would apply 
cleanly.

http://marc.info/?l=linux-scsim=138891322826100w=2 shows the same problem.

   * are finished in a reasonable time. Hence do not allow the fast I/O fail
 @@ -368,6 +371,7 @@ invalid:
  
  /**
   * srp_reconnect_work() - reconnect and schedule a new attempt if necessary
 + * @work: Work structure used for scheduling this operation.
   */
  static void srp_reconnect_work(struct work_struct *work)
  {
 @@ -408,6 +412,7 @@ static void __rport_fail_io_fast(struct srp_rport
 *rport)
  
  /**
   * rport_fast_io_fail_timedout() - fast I/O failure timeout handler
 + * @work: Work structure used for scheduling this operation.
   */
  static void rport_fast_io_fail_timedout(struct work_struct *work)
  {
 @@ -426,6 +431,7 @@ static void rport_fast_io_fail_timedout(struct
 work_struct *work)
  
  /**
   * rport_dev_loss_timedout() - device loss timeout handler
 + * @work: Work structure used for scheduling this operation.
   */
  static void rport_dev_loss_timedout(struct work_struct *work)
  {
 @@ -488,6 +494,7 @@ static void __srp_start_tl_fail_timers(struct
 srp_rport *rport)
  
  /**
   * srp_start_tl_fail_timers() - start the transport layer failure timers
 + * @rport: SRP target port.
   *
   * Start the transport layer fast I/O failure and device loss timers.
 Do not
   * modify a timer that was already started.
 @@ -502,6 +509,7 @@ EXPORT_SYMBOL(srp_start_tl_fail_timers);
  
  /**
   * scsi_request_fn_active() - number of kernel threads inside
 scsi_request_fn()
 + * @shost: SCSI host for which to count the number of scsi_request_fn()
 callers.
   */
  static int scsi_request_fn_active(struct Scsi_Host *shost)
  {
 @@ -522,6 +530,7 @@ static int scsi_request_fn_active(struct Scsi_Host
 *shost)
  
  /**
   * srp_reconnect_rport() - reconnect to an SRP target port
 + * @rport: SRP target port.
   *
   * Blocks SCSI command queueing before invoking reconnect() such that
   * queuecommand() won't be invoked concurrently with reconnect() from
 outside
 @@ -599,6 +608,7 @@ EXPORT_SYMBOL(srp_reconnect_rport);
  
  /**
   * srp_timed_out() - SRP transport intercept of the SCSI timeout EH
 + * @scmd: SCSI command.
   *
   * If a timeout occurs while an rport is in the blocked state, ask the SCSI
   * EH to continue waiting (BLK_EH_RESET_TIMER). Otherwise let the SCSI core
 @@ -674,6 +684,7 @@ static int srp_host_match(struct attribute_container
 *cont, struct device *dev)
  
  /**
   * srp_rport_get() - increment rport reference count
 + * @rport: SRP target port.
   */
  void srp_rport_get(struct srp_rport *rport)
  {
 @@ -683,6 +694,7 @@ EXPORT_SYMBOL(srp_rport_get);
  
  /**
   * srp_rport_put() - decrement rport reference count
 + * @rport: SRP target port.
   */
  void srp_rport_put(struct srp_rport *rport)
  {
 diff --git a/include/scsi/scsi_transport_srp.h
 b/include/scsi/scsi_transport_srp.h
 index 4ebf691..69eb021 100644
 --- a/include/scsi/scsi_transport_srp.h
 +++