[PATCH 00/36] [Set 4] Rid W=1 warnings in SCSI

[PATCH 00/36] [Set 4] Rid W=1 warnings in SCSI

[Lee Jones]

This set is part of a larger effort attempting to clean-up W=1
kernel builds, which are currently overwhelmingly riddled with
niggly little warnings.

Lee Jones (36):
  scsi: myrb: Demote non-conformant kernel-doc headers and fix others
  scsi: ipr: Fix incorrect function names in their headers
  scsi: mvumi: Fix formatting and doc-rot issues
  scsi: sd_zbc: Place function name into header
  scsi: pmcraid: Fix a whole host of kernel-doc issues
  scsi: sd: Fix function name in header
  scsi: aic94xx: aic94xx_dump: Correct misspelling of function
    asd_dump_seq_state()
  scsi: be2iscsi: be_main: Ensure function follows directly after its
    header
  scsi: dc395x: Fix some function param descriptions
  scsi: initio: Fix a few kernel-doc misdemeanours
  scsi: a100u2w: Fix some misnaming and formatting issues
  scsi: myrs: Add missing ':' to make the kernel-doc checker happy
  scsi: pmcraid: Correct function name pmcraid_show_adapter_id() in
    header
  scsi: mpt3sas: mpt3sas_scs: Fix a few kernel-doc issues
  scsi: be2iscsi: be_main: Demote incomplete/non-conformant kernel-doc
    header
  scsi: isci: phy: Fix a few different kernel-doc related issues
  scsi: fnic: fnic_scsi: Demote non-conformant kernel-doc headers
  scsi: fnic: fnic_fcs: Kernel-doc headers must contain the function
    name
  scsi: isci: phy: Provide function name and demote non-conforming
    header
  scsi: isci: request: Fix a myriad of kernel-doc issues
  scsi: isci: host: Fix bunch of kernel-doc related issues
  scsi: isci: task: Demote non-conformant header and remove superfluous
    param
  scsi: isci: remote_node_table: Fix a bunch of kernel-doc misdemeanours
  scsi: isci: remote_node_context: Fix one function header and demote a
    couple more
  scsi: isci: port_config: Fix a bunch of doc-rot and demote abuses
  scsi: isci: remote_device: Fix a bunch of doc-rot issues
  scsi: isci: request: Fix doc-rot issue relating to 'ireq' param
  scsi: isci: port: Fix a bunch of kernel-doc issues
  scsi: isci: remote_node_context: Demote kernel-doc abuse
  scsi: isci: remote_node_table: Provide some missing params and remove
    others
  scsi: cxlflash: main: Fix a little do-rot
  scsi: cxlflash: superpipe: Fix a few misnaming issues
  scsi: ibmvscsi: Fix a bunch of kernel-doc related issues
  scsi: ibmvscsi: ibmvfc: Fix a bunch of misdocumentation
  scsi: ibmvscsi_tgt: ibmvscsi_tgt: Remove duplicate section 'NOTE'
  scsi: cxlflash: vlun: Fix some misnaming related doc-rot

 drivers/scsi/a100u2w.c                   |  8 +--
 drivers/scsi/aic94xx/aic94xx_dump.c      |  2 +-
 drivers/scsi/be2iscsi/be_main.c          |  5 +-
 drivers/scsi/cxlflash/main.c             |  8 +--
 drivers/scsi/cxlflash/superpipe.c        |  6 +-
 drivers/scsi/cxlflash/vlun.c             |  8 +--
 drivers/scsi/dc395x.c                    |  3 +-
 drivers/scsi/fnic/fnic_fcs.c             |  2 +-
 drivers/scsi/fnic/fnic_scsi.c            |  6 +-
 drivers/scsi/ibmvscsi/ibmvfc.c           | 29 ++++++----
 drivers/scsi/ibmvscsi/ibmvscsi.c         | 70 ++++++++++++------------
 drivers/scsi/ibmvscsi_tgt/ibmvscsi_tgt.c |  8 +--
 drivers/scsi/initio.c                    | 13 ++---
 drivers/scsi/ipr.c                       |  8 +--
 drivers/scsi/isci/host.c                 | 37 ++++++-------
 drivers/scsi/isci/phy.c                  | 34 ++++++------
 drivers/scsi/isci/port.c                 | 58 ++++++++++----------
 drivers/scsi/isci/port_config.c          | 37 +++++++------
 drivers/scsi/isci/remote_device.c        | 31 ++++++-----
 drivers/scsi/isci/remote_node_context.c  | 13 +----
 drivers/scsi/isci/remote_node_table.c    | 64 +++++++++++-----------
 drivers/scsi/isci/request.c              | 60 ++++++++++----------
 drivers/scsi/isci/task.c                 |  3 +-
 drivers/scsi/mpt3sas/mpt3sas_scsih.c     | 18 +++---
 drivers/scsi/mvumi.c                     |  5 +-
 drivers/scsi/myrb.c                      | 47 ++++++++--------
 drivers/scsi/myrs.c                      |  6 +-
 drivers/scsi/pmcraid.c                   | 70 ++++++++++++------------
 drivers/scsi/sd.c                        |  2 +-
 drivers/scsi/sd_zbc.c                    |  2 +-
 30 files changed, 329 insertions(+), 334 deletions(-)

