Changeset 28d9c95 in mainline

Timestamp:

2011-05-17T12:21:55Z (13 years ago)

Author:

Jan Vesely <jano.vesely@…>

Branches:

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

Children:

d736fe38

Parents:

5f94a0c

Message:

Cleanup, add normal and doxygen comments

Location:

uspace/drv

Files:

• ohci/batch.c (modified) (15 diffs)
• ohci/batch.h (modified) (2 diffs)
• ohci/hw_struct/transfer_descriptor.c (modified) (1 diff)
• uhci-hcd/batch.c (modified) (3 diffs)

uspace/drv/ohci/batch.c

@@ -44 +44 @@
 #include "hw_struct/transfer_descriptor.h"
 
+/** OHCI specific data required for USB transfer */
 typedef struct ohci_transfer_batch {
+        /** Endpoint descriptor of the target endpoint. */
         ed_t *ed;
+        /** List of TDs needed for the transfer */
         td_t **tds;
+        /** Number of TDs used by the transfer */
         size_t td_count;
+        /** Dummy TD to be left at the ED and used by the next transfer */
         size_t leave_td;
-        char *device_buffer;
+        /** Data buffer, must be accessible byb the OHCI hw. */
+        void *device_buffer;
 } ohci_transfer_batch_t;
-
+/*----------------------------------------------------------------------------*/
+static void batch_control(usb_transfer_batch_t *instance,
+    usb_direction_t data_dir, usb_direction_t status_dir);
+static void batch_data(usb_transfer_batch_t *instance);
+/*----------------------------------------------------------------------------*/
+/** Safely destructs ohci_transfer_batch_t structure
+ *
+ * @param[in] ohci_batch Instance to destroy.
+ */
 static void ohci_transfer_batch_dispose(void *ohci_batch)
 {
@@ -69 +83 @@
 }
 /*----------------------------------------------------------------------------*/
-static void batch_control(usb_transfer_batch_t *instance,
-    usb_direction_t data_dir, usb_direction_t status_dir);
-static void batch_data(usb_transfer_batch_t *instance);
-/*----------------------------------------------------------------------------*/
+/** Allocate memory initialize internal structures
+ *
+ * @param[in] fun DDF function to pass to callback.
+ * @param[in] ep Communication target
+ * @param[in] buffer Data source/destination.
+ * @param[in] buffer_size Size of the buffer.
+ * @param[in] setup_buffer Setup data source (if not NULL)
+ * @param[in] setup_size Size of setup_buffer (should be always 8)
+ * @param[in] func_in function to call on inbound transfer completion
+ * @param[in] func_out function to call on outbound transfer completion
+ * @param[in] arg additional parameter to func_in or func_out
+ * @return Valid pointer if all structures were successfully created,
+ * NULL otherwise.
+ *
+ * Allocates and initializes structures needed by the OHCI hw for the transfer.
+ */
 usb_transfer_batch_t * batch_get(ddf_fun_t *fun, endpoint_t *ep,
     char *buffer, size_t buffer_size, char* setup_buffer, size_t setup_size,
@@ -107 +133 @@
         }
 
-        /* we need one extra place for td that is currently assigned to hcd_ep*/
+        /* We need an extra place for TD that is currently assigned to hcd_ep*/
         data->tds = calloc(sizeof(td_t*), data->td_count + 1);
         CHECK_NULL_DISPOSE_RETURN(data->tds,
             "Failed to allocate transfer descriptors.\n");
 
+        /* Add TD left over by the previous transfer */
         data->tds[0] = hcd_ep->td;
         data->leave_td = 0;
@@ -123 +150 @@
         data->ed = hcd_ep->ed;
 
