git: 2d3426eb9e31 - stable/13 - cam: Add doxygen docs to cam_sim_alloc

The branch stable/13 has been updated by imp:

URL: https://cgit.FreeBSD.org/src/commit/?id=2d3426eb9e31fd9e07e1542663426fccf82627e5

commit 2d3426eb9e31fd9e07e1542663426fccf82627e5
Author:     Warner Losh <imp@FreeBSD.org>
AuthorDate: 2024-12-28 17:59:59 +0000
Commit:     Warner Losh <imp@FreeBSD.org>
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,