From nobody Sat Dec 28 18:01:15 2024 X-Original-To: dev-commits-src-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4YL9Cb6hNQz5hyKJ; Sat, 28 Dec 2024 18:01:15 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R11" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4YL9Cb6C3xz4sXP; Sat, 28 Dec 2024 18:01:15 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1735408875; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=yOVpFOA5gTdlW0TvzRm+lizWzS0pOUVSfdS8i5ThlSQ=; b=u2t8M34o28uMUl0kmdoYp9LV1un8eryMik/U+vl4is8coFO3swm3/6pzSgBqfM4nvVW2EN 6eRESTlqUx6ZJ+eGmEvKGPTzAuxrNJWES5/P3n/35xDwGY9DF9GyMF/KS0FDCDHkz9fFEh mNZxrNJIRDKIL/UM9MXap9Y4ppwieQgDC5e2QdpGzNVUZrrwfs98WqYEQirRaZKlQPFqq7 hIKngqZRXZslAwazSySzikA9LNUzpAkutiM68WafhOCx9X0lHTyvCtLbDImngDU+ZYZxp2 zIQgss16E/o96+M8wL0bwlrS7/YNFtgbvW/R5jaqeaNB4xwP0/po3ZRxBjE2Tw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1735408875; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=yOVpFOA5gTdlW0TvzRm+lizWzS0pOUVSfdS8i5ThlSQ=; b=iD1GyBGoIVZSIj4mHEIzV6acdAyUJ/gjjSfvceOh0z8Z+UPaDg/M06pYxVFziB7J+xpmJT OzXSK8PvHRoETURhhGtwkB7xcDQN8fN6R2vo2yh5P7mOfCQrW58BxIqNypiI2JcsknE4/6 r+FA6ECHUyALVEys6tZn0Hi/zD5jCRkreH07p5HOoptMJcFTI9ssNesklUbBzkEPYJmqSy 6bhyEwMCDEWW+LPfP+/r0CribqAbiTUxp74nEWvOq4WioR28T+aqC02pLaOoHsYKfbCHEa le5sBhSrjiN2KrlEVAdAjpvFIOGPHwgJQz1Fc/Kpjh4i4FLPQXWgiI+EwR4Slw== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1735408875; a=rsa-sha256; cv=none; b=W7C4BCnvS7xdMKKFGuIVQZGcjLTGyak1QETnZgH97BpQkWEV0Boj9+J9Ae4DvCu0KvgKFu O1/y0OTjBrZp/7lARj5C4cOr6+uS3N4OdSRIsglC96NGIvb4XMo2z1h1b5lSq5E3jX0UVI NRYnxZkAEvUfY0fjvv5U3kYJyOds/CqURK37hQLSU2uQYXYgM/E2CQXDFZlzCu1mv7hUqf toCORaJPVReh6rDnIWX00g6fZr5v6u9un8Dyhpc1xet9FKT0shM9OcaBiuaKAMmzh7AAnV 65bb6gdyxrS9mHN0xWxV9m+aw3zud9jo/Hz69o6OStdnI8Wa/ft9pkkRqxaVyg== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4YL9Cb5WlJzZcT; Sat, 28 Dec 2024 18:01:15 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.18.1/8.18.1) with ESMTP id 4BSI1F0h038305; Sat, 28 Dec 2024 18:01:15 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.18.1/8.18.1/Submit) id 4BSI1F2E038302; Sat, 28 Dec 2024 18:01:15 GMT (envelope-from git) Date: Sat, 28 Dec 2024 18:01:15 GMT Message-Id: <202412281801.4BSI1F2E038302@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-branches@FreeBSD.org From: Warner Losh Subject: git: 2d3426eb9e31 - stable/13 - cam: Add doxygen docs to cam_sim_alloc List-Id: Commit messages for all branches of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-src-all@freebsd.org Sender: owner-dev-commits-src-all@FreeBSD.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: imp X-Git-Repository: src X-Git-Refname: refs/heads/stable/13 X-Git-Reftype: branch X-Git-Commit: 2d3426eb9e31fd9e07e1542663426fccf82627e5 Auto-Submitted: auto-generated The branch stable/13 has been updated by imp: URL: https://cgit.FreeBSD.org/src/commit/?id=2d3426eb9e31fd9e07e1542663426fccf82627e5 commit 2d3426eb9e31fd9e07e1542663426fccf82627e5 Author: Warner Losh AuthorDate: 2024-12-28 17:59:59 +0000 Commit: Warner Losh CommitDate: 2024-12-28 18:00:50 +0000 cam: Add doxygen docs to cam_sim_alloc Add description for what each of the parameters are to the cam_sim_alloc call. Add some additional context for the mtx and queue parameters to explain what special values passed in mean. MFC After: 3 days Reviewed by: mav@ Sponsored by: Netflix Differential Revision: https://reviews.freebsd.org/D30115 (cherry picked from commit cb5880594387d5b07c5d580c4aa1b633947a6046) --- sys/cam/cam_sim.c | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/sys/cam/cam_sim.c b/sys/cam/cam_sim.c index 5d03c69d0c7a..e03ed0fee1fb 100644 --- a/sys/cam/cam_sim.c +++ b/sys/cam/cam_sim.c @@ -62,6 +62,42 @@ cam_simq_free(struct cam_devq *devq) cam_devq_free(devq); } + + +/** + * @brief allocate a new sim and fill in the details + * + * A Storage Interface Module (SIM) is the interface between CAM and + * hardware. SIM receives CCBs from CAM via @p sim_action callback and + * translates them into DMA or other hardware transactions. During system + * dumps, it can be polled with the @p sim_poll callback. CCB processing is + * terminated by calling @c xpt_done(). + * + * The @p mtx acts as a perimeter lock for the SIM. All calls into the SIM's + * @p sim_action are made with this lock held. It is also used to hold/release + * a SIM, managing its reference count. When the lock is NULL, the SIM is 100% + * responsible for locking (and the reference counting is done with a shared + * lock. + * + * The cam_devq passed in (@c queue) is used to arbitrate the number of + * outstanding transactions to the SIM. For HBAs that have global limits shared + * between the different buses, the same devq should be specified for each bus + * attached to the SIM. + * + * @param sim_action Function to call to process CCBs + * @param sim_poll Function to poll the hardware for completions + * @param sim_name Name of SIM class + * @param softc Software context associated with the SIM + * @param unit Unit number of SIM + * @param mtx Mutex to lock while interacting with the SIM, or NULL + * for a SIM that handle its own locking to enable multi + * queue support. + * @param max_dev_transactions Maximum number of concurrent untagged + * transactions possible + * @param max_tagged_dev_transactions Maximum number of concurrent tagged + * transactions possible. + * @param queue The cam_devq to use for this SIM. + */ struct cam_sim * cam_sim_alloc(sim_action_func sim_action, sim_poll_func sim_poll, const char *sim_name, void *softc, u_int32_t unit,