+        /* NOTE: OHCI is capable of handling buffer that crosses page boundaries
+         * it is, however, not capable of handling buffer that accupies more
+         * than two pages (the first page is computete using start pointer, the
+         * other using end pointer)*/
         if (setup_size + buffer_size > 0) {
                 data->device_buffer = malloc32(setup_size + buffer_size);
@@ -135 +166 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Check batch TDs' status.
+ *
+ * @param[in] instance Batch structure to use.
+ * @return False, if there is an active TD, true otherwise.
+ *
+ * Walk all TDs (usually there is just one). Stop with false if there is an
+ * active TD. Stop with true if an error is found. Return true if the walk
+ * completes with the last TD.
+ */
 bool batch_is_complete(usb_transfer_batch_t *instance)
 {
@@ -178 +218 @@
         /* Clear possible ED HALT */
         data->ed->td_head &= ~ED_TDHEAD_HALTED_FLAG;
-        uint32_t pa = addr_to_phys(hcd_ep->td);
+        const uint32_t pa = addr_to_phys(hcd_ep->td);
         assert(pa == (data->ed->td_head & ED_TDHEAD_PTR_MASK));
         assert(pa == (data->ed->td_tail & ED_TDTAIL_PTR_MASK));
@@ -185 +225 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Starts execution of the TD list
+ *
+ * @param[in] instance Batch structure to use
+ */
 void batch_commit(usb_transfer_batch_t *instance)
 {
@@ -193 +237 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Prepares control write transfer.
+ *
+ * @param[in] instance Batch structure to use.
+ *
+ * Uses generic control transfer using direction OUT(data stage) and
+ * IN(status stage).
+ */
 void batch_control_write(usb_transfer_batch_t *instance)
 {
@@ -203 +254 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Prepares control read transfer.
+ *
+ * @param[in] instance Batch structure to use.
+ *
+ * Uses generic control transfer using direction IN(data stage) and
+ * OUT(status stage).
+ */
 void batch_control_read(usb_transfer_batch_t *instance)
 {
@@ -211 +269 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Prepare interrupt in transfer.
+ *
+ * @param[in] instance Batch structure to use.
+ *
+ * Data transfer.
+ */
 void batch_interrupt_in(usb_transfer_batch_t *instance)
 {
@@ -219 +283 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Prepare interrupt out transfer.
+ *
+ * @param[in] instance Batch structure to use.
+ *
+ * Data transfer.
+ */
 void batch_interrupt_out(usb_transfer_batch_t *instance)
 {
@@ -229 +299 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Prepare bulk in transfer.
+ *
+ * @param[in] instance Batch structure to use.
+ *
+ * Data transfer.
+ */
 void batch_bulk_in(usb_transfer_batch_t *instance)
 {
@@ -237 +313 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Prepare bulk out transfer.
+ *
+ * @param[in] instance Batch structure to use.
+ *
+ * Data transfer.
+ */
 void batch_bulk_out(usb_transfer_batch_t *instance)
 {
@@ -247 +329 @@
 }
 /*----------------------------------------------------------------------------*/
-ed_t * batch_ed(usb_transfer_batch_t *instance)
-{
-        assert(instance);
-        ohci_transfer_batch_t *data = instance->private_data;
-        assert(data);
-        return data->ed;
-}
-/*----------------------------------------------------------------------------*/
+/** Prepare generic control transfer
+ *
+ * @param[in] instance Batch structure to use.
+ * @param[in] data_dir Direction to use for data stage.
+ * @param[in] status_dir Direction to use for status stage.
+ *
+ * Setup stage with toggle 0 and direction BOTH(SETUP_PID)
+ * Data stage with alternating toggle and direction supplied by parameter.
+ * Status stage with toggle 1 and direction supplied by parameter.
+ */
 void batch_control(usb_transfer_batch_t *instance,
     usb_direction_t data_dir, usb_direction_t status_dir)
@@ -303 +387 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Prepare generic data transfer
+ *
+ * @param[in] instance Batch structure to use.
+ *
+ * Direction is supplied by the associated ep and toggle is maintained by the
+ * OHCI hw in ED.
+ */
 void batch_data(usb_transfer_batch_t *instance)
 {

uspace/drv/ohci/batch.h

@@ -41 +41 @@
 #include <usb/host/batch.h>
 
-#include "hw_struct/endpoint_descriptor.h"
-
 usb_transfer_batch_t * batch_get(
     ddf_fun_t *fun, endpoint_t *ep, char *buffer, size_t size,
@@ -65 +63 @@
 
 void batch_bulk_out(usb_transfer_batch_t *instance);
-
-ed_t * batch_ed(usb_transfer_batch_t *instance);
 #endif
 /**

uspace/drv/ohci/hw_struct/transfer_descriptor.c

@@ -44 +44 @@
         assert(instance);
         bzero(instance, sizeof(td_t));
-        instance-> status = 0
+        instance->status = 0
             | ((dp[dir] & TD_STATUS_DP_MASK) << TD_STATUS_DP_SHIFT)
             | ((CC_NOACCESS2 & TD_STATUS_CC_MASK) << TD_STATUS_CC_SHIFT);

uspace/drv/uhci-hcd/batch.c

@@ -45 +45 @@
 #define DEFAULT_ERROR_COUNT 3
 
+/** UHCI specific data required for USB transfer */
 typedef struct uhci_transfer_batch {
+        /** Queue head
+         * This QH is used to maintain UHCI schedule structure and the element
+         * pointer points to the first TD of this batch.
+         */
         qh_t *qh;
+        /** List of TDs needed for the transfer */
         td_t *tds;
+        /** Number of TDs used by the transfer */
+        size_t td_count;
+        /** Data buffer, must be accessible by the UHCI hw */
         void *device_buffer;
-        size_t td_count;
 } uhci_transfer_batch_t;
 /*----------------------------------------------------------------------------*/
-static void uhci_transfer_batch_dispose(void *uhci_batch)
-{
-        uhci_transfer_batch_t *instance = uhci_batch;
-        assert(instance);
-        free32(instance->device_buffer);
-        free(instance);
-}
-/*----------------------------------------------------------------------------*/
-
 static void batch_control(usb_transfer_batch_t *instance,
     usb_packet_id data_stage, usb_packet_id status_stage);
 static void batch_data(usb_transfer_batch_t *instance, usb_packet_id pid);
-
+/*----------------------------------------------------------------------------*/
+/** Safely destructs uhci_transfer_batch_t structure
+ *
+ * @param[in] uhci_batch Instance to destroy.
+ */
+static void uhci_transfer_batch_dispose(void *uhci_batch)
+{
+        uhci_transfer_batch_t *instance = uhci_batch;
+        assert(instance);
+        free32(instance->device_buffer);
+        free(instance);
+}
+/*----------------------------------------------------------------------------*/
 /** Allocate memory and initialize internal data structure.
  *
@@ -173 +184 @@
                 instance->error = td_status(&data->tds[i]);
                 if (instance->error != EOK) {
-                        usb_log_debug("Batch(%p) found error TD(%zu):%" PRIx32 ".\n",
-                            instance, i, data->tds[i].status);
+                        usb_log_debug("Batch(%p) found error TD(%zu):%"
+                            PRIx32 ".\n", instance, i, data->tds[i].status);
                         td_print_status(&data->tds[i]);
 
@@ -397 +408 @@
 /*----------------------------------------------------------------------------*/
 /** Provides access to QH data structure.
+ *
  * @param[in] instance Batch pointer to use.
  * @return Pointer to the QH used by the batch.