Changeset 13927cf in mainline for uspace/drv/ehci-hcd/pci.c

Timestamp:

2011-03-07T14:30:32Z (14 years ago)

Author:

Jan Vesely <jano.vesely@…>

Branches:

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

Children:

275bf456

Parents:

bcaefe3

Message:

Doxygen and other comments

File:

• uspace/drv/ehci-hcd/pci.c (modified) (15 diffs)

uspace/drv/ehci-hcd/pci.c

@@ -48 +48 @@
 
 #define PAGE_SIZE_MASK 0xfffff000
+
 #define HCC_PARAMS_OFFSET 0x8
 #define HCC_PARAMS_EECP_MASK 0xff
@@ -62 +63 @@
 #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 +136 @@
 }
 /*----------------------------------------------------------------------------*/
+/** 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 +153 @@
 }
 /*----------------------------------------------------------------------------*/
+/** 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 +175 @@
 
 
-        /* read register space BAR */
+        /* read register space BASE BAR */
         sysarg_t address = 0x10;
         sysarg_t value;
@@ -175 +185 @@
         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 +205 @@
         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 +220 @@
         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 +227 @@
         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 +243 @@
         }
 
+
         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 +255 @@
                 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 +266 @@
         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 +272 @@
         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 +282 @@
  */
 
-        /* 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 +297 @@
         }
 
-
         async_hangup(parent_phone);
         return ret;