Commit 8aa29f19 authored by Bart Van Assche's avatar Bart Van Assche Committed by Martin K. Petersen
Browse files

scsi: ufs: Fix kernel-doc errors and warnings 



Avoid that the kernel-doc tool complains about mismatches between
kernel-doc headers and function definitions. Avoid that errors like the
following are reported when building the UFS driver with W=1:

drivers/scsi/ufs/tc-dwc-g210-pci.c:60: error: Cannot parse struct or union!
drivers/scsi/ufs/tc-dwc-g210-pltfrm.c:26: warning: cannot understand function prototype: 'struct ufs_hba_variant_ops tc_dwc_g210_20bit_pltfm_hba_vops = '

Signed-off-by: default avatarBart Van Assche <bart.vanassche@wdc.com>
Cc: Vivek Gautam <vivek.gautam@codeaurora.org>
Cc: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
Signed-off-by: default avatarMartin K. Petersen <martin.petersen@oracle.com>
parent e0b14a4a

drivers/scsi/ufs/tc-dwc-g210-pci.c

+2 −2
Original line number Diff line number Diff line
@@ -51,7 +51,7 @@ static int tc_dwc_g210_pci_runtime_idle(struct device *dev) 
	return ufshcd_runtime_idle(dev_get_drvdata(dev));

}



/**

/*

 * struct ufs_hba_dwc_vops - UFS DWC specific variant operations

 */

