greybus: es1-ap-usb: document the lack of callback for the outgoing bulk urbs
We don't need a callback for bulk out urbs to do anything except put the
urb back in the pool. Document why we do this and what is involved.
Signed-off-by: Greg Kroah-Hartman <greg@kroah.com>
diff --git a/drivers/staging/greybus/es1-ap-usb.c b/drivers/staging/greybus/es1-ap-usb.c
index b8784b1..2fccece 100644
--- a/drivers/staging/greybus/es1-ap-usb.c
+++ b/drivers/staging/greybus/es1-ap-usb.c
@@ -418,6 +418,31 @@
/* If urb is not NULL, then we need to free this urb */
usb_free_urb(urb);
+
+ /*
+ * Yes, you are right, we aren't telling anyone that the urb finished.
+ * "That's crazy! How does this all even work?" you might be saying.
+ * The "magic" is the idea that greybus works on the "operation" level,
+ * not the "send a buffer" level. All operations are "round-trip" with
+ * a response from the device that the operation finished, or it will
+ * time out. Because of that, we don't care that this urb finished, or
+ * failed, or did anything else, as higher levels of the protocol stack
+ * will handle completions and timeouts and the rest.
+ *
+ * This protocol is "needed" due to some hardware restrictions on the
+ * current generation of Unipro controllers. Think about it for a
+ * minute, this is a USB driver, talking to a Unipro bridge, impediance
+ * mismatch is huge, yet the Unipro controller are even more
+ * underpowered than this little USB controller. We rely on the round
+ * trip to keep stalls in the Unipro controllers from happening so that
+ * we can keep data flowing properly, no matter how slow it might be.
+ *
+ * Once again, a wonderful bus protocol cut down in its prime by a naive
+ * controller chip. We dream of the day we have a "real" HCD for
+ * Unipro. Until then, we suck it up and make the hardware work, as
+ * that's the job of the firmware and kernel.
+ * </rant>
+ */
}
/*