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>
This commit is contained in:
parent
ae37d1944f
commit
1ab91550e6
|
@ -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
|
||||
|
||||
|
|
Loading…
Reference in New Issue