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

Timestamp:

2018-01-08T17:17:38Z (6 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/endpoint.c (modified) (12 diffs)

uspace/lib/usbhost/src/endpoint.c

@@ -49 +49 @@
 #include "endpoint.h"
 
-/** Initialize provided endpoint structure.
+/**
+ * Initialize provided endpoint structure.
  */
 void endpoint_init(endpoint_t *ep, device_t *dev, const usb_endpoint_descriptors_t *desc)
@@ -78 +79 @@
 }
 
+/**
+ * Get the bus endpoint belongs to.
+ */
 static inline const bus_ops_t *get_bus_ops(endpoint_t *ep)
 {
@@ -83 +87 @@
 }
 
+/**
+ * Increase the reference count on endpoint.
+ */
 void endpoint_add_ref(endpoint_t *ep)
 {
@@ -88 +95 @@
 }
 
+/**
+ * Call the desctruction callback. Default behavior is to free the memory directly.
+ */
 static inline void endpoint_destroy(endpoint_t *ep)
 {
@@ -101 +111 @@
 }
 
+/**
+ * Decrease the reference count.
+ */
 void endpoint_del_ref(endpoint_t *ep)
 {
@@ -110 +123 @@
 static void endpoint_toggle_reset(endpoint_t *ep, toggle_reset_mode_t mode);
 
-/** Mark the endpoint as active and block access for further fibrils.
+/**
+ * Mark the endpoint as active and block access for further fibrils. If the
+ * endpoint is already active, it will block on ep->avail condvar.
+ *
+ * Call only under endpoint guard. After you activate the endpoint and release
+ * the guard, you must assume that particular transfer is already finished/aborted.
+ *
  * @param ep endpoint_t structure.
+ * @param batch Transfer batch this endpoint is bocked by.
  */
 void endpoint_activate_locked(endpoint_t *ep, usb_transfer_batch_t *batch)
@@ -125 +145 @@
 }
 
-/** Mark the endpoint as inactive and allow access for further fibrils.
+/**
+ * Mark the endpoint as inactive and allow access for further fibrils.
+ *
  * @param ep endpoint_t structure.
  */
@@ -140 +162 @@
 }
 
-/** Abort an active batch on endpoint, if any.
+/**
+ * Abort an active batch on endpoint, if any.
  *
  * @param[in] ep endpoint_t structure.
@@ -157 +180 @@
 }
 
+/**
+ * The transfer on an endpoint can trigger a reset of the toggle bit. This
+ * function calls the respective bus callbacks to resolve it.
+ *
+ * @param ep The endpoint that triggered the reset
+ * @param mode Whether to reset no, one or all endpoints on a device.
+ */
 static void endpoint_toggle_reset(endpoint_t *ep, toggle_reset_mode_t mode)
 {
@@ -168 +198 @@
                 return;
 
-        device_t *dev = ep->device;
 
         if (mode == RESET_ALL) {
+                const device_t *dev = ep->device;
                 for (usb_endpoint_t i = 0; i < USB_ENDPOINT_MAX; ++i) {
                         if (dev->endpoints[i])
@@ -180 +210 @@
 }
 
-ssize_t endpoint_count_bw(endpoint_t *ep, size_t packet_size)
+/**
+ * Call the bus operation to count bandwidth.
+ *
+ * @param ep Endpoint on which the transfer will take place.
+ * @param size The payload size.
+ */
+ssize_t endpoint_count_bw(endpoint_t *ep, size_t size)
 {
         assert(ep);
@@ -188 +224 @@
                 return 0;
 
-        return ops->endpoint_count_bw(ep, packet_size);
-}
-
-/** Prepare generic usb_transfer_batch and schedule it.
- * @param ep Endpoint for which the batch shall be created.
- * @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.
+        return ops->endpoint_count_bw(ep, size);
+}
+
+/**
+ * Initiate a transfer on an endpoint. Creates a transfer batch, checks the
+ * bandwidth requirements and schedules the batch.
+ *
+ * @param endpoint Endpoint 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 on_complete Callback which is called after the batch is complete
  * @param arg Callback parameter.
  * @param name Communication identifier (for nicer output).
- * @return Error code.
  */
 int endpoint_send_batch(endpoint_t *ep, usb_target_t target,