Index: uspace/drv/ehci-hcd/pci.c
===================================================================
--- uspace/drv/ehci-hcd/pci.c	(revision 4ed80ce8b4e9e95cf33dd066d8ceb8c158889e93)
+++ uspace/drv/ehci-hcd/pci.c	(revision 13927cfcd16bb10a7b1b391c2033d711fe72f45d)
@@ -48,4 +48,5 @@
 
 #define PAGE_SIZE_MASK 0xfffff000
+
 #define HCC_PARAMS_OFFSET 0x8
 #define HCC_PARAMS_EECP_MASK 0xff
@@ -62,10 +63,9 @@
 #define WAIT_STEP 10
 
-
 /** Get address of registers and IRQ for given device.
  *
  * @param[in] dev Device asking for the addresses.
- * @param[out] io_reg_address Base address of the I/O range.
- * @param[out] io_reg_size Size of the I/O range.
+ * @param[out] mem_reg_address Base address of the memory range.
+ * @param[out] mem_reg_size Size of the memory range.
  * @param[out] irq_no IRQ assigned to the device.
  * @return Error code.
@@ -136,4 +136,9 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Calls the PCI driver with a request to enable interrupts
+ *
+ * @param[in] device Device asking for interrupts
+ * @return Error code.
+ */
 int pci_enable_interrupts(ddf_dev_t *device)
 {
@@ -148,4 +153,9 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Implements BIOS handoff routine as decribed in EHCI spec
+ *
+ * @param[in] device Device asking for interrupts
+ * @return Error code.
+ */
 int pci_disable_legacy(ddf_dev_t *device)
 {
@@ -165,5 +175,5 @@
 
 
-	/* read register space BAR */
+	/* read register space BASE BAR */
 	sysarg_t address = 0x10;
 	sysarg_t value;
@@ -175,9 +185,9 @@
 	usb_log_info("Register space BAR at %p:%x.\n", address, value);
 
-	/* clear lower byte, it's not part of the address */
+	/* clear lower byte, it's not part of the BASE address */
 	uintptr_t registers = (value & 0xffffff00);
-	usb_log_info("Memory registers address:%p.\n", registers);
-
-	/* if nothing setup the hc, the we don't need to to turn it off */
+	usb_log_info("Memory registers BASE address:%p.\n", registers);
+
+	/* if nothing setup the hc, we don't need to turn it off */
 	if (registers == 0)
 		return ENOTSUP;
@@ -195,10 +205,14 @@
 	const uint32_t hcc_params =
 	    *(uint32_t*)(registers + HCC_PARAMS_OFFSET);
-
 	usb_log_debug("Value of hcc params register: %x.\n", hcc_params);
+
+	/* Read value of EHCI Extended Capabilities Pointer
+	 * (points to PCI config space) */
 	uint32_t eecp =
 	    (hcc_params >> HCC_PARAMS_EECP_OFFSET) & HCC_PARAMS_EECP_MASK;
 	usb_log_debug("Value of EECP: %x.\n", eecp);
 
+	/* Read the second EEC. i.e. Legacy Support and Control register */
+	/* TODO: Check capability type here */
 	ret = async_req_2_1(parent_phone, DEV_IFACE_ID(PCI_DEV_IFACE),
 	    IPC_M_CONFIG_SPACE_READ_32, eecp + USBLEGCTLSTS_OFFSET, &value);
@@ -206,4 +220,6 @@
 	usb_log_debug("USBLEGCTLSTS: %x.\n", value);
 
+	/* Read the first EEC. i.e. Legacy Support register */
+	/* TODO: Check capability type here */
 	ret = async_req_2_1(parent_phone, DEV_IFACE_ID(PCI_DEV_IFACE),
 	    IPC_M_CONFIG_SPACE_READ_32, eecp + USBLEGSUP_OFFSET, &value);
@@ -211,12 +227,13 @@
 	usb_log_debug2("USBLEGSUP: %x.\n", value);
 
-	/* request control from firmware/BIOS, by writing 1 to highest byte */
+	/* Request control from firmware/BIOS, by writing 1 to highest byte.
+	 * (OS Control semaphore)*/
 	ret = async_req_3_0(parent_phone, DEV_IFACE_ID(PCI_DEV_IFACE),
 	   IPC_M_CONFIG_SPACE_WRITE_8, eecp + USBLEGSUP_OFFSET + 3, 1);
-	CHECK_RET_HANGUP_RETURN(ret, "Failed(%d) request OS EHCI control.\n",
+	CHECK_RET_HANGUP_RETURN(ret, "Failed(%d) to request OS EHCI control.\n",
 	    ret);
 
 	size_t wait = 0;
-	/* wait for BIOS to release control */
+	/* Wait for BIOS to release control. */
 	while ((wait < DEFAULT_WAIT) && (value & USBLEGSUP_BIOS_CONTROL)) {
 		async_usleep(WAIT_STEP);
@@ -226,7 +243,9 @@
 	}
 
+
 	if ((value & USBLEGSUP_BIOS_CONTROL) != 0) {
 		usb_log_info("BIOS released control after %d usec.\n", wait);
 	} else {
+		/* BIOS failed to hand over control, this should not happen. */
 		usb_log_warning( "BIOS failed to release control after"
 		    "%d usecs, force it.\n", wait);
@@ -236,8 +255,10 @@
 		CHECK_RET_HANGUP_RETURN(ret,
 		    "Failed(%d) to force OS EHCI control.\n", ret);
-	}
-
-
-	/* zero SMI enables in legacy control register */
+		/* TODO: This does not seem to work on my machine */
+	}
+
+
+	/* Zero SMI enables in legacy control register.
+	 * It would prevent pre-OS code from interfering. */
 	ret = async_req_3_0(parent_phone, DEV_IFACE_ID(PCI_DEV_IFACE),
 	   IPC_M_CONFIG_SPACE_WRITE_32, eecp + USBLEGCTLSTS_OFFSET, 0);
@@ -245,4 +266,5 @@
 	usb_log_debug("Zeroed USBLEGCTLSTS register.\n");
 
+	/* Read again Legacy Support and Control register */
 	ret = async_req_2_1(parent_phone, DEV_IFACE_ID(PCI_DEV_IFACE),
 	    IPC_M_CONFIG_SPACE_READ_32, eecp + USBLEGCTLSTS_OFFSET, &value);
@@ -250,4 +272,5 @@
 	usb_log_debug2("USBLEGCTLSTS: %x.\n", value);
 
+	/* Read again Legacy Support register */
 	ret = async_req_2_1(parent_phone, DEV_IFACE_ID(PCI_DEV_IFACE),
 	    IPC_M_CONFIG_SPACE_READ_32, eecp + USBLEGSUP_OFFSET, &value);
@@ -259,8 +282,9 @@
  */
 
-	/* size of capability registers in memory space */
+	/* Get size of capability registers in memory space. */
 	uint8_t operation_offset = *(uint8_t*)registers;
 	usb_log_debug("USBCMD offset: %d.\n", operation_offset);
-	/* zero USBCMD register */
+
+	/* Zero USBCMD register. */
 	volatile uint32_t *usbcmd =
 	 (uint32_t*)((uint8_t*)registers + operation_offset);
@@ -273,5 +297,4 @@
 	}
 
-
 	async_hangup(parent_phone);
 	return ret;
