* scsi_transport_srp.c kernel-doc warnings
@ 2013-12-30 5:02 Randy Dunlap
2014-01-05 1:53 ` [PATCH] scsi: eliminate " Randy Dunlap
0 siblings, 1 reply; 7+ messages in thread
From: Randy Dunlap @ 2013-12-30 5:02 UTC (permalink / raw)
To: Bart Van Assche, linux-scsi
Hi Bart,
Please complete the kernel-doc notation in scsi_transport_srp.c to eliminate
the following kernel-doc warnings or make them not use kernel-doc notation
at all. [This list is from v3.13-rc6.]
Warning(drivers/scsi/scsi_transport_srp.c:75): No description found for parameter 'reconnect_delay'
Warning(drivers/scsi/scsi_transport_srp.c:75): No description found for parameter 'fast_io_fail_tmo'
Warning(drivers/scsi/scsi_transport_srp.c:75): No description found for parameter 'dev_loss_tmo'
Warning(drivers/scsi/scsi_transport_srp.c:373): No description found for parameter 'work'
Warning(drivers/scsi/scsi_transport_srp.c:413): No description found for parameter 'work'
Warning(drivers/scsi/scsi_transport_srp.c:431): No description found for parameter 'work'
Warning(drivers/scsi/scsi_transport_srp.c:496): No description found for parameter 'rport'
Warning(drivers/scsi/scsi_transport_srp.c:507): No description found for parameter 'shost'
Warning(drivers/scsi/scsi_transport_srp.c:545): No description found for parameter 'rport'
Warning(drivers/scsi/scsi_transport_srp.c:611): No description found for parameter 'scmd'
Warning(drivers/scsi/scsi_transport_srp.c:679): No description found for parameter 'rport'
Warning(drivers/scsi/scsi_transport_srp.c:688): No description found for parameter 'rport'
thanks,
--
~Randy
^ permalink raw reply [flat|nested] 7+ messages in thread
* [PATCH] scsi: eliminate scsi_transport_srp.c kernel-doc warnings
2013-12-30 5:02 scsi_transport_srp.c kernel-doc warnings Randy Dunlap
@ 2014-01-05 1:53 ` Randy Dunlap
2014-01-05 9:13 ` [PATCH] scsi_transport_srp: Fix " Bart Van Assche
0 siblings, 1 reply; 7+ messages in thread
From: Randy Dunlap @ 2014-01-05 1:53 UTC (permalink / raw)
To: Bart Van Assche, linux-scsi, James E.J. Bottomley; +Cc: dgilbert
From: Randy Dunlap <rdunlap@infradead.org>
drivers/scsi/scsi_transport_srp.c has incomplete kernel-doc notation
for some of the functions. This causes several kernel-doc warnings.
Fix these kernel-doc warnings by changing the beginning /** kernel-doc
marker to a plain /* comment.
Warning(drivers/scsi/scsi_transport_srp.c:75): No description found for parameter 'reconnect_delay'
Warning(drivers/scsi/scsi_transport_srp.c:75): No description found for parameter 'fast_io_fail_tmo'
Warning(drivers/scsi/scsi_transport_srp.c:75): No description found for parameter 'dev_loss_tmo'
Warning(drivers/scsi/scsi_transport_srp.c:373): No description found for parameter 'work'
Warning(drivers/scsi/scsi_transport_srp.c:413): No description found for parameter 'work'
Warning(drivers/scsi/scsi_transport_srp.c:431): No description found for parameter 'work'
Warning(drivers/scsi/scsi_transport_srp.c:496): No description found for parameter 'rport'
Warning(drivers/scsi/scsi_transport_srp.c:507): No description found for parameter 'shost'
Warning(drivers/scsi/scsi_transport_srp.c:545): No description found for parameter 'rport'
Warning(drivers/scsi/scsi_transport_srp.c:611): No description found for parameter 'scmd'
Warning(drivers/scsi/scsi_transport_srp.c:679): No description found for parameter 'rport'
Warning(drivers/scsi/scsi_transport_srp.c:688): No description found for parameter 'rport'
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
---
drivers/scsi/scsi_transport_srp.c | 20 ++++++++++----------
1 file changed, 10 insertions(+), 10 deletions(-)
--- lnx-313-rc7.orig/drivers/scsi/scsi_transport_srp.c
+++ lnx-313-rc7/drivers/scsi/scsi_transport_srp.c
@@ -62,7 +62,7 @@ static inline struct Scsi_Host *rport_to
return dev_to_shost(r->dev.parent);
}
-/**
+/*
* srp_tmo_valid() - check timeout combination validity
*
* The combination of the timeout parameters must be such that SCSI commands
@@ -366,7 +366,7 @@ invalid:
return -EINVAL;
}
-/**
+/*
* srp_reconnect_work() - reconnect and schedule a new attempt if necessary
*/
static void srp_reconnect_work(struct work_struct *work)
@@ -406,7 +406,7 @@ static void __rport_fail_io_fast(struct
i->f->terminate_rport_io(rport);
}
-/**
+/*
* rport_fast_io_fail_timedout() - fast I/O failure timeout handler
*/
static void rport_fast_io_fail_timedout(struct work_struct *work)
@@ -424,7 +424,7 @@ static void rport_fast_io_fail_timedout(
mutex_unlock(&rport->mutex);
}
-/**
+/*
* rport_dev_loss_timedout() - device loss timeout handler
*/
static void rport_dev_loss_timedout(struct work_struct *work)
@@ -486,7 +486,7 @@ static void __srp_start_tl_fail_timers(s
}
}
-/**
+/*
* srp_start_tl_fail_timers() - start the transport layer failure timers
*
* Start the transport layer fast I/O failure and device loss timers. Do not
@@ -500,7 +500,7 @@ void srp_start_tl_fail_timers(struct srp
}
EXPORT_SYMBOL(srp_start_tl_fail_timers);
-/**
+/*
* scsi_request_fn_active() - number of kernel threads inside scsi_request_fn()
*/
static int scsi_request_fn_active(struct Scsi_Host *shost)
@@ -520,7 +520,7 @@ static int scsi_request_fn_active(struct
return request_fn_active;
}
-/**
+/*
* srp_reconnect_rport() - reconnect to an SRP target port
*
* Blocks SCSI command queueing before invoking reconnect() such that
@@ -597,7 +597,7 @@ out:
}
EXPORT_SYMBOL(srp_reconnect_rport);
-/**
+/*
* srp_timed_out() - SRP transport intercept of the SCSI timeout EH
*
* If a timeout occurs while an rport is in the blocked state, ask the SCSI
@@ -672,7 +672,7 @@ static int srp_host_match(struct attribu
return &i->t.host_attrs.ac == cont;
}
-/**
+/*
* srp_rport_get() - increment rport reference count
*/
void srp_rport_get(struct srp_rport *rport)
@@ -681,7 +681,7 @@ void srp_rport_get(struct srp_rport *rpo
}
EXPORT_SYMBOL(srp_rport_get);
-/**
+/*
* srp_rport_put() - decrement rport reference count
*/
void srp_rport_put(struct srp_rport *rport)
^ permalink raw reply [flat|nested] 7+ messages in thread
* [PATCH] scsi_transport_srp: Fix kernel-doc warnings
2014-01-05 1:53 ` [PATCH] scsi: eliminate " Randy Dunlap
@ 2014-01-05 9:13 ` Bart Van Assche
2014-01-05 20:39 ` Randy Dunlap
0 siblings, 1 reply; 7+ messages in thread
From: Bart Van Assche @ 2014-01-05 9:13 UTC (permalink / raw)
To: James E.J. Bottomley
Cc: linux-scsi, David Dillow, Vu Pham, Sebastian Riemer,
Randy Dunlap, Douglas Gilbert
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 <bvanassche@acm.org>
Cc: David Dillow <dillowda@ornl.gov>
Cc: Vu Pham <vu@mellanox.com>
Cc: Sebastian Riemer <sebastian.riemer@profitbricks.com>
Cc: James Bottomley <jbottomley@parallels.com>
Cc: Randy Dunlap <rdunlap@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 of failed reconnect attempts.
+ * @reconnect_work: Work structure used for scheduling reconnect
attempts.
+ * @fast_io_fail_tmo: Fast I/O fail timeout in seconds.
+ * @dev_loss_tmo: Device loss timeout in seconds.
+ * @fast_io_fail_work: Work structure used for scheduling fast I/O fail
work.
+ * @dev_loss_work: Work structure used for scheduling device loss work.
*/
struct srp_rport {
/* for initiator and target drivers */
@@ -60,6 +76,8 @@ struct srp_rport {
/**
* struct srp_function_template
+ *
+ * Fields that are only relevant for SRP initiator drivers:
* @has_rport_state: Whether or not to create the state,
fast_io_fail_tmo and
* dev_loss_tmo sysfs attribute for an rport.
* @reset_timer_if_blocked: Whether or srp_timed_out() should reset the
command
@@ -71,6 +89,11 @@ struct srp_rport {
* srp_reconnect_rport().
* @terminate_rport_io: Callback function for terminating all
outstanding I/O
* requests for an rport.
+ * @rport_delete: Callback function that deletes an rport.
+ *
+ * Fields that are only relevant for SRP target drivers:
+ * @tsk_mgmt_response: Callback function for sending a task management
response.
+ * @it_nexus_response: Callback function for processing an IT nexus
response.
*/
struct srp_function_template {
/* for initiator drivers */
@@ -104,6 +127,7 @@ extern void srp_remove_host(struct Scsi_Host *);
/**
* srp_chkready() - evaluate the transport layer state before I/O
+ * @rport: SRP target port pointer.
*
* Returns a SCSI result code that can be returned by the LLD
queuecommand()
* implementation. The role of this function is similar to that of
--
1.8.1.4
^ permalink raw reply related [flat|nested] 7+ messages in thread
* Re: [PATCH] scsi_transport_srp: Fix kernel-doc warnings
2014-01-05 9:13 ` [PATCH] scsi_transport_srp: Fix " Bart Van Assche
@ 2014-01-05 20:39 ` Randy Dunlap
2014-01-06 6:39 ` Bart Van Assche
0 siblings, 1 reply; 7+ messages in thread
From: Randy Dunlap @ 2014-01-05 20:39 UTC (permalink / raw)
To: Bart Van Assche, James E.J. Bottomley
Cc: linux-scsi, David Dillow, Vu Pham, Sebastian Riemer, Douglas Gilbert
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 <bvanassche@acm.org>
> Cc: David Dillow <dillowda@ornl.gov>
> Cc: Vu Pham <vu@mellanox.com>
> Cc: Sebastian Riemer <sebastian.riemer@profitbricks.com>
> Cc: James Bottomley <jbottomley@parallels.com>
> Cc: Randy Dunlap <rdunlap@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-scsi&m=138891322826100&w=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
> +++ 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 of failed reconnect attempts.
> + * @reconnect_work: Work structure used for scheduling reconnect
> attempts.
> + * @fast_io_fail_tmo: Fast I/O fail timeout in seconds.
> + * @dev_loss_tmo: Device loss timeout in seconds.
> + * @fast_io_fail_work: Work structure used for scheduling fast I/O fail
> work.
> + * @dev_loss_work: Work structure used for scheduling device loss work.
> */
> struct srp_rport {
> /* for initiator and target drivers */
> @@ -60,6 +76,8 @@ struct srp_rport {
>
> /**
> * struct srp_function_template
> + *
> + * Fields that are only relevant for SRP initiator drivers:
> * @has_rport_state: Whether or not to create the state,
> fast_io_fail_tmo and
> * dev_loss_tmo sysfs attribute for an rport.
> * @reset_timer_if_blocked: Whether or srp_timed_out() should reset the
> command
> @@ -71,6 +89,11 @@ struct srp_rport {
> * srp_reconnect_rport().
> * @terminate_rport_io: Callback function for terminating all
> outstanding I/O
> * requests for an rport.
> + * @rport_delete: Callback function that deletes an rport.
> + *
> + * Fields that are only relevant for SRP target drivers:
> + * @tsk_mgmt_response: Callback function for sending a task management
> response.
> + * @it_nexus_response: Callback function for processing an IT nexus
> response.
> */
> struct srp_function_template {
> /* for initiator drivers */
> @@ -104,6 +127,7 @@ extern void srp_remove_host(struct Scsi_Host *);
>
> /**
> * srp_chkready() - evaluate the transport layer state before I/O
> + * @rport: SRP target port pointer.
> *
> * Returns a SCSI result code that can be returned by the LLD
> queuecommand()
> * implementation. The role of this function is similar to that of
>
--
~Randy
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [PATCH] scsi_transport_srp: Fix kernel-doc warnings
2014-01-05 20:39 ` Randy Dunlap
@ 2014-01-06 6:39 ` Bart Van Assche
2014-01-06 12:53 ` Sebastian Riemer
2014-01-06 20:26 ` Randy Dunlap
0 siblings, 2 replies; 7+ messages in thread
From: Bart Van Assche @ 2014-01-06 6:39 UTC (permalink / raw)
To: Randy Dunlap, James E.J. Bottomley
Cc: linux-scsi, David Dillow, Vu Pham, Sebastian Riemer, Douglas Gilbert
[-- Attachment #1: Type: text/plain, Size: 1223 bytes --]
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 ?
Thanks,
Bart.
[-- Attachment #2: 0001-scsi_transport_srp-Fix-kernel-doc-warnings.patch --]
[-- Type: text/x-patch, Size: 6894 bytes --]
>From 6dc06b90bf848ec9bb498495b21c66b168726ef4 Mon Sep 17 00:00:00 2001
From: Bart Van Assche <bvanassche@acm.org>
Date: Sun, 5 Jan 2014 09:55:23 +0100
Subject: [PATCH] scsi_transport_srp: Fix kernel-doc warnings
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 <bvanassche@acm.org>
Cc: David Dillow <dillowda@ornl.gov>
Cc: Vu Pham <vu@mellanox.com>
Cc: Sebastian Riemer <sebastian.riemer@profitbricks.com>
Cc: James Bottomley <jbottomley@parallels.com>
Cc: Randy Dunlap <rdunlap@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 of failed reconnect attempts.
+ * @reconnect_work: Work structure used for scheduling reconnect attempts.
+ * @fast_io_fail_tmo: Fast I/O fail timeout in seconds.
+ * @dev_loss_tmo: Device loss timeout in seconds.
+ * @fast_io_fail_work: Work structure used for scheduling fast I/O fail work.
+ * @dev_loss_work: Work structure used for scheduling device loss work.
*/
struct srp_rport {
/* for initiator and target drivers */
@@ -60,6 +76,8 @@ struct srp_rport {
/**
* struct srp_function_template
+ *
+ * Fields that are only relevant for SRP initiator drivers:
* @has_rport_state: Whether or not to create the state, fast_io_fail_tmo and
* dev_loss_tmo sysfs attribute for an rport.
* @reset_timer_if_blocked: Whether or srp_timed_out() should reset the command
@@ -71,6 +89,11 @@ struct srp_rport {
* srp_reconnect_rport().
* @terminate_rport_io: Callback function for terminating all outstanding I/O
* requests for an rport.
+ * @rport_delete: Callback function that deletes an rport.
+ *
+ * Fields that are only relevant for SRP target drivers:
+ * @tsk_mgmt_response: Callback function for sending a task management response.
+ * @it_nexus_response: Callback function for processing an IT nexus response.
*/
struct srp_function_template {
/* for initiator drivers */
@@ -104,6 +127,7 @@ extern void srp_remove_host(struct Scsi_Host *);
/**
* srp_chkready() - evaluate the transport layer state before I/O
+ * @rport: SRP target port pointer.
*
* Returns a SCSI result code that can be returned by the LLD queuecommand()
* implementation. The role of this function is similar to that of
--
1.8.1.4
^ permalink raw reply related [flat|nested] 7+ messages in thread
* Re: [PATCH] scsi_transport_srp: Fix kernel-doc warnings
2014-01-06 6:39 ` Bart Van Assche
@ 2014-01-06 12:53 ` Sebastian Riemer
2014-01-06 20:26 ` Randy Dunlap
1 sibling, 0 replies; 7+ messages in thread
From: Sebastian Riemer @ 2014-01-06 12:53 UTC (permalink / raw)
To: Bart Van Assche
Cc: Randy Dunlap, James E.J. Bottomley, linux-scsi, David Dillow,
Vu Pham, Douglas Gilbert
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.riemer@profitbricks.com>
Cheers,
Sebastian
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [PATCH] scsi_transport_srp: Fix kernel-doc warnings
2014-01-06 6:39 ` Bart Van Assche
2014-01-06 12:53 ` Sebastian Riemer
@ 2014-01-06 20:26 ` Randy Dunlap
1 sibling, 0 replies; 7+ messages in thread
From: Randy Dunlap @ 2014-01-06 20:26 UTC (permalink / raw)
To: Bart Van Assche, James E.J. Bottomley
Cc: linux-scsi, David Dillow, Vu Pham, Sebastian Riemer, Douglas Gilbert
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 <rdunlap@infradead.org>
--
~Randy
^ permalink raw reply [flat|nested] 7+ messages in thread
end of thread, other threads:[~2014-01-06 20:26 UTC | newest]
Thread overview: 7+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2013-12-30 5:02 scsi_transport_srp.c kernel-doc warnings Randy Dunlap
2014-01-05 1:53 ` [PATCH] scsi: eliminate " Randy Dunlap
2014-01-05 9:13 ` [PATCH] scsi_transport_srp: Fix " Bart Van Assche
2014-01-05 20:39 ` Randy Dunlap
2014-01-06 6:39 ` Bart Van Assche
2014-01-06 12:53 ` Sebastian Riemer
2014-01-06 20:26 ` Randy Dunlap
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.