From 8aa29f192ca675746ab4f39e46a5fd712a76faa6 Mon Sep 17 00:00:00 2001 From: Bart Van Assche Date: Thu, 1 Mar 2018 15:07:20 -0800 Subject: [PATCH] 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: Bart Van Assche Cc: Vivek Gautam Cc: Stanislav Nijnikov Signed-off-by: Martin K. Petersen --- drivers/scsi/ufs/tc-dwc-g210-pci.c | 4 +- drivers/scsi/ufs/tc-dwc-g210-pltfrm.c | 2 +- drivers/scsi/ufs/ufshcd-pci.c | 7 +- drivers/scsi/ufs/ufshcd.c | 94 +++++++++++++-------------- 4 files changed, 52 insertions(+), 55 deletions(-) diff --git a/drivers/scsi/ufs/tc-dwc-g210-pci.c b/drivers/scsi/ufs/tc-dwc-g210-pci.c index 325d5e14fc0d..2f41722a8c28 100644 --- a/drivers/scsi/ufs/tc-dwc-g210-pci.c +++ b/drivers/scsi/ufs/tc-dwc-g210-pci.c @@ -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) { diff --git a/drivers/scsi/ufs/tc-dwc-g210-pltfrm.c b/drivers/scsi/ufs/tc-dwc-g210-pltfrm.c index 2d3f5270f875..6dfe5a9206e9 100644 --- a/drivers/scsi/ufs/tc-dwc-g210-pltfrm.c +++ b/drivers/scsi/ufs/tc-dwc-g210-pltfrm.c @@ -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 = { diff --git a/drivers/scsi/ufs/ufshcd-pci.c b/drivers/scsi/ufs/ufshcd-pci.c index 925b0ec7ec54..ffe6f82182ba 100644 --- a/drivers/scsi/ufs/ufshcd-pci.c +++ b/drivers/scsi/ufs/ufshcd-pci.c @@ -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) { diff --git a/drivers/scsi/ufs/ufshcd.c b/drivers/scsi/ufs/ufshcd.c index 1fbb17bb175b..3abcd31646eb 100644 --- a/drivers/scsi/ufs/ufshcd.c +++ b/drivers/scsi/ufs/ufshcd.c @@ -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) {