Changeset 1102eca in mainline for uspace/lib/usbhost/src/hcd.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/hcd.c (modified) (8 diffs)

uspace/lib/usbhost/src/hcd.c

@@ -32 +32 @@
 /** @file
  *
+ * Host controller driver framework. Encapsulates DDF device of HC to an
+ * hc_device_t, which is passed to driver implementing hc_driver_t.
  */
 
@@ -68 +70 @@
 static const hc_driver_t *hc_driver;
 
+/**
+ * The main HC driver routine.
+ */
 int hc_driver_main(const hc_driver_t *driver)
 {
@@ -81 +86 @@
 }
 
-/** IRQ handling callback, forward status from call to diver structure.
- *
- * @param[in] dev DDF instance of the device to use.
- * @param[in] iid (Unused).
- * @param[in] call Pointer to the call from kernel.
+/**
+ * IRQ handling callback. Call the bus operation.
+ *
+ * Currently, there is a bus ops lookup to find the interrupt handler. So far,
+ * the mechanism is too flexible, as it allows different instances of HC to
+ * have different IRQ handlers, disallowing us to optimize the lookup here.
+ * TODO: Make the bus mechanism less flexible in irq handling and remove the
+ * lookup.
  */
 static void irq_handler(ipc_callid_t iid, ipc_call_t *call, ddf_dev_t *dev)
@@ -99 +107 @@
 }
 
-/** Worker for the HW interrupt replacement fibril.
+/**
+ * Worker for the HW interrupt replacement fibril.
  */
 static int interrupt_polling(void *arg)
@@ -123 +132 @@
 }
 
+/**
+ * Clean the IRQ code bottom-half.
+ */
 static inline void irq_code_clean(irq_code_t *code)
 {
@@ -135 +147 @@
 }
 
-/** Register interrupt handler
- *
- * @param[in] device Host controller DDF device
- * @param[in] regs Register range
- * @param[in] irq Interrupt number
- * @paran[in] handler Interrupt handler
- * @param[in] gen_irq_code IRQ code generator.
+/**
+ * Register an interrupt handler. If there is a callback to setup the bottom half,
+ * invoke it and register it. Register for notifications.
+ *
+ * If this method fails, a polling fibril is started instead.
+ *
+ * @param[in] hcd Host controller device.
+ * @param[in] hw_res Resources to be used.
  *
  * @return IRQ capability handle on success.
@@ -181 +194 @@
 }
 
-/** Initialize HC in memory of the driver.
- *
- * @param device DDF instance of the device to use
- * @return Error code
+/**
+ * Initialize HC in memory of the driver.
  *
  * This function does all the preparatory work for hc and rh drivers:
@@ -192 +203 @@
  *  - calls driver specific initialization
  *  - registers root hub
+ *
+ * @param device DDF instance of the device to use
+ * @return Error code
  */
 int hc_dev_add(ddf_dev_t *device)