Changeset eb0dc58 in mainline

Timestamp:

2011-03-13T13:59:19Z (13 years ago)

Author:

Jan Vesely <jano.vesely@…>

Branches:

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

Children:

6143ce3

Parents:

67352d2

Message:

Doxygen comments, use helper function for setting IOC flag

Location:

uspace/drv/uhci-hcd

Files:

• batch.c (modified) (2 diffs)
• uhci_struct/transfer_descriptor.c (modified) (4 diffs)
• uhci_struct/transfer_descriptor.h (modified) (6 diffs)

uspace/drv/uhci-hcd/batch.c

@@ -319 +319 @@
                 ++packet;
         }
-        instance->tds[packet - 1].status |= TD_STATUS_IOC_FLAG;
+        td_set_ioc(&instance->tds[packet - 1]);
         device_keeper_set_toggle(instance->manager, instance->target, toggle);
 }
@@ -371 +371 @@
             0, 1, false, low_speed, instance->target, status_stage, NULL, NULL);
 
-
-        instance->tds[packet].status |= TD_STATUS_IOC_FLAG;
+        td_set_ioc(&instance->tds[packet]);
         usb_log_debug2("Control last TD status: %x.\n",
             instance->tds[packet].status);

uspace/drv/uhci-hcd/uhci_struct/transfer_descriptor.c

@@ -44 +44 @@
  * @param[in] size Size of data source.
  * @param[in] toggle Value of toggle bit.
- * @param[in] iso True if TD is for Isochronous transfer.
+ * @param[in] iso True if TD represents Isochronous transfer.
  * @param[in] low_speed Target device's speed.
  * @param[in] target Address and endpoint receiving the transfer.
@@ -51 +51 @@
  * @param[in] next Net TD in transaction.
  * @return Error code.
+ *
+ * Uses a mix of supplied and default values.
+ * Implicit values:
+ *  - all TDs have vertical flag set (makes transfers to endpoints atomic)
+ *  - in the error field only active it is set
+ *  - if the packet uses PID_IN and is not isochronous SPD is set
+ *
+ * Dumps 8 bytes of buffer if PID_SETUP is used.
  */
 void td_init(td_t *instance, int err_count, size_t size, bool toggle, bool iso,
@@ -94 +102 @@
         if (pid == USB_PID_SETUP) {
                 usb_log_debug("SETUP BUFFER: %s\n",
-                        usb_debug_str_buffer(buffer, 8, 8));
+                    usb_debug_str_buffer(buffer, 8, 8));
         }
 }
@@ -128 +136 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Print values in status field (dw1) in a human readable way.
+ *
+ * @param[in] instance TD structure to use.
+ */
 void td_print_status(td_t *instance)
 {

uspace/drv/uhci-hcd/uhci_struct/transfer_descriptor.h

@@ -45 +45 @@
 
         volatile uint32_t status;
-
 #define TD_STATUS_RESERVED_MASK 0xc000f800
 #define TD_STATUS_SPD_FLAG ( 1 << 29 )
@@ -70 +69 @@
 
         volatile uint32_t device;
-
 #define TD_DEVICE_MAXLEN_POS 21
 #define TD_DEVICE_MAXLEN_MASK ( 0x7ff )
@@ -85 +83 @@
 
         /* there is 16 bytes of data available here, according to UHCI
-         * Design guide, according to linux kernel the hardware does not care
-         * we don't use it anyway
+         * Design guide, according to linux kernel the hardware does not care,
+         * it just needs to be aligned, we don't use it anyway
          */
 } __attribute__((packed)) td_t;
@@ -97 +95 @@
 int td_status(td_t *instance);
 
+void td_print_status(td_t *instance);
+/*----------------------------------------------------------------------------*/
+/** Helper function for parsing actual size out of TD.
+ *
+ * @param[in] instance TD structure to use.
+ * @return Parsed actual size.
+ */
 static inline size_t td_act_size(td_t *instance)
 {
         assert(instance);
-        return
-            ((instance->status >> TD_STATUS_ACTLEN_POS) + 1)
-            & TD_STATUS_ACTLEN_MASK;
+        const uint32_t s = instance->status;
+        return ((s >> TD_STATUS_ACTLEN_POS) + 1) & TD_STATUS_ACTLEN_MASK;
 }
-
+/*----------------------------------------------------------------------------*/
+/** Checks whether less than max data were recieved and packet is marked as SPD.
+ *
+ * @param[in] instance TD structure to use.
+ * @return True if packet is short (less than max bytes and SPD set), false
+ *     otherwise.
+ */
 static inline bool td_is_short(td_t *instance)
 {
@@ -114 +124 @@
             (instance->status | TD_STATUS_SPD_FLAG) && act_size < max_size;
 }
-
+/*----------------------------------------------------------------------------*/
+/** Helper function for parsing value of toggle bit.
+ *
+ * @param[in] instance TD structure to use.
+ * @return Toggle bit value.
+ */
 static inline int td_toggle(td_t *instance)
 {
         assert(instance);
-        return ((instance->device & TD_DEVICE_DATA_TOGGLE_ONE_FLAG) != 0)
-            ? 1 : 0;
+        return (instance->device & TD_DEVICE_DATA_TOGGLE_ONE_FLAG) ? 1 : 0;
 }
-
+/*----------------------------------------------------------------------------*/
+/** Helper function for parsing value of active bit
+ *
+ * @param[in] instance TD structure to use.
+ * @return Active bit value.
+ */
 static inline bool td_is_active(td_t *instance)
 {
@@ -127 +146 @@
         return (instance->status & TD_STATUS_ERROR_ACTIVE) != 0;
 }
-
-void td_print_status(td_t *instance);
+/*----------------------------------------------------------------------------*/
+/** Helper function for setting IOC bit.
+ *
+ * @param[in] instance TD structure to use.
+ */
+static inline void td_set_ioc(td_t *instance)
+{
+        assert(instance);
+        instance->status |= TD_STATUS_IOC_FLAG;
+}
+/*----------------------------------------------------------------------------*/
 #endif
 /**