Index: uspace/drv/bus/usb/xhci/hc.c
===================================================================
--- uspace/drv/bus/usb/xhci/hc.c	(revision 63431db22d38ba4867125d47d6fc3180e8026b8b)
+++ uspace/drv/bus/usb/xhci/hc.c	(revision 17c5e62d0dbb1b04123131491f4743240d75deb7)
@@ -66,4 +66,7 @@
 /**
  * Walk the list of extended capabilities.
+ *
+ * The most interesting thing hidden in extended capabilities is the mapping of
+ * ports to protocol versions and speeds.
  */
 static int hc_parse_ec(xhci_hc_t *hc)
@@ -145,4 +148,7 @@
 }
 
+/**
+ * Initialize MMIO spaces of xHC.
+ */
 int hc_init_mmio(xhci_hc_t *hc, const hw_res_list_parsed_t *hw_res)
 {
@@ -195,4 +201,7 @@
 }
 
+/**
+ * Initialize structures kept in allocated memory.
+ */
 int hc_init_memory(xhci_hc_t *hc, ddf_dev_t *device)
 {
@@ -338,4 +347,7 @@
 }
 
+/**
+ * Claim xHC from BIOS. Implements handoff as per Section 4.22.1 of xHCI spec.
+ */
 int hc_claim(xhci_hc_t *hc, ddf_dev_t *dev)
 {
@@ -344,5 +356,4 @@
 		return EOK;
 
-	/* Section 4.22.1 */
 	/* TODO: Test this with USB3-aware BIOS */
 	usb_log_debug2("LEGSUP: bios: %x, os: %x", hc->legsup->sem_bios, hc->legsup->sem_os);
@@ -363,4 +374,7 @@
 }
 
+/**
+ * Ask the xHC to reset its state. Implements sequence 
+ */
 static int hc_reset(xhci_hc_t *hc)
 {
@@ -454,17 +468,4 @@
 }
 
-int hc_schedule(usb_transfer_batch_t *batch)
-{
-	assert(batch);
-	xhci_hc_t *hc = bus_to_hc(endpoint_get_bus(batch->ep));
-
-	if (!batch->target.address) {
-		usb_log_error("Attempted to schedule transfer to address 0.");
-		return EINVAL;
-	}
-
-	return xhci_transfer_schedule(hc, batch);
-}
-
 typedef int (*event_handler) (xhci_hc_t *, xhci_trb_t *trb);
 
@@ -484,4 +485,14 @@
 }
 
+/**
+ * Dequeue from event ring and handle dequeued events.
+ *
+ * As there can be events, that blocks on waiting for subsequent events,
+ * we solve this problem by first copying the event TRBs from the event ring,
+ * then asserting EHB and only after, handling the events.
+ *
+ * Whenever the event handling blocks, it switches fibril, and incoming
+ * IPC notification will create new event handling fibril for us.
+ */
 static void hc_run_event_ring(xhci_hc_t *hc, xhci_event_ring_t *event_ring, xhci_interrupter_regs_t *intr)
 {
@@ -541,4 +552,13 @@
 }
 
+/**
+ * Handle an interrupt request from xHC. Resolve all situations that trigger an
+ * interrupt separately.
+ *
+ * Note that all RW1C bits in USBSTS register are cleared at the time of
+ * handling the interrupt in irq_code. This method is the top-half.
+ *
+ * @param status contents of USBSTS register at the time of the interrupt.
+ */
 void hc_interrupt(bus_t *bus, uint32_t status)
 {
@@ -573,4 +593,7 @@
 }
 
+/**
+ * Tear down all in-memory structures.
+ */
 void hc_fini(xhci_hc_t *hc)
 {
@@ -585,4 +608,7 @@
 }
 
+/**
+ * Ring a xHC Doorbell. Implements section 4.7.
+ */
 int hc_ring_doorbell(xhci_hc_t *hc, unsigned doorbell, unsigned target)
 {
@@ -594,4 +620,9 @@
 }
 
+/**
+ * Issue an Enable Slot command, returning the obtained Slot ID.
+ *
+ * @param slot_id Pointer where to store the obtained Slot ID.
+ */
 int hc_enable_slot(xhci_hc_t *hc, uint32_t *slot_id)
 {
@@ -615,4 +646,9 @@
 }
 
+/**
+ * Issue a Disable Slot command for a slot occupied by device.
+ *
+ * Frees the device context 
+ */
 int hc_disable_slot(xhci_hc_t *hc, xhci_device_t *dev)
 {
@@ -634,4 +670,7 @@
 }
 
+/**
+ * Prepare an empty Endpoint Input Context inside a dma buffer.
+ */
 static int create_configure_ep_input_ctx(dma_buffer_t *dma_buf)
 {
@@ -649,4 +688,10 @@
 }
 
+/**
+ * Initialize a device, assigning it an address. Implements section 4.3.4.
+ *
+ * @param dev Device to assing an address (unconfigured yet)
+ * @param ep0 EP0 of device TODO remove, can be fetched from dev
+ */
 int hc_address_device(xhci_hc_t *hc, xhci_device_t *dev, xhci_endpoint_t *ep0)
 {
@@ -713,4 +758,9 @@
 }
 
+/**
+ * Issue a Configure Device command for a device in slot.
+ *
+ * @param slot_id Slot ID assigned to the device.
+ */
 int hc_configure_device(xhci_hc_t *hc, uint32_t slot_id)
 {
@@ -726,4 +776,9 @@
 }
 
+/**
+ * Issue a Deconfigure Device command for a device in slot.
+ *
+ * @param slot_id Slot ID assigned to the device.
+ */
 int hc_deconfigure_device(xhci_hc_t *hc, uint32_t slot_id)
 {
@@ -732,4 +787,11 @@
 }
 
+/**
+ * Instruct xHC to add an endpoint with supplied endpoint context.
+ *
+ * @param slot_id Slot ID assigned to the device.
+ * @param ep_idx Endpoint index (number + direction) in question
+ * @param ep_ctx Endpoint context of the endpoint
+ */
 int hc_add_endpoint(xhci_hc_t *hc, uint32_t slot_id, uint8_t ep_idx, xhci_ep_ctx_t *ep_ctx)
 {
@@ -748,4 +810,10 @@
 }
 
+/**
+ * Instruct xHC to drop an endpoint.
+ *
+ * @param slot_id Slot ID assigned to the device.
+ * @param ep_idx Endpoint index (number + direction) in question
+ */
 int hc_drop_endpoint(xhci_hc_t *hc, uint32_t slot_id, uint8_t ep_idx)
 {
@@ -763,4 +831,12 @@
 }
 
+/**
+ * Instruct xHC to update information about an endpoint, using supplied
+ * endpoint context.
+ *
+ * @param slot_id Slot ID assigned to the device.
+ * @param ep_idx Endpoint index (number + direction) in question
+ * @param ep_ctx Endpoint context of the endpoint
+ */
 int hc_update_endpoint(xhci_hc_t *hc, uint32_t slot_id, uint8_t ep_idx, xhci_ep_ctx_t *ep_ctx)
 {
