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

1 files changed, 36 insertions, 0 deletions

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,