Changeset 17ceb72 in mainline for uspace/drv/uhci-hcd/transfer_list.c

Timestamp:

2011-03-14T01:39:44Z (14 years ago)

Author:

Jan Vesely <jano.vesely@…>

Branches:

lfn, master, serial, ticket/834-toolchain-update, topic/msim-upgrade, topic/simplify-dev-export

Children:

6298d80

Parents:

3bd96bb

Message:

Doxygen

File:

• uspace/drv/uhci-hcd/transfer_list.c (modified) (12 diffs)

uspace/drv/uhci-hcd/transfer_list.c

@@ -26 +26 @@
  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
-/** @addtogroup usb
+/** @addtogroup drvusbuhcihc
  * @{
  */
 /** @file
- * @brief UHCI driver
+ * @brief UHCI driver transfer list implementation
  */
 #include <errno.h>
-
 #include <usb/debug.h>
 
@@ -41 +40 @@
     transfer_list_t *instance, batch_t *batch);
 /*----------------------------------------------------------------------------*/
-/** Initializes transfer list structures.
+/** Initialize transfer list structures.
  *
  * @param[in] instance Memory place to use.
- * @param[in] name Name of te new list.
+ * @param[in] name Name of the new list.
  * @return Error code
  *
@@ -66 +65 @@
 }
 /*----------------------------------------------------------------------------*/
-/** Set the next list in chain.
+/** Set the next list in transfer list chain.
  *
  * @param[in] instance List to lead.
@@ -72 +71 @@
  * @return Error code
  *
- * Does not check whether there was a next list already.
+ * Does not check whether this replaces an existing list .
  */
 void transfer_list_set_next(transfer_list_t *instance, transfer_list_t *next)
@@ -80 +79 @@
         if (!instance->queue_head)
                 return;
-        /* set both next and element to point to the same QH */
+        /* Set both next and element to point to the same QH */
         qh_set_next_qh(instance->queue_head, next->queue_head_pa);
         qh_set_element_qh(instance->queue_head, next->queue_head_pa);
 }
 /*----------------------------------------------------------------------------*/
-/** Submits a new transfer batch to list and queue.
+/** Submit transfer batch to the list and queue.
  *
  * @param[in] instance List to use.
  * @param[in] batch Transfer batch to submit.
  * @return Error code
+ *
+ * The batch is added to the end of the list and queue.
  */
 void transfer_list_add_batch(transfer_list_t *instance, batch_t *batch)
@@ -106 +107 @@
         fibril_mutex_lock(&instance->guard);
 
+        /* Add to the hardware queue. */
         if (list_empty(&instance->batch_list)) {
                 /* There is nothing scheduled */
@@ -117 +119 @@
                 qh_set_next_qh(last->qh, pa);
         }
+        /* Add to the driver list */
         list_append(&batch->link, &instance->batch_list);
 
@@ -126 +129 @@
 }
 /*----------------------------------------------------------------------------*/
-/** Removes a transfer batch from the list and queue.
+/** Remove a transfer batch from the list and queue.
  *
  * @param[in] instance List to use.
@@ -144 +147 @@
 
         const char * pos = NULL;
+        /* Remove from the hardware queue */
         if (batch->link.prev == &instance->batch_list) {
                 /* I'm the first one here */
@@ -154 +158 @@
                 pos = "NOT FIRST";
         }
+        /* Remove from the driver list */
         list_remove(&batch->link);
         usb_log_debug("Batch(%p) removed (%s) from %s, next element %x.\n",
@@ -159 +164 @@
 }
 /*----------------------------------------------------------------------------*/
-/** Checks list for finished batches.
+/** Check list for finished batches.
  *
  * @param[in] instance List to use.
  * @return Error code
+ *
+ * Creates a local list of finished batches and calls next_step on each and
+ * every one. This is safer because next_step may theoretically access
+ * this transfer list leading to the deadlock if its done inline.
  */
 void transfer_list_remove_finished(transfer_list_t *instance)
@@ -177 +186 @@
 
                 if (batch_is_complete(batch)) {
+                        /* Save for post-processing */
                         transfer_list_remove_batch(instance, batch);
                         list_append(current, &done);