* 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 a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).