Changeset 1102eca in mainline for uspace/lib/usbhost/src/bus.c

Timestamp:

2018-01-08T17:17:38Z (8 years ago)

Author:

Ondřej Hlavatý <aearsis@…>

Branches:

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

Children:

bdd8842c

Parents:

eb928c4

Message:

usbhost: documentation & cleanup

File:

• uspace/lib/usbhost/src/bus.c (modified) (18 diffs)

uspace/lib/usbhost/src/bus.c

@@ -32 +32 @@
 /** @file
  *
+ * The Bus is a structure that serves as an interface of the HC driver
+ * implementation for the usbhost library. Every HC driver that uses libusbhost
+ * must use a bus_t (or its child), fill it with bus_ops and present it to the
+ * library. The library then handles the DDF interface and translates it to the
+ * bus callbacks.
  */
 
@@ -44 +49 @@
 
 /**
- * Initializes the bus structure.
+ * Initializes the base bus structure.
  */
 void bus_init(bus_t *bus, size_t device_size)
@@ -57 +62 @@
 }
 
+/**
+ * Initialize the device_t structure belonging to a bus.
+ */
 int bus_device_init(device_t *dev, bus_t *bus)
 {
@@ -72 +80 @@
 }
 
+/**
+ * Create a name of the ddf function node.
+ */
 int bus_device_set_default_name(device_t *dev)
 {
@@ -84 +95 @@
 }
 
+/**
+ * Invoke the device_enumerate bus operation.
+ */
 int bus_device_enumerate(device_t *dev)
 {
@@ -95 +109 @@
 }
 
+/**
+ * Invoke the device_remove bus operation.
+ */
 int bus_device_remove(device_t *dev)
 {
@@ -106 +123 @@
 }
 
+/**
+ * Invoke the device_online bus operation.
+ */
 int bus_device_online(device_t *dev)
 {
@@ -117 +137 @@
 }
 
+/**
+ * Invoke the device_offline bus operation.
+ */
 int bus_device_offline(device_t *dev)
 {
@@ -128 +151 @@
 }
 
+/**
+ * Create and register new endpoint to the bus.
+ *
+ * @param[in] device The device of which the endpoint shall be created
+ * @param[in] desc Endpoint descriptors as reported by the device
+ * @param[out] out_ep The resulting new endpoint reference, if any. Can be NULL.
+ */
 int bus_endpoint_add(device_t *device, const usb_endpoint_descriptors_t *desc, endpoint_t **out_ep)
 {
@@ -135 +165 @@
         bus_t *bus = device->bus;
 
+        const bus_ops_t *register_ops = BUS_OPS_LOOKUP(bus->ops, endpoint_register);
+        if (!register_ops)
+                return ENOTSUP;
+
         const bus_ops_t *create_ops = BUS_OPS_LOOKUP(bus->ops, endpoint_create);
-        const bus_ops_t *register_ops = BUS_OPS_LOOKUP(bus->ops, endpoint_register);
-        if (!create_ops || !register_ops)
-                return ENOTSUP;
-
-        endpoint_t *ep = create_ops->endpoint_create(device, desc);
-        if (!ep)
-                return ENOMEM;
+        endpoint_t *ep;
+        if (create_ops) {
+                ep = create_ops->endpoint_create(device, desc);
+                if (!ep)
+                        return ENOMEM;
+        } else {
+                ep = calloc(1, sizeof(endpoint_t));
+                if (!ep)
+                        return ENOMEM;
+                endpoint_init(ep, device, desc);
+        }
 
         /* Bus reference */
@@ -186 +224 @@
 }
 
-/** Searches for an endpoint. Returns a reference.
+/**
+ * Search for an endpoint. Returns a reference.
  */
 endpoint_t *bus_find_endpoint(device_t *device, usb_endpoint_t endpoint)
@@ -204 +243 @@
 }
 
+/**
+ * Remove an endpoint from the device. Consumes a reference.
+ */
 int bus_endpoint_remove(endpoint_t *ep)
 {
@@ -233 +275 @@
         endpoint_del_ref(ep);
 
+        /* Given reference */
+        endpoint_del_ref(ep);
+
         return EOK;
 }
 
+/**
+ * Reserve the default address on the bus. Also, report the speed of the device
+ * that is listening on the default address.
+ *
+ * The speed is then used for devices enumerated while the address is reserved.
+ */
 int bus_reserve_default_address(bus_t *bus, usb_speed_t speed)
 {
@@ -251 +302 @@
 }
 
+/**
+ * Release the default address.
+ */
 void bus_release_default_address(bus_t *bus)
 {
@@ -257 +311 @@
 }
 
-/** Prepare generic usb_transfer_batch and schedule it.
+/**
+ * Initiate a transfer on the bus. Finds the target endpoint, creates
+ * a transfer batch and schedules it.
+ *
  * @param device Device for which to send the batch
- * @param target address and endpoint number.
- * @param setup_data Data to use in setup stage (Control communication type)
- * @param in Callback for device to host communication.
- * @param out Callback for host to device communication.
+ * @param target The target of the transfer.
+ * @param direction A direction of the transfer.
+ * @param data A pointer to the data buffer.
+ * @param size Size of the data buffer.
+ * @param setup_data Data to use in the setup stage (Control communication type)
+ * @param on_complete Callback which is called after the batch is complete
  * @param arg Callback parameter.
  * @param name Communication identifier (for nicer output).
@@ -301 +360 @@
 } sync_data_t;
 
+/**
+ * Callback for finishing the transfer. Wake the issuing thread.
+ */
 static int sync_transfer_complete(void *arg, int error, size_t transfered_size)
 {
@@ -314 +376 @@
 }
 
+/**
+ * Issue a transfer on the bus, wait for result.
+ *
+ * @param device Device for which to send the batch
+ * @param target The target of the transfer.
+ * @param direction A direction of the transfer.
+ * @param data A pointer to the data buffer.
+ * @param size Size of the data buffer.
+ * @param setup_data Data to use in the setup stage (Control communication type)
+ * @param name Communication identifier (for nicer output).
+ */
 ssize_t bus_device_send_batch_sync(device_t *device, usb_target_t target,
     usb_direction_t direction, char *data, size_t size, uint64_t setup_data,
@@ -330 +403 @@
         fibril_mutex_lock(&sd.done_mtx);
         while (!sd.done) {
-                fibril_condvar_wait_timeout(&sd.done_cv, &sd.done_mtx, 3000000);
-                if (!sd.done)
-                        usb_log_debug2("Still waiting...");
+                fibril_condvar_wait(&sd.done_cv, &sd.done_mtx);
         }
         fibril_mutex_unlock(&sd.done_mtx);