Index: uspace/drv/bus/usb/ohci/hw_struct/transfer_descriptor.h
===================================================================
--- uspace/drv/bus/usb/ohci/hw_struct/transfer_descriptor.h	(revision d394f1b8dd1a2388176091c3a5ad3d0d48560da2)
+++ uspace/drv/bus/usb/ohci/hw_struct/transfer_descriptor.h	(revision 20a3465b8133a4f1f5c4b5a50daf07cb90a66462)
@@ -37,6 +37,6 @@
 #include <bool.h>
 #include <stdint.h>
+
 #include "../utils/malloc32.h"
-
 #include "completion_codes.h"
 
@@ -46,52 +46,64 @@
 #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,16 +111,29 @@
 }
 
-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;
 }
