Changeset 275bf456 in mainline

Timestamp:

2011-03-07T16:02:26Z (13 years ago)

Author:

Jan Vesely <jano.vesely@…>

Branches:

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

Children:

0d3167e

Parents:

13927cf

Message:

Doxygen and other comments uhci-rhd refactoring.

Location:

uspace/drv/uhci-rhd

Files:

• main.c (modified) (8 diffs)
• port.c (modified) (10 diffs)
• port_status.c (modified) (1 diff)
• root_hub.c (modified) (4 diffs)

uspace/drv/uhci-rhd/main.c

@@ -35 +35 @@
 #include <devman.h>
 #include <device/hw_res.h>
+#include <errno.h>
 #include <usb_iface.h>
 #include <usb/ddfiface.h>
+#include <usb/debug.h>
 
-#include <errno.h>
 
-#include <usb/debug.h>
 
 #include "root_hub.h"
@@ -47 +47 @@
 static int hc_get_my_registers(ddf_dev_t *dev,
     uintptr_t *io_reg_address, size_t *io_reg_size);
-
+/*----------------------------------------------------------------------------*/
 static int usb_iface_get_hc_handle(ddf_fun_t *fun, devman_handle_t *handle)
 {
@@ -58 +58 @@
         return EOK;
 }
-
+/*----------------------------------------------------------------------------*/
 static usb_iface_t uhci_rh_usb_iface = {
         .get_hc_handle = usb_iface_get_hc_handle,
         .get_address = usb_iface_get_address_hub_impl
 };
-
+/*----------------------------------------------------------------------------*/
 static ddf_dev_ops_t uhci_rh_ops = {
         .interfaces[USB_DEV_IFACE] = &uhci_rh_usb_iface,
 };
-
+/*----------------------------------------------------------------------------*/
+/** Initializes a new ddf driver instance of UHCI root hub.
+ *
+ * @param[in] device DDF instance of the device to initialize.
+ * @return Error code.
+ */
 static int uhci_rh_add_device(ddf_dev_t *device)
 {
@@ -104 +109 @@
         return EOK;
 }
-
+/*----------------------------------------------------------------------------*/
 static driver_ops_t uhci_rh_driver_ops = {
         .add_device = uhci_rh_add_device,
 };
-
+/*----------------------------------------------------------------------------*/
 static driver_t uhci_rh_driver = {
         .name = NAME,
@@ -114 +119 @@
 };
 /*----------------------------------------------------------------------------*/
+/** Initializes global driver structures (NONE).
+ *
+ * @param[in] argc Nmber of arguments in argv vector (ignored).
+ * @param[in] argv Cmdline argument vector (ignored).
+ * @return Error code.
+ *
+ * Driver debug level is set here.
+ */
 int main(int argc, char *argv[])
 {
@@ -120 +133 @@
 }
 /*----------------------------------------------------------------------------*/
-int hc_get_my_registers(ddf_dev_t *dev,
-    uintptr_t *io_reg_address, size_t *io_reg_size)
+/** Get address of I/O registers.
+ *
+ * @param[in] dev Device asking for the addresses.
+ * @param[out] io_reg_address Base address of the memory range.
+ * @param[out] io_reg_size Size of the memory range.
+ * @return Error code.
+ */
+int hc_get_my_registers(
+    ddf_dev_t *dev, uintptr_t *io_reg_address, size_t *io_reg_size)
 {
         assert(dev != NULL);
@@ -146 +166 @@
         for (i = 0; i < hw_resources.count; i++) {
                 hw_resource_t *res = &hw_resources.resources[i];
-                switch (res->type) {
-                        case IO_RANGE:
-                                io_address = (uintptr_t)
-                                    res->res.io_range.address;
-                                io_size = res->res.io_range.size;
-                                io_found = true;
-                                break;
-                        default:
-                                break;
+                switch (res->type)
+                {
+                case IO_RANGE:
+                        io_address = (uintptr_t) res->res.io_range.address;
+                        io_size = res->res.io_range.size;
+                        io_found = true;
+
+                default:
+                        break;
                 }
         }
@@ -170 +190 @@
         }
         rc = EOK;
+
 leave:
         async_hangup(parent_phone);
-
         return rc;
 }

uspace/drv/uhci-rhd/port.c

@@ -46 +46 @@
 #include "port_status.h"
 
