Changes in uspace/drv/bus/usb/ohci/hw_struct/transfer_descriptor.h [d394f1b8:70d72dd] in mainline

File:

• uspace/drv/bus/usb/ohci/hw_struct/transfer_descriptor.h (modified) (3 diffs)

uspace/drv/bus/usb/ohci/hw_struct/transfer_descriptor.h

@@ -37 +37 @@
 #include <bool.h>
 #include <stdint.h>
+
 #include "../utils/malloc32.h"
-
 #include "completion_codes.h"
 
@@ -46 +46 @@
 #define OHCI_TD_MAX_TRANSFER (4 * 1024)
 
+/**
+ * Transfer Descriptor representation.
+ *
+ * See OHCI spec chapter 4.3.1 General Transfer Descriptor on page 19
+ * (pdf page 33) for details.
+ */
 typedef struct td {
+        /** Status field. Do not touch on active TDs. */
         volatile uint32_t status;
 #define TD_STATUS_ROUND_FLAG (1 << 18)
-#define TD_STATUS_DP_MASK (0x3) /* direction/PID */
+#define TD_STATUS_DP_MASK (0x3) /* Direction/PID */
 #define TD_STATUS_DP_SHIFT (19)
 #define TD_STATUS_DP_SETUP (0x0)
 #define TD_STATUS_DP_OUT (0x1)
 #define TD_STATUS_DP_IN (0x2)
-#define TD_STATUS_DI_MASK (0x7) /* delay interrupt, wait DI frames before int */
+#define TD_STATUS_DI_MASK (0x7) /* Delay interrupt, wait n frames before irq */
 #define TD_STATUS_DI_SHIFT (21)
 #define TD_STATUS_DI_NO_INTERRUPT (0x7)
-#define TD_STATUS_T_MASK (0x3)  /* data toggle 1x = use ED toggle carry */
-#define TD_STATUS_T_SHIFT (24)
-#define TD_STATUS_T_0 (0x2)
-#define TD_STATUS_T_1 (0x3)
-#define TD_STATUS_T_ED (0)
-#define TD_STATUS_EC_MASK (0x3) /* error count */
+#define TD_STATUS_T_FLAG (1 << 24) /* Explicit toggle bit value for this TD */
+#define TD_STATUS_T_USE_TD_FLAG (1 << 25) /* 1 = use bit 24 as toggle bit */
+#define TD_STATUS_EC_MASK (0x3) /* Error count */
 #define TD_STATUS_EC_SHIFT (26)
-#define TD_STATUS_CC_MASK (0xf) /* condition code */
+#define TD_STATUS_CC_MASK (0xf) /* Condition code */
 #define TD_STATUS_CC_SHIFT (28)
 
-        volatile uint32_t cbp; /* current buffer ptr, data to be transfered */
+        /**
+         * Current buffer pointer.
+         * Phys address of the first byte to be transferred. */
+        volatile uint32_t cbp;
+
+        /** Pointer to the next TD in chain. 16-byte aligned. */
         volatile uint32_t next;
 #define TD_NEXT_PTR_MASK (0xfffffff0)
 #define TD_NEXT_PTR_SHIFT (0)
 
-        volatile uint32_t be; /* buffer end, address of the last byte */
+        /**
+         * Buffer end.
+         * Phys address of the last byte of the transfer.
+         * @note this does not have to be on the same page as cbp.
+         */
+        volatile uint32_t be;
 } __attribute__((packed)) td_t;
 
-void td_init(td_t *instance,
+void td_init(td_t *instance, const td_t *next,
     usb_direction_t dir, const void *buffer, size_t size, int toggle);
 
-inline static void td_set_next(td_t *instance, td_t *next)
+/**
+ * Check TD for completion.
+ * @param instance TD structure.
+ * @return true if the TD was accessed and processed by hw, false otherwise.
+ */
+inline static bool td_is_finished(const td_t *instance)
 {
         assert(instance);
-        instance->next = addr_to_phys(next) & TD_NEXT_PTR_MASK;
-}
-
-inline static bool td_is_finished(td_t *instance)
-{
-        assert(instance);
-        int cc = (instance->status >> TD_STATUS_CC_SHIFT) & TD_STATUS_CC_MASK;
-        /* something went wrong, error code is set */
+        const int cc =
+            (instance->status >> TD_STATUS_CC_SHIFT) & TD_STATUS_CC_MASK;
+        /* This value is changed on transfer completion,
+         * either to CC_NOERROR or and error code.
+         * See OHCI spec 4.3.1.3.5 p. 23 (pdf 37) */
         if (cc != CC_NOACCESS1 && cc != CC_NOACCESS2) {
-                return true;
-        }
-        /* everything done */
-        if (cc == CC_NOERROR && instance->cbp == 0) {
                 return true;
         }
@@ -99 +111 @@
 }
 
-static inline int td_error(td_t *instance)
+/**
+ * Get error code that indicates transfer status.
+ * @param instance TD structure.
+ * @return Error code.
+ */
+static inline int td_error(const td_t *instance)
 {
         assert(instance);
-        int cc = (instance->status >> TD_STATUS_CC_SHIFT) & TD_STATUS_CC_MASK;
+        const int cc =
+            (instance->status >> TD_STATUS_CC_SHIFT) & TD_STATUS_CC_MASK;
         return cc_to_rc(cc);
 }
 
+/**
+ * Get remaining portion of buffer to be read/written
+ * @param instance TD structure
+ * @return size of remaining buffer.
+ */
 static inline size_t td_remain_size(td_t *instance)
 {
         assert(instance);
+        /* Current buffer pointer is cleared on successful transfer */
         if (instance->cbp == 0)
                 return 0;
+        /* Buffer end points to the last byte of transfer buffer, so add 1 */
         return instance->be - instance->cbp + 1;
 }