Cc: Alan Cox <alan@lxorguk.ukuu.org.uk>
Cc: Alex Davis <letmein@erols.com>
Cc: Ali Akcaagac <aliakc@web.de>
Cc: Anil Ravindranath <anil_ravindranath@pmc-sierra.com>
Cc: Artur Paszkiewicz <artur.paszkiewicz@intel.com>
Cc: Badari Pulavarty <pbadari@us.ibm.com>
Cc: Bas Vermeulen <bvermeul@blackstar.xs4all.nl>
Cc: Benjamin Herrenschmidt <benh@kernel.crashing.org>
Cc: Brian King <brking@linux.vnet.ibm.com>
Cc: Brian King <brking@us.ibm.com>
Cc: Brian Macy <bmacy@sunshinecomputing.com>
Cc: "Bryant G. Ly" <bryantly@linux.vnet.ibm.com>
Cc: Christoph Hellwig <hch@lst.de>
Cc: "C.L. Huang" <ching@tekram.com.tw>
Cc: Colin DeVilbiss <devilbis@us.ibm.com>
Cc: Dave Boutcher <boutcher@us.ibm.com>
Cc: Dave Boutcher <sleddog@us.ibm.com>
Cc: David Chaw <david_chaw@adaptec.com>
Cc: dc395x@twibble.org
Cc: Douglas Gilbert <dgilbert@interlog.com>
Cc: Doug Ledford <dledford@redhat.com>
Cc: Drew Eckhardt <drew@colorado.edu>
Cc: Erich Chen <erich@tekram.com.tw>
Cc: Eric Youngdale <eric@andante.org>
Cc: FUJITA Tomonori <tomof@acm.org>
Cc: Hannes Reinecke <hare@kernel.org>
Cc: Hannes Reinecke <hare@suse.de>
Cc: "James E.J. Bottomley" <jejb@linux.ibm.com>
Cc: Jamie Lenehan <lenehan@twibble.org>
Cc: Jirka Hanika <geo@ff.cuni.cz>
Cc: Jitendra Bhivare <jitendra.bhivare@broadcom.com>
Cc: Karan Tilak Kumar <kartilak@cisco.com>
Cc: Ketan Mukadam <ketan.mukadam@broadcom.com>
Cc: Kurt Garloff <garloff@suse.de>
Cc: Lee Jones <lee.jones@linaro.org>
Cc: Le Moal <damien.lemoal@hgst.com>
Cc: "Leonard N. Zubkoff" <lnz@dandelion.com>
Cc: Linda Xie <lxie@us.ibm.com>
Cc: linux-drivers@broadcom.com
Cc: Linux GmbH <hare@suse.com>
Cc: linuxppc-dev@lists.ozlabs.org
Cc: linux-scsi@vger.kernel.org
Cc: Luben Tuikov <luben_tuikov@adaptec.com>
Cc: "Manoj N. Kumar" <manoj@linux.ibm.com>
Cc: "Martin K. Petersen" <martin.petersen@oracle.com>
Cc: Marvell <jyli@marvell.com>
Cc: "Matthew R. Ochs" <mrochs@linux.ibm.com>
Cc: Michael Cyr <mikecyr@linux.ibm.com>
Cc: Michael Ellerman <mpe@ellerman.id.au>
Cc: MPT-FusionLinux.pdl@avagotech.com
Cc: MPT-FusionLinux.pdl@broadcom.com
Cc: "Nicholas A. Bellinger" <nab@kernel.org>
Cc: Oliver Neukum <oliver@neukum.org>
Cc: Paul Mackerras <paulus@samba.org>
Cc: Richard Gooch <rgooch@atnf.csiro.au>
Cc: Santiago Leon <santil@us.ibm.com>
Cc: Sathya Prakash <sathya.prakash@broadcom.com>
Cc: Satish Kharat <satishkh@cisco.com>
Cc: Sesidhar Baddela <sebaddel@cisco.com>
Cc: Shaun Tancheff <shaun.tancheff@seagate.com>
Cc: Sreekanth Reddy <sreekanth.reddy@broadcom.com>
Cc: Subbu Seetharaman <subbu.seetharaman@broadcom.com>
Cc: Suganath Prabu Subramani <suganath-prabu.subramani@broadcom.com>
Cc: target-devel@vger.kernel.org
Cc: Torben Mathiasen <tmm@image.dk>
Cc: Tyrel Datwyler <tyreld@linux.ibm.com>
Cc: Uma Krishnan <ukrishn@linux.ibm.com>
Cc: willy@debian.org
-- 
2.27.0

[PATCH 33/36] scsi: ibmvscsi: Fix a bunch of kernel-doc related issues

[Lee Jones]

