From 18b31dff9306e99b639dd771af66ac83fda1f67b Mon Sep 17 00:00:00 2001 From: "Ewan D. Milne" Date: Fri, 11 Apr 2025 15:52:18 -0400 Subject: [PATCH] scsi: scsi_lib: Add kernel-doc for exported functions JIRA: https://issues.redhat.com/browse/RHEL-86156 Upstream Status: From upstream linux mainline Add kernel-doc for scsi_failures_reset_retries() and scsi_alloc_request() since these are exported. This allows them to be part of the SCSI driver-api docbook. Fix kernel-doc comments for scsi_vpd_tpg_id() [add kernel-doc for one parameter and fix a typo]. Signed-off-by: Randy Dunlap Link: https://lore.kernel.org/r/20241212205217.597844-4-rdunlap@infradead.org CC: James E.J. Bottomley CC: Martin K. Petersen Signed-off-by: Martin K. Petersen (cherry picked from commit 39d2112ab7c8050642fdc2830a0a3edc5337827f) Signed-off-by: Ewan D. Milne --- drivers/scsi/scsi_lib.c | 21 ++++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) diff --git a/drivers/scsi/scsi_lib.c b/drivers/scsi/scsi_lib.c index b6575f365c61..3070277a307b 100644 --- a/drivers/scsi/scsi_lib.c +++ b/drivers/scsi/scsi_lib.c @@ -184,6 +184,10 @@ void scsi_queue_insert(struct scsi_cmnd *cmd, int reason) __scsi_queue_insert(cmd, reason, true); } +/** + * scsi_failures_reset_retries - reset all failures to zero + * @failures: &struct scsi_failures with specific failure modes set + */ void scsi_failures_reset_retries(struct scsi_failures *failures) { struct scsi_failure *failure; @@ -1232,6 +1236,15 @@ static void scsi_initialize_rq(struct request *rq) cmd->retries = 0; } +/** + * scsi_alloc_request - allocate a block request and partially + * initialize its &scsi_cmnd + * @q: the device's request queue + * @opf: the request operation code + * @flags: block layer allocation flags + * + * Return: &struct request pointer on success or %NULL on failure + */ struct request *scsi_alloc_request(struct request_queue *q, blk_opf_t opf, blk_mq_req_flags_t flags) { @@ -3410,14 +3423,16 @@ int scsi_vpd_lun_id(struct scsi_device *sdev, char *id, size_t id_len) } EXPORT_SYMBOL(scsi_vpd_lun_id); -/* +/** * scsi_vpd_tpg_id - return a target port group identifier * @sdev: SCSI device + * @rel_id: pointer to return relative target port in if not %NULL * * Returns the Target Port Group identifier from the information - * froom VPD page 0x83 of the device. + * from VPD page 0x83 of the device. + * Optionally sets @rel_id to the relative target port on success. * - * Returns the identifier or error on failure. + * Return: the identifier or error on failure. */ int scsi_vpd_tpg_id(struct scsi_device *sdev, int *rel_id) {