Changeset 17ceb72 in mainline for uspace/drv/uhci-hcd/uhci_hc.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/uhci_hc.c (modified) (14 diffs)

uspace/drv/uhci-hcd/uhci_hc.c

@@ -26 +26 @@
  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
-/** @addtogroup usb
+/** @addtogroup drvusbuhcihc
  * @{
  */
 /** @file
- * @brief UHCI driver
+ * @brief UHCI Host controller driver routines
  */
 #include <errno.h>
@@ -59 +59 @@
         }
 };
-
-/** Gets USB address of the calling device.
- *
- * @param[in] fun UHCI hc function.
- * @param[in] handle Handle of the device seeking address.
- * @param[out] address Place to store found address.
- * @return Error code.
- */
 /*----------------------------------------------------------------------------*/
 static int uhci_hc_init_transfer_lists(uhci_hc_t *instance);
@@ -78 +70 @@
     bool low_speed, usb_transfer_type_t transfer, size_t size);
 /*----------------------------------------------------------------------------*/
-/** Initializes UHCI hcd driver structure
+/** Initialize UHCI hcd driver structure
  *
  * @param[in] instance Memory place to initialize.
@@ -86 +78 @@
  * @return Error code.
  * @note Should be called only once on any structure.
+ *
+ * Initializes memory structures, starts up hw, and launches debugger and
+ * interrupt fibrils.
  */
 int uhci_hc_init(uhci_hc_t *instance, ddf_fun_t *fun, void *regs, size_t reg_size)
@@ -130 +125 @@
 }
 /*----------------------------------------------------------------------------*/
-/** Initializes UHCI hcd hw resources.
+/** Initialize UHCI hc hw resources.
  *
  * @param[in] instance UHCI structure to use.
+ * For magic values see UHCI Design Guide
  */
 void uhci_hc_init_hw(uhci_hc_t *instance)
@@ -154 +150 @@
 
         /* Enable all interrupts, but resume interrupt */
-//      pio_write_16(&instance->registers->usbintr,
-//          UHCI_INTR_CRC | UHCI_INTR_COMPLETE | UHCI_INTR_SHORT_PACKET);
+        pio_write_16(&instance->registers->usbintr,
+            UHCI_INTR_CRC | UHCI_INTR_COMPLETE | UHCI_INTR_SHORT_PACKET);
 
         uint16_t status = pio_read_16(&registers->usbcmd);
@@ -166 +162 @@
 }
 /*----------------------------------------------------------------------------*/
-/** Initializes UHCI hcd memory structures.
+/** Initialize UHCI hc memory structures.
  *
  * @param[in] instance UHCI structure to use.
  * @return Error code
  * @note Should be called only once on any structure.
+ *
+ * Structures:
+ *  - interrupt code (I/O addressses are customized per instance)
+ *  - transfer lists (queue heads need to be accessible by the hw)
+ *  - frame list page (needs to be one UHCI hw accessible 4K page)
  */
 int uhci_hc_init_mem_structures(uhci_hc_t *instance)
@@ -229 +230 @@
 }
 /*----------------------------------------------------------------------------*/
-/** Initializes UHCI hcd transfer lists.
+/** Initialize UHCI hc transfer lists.
  *
  * @param[in] instance UHCI structure to use.
  * @return Error code
  * @note Should be called only once on any structure.
+ *
+ * Initializes transfer lists and sets them in one chain to support proper
+ * USB scheduling. Sets pointer table for quick access.
  */
 int uhci_hc_init_transfer_lists(uhci_hc_t *instance)
@@ -293 +297 @@
 }
 /*----------------------------------------------------------------------------*/
-/** Schedules batch for execution.
+/** Schedule batch for execution.
  *
  * @param[in] instance UHCI structure to use.
  * @param[in] batch Transfer batch to schedule.
  * @return Error code
+ *
+ * Checks for bandwidth availability and appends the batch to the proper queue.
  */
 int uhci_hc_schedule(uhci_hc_t *instance, batch_t *batch)
@@ -312 +318 @@
                 return ENOTSUP;
         }
-        /* TODO: check available bandwith here */
+        /* TODO: check available bandwidth here */
 
         transfer_list_t *list =
@@ -322 +328 @@
 }
 /*----------------------------------------------------------------------------*/
-/** Takes action based on the interrupt cause.
+/** Take action based on the interrupt cause.
  *
  * @param[in] instance UHCI structure to use.
- * @param[in] status Value of the stsatus regiser at the time of interrupt.
+ * @param[in] status Value of the status register at the time of interrupt.
+ *
+ * Interrupt might indicate:
+ * - transaction completed, either by triggering IOC, SPD, or an error
+ * - some kind of device error
+ * - resume from suspend state (not implemented)
  */
 void uhci_hc_interrupt(uhci_hc_t *instance, uint16_t status)
@@ -342 +353 @@
 /** Polling function, emulates interrupts.
  *
- * @param[in] arg UHCI structure to use.
- * @return EOK
+ * @param[in] arg UHCI hc structure to use.
+ * @return EOK (should never return)
  */
 int uhci_hc_interrupt_emulator(void* arg)
@@ -366 +377 @@
  *
  * @param[in] arg UHCI structure to use.
- * @return EOK
+ * @return EOK (should never return)
  */
 int uhci_hc_debug_checker(void *arg)
@@ -430 +441 @@
 }
 /*----------------------------------------------------------------------------*/
-/** Checks transfer packets, for USB validity
+/** Check transfer packets, for USB validity
  *
  * @param[in] low_speed Transfer speed.
  * @param[in] transfer Transer type
  * @param[in] size Maximum size of used packets
- * @return EOK
+ * @return True if transaction is allowed by USB specs, false otherwise
  */
 bool allowed_usb_packet(