add some documentation in usb.h and usb_drv.h

Change-Id: Icd39ee5c017fc219144b33ef96b0df85c5d430da

2 files changed, 39 insertions, 0 deletions

diff --git a/firmware/export/usb.h b/firmware/export/usb.h
index ff85cb99ce..0c74efc9e2 100644
--- a/firmware/export/usb.h
+++ b/firmware/export/usb.h
@@ -178,6 +178,9 @@ struct usb_transfer_completion_event_data
 void usb_init(void) INIT_ATTR;
 /* target must implement this to enable/disable the usb transceiver/core */
 void usb_enable(bool on);
+/* when one or more driver requires exclusive mode, this is called after all threads have acknowledged
+ * exclusive mode and disk have been umounted; otherwise it is called immediately after host has
+ * been detected */
 void usb_attach(void);
 /* enable usb detection monitoring; before this function is called, all usb
  * detection changes are ignored */
diff --git a/firmware/export/usb_drv.h b/firmware/export/usb_drv.h
index 6ec9ac07e5..b5b5a7f065 100644
--- a/firmware/export/usb_drv.h
+++ b/firmware/export/usb_drv.h
@@ -23,9 +23,45 @@
 #include "usb_ch9.h"
 #include "kernel.h"
 
+/** USB initialisation flow:
+ * usb_init()
+ *    -> usb_init_device()
+ *       -> [soc specific one-time init]
+ *       -> usb_drv_startup()
+ * .....
+ * [USB is plugged]
+ * usb_enable(true)
+ *    -> soc specific controller/clock init
+ *    -> usb_core_init()
+ *       -> usb_drv_init()
+ *          -> usb_drv_int_enable(true)  [only if controller needs soc specific code for interrupt]
+ *       -> for each usb driver, driver.init()
+ * #ifdef USB_DETECT_BY_REQUEST
+ *   [rockbox waits until first control request before proceeding]
+ * #endif
+ * [rockbox decides which usb drivers to enable, based on user preference and buttons]
+ * -> if not exclusive mode, usb_attach()
+ * -> if exclusive mode, usb_attach() call be called at any point starting from now
+ *    (but after threads have acked usb mode and disk have been unmounted)
+ * for each enabled driver
+ *    -> driver.request_endpoints()
+ *    -> driver.set_first_interface()
+ * [usb controller/core start answering requests]
+ * .....
+ * [USB is unplugged]
+ * usb_enable(false)
+ *    -> usb_core_exit()
+ *       -> for each enabled usb driver, driver.disconnect()
+ *       -> usb_drv_exit()
+ *          -> usb_drv_int_enable(false)  [ditto]
+ *    -> soc specific controller/clock deinit */
+
+/* one-time initialisation of the USB driver */
 void usb_drv_startup(void);
 void usb_drv_int_enable(bool enable); /* Target implemented */
+/* enable and initialise the USB controller */
 void usb_drv_init(void);
+/* stop and disable and the USB controller */
 void usb_drv_exit(void);
 void usb_drv_int(void); /* Call from target INT handler */
 void usb_drv_stall(int endpoint, bool stall,bool in);