Proxmox-Port/linux-loongson
1
0
Fork 0
mirror of https://git.kernel.org/pub/scm/linux/kernel/git/chenhuacai/linux-loongson synced 2025-09-02 16:44:59 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

scsi: ufs: core: Improve return value documentation

Browse Source 
Some functions return a negative value to indicate an error while other
functions return a value != 0 to indicate an error. Document the return
value behavior where this documentation is missing and fix the return
value documentation where necessary. Add warnings to detect mismatches
between documentation and implementation. This matters because several
sysfs callback functions only work correctly if a negative value is
returned upon error.

Signed-off-by: Bart Van Assche <bvanassche@acm.org>
Link: https://lore.kernel.org/r/20250623215909.4169007-1-bvanassche@acm.org
Signed-off-by: Martin K. Petersen <martin.petersen@oracle.com>
This commit is contained in:
Bart Van Assche 2025-06-23 14:59:01 -07:00 committed by Martin K. Petersen
parent 26b971d58a
commit cc59f3b685
1 changed files with 29 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

37
drivers/ufs/core/ufshcd.c
View File

@ -2566,7 +2566,7 @@ ufshcd_wait_for_uic_cmd(struct ufs_hba *hba, struct uic_command *uic_cmd)
* @hba: per adapter instance * @hba: per adapter instance
* @uic_cmd: UIC command * @uic_cmd: UIC command
* *
* Return: 0 only if success. * Return: 0 if successful; < 0 upon failure.
*/ */
static int static int
__ufshcd_send_uic_cmd(struct ufs_hba *hba, struct uic_command *uic_cmd) __ufshcd_send_uic_cmd(struct ufs_hba *hba, struct uic_command *uic_cmd)
@ -3072,6 +3072,9 @@ static void ufshcd_setup_dev_cmd(struct ufs_hba *hba, struct ufshcd_lrb *lrbp,
hba->dev_cmd.type = cmd_type; hba->dev_cmd.type = cmd_type;
} }
/*
* Return: 0 upon success; < 0 upon failure.
*/
static int ufshcd_compose_dev_cmd(struct ufs_hba *hba, static int ufshcd_compose_dev_cmd(struct ufs_hba *hba,
struct ufshcd_lrb *lrbp, enum dev_cmd_type cmd_type, int tag) struct ufshcd_lrb *lrbp, enum dev_cmd_type cmd_type, int tag)
{ {
@ -3184,9 +3187,13 @@ ufshcd_dev_cmd_completion(struct ufs_hba *hba, struct ufshcd_lrb *lrbp)
break; break;
} }
WARN_ONCE(err > 0, "Incorrect return value %d > 0\n", err);
return err; return err;
} }
/*
* Return: 0 upon success; < 0 upon failure.
*/
static int ufshcd_wait_for_dev_cmd(struct ufs_hba *hba, static int ufshcd_wait_for_dev_cmd(struct ufs_hba *hba,
struct ufshcd_lrb *lrbp, int max_timeout) struct ufshcd_lrb *lrbp, int max_timeout)
{ {
@ -3261,6 +3268,7 @@ static int ufshcd_wait_for_dev_cmd(struct ufs_hba *hba,
} }
} }
WARN_ONCE(err > 0, "Incorrect return value %d > 0\n", err);
return err; return err;
} }
@ -3278,6 +3286,9 @@ static void ufshcd_dev_man_unlock(struct ufs_hba *hba)
ufshcd_release(hba); ufshcd_release(hba);
} }
/*
* Return: 0 upon success; < 0 upon failure.
*/
static int ufshcd_issue_dev_cmd(struct ufs_hba *hba, struct ufshcd_lrb *lrbp, static int ufshcd_issue_dev_cmd(struct ufs_hba *hba, struct ufshcd_lrb *lrbp,
const u32 tag, int timeout) const u32 tag, int timeout)
{ {
@ -3365,6 +3376,7 @@ static int ufshcd_query_flag_retry(struct ufs_hba *hba,
dev_err(hba->dev, dev_err(hba->dev,
"%s: query flag, opcode %d, idn %d, failed with error %d after %d retries\n", "%s: query flag, opcode %d, idn %d, failed with error %d after %d retries\n",
__func__, opcode, idn, ret, retries); __func__, opcode, idn, ret, retries);
WARN_ONCE(ret > 0, "Incorrect return value %d > 0\n", ret);
return ret; return ret;
} }
@ -3376,7 +3388,7 @@ static int ufshcd_query_flag_retry(struct ufs_hba *hba,
* @index: flag index to access * @index: flag index to access
* @flag_res: the flag value after the query request completes * @flag_res: the flag value after the query request completes
* *
* Return: 0 for success, non-zero in case of failure. * Return: 0 for success; < 0 upon failure.
*/ */
int ufshcd_query_flag(struct ufs_hba *hba, enum query_opcode opcode, int ufshcd_query_flag(struct ufs_hba *hba, enum query_opcode opcode,
enum flag_idn idn, u8 index, bool *flag_res) enum flag_idn idn, u8 index, bool *flag_res)
@ -3432,6 +3444,7 @@ int ufshcd_query_flag(struct ufs_hba *hba, enum query_opcode opcode,
out_unlock: out_unlock:
ufshcd_dev_man_unlock(hba); ufshcd_dev_man_unlock(hba);
WARN_ONCE(err > 0, "Incorrect return value %d > 0\n", err);
return err; return err;
} }
@ -3444,7 +3457,7 @@ int ufshcd_query_flag(struct ufs_hba *hba, enum query_opcode opcode,
* @selector: selector field * @selector: selector field
* @attr_val: the attribute value after the query request completes * @attr_val: the attribute value after the query request completes
* *
* Return: 0 for success, non-zero in case of failure. * Return: 0 upon success; < 0 upon failure.
*/ */
int ufshcd_query_attr(struct ufs_hba *hba, enum query_opcode opcode, int ufshcd_query_attr(struct ufs_hba *hba, enum query_opcode opcode,
enum attr_idn idn, u8 index, u8 selector, u32 *attr_val) enum attr_idn idn, u8 index, u8 selector, u32 *attr_val)
@ -3493,6 +3506,7 @@ int ufshcd_query_attr(struct ufs_hba *hba, enum query_opcode opcode,
out_unlock: out_unlock:
ufshcd_dev_man_unlock(hba); ufshcd_dev_man_unlock(hba);
WARN_ONCE(err > 0, "Incorrect return value %d > 0\n", err);
return err; return err;
} }
@ -3507,7 +3521,7 @@ int ufshcd_query_attr(struct ufs_hba *hba, enum query_opcode opcode,
* @attr_val: the attribute value after the query request * @attr_val: the attribute value after the query request
* completes * completes
* *
* Return: 0 for success, non-zero in case of failure. * Return: 0 for success; < 0 upon failure.
*/ */
int ufshcd_query_attr_retry(struct ufs_hba *hba, int ufshcd_query_attr_retry(struct ufs_hba *hba,
enum query_opcode opcode, enum attr_idn idn, u8 index, u8 selector, enum query_opcode opcode, enum attr_idn idn, u8 index, u8 selector,
@ -3530,9 +3544,13 @@ int ufshcd_query_attr_retry(struct ufs_hba *hba,
dev_err(hba->dev, dev_err(hba->dev,
"%s: query attribute, idn %d, failed with error %d after %d retries\n", "%s: query attribute, idn %d, failed with error %d after %d retries\n",
__func__, idn, ret, QUERY_REQ_RETRIES); __func__, idn, ret, QUERY_REQ_RETRIES);
WARN_ONCE(ret > 0, "Incorrect return value %d > 0\n", ret);
return ret; return ret;
} }
/*
* Return: 0 if successful; < 0 upon failure.
*/
static int __ufshcd_query_descriptor(struct ufs_hba *hba, static int __ufshcd_query_descriptor(struct ufs_hba *hba,
enum query_opcode opcode, enum desc_idn idn, u8 index, enum query_opcode opcode, enum desc_idn idn, u8 index,
u8 selector, u8 *desc_buf, int *buf_len) u8 selector, u8 *desc_buf, int *buf_len)
@ -3590,6 +3608,7 @@ static int __ufshcd_query_descriptor(struct ufs_hba *hba,
out_unlock: out_unlock:
hba->dev_cmd.query.descriptor = NULL; hba->dev_cmd.query.descriptor = NULL;
ufshcd_dev_man_unlock(hba); ufshcd_dev_man_unlock(hba);
WARN_ONCE(err > 0, "Incorrect return value %d > 0\n", err);
return err; return err;
} }
@ -3606,7 +3625,7 @@ static int __ufshcd_query_descriptor(struct ufs_hba *hba,
* The buf_len parameter will contain, on return, the length parameter * The buf_len parameter will contain, on return, the length parameter
* received on the response. * received on the response.
* *
* Return: 0 for success, non-zero in case of failure. * Return: 0 for success; < 0 upon failure.
*/ */
int ufshcd_query_descriptor_retry(struct ufs_hba *hba, int ufshcd_query_descriptor_retry(struct ufs_hba *hba,
enum query_opcode opcode, enum query_opcode opcode,
@ -3624,6 +3643,7 @@ int ufshcd_query_descriptor_retry(struct ufs_hba *hba,
break; break;
} }
WARN_ONCE(err > 0, "Incorrect return value %d > 0\n", err);
return err; return err;
} }
@ -3636,7 +3656,7 @@ int ufshcd_query_descriptor_retry(struct ufs_hba *hba,
* @param_read_buf: pointer to buffer where parameter would be read * @param_read_buf: pointer to buffer where parameter would be read
* @param_size: sizeof(param_read_buf) * @param_size: sizeof(param_read_buf)
* *
* Return: 0 in case of success, non-zero otherwise. * Return: 0 in case of success; < 0 upon failure.
*/ */
int ufshcd_read_desc_param(struct ufs_hba *hba, int ufshcd_read_desc_param(struct ufs_hba *hba,
enum desc_idn desc_id, enum desc_idn desc_id,
@ -3703,6 +3723,7 @@ int ufshcd_read_desc_param(struct ufs_hba *hba,
out: out:
if (is_kmalloc) if (is_kmalloc)
kfree(desc_buf); kfree(desc_buf);
WARN_ONCE(ret > 0, "Incorrect return value %d > 0\n", ret);
return ret; return ret;
} }
@ -3816,7 +3837,7 @@ int ufshcd_read_string_desc(struct ufs_hba *hba, u8 desc_index,
* @param_read_buf: pointer to buffer where parameter would be read * @param_read_buf: pointer to buffer where parameter would be read
* @param_size: sizeof(param_read_buf) * @param_size: sizeof(param_read_buf)
* *
* Return: 0 in case of success, non-zero otherwise. * Return: 0 in case of success; < 0 upon failure.
*/ */
static inline int ufshcd_read_unit_desc_param(struct ufs_hba *hba, static inline int ufshcd_read_unit_desc_param(struct ufs_hba *hba,
int lun, int lun,
@ -4794,7 +4815,7 @@ static int ufshcd_complete_dev_init(struct ufs_hba *hba)
* 3. Program UTRL and UTMRL base address * 3. Program UTRL and UTMRL base address
* 4. Configure run-stop-registers * 4. Configure run-stop-registers
* *
* Return: 0 on success, non-zero value on failure. * Return: 0 if successful; < 0 upon failure.
*/ */
int ufshcd_make_hba_operational(struct ufs_hba *hba) int ufshcd_make_hba_operational(struct ufs_hba *hba)
{ {