usb: document usb states, powering and detection

Change-Id: Ia3b7d6c6294bfb9272355c3f28a994dd0e83cbce
Reviewed-on: http://gerrit.rockbox.org/1096
Reviewed-by: Amaury Pouly <amaury.pouly@gmail.com>

1 files changed, 112 insertions, 16 deletions

diff --git a/firmware/export/usb.h b/firmware/export/usb.h
index f13ade2acd..62bcffe666 100644
--- a/firmware/export/usb.h
+++ b/firmware/export/usb.h
@@ -25,6 +25,80 @@
 #include "kernel.h"
 #include "button.h"
 
+/** USB introduction
+ * Targets which do not have any hardware support for USB, and cannot even detect
+ * it must define USB_NONE. Otherwise, they must at least implement USB
+ * detection.
+ *
+ * USB architecture
+ * The USB code is split into several parts:
+ * - usb: manages the USB connection
+ * - usb_core: implements a software USB stack based on usb_drv
+ * - usb_drv: implements the USB protocol based on some hardware transceiver/core
+ * - usb_{hid,storage,...}: implement USB functionalities based on usb_core
+ * Note that not all those are compiled in, in particular in the case of a
+ * hardware USB stack, or when the driver doesn't support all types of transfers.
+ *
+ * Software versus hardware USB stack
+ * A very important thing to keep in mind is that there are two very different
+ * situations:
+ * - software USB stack: the device only provides a USB transceiver and the
+ *   USB stack must be implemented entirely in software. In this case the target
+ *   must define HAVE_USBSTACK, correctly set CONFIG_USBOTG and implement a driver
+ *   for the transceiver.
+ * - hardware USB stack: the device has a dedicated chip which implements the
+ *   USB stack in hardware. In this case the target must *NOT* define HAVE_USBSTACK
+ *   but can still define CONFIG_USBOTG and implement a driver to enable/disable
+ *   the USB hardware.
+ *
+ * USB ignore buttons
+ * In some cases, the user wants to prevent Rockbox from entering USB mode. It
+ * can do so by holding a button while inserting the cable. By default any button
+ * will prevent the USB mode from kicking-in, so targets can optionally define
+ * USBPOWER_BTN_IGNORE to a mask of buttons to ignore in this check.
+ *
+ * USB states
+ * It is important to understand that the usb code can be in one of three states:
+ * - extracted: no USB cable is plugged
+ * - powered-only: a USB cable is plugged but the USB mode will not be entered,
+ *   either because no host was detected or because the user requested so.
+ * - inserted: a USB cable is plugged and the USB mode has been entered, either
+ *   the software or hardware stack is running.
+ *
+ * USB exclusive mode
+ * Either in hardware or software stack, if the USB was configured to run in
+ * mass storage mode, it will require exclusive access to the disk and ask all
+ * threads to release any file handle and stop using the disks. It does so by
+ * broadcasting a SYS_USB_CONNECTED message, which threads must acknowledge using
+ * usb_acknowledge(SYS_USB_CONNECTED_ACK). They must not access the disk until
+ * SYS_USB_DISCONNECTED is broadcast. To ease waiting, threads can call
+ * usb_wait_for_disconnect() or usb_wait_for_disconnect_w_tmo() on their waiting
+ * queue.
+ *
+ * USB detection
+ * Except when no usb code is compiled at all (USB_NONE), the usb thread keeps
+ * track of the USB insertion state, which can be either USB_INSERTED (meaning
+ * 5v is present) or USB_EXTRACTED. Each target must implement usb_detect()
+ * to report the insertion state.
+ * Targets which support insertion/extraction interrupts must define
+ * USB_STATUS_BY_EVENT and notify the thread on changes by calling
+ * usb_status_event() with the new state. Other targets must *not* define
+ * USB_STATUS_BY_EVENT and the usb thread by regularly poll the insertion state
+ * using usb_detect().
+ *
+ * USB powering & charging
+ * Device which can be powered from USB must define HAVE_USB_POWER. Note that
+ * powering doesn't imply charging (for example a AA-powered device can be
+ * powered from USB but not charged), charging sources are reported by the
+ * power subsystem (see power.h). The USB specification mandates the maximum
+ * current which can be drawn under which cirmcunstances. Device which cannot
+ * control the charge current should make sure it is always <100mA to meet the
+ * USB specification. Device with configurable charging current which support
+ * >=100mA must define HAVE_USB_CHARGING_ENABLE and implement
+ * usb_charging_maxcurrent_change() to let the usb thread control the maximum
+ * charging control.
+ * */
+
 #if defined(IPOD_COLOR) || defined(IPOD_4G) \
  || defined(IPOD_MINI)  || defined(IPOD_MINI2G)
 #define USB_FIREWIRE_HANDLING
@@ -38,7 +112,7 @@ enum
 #endif
     USB_EXTRACTED = 0,       /* Event+State */
     USB_INSERTED,            /* Event+State */
-    USB_POWERED,             /* State - transitional indicator if no power */
+    USB_POWERED,             /* State - transitional indicator if no host */
 #if (CONFIG_STORAGE & STORAGE_MMC)
     USB_REENABLE,            /* Event */
 #endif