static struct ufs_hba_variant_ops tc_dwc_g210_pci_hba_vops = {
@@ -71,7 +71,7 @@ static void tc_dwc_g210_pci_shutdown(struct pci_dev *pdev) 
/**

 * tc_dwc_g210_pci_remove - de-allocate PCI/SCSI host and host memory space

 *		data structure memory

 * @pdev - pointer to PCI handle

 * @pdev: pointer to PCI handle

 */

static void tc_dwc_g210_pci_remove(struct pci_dev *pdev)

{

drivers/scsi/ufs/tc-dwc-g210-pltfrm.c

+1 −1
Original line number Diff line number Diff line
@@ -20,7 +20,7 @@ 
#include "ufshcd-dwc.h"

#include "tc-dwc-g210.h"



/**

/*

 * UFS DWC specific variant operations

 */

static struct ufs_hba_variant_ops tc_dwc_g210_20bit_pltfm_hba_vops = {

drivers/scsi/ufs/ufshcd-pci.c

+3 −4
Original line number Diff line number Diff line
@@ -75,8 +75,7 @@ static struct ufs_hba_variant_ops ufs_intel_cnl_hba_vops = { 
#ifdef CONFIG_PM_SLEEP

/**

 * ufshcd_pci_suspend - suspend power management function

 * @pdev: pointer to PCI device handle

 * @state: power state

 * @dev: pointer to PCI device handle

 *

 * Returns 0 if successful

 * Returns non-zero otherwise
@@ -88,7 +87,7 @@ static int ufshcd_pci_suspend(struct device *dev) 


/**

 * ufshcd_pci_resume - resume power management function

 * @pdev: pointer to PCI device handle

 * @dev: pointer to PCI device handle

 *

 * Returns 0 if successful

 * Returns non-zero otherwise
@@ -126,7 +125,7 @@ static void ufshcd_pci_shutdown(struct pci_dev *pdev) 
/**

 * ufshcd_pci_remove - de-allocate PCI/SCSI host and host memory space

 *		data structure memory

 * @pdev - pointer to PCI handle

 * @pdev: pointer to PCI handle

 */

static void ufshcd_pci_remove(struct pci_dev *pdev)

{

drivers/scsi/ufs/ufshcd.c

+46 −48
Original line number Diff line number Diff line
@@ -524,7 +524,7 @@ int ufshcd_wait_for_register(struct ufs_hba *hba, u32 reg, u32 mask, 


/**

 * ufshcd_get_intr_mask - Get the interrupt bit mask

 * @hba - Pointer to adapter instance

 * @hba: Pointer to adapter instance

 *

 * Returns interrupt bit mask per version

 */
@@ -551,7 +551,7 @@ static inline u32 ufshcd_get_intr_mask(struct ufs_hba *hba) 


/**

 * ufshcd_get_ufs_version - Get the UFS version supported by the HBA

 * @hba - Pointer to adapter instance

 * @hba: Pointer to adapter instance

 *

 * Returns UFSHCI version supported by the controller

 */
@@ -578,7 +578,7 @@ static inline bool ufshcd_is_device_present(struct ufs_hba *hba) 


/**

 * ufshcd_get_tr_ocs - Get the UTRD Overall Command Status

 * @lrb: pointer to local command reference block

 * @lrbp: pointer to local command reference block

 *

 * This function is used to get the OCS field from UTRD

 * Returns the OCS field in the UTRD
@@ -1738,7 +1738,7 @@ void ufshcd_send_command(struct ufs_hba *hba, unsigned int task_tag) 


/**

 * ufshcd_copy_sense_data - Copy sense data in case of check condition

 * @lrb - pointer to local reference block

 * @lrbp: pointer to local reference block

 */

static inline void ufshcd_copy_sense_data(struct ufshcd_lrb *lrbp)

{
@@ -1760,7 +1760,7 @@ static inline void ufshcd_copy_sense_data(struct ufshcd_lrb *lrbp) 
 * ufshcd_copy_query_response() - Copy the Query Response and the data

 * descriptor

 * @hba: per adapter instance

 * @lrb - pointer to local reference block

 * @lrbp: pointer to local reference block

 */

static

int ufshcd_copy_query_response(struct ufs_hba *hba, struct ufshcd_lrb *lrbp)
@@ -1861,7 +1861,7 @@ ufshcd_dispatch_uic_cmd(struct ufs_hba *hba, struct uic_command *uic_cmd) 
/**

 * ufshcd_wait_for_uic_cmd - Wait complectioin of UIC command

 * @hba: per adapter instance

 * @uic_command: UIC command

 * @uic_cmd: UIC command

 *

 * Must be called with mutex held.

 * Returns 0 only if success.
@@ -1944,7 +1944,8 @@ ufshcd_send_uic_cmd(struct ufs_hba *hba, struct uic_command *uic_cmd) 


/**

 * ufshcd_map_sg - Map scatter-gather list to prdt

 * @lrbp - pointer to local reference block

 * @hba: per adapter instance

 * @lrbp: pointer to local reference block

 *

 * Returns 0 in case of success, non-zero value in case of failure

 */
@@ -2080,8 +2081,8 @@ static void ufshcd_prepare_req_desc_hdr(struct ufshcd_lrb *lrbp, 
/**

 * ufshcd_prepare_utp_scsi_cmd_upiu() - fills the utp_transfer_req_desc,

 * for scsi commands

 * @lrbp - local reference block pointer

 * @upiu_flags - flags

 * @lrbp: local reference block pointer

 * @upiu_flags: flags

 */

static

void ufshcd_prepare_utp_scsi_cmd_upiu(struct ufshcd_lrb *lrbp, u32 upiu_flags)
@@ -2169,8 +2170,8 @@ static inline void ufshcd_prepare_utp_nop_upiu(struct ufshcd_lrb *lrbp) 
/**

 * ufshcd_comp_devman_upiu - UFS Protocol Information Unit(UPIU)

 *			     for Device Management Purposes

 * @hba - per adapter instance

 * @lrb - pointer to local reference block

 * @hba: per adapter instance

 * @lrbp: pointer to local reference block

 */

static int ufshcd_comp_devman_upiu(struct ufs_hba *hba, struct ufshcd_lrb *lrbp)

{
@@ -2197,8 +2198,8 @@ static int ufshcd_comp_devman_upiu(struct ufs_hba *hba, struct ufshcd_lrb *lrbp) 
/**

 * ufshcd_comp_scsi_upiu - UFS Protocol Information Unit(UPIU)

 *			   for SCSI Purposes

 * @hba - per adapter instance

 * @lrb - pointer to local reference block

 * @hba: per adapter instance

 * @lrbp: pointer to local reference block

 */

static int ufshcd_comp_scsi_upiu(struct ufs_hba *hba, struct ufshcd_lrb *lrbp)

{
@@ -2224,7 +2225,7 @@ static int ufshcd_comp_scsi_upiu(struct ufs_hba *hba, struct ufshcd_lrb *lrbp) 


/**

 * ufshcd_upiu_wlun_to_scsi_wlun - maps UPIU W-LUN id to SCSI W-LUN ID

 * @scsi_lun: UPIU W-LUN id

 * @upiu_wlun_id: UPIU W-LUN id

 *

 * Returns SCSI W-LUN id

 */
@@ -2235,8 +2236,8 @@ static inline u16 ufshcd_upiu_wlun_to_scsi_wlun(u8 upiu_wlun_id) 


/**

 * ufshcd_queuecommand - main entry point for SCSI requests

 * @host: SCSI host pointer

 * @cmd: command from SCSI Midlayer

 * @done: call back function

 *

 * Returns 0 for success, non-zero in case of failure

 */
@@ -2477,7 +2478,7 @@ static int ufshcd_wait_for_dev_cmd(struct ufs_hba *hba, 
/**

 * ufshcd_get_dev_cmd_tag - Get device management command tag

 * @hba: per-adapter instance

 * @tag: pointer to variable with available slot value

 * @tag_out: pointer to variable with available slot value

 *

 * Get a free slot and lock it until device management command

 * completes.
@@ -2514,9 +2515,9 @@ static inline void ufshcd_put_dev_cmd_tag(struct ufs_hba *hba, int tag) 


/**

 * ufshcd_exec_dev_cmd - API for sending device management requests

 * @hba - UFS hba

 * @cmd_type - specifies the type (NOP, Query...)

 * @timeout - time in seconds

 * @hba: UFS hba

 * @cmd_type: specifies the type (NOP, Query...)

 * @timeout: time in seconds

 *

 * NOTE: Since there is only one available tag for device management commands,

 * it is expected you hold the hba->dev_cmd.lock mutex.
@@ -2613,10 +2614,10 @@ static int ufshcd_query_flag_retry(struct ufs_hba *hba, 


/**

 * ufshcd_query_flag() - API function for sending flag query requests

 * hba: per-adapter instance

 * query_opcode: flag query to perform

 * idn: flag idn to access

 * flag_res: the flag value after the query request completes

 * @hba: per-adapter instance

 * @opcode: flag query to perform

 * @idn: flag idn to access

 * @flag_res: the flag value after the query request completes

 *

 * Returns 0 for success, non-zero in case of failure

 */
@@ -2680,12 +2681,12 @@ out_unlock: 


/**

 * ufshcd_query_attr - API function for sending attribute requests

 * hba: per-adapter instance

 * opcode: attribute opcode

 * idn: attribute idn to access

 * index: index field

 * selector: selector field

 * attr_val: the attribute value after the query request completes

 * @hba: per-adapter instance

 * @opcode: attribute opcode

 * @idn: attribute idn to access

 * @index: index field

 * @selector: selector field

 * @attr_val: the attribute value after the query request completes

 *

 * Returns 0 for success, non-zero in case of failure

*/
@@ -2844,15 +2845,14 @@ out: 
}



/**

 * ufshcd_query_descriptor_retry - API function for sending descriptor

 * requests

 * hba: per-adapter instance

 * opcode: attribute opcode

 * idn: attribute idn to access

 * index: index field

 * selector: selector field

 * desc_buf: the buffer that contains the descriptor

 * buf_len: length parameter passed to the device

 * ufshcd_query_descriptor_retry - API function for sending descriptor requests

 * @hba: per-adapter instance

 * @opcode: attribute opcode

 * @idn: attribute idn to access

 * @index: index field

 * @selector: selector field

 * @desc_buf: the buffer that contains the descriptor

 * @buf_len: length parameter passed to the device

 *

 * Returns 0 for success, non-zero in case of failure.

 * The buf_len parameter will contain, on return, the length parameter
@@ -3077,7 +3077,6 @@ static int ufshcd_read_device_desc(struct ufs_hba *hba, u8 *buf, u32 size) 
 *

 * Return 0 in case of success, non-zero otherwise

 */

#define ASCII_STD true

int ufshcd_read_string_desc(struct ufs_hba *hba, int desc_index,

			    u8 *buf, u32 size, bool ascii)

{
@@ -3879,7 +3878,7 @@ static int ufshcd_config_pwr_mode(struct ufs_hba *hba, 


/**

 * ufshcd_complete_dev_init() - checks device readiness

 * hba: per-adapter instance

 * @hba: per-adapter instance

 *

 * Set fDeviceInit flag and poll until device toggles it.

 */
@@ -4418,7 +4417,7 @@ static int ufshcd_task_req_compl(struct ufs_hba *hba, u32 index, u8 *resp) 


/**

 * ufshcd_scsi_cmd_status - Update SCSI command result based on SCSI status

 * @lrb: pointer to local reference block of completed command

 * @lrbp: pointer to local reference block of completed command

 * @scsi_status: SCSI command status

 *

 * Returns value base on SCSI command status
@@ -4453,7 +4452,7 @@ ufshcd_scsi_cmd_status(struct ufshcd_lrb *lrbp, int scsi_status) 
/**

 * ufshcd_transfer_rsp_status - Get overall status of the response

 * @hba: per adapter instance

 * @lrb: pointer to local reference block of completed command

 * @lrbp: pointer to local reference block of completed command

 *

 * Returns result of the command to notify SCSI midlayer

 */
@@ -5761,7 +5760,7 @@ static int ufshcd_reset_and_restore(struct ufs_hba *hba) 


/**

 * ufshcd_eh_host_reset_handler - host reset handler registered to scsi layer

 * @cmd - SCSI command pointer

 * @cmd: SCSI command pointer

 *

 * Returns SUCCESS/FAILED

 */
@@ -5946,11 +5945,11 @@ static void ufshcd_init_icc_levels(struct ufs_hba *hba) 
 * will take effect only when its sent to "UFS device" well known logical unit

 * hence we require the scsi_device instance to represent this logical unit in

 * order for the UFS host driver to send the SSU command for power management.



 *

 * We also require the scsi_device instance for "RPMB" (Replay Protected Memory

 * Block) LU so user space process can control this LU. User space may also

 * want to have access to BOOT LU.



 *

 * This function adds scsi device instances for each of all well known LUs

 * (except "REPORT LUNS" LU).

 *
@@ -6019,7 +6018,7 @@ static int ufs_get_device_desc(struct ufs_hba *hba, 
	model_index = desc_buf[DEVICE_DESC_PARAM_PRDCT_NAME];



	err = ufshcd_read_string_desc(hba, model_index, str_desc_buf,

				QUERY_DESC_MAX_SIZE, ASCII_STD);

				      QUERY_DESC_MAX_SIZE, true/*ASCII*/);

	if (err) {

		dev_err(hba->dev, "%s: Failed reading Product Name. err = %d\n",

			__func__, err);
@@ -7413,7 +7412,6 @@ out: 
/**

 * ufshcd_system_suspend - system suspend routine

 * @hba: per adapter instance

 * @pm_op: runtime PM or system PM

 *

 * Check the description of ufshcd_suspend() function for more details.

 *
@@ -7597,7 +7595,7 @@ EXPORT_SYMBOL(ufshcd_shutdown); 
/**

 * ufshcd_remove - de-allocate SCSI host and host memory space

 *		data structure memory

 * @hba - per adapter instance

 * @hba: per adapter instance

 */

void ufshcd_remove(struct ufs_hba *hba)

{

CRA Git | Maintained and supported by SUSTech CRA and CCSE