Index: sys/cam/cam_sim.c
===================================================================
--- sys/cam/cam_sim.c
+++ sys/cam/cam_sim.c
@@ -64,6 +64,41 @@
 	cam_devq_free(devq);
 }
 
+/**
+ * @brief allocate a new sim and fill in the details
+ *
+ * Allocates memory and fills in different fields and initializes the
+ * callout. The sim acts as the glue between the CAM system and other parts of
+ * the system. An @c sim_action routine gets messages from CAM's xpt system. The
+ * sim is responsible for interpreting these messages in the form of CCBs and
+ * translating them into DMA or other transactions for the HBA or other
+ * hardware.
+ *
+ * The @c mtx acts as a perimeter lock for the sim. All calls into the sim's @c
+ * 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 sims that handle their
+ *			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,