Fixes the following W=1 kernel build warning(s):

 drivers/scsi/ibmvscsi/ibmvscsi.c:143: warning: Function parameter or member 'hostdata' not described in 'ibmvscsi_release_crq_queue'
 drivers/scsi/ibmvscsi/ibmvscsi.c:143: warning: Function parameter or member 'max_requests' not described in 'ibmvscsi_release_crq_queue'
 drivers/scsi/ibmvscsi/ibmvscsi.c:143: warning: expecting prototype for release_crq_queue(). Prototype was for ibmvscsi_release_crq_queue() instead
 drivers/scsi/ibmvscsi/ibmvscsi.c:286: warning: expecting prototype for reset_crq_queue(). Prototype was for ibmvscsi_reset_crq_queue() instead
 drivers/scsi/ibmvscsi/ibmvscsi.c:328: warning: Function parameter or member 'max_requests' not described in 'ibmvscsi_init_crq_queue'
 drivers/scsi/ibmvscsi/ibmvscsi.c:328: warning: expecting prototype for initialize_crq_queue(). Prototype was for ibmvscsi_init_crq_queue() instead
 drivers/scsi/ibmvscsi/ibmvscsi.c:414: warning: expecting prototype for reenable_crq_queue(). Prototype was for ibmvscsi_reenable_crq_queue() instead
 drivers/scsi/ibmvscsi/ibmvscsi.c:536: warning: expecting prototype for ibmvscsi_free(). Prototype was for free_event_struct() instead
 drivers/scsi/ibmvscsi/ibmvscsi.c:558: warning: expecting prototype for get_evt_struct(). Prototype was for get_event_struct() instead
 drivers/scsi/ibmvscsi/ibmvscsi.c:587: warning: Function parameter or member 'evt_struct' not described in 'init_event_struct'
 drivers/scsi/ibmvscsi/ibmvscsi.c:587: warning: Excess function parameter 'evt' description in 'init_event_struct'
 drivers/scsi/ibmvscsi/ibmvscsi.c:608: warning: Function parameter or member 'cmd' not described in 'set_srp_direction'
 drivers/scsi/ibmvscsi/ibmvscsi.c:608: warning: Function parameter or member 'srp_cmd' not described in 'set_srp_direction'
 drivers/scsi/ibmvscsi/ibmvscsi.c:608: warning: Function parameter or member 'numbuf' not described in 'set_srp_direction'
 drivers/scsi/ibmvscsi/ibmvscsi.c:641: warning: Function parameter or member 'evt_struct' not described in 'unmap_cmd_data'
 drivers/scsi/ibmvscsi/ibmvscsi.c:683: warning: Function parameter or member 'evt_struct' not described in 'map_sg_data'
 drivers/scsi/ibmvscsi/ibmvscsi.c:757: warning: Function parameter or member 'evt_struct' not described in 'map_data_for_srp_cmd'
 drivers/scsi/ibmvscsi/ibmvscsi.c:783: warning: Function parameter or member 'error_code' not described in 'purge_requests'
 drivers/scsi/ibmvscsi/ibmvscsi.c:846: warning: Function parameter or member 't' not described in 'ibmvscsi_timeout'
 drivers/scsi/ibmvscsi/ibmvscsi.c:846: warning: Excess function parameter 'evt_struct' description in 'ibmvscsi_timeout'
 drivers/scsi/ibmvscsi/ibmvscsi.c:1043: warning: Function parameter or member 'cmnd' not described in 'ibmvscsi_queuecommand_lck'
 drivers/scsi/ibmvscsi/ibmvscsi.c:1043: warning: expecting prototype for ibmvscsi_queue(). Prototype was for ibmvscsi_queuecommand_lck() instead
 drivers/scsi/ibmvscsi/ibmvscsi.c:1351: warning: expecting prototype for init_host(). Prototype was for enable_fast_fail() instead
 drivers/scsi/ibmvscsi/ibmvscsi.c:1464: warning: Function parameter or member 'hostdata' not described in 'init_adapter'
 drivers/scsi/ibmvscsi/ibmvscsi.c:1475: warning: Function parameter or member 'evt_struct' not described in 'sync_completion'
 drivers/scsi/ibmvscsi/ibmvscsi.c:1488: warning: Function parameter or member 'cmd' not described in 'ibmvscsi_eh_abort_handler'
 drivers/scsi/ibmvscsi/ibmvscsi.c:1488: warning: expecting prototype for ibmvscsi_abort(). Prototype was for ibmvscsi_eh_abort_handler() instead
 drivers/scsi/ibmvscsi/ibmvscsi.c:1627: warning: Function parameter or member 'cmd' not described in 'ibmvscsi_eh_device_reset_handler'
 drivers/scsi/ibmvscsi/ibmvscsi.c:1893: warning: Excess function parameter 'reason' description in 'ibmvscsi_change_queue_depth'
 drivers/scsi/ibmvscsi/ibmvscsi.c:2221: warning: Function parameter or member 'vdev' not described in 'ibmvscsi_probe'
 drivers/scsi/ibmvscsi/ibmvscsi.c:2221: warning: Function parameter or member 'id' not described in 'ibmvscsi_probe'
 drivers/scsi/ibmvscsi/ibmvscsi.c:2221: warning: expecting prototype for Called by bus code for each adapter(). Prototype was for ibmvscsi_probe() instead
 drivers/scsi/ibmvscsi/ibmvscsi.c:2381: warning: cannot understand function prototype: 'const struct vio_device_id ibmvscsi_device_table[] = '

Cc: Tyrel Datwyler <tyreld@linux.ibm.com>
Cc: Michael Ellerman <mpe@ellerman.id.au>
Cc: Benjamin Herrenschmidt <benh@kernel.crashing.org>
Cc: Paul Mackerras <paulus@samba.org>
Cc: "James E.J. Bottomley" <jejb@linux.ibm.com>
Cc: "Martin K. Petersen" <martin.petersen@oracle.com>
Cc: Colin DeVilbiss <devilbis@us.ibm.com>
Cc: Santiago Leon <santil@us.ibm.com>
Cc: Dave Boutcher <sleddog@us.ibm.com>
Cc: linux-scsi@vger.kernel.org
Cc: linuxppc-dev@lists.ozlabs.org
Signed-off-by: Lee Jones <lee.jones@linaro.org>
---
 drivers/scsi/ibmvscsi/ibmvscsi.c | 70 ++++++++++++++++----------------
 1 file changed, 35 insertions(+), 35 deletions(-)

diff --git a/drivers/scsi/ibmvscsi/ibmvscsi.c b/drivers/scsi/ibmvscsi/ibmvscsi.c
index 77fafb1bc173a..9ffd71e425f90 100644
--- a/drivers/scsi/ibmvscsi/ibmvscsi.c
+++ b/drivers/scsi/ibmvscsi/ibmvscsi.c
@@ -130,9 +130,10 @@ static irqreturn_t ibmvscsi_handle_event(int irq, void *dev_instance)
 }
 
 /**
- * release_crq_queue: - Deallocates data and unregisters CRQ
- * @queue:	crq_queue to initialize and register
- * @host_data:	ibmvscsi_host_data of host
+ * ibmvscsi_release_crq_queue() - Deallocates data and unregisters CRQ
+ * @queue:		crq_queue to initialize and register
+ * @hostdata:		ibmvscsi_host_data of host
+ * @max_requests:	maximum requests (unused)
  *
  * Frees irq, deallocates a page for messages, unmaps dma, and unregisters
  * the crq with the hypervisor.
@@ -276,10 +277,9 @@ static void set_adapter_info(struct ibmvscsi_host_data *hostdata)
 }
 
 /**
- * reset_crq_queue: - resets a crq after a failure
+ * ibmvscsi_reset_crq_queue() - resets a crq after a failure
  * @queue:	crq_queue to initialize and register
  * @hostdata:	ibmvscsi_host_data of host
- *
  */
 static int ibmvscsi_reset_crq_queue(struct crq_queue *queue,
 				    struct ibmvscsi_host_data *hostdata)
@@ -314,9 +314,10 @@ static int ibmvscsi_reset_crq_queue(struct crq_queue *queue,
 }
 
 /**
- * initialize_crq_queue: - Initializes and registers CRQ with hypervisor
- * @queue:	crq_queue to initialize and register
- * @hostdata:	ibmvscsi_host_data of host
+ * ibmvscsi_init_crq_queue() - Initializes and registers CRQ with hypervisor
+ * @queue:		crq_queue to initialize and register
+ * @hostdata:		ibmvscsi_host_data of host
+ * @max_requests:	maximum requests (unused)
  *
  * Allocates a page for messages, maps it for dma, and registers
  * the crq with the hypervisor.
@@ -404,10 +405,9 @@ static int ibmvscsi_init_crq_queue(struct crq_queue *queue,
 }
 
 /**
- * reenable_crq_queue: - reenables a crq after
+ * ibmvscsi_reenable_crq_queue() - reenables a crq after
  * @queue:	crq_queue to initialize and register
  * @hostdata:	ibmvscsi_host_data of host
- *
  */
 static int ibmvscsi_reenable_crq_queue(struct crq_queue *queue,
 				       struct ibmvscsi_host_data *hostdata)
@@ -439,7 +439,7 @@ static int ibmvscsi_reenable_crq_queue(struct crq_queue *queue,
  * @hostdata:	ibmvscsi_host_data who owns the event pool
  *
  * Returns zero on success.
-*/
+ */
 static int initialize_event_pool(struct event_pool *pool,
 				 int size, struct ibmvscsi_host_data *hostdata)
 {
@@ -478,12 +478,12 @@ static int initialize_event_pool(struct event_pool *pool,
 }
 
 /**
- * release_event_pool: - Frees memory of an event pool of a host
+ * release_event_pool() - Frees memory of an event pool of a host
  * @pool:	event_pool to be released
  * @hostdata:	ibmvscsi_host_data who owns the even pool
  *
  * Returns zero on success.
-*/
+ */
 static void release_event_pool(struct event_pool *pool,
 			       struct ibmvscsi_host_data *hostdata)
 {
@@ -526,11 +526,10 @@ static int valid_event_struct(struct event_pool *pool,
 }
 
 /**
- * ibmvscsi_free-event_struct: - Changes status of event to "free"
+ * free_event_struct() - Changes status of event to "free"
  * @pool:	event_pool that contains the event
  * @evt:	srp_event_struct to be modified
- *
-*/
+ */
 static void free_event_struct(struct event_pool *pool,
 				       struct srp_event_struct *evt)
 {
@@ -547,7 +546,7 @@ static void free_event_struct(struct event_pool *pool,
 }
 
 /**
- * get_evt_struct: - Gets the next free event in pool
+ * get_event_struct() - Gets the next free event in pool
  * @pool:	event_pool that contains the events to be searched
  *
  * Returns the next event in "free" state, and NULL if none are free.
@@ -575,7 +574,7 @@ static struct srp_event_struct *get_event_struct(struct event_pool *pool)
 /**
  * init_event_struct: Initialize fields in an event struct that are always 
  *                    required.
- * @evt:        The event
+ * @evt_struct: The event
  * @done:       Routine to call when the event is responded to
  * @format:     SRP or MAD format
  * @timeout:    timeout value set in the CRQ
@@ -597,7 +596,7 @@ static void init_event_struct(struct srp_event_struct *evt_struct,
  * Routines for receiving SCSI responses from the hosting partition
  */
 
-/**
+/*
  * set_srp_direction: Set the fields in the srp related to data
  *     direction and number of buffers based on the direction in
  *     the scsi_cmnd and the number of buffers
@@ -632,9 +631,9 @@ static void set_srp_direction(struct scsi_cmnd *cmd,
 /**
  * unmap_cmd_data: - Unmap data pointed in srp_cmd based on the format
  * @cmd:	srp_cmd whose additional_data member will be unmapped
+ * @evt_struct: the event
  * @dev:	device for which the memory is mapped
- *
-*/
+ */
 static void unmap_cmd_data(struct srp_cmd *cmd,
 			   struct srp_event_struct *evt_struct,
 			   struct device *dev)
@@ -671,6 +670,7 @@ static int map_sg_list(struct scsi_cmnd *cmd, int nseg,
 /**
  * map_sg_data: - Maps dma for a scatterlist and initializes descriptor fields
  * @cmd:	struct scsi_cmnd with the scatterlist
+ * @evt_struct:	struct srp_event_struct to map
  * @srp_cmd:	srp_cmd that contains the memory descriptor
  * @dev:	device for which to map dma memory
  *
@@ -745,6 +745,7 @@ static int map_sg_data(struct scsi_cmnd *cmd,
 /**
  * map_data_for_srp_cmd: - Calls functions to map data for srp cmds
  * @cmd:	struct scsi_cmnd with the memory to be mapped
+ * @evt_struct:	struct srp_event_struct to map
  * @srp_cmd:	srp_cmd that contains the memory descriptor
  * @dev:	dma device for which to map dma memory
  *
@@ -778,6 +779,7 @@ static int map_data_for_srp_cmd(struct scsi_cmnd *cmd,
 /**
  * purge_requests: Our virtual adapter just shut down.  purge any sent requests
  * @hostdata:    the adapter
+ * @error_code:  error code to return as the 'result'
  */
 static void purge_requests(struct ibmvscsi_host_data *hostdata, int error_code)
 {
@@ -838,7 +840,7 @@ static void ibmvscsi_reset_host(struct ibmvscsi_host_data *hostdata)
 
 /**
  * ibmvscsi_timeout - Internal command timeout handler
- * @evt_struct:	struct srp_event_struct that timed out
+ * @t:	struct srp_event_struct that timed out
  *
  * Called when an internally generated command times out
 */
@@ -1034,8 +1036,8 @@ static inline u16 lun_from_dev(struct scsi_device *dev)
 }
 
 /**
- * ibmvscsi_queue: - The queuecommand function of the scsi template 
- * @cmd:	struct scsi_cmnd to be executed
+ * ibmvscsi_queuecommand_lck() - The queuecommand function of the scsi template 
+ * @cmnd:	struct scsi_cmnd to be executed
  * @done:	Callback function to be called when cmd is completed
 */
 static int ibmvscsi_queuecommand_lck(struct scsi_cmnd *cmnd,
@@ -1342,7 +1344,7 @@ static void fast_fail_rsp(struct srp_event_struct *evt_struct)
 }
 
 /**
- * init_host - Start host initialization
+ * enable_fast_fail() - Start host initialization
  * @hostdata:	ibmvscsi_host_data of host
  *
  * Returns zero if successful.
@@ -1456,16 +1458,15 @@ static void send_mad_adapter_info(struct ibmvscsi_host_data *hostdata)
 	spin_unlock_irqrestore(hostdata->host->host_lock, flags);
 };
 
-/**
- * init_adapter: Start virtual adapter initialization sequence
- *
+/*
+ * init_adapter() - Start virtual adapter initialization sequence
  */
 static void init_adapter(struct ibmvscsi_host_data *hostdata)
 {
 	send_mad_adapter_info(hostdata);
 }
 
-/**
+/*
  * sync_completion: Signal that a synchronous command has completed
  * Note that after returning from this call, the evt_struct is freed.
  * the caller waiting on this completion shouldn't touch the evt_struct
@@ -1480,8 +1481,8 @@ static void sync_completion(struct srp_event_struct *evt_struct)
 	complete(&evt_struct->comp);
 }
 
-/**
- * ibmvscsi_abort: Abort a command...from scsi host template
+/*
+ * ibmvscsi_eh_abort_handler: Abort a command...from scsi host template
  * send this over to the server and wait synchronously for the response
  */
 static int ibmvscsi_eh_abort_handler(struct scsi_cmnd *cmd)
@@ -1618,7 +1619,7 @@ static int ibmvscsi_eh_abort_handler(struct scsi_cmnd *cmd)
 	return SUCCESS;
 }
 
-/**
+/*
  * ibmvscsi_eh_device_reset_handler: Reset a single LUN...from scsi host 
  * template send this over to the server and wait synchronously for the 
  * response
@@ -1884,7 +1885,6 @@ static int ibmvscsi_slave_configure(struct scsi_device *sdev)
  * ibmvscsi_change_queue_depth - Change the device's queue depth
  * @sdev:	scsi device struct
  * @qdepth:	depth to set
- * @reason:	calling context
  *
  * Return value:
  * 	actual depth set
@@ -2214,7 +2214,7 @@ static int ibmvscsi_work(void *data)
 	return 0;
 }
 
-/**
+/*
  * Called by bus code for each adapter
  */
 static int ibmvscsi_probe(struct vio_dev *vdev, const struct vio_device_id *id)
@@ -2374,7 +2374,7 @@ static int ibmvscsi_resume(struct device *dev)
 	return 0;
 }
 
-/**
+/*
  * ibmvscsi_device_table: Used by vio.c to match devices in the device tree we 
  * support.
  */
-- 
2.27.0

[PATCH 34/36] scsi: ibmvscsi: ibmvfc: Fix a bunch of misdocumentation

[Lee Jones]

Fixes the following W=1 kernel build warning(s):

 drivers/scsi/ibmvscsi/ibmvfc.c:331: warning: Function parameter or member 'vhost' not described in 'ibmvfc_get_err_result'
 drivers/scsi/ibmvscsi/ibmvfc.c:653: warning: Excess function parameter 'job_step' description in 'ibmvfc_del_tgt'
 drivers/scsi/ibmvscsi/ibmvfc.c:773: warning: Function parameter or member 'queue' not described in 'ibmvfc_init_event_pool'
 drivers/scsi/ibmvscsi/ibmvfc.c:773: warning: Function parameter or member 'size' not described in 'ibmvfc_init_event_pool'
 drivers/scsi/ibmvscsi/ibmvfc.c:823: warning: Function parameter or member 'queue' not described in 'ibmvfc_free_event_pool'
 drivers/scsi/ibmvscsi/ibmvfc.c:1413: warning: Function parameter or member 'vhost' not described in 'ibmvfc_gather_partition_info'
 drivers/scsi/ibmvscsi/ibmvfc.c:1483: warning: Function parameter or member 'queue' not described in 'ibmvfc_get_event'
 drivers/scsi/ibmvscsi/ibmvfc.c:1483: warning: Excess function parameter 'vhost' description in 'ibmvfc_get_event'
 drivers/scsi/ibmvscsi/ibmvfc.c:1630: warning: Function parameter or member 't' not described in 'ibmvfc_timeout'
 drivers/scsi/ibmvscsi/ibmvfc.c:1630: warning: Excess function parameter 'evt' description in 'ibmvfc_timeout'
 drivers/scsi/ibmvscsi/ibmvfc.c:1893: warning: Function parameter or member 'shost' not described in 'ibmvfc_queuecommand'
 drivers/scsi/ibmvscsi/ibmvfc.c:1893: warning: Excess function parameter 'done' description in 'ibmvfc_queuecommand'
 drivers/scsi/ibmvscsi/ibmvfc.c:2324: warning: Function parameter or member 'rport' not described in 'ibmvfc_match_rport'
 drivers/scsi/ibmvscsi/ibmvfc.c:2324: warning: Excess function parameter 'device' description in 'ibmvfc_match_rport'
 drivers/scsi/ibmvscsi/ibmvfc.c:3133: warning: Function parameter or member 'evt_doneq' not described in 'ibmvfc_handle_crq'
 drivers/scsi/ibmvscsi/ibmvfc.c:3317: warning: Excess function parameter 'reason' description in 'ibmvfc_change_queue_depth'
 drivers/scsi/ibmvscsi/ibmvfc.c:3390: warning: Function parameter or member 'attr' not described in 'ibmvfc_show_log_level'
 drivers/scsi/ibmvscsi/ibmvfc.c:3413: warning: Function parameter or member 'attr' not described in 'ibmvfc_store_log_level'
 drivers/scsi/ibmvscsi/ibmvfc.c:3413: warning: Function parameter or member 'count' not described in 'ibmvfc_store_log_level'
 drivers/scsi/ibmvscsi/ibmvfc.c:4121: warning: Function parameter or member 'done' not described in '__ibmvfc_tgt_get_implicit_logout_evt'
 drivers/scsi/ibmvscsi/ibmvfc.c:4438: warning: Function parameter or member 't' not described in 'ibmvfc_adisc_timeout'
 drivers/scsi/ibmvscsi/ibmvfc.c:4438: warning: Excess function parameter 'tgt' description in 'ibmvfc_adisc_timeout'
 drivers/scsi/ibmvscsi/ibmvfc.c:4641: warning: Function parameter or member 'target' not described in 'ibmvfc_alloc_target'
 drivers/scsi/ibmvscsi/ibmvfc.c:4641: warning: Excess function parameter 'scsi_id' description in 'ibmvfc_alloc_target'
 drivers/scsi/ibmvscsi/ibmvfc.c:5068: warning: Function parameter or member 'evt' not described in 'ibmvfc_npiv_logout_done'
 drivers/scsi/ibmvscsi/ibmvfc.c:5068: warning: Excess function parameter 'vhost' description in 'ibmvfc_npiv_logout_done'

Cc: Tyrel Datwyler <tyreld@linux.ibm.com>
Cc: Michael Ellerman <mpe@ellerman.id.au>
Cc: Benjamin Herrenschmidt <benh@kernel.crashing.org>
Cc: Paul Mackerras <paulus@samba.org>
Cc: "James E.J. Bottomley" <jejb@linux.ibm.com>
Cc: "Martin K. Petersen" <martin.petersen@oracle.com>
Cc: Brian King <brking@linux.vnet.ibm.com>
Cc: linux-scsi@vger.kernel.org
Cc: linuxppc-dev@lists.ozlabs.org
Signed-off-by: Lee Jones <lee.jones@linaro.org>
---
 drivers/scsi/ibmvscsi/ibmvfc.c | 29 ++++++++++++++++++-----------
 1 file changed, 18 insertions(+), 11 deletions(-)

diff --git a/drivers/scsi/ibmvscsi/ibmvfc.c b/drivers/scsi/ibmvscsi/ibmvfc.c
index a38d9d5d90ba3..a7a9b647ea178 100644
--- a/drivers/scsi/ibmvscsi/ibmvfc.c
+++ b/drivers/scsi/ibmvscsi/ibmvfc.c
@@ -326,6 +326,7 @@ static const char *ibmvfc_get_cmd_error(u16 status, u16 error)
 
 /**
  * ibmvfc_get_err_result - Find the scsi status to return for the fcp response
+ * @vhost:      ibmvfc host struct
  * @vfc_cmd:	ibmvfc command struct
  *
  * Return value:
@@ -650,8 +651,6 @@ static void ibmvfc_reinit_host(struct ibmvfc_host *vhost)
 /**
  * ibmvfc_del_tgt - Schedule cleanup and removal of the target
  * @tgt:		ibmvfc target struct
- * @job_step:	job step to perform
- *
  **/
 static void ibmvfc_del_tgt(struct ibmvfc_target *tgt)
 {
@@ -768,6 +767,8 @@ static int ibmvfc_send_crq_init_complete(struct ibmvfc_host *vhost)
 /**
  * ibmvfc_init_event_pool - Allocates and initializes the event pool for a host
  * @vhost:	ibmvfc host who owns the event pool
+ * @queue:      ibmvfc queue struct
+ * @size:       pool size
  *
  * Returns zero on success.
  **/
@@ -820,6 +821,7 @@ static int ibmvfc_init_event_pool(struct ibmvfc_host *vhost,
 /**
  * ibmvfc_free_event_pool - Frees memory of the event pool of a host
  * @vhost:	ibmvfc host who owns the event pool
+ * @queue:      ibmvfc queue struct
  *
  **/
 static void ibmvfc_free_event_pool(struct ibmvfc_host *vhost,
@@ -1414,6 +1416,7 @@ static int ibmvfc_issue_fc_host_lip(struct Scsi_Host *shost)
 
 /**
  * ibmvfc_gather_partition_info - Gather info about the LPAR
+ * @vhost:      ibmvfc host struct
  *
  * Return value:
  *	none
@@ -1484,7 +1487,7 @@ static void ibmvfc_set_login_info(struct ibmvfc_host *vhost)
 
 /**
  * ibmvfc_get_event - Gets the next free event in pool
- * @vhost:	ibmvfc host struct
+ * @queue:      ibmvfc queue struct
  *
  * Returns a free event from the pool.
  **/
@@ -1631,7 +1634,7 @@ static int ibmvfc_map_sg_data(struct scsi_cmnd *scmd,
 
 /**
  * ibmvfc_timeout - Internal command timeout handler
- * @evt:	struct ibmvfc_event that timed out
+ * @t:	struct ibmvfc_event that timed out
  *
  * Called when an internally generated command times out
  **/
@@ -1892,8 +1895,8 @@ static struct ibmvfc_cmd *ibmvfc_init_vfc_cmd(struct ibmvfc_event *evt, struct s
 
 /**
  * ibmvfc_queuecommand - The queuecommand function of the scsi template
+ * @shost:	scsi host struct
  * @cmnd:	struct scsi_cmnd to be executed
- * @done:	Callback function to be called when cmnd is completed
  *
  * Returns:
  *	0 on success / other on failure
@@ -2324,7 +2327,7 @@ static int ibmvfc_reset_device(struct scsi_device *sdev, int type, char *desc)
 /**
  * ibmvfc_match_rport - Match function for specified remote port
  * @evt:	ibmvfc event struct
- * @device:	device to match (rport)
+ * @rport:	device to match
  *
  * Returns:
  *	1 if event matches rport / 0 if event does not match rport
@@ -3135,8 +3138,9 @@ static void ibmvfc_handle_async(struct ibmvfc_async_crq *crq,
  * ibmvfc_handle_crq - Handles and frees received events in the CRQ
  * @crq:	Command/Response queue
  * @vhost:	ibmvfc host struct
+ * @evt_doneq:	Event done queue
  *
- **/
+**/
 static void ibmvfc_handle_crq(struct ibmvfc_crq *crq, struct ibmvfc_host *vhost,
 			      struct list_head *evt_doneq)
 {
@@ -3317,7 +3321,6 @@ static int ibmvfc_slave_configure(struct scsi_device *sdev)
  * ibmvfc_change_queue_depth - Change the device's queue depth
  * @sdev:	scsi device struct
  * @qdepth:	depth to set
- * @reason:	calling context
  *
  * Return value:
  * 	actual depth set
@@ -3389,6 +3392,7 @@ static ssize_t ibmvfc_show_host_capabilities(struct device *dev,
 /**
  * ibmvfc_show_log_level - Show the adapter's error logging level
  * @dev:	class device struct
+ * @attr:	unused
  * @buf:	buffer
  *
  * Return value:
@@ -3411,7 +3415,9 @@ static ssize_t ibmvfc_show_log_level(struct device *dev,
 /**
  * ibmvfc_store_log_level - Change the adapter's error logging level
  * @dev:	class device struct
+ * @attr:	unused
  * @buf:	buffer
+ * @count:      buffer size
  *
  * Return value:
  * 	number of bytes printed to buffer
@@ -4121,6 +4127,7 @@ static void ibmvfc_tgt_implicit_logout_done(struct ibmvfc_event *evt)
 /**
  * __ibmvfc_tgt_get_implicit_logout_evt - Allocate and init an event for implicit logout
  * @tgt:		ibmvfc target struct
+ * @done:		Routine to call when the event is responded to
  *
  * Returns:
  *	Allocated and initialized ibmvfc_event struct
@@ -4437,7 +4444,7 @@ static void ibmvfc_tgt_adisc_cancel_done(struct ibmvfc_event *evt)
 
 /**
  * ibmvfc_adisc_timeout - Handle an ADISC timeout
- * @tgt:		ibmvfc target struct
+ * @t:		ibmvfc target struct
  *
  * If an ADISC times out, send a cancel. If the cancel times
  * out, reset the CRQ. When the ADISC comes back as cancelled,
@@ -4640,7 +4647,7 @@ static void ibmvfc_tgt_query_target(struct ibmvfc_target *tgt)
 /**
  * ibmvfc_alloc_target - Allocate and initialize an ibmvfc target
  * @vhost:		ibmvfc host struct
- * @scsi_id:	SCSI ID to allocate target for
+ * @target:		Holds SCSI ID to allocate target forand the WWPN
  *
  * Returns:
  *	0 on success / other on failure
@@ -5070,7 +5077,7 @@ static void ibmvfc_npiv_login(struct ibmvfc_host *vhost)
 
 /**
  * ibmvfc_npiv_logout_done - Completion handler for NPIV Logout
- * @vhost:		ibmvfc host struct
+ * @evt:		ibmvfc event struct
  *
  **/
 static void ibmvfc_npiv_logout_done(struct ibmvfc_event *evt)
-- 
2.27.0

Re: [PATCH 00/36] [Set 4] Rid W=1 warnings in SCSI

[Martin K. Petersen]

Lee,

> This set is part of a larger effort attempting to clean-up W=1 kernel
> builds, which are currently overwhelmingly riddled with niggly little
> warnings.

Applied to 5.13/scsi-staging, thanks! I fixed a few little things.

-- 
Martin K. Petersen	Oracle Linux Engineering

Re: [PATCH 00/36] [Set 4] Rid W=1 warnings in SCSI

[Lee Jones]

On Thu, 18 Mar 2021, Martin K. Petersen wrote:

> 
> Lee,
> 
> > This set is part of a larger effort attempting to clean-up W=1 kernel
> > builds, which are currently overwhelmingly riddled with niggly little
> > warnings.
> 
> Applied to 5.13/scsi-staging, thanks! I fixed a few little things.

Thanks for your continued support Martin.

-- 
Lee Jones [李琼斯]
Senior Technical Lead - Developer Services
Linaro.org │ Open source software for Arm SoCs
Follow Linaro: Facebook | Twitter | Blog

Re: [PATCH 00/36] [Set 4] Rid W=1 warnings in SCSI

[Martin K. Petersen]

On Wed, 17 Mar 2021 09:11:54 +0000, Lee Jones wrote:

> This set is part of a larger effort attempting to clean-up W=1
> kernel builds, which are currently overwhelmingly riddled with
> niggly little warnings.
> 
> Lee Jones (36):
>   scsi: myrb: Demote non-conformant kernel-doc headers and fix others
>   scsi: ipr: Fix incorrect function names in their headers
>   scsi: mvumi: Fix formatting and doc-rot issues
>   scsi: sd_zbc: Place function name into header
>   scsi: pmcraid: Fix a whole host of kernel-doc issues
>   scsi: sd: Fix function name in header
>   scsi: aic94xx: aic94xx_dump: Correct misspelling of function
>     asd_dump_seq_state()
>   scsi: be2iscsi: be_main: Ensure function follows directly after its
>     header
>   scsi: dc395x: Fix some function param descriptions
>   scsi: initio: Fix a few kernel-doc misdemeanours
>   scsi: a100u2w: Fix some misnaming and formatting issues
>   scsi: myrs: Add missing ':' to make the kernel-doc checker happy
>   scsi: pmcraid: Correct function name pmcraid_show_adapter_id() in
>     header
>   scsi: mpt3sas: mpt3sas_scs: Fix a few kernel-doc issues
>   scsi: be2iscsi: be_main: Demote incomplete/non-conformant kernel-doc
>     header
>   scsi: isci: phy: Fix a few different kernel-doc related issues
>   scsi: fnic: fnic_scsi: Demote non-conformant kernel-doc headers
>   scsi: fnic: fnic_fcs: Kernel-doc headers must contain the function
>     name
>   scsi: isci: phy: Provide function name and demote non-conforming
>     header
>   scsi: isci: request: Fix a myriad of kernel-doc issues
>   scsi: isci: host: Fix bunch of kernel-doc related issues
>   scsi: isci: task: Demote non-conformant header and remove superfluous
>     param
>   scsi: isci: remote_node_table: Fix a bunch of kernel-doc misdemeanours
>   scsi: isci: remote_node_context: Fix one function header and demote a
>     couple more
>   scsi: isci: port_config: Fix a bunch of doc-rot and demote abuses
>   scsi: isci: remote_device: Fix a bunch of doc-rot issues
>   scsi: isci: request: Fix doc-rot issue relating to 'ireq' param
>   scsi: isci: port: Fix a bunch of kernel-doc issues
>   scsi: isci: remote_node_context: Demote kernel-doc abuse
>   scsi: isci: remote_node_table: Provide some missing params and remove
>     others
>   scsi: cxlflash: main: Fix a little do-rot
>   scsi: cxlflash: superpipe: Fix a few misnaming issues
>   scsi: ibmvscsi: Fix a bunch of kernel-doc related issues
>   scsi: ibmvscsi: ibmvfc: Fix a bunch of misdocumentation
>   scsi: ibmvscsi_tgt: ibmvscsi_tgt: Remove duplicate section 'NOTE'
>   scsi: cxlflash: vlun: Fix some misnaming related doc-rot
> 
> [...]

Applied to 5.13/scsi-queue, thanks!

[01/36] scsi: myrb: Demote non-conformant kernel-doc headers and fix others
        https://git.kernel.org/mkp/scsi/c/12a1b740f225
[02/36] scsi: ipr: Fix incorrect function names in their headers
        https://git.kernel.org/mkp/scsi/c/637b5c3ebc1c
[03/36] scsi: mvumi: Fix formatting and doc-rot issues
        https://git.kernel.org/mkp/scsi/c/5ccd626516e1
[04/36] scsi: sd_zbc: Place function name into header
        https://git.kernel.org/mkp/scsi/c/59863cb53d80
[05/36] scsi: pmcraid: Fix a whole host of kernel-doc issues
        https://git.kernel.org/mkp/scsi/c/3673b7b0007b
[06/36] scsi: sd: Fix function name in header
        https://git.kernel.org/mkp/scsi/c/ad907c54e36f
[07/36] scsi: aic94xx: aic94xx_dump: Correct misspelling of function asd_dump_seq_state()
        https://git.kernel.org/mkp/scsi/c/3e2f4679ea03
[08/36] scsi: be2iscsi: be_main: Ensure function follows directly after its header
        https://git.kernel.org/mkp/scsi/c/f1d50e8ee5c9
[09/36] scsi: dc395x: Fix some function param descriptions
        https://git.kernel.org/mkp/scsi/c/33c8ef953ece
[10/36] scsi: initio: Fix a few kernel-doc misdemeanours
        https://git.kernel.org/mkp/scsi/c/100ec495e01e
[11/36] scsi: a100u2w: Fix some misnaming and formatting issues
        https://git.kernel.org/mkp/scsi/c/c548a6250627
[12/36] scsi: myrs: Add missing ':' to make the kernel-doc checker happy
        https://git.kernel.org/mkp/scsi/c/9eb292eb2ef7
[13/36] scsi: pmcraid: Correct function name pmcraid_show_adapter_id() in header
        https://git.kernel.org/mkp/scsi/c/a364a147b1dc
[14/36] scsi: mpt3sas: mpt3sas_scs: Fix a few kernel-doc issues
        https://git.kernel.org/mkp/scsi/c/a8d548b0b3ee
[15/36] scsi: be2iscsi: be_main: Demote incomplete/non-conformant kernel-doc header
        https://git.kernel.org/mkp/scsi/c/a90a8c607570
[16/36] scsi: isci: phy: Fix a few different kernel-doc related issues
        https://git.kernel.org/mkp/scsi/c/6af1d9bd9051
[17/36] scsi: fnic: fnic_scsi: Demote non-conformant kernel-doc headers
        https://git.kernel.org/mkp/scsi/c/c7eab0704c30
[18/36] scsi: fnic: fnic_fcs: Kernel-doc headers must contain the function name
        https://git.kernel.org/mkp/scsi/c/2efd8631d6a5
[19/36] scsi: isci: phy: Provide function name and demote non-conforming header
        https://git.kernel.org/mkp/scsi/c/6ab7ca5139b7
[20/36] scsi: isci: request: Fix a myriad of kernel-doc issues
        https://git.kernel.org/mkp/scsi/c/db35a0835357
[21/36] scsi: isci: host: Fix bunch of kernel-doc related issues
        https://git.kernel.org/mkp/scsi/c/44b7ca966128
[22/36] scsi: isci: task: Demote non-conformant header and remove superfluous param
        https://git.kernel.org/mkp/scsi/c/0afdee03f2e7
[23/36] scsi: isci: remote_node_table: Fix a bunch of kernel-doc misdemeanours
        https://git.kernel.org/mkp/scsi/c/103d61927ed3
[24/36] scsi: isci: remote_node_context: Fix one function header and demote a couple more
        https://git.kernel.org/mkp/scsi/c/ad276048f1bc
[25/36] scsi: isci: port_config: Fix a bunch of doc-rot and demote abuses
        https://git.kernel.org/mkp/scsi/c/29faa5ce26ae
[26/36] scsi: isci: remote_device: Fix a bunch of doc-rot issues
        https://git.kernel.org/mkp/scsi/c/242e15d7a4f4
[27/36] scsi: isci: request: Fix doc-rot issue relating to 'ireq' param
        https://git.kernel.org/mkp/scsi/c/a8604e44514d
[28/36] scsi: isci: port: Fix a bunch of kernel-doc issues
        https://git.kernel.org/mkp/scsi/c/7292a8b039c5
[29/36] scsi: isci: remote_node_context: Demote kernel-doc abuse
        https://git.kernel.org/mkp/scsi/c/d2d480f132e8
[30/36] scsi: isci: remote_node_table: Provide some missing params and remove others
        https://git.kernel.org/mkp/scsi/c/188f513dd22c
[31/36] scsi: cxlflash: main: Fix a little do-rot
        https://git.kernel.org/mkp/scsi/c/cf0ad7a15ac5
[32/36] scsi: cxlflash: superpipe: Fix a few misnaming issues
        https://git.kernel.org/mkp/scsi/c/32b3edfd28f8
[33/36] scsi: ibmvscsi: Fix a bunch of kernel-doc related issues
        https://git.kernel.org/mkp/scsi/c/841d7df0d416
[34/36] scsi: ibmvscsi: ibmvfc: Fix a bunch of misdocumentation
        https://git.kernel.org/mkp/scsi/c/dd9c77297148
[35/36] scsi: ibmvscsi_tgt: ibmvscsi_tgt: Remove duplicate section 'NOTE'
        https://git.kernel.org/mkp/scsi/c/cba3ebfc008e
[36/36] scsi: cxlflash: vlun: Fix some misnaming related doc-rot
        https://git.kernel.org/mkp/scsi/c/a690baa47fd1

-- 
Martin K. Petersen	Oracle Linux Engineering