-static int uhci_port_new_device(uhci_port_t *port, uint16_t status);
+static int uhci_port_new_device(uhci_port_t *port, usb_speed_t speed);
 static int uhci_port_remove_device(uhci_port_t *port);
 static int uhci_port_set_enabled(uhci_port_t *port, bool enabled);
 static int uhci_port_check(void *port);
-static int new_device_enable_port(int portno, void *arg);
-
-int uhci_port_init(
-  uhci_port_t *port, port_status_t *address, unsigned number,
-  unsigned usec, ddf_dev_t *rh)
+static int uhci_port_reset_enable(int portno, void *arg);
+/*----------------------------------------------------------------------------*/
+/** Initializes UHCI root hub port instance.
+ *
+ * @param[in] port Memory structure to use.
+ * @param[in] addr Address of I/O register.
+ * @param[in] number Port number.
+ * @param[in] usec Polling interval.
+ * @param[in] rh Pointer to ddf instance fo the root hub driver.
+ * @return Error code.
+ *
+ * Starts the polling fibril.
+ */
+int uhci_port_init(uhci_port_t *port,
+    port_status_t *address, unsigned number, unsigned usec, ddf_dev_t *rh)
 {
         assert(port);
+
         port->address = address;
         port->number = number;
@@ -62 +73 @@
         port->attached_device = 0;
         port->rh = rh;
+
         int rc = usb_hc_connection_initialize_from_device(
             &port->hc_connection, rh);
@@ -75 +87 @@
                 return ENOMEM;
         }
+
         fibril_add_ready(port->checker);
         usb_log_debug("Port(%p - %d): Added fibril. %x\n",
@@ -81 +94 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Finishes UHCI root hub port instance.
+ *
+ * @param[in] port Memory structure to use.
+ *
+ * Stops the polling fibril.
+ */
 void uhci_port_fini(uhci_port_t *port)
 {
-// TODO: destroy fibril
-// TODO: hangup phone
-//      fibril_teardown(port->checker);
+        /* TODO: Kill fibril here */
         return;
 }
 /*----------------------------------------------------------------------------*/
+/** Periodically checks port status and reports new devices.
+ *
+ * @param[in] port Memory structure to use.
+ * @return Error code.
+ */
 int uhci_port_check(void *port)
 {
-        uhci_port_t *port_instance = port;
-        assert(port_instance);
-//      port_status_write(port_instance->address, 0);
-
+        uhci_port_t *instance = port;
+        assert(instance);
+
+        /* Iteration count, for debug purposes only */
         unsigned count = 0;
 
         while (1) {
-                async_usleep(port_instance->wait_period_usec);
+                async_usleep(instance->wait_period_usec);
 
                 /* read register value */
-                port_status_t port_status =
-                        port_status_read(port_instance->address);
-
-                /* debug print */
-                static fibril_mutex_t dbg_mtx = FIBRIL_MUTEX_INITIALIZER(dbg_mtx);
+                port_status_t port_status = port_status_read(instance->address);
+
+                /* debug print mutex */
+                static fibril_mutex_t dbg_mtx =
+                    FIBRIL_MUTEX_INITIALIZER(dbg_mtx);
                 fibril_mutex_lock(&dbg_mtx);
                 usb_log_debug2("Port(%p - %d): Status: %#04x. === %u\n",
-                  port_instance->address, port_instance->number, port_status, count++);
+                  instance->address, instance->number, port_status, count++);
 //              print_port_status(port_status);
                 fibril_mutex_unlock(&dbg_mtx);
 
-                if ((port_status & STATUS_CONNECTED_CHANGED) != 0) {
-                        usb_log_debug("Port(%p - %d): Connected change detected: %x.\n",
-                            port_instance->address, port_instance->number, port_status);
-
-
-                        int rc = usb_hc_connection_open(
-                            &port_instance->hc_connection);
-                        if (rc != EOK) {
-                                usb_log_error("Port(%p - %d): Failed to connect to HC.",
-                                    port_instance->address, port_instance->number);
-                                continue;
-                        }
-
-                        /* remove any old device */
-                        if (port_instance->attached_device) {
-                                usb_log_debug("Port(%p - %d): Removing device.\n",
-                                    port_instance->address, port_instance->number);
-                                uhci_port_remove_device(port_instance);
-                        }
-
-                        if ((port_status & STATUS_CONNECTED) != 0) {
-                                /* new device */
-                                uhci_port_new_device(port_instance, port_status);
-                        } else {
-                                /* ack changes by writing one to WC bits */
-                                port_status_write(port_instance->address, port_status);
-                                usb_log_debug("Port(%p - %d): Change status ACK.\n",
-                                                port_instance->address, port_instance->number);
-                        }
-
-                        rc = usb_hc_connection_close(
-                            &port_instance->hc_connection);
-                        if (rc != EOK) {
-                                usb_log_error("Port(%p - %d): Failed to disconnect from HC.",
-                                    port_instance->address, port_instance->number);
-                        }
-                }
-        }
-        return EOK;
-}
-
+                if ((port_status & STATUS_CONNECTED_CHANGED) == 0)
+                        continue;
+
+                usb_log_debug("Port(%p - %d): Connected change detected: %x.\n",
+                    instance->address, instance->number, port_status);
+
+                int rc =
+                    usb_hc_connection_open(&instance->hc_connection);
+                if (rc != EOK) {
+                        usb_log_error("Port(%p - %d): Failed to connect to HC.",
+                            instance->address, instance->number);
+                        continue;
+                }
+
+                /* Remove any old device */
+                if (instance->attached_device) {
+                        usb_log_debug2("Port(%p - %d): Removing device.\n",
+                            instance->address, instance->number);
+                        uhci_port_remove_device(instance);
+                }
+
+                if ((port_status & STATUS_CONNECTED) != 0) {
+                        /* New device */
+                        const usb_speed_t speed =
+                            ((port_status & STATUS_LOW_SPEED) != 0) ?
+                            USB_SPEED_LOW : USB_SPEED_FULL;
+                        uhci_port_new_device(instance, speed);
+                } else {
+                        /* Write one to WC bits, to ack changes */
+                        port_status_write(instance->address, port_status);
+                        usb_log_debug("Port(%p - %d): Change status ACK.\n",
+                            instance->address, instance->number);
+                }
+
+                rc = usb_hc_connection_close(&instance->hc_connection);
+                if (rc != EOK) {
+                        usb_log_error("Port(%p - %d): Failed to disconnect.",
+                            instance->address, instance->number);
+                }
+        }
+        return EOK;
+}
+/*----------------------------------------------------------------------------*/
 /** Callback for enabling port during adding a new device.
  *
@@ -159 +183 @@
  * @return Error code.
  */
