add some documentation in usb.h and usb_drv.h

Change-Id: Icd39ee5c017fc219144b33ef96b0df85c5d430da

1 files changed, 36 insertions, 0 deletions

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);