Changeset ec4538d in mainline for uspace/drv/uhci-hcd

Timestamp:

2011-03-07T19:08:13Z (15 years ago)

Author:

Jan Vesely <jano.vesely@…>

Branches:

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

Children:

1d115c8, a8e98498

Parents:

f16a76b (diff), 18e9eeb (diff)
Note: this is a merge changeset, the changes displayed below correspond to the merge itself.
Use the (diff) links above to see all the changes relative to each parent.

Message:

EHCI handsoff fix (it works now), refactoring, Doxygen

Location:

uspace/drv/uhci-hcd

Files:

• batch.c (modified) (21 diffs)
• iface.c (modified) (11 diffs)
• main.c (modified) (5 diffs)
• pci.c (modified) (5 diffs)
• root_hub.c (modified) (5 diffs)
• transfer_list.c (modified) (7 diffs)
• transfer_list.h (modified) (1 diff)
• uhci.c (modified) (15 diffs)
• uhci.h (modified) (1 diff)
• uhci_struct/queue_head.h (modified) (2 diffs)
• uhci_struct/transfer_descriptor.c (modified) (2 diffs)
• utils/device_keeper.c (modified) (14 diffs)

uspace/drv/uhci-hcd/batch.c

@@ -57 +57 @@
 
 
+/** Allocates memory and initializes internal data structures.
+ *
+ * @param[in] fun DDF function to pass to callback.
+ * @param[in] target Device and endpoint target of the transaction.
+ * @param[in] transfer_type Interrupt, Control or Bulk.
+ * @param[in] max_packet_size maximum allowed size of data packets.
+ * @param[in] speed Speed of the transaction.
+ * @param[in] buffer Data source/destination.
+ * @param[in] size Size of the buffer.
+ * @param[in] setup_buffer Setup data source (if not NULL)
+ * @param[in] setup_size Size of setup_buffer (should be always 8)
+ * @param[in] func_in function to call on inbound transaction completion
+ * @param[in] func_out function to call on outbound transaction completion
+ * @param[in] arg additional parameter to func_in or func_out
+ * @param[in] manager Pointer to toggle management structure.
+ * @return False, if there is an active TD, true otherwise.
+ */
 batch_t * batch_get(ddf_fun_t *fun, usb_target_t target,
     usb_transfer_type_t transfer_type, size_t max_packet_size,
@@ -69 +86 @@
         assert(func_in != NULL || func_out != NULL);
 
+#define CHECK_NULL_DISPOSE_RETURN(ptr, message...) \
+        if (ptr == NULL) { \
+                usb_log_error(message); \
+                if (instance) { \
+                        batch_dispose(instance); \
+                } \
+                return NULL; \
+        } else (void)0
+
         batch_t *instance = malloc(sizeof(batch_t));
-        if (instance == NULL) {
-                usb_log_error("Failed to allocate batch instance.\n");
-                return NULL;
-        }
-
-        instance->qh = queue_head_get();
-        if (instance->qh == NULL) {
-                usb_log_error("Failed to allocate queue head.\n");
-                free(instance);
-                return NULL;
-        }
+        CHECK_NULL_DISPOSE_RETURN(instance,
+            "Failed to allocate batch instance.\n");
+        bzero(instance, sizeof(batch_t));
+
+        instance->qh = malloc32(sizeof(queue_head_t));
+        CHECK_NULL_DISPOSE_RETURN(instance->qh,
+            "Failed to allocate batch queue head.\n");
+        queue_head_init(instance->qh);
 
         instance->packets = (size + max_packet_size - 1) / max_packet_size;
@@ -88 +111 @@
 
         instance->tds = malloc32(sizeof(td_t) * instance->packets);
-        if (instance->tds == NULL) {
-                usb_log_error("Failed to allocate transfer descriptors.\n");
-                queue_head_dispose(instance->qh);
-                free(instance);
-                return NULL;
-        }
+        CHECK_NULL_DISPOSE_RETURN(
+            instance->tds, "Failed to allocate transfer descriptors.\n");
         bzero(instance->tds, sizeof(td_t) * instance->packets);
 
-        const size_t transport_size = max_packet_size * instance->packets;
-
-        instance->transport_buffer =
-           (size > 0) ? malloc32(transport_size) : NULL;
-
-        if ((size > 0) && (instance->transport_buffer == NULL)) {
-                usb_log_error("Failed to allocate device accessible buffer.\n");
-                queue_head_dispose(instance->qh);
-                free32(instance->tds);
-                free(instance);
-                return NULL;
-        }
-
-        instance->setup_buffer = setup_buffer ? malloc32(setup_size) : NULL;
-        if ((setup_size > 0) && (instance->setup_buffer == NULL)) {
-                usb_log_error("Failed to allocate device accessible setup buffer.\n");
-                queue_head_dispose(instance->qh);
-                free32(instance->tds);
-                free32(instance->transport_buffer);
-                free(instance);
-                return NULL;
-        }
-        if (instance->setup_buffer) {
+//      const size_t transport_size = max_packet_size * instance->packets;
+
+        if (size > 0) {
+                instance->transport_buffer = malloc32(size);
+                CHECK_NULL_DISPOSE_RETURN(instance->transport_buffer,
+                    "Failed to allocate device accessible buffer.\n");
+        }
+
+        if (setup_size > 0) {
+                instance->setup_buffer = malloc32(setup_size);
+                CHECK_NULL_DISPOSE_RETURN(instance->setup_buffer,
+                    "Failed to allocate device accessible setup buffer.\n");
                 memcpy(instance->setup_buffer, setup_buffer, setup_size);
         }
 
+
+        link_initialize(&instance->link);
+
         instance->max_packet_size = max_packet_size;
-
-        link_initialize(&instance->link);
-
         instance->target = target;
         instance->transfer_type = transfer_type;
-
-        if (func_out)
-                instance->callback_out = func_out;
-        if (func_in)
-                instance->callback_in = func_in;
-
         instance->buffer = buffer;
         instance->buffer_size = size;
@@ -142 +144 @@
         instance->manager = manager;
 
-        queue_head_element_td(instance->qh, addr_to_phys(instance->tds));
+        if (func_out)
+                instance->callback_out = func_out;
+        if (func_in)
+                instance->callback_in = func_in;
+
+        queue_head_set_element_td(instance->qh, addr_to_phys(instance->tds));
+
         usb_log_debug("Batch(%p) %d:%d memory structures ready.\n",
             instance, target.address, target.endpoint);
@@ -148 +156 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Checks batch TDs for activity.
+ *
+ * @param[in] instance Batch structure to use.
+ * @return False, if there is an active TD, true otherwise.
+ */
 bool batch_is_complete(batch_t *instance)
 {
@@ -165 +178 @@
                             instance, i, instance->tds[i].status);
 
-                        device_keeper_set_toggle(instance->manager, instance->target,
-                            td_toggle(&instance->tds[i]));
+                        device_keeper_set_toggle(instance->manager,
+                            instance->target, td_toggle(&instance->tds[i]));
                         if (i > 0)
                                 goto substract_ret;
@@ -181 +194 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Prepares control write transaction.
+ *
+ * @param[in] instance Batch structure to use.
+ */
 void batch_control_write(batch_t *instance)
 {
         assert(instance);
         /* we are data out, we are supposed to provide data */
-        memcpy(instance->transport_buffer, instance->buffer, instance->buffer_size);
+        memcpy(instance->transport_buffer, instance->buffer,
+            instance->buffer_size);
         batch_control(instance, USB_PID_OUT, USB_PID_IN);
         instance->next_step = batch_call_out_and_dispose;
@@ -192 +210 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Prepares control read transaction.
+ *
+ * @param[in] instance Batch structure to use.
+ */
 void batch_control_read(batch_t *instance)
 {
@@ -201 +223 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Prepares interrupt in transaction.
+ *
+ * @param[in] instance Batch structure to use.
+ */
 void batch_interrupt_in(batch_t *instance)
 {
@@ -210 +236 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Prepares interrupt out transaction.
+ *
+ * @param[in] instance Batch structure to use.
+ */
 void batch_interrupt_out(batch_t *instance)
 {
         assert(instance);
+        /* we are data out, we are supposed to provide data */
         memcpy(instance->transport_buffer, instance->buffer, instance->buffer_size);
         batch_data(instance, USB_PID_OUT);
@@ -220 +251 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Prepares bulk in transaction.
+ *
+ * @param[in] instance Batch structure to use.
+ */
 void batch_bulk_in(batch_t *instance)
 {
@@ -229 +264 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Prepares bulk out transaction.
+ *
+ * @param[in] instance Batch structure to use.
+ */
 void batch_bulk_out(batch_t *instance)
 {
@@ -239 +278 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Prepares generic data transaction
+ *
+ * @param[in] instance Batch structure to use.
+ * @param[in] pid to use for data packets.
+ */
 void batch_data(batch_t *instance, usb_packet_id pid)
 {
         assert(instance);
         const bool low_speed = instance->speed == USB_SPEED_LOW;
-        int toggle = device_keeper_get_toggle(instance->manager, instance->target);
+        int toggle =
+            device_keeper_get_toggle(instance->manager, instance->target);
         assert(toggle == 0 || toggle == 1);
 
@@ -253 +298 @@
                     - remain_size;
 
-
                 const size_t packet_size =
                     (instance->max_packet_size > remain_size) ?
                     remain_size : instance->max_packet_size;
 
-                td_init(&instance->tds[packet],
-                    DEFAULT_ERROR_COUNT, packet_size, toggle, false, low_speed,
-                    instance->target, pid, data,
-                    &instance->tds[packet + 1]);
+                td_t *next_packet = (packet + 1 < instance->packets)
+                    ? &instance->tds[packet + 1] : NULL;
+
+                assert(packet < instance->packets);
+                assert(packet_size <= remain_size);
+
+                td_init(
+                    &instance->tds[packet], DEFAULT_ERROR_COUNT, packet_size,
+                    toggle, false, low_speed, instance->target, pid, data,
+                    next_packet);
+
 
                 toggle = 1 - toggle;
+                remain_size -= packet_size;
                 ++packet;
-                assert(packet <= instance->packets);
-                assert(packet_size <= remain_size);
-                remain_size -= packet_size;
         }
         device_keeper_set_toggle(instance->manager, instance->target, toggle);
-
-        instance->tds[packet - 1].status |= TD_STATUS_COMPLETE_INTERRUPT_FLAG;
-        instance->tds[packet - 1].next = 0 | LINK_POINTER_TERMINATE_FLAG;
-}
-/*----------------------------------------------------------------------------*/
+}
+/*----------------------------------------------------------------------------*/
+/** Prepares generic control transaction
+ *
+ * @param[in] instance Batch structure to use.
+ * @param[in] data_stage to use for data packets.
+ * @param[in] status_stage to use for data packets.
+ */
 void batch_control(batch_t *instance,
    usb_packet_id data_stage, usb_packet_id status_stage)
@@ -301 +353 @@
                     remain_size : instance->max_packet_size;
 
-                td_init(&instance->tds[packet],
-                    DEFAULT_ERROR_COUNT, packet_size, toggle, false, low_speed,
-                    instance->target, data_stage, data,
-                    &instance->tds[packet + 1]);
+                td_init(
+                    &instance->tds[packet], DEFAULT_ERROR_COUNT, packet_size,
+                    toggle, false, low_speed, instance->target, data_stage,
+                    data, &instance->tds[packet + 1]);
 
                 ++packet;
@@ -323 +375 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Prepares data, gets error status and calls callback in.
+ *
+ * @param[in] instance Batch structure to use.
+ */
 void batch_call_in(batch_t *instance)
 {
@@ -328 +384 @@
         assert(instance->callback_in);
 
-        memcpy(instance->buffer, instance->transport_buffer, instance->buffer_size);
+        /* we are data in, we need data */
+        memcpy(instance->buffer, instance->transport_buffer,
+            instance->buffer_size);
 
         int err = instance->error;
@@ -335 +393 @@
             instance->transfered_size);
 
-        instance->callback_in(instance->fun,
-            err, instance->transfered_size,
-            instance->arg);
-}
-/*----------------------------------------------------------------------------*/
+        instance->callback_in(
+            instance->fun, err, instance->transfered_size, instance->arg);
+}
+/*----------------------------------------------------------------------------*/
+/** Gets error status and calls callback out.
+ *
+ * @param[in] instance Batch structure to use.
+ */
 void batch_call_out(batch_t *instance)
 {
@@ -352 +413 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Prepares data, gets error status, calls callback in and dispose.
+ *
+ * @param[in] instance Batch structure to use.
+ */
 void batch_call_in_and_dispose(batch_t *instance)
 {
@@ -359 +424 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Gets error status, calls callback out and dispose.
+ *
+ * @param[in] instance Batch structure to use.
+ */
 void batch_call_out_and_dispose(batch_t *instance)
 {
@@ -366 +435 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Correctly disposes all used data structures.
+ *
+ * @param[in] instance Batch structure to use.
+ */
 void batch_dispose(batch_t *instance)
 {
         assert(instance);
         usb_log_debug("Batch(%p) disposing.\n", instance);
+        /* free32 is NULL safe */
         free32(instance->tds);
         free32(instance->qh);

uspace/drv/uhci-hcd/iface.c

@@ -43 +43 @@
 #include "utils/device_keeper.h"
 
+/** Reserve default address interface function
+ *
+ * @param[in] fun DDF function that was called.
+ * @param[in] speed Speed to associate with the new default address.
+ * @return Error code.
+ */
 /*----------------------------------------------------------------------------*/
 static int reserve_default_address(ddf_fun_t *fun, usb_speed_t speed)
@@ -54 +60 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Release default address interface function
+ *
+ * @param[in] fun DDF function that was called.
+ * @return Error code.
+ */
 static int release_default_address(ddf_fun_t *fun)
 {
@@ -64 +75 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Request address interface function
+ *
+ * @param[in] fun DDF function that was called.
+ * @param[in] speed Speed to associate with the new default address.
+ * @param[out] address Place to write a new address.
+ * @return Error code.
+ */
 static int request_address(ddf_fun_t *fun, usb_speed_t speed,
     usb_address_t *address)
@@ -80 +98 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Bind address interface function
+ *
+ * @param[in] fun DDF function that was called.
+ * @param[in] address Address of the device
+ * @param[in] handle Devman handle of the device driver.
+ * @return Error code.
+ */
 static int bind_address(
   ddf_fun_t *fun, usb_address_t address, devman_handle_t handle)
@@ -91 +116 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Release address interface function
+ *
+ * @param[in] fun DDF function that was called.
+ * @param[in] address USB address to be released.
+ * @return Error code.
+ */
 static int release_address(ddf_fun_t *fun, usb_address_t address)
 {
@@ -101 +132 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Interrupt out transaction interface function
+ *
+ * @param[in] fun DDF function that was called.
+ * @param[in] target USB device to write to.
+ * @param[in] max_packet_size maximum size of data packet the device accepts
+ * @param[in] data Source of data.
+ * @param[in] size Size of data source.
+ * @param[in] callback Function to call on transaction completion
+ * @param[in] arg Additional for callback function.
+ * @return Error code.
+ */
 static int interrupt_out(ddf_fun_t *fun, usb_target_t target,
     size_t max_packet_size, void *data, size_t size,
@@ -122 +164 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Interrupt in transaction interface function
+ *
+ * @param[in] fun DDF function that was called.
+ * @param[in] target USB device to write to.
+ * @param[in] max_packet_size maximum size of data packet the device accepts
+ * @param[out] data Data destination.
+ * @param[in] size Size of data source.
+ * @param[in] callback Function to call on transaction completion
+ * @param[in] arg Additional for callback function.
+ * @return Error code.
+ */
 static int interrupt_in(ddf_fun_t *fun, usb_target_t target,
     size_t max_packet_size, void *data, size_t size,
@@ -142 +195 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Bulk out transaction interface function
+ *
+ * @param[in] fun DDF function that was called.
+ * @param[in] target USB device to write to.
+ * @param[in] max_packet_size maximum size of data packet the device accepts
+ * @param[in] data Source of data.
+ * @param[in] size Size of data source.
+ * @param[in] callback Function to call on transaction completion
+ * @param[in] arg Additional for callback function.
+ * @return Error code.
+ */
 static int bulk_out(ddf_fun_t *fun, usb_target_t target,
     size_t max_packet_size, void *data, size_t size,
@@ -163 +227 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Bulk in transaction interface function
+ *
+ * @param[in] fun DDF function that was called.
+ * @param[in] target USB device to write to.
+ * @param[in] max_packet_size maximum size of data packet the device accepts
+ * @param[out] data Data destination.
+ * @param[in] size Size of data source.
+ * @param[in] callback Function to call on transaction completion
+ * @param[in] arg Additional for callback function.
+ * @return Error code.
+ */
 static int bulk_in(ddf_fun_t *fun, usb_target_t target,
     size_t max_packet_size, void *data, size_t size,
@@ -183 +258 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Control write transaction interface function
+ *
+ * @param[in] fun DDF function that was called.
+ * @param[in] target USB device to write to.
+ * @param[in] max_packet_size maximum size of data packet the device accepts.
+ * @param[in] setup_data Data to send with SETUP packet.
+ * @param[in] setup_size Size of data to send with SETUP packet (should be 8B).
+ * @param[in] data Source of data.
+ * @param[in] size Size of data source.
+ * @param[in] callback Function to call on transaction completion.
+ * @param[in] arg Additional for callback function.
+ * @return Error code.
+ */
 static int control_write(ddf_fun_t *fun, usb_target_t target,
     size_t max_packet_size,
@@ -208 +296 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Control read transaction interface function
+ *
+ * @param[in] fun DDF function that was called.
+ * @param[in] target USB device to write to.
+ * @param[in] max_packet_size maximum size of data packet the device accepts.
+ * @param[in] setup_data Data to send with SETUP packet.
+ * @param[in] setup_size Size of data to send with SETUP packet (should be 8B).
+ * @param[out] data Source of data.
+ * @param[in] size Size of data source.
+ * @param[in] callback Function to call on transaction completion.
+ * @param[in] arg Additional for callback function.
+ * @return Error code.
+ */
 static int control_read(ddf_fun_t *fun, usb_target_t target,
     size_t max_packet_size,

uspace/drv/uhci-hcd/main.c

@@ -60 +60 @@
 };
 /*----------------------------------------------------------------------------*/
+/** IRQ handling callback, identifies devic
+ *
+ * @param[in] dev DDF instance of the device to use.
+ * @param[in] iid (Unused).
+ * @param[in] call Pointer to the call that represents interrupt.
+ */
 static void irq_handler(ddf_dev_t *dev, ipc_callid_t iid, ipc_call_t *call)
 {
@@ -69 +75 @@
 }
 /*----------------------------------------------------------------------------*/
-static int uhci_add_device(ddf_dev_t *device)
+/** Initializes a new ddf driver instance of UHCI hcd.
+ *
+ * @param[in] device DDF instance of the device to initialize.
+ * @return Error code.
+ *
+ * Gets and initialies hardware resources, disables any legacy support,
+ * and reports root hub device.
+ */
+int uhci_add_device(ddf_dev_t *device)
 {
         assert(device);
@@ -96 +110 @@
         ret = pci_disable_legacy(device);
         CHECK_RET_FREE_HC_RETURN(ret,
-            "Failed(%d) disable legacy USB: %s.\n", ret, str_error(ret));
+            "Failed(%d) to disable legacy USB: %s.\n", ret, str_error(ret));
 
 #if 0
@@ -113 +127 @@
 
         ret = uhci_init(hcd, device, (void*)io_reg_base, io_reg_size);
-        CHECK_RET_FREE_HC_RETURN(ret, "Failed(%d) to init uhci-hcd.\n",
-            ret);
+        CHECK_RET_FREE_HC_RETURN(ret, "Failed(%d) to init uhci-hcd.\n", ret);
 #undef CHECK_RET_FREE_HC_RETURN
 
@@ -155 +168 @@
 }
 /*----------------------------------------------------------------------------*/
+/** 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[])
 {

uspace/drv/uhci-hcd/pci.c

@@ -65 +65 @@
 
         int rc;
-
         hw_resource_list_t hw_resources;
         rc = hw_res_get_resource_list(parent_phone, &hw_resources);
@@ -82 +81 @@
         for (i = 0; i < hw_resources.count; i++) {
                 hw_resource_t *res = &hw_resources.resources[i];
-                switch (res->type) {
-                        case INTERRUPT:
-                                irq = res->res.interrupt.irq;
-                                irq_found = true;
-                                usb_log_debug2("Found interrupt: %d.\n", irq);
-                                break;
-                        case IO_RANGE:
-                                io_address = res->res.io_range.address;
-                                io_size = res->res.io_range.size;
-                                usb_log_debug2("Found io: %llx %zu.\n",
-                                    res->res.io_range.address, res->res.io_range.size);
-                                io_found = true;
-                                break;
-                        default:
-                                break;
+                switch (res->type)
+                {
+                case INTERRUPT:
+                        irq = res->res.interrupt.irq;
+                        irq_found = true;
+                        usb_log_debug2("Found interrupt: %d.\n", irq);
+                        break;
+
+                case IO_RANGE:
+                        io_address = res->res.io_range.address;
+                        io_size = res->res.io_range.size;
+                        usb_log_debug2("Found io: %llx %zu.\n",
+                            res->res.io_range.address, res->res.io_range.size);
+                        io_found = true;
+
+                default:
+                        break;
                 }
         }
 
-        if (!io_found) {
-                rc = ENOENT;
-                goto leave;
-        }
-
-        if (!irq_found) {
+        if (!io_found || !irq_found) {
                 rc = ENOENT;
                 goto leave;
@@ -121 +117 @@
 }
 /*----------------------------------------------------------------------------*/
+/** 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)
 {
@@ -130 +131 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Calls the PCI driver with a request to clear legacy support register
+ *
+ * @param[in] device Device asking to disable interrupts
+ * @return Error code.
+ */
 int pci_disable_legacy(ddf_dev_t *device)
 {
         assert(device);
-        int parent_phone = devman_parent_device_connect(device->handle,
-                IPC_FLAG_BLOCKING);
+        int parent_phone =
+            devman_parent_device_connect(device->handle, IPC_FLAG_BLOCKING);
         if (parent_phone < 0) {
                 return parent_phone;
@@ -144 +150 @@
         sysarg_t value = 0x8f00;
 
-  int rc = async_req_3_0(parent_phone, DEV_IFACE_ID(PCI_DEV_IFACE),
+        int rc = async_req_3_0(parent_phone, DEV_IFACE_ID(PCI_DEV_IFACE),
             IPC_M_CONFIG_SPACE_WRITE_16, address, value);
         async_hangup(parent_phone);
 
-  return rc;
+        return rc;
 }
 /*----------------------------------------------------------------------------*/

uspace/drv/uhci-hcd/root_hub.c

@@ -45 +45 @@
 
 /*----------------------------------------------------------------------------*/
-static int usb_iface_get_hc_handle_rh_impl(ddf_fun_t *root_hub_fun,
-    devman_handle_t *handle)
+/** Gets handle of the respective hc (parent device).
+ *
+ * @param[in] root_hub_fun Root hub function seeking hc handle.
+ * @param[out] handle Place to write the handle.
+ * @return Error code.
+ */
+static int usb_iface_get_hc_handle_rh_impl(
+    ddf_fun_t *root_hub_fun, devman_handle_t *handle)
 {
+        /* TODO: Can't this use parent pointer? */
         ddf_fun_t *hc_fun = root_hub_fun->driver_data;
         assert(hc_fun != NULL);
@@ -56 +63 @@
 }
 /*----------------------------------------------------------------------------*/
-static int usb_iface_get_address_rh_impl(ddf_fun_t *fun, devman_handle_t handle,
-    usb_address_t *address)
+/** Gets USB address of the calling device.
+ *
+ * @param[in] fun Root hub function.
+ * @param[in] handle Handle of the device seeking address.
+ * @param[out] address Place to store found address.
+ * @return Error code.
+ */
+static int usb_iface_get_address_rh_impl(
+    ddf_fun_t *fun, devman_handle_t handle, usb_address_t *address)
 {
+        /* TODO: What does this do? Is it neccessary? Can't it use implemented
+         * hc function?*/
         assert(fun);
         ddf_fun_t *hc_fun = fun->driver_data;
@@ -65 +81 @@
         assert(hc);
 
-        usb_address_t addr = device_keeper_find(&hc->device_manager,
-            handle);
+        usb_address_t addr = device_keeper_find(&hc->device_manager, handle);
         if (addr < 0) {
                 return addr;
@@ -83 +98 @@
 };
 /*----------------------------------------------------------------------------*/
+/** Gets root hub hw resources.
+ *
+ * @param[in] fun Root hub function.
+ * @return Pointer to the resource list used by the root hub.
+ */
 static hw_resource_list_t *get_resource_list(ddf_fun_t *dev)
 {
@@ -91 +111 @@
         assert(hc);
 
-        //TODO: fix memory leak
+        /* TODO: fix memory leak */
         hw_resource_list_t *resource_list = malloc(sizeof(hw_resource_list_t));
         assert(resource_list);

uspace/drv/uhci-hcd/transfer_list.c

@@ -38 +38 @@
 #include "transfer_list.h"
 
+static void transfer_list_remove_batch(
+    transfer_list_t *instance, batch_t *batch);
+/*----------------------------------------------------------------------------*/
+/** Initializes transfer list structures.
+ *
+ * @param[in] instance Memory place to use.
+ * @param[in] name Name of te new list.
+ * @return Error code
+ *
+ * Allocates memory for internat queue_head_t structure.
+ */
 int transfer_list_init(transfer_list_t *instance, const char *name)
 {
@@ -43 +54 @@
         instance->next = NULL;
         instance->name = name;
-        instance->queue_head = queue_head_get();
+        instance->queue_head = malloc32(sizeof(queue_head_t));
         if (!instance->queue_head) {
                 usb_log_error("Failed to allocate queue head.\n");
                 return ENOMEM;
         }
-        instance->queue_head_pa = (uintptr_t)addr_to_phys(instance->queue_head);
+        instance->queue_head_pa = addr_to_phys(instance->queue_head);
 
         queue_head_init(instance->queue_head);
@@ -56 +67 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Set the next list in chain.
+ *
+ * @param[in] instance List to lead.
+ * @param[in] next List to append.
+ * @return Error code
+ */
 void transfer_list_set_next(transfer_list_t *instance, transfer_list_t *next)
 {
@@ -66 +83 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Submits a new transfer batch to list and queue.
+ *
+ * @param[in] instance List to use.
+ * @param[in] batch Transfer batch to submit.
+ * @return Error code
+ */
 void transfer_list_add_batch(transfer_list_t *instance, batch_t *batch)
 {
         assert(instance);
         assert(batch);
-        usb_log_debug2("Adding batch(%p) to queue %s.\n", batch, instance->name);
+        usb_log_debug2(
+            "Adding batch(%p) to queue %s.\n", batch, instance->name);
 
         uint32_t pa = (uintptr_t)addr_to_phys(batch->qh);
@@ -97 +121 @@
         queue_head_append_qh(last->qh, pa);
         list_append(&batch->link, &instance->batch_list);
+
         usb_log_debug("Batch(%p) added to queue %s last, first is %p.\n",
-                batch, instance->name, first );
+                batch, instance->name, first);
         fibril_mutex_unlock(&instance->guard);
 }
 /*----------------------------------------------------------------------------*/
-static void transfer_list_remove_batch(
-    transfer_list_t *instance, batch_t *batch)
+/** Removes a transfer batch from list and queue.
+ *
+ * @param[in] instance List to use.
+ * @param[in] batch Transfer batch to remove.
+ * @return Error code
+ */
+void transfer_list_remove_batch(transfer_list_t *instance, batch_t *batch)
 {
         assert(instance);
@@ -109 +139 @@
         assert(instance->queue_head);
         assert(batch->qh);
-        usb_log_debug2("Removing batch(%p) from queue %s.\n", batch, instance->name);
+        usb_log_debug2(
+            "Removing batch(%p) from queue %s.\n", batch, instance->name);
 
-        /* I'm the first one here */
         if (batch->link.prev == &instance->batch_list) {
-                usb_log_debug("Batch(%p) removed (FIRST) from queue %s, next element %x.\n",
-                        batch, instance->name, batch->qh->next_queue);
+                /* I'm the first one here */
+                usb_log_debug(
+                    "Batch(%p) removed (FIRST) from %s, next element %x.\n",
+                    batch, instance->name, batch->qh->next_queue);
                 instance->queue_head->element = batch->qh->next_queue;
         } else {
-                usb_log_debug("Batch(%p) removed (NOT FIRST) from queue, next element %x.\n",
-                        batch, instance->name, batch->qh->next_queue);
-                batch_t *prev = list_get_instance(batch->link.prev, batch_t, link);
+                usb_log_debug(
+                    "Batch(%p) removed (FIRST:NO) from %s, next element %x.\n",
+                    batch, instance->name, batch->qh->next_queue);
+                batch_t *prev =
+                    list_get_instance(batch->link.prev, batch_t, link);
                 prev->qh->next_queue = batch->qh->next_queue;
         }
@@ -125 +159 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Checks list for finished transfers.
+ *
+ * @param[in] instance List to use.
+ * @return Error code
+ */
 void transfer_list_remove_finished(transfer_list_t *instance)
 {

uspace/drv/uhci-hcd/transfer_list.h

@@ -58 +58 @@
 {
         assert(instance);
-        queue_head_dispose(instance->queue_head);
+        free32(instance->queue_head);
 }
 void transfer_list_remove_finished(transfer_list_t *instance);

uspace/drv/uhci-hcd/uhci.c

@@ -61 +61 @@
 };
 
-static int usb_iface_get_address(ddf_fun_t *fun, devman_handle_t handle,
-    usb_address_t *address)
+/** Gets USB address of the calling device.
+ *
+ * @param[in] fun UHCI hc function.
+ * @param[in] handle Handle of the device seeking address.
+ * @param[out] address Place to store found address.
+ * @return Error code.
+ */
+static int usb_iface_get_address(
+    ddf_fun_t *fun, devman_handle_t handle, usb_address_t *address)
 {
         assert(fun);
@@ -99 +106 @@
 
 static bool allowed_usb_packet(
-        bool low_speed, usb_transfer_type_t, size_t size);
-
-
+    bool low_speed, usb_transfer_type_t transfer, size_t size);
+/*----------------------------------------------------------------------------*/
+/** Initializes UHCI hcd driver structure
+ *
+ * @param[in] instance Memory place to initialize.
+ * @param[in] dev DDF device.
+ * @param[in] regs Address of I/O control registers.
+ * @param[in] size Size of I/O control registers.
+ * @return Error code.
+ * @note Should be called only once on any structure.
+ */
 int uhci_init(uhci_t *instance, ddf_dev_t *dev, void *regs, size_t reg_size)
 {
@@ -156 +171 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Initializes UHCI hcd hw resources.
+ *
+ * @param[in] instance UHCI structure to use.
+ */
 void uhci_init_hw(uhci_t *instance)
 {
         assert(instance);
-
-        /* reset everything, who knows what touched it before us */
-        pio_write_16(&instance->registers->usbcmd, UHCI_CMD_GLOBAL_RESET);
+        regs_t *registers = instance->registers;
+
+        /* Reset everything, who knows what touched it before us */
+        pio_write_16(&registers->usbcmd, UHCI_CMD_GLOBAL_RESET);
         async_usleep(10000); /* 10ms according to USB spec */
-        pio_write_16(&instance->registers->usbcmd, 0);
-
-        /* reset hc, all states and counters */
-        pio_write_16(&instance->registers->usbcmd, UHCI_CMD_HCRESET);
+        pio_write_16(&registers->usbcmd, 0);
+
+        /* Reset hc, all states and counters */
+        pio_write_16(&registers->usbcmd, UHCI_CMD_HCRESET);
         do { async_usleep(10); }
-        while ((pio_read_16(&instance->registers->usbcmd) & UHCI_CMD_HCRESET) != 0);
-
-        /* set framelist pointer */
+        while ((pio_read_16(&registers->usbcmd) & UHCI_CMD_HCRESET) != 0);
+
+        /* Set framelist pointer */
         const uint32_t pa = addr_to_phys(instance->frame_list);
-        pio_write_32(&instance->registers->flbaseadd, pa);
-
-        /* enable all interrupts, but resume interrupt */
+        pio_write_32(&registers->flbaseadd, pa);
+
+        /* Enable all interrupts, but resume interrupt */
 //      pio_write_16(&instance->registers->usbintr,
 //          UHCI_INTR_CRC | UHCI_INTR_COMPLETE | UHCI_INTR_SHORT_PACKET);
 
-        uint16_t status = pio_read_16(&instance->registers->usbcmd);
-        usb_log_warning("Previous command value: %x.\n", status);
+        uint16_t status = pio_read_16(&registers->usbcmd);
+        if (status != 0)
+                usb_log_warning("Previous command value: %x.\n", status);
+
         /* Start the hc with large(64B) packet FSBR */
-        pio_write_16(&instance->registers->usbcmd,
+        pio_write_16(&registers->usbcmd,
             UHCI_CMD_RUN_STOP | UHCI_CMD_MAX_PACKET | UHCI_CMD_CONFIGURE);
 }
 /*----------------------------------------------------------------------------*/
+/** Initializes UHCI hcd memory structures.
+ *
+ * @param[in] instance UHCI structure to use.
+ * @return Error code
+ * @note Should be called only once on any structure.
+ */
 int uhci_init_mem_structures(uhci_t *instance)
 {
@@ -196 +224 @@
         } else (void) 0
 
-        /* init interrupt code */
+        /* Init interrupt code */
         instance->interrupt_code.cmds = malloc(sizeof(uhci_cmds));
         int ret = (instance->interrupt_code.cmds == NULL) ? ENOMEM : EOK;
-        CHECK_RET_DEST_CMDS_RETURN(ret, "Failed to allocate interrupt cmds space.\n");
+        CHECK_RET_DEST_CMDS_RETURN(ret,
+            "Failed to allocate interrupt cmds space.\n");
 
         {
                 irq_cmd_t *interrupt_commands = instance->interrupt_code.cmds;
                 memcpy(interrupt_commands, uhci_cmds, sizeof(uhci_cmds));
-                interrupt_commands[0].addr = (void*)&instance->registers->usbsts;
-                interrupt_commands[1].addr = (void*)&instance->registers->usbsts;
+                interrupt_commands[0].addr =
+                    (void*)&instance->registers->usbsts;
+                interrupt_commands[1].addr =
+                    (void*)&instance->registers->usbsts;
                 instance->interrupt_code.cmdcount =
                     sizeof(uhci_cmds) / sizeof(irq_cmd_t);
         }
 
-        /* init transfer lists */
+        /* Init transfer lists */
         ret = uhci_init_transfer_lists(instance);
-        CHECK_RET_DEST_CMDS_RETURN(ret, "Failed to initialize transfer lists.\n");
+        CHECK_RET_DEST_CMDS_RETURN(ret, "Failed to init transfer lists.\n");
         usb_log_debug("Initialized transfer lists.\n");
 
-        /* frame list initialization */
+        /* Init USB frame list page*/
         instance->frame_list = get_page();
         ret = instance ? EOK : ENOMEM;
@@ -221 +252 @@
         usb_log_debug("Initialized frame list.\n");
 
-        /* initialize all frames to point to the first queue head */
+        /* Set all frames to point to the first queue head */
         const uint32_t queue =
           instance->transfers_interrupt.queue_head_pa
@@ -231 +262 @@
         }
 
-        /* init address keeper(libusb) */
+        /* Init device keeper*/
         device_keeper_init(&instance->device_manager);
         usb_log_debug("Initialized device manager.\n");
@@ -239 +270 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Initializes UHCI hcd transfer lists.
+ *
+ * @param[in] instance UHCI structure to use.
+ * @return Error code
+ * @note Should be called only once on any structure.
+ */
 int uhci_init_transfer_lists(uhci_t *instance)
 {
@@ -257 +294 @@
         CHECK_RET_CLEAR_RETURN(ret, "Failed to init BULK list.");
 
-        ret = transfer_list_init(&instance->transfers_control_full, "CONTROL_FULL");
+        ret = transfer_list_init(
+            &instance->transfers_control_full, "CONTROL_FULL");
         CHECK_RET_CLEAR_RETURN(ret, "Failed to init CONTROL FULL list.");
 
-        ret = transfer_list_init(&instance->transfers_control_slow, "CONTROL_SLOW");
+        ret = transfer_list_init(
+            &instance->transfers_control_slow, "CONTROL_SLOW");
         CHECK_RET_CLEAR_RETURN(ret, "Failed to init CONTROL SLOW list.");
 
@@ -279 +318 @@
 #endif
 
-        instance->transfers[0][USB_TRANSFER_INTERRUPT] =
+        /* Assign pointers to be used during scheduling */
+        instance->transfers[USB_SPEED_FULL][USB_TRANSFER_INTERRUPT] =
           &instance->transfers_interrupt;
-        instance->transfers[1][USB_TRANSFER_INTERRUPT] =
+        instance->transfers[USB_SPEED_LOW][USB_TRANSFER_INTERRUPT] =
           &instance->transfers_interrupt;
-        instance->transfers[0][USB_TRANSFER_CONTROL] =
+        instance->transfers[USB_SPEED_FULL][USB_TRANSFER_CONTROL] =
           &instance->transfers_control_full;
-        instance->transfers[1][USB_TRANSFER_CONTROL] =
+        instance->transfers[USB_SPEED_LOW][USB_TRANSFER_CONTROL] =
           &instance->transfers_control_slow;
-        instance->transfers[0][USB_TRANSFER_BULK] =
+        instance->transfers[USB_SPEED_FULL][USB_TRANSFER_BULK] =
           &instance->transfers_bulk_full;
 
@@ -294 +334 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Schedules batch for execution.
+ *
+ * @param[in] instance UHCI structure to use.
+ * @param[in] batch Transfer batch to schedule.
+ * @return Error code
+ */
 int uhci_schedule(uhci_t *instance, batch_t *batch)
 {
@@ -301 +347 @@
         if (!allowed_usb_packet(
             low_speed, batch->transfer_type, batch->max_packet_size)) {
-                usb_log_warning("Invalid USB packet specified %s SPEED %d %zu.\n",
+                usb_log_warning(
+                    "Invalid USB packet specified %s SPEED %d %zu.\n",
                     low_speed ? "LOW" : "FULL" , batch->transfer_type,
                     batch->max_packet_size);
@@ -316 +363 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Takes action based on the interrupt cause.
+ *
+ * @param[in] instance UHCI structure to use.
+ * @param[in] status Value of the stsatus regiser at the time of interrupt.
+ */
 void uhci_interrupt(uhci_t *instance, uint16_t status)
 {
         assert(instance);
+        /* TODO: Check interrupt cause here */
         transfer_list_remove_finished(&instance->transfers_interrupt);
         transfer_list_remove_finished(&instance->transfers_control_slow);
@@ -325 +378 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Polling function, emulates interrupts.
+ *
+ * @param[in] arg UHCI structure to use.
+ * @return EOK
+ */
 int uhci_interrupt_emulator(void* arg)
 {
@@ -343 +401 @@
 }
 /*---------------------------------------------------------------------------*/
+/** Debug function, checks consistency of memory structures.
+ *
+ * @param[in] arg UHCI structure to use.
+ * @return EOK
+ */
 int uhci_debug_checker(void *arg)
 {
@@ -401 +464 @@
                 async_usleep(UHCI_DEBUGER_TIMEOUT);
         }
-        return 0;
+        return EOK;
 #undef QH
 }
 /*----------------------------------------------------------------------------*/
+/** Checks transfer packets, for USB validity
+ *
+ * @param[in] low_speed Transfer speed.
+ * @param[in] transfer Transer type
+ * @param[in] size Maximum size of used packets
+ * @return EOK
+ */
 bool allowed_usb_packet(
     bool low_speed, usb_transfer_type_t transfer, size_t size)

uspace/drv/uhci-hcd/uhci.h

@@ -84 +84 @@
         device_keeper_t device_manager;
 
-        volatile regs_t *registers;
+        regs_t *registers;
 
         link_pointer_t *frame_list;

uspace/drv/uhci-hcd/uhci_struct/queue_head.h

@@ -71 +71 @@
 }
 
-static inline void queue_head_element_td(queue_head_t *instance, uint32_t pa)
+static inline void queue_head_set_element_td(queue_head_t *instance, uint32_t pa)
 {
         if (pa) {
@@ -78 +78 @@
 }
 
-static inline queue_head_t * queue_head_get() {
-        queue_head_t *ret = malloc32(sizeof(queue_head_t));
-        if (ret)
-                queue_head_init(ret);
-        return ret;
-}
-
-static inline void queue_head_dispose(queue_head_t *head)
-        { free32(head); }
-
-
 #endif
 /**

uspace/drv/uhci-hcd/uhci_struct/transfer_descriptor.c

@@ -38 +38 @@
 #include "utils/malloc32.h"
 
+/** Initializes Transfer Descriptor
+ *
+ * @param[in] instance Memory place to initialize.
+ * @param[in] err_count Number of retries hc should attempt.
+ * @param[in] size Size of data source.
+ * @param[in] toggle Value of toggle bit.
+ * @param[in] iso True if TD is for Isochronous transfer.
+ * @param[in] low_speed Target device's speed.
+ * @param[in] target Address and endpoint receiving the transfer.
+ * @param[in] pid Packet identification (SETUP, IN or OUT).
+ * @param[in] buffer Source of data.
+ * @param[in] next Net TD in transaction.
+ * @return Error code.
+ */
 void td_init(td_t *instance, int err_count, size_t size, bool toggle, bool iso,
-    bool low_speed, usb_target_t target, usb_packet_id pid, void *buffer, td_t *next)
+    bool low_speed, usb_target_t target, usb_packet_id pid, void *buffer,
+    td_t *next)
 {
         assert(instance);
         assert(size < 1024);
-        assert((pid == USB_PID_SETUP) || (pid == USB_PID_IN) || (pid == USB_PID_OUT));
+        assert((pid == USB_PID_SETUP) || (pid == USB_PID_IN)
+            || (pid == USB_PID_OUT));
 
         instance->next = 0
@@ -81 +97 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Converts TD status into standard error code
+ *
+ * @param[in] instance TD structure to use.
+ * @return Error code.
+ */
 int td_status(td_t *instance)
 {

uspace/drv/uhci-hcd/utils/device_keeper.c

@@ -39 +39 @@
 
 /*----------------------------------------------------------------------------*/
+/** Initializes device keeper structure.
+ *
+ * @param[in] instance Memory place to initialize.
+ */
 void device_keeper_init(device_keeper_t *instance)
 {
@@ -53 +57 @@
 }
 /*----------------------------------------------------------------------------*/
-void device_keeper_reserve_default(
-    device_keeper_t *instance, usb_speed_t speed)
+/** Attempts to obtain address 0, blocks.
+ *
+ * @param[in] instance Device keeper structure to use.
+ * @param[in] speed Speed of the device requesting default address.
+ */
+void device_keeper_reserve_default(device_keeper_t *instance, usb_speed_t speed)
 {
         assert(instance);
@@ -67 +75 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Attempts to obtain address 0, blocks.
+ *
+ * @param[in] instance Device keeper structure to use.
+ * @param[in] speed Speed of the device requesting default address.
+ */
 void device_keeper_release_default(device_keeper_t *instance)
 {
@@ -76 +89 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Checks setup data for signs of toggle reset.
+ *
+ * @param[in] instance Device keeper structure to use.
+ * @param[in] target Device to receive setup packet.
+ * @param[in] data Setup packet data.
+ */
 void device_keeper_reset_if_need(
     device_keeper_t *instance, usb_target_t target, const unsigned char *data)
@@ -84 +103 @@
             || target.address >= USB_ADDRESS_COUNT || target.address < 0
             || !instance->devices[target.address].occupied) {
-                goto the_end;
+                fibril_mutex_unlock(&instance->guard);
+                return;
         }
 
@@ -90 +110 @@
         {
         case 0x01: /*clear feature*/
-                /* recipient is enpoint, value is zero (ENDPOINT_STALL) */
+                /* recipient is endpoint, value is zero (ENDPOINT_STALL) */
                 if (((data[0] & 0xf) == 1) && ((data[2] | data[3]) == 0)) {
-                        /* enpoint number is < 16, thus first byte is enough */
-                        instance->devices[target.address].toggle_status &= ~(1 << data[4]);
+                        /* endpoint number is < 16, thus first byte is enough */
+                        instance->devices[target.address].toggle_status &=
+                            ~(1 << data[4]);
                 }
         break;
@@ -102 +123 @@
         break;
         }
-the_end:
-        fibril_mutex_unlock(&instance->guard);
-}
-/*----------------------------------------------------------------------------*/
+        fibril_mutex_unlock(&instance->guard);
+}
+/*----------------------------------------------------------------------------*/
+/** Gets current value of endpoint toggle.
+ *
+ * @param[in] instance Device keeper structure to use.
+ * @param[in] target Device and endpoint used.
+ * @return Error code
+ */
 int device_keeper_get_toggle(device_keeper_t *instance, usb_target_t target)
 {
@@ -116 +142 @@
                 ret = EINVAL;
         } else {
-                ret = (instance->devices[target.address].toggle_status >> target.endpoint) & 1;
+                ret =
+                    (instance->devices[target.address].toggle_status
+                        >> target.endpoint) & 1;
         }
         fibril_mutex_unlock(&instance->guard);
@@ -122 +150 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Sets current value of endpoint toggle.
+ *
+ * @param[in] instance Device keeper structure to use.
+ * @param[in] target Device and endpoint used.
+ * @param[in] toggle Current toggle value.
+ * @return Error code.
+ */
 int device_keeper_set_toggle(
     device_keeper_t *instance, usb_target_t target, bool toggle)
@@ -144 +179 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Gets a free USB address
+ *
+ * @param[in] instance Device keeper structure to use.
+ * @param[in] speed Speed of the device requiring address.
+ * @return Free address, or error code.
+ */
 usb_address_t device_keeper_request(
     device_keeper_t *instance, usb_speed_t speed)
@@ -171 +212 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Binds USB address to devman handle.
+ *
+ * @param[in] instance Device keeper structure to use.
+ * @param[in] address Device address
+ * @param[in] handle Devman handle of the device.
+ */
 void device_keeper_bind(
     device_keeper_t *instance, usb_address_t address, devman_handle_t handle)
@@ -183 +230 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Releases used USB address.
+ *
+ * @param[in] instance Device keeper structure to use.
+ * @param[in] address Device address
+ */
 void device_keeper_release(device_keeper_t *instance, usb_address_t address)
 {
@@ -195 +247 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Finds USB address associated with the device
+ *
+ * @param[in] instance Device keeper structure to use.
+ * @param[in] handle Devman handle of the device seeking its address.
+ * @return USB Address, or error code.
+ */
 usb_address_t device_keeper_find(
     device_keeper_t *instance, devman_handle_t handle)
@@ -212 +270 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Gets speed associated with the address
+ *
+ * @param[in] instance Device keeper structure to use.
+ * @param[in] address Address of the device.
+ * @return USB speed.
+ */
 usb_speed_t device_keeper_speed(
     device_keeper_t *instance, usb_address_t address)