-static int new_device_enable_port(int portno, void *arg)
+int uhci_port_reset_enable(int portno, void *arg)
 {
         uhci_port_t *port = (uhci_port_t *) arg;
@@ -184 +208 @@
                 port_status_write(port->address, port_status);
                 async_usleep(10000);
-                port_status =
-                        port_status_read(port->address);
+                port_status = port_status_read(port->address);
                 port_status &= ~STATUS_IN_RESET;
                 port_status_write(port->address, port_status);
@@ -194 +217 @@
         /* Enable the port. */
         uhci_port_set_enabled(port, true);
-
-        return EOK;
-}
-
-/*----------------------------------------------------------------------------*/
-static int uhci_port_new_device(uhci_port_t *port, uint16_t status)
+        return EOK;
+}
+/*----------------------------------------------------------------------------*/
+/** Initializes and reports connected device.
+ *
+ * @param[in] port Memory structure to use.
+ * @param[in] speed Detected speed.
+ * @return Error code.
+ *
+ * Uses libUSB function to do the actual work.
+ */
+int uhci_port_new_device(uhci_port_t *port, usb_speed_t speed)
 {
         assert(port);
@@ -209 +238 @@
         usb_address_t dev_addr;
         int rc = usb_hc_new_device_wrapper(port->rh, &port->hc_connection,
-            ((status & STATUS_LOW_SPEED) != 0) ? USB_SPEED_LOW : USB_SPEED_FULL,
-            new_device_enable_port, port->number, port,
+            speed, uhci_port_reset_enable, port->number, port,
             &dev_addr, &port->attached_device, NULL, NULL, NULL);
 
         if (rc != EOK) {
-                usb_log_error("Port(%p-%d): Failed(%d) adding new device: %s.\n",
+                usb_log_error("Port(%p-%d): Failed(%d) to add device: %s.\n",
                     port->address, port->number, rc, str_error(rc));
                 uhci_port_set_enabled(port, false);
@@ -225 +253 @@
         return EOK;
 }
-
-/*----------------------------------------------------------------------------*/
-static int uhci_port_remove_device(uhci_port_t *port)
+/*----------------------------------------------------------------------------*/
+/** Removes device.
+ *
+ * @param[in] port Memory structure to use.
+ * @return Error code.
+ *
+ * Does not work DDF does not support device removal.
+ */
+int uhci_port_remove_device(uhci_port_t *port)
 {
         usb_log_error("Port(%p-%d): Don't know how to remove device %#x.\n",
-                port->address, port->number, (unsigned int)port->attached_device);
-//      uhci_port_set_enabled(port, false);
-        return EOK;
-}
-/*----------------------------------------------------------------------------*/
-static int uhci_port_set_enabled(uhci_port_t *port, bool enabled)
+            port->address, port->number, (unsigned int)port->attached_device);
+        return EOK;
+}
+/*----------------------------------------------------------------------------*/
+/** Enables and disables port.
+ *
+ * @param[in] port Memory structure to use.
+ * @return Error code. (Always EOK)
+ */
+int uhci_port_set_enabled(uhci_port_t *port, bool enabled)
 {
         assert(port);
 
-        /* read register value */
-        port_status_t port_status
-                = port_status_read(port->address);
-
-        /* enable port: register write */
+        /* Read register value */
+        port_status_t port_status = port_status_read(port->address);
+
+        /* Set enabled bit */
         if (enabled) {
                 port_status |= STATUS_ENABLED;
@@ -249 +286 @@
                 port_status &= ~STATUS_ENABLED;
         }
+
+        /* Write new value. */
         port_status_write(port->address, port_status);
 

uspace/drv/uhci-rhd/port_status.c

@@ -60 +60 @@
 };
 
