From owner-dev-commits-src-main@freebsd.org Wed May 5 17:47:01 2021 Return-Path: Delivered-To: dev-commits-src-main@mailman.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.nyi.freebsd.org (Postfix) with ESMTP id 00CBE5FDFCF; Wed, 5 May 2021 17:47:01 +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 "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4Fb40N6glyz4ZXS; Wed, 5 May 2021 17:47:00 +0000 (UTC) (envelope-from git@FreeBSD.org) 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 CD75812AC; Wed, 5 May 2021 17:47:00 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.16.1/8.16.1) with ESMTP id 145Hl0lW076888; Wed, 5 May 2021 17:47:00 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 145Hl0YV076887; Wed, 5 May 2021 17:47:00 GMT (envelope-from git) Date: Wed, 5 May 2021 17:47:00 GMT Message-Id: <202105051747.145Hl0YV076887@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Warner Losh Subject: git: cb5880594387 - main - cam: Add doxygen docs to cam_sim_alloc 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/main X-Git-Reftype: branch X-Git-Commit: cb5880594387d5b07c5d580c4aa1b633947a6046 Auto-Submitted: auto-generated X-BeenThere: dev-commits-src-main@freebsd.org X-Mailman-Version: 2.1.34 Precedence: list List-Id: Commit messages for the main branch of the src repository List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 05 May 2021 17:47:01 -0000 The branch main has been updated by imp: URL: https://cgit.FreeBSD.org/src/commit/?id=cb5880594387d5b07c5d580c4aa1b633947a6046 commit cb5880594387d5b07c5d580c4aa1b633947a6046 Author: Warner Losh AuthorDate: 2021-05-05 17:44:19 +0000 Commit: Warner Losh CommitDate: 2021-05-05 17:44:39 +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 --- 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 e82332b999c3..5b6d43b81d5d 100644 --- a/sys/cam/cam_sim.c +++ b/sys/cam/cam_sim.c @@ -64,6 +64,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,