From patchwork Thu Dec 12 20:52:13 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Randy Dunlap X-Patchwork-Id: 13905975 Received: from bombadil.infradead.org (bombadil.infradead.org [198.137.202.133]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 20447174EF0 for ; Thu, 12 Dec 2024 20:52:21 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=198.137.202.133 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1734036744; cv=none; b=ajaELDQh+c9FUkdU+3KY+VyNC76uUVysyM0igH9p+NteS9XI7RmuQ319u4UCLzj8aq1cpiHBaU3S6IsJQw3l3oVsWrdB5dDZZP0AaUiROu4b+V3GdYFT2Bv80UWIa41dnA9vw0Gomuu9yBaR0/Fnzo3X5b2EtXH6wgZN2tBEUVI= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1734036744; c=relaxed/simple; bh=4ngiEe0x9XtiiIzntJzGDjQPZ86NDRlTiw/SBm/jL6k=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=eWnFjQgaYYI/ABkvM9UqMNjswZ6FOaVFwIOGuQpCqIQaU5MFIip+b7dMyXaTqP2gIIYl/b7jmMM9y2xMWHPIzlL2PK0O3+I4nmo8IKa8XgGIa8pMe6JNYGgp+N/8ojaCuT92bFkLaFm5999wQkRtvpFd4OpmrEHUvBh5qY/NPrA= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=infradead.org; spf=none smtp.mailfrom=infradead.org; dkim=pass (2048-bit key) header.d=infradead.org header.i=@infradead.org header.b=OGw5AVnN; arc=none smtp.client-ip=198.137.202.133 Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=infradead.org Authentication-Results: smtp.subspace.kernel.org; spf=none smtp.mailfrom=infradead.org Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=infradead.org header.i=@infradead.org header.b="OGw5AVnN" DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20210309; h=Content-Transfer-Encoding: MIME-Version:References:In-Reply-To:Message-ID:Date:Subject:Cc:To:From:Sender :Reply-To:Content-Type:Content-ID:Content-Description; bh=2JSVrMTLtEdvHY3lENAB58Do4Sads+kpExTjyXAj4QQ=; b=OGw5AVnNTt0RaxH2/c2L6TOxN1 m17n8DRXDBv0kvbvUOQzpsbxqgjqasia/posXJ4SNrXYzPaQd11hJP4UFi5wch77y+BHvK10X/GC+ bFSFuB0tLjRppNnDfVc5x20R+R2rgWgeNT/wGg5MpLo5iZh2F1p3qG2ZkBZ/yJX3IyrLY0OfgzNy6 E6eAd3rXRG6oOtUsNUZyC9CH8c9yYcoXOVn2nVbJCWMFbYFpQDgP4Bq1XdaijwkSV4fw/KZuhHJNV TD5A6kcJjYRGEwnoauZaVnPPzIl6D/9GwKQbdPa9eJ5f/p5vDBLtWMlOqF5JNRDBe3WWjjJg18095 xTgFOq9A==; Received: from [50.53.2.24] (helo=bombadil.infradead.org) by bombadil.infradead.org with esmtpsa (Exim 4.98 #2 (Red Hat Linux)) id 1tLqAX-00000001rO5-2VvX; Thu, 12 Dec 2024 20:52:21 +0000 From: Randy Dunlap To: linux-scsi@vger.kernel.org Cc: Randy Dunlap , "James E.J. Bottomley" , "Martin K. Petersen" Subject: [PATCH 1/5] scsi: scsi_error: add kernel-doc for exported functions Date: Thu, 12 Dec 2024 12:52:13 -0800 Message-ID: <20241212205217.597844-2-rdunlap@infradead.org> X-Mailer: git-send-email 2.47.1 In-Reply-To: <20241212205217.597844-1-rdunlap@infradead.org> References: <20241212205217.597844-1-rdunlap@infradead.org> Precedence: bulk X-Mailing-List: linux-scsi@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Convert scsi_report_bus_reset() and scsi_report_device_reset() to kernel-doc since they are exported. This allows them to be part of the driver-api/scsi.rst docbook. Signed-off-by: Randy Dunlap CC: "James E.J. Bottomley" CC: "Martin K. Petersen" --- drivers/scsi/scsi_error.c | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) --- linux-next-20241212.orig/drivers/scsi/scsi_error.c +++ linux-next-20241212/drivers/scsi/scsi_error.c @@ -2363,14 +2363,14 @@ int scsi_error_handler(void *data) return 0; } -/* - * Function: scsi_report_bus_reset() +/** + * scsi_report_bus_reset() - report bus reset observed * - * Purpose: Utility function used by low-level drivers to report that - * they have observed a bus reset on the bus being handled. + * Utility function used by low-level drivers to report that + * they have observed a bus reset on the bus being handled. * - * Arguments: shost - Host in question - * channel - channel on which reset was observed. + * @shost: Host in question + * @channel: channel on which reset was observed. * * Returns: Nothing * @@ -2395,15 +2395,15 @@ void scsi_report_bus_reset(struct Scsi_H } EXPORT_SYMBOL(scsi_report_bus_reset); -/* - * Function: scsi_report_device_reset() +/** + * scsi_report_device_reset() - report device reset observed * - * Purpose: Utility function used by low-level drivers to report that - * they have observed a device reset on the device being handled. + * Utility function used by low-level drivers to report that + * they have observed a device reset on the device being handled. * - * Arguments: shost - Host in question - * channel - channel on which reset was observed - * target - target on which reset was observed + * @shost: Host in question + * @channel: channel on which reset was observed + * @target: target on which reset was observed * * Returns: Nothing * From patchwork Thu Dec 12 20:52:14 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Randy Dunlap X-Patchwork-Id: 13905977 Received: from bombadil.infradead.org (bombadil.infradead.org [198.137.202.133]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 8B0911A4F22 for ; Thu, 12 Dec 2024 20:52:22 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=198.137.202.133 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1734036745; cv=none; b=BUVWCbME9PXDv9FEQO1ahNE4qBDj0syIYUKfSC/a191BJzrx2BaJkvtcdFF2dARKlGP58ozvi8adKflfe/GOVzbMJSvbsusgmnWk83nSvdEx4wkG8H6bZ0xiGec7c5vcPuOksEwSUH5OsdZDUPxrnGyuFRDDkvGuYTjm6/u/dac= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1734036745; c=relaxed/simple; bh=++GVuqGnOdqduHfgyfRPg2vHaMJGQK29XZRdvyQ4xdM=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=AcMKTzJsoejiQHJ5IMklTyJAP+ie9CjpYiWsykYJiaJpAQFbaTjlpm8uCSHbr+BVVTEdKcWUcswCyOyjukevyCP4pKK9G3cLLYw9y9EHNDv7L+nlTbIgY5n+VmRo1NRPlcu+rBnbKBnAHH2AzVKvIzYx4rt+X2LFFjWnb99yyfU= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=infradead.org; spf=none smtp.mailfrom=infradead.org; dkim=pass (2048-bit key) header.d=infradead.org header.i=@infradead.org header.b=R4ErBP3w; arc=none smtp.client-ip=198.137.202.133 Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=infradead.org Authentication-Results: smtp.subspace.kernel.org; spf=none smtp.mailfrom=infradead.org Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=infradead.org header.i=@infradead.org header.b="R4ErBP3w" DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20210309; h=Content-Transfer-Encoding: MIME-Version:References:In-Reply-To:Message-ID:Date:Subject:Cc:To:From:Sender :Reply-To:Content-Type:Content-ID:Content-Description; bh=PXEkCulTFjRJ7qcn0gnZBXZ52hajeLcq5bPwWoTRmsw=; b=R4ErBP3wUKR7i2rSZf2jzdjP1v j6yc/0OCXLgsLVJjvdE4i1QKTkfSISb2p7rUWCh32uD89zFwAFw7PNfmkZCXWINXhfGjdzjg03IEN DeiRDpvqa0KiyoPB8FU6V18m8mEvjIzs989TtiO9uNmXRkJA3egIeDC3jQnotgyPwOG8tA1dJkK7p 6RqAfwfpfQGtgkN8FisXB0c2fXD4xzlPeU/BoKC/ZoCVmu3/Q1OMArcKJpAu6QPn/5pYvkg0XnfvS k9lWJqLqhIst8BkXJ7CizTlpdhQe0zYZa4VCMb5v5KRsfQfnGoPQxdUgjglAhvTkzVWlHRtmLbpw2 mhK2ZTzQ==; Received: from [50.53.2.24] (helo=bombadil.infradead.org) by bombadil.infradead.org with esmtpsa (Exim 4.98 #2 (Red Hat Linux)) id 1tLqAX-00000001rO5-3S4w; Thu, 12 Dec 2024 20:52:21 +0000 From: Randy Dunlap To: linux-scsi@vger.kernel.org Cc: Randy Dunlap , "James E.J. Bottomley" , "Martin K. Petersen" Subject: [PATCH 2/5] scsi: scsi_ioctl: add kernel-doc for exported functions Date: Thu, 12 Dec 2024 12:52:14 -0800 Message-ID: <20241212205217.597844-3-rdunlap@infradead.org> X-Mailer: git-send-email 2.47.1 In-Reply-To: <20241212205217.597844-1-rdunlap@infradead.org> References: <20241212205217.597844-1-rdunlap@infradead.org> Precedence: bulk X-Mailing-List: linux-scsi@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Add kernel-doc for scsi_set_medium_removal(), scsi_cmd_allowed(), and scsi_ioctl_block_when_processing_errors() since these are exported. This allows them to be part of the SCSI driver-api docbook. Signed-off-by: Randy Dunlap CC: "James E.J. Bottomley" CC: "Martin K. Petersen" --- drivers/scsi/scsi_ioctl.c | 35 ++++++++++++++++++++++++++++++----- 1 file changed, 30 insertions(+), 5 deletions(-) --- linux-next-20241212.orig/drivers/scsi/scsi_ioctl.c +++ linux-next-20241212/drivers/scsi/scsi_ioctl.c @@ -37,8 +37,10 @@ * @host: host to identify * @buffer: userspace buffer for identification * - * Return an identifying string at @buffer, if @buffer is non-NULL, filling - * to the length stored at * (int *) @buffer. + * Return: + * * if successful, %1 and an identifying string at @buffer, if @buffer + * is non-NULL, filling to the length stored at * (int *) @buffer. + * * <0 error code on failure. */ static int ioctl_probe(struct Scsi_Host *host, void __user *buffer) { @@ -121,6 +123,16 @@ out: return result; } +/** + * scsi_set_medium_removal() - send command to allow or prevent medium removal + * @sdev: target scsi device + * @state: removal state to set (prevent or allow) + * + * Returns: + * * %0 if @sdev is not removable or not lockable or successful. + * * non-%0 is a SCSI result code if > 0 or kernel error code if < 0. + * * Sets @sdev->locked to the new state on success. + */ int scsi_set_medium_removal(struct scsi_device *sdev, char state) { char scsi_cmd[MAX_COMMAND_SIZE]; @@ -242,11 +254,15 @@ static int scsi_send_start_stop(struct s NORMAL_RETRIES); } -/* - * Check if the given command is allowed. +/** + * scsi_cmd_allowed() - Check if the given command is allowed. + * @cmd: SCSI command to check + * @open_for_write: is the file / block device opened for writing? * * Only a subset of commands are allowed for unprivileged users. Commands used * to format the media, update the firmware, etc. are not permitted. + * + * Return: %true if the cmd is allowed, otherwise @false. */ bool scsi_cmd_allowed(unsigned char *cmd, bool open_for_write) { @@ -859,6 +875,8 @@ static int scsi_ioctl_sg_io(struct scsi_ * Description: The scsi_ioctl() function differs from most ioctls in that it * does not take a major/minor number as the dev field. Rather, it takes * a pointer to a &struct scsi_device. + * + * Return: varies depending on the @cmd */ int scsi_ioctl(struct scsi_device *sdev, bool open_for_write, int cmd, void __user *arg) @@ -941,8 +959,15 @@ int scsi_ioctl(struct scsi_device *sdev, } EXPORT_SYMBOL(scsi_ioctl); -/* +/** + * scsi_ioctl_block_when_processing_errors - prevent commands from being queued + * @sdev: target scsi device + * @cmd: which ioctl is it + * @ndelay: no delay (non-blocking) + * * We can process a reset even when a device isn't fully operable. + * + * Return: %0 on success, <0 error code. */ int scsi_ioctl_block_when_processing_errors(struct scsi_device *sdev, int cmd, bool ndelay) From patchwork Thu Dec 12 20:52:15 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Randy Dunlap X-Patchwork-Id: 13905976 Received: from bombadil.infradead.org (bombadil.infradead.org [198.137.202.133]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 738511917D6 for ; Thu, 12 Dec 2024 20:52:22 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=198.137.202.133 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1734036745; cv=none; b=RTFgkzOMfo/ogGKIx3ScsgmRpuqxTxGctvOosgnGiroDfE8Kk4V23mJoRWgcZK5z6sQa3Bbwqv/eawxrWlJXJLdP+/kHVKQEg1lOeYJUvoSIIqrH1ZMeNu1flaoLTDnvZu5h+BxlyQjGej3sEd+CiRCCfukRPELRxgFdzNJI5Qg= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1734036745; c=relaxed/simple; bh=rbW1MWjtSR5nGGTwTbZhYFX/todq16UnxeMXHgwMn7A=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=iKA9RM6nVQK/ktXg/1v69JrFrbHMSzjin0yawTlIUacrxOS2zkLQ+buVgayKcpCqjSBv/rhAgx/jFeXn3lJFboD5SaHv7JjMwtEqiNMhkcfISSkIwgqSxY5Mc+KeEOY0K5BPhIe7GeFKxzBs58OGCMUb+UTXngBcalEbOarFR9s= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=infradead.org; spf=none smtp.mailfrom=infradead.org; dkim=pass (2048-bit key) header.d=infradead.org header.i=@infradead.org header.b=d4Jtg193; arc=none smtp.client-ip=198.137.202.133 Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=infradead.org Authentication-Results: smtp.subspace.kernel.org; spf=none smtp.mailfrom=infradead.org Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=infradead.org header.i=@infradead.org header.b="d4Jtg193" DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20210309; h=Content-Transfer-Encoding: MIME-Version:References:In-Reply-To:Message-ID:Date:Subject:Cc:To:From:Sender :Reply-To:Content-Type:Content-ID:Content-Description; bh=6EG/TMrAs+0NuIAxtUlxCtd0MXNMBUvcVZY0rG9bFgw=; b=d4Jtg193SrHVZ1Sm5kL/tZTmdP o4nh/8qPwBP+K01OtQiSWQFSlKGlk8xxRQYmZ57OWnoq8WzQq48wIqXvaDAh1Ke6Xv65qBz/EStxk 9I1Zw958Bay9A3QLrlQoeTZFL6Oc4B2DiVYySA5fw3hS9rMpn7J39MNZA4csePsP1WN3ZqTiVX53+ vaeCkXw32DQXiuZ4e3bJlSo9kjy+RVg3/k8WKNJevKgAIBJP7ULuUnloSa3z0Bv+utasCVbd1Ry/j ic0jwhamlkrDdudnFniOGcVPgskYn6CsR0mftUgPZCtFMsSUbKxorKhc2Ntzmfwj46oxVo3BN07eZ t+HNKDvQ==; Received: from [50.53.2.24] (helo=bombadil.infradead.org) by bombadil.infradead.org with esmtpsa (Exim 4.98 #2 (Red Hat Linux)) id 1tLqAY-00000001rO5-0CJr; Thu, 12 Dec 2024 20:52:22 +0000 From: Randy Dunlap To: linux-scsi@vger.kernel.org Cc: Randy Dunlap , "James E.J. Bottomley" , "Martin K. Petersen" Subject: [PATCH 3/5] scsi: scsi_lib: add kernel-doc for exported functions Date: Thu, 12 Dec 2024 12:52:15 -0800 Message-ID: <20241212205217.597844-4-rdunlap@infradead.org> X-Mailer: git-send-email 2.47.1 In-Reply-To: <20241212205217.597844-1-rdunlap@infradead.org> References: <20241212205217.597844-1-rdunlap@infradead.org> Precedence: bulk X-Mailing-List: linux-scsi@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 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 CC: "James E.J. Bottomley" CC: "Martin K. Petersen" --- drivers/scsi/scsi_lib.c | 21 ++++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) --- linux-next-20241212.orig/drivers/scsi/scsi_lib.c +++ linux-next-20241212/drivers/scsi/scsi_lib.c @@ -184,6 +184,10 @@ void scsi_queue_insert(struct scsi_cmnd __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; @@ -1214,6 +1218,15 @@ static void scsi_initialize_rq(struct re 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) { @@ -3365,14 +3378,16 @@ int scsi_vpd_lun_id(struct scsi_device * } 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) { From patchwork Thu Dec 12 20:52:16 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Randy Dunlap X-Patchwork-Id: 13905973 Received: from bombadil.infradead.org (bombadil.infradead.org [198.137.202.133]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id BB8471A83E3 for ; Thu, 12 Dec 2024 20:52:22 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=198.137.202.133 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1734036744; cv=none; b=BuaKK7WqTHMjb3hrXA0aha5ypaPUJFCKkJOU8XbjjfCIZpy46EQDRD3yYBb4nqKDv0/i9FUEyfTilo79iDjOgUPjZPPExzCdT8Is1vkDi6kYTJOpvFbYsK5W2tiWc389EDy+OJFA+ZGG60l9IS2sUH2yVbiaZRVttCJKBWZsENw= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1734036744; c=relaxed/simple; bh=nQv12PEvV2tmUwfrTW4su8DaOdr/1dsZayRhHagha94=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=Eqzi/9Ra6Ual1NYA3VtA2f8yXkRtmFxG7DJ9I0dZQE/7rbVQz8fs2VdhmPw4/1rY86++un/2U0uGzDPQr+i/c0tX76FuhjfKYIEQpjQC5kRsZmXdg8UI1zXnI/UG5AEoMqbDXZnGRdAfOmHEsneDIiWN5scLljUEmnW8jugRriI= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=infradead.org; spf=none smtp.mailfrom=infradead.org; dkim=pass (2048-bit key) header.d=infradead.org header.i=@infradead.org header.b=Bby4iQlR; arc=none smtp.client-ip=198.137.202.133 Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=infradead.org Authentication-Results: smtp.subspace.kernel.org; spf=none smtp.mailfrom=infradead.org Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=infradead.org header.i=@infradead.org header.b="Bby4iQlR" DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20210309; h=Content-Transfer-Encoding: MIME-Version:References:In-Reply-To:Message-ID:Date:Subject:Cc:To:From:Sender :Reply-To:Content-Type:Content-ID:Content-Description; bh=c6eUrfWUzoERxKCckTbpTcUBfrCSpBr7XbzXbOOJD4A=; b=Bby4iQlRtCdcbxXk/wbo3ItZ4J LO7t6ni/xEBNeSnebU+CqX0s+iVamPlwRlMkROZmgX6b2WJAhMxTlB/rmzDkgXAECDXb11XcyCYhX jGCmkOzaSAFY/xDBknaPHznaTOLbU9NhqTzrM9AFN2H+h0Ph0/2Gk7bFJvQYsNayWLsovZ82WCWzl 4IGzSflMRYqNZ7G+UsKbRFS/FUOzQMHdQ3xeNHpNKdIbsYoXucjkA0KhCvyJofM0/NbNZJtTEk8h1 T3pLeU5gsW7kezRDpBufk47ZbRxqd6eVWZH+wnSHCq/cinGcqJQkJJRb+8wnIAkY2mPtt1vo0gT5P pxa34ylA==; Received: from [50.53.2.24] (helo=bombadil.infradead.org) by bombadil.infradead.org with esmtpsa (Exim 4.98 #2 (Red Hat Linux)) id 1tLqAY-00000001rO5-19UI; Thu, 12 Dec 2024 20:52:22 +0000 From: Randy Dunlap To: linux-scsi@vger.kernel.org Cc: Randy Dunlap , "James E.J. Bottomley" , "Martin K. Petersen" Subject: [PATCH 4/5] scsi: scsi_scan: add kernel-doc for exported function Date: Thu, 12 Dec 2024 12:52:16 -0800 Message-ID: <20241212205217.597844-5-rdunlap@infradead.org> X-Mailer: git-send-email 2.47.1 In-Reply-To: <20241212205217.597844-1-rdunlap@infradead.org> References: <20241212205217.597844-1-rdunlap@infradead.org> Precedence: bulk X-Mailing-List: linux-scsi@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Add kernel-doc for scsi_add_device() since it is exported. This allows it to be part of the SCSI driver-api docbook. Signed-off-by: Randy Dunlap CC: "James E.J. Bottomley" CC: "Martin K. Petersen" --- drivers/scsi/scsi_scan.c | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) --- linux-next-20241212.orig/drivers/scsi/scsi_scan.c +++ linux-next-20241212/drivers/scsi/scsi_scan.c @@ -1634,6 +1634,24 @@ struct scsi_device *__scsi_add_device(st } EXPORT_SYMBOL(__scsi_add_device); +/** + * scsi_add_device - creates a new SCSI (LU) instance + * @host: the &Scsi_Host instance where the device is located + * @channel: target channel number (rarely other than %0) + * @target: target id number + * @lun: LUN of target device + * + * Probe for a specific LUN and add it if found. + * + * Notes: This call is usually performed internally during a scsi + * bus scan when an HBA is added (i.e. scsi_scan_host()). So it + * should only be called if the HBA becomes aware of a new scsi + * device (lu) after scsi_scan_host() has completed. If successful + * this call can lead to sdev_init() and sdev_configure() callbacks + * into the LLD. + * + * Return: %0 on success or negative error code on failure + */ int scsi_add_device(struct Scsi_Host *host, uint channel, uint target, u64 lun) { @@ -2025,6 +2043,8 @@ static void do_scan_async(void *_data, a /** * scsi_scan_host - scan the given adapter * @shost: adapter to scan + * + * Notes: Should be called after scsi_add_host() **/ void scsi_scan_host(struct Scsi_Host *shost) { From patchwork Thu Dec 12 20:52:17 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Randy Dunlap X-Patchwork-Id: 13905972 Received: from bombadil.infradead.org (bombadil.infradead.org [198.137.202.133]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id E498C1ABECF for ; Thu, 12 Dec 2024 20:52:22 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=198.137.202.133 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1734036744; cv=none; b=E9to+vImDhTbQYyKnjJGGM3GiWRXvMxXc25Hd8nxQ4kAy1UkQO02F1HeAT59I/it86fuMC84eL9W7kbMs9vUeB6reku4iGj4v7x2UD4mZ7wmrhp1HFg6N8UTOFa7ml/qGRWQpFLekvahBkIdfSYC36Y/EWn8dHCYZH3Pn4dom9k= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1734036744; c=relaxed/simple; bh=/ndaERqmRgwGQ9r6zP/NB3YKf/JSGMmm+65eWWD2sIc=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=bjZzrtjND87fLPkLhwCYxnNH2ifZFTqn/Hmz1wye6+Cp/IO15TIUq+uyRdFSik0HhwuI0SrrRzNCNrJrWZMlJnlMrHKtafQKRTYQ4zwfHxwlQ/CLipdP5Uygd/D6JI3msTPmy+S769RVQazW3H1U/ejCxCL2tedMprnI30R4ntw= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=infradead.org; spf=none smtp.mailfrom=infradead.org; dkim=pass (2048-bit key) header.d=infradead.org header.i=@infradead.org header.b=To9FaaDM; arc=none smtp.client-ip=198.137.202.133 Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=infradead.org Authentication-Results: smtp.subspace.kernel.org; spf=none smtp.mailfrom=infradead.org Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=infradead.org header.i=@infradead.org header.b="To9FaaDM" DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20210309; h=Content-Transfer-Encoding: MIME-Version:References:In-Reply-To:Message-ID:Date:Subject:Cc:To:From:Sender :Reply-To:Content-Type:Content-ID:Content-Description; bh=vx5PlpxbwZpb2opqxy2k3FqmU4u+duEDP1k6keYODu4=; b=To9FaaDMGqYlda+8V5ciAUaqnY +OSNaO+g8kY49/q1urg2Z7wYWFzgY8fgtWYIFlWabfh0rU6UevW4DMZ139+GRlmoAC/eLNFVgIzpe bcuPWw5siWscQMmTKCEaxXfO1y0RT3h0aDB6ACoWFEey5KWw2wugsTV47hheQ8/L50dvB4/a08ZW4 m/4tdjgl2AyHkJcHiqQGh4k8x2UfUBRy4l9OFzM9+SnqJTHJ9a6oLuFxdjE9iNWhrzhHw5efNGpO2 Uq9VIpt70Ozpe/4Sj9gyr6vkJMnoRkAzMmvNwF2i6yqAWUt5IKCANj14F3XGnowHk57wzVZXiEEjm Bn9osUSg==; Received: from [50.53.2.24] (helo=bombadil.infradead.org) by bombadil.infradead.org with esmtpsa (Exim 4.98 #2 (Red Hat Linux)) id 1tLqAY-00000001rO5-27Bf; Thu, 12 Dec 2024 20:52:22 +0000 From: Randy Dunlap To: linux-scsi@vger.kernel.org Cc: Randy Dunlap , "James E.J. Bottomley" , "Martin K. Petersen" Subject: [PATCH 5/5] scsi: transports: fix kernel-doc for exported functions Date: Thu, 12 Dec 2024 12:52:17 -0800 Message-ID: <20241212205217.597844-6-rdunlap@infradead.org> X-Mailer: git-send-email 2.47.1 In-Reply-To: <20241212205217.597844-1-rdunlap@infradead.org> References: <20241212205217.597844-1-rdunlap@infradead.org> Precedence: bulk X-Mailing-List: linux-scsi@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Fix kernel-doc for sas_port_alloc(), sas_port_alloc_num(), and spi_dv_device(). This allows them to be part of the SCSI driver-api docbook. Signed-off-by: Randy Dunlap CC: "James E.J. Bottomley" CC: "Martin K. Petersen" --- drivers/scsi/scsi_transport_sas.c | 10 ++++++---- drivers/scsi/scsi_transport_spi.c | 3 ++- 2 files changed, 8 insertions(+), 5 deletions(-) --- linux-next-20241212.orig/drivers/scsi/scsi_transport_sas.c +++ linux-next-20241212/drivers/scsi/scsi_transport_sas.c @@ -888,7 +888,8 @@ static void sas_port_delete_link(struct sysfs_remove_link(&phy->dev.kobj, "port"); } -/** sas_port_alloc - allocate and initialize a SAS port structure +/** + * sas_port_alloc - allocate and initialize a SAS port structure * * @parent: parent device * @port_id: port number @@ -897,7 +898,7 @@ static void sas_port_delete_link(struct * below the device specified by @parent which must be either a Scsi_Host * or a sas_expander_device. * - * Returns %NULL on error + * Returns: %NULL on error */ struct sas_port *sas_port_alloc(struct device *parent, int port_id) { @@ -932,7 +933,8 @@ struct sas_port *sas_port_alloc(struct d } EXPORT_SYMBOL(sas_port_alloc); -/** sas_port_alloc_num - allocate and initialize a SAS port structure +/** + * sas_port_alloc_num - allocate and initialize a SAS port structure * * @parent: parent device * @@ -942,7 +944,7 @@ EXPORT_SYMBOL(sas_port_alloc); * the device tree below the device specified by @parent which must be * either a Scsi_Host or a sas_expander_device. * - * Returns %NULL on error + * Returns: %NULL on error */ struct sas_port *sas_port_alloc_num(struct device *parent) { --- linux-next-20241212.orig/drivers/scsi/scsi_transport_spi.c +++ linux-next-20241212/drivers/scsi/scsi_transport_spi.c @@ -985,7 +985,8 @@ spi_dv_device_internal(struct scsi_devic } -/** spi_dv_device - Do Domain Validation on the device +/** + * spi_dv_device - Do Domain Validation on the device * @sdev: scsi device to validate * * Performs the domain validation on the given device in the