+/** Prints portr status in a human readable way.
+ *
+ * @param[in] value Port value to print.
+ * @return Error code.
+ */
 void print_port_status(port_status_t value)
 {

uspace/drv/uhci-rhd/root_hub.c

@@ -40 +40 @@
 #include "root_hub.h"
 
+/** Initializes UHCI root hub instance.
+ *
+ * @param[in] instance Driver memory structure to use.
+ * @param[in] addr Address of I/O registers.
+ * @param[in] size Size of available I/O space.
+ * @param[in] rh Pointer to ddf instance fo the root hub driver.
+ * @return Error code.
+ */
 int uhci_root_hub_init(
   uhci_root_hub_t *instance, void *addr, size_t size, ddf_dev_t *rh)
@@ -47 +55 @@
         int ret;
 
-        /* allow access to root hub registers */
-        assert(sizeof(port_status_t) * UHCI_ROOT_HUB_PORT_COUNT == size);
+        /* Allow access to root hub port registers */
+        assert(sizeof(port_status_t) * UHCI_ROOT_HUB_PORT_COUNT <= size);
         port_status_t *regs;
         ret = pio_enable(addr, size, (void**)&regs);
-
         if (ret < 0) {
-                usb_log_error("Failed to gain access to port registers at %p\n", regs);
+                usb_log_error(
+                    "Failed to gain access to port registers at %p\n", regs);
                 return ret;
         }
@@ -60 +68 @@
         unsigned i = 0;
         for (; i < UHCI_ROOT_HUB_PORT_COUNT; ++i) {
-                /* mind pointer arithmetics */
+                /* NOTE: mind pointer arithmetics here */
                 ret = uhci_port_init(
-                  &instance->ports[i], regs + i, i, ROOT_HUB_WAIT_USEC, rh);
+                    &instance->ports[i], regs + i, i, ROOT_HUB_WAIT_USEC, rh);
                 if (ret != EOK) {
                         unsigned j = 0;
@@ -74 +82 @@
 }
 /*----------------------------------------------------------------------------*/
-int uhci_root_hub_fini( uhci_root_hub_t* instance )
+/** Finishes UHCI root hub instance.
+ *
+ * @param[in] instance Driver memory structure to use.
+ * @return Error code.
+ */
+int uhci_root_hub_fini(uhci_root_hub_t* instance)
 {
-        assert( instance );
-        // TODO:
-        //destroy fibril here
-        //disable access to registers
+        assert(instance);
+        unsigned i = 0;
+        for (; i < UHCI_ROOT_HUB_PORT_COUNT; ++i) {
+                uhci_port_fini(&instance->ports[i]);
+        }
         return EOK;
 }