Changeset 9d2d444 in mainline for uspace/drv/uhci-hcd/hw_struct

Timestamp:

2011-04-13T19:42:36Z (15 years ago)

Author:

Jan Vesely <jano.vesely@…>

Branches:

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

Children:

ea993d18

Parents:

4c70554

Message:

More refactoring and doxygen

Location:

uspace/drv/uhci-hcd/hw_struct

Files:

• queue_head.h (modified) (4 diffs)
• transfer_descriptor.c (modified) (4 diffs)
• transfer_descriptor.h (modified) (1 diff)

uspace/drv/uhci-hcd/hw_struct/queue_head.h

@@ -37 +37 @@
 
 #include "link_pointer.h"
+#include "transfer_descriptor.h"
 #include "utils/malloc32.h"
 
+/** This structure is defined in UHCI design guide p. 31 */
 typedef struct queue_head {
+        /** Pointer to the next entity (another QH or TD */
         volatile link_pointer_t next;
+        /** Pointer to the contained entities (execution controlled by vertical flag*/
         volatile link_pointer_t element;
 } __attribute__((packed)) qh_t;
@@ -63 +67 @@
  * @param[in] pa Physical address of the next queue head.
  *
- * Adds proper flag. If the pointer is NULL or terminal, sets next to terminal
- * NULL.
+ * Adds proper flag. If the pointer is NULL, sets next to terminal NULL.
  */
 static inline void qh_set_next_qh(qh_t *instance, qh_t *next)
 {
-        /* Address is valid and not terminal */
         uint32_t pa = addr_to_phys(next);
         if (pa) {
@@ -82 +84 @@
  * @param[in] pa Physical address of the TD structure.
  *
- * Adds proper flag. If the pointer is NULL or terminal, sets element
- * to terminal NULL.
+ * Adds proper flag. If the pointer is NULL, sets element to terminal NULL.
  */
-static inline void qh_set_element_td(qh_t *instance, uint32_t pa)
+static inline void qh_set_element_td(qh_t *instance, td_t *td)
 {
-        if (pa && ((pa & LINK_POINTER_TERMINATE_FLAG) == 0)) {
+        uint32_t pa = addr_to_phys(td);
+        if (pa) {
                 instance->element = LINK_POINTER_TD(pa);
         } else {
@@ -93 +95 @@
         }
 }
-
 #endif
 /**

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

@@ -77 +77 @@
 
         instance->status = 0
-            | ((err_count & TD_STATUS_ERROR_COUNT_MASK) << TD_STATUS_ERROR_COUNT_POS)
+            | ((err_count & TD_STATUS_ERROR_COUNT_MASK)
+                << TD_STATUS_ERROR_COUNT_POS)
             | (low_speed ? TD_STATUS_LOW_SPEED_FLAG : 0)
             | (iso ? TD_STATUS_ISOCHRONOUS_FLAG : 0)
@@ -89 +90 @@
             | (((size - 1) & TD_DEVICE_MAXLEN_MASK) << TD_DEVICE_MAXLEN_POS)
             | (toggle ? TD_DEVICE_DATA_TOGGLE_ONE_FLAG : 0)
-            | ((target.address & TD_DEVICE_ADDRESS_MASK) << TD_DEVICE_ADDRESS_POS)
-            | ((target.endpoint & TD_DEVICE_ENDPOINT_MASK) << TD_DEVICE_ENDPOINT_POS)
+            | ((target.address & TD_DEVICE_ADDRESS_MASK)
+                << TD_DEVICE_ADDRESS_POS)
+            | ((target.endpoint & TD_DEVICE_ENDPOINT_MASK)
+                << TD_DEVICE_ENDPOINT_POS)
             | ((pid & TD_DEVICE_PID_MASK) << TD_DEVICE_PID_POS);
 
@@ -114 +117 @@
         assert(instance);
 
-        /* this is hc internal error it should never be reported */
+        /* This is hc internal error it should never be reported. */
         if ((instance->status & TD_STATUS_ERROR_BIT_STUFF) != 0)
                 return EAGAIN;
@@ -123 +126 @@
                 return EBADCHECKSUM;
 
-        /* hc does not end transaction on these, it should never be reported */
+        /* HC does not end transactions on these, it should never be reported */
         if ((instance->status & TD_STATUS_ERROR_NAK) != 0)
                 return EAGAIN;
 
-        /* buffer overrun or underrun */
+        /* Buffer overrun or underrun */
         if ((instance->status & TD_STATUS_ERROR_BUFFER) != 0)
                 return ERANGE;
 
-        /* device babble is something serious */
+        /* Device babble is something serious */
         if ((instance->status & TD_STATUS_ERROR_BABBLE) != 0)
                 return EIO;
 
-        /* stall might represent err count reaching zero or stall response from
-         * the device, is err count reached zero, one of the above is reported*/
+        /* Stall might represent err count reaching zero or stall response from
+         * the device. If err count reached zero, one of the above is reported*/
         if ((instance->status & TD_STATUS_ERROR_STALLED) != 0)
                 return ESTALL;

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

@@ -40 +40 @@
 #include "link_pointer.h"
 
-/** UHCI Transfer Descriptor */
+/** Transfer Descriptor, defined in UHCI design guide p. 26 */
 typedef struct transfer_descriptor {
+        /** Pointer to the next entity (TD or QH) */
         link_pointer_t next;
 
+        /** Status doubleword */
         volatile uint32_t status;
 #define TD_STATUS_RESERVED_MASK 0xc000f800
-#define TD_STATUS_SPD_FLAG ( 1 << 29 )
-#define TD_STATUS_ERROR_COUNT_POS ( 27 )
-#define TD_STATUS_ERROR_COUNT_MASK ( 0x3 )
-#define TD_STATUS_LOW_SPEED_FLAG ( 1 << 26 )
-#define TD_STATUS_ISOCHRONOUS_FLAG ( 1 << 25 )
-#define TD_STATUS_IOC_FLAG ( 1 << 24 )
+#define TD_STATUS_SPD_FLAG         (1 << 29)
+#define TD_STATUS_ERROR_COUNT_POS 27
+#define TD_STATUS_ERROR_COUNT_MASK 0x3
+#define TD_STATUS_LOW_SPEED_FLAG   (1 << 26)
+#define TD_STATUS_ISOCHRONOUS_FLAG (1 << 25)
+#define TD_STATUS_IOC_FLAG         (1 << 24)
 
-#define TD_STATUS_ERROR_ACTIVE ( 1 << 23 )
-#define TD_STATUS_ERROR_STALLED ( 1 << 22 )
-#define TD_STATUS_ERROR_BUFFER ( 1 << 21 )
-#define TD_STATUS_ERROR_BABBLE ( 1 << 20 )
-#define TD_STATUS_ERROR_NAK ( 1 << 19 )
-#define TD_STATUS_ERROR_CRC ( 1 << 18 )
-#define TD_STATUS_ERROR_BIT_STUFF ( 1 << 17 )
-#define TD_STATUS_ERROR_RESERVED ( 1 << 16 )
+#define TD_STATUS_ERROR_ACTIVE    (1 << 23)
+#define TD_STATUS_ERROR_STALLED   (1 << 22)
+#define TD_STATUS_ERROR_BUFFER    (1 << 21)
+#define TD_STATUS_ERROR_BABBLE    (1 << 20)
+#define TD_STATUS_ERROR_NAK       (1 << 19)
+#define TD_STATUS_ERROR_CRC       (1 << 18)
+#define TD_STATUS_ERROR_BIT_STUFF (1 << 17)
+#define TD_STATUS_ERROR_RESERVED  (1 << 16)
 #define TD_STATUS_ERROR_POS 16
-#define TD_STATUS_ERROR_MASK ( 0xff )
+#define TD_STATUS_ERROR_MASK 0xff
 
 #define TD_STATUS_ACTLEN_POS 0
 #define TD_STATUS_ACTLEN_MASK 0x7ff
 
+        /* double word with USB device specific info */
         volatile uint32_t device;
 #define TD_DEVICE_MAXLEN_POS 21
-#define TD_DEVICE_MAXLEN_MASK ( 0x7ff )
-#define TD_DEVICE_RESERVED_FLAG ( 1 << 20 )
-#define TD_DEVICE_DATA_TOGGLE_ONE_FLAG ( 1 << 19 )
+#define TD_DEVICE_MAXLEN_MASK 0x7ff
+#define TD_DEVICE_RESERVED_FLAG        (1 << 20)
+#define TD_DEVICE_DATA_TOGGLE_ONE_FLAG (1 << 19)
 #define TD_DEVICE_ENDPOINT_POS 15
-#define TD_DEVICE_ENDPOINT_MASK ( 0xf )
+#define TD_DEVICE_ENDPOINT_MASK 0xf
 #define TD_DEVICE_ADDRESS_POS 8
-#define TD_DEVICE_ADDRESS_MASK ( 0x7f )
+#define TD_DEVICE_ADDRESS_MASK 0x7f
 #define TD_DEVICE_PID_POS 0
-#define TD_DEVICE_PID_MASK ( 0xff )
+#define TD_DEVICE_PID_MASK 0xff
 
+        /** Pointer(physical) to the beginning of the transaction's buffer */
         volatile uint32_t buffer_ptr;
 
-        /* there is 16 bytes of data available here, according to UHCI
-         * Design guide, according to linux kernel the hardware does not care,
-         * it just needs to be aligned, we don't use it anyway
+        /* According to UHCI design guide, there is 16 bytes of
+         * data available here.
+         * 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;