Changeset a7e2f0d in mainline

Timestamp:

2011-03-07T18:57:00Z (14 years ago)

Author:

Jan Vesely <jano.vesely@…>

Branches:

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

Children:

18e9eeb

Parents:

0d3167e

Message:

Doxygen and other comments

Location:

uspace/drv/uhci-hcd

Files:

• batch.c (modified) (16 diffs)
• iface.c (modified) (11 diffs)
• main.c (modified) (5 diffs)
• pci.c (modified) (3 diffs)
• root_hub.c (modified) (5 diffs)
• transfer_list.c (modified) (7 diffs)
• uhci.c (modified) (15 diffs)
• uhci.h (modified) (1 diff)
• 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,
@@ -139 +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)
 {
@@ -172 +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;
@@ -183 +210 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Prepares control read transaction.
+ *
+ * @param[in] instance Batch structure to use.
+ */
 void batch_control_read(batch_t *instance)
 {
@@ -192 +223 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Prepares interrupt in transaction.
+ *
+ * @param[in] instance Batch structure to use.
+ */
 void batch_interrupt_in(batch_t *instance)
 {
@@ -201 +236 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Prepares interrupt out transaction.
+ *
+ * @param[in] instance Batch structure to use.
+ */
 void batch_interrupt_out(batch_t *instance)
 {
@@ -212 +251 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Prepares bulk in transaction.
+ *
+ * @param[in] instance Batch structure to use.
+ */
 void batch_bulk_in(batch_t *instance)
 {
@@ -221 +264 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Prepares bulk out transaction.
+ *
+ * @param[in] instance Batch structure to use.
+ */
 void batch_bulk_out(batch_t *instance)
 {
@@ -231 +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)
 {
@@ -269 +321 @@
 }
 /*----------------------------------------------------------------------------*/
+/** 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)
@@ -317 +375 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Prepares data, gets error status and calls callback in.
+ *
+ * @param[in] instance Batch structure to use.
+ */
 void batch_call_in(batch_t *instance)
 {
@@ -323 +385 @@
 
         /* we are data in, we need data */
-        memcpy(instance->buffer, instance->transport_buffer, instance->buffer_size);
+        memcpy(instance->buffer, instance->transport_buffer,
+            instance->buffer_size);
 
         int err = instance->error;
@@ -334 +397 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Gets error status and calls callback out.
+ *
+ * @param[in] instance Batch structure to use.
+ */
 void batch_call_out(batch_t *instance)
 {
@@ -346 +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)
 {
@@ -353 +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)
 {
@@ -360 +435 @@
 }
 /*----------------------------------------------------------------------------*/
+/** Correctly disposes all used data structures.
+ *
+ * @param[in] instance Batch structure to use.
+ */
 void batch_dispose(batch_t *instance)
 {

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);
@@ -118 +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)
 {
@@ -127 +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)
 {

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)
 {
@@ -48 +59 @@
                 return ENOMEM;
         }
-        queue_head_init(instance->queue_head);
         instance->queue_head_pa = addr_to_phys(instance->queue_head);
 
@@ -57 +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)
 {
@@ -67 +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);
@@ -98 +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);
@@ -110 +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;
         }
@@ -126 +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/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/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)