summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@linux-foundation.org>2013-07-02 11:31:09 -0700
committerLinus Torvalds <torvalds@linux-foundation.org>2013-07-02 11:31:09 -0700
commita84270189e2afc7028b1123415a66d444f460977 (patch)
tree0f239afe73655167c02b411d1cf84bf3211818af /Documentation
parentbcd7351e83728859833e3c5b8aae9a2816914e4b (diff)
parent3a0ddc714a1b8fcbff24c135a1332a28b4668d78 (diff)
Merge tag 'usb-3.11-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/usb
Pull USB updates from Greg KH: "Here's the big USB 3.11-rc1 merge request. Lots of gadget and finally, chipidea driver updates (they were much needed), along with a new host controller driver, lots of little serial driver fixes, the removal of the 255 usb-serial device limitation, and a variety of other minor things. All of these have been in the linux-next releases for a while" * tag 'usb-3.11-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/usb: (254 commits) usb: musb: omap2430: make it compile again usb: chipidea: ci_hdrc_imx: access phy via private data xhci: Add missing unlocks on error paths USB: option,qcserial: move Novatel Gobi1K IDs to qcserial ehci-atmel.c: prepare clk before calling enable USB: ohci-at91: prepare clk before calling enable USB: HWA: fix device probe failure wusbcore: add entries in Documentation/ABI for new wusbhc sysfs attributes wusbcore: add sysfs attribute for retry count wusbcore: add sysfs attribute for DNTS count and interval usb: chipidea: drop "13xxx" infix usb: phy: tegra: remove duplicated include from phy-tegra-usb.c usb: host: xhci-plat: release mem region while removing module usbmisc_imx: allow autoloading on according to dt ids usb: fix build error without CONFIG_USB_PHY usb: check usb_hub_to_struct_hub() return value xhci: check for failed dma pool allocation usb: gadget: f_subset: fix missing unlock on error in geth_alloc() usb: gadget: f_ncm: fix missing unlock on error in ncm_alloc() usb: gadget: f_ecm: fix missing unlock on error in ecm_alloc() ...
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/ABI/testing/configfs-usb-gadget81
-rw-r--r--Documentation/ABI/testing/configfs-usb-gadget-acm8
-rw-r--r--Documentation/ABI/testing/configfs-usb-gadget-ecm16
-rw-r--r--Documentation/ABI/testing/configfs-usb-gadget-eem14
-rw-r--r--Documentation/ABI/testing/configfs-usb-gadget-ncm15
-rw-r--r--Documentation/ABI/testing/configfs-usb-gadget-obex9
-rw-r--r--Documentation/ABI/testing/configfs-usb-gadget-phonet8
-rw-r--r--Documentation/ABI/testing/configfs-usb-gadget-rndis14
-rw-r--r--Documentation/ABI/testing/configfs-usb-gadget-serial9
-rw-r--r--Documentation/ABI/testing/configfs-usb-gadget-subset14
-rw-r--r--Documentation/ABI/testing/sysfs-bus-usb27
-rw-r--r--Documentation/ABI/testing/sysfs-class-uwb_rc-wusbhc19
-rw-r--r--Documentation/devicetree/bindings/usb/ci13xxx-imx.txt6
-rw-r--r--Documentation/devicetree/bindings/usb/nvidia,tegra20-ehci.txt27
-rw-r--r--Documentation/devicetree/bindings/usb/nvidia,tegra20-usb-phy.txt41
-rw-r--r--Documentation/devicetree/bindings/usb/usb3503.txt5
-rw-r--r--Documentation/usb/gadget_configfs.txt384
17 files changed, 672 insertions, 25 deletions
diff --git a/Documentation/ABI/testing/configfs-usb-gadget b/Documentation/ABI/testing/configfs-usb-gadget
new file mode 100644
index 000000000000..01e769d6984d
--- /dev/null
+++ b/Documentation/ABI/testing/configfs-usb-gadget
@@ -0,0 +1,81 @@
+What: /config/usb-gadget
+Date: Jun 2013
+KenelVersion: 3.11
+Description:
+ This group contains sub-groups corresponding to created
+ USB gadgets.
+
+What: /config/usb-gadget/gadget
+Date: Jun 2013
+KenelVersion: 3.11
+Description:
+
+ The attributes of a gadget:
+
+ UDC - bind a gadget to UDC/unbind a gadget;
+ write UDC's name found in /sys/class/udc/*
+ to bind a gadget, empty string "" to unbind.
+
+ bDeviceClass - USB device class code
+ bDeviceSubClass - USB device subclass code
+ bDeviceProtocol - USB device protocol code
+ bMaxPacketSize0 - maximum endpoint 0 packet size
+ bcdDevice - bcd device release number
+ bcdUSB - bcd USB specification version number
+ idProduct - product ID
+ idVendor - vendor ID
+
+What: /config/usb-gadget/gadget/configs
+Date: Jun 2013
+KenelVersion: 3.11
+Description:
+ This group contains a USB gadget's configurations
+
+What: /config/usb-gadget/gadget/configs/config
+Date: Jun 2013
+KernelVersion: 3.11
+Description:
+ The attributes of a configuration:
+
+ bmAttributes - configuration characteristics
+ MaxPower - maximum power consumption from the bus
+
+What: /config/usb-gadget/gadget/configs/config/strings
+Date: Jun 2013
+KernelVersion: 3.11
+Description:
+ This group contains subdirectories for language-specific
+ strings for this configuration.
+
+What: /config/usb-gadget/gadget/configs/config/strings/language
+Date: Jun 2013
+KernelVersion: 3.11
+Description:
+ The attributes:
+
+ configuration - configuration description
+
+
+What: /config/usb-gadget/gadget/functions
+Date: Jun 2013
+KenelVersion: 3.11
+Description:
+ This group contains functions available to this USB gadget.
+
+What: /config/usb-gadget/gadget/strings
+Date: Jun 2013
+KenelVersion: 3.11
+Description:
+ This group contains subdirectories for language-specific
+ strings for this gadget.
+
+What: /config/usb-gadget/gadget/strings/language
+Date: Jun 2013
+KenelVersion: 3.11
+Description:
+ The attributes:
+
+ serialnumber - gadget's serial number (string)
+ product - gadget's product description
+ manufacturer - gadget's manufacturer description
+
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-acm b/Documentation/ABI/testing/configfs-usb-gadget-acm
new file mode 100644
index 000000000000..5708a568b5f6
--- /dev/null
+++ b/Documentation/ABI/testing/configfs-usb-gadget-acm
@@ -0,0 +1,8 @@
+What: /config/usb-gadget/gadget/functions/acm.name
+Date: Jun 2013
+KenelVersion: 3.11
+Description:
+
+ This item contains just one readonly attribute: port_num.
+ It contains the port number of the /dev/ttyGS<n> device
+ associated with acm function's instance "name".
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-ecm b/Documentation/ABI/testing/configfs-usb-gadget-ecm
new file mode 100644
index 000000000000..6b9a582ce0b5
--- /dev/null
+++ b/Documentation/ABI/testing/configfs-usb-gadget-ecm
@@ -0,0 +1,16 @@
+What: /config/usb-gadget/gadget/functions/ecm.name
+Date: Jun 2013
+KenelVersion: 3.11
+Description:
+ The attributes:
+
+ ifname - network device interface name associated with
+ this function instance
+ qmult - queue length multiplier for high and
+ super speed
+ host_addr - MAC address of host's end of this
+ Ethernet over USB link
+ dev_addr - MAC address of device's end of this
+ Ethernet over USB link
+
+
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-eem b/Documentation/ABI/testing/configfs-usb-gadget-eem
new file mode 100644
index 000000000000..dbddf36b48b3
--- /dev/null
+++ b/Documentation/ABI/testing/configfs-usb-gadget-eem
@@ -0,0 +1,14 @@
+What: /config/usb-gadget/gadget/functions/eem.name
+Date: Jun 2013
+KenelVersion: 3.11
+Description:
+ The attributes:
+
+ ifname - network device interface name associated with
+ this function instance
+ qmult - queue length multiplier for high and
+ super speed
+ host_addr - MAC address of host's end of this
+ Ethernet over USB link
+ dev_addr - MAC address of device's end of this
+ Ethernet over USB link
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-ncm b/Documentation/ABI/testing/configfs-usb-gadget-ncm
new file mode 100644
index 000000000000..bc309f42357d
--- /dev/null
+++ b/Documentation/ABI/testing/configfs-usb-gadget-ncm
@@ -0,0 +1,15 @@
+What: /config/usb-gadget/gadget/functions/ncm.name
+Date: Jun 2013
+KenelVersion: 3.11
+Description:
+ The attributes:
+
+ ifname - network device interface name associated with
+ this function instance
+ qmult - queue length multiplier for high and
+ super speed
+ host_addr - MAC address of host's end of this
+ Ethernet over USB link
+ dev_addr - MAC address of device's end of this
+ Ethernet over USB link
+
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-obex b/Documentation/ABI/testing/configfs-usb-gadget-obex
new file mode 100644
index 000000000000..aaa5c96fb7c6
--- /dev/null
+++ b/Documentation/ABI/testing/configfs-usb-gadget-obex
@@ -0,0 +1,9 @@
+What: /config/usb-gadget/gadget/functions/obex.name
+Date: Jun 2013
+KenelVersion: 3.11
+Description:
+
+ This item contains just one readonly attribute: port_num.
+ It contains the port number of the /dev/ttyGS<n> device
+ associated with obex function's instance "name".
+
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-phonet b/Documentation/ABI/testing/configfs-usb-gadget-phonet
new file mode 100644
index 000000000000..3e3b742cdfd7
--- /dev/null
+++ b/Documentation/ABI/testing/configfs-usb-gadget-phonet
@@ -0,0 +1,8 @@
+What: /config/usb-gadget/gadget/functions/phonet.name
+Date: Jun 2013
+KenelVersion: 3.11
+Description:
+
+ This item contains just one readonly attribute: ifname.
+ It contains the network interface name assigned during
+ network device registration.
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-rndis b/Documentation/ABI/testing/configfs-usb-gadget-rndis
new file mode 100644
index 000000000000..822e6dad8fc0
--- /dev/null
+++ b/Documentation/ABI/testing/configfs-usb-gadget-rndis
@@ -0,0 +1,14 @@
+What: /config/usb-gadget/gadget/functions/rndis.name
+Date: Jun 2013
+KenelVersion: 3.11
+Description:
+ The attributes:
+
+ ifname - network device interface name associated with
+ this function instance
+ qmult - queue length multiplier for high and
+ super speed
+ host_addr - MAC address of host's end of this
+ Ethernet over USB link
+ dev_addr - MAC address of device's end of this
+ Ethernet over USB link
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-serial b/Documentation/ABI/testing/configfs-usb-gadget-serial
new file mode 100644
index 000000000000..16f130c1501f
--- /dev/null
+++ b/Documentation/ABI/testing/configfs-usb-gadget-serial
@@ -0,0 +1,9 @@
+What: /config/usb-gadget/gadget/functions/gser.name
+Date: Jun 2013
+KenelVersion: 3.11
+Description:
+
+ This item contains just one readonly attribute: port_num.
+ It contains the port number of the /dev/ttyGS<n> device
+ associated with gser function's instance "name".
+
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-subset b/Documentation/ABI/testing/configfs-usb-gadget-subset
new file mode 100644
index 000000000000..154ae597cd99
--- /dev/null
+++ b/Documentation/ABI/testing/configfs-usb-gadget-subset
@@ -0,0 +1,14 @@
+What: /config/usb-gadget/gadget/functions/geth.name
+Date: Jun 2013
+KenelVersion: 3.11
+Description:
+ The attributes:
+
+ ifname - network device interface name associated with
+ this function instance
+ qmult - queue length multiplier for high and
+ super speed
+ host_addr - MAC address of host's end of this
+ Ethernet over USB link
+ dev_addr - MAC address of device's end of this
+ Ethernet over USB link
diff --git a/Documentation/ABI/testing/sysfs-bus-usb b/Documentation/ABI/testing/sysfs-bus-usb
index f093e59cbe5f..9759b8c91332 100644
--- a/Documentation/ABI/testing/sysfs-bus-usb
+++ b/Documentation/ABI/testing/sysfs-bus-usb
@@ -236,3 +236,30 @@ Description:
This attribute is to expose these information to user space.
The file will read "hotplug", "wired" and "not used" if the
information is available, and "unknown" otherwise.
+
+What: /sys/bus/usb/devices/.../power/usb2_lpm_l1_timeout
+Date: May 2013
+Contact: Mathias Nyman <mathias.nyman@linux.intel.com>
+Description:
+ USB 2.0 devices may support hardware link power management (LPM)
+ L1 sleep state. The usb2_lpm_l1_timeout attribute allows
+ tuning the timeout for L1 inactivity timer (LPM timer), e.g.
+ needed inactivity time before host requests the device to go to L1 sleep.
+ Useful for power management tuning.
+ Supported values are 0 - 65535 microseconds.
+
+What: /sys/bus/usb/devices/.../power/usb2_lpm_besl
+Date: May 2013
+Contact: Mathias Nyman <mathias.nyman@linux.intel.com>
+Description:
+ USB 2.0 devices that support hardware link power management (LPM)
+ L1 sleep state now use a best effort service latency value (BESL) to
+ indicate the best effort to resumption of service to the device after the
+ initiation of the resume event.
+ If the device does not have a preferred besl value then the host can select
+ one instead. This usb2_lpm_besl attribute allows to tune the host selected besl
+ value in order to tune power saving and service latency.
+
+ Supported values are 0 - 15.
+ More information on how besl values map to microseconds can be found in
+ USB 2.0 ECN Errata for Link Power Management, section 4.10)
diff --git a/Documentation/ABI/testing/sysfs-class-uwb_rc-wusbhc b/Documentation/ABI/testing/sysfs-class-uwb_rc-wusbhc
index 25b1e751b777..5977e2875325 100644
--- a/Documentation/ABI/testing/sysfs-class-uwb_rc-wusbhc
+++ b/Documentation/ABI/testing/sysfs-class-uwb_rc-wusbhc
@@ -36,3 +36,22 @@ Description:
Refer to [ECMA-368] section 10.3.1.1 for the value to
use.
+
+What: /sys/class/uwb_rc/uwbN/wusbhc/wusb_dnts
+Date: June 2013
+KernelVersion: 3.11
+Contact: Thomas Pugliese <thomas.pugliese@gmail.com>
+Description:
+ The device notification time slot (DNTS) count and inverval in
+ milliseconds that the WUSB host should use. This controls how
+ often the devices will have the opportunity to send
+ notifications to the host.
+
+What: /sys/class/uwb_rc/uwbN/wusbhc/wusb_retry_count
+Date: June 2013
+KernelVersion: 3.11
+Contact: Thomas Pugliese <thomas.pugliese@gmail.com>
+Description:
+ The number of retries that the WUSB host should attempt
+ before reporting an error for a bus transaction. The range of
+ valid values is [0..15], where 0 indicates infinite retries.
diff --git a/Documentation/devicetree/bindings/usb/ci13xxx-imx.txt b/Documentation/devicetree/bindings/usb/ci13xxx-imx.txt
index 1c04a4c9515f..b4b5b7906c88 100644
--- a/Documentation/devicetree/bindings/usb/ci13xxx-imx.txt
+++ b/Documentation/devicetree/bindings/usb/ci13xxx-imx.txt
@@ -5,6 +5,12 @@ Required properties:
- reg: Should contain registers location and length
- interrupts: Should contain controller interrupt
+Recommended properies:
+- phy_type: the type of the phy connected to the core. Should be one
+ of "utmi", "utmi_wide", "ulpi", "serial" or "hsic". Without this
+ property the PORTSC register won't be touched
+- dr_mode: One of "host", "peripheral" or "otg". Defaults to "otg"
+
Optional properties:
- fsl,usbphy: phandler of usb phy that connects to the only one port
- fsl,usbmisc: phandler of non-core register device, with one argument
diff --git a/Documentation/devicetree/bindings/usb/nvidia,tegra20-ehci.txt b/Documentation/devicetree/bindings/usb/nvidia,tegra20-ehci.txt
index 34c952883276..df0933043a5b 100644
--- a/Documentation/devicetree/bindings/usb/nvidia,tegra20-ehci.txt
+++ b/Documentation/devicetree/bindings/usb/nvidia,tegra20-ehci.txt
@@ -6,27 +6,10 @@ Practice : Universal Serial Bus" with the following modifications
and additions :
Required properties :
- - compatible : Should be "nvidia,tegra20-ehci" for USB controllers
- used in host mode.
- - phy_type : Should be one of "ulpi" or "utmi".
- - nvidia,vbus-gpio : If present, specifies a gpio that needs to be
- activated for the bus to be powered.
- - nvidia,phy : phandle of the PHY instance, the controller is connected to.
-
-Required properties for phy_type == ulpi:
- - nvidia,phy-reset-gpio : The GPIO used to reset the PHY.
+ - compatible : Should be "nvidia,tegra20-ehci".
+ - nvidia,phy : phandle of the PHY that the controller is connected to.
+ - clocks : Contains a single entry which defines the USB controller's clock.
Optional properties:
- - dr_mode : dual role mode. Indicates the working mode for
- nvidia,tegra20-ehci compatible controllers. Can be "host", "peripheral",
- or "otg". Default to "host" if not defined for backward compatibility.
- host means this is a host controller
- peripheral means it is device controller
- otg means it can operate as either ("on the go")
- - nvidia,has-legacy-mode : boolean indicates whether this controller can
- operate in legacy mode (as APX 2500 / 2600). In legacy mode some
- registers are accessed through the APB_MISC base address instead of
- the USB controller. Since this is a legacy issue it probably does not
- warrant a compatible string of its own.
- - nvidia,needs-double-reset : boolean is to be set for some of the Tegra2
- USB ports, which need reset twice due to hardware issues.
+ - nvidia,needs-double-reset : boolean is to be set for some of the Tegra20
+ USB ports, which need reset twice due to hardware issues.
diff --git a/Documentation/devicetree/bindings/usb/nvidia,tegra20-usb-phy.txt b/Documentation/devicetree/bindings/usb/nvidia,tegra20-usb-phy.txt
index 6bdaba2f0aa1..c4c9e9e664aa 100644
--- a/Documentation/devicetree/bindings/usb/nvidia,tegra20-usb-phy.txt
+++ b/Documentation/devicetree/bindings/usb/nvidia,tegra20-usb-phy.txt
@@ -4,14 +4,49 @@ The device node for Tegra SOC USB PHY:
Required properties :
- compatible : Should be "nvidia,tegra20-usb-phy".
- - reg : Address and length of the register set for the USB PHY interface.
- - phy_type : Should be one of "ulpi" or "utmi".
+ - reg : Defines the following set of registers, in the order listed:
+ - The PHY's own register set.
+ Always present.
+ - The register set of the PHY containing the UTMI pad control registers.
+ Present if-and-only-if phy_type == utmi.
+ - phy_type : Should be one of "utmi", "ulpi" or "hsic".
+ - clocks : Defines the clocks listed in the clock-names property.
+ - clock-names : The following clock names must be present:
+ - reg: The clock needed to access the PHY's own registers. This is the
+ associated EHCI controller's clock. Always present.
+ - pll_u: PLL_U. Always present.
+ - timer: The timeout clock (clk_m). Present if phy_type == utmi.
+ - utmi-pads: The clock needed to access the UTMI pad control registers.
+ Present if phy_type == utmi.
+ - ulpi-link: The clock Tegra provides to the ULPI PHY (cdev2).
+ Present if phy_type == ulpi, and ULPI link mode is in use.
Required properties for phy_type == ulpi:
- nvidia,phy-reset-gpio : The GPIO used to reset the PHY.
+Required PHY timing params for utmi phy:
+ - nvidia,hssync-start-delay : Number of 480 Mhz clock cycles to wait before
+ start of sync launches RxActive
+ - nvidia,elastic-limit : Variable FIFO Depth of elastic input store
+ - nvidia,idle-wait-delay : Number of 480 Mhz clock cycles of idle to wait
+ before declare IDLE.
+ - nvidia,term-range-adj : Range adjusment on terminations
+ - nvidia,xcvr-setup : HS driver output control
+ - nvidia,xcvr-lsfslew : LS falling slew rate control.
+ - nvidia,xcvr-lsrslew : LS rising slew rate control.
+
Optional properties:
- nvidia,has-legacy-mode : boolean indicates whether this controller can
operate in legacy mode (as APX 2500 / 2600). In legacy mode some
registers are accessed through the APB_MISC base address instead of
- the USB controller. \ No newline at end of file
+ the USB controller.
+ - nvidia,is-wired : boolean. Indicates whether we can do certain kind of power
+ optimizations for the devices that are always connected. e.g. modem.
+ - dr_mode : dual role mode. Indicates the working mode for the PHY. Can be
+ "host", "peripheral", or "otg". Defaults to "host" if not defined.
+ host means this is a host controller
+ peripheral means it is device controller
+ otg means it can operate as either ("on the go")
+
+Required properties for dr_mode == otg:
+ - vbus-supply: regulator for VBUS
diff --git a/Documentation/devicetree/bindings/usb/usb3503.txt b/Documentation/devicetree/bindings/usb/usb3503.txt
index 6813a715fc7d..8c5be48b43c8 100644
--- a/Documentation/devicetree/bindings/usb/usb3503.txt
+++ b/Documentation/devicetree/bindings/usb/usb3503.txt
@@ -4,6 +4,10 @@ Required properties:
- compatible: Should be "smsc,usb3503".
- reg: Specifies the i2c slave address, it should be 0x08.
- connect-gpios: Should specify GPIO for connect.
+- disabled-ports: Should specify the ports unused.
+ '1' or '2' or '3' are availe for this property to describe the port
+ number. 1~3 property values are possible to be desribed.
+ Do not describe this property if all ports have to be enabled.
- intn-gpios: Should specify GPIO for interrupt.
- reset-gpios: Should specify GPIO for reset.
- initial-mode: Should specify initial mode.
@@ -14,6 +18,7 @@ Examples:
compatible = "smsc,usb3503";
reg = <0x08>;
connect-gpios = <&gpx3 0 1>;
+ disabled-ports = <2 3>;
intn-gpios = <&gpx3 4 1>;
reset-gpios = <&gpx3 5 1>;
initial-mode = <1>;
diff --git a/Documentation/usb/gadget_configfs.txt b/Documentation/usb/gadget_configfs.txt
new file mode 100644
index 000000000000..8ec2a67c39b7
--- /dev/null
+++ b/Documentation/usb/gadget_configfs.txt
@@ -0,0 +1,384 @@
+
+
+
+
+ Linux USB gadget configured through configfs
+
+
+ 25th April 2013
+
+
+
+
+Overview
+========
+
+A USB Linux Gadget is a device which has a UDC (USB Device Controller) and can
+be connected to a USB Host to extend it with additional functions like a serial
+port or a mass storage capability.
+
+A gadget is seen by its host as a set of configurations, each of which contains
+a number of interfaces which, from the gadget's perspective, are known as
+functions, each function representing e.g. a serial connection or a SCSI disk.
+
+Linux provides a number of functions for gadgets to use.
+
+Creating a gadget means deciding what configurations there will be
+and which functions each configuration will provide.
+
+Configfs (please see Documentation/filesystems/configfs/*) lends itslef nicely
+for the purpose of telling the kernel about the above mentioned decision.
+This document is about how to do it.
+
+It also describes how configfs integration into gadget is designed.
+
+
+
+
+Requirements
+============
+
+In order for this to work configfs must be available, so CONFIGFS_FS must be
+'y' or 'm' in .config. As of this writing USB_LIBCOMPOSITE selects CONFIGFS_FS.
+
+
+
+
+Usage
+=====
+
+(The original post describing the first function
+made available through configfs can be seen here:
+http://www.spinics.net/lists/linux-usb/msg76388.html)
+
+$ modprobe libcomposite
+$ mount none $CONFIGFS_HOME -t configfs
+
+where CONFIGFS_HOME is the mount point for configfs
+
+1. Creating the gadgets
+-----------------------
+
+For each gadget to be created its corresponding directory must be created:
+
+$ mkdir $CONFIGFS_HOME/usb_gadget/<gadget name>
+
+e.g.:
+
+$ mkdir $CONFIGFS_HOME/usb_gadget/g1
+
+...
+...
+...
+
+$ cd $CONFIGFS_HOME/usb_gadget/g1
+
+Each gadget needs to have its vendor id <VID> and product id <PID> specified:
+
+$ echo <VID> > idVendor
+$ echo <PID> > idProduct
+
+A gadget also needs its serial number, manufacturer and product strings.
+In order to have a place to store them, a strings subdirectory must be created
+for each language, e.g.:
+
+$ mkdir strings/0x409
+
+Then the strings can be specified:
+
+$ echo <serial number> > strings/0x409/serialnumber
+$ echo <manufacturer> > strings/0x409/manufacturer
+$ echo <product> > strings/0x409/product
+
+2. Creating the configurations
+------------------------------
+
+Each gadget will consist of a number of configurations, their corresponding
+directories must be created:
+
+$ mkdir configs/<name>.<number>
+
+where <name> can be any string which is legal in a filesystem and the
+<numebr> is the configuration's number, e.g.:
+
+$ mkdir configs/c.1
+
+...
+...
+...
+
+Each configuration also needs its strings, so a subdirectory must be created
+for each language, e.g.:
+
+$ mkdir configs/c.1/strings/0x409
+
+Then the configuration string can be specified:
+
+$ echo <configuration> > configs/c.1/strings/0x409/configuration
+
+Some attributes can also be set for a configuration, e.g.:
+
+$ echo 120 > configs/c.1/MaxPower
+
+3. Creating the functions
+-------------------------
+
+The gadget will provide some functions, for each function its corresponding
+directory must be created:
+
+$ mkdir functions/<name>.<instance name>
+
+where <name> corresponds to one of allowed function names and instance name
+is an arbitrary string allowed in a filesystem, e.g.:
+
+$ mkdir functions/ncm.usb0 # usb_f_ncm.ko gets loaded with request_module()
+
+...
+...
+...
+
+Each function provides its specific set of attributes, with either read-only
+or read-write access. Where applicable they need to be written to as
+appropriate.
+Please refer to Documentation/ABI/*/configfs-usb-gadget* for more information.
+
+4. Associating the functions with their configurations
+------------------------------------------------------
+
+At this moment a number of gadgets is created, each of which has a number of
+configurations specified and a number of functions available. What remains
+is specifying which function is available in which configuration (the same
+function can be used in multiple configurations). This is achieved with
+creating symbolic links:
+
+$ ln -s functions/<name>.<instance name> configs/<name>.<number>
+
+e.g.:
+
+$ ln -s functions/ncm.usb0 configs/c.1
+
+...
+...
+...
+
+5. Enabling the gadget
+----------------------
+
+All the above steps serve the purpose of composing the gadget of
+configurations and functions.
+
+An example directory structure might look like this:
+
+.
+./strings
+./strings/0x409
+./strings/0x409/serialnumber
+./strings/0x409/product
+./strings/0x409/manufacturer
+./configs
+./configs/c.1
+./configs/c.1/ncm.usb0 -> ../../../../usb_gadget/g1/functions/ncm.usb0
+./configs/c.1/strings
+./configs/c.1/strings/0x409
+./configs/c.1/strings/0x409/configuration
+./configs/c.1/bmAttributes
+./configs/c.1/MaxPower
+./functions
+./functions/ncm.usb0
+./functions/ncm.usb0/ifname
+./functions/ncm.usb0/qmult
+./functions/ncm.usb0/host_addr
+./functions/ncm.usb0/dev_addr
+./UDC
+./bcdUSB
+./bcdDevice
+./idProduct
+./idVendor
+./bMaxPacketSize0
+./bDeviceProtocol
+./bDeviceSubClass
+./bDeviceClass
+
+
+Such a gadget must be finally enabled so that the USB host can enumerate it.
+In order to enable the gadget it must be bound to a UDC (USB Device Controller).
+
+$ echo <udc name> > UDC
+
+where <udc name> is one of those found in /sys/class/udc/*
+e.g.:
+
+$ echo s3c-hsotg > UDC
+
+
+6. Disabling the gadget
+-----------------------
+
+$ echo "" > UDC
+
+7. Cleaning up
+--------------
+
+Remove functions from configurations:
+
+$ rm configs/<config name>.<number>/<function>
+
+where <config name>.<number> specify the configuration and <function> is
+a symlink to a function being removed from the configuration, e.g.:
+
+$ rm configfs/c.1/ncm.usb0
+
+...
+...
+...
+
+Remove strings directories in configurations
+
+$ rmdir configs/<config name>.<number>/strings/<lang>
+
+e.g.:
+
+$ rmdir configs/c.1/strings/0x409
+
+...
+...
+...
+
+and remove the configurations
+
+$ rmdir configs/<config name>.<number>
+
+e.g.:
+
+rmdir configs/c.1
+
+...
+...
+...
+
+Remove functions (function modules are not unloaded, though)
+
+$ rmdir functions/<name>.<instance name>
+
+e.g.:
+
+$ rmdir functions/ncm.usb0
+
+...
+...
+...
+
+Remove strings directories in the gadget
+
+$ rmdir strings/<lang>
+
+e.g.:
+
+$ rmdir strings/0x409
+
+and finally remove the gadget:
+
+$ cd ..
+$ rmdir <gadget name>
+
+e.g.:
+
+$ rmdir g1
+
+
+
+
+Implementation design
+=====================
+
+Below the idea of how configfs works is presented.
+In configfs there are items and groups, both represented as directories.
+The difference between an item and a group is that a group can contain
+other groups. In the picture below only an item is shown.
+Both items and groups can have attributes, which are represented as files.
+The user can create and remove directories, but cannot remove files,
+which can be read-only or read-write, depending on what they represent.
+
+The filesystem part of configfs operates on config_items/groups and
+configfs_attributes which are generic and of the same type for all
+configured elements. However, they are embedded in usage-specific
+larger structures. In the picture below there is a "cs" which contains
+a config_item and an "sa" which contains a configfs_attribute.
+
+The filesystem view would be like this:
+
+./
+./cs (directory)
+ |
+ +--sa (file)
+ |
+ .
+ .
+ .
+
+Whenever a user reads/writes the "sa" file, a function is called
+which accepts a struct config_item and a struct configfs_attribute.
+In the said function the "cs" and "sa" are retrieved using the well
+known container_of technique and an appropriate sa's function (show or
+store) is called and passed the "cs" and a character buffer. The "show"
+is for displaying the file's contents (copy data from the cs to the
+buffer), while the "store" is for modifying the file's contents (copy data
+from the buffer to the cs), but it is up to the implementer of the
+two functions to decide what they actually do.
+
+typedef struct configured_structure cs;
+typedef struc specific_attribute sa;
+
+ sa
+ +----------------------------------+
+ cs | (*show)(cs *, buffer); |
++-----------------+ | (*store)(cs *, buffer, length); |
+| | | |
+| +-------------+ | | +------------------+ |
+| | struct |-|----|------>|struct | |
+| | config_item | | | |configfs_attribute| |
+| +-------------+ | | +------------------+ |
+| | +----------------------------------+
+| data to be set | .
+| | .
++-----------------+ .
+
+The file names are decided by the config item/group designer, while
+the directories in general can be named at will. A group can have
+a number of its default sub-groups created automatically.
+
+For more information on configfs please see
+Documentation/filesystems/configfs/*.
+
+The concepts described above translate to USB gadgets like this:
+
+1. A gadget has its config group, which has some attributes (idVendor,
+idProduct etc) and default sub-groups (configs, functions, strings).
+Writing to the attributes causes the information to be stored in
+appropriate locations. In the configs, functions and strings sub-groups
+a user can create their sub-groups to represent configurations, functions,
+and groups of strings in a given language.
+
+2. The user creates configurations and functions, in the configurations
+creates symbolic links to functions. This information is used when the
+gadget's UDC attribute is written to, which means binding the gadget
+to the UDC. The code in drivers/usb/gadget/configfs.c iterates over
+all configurations, and in each configuration it iterates over all
+functions and binds them. This way the whole gadget is bound.
+
+3. The file drivers/usb/gadget/configfs.c contains code for
+
+ - gadget's config_group
+ - gadget's default groups (configs, functions, strings)
+ - associating functions with configurations (symlinks)
+
+4. Each USB function naturally has its own view of what it wants
+configured, so config_groups for particular functions are defined
+in the functions implementation files drivers/usb/gadget/f_*.c.
+
+5. Funciton's code is written in such a way that it uses
+
+usb_get_function_instance(), which, in turn, calls request_module.
+So, provided that modprobe works, modules for particular functions
+are loaded automatically. Please note that the converse is not true:
+after a gadget is disabled and torn down, the modules remain loaded.