Message-Id: <20210317091230.2912389-21-lee.jones@linaro.org>
Date:   Wed, 17 Mar 2021 09:12:14 +0000
From:   Lee Jones <lee.jones@...aro.org>
To:     lee.jones@...aro.org
Cc:     linux-kernel@...r.kernel.org,
        Artur Paszkiewicz <artur.paszkiewicz@...el.com>,
        "James E.J. Bottomley" <jejb@...ux.ibm.com>,
        "Martin K. Petersen" <martin.petersen@...cle.com>,
        linux-scsi@...r.kernel.org
Subject: [PATCH 20/36] scsi: isci: request: Fix a myriad of kernel-doc issues

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

 drivers/scsi/isci/request.c:211: warning: wrong kernel-doc identifier on line:
 drivers/scsi/isci/request.c:414: warning: wrong kernel-doc identifier on line:
 drivers/scsi/isci/request.c:472: warning: Function parameter or member 'ireq' not described in 'scu_ssp_task_request_construct_task_context'
 drivers/scsi/isci/request.c:472: warning: expecting prototype for The(). Prototype was for scu_ssp_task_request_construct_task_context() instead
 drivers/scsi/isci/request.c:501: warning: Function parameter or member 'ireq' not described in 'scu_sata_request_construct_task_context'
 drivers/scsi/isci/request.c:501: warning: expecting prototype for This method is will fill in the SCU Task Context for any type of SATA(). Prototype was for scu_sata_request_construct_task_context() instead
 drivers/scsi/isci/request.c:597: warning: Cannot understand  *
 drivers/scsi/isci/request.c:785: warning: expecting prototype for sci_req_tx_bytes(). Prototype was for SCU_TASK_CONTEXT_SRAM() instead
 drivers/scsi/isci/request.c:1399: warning: Cannot understand  *
 drivers/scsi/isci/request.c:1446: warning: Cannot understand  *
 drivers/scsi/isci/request.c:2465: warning: Function parameter or member 'task' not described in 'isci_request_process_response_iu'
 drivers/scsi/isci/request.c:2465: warning: Excess function parameter 'sas_task' description in 'isci_request_process_response_iu'
 drivers/scsi/isci/request.c:2501: warning: Function parameter or member 'task' not described in 'isci_request_set_open_reject_status'
 drivers/scsi/isci/request.c:2524: warning: Function parameter or member 'idev' not described in 'isci_request_handle_controller_specific_errors'
 drivers/scsi/isci/request.c:2524: warning: Function parameter or member 'task' not described in 'isci_request_handle_controller_specific_errors'
 drivers/scsi/isci/request.c:3337: warning: Function parameter or member 'idev' not described in 'isci_io_request_build'
 drivers/scsi/isci/request.c:3337: warning: Excess function parameter 'sci_device' description in 'isci_io_request_build'

Cc: Artur Paszkiewicz <artur.paszkiewicz@...el.com>
Cc: "James E.J. Bottomley" <jejb@...ux.ibm.com>
Cc: "Martin K. Petersen" <martin.petersen@...cle.com>
Cc: linux-scsi@...r.kernel.org
Signed-off-by: Lee Jones <lee.jones@...aro.org>
---
 drivers/scsi/isci/request.c | 58 ++++++++++++++++++-------------------
 1 file changed, 28 insertions(+), 30 deletions(-)

diff --git a/drivers/scsi/isci/request.c b/drivers/scsi/isci/request.c
index 58e62162882f2..49ab2555c0cdf 100644
--- a/drivers/scsi/isci/request.c
+++ b/drivers/scsi/isci/request.c
@@ -207,11 +207,8 @@ static void sci_task_request_build_ssp_task_iu(struct isci_request *ireq)
 		SCI_CONTROLLER_INVALID_IO_TAG;
 }
 
-/**
+/*
  * This method is will fill in the SCU Task Context for any type of SSP request.
- * @sci_req:
- * @task_context:
- *
  */
 static void scu_ssp_request_construct_task_context(
 	struct isci_request *ireq,
@@ -410,10 +407,8 @@ static void scu_ssp_ireq_dif_strip(struct isci_request *ireq, u8 type, u8 op)
 	tc->ref_tag_seed_gen = 0;
 }
 
-/**
+/*
  * This method is will fill in the SCU Task Context for a SSP IO request.
- * @sci_req:
- *
  */
 static void scu_ssp_io_request_construct_task_context(struct isci_request *ireq,
 						      enum dma_data_direction dir,
@@ -456,17 +451,16 @@ static void scu_ssp_io_request_construct_task_context(struct isci_request *ireq,
 }
 
 /**
- * This method will fill in the SCU Task Context for a SSP Task request.  The
- *    following important settings are utilized: -# priority ==
- *    SCU_TASK_PRIORITY_HIGH.  This ensures that the task request is issued
- *    ahead of other task destined for the same Remote Node. -# task_type ==
- *    SCU_TASK_TYPE_IOREAD.  This simply indicates that a normal request type
- *    (i.e. non-raw frame) is being utilized to perform task management. -#
- *    control_frame == 1.  This ensures that the proper endianess is set so
- *    that the bytes are transmitted in the right order for a task frame.
- * @sci_req: This parameter specifies the task request object being
- *    constructed.
- *
+ * scu_ssp_task_request_construct_task_context() - This method will fill in
+ *    the SCU Task Context for a SSP Task request.  The following important
+ *    settings are utilized: -# priority == SCU_TASK_PRIORITY_HIGH.  This
+ *    ensures that the task request is issued ahead of other task destined
+ *    for the same Remote Node. -# task_type == SCU_TASK_TYPE_IOREAD.  This
+ *    simply indicates that a normal request type (i.e. non-raw frame) is
+ *    being utilized to perform task management. -#control_frame == 1.  This
+ *    ensures that the proper endianess is set so that the bytes are
+ *    transmitted in the right order for a task frame.
+ * @ireq: This parameter specifies the task request object being constructed.
  */
 static void scu_ssp_task_request_construct_task_context(struct isci_request *ireq)
 {
@@ -484,6 +478,7 @@ static void scu_ssp_task_request_construct_task_context(struct isci_request *ire
 }
 
 /**
+ * scu_sata_request_construct_task_context()
  * This method is will fill in the SCU Task Context for any type of SATA
  *    request.  This is called from the various SATA constructors.
  * @sci_req: The general IO request object which is to be used in
@@ -593,9 +588,9 @@ static enum sci_status sci_stp_pio_request_construct(struct isci_request *ireq,
 	return SCI_SUCCESS;
 }
 
-/**
- *
- * @sci_req: This parameter specifies the request to be constructed as an
+/*
+ * sci_stp_optimized_request_construct()
+ * @ireq: This parameter specifies the request to be constructed as an
  *    optimized request.
  * @optimized_task_type: This parameter specifies whether the request is to be
  *    an UDMA request or a NCQ request. - A value of 0 indicates UDMA. - A
@@ -778,11 +773,11 @@ static enum sci_status sci_io_request_construct_basic_sata(struct isci_request *
 	return status;
 }
 
+#define SCU_TASK_CONTEXT_SRAM 0x200000
 /**
  * sci_req_tx_bytes - bytes transferred when reply underruns request
  * @ireq: request that was terminated early
  */
-#define SCU_TASK_CONTEXT_SRAM 0x200000
 static u32 sci_req_tx_bytes(struct isci_request *ireq)
 {
 	struct isci_host *ihost = ireq->owning_controller;
@@ -1396,10 +1391,10 @@ static enum sci_status sci_stp_request_pio_data_out_transmit_data(struct isci_re
 }
 
 /**
- *
- * @stp_request: The request that is used for the SGL processing.
- * @data_buffer: The buffer of data to be copied.
- * @length: The length of the data transfer.
+ * sci_stp_request_pio_data_in_copy_data_buffer()
+ * @stp_req: The request that is used for the SGL processing.
+ * @data_buf: The buffer of data to be copied.
+ * @len: The length of the data transfer.
  *
  * Copy the data from the buffer for the length specified to the IO request SGL
  * specified data region. enum sci_status
@@ -1443,8 +1438,8 @@ sci_stp_request_pio_data_in_copy_data_buffer(struct isci_stp_request *stp_req,
 }
 
 /**
- *
- * @sci_req: The PIO DATA IN request that is to receive the data.
+ * sci_stp_request_pio_data_in_copy_data()
+ * @stp_req: The PIO DATA IN request that is to receive the data.
  * @data_buffer: The buffer to copy from.
  *
  * Copy the data buffer to the io request data region. enum sci_status
@@ -2452,7 +2447,7 @@ sci_io_request_tc_completion(struct isci_request *ireq,
  * isci_request_process_response_iu() - This function sets the status and
  *    response iu, in the task struct, from the request object for the upper
  *    layer driver.
- * @sas_task: This parameter is the task struct from the upper layer driver.
+ * @task: This parameter is the task struct from the upper layer driver.
  * @resp_iu: This parameter points to the response iu of the completed request.
  * @dev: This parameter specifies the linux device struct.
  *
@@ -2485,6 +2480,7 @@ static void isci_request_process_response_iu(
  * isci_request_set_open_reject_status() - This function prepares the I/O
  *    completion for OPEN_REJECT conditions.
  * @request: This parameter is the completed isci_request object.
+ * @task: This parameter is the task struct from the upper layer driver.
  * @response_ptr: This parameter specifies the service response for the I/O.
  * @status_ptr: This parameter specifies the exec status for the I/O.
  * @open_rej_reason: This parameter specifies the encoded reason for the
@@ -2509,7 +2505,9 @@ static void isci_request_set_open_reject_status(
 /**
  * isci_request_handle_controller_specific_errors() - This function decodes
  *    controller-specific I/O completion error conditions.
+ * @idev: Remote device
  * @request: This parameter is the completed isci_request object.
+ * @task: This parameter is the task struct from the upper layer driver.
  * @response_ptr: This parameter specifies the service response for the I/O.
  * @status_ptr: This parameter specifies the exec status for the I/O.
  *
@@ -3326,7 +3324,7 @@ static enum sci_status isci_smp_request_build(struct isci_request *ireq)
  * @ihost: This parameter specifies the ISCI host object
  * @request: This parameter points to the isci_request object allocated in the
  *    request construct function.
- * @sci_device: This parameter is the handle for the sci core's remote device
+ * @idev: This parameter is the handle for the sci core's remote device
  *    object that is the destination for this request.
  *
  * SCI_SUCCESS on successfull completion, or specific failure code.
-- 
2.27.0

Powered by blists - more mailing lists