@@ -100,16 +174,26 @@ struct usb_transfer_completion_event_data
 };
 #endif /* HAVE_USBSTACK */
 
+/* initialise the usb code and thread */
 void usb_init(void) INIT_ATTR;
+/* target must implement this to enable/disable the usb transceiver/core */
 void usb_enable(bool on);
 void usb_attach(void);
+/* enable usb detection monitoring; before this function is called, all usb
+ * detection changes are ignored */
 void usb_start_monitoring(void) INIT_ATTR;
 void usb_close(void);
+/* acknowledge usb connection, typically with SYS_USB_CONNECTED_ACK */
 void usb_acknowledge(long id);
+/* block the current thread until SYS_USB_DISCONNECTED has been broadcast */
 void usb_wait_for_disconnect(struct event_queue *q);
+/* same as usb_wait_for_disconnect() but with a timeout, returns 1 on timeout */
 int usb_wait_for_disconnect_w_tmo(struct event_queue *q, int ticks);
-bool usb_inserted(void); /* return the official value, what's been reported to the threads */
-int usb_detect(void); /* return the raw hardware value - nothing/pc/charger */
+/* check whether USB is plugged, note that this is the official value which has
+ * been reported to the thread */
+bool usb_inserted(void);
+/* check whether USB is plugged, note that this is the raw hardware value */
+int usb_detect(void);
 #ifdef USB_STATUS_BY_EVENT
 /* Notify USB insertion state (USB_INSERTED or USB_EXTRACTED) */
 void usb_status_event(int current_status);
@@ -118,33 +202,37 @@ void usb_status_event(int current_status);
 bool usb_powered(void);
 #ifdef HAVE_USB_CHARGING_ENABLE
 enum {
-    USB_CHARGING_DISABLE,
-    USB_CHARGING_ENABLE,
-    USB_CHARGING_FORCE
+    USB_CHARGING_DISABLE, /* the USB code will never ask for more than 100mA */
+    USB_CHARGING_ENABLE, /* the code will ask for the maximum possible value */
+    USB_CHARGING_FORCE /* the code will always ask for 500mA */
 };
-/* called by app, implemented by usb_core on targets with rockbox usb
- * or target-specific code on others
- */
+/* select the USB charging mode, typically used by apps/ to reflect user setting,
+ * implemented by usb_core on targets with a software stack, and by target code
+ * on targets with a hardware stack */
 void usb_charging_enable(int state);
 #ifdef HAVE_USBSTACK
+/* update the USB charging value based on the current USB state */
 void usb_charger_update(void);
 #endif /* HAVE_USBSTACK */
-/* hardware which knows how to control usb current should use one
- * of the following to find out from the usb stack how much is ok
- */
-/* implemented by target, called by usb when value changes */
+/* limit the maximum USB current the charger can draw */
 void usb_charging_maxcurrent_change(int maxcurrent);
-/* implemented by usb, called by target to get value */
+/* returns the maximum allowed USB current, based on USB charging mode and state */
 int usb_charging_maxcurrent(void);
 #endif /* HAVE_USB_CHARGING_ENABLE */
 #endif /* HAVE_USB_POWER */
 #ifdef HAVE_USBSTACK
+/* USB driver call this function to notify that a transfer has completed */
 void usb_signal_transfer_completion(
     struct usb_transfer_completion_event_data *event_data);
+/* notify the USB code that some important event has occurred which influences the
+ * USB state (like USB_NOTIFY_SET_ADDR). USB drivers should call usb_core_notify_*
+ * functions and not this function. */
 void usb_signal_notify(long id, intptr_t data);
+/* returns whether a USB_DRIVER_* is enabled (like HID, mass storage, ...) */
 bool usb_driver_enabled(int driver);
-bool usb_exclusive_storage(void); /* storage is available for usb */
-#endif
+/* returns whether exclusive storage is available for USB */
+bool usb_exclusive_storage(void);
+#endif /* HAVE_USBSTACK */
 int usb_release_exclusive_storage(void);
 
 #ifdef USB_FIREWIRE_HANDLING
@@ -153,14 +241,22 @@ void usb_firewire_connect_event(void);
 #endif
 
 #ifdef USB_ENABLE_HID
+/* enable or disable the HID driver */
 void usb_set_hid(bool enable);
 #endif
 
 #if defined(USB_ENABLE_STORAGE) && defined(HAVE_MULTIDRIVE)
+/* when the target has several drives, decide whether mass storage should
+ * skip the first drive. This is useful when the second drive is a SD card
+ * and the host only supports access to the first USB drive (this is very common
+ * in car tuners and USB speakers) */
 void usb_set_skip_first_drive(bool skip);
 #endif
 
 #if !defined(SIMULATOR) && !defined(USB_NONE)
+/* initialise the USB hardware, this is a one-time init and it should setup what
+ * is necessary to do proper USB detection, and it should call usb_drv_startup()
+ * to do the one-time initialisation of the USB driver */
 void usb_init_device(void);
 #endif