diff options
author | Linus Torvalds <torvalds@linux-foundation.org> | 2013-07-02 18:31:09 (GMT) |
---|---|---|
committer | Linus Torvalds <torvalds@linux-foundation.org> | 2013-07-02 18:31:09 (GMT) |
commit | a84270189e2afc7028b1123415a66d444f460977 (patch) | |
tree | 0f239afe73655167c02b411d1cf84bf3211818af /Documentation | |
parent | bcd7351e83728859833e3c5b8aae9a2816914e4b (diff) | |
parent | 3a0ddc714a1b8fcbff24c135a1332a28b4668d78 (diff) | |
download | linux-a84270189e2afc7028b1123415a66d444f460977.tar.xz |
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')
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 0000000..01e769d --- /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 0000000..5708a56 --- /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 0000000..6b9a582 --- /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 0000000..dbddf36 --- /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 0000000..bc309f423 --- /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 0000000..aaa5c96 --- /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 0000000..3e3b742 --- /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 0000000..822e6da --- /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 0000000..16f130c --- /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 0000000..154ae59 --- /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 f093e59..9759b8c 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 25b1e75..5977e28 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 1c04a4c..b4b5b79 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 34c9528..df09330 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 6bdaba2..c4c9e9e 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 6813a71..8c5be48 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 0000000..8ec2a67 --- /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. |