From 804898e8bc43080c9194ae7e1807bf0e995bad73 Mon Sep 17 00:00:00 2001 From: Chris Brandt Date: Wed, 15 May 2019 10:20:39 -0500 Subject: dt-bindings: rcar-gen3-phy-usb2: Document dr_mode Document the optional dr_mode property Signed-off-by: Chris Brandt Reviewed-by: Rob Herring Reviewed-by: Yoshihiro Shimoda Reviewed-by: Simon Horman Signed-off-by: Greg Kroah-Hartman --- Documentation/devicetree/bindings/phy/rcar-gen3-phy-usb2.txt | 3 +++ 1 file changed, 3 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/phy/rcar-gen3-phy-usb2.txt b/Documentation/devicetree/bindings/phy/rcar-gen3-phy-usb2.txt index d46188f450bf..64afd086e606 100644 --- a/Documentation/devicetree/bindings/phy/rcar-gen3-phy-usb2.txt +++ b/Documentation/devicetree/bindings/phy/rcar-gen3-phy-usb2.txt @@ -46,6 +46,9 @@ channel as USB OTG: regulator will be managed during the PHY power on/off sequence. - renesas,no-otg-pins: boolean, specify when a board does not provide proper otg pins. +- dr_mode: string, indicates the working mode for the PHY. Can be "host", + "peripheral", or "otg". Should be set if otg controller is not used. + Example (R-Car H3): -- cgit v1.2.3-59-g8ed1b From b051c93746543385f398b6b8002a51e9d43143a6 Mon Sep 17 00:00:00 2001 From: Chris Brandt Date: Wed, 15 May 2019 10:20:40 -0500 Subject: dt-bindings: rcar-gen3-phy-usb2: Add r7s9210 support Document RZ/A2 (R7S9210) SoC bindings. Signed-off-by: Chris Brandt Reviewed-by: Rob Herring Reviewed-by: Yoshihiro Shimoda Reviewed-by: Simon Horman Signed-off-by: Greg Kroah-Hartman --- Documentation/devicetree/bindings/phy/rcar-gen3-phy-usb2.txt | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/phy/rcar-gen3-phy-usb2.txt b/Documentation/devicetree/bindings/phy/rcar-gen3-phy-usb2.txt index 64afd086e606..503a8cfb3184 100644 --- a/Documentation/devicetree/bindings/phy/rcar-gen3-phy-usb2.txt +++ b/Documentation/devicetree/bindings/phy/rcar-gen3-phy-usb2.txt @@ -1,10 +1,12 @@ * Renesas R-Car generation 3 USB 2.0 PHY This file provides information on what the device node for the R-Car generation -3, RZ/G1C and RZ/G2 USB 2.0 PHY contain. +3, RZ/G1C, RZ/G2 and RZ/A2 USB 2.0 PHY contain. Required properties: -- compatible: "renesas,usb2-phy-r8a77470" if the device is a part of an R8A77470 +- compatible: "renesas,usb2-phy-r7s9210" if the device is a part of an R7S9210 + SoC. + "renesas,usb2-phy-r8a77470" if the device is a part of an R8A77470 SoC. "renesas,usb2-phy-r8a774a1" if the device is a part of an R8A774A1 SoC. @@ -20,8 +22,8 @@ Required properties: R8A77990 SoC. "renesas,usb2-phy-r8a77995" if the device is a part of an R8A77995 SoC. - "renesas,rcar-gen3-usb2-phy" for a generic R-Car Gen3 or RZ/G2 - compatible device. + "renesas,rcar-gen3-usb2-phy" for a generic R-Car Gen3, RZ/G2 or + RZ/A2 compatible device. When compatible with the generic version, nodes must list the SoC-specific version corresponding to the platform first -- cgit v1.2.3-59-g8ed1b From 6e9aed4ed4ca129510fcb1af495391d4717246d6 Mon Sep 17 00:00:00 2001 From: Chris Brandt Date: Wed, 15 May 2019 10:20:45 -0500 Subject: dt-bindings: usb: renesas_usbhs: Add support for r7s9210 Add support for r7s9210 (RZ/A2M) SoC Signed-off-by: Chris Brandt Reviewed-by: Rob Herring Reviewed-by: Yoshihiro Shimoda Reviewed-by: Simon Horman Signed-off-by: Greg Kroah-Hartman --- Documentation/devicetree/bindings/usb/renesas_usbhs.txt | 2 ++ 1 file changed, 2 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/usb/renesas_usbhs.txt b/Documentation/devicetree/bindings/usb/renesas_usbhs.txt index b8acc2a994a8..e39255ea6e4f 100644 --- a/Documentation/devicetree/bindings/usb/renesas_usbhs.txt +++ b/Documentation/devicetree/bindings/usb/renesas_usbhs.txt @@ -20,9 +20,11 @@ Required properties: - "renesas,usbhs-r8a77990" for r8a77990 (R-Car E3) compatible device - "renesas,usbhs-r8a77995" for r8a77995 (R-Car D3) compatible device - "renesas,usbhs-r7s72100" for r7s72100 (RZ/A1) compatible device + - "renesas,usbhs-r7s9210" for r7s9210 (RZ/A2) compatible device - "renesas,rcar-gen2-usbhs" for R-Car Gen2 or RZ/G1 compatible devices - "renesas,rcar-gen3-usbhs" for R-Car Gen3 or RZ/G2 compatible devices - "renesas,rza1-usbhs" for RZ/A1 compatible device + - "renesas,rza2-usbhs" for RZ/A2 compatible device When compatible with the generic version, nodes must list the SoC-specific version corresponding to the platform first followed -- cgit v1.2.3-59-g8ed1b From 96ef07f79ae8644ab9c277e3f2f4fb04a54be43d Mon Sep 17 00:00:00 2001 From: Bjorn Andersson Date: Wed, 1 May 2019 17:14:05 -0700 Subject: dt-bindings: phy: Add binding for Qualcomm PCIe2 PHY The Qualcomm PCIe2 PHY is a Synopsys based PCIe PHY found in a number of Qualcomm platforms, add a binding to describe this. Signed-off-by: Bjorn Andersson Reviewed-by: Rob Herring Signed-off-by: Kishon Vijay Abraham I --- .../devicetree/bindings/phy/qcom-pcie2-phy.txt | 42 ++++++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 Documentation/devicetree/bindings/phy/qcom-pcie2-phy.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/phy/qcom-pcie2-phy.txt b/Documentation/devicetree/bindings/phy/qcom-pcie2-phy.txt new file mode 100644 index 000000000000..30064253f290 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/qcom-pcie2-phy.txt @@ -0,0 +1,42 @@ +Qualcomm PCIe2 PHY controller +============================= + +The Qualcomm PCIe2 PHY is a Synopsys based phy found in a number of Qualcomm +platforms. + +Required properties: + - compatible: compatible list, should be: + "qcom,qcs404-pcie2-phy", "qcom,pcie2-phy" + + - reg: offset and length of the PHY register set. + - #phy-cells: must be 0. + + - clocks: a clock-specifier pair for the "pipe" clock + + - vdda-vp-supply: phandle to low voltage regulator + - vdda-vph-supply: phandle to high voltage regulator + + - resets: reset-specifier pairs for the "phy" and "pipe" resets + - reset-names: list of resets, should contain: + "phy" and "pipe" + + - clock-output-names: name of the outgoing clock signal from the PHY PLL + - #clock-cells: must be 0 + +Example: + phy@7786000 { + compatible = "qcom,qcs404-pcie2-phy", "qcom,pcie2-phy"; + reg = <0x07786000 0xb8>; + + clocks = <&gcc GCC_PCIE_0_PIPE_CLK>; + resets = <&gcc GCC_PCIEPHY_0_PHY_BCR>, + <&gcc GCC_PCIE_0_PIPE_ARES>; + reset-names = "phy", "pipe"; + + vdda-vp-supply = <&vreg_l3_1p05>; + vdda-vph-supply = <&vreg_l5_1p8>; + + clock-output-names = "pcie_0_pipe_clk"; + #clock-cells = <0>; + #phy-cells = <0>; + }; -- cgit v1.2.3-59-g8ed1b From f40043b368ae787837ef659728f0b08bd34f5317 Mon Sep 17 00:00:00 2001 From: Thierry Reding Date: Thu, 25 Apr 2019 17:34:42 +0200 Subject: dt-bindings: phy: tegra-xusb: List PLL power supplies These power supplies provide power for various PLLs that are set up and driven by the XUSB pad controller. These power supplies were previously improperly added to the PCIe and XUSB controllers, but depending on the driver probe order, power to the PLLs will not be supplied soon enough and cause initialization to fail. Reviewed-by: Rob Herring Signed-off-by: Thierry Reding Acked-by: Jon Hunter Signed-off-by: Kishon Vijay Abraham I --- .../devicetree/bindings/phy/nvidia,tegra124-xusb-padctl.txt | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/phy/nvidia,tegra124-xusb-padctl.txt b/Documentation/devicetree/bindings/phy/nvidia,tegra124-xusb-padctl.txt index daedb15f322e..9fb682e47c29 100644 --- a/Documentation/devicetree/bindings/phy/nvidia,tegra124-xusb-padctl.txt +++ b/Documentation/devicetree/bindings/phy/nvidia,tegra124-xusb-padctl.txt @@ -42,6 +42,18 @@ Required properties: - reset-names: Must include the following entries: - "padctl" +For Tegra124: +- avdd-pll-utmip-supply: UTMI PLL power supply. Must supply 1.8 V. +- avdd-pll-erefe-supply: PLLE reference PLL power supply. Must supply 1.05 V. +- avdd-pex-pll-supply: PCIe/USB3 PLL power supply. Must supply 1.05 V. +- hvdd-pex-pll-e-supply: High-voltage PLLE power supply. Must supply 3.3 V. + +For Tegra210: +- avdd-pll-utmip-supply: UTMI PLL power supply. Must supply 1.8 V. +- avdd-pll-uerefe-supply: PLLE reference PLL power supply. Must supply 1.05 V. +- dvdd-pex-pll-supply: PCIe/USB3 PLL power supply. Must supply 1.05 V. +- hvdd-pex-pll-e-supply: High-voltage PLLE power supply. Must supply 1.8 V. + For Tegra186: - avdd-pll-erefeut-supply: UPHY brick and reference clock as well as UTMI PHY power supply. Must supply 1.8 V. -- cgit v1.2.3-59-g8ed1b From 59d7d4c5178d18b58414194271ad85e30ecaff92 Mon Sep 17 00:00:00 2001 From: Simon Horman Date: Mon, 17 Jun 2019 11:06:02 +0200 Subject: dt-bindings: usb: renesas_usbhs: Rename bindings documentation file For consistency with the naming of (most) other documentation files for DT bindings for Renesas IP blocks rename the Renesas USBHS documentation file from renesas-usbhs.txt to renesas,usbhs.txt. Signed-off-by: Simon Horman Signed-off-by: Felipe Balbi --- .../devicetree/bindings/usb/renesas,usbhs.txt | 57 ++++++++++++++++++++++ .../devicetree/bindings/usb/renesas_usbhs.txt | 57 ---------------------- 2 files changed, 57 insertions(+), 57 deletions(-) create mode 100644 Documentation/devicetree/bindings/usb/renesas,usbhs.txt delete mode 100644 Documentation/devicetree/bindings/usb/renesas_usbhs.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/usb/renesas,usbhs.txt b/Documentation/devicetree/bindings/usb/renesas,usbhs.txt new file mode 100644 index 000000000000..e39255ea6e4f --- /dev/null +++ b/Documentation/devicetree/bindings/usb/renesas,usbhs.txt @@ -0,0 +1,57 @@ +Renesas Electronics USBHS driver + +Required properties: + - compatible: Must contain one or more of the following: + + - "renesas,usbhs-r8a7743" for r8a7743 (RZ/G1M) compatible device + - "renesas,usbhs-r8a7744" for r8a7744 (RZ/G1N) compatible device + - "renesas,usbhs-r8a7745" for r8a7745 (RZ/G1E) compatible device + - "renesas,usbhs-r8a77470" for r8a77470 (RZ/G1C) compatible device + - "renesas,usbhs-r8a774a1" for r8a774a1 (RZ/G2M) compatible device + - "renesas,usbhs-r8a774c0" for r8a774c0 (RZ/G2E) compatible device + - "renesas,usbhs-r8a7790" for r8a7790 (R-Car H2) compatible device + - "renesas,usbhs-r8a7791" for r8a7791 (R-Car M2-W) compatible device + - "renesas,usbhs-r8a7792" for r8a7792 (R-Car V2H) compatible device + - "renesas,usbhs-r8a7793" for r8a7793 (R-Car M2-N) compatible device + - "renesas,usbhs-r8a7794" for r8a7794 (R-Car E2) compatible device + - "renesas,usbhs-r8a7795" for r8a7795 (R-Car H3) compatible device + - "renesas,usbhs-r8a7796" for r8a7796 (R-Car M3-W) compatible device + - "renesas,usbhs-r8a77965" for r8a77965 (R-Car M3-N) compatible device + - "renesas,usbhs-r8a77990" for r8a77990 (R-Car E3) compatible device + - "renesas,usbhs-r8a77995" for r8a77995 (R-Car D3) compatible device + - "renesas,usbhs-r7s72100" for r7s72100 (RZ/A1) compatible device + - "renesas,usbhs-r7s9210" for r7s9210 (RZ/A2) compatible device + - "renesas,rcar-gen2-usbhs" for R-Car Gen2 or RZ/G1 compatible devices + - "renesas,rcar-gen3-usbhs" for R-Car Gen3 or RZ/G2 compatible devices + - "renesas,rza1-usbhs" for RZ/A1 compatible device + - "renesas,rza2-usbhs" for RZ/A2 compatible device + + When compatible with the generic version, nodes must list the + SoC-specific version corresponding to the platform first followed + by the generic version. + + - reg: Base address and length of the register for the USBHS + - interrupts: Interrupt specifier for the USBHS + - clocks: A list of phandle + clock specifier pairs. + - In case of "renesas,rcar-gen3-usbhs", two clocks are required. + First clock should be peripheral and second one should be host. + - In case of except above, one clock is required. First clock + should be peripheral. + +Optional properties: + - renesas,buswait: Integer to use BUSWAIT register + - renesas,enable-gpio: A gpio specifier to check GPIO determining if USB + function should be enabled + - phys: phandle + phy specifier pair + - phy-names: must be "usb" + - dmas: Must contain a list of references to DMA specifiers. + - dma-names : named "ch%d", where %d is the channel number ranging from zero + to the number of channels (DnFIFOs) minus one. + +Example: + usbhs: usb@e6590000 { + compatible = "renesas,usbhs-r8a7790", "renesas,rcar-gen2-usbhs"; + reg = <0 0xe6590000 0 0x100>; + interrupts = <0 107 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&mstp7_clks R8A7790_CLK_HSUSB>; + }; diff --git a/Documentation/devicetree/bindings/usb/renesas_usbhs.txt b/Documentation/devicetree/bindings/usb/renesas_usbhs.txt deleted file mode 100644 index e39255ea6e4f..000000000000 --- a/Documentation/devicetree/bindings/usb/renesas_usbhs.txt +++ /dev/null @@ -1,57 +0,0 @@ -Renesas Electronics USBHS driver - -Required properties: - - compatible: Must contain one or more of the following: - - - "renesas,usbhs-r8a7743" for r8a7743 (RZ/G1M) compatible device - - "renesas,usbhs-r8a7744" for r8a7744 (RZ/G1N) compatible device - - "renesas,usbhs-r8a7745" for r8a7745 (RZ/G1E) compatible device - - "renesas,usbhs-r8a77470" for r8a77470 (RZ/G1C) compatible device - - "renesas,usbhs-r8a774a1" for r8a774a1 (RZ/G2M) compatible device - - "renesas,usbhs-r8a774c0" for r8a774c0 (RZ/G2E) compatible device - - "renesas,usbhs-r8a7790" for r8a7790 (R-Car H2) compatible device - - "renesas,usbhs-r8a7791" for r8a7791 (R-Car M2-W) compatible device - - "renesas,usbhs-r8a7792" for r8a7792 (R-Car V2H) compatible device - - "renesas,usbhs-r8a7793" for r8a7793 (R-Car M2-N) compatible device - - "renesas,usbhs-r8a7794" for r8a7794 (R-Car E2) compatible device - - "renesas,usbhs-r8a7795" for r8a7795 (R-Car H3) compatible device - - "renesas,usbhs-r8a7796" for r8a7796 (R-Car M3-W) compatible device - - "renesas,usbhs-r8a77965" for r8a77965 (R-Car M3-N) compatible device - - "renesas,usbhs-r8a77990" for r8a77990 (R-Car E3) compatible device - - "renesas,usbhs-r8a77995" for r8a77995 (R-Car D3) compatible device - - "renesas,usbhs-r7s72100" for r7s72100 (RZ/A1) compatible device - - "renesas,usbhs-r7s9210" for r7s9210 (RZ/A2) compatible device - - "renesas,rcar-gen2-usbhs" for R-Car Gen2 or RZ/G1 compatible devices - - "renesas,rcar-gen3-usbhs" for R-Car Gen3 or RZ/G2 compatible devices - - "renesas,rza1-usbhs" for RZ/A1 compatible device - - "renesas,rza2-usbhs" for RZ/A2 compatible device - - When compatible with the generic version, nodes must list the - SoC-specific version corresponding to the platform first followed - by the generic version. - - - reg: Base address and length of the register for the USBHS - - interrupts: Interrupt specifier for the USBHS - - clocks: A list of phandle + clock specifier pairs. - - In case of "renesas,rcar-gen3-usbhs", two clocks are required. - First clock should be peripheral and second one should be host. - - In case of except above, one clock is required. First clock - should be peripheral. - -Optional properties: - - renesas,buswait: Integer to use BUSWAIT register - - renesas,enable-gpio: A gpio specifier to check GPIO determining if USB - function should be enabled - - phys: phandle + phy specifier pair - - phy-names: must be "usb" - - dmas: Must contain a list of references to DMA specifiers. - - dma-names : named "ch%d", where %d is the channel number ranging from zero - to the number of channels (DnFIFOs) minus one. - -Example: - usbhs: usb@e6590000 { - compatible = "renesas,usbhs-r8a7790", "renesas,rcar-gen2-usbhs"; - reg = <0 0xe6590000 0 0x100>; - interrupts = <0 107 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&mstp7_clks R8A7790_CLK_HSUSB>; - }; -- cgit v1.2.3-59-g8ed1b From 23c46801d14cb647afefc9ec9a7f785777251e76 Mon Sep 17 00:00:00 2001 From: Simon Horman Date: Mon, 17 Jun 2019 11:06:03 +0200 Subject: dt-bindings: usb: renesas_gen3: Rename bindings documentation file For consistency with the naming of (most) other documentation files for DT bindings for Renesas IP blocks rename the Renesas USB3.0 peripheral documentation file from renesas-gen3.txt to renesas,gen3.txt. Signed-off-by: Simon Horman Signed-off-by: Felipe Balbi --- .../devicetree/bindings/usb/renesas,usb3.txt | 41 ++++++++++++++++++++++ .../devicetree/bindings/usb/renesas_usb3.txt | 41 ---------------------- 2 files changed, 41 insertions(+), 41 deletions(-) create mode 100644 Documentation/devicetree/bindings/usb/renesas,usb3.txt delete mode 100644 Documentation/devicetree/bindings/usb/renesas_usb3.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/usb/renesas,usb3.txt b/Documentation/devicetree/bindings/usb/renesas,usb3.txt new file mode 100644 index 000000000000..35039e720515 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/renesas,usb3.txt @@ -0,0 +1,41 @@ +Renesas Electronics USB3.0 Peripheral driver + +Required properties: + - compatible: Must contain one of the following: + - "renesas,r8a774a1-usb3-peri" + - "renesas,r8a774c0-usb3-peri" + - "renesas,r8a7795-usb3-peri" + - "renesas,r8a7796-usb3-peri" + - "renesas,r8a77965-usb3-peri" + - "renesas,r8a77990-usb3-peri" + - "renesas,rcar-gen3-usb3-peri" for a generic R-Car Gen3 or RZ/G2 + compatible device + + When compatible with the generic version, nodes must list the + SoC-specific version corresponding to the platform first + followed by the generic version. + + - reg: Base address and length of the register for the USB3.0 Peripheral + - interrupts: Interrupt specifier for the USB3.0 Peripheral + - clocks: clock phandle and specifier pair + +Optional properties: + - phys: phandle + phy specifier pair + - phy-names: must be "usb" + +Example of R-Car H3 ES1.x: + usb3_peri0: usb@ee020000 { + compatible = "renesas,r8a7795-usb3-peri", + "renesas,rcar-gen3-usb3-peri"; + reg = <0 0xee020000 0 0x400>; + interrupts = ; + clocks = <&cpg CPG_MOD 328>; + }; + + usb3_peri1: usb@ee060000 { + compatible = "renesas,r8a7795-usb3-peri", + "renesas,rcar-gen3-usb3-peri"; + reg = <0 0xee060000 0 0x400>; + interrupts = ; + clocks = <&cpg CPG_MOD 327>; + }; diff --git a/Documentation/devicetree/bindings/usb/renesas_usb3.txt b/Documentation/devicetree/bindings/usb/renesas_usb3.txt deleted file mode 100644 index 35039e720515..000000000000 --- a/Documentation/devicetree/bindings/usb/renesas_usb3.txt +++ /dev/null @@ -1,41 +0,0 @@ -Renesas Electronics USB3.0 Peripheral driver - -Required properties: - - compatible: Must contain one of the following: - - "renesas,r8a774a1-usb3-peri" - - "renesas,r8a774c0-usb3-peri" - - "renesas,r8a7795-usb3-peri" - - "renesas,r8a7796-usb3-peri" - - "renesas,r8a77965-usb3-peri" - - "renesas,r8a77990-usb3-peri" - - "renesas,rcar-gen3-usb3-peri" for a generic R-Car Gen3 or RZ/G2 - compatible device - - When compatible with the generic version, nodes must list the - SoC-specific version corresponding to the platform first - followed by the generic version. - - - reg: Base address and length of the register for the USB3.0 Peripheral - - interrupts: Interrupt specifier for the USB3.0 Peripheral - - clocks: clock phandle and specifier pair - -Optional properties: - - phys: phandle + phy specifier pair - - phy-names: must be "usb" - -Example of R-Car H3 ES1.x: - usb3_peri0: usb@ee020000 { - compatible = "renesas,r8a7795-usb3-peri", - "renesas,rcar-gen3-usb3-peri"; - reg = <0 0xee020000 0 0x400>; - interrupts = ; - clocks = <&cpg CPG_MOD 328>; - }; - - usb3_peri1: usb@ee060000 { - compatible = "renesas,r8a7795-usb3-peri", - "renesas,rcar-gen3-usb3-peri"; - reg = <0 0xee060000 0 0x400>; - interrupts = ; - clocks = <&cpg CPG_MOD 327>; - }; -- cgit v1.2.3-59-g8ed1b From cd5f9726773b654f8e1cfd6ec1a989c558fa164b Mon Sep 17 00:00:00 2001 From: Douglas Anderson Date: Mon, 20 May 2019 10:56:03 -0700 Subject: Documentation: dt-bindings: Add snps,need-phy-for-wake for dwc2 USB Some SoCs with a dwc2 USB controller may need to keep the PHY on to support remote wakeup. Allow specifying this as a device tree property. Reviewed-by: Rob Herring Signed-off-by: Douglas Anderson Signed-off-by: Felipe Balbi --- Documentation/devicetree/bindings/usb/dwc2.txt | 3 +++ 1 file changed, 3 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/usb/dwc2.txt b/Documentation/devicetree/bindings/usb/dwc2.txt index 49eac0dc86b0..aafff3a6904d 100644 --- a/Documentation/devicetree/bindings/usb/dwc2.txt +++ b/Documentation/devicetree/bindings/usb/dwc2.txt @@ -42,6 +42,8 @@ Refer to phy/phy-bindings.txt for generic phy consumer properties - g-rx-fifo-size: size of rx fifo size in gadget mode. - g-np-tx-fifo-size: size of non-periodic tx fifo size in gadget mode. - g-tx-fifo-size: size of periodic tx fifo per endpoint (except ep0) in gadget mode. +- snps,need-phy-for-wake: If present indicates that the phy needs to be left + on for remote wakeup during suspend. - snps,reset-phy-on-wake: If present indicates that we need to reset the PHY when we detect a wakeup. This is due to a hardware errata. @@ -58,4 +60,5 @@ Example: clock-names = "otg"; phys = <&usbphy>; phy-names = "usb2-phy"; + snps,need-phy-for-wake; }; -- cgit v1.2.3-59-g8ed1b From 34cc761bdcc84fa7b9c5fd4e1f8548df6979f194 Mon Sep 17 00:00:00 2001 From: Anurag Kumar Vulisha Date: Fri, 10 May 2019 12:37:26 +0530 Subject: doc: dt: bindings: usb: dwc3: Update entries for disabling U1 and U2 This patch updates the documentation with the information related to the quirks that needs to be added for disabling the link entering into the U1 and U2 states Reviewed-by: Rob Herring Signed-off-by: Anurag Kumar Vulisha Signed-off-by: Felipe Balbi --- Documentation/devicetree/bindings/usb/dwc3.txt | 2 ++ 1 file changed, 2 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/usb/dwc3.txt b/Documentation/devicetree/bindings/usb/dwc3.txt index 8e5265e9f658..66780a47ad85 100644 --- a/Documentation/devicetree/bindings/usb/dwc3.txt +++ b/Documentation/devicetree/bindings/usb/dwc3.txt @@ -64,6 +64,8 @@ Optional properties: - snps,dis_u2_susphy_quirk: when set core will disable USB2 suspend phy. - snps,dis_enblslpm_quirk: when set clears the enblslpm in GUSB2PHYCFG, disabling the suspend signal to the PHY. + - snps,dis-u1-entry-quirk: set if link entering into U1 needs to be disabled. + - snps,dis-u2-entry-quirk: set if link entering into U2 needs to be disabled. - snps,dis_rxdet_inp3_quirk: when set core will disable receiver detection in PHY P3 power state. - snps,dis-u2-freeclk-exists-quirk: when set, clear the u2_freeclk_exists -- cgit v1.2.3-59-g8ed1b From ecefae6db042283bf88ef3777f2381b18df8ed46 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 18 Jun 2019 18:05:38 -0300 Subject: docs: usb: rename files to .rst and add them to drivers-api While there are a mix of things here, most of the stuff were written from Kernel developer's PoV. So, add them to the driver-api book. A follow up for this patch would be to move documents from there that are specific to sysadmins, adding them to the admin-guide. Signed-off-by: Mauro Carvalho Chehab Acked-by: Johan Hovold Acked-by: Felipe Balbi Signed-off-by: Greg Kroah-Hartman --- Documentation/index.rst | 1 + Documentation/index.rst.rej | 10 + Documentation/usb/WUSB-Design-overview.txt | 457 ------------- Documentation/usb/acm.rst | 132 ++++ Documentation/usb/acm.txt | 132 ---- Documentation/usb/authorization.rst | 132 ++++ Documentation/usb/authorization.txt | 132 ---- Documentation/usb/chipidea.rst | 133 ++++ Documentation/usb/chipidea.txt | 133 ---- Documentation/usb/dwc3.rst | 53 ++ Documentation/usb/dwc3.txt | 53 -- Documentation/usb/ehci.rst | 230 +++++++ Documentation/usb/ehci.txt | 230 ------- Documentation/usb/functionfs.rst | 68 ++ Documentation/usb/functionfs.txt | 68 -- Documentation/usb/gadget-testing.rst | 934 +++++++++++++++++++++++++++ Documentation/usb/gadget-testing.txt | 934 --------------------------- Documentation/usb/gadget_configfs.rst | 390 +++++++++++ Documentation/usb/gadget_configfs.txt | 390 ----------- Documentation/usb/gadget_hid.rst | 457 +++++++++++++ Documentation/usb/gadget_hid.txt | 457 ------------- Documentation/usb/gadget_multi.rst | 165 +++++ Documentation/usb/gadget_multi.txt | 165 ----- Documentation/usb/gadget_printer.rst | 523 +++++++++++++++ Documentation/usb/gadget_printer.txt | 523 --------------- Documentation/usb/gadget_serial.rst | 289 +++++++++ Documentation/usb/gadget_serial.txt | 289 --------- Documentation/usb/index.rst | 39 ++ Documentation/usb/iuu_phoenix.rst | 94 +++ Documentation/usb/iuu_phoenix.txt | 94 --- Documentation/usb/mass-storage.rst | 234 +++++++ Documentation/usb/mass-storage.txt | 234 ------- Documentation/usb/misc_usbsevseg.rst | 51 ++ Documentation/usb/misc_usbsevseg.txt | 51 -- Documentation/usb/mtouchusb.rst | 84 +++ Documentation/usb/mtouchusb.txt | 84 --- Documentation/usb/ohci.rst | 35 + Documentation/usb/ohci.txt | 35 - Documentation/usb/rio.rst | 109 ++++ Documentation/usb/rio.txt | 109 ---- Documentation/usb/text_files.rst | 29 + Documentation/usb/usb-help.rst | 17 + Documentation/usb/usb-help.txt | 17 - Documentation/usb/usb-serial.rst | 537 +++++++++++++++ Documentation/usb/usb-serial.txt | 537 --------------- Documentation/usb/usbip_protocol.rst | 411 ++++++++++++ Documentation/usb/usbip_protocol.txt | 411 ------------ Documentation/usb/usbmon.rst | 375 +++++++++++ Documentation/usb/usbmon.txt | 375 ----------- Documentation/usb/wusb-design-overview.rst | 457 +++++++++++++ MAINTAINERS | 12 +- drivers/usb/Kconfig | 2 +- drivers/usb/class/Kconfig | 2 +- drivers/usb/gadget/Kconfig | 6 +- drivers/usb/gadget/function/f_mass_storage.c | 2 +- drivers/usb/gadget/legacy/Kconfig | 6 +- drivers/usb/host/Kconfig | 2 +- drivers/usb/misc/Kconfig | 2 +- drivers/usb/mon/Kconfig | 2 +- drivers/usb/serial/Kconfig | 10 +- drivers/usb/serial/belkin_sa.c | 2 +- drivers/usb/serial/belkin_sa.h | 2 +- drivers/usb/serial/cypress_m8.c | 2 +- drivers/usb/serial/empeg.c | 2 +- drivers/usb/serial/ftdi_sio.c | 2 +- drivers/usb/serial/ir-usb.c | 2 +- drivers/usb/serial/keyspan_pda.c | 2 +- drivers/usb/serial/omninet.c | 2 +- drivers/usb/serial/oti6858.c | 2 +- drivers/usb/serial/pl2303.c | 2 +- drivers/usb/serial/usb-serial.c | 2 +- drivers/usb/serial/visor.c | 2 +- drivers/usb/serial/visor.h | 2 +- drivers/usb/serial/whiteheat.c | 2 +- drivers/usb/serial/whiteheat.h | 2 +- 75 files changed, 6027 insertions(+), 5948 deletions(-) create mode 100644 Documentation/index.rst.rej delete mode 100644 Documentation/usb/WUSB-Design-overview.txt create mode 100644 Documentation/usb/acm.rst delete mode 100644 Documentation/usb/acm.txt create mode 100644 Documentation/usb/authorization.rst delete mode 100644 Documentation/usb/authorization.txt create mode 100644 Documentation/usb/chipidea.rst delete mode 100644 Documentation/usb/chipidea.txt create mode 100644 Documentation/usb/dwc3.rst delete mode 100644 Documentation/usb/dwc3.txt create mode 100644 Documentation/usb/ehci.rst delete mode 100644 Documentation/usb/ehci.txt create mode 100644 Documentation/usb/functionfs.rst delete mode 100644 Documentation/usb/functionfs.txt create mode 100644 Documentation/usb/gadget-testing.rst delete mode 100644 Documentation/usb/gadget-testing.txt create mode 100644 Documentation/usb/gadget_configfs.rst delete mode 100644 Documentation/usb/gadget_configfs.txt create mode 100644 Documentation/usb/gadget_hid.rst delete mode 100644 Documentation/usb/gadget_hid.txt create mode 100644 Documentation/usb/gadget_multi.rst delete mode 100644 Documentation/usb/gadget_multi.txt create mode 100644 Documentation/usb/gadget_printer.rst delete mode 100644 Documentation/usb/gadget_printer.txt create mode 100644 Documentation/usb/gadget_serial.rst delete mode 100644 Documentation/usb/gadget_serial.txt create mode 100644 Documentation/usb/index.rst create mode 100644 Documentation/usb/iuu_phoenix.rst delete mode 100644 Documentation/usb/iuu_phoenix.txt create mode 100644 Documentation/usb/mass-storage.rst delete mode 100644 Documentation/usb/mass-storage.txt create mode 100644 Documentation/usb/misc_usbsevseg.rst delete mode 100644 Documentation/usb/misc_usbsevseg.txt create mode 100644 Documentation/usb/mtouchusb.rst delete mode 100644 Documentation/usb/mtouchusb.txt create mode 100644 Documentation/usb/ohci.rst delete mode 100644 Documentation/usb/ohci.txt create mode 100644 Documentation/usb/rio.rst delete mode 100644 Documentation/usb/rio.txt create mode 100644 Documentation/usb/text_files.rst create mode 100644 Documentation/usb/usb-help.rst delete mode 100644 Documentation/usb/usb-help.txt create mode 100644 Documentation/usb/usb-serial.rst delete mode 100644 Documentation/usb/usb-serial.txt create mode 100644 Documentation/usb/usbip_protocol.rst delete mode 100644 Documentation/usb/usbip_protocol.txt create mode 100644 Documentation/usb/usbmon.rst delete mode 100644 Documentation/usb/usbmon.txt create mode 100644 Documentation/usb/wusb-design-overview.rst (limited to 'Documentation') diff --git a/Documentation/index.rst b/Documentation/index.rst index a7566ef62411..91055adde327 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -101,6 +101,7 @@ needed). filesystems/index vm/index bpf/index + usb/index misc-devices/index Architecture-specific documentation diff --git a/Documentation/index.rst.rej b/Documentation/index.rst.rej new file mode 100644 index 000000000000..b1af6eab22f3 --- /dev/null +++ b/Documentation/index.rst.rej @@ -0,0 +1,10 @@ +--- Documentation/index.rst ++++ Documentation/index.rst +@@ -103,6 +103,7 @@ needed). + vm/index + bpf/index + PCI/index ++ usb/index + misc-devices/index + + Architecture-specific documentation diff --git a/Documentation/usb/WUSB-Design-overview.txt b/Documentation/usb/WUSB-Design-overview.txt deleted file mode 100644 index dc5e21609bb5..000000000000 --- a/Documentation/usb/WUSB-Design-overview.txt +++ /dev/null @@ -1,457 +0,0 @@ -================================ -Linux UWB + Wireless USB + WiNET -================================ - - Copyright (C) 2005-2006 Intel Corporation - - Inaky Perez-Gonzalez - - This program is free software; you can redistribute it and/or - modify it under the terms of the GNU General Public License version - 2 as published by the Free Software Foundation. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program; if not, write to the Free Software - Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA - 02110-1301, USA. - - -Please visit http://bughost.org/thewiki/Design-overview.txt-1.8 for -updated content. - - * Design-overview.txt-1.8 - -This code implements a Ultra Wide Band stack for Linux, as well as -drivers for the USB based UWB radio controllers defined in the -Wireless USB 1.0 specification (including Wireless USB host controller -and an Intel WiNET controller). - -.. Contents - 1. Introduction - 1. HWA: Host Wire adapters, your Wireless USB dongle - - 2. DWA: Device Wired Adaptor, a Wireless USB hub for wired - devices - 3. WHCI: Wireless Host Controller Interface, the PCI WUSB host - adapter - 2. The UWB stack - 1. Devices and hosts: the basic structure - - 2. Host Controller life cycle - - 3. On the air: beacons and enumerating the radio neighborhood - - 4. Device lists - 5. Bandwidth allocation - - 3. Wireless USB Host Controller drivers - - 4. Glossary - - -Introduction -============ - -UWB is a wide-band communication protocol that is to serve also as the -low-level protocol for others (much like TCP sits on IP). Currently -these others are Wireless USB and TCP/IP, but seems Bluetooth and -Firewire/1394 are coming along. - -UWB uses a band from roughly 3 to 10 GHz, transmitting at a max of -~-41dB (or 0.074 uW/MHz--geography specific data is still being -negotiated w/ regulators, so watch for changes). That band is divided in -a bunch of ~1.5 GHz wide channels (or band groups) composed of three -subbands/subchannels (528 MHz each). Each channel is independent of each -other, so you could consider them different "busses". Initially this -driver considers them all a single one. - -Radio time is divided in 65536 us long /superframes/, each one divided -in 256 256us long /MASs/ (Media Allocation Slots), which are the basic -time/media allocation units for transferring data. At the beginning of -each superframe there is a Beacon Period (BP), where every device -transmit its beacon on a single MAS. The length of the BP depends on how -many devices are present and the length of their beacons. - -Devices have a MAC (fixed, 48 bit address) and a device (changeable, 16 -bit address) and send periodic beacons to advertise themselves and pass -info on what they are and do. They advertise their capabilities and a -bunch of other stuff. - -The different logical parts of this driver are: - - * - - *UWB*: the Ultra-Wide-Band stack -- manages the radio and - associated spectrum to allow for devices sharing it. Allows to - control bandwidth assignment, beaconing, scanning, etc - - * - - *WUSB*: the layer that sits on top of UWB to provide Wireless USB. - The Wireless USB spec defines means to control a UWB radio and to - do the actual WUSB. - - -HWA: Host Wire adapters, your Wireless USB dongle -------------------------------------------------- - -WUSB also defines a device called a Host Wire Adaptor (HWA), which in -mere terms is a USB dongle that enables your PC to have UWB and Wireless -USB. The Wireless USB Host Controller in a HWA looks to the host like a -[Wireless] USB controller connected via USB (!) - -The HWA itself is broken in two or three main interfaces: - - * - - *RC*: Radio control -- this implements an interface to the - Ultra-Wide-Band radio controller. The driver for this implements a - USB-based UWB Radio Controller to the UWB stack. - - * - - *HC*: the wireless USB host controller. It looks like a USB host - whose root port is the radio and the WUSB devices connect to it. - To the system it looks like a separate USB host. The driver (will) - implement a USB host controller (similar to UHCI, OHCI or EHCI) - for which the root hub is the radio...To reiterate: it is a USB - controller that is connected via USB instead of PCI. - - * - - *WINET*: some HW provide a WiNET interface (IP over UWB). This - package provides a driver for it (it looks like a network - interface, winetX). The driver detects when there is a link up for - their type and kick into gear. - - -DWA: Device Wired Adaptor, a Wireless USB hub for wired devices ---------------------------------------------------------------- - -These are the complement to HWAs. They are a USB host for connecting -wired devices, but it is connected to your PC connected via Wireless -USB. To the system it looks like yet another USB host. To the untrained -eye, it looks like a hub that connects upstream wirelessly. - -We still offer no support for this; however, it should share a lot of -code with the HWA-RC driver; there is a bunch of factorization work that -has been done to support that in upcoming releases. - - -WHCI: Wireless Host Controller Interface, the PCI WUSB host adapter -------------------------------------------------------------------- - -This is your usual PCI device that implements WHCI. Similar in concept -to EHCI, it allows your wireless USB devices (including DWAs) to connect -to your host via a PCI interface. As in the case of the HWA, it has a -Radio Control interface and the WUSB Host Controller interface per se. - -There is still no driver support for this, but will be in upcoming -releases. - - -The UWB stack -============= - -The main mission of the UWB stack is to keep a tally of which devices -are in radio proximity to allow drivers to connect to them. As well, it -provides an API for controlling the local radio controllers (RCs from -now on), such as to start/stop beaconing, scan, allocate bandwidth, etc. - - -Devices and hosts: the basic structure --------------------------------------- - -The main building block here is the UWB device (struct uwb_dev). For -each device that pops up in radio presence (ie: the UWB host receives a -beacon from it) you get a struct uwb_dev that will show up in -/sys/bus/uwb/devices. - -For each RC that is detected, a new struct uwb_rc and struct uwb_dev are -created. An entry is also created in /sys/class/uwb_rc for each RC. - -Each RC driver is implemented by a separate driver that plugs into the -interface that the UWB stack provides through a struct uwb_rc_ops. The -spec creators have been nice enough to make the message format the same -for HWA and WHCI RCs, so the driver is really a very thin transport that -moves the requests from the UWB API to the device [/uwb_rc_ops->cmd()/] -and sends the replies and notifications back to the API -[/uwb_rc_neh_grok()/]. Notifications are handled to the UWB daemon, that -is chartered, among other things, to keep the tab of how the UWB radio -neighborhood looks, creating and destroying devices as they show up or -disappear. - -Command execution is very simple: a command block is sent and a event -block or reply is expected back. For sending/receiving command/events, a -handle called /neh/ (Notification/Event Handle) is opened with -/uwb_rc_neh_open()/. - -The HWA-RC (USB dongle) driver (drivers/uwb/hwa-rc.c) does this job for -the USB connected HWA. Eventually, drivers/whci-rc.c will do the same -for the PCI connected WHCI controller. - - -Host Controller life cycle --------------------------- - -So let's say we connect a dongle to the system: it is detected and -firmware uploaded if needed [for Intel's i1480 -/drivers/uwb/ptc/usb.c:ptc_usb_probe()/] and then it is reenumerated. -Now we have a real HWA device connected and -/drivers/uwb/hwa-rc.c:hwarc_probe()/ picks it up, that will set up the -Wire-Adaptor environment and then suck it into the UWB stack's vision of -the world [/drivers/uwb/lc-rc.c:uwb_rc_add()/]. - - * - - [*] The stack should put a new RC to scan for devices - [/uwb_rc_scan()/] so it finds what's available around and tries to - connect to them, but this is policy stuff and should be driven - from user space. As of now, the operator is expected to do it - manually; see the release notes for documentation on the procedure. - -When a dongle is disconnected, /drivers/uwb/hwa-rc.c:hwarc_disconnect()/ -takes time of tearing everything down safely (or not...). - - -On the air: beacons and enumerating the radio neighborhood ----------------------------------------------------------- - -So assuming we have devices and we have agreed for a channel to connect -on (let's say 9), we put the new RC to beacon: - - * - - $ echo 9 0 > /sys/class/uwb_rc/uwb0/beacon - -Now it is visible. If there were other devices in the same radio channel -and beacon group (that's what the zero is for), the dongle's radio -control interface will send beacon notifications on its -notification/event endpoint (NEEP). The beacon notifications are part of -the event stream that is funneled into the API with -/drivers/uwb/neh.c:uwb_rc_neh_grok()/ and delivered to the UWBD, the UWB -daemon through a notification list. - -UWBD wakes up and scans the event list; finds a beacon and adds it to -the BEACON CACHE (/uwb_beca/). If he receives a number of beacons from -the same device, he considers it to be 'onair' and creates a new device -[/drivers/uwb/lc-dev.c:uwbd_dev_onair()/]. Similarly, when no beacons -are received in some time, the device is considered gone and wiped out -[uwbd calls periodically /uwb/beacon.c:uwb_beca_purge()/ that will purge -the beacon cache of dead devices]. - - -Device lists ------------- - -All UWB devices are kept in the list of the struct bus_type uwb_bus_type. - - -Bandwidth allocation --------------------- - -The UWB stack maintains a local copy of DRP availability through -processing of incoming *DRP Availability Change* notifications. This -local copy is currently used to present the current bandwidth -availability to the user through the sysfs file -/sys/class/uwb_rc/uwbx/bw_avail. In the future the bandwidth -availability information will be used by the bandwidth reservation -routines. - -The bandwidth reservation routines are in progress and are thus not -present in the current release. When completed they will enable a user -to initiate DRP reservation requests through interaction with sysfs. DRP -reservation requests from remote UWB devices will also be handled. The -bandwidth management done by the UWB stack will include callbacks to the -higher layers will enable the higher layers to use the reservations upon -completion. [Note: The bandwidth reservation work is in progress and -subject to change.] - - -Wireless USB Host Controller drivers -==================================== - -*WARNING* This section needs a lot of work! - -As explained above, there are three different types of HCs in the WUSB -world: HWA-HC, DWA-HC and WHCI-HC. - -HWA-HC and DWA-HC share that they are Wire-Adapters (USB or WUSB -connected controllers), and their transfer management system is almost -identical. So is their notification delivery system. - -HWA-HC and WHCI-HC share that they are both WUSB host controllers, so -they have to deal with WUSB device life cycle and maintenance, wireless -root-hub - -HWA exposes a Host Controller interface (HWA-HC 0xe0/02/02). This has -three endpoints (Notifications, Data Transfer In and Data Transfer -Out--known as NEP, DTI and DTO in the code). - -We reserve UWB bandwidth for our Wireless USB Cluster, create a Cluster -ID and tell the HC to use all that. Then we start it. This means the HC -starts sending MMCs. - - * - - The MMCs are blocks of data defined somewhere in the WUSB1.0 spec - that define a stream in the UWB channel time allocated for sending - WUSB IEs (host to device commands/notifications) and Device - Notifications (device initiated to host). Each host defines a - unique Wireless USB cluster through MMCs. Devices can connect to a - single cluster at the time. The IEs are Information Elements, and - among them are the bandwidth allocations that tell each device - when can they transmit or receive. - -Now it all depends on external stimuli. - -New device connection ---------------------- - -A new device pops up, it scans the radio looking for MMCs that give out -the existence of Wireless USB channels. Once one (or more) are found, -selects which one to connect to. Sends a /DN_Connect/ (device -notification connect) during the DNTS (Device Notification Time -Slot--announced in the MMCs - -HC picks the /DN_Connect/ out (nep module sends to notif.c for delivery -into /devconnect/). This process starts the authentication process for -the device. First we allocate a /fake port/ and assign an -unauthenticated address (128 to 255--what we really do is -0x80 | fake_port_idx). We fiddle with the fake port status and /hub_wq/ -sees a new connection, so he moves on to enable the fake port with a reset. - -So now we are in the reset path -- we know we have a non-yet enumerated -device with an unauthorized address; we ask user space to authenticate -(FIXME: not yet done, similar to bluetooth pairing), then we do the key -exchange (FIXME: not yet done) and issue a /set address 0/ to bring the -device to the default state. Device is authenticated. - -From here, the USB stack takes control through the usb_hcd ops. hub_wq -has seen the port status changes, as we have been toggling them. It will -start enumerating and doing transfers through usb_hcd->urb_enqueue() to -read descriptors and move our data. - -Device life cycle and keep alives ---------------------------------- - -Every time there is a successful transfer to/from a device, we update a -per-device activity timestamp. If not, every now and then we check and -if the activity timestamp gets old, we ping the device by sending it a -Keep Alive IE; it responds with a /DN_Alive/ pong during the DNTS (this -arrives to us as a notification through -devconnect.c:wusb_handle_dn_alive(). If a device times out, we -disconnect it from the system (cleaning up internal information and -toggling the bits in the fake hub port, which kicks hub_wq into removing -the rest of the stuff). - -This is done through devconnect:__wusb_check_devs(), which will scan the -device list looking for whom needs refreshing. - -If the device wants to disconnect, it will either die (ugly) or send a -/DN_Disconnect/ that will prompt a disconnection from the system. - -Sending and receiving data --------------------------- - -Data is sent and received through /Remote Pipes/ (rpipes). An rpipe is -/aimed/ at an endpoint in a WUSB device. This is the same for HWAs and -DWAs. - -Each HC has a number of rpipes and buffers that can be assigned to them; -when doing a data transfer (xfer), first the rpipe has to be aimed and -prepared (buffers assigned), then we can start queueing requests for -data in or out. - -Data buffers have to be segmented out before sending--so we send first a -header (segment request) and then if there is any data, a data buffer -immediately after to the DTI interface (yep, even the request). If our -buffer is bigger than the max segment size, then we just do multiple -requests. - -[This sucks, because doing USB scatter gatter in Linux is resource -intensive, if any...not that the current approach is not. It just has to -be cleaned up a lot :)]. - -If reading, we don't send data buffers, just the segment headers saying -we want to read segments. - -When the xfer is executed, we receive a notification that says data is -ready in the DTI endpoint (handled through -xfer.c:wa_handle_notif_xfer()). In there we read from the DTI endpoint a -descriptor that gives us the status of the transfer, its identification -(given when we issued it) and the segment number. If it was a data read, -we issue another URB to read into the destination buffer the chunk of -data coming out of the remote endpoint. Done, wait for the next guy. The -callbacks for the URBs issued from here are the ones that will declare -the xfer complete at some point and call its callback. - -Seems simple, but the implementation is not trivial. - - * - - *WARNING* Old!! - -The main xfer descriptor, wa_xfer (equivalent to a URB) contains an -array of segments, tallys on segments and buffers and callback -information. Buried in there is a lot of URBs for executing the segments -and buffer transfers. - -For OUT xfers, there is an array of segments, one URB for each, another -one of buffer URB. When submitting, we submit URBs for segment request -1, buffer 1, segment 2, buffer 2...etc. Then we wait on the DTI for xfer -result data; when all the segments are complete, we call the callback to -finalize the transfer. - -For IN xfers, we only issue URBs for the segments we want to read and -then wait for the xfer result data. - -URB mapping into xfers -^^^^^^^^^^^^^^^^^^^^^^ - -This is done by hwahc_op_urb_[en|de]queue(). In enqueue() we aim an -rpipe to the endpoint where we have to transmit, create a transfer -context (wa_xfer) and submit it. When the xfer is done, our callback is -called and we assign the status bits and release the xfer resources. - -In dequeue() we are basically cancelling/aborting the transfer. We issue -a xfer abort request to the HC, cancel all the URBs we had submitted -and not yet done and when all that is done, the xfer callback will be -called--this will call the URB callback. - - -Glossary -======== - -*DWA* -- Device Wire Adapter - -USB host, wired for downstream devices, upstream connects wirelessly -with Wireless USB. - -*EVENT* -- Response to a command on the NEEP - -*HWA* -- Host Wire Adapter / USB dongle for UWB and Wireless USB - -*NEH* -- Notification/Event Handle - -Handle/file descriptor for receiving notifications or events. The WA -code requires you to get one of this to listen for notifications or -events on the NEEP. - -*NEEP* -- Notification/Event EndPoint - -Stuff related to the management of the first endpoint of a HWA USB -dongle that is used to deliver an stream of events and notifications to -the host. - -*NOTIFICATION* -- Message coming in the NEEP as response to something. - -*RC* -- Radio Control - -Design-overview.txt-1.8 (last edited 2006-11-04 12:22:24 by -InakyPerezGonzalez) diff --git a/Documentation/usb/acm.rst b/Documentation/usb/acm.rst new file mode 100644 index 000000000000..e8bda98e9b51 --- /dev/null +++ b/Documentation/usb/acm.rst @@ -0,0 +1,132 @@ +====================== +Linux ACM driver v0.16 +====================== + +Copyright (c) 1999 Vojtech Pavlik + +Sponsored by SuSE + +0. Disclaimer +~~~~~~~~~~~~~ +This program is free software; you can redistribute it and/or modify it +under the terms of the GNU General Public License as published by the Free +Software Foundation; either version 2 of the License, or (at your option) +any later version. + +This program is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for +more details. + +You should have received a copy of the GNU General Public License along +with this program; if not, write to the Free Software Foundation, Inc., 59 +Temple Place, Suite 330, Boston, MA 02111-1307 USA + +Should you need to contact me, the author, you can do so either by e-mail - +mail your message to , or by paper mail: Vojtech Pavlik, +Ucitelska 1576, Prague 8, 182 00 Czech Republic + +For your convenience, the GNU General Public License version 2 is included +in the package: See the file COPYING. + +1. Usage +~~~~~~~~ +The drivers/usb/class/cdc-acm.c drivers works with USB modems and USB ISDN terminal +adapters that conform to the Universal Serial Bus Communication Device Class +Abstract Control Model (USB CDC ACM) specification. + +Many modems do, here is a list of those I know of: + + - 3Com OfficeConnect 56k + - 3Com Voice FaxModem Pro + - 3Com Sportster + - MultiTech MultiModem 56k + - Zoom 2986L FaxModem + - Compaq 56k FaxModem + - ELSA Microlink 56k + +I know of one ISDN TA that does work with the acm driver: + + - 3Com USR ISDN Pro TA + +Some cell phones also connect via USB. I know the following phones work: + + - SonyEricsson K800i + +Unfortunately many modems and most ISDN TAs use proprietary interfaces and +thus won't work with this drivers. Check for ACM compliance before buying. + +To use the modems you need these modules loaded:: + + usbcore.ko + uhci-hcd.ko ohci-hcd.ko or ehci-hcd.ko + cdc-acm.ko + +After that, the modem[s] should be accessible. You should be able to use +minicom, ppp and mgetty with them. + +2. Verifying that it works +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The first step would be to check /sys/kernel/debug/usb/devices, it should look +like this:: + + T: Bus=01 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=12 MxCh= 2 + B: Alloc= 0/900 us ( 0%), #Int= 0, #Iso= 0 + D: Ver= 1.00 Cls=09(hub ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 + P: Vendor=0000 ProdID=0000 Rev= 0.00 + S: Product=USB UHCI Root Hub + S: SerialNumber=6800 + C:* #Ifs= 1 Cfg#= 1 Atr=40 MxPwr= 0mA + I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub + E: Ad=81(I) Atr=03(Int.) MxPS= 8 Ivl=255ms + T: Bus=01 Lev=01 Prnt=01 Port=01 Cnt=01 Dev#= 2 Spd=12 MxCh= 0 + D: Ver= 1.00 Cls=02(comm.) Sub=00 Prot=00 MxPS= 8 #Cfgs= 2 + P: Vendor=04c1 ProdID=008f Rev= 2.07 + S: Manufacturer=3Com Inc. + S: Product=3Com U.S. Robotics Pro ISDN TA + S: SerialNumber=UFT53A49BVT7 + C: #Ifs= 1 Cfg#= 1 Atr=60 MxPwr= 0mA + I: If#= 0 Alt= 0 #EPs= 3 Cls=ff(vend.) Sub=ff Prot=ff Driver=acm + E: Ad=85(I) Atr=02(Bulk) MxPS= 64 Ivl= 0ms + E: Ad=04(O) Atr=02(Bulk) MxPS= 64 Ivl= 0ms + E: Ad=81(I) Atr=03(Int.) MxPS= 16 Ivl=128ms + C:* #Ifs= 2 Cfg#= 2 Atr=60 MxPwr= 0mA + I: If#= 0 Alt= 0 #EPs= 1 Cls=02(comm.) Sub=02 Prot=01 Driver=acm + E: Ad=81(I) Atr=03(Int.) MxPS= 16 Ivl=128ms + I: If#= 1 Alt= 0 #EPs= 2 Cls=0a(data ) Sub=00 Prot=00 Driver=acm + E: Ad=85(I) Atr=02(Bulk) MxPS= 64 Ivl= 0ms + E: Ad=04(O) Atr=02(Bulk) MxPS= 64 Ivl= 0ms + +The presence of these three lines (and the Cls= 'comm' and 'data' classes) +is important, it means it's an ACM device. The Driver=acm means the acm +driver is used for the device. If you see only Cls=ff(vend.) then you're out +of luck, you have a device with vendor specific-interface:: + + D: Ver= 1.00 Cls=02(comm.) Sub=00 Prot=00 MxPS= 8 #Cfgs= 2 + I: If#= 0 Alt= 0 #EPs= 1 Cls=02(comm.) Sub=02 Prot=01 Driver=acm + I: If#= 1 Alt= 0 #EPs= 2 Cls=0a(data ) Sub=00 Prot=00 Driver=acm + +In the system log you should see:: + + usb.c: USB new device connect, assigned device number 2 + usb.c: kmalloc IF c7691fa0, numif 1 + usb.c: kmalloc IF c7b5f3e0, numif 2 + usb.c: skipped 4 class/vendor specific interface descriptors + usb.c: new device strings: Mfr=1, Product=2, SerialNumber=3 + usb.c: USB device number 2 default language ID 0x409 + Manufacturer: 3Com Inc. + Product: 3Com U.S. Robotics Pro ISDN TA + SerialNumber: UFT53A49BVT7 + acm.c: probing config 1 + acm.c: probing config 2 + ttyACM0: USB ACM device + acm.c: acm_control_msg: rq: 0x22 val: 0x0 len: 0x0 result: 0 + acm.c: acm_control_msg: rq: 0x20 val: 0x0 len: 0x7 result: 7 + usb.c: acm driver claimed interface c7b5f3e0 + usb.c: acm driver claimed interface c7b5f3f8 + usb.c: acm driver claimed interface c7691fa0 + +If all this seems to be OK, fire up minicom and set it to talk to the ttyACM +device and try typing 'at'. If it responds with 'OK', then everything is +working. diff --git a/Documentation/usb/acm.txt b/Documentation/usb/acm.txt deleted file mode 100644 index e8bda98e9b51..000000000000 --- a/Documentation/usb/acm.txt +++ /dev/null @@ -1,132 +0,0 @@ -====================== -Linux ACM driver v0.16 -====================== - -Copyright (c) 1999 Vojtech Pavlik - -Sponsored by SuSE - -0. Disclaimer -~~~~~~~~~~~~~ -This program is free software; you can redistribute it and/or modify it -under the terms of the GNU General Public License as published by the Free -Software Foundation; either version 2 of the License, or (at your option) -any later version. - -This program is distributed in the hope that it will be useful, but -WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY -or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for -more details. - -You should have received a copy of the GNU General Public License along -with this program; if not, write to the Free Software Foundation, Inc., 59 -Temple Place, Suite 330, Boston, MA 02111-1307 USA - -Should you need to contact me, the author, you can do so either by e-mail - -mail your message to , or by paper mail: Vojtech Pavlik, -Ucitelska 1576, Prague 8, 182 00 Czech Republic - -For your convenience, the GNU General Public License version 2 is included -in the package: See the file COPYING. - -1. Usage -~~~~~~~~ -The drivers/usb/class/cdc-acm.c drivers works with USB modems and USB ISDN terminal -adapters that conform to the Universal Serial Bus Communication Device Class -Abstract Control Model (USB CDC ACM) specification. - -Many modems do, here is a list of those I know of: - - - 3Com OfficeConnect 56k - - 3Com Voice FaxModem Pro - - 3Com Sportster - - MultiTech MultiModem 56k - - Zoom 2986L FaxModem - - Compaq 56k FaxModem - - ELSA Microlink 56k - -I know of one ISDN TA that does work with the acm driver: - - - 3Com USR ISDN Pro TA - -Some cell phones also connect via USB. I know the following phones work: - - - SonyEricsson K800i - -Unfortunately many modems and most ISDN TAs use proprietary interfaces and -thus won't work with this drivers. Check for ACM compliance before buying. - -To use the modems you need these modules loaded:: - - usbcore.ko - uhci-hcd.ko ohci-hcd.ko or ehci-hcd.ko - cdc-acm.ko - -After that, the modem[s] should be accessible. You should be able to use -minicom, ppp and mgetty with them. - -2. Verifying that it works -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The first step would be to check /sys/kernel/debug/usb/devices, it should look -like this:: - - T: Bus=01 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=12 MxCh= 2 - B: Alloc= 0/900 us ( 0%), #Int= 0, #Iso= 0 - D: Ver= 1.00 Cls=09(hub ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 - P: Vendor=0000 ProdID=0000 Rev= 0.00 - S: Product=USB UHCI Root Hub - S: SerialNumber=6800 - C:* #Ifs= 1 Cfg#= 1 Atr=40 MxPwr= 0mA - I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub - E: Ad=81(I) Atr=03(Int.) MxPS= 8 Ivl=255ms - T: Bus=01 Lev=01 Prnt=01 Port=01 Cnt=01 Dev#= 2 Spd=12 MxCh= 0 - D: Ver= 1.00 Cls=02(comm.) Sub=00 Prot=00 MxPS= 8 #Cfgs= 2 - P: Vendor=04c1 ProdID=008f Rev= 2.07 - S: Manufacturer=3Com Inc. - S: Product=3Com U.S. Robotics Pro ISDN TA - S: SerialNumber=UFT53A49BVT7 - C: #Ifs= 1 Cfg#= 1 Atr=60 MxPwr= 0mA - I: If#= 0 Alt= 0 #EPs= 3 Cls=ff(vend.) Sub=ff Prot=ff Driver=acm - E: Ad=85(I) Atr=02(Bulk) MxPS= 64 Ivl= 0ms - E: Ad=04(O) Atr=02(Bulk) MxPS= 64 Ivl= 0ms - E: Ad=81(I) Atr=03(Int.) MxPS= 16 Ivl=128ms - C:* #Ifs= 2 Cfg#= 2 Atr=60 MxPwr= 0mA - I: If#= 0 Alt= 0 #EPs= 1 Cls=02(comm.) Sub=02 Prot=01 Driver=acm - E: Ad=81(I) Atr=03(Int.) MxPS= 16 Ivl=128ms - I: If#= 1 Alt= 0 #EPs= 2 Cls=0a(data ) Sub=00 Prot=00 Driver=acm - E: Ad=85(I) Atr=02(Bulk) MxPS= 64 Ivl= 0ms - E: Ad=04(O) Atr=02(Bulk) MxPS= 64 Ivl= 0ms - -The presence of these three lines (and the Cls= 'comm' and 'data' classes) -is important, it means it's an ACM device. The Driver=acm means the acm -driver is used for the device. If you see only Cls=ff(vend.) then you're out -of luck, you have a device with vendor specific-interface:: - - D: Ver= 1.00 Cls=02(comm.) Sub=00 Prot=00 MxPS= 8 #Cfgs= 2 - I: If#= 0 Alt= 0 #EPs= 1 Cls=02(comm.) Sub=02 Prot=01 Driver=acm - I: If#= 1 Alt= 0 #EPs= 2 Cls=0a(data ) Sub=00 Prot=00 Driver=acm - -In the system log you should see:: - - usb.c: USB new device connect, assigned device number 2 - usb.c: kmalloc IF c7691fa0, numif 1 - usb.c: kmalloc IF c7b5f3e0, numif 2 - usb.c: skipped 4 class/vendor specific interface descriptors - usb.c: new device strings: Mfr=1, Product=2, SerialNumber=3 - usb.c: USB device number 2 default language ID 0x409 - Manufacturer: 3Com Inc. - Product: 3Com U.S. Robotics Pro ISDN TA - SerialNumber: UFT53A49BVT7 - acm.c: probing config 1 - acm.c: probing config 2 - ttyACM0: USB ACM device - acm.c: acm_control_msg: rq: 0x22 val: 0x0 len: 0x0 result: 0 - acm.c: acm_control_msg: rq: 0x20 val: 0x0 len: 0x7 result: 7 - usb.c: acm driver claimed interface c7b5f3e0 - usb.c: acm driver claimed interface c7b5f3f8 - usb.c: acm driver claimed interface c7691fa0 - -If all this seems to be OK, fire up minicom and set it to talk to the ttyACM -device and try typing 'at'. If it responds with 'OK', then everything is -working. diff --git a/Documentation/usb/authorization.rst b/Documentation/usb/authorization.rst new file mode 100644 index 000000000000..9e53909d04c2 --- /dev/null +++ b/Documentation/usb/authorization.rst @@ -0,0 +1,132 @@ +============================================================== +Authorizing (or not) your USB devices to connect to the system +============================================================== + +Copyright (C) 2007 Inaky Perez-Gonzalez Intel Corporation + +This feature allows you to control if a USB device can be used (or +not) in a system. This feature will allow you to implement a lock-down +of USB devices, fully controlled by user space. + +As of now, when a USB device is connected it is configured and +its interfaces are immediately made available to the users. With this +modification, only if root authorizes the device to be configured will +then it be possible to use it. + +Usage +===== + +Authorize a device to connect:: + + $ echo 1 > /sys/bus/usb/devices/DEVICE/authorized + +De-authorize a device:: + + $ echo 0 > /sys/bus/usb/devices/DEVICE/authorized + +Set new devices connected to hostX to be deauthorized by default (ie: +lock down):: + + $ echo 0 > /sys/bus/usb/devices/usbX/authorized_default + +Remove the lock down:: + + $ echo 1 > /sys/bus/usb/devices/usbX/authorized_default + +By default, Wired USB devices are authorized by default to +connect. Wireless USB hosts deauthorize by default all new connected +devices (this is so because we need to do an authentication phase +before authorizing). Writing "2" to the authorized_default attribute +causes kernel to only authorize by default devices connected to internal +USB ports. + + +Example system lockdown (lame) +------------------------------ + +Imagine you want to implement a lockdown so only devices of type XYZ +can be connected (for example, it is a kiosk machine with a visible +USB port):: + + boot up + rc.local -> + + for host in /sys/bus/usb/devices/usb* + do + echo 0 > $host/authorized_default + done + +Hookup an script to udev, for new USB devices:: + + if device_is_my_type $DEV + then + echo 1 > $device_path/authorized + done + + +Now, device_is_my_type() is where the juice for a lockdown is. Just +checking if the class, type and protocol match something is the worse +security verification you can make (or the best, for someone willing +to break it). If you need something secure, use crypto and Certificate +Authentication or stuff like that. Something simple for an storage key +could be:: + + function device_is_my_type() + { + echo 1 > authorized # temporarily authorize it + # FIXME: make sure none can mount it + mount DEVICENODE /mntpoint + sum=$(md5sum /mntpoint/.signature) + if [ $sum = $(cat /etc/lockdown/keysum) ] + then + echo "We are good, connected" + umount /mntpoint + # Other stuff so others can use it + else + echo 0 > authorized + fi + } + + +Of course, this is lame, you'd want to do a real certificate +verification stuff with PKI, so you don't depend on a shared secret, +etc, but you get the idea. Anybody with access to a device gadget kit +can fake descriptors and device info. Don't trust that. You are +welcome. + + +Interface authorization +----------------------- + +There is a similar approach to allow or deny specific USB interfaces. +That allows to block only a subset of an USB device. + +Authorize an interface:: + + $ echo 1 > /sys/bus/usb/devices/INTERFACE/authorized + +Deauthorize an interface:: + + $ echo 0 > /sys/bus/usb/devices/INTERFACE/authorized + +The default value for new interfaces +on a particular USB bus can be changed, too. + +Allow interfaces per default:: + + $ echo 1 > /sys/bus/usb/devices/usbX/interface_authorized_default + +Deny interfaces per default:: + + $ echo 0 > /sys/bus/usb/devices/usbX/interface_authorized_default + +Per default the interface_authorized_default bit is 1. +So all interfaces would authorized per default. + +Note: + If a deauthorized interface will be authorized so the driver probing must + be triggered manually by writing INTERFACE to /sys/bus/usb/drivers_probe + +For drivers that need multiple interfaces all needed interfaces should be +authorized first. After that the drivers should be probed. +This avoids side effects. diff --git a/Documentation/usb/authorization.txt b/Documentation/usb/authorization.txt deleted file mode 100644 index 9e53909d04c2..000000000000 --- a/Documentation/usb/authorization.txt +++ /dev/null @@ -1,132 +0,0 @@ -============================================================== -Authorizing (or not) your USB devices to connect to the system -============================================================== - -Copyright (C) 2007 Inaky Perez-Gonzalez Intel Corporation - -This feature allows you to control if a USB device can be used (or -not) in a system. This feature will allow you to implement a lock-down -of USB devices, fully controlled by user space. - -As of now, when a USB device is connected it is configured and -its interfaces are immediately made available to the users. With this -modification, only if root authorizes the device to be configured will -then it be possible to use it. - -Usage -===== - -Authorize a device to connect:: - - $ echo 1 > /sys/bus/usb/devices/DEVICE/authorized - -De-authorize a device:: - - $ echo 0 > /sys/bus/usb/devices/DEVICE/authorized - -Set new devices connected to hostX to be deauthorized by default (ie: -lock down):: - - $ echo 0 > /sys/bus/usb/devices/usbX/authorized_default - -Remove the lock down:: - - $ echo 1 > /sys/bus/usb/devices/usbX/authorized_default - -By default, Wired USB devices are authorized by default to -connect. Wireless USB hosts deauthorize by default all new connected -devices (this is so because we need to do an authentication phase -before authorizing). Writing "2" to the authorized_default attribute -causes kernel to only authorize by default devices connected to internal -USB ports. - - -Example system lockdown (lame) ------------------------------- - -Imagine you want to implement a lockdown so only devices of type XYZ -can be connected (for example, it is a kiosk machine with a visible -USB port):: - - boot up - rc.local -> - - for host in /sys/bus/usb/devices/usb* - do - echo 0 > $host/authorized_default - done - -Hookup an script to udev, for new USB devices:: - - if device_is_my_type $DEV - then - echo 1 > $device_path/authorized - done - - -Now, device_is_my_type() is where the juice for a lockdown is. Just -checking if the class, type and protocol match something is the worse -security verification you can make (or the best, for someone willing -to break it). If you need something secure, use crypto and Certificate -Authentication or stuff like that. Something simple for an storage key -could be:: - - function device_is_my_type() - { - echo 1 > authorized # temporarily authorize it - # FIXME: make sure none can mount it - mount DEVICENODE /mntpoint - sum=$(md5sum /mntpoint/.signature) - if [ $sum = $(cat /etc/lockdown/keysum) ] - then - echo "We are good, connected" - umount /mntpoint - # Other stuff so others can use it - else - echo 0 > authorized - fi - } - - -Of course, this is lame, you'd want to do a real certificate -verification stuff with PKI, so you don't depend on a shared secret, -etc, but you get the idea. Anybody with access to a device gadget kit -can fake descriptors and device info. Don't trust that. You are -welcome. - - -Interface authorization ------------------------ - -There is a similar approach to allow or deny specific USB interfaces. -That allows to block only a subset of an USB device. - -Authorize an interface:: - - $ echo 1 > /sys/bus/usb/devices/INTERFACE/authorized - -Deauthorize an interface:: - - $ echo 0 > /sys/bus/usb/devices/INTERFACE/authorized - -The default value for new interfaces -on a particular USB bus can be changed, too. - -Allow interfaces per default:: - - $ echo 1 > /sys/bus/usb/devices/usbX/interface_authorized_default - -Deny interfaces per default:: - - $ echo 0 > /sys/bus/usb/devices/usbX/interface_authorized_default - -Per default the interface_authorized_default bit is 1. -So all interfaces would authorized per default. - -Note: - If a deauthorized interface will be authorized so the driver probing must - be triggered manually by writing INTERFACE to /sys/bus/usb/drivers_probe - -For drivers that need multiple interfaces all needed interfaces should be -authorized first. After that the drivers should be probed. -This avoids side effects. diff --git a/Documentation/usb/chipidea.rst b/Documentation/usb/chipidea.rst new file mode 100644 index 000000000000..68473abe2823 --- /dev/null +++ b/Documentation/usb/chipidea.rst @@ -0,0 +1,133 @@ +============================================== +ChipIdea Highspeed Dual Role Controller Driver +============================================== + +1. How to test OTG FSM(HNP and SRP) +----------------------------------- + +To show how to demo OTG HNP and SRP functions via sys input files +with 2 Freescale i.MX6Q sabre SD boards. + +1.1 How to enable OTG FSM +------------------------- + +1.1.1 Select CONFIG_USB_OTG_FSM in menuconfig, rebuild kernel +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Image and modules. If you want to check some internal +variables for otg fsm, mount debugfs, there are 2 files +which can show otg fsm variables and some controller registers value:: + + cat /sys/kernel/debug/ci_hdrc.0/otg + cat /sys/kernel/debug/ci_hdrc.0/registers + +1.1.2 Add below entries in your dts file for your controller node +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + otg-rev = <0x0200>; + adp-disable; + +1.2 Test operations +------------------- + +1) Power up 2 Freescale i.MX6Q sabre SD boards with gadget class driver loaded + (e.g. g_mass_storage). + +2) Connect 2 boards with usb cable with one end is micro A plug, the other end + is micro B plug. + + The A-device(with micro A plug inserted) should enumerate B-device. + +3) Role switch + + On B-device:: + + echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req + + B-device should take host role and enumerate A-device. + +4) A-device switch back to host. + + On B-device:: + + echo 0 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req + + or, by introducing HNP polling, B-Host can know when A-peripheral wish + to be host role, so this role switch also can be trigged in A-peripheral + side by answering the polling from B-Host, this can be done on A-device:: + + echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_req + + A-device should switch back to host and enumerate B-device. + +5) Remove B-device(unplug micro B plug) and insert again in 10 seconds, + A-device should enumerate B-device again. + +6) Remove B-device(unplug micro B plug) and insert again after 10 seconds, + A-device should NOT enumerate B-device. + + if A-device wants to use bus: + + On A-device:: + + echo 0 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_drop + echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_req + + if B-device wants to use bus: + + On B-device:: + + echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req + +7) A-device power down the bus. + + On A-device:: + + echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_drop + + A-device should disconnect with B-device and power down the bus. + +8) B-device does data pulse for SRP. + + On B-device:: + + echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req + + A-device should resume usb bus and enumerate B-device. + +1.3 Reference document +---------------------- +"On-The-Go and Embedded Host Supplement to the USB Revision 2.0 Specification +July 27, 2012 Revision 2.0 version 1.1a" + +2. How to enable USB as system wakeup source +-------------------------------------------- +Below is the example for how to enable USB as system wakeup source +at imx6 platform. + +2.1 Enable core's wakeup:: + + echo enabled > /sys/bus/platform/devices/ci_hdrc.0/power/wakeup + +2.2 Enable glue layer's wakeup:: + + echo enabled > /sys/bus/platform/devices/2184000.usb/power/wakeup + +2.3 Enable PHY's wakeup (optional):: + + echo enabled > /sys/bus/platform/devices/20c9000.usbphy/power/wakeup + +2.4 Enable roothub's wakeup:: + + echo enabled > /sys/bus/usb/devices/usb1/power/wakeup + +2.5 Enable related device's wakeup:: + + echo enabled > /sys/bus/usb/devices/1-1/power/wakeup + +If the system has only one usb port, and you want usb wakeup at this port, you +can use below script to enable usb wakeup:: + + for i in $(find /sys -name wakeup | grep usb);do echo enabled > $i;done; diff --git a/Documentation/usb/chipidea.txt b/Documentation/usb/chipidea.txt deleted file mode 100644 index 68473abe2823..000000000000 --- a/Documentation/usb/chipidea.txt +++ /dev/null @@ -1,133 +0,0 @@ -============================================== -ChipIdea Highspeed Dual Role Controller Driver -============================================== - -1. How to test OTG FSM(HNP and SRP) ------------------------------------ - -To show how to demo OTG HNP and SRP functions via sys input files -with 2 Freescale i.MX6Q sabre SD boards. - -1.1 How to enable OTG FSM -------------------------- - -1.1.1 Select CONFIG_USB_OTG_FSM in menuconfig, rebuild kernel -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Image and modules. If you want to check some internal -variables for otg fsm, mount debugfs, there are 2 files -which can show otg fsm variables and some controller registers value:: - - cat /sys/kernel/debug/ci_hdrc.0/otg - cat /sys/kernel/debug/ci_hdrc.0/registers - -1.1.2 Add below entries in your dts file for your controller node -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -:: - - otg-rev = <0x0200>; - adp-disable; - -1.2 Test operations -------------------- - -1) Power up 2 Freescale i.MX6Q sabre SD boards with gadget class driver loaded - (e.g. g_mass_storage). - -2) Connect 2 boards with usb cable with one end is micro A plug, the other end - is micro B plug. - - The A-device(with micro A plug inserted) should enumerate B-device. - -3) Role switch - - On B-device:: - - echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req - - B-device should take host role and enumerate A-device. - -4) A-device switch back to host. - - On B-device:: - - echo 0 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req - - or, by introducing HNP polling, B-Host can know when A-peripheral wish - to be host role, so this role switch also can be trigged in A-peripheral - side by answering the polling from B-Host, this can be done on A-device:: - - echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_req - - A-device should switch back to host and enumerate B-device. - -5) Remove B-device(unplug micro B plug) and insert again in 10 seconds, - A-device should enumerate B-device again. - -6) Remove B-device(unplug micro B plug) and insert again after 10 seconds, - A-device should NOT enumerate B-device. - - if A-device wants to use bus: - - On A-device:: - - echo 0 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_drop - echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_req - - if B-device wants to use bus: - - On B-device:: - - echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req - -7) A-device power down the bus. - - On A-device:: - - echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_drop - - A-device should disconnect with B-device and power down the bus. - -8) B-device does data pulse for SRP. - - On B-device:: - - echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req - - A-device should resume usb bus and enumerate B-device. - -1.3 Reference document ----------------------- -"On-The-Go and Embedded Host Supplement to the USB Revision 2.0 Specification -July 27, 2012 Revision 2.0 version 1.1a" - -2. How to enable USB as system wakeup source --------------------------------------------- -Below is the example for how to enable USB as system wakeup source -at imx6 platform. - -2.1 Enable core's wakeup:: - - echo enabled > /sys/bus/platform/devices/ci_hdrc.0/power/wakeup - -2.2 Enable glue layer's wakeup:: - - echo enabled > /sys/bus/platform/devices/2184000.usb/power/wakeup - -2.3 Enable PHY's wakeup (optional):: - - echo enabled > /sys/bus/platform/devices/20c9000.usbphy/power/wakeup - -2.4 Enable roothub's wakeup:: - - echo enabled > /sys/bus/usb/devices/usb1/power/wakeup - -2.5 Enable related device's wakeup:: - - echo enabled > /sys/bus/usb/devices/1-1/power/wakeup - -If the system has only one usb port, and you want usb wakeup at this port, you -can use below script to enable usb wakeup:: - - for i in $(find /sys -name wakeup | grep usb);do echo enabled > $i;done; diff --git a/Documentation/usb/dwc3.rst b/Documentation/usb/dwc3.rst new file mode 100644 index 000000000000..f94a7ba16573 --- /dev/null +++ b/Documentation/usb/dwc3.rst @@ -0,0 +1,53 @@ +=========== +DWC3 driver +=========== + + +TODO +~~~~ + +Please pick something while reading :) + +- Convert interrupt handler to per-ep-thread-irq + + As it turns out some DWC3-commands ~1ms to complete. Currently we spin + until the command completes which is bad. + + Implementation idea: + + - dwc core implements a demultiplexing irq chip for interrupts per + endpoint. The interrupt numbers are allocated during probe and belong + to the device. If MSI provides per-endpoint interrupt this dummy + interrupt chip can be replaced with "real" interrupts. + - interrupts are requested / allocated on usb_ep_enable() and removed on + usb_ep_disable(). Worst case are 32 interrupts, the lower limit is two + for ep0/1. + - dwc3_send_gadget_ep_cmd() will sleep in wait_for_completion_timeout() + until the command completes. + - the interrupt handler is split into the following pieces: + + - primary handler of the device + goes through every event and calls generic_handle_irq() for event + it. On return from generic_handle_irq() in acknowledges the event + counter so interrupt goes away (eventually). + + - threaded handler of the device + none + + - primary handler of the EP-interrupt + reads the event and tries to process it. Everything that requires + sleeping is handed over to the Thread. The event is saved in an + per-endpoint data-structure. + We probably have to pay attention not to process events once we + handed something to thread so we don't process event X prio Y + where X > Y. + + - threaded handler of the EP-interrupt + handles the remaining EP work which might sleep such as waiting + for command completion. + + Latency: + + There should be no increase in latency since the interrupt-thread has a + high priority and will be run before an average task in user land + (except the user changed priorities). diff --git a/Documentation/usb/dwc3.txt b/Documentation/usb/dwc3.txt deleted file mode 100644 index f94a7ba16573..000000000000 --- a/Documentation/usb/dwc3.txt +++ /dev/null @@ -1,53 +0,0 @@ -=========== -DWC3 driver -=========== - - -TODO -~~~~ - -Please pick something while reading :) - -- Convert interrupt handler to per-ep-thread-irq - - As it turns out some DWC3-commands ~1ms to complete. Currently we spin - until the command completes which is bad. - - Implementation idea: - - - dwc core implements a demultiplexing irq chip for interrupts per - endpoint. The interrupt numbers are allocated during probe and belong - to the device. If MSI provides per-endpoint interrupt this dummy - interrupt chip can be replaced with "real" interrupts. - - interrupts are requested / allocated on usb_ep_enable() and removed on - usb_ep_disable(). Worst case are 32 interrupts, the lower limit is two - for ep0/1. - - dwc3_send_gadget_ep_cmd() will sleep in wait_for_completion_timeout() - until the command completes. - - the interrupt handler is split into the following pieces: - - - primary handler of the device - goes through every event and calls generic_handle_irq() for event - it. On return from generic_handle_irq() in acknowledges the event - counter so interrupt goes away (eventually). - - - threaded handler of the device - none - - - primary handler of the EP-interrupt - reads the event and tries to process it. Everything that requires - sleeping is handed over to the Thread. The event is saved in an - per-endpoint data-structure. - We probably have to pay attention not to process events once we - handed something to thread so we don't process event X prio Y - where X > Y. - - - threaded handler of the EP-interrupt - handles the remaining EP work which might sleep such as waiting - for command completion. - - Latency: - - There should be no increase in latency since the interrupt-thread has a - high priority and will be run before an average task in user land - (except the user changed priorities). diff --git a/Documentation/usb/ehci.rst b/Documentation/usb/ehci.rst new file mode 100644 index 000000000000..31f650e7c1b4 --- /dev/null +++ b/Documentation/usb/ehci.rst @@ -0,0 +1,230 @@ +=========== +EHCI driver +=========== + +27-Dec-2002 + +The EHCI driver is used to talk to high speed USB 2.0 devices using +USB 2.0-capable host controller hardware. The USB 2.0 standard is +compatible with the USB 1.1 standard. It defines three transfer speeds: + + - "High Speed" 480 Mbit/sec (60 MByte/sec) + - "Full Speed" 12 Mbit/sec (1.5 MByte/sec) + - "Low Speed" 1.5 Mbit/sec + +USB 1.1 only addressed full speed and low speed. High speed devices +can be used on USB 1.1 systems, but they slow down to USB 1.1 speeds. + +USB 1.1 devices may also be used on USB 2.0 systems. When plugged +into an EHCI controller, they are given to a USB 1.1 "companion" +controller, which is a OHCI or UHCI controller as normally used with +such devices. When USB 1.1 devices plug into USB 2.0 hubs, they +interact with the EHCI controller through a "Transaction Translator" +(TT) in the hub, which turns low or full speed transactions into +high speed "split transactions" that don't waste transfer bandwidth. + +At this writing, this driver has been seen to work with implementations +of EHCI from (in alphabetical order): Intel, NEC, Philips, and VIA. +Other EHCI implementations are becoming available from other vendors; +you should expect this driver to work with them too. + +While usb-storage devices have been available since mid-2001 (working +quite speedily on the 2.4 version of this driver), hubs have only +been available since late 2001, and other kinds of high speed devices +appear to be on hold until more systems come with USB 2.0 built-in. +Such new systems have been available since early 2002, and became much +more typical in the second half of 2002. + +Note that USB 2.0 support involves more than just EHCI. It requires +other changes to the Linux-USB core APIs, including the hub driver, +but those changes haven't needed to really change the basic "usbcore" +APIs exposed to USB device drivers. + +- David Brownell + + + +Functionality +============= + +This driver is regularly tested on x86 hardware, and has also been +used on PPC hardware so big/little endianness issues should be gone. +It's believed to do all the right PCI magic so that I/O works even on +systems with interesting DMA mapping issues. + +Transfer Types +-------------- + +At this writing the driver should comfortably handle all control, bulk, +and interrupt transfers, including requests to USB 1.1 devices through +transaction translators (TTs) in USB 2.0 hubs. But you may find bugs. + +High Speed Isochronous (ISO) transfer support is also functional, but +at this writing no Linux drivers have been using that support. + +Full Speed Isochronous transfer support, through transaction translators, +is not yet available. Note that split transaction support for ISO +transfers can't share much code with the code for high speed ISO transfers, +since EHCI represents these with a different data structure. So for now, +most USB audio and video devices can't be connected to high speed buses. + +Driver Behavior +--------------- + +Transfers of all types can be queued. This means that control transfers +from a driver on one interface (or through usbfs) won't interfere with +ones from another driver, and that interrupt transfers can use periods +of one frame without risking data loss due to interrupt processing costs. + +The EHCI root hub code hands off USB 1.1 devices to its companion +controller. This driver doesn't need to know anything about those +drivers; a OHCI or UHCI driver that works already doesn't need to change +just because the EHCI driver is also present. + +There are some issues with power management; suspend/resume doesn't +behave quite right at the moment. + +Also, some shortcuts have been taken with the scheduling periodic +transactions (interrupt and isochronous transfers). These place some +limits on the number of periodic transactions that can be scheduled, +and prevent use of polling intervals of less than one frame. + + +Use by +====== + +Assuming you have an EHCI controller (on a PCI card or motherboard) +and have compiled this driver as a module, load this like:: + + # modprobe ehci-hcd + +and remove it by:: + + # rmmod ehci-hcd + +You should also have a driver for a "companion controller", such as +"ohci-hcd" or "uhci-hcd". In case of any trouble with the EHCI driver, +remove its module and then the driver for that companion controller will +take over (at lower speed) all the devices that were previously handled +by the EHCI driver. + +Module parameters (pass to "modprobe") include: + + log2_irq_thresh (default 0): + Log2 of default interrupt delay, in microframes. The default + value is 0, indicating 1 microframe (125 usec). Maximum value + is 6, indicating 2^6 = 64 microframes. This controls how often + the EHCI controller can issue interrupts. + +If you're using this driver on a 2.5 kernel, and you've enabled USB +debugging support, you'll see three files in the "sysfs" directory for +any EHCI controller: + + "async" + dumps the asynchronous schedule, used for control + and bulk transfers. Shows each active qh and the qtds + pending, usually one qtd per urb. (Look at it with + usb-storage doing disk I/O; watch the request queues!) + "periodic" + dumps the periodic schedule, used for interrupt + and isochronous transfers. Doesn't show qtds. + "registers" + show controller register state, and + +The contents of those files can help identify driver problems. + + +Device drivers shouldn't care whether they're running over EHCI or not, +but they may want to check for "usb_device->speed == USB_SPEED_HIGH". +High speed devices can do things that full speed (or low speed) ones +can't, such as "high bandwidth" periodic (interrupt or ISO) transfers. +Also, some values in device descriptors (such as polling intervals for +periodic transfers) use different encodings when operating at high speed. + +However, do make a point of testing device drivers through USB 2.0 hubs. +Those hubs report some failures, such as disconnections, differently when +transaction translators are in use; some drivers have been seen to behave +badly when they see different faults than OHCI or UHCI report. + + +Performance +=========== + +USB 2.0 throughput is gated by two main factors: how fast the host +controller can process requests, and how fast devices can respond to +them. The 480 Mbit/sec "raw transfer rate" is obeyed by all devices, +but aggregate throughput is also affected by issues like delays between +individual high speed packets, driver intelligence, and of course the +overall system load. Latency is also a performance concern. + +Bulk transfers are most often used where throughput is an issue. It's +good to keep in mind that bulk transfers are always in 512 byte packets, +and at most 13 of those fit into one USB 2.0 microframe. Eight USB 2.0 +microframes fit in a USB 1.1 frame; a microframe is 1 msec/8 = 125 usec. + +So more than 50 MByte/sec is available for bulk transfers, when both +hardware and device driver software allow it. Periodic transfer modes +(isochronous and interrupt) allow the larger packet sizes which let you +approach the quoted 480 MBit/sec transfer rate. + +Hardware Performance +-------------------- + +At this writing, individual USB 2.0 devices tend to max out at around +20 MByte/sec transfer rates. This is of course subject to change; +and some devices now go faster, while others go slower. + +The first NEC implementation of EHCI seems to have a hardware bottleneck +at around 28 MByte/sec aggregate transfer rate. While this is clearly +enough for a single device at 20 MByte/sec, putting three such devices +onto one bus does not get you 60 MByte/sec. The issue appears to be +that the controller hardware won't do concurrent USB and PCI access, +so that it's only trying six (or maybe seven) USB transactions each +microframe rather than thirteen. (Seems like a reasonable trade off +for a product that beat all the others to market by over a year!) + +It's expected that newer implementations will better this, throwing +more silicon real estate at the problem so that new motherboard chip +sets will get closer to that 60 MByte/sec target. That includes an +updated implementation from NEC, as well as other vendors' silicon. + +There's a minimum latency of one microframe (125 usec) for the host +to receive interrupts from the EHCI controller indicating completion +of requests. That latency is tunable; there's a module option. By +default ehci-hcd driver uses the minimum latency, which means that if +you issue a control or bulk request you can often expect to learn that +it completed in less than 250 usec (depending on transfer size). + +Software Performance +-------------------- + +To get even 20 MByte/sec transfer rates, Linux-USB device drivers will +need to keep the EHCI queue full. That means issuing large requests, +or using bulk queuing if a series of small requests needs to be issued. +When drivers don't do that, their performance results will show it. + +In typical situations, a usb_bulk_msg() loop writing out 4 KB chunks is +going to waste more than half the USB 2.0 bandwidth. Delays between the +I/O completion and the driver issuing the next request will take longer +than the I/O. If that same loop used 16 KB chunks, it'd be better; a +sequence of 128 KB chunks would waste a lot less. + +But rather than depending on such large I/O buffers to make synchronous +I/O be efficient, it's better to just queue up several (bulk) requests +to the HC, and wait for them all to complete (or be canceled on error). +Such URB queuing should work with all the USB 1.1 HC drivers too. + +In the Linux 2.5 kernels, new usb_sg_*() api calls have been defined; they +queue all the buffers from a scatterlist. They also use scatterlist DMA +mapping (which might apply an IOMMU) and IRQ reduction, all of which will +help make high speed transfers run as fast as they can. + + +TBD: + Interrupt and ISO transfer performance issues. Those periodic + transfers are fully scheduled, so the main issue is likely to be how + to trigger "high bandwidth" modes. + +TBD: + More than standard 80% periodic bandwidth allocation is possible + through sysfs uframe_periodic_max parameter. Describe that. diff --git a/Documentation/usb/ehci.txt b/Documentation/usb/ehci.txt deleted file mode 100644 index 31f650e7c1b4..000000000000 --- a/Documentation/usb/ehci.txt +++ /dev/null @@ -1,230 +0,0 @@ -=========== -EHCI driver -=========== - -27-Dec-2002 - -The EHCI driver is used to talk to high speed USB 2.0 devices using -USB 2.0-capable host controller hardware. The USB 2.0 standard is -compatible with the USB 1.1 standard. It defines three transfer speeds: - - - "High Speed" 480 Mbit/sec (60 MByte/sec) - - "Full Speed" 12 Mbit/sec (1.5 MByte/sec) - - "Low Speed" 1.5 Mbit/sec - -USB 1.1 only addressed full speed and low speed. High speed devices -can be used on USB 1.1 systems, but they slow down to USB 1.1 speeds. - -USB 1.1 devices may also be used on USB 2.0 systems. When plugged -into an EHCI controller, they are given to a USB 1.1 "companion" -controller, which is a OHCI or UHCI controller as normally used with -such devices. When USB 1.1 devices plug into USB 2.0 hubs, they -interact with the EHCI controller through a "Transaction Translator" -(TT) in the hub, which turns low or full speed transactions into -high speed "split transactions" that don't waste transfer bandwidth. - -At this writing, this driver has been seen to work with implementations -of EHCI from (in alphabetical order): Intel, NEC, Philips, and VIA. -Other EHCI implementations are becoming available from other vendors; -you should expect this driver to work with them too. - -While usb-storage devices have been available since mid-2001 (working -quite speedily on the 2.4 version of this driver), hubs have only -been available since late 2001, and other kinds of high speed devices -appear to be on hold until more systems come with USB 2.0 built-in. -Such new systems have been available since early 2002, and became much -more typical in the second half of 2002. - -Note that USB 2.0 support involves more than just EHCI. It requires -other changes to the Linux-USB core APIs, including the hub driver, -but those changes haven't needed to really change the basic "usbcore" -APIs exposed to USB device drivers. - -- David Brownell - - - -Functionality -============= - -This driver is regularly tested on x86 hardware, and has also been -used on PPC hardware so big/little endianness issues should be gone. -It's believed to do all the right PCI magic so that I/O works even on -systems with interesting DMA mapping issues. - -Transfer Types --------------- - -At this writing the driver should comfortably handle all control, bulk, -and interrupt transfers, including requests to USB 1.1 devices through -transaction translators (TTs) in USB 2.0 hubs. But you may find bugs. - -High Speed Isochronous (ISO) transfer support is also functional, but -at this writing no Linux drivers have been using that support. - -Full Speed Isochronous transfer support, through transaction translators, -is not yet available. Note that split transaction support for ISO -transfers can't share much code with the code for high speed ISO transfers, -since EHCI represents these with a different data structure. So for now, -most USB audio and video devices can't be connected to high speed buses. - -Driver Behavior ---------------- - -Transfers of all types can be queued. This means that control transfers -from a driver on one interface (or through usbfs) won't interfere with -ones from another driver, and that interrupt transfers can use periods -of one frame without risking data loss due to interrupt processing costs. - -The EHCI root hub code hands off USB 1.1 devices to its companion -controller. This driver doesn't need to know anything about those -drivers; a OHCI or UHCI driver that works already doesn't need to change -just because the EHCI driver is also present. - -There are some issues with power management; suspend/resume doesn't -behave quite right at the moment. - -Also, some shortcuts have been taken with the scheduling periodic -transactions (interrupt and isochronous transfers). These place some -limits on the number of periodic transactions that can be scheduled, -and prevent use of polling intervals of less than one frame. - - -Use by -====== - -Assuming you have an EHCI controller (on a PCI card or motherboard) -and have compiled this driver as a module, load this like:: - - # modprobe ehci-hcd - -and remove it by:: - - # rmmod ehci-hcd - -You should also have a driver for a "companion controller", such as -"ohci-hcd" or "uhci-hcd". In case of any trouble with the EHCI driver, -remove its module and then the driver for that companion controller will -take over (at lower speed) all the devices that were previously handled -by the EHCI driver. - -Module parameters (pass to "modprobe") include: - - log2_irq_thresh (default 0): - Log2 of default interrupt delay, in microframes. The default - value is 0, indicating 1 microframe (125 usec). Maximum value - is 6, indicating 2^6 = 64 microframes. This controls how often - the EHCI controller can issue interrupts. - -If you're using this driver on a 2.5 kernel, and you've enabled USB -debugging support, you'll see three files in the "sysfs" directory for -any EHCI controller: - - "async" - dumps the asynchronous schedule, used for control - and bulk transfers. Shows each active qh and the qtds - pending, usually one qtd per urb. (Look at it with - usb-storage doing disk I/O; watch the request queues!) - "periodic" - dumps the periodic schedule, used for interrupt - and isochronous transfers. Doesn't show qtds. - "registers" - show controller register state, and - -The contents of those files can help identify driver problems. - - -Device drivers shouldn't care whether they're running over EHCI or not, -but they may want to check for "usb_device->speed == USB_SPEED_HIGH". -High speed devices can do things that full speed (or low speed) ones -can't, such as "high bandwidth" periodic (interrupt or ISO) transfers. -Also, some values in device descriptors (such as polling intervals for -periodic transfers) use different encodings when operating at high speed. - -However, do make a point of testing device drivers through USB 2.0 hubs. -Those hubs report some failures, such as disconnections, differently when -transaction translators are in use; some drivers have been seen to behave -badly when they see different faults than OHCI or UHCI report. - - -Performance -=========== - -USB 2.0 throughput is gated by two main factors: how fast the host -controller can process requests, and how fast devices can respond to -them. The 480 Mbit/sec "raw transfer rate" is obeyed by all devices, -but aggregate throughput is also affected by issues like delays between -individual high speed packets, driver intelligence, and of course the -overall system load. Latency is also a performance concern. - -Bulk transfers are most often used where throughput is an issue. It's -good to keep in mind that bulk transfers are always in 512 byte packets, -and at most 13 of those fit into one USB 2.0 microframe. Eight USB 2.0 -microframes fit in a USB 1.1 frame; a microframe is 1 msec/8 = 125 usec. - -So more than 50 MByte/sec is available for bulk transfers, when both -hardware and device driver software allow it. Periodic transfer modes -(isochronous and interrupt) allow the larger packet sizes which let you -approach the quoted 480 MBit/sec transfer rate. - -Hardware Performance --------------------- - -At this writing, individual USB 2.0 devices tend to max out at around -20 MByte/sec transfer rates. This is of course subject to change; -and some devices now go faster, while others go slower. - -The first NEC implementation of EHCI seems to have a hardware bottleneck -at around 28 MByte/sec aggregate transfer rate. While this is clearly -enough for a single device at 20 MByte/sec, putting three such devices -onto one bus does not get you 60 MByte/sec. The issue appears to be -that the controller hardware won't do concurrent USB and PCI access, -so that it's only trying six (or maybe seven) USB transactions each -microframe rather than thirteen. (Seems like a reasonable trade off -for a product that beat all the others to market by over a year!) - -It's expected that newer implementations will better this, throwing -more silicon real estate at the problem so that new motherboard chip -sets will get closer to that 60 MByte/sec target. That includes an -updated implementation from NEC, as well as other vendors' silicon. - -There's a minimum latency of one microframe (125 usec) for the host -to receive interrupts from the EHCI controller indicating completion -of requests. That latency is tunable; there's a module option. By -default ehci-hcd driver uses the minimum latency, which means that if -you issue a control or bulk request you can often expect to learn that -it completed in less than 250 usec (depending on transfer size). - -Software Performance --------------------- - -To get even 20 MByte/sec transfer rates, Linux-USB device drivers will -need to keep the EHCI queue full. That means issuing large requests, -or using bulk queuing if a series of small requests needs to be issued. -When drivers don't do that, their performance results will show it. - -In typical situations, a usb_bulk_msg() loop writing out 4 KB chunks is -going to waste more than half the USB 2.0 bandwidth. Delays between the -I/O completion and the driver issuing the next request will take longer -than the I/O. If that same loop used 16 KB chunks, it'd be better; a -sequence of 128 KB chunks would waste a lot less. - -But rather than depending on such large I/O buffers to make synchronous -I/O be efficient, it's better to just queue up several (bulk) requests -to the HC, and wait for them all to complete (or be canceled on error). -Such URB queuing should work with all the USB 1.1 HC drivers too. - -In the Linux 2.5 kernels, new usb_sg_*() api calls have been defined; they -queue all the buffers from a scatterlist. They also use scatterlist DMA -mapping (which might apply an IOMMU) and IRQ reduction, all of which will -help make high speed transfers run as fast as they can. - - -TBD: - Interrupt and ISO transfer performance issues. Those periodic - transfers are fully scheduled, so the main issue is likely to be how - to trigger "high bandwidth" modes. - -TBD: - More than standard 80% periodic bandwidth allocation is possible - through sysfs uframe_periodic_max parameter. Describe that. diff --git a/Documentation/usb/functionfs.rst b/Documentation/usb/functionfs.rst new file mode 100644 index 000000000000..7fdc6d840ac5 --- /dev/null +++ b/Documentation/usb/functionfs.rst @@ -0,0 +1,68 @@ +==================== +How FunctionFS works +==================== + +From kernel point of view it is just a composite function with some +unique behaviour. It may be added to an USB configuration only after +the user space driver has registered by writing descriptors and +strings (the user space program has to provide the same information +that kernel level composite functions provide when they are added to +the configuration). + +This in particular means that the composite initialisation functions +may not be in init section (ie. may not use the __init tag). + +From user space point of view it is a file system which when +mounted provides an "ep0" file. User space driver need to +write descriptors and strings to that file. It does not need +to worry about endpoints, interfaces or strings numbers but +simply provide descriptors such as if the function was the +only one (endpoints and strings numbers starting from one and +interface numbers starting from zero). The FunctionFS changes +them as needed also handling situation when numbers differ in +different configurations. + +When descriptors and strings are written "ep#" files appear +(one for each declared endpoint) which handle communication on +a single endpoint. Again, FunctionFS takes care of the real +numbers and changing of the configuration (which means that +"ep1" file may be really mapped to (say) endpoint 3 (and when +configuration changes to (say) endpoint 2)). "ep0" is used +for receiving events and handling setup requests. + +When all files are closed the function disables itself. + +What I also want to mention is that the FunctionFS is designed in such +a way that it is possible to mount it several times so in the end +a gadget could use several FunctionFS functions. The idea is that +each FunctionFS instance is identified by the device name used +when mounting. + +One can imagine a gadget that has an Ethernet, MTP and HID interfaces +where the last two are implemented via FunctionFS. On user space +level it would look like this:: + + $ insmod g_ffs.ko idVendor= iSerialNumber= functions=mtp,hid + $ mkdir /dev/ffs-mtp && mount -t functionfs mtp /dev/ffs-mtp + $ ( cd /dev/ffs-mtp && mtp-daemon ) & + $ mkdir /dev/ffs-hid && mount -t functionfs hid /dev/ffs-hid + $ ( cd /dev/ffs-hid && hid-daemon ) & + +On kernel level the gadget checks ffs_data->dev_name to identify +whether it's FunctionFS designed for MTP ("mtp") or HID ("hid"). + +If no "functions" module parameters is supplied, the driver accepts +just one function with any name. + +When "functions" module parameter is supplied, only functions +with listed names are accepted. In particular, if the "functions" +parameter's value is just a one-element list, then the behaviour +is similar to when there is no "functions" at all; however, +only a function with the specified name is accepted. + +The gadget is registered only after all the declared function +filesystems have been mounted and USB descriptors of all functions +have been written to their ep0's. + +Conversely, the gadget is unregistered after the first USB function +closes its endpoints. diff --git a/Documentation/usb/functionfs.txt b/Documentation/usb/functionfs.txt deleted file mode 100644 index 7fdc6d840ac5..000000000000 --- a/Documentation/usb/functionfs.txt +++ /dev/null @@ -1,68 +0,0 @@ -==================== -How FunctionFS works -==================== - -From kernel point of view it is just a composite function with some -unique behaviour. It may be added to an USB configuration only after -the user space driver has registered by writing descriptors and -strings (the user space program has to provide the same information -that kernel level composite functions provide when they are added to -the configuration). - -This in particular means that the composite initialisation functions -may not be in init section (ie. may not use the __init tag). - -From user space point of view it is a file system which when -mounted provides an "ep0" file. User space driver need to -write descriptors and strings to that file. It does not need -to worry about endpoints, interfaces or strings numbers but -simply provide descriptors such as if the function was the -only one (endpoints and strings numbers starting from one and -interface numbers starting from zero). The FunctionFS changes -them as needed also handling situation when numbers differ in -different configurations. - -When descriptors and strings are written "ep#" files appear -(one for each declared endpoint) which handle communication on -a single endpoint. Again, FunctionFS takes care of the real -numbers and changing of the configuration (which means that -"ep1" file may be really mapped to (say) endpoint 3 (and when -configuration changes to (say) endpoint 2)). "ep0" is used -for receiving events and handling setup requests. - -When all files are closed the function disables itself. - -What I also want to mention is that the FunctionFS is designed in such -a way that it is possible to mount it several times so in the end -a gadget could use several FunctionFS functions. The idea is that -each FunctionFS instance is identified by the device name used -when mounting. - -One can imagine a gadget that has an Ethernet, MTP and HID interfaces -where the last two are implemented via FunctionFS. On user space -level it would look like this:: - - $ insmod g_ffs.ko idVendor= iSerialNumber= functions=mtp,hid - $ mkdir /dev/ffs-mtp && mount -t functionfs mtp /dev/ffs-mtp - $ ( cd /dev/ffs-mtp && mtp-daemon ) & - $ mkdir /dev/ffs-hid && mount -t functionfs hid /dev/ffs-hid - $ ( cd /dev/ffs-hid && hid-daemon ) & - -On kernel level the gadget checks ffs_data->dev_name to identify -whether it's FunctionFS designed for MTP ("mtp") or HID ("hid"). - -If no "functions" module parameters is supplied, the driver accepts -just one function with any name. - -When "functions" module parameter is supplied, only functions -with listed names are accepted. In particular, if the "functions" -parameter's value is just a one-element list, then the behaviour -is similar to when there is no "functions" at all; however, -only a function with the specified name is accepted. - -The gadget is registered only after all the declared function -filesystems have been mounted and USB descriptors of all functions -have been written to their ep0's. - -Conversely, the gadget is unregistered after the first USB function -closes its endpoints. diff --git a/Documentation/usb/gadget-testing.rst b/Documentation/usb/gadget-testing.rst new file mode 100644 index 000000000000..2eeb3e9299e4 --- /dev/null +++ b/Documentation/usb/gadget-testing.rst @@ -0,0 +1,934 @@ +============== +Gadget Testing +============== + +This file summarizes information on basic testing of USB functions +provided by gadgets. + +.. contents + + 1. ACM function + 2. ECM function + 3. ECM subset function + 4. EEM function + 5. FFS function + 6. HID function + 7. LOOPBACK function + 8. MASS STORAGE function + 9. MIDI function + 10. NCM function + 11. OBEX function + 12. PHONET function + 13. RNDIS function + 14. SERIAL function + 15. SOURCESINK function + 16. UAC1 function (legacy implementation) + 17. UAC2 function + 18. UVC function + 19. PRINTER function + 20. UAC1 function (new API) + + +1. ACM function +=============== + +The function is provided by usb_f_acm.ko module. + +Function-specific configfs interface +------------------------------------ + +The function name to use when creating the function directory is "acm". +The ACM function provides just one attribute in its function directory: + + port_num + +The attribute is read-only. + +There can be at most 4 ACM/generic serial/OBEX ports in the system. + + +Testing the ACM function +------------------------ + +On the host:: + + cat > /dev/ttyACM + +On the device:: + + cat /dev/ttyGS + +then the other way round + +On the device:: + + cat > /dev/ttyGS + +On the host:: + + cat /dev/ttyACM + +2. ECM function +=============== + +The function is provided by usb_f_ecm.ko module. + +Function-specific configfs interface +------------------------------------ + +The function name to use when creating the function directory is "ecm". +The ECM function provides these attributes in its function directory: + + =============== ================================================== + 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 + =============== ================================================== + +and after creating the functions/ecm. they contain default +values: qmult is 5, dev_addr and host_addr are randomly selected. +Except for ifname they can be written to until the function is linked to a +configuration. The ifname is read-only and contains the name of the interface +which was assigned by the net core, e. g. usb0. + +Testing the ECM function +------------------------ + +Configure IP addresses of the device and the host. Then: + +On the device:: + + ping + +On the host:: + + ping + +3. ECM subset function +====================== + +The function is provided by usb_f_ecm_subset.ko module. + +Function-specific configfs interface +------------------------------------ + +The function name to use when creating the function directory is "geth". +The ECM subset function provides these attributes in its function directory: + + =============== ================================================== + 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 + =============== ================================================== + +and after creating the functions/ecm. they contain default +values: qmult is 5, dev_addr and host_addr are randomly selected. +Except for ifname they can be written to until the function is linked to a +configuration. The ifname is read-only and contains the name of the interface +which was assigned by the net core, e. g. usb0. + +Testing the ECM subset function +------------------------------- + +Configure IP addresses of the device and the host. Then: + +On the device:: + + ping + +On the host:: + + ping + +4. EEM function +=============== + +The function is provided by usb_f_eem.ko module. + +Function-specific configfs interface +------------------------------------ + +The function name to use when creating the function directory is "eem". +The EEM function provides these attributes in its function directory: + + =============== ================================================== + 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 + =============== ================================================== + +and after creating the functions/eem. they contain default +values: qmult is 5, dev_addr and host_addr are randomly selected. +Except for ifname they can be written to until the function is linked to a +configuration. The ifname is read-only and contains the name of the interface +which was assigned by the net core, e. g. usb0. + +Testing the EEM function +------------------------ + +Configure IP addresses of the device and the host. Then: + +On the device:: + + ping + +On the host:: + + ping + +5. FFS function +=============== + +The function is provided by usb_f_fs.ko module. + +Function-specific configfs interface +------------------------------------ + +The function name to use when creating the function directory is "ffs". +The function directory is intentionally empty and not modifiable. + +After creating the directory there is a new instance (a "device") of FunctionFS +available in the system. Once a "device" is available, the user should follow +the standard procedure for using FunctionFS (mount it, run the userspace +process which implements the function proper). The gadget should be enabled +by writing a suitable string to usb_gadget//UDC. + +Testing the FFS function +------------------------ + +On the device: start the function's userspace daemon, enable the gadget + +On the host: use the USB function provided by the device + +6. HID function +=============== + +The function is provided by usb_f_hid.ko module. + +Function-specific configfs interface +------------------------------------ + +The function name to use when creating the function directory is "hid". +The HID function provides these attributes in its function directory: + + =============== =========================================== + protocol HID protocol to use + report_desc data to be used in HID reports, except data + passed with /dev/hidg + report_length HID report length + subclass HID subclass to use + =============== =========================================== + +For a keyboard the protocol and the subclass are 1, the report_length is 8, +while the report_desc is:: + + $ hd my_report_desc + 00000000 05 01 09 06 a1 01 05 07 19 e0 29 e7 15 00 25 01 |..........)...%.| + 00000010 75 01 95 08 81 02 95 01 75 08 81 03 95 05 75 01 |u.......u.....u.| + 00000020 05 08 19 01 29 05 91 02 95 01 75 03 91 03 95 06 |....).....u.....| + 00000030 75 08 15 00 25 65 05 07 19 00 29 65 81 00 c0 |u...%e....)e...| + 0000003f + +Such a sequence of bytes can be stored to the attribute with echo:: + + $ echo -ne \\x05\\x01\\x09\\x06\\xa1..... + +Testing the HID function +------------------------ + +Device: + +- create the gadget +- connect the gadget to a host, preferably not the one used + to control the gadget +- run a program which writes to /dev/hidg, e.g. + a userspace program found in Documentation/usb/gadget_hid.rst:: + + $ ./hid_gadget_test /dev/hidg0 keyboard + +Host: + +- observe the keystrokes from the gadget + +7. LOOPBACK function +==================== + +The function is provided by usb_f_ss_lb.ko module. + +Function-specific configfs interface +------------------------------------ + +The function name to use when creating the function directory is "Loopback". +The LOOPBACK function provides these attributes in its function directory: + + =============== ======================= + qlen depth of loopback queue + bulk_buflen buffer length + =============== ======================= + +Testing the LOOPBACK function +----------------------------- + +device: run the gadget + +host: test-usb (tools/usb/testusb.c) + +8. MASS STORAGE function +======================== + +The function is provided by usb_f_mass_storage.ko module. + +Function-specific configfs interface +------------------------------------ + +The function name to use when creating the function directory is "mass_storage". +The MASS STORAGE function provides these attributes in its directory: +files: + + =============== ============================================== + stall Set to permit function to halt bulk endpoints. + Disabled on some USB devices known not to work + correctly. You should set it to true. + num_buffers Number of pipeline buffers. Valid numbers + are 2..4. Available only if + CONFIG_USB_GADGET_DEBUG_FILES is set. + =============== ============================================== + +and a default lun.0 directory corresponding to SCSI LUN #0. + +A new lun can be added with mkdir:: + + $ mkdir functions/mass_storage.0/partition.5 + +Lun numbering does not have to be continuous, except for lun #0 which is +created by default. A maximum of 8 luns can be specified and they all must be +named following the . scheme. The numbers can be 0..8. +Probably a good convention is to name the luns "lun.", +although it is not mandatory. + +In each lun directory there are the following attribute files: + + =============== ============================================== + file The path to the backing file for the LUN. + Required if LUN is not marked as removable. + ro Flag specifying access to the LUN shall be + read-only. This is implied if CD-ROM emulation + is enabled as well as when it was impossible + to open "filename" in R/W mode. + removable Flag specifying that LUN shall be indicated as + being removable. + cdrom Flag specifying that LUN shall be reported as + being a CD-ROM. + nofua Flag specifying that FUA flag + in SCSI WRITE(10,12) + =============== ============================================== + +Testing the MASS STORAGE function +--------------------------------- + +device: connect the gadget, enable it +host: dmesg, see the USB drives appear (if system configured to automatically +mount) + +9. MIDI function +================ + +The function is provided by usb_f_midi.ko module. + +Function-specific configfs interface +------------------------------------ + +The function name to use when creating the function directory is "midi". +The MIDI function provides these attributes in its function directory: + + =============== ==================================== + buflen MIDI buffer length + id ID string for the USB MIDI adapter + in_ports number of MIDI input ports + index index value for the USB MIDI adapter + out_ports number of MIDI output ports + qlen USB read request queue length + =============== ==================================== + +Testing the MIDI function +------------------------- + +There are two cases: playing a mid from the gadget to +the host and playing a mid from the host to the gadget. + +1) Playing a mid from the gadget to the host: + +host:: + + $ arecordmidi -l + Port Client name Port name + 14:0 Midi Through Midi Through Port-0 + 24:0 MIDI Gadget MIDI Gadget MIDI 1 + $ arecordmidi -p 24:0 from_gadget.mid + +gadget:: + + $ aplaymidi -l + Port Client name Port name + 20:0 f_midi f_midi + + $ aplaymidi -p 20:0 to_host.mid + +2) Playing a mid from the host to the gadget + +gadget:: + + $ arecordmidi -l + Port Client name Port name + 20:0 f_midi f_midi + + $ arecordmidi -p 20:0 from_host.mid + +host:: + + $ aplaymidi -l + Port Client name Port name + 14:0 Midi Through Midi Through Port-0 + 24:0 MIDI Gadget MIDI Gadget MIDI 1 + + $ aplaymidi -p24:0 to_gadget.mid + +The from_gadget.mid should sound identical to the to_host.mid. + +The from_host.id should sound identical to the to_gadget.mid. + +MIDI files can be played to speakers/headphones with e.g. timidity installed:: + + $ aplaymidi -l + Port Client name Port name + 14:0 Midi Through Midi Through Port-0 + 24:0 MIDI Gadget MIDI Gadget MIDI 1 + 128:0 TiMidity TiMidity port 0 + 128:1 TiMidity TiMidity port 1 + 128:2 TiMidity TiMidity port 2 + 128:3 TiMidity TiMidity port 3 + + $ aplaymidi -p 128:0 file.mid + +MIDI ports can be logically connected using the aconnect utility, e.g.:: + + $ aconnect 24:0 128:0 # try it on the host + +After the gadget's MIDI port is connected to timidity's MIDI port, +whatever is played at the gadget side with aplaymidi -l is audible +in host's speakers/headphones. + +10. NCM function +================ + +The function is provided by usb_f_ncm.ko module. + +Function-specific configfs interface +------------------------------------ + +The function name to use when creating the function directory is "ncm". +The NCM function provides these attributes in its function directory: + + =============== ================================================== + 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 + =============== ================================================== + +and after creating the functions/ncm. they contain default +values: qmult is 5, dev_addr and host_addr are randomly selected. +Except for ifname they can be written to until the function is linked to a +configuration. The ifname is read-only and contains the name of the interface +which was assigned by the net core, e. g. usb0. + +Testing the NCM function +------------------------ + +Configure IP addresses of the device and the host. Then: + +On the device:: + + ping + +On the host:: + + ping + +11. OBEX function +================= + +The function is provided by usb_f_obex.ko module. + +Function-specific configfs interface +------------------------------------ + +The function name to use when creating the function directory is "obex". +The OBEX function provides just one attribute in its function directory: + + port_num + +The attribute is read-only. + +There can be at most 4 ACM/generic serial/OBEX ports in the system. + +Testing the OBEX function +------------------------- + +On device:: + + seriald -f /dev/ttyGS -s 1024 + +On host:: + + serialc -v -p -i -a1 -s1024 \ + -t -r + +where seriald and serialc are Felipe's utilities found here: + + https://github.com/felipebalbi/usb-tools.git master + +12. PHONET function +=================== + +The function is provided by usb_f_phonet.ko module. + +Function-specific configfs interface +------------------------------------ + +The function name to use when creating the function directory is "phonet". +The PHONET function provides just one attribute in its function directory: + + =============== ================================================== + ifname network device interface name associated with this + function instance + =============== ================================================== + +Testing the PHONET function +--------------------------- + +It is not possible to test the SOCK_STREAM protocol without a specific piece +of hardware, so only SOCK_DGRAM has been tested. For the latter to work, +in the past I had to apply the patch mentioned here: + +http://www.spinics.net/lists/linux-usb/msg85689.html + +These tools are required: + +git://git.gitorious.org/meego-cellular/phonet-utils.git + +On the host:: + + $ ./phonet -a 0x10 -i usbpn0 + $ ./pnroute add 0x6c usbpn0 + $./pnroute add 0x10 usbpn0 + $ ifconfig usbpn0 up + +On the device:: + + $ ./phonet -a 0x6c -i upnlink0 + $ ./pnroute add 0x10 upnlink0 + $ ifconfig upnlink0 up + +Then a test program can be used:: + + http://www.spinics.net/lists/linux-usb/msg85690.html + +On the device:: + + $ ./pnxmit -a 0x6c -r + +On the host:: + + $ ./pnxmit -a 0x10 -s 0x6c + +As a result some data should be sent from host to device. +Then the other way round: + +On the host:: + + $ ./pnxmit -a 0x10 -r + +On the device:: + + $ ./pnxmit -a 0x6c -s 0x10 + +13. RNDIS function +================== + +The function is provided by usb_f_rndis.ko module. + +Function-specific configfs interface +------------------------------------ + +The function name to use when creating the function directory is "rndis". +The RNDIS function provides these attributes in its function directory: + + =============== ================================================== + 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 + =============== ================================================== + +and after creating the functions/rndis. they contain default +values: qmult is 5, dev_addr and host_addr are randomly selected. +Except for ifname they can be written to until the function is linked to a +configuration. The ifname is read-only and contains the name of the interface +which was assigned by the net core, e. g. usb0. + +Testing the RNDIS function +-------------------------- + +Configure IP addresses of the device and the host. Then: + +On the device:: + + ping + +On the host:: + + ping + +14. SERIAL function +=================== + +The function is provided by usb_f_gser.ko module. + +Function-specific configfs interface +------------------------------------ + +The function name to use when creating the function directory is "gser". +The SERIAL function provides just one attribute in its function directory: + + port_num + +The attribute is read-only. + +There can be at most 4 ACM/generic serial/OBEX ports in the system. + +Testing the SERIAL function +--------------------------- + +On host:: + + insmod usbserial + echo VID PID >/sys/bus/usb-serial/drivers/generic/new_id + +On host:: + + cat > /dev/ttyUSB + +On target:: + + cat /dev/ttyGS + +then the other way round + +On target:: + + cat > /dev/ttyGS + +On host:: + + cat /dev/ttyUSB + +15. SOURCESINK function +======================= + +The function is provided by usb_f_ss_lb.ko module. + +Function-specific configfs interface +------------------------------------ + +The function name to use when creating the function directory is "SourceSink". +The SOURCESINK function provides these attributes in its function directory: + + =============== ================================== + pattern 0 (all zeros), 1 (mod63), 2 (none) + isoc_interval 1..16 + isoc_maxpacket 0 - 1023 (fs), 0 - 1024 (hs/ss) + isoc_mult 0..2 (hs/ss only) + isoc_maxburst 0..15 (ss only) + bulk_buflen buffer length + bulk_qlen depth of queue for bulk + iso_qlen depth of queue for iso + =============== ================================== + +Testing the SOURCESINK function +------------------------------- + +device: run the gadget + +host: test-usb (tools/usb/testusb.c) + + +16. UAC1 function (legacy implementation) +========================================= + +The function is provided by usb_f_uac1_legacy.ko module. + +Function-specific configfs interface +------------------------------------ + +The function name to use when creating the function directory +is "uac1_legacy". +The uac1 function provides these attributes in its function directory: + + =============== ==================================== + audio_buf_size audio buffer size + fn_cap capture pcm device file name + fn_cntl control device file name + fn_play playback pcm device file name + req_buf_size ISO OUT endpoint request buffer size + req_count ISO OUT endpoint request count + =============== ==================================== + +The attributes have sane default values. + +Testing the UAC1 function +------------------------- + +device: run the gadget + +host:: + + aplay -l # should list our USB Audio Gadget + +17. UAC2 function +================= + +The function is provided by usb_f_uac2.ko module. + +Function-specific configfs interface +------------------------------------ + +The function name to use when creating the function directory is "uac2". +The uac2 function provides these attributes in its function directory: + + =============== ==================================================== + c_chmask capture channel mask + c_srate capture sampling rate + c_ssize capture sample size (bytes) + p_chmask playback channel mask + p_srate playback sampling rate + p_ssize playback sample size (bytes) + req_number the number of pre-allocated request for both capture + and playback + =============== ==================================================== + +The attributes have sane default values. + +Testing the UAC2 function +------------------------- + +device: run the gadget +host: aplay -l # should list our USB Audio Gadget + +This function does not require real hardware support, it just +sends a stream of audio data to/from the host. In order to +actually hear something at the device side, a command similar +to this must be used at the device side:: + + $ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 & + +e.g.:: + + $ arecord -f dat -t wav -D hw:CARD=UAC2Gadget,DEV=0 | \ + aplay -D default:CARD=OdroidU3 + +18. UVC function +================ + +The function is provided by usb_f_uvc.ko module. + +Function-specific configfs interface +------------------------------------ + +The function name to use when creating the function directory is "uvc". +The uvc function provides these attributes in its function directory: + + =================== ================================================ + streaming_interval interval for polling endpoint for data transfers + streaming_maxburst bMaxBurst for super speed companion descriptor + streaming_maxpacket maximum packet size this endpoint is capable of + sending or receiving when this configuration is + selected + =================== ================================================ + +There are also "control" and "streaming" subdirectories, each of which contain +a number of their subdirectories. There are some sane defaults provided, but +the user must provide the following: + + ================== ==================================================== + control header create in control/header, link from control/class/fs + and/or control/class/ss + streaming header create in streaming/header, link from + streaming/class/fs and/or streaming/class/hs and/or + streaming/class/ss + format description create in streaming/mjpeg and/or + streaming/uncompressed + frame description create in streaming/mjpeg/ and/or in + streaming/uncompressed/ + ================== ==================================================== + +Each frame description contains frame interval specification, and each +such specification consists of a number of lines with an inverval value +in each line. The rules stated above are best illustrated with an example:: + + # mkdir functions/uvc.usb0/control/header/h + # cd functions/uvc.usb0/control/ + # ln -s header/h class/fs + # ln -s header/h class/ss + # mkdir -p functions/uvc.usb0/streaming/uncompressed/u/360p + # cat < functions/uvc.usb0/streaming/uncompressed/u/360p/dwFrameInterval + 666666 + 1000000 + 5000000 + EOF + # cd $GADGET_CONFIGFS_ROOT + # mkdir functions/uvc.usb0/streaming/header/h + # cd functions/uvc.usb0/streaming/header/h + # ln -s ../../uncompressed/u + # cd ../../class/fs + # ln -s ../../header/h + # cd ../../class/hs + # ln -s ../../header/h + # cd ../../class/ss + # ln -s ../../header/h + + +Testing the UVC function +------------------------ + +device: run the gadget, modprobe vivid:: + + # uvc-gadget -u /dev/video -v /dev/video + +where uvc-gadget is this program: + http://git.ideasonboard.org/uvc-gadget.git + +with these patches: + + http://www.spinics.net/lists/linux-usb/msg99220.html + +host:: + + luvcview -f yuv + +19. PRINTER function +==================== + +The function is provided by usb_f_printer.ko module. + +Function-specific configfs interface +------------------------------------ + +The function name to use when creating the function directory is "printer". +The printer function provides these attributes in its function directory: + + ========== =========================================== + pnp_string Data to be passed to the host in pnp string + q_len Number of requests per endpoint + ========== =========================================== + +Testing the PRINTER function +---------------------------- + +The most basic testing: + +device: run the gadget:: + + # ls -l /devices/virtual/usb_printer_gadget/ + +should show g_printer. + +If udev is active, then /dev/g_printer should appear automatically. + +host: + +If udev is active, then e.g. /dev/usb/lp0 should appear. + +host->device transmission: + +device:: + + # cat /dev/g_printer + +host:: + + # cat > /dev/usb/lp0 + +device->host transmission:: + + # cat > /dev/g_printer + +host:: + + # cat /dev/usb/lp0 + +More advanced testing can be done with the prn_example +described in Documentation/usb/gadget_printer.rst. + + +20. UAC1 function (virtual ALSA card, using u_audio API) +======================================================== + +The function is provided by usb_f_uac1.ko module. +It will create a virtual ALSA card and the audio streams are simply +sinked to and sourced from it. + +Function-specific configfs interface +------------------------------------ + +The function name to use when creating the function directory is "uac1". +The uac1 function provides these attributes in its function directory: + + ========== ==================================================== + c_chmask capture channel mask + c_srate capture sampling rate + c_ssize capture sample size (bytes) + p_chmask playback channel mask + p_srate playback sampling rate + p_ssize playback sample size (bytes) + req_number the number of pre-allocated request for both capture + and playback + ========== ==================================================== + +The attributes have sane default values. + +Testing the UAC1 function +------------------------- + +device: run the gadget +host: aplay -l # should list our USB Audio Gadget + +This function does not require real hardware support, it just +sends a stream of audio data to/from the host. In order to +actually hear something at the device side, a command similar +to this must be used at the device side:: + + $ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 & + +e.g.:: + + $ arecord -f dat -t wav -D hw:CARD=UAC1Gadget,DEV=0 | \ + aplay -D default:CARD=OdroidU3 diff --git a/Documentation/usb/gadget-testing.txt b/Documentation/usb/gadget-testing.txt deleted file mode 100644 index 7d7f2340af42..000000000000 --- a/Documentation/usb/gadget-testing.txt +++ /dev/null @@ -1,934 +0,0 @@ -============== -Gadget Testing -============== - -This file summarizes information on basic testing of USB functions -provided by gadgets. - -.. contents - - 1. ACM function - 2. ECM function - 3. ECM subset function - 4. EEM function - 5. FFS function - 6. HID function - 7. LOOPBACK function - 8. MASS STORAGE function - 9. MIDI function - 10. NCM function - 11. OBEX function - 12. PHONET function - 13. RNDIS function - 14. SERIAL function - 15. SOURCESINK function - 16. UAC1 function (legacy implementation) - 17. UAC2 function - 18. UVC function - 19. PRINTER function - 20. UAC1 function (new API) - - -1. ACM function -=============== - -The function is provided by usb_f_acm.ko module. - -Function-specific configfs interface ------------------------------------- - -The function name to use when creating the function directory is "acm". -The ACM function provides just one attribute in its function directory: - - port_num - -The attribute is read-only. - -There can be at most 4 ACM/generic serial/OBEX ports in the system. - - -Testing the ACM function ------------------------- - -On the host:: - - cat > /dev/ttyACM - -On the device:: - - cat /dev/ttyGS - -then the other way round - -On the device:: - - cat > /dev/ttyGS - -On the host:: - - cat /dev/ttyACM - -2. ECM function -=============== - -The function is provided by usb_f_ecm.ko module. - -Function-specific configfs interface ------------------------------------- - -The function name to use when creating the function directory is "ecm". -The ECM function provides these attributes in its function directory: - - =============== ================================================== - 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 - =============== ================================================== - -and after creating the functions/ecm. they contain default -values: qmult is 5, dev_addr and host_addr are randomly selected. -Except for ifname they can be written to until the function is linked to a -configuration. The ifname is read-only and contains the name of the interface -which was assigned by the net core, e. g. usb0. - -Testing the ECM function ------------------------- - -Configure IP addresses of the device and the host. Then: - -On the device:: - - ping - -On the host:: - - ping - -3. ECM subset function -====================== - -The function is provided by usb_f_ecm_subset.ko module. - -Function-specific configfs interface ------------------------------------- - -The function name to use when creating the function directory is "geth". -The ECM subset function provides these attributes in its function directory: - - =============== ================================================== - 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 - =============== ================================================== - -and after creating the functions/ecm. they contain default -values: qmult is 5, dev_addr and host_addr are randomly selected. -Except for ifname they can be written to until the function is linked to a -configuration. The ifname is read-only and contains the name of the interface -which was assigned by the net core, e. g. usb0. - -Testing the ECM subset function -------------------------------- - -Configure IP addresses of the device and the host. Then: - -On the device:: - - ping - -On the host:: - - ping - -4. EEM function -=============== - -The function is provided by usb_f_eem.ko module. - -Function-specific configfs interface ------------------------------------- - -The function name to use when creating the function directory is "eem". -The EEM function provides these attributes in its function directory: - - =============== ================================================== - 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 - =============== ================================================== - -and after creating the functions/eem. they contain default -values: qmult is 5, dev_addr and host_addr are randomly selected. -Except for ifname they can be written to until the function is linked to a -configuration. The ifname is read-only and contains the name of the interface -which was assigned by the net core, e. g. usb0. - -Testing the EEM function ------------------------- - -Configure IP addresses of the device and the host. Then: - -On the device:: - - ping - -On the host:: - - ping - -5. FFS function -=============== - -The function is provided by usb_f_fs.ko module. - -Function-specific configfs interface ------------------------------------- - -The function name to use when creating the function directory is "ffs". -The function directory is intentionally empty and not modifiable. - -After creating the directory there is a new instance (a "device") of FunctionFS -available in the system. Once a "device" is available, the user should follow -the standard procedure for using FunctionFS (mount it, run the userspace -process which implements the function proper). The gadget should be enabled -by writing a suitable string to usb_gadget//UDC. - -Testing the FFS function ------------------------- - -On the device: start the function's userspace daemon, enable the gadget - -On the host: use the USB function provided by the device - -6. HID function -=============== - -The function is provided by usb_f_hid.ko module. - -Function-specific configfs interface ------------------------------------- - -The function name to use when creating the function directory is "hid". -The HID function provides these attributes in its function directory: - - =============== =========================================== - protocol HID protocol to use - report_desc data to be used in HID reports, except data - passed with /dev/hidg - report_length HID report length - subclass HID subclass to use - =============== =========================================== - -For a keyboard the protocol and the subclass are 1, the report_length is 8, -while the report_desc is:: - - $ hd my_report_desc - 00000000 05 01 09 06 a1 01 05 07 19 e0 29 e7 15 00 25 01 |..........)...%.| - 00000010 75 01 95 08 81 02 95 01 75 08 81 03 95 05 75 01 |u.......u.....u.| - 00000020 05 08 19 01 29 05 91 02 95 01 75 03 91 03 95 06 |....).....u.....| - 00000030 75 08 15 00 25 65 05 07 19 00 29 65 81 00 c0 |u...%e....)e...| - 0000003f - -Such a sequence of bytes can be stored to the attribute with echo:: - - $ echo -ne \\x05\\x01\\x09\\x06\\xa1..... - -Testing the HID function ------------------------- - -Device: - -- create the gadget -- connect the gadget to a host, preferably not the one used - to control the gadget -- run a program which writes to /dev/hidg, e.g. - a userspace program found in Documentation/usb/gadget_hid.txt:: - - $ ./hid_gadget_test /dev/hidg0 keyboard - -Host: - -- observe the keystrokes from the gadget - -7. LOOPBACK function -==================== - -The function is provided by usb_f_ss_lb.ko module. - -Function-specific configfs interface ------------------------------------- - -The function name to use when creating the function directory is "Loopback". -The LOOPBACK function provides these attributes in its function directory: - - =============== ======================= - qlen depth of loopback queue - bulk_buflen buffer length - =============== ======================= - -Testing the LOOPBACK function ------------------------------ - -device: run the gadget - -host: test-usb (tools/usb/testusb.c) - -8. MASS STORAGE function -======================== - -The function is provided by usb_f_mass_storage.ko module. - -Function-specific configfs interface ------------------------------------- - -The function name to use when creating the function directory is "mass_storage". -The MASS STORAGE function provides these attributes in its directory: -files: - - =============== ============================================== - stall Set to permit function to halt bulk endpoints. - Disabled on some USB devices known not to work - correctly. You should set it to true. - num_buffers Number of pipeline buffers. Valid numbers - are 2..4. Available only if - CONFIG_USB_GADGET_DEBUG_FILES is set. - =============== ============================================== - -and a default lun.0 directory corresponding to SCSI LUN #0. - -A new lun can be added with mkdir:: - - $ mkdir functions/mass_storage.0/partition.5 - -Lun numbering does not have to be continuous, except for lun #0 which is -created by default. A maximum of 8 luns can be specified and they all must be -named following the . scheme. The numbers can be 0..8. -Probably a good convention is to name the luns "lun.", -although it is not mandatory. - -In each lun directory there are the following attribute files: - - =============== ============================================== - file The path to the backing file for the LUN. - Required if LUN is not marked as removable. - ro Flag specifying access to the LUN shall be - read-only. This is implied if CD-ROM emulation - is enabled as well as when it was impossible - to open "filename" in R/W mode. - removable Flag specifying that LUN shall be indicated as - being removable. - cdrom Flag specifying that LUN shall be reported as - being a CD-ROM. - nofua Flag specifying that FUA flag - in SCSI WRITE(10,12) - =============== ============================================== - -Testing the MASS STORAGE function ---------------------------------- - -device: connect the gadget, enable it -host: dmesg, see the USB drives appear (if system configured to automatically -mount) - -9. MIDI function -================ - -The function is provided by usb_f_midi.ko module. - -Function-specific configfs interface ------------------------------------- - -The function name to use when creating the function directory is "midi". -The MIDI function provides these attributes in its function directory: - - =============== ==================================== - buflen MIDI buffer length - id ID string for the USB MIDI adapter - in_ports number of MIDI input ports - index index value for the USB MIDI adapter - out_ports number of MIDI output ports - qlen USB read request queue length - =============== ==================================== - -Testing the MIDI function -------------------------- - -There are two cases: playing a mid from the gadget to -the host and playing a mid from the host to the gadget. - -1) Playing a mid from the gadget to the host: - -host:: - - $ arecordmidi -l - Port Client name Port name - 14:0 Midi Through Midi Through Port-0 - 24:0 MIDI Gadget MIDI Gadget MIDI 1 - $ arecordmidi -p 24:0 from_gadget.mid - -gadget:: - - $ aplaymidi -l - Port Client name Port name - 20:0 f_midi f_midi - - $ aplaymidi -p 20:0 to_host.mid - -2) Playing a mid from the host to the gadget - -gadget:: - - $ arecordmidi -l - Port Client name Port name - 20:0 f_midi f_midi - - $ arecordmidi -p 20:0 from_host.mid - -host:: - - $ aplaymidi -l - Port Client name Port name - 14:0 Midi Through Midi Through Port-0 - 24:0 MIDI Gadget MIDI Gadget MIDI 1 - - $ aplaymidi -p24:0 to_gadget.mid - -The from_gadget.mid should sound identical to the to_host.mid. - -The from_host.id should sound identical to the to_gadget.mid. - -MIDI files can be played to speakers/headphones with e.g. timidity installed:: - - $ aplaymidi -l - Port Client name Port name - 14:0 Midi Through Midi Through Port-0 - 24:0 MIDI Gadget MIDI Gadget MIDI 1 - 128:0 TiMidity TiMidity port 0 - 128:1 TiMidity TiMidity port 1 - 128:2 TiMidity TiMidity port 2 - 128:3 TiMidity TiMidity port 3 - - $ aplaymidi -p 128:0 file.mid - -MIDI ports can be logically connected using the aconnect utility, e.g.:: - - $ aconnect 24:0 128:0 # try it on the host - -After the gadget's MIDI port is connected to timidity's MIDI port, -whatever is played at the gadget side with aplaymidi -l is audible -in host's speakers/headphones. - -10. NCM function -================ - -The function is provided by usb_f_ncm.ko module. - -Function-specific configfs interface ------------------------------------- - -The function name to use when creating the function directory is "ncm". -The NCM function provides these attributes in its function directory: - - =============== ================================================== - 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 - =============== ================================================== - -and after creating the functions/ncm. they contain default -values: qmult is 5, dev_addr and host_addr are randomly selected. -Except for ifname they can be written to until the function is linked to a -configuration. The ifname is read-only and contains the name of the interface -which was assigned by the net core, e. g. usb0. - -Testing the NCM function ------------------------- - -Configure IP addresses of the device and the host. Then: - -On the device:: - - ping - -On the host:: - - ping - -11. OBEX function -================= - -The function is provided by usb_f_obex.ko module. - -Function-specific configfs interface ------------------------------------- - -The function name to use when creating the function directory is "obex". -The OBEX function provides just one attribute in its function directory: - - port_num - -The attribute is read-only. - -There can be at most 4 ACM/generic serial/OBEX ports in the system. - -Testing the OBEX function -------------------------- - -On device:: - - seriald -f /dev/ttyGS -s 1024 - -On host:: - - serialc -v -p -i -a1 -s1024 \ - -t -r - -where seriald and serialc are Felipe's utilities found here: - - https://github.com/felipebalbi/usb-tools.git master - -12. PHONET function -=================== - -The function is provided by usb_f_phonet.ko module. - -Function-specific configfs interface ------------------------------------- - -The function name to use when creating the function directory is "phonet". -The PHONET function provides just one attribute in its function directory: - - =============== ================================================== - ifname network device interface name associated with this - function instance - =============== ================================================== - -Testing the PHONET function ---------------------------- - -It is not possible to test the SOCK_STREAM protocol without a specific piece -of hardware, so only SOCK_DGRAM has been tested. For the latter to work, -in the past I had to apply the patch mentioned here: - -http://www.spinics.net/lists/linux-usb/msg85689.html - -These tools are required: - -git://git.gitorious.org/meego-cellular/phonet-utils.git - -On the host:: - - $ ./phonet -a 0x10 -i usbpn0 - $ ./pnroute add 0x6c usbpn0 - $./pnroute add 0x10 usbpn0 - $ ifconfig usbpn0 up - -On the device:: - - $ ./phonet -a 0x6c -i upnlink0 - $ ./pnroute add 0x10 upnlink0 - $ ifconfig upnlink0 up - -Then a test program can be used:: - - http://www.spinics.net/lists/linux-usb/msg85690.html - -On the device:: - - $ ./pnxmit -a 0x6c -r - -On the host:: - - $ ./pnxmit -a 0x10 -s 0x6c - -As a result some data should be sent from host to device. -Then the other way round: - -On the host:: - - $ ./pnxmit -a 0x10 -r - -On the device:: - - $ ./pnxmit -a 0x6c -s 0x10 - -13. RNDIS function -================== - -The function is provided by usb_f_rndis.ko module. - -Function-specific configfs interface ------------------------------------- - -The function name to use when creating the function directory is "rndis". -The RNDIS function provides these attributes in its function directory: - - =============== ================================================== - 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 - =============== ================================================== - -and after creating the functions/rndis. they contain default -values: qmult is 5, dev_addr and host_addr are randomly selected. -Except for ifname they can be written to until the function is linked to a -configuration. The ifname is read-only and contains the name of the interface -which was assigned by the net core, e. g. usb0. - -Testing the RNDIS function --------------------------- - -Configure IP addresses of the device and the host. Then: - -On the device:: - - ping - -On the host:: - - ping - -14. SERIAL function -=================== - -The function is provided by usb_f_gser.ko module. - -Function-specific configfs interface ------------------------------------- - -The function name to use when creating the function directory is "gser". -The SERIAL function provides just one attribute in its function directory: - - port_num - -The attribute is read-only. - -There can be at most 4 ACM/generic serial/OBEX ports in the system. - -Testing the SERIAL function ---------------------------- - -On host:: - - insmod usbserial - echo VID PID >/sys/bus/usb-serial/drivers/generic/new_id - -On host:: - - cat > /dev/ttyUSB - -On target:: - - cat /dev/ttyGS - -then the other way round - -On target:: - - cat > /dev/ttyGS - -On host:: - - cat /dev/ttyUSB - -15. SOURCESINK function -======================= - -The function is provided by usb_f_ss_lb.ko module. - -Function-specific configfs interface ------------------------------------- - -The function name to use when creating the function directory is "SourceSink". -The SOURCESINK function provides these attributes in its function directory: - - =============== ================================== - pattern 0 (all zeros), 1 (mod63), 2 (none) - isoc_interval 1..16 - isoc_maxpacket 0 - 1023 (fs), 0 - 1024 (hs/ss) - isoc_mult 0..2 (hs/ss only) - isoc_maxburst 0..15 (ss only) - bulk_buflen buffer length - bulk_qlen depth of queue for bulk - iso_qlen depth of queue for iso - =============== ================================== - -Testing the SOURCESINK function -------------------------------- - -device: run the gadget - -host: test-usb (tools/usb/testusb.c) - - -16. UAC1 function (legacy implementation) -========================================= - -The function is provided by usb_f_uac1_legacy.ko module. - -Function-specific configfs interface ------------------------------------- - -The function name to use when creating the function directory -is "uac1_legacy". -The uac1 function provides these attributes in its function directory: - - =============== ==================================== - audio_buf_size audio buffer size - fn_cap capture pcm device file name - fn_cntl control device file name - fn_play playback pcm device file name - req_buf_size ISO OUT endpoint request buffer size - req_count ISO OUT endpoint request count - =============== ==================================== - -The attributes have sane default values. - -Testing the UAC1 function -------------------------- - -device: run the gadget - -host:: - - aplay -l # should list our USB Audio Gadget - -17. UAC2 function -================= - -The function is provided by usb_f_uac2.ko module. - -Function-specific configfs interface ------------------------------------- - -The function name to use when creating the function directory is "uac2". -The uac2 function provides these attributes in its function directory: - - =============== ==================================================== - c_chmask capture channel mask - c_srate capture sampling rate - c_ssize capture sample size (bytes) - p_chmask playback channel mask - p_srate playback sampling rate - p_ssize playback sample size (bytes) - req_number the number of pre-allocated request for both capture - and playback - =============== ==================================================== - -The attributes have sane default values. - -Testing the UAC2 function -------------------------- - -device: run the gadget -host: aplay -l # should list our USB Audio Gadget - -This function does not require real hardware support, it just -sends a stream of audio data to/from the host. In order to -actually hear something at the device side, a command similar -to this must be used at the device side:: - - $ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 & - -e.g.:: - - $ arecord -f dat -t wav -D hw:CARD=UAC2Gadget,DEV=0 | \ - aplay -D default:CARD=OdroidU3 - -18. UVC function -================ - -The function is provided by usb_f_uvc.ko module. - -Function-specific configfs interface ------------------------------------- - -The function name to use when creating the function directory is "uvc". -The uvc function provides these attributes in its function directory: - - =================== ================================================ - streaming_interval interval for polling endpoint for data transfers - streaming_maxburst bMaxBurst for super speed companion descriptor - streaming_maxpacket maximum packet size this endpoint is capable of - sending or receiving when this configuration is - selected - =================== ================================================ - -There are also "control" and "streaming" subdirectories, each of which contain -a number of their subdirectories. There are some sane defaults provided, but -the user must provide the following: - - ================== ==================================================== - control header create in control/header, link from control/class/fs - and/or control/class/ss - streaming header create in streaming/header, link from - streaming/class/fs and/or streaming/class/hs and/or - streaming/class/ss - format description create in streaming/mjpeg and/or - streaming/uncompressed - frame description create in streaming/mjpeg/ and/or in - streaming/uncompressed/ - ================== ==================================================== - -Each frame description contains frame interval specification, and each -such specification consists of a number of lines with an inverval value -in each line. The rules stated above are best illustrated with an example:: - - # mkdir functions/uvc.usb0/control/header/h - # cd functions/uvc.usb0/control/ - # ln -s header/h class/fs - # ln -s header/h class/ss - # mkdir -p functions/uvc.usb0/streaming/uncompressed/u/360p - # cat < functions/uvc.usb0/streaming/uncompressed/u/360p/dwFrameInterval - 666666 - 1000000 - 5000000 - EOF - # cd $GADGET_CONFIGFS_ROOT - # mkdir functions/uvc.usb0/streaming/header/h - # cd functions/uvc.usb0/streaming/header/h - # ln -s ../../uncompressed/u - # cd ../../class/fs - # ln -s ../../header/h - # cd ../../class/hs - # ln -s ../../header/h - # cd ../../class/ss - # ln -s ../../header/h - - -Testing the UVC function ------------------------- - -device: run the gadget, modprobe vivid:: - - # uvc-gadget -u /dev/video -v /dev/video - -where uvc-gadget is this program: - http://git.ideasonboard.org/uvc-gadget.git - -with these patches: - - http://www.spinics.net/lists/linux-usb/msg99220.html - -host:: - - luvcview -f yuv - -19. PRINTER function -==================== - -The function is provided by usb_f_printer.ko module. - -Function-specific configfs interface ------------------------------------- - -The function name to use when creating the function directory is "printer". -The printer function provides these attributes in its function directory: - - ========== =========================================== - pnp_string Data to be passed to the host in pnp string - q_len Number of requests per endpoint - ========== =========================================== - -Testing the PRINTER function ----------------------------- - -The most basic testing: - -device: run the gadget:: - - # ls -l /devices/virtual/usb_printer_gadget/ - -should show g_printer. - -If udev is active, then /dev/g_printer should appear automatically. - -host: - -If udev is active, then e.g. /dev/usb/lp0 should appear. - -host->device transmission: - -device:: - - # cat /dev/g_printer - -host:: - - # cat > /dev/usb/lp0 - -device->host transmission:: - - # cat > /dev/g_printer - -host:: - - # cat /dev/usb/lp0 - -More advanced testing can be done with the prn_example -described in Documentation/usb/gadget_printer.txt. - - -20. UAC1 function (virtual ALSA card, using u_audio API) -======================================================== - -The function is provided by usb_f_uac1.ko module. -It will create a virtual ALSA card and the audio streams are simply -sinked to and sourced from it. - -Function-specific configfs interface ------------------------------------- - -The function name to use when creating the function directory is "uac1". -The uac1 function provides these attributes in its function directory: - - ========== ==================================================== - c_chmask capture channel mask - c_srate capture sampling rate - c_ssize capture sample size (bytes) - p_chmask playback channel mask - p_srate playback sampling rate - p_ssize playback sample size (bytes) - req_number the number of pre-allocated request for both capture - and playback - ========== ==================================================== - -The attributes have sane default values. - -Testing the UAC1 function -------------------------- - -device: run the gadget -host: aplay -l # should list our USB Audio Gadget - -This function does not require real hardware support, it just -sends a stream of audio data to/from the host. In order to -actually hear something at the device side, a command similar -to this must be used at the device side:: - - $ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 & - -e.g.:: - - $ arecord -f dat -t wav -D hw:CARD=UAC1Gadget,DEV=0 | \ - aplay -D default:CARD=OdroidU3 diff --git a/Documentation/usb/gadget_configfs.rst b/Documentation/usb/gadget_configfs.rst new file mode 100644 index 000000000000..54fb08baae22 --- /dev/null +++ b/Documentation/usb/gadget_configfs.rst @@ -0,0 +1,390 @@ +============================================ +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 itself 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/ + +e.g.:: + + $ mkdir $CONFIGFS_HOME/usb_gadget/g1 + + ... + ... + ... + + $ cd $CONFIGFS_HOME/usb_gadget/g1 + +Each gadget needs to have its vendor id and product id specified:: + + $ echo > idVendor + $ echo > 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 > strings/0x409/serialnumber + $ echo > strings/0x409/manufacturer + $ echo > strings/0x409/product + +2. Creating the configurations +------------------------------ + +Each gadget will consist of a number of configurations, their corresponding +directories must be created: + +$ mkdir configs/. + +where can be any string which is legal in a filesystem and the + 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 > 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/. + +where 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/. configs/. + +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 + +where 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/./ + +where . specify the configuration and is +a symlink to a function being removed from the configuration, e.g.:: + + $ rm configs/c.1/ncm.usb0 + + ... + ... + ... + +Remove strings directories in configurations: + + $ rmdir configs/./strings/ + +e.g.:: + + $ rmdir configs/c.1/strings/0x409 + + ... + ... + ... + +and remove the configurations:: + + $ rmdir configs/. + +e.g.:: + + rmdir configs/c.1 + + ... + ... + ... + +Remove functions (function modules are not unloaded, though): + + $ rmdir functions/. + +e.g.:: + + $ rmdir functions/ncm.usb0 + + ... + ... + ... + +Remove strings directories in the gadget:: + + $ rmdir strings/ + +e.g.:: + + $ rmdir strings/0x409 + +and finally remove the gadget:: + + $ cd .. + $ rmdir + +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 struct 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. Function'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. diff --git a/Documentation/usb/gadget_configfs.txt b/Documentation/usb/gadget_configfs.txt deleted file mode 100644 index 54fb08baae22..000000000000 --- a/Documentation/usb/gadget_configfs.txt +++ /dev/null @@ -1,390 +0,0 @@ -============================================ -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 itself 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/ - -e.g.:: - - $ mkdir $CONFIGFS_HOME/usb_gadget/g1 - - ... - ... - ... - - $ cd $CONFIGFS_HOME/usb_gadget/g1 - -Each gadget needs to have its vendor id and product id specified:: - - $ echo > idVendor - $ echo > 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 > strings/0x409/serialnumber - $ echo > strings/0x409/manufacturer - $ echo > strings/0x409/product - -2. Creating the configurations ------------------------------- - -Each gadget will consist of a number of configurations, their corresponding -directories must be created: - -$ mkdir configs/. - -where can be any string which is legal in a filesystem and the - 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 > 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/. - -where 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/. configs/. - -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 - -where 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/./ - -where . specify the configuration and is -a symlink to a function being removed from the configuration, e.g.:: - - $ rm configs/c.1/ncm.usb0 - - ... - ... - ... - -Remove strings directories in configurations: - - $ rmdir configs/./strings/ - -e.g.:: - - $ rmdir configs/c.1/strings/0x409 - - ... - ... - ... - -and remove the configurations:: - - $ rmdir configs/. - -e.g.:: - - rmdir configs/c.1 - - ... - ... - ... - -Remove functions (function modules are not unloaded, though): - - $ rmdir functions/. - -e.g.:: - - $ rmdir functions/ncm.usb0 - - ... - ... - ... - -Remove strings directories in the gadget:: - - $ rmdir strings/ - -e.g.:: - - $ rmdir strings/0x409 - -and finally remove the gadget:: - - $ cd .. - $ rmdir - -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 struct 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. Function'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. diff --git a/Documentation/usb/gadget_hid.rst b/Documentation/usb/gadget_hid.rst new file mode 100644 index 000000000000..098d563040cc --- /dev/null +++ b/Documentation/usb/gadget_hid.rst @@ -0,0 +1,457 @@ +=========================== +Linux USB HID gadget driver +=========================== + +Introduction +============ + +The HID Gadget driver provides emulation of USB Human Interface +Devices (HID). The basic HID handling is done in the kernel, +and HID reports can be sent/received through I/O on the +/dev/hidgX character devices. + +For more details about HID, see the developer page on +http://www.usb.org/developers/hidpage/ + +Configuration +============= + +g_hid is a platform driver, so to use it you need to add +struct platform_device(s) to your platform code defining the +HID function descriptors you want to use - E.G. something +like:: + + #include + #include + + /* hid descriptor for a keyboard */ + static struct hidg_func_descriptor my_hid_data = { + .subclass = 0, /* No subclass */ + .protocol = 1, /* Keyboard */ + .report_length = 8, + .report_desc_length = 63, + .report_desc = { + 0x05, 0x01, /* USAGE_PAGE (Generic Desktop) */ + 0x09, 0x06, /* USAGE (Keyboard) */ + 0xa1, 0x01, /* COLLECTION (Application) */ + 0x05, 0x07, /* USAGE_PAGE (Keyboard) */ + 0x19, 0xe0, /* USAGE_MINIMUM (Keyboard LeftControl) */ + 0x29, 0xe7, /* USAGE_MAXIMUM (Keyboard Right GUI) */ + 0x15, 0x00, /* LOGICAL_MINIMUM (0) */ + 0x25, 0x01, /* LOGICAL_MAXIMUM (1) */ + 0x75, 0x01, /* REPORT_SIZE (1) */ + 0x95, 0x08, /* REPORT_COUNT (8) */ + 0x81, 0x02, /* INPUT (Data,Var,Abs) */ + 0x95, 0x01, /* REPORT_COUNT (1) */ + 0x75, 0x08, /* REPORT_SIZE (8) */ + 0x81, 0x03, /* INPUT (Cnst,Var,Abs) */ + 0x95, 0x05, /* REPORT_COUNT (5) */ + 0x75, 0x01, /* REPORT_SIZE (1) */ + 0x05, 0x08, /* USAGE_PAGE (LEDs) */ + 0x19, 0x01, /* USAGE_MINIMUM (Num Lock) */ + 0x29, 0x05, /* USAGE_MAXIMUM (Kana) */ + 0x91, 0x02, /* OUTPUT (Data,Var,Abs) */ + 0x95, 0x01, /* REPORT_COUNT (1) */ + 0x75, 0x03, /* REPORT_SIZE (3) */ + 0x91, 0x03, /* OUTPUT (Cnst,Var,Abs) */ + 0x95, 0x06, /* REPORT_COUNT (6) */ + 0x75, 0x08, /* REPORT_SIZE (8) */ + 0x15, 0x00, /* LOGICAL_MINIMUM (0) */ + 0x25, 0x65, /* LOGICAL_MAXIMUM (101) */ + 0x05, 0x07, /* USAGE_PAGE (Keyboard) */ + 0x19, 0x00, /* USAGE_MINIMUM (Reserved) */ + 0x29, 0x65, /* USAGE_MAXIMUM (Keyboard Application) */ + 0x81, 0x00, /* INPUT (Data,Ary,Abs) */ + 0xc0 /* END_COLLECTION */ + } + }; + + static struct platform_device my_hid = { + .name = "hidg", + .id = 0, + .num_resources = 0, + .resource = 0, + .dev.platform_data = &my_hid_data, + }; + +You can add as many HID functions as you want, only limited by +the amount of interrupt endpoints your gadget driver supports. + +Configuration with configfs +=========================== + +Instead of adding fake platform devices and drivers in order to pass +some data to the kernel, if HID is a part of a gadget composed with +configfs the hidg_func_descriptor.report_desc is passed to the kernel +by writing the appropriate stream of bytes to a configfs attribute. + +Send and receive HID reports +============================ + +HID reports can be sent/received using read/write on the +/dev/hidgX character devices. See below for an example program +to do this. + +hid_gadget_test is a small interactive program to test the HID +gadget driver. To use, point it at a hidg device and set the +device type (keyboard / mouse / joystick) - E.G.:: + + # hid_gadget_test /dev/hidg0 keyboard + +You are now in the prompt of hid_gadget_test. You can type any +combination of options and values. Available options and +values are listed at program start. In keyboard mode you can +send up to six values. + +For example type: g i s t r --left-shift + +Hit return and the corresponding report will be sent by the +HID gadget. + +Another interesting example is the caps lock test. Type +--caps-lock and hit return. A report is then sent by the +gadget and you should receive the host answer, corresponding +to the caps lock LED status:: + + --caps-lock + recv report:2 + +With this command:: + + # hid_gadget_test /dev/hidg1 mouse + +You can test the mouse emulation. Values are two signed numbers. + + +Sample code:: + + /* hid_gadget_test */ + + #include + #include + #include + #include + #include + #include + #include + #include + #include + + #define BUF_LEN 512 + + struct options { + const char *opt; + unsigned char val; + }; + + static struct options kmod[] = { + {.opt = "--left-ctrl", .val = 0x01}, + {.opt = "--right-ctrl", .val = 0x10}, + {.opt = "--left-shift", .val = 0x02}, + {.opt = "--right-shift", .val = 0x20}, + {.opt = "--left-alt", .val = 0x04}, + {.opt = "--right-alt", .val = 0x40}, + {.opt = "--left-meta", .val = 0x08}, + {.opt = "--right-meta", .val = 0x80}, + {.opt = NULL} + }; + + static struct options kval[] = { + {.opt = "--return", .val = 0x28}, + {.opt = "--esc", .val = 0x29}, + {.opt = "--bckspc", .val = 0x2a}, + {.opt = "--tab", .val = 0x2b}, + {.opt = "--spacebar", .val = 0x2c}, + {.opt = "--caps-lock", .val = 0x39}, + {.opt = "--f1", .val = 0x3a}, + {.opt = "--f2", .val = 0x3b}, + {.opt = "--f3", .val = 0x3c}, + {.opt = "--f4", .val = 0x3d}, + {.opt = "--f5", .val = 0x3e}, + {.opt = "--f6", .val = 0x3f}, + {.opt = "--f7", .val = 0x40}, + {.opt = "--f8", .val = 0x41}, + {.opt = "--f9", .val = 0x42}, + {.opt = "--f10", .val = 0x43}, + {.opt = "--f11", .val = 0x44}, + {.opt = "--f12", .val = 0x45}, + {.opt = "--insert", .val = 0x49}, + {.opt = "--home", .val = 0x4a}, + {.opt = "--pageup", .val = 0x4b}, + {.opt = "--del", .val = 0x4c}, + {.opt = "--end", .val = 0x4d}, + {.opt = "--pagedown", .val = 0x4e}, + {.opt = "--right", .val = 0x4f}, + {.opt = "--left", .val = 0x50}, + {.opt = "--down", .val = 0x51}, + {.opt = "--kp-enter", .val = 0x58}, + {.opt = "--up", .val = 0x52}, + {.opt = "--num-lock", .val = 0x53}, + {.opt = NULL} + }; + + int keyboard_fill_report(char report[8], char buf[BUF_LEN], int *hold) + { + char *tok = strtok(buf, " "); + int key = 0; + int i = 0; + + for (; tok != NULL; tok = strtok(NULL, " ")) { + + if (strcmp(tok, "--quit") == 0) + return -1; + + if (strcmp(tok, "--hold") == 0) { + *hold = 1; + continue; + } + + if (key < 6) { + for (i = 0; kval[i].opt != NULL; i++) + if (strcmp(tok, kval[i].opt) == 0) { + report[2 + key++] = kval[i].val; + break; + } + if (kval[i].opt != NULL) + continue; + } + + if (key < 6) + if (islower(tok[0])) { + report[2 + key++] = (tok[0] - ('a' - 0x04)); + continue; + } + + for (i = 0; kmod[i].opt != NULL; i++) + if (strcmp(tok, kmod[i].opt) == 0) { + report[0] = report[0] | kmod[i].val; + break; + } + if (kmod[i].opt != NULL) + continue; + + if (key < 6) + fprintf(stderr, "unknown option: %s\n", tok); + } + return 8; + } + + static struct options mmod[] = { + {.opt = "--b1", .val = 0x01}, + {.opt = "--b2", .val = 0x02}, + {.opt = "--b3", .val = 0x04}, + {.opt = NULL} + }; + + int mouse_fill_report(char report[8], char buf[BUF_LEN], int *hold) + { + char *tok = strtok(buf, " "); + int mvt = 0; + int i = 0; + for (; tok != NULL; tok = strtok(NULL, " ")) { + + if (strcmp(tok, "--quit") == 0) + return -1; + + if (strcmp(tok, "--hold") == 0) { + *hold = 1; + continue; + } + + for (i = 0; mmod[i].opt != NULL; i++) + if (strcmp(tok, mmod[i].opt) == 0) { + report[0] = report[0] | mmod[i].val; + break; + } + if (mmod[i].opt != NULL) + continue; + + if (!(tok[0] == '-' && tok[1] == '-') && mvt < 2) { + errno = 0; + report[1 + mvt++] = (char)strtol(tok, NULL, 0); + if (errno != 0) { + fprintf(stderr, "Bad value:'%s'\n", tok); + report[1 + mvt--] = 0; + } + continue; + } + + fprintf(stderr, "unknown option: %s\n", tok); + } + return 3; + } + + static struct options jmod[] = { + {.opt = "--b1", .val = 0x10}, + {.opt = "--b2", .val = 0x20}, + {.opt = "--b3", .val = 0x40}, + {.opt = "--b4", .val = 0x80}, + {.opt = "--hat1", .val = 0x00}, + {.opt = "--hat2", .val = 0x01}, + {.opt = "--hat3", .val = 0x02}, + {.opt = "--hat4", .val = 0x03}, + {.opt = "--hatneutral", .val = 0x04}, + {.opt = NULL} + }; + + int joystick_fill_report(char report[8], char buf[BUF_LEN], int *hold) + { + char *tok = strtok(buf, " "); + int mvt = 0; + int i = 0; + + *hold = 1; + + /* set default hat position: neutral */ + report[3] = 0x04; + + for (; tok != NULL; tok = strtok(NULL, " ")) { + + if (strcmp(tok, "--quit") == 0) + return -1; + + for (i = 0; jmod[i].opt != NULL; i++) + if (strcmp(tok, jmod[i].opt) == 0) { + report[3] = (report[3] & 0xF0) | jmod[i].val; + break; + } + if (jmod[i].opt != NULL) + continue; + + if (!(tok[0] == '-' && tok[1] == '-') && mvt < 3) { + errno = 0; + report[mvt++] = (char)strtol(tok, NULL, 0); + if (errno != 0) { + fprintf(stderr, "Bad value:'%s'\n", tok); + report[mvt--] = 0; + } + continue; + } + + fprintf(stderr, "unknown option: %s\n", tok); + } + return 4; + } + + void print_options(char c) + { + int i = 0; + + if (c == 'k') { + printf(" keyboard options:\n" + " --hold\n"); + for (i = 0; kmod[i].opt != NULL; i++) + printf("\t\t%s\n", kmod[i].opt); + printf("\n keyboard values:\n" + " [a-z] or\n"); + for (i = 0; kval[i].opt != NULL; i++) + printf("\t\t%-8s%s", kval[i].opt, i % 2 ? "\n" : ""); + printf("\n"); + } else if (c == 'm') { + printf(" mouse options:\n" + " --hold\n"); + for (i = 0; mmod[i].opt != NULL; i++) + printf("\t\t%s\n", mmod[i].opt); + printf("\n mouse values:\n" + " Two signed numbers\n" + "--quit to close\n"); + } else { + printf(" joystick options:\n"); + for (i = 0; jmod[i].opt != NULL; i++) + printf("\t\t%s\n", jmod[i].opt); + printf("\n joystick values:\n" + " three signed numbers\n" + "--quit to close\n"); + } + } + + int main(int argc, const char *argv[]) + { + const char *filename = NULL; + int fd = 0; + char buf[BUF_LEN]; + int cmd_len; + char report[8]; + int to_send = 8; + int hold = 0; + fd_set rfds; + int retval, i; + + if (argc < 3) { + fprintf(stderr, "Usage: %s devname mouse|keyboard|joystick\n", + argv[0]); + return 1; + } + + if (argv[2][0] != 'k' && argv[2][0] != 'm' && argv[2][0] != 'j') + return 2; + + filename = argv[1]; + + if ((fd = open(filename, O_RDWR, 0666)) == -1) { + perror(filename); + return 3; + } + + print_options(argv[2][0]); + + while (42) { + + FD_ZERO(&rfds); + FD_SET(STDIN_FILENO, &rfds); + FD_SET(fd, &rfds); + + retval = select(fd + 1, &rfds, NULL, NULL, NULL); + if (retval == -1 && errno == EINTR) + continue; + if (retval < 0) { + perror("select()"); + return 4; + } + + if (FD_ISSET(fd, &rfds)) { + cmd_len = read(fd, buf, BUF_LEN - 1); + printf("recv report:"); + for (i = 0; i < cmd_len; i++) + printf(" %02x", buf[i]); + printf("\n"); + } + + if (FD_ISSET(STDIN_FILENO, &rfds)) { + memset(report, 0x0, sizeof(report)); + cmd_len = read(STDIN_FILENO, buf, BUF_LEN - 1); + + if (cmd_len == 0) + break; + + buf[cmd_len - 1] = '\0'; + hold = 0; + + memset(report, 0x0, sizeof(report)); + if (argv[2][0] == 'k') + to_send = keyboard_fill_report(report, buf, &hold); + else if (argv[2][0] == 'm') + to_send = mouse_fill_report(report, buf, &hold); + else + to_send = joystick_fill_report(report, buf, &hold); + + if (to_send == -1) + break; + + if (write(fd, report, to_send) != to_send) { + perror(filename); + return 5; + } + if (!hold) { + memset(report, 0x0, sizeof(report)); + if (write(fd, report, to_send) != to_send) { + perror(filename); + return 6; + } + } + } + } + + close(fd); + return 0; + } diff --git a/Documentation/usb/gadget_hid.txt b/Documentation/usb/gadget_hid.txt deleted file mode 100644 index 098d563040cc..000000000000 --- a/Documentation/usb/gadget_hid.txt +++ /dev/null @@ -1,457 +0,0 @@ -=========================== -Linux USB HID gadget driver -=========================== - -Introduction -============ - -The HID Gadget driver provides emulation of USB Human Interface -Devices (HID). The basic HID handling is done in the kernel, -and HID reports can be sent/received through I/O on the -/dev/hidgX character devices. - -For more details about HID, see the developer page on -http://www.usb.org/developers/hidpage/ - -Configuration -============= - -g_hid is a platform driver, so to use it you need to add -struct platform_device(s) to your platform code defining the -HID function descriptors you want to use - E.G. something -like:: - - #include - #include - - /* hid descriptor for a keyboard */ - static struct hidg_func_descriptor my_hid_data = { - .subclass = 0, /* No subclass */ - .protocol = 1, /* Keyboard */ - .report_length = 8, - .report_desc_length = 63, - .report_desc = { - 0x05, 0x01, /* USAGE_PAGE (Generic Desktop) */ - 0x09, 0x06, /* USAGE (Keyboard) */ - 0xa1, 0x01, /* COLLECTION (Application) */ - 0x05, 0x07, /* USAGE_PAGE (Keyboard) */ - 0x19, 0xe0, /* USAGE_MINIMUM (Keyboard LeftControl) */ - 0x29, 0xe7, /* USAGE_MAXIMUM (Keyboard Right GUI) */ - 0x15, 0x00, /* LOGICAL_MINIMUM (0) */ - 0x25, 0x01, /* LOGICAL_MAXIMUM (1) */ - 0x75, 0x01, /* REPORT_SIZE (1) */ - 0x95, 0x08, /* REPORT_COUNT (8) */ - 0x81, 0x02, /* INPUT (Data,Var,Abs) */ - 0x95, 0x01, /* REPORT_COUNT (1) */ - 0x75, 0x08, /* REPORT_SIZE (8) */ - 0x81, 0x03, /* INPUT (Cnst,Var,Abs) */ - 0x95, 0x05, /* REPORT_COUNT (5) */ - 0x75, 0x01, /* REPORT_SIZE (1) */ - 0x05, 0x08, /* USAGE_PAGE (LEDs) */ - 0x19, 0x01, /* USAGE_MINIMUM (Num Lock) */ - 0x29, 0x05, /* USAGE_MAXIMUM (Kana) */ - 0x91, 0x02, /* OUTPUT (Data,Var,Abs) */ - 0x95, 0x01, /* REPORT_COUNT (1) */ - 0x75, 0x03, /* REPORT_SIZE (3) */ - 0x91, 0x03, /* OUTPUT (Cnst,Var,Abs) */ - 0x95, 0x06, /* REPORT_COUNT (6) */ - 0x75, 0x08, /* REPORT_SIZE (8) */ - 0x15, 0x00, /* LOGICAL_MINIMUM (0) */ - 0x25, 0x65, /* LOGICAL_MAXIMUM (101) */ - 0x05, 0x07, /* USAGE_PAGE (Keyboard) */ - 0x19, 0x00, /* USAGE_MINIMUM (Reserved) */ - 0x29, 0x65, /* USAGE_MAXIMUM (Keyboard Application) */ - 0x81, 0x00, /* INPUT (Data,Ary,Abs) */ - 0xc0 /* END_COLLECTION */ - } - }; - - static struct platform_device my_hid = { - .name = "hidg", - .id = 0, - .num_resources = 0, - .resource = 0, - .dev.platform_data = &my_hid_data, - }; - -You can add as many HID functions as you want, only limited by -the amount of interrupt endpoints your gadget driver supports. - -Configuration with configfs -=========================== - -Instead of adding fake platform devices and drivers in order to pass -some data to the kernel, if HID is a part of a gadget composed with -configfs the hidg_func_descriptor.report_desc is passed to the kernel -by writing the appropriate stream of bytes to a configfs attribute. - -Send and receive HID reports -============================ - -HID reports can be sent/received using read/write on the -/dev/hidgX character devices. See below for an example program -to do this. - -hid_gadget_test is a small interactive program to test the HID -gadget driver. To use, point it at a hidg device and set the -device type (keyboard / mouse / joystick) - E.G.:: - - # hid_gadget_test /dev/hidg0 keyboard - -You are now in the prompt of hid_gadget_test. You can type any -combination of options and values. Available options and -values are listed at program start. In keyboard mode you can -send up to six values. - -For example type: g i s t r --left-shift - -Hit return and the corresponding report will be sent by the -HID gadget. - -Another interesting example is the caps lock test. Type ---caps-lock and hit return. A report is then sent by the -gadget and you should receive the host answer, corresponding -to the caps lock LED status:: - - --caps-lock - recv report:2 - -With this command:: - - # hid_gadget_test /dev/hidg1 mouse - -You can test the mouse emulation. Values are two signed numbers. - - -Sample code:: - - /* hid_gadget_test */ - - #include - #include - #include - #include - #include - #include - #include - #include - #include - - #define BUF_LEN 512 - - struct options { - const char *opt; - unsigned char val; - }; - - static struct options kmod[] = { - {.opt = "--left-ctrl", .val = 0x01}, - {.opt = "--right-ctrl", .val = 0x10}, - {.opt = "--left-shift", .val = 0x02}, - {.opt = "--right-shift", .val = 0x20}, - {.opt = "--left-alt", .val = 0x04}, - {.opt = "--right-alt", .val = 0x40}, - {.opt = "--left-meta", .val = 0x08}, - {.opt = "--right-meta", .val = 0x80}, - {.opt = NULL} - }; - - static struct options kval[] = { - {.opt = "--return", .val = 0x28}, - {.opt = "--esc", .val = 0x29}, - {.opt = "--bckspc", .val = 0x2a}, - {.opt = "--tab", .val = 0x2b}, - {.opt = "--spacebar", .val = 0x2c}, - {.opt = "--caps-lock", .val = 0x39}, - {.opt = "--f1", .val = 0x3a}, - {.opt = "--f2", .val = 0x3b}, - {.opt = "--f3", .val = 0x3c}, - {.opt = "--f4", .val = 0x3d}, - {.opt = "--f5", .val = 0x3e}, - {.opt = "--f6", .val = 0x3f}, - {.opt = "--f7", .val = 0x40}, - {.opt = "--f8", .val = 0x41}, - {.opt = "--f9", .val = 0x42}, - {.opt = "--f10", .val = 0x43}, - {.opt = "--f11", .val = 0x44}, - {.opt = "--f12", .val = 0x45}, - {.opt = "--insert", .val = 0x49}, - {.opt = "--home", .val = 0x4a}, - {.opt = "--pageup", .val = 0x4b}, - {.opt = "--del", .val = 0x4c}, - {.opt = "--end", .val = 0x4d}, - {.opt = "--pagedown", .val = 0x4e}, - {.opt = "--right", .val = 0x4f}, - {.opt = "--left", .val = 0x50}, - {.opt = "--down", .val = 0x51}, - {.opt = "--kp-enter", .val = 0x58}, - {.opt = "--up", .val = 0x52}, - {.opt = "--num-lock", .val = 0x53}, - {.opt = NULL} - }; - - int keyboard_fill_report(char report[8], char buf[BUF_LEN], int *hold) - { - char *tok = strtok(buf, " "); - int key = 0; - int i = 0; - - for (; tok != NULL; tok = strtok(NULL, " ")) { - - if (strcmp(tok, "--quit") == 0) - return -1; - - if (strcmp(tok, "--hold") == 0) { - *hold = 1; - continue; - } - - if (key < 6) { - for (i = 0; kval[i].opt != NULL; i++) - if (strcmp(tok, kval[i].opt) == 0) { - report[2 + key++] = kval[i].val; - break; - } - if (kval[i].opt != NULL) - continue; - } - - if (key < 6) - if (islower(tok[0])) { - report[2 + key++] = (tok[0] - ('a' - 0x04)); - continue; - } - - for (i = 0; kmod[i].opt != NULL; i++) - if (strcmp(tok, kmod[i].opt) == 0) { - report[0] = report[0] | kmod[i].val; - break; - } - if (kmod[i].opt != NULL) - continue; - - if (key < 6) - fprintf(stderr, "unknown option: %s\n", tok); - } - return 8; - } - - static struct options mmod[] = { - {.opt = "--b1", .val = 0x01}, - {.opt = "--b2", .val = 0x02}, - {.opt = "--b3", .val = 0x04}, - {.opt = NULL} - }; - - int mouse_fill_report(char report[8], char buf[BUF_LEN], int *hold) - { - char *tok = strtok(buf, " "); - int mvt = 0; - int i = 0; - for (; tok != NULL; tok = strtok(NULL, " ")) { - - if (strcmp(tok, "--quit") == 0) - return -1; - - if (strcmp(tok, "--hold") == 0) { - *hold = 1; - continue; - } - - for (i = 0; mmod[i].opt != NULL; i++) - if (strcmp(tok, mmod[i].opt) == 0) { - report[0] = report[0] | mmod[i].val; - break; - } - if (mmod[i].opt != NULL) - continue; - - if (!(tok[0] == '-' && tok[1] == '-') && mvt < 2) { - errno = 0; - report[1 + mvt++] = (char)strtol(tok, NULL, 0); - if (errno != 0) { - fprintf(stderr, "Bad value:'%s'\n", tok); - report[1 + mvt--] = 0; - } - continue; - } - - fprintf(stderr, "unknown option: %s\n", tok); - } - return 3; - } - - static struct options jmod[] = { - {.opt = "--b1", .val = 0x10}, - {.opt = "--b2", .val = 0x20}, - {.opt = "--b3", .val = 0x40}, - {.opt = "--b4", .val = 0x80}, - {.opt = "--hat1", .val = 0x00}, - {.opt = "--hat2", .val = 0x01}, - {.opt = "--hat3", .val = 0x02}, - {.opt = "--hat4", .val = 0x03}, - {.opt = "--hatneutral", .val = 0x04}, - {.opt = NULL} - }; - - int joystick_fill_report(char report[8], char buf[BUF_LEN], int *hold) - { - char *tok = strtok(buf, " "); - int mvt = 0; - int i = 0; - - *hold = 1; - - /* set default hat position: neutral */ - report[3] = 0x04; - - for (; tok != NULL; tok = strtok(NULL, " ")) { - - if (strcmp(tok, "--quit") == 0) - return -1; - - for (i = 0; jmod[i].opt != NULL; i++) - if (strcmp(tok, jmod[i].opt) == 0) { - report[3] = (report[3] & 0xF0) | jmod[i].val; - break; - } - if (jmod[i].opt != NULL) - continue; - - if (!(tok[0] == '-' && tok[1] == '-') && mvt < 3) { - errno = 0; - report[mvt++] = (char)strtol(tok, NULL, 0); - if (errno != 0) { - fprintf(stderr, "Bad value:'%s'\n", tok); - report[mvt--] = 0; - } - continue; - } - - fprintf(stderr, "unknown option: %s\n", tok); - } - return 4; - } - - void print_options(char c) - { - int i = 0; - - if (c == 'k') { - printf(" keyboard options:\n" - " --hold\n"); - for (i = 0; kmod[i].opt != NULL; i++) - printf("\t\t%s\n", kmod[i].opt); - printf("\n keyboard values:\n" - " [a-z] or\n"); - for (i = 0; kval[i].opt != NULL; i++) - printf("\t\t%-8s%s", kval[i].opt, i % 2 ? "\n" : ""); - printf("\n"); - } else if (c == 'm') { - printf(" mouse options:\n" - " --hold\n"); - for (i = 0; mmod[i].opt != NULL; i++) - printf("\t\t%s\n", mmod[i].opt); - printf("\n mouse values:\n" - " Two signed numbers\n" - "--quit to close\n"); - } else { - printf(" joystick options:\n"); - for (i = 0; jmod[i].opt != NULL; i++) - printf("\t\t%s\n", jmod[i].opt); - printf("\n joystick values:\n" - " three signed numbers\n" - "--quit to close\n"); - } - } - - int main(int argc, const char *argv[]) - { - const char *filename = NULL; - int fd = 0; - char buf[BUF_LEN]; - int cmd_len; - char report[8]; - int to_send = 8; - int hold = 0; - fd_set rfds; - int retval, i; - - if (argc < 3) { - fprintf(stderr, "Usage: %s devname mouse|keyboard|joystick\n", - argv[0]); - return 1; - } - - if (argv[2][0] != 'k' && argv[2][0] != 'm' && argv[2][0] != 'j') - return 2; - - filename = argv[1]; - - if ((fd = open(filename, O_RDWR, 0666)) == -1) { - perror(filename); - return 3; - } - - print_options(argv[2][0]); - - while (42) { - - FD_ZERO(&rfds); - FD_SET(STDIN_FILENO, &rfds); - FD_SET(fd, &rfds); - - retval = select(fd + 1, &rfds, NULL, NULL, NULL); - if (retval == -1 && errno == EINTR) - continue; - if (retval < 0) { - perror("select()"); - return 4; - } - - if (FD_ISSET(fd, &rfds)) { - cmd_len = read(fd, buf, BUF_LEN - 1); - printf("recv report:"); - for (i = 0; i < cmd_len; i++) - printf(" %02x", buf[i]); - printf("\n"); - } - - if (FD_ISSET(STDIN_FILENO, &rfds)) { - memset(report, 0x0, sizeof(report)); - cmd_len = read(STDIN_FILENO, buf, BUF_LEN - 1); - - if (cmd_len == 0) - break; - - buf[cmd_len - 1] = '\0'; - hold = 0; - - memset(report, 0x0, sizeof(report)); - if (argv[2][0] == 'k') - to_send = keyboard_fill_report(report, buf, &hold); - else if (argv[2][0] == 'm') - to_send = mouse_fill_report(report, buf, &hold); - else - to_send = joystick_fill_report(report, buf, &hold); - - if (to_send == -1) - break; - - if (write(fd, report, to_send) != to_send) { - perror(filename); - return 5; - } - if (!hold) { - memset(report, 0x0, sizeof(report)); - if (write(fd, report, to_send) != to_send) { - perror(filename); - return 6; - } - } - } - } - - close(fd); - return 0; - } diff --git a/Documentation/usb/gadget_multi.rst b/Documentation/usb/gadget_multi.rst new file mode 100644 index 000000000000..9806b55af301 --- /dev/null +++ b/Documentation/usb/gadget_multi.rst @@ -0,0 +1,165 @@ +============================== +Multifunction Composite Gadget +============================== + +Overview +======== + +The Multifunction Composite Gadget (or g_multi) is a composite gadget +that makes extensive use of the composite framework to provide +a... multifunction gadget. + +In it's standard configuration it provides a single USB configuration +with RNDIS[1] (that is Ethernet), USB CDC[2] ACM (that is serial) and +USB Mass Storage functions. + +A CDC ECM (Ethernet) function may be turned on via a Kconfig option +and RNDIS can be turned off. If they are both enabled the gadget will +have two configurations -- one with RNDIS and another with CDC ECM[3]. + +Please note that if you use non-standard configuration (that is enable +CDC ECM) you may need to change vendor and/or product ID. + +Host drivers +============ + +To make use of the gadget one needs to make it work on host side -- +without that there's no hope of achieving anything with the gadget. +As one might expect, things one need to do very from system to system. + +Linux host drivers +------------------ + +Since the gadget uses standard composite framework and appears as such +to Linux host it does not need any additional drivers on Linux host +side. All the functions are handled by respective drivers developed +for them. + +This is also true for two configuration set-up with RNDIS +configuration being the first one. Linux host will use the second +configuration with CDC ECM which should work better under Linux. + +Windows host drivers +-------------------- + +For the gadget to work under Windows two conditions have to be met: + +Detecting as composite gadget +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +First of all, Windows need to detect the gadget as an USB composite +gadget which on its own have some conditions[4]. If they are met, +Windows lets USB Generic Parent Driver[5] handle the device which then +tries to match drivers for each individual interface (sort of, don't +get into too many details). + +The good news is: you do not have to worry about most of the +conditions! + +The only thing to worry is that the gadget has to have a single +configuration so a dual RNDIS and CDC ECM gadget won't work unless you +create a proper INF -- and of course, if you do submit it! + +Installing drivers for each function +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The other, trickier thing is making Windows install drivers for each +individual function. + +For mass storage it is trivial since Windows detect it's an interface +implementing USB Mass Storage class and selects appropriate driver. + +Things are harder with RDNIS and CDC ACM. + +RNDIS +..... + +To make Windows select RNDIS drivers for the first function in the +gadget, one needs to use the [[file:linux.inf]] file provided with this +document. It "attaches" Window's RNDIS driver to the first interface +of the gadget. + +Please note, that while testing we encountered some issues[6] when +RNDIS was not the first interface. You do not need to worry abut it +unless you are trying to develop your own gadget in which case watch +out for this bug. + +CDC ACM +....... + +Similarly, [[file:linux-cdc-acm.inf]] is provided for CDC ACM. + +Customising the gadget +...................... + +If you intend to hack the g_multi gadget be advised that rearranging +functions will obviously change interface numbers for each of the +functionality. As an effect provided INFs won't work since they have +interface numbers hard-coded in them (it's not hard to change those +though[7]). + +This also means, that after experimenting with g_multi and changing +provided functions one should change gadget's vendor and/or product ID +so there will be no collision with other customised gadgets or the +original gadget. + +Failing to comply may cause brain damage after wondering for hours why +things don't work as intended before realising Windows have cached +some drivers information (changing USB port may sometimes help plus +you might try using USBDeview[8] to remove the phantom device). + +INF testing +........... + +Provided INF files have been tested on Windows XP SP3, Windows Vista +and Windows 7, all 32-bit versions. It should work on 64-bit versions +as well. It most likely won't work on Windows prior to Windows XP +SP2. + +Other systems +------------- + +At this moment, drivers for any other systems have not been tested. +Knowing how MacOS is based on BSD and BSD is an Open Source it is +believed that it should (read: "I have no idea whether it will") work +out-of-the-box. + +For more exotic systems I have even less to say... + +Any testing and drivers *are* *welcome*! + +Authors +======= + +This document has been written by Michal Nazarewicz +([[mailto:mina86@mina86.com]]). INF files have been hacked with +support of Marek Szyprowski ([[mailto:m.szyprowski@samsung.com]]) and +Xiaofan Chen ([[mailto:xiaofanc@gmail.com]]) basing on the MS RNDIS +template[9], Microchip's CDC ACM INF file and David Brownell's +([[mailto:dbrownell@users.sourceforge.net]]) original INF files. + +Footnotes +========= + +[1] Remote Network Driver Interface Specification, +[[http://msdn.microsoft.com/en-us/library/ee484414.aspx]]. + +[2] Communications Device Class Abstract Control Model, spec for this +and other USB classes can be found at +[[http://www.usb.org/developers/devclass_docs/]]. + +[3] CDC Ethernet Control Model. + +[4] [[http://msdn.microsoft.com/en-us/library/ff537109(v=VS.85).aspx]] + +[5] [[http://msdn.microsoft.com/en-us/library/ff539234(v=VS.85).aspx]] + +[6] To put it in some other nice words, Windows failed to respond to +any user input. + +[7] You may find [[http://www.cygnal.org/ubb/Forum9/HTML/001050.html]] +useful. + +[8] http://www.nirsoft.net/utils/usb_devices_view.html + +[9] [[http://msdn.microsoft.com/en-us/library/ff570620.aspx]] diff --git a/Documentation/usb/gadget_multi.txt b/Documentation/usb/gadget_multi.txt deleted file mode 100644 index 9806b55af301..000000000000 --- a/Documentation/usb/gadget_multi.txt +++ /dev/null @@ -1,165 +0,0 @@ -============================== -Multifunction Composite Gadget -============================== - -Overview -======== - -The Multifunction Composite Gadget (or g_multi) is a composite gadget -that makes extensive use of the composite framework to provide -a... multifunction gadget. - -In it's standard configuration it provides a single USB configuration -with RNDIS[1] (that is Ethernet), USB CDC[2] ACM (that is serial) and -USB Mass Storage functions. - -A CDC ECM (Ethernet) function may be turned on via a Kconfig option -and RNDIS can be turned off. If they are both enabled the gadget will -have two configurations -- one with RNDIS and another with CDC ECM[3]. - -Please note that if you use non-standard configuration (that is enable -CDC ECM) you may need to change vendor and/or product ID. - -Host drivers -============ - -To make use of the gadget one needs to make it work on host side -- -without that there's no hope of achieving anything with the gadget. -As one might expect, things one need to do very from system to system. - -Linux host drivers ------------------- - -Since the gadget uses standard composite framework and appears as such -to Linux host it does not need any additional drivers on Linux host -side. All the functions are handled by respective drivers developed -for them. - -This is also true for two configuration set-up with RNDIS -configuration being the first one. Linux host will use the second -configuration with CDC ECM which should work better under Linux. - -Windows host drivers --------------------- - -For the gadget to work under Windows two conditions have to be met: - -Detecting as composite gadget -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -First of all, Windows need to detect the gadget as an USB composite -gadget which on its own have some conditions[4]. If they are met, -Windows lets USB Generic Parent Driver[5] handle the device which then -tries to match drivers for each individual interface (sort of, don't -get into too many details). - -The good news is: you do not have to worry about most of the -conditions! - -The only thing to worry is that the gadget has to have a single -configuration so a dual RNDIS and CDC ECM gadget won't work unless you -create a proper INF -- and of course, if you do submit it! - -Installing drivers for each function -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The other, trickier thing is making Windows install drivers for each -individual function. - -For mass storage it is trivial since Windows detect it's an interface -implementing USB Mass Storage class and selects appropriate driver. - -Things are harder with RDNIS and CDC ACM. - -RNDIS -..... - -To make Windows select RNDIS drivers for the first function in the -gadget, one needs to use the [[file:linux.inf]] file provided with this -document. It "attaches" Window's RNDIS driver to the first interface -of the gadget. - -Please note, that while testing we encountered some issues[6] when -RNDIS was not the first interface. You do not need to worry abut it -unless you are trying to develop your own gadget in which case watch -out for this bug. - -CDC ACM -....... - -Similarly, [[file:linux-cdc-acm.inf]] is provided for CDC ACM. - -Customising the gadget -...................... - -If you intend to hack the g_multi gadget be advised that rearranging -functions will obviously change interface numbers for each of the -functionality. As an effect provided INFs won't work since they have -interface numbers hard-coded in them (it's not hard to change those -though[7]). - -This also means, that after experimenting with g_multi and changing -provided functions one should change gadget's vendor and/or product ID -so there will be no collision with other customised gadgets or the -original gadget. - -Failing to comply may cause brain damage after wondering for hours why -things don't work as intended before realising Windows have cached -some drivers information (changing USB port may sometimes help plus -you might try using USBDeview[8] to remove the phantom device). - -INF testing -........... - -Provided INF files have been tested on Windows XP SP3, Windows Vista -and Windows 7, all 32-bit versions. It should work on 64-bit versions -as well. It most likely won't work on Windows prior to Windows XP -SP2. - -Other systems -------------- - -At this moment, drivers for any other systems have not been tested. -Knowing how MacOS is based on BSD and BSD is an Open Source it is -believed that it should (read: "I have no idea whether it will") work -out-of-the-box. - -For more exotic systems I have even less to say... - -Any testing and drivers *are* *welcome*! - -Authors -======= - -This document has been written by Michal Nazarewicz -([[mailto:mina86@mina86.com]]). INF files have been hacked with -support of Marek Szyprowski ([[mailto:m.szyprowski@samsung.com]]) and -Xiaofan Chen ([[mailto:xiaofanc@gmail.com]]) basing on the MS RNDIS -template[9], Microchip's CDC ACM INF file and David Brownell's -([[mailto:dbrownell@users.sourceforge.net]]) original INF files. - -Footnotes -========= - -[1] Remote Network Driver Interface Specification, -[[http://msdn.microsoft.com/en-us/library/ee484414.aspx]]. - -[2] Communications Device Class Abstract Control Model, spec for this -and other USB classes can be found at -[[http://www.usb.org/developers/devclass_docs/]]. - -[3] CDC Ethernet Control Model. - -[4] [[http://msdn.microsoft.com/en-us/library/ff537109(v=VS.85).aspx]] - -[5] [[http://msdn.microsoft.com/en-us/library/ff539234(v=VS.85).aspx]] - -[6] To put it in some other nice words, Windows failed to respond to -any user input. - -[7] You may find [[http://www.cygnal.org/ubb/Forum9/HTML/001050.html]] -useful. - -[8] http://www.nirsoft.net/utils/usb_devices_view.html - -[9] [[http://msdn.microsoft.com/en-us/library/ff570620.aspx]] diff --git a/Documentation/usb/gadget_printer.rst b/Documentation/usb/gadget_printer.rst new file mode 100644 index 000000000000..5e5516c69075 --- /dev/null +++ b/Documentation/usb/gadget_printer.rst @@ -0,0 +1,523 @@ +=============================== +Linux USB Printer Gadget Driver +=============================== + +06/04/2007 + +Copyright (C) 2007 Craig W. Nadler + + + +General +======= + +This driver may be used if you are writing printer firmware using Linux as +the embedded OS. This driver has nothing to do with using a printer with +your Linux host system. + +You will need a USB device controller and a Linux driver for it that accepts +a gadget / "device class" driver using the Linux USB Gadget API. After the +USB device controller driver is loaded then load the printer gadget driver. +This will present a printer interface to the USB Host that your USB Device +port is connected to. + +This driver is structured for printer firmware that runs in user mode. The +user mode printer firmware will read and write data from the kernel mode +printer gadget driver using a device file. The printer returns a printer status +byte when the USB HOST sends a device request to get the printer status. The +user space firmware can read or write this status byte using a device file +/dev/g_printer . Both blocking and non-blocking read/write calls are supported. + + + + +Howto Use This Driver +===================== + +To load the USB device controller driver and the printer gadget driver. The +following example uses the Netchip 2280 USB device controller driver:: + + modprobe net2280 + modprobe g_printer + + +The follow command line parameter can be used when loading the printer gadget +(ex: modprobe g_printer idVendor=0x0525 idProduct=0xa4a8 ): + +idVendor + This is the Vendor ID used in the device descriptor. The default is + the Netchip vendor id 0x0525. YOU MUST CHANGE TO YOUR OWN VENDOR ID + BEFORE RELEASING A PRODUCT. If you plan to release a product and don't + already have a Vendor ID please see www.usb.org for details on how to + get one. + +idProduct + This is the Product ID used in the device descriptor. The default + is 0xa4a8, you should change this to an ID that's not used by any of + your other USB products if you have any. It would be a good idea to + start numbering your products starting with say 0x0001. + +bcdDevice + This is the version number of your product. It would be a good idea + to put your firmware version here. + +iManufacturer + A string containing the name of the Vendor. + +iProduct + A string containing the Product Name. + +iSerialNum + A string containing the Serial Number. This should be changed for + each unit of your product. + +iPNPstring + The PNP ID string used for this printer. You will want to set + either on the command line or hard code the PNP ID string used for + your printer product. + +qlen + The number of 8k buffers to use per endpoint. The default is 10, you + should tune this for your product. You may also want to tune the + size of each buffer for your product. + + + + +Using The Example Code +====================== + +This example code talks to stdout, instead of a print engine. + +To compile the test code below: + +1) save it to a file called prn_example.c +2) compile the code with the follow command:: + + gcc prn_example.c -o prn_example + + + +To read printer data from the host to stdout:: + + # prn_example -read_data + + +To write printer data from a file (data_file) to the host:: + + # cat data_file | prn_example -write_data + + +To get the current printer status for the gadget driver::: + + # prn_example -get_status + + Printer status is: + Printer is NOT Selected + Paper is Out + Printer OK + + +To set printer to Selected/On-line:: + + # prn_example -selected + + +To set printer to Not Selected/Off-line:: + + # prn_example -not_selected + + +To set paper status to paper out:: + + # prn_example -paper_out + + +To set paper status to paper loaded:: + + # prn_example -paper_loaded + + +To set error status to printer OK:: + + # prn_example -no_error + + +To set error status to ERROR:: + + # prn_example -error + + + + +Example Code +============ + +:: + + + #include + #include + #include + #include + #include + #include + + #define PRINTER_FILE "/dev/g_printer" + #define BUF_SIZE 512 + + + /* + * 'usage()' - Show program usage. + */ + + static void + usage(const char *option) /* I - Option string or NULL */ + { + if (option) { + fprintf(stderr,"prn_example: Unknown option \"%s\"!\n", + option); + } + + fputs("\n", stderr); + fputs("Usage: prn_example -[options]\n", stderr); + fputs("Options:\n", stderr); + fputs("\n", stderr); + fputs("-get_status Get the current printer status.\n", stderr); + fputs("-selected Set the selected status to selected.\n", stderr); + fputs("-not_selected Set the selected status to NOT selected.\n", + stderr); + fputs("-error Set the error status to error.\n", stderr); + fputs("-no_error Set the error status to NO error.\n", stderr); + fputs("-paper_out Set the paper status to paper out.\n", stderr); + fputs("-paper_loaded Set the paper status to paper loaded.\n", + stderr); + fputs("-read_data Read printer data from driver.\n", stderr); + fputs("-write_data Write printer sata to driver.\n", stderr); + fputs("-NB_read_data (Non-Blocking) Read printer data from driver.\n", + stderr); + fputs("\n\n", stderr); + + exit(1); + } + + + static int + read_printer_data() + { + struct pollfd fd[1]; + + /* Open device file for printer gadget. */ + fd[0].fd = open(PRINTER_FILE, O_RDWR); + if (fd[0].fd < 0) { + printf("Error %d opening %s\n", fd[0].fd, PRINTER_FILE); + close(fd[0].fd); + return(-1); + } + + fd[0].events = POLLIN | POLLRDNORM; + + while (1) { + static char buf[BUF_SIZE]; + int bytes_read; + int retval; + + /* Wait for up to 1 second for data. */ + retval = poll(fd, 1, 1000); + + if (retval && (fd[0].revents & POLLRDNORM)) { + + /* Read data from printer gadget driver. */ + bytes_read = read(fd[0].fd, buf, BUF_SIZE); + + if (bytes_read < 0) { + printf("Error %d reading from %s\n", + fd[0].fd, PRINTER_FILE); + close(fd[0].fd); + return(-1); + } else if (bytes_read > 0) { + /* Write data to standard OUTPUT (stdout). */ + fwrite(buf, 1, bytes_read, stdout); + fflush(stdout); + } + + } + + } + + /* Close the device file. */ + close(fd[0].fd); + + return 0; + } + + + static int + write_printer_data() + { + struct pollfd fd[1]; + + /* Open device file for printer gadget. */ + fd[0].fd = open (PRINTER_FILE, O_RDWR); + if (fd[0].fd < 0) { + printf("Error %d opening %s\n", fd[0].fd, PRINTER_FILE); + close(fd[0].fd); + return(-1); + } + + fd[0].events = POLLOUT | POLLWRNORM; + + while (1) { + int retval; + static char buf[BUF_SIZE]; + /* Read data from standard INPUT (stdin). */ + int bytes_read = fread(buf, 1, BUF_SIZE, stdin); + + if (!bytes_read) { + break; + } + + while (bytes_read) { + + /* Wait for up to 1 second to sent data. */ + retval = poll(fd, 1, 1000); + + /* Write data to printer gadget driver. */ + if (retval && (fd[0].revents & POLLWRNORM)) { + retval = write(fd[0].fd, buf, bytes_read); + if (retval < 0) { + printf("Error %d writing to %s\n", + fd[0].fd, + PRINTER_FILE); + close(fd[0].fd); + return(-1); + } else { + bytes_read -= retval; + } + + } + + } + + } + + /* Wait until the data has been sent. */ + fsync(fd[0].fd); + + /* Close the device file. */ + close(fd[0].fd); + + return 0; + } + + + static int + read_NB_printer_data() + { + int fd; + static char buf[BUF_SIZE]; + int bytes_read; + + /* Open device file for printer gadget. */ + fd = open(PRINTER_FILE, O_RDWR|O_NONBLOCK); + if (fd < 0) { + printf("Error %d opening %s\n", fd, PRINTER_FILE); + close(fd); + return(-1); + } + + while (1) { + /* Read data from printer gadget driver. */ + bytes_read = read(fd, buf, BUF_SIZE); + if (bytes_read <= 0) { + break; + } + + /* Write data to standard OUTPUT (stdout). */ + fwrite(buf, 1, bytes_read, stdout); + fflush(stdout); + } + + /* Close the device file. */ + close(fd); + + return 0; + } + + + static int + get_printer_status() + { + int retval; + int fd; + + /* Open device file for printer gadget. */ + fd = open(PRINTER_FILE, O_RDWR); + if (fd < 0) { + printf("Error %d opening %s\n", fd, PRINTER_FILE); + close(fd); + return(-1); + } + + /* Make the IOCTL call. */ + retval = ioctl(fd, GADGET_GET_PRINTER_STATUS); + if (retval < 0) { + fprintf(stderr, "ERROR: Failed to set printer status\n"); + return(-1); + } + + /* Close the device file. */ + close(fd); + + return(retval); + } + + + static int + set_printer_status(unsigned char buf, int clear_printer_status_bit) + { + int retval; + int fd; + + retval = get_printer_status(); + if (retval < 0) { + fprintf(stderr, "ERROR: Failed to get printer status\n"); + return(-1); + } + + /* Open device file for printer gadget. */ + fd = open(PRINTER_FILE, O_RDWR); + + if (fd < 0) { + printf("Error %d opening %s\n", fd, PRINTER_FILE); + close(fd); + return(-1); + } + + if (clear_printer_status_bit) { + retval &= ~buf; + } else { + retval |= buf; + } + + /* Make the IOCTL call. */ + if (ioctl(fd, GADGET_SET_PRINTER_STATUS, (unsigned char)retval)) { + fprintf(stderr, "ERROR: Failed to set printer status\n"); + return(-1); + } + + /* Close the device file. */ + close(fd); + + return 0; + } + + + static int + display_printer_status() + { + char printer_status; + + printer_status = get_printer_status(); + if (printer_status < 0) { + fprintf(stderr, "ERROR: Failed to get printer status\n"); + return(-1); + } + + printf("Printer status is:\n"); + if (printer_status & PRINTER_SELECTED) { + printf(" Printer is Selected\n"); + } else { + printf(" Printer is NOT Selected\n"); + } + if (printer_status & PRINTER_PAPER_EMPTY) { + printf(" Paper is Out\n"); + } else { + printf(" Paper is Loaded\n"); + } + if (printer_status & PRINTER_NOT_ERROR) { + printf(" Printer OK\n"); + } else { + printf(" Printer ERROR\n"); + } + + return(0); + } + + + int + main(int argc, char *argv[]) + { + int i; /* Looping var */ + int retval = 0; + + /* No Args */ + if (argc == 1) { + usage(0); + exit(0); + } + + for (i = 1; i < argc && !retval; i ++) { + + if (argv[i][0] != '-') { + continue; + } + + if (!strcmp(argv[i], "-get_status")) { + if (display_printer_status()) { + retval = 1; + } + + } else if (!strcmp(argv[i], "-paper_loaded")) { + if (set_printer_status(PRINTER_PAPER_EMPTY, 1)) { + retval = 1; + } + + } else if (!strcmp(argv[i], "-paper_out")) { + if (set_printer_status(PRINTER_PAPER_EMPTY, 0)) { + retval = 1; + } + + } else if (!strcmp(argv[i], "-selected")) { + if (set_printer_status(PRINTER_SELECTED, 0)) { + retval = 1; + } + + } else if (!strcmp(argv[i], "-not_selected")) { + if (set_printer_status(PRINTER_SELECTED, 1)) { + retval = 1; + } + + } else if (!strcmp(argv[i], "-error")) { + if (set_printer_status(PRINTER_NOT_ERROR, 1)) { + retval = 1; + } + + } else if (!strcmp(argv[i], "-no_error")) { + if (set_printer_status(PRINTER_NOT_ERROR, 0)) { + retval = 1; + } + + } else if (!strcmp(argv[i], "-read_data")) { + if (read_printer_data()) { + retval = 1; + } + + } else if (!strcmp(argv[i], "-write_data")) { + if (write_printer_data()) { + retval = 1; + } + + } else if (!strcmp(argv[i], "-NB_read_data")) { + if (read_NB_printer_data()) { + retval = 1; + } + + } else { + usage(argv[i]); + retval = 1; + } + } + + exit(retval); + } diff --git a/Documentation/usb/gadget_printer.txt b/Documentation/usb/gadget_printer.txt deleted file mode 100644 index 5e5516c69075..000000000000 --- a/Documentation/usb/gadget_printer.txt +++ /dev/null @@ -1,523 +0,0 @@ -=============================== -Linux USB Printer Gadget Driver -=============================== - -06/04/2007 - -Copyright (C) 2007 Craig W. Nadler - - - -General -======= - -This driver may be used if you are writing printer firmware using Linux as -the embedded OS. This driver has nothing to do with using a printer with -your Linux host system. - -You will need a USB device controller and a Linux driver for it that accepts -a gadget / "device class" driver using the Linux USB Gadget API. After the -USB device controller driver is loaded then load the printer gadget driver. -This will present a printer interface to the USB Host that your USB Device -port is connected to. - -This driver is structured for printer firmware that runs in user mode. The -user mode printer firmware will read and write data from the kernel mode -printer gadget driver using a device file. The printer returns a printer status -byte when the USB HOST sends a device request to get the printer status. The -user space firmware can read or write this status byte using a device file -/dev/g_printer . Both blocking and non-blocking read/write calls are supported. - - - - -Howto Use This Driver -===================== - -To load the USB device controller driver and the printer gadget driver. The -following example uses the Netchip 2280 USB device controller driver:: - - modprobe net2280 - modprobe g_printer - - -The follow command line parameter can be used when loading the printer gadget -(ex: modprobe g_printer idVendor=0x0525 idProduct=0xa4a8 ): - -idVendor - This is the Vendor ID used in the device descriptor. The default is - the Netchip vendor id 0x0525. YOU MUST CHANGE TO YOUR OWN VENDOR ID - BEFORE RELEASING A PRODUCT. If you plan to release a product and don't - already have a Vendor ID please see www.usb.org for details on how to - get one. - -idProduct - This is the Product ID used in the device descriptor. The default - is 0xa4a8, you should change this to an ID that's not used by any of - your other USB products if you have any. It would be a good idea to - start numbering your products starting with say 0x0001. - -bcdDevice - This is the version number of your product. It would be a good idea - to put your firmware version here. - -iManufacturer - A string containing the name of the Vendor. - -iProduct - A string containing the Product Name. - -iSerialNum - A string containing the Serial Number. This should be changed for - each unit of your product. - -iPNPstring - The PNP ID string used for this printer. You will want to set - either on the command line or hard code the PNP ID string used for - your printer product. - -qlen - The number of 8k buffers to use per endpoint. The default is 10, you - should tune this for your product. You may also want to tune the - size of each buffer for your product. - - - - -Using The Example Code -====================== - -This example code talks to stdout, instead of a print engine. - -To compile the test code below: - -1) save it to a file called prn_example.c -2) compile the code with the follow command:: - - gcc prn_example.c -o prn_example - - - -To read printer data from the host to stdout:: - - # prn_example -read_data - - -To write printer data from a file (data_file) to the host:: - - # cat data_file | prn_example -write_data - - -To get the current printer status for the gadget driver::: - - # prn_example -get_status - - Printer status is: - Printer is NOT Selected - Paper is Out - Printer OK - - -To set printer to Selected/On-line:: - - # prn_example -selected - - -To set printer to Not Selected/Off-line:: - - # prn_example -not_selected - - -To set paper status to paper out:: - - # prn_example -paper_out - - -To set paper status to paper loaded:: - - # prn_example -paper_loaded - - -To set error status to printer OK:: - - # prn_example -no_error - - -To set error status to ERROR:: - - # prn_example -error - - - - -Example Code -============ - -:: - - - #include - #include - #include - #include - #include - #include - - #define PRINTER_FILE "/dev/g_printer" - #define BUF_SIZE 512 - - - /* - * 'usage()' - Show program usage. - */ - - static void - usage(const char *option) /* I - Option string or NULL */ - { - if (option) { - fprintf(stderr,"prn_example: Unknown option \"%s\"!\n", - option); - } - - fputs("\n", stderr); - fputs("Usage: prn_example -[options]\n", stderr); - fputs("Options:\n", stderr); - fputs("\n", stderr); - fputs("-get_status Get the current printer status.\n", stderr); - fputs("-selected Set the selected status to selected.\n", stderr); - fputs("-not_selected Set the selected status to NOT selected.\n", - stderr); - fputs("-error Set the error status to error.\n", stderr); - fputs("-no_error Set the error status to NO error.\n", stderr); - fputs("-paper_out Set the paper status to paper out.\n", stderr); - fputs("-paper_loaded Set the paper status to paper loaded.\n", - stderr); - fputs("-read_data Read printer data from driver.\n", stderr); - fputs("-write_data Write printer sata to driver.\n", stderr); - fputs("-NB_read_data (Non-Blocking) Read printer data from driver.\n", - stderr); - fputs("\n\n", stderr); - - exit(1); - } - - - static int - read_printer_data() - { - struct pollfd fd[1]; - - /* Open device file for printer gadget. */ - fd[0].fd = open(PRINTER_FILE, O_RDWR); - if (fd[0].fd < 0) { - printf("Error %d opening %s\n", fd[0].fd, PRINTER_FILE); - close(fd[0].fd); - return(-1); - } - - fd[0].events = POLLIN | POLLRDNORM; - - while (1) { - static char buf[BUF_SIZE]; - int bytes_read; - int retval; - - /* Wait for up to 1 second for data. */ - retval = poll(fd, 1, 1000); - - if (retval && (fd[0].revents & POLLRDNORM)) { - - /* Read data from printer gadget driver. */ - bytes_read = read(fd[0].fd, buf, BUF_SIZE); - - if (bytes_read < 0) { - printf("Error %d reading from %s\n", - fd[0].fd, PRINTER_FILE); - close(fd[0].fd); - return(-1); - } else if (bytes_read > 0) { - /* Write data to standard OUTPUT (stdout). */ - fwrite(buf, 1, bytes_read, stdout); - fflush(stdout); - } - - } - - } - - /* Close the device file. */ - close(fd[0].fd); - - return 0; - } - - - static int - write_printer_data() - { - struct pollfd fd[1]; - - /* Open device file for printer gadget. */ - fd[0].fd = open (PRINTER_FILE, O_RDWR); - if (fd[0].fd < 0) { - printf("Error %d opening %s\n", fd[0].fd, PRINTER_FILE); - close(fd[0].fd); - return(-1); - } - - fd[0].events = POLLOUT | POLLWRNORM; - - while (1) { - int retval; - static char buf[BUF_SIZE]; - /* Read data from standard INPUT (stdin). */ - int bytes_read = fread(buf, 1, BUF_SIZE, stdin); - - if (!bytes_read) { - break; - } - - while (bytes_read) { - - /* Wait for up to 1 second to sent data. */ - retval = poll(fd, 1, 1000); - - /* Write data to printer gadget driver. */ - if (retval && (fd[0].revents & POLLWRNORM)) { - retval = write(fd[0].fd, buf, bytes_read); - if (retval < 0) { - printf("Error %d writing to %s\n", - fd[0].fd, - PRINTER_FILE); - close(fd[0].fd); - return(-1); - } else { - bytes_read -= retval; - } - - } - - } - - } - - /* Wait until the data has been sent. */ - fsync(fd[0].fd); - - /* Close the device file. */ - close(fd[0].fd); - - return 0; - } - - - static int - read_NB_printer_data() - { - int fd; - static char buf[BUF_SIZE]; - int bytes_read; - - /* Open device file for printer gadget. */ - fd = open(PRINTER_FILE, O_RDWR|O_NONBLOCK); - if (fd < 0) { - printf("Error %d opening %s\n", fd, PRINTER_FILE); - close(fd); - return(-1); - } - - while (1) { - /* Read data from printer gadget driver. */ - bytes_read = read(fd, buf, BUF_SIZE); - if (bytes_read <= 0) { - break; - } - - /* Write data to standard OUTPUT (stdout). */ - fwrite(buf, 1, bytes_read, stdout); - fflush(stdout); - } - - /* Close the device file. */ - close(fd); - - return 0; - } - - - static int - get_printer_status() - { - int retval; - int fd; - - /* Open device file for printer gadget. */ - fd = open(PRINTER_FILE, O_RDWR); - if (fd < 0) { - printf("Error %d opening %s\n", fd, PRINTER_FILE); - close(fd); - return(-1); - } - - /* Make the IOCTL call. */ - retval = ioctl(fd, GADGET_GET_PRINTER_STATUS); - if (retval < 0) { - fprintf(stderr, "ERROR: Failed to set printer status\n"); - return(-1); - } - - /* Close the device file. */ - close(fd); - - return(retval); - } - - - static int - set_printer_status(unsigned char buf, int clear_printer_status_bit) - { - int retval; - int fd; - - retval = get_printer_status(); - if (retval < 0) { - fprintf(stderr, "ERROR: Failed to get printer status\n"); - return(-1); - } - - /* Open device file for printer gadget. */ - fd = open(PRINTER_FILE, O_RDWR); - - if (fd < 0) { - printf("Error %d opening %s\n", fd, PRINTER_FILE); - close(fd); - return(-1); - } - - if (clear_printer_status_bit) { - retval &= ~buf; - } else { - retval |= buf; - } - - /* Make the IOCTL call. */ - if (ioctl(fd, GADGET_SET_PRINTER_STATUS, (unsigned char)retval)) { - fprintf(stderr, "ERROR: Failed to set printer status\n"); - return(-1); - } - - /* Close the device file. */ - close(fd); - - return 0; - } - - - static int - display_printer_status() - { - char printer_status; - - printer_status = get_printer_status(); - if (printer_status < 0) { - fprintf(stderr, "ERROR: Failed to get printer status\n"); - return(-1); - } - - printf("Printer status is:\n"); - if (printer_status & PRINTER_SELECTED) { - printf(" Printer is Selected\n"); - } else { - printf(" Printer is NOT Selected\n"); - } - if (printer_status & PRINTER_PAPER_EMPTY) { - printf(" Paper is Out\n"); - } else { - printf(" Paper is Loaded\n"); - } - if (printer_status & PRINTER_NOT_ERROR) { - printf(" Printer OK\n"); - } else { - printf(" Printer ERROR\n"); - } - - return(0); - } - - - int - main(int argc, char *argv[]) - { - int i; /* Looping var */ - int retval = 0; - - /* No Args */ - if (argc == 1) { - usage(0); - exit(0); - } - - for (i = 1; i < argc && !retval; i ++) { - - if (argv[i][0] != '-') { - continue; - } - - if (!strcmp(argv[i], "-get_status")) { - if (display_printer_status()) { - retval = 1; - } - - } else if (!strcmp(argv[i], "-paper_loaded")) { - if (set_printer_status(PRINTER_PAPER_EMPTY, 1)) { - retval = 1; - } - - } else if (!strcmp(argv[i], "-paper_out")) { - if (set_printer_status(PRINTER_PAPER_EMPTY, 0)) { - retval = 1; - } - - } else if (!strcmp(argv[i], "-selected")) { - if (set_printer_status(PRINTER_SELECTED, 0)) { - retval = 1; - } - - } else if (!strcmp(argv[i], "-not_selected")) { - if (set_printer_status(PRINTER_SELECTED, 1)) { - retval = 1; - } - - } else if (!strcmp(argv[i], "-error")) { - if (set_printer_status(PRINTER_NOT_ERROR, 1)) { - retval = 1; - } - - } else if (!strcmp(argv[i], "-no_error")) { - if (set_printer_status(PRINTER_NOT_ERROR, 0)) { - retval = 1; - } - - } else if (!strcmp(argv[i], "-read_data")) { - if (read_printer_data()) { - retval = 1; - } - - } else if (!strcmp(argv[i], "-write_data")) { - if (write_printer_data()) { - retval = 1; - } - - } else if (!strcmp(argv[i], "-NB_read_data")) { - if (read_NB_printer_data()) { - retval = 1; - } - - } else { - usage(argv[i]); - retval = 1; - } - } - - exit(retval); - } diff --git a/Documentation/usb/gadget_serial.rst b/Documentation/usb/gadget_serial.rst new file mode 100644 index 000000000000..dce8bc1fb1f2 --- /dev/null +++ b/Documentation/usb/gadget_serial.rst @@ -0,0 +1,289 @@ +=============================== +Linux Gadget Serial Driver v2.0 +=============================== + +11/20/2004 + +(updated 8-May-2008 for v2.3) + + +License and Disclaimer +---------------------- +This program is free software; you can redistribute it and/or +modify it under the terms of the GNU General Public License as +published by the Free Software Foundation; either version 2 of +the License, or (at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public +License along with this program; if not, write to the Free +Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, +MA 02111-1307 USA. + +This document and the gadget serial driver itself are +Copyright (C) 2004 by Al Borchers (alborchers@steinerpoint.com). + +If you have questions, problems, or suggestions for this driver +please contact Al Borchers at alborchers@steinerpoint.com. + + +Prerequisites +------------- +Versions of the gadget serial driver are available for the +2.4 Linux kernels, but this document assumes you are using +version 2.3 or later of the gadget serial driver in a 2.6 +Linux kernel. + +This document assumes that you are familiar with Linux and +Windows and know how to configure and build Linux kernels, run +standard utilities, use minicom and HyperTerminal, and work with +USB and serial devices. It also assumes you configure the Linux +gadget and usb drivers as modules. + +With version 2.3 of the driver, major and minor device nodes are +no longer statically defined. Your Linux based system should mount +sysfs in /sys, and use "mdev" (in Busybox) or "udev" to make the +/dev nodes matching the sysfs /sys/class/tty files. + + + +Overview +-------- +The gadget serial driver is a Linux USB gadget driver, a USB device +side driver. It runs on a Linux system that has USB device side +hardware; for example, a PDA, an embedded Linux system, or a PC +with a USB development card. + +The gadget serial driver talks over USB to either a CDC ACM driver +or a generic USB serial driver running on a host PC:: + + Host + -------------------------------------- + | Host-Side CDC ACM USB Host | + | Operating | or | Controller | USB + | System | Generic USB | Driver |-------- + | (Linux or | Serial | and | | + | Windows) Driver USB Stack | | + -------------------------------------- | + | + | + | + Gadget | + -------------------------------------- | + | Gadget USB Periph. | | + | Device-Side | Gadget | Controller | | + | Linux | Serial | Driver |-------- + | Operating | Driver | and | + | System USB Stack | + -------------------------------------- + +On the device-side Linux system, the gadget serial driver looks +like a serial device. + +On the host-side system, the gadget serial device looks like a +CDC ACM compliant class device or a simple vendor specific device +with bulk in and bulk out endpoints, and it is treated similarly +to other serial devices. + +The host side driver can potentially be any ACM compliant driver +or any driver that can talk to a device with a simple bulk in/out +interface. Gadget serial has been tested with the Linux ACM driver, +the Windows usbser.sys ACM driver, and the Linux USB generic serial +driver. + +With the gadget serial driver and the host side ACM or generic +serial driver running, you should be able to communicate between +the host and the gadget side systems as if they were connected by a +serial cable. + +The gadget serial driver only provides simple unreliable data +communication. It does not yet handle flow control or many other +features of normal serial devices. + + +Installing the Gadget Serial Driver +----------------------------------- +To use the gadget serial driver you must configure the Linux gadget +side kernel for "Support for USB Gadgets", for a "USB Peripheral +Controller" (for example, net2280), and for the "Serial Gadget" +driver. All this are listed under "USB Gadget Support" when +configuring the kernel. Then rebuild and install the kernel or +modules. + +Then you must load the gadget serial driver. To load it as an +ACM device (recommended for interoperability), do this:: + + modprobe g_serial + +To load it as a vendor specific bulk in/out device, do this:: + + modprobe g_serial use_acm=0 + +This will also automatically load the underlying gadget peripheral +controller driver. This must be done each time you reboot the gadget +side Linux system. You can add this to the start up scripts, if +desired. + +Your system should use mdev (from busybox) or udev to make the +device nodes. After this gadget driver has been set up you should +then see a /dev/ttyGS0 node:: + + # ls -l /dev/ttyGS0 | cat + crw-rw---- 1 root root 253, 0 May 8 14:10 /dev/ttyGS0 + # + +Note that the major number (253, above) is system-specific. If +you need to create /dev nodes by hand, the right numbers to use +will be in the /sys/class/tty/ttyGS0/dev file. + +When you link this gadget driver early, perhaps even statically, +you may want to set up an /etc/inittab entry to run "getty" on it. +The /dev/ttyGS0 line should work like most any other serial port. + + +If gadget serial is loaded as an ACM device you will want to use +either the Windows or Linux ACM driver on the host side. If gadget +serial is loaded as a bulk in/out device, you will want to use the +Linux generic serial driver on the host side. Follow the appropriate +instructions below to install the host side driver. + + +Installing the Windows Host ACM Driver +-------------------------------------- +To use the Windows ACM driver you must have the "linux-cdc-acm.inf" +file (provided along this document) which supports all recent versions +of Windows. + +When the gadget serial driver is loaded and the USB device connected +to the Windows host with a USB cable, Windows should recognize the +gadget serial device and ask for a driver. Tell Windows to find the +driver in the folder that contains the "linux-cdc-acm.inf" file. + +For example, on Windows XP, when the gadget serial device is first +plugged in, the "Found New Hardware Wizard" starts up. Select +"Install from a list or specific location (Advanced)", then on the +next screen select "Include this location in the search" and enter the +path or browse to the folder containing the "linux-cdc-acm.inf" file. +Windows will complain that the Gadget Serial driver has not passed +Windows Logo testing, but select "Continue anyway" and finish the +driver installation. + +On Windows XP, in the "Device Manager" (under "Control Panel", +"System", "Hardware") expand the "Ports (COM & LPT)" entry and you +should see "Gadget Serial" listed as the driver for one of the COM +ports. + +To uninstall the Windows XP driver for "Gadget Serial", right click +on the "Gadget Serial" entry in the "Device Manager" and select +"Uninstall". + + +Installing the Linux Host ACM Driver +------------------------------------ +To use the Linux ACM driver you must configure the Linux host side +kernel for "Support for Host-side USB" and for "USB Modem (CDC ACM) +support". + +Once the gadget serial driver is loaded and the USB device connected +to the Linux host with a USB cable, the host system should recognize +the gadget serial device. For example, the command:: + + cat /sys/kernel/debug/usb/devices + +should show something like this::: + + T: Bus=01 Lev=01 Prnt=01 Port=01 Cnt=02 Dev#= 5 Spd=480 MxCh= 0 + D: Ver= 2.00 Cls=02(comm.) Sub=00 Prot=00 MxPS=64 #Cfgs= 1 + P: Vendor=0525 ProdID=a4a7 Rev= 2.01 + S: Manufacturer=Linux 2.6.8.1 with net2280 + S: Product=Gadget Serial + S: SerialNumber=0 + C:* #Ifs= 2 Cfg#= 2 Atr=c0 MxPwr= 2mA + I: If#= 0 Alt= 0 #EPs= 1 Cls=02(comm.) Sub=02 Prot=01 Driver=acm + E: Ad=83(I) Atr=03(Int.) MxPS= 8 Ivl=32ms + I: If#= 1 Alt= 0 #EPs= 2 Cls=0a(data ) Sub=00 Prot=00 Driver=acm + E: Ad=81(I) Atr=02(Bulk) MxPS= 512 Ivl=0ms + E: Ad=02(O) Atr=02(Bulk) MxPS= 512 Ivl=0ms + +If the host side Linux system is configured properly, the ACM driver +should be loaded automatically. The command "lsmod" should show the +"acm" module is loaded. + + +Installing the Linux Host Generic USB Serial Driver +--------------------------------------------------- +To use the Linux generic USB serial driver you must configure the +Linux host side kernel for "Support for Host-side USB", for "USB +Serial Converter support", and for the "USB Generic Serial Driver". + +Once the gadget serial driver is loaded and the USB device connected +to the Linux host with a USB cable, the host system should recognize +the gadget serial device. For example, the command:: + + cat /sys/kernel/debug/usb/devices + +should show something like this::: + + T: Bus=01 Lev=01 Prnt=01 Port=01 Cnt=02 Dev#= 6 Spd=480 MxCh= 0 + D: Ver= 2.00 Cls=ff(vend.) Sub=00 Prot=00 MxPS=64 #Cfgs= 1 + P: Vendor=0525 ProdID=a4a6 Rev= 2.01 + S: Manufacturer=Linux 2.6.8.1 with net2280 + S: Product=Gadget Serial + S: SerialNumber=0 + C:* #Ifs= 1 Cfg#= 1 Atr=c0 MxPwr= 2mA + I: If#= 0 Alt= 0 #EPs= 2 Cls=0a(data ) Sub=00 Prot=00 Driver=serial + E: Ad=81(I) Atr=02(Bulk) MxPS= 512 Ivl=0ms + E: Ad=02(O) Atr=02(Bulk) MxPS= 512 Ivl=0ms + +You must load the usbserial driver and explicitly set its parameters +to configure it to recognize the gadget serial device, like this:: + + echo 0x0525 0xA4A6 >/sys/bus/usb-serial/drivers/generic/new_id + +The legacy way is to use module parameters:: + + modprobe usbserial vendor=0x0525 product=0xA4A6 + +If everything is working, usbserial will print a message in the +system log saying something like "Gadget Serial converter now +attached to ttyUSB0". + + +Testing with Minicom or HyperTerminal +------------------------------------- +Once the gadget serial driver and the host driver are both installed, +and a USB cable connects the gadget device to the host, you should +be able to communicate over USB between the gadget and host systems. +You can use minicom or HyperTerminal to try this out. + +On the gadget side run "minicom -s" to configure a new minicom +session. Under "Serial port setup" set "/dev/ttygserial" as the +"Serial Device". Set baud rate, data bits, parity, and stop bits, +to 9600, 8, none, and 1--these settings mostly do not matter. +Under "Modem and dialing" erase all the modem and dialing strings. + +On a Linux host running the ACM driver, configure minicom similarly +but use "/dev/ttyACM0" as the "Serial Device". (If you have other +ACM devices connected, change the device name appropriately.) + +On a Linux host running the USB generic serial driver, configure +minicom similarly, but use "/dev/ttyUSB0" as the "Serial Device". +(If you have other USB serial devices connected, change the device +name appropriately.) + +On a Windows host configure a new HyperTerminal session to use the +COM port assigned to Gadget Serial. The "Port Settings" will be +set automatically when HyperTerminal connects to the gadget serial +device, so you can leave them set to the default values--these +settings mostly do not matter. + +With minicom configured and running on the gadget side and with +minicom or HyperTerminal configured and running on the host side, +you should be able to send data back and forth between the gadget +side and host side systems. Anything you type on the terminal +window on the gadget side should appear in the terminal window on +the host side and vice versa. diff --git a/Documentation/usb/gadget_serial.txt b/Documentation/usb/gadget_serial.txt deleted file mode 100644 index dce8bc1fb1f2..000000000000 --- a/Documentation/usb/gadget_serial.txt +++ /dev/null @@ -1,289 +0,0 @@ -=============================== -Linux Gadget Serial Driver v2.0 -=============================== - -11/20/2004 - -(updated 8-May-2008 for v2.3) - - -License and Disclaimer ----------------------- -This program is free software; you can redistribute it and/or -modify it under the terms of the GNU General Public License as -published by the Free Software Foundation; either version 2 of -the License, or (at your option) any later version. - -This program is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public -License along with this program; if not, write to the Free -Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, -MA 02111-1307 USA. - -This document and the gadget serial driver itself are -Copyright (C) 2004 by Al Borchers (alborchers@steinerpoint.com). - -If you have questions, problems, or suggestions for this driver -please contact Al Borchers at alborchers@steinerpoint.com. - - -Prerequisites -------------- -Versions of the gadget serial driver are available for the -2.4 Linux kernels, but this document assumes you are using -version 2.3 or later of the gadget serial driver in a 2.6 -Linux kernel. - -This document assumes that you are familiar with Linux and -Windows and know how to configure and build Linux kernels, run -standard utilities, use minicom and HyperTerminal, and work with -USB and serial devices. It also assumes you configure the Linux -gadget and usb drivers as modules. - -With version 2.3 of the driver, major and minor device nodes are -no longer statically defined. Your Linux based system should mount -sysfs in /sys, and use "mdev" (in Busybox) or "udev" to make the -/dev nodes matching the sysfs /sys/class/tty files. - - - -Overview --------- -The gadget serial driver is a Linux USB gadget driver, a USB device -side driver. It runs on a Linux system that has USB device side -hardware; for example, a PDA, an embedded Linux system, or a PC -with a USB development card. - -The gadget serial driver talks over USB to either a CDC ACM driver -or a generic USB serial driver running on a host PC:: - - Host - -------------------------------------- - | Host-Side CDC ACM USB Host | - | Operating | or | Controller | USB - | System | Generic USB | Driver |-------- - | (Linux or | Serial | and | | - | Windows) Driver USB Stack | | - -------------------------------------- | - | - | - | - Gadget | - -------------------------------------- | - | Gadget USB Periph. | | - | Device-Side | Gadget | Controller | | - | Linux | Serial | Driver |-------- - | Operating | Driver | and | - | System USB Stack | - -------------------------------------- - -On the device-side Linux system, the gadget serial driver looks -like a serial device. - -On the host-side system, the gadget serial device looks like a -CDC ACM compliant class device or a simple vendor specific device -with bulk in and bulk out endpoints, and it is treated similarly -to other serial devices. - -The host side driver can potentially be any ACM compliant driver -or any driver that can talk to a device with a simple bulk in/out -interface. Gadget serial has been tested with the Linux ACM driver, -the Windows usbser.sys ACM driver, and the Linux USB generic serial -driver. - -With the gadget serial driver and the host side ACM or generic -serial driver running, you should be able to communicate between -the host and the gadget side systems as if they were connected by a -serial cable. - -The gadget serial driver only provides simple unreliable data -communication. It does not yet handle flow control or many other -features of normal serial devices. - - -Installing the Gadget Serial Driver ------------------------------------ -To use the gadget serial driver you must configure the Linux gadget -side kernel for "Support for USB Gadgets", for a "USB Peripheral -Controller" (for example, net2280), and for the "Serial Gadget" -driver. All this are listed under "USB Gadget Support" when -configuring the kernel. Then rebuild and install the kernel or -modules. - -Then you must load the gadget serial driver. To load it as an -ACM device (recommended for interoperability), do this:: - - modprobe g_serial - -To load it as a vendor specific bulk in/out device, do this:: - - modprobe g_serial use_acm=0 - -This will also automatically load the underlying gadget peripheral -controller driver. This must be done each time you reboot the gadget -side Linux system. You can add this to the start up scripts, if -desired. - -Your system should use mdev (from busybox) or udev to make the -device nodes. After this gadget driver has been set up you should -then see a /dev/ttyGS0 node:: - - # ls -l /dev/ttyGS0 | cat - crw-rw---- 1 root root 253, 0 May 8 14:10 /dev/ttyGS0 - # - -Note that the major number (253, above) is system-specific. If -you need to create /dev nodes by hand, the right numbers to use -will be in the /sys/class/tty/ttyGS0/dev file. - -When you link this gadget driver early, perhaps even statically, -you may want to set up an /etc/inittab entry to run "getty" on it. -The /dev/ttyGS0 line should work like most any other serial port. - - -If gadget serial is loaded as an ACM device you will want to use -either the Windows or Linux ACM driver on the host side. If gadget -serial is loaded as a bulk in/out device, you will want to use the -Linux generic serial driver on the host side. Follow the appropriate -instructions below to install the host side driver. - - -Installing the Windows Host ACM Driver --------------------------------------- -To use the Windows ACM driver you must have the "linux-cdc-acm.inf" -file (provided along this document) which supports all recent versions -of Windows. - -When the gadget serial driver is loaded and the USB device connected -to the Windows host with a USB cable, Windows should recognize the -gadget serial device and ask for a driver. Tell Windows to find the -driver in the folder that contains the "linux-cdc-acm.inf" file. - -For example, on Windows XP, when the gadget serial device is first -plugged in, the "Found New Hardware Wizard" starts up. Select -"Install from a list or specific location (Advanced)", then on the -next screen select "Include this location in the search" and enter the -path or browse to the folder containing the "linux-cdc-acm.inf" file. -Windows will complain that the Gadget Serial driver has not passed -Windows Logo testing, but select "Continue anyway" and finish the -driver installation. - -On Windows XP, in the "Device Manager" (under "Control Panel", -"System", "Hardware") expand the "Ports (COM & LPT)" entry and you -should see "Gadget Serial" listed as the driver for one of the COM -ports. - -To uninstall the Windows XP driver for "Gadget Serial", right click -on the "Gadget Serial" entry in the "Device Manager" and select -"Uninstall". - - -Installing the Linux Host ACM Driver ------------------------------------- -To use the Linux ACM driver you must configure the Linux host side -kernel for "Support for Host-side USB" and for "USB Modem (CDC ACM) -support". - -Once the gadget serial driver is loaded and the USB device connected -to the Linux host with a USB cable, the host system should recognize -the gadget serial device. For example, the command:: - - cat /sys/kernel/debug/usb/devices - -should show something like this::: - - T: Bus=01 Lev=01 Prnt=01 Port=01 Cnt=02 Dev#= 5 Spd=480 MxCh= 0 - D: Ver= 2.00 Cls=02(comm.) Sub=00 Prot=00 MxPS=64 #Cfgs= 1 - P: Vendor=0525 ProdID=a4a7 Rev= 2.01 - S: Manufacturer=Linux 2.6.8.1 with net2280 - S: Product=Gadget Serial - S: SerialNumber=0 - C:* #Ifs= 2 Cfg#= 2 Atr=c0 MxPwr= 2mA - I: If#= 0 Alt= 0 #EPs= 1 Cls=02(comm.) Sub=02 Prot=01 Driver=acm - E: Ad=83(I) Atr=03(Int.) MxPS= 8 Ivl=32ms - I: If#= 1 Alt= 0 #EPs= 2 Cls=0a(data ) Sub=00 Prot=00 Driver=acm - E: Ad=81(I) Atr=02(Bulk) MxPS= 512 Ivl=0ms - E: Ad=02(O) Atr=02(Bulk) MxPS= 512 Ivl=0ms - -If the host side Linux system is configured properly, the ACM driver -should be loaded automatically. The command "lsmod" should show the -"acm" module is loaded. - - -Installing the Linux Host Generic USB Serial Driver ---------------------------------------------------- -To use the Linux generic USB serial driver you must configure the -Linux host side kernel for "Support for Host-side USB", for "USB -Serial Converter support", and for the "USB Generic Serial Driver". - -Once the gadget serial driver is loaded and the USB device connected -to the Linux host with a USB cable, the host system should recognize -the gadget serial device. For example, the command:: - - cat /sys/kernel/debug/usb/devices - -should show something like this::: - - T: Bus=01 Lev=01 Prnt=01 Port=01 Cnt=02 Dev#= 6 Spd=480 MxCh= 0 - D: Ver= 2.00 Cls=ff(vend.) Sub=00 Prot=00 MxPS=64 #Cfgs= 1 - P: Vendor=0525 ProdID=a4a6 Rev= 2.01 - S: Manufacturer=Linux 2.6.8.1 with net2280 - S: Product=Gadget Serial - S: SerialNumber=0 - C:* #Ifs= 1 Cfg#= 1 Atr=c0 MxPwr= 2mA - I: If#= 0 Alt= 0 #EPs= 2 Cls=0a(data ) Sub=00 Prot=00 Driver=serial - E: Ad=81(I) Atr=02(Bulk) MxPS= 512 Ivl=0ms - E: Ad=02(O) Atr=02(Bulk) MxPS= 512 Ivl=0ms - -You must load the usbserial driver and explicitly set its parameters -to configure it to recognize the gadget serial device, like this:: - - echo 0x0525 0xA4A6 >/sys/bus/usb-serial/drivers/generic/new_id - -The legacy way is to use module parameters:: - - modprobe usbserial vendor=0x0525 product=0xA4A6 - -If everything is working, usbserial will print a message in the -system log saying something like "Gadget Serial converter now -attached to ttyUSB0". - - -Testing with Minicom or HyperTerminal -------------------------------------- -Once the gadget serial driver and the host driver are both installed, -and a USB cable connects the gadget device to the host, you should -be able to communicate over USB between the gadget and host systems. -You can use minicom or HyperTerminal to try this out. - -On the gadget side run "minicom -s" to configure a new minicom -session. Under "Serial port setup" set "/dev/ttygserial" as the -"Serial Device". Set baud rate, data bits, parity, and stop bits, -to 9600, 8, none, and 1--these settings mostly do not matter. -Under "Modem and dialing" erase all the modem and dialing strings. - -On a Linux host running the ACM driver, configure minicom similarly -but use "/dev/ttyACM0" as the "Serial Device". (If you have other -ACM devices connected, change the device name appropriately.) - -On a Linux host running the USB generic serial driver, configure -minicom similarly, but use "/dev/ttyUSB0" as the "Serial Device". -(If you have other USB serial devices connected, change the device -name appropriately.) - -On a Windows host configure a new HyperTerminal session to use the -COM port assigned to Gadget Serial. The "Port Settings" will be -set automatically when HyperTerminal connects to the gadget serial -device, so you can leave them set to the default values--these -settings mostly do not matter. - -With minicom configured and running on the gadget side and with -minicom or HyperTerminal configured and running on the host side, -you should be able to send data back and forth between the gadget -side and host side systems. Anything you type on the terminal -window on the gadget side should appear in the terminal window on -the host side and vice versa. diff --git a/Documentation/usb/index.rst b/Documentation/usb/index.rst new file mode 100644 index 000000000000..e55386a4abfb --- /dev/null +++ b/Documentation/usb/index.rst @@ -0,0 +1,39 @@ +=========== +USB support +=========== + +.. toctree:: + :maxdepth: 1 + + acm + authorization + chipidea + dwc3 + ehci + functionfs + gadget_configfs + gadget_hid + gadget_multi + gadget_printer + gadget_serial + gadget-testing + iuu_phoenix + mass-storage + misc_usbsevseg + mtouchusb + ohci + rio + usbip_protocol + usbmon + usb-serial + wusb-design-overview + + usb-help + text_files + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/usb/iuu_phoenix.rst b/Documentation/usb/iuu_phoenix.rst new file mode 100644 index 000000000000..b76268728450 --- /dev/null +++ b/Documentation/usb/iuu_phoenix.rst @@ -0,0 +1,94 @@ +============================= +Infinity Usb Unlimited Readme +============================= + +Hi all, + + +This module provide a serial interface to use your +IUU unit in phoenix mode. Loading this module will +bring a ttyUSB[0-x] interface. This driver must be +used by your favorite application to pilot the IUU + +This driver is still in beta stage, so bugs can +occur and your system may freeze. As far I now, +I never had any problem with it, but I'm not a real +guru, so don't blame me if your system is unstable + +You can plug more than one IUU. Every unit will +have his own device file(/dev/ttyUSB0,/dev/ttyUSB1,...) + + + +How to tune the reader speed? +============================= + + A few parameters can be used at load time + To use parameters, just unload the module if it is + already loaded and use modprobe iuu_phoenix param=value. + In case of prebuilt module, use the command + insmod iuu_phoenix param=value. + + Example:: + + modprobe iuu_phoenix clockmode=3 + + The parameters are: + +clockmode: + 1=3Mhz579,2=3Mhz680,3=6Mhz (int) +boost: + overclock boost percent 100 to 500 (int) +cdmode: + Card detect mode + 0=none, 1=CD, 2=!CD, 3=DSR, 4=!DSR, 5=CTS, 6=!CTS, 7=RING, 8=!RING (int) +xmas: + xmas color enabled or not (bool) +debug: + Debug enabled or not (bool) + +- clockmode will provide 3 different base settings commonly adopted by + different software: + + 1. 3Mhz579 + 2. 3Mhz680 + 3. 6Mhz + +- boost provide a way to overclock the reader ( my favorite :-) ) + For example to have best performance than a simple clockmode=3, try this:: + + modprobe boost=195 + + This will put the reader in a base of 3Mhz579 but boosted a 195 % ! + the real clock will be now : 6979050 Hz ( 6Mhz979 ) and will increase + the speed to a score 10 to 20% better than the simple clockmode=3 !!! + + +- cdmode permit to setup the signal used to inform the userland ( ioctl answer ) + if the card is present or not. Eight signals are possible. + +- xmas is completely useless except for your eyes. This is one of my friend who was + so sad to have a nice device like the iuu without seeing all color range available. + So I have added this option to permit him to see a lot of color ( each activity change the color + and the frequency randomly ) + +- debug will produce a lot of debugging messages... + + +Last notes +========== + + Don't worry about the serial settings, the serial emulation + is an abstraction, so use any speed or parity setting will + work. ( This will not change anything ).Later I will perhaps + use this settings to deduce de boost but is that feature + really necessary ? + The autodetect feature used is the serial CD. If that doesn't + work for your software, disable detection mechanism in it. + + + Have fun ! + + Alain Degreffe + + eczema(at)ecze.com diff --git a/Documentation/usb/iuu_phoenix.txt b/Documentation/usb/iuu_phoenix.txt deleted file mode 100644 index b76268728450..000000000000 --- a/Documentation/usb/iuu_phoenix.txt +++ /dev/null @@ -1,94 +0,0 @@ -============================= -Infinity Usb Unlimited Readme -============================= - -Hi all, - - -This module provide a serial interface to use your -IUU unit in phoenix mode. Loading this module will -bring a ttyUSB[0-x] interface. This driver must be -used by your favorite application to pilot the IUU - -This driver is still in beta stage, so bugs can -occur and your system may freeze. As far I now, -I never had any problem with it, but I'm not a real -guru, so don't blame me if your system is unstable - -You can plug more than one IUU. Every unit will -have his own device file(/dev/ttyUSB0,/dev/ttyUSB1,...) - - - -How to tune the reader speed? -============================= - - A few parameters can be used at load time - To use parameters, just unload the module if it is - already loaded and use modprobe iuu_phoenix param=value. - In case of prebuilt module, use the command - insmod iuu_phoenix param=value. - - Example:: - - modprobe iuu_phoenix clockmode=3 - - The parameters are: - -clockmode: - 1=3Mhz579,2=3Mhz680,3=6Mhz (int) -boost: - overclock boost percent 100 to 500 (int) -cdmode: - Card detect mode - 0=none, 1=CD, 2=!CD, 3=DSR, 4=!DSR, 5=CTS, 6=!CTS, 7=RING, 8=!RING (int) -xmas: - xmas color enabled or not (bool) -debug: - Debug enabled or not (bool) - -- clockmode will provide 3 different base settings commonly adopted by - different software: - - 1. 3Mhz579 - 2. 3Mhz680 - 3. 6Mhz - -- boost provide a way to overclock the reader ( my favorite :-) ) - For example to have best performance than a simple clockmode=3, try this:: - - modprobe boost=195 - - This will put the reader in a base of 3Mhz579 but boosted a 195 % ! - the real clock will be now : 6979050 Hz ( 6Mhz979 ) and will increase - the speed to a score 10 to 20% better than the simple clockmode=3 !!! - - -- cdmode permit to setup the signal used to inform the userland ( ioctl answer ) - if the card is present or not. Eight signals are possible. - -- xmas is completely useless except for your eyes. This is one of my friend who was - so sad to have a nice device like the iuu without seeing all color range available. - So I have added this option to permit him to see a lot of color ( each activity change the color - and the frequency randomly ) - -- debug will produce a lot of debugging messages... - - -Last notes -========== - - Don't worry about the serial settings, the serial emulation - is an abstraction, so use any speed or parity setting will - work. ( This will not change anything ).Later I will perhaps - use this settings to deduce de boost but is that feature - really necessary ? - The autodetect feature used is the serial CD. If that doesn't - work for your software, disable detection mechanism in it. - - - Have fun ! - - Alain Degreffe - - eczema(at)ecze.com diff --git a/Documentation/usb/mass-storage.rst b/Documentation/usb/mass-storage.rst new file mode 100644 index 000000000000..d181b47c3cb6 --- /dev/null +++ b/Documentation/usb/mass-storage.rst @@ -0,0 +1,234 @@ +========================= +Mass Storage Gadget (MSG) +========================= + +Overview +======== + + Mass Storage Gadget (or MSG) acts as a USB Mass Storage device, + appearing to the host as a disk or a CD-ROM drive. It supports + multiple logical units (LUNs). Backing storage for each LUN is + provided by a regular file or a block device, access can be limited + to read-only, and gadget can indicate that it is removable and/or + CD-ROM (the latter implies read-only access). + + Its requirements are modest; only a bulk-in and a bulk-out endpoint + are needed. The memory requirement amounts to two 16K buffers. + Support is included for full-speed, high-speed and SuperSpeed + operation. + + Note that the driver is slightly non-portable in that it assumes + a single memory/DMA buffer will be usable for bulk-in and bulk-out + endpoints. With most device controllers this is not an issue, but + there may be some with hardware restrictions that prevent a buffer + from being used by more than one endpoint. + + This document describes how to use the gadget from user space, its + relation to mass storage function (or MSF) and different gadgets + using it, and how it differs from File Storage Gadget (or FSG) + (which is no longer included in Linux). It will talk only briefly + about how to use MSF within composite gadgets. + +Module parameters +================= + + The mass storage gadget accepts the following mass storage specific + module parameters: + + - file=filename[,filename...] + + This parameter lists paths to files or block devices used for + backing storage for each logical unit. There may be at most + FSG_MAX_LUNS (8) LUNs set. If more files are specified, they will + be silently ignored. See also “luns” parameter. + + *BEWARE* that if a file is used as a backing storage, it may not + be modified by any other process. This is because the host + assumes the data does not change without its knowledge. It may be + read, but (if the logical unit is writable) due to buffering on + the host side, the contents are not well defined. + + The size of the logical unit will be rounded down to a full + logical block. The logical block size is 2048 bytes for LUNs + simulating CD-ROM, block size of the device if the backing file is + a block device, or 512 bytes otherwise. + + - removable=b[,b...] + + This parameter specifies whether each logical unit should be + removable. “b” here is either “y”, “Y” or “1” for true or “n”, + “N” or “0” for false. + + If this option is set for a logical unit, gadget will accept an + “eject” SCSI request (Start/Stop Unit). When it is sent, the + backing file will be closed to simulate ejection and the logical + unit will not be mountable by the host until a new backing file is + specified by userspace on the device (see “sysfs entries” + section). + + If a logical unit is not removable (the default), a backing file + must be specified for it with the “file” parameter as the module + is loaded. The same applies if the module is built in, no + exceptions. + + The default value of the flag is false, *HOWEVER* it used to be + true. This has been changed to better match File Storage Gadget + and because it seems like a saner default after all. Thus to + maintain compatibility with older kernels, it's best to specify + the default values. Also, if one relied on old default, explicit + “n” needs to be specified now. + + Note that “removable” means the logical unit's media can be + ejected or removed (as is true for a CD-ROM drive or a card + reader). It does *not* mean that the entire gadget can be + unplugged from the host; the proper term for that is + “hot-unpluggable”. + + - cdrom=b[,b...] + + This parameter specifies whether each logical unit should simulate + CD-ROM. The default is false. + + - ro=b[,b...] + + This parameter specifies whether each logical unit should be + reported as read only. This will prevent host from modifying the + backing files. + + Note that if this flag for given logical unit is false but the + backing file could not be opened in read/write mode, the gadget + will fall back to read only mode anyway. + + The default value for non-CD-ROM logical units is false; for + logical units simulating CD-ROM it is forced to true. + + - nofua=b[,b...] + + This parameter specifies whether FUA flag should be ignored in SCSI + Write10 and Write12 commands sent to given logical units. + + MS Windows mounts removable storage in “Removal optimised mode” by + default. All the writes to the media are synchronous, which is + achieved by setting the FUA (Force Unit Access) bit in SCSI + Write(10,12) commands. This forces each write to wait until the + data has actually been written out and prevents I/O requests + aggregation in block layer dramatically decreasing performance. + + Note that this may mean that if the device is powered from USB and + the user unplugs the device without unmounting it first (which at + least some Windows users do), the data may be lost. + + The default value is false. + + - luns=N + + This parameter specifies number of logical units the gadget will + have. It is limited by FSG_MAX_LUNS (8) and higher value will be + capped. + + If this parameter is provided, and the number of files specified + in “file” argument is greater then the value of “luns”, all excess + files will be ignored. + + If this parameter is not present, the number of logical units will + be deduced from the number of files specified in the “file” + parameter. If the file parameter is missing as well, one is + assumed. + + - stall=b + + Specifies whether the gadget is allowed to halt bulk endpoints. + The default is determined according to the type of USB device + controller, but usually true. + + In addition to the above, the gadget also accepts the following + parameters defined by the composite framework (they are common to + all composite gadgets so just a quick listing): + + - idVendor -- USB Vendor ID (16 bit integer) + - idProduct -- USB Product ID (16 bit integer) + - bcdDevice -- USB Device version (BCD) (16 bit integer) + - iManufacturer -- USB Manufacturer string (string) + - iProduct -- USB Product string (string) + - iSerialNumber -- SerialNumber string (sting) + +sysfs entries +============= + + For each logical unit, the gadget creates a directory in the sysfs + hierarchy. Inside of it the following three files are created: + + - file + + When read it returns the path to the backing file for the given + logical unit. If there is no backing file (possible only if the + logical unit is removable), the content is empty. + + When written into, it changes the backing file for given logical + unit. This change can be performed even if given logical unit is + not specified as removable (but that may look strange to the + host). It may fail, however, if host disallowed medium removal + with the Prevent-Allow Medium Removal SCSI command. + + - ro + + Reflects the state of ro flag for the given logical unit. It can + be read any time, and written to when there is no backing file + open for given logical unit. + + - nofua + + Reflects the state of nofua flag for given logical unit. It can + be read and written. + + Other then those, as usual, the values of module parameters can be + read from /sys/module/g_mass_storage/parameters/* files. + +Other gadgets using mass storage function +========================================= + + The Mass Storage Gadget uses the Mass Storage Function to handle + mass storage protocol. As a composite function, MSF may be used by + other gadgets as well (eg. g_multi and acm_ms). + + All of the information in previous sections are valid for other + gadgets using MSF, except that support for mass storage related + module parameters may be missing, or the parameters may have + a prefix. To figure out whether any of this is true one needs to + consult the gadget's documentation or its source code. + + For examples of how to include mass storage function in gadgets, one + may take a look at mass_storage.c, acm_ms.c and multi.c (sorted by + complexity). + +Relation to file storage gadget +=============================== + + The Mass Storage Function and thus the Mass Storage Gadget has been + based on the File Storage Gadget. The difference between the two is + that MSG is a composite gadget (ie. uses the composite framework) + while file storage gadget was a traditional gadget. From userspace + point of view this distinction does not really matter, but from + kernel hacker's point of view, this means that (i) MSG does not + duplicate code needed for handling basic USB protocol commands and + (ii) MSF can be used in any other composite gadget. + + Because of that, File Storage Gadget has been removed in Linux 3.8. + All users need to transition to the Mass Storage Gadget. The two + gadgets behave mostly the same from the outside except: + + 1. In FSG the “removable” and “cdrom” module parameters set the flag + for all logical units whereas in MSG they accept a list of y/n + values for each logical unit. If one uses only a single logical + unit this does not matter, but if there are more, the y/n value + needs to be repeated for each logical unit. + + 2. FSG's “serial”, “vendor”, “product” and “release” module + parameters are handled in MSG by the composite layer's parameters + named respectively: “iSerialnumber”, “idVendor”, “idProduct” and + “bcdDevice”. + + 3. MSG does not support FSG's test mode, thus “transport”, + “protocol” and “buflen” FSG's module parameters are not + supported. MSG always uses SCSI protocol with bulk only + transport mode and 16 KiB buffers. diff --git a/Documentation/usb/mass-storage.txt b/Documentation/usb/mass-storage.txt deleted file mode 100644 index d181b47c3cb6..000000000000 --- a/Documentation/usb/mass-storage.txt +++ /dev/null @@ -1,234 +0,0 @@ -========================= -Mass Storage Gadget (MSG) -========================= - -Overview -======== - - Mass Storage Gadget (or MSG) acts as a USB Mass Storage device, - appearing to the host as a disk or a CD-ROM drive. It supports - multiple logical units (LUNs). Backing storage for each LUN is - provided by a regular file or a block device, access can be limited - to read-only, and gadget can indicate that it is removable and/or - CD-ROM (the latter implies read-only access). - - Its requirements are modest; only a bulk-in and a bulk-out endpoint - are needed. The memory requirement amounts to two 16K buffers. - Support is included for full-speed, high-speed and SuperSpeed - operation. - - Note that the driver is slightly non-portable in that it assumes - a single memory/DMA buffer will be usable for bulk-in and bulk-out - endpoints. With most device controllers this is not an issue, but - there may be some with hardware restrictions that prevent a buffer - from being used by more than one endpoint. - - This document describes how to use the gadget from user space, its - relation to mass storage function (or MSF) and different gadgets - using it, and how it differs from File Storage Gadget (or FSG) - (which is no longer included in Linux). It will talk only briefly - about how to use MSF within composite gadgets. - -Module parameters -================= - - The mass storage gadget accepts the following mass storage specific - module parameters: - - - file=filename[,filename...] - - This parameter lists paths to files or block devices used for - backing storage for each logical unit. There may be at most - FSG_MAX_LUNS (8) LUNs set. If more files are specified, they will - be silently ignored. See also “luns” parameter. - - *BEWARE* that if a file is used as a backing storage, it may not - be modified by any other process. This is because the host - assumes the data does not change without its knowledge. It may be - read, but (if the logical unit is writable) due to buffering on - the host side, the contents are not well defined. - - The size of the logical unit will be rounded down to a full - logical block. The logical block size is 2048 bytes for LUNs - simulating CD-ROM, block size of the device if the backing file is - a block device, or 512 bytes otherwise. - - - removable=b[,b...] - - This parameter specifies whether each logical unit should be - removable. “b” here is either “y”, “Y” or “1” for true or “n”, - “N” or “0” for false. - - If this option is set for a logical unit, gadget will accept an - “eject” SCSI request (Start/Stop Unit). When it is sent, the - backing file will be closed to simulate ejection and the logical - unit will not be mountable by the host until a new backing file is - specified by userspace on the device (see “sysfs entries” - section). - - If a logical unit is not removable (the default), a backing file - must be specified for it with the “file” parameter as the module - is loaded. The same applies if the module is built in, no - exceptions. - - The default value of the flag is false, *HOWEVER* it used to be - true. This has been changed to better match File Storage Gadget - and because it seems like a saner default after all. Thus to - maintain compatibility with older kernels, it's best to specify - the default values. Also, if one relied on old default, explicit - “n” needs to be specified now. - - Note that “removable” means the logical unit's media can be - ejected or removed (as is true for a CD-ROM drive or a card - reader). It does *not* mean that the entire gadget can be - unplugged from the host; the proper term for that is - “hot-unpluggable”. - - - cdrom=b[,b...] - - This parameter specifies whether each logical unit should simulate - CD-ROM. The default is false. - - - ro=b[,b...] - - This parameter specifies whether each logical unit should be - reported as read only. This will prevent host from modifying the - backing files. - - Note that if this flag for given logical unit is false but the - backing file could not be opened in read/write mode, the gadget - will fall back to read only mode anyway. - - The default value for non-CD-ROM logical units is false; for - logical units simulating CD-ROM it is forced to true. - - - nofua=b[,b...] - - This parameter specifies whether FUA flag should be ignored in SCSI - Write10 and Write12 commands sent to given logical units. - - MS Windows mounts removable storage in “Removal optimised mode” by - default. All the writes to the media are synchronous, which is - achieved by setting the FUA (Force Unit Access) bit in SCSI - Write(10,12) commands. This forces each write to wait until the - data has actually been written out and prevents I/O requests - aggregation in block layer dramatically decreasing performance. - - Note that this may mean that if the device is powered from USB and - the user unplugs the device without unmounting it first (which at - least some Windows users do), the data may be lost. - - The default value is false. - - - luns=N - - This parameter specifies number of logical units the gadget will - have. It is limited by FSG_MAX_LUNS (8) and higher value will be - capped. - - If this parameter is provided, and the number of files specified - in “file” argument is greater then the value of “luns”, all excess - files will be ignored. - - If this parameter is not present, the number of logical units will - be deduced from the number of files specified in the “file” - parameter. If the file parameter is missing as well, one is - assumed. - - - stall=b - - Specifies whether the gadget is allowed to halt bulk endpoints. - The default is determined according to the type of USB device - controller, but usually true. - - In addition to the above, the gadget also accepts the following - parameters defined by the composite framework (they are common to - all composite gadgets so just a quick listing): - - - idVendor -- USB Vendor ID (16 bit integer) - - idProduct -- USB Product ID (16 bit integer) - - bcdDevice -- USB Device version (BCD) (16 bit integer) - - iManufacturer -- USB Manufacturer string (string) - - iProduct -- USB Product string (string) - - iSerialNumber -- SerialNumber string (sting) - -sysfs entries -============= - - For each logical unit, the gadget creates a directory in the sysfs - hierarchy. Inside of it the following three files are created: - - - file - - When read it returns the path to the backing file for the given - logical unit. If there is no backing file (possible only if the - logical unit is removable), the content is empty. - - When written into, it changes the backing file for given logical - unit. This change can be performed even if given logical unit is - not specified as removable (but that may look strange to the - host). It may fail, however, if host disallowed medium removal - with the Prevent-Allow Medium Removal SCSI command. - - - ro - - Reflects the state of ro flag for the given logical unit. It can - be read any time, and written to when there is no backing file - open for given logical unit. - - - nofua - - Reflects the state of nofua flag for given logical unit. It can - be read and written. - - Other then those, as usual, the values of module parameters can be - read from /sys/module/g_mass_storage/parameters/* files. - -Other gadgets using mass storage function -========================================= - - The Mass Storage Gadget uses the Mass Storage Function to handle - mass storage protocol. As a composite function, MSF may be used by - other gadgets as well (eg. g_multi and acm_ms). - - All of the information in previous sections are valid for other - gadgets using MSF, except that support for mass storage related - module parameters may be missing, or the parameters may have - a prefix. To figure out whether any of this is true one needs to - consult the gadget's documentation or its source code. - - For examples of how to include mass storage function in gadgets, one - may take a look at mass_storage.c, acm_ms.c and multi.c (sorted by - complexity). - -Relation to file storage gadget -=============================== - - The Mass Storage Function and thus the Mass Storage Gadget has been - based on the File Storage Gadget. The difference between the two is - that MSG is a composite gadget (ie. uses the composite framework) - while file storage gadget was a traditional gadget. From userspace - point of view this distinction does not really matter, but from - kernel hacker's point of view, this means that (i) MSG does not - duplicate code needed for handling basic USB protocol commands and - (ii) MSF can be used in any other composite gadget. - - Because of that, File Storage Gadget has been removed in Linux 3.8. - All users need to transition to the Mass Storage Gadget. The two - gadgets behave mostly the same from the outside except: - - 1. In FSG the “removable” and “cdrom” module parameters set the flag - for all logical units whereas in MSG they accept a list of y/n - values for each logical unit. If one uses only a single logical - unit this does not matter, but if there are more, the y/n value - needs to be repeated for each logical unit. - - 2. FSG's “serial”, “vendor”, “product” and “release” module - parameters are handled in MSG by the composite layer's parameters - named respectively: “iSerialnumber”, “idVendor”, “idProduct” and - “bcdDevice”. - - 3. MSG does not support FSG's test mode, thus “transport”, - “protocol” and “buflen” FSG's module parameters are not - supported. MSG always uses SCSI protocol with bulk only - transport mode and 16 KiB buffers. diff --git a/Documentation/usb/misc_usbsevseg.rst b/Documentation/usb/misc_usbsevseg.rst new file mode 100644 index 000000000000..6274aee083ed --- /dev/null +++ b/Documentation/usb/misc_usbsevseg.rst @@ -0,0 +1,51 @@ +============================= +USB 7-Segment Numeric Display +============================= + +Manufactured by Delcom Engineering + +Device Information +------------------ +USB VENDOR_ID 0x0fc5 +USB PRODUCT_ID 0x1227 +Both the 6 character and 8 character displays have PRODUCT_ID, +and according to Delcom Engineering no queryable information +can be obtained from the device to tell them apart. + +Device Modes +------------ +By default, the driver assumes the display is only 6 characters +The mode for 6 characters is: + + MSB 0x06; LSB 0x3f + +For the 8 character display: + + MSB 0x08; LSB 0xff + +The device can accept "text" either in raw, hex, or ascii textmode. +raw controls each segment manually, +hex expects a value between 0-15 per character, +ascii expects a value between '0'-'9' and 'A'-'F'. +The default is ascii. + +Device Operation +---------------- +1. Turn on the device: + echo 1 > /sys/bus/usb/.../powered +2. Set the device's mode: + echo $mode_msb > /sys/bus/usb/.../mode_msb + echo $mode_lsb > /sys/bus/usb/.../mode_lsb +3. Set the textmode: + echo $textmode > /sys/bus/usb/.../textmode +4. set the text (for example): + echo "123ABC" > /sys/bus/usb/.../text (ascii) + echo "A1B2" > /sys/bus/usb/.../text (ascii) + echo -ne "\x01\x02\x03" > /sys/bus/usb/.../text (hex) +5. Set the decimal places. + The device has either 6 or 8 decimal points. + to set the nth decimal place calculate 10 ** n + and echo it in to /sys/bus/usb/.../decimals + To set multiple decimals points sum up each power. + For example, to set the 0th and 3rd decimal place + echo 1001 > /sys/bus/usb/.../decimals diff --git a/Documentation/usb/misc_usbsevseg.txt b/Documentation/usb/misc_usbsevseg.txt deleted file mode 100644 index 6274aee083ed..000000000000 --- a/Documentation/usb/misc_usbsevseg.txt +++ /dev/null @@ -1,51 +0,0 @@ -============================= -USB 7-Segment Numeric Display -============================= - -Manufactured by Delcom Engineering - -Device Information ------------------- -USB VENDOR_ID 0x0fc5 -USB PRODUCT_ID 0x1227 -Both the 6 character and 8 character displays have PRODUCT_ID, -and according to Delcom Engineering no queryable information -can be obtained from the device to tell them apart. - -Device Modes ------------- -By default, the driver assumes the display is only 6 characters -The mode for 6 characters is: - - MSB 0x06; LSB 0x3f - -For the 8 character display: - - MSB 0x08; LSB 0xff - -The device can accept "text" either in raw, hex, or ascii textmode. -raw controls each segment manually, -hex expects a value between 0-15 per character, -ascii expects a value between '0'-'9' and 'A'-'F'. -The default is ascii. - -Device Operation ----------------- -1. Turn on the device: - echo 1 > /sys/bus/usb/.../powered -2. Set the device's mode: - echo $mode_msb > /sys/bus/usb/.../mode_msb - echo $mode_lsb > /sys/bus/usb/.../mode_lsb -3. Set the textmode: - echo $textmode > /sys/bus/usb/.../textmode -4. set the text (for example): - echo "123ABC" > /sys/bus/usb/.../text (ascii) - echo "A1B2" > /sys/bus/usb/.../text (ascii) - echo -ne "\x01\x02\x03" > /sys/bus/usb/.../text (hex) -5. Set the decimal places. - The device has either 6 or 8 decimal points. - to set the nth decimal place calculate 10 ** n - and echo it in to /sys/bus/usb/.../decimals - To set multiple decimals points sum up each power. - For example, to set the 0th and 3rd decimal place - echo 1001 > /sys/bus/usb/.../decimals diff --git a/Documentation/usb/mtouchusb.rst b/Documentation/usb/mtouchusb.rst new file mode 100644 index 000000000000..d1111b74bf75 --- /dev/null +++ b/Documentation/usb/mtouchusb.rst @@ -0,0 +1,84 @@ +================ +mtouchusb driver +================ + +Changes +======= + +- 0.3 - Created based off of scanner & INSTALL from the original touchscreen + driver on freecode (http://freecode.com/projects/3mtouchscreendriver) +- Amended for linux-2.4.18, then 2.4.19 + +- 0.5 - Complete rewrite using Linux Input in 2.6.3 + Unfortunately no calibration support at this time + +- 1.4 - Multiple changes to support the EXII 5000UC and house cleaning + Changed reset from standard USB dev reset to vendor reset + Changed data sent to host from compensated to raw coordinates + Eliminated vendor/product module params + Performed multiple successful tests with an EXII-5010UC + +Supported Hardware +================== + +:: + + All controllers have the Vendor: 0x0596 & Product: 0x0001 + + + Controller Description Part Number + ------------------------------------------------------ + + USB Capacitive - Pearl Case 14-205 (Discontinued) + USB Capacitive - Black Case 14-124 (Discontinued) + USB Capacitive - No Case 14-206 (Discontinued) + + USB Capacitive - Pearl Case EXII-5010UC + USB Capacitive - Black Case EXII-5030UC + USB Capacitive - No Case EXII-5050UC + +Driver Notes +============ + +Installation is simple, you only need to add Linux Input, Linux USB, and the +driver to the kernel. The driver can also be optionally built as a module. + +This driver appears to be one of possible 2 Linux USB Input Touchscreen +drivers. Although 3M produces a binary only driver available for +download, I persist in updating this driver since I would like to use the +touchscreen for embedded apps using QTEmbedded, DirectFB, etc. So I feel the +logical choice is to use Linux Input. + +Currently there is no way to calibrate the device via this driver. Even if +the device could be calibrated, the driver pulls to raw coordinate data from +the controller. This means calibration must be performed within the +userspace. + +The controller screen resolution is now 0 to 16384 for both X and Y reporting +the raw touch data. This is the same for the old and new capacitive USB +controllers. + +Perhaps at some point an abstract function will be placed into evdev so +generic functions like calibrations, resets, and vendor information can be +requested from the userspace (And the drivers would handle the vendor specific +tasks). + +TODO +==== + +Implement a control urb again to handle requests to and from the device +such as calibration, etc once/if it becomes available. + +Disclaimer +========== + +I am not a MicroTouch/3M employee, nor have I ever been. 3M does not support +this driver! If you want touch drivers only supported within X, please go to: + +http://www.3m.com/3MTouchSystems/ + +Thanks +====== + +A huge thank you to 3M Touch Systems for the EXII-5010UC controllers for +testing! diff --git a/Documentation/usb/mtouchusb.txt b/Documentation/usb/mtouchusb.txt deleted file mode 100644 index d1111b74bf75..000000000000 --- a/Documentation/usb/mtouchusb.txt +++ /dev/null @@ -1,84 +0,0 @@ -================ -mtouchusb driver -================ - -Changes -======= - -- 0.3 - Created based off of scanner & INSTALL from the original touchscreen - driver on freecode (http://freecode.com/projects/3mtouchscreendriver) -- Amended for linux-2.4.18, then 2.4.19 - -- 0.5 - Complete rewrite using Linux Input in 2.6.3 - Unfortunately no calibration support at this time - -- 1.4 - Multiple changes to support the EXII 5000UC and house cleaning - Changed reset from standard USB dev reset to vendor reset - Changed data sent to host from compensated to raw coordinates - Eliminated vendor/product module params - Performed multiple successful tests with an EXII-5010UC - -Supported Hardware -================== - -:: - - All controllers have the Vendor: 0x0596 & Product: 0x0001 - - - Controller Description Part Number - ------------------------------------------------------ - - USB Capacitive - Pearl Case 14-205 (Discontinued) - USB Capacitive - Black Case 14-124 (Discontinued) - USB Capacitive - No Case 14-206 (Discontinued) - - USB Capacitive - Pearl Case EXII-5010UC - USB Capacitive - Black Case EXII-5030UC - USB Capacitive - No Case EXII-5050UC - -Driver Notes -============ - -Installation is simple, you only need to add Linux Input, Linux USB, and the -driver to the kernel. The driver can also be optionally built as a module. - -This driver appears to be one of possible 2 Linux USB Input Touchscreen -drivers. Although 3M produces a binary only driver available for -download, I persist in updating this driver since I would like to use the -touchscreen for embedded apps using QTEmbedded, DirectFB, etc. So I feel the -logical choice is to use Linux Input. - -Currently there is no way to calibrate the device via this driver. Even if -the device could be calibrated, the driver pulls to raw coordinate data from -the controller. This means calibration must be performed within the -userspace. - -The controller screen resolution is now 0 to 16384 for both X and Y reporting -the raw touch data. This is the same for the old and new capacitive USB -controllers. - -Perhaps at some point an abstract function will be placed into evdev so -generic functions like calibrations, resets, and vendor information can be -requested from the userspace (And the drivers would handle the vendor specific -tasks). - -TODO -==== - -Implement a control urb again to handle requests to and from the device -such as calibration, etc once/if it becomes available. - -Disclaimer -========== - -I am not a MicroTouch/3M employee, nor have I ever been. 3M does not support -this driver! If you want touch drivers only supported within X, please go to: - -http://www.3m.com/3MTouchSystems/ - -Thanks -====== - -A huge thank you to 3M Touch Systems for the EXII-5010UC controllers for -testing! diff --git a/Documentation/usb/ohci.rst b/Documentation/usb/ohci.rst new file mode 100644 index 000000000000..bb3c49719e6b --- /dev/null +++ b/Documentation/usb/ohci.rst @@ -0,0 +1,35 @@ +==== +OHCI +==== + +23-Aug-2002 + +The "ohci-hcd" driver is a USB Host Controller Driver (HCD) that is derived +from the "usb-ohci" driver from the 2.4 kernel series. The "usb-ohci" code +was written primarily by Roman Weissgaerber but with +contributions from many others (read its copyright/licencing header). + +It supports the "Open Host Controller Interface" (OHCI), which standardizes +hardware register protocols used to talk to USB 1.1 host controllers. As +compared to the earlier "Universal Host Controller Interface" (UHCI) from +Intel, it pushes more intelligence into the hardware. USB 1.1 controllers +from vendors other than Intel and VIA generally use OHCI. + +Changes since the 2.4 kernel include + + - improved robustness; bugfixes; and less overhead + - supports the updated and simplified usbcore APIs + - interrupt transfers can be larger, and can be queued + - less code, by using the upper level "hcd" framework + - supports some non-PCI implementations of OHCI + - ... more + +The "ohci-hcd" driver handles all USB 1.1 transfer types. Transfers of all +types can be queued. That was also true in "usb-ohci", except for interrupt +transfers. Previously, using periods of one frame would risk data loss due +to overhead in IRQ processing. When interrupt transfers are queued, those +risks can be minimized by making sure the hardware always has transfers to +work on while the OS is getting around to the relevant IRQ processing. + +- David Brownell + diff --git a/Documentation/usb/ohci.txt b/Documentation/usb/ohci.txt deleted file mode 100644 index bb3c49719e6b..000000000000 --- a/Documentation/usb/ohci.txt +++ /dev/null @@ -1,35 +0,0 @@ -==== -OHCI -==== - -23-Aug-2002 - -The "ohci-hcd" driver is a USB Host Controller Driver (HCD) that is derived -from the "usb-ohci" driver from the 2.4 kernel series. The "usb-ohci" code -was written primarily by Roman Weissgaerber but with -contributions from many others (read its copyright/licencing header). - -It supports the "Open Host Controller Interface" (OHCI), which standardizes -hardware register protocols used to talk to USB 1.1 host controllers. As -compared to the earlier "Universal Host Controller Interface" (UHCI) from -Intel, it pushes more intelligence into the hardware. USB 1.1 controllers -from vendors other than Intel and VIA generally use OHCI. - -Changes since the 2.4 kernel include - - - improved robustness; bugfixes; and less overhead - - supports the updated and simplified usbcore APIs - - interrupt transfers can be larger, and can be queued - - less code, by using the upper level "hcd" framework - - supports some non-PCI implementations of OHCI - - ... more - -The "ohci-hcd" driver handles all USB 1.1 transfer types. Transfers of all -types can be queued. That was also true in "usb-ohci", except for interrupt -transfers. Previously, using periods of one frame would risk data loss due -to overhead in IRQ processing. When interrupt transfers are queued, those -risks can be minimized by making sure the hardware always has transfers to -work on while the OS is getting around to the relevant IRQ processing. - -- David Brownell - diff --git a/Documentation/usb/rio.rst b/Documentation/usb/rio.rst new file mode 100644 index 000000000000..ea73475471db --- /dev/null +++ b/Documentation/usb/rio.rst @@ -0,0 +1,109 @@ +============ +Diamonds Rio +============ + +Copyright (C) 1999, 2000 Bruce Tenison + +Portions Copyright (C) 1999, 2000 David Nelson + +Thanks to David Nelson for guidance and the usage of the scanner.txt +and scanner.c files to model our driver and this informative file. + +Mar. 2, 2000 + +Changes +======= + +- Initial Revision + + +Overview +======== + +This README will address issues regarding how to configure the kernel +to access a RIO 500 mp3 player. +Before I explain how to use this to access the Rio500 please be warned: + +.. warning:: + + Please note that this software is still under development. The authors + are in no way responsible for any damage that may occur, no matter how + inconsequential. + +It seems that the Rio has a problem when sending .mp3 with low batteries. +I suggest when the batteries are low and you want to transfer stuff that you +replace it with a fresh one. In my case, what happened is I lost two 16kb +blocks (they are no longer usable to store information to it). But I don't +know if that's normal or not; it could simply be a problem with the flash +memory. + +In an extreme case, I left my Rio playing overnight and the batteries wore +down to nothing and appear to have corrupted the flash memory. My RIO +needed to be replaced as a result. Diamond tech support is aware of the +problem. Do NOT allow your batteries to wear down to nothing before +changing them. It appears RIO 500 firmware does not handle low battery +power well at all. + +On systems with OHCI controllers, the kernel OHCI code appears to have +power on problems with some chipsets. If you are having problems +connecting to your RIO 500, try turning it on first and then plugging it +into the USB cable. + +Contact Information +------------------- + + The main page for the project is hosted at sourceforge.net in the following + URL: . You can also go to the project's + sourceforge home page at: . + There is also a mailing list: rio500-users@lists.sourceforge.net + +Authors +------- + +Most of the code was written by Cesar Miquel . Keith +Clayton is incharge of the PPC port and making sure +things work there. Bruce Tenison is adding support +for .fon files and also does testing. The program will mostly sure be +re-written and Pete Ikusz along with the rest will re-design it. I would +also like to thank Tri Nguyen who provided use +with some important information regarding the communication with the Rio. + +Additional Information and userspace tools + + http://rio500.sourceforge.net/ + + +Requirements +============ + +A host with a USB port running a Linux kernel with RIO 500 support enabled. + +The driver is a module called rio500, which should be automatically loaded +as you plug in your device. If that fails you can manually load it with + + modprobe rio500 + +Udev should automatically create a device node as soon as plug in your device. +If that fails, you can manually add a device for the USB rio500:: + + mknod /dev/usb/rio500 c 180 64 + +In that case, set appropriate permissions for /dev/usb/rio500 (don't forget +about group and world permissions). Both read and write permissions are +required for proper operation. + +That's it. The Rio500 Utils at: http://rio500.sourceforge.net should +be able to access the rio500. + +Limits +====== + +You can use only a single rio500 device at a time with your computer. + +Bugs +==== + +If you encounter any problems feel free to drop me an email. + +Bruce Tenison +btenison@dibbs.net diff --git a/Documentation/usb/rio.txt b/Documentation/usb/rio.txt deleted file mode 100644 index ea73475471db..000000000000 --- a/Documentation/usb/rio.txt +++ /dev/null @@ -1,109 +0,0 @@ -============ -Diamonds Rio -============ - -Copyright (C) 1999, 2000 Bruce Tenison - -Portions Copyright (C) 1999, 2000 David Nelson - -Thanks to David Nelson for guidance and the usage of the scanner.txt -and scanner.c files to model our driver and this informative file. - -Mar. 2, 2000 - -Changes -======= - -- Initial Revision - - -Overview -======== - -This README will address issues regarding how to configure the kernel -to access a RIO 500 mp3 player. -Before I explain how to use this to access the Rio500 please be warned: - -.. warning:: - - Please note that this software is still under development. The authors - are in no way responsible for any damage that may occur, no matter how - inconsequential. - -It seems that the Rio has a problem when sending .mp3 with low batteries. -I suggest when the batteries are low and you want to transfer stuff that you -replace it with a fresh one. In my case, what happened is I lost two 16kb -blocks (they are no longer usable to store information to it). But I don't -know if that's normal or not; it could simply be a problem with the flash -memory. - -In an extreme case, I left my Rio playing overnight and the batteries wore -down to nothing and appear to have corrupted the flash memory. My RIO -needed to be replaced as a result. Diamond tech support is aware of the -problem. Do NOT allow your batteries to wear down to nothing before -changing them. It appears RIO 500 firmware does not handle low battery -power well at all. - -On systems with OHCI controllers, the kernel OHCI code appears to have -power on problems with some chipsets. If you are having problems -connecting to your RIO 500, try turning it on first and then plugging it -into the USB cable. - -Contact Information -------------------- - - The main page for the project is hosted at sourceforge.net in the following - URL: . You can also go to the project's - sourceforge home page at: . - There is also a mailing list: rio500-users@lists.sourceforge.net - -Authors -------- - -Most of the code was written by Cesar Miquel . Keith -Clayton is incharge of the PPC port and making sure -things work there. Bruce Tenison is adding support -for .fon files and also does testing. The program will mostly sure be -re-written and Pete Ikusz along with the rest will re-design it. I would -also like to thank Tri Nguyen who provided use -with some important information regarding the communication with the Rio. - -Additional Information and userspace tools - - http://rio500.sourceforge.net/ - - -Requirements -============ - -A host with a USB port running a Linux kernel with RIO 500 support enabled. - -The driver is a module called rio500, which should be automatically loaded -as you plug in your device. If that fails you can manually load it with - - modprobe rio500 - -Udev should automatically create a device node as soon as plug in your device. -If that fails, you can manually add a device for the USB rio500:: - - mknod /dev/usb/rio500 c 180 64 - -In that case, set appropriate permissions for /dev/usb/rio500 (don't forget -about group and world permissions). Both read and write permissions are -required for proper operation. - -That's it. The Rio500 Utils at: http://rio500.sourceforge.net should -be able to access the rio500. - -Limits -====== - -You can use only a single rio500 device at a time with your computer. - -Bugs -==== - -If you encounter any problems feel free to drop me an email. - -Bruce Tenison -btenison@dibbs.net diff --git a/Documentation/usb/text_files.rst b/Documentation/usb/text_files.rst new file mode 100644 index 000000000000..6a8d3fcf64b6 --- /dev/null +++ b/Documentation/usb/text_files.rst @@ -0,0 +1,29 @@ +Linux CDC ACM inf +----------------- + +.. include:: linux-cdc-acm.inf + :literal: + +Linux inf +--------- + +.. include:: linux.inf + :literal: + +USB devfs drop permissions source +--------------------------------- + +.. literalinclude:: usbdevfs-drop-permissions.c + :language: c + +WUSB command line script to manipulate auth credentials +------------------------------------------------------- + +.. literalinclude:: wusb-cbaf + :language: shell + +Credits +------- + +.. include:: CREDITS + :literal: diff --git a/Documentation/usb/usb-help.rst b/Documentation/usb/usb-help.rst new file mode 100644 index 000000000000..dc23ecd4d802 --- /dev/null +++ b/Documentation/usb/usb-help.rst @@ -0,0 +1,17 @@ +============== +USB references +============== + +2008-Mar-7 + +For USB help other than the readme files that are located in +`Documentation/usb/*`, see the following: + +- Linux-USB project: http://www.linux-usb.org + mirrors at http://usb.in.tum.de/linux-usb/ + and http://it.linux-usb.org +- Linux USB Guide: http://linux-usb.sourceforge.net +- Linux-USB device overview (working devices and drivers): + http://www.qbik.ch/usb/devices/ + +The Linux-USB mailing list is at linux-usb@vger.kernel.org diff --git a/Documentation/usb/usb-help.txt b/Documentation/usb/usb-help.txt deleted file mode 100644 index dc23ecd4d802..000000000000 --- a/Documentation/usb/usb-help.txt +++ /dev/null @@ -1,17 +0,0 @@ -============== -USB references -============== - -2008-Mar-7 - -For USB help other than the readme files that are located in -`Documentation/usb/*`, see the following: - -- Linux-USB project: http://www.linux-usb.org - mirrors at http://usb.in.tum.de/linux-usb/ - and http://it.linux-usb.org -- Linux USB Guide: http://linux-usb.sourceforge.net -- Linux-USB device overview (working devices and drivers): - http://www.qbik.ch/usb/devices/ - -The Linux-USB mailing list is at linux-usb@vger.kernel.org diff --git a/Documentation/usb/usb-serial.rst b/Documentation/usb/usb-serial.rst new file mode 100644 index 000000000000..8fa7dbd3da9a --- /dev/null +++ b/Documentation/usb/usb-serial.rst @@ -0,0 +1,537 @@ +========== +USB serial +========== + +Introduction +============ + + The USB serial driver currently supports a number of different USB to + serial converter products, as well as some devices that use a serial + interface from userspace to talk to the device. + + See the individual product section below for specific information about + the different devices. + + +Configuration +============= + + Currently the driver can handle up to 256 different serial interfaces at + one time. + + The major number that the driver uses is 188 so to use the driver, + create the following nodes:: + + mknod /dev/ttyUSB0 c 188 0 + mknod /dev/ttyUSB1 c 188 1 + mknod /dev/ttyUSB2 c 188 2 + mknod /dev/ttyUSB3 c 188 3 + . + . + . + mknod /dev/ttyUSB254 c 188 254 + mknod /dev/ttyUSB255 c 188 255 + + When the device is connected and recognized by the driver, the driver + will print to the system log, which node(s) the device has been bound + to. + + +Specific Devices Supported +========================== + + +ConnectTech WhiteHEAT 4 port converter +-------------------------------------- + + ConnectTech has been very forthcoming with information about their + device, including providing a unit to test with. + + The driver is officially supported by Connect Tech Inc. + http://www.connecttech.com + + For any questions or problems with this driver, please contact + Connect Tech's Support Department at support@connecttech.com + + +HandSpring Visor, Palm USB, and Clié USB driver +----------------------------------------------- + + This driver works with all HandSpring USB, Palm USB, and Sony Clié USB + devices. + + Only when the device tries to connect to the host, will the device show + up to the host as a valid USB device. When this happens, the device is + properly enumerated, assigned a port, and then communication _should_ be + possible. The driver cleans up properly when the device is removed, or + the connection is canceled on the device. + + NOTE: + This means that in order to talk to the device, the sync button must be + pressed BEFORE trying to get any program to communicate to the device. + This goes against the current documentation for pilot-xfer and other + packages, but is the only way that it will work due to the hardware + in the device. + + When the device is connected, try talking to it on the second port + (this is usually /dev/ttyUSB1 if you do not have any other usb-serial + devices in the system.) The system log should tell you which port is + the port to use for the HotSync transfer. The "Generic" port can be used + for other device communication, such as a PPP link. + + For some Sony Clié devices, /dev/ttyUSB0 must be used to talk to the + device. This is true for all OS version 3.5 devices, and most devices + that have had a flash upgrade to a newer version of the OS. See the + kernel system log for information on which is the correct port to use. + + If after pressing the sync button, nothing shows up in the system log, + try resetting the device, first a hot reset, and then a cold reset if + necessary. Some devices need this before they can talk to the USB port + properly. + + Devices that are not compiled into the kernel can be specified with module + parameters. e.g. modprobe visor vendor=0x54c product=0x66 + + There is a webpage and mailing lists for this portion of the driver at: + http://sourceforge.net/projects/usbvisor/ + + For any questions or problems with this driver, please contact Greg + Kroah-Hartman at greg@kroah.com + + +PocketPC PDA Driver +------------------- + + This driver can be used to connect to Compaq iPAQ, HP Jornada, Casio EM500 + and other PDAs running Windows CE 3.0 or PocketPC 2002 using a USB + cable/cradle. + Most devices supported by ActiveSync are supported out of the box. + For others, please use module parameters to specify the product and vendor + id. e.g. modprobe ipaq vendor=0x3f0 product=0x1125 + + The driver presents a serial interface (usually on /dev/ttyUSB0) over + which one may run ppp and establish a TCP/IP link to the PDA. Once this + is done, you can transfer files, backup, download email etc. The most + significant advantage of using USB is speed - I can get 73 to 113 + kbytes/sec for download/upload to my iPAQ. + + This driver is only one of a set of components required to utilize + the USB connection. Please visit http://synce.sourceforge.net which + contains the necessary packages and a simple step-by-step howto. + + Once connected, you can use Win CE programs like ftpView, Pocket Outlook + from the PDA and xcerdisp, synce utilities from the Linux side. + + To use Pocket IE, follow the instructions given at + http://www.tekguru.co.uk/EM500/usbtonet.htm to achieve the same thing + on Win98. Omit the proxy server part; Linux is quite capable of forwarding + packets unlike Win98. Another modification is required at least for the + iPAQ - disable autosync by going to the Start/Settings/Connections menu + and unchecking the "Automatically synchronize ..." box. Go to + Start/Programs/Connections, connect the cable and select "usbdial" (or + whatever you named your new USB connection). You should finally wind + up with a "Connected to usbdial" window with status shown as connected. + Now start up PIE and browse away. + + If it doesn't work for some reason, load both the usbserial and ipaq module + with the module parameter "debug" set to 1 and examine the system log. + You can also try soft-resetting your PDA before attempting a connection. + + Other functionality may be possible depending on your PDA. According to + Wes Cilldhaire , with the Toshiba E570, + ...if you boot into the bootloader (hold down the power when hitting the + reset button, continuing to hold onto the power until the bootloader screen + is displayed), then put it in the cradle with the ipaq driver loaded, open + a terminal on /dev/ttyUSB0, it gives you a "USB Reflash" terminal, which can + be used to flash the ROM, as well as the microP code.. so much for needing + Toshiba's $350 serial cable for flashing!! :D + NOTE: This has NOT been tested. Use at your own risk. + + For any questions or problems with the driver, please contact Ganesh + Varadarajan + + +Keyspan PDA Serial Adapter +-------------------------- + + Single port DB-9 serial adapter, pushed as a PDA adapter for iMacs (mostly + sold in Macintosh catalogs, comes in a translucent white/green dongle). + Fairly simple device. Firmware is homebrew. + This driver also works for the Xircom/Entrega single port serial adapter. + + Current status: + + Things that work: + - basic input/output (tested with 'cu') + - blocking write when serial line can't keep up + - changing baud rates (up to 115200) + - getting/setting modem control pins (TIOCM{GET,SET,BIS,BIC}) + - sending break (although duration looks suspect) + + Things that don't: + - device strings (as logged by kernel) have trailing binary garbage + - device ID isn't right, might collide with other Keyspan products + - changing baud rates ought to flush tx/rx to avoid mangled half characters + + Big Things on the todo list: + - parity, 7 vs 8 bits per char, 1 or 2 stop bits + - HW flow control + - not all of the standard USB descriptors are handled: + Get_Status, Set_Feature, O_NONBLOCK, select() + + For any questions or problems with this driver, please contact Brian + Warner at warner@lothar.com + + +Keyspan USA-series Serial Adapters +---------------------------------- + + Single, Dual and Quad port adapters - driver uses Keyspan supplied + firmware and is being developed with their support. + + Current status: + + The USA-18X, USA-28X, USA-19, USA-19W and USA-49W are supported and + have been pretty thoroughly tested at various baud rates with 8-N-1 + character settings. Other character lengths and parity setups are + presently untested. + + The USA-28 isn't yet supported though doing so should be pretty + straightforward. Contact the maintainer if you require this + functionality. + + More information is available at: + + http://www.carnationsoftware.com/carnation/Keyspan.html + + For any questions or problems with this driver, please contact Hugh + Blemings at hugh@misc.nu + + +FTDI Single Port Serial Driver +------------------------------ + + This is a single port DB-25 serial adapter. + + Devices supported include: + + - TripNav TN-200 USB GPS + - Navis Engineering Bureau CH-4711 USB GPS + + For any questions or problems with this driver, please contact Bill Ryder. + + +ZyXEL omni.net lcd plus ISDN TA +------------------------------- + + This is an ISDN TA. Please report both successes and troubles to + azummo@towertech.it + + +Cypress M8 CY4601 Family Serial Driver +-------------------------------------- + + This driver was in most part developed by Neil "koyama" Whelchel. It + has been improved since that previous form to support dynamic serial + line settings and improved line handling. The driver is for the most + part stable and has been tested on an smp machine. (dual p2) + + Chipsets supported under CY4601 family: + + CY7C63723, CY7C63742, CY7C63743, CY7C64013 + + Devices supported: + + - DeLorme's USB Earthmate GPS (SiRF Star II lp arch) + - Cypress HID->COM RS232 adapter + + Note: + Cypress Semiconductor claims no affiliation with the + hid->com device. + + Most devices using chipsets under the CY4601 family should + work with the driver. As long as they stay true to the CY4601 + usbserial specification. + + Technical notes: + + The Earthmate starts out at 4800 8N1 by default... the driver will + upon start init to this setting. usbserial core provides the rest + of the termios settings, along with some custom termios so that the + output is in proper format and parsable. + + The device can be put into sirf mode by issuing NMEA command:: + + $PSRF100,,,,,*CHECKSUM + $PSRF100,0,9600,8,1,0*0C + + It should then be sufficient to change the port termios to match this + to begin communicating. + + As far as I can tell it supports pretty much every sirf command as + documented online available with firmware 2.31, with some unknown + message ids. + + The hid->com adapter can run at a maximum baud of 115200bps. Please note + that the device has trouble or is incapable of raising line voltage properly. + It will be fine with null modem links, as long as you do not try to link two + together without hacking the adapter to set the line high. + + The driver is smp safe. Performance with the driver is rather low when using + it for transferring files. This is being worked on, but I would be willing to + accept patches. An urb queue or packet buffer would likely fit the bill here. + + If you have any questions, problems, patches, feature requests, etc. you can + contact me here via email: + + dignome@gmail.com + + (your problems/patches can alternately be submitted to usb-devel) + + +Digi AccelePort Driver +---------------------- + + This driver supports the Digi AccelePort USB 2 and 4 devices, 2 port + (plus a parallel port) and 4 port USB serial converters. The driver + does NOT yet support the Digi AccelePort USB 8. + + This driver works under SMP with the usb-uhci driver. It does not + work under SMP with the uhci driver. + + The driver is generally working, though we still have a few more ioctls + to implement and final testing and debugging to do. The parallel port + on the USB 2 is supported as a serial to parallel converter; in other + words, it appears as another USB serial port on Linux, even though + physically it is really a parallel port. The Digi Acceleport USB 8 + is not yet supported. + + Please contact Peter Berger (pberger@brimson.com) or Al Borchers + (alborchers@steinerpoint.com) for questions or problems with this + driver. + + +Belkin USB Serial Adapter F5U103 +-------------------------------- + + Single port DB-9/PS-2 serial adapter from Belkin with firmware by eTEK Labs. + The Peracom single port serial adapter also works with this driver, as + well as the GoHubs adapter. + + Current status: + + The following have been tested and work: + + - Baud rate 300-230400 + - Data bits 5-8 + - Stop bits 1-2 + - Parity N,E,O,M,S + - Handshake None, Software (XON/XOFF), Hardware (CTSRTS,CTSDTR) [1]_ + - Break Set and clear + - Line control Input/Output query and control [2]_ + + .. [1] + Hardware input flow control is only enabled for firmware + levels above 2.06. Read source code comments describing Belkin + firmware errata. Hardware output flow control is working for all + firmware versions. + + .. [2] + Queries of inputs (CTS,DSR,CD,RI) show the last + reported state. Queries of outputs (DTR,RTS) show the last + requested state and may not reflect current state as set by + automatic hardware flow control. + + TO DO List: + - Add true modem control line query capability. Currently tracks the + states reported by the interrupt and the states requested. + - Add error reporting back to application for UART error conditions. + - Add support for flush ioctls. + - Add everything else that is missing :) + + For any questions or problems with this driver, please contact William + Greathouse at wgreathouse@smva.com + + +Empeg empeg-car Mark I/II Driver +-------------------------------- + + This is an experimental driver to provide connectivity support for the + client synchronization tools for an Empeg empeg-car mp3 player. + + Tips: + * Don't forget to create the device nodes for ttyUSB{0,1,2,...} + * modprobe empeg (modprobe is your friend) + * emptool --usb /dev/ttyUSB0 (or whatever you named your device node) + + For any questions or problems with this driver, please contact Gary + Brubaker at xavyer@ix.netcom.com + + +MCT USB Single Port Serial Adapter U232 +--------------------------------------- + + This driver is for the MCT USB-RS232 Converter (25 pin, Model No. + U232-P25) from Magic Control Technology Corp. (there is also a 9 pin + Model No. U232-P9). More information about this device can be found at + the manufacturer's web-site: http://www.mct.com.tw. + + The driver is generally working, though it still needs some more testing. + It is derived from the Belkin USB Serial Adapter F5U103 driver and its + TODO list is valid for this driver as well. + + This driver has also been found to work for other products, which have + the same Vendor ID but different Product IDs. Sitecom's U232-P25 serial + converter uses Product ID 0x230 and Vendor ID 0x711 and works with this + driver. Also, D-Link's DU-H3SP USB BAY also works with this driver. + + For any questions or problems with this driver, please contact Wolfgang + Grandegger at wolfgang@ces.ch + + +Inside Out Networks Edgeport Driver +----------------------------------- + + This driver supports all devices made by Inside Out Networks, specifically + the following models: + + - Edgeport/4 + - Rapidport/4 + - Edgeport/4t + - Edgeport/2 + - Edgeport/4i + - Edgeport/2i + - Edgeport/421 + - Edgeport/21 + - Edgeport/8 + - Edgeport/8 Dual + - Edgeport/2D8 + - Edgeport/4D8 + - Edgeport/8i + - Edgeport/2 DIN + - Edgeport/4 DIN + - Edgeport/16 Dual + + For any questions or problems with this driver, please contact Greg + Kroah-Hartman at greg@kroah.com + + +REINER SCT cyberJack pinpad/e-com USB chipcard reader +----------------------------------------------------- + + Interface to ISO 7816 compatible contactbased chipcards, e.g. GSM SIMs. + + Current status: + + This is the kernel part of the driver for this USB card reader. + There is also a user part for a CT-API driver available. A site + for downloading is TBA. For now, you can request it from the + maintainer (linux-usb@sii.li). + + For any questions or problems with this driver, please contact + linux-usb@sii.li + + +Prolific PL2303 Driver +---------------------- + + This driver supports any device that has the PL2303 chip from Prolific + in it. This includes a number of single port USB to serial converters, + more than 70% of USB GPS devices (in 2010), and some USB UPSes. Devices + from Aten (the UC-232) and IO-Data work with this driver, as does + the DCU-11 mobile-phone cable. + + For any questions or problems with this driver, please contact Greg + Kroah-Hartman at greg@kroah.com + + +KL5KUSB105 chipset / PalmConnect USB single-port adapter +-------------------------------------------------------- + +Current status: + + The driver was put together by looking at the usb bus transactions + done by Palm's driver under Windows, so a lot of functionality is + still missing. Notably, serial ioctls are sometimes faked or not yet + implemented. Support for finding out about DSR and CTS line status is + however implemented (though not nicely), so your favorite autopilot(1) + and pilot-manager -daemon calls will work. Baud rates up to 115200 + are supported, but handshaking (software or hardware) is not, which is + why it is wise to cut down on the rate used is wise for large + transfers until this is settled. + + See http://www.uuhaus.de/linux/palmconnect.html for up-to-date + information on this driver. + +Winchiphead CH341 Driver +------------------------ + + This driver is for the Winchiphead CH341 USB-RS232 Converter. This chip + also implements an IEEE 1284 parallel port, I2C and SPI, but that is not + supported by the driver. The protocol was analyzed from the behaviour + of the Windows driver, no datasheet is available at present. + + The manufacturer's website: http://www.winchiphead.com/. + + For any questions or problems with this driver, please contact + frank@kingswood-consulting.co.uk. + +Moschip MCS7720, MCS7715 driver +------------------------------- + + These chips are present in devices sold by various manufacturers, such as Syba + and Cables Unlimited. There may be others. The 7720 provides two serial + ports, and the 7715 provides one serial and one standard PC parallel port. + Support for the 7715's parallel port is enabled by a separate option, which + will not appear unless parallel port support is first enabled at the top-level + of the Device Drivers config menu. Currently only compatibility mode is + supported on the parallel port (no ECP/EPP). + + TODO: + - Implement ECP/EPP modes for the parallel port. + - Baud rates higher than 115200 are currently broken. + - Devices with a single serial port based on the Moschip MCS7703 may work + with this driver with a simple addition to the usb_device_id table. I + don't have one of these devices, so I can't say for sure. + +Generic Serial driver +--------------------- + + If your device is not one of the above listed devices, compatible with + the above models, you can try out the "generic" interface. This + interface does not provide any type of control messages sent to the + device, and does not support any kind of device flow control. All that + is required of your device is that it has at least one bulk in endpoint, + or one bulk out endpoint. + + To enable the generic driver to recognize your device, provide:: + + echo >/sys/bus/usb-serial/drivers/generic/new_id + + where the and is replaced with the hex representation of your + device's vendor id and product id. + If the driver is compiled as a module you can also provide one id when + loading the module:: + + insmod usbserial vendor=0x#### product=0x#### + + This driver has been successfully used to connect to the NetChip USB + development board, providing a way to develop USB firmware without + having to write a custom driver. + + For any questions or problems with this driver, please contact Greg + Kroah-Hartman at greg@kroah.com + + +Contact +======= + + If anyone has any problems using these drivers, with any of the above + specified products, please contact the specific driver's author listed + above, or join the Linux-USB mailing list (information on joining the + mailing list, as well as a link to its searchable archive is at + http://www.linux-usb.org/ ) + + +Greg Kroah-Hartman +greg@kroah.com diff --git a/Documentation/usb/usb-serial.txt b/Documentation/usb/usb-serial.txt deleted file mode 100644 index 8fa7dbd3da9a..000000000000 --- a/Documentation/usb/usb-serial.txt +++ /dev/null @@ -1,537 +0,0 @@ -========== -USB serial -========== - -Introduction -============ - - The USB serial driver currently supports a number of different USB to - serial converter products, as well as some devices that use a serial - interface from userspace to talk to the device. - - See the individual product section below for specific information about - the different devices. - - -Configuration -============= - - Currently the driver can handle up to 256 different serial interfaces at - one time. - - The major number that the driver uses is 188 so to use the driver, - create the following nodes:: - - mknod /dev/ttyUSB0 c 188 0 - mknod /dev/ttyUSB1 c 188 1 - mknod /dev/ttyUSB2 c 188 2 - mknod /dev/ttyUSB3 c 188 3 - . - . - . - mknod /dev/ttyUSB254 c 188 254 - mknod /dev/ttyUSB255 c 188 255 - - When the device is connected and recognized by the driver, the driver - will print to the system log, which node(s) the device has been bound - to. - - -Specific Devices Supported -========================== - - -ConnectTech WhiteHEAT 4 port converter --------------------------------------- - - ConnectTech has been very forthcoming with information about their - device, including providing a unit to test with. - - The driver is officially supported by Connect Tech Inc. - http://www.connecttech.com - - For any questions or problems with this driver, please contact - Connect Tech's Support Department at support@connecttech.com - - -HandSpring Visor, Palm USB, and Clié USB driver ------------------------------------------------ - - This driver works with all HandSpring USB, Palm USB, and Sony Clié USB - devices. - - Only when the device tries to connect to the host, will the device show - up to the host as a valid USB device. When this happens, the device is - properly enumerated, assigned a port, and then communication _should_ be - possible. The driver cleans up properly when the device is removed, or - the connection is canceled on the device. - - NOTE: - This means that in order to talk to the device, the sync button must be - pressed BEFORE trying to get any program to communicate to the device. - This goes against the current documentation for pilot-xfer and other - packages, but is the only way that it will work due to the hardware - in the device. - - When the device is connected, try talking to it on the second port - (this is usually /dev/ttyUSB1 if you do not have any other usb-serial - devices in the system.) The system log should tell you which port is - the port to use for the HotSync transfer. The "Generic" port can be used - for other device communication, such as a PPP link. - - For some Sony Clié devices, /dev/ttyUSB0 must be used to talk to the - device. This is true for all OS version 3.5 devices, and most devices - that have had a flash upgrade to a newer version of the OS. See the - kernel system log for information on which is the correct port to use. - - If after pressing the sync button, nothing shows up in the system log, - try resetting the device, first a hot reset, and then a cold reset if - necessary. Some devices need this before they can talk to the USB port - properly. - - Devices that are not compiled into the kernel can be specified with module - parameters. e.g. modprobe visor vendor=0x54c product=0x66 - - There is a webpage and mailing lists for this portion of the driver at: - http://sourceforge.net/projects/usbvisor/ - - For any questions or problems with this driver, please contact Greg - Kroah-Hartman at greg@kroah.com - - -PocketPC PDA Driver -------------------- - - This driver can be used to connect to Compaq iPAQ, HP Jornada, Casio EM500 - and other PDAs running Windows CE 3.0 or PocketPC 2002 using a USB - cable/cradle. - Most devices supported by ActiveSync are supported out of the box. - For others, please use module parameters to specify the product and vendor - id. e.g. modprobe ipaq vendor=0x3f0 product=0x1125 - - The driver presents a serial interface (usually on /dev/ttyUSB0) over - which one may run ppp and establish a TCP/IP link to the PDA. Once this - is done, you can transfer files, backup, download email etc. The most - significant advantage of using USB is speed - I can get 73 to 113 - kbytes/sec for download/upload to my iPAQ. - - This driver is only one of a set of components required to utilize - the USB connection. Please visit http://synce.sourceforge.net which - contains the necessary packages and a simple step-by-step howto. - - Once connected, you can use Win CE programs like ftpView, Pocket Outlook - from the PDA and xcerdisp, synce utilities from the Linux side. - - To use Pocket IE, follow the instructions given at - http://www.tekguru.co.uk/EM500/usbtonet.htm to achieve the same thing - on Win98. Omit the proxy server part; Linux is quite capable of forwarding - packets unlike Win98. Another modification is required at least for the - iPAQ - disable autosync by going to the Start/Settings/Connections menu - and unchecking the "Automatically synchronize ..." box. Go to - Start/Programs/Connections, connect the cable and select "usbdial" (or - whatever you named your new USB connection). You should finally wind - up with a "Connected to usbdial" window with status shown as connected. - Now start up PIE and browse away. - - If it doesn't work for some reason, load both the usbserial and ipaq module - with the module parameter "debug" set to 1 and examine the system log. - You can also try soft-resetting your PDA before attempting a connection. - - Other functionality may be possible depending on your PDA. According to - Wes Cilldhaire , with the Toshiba E570, - ...if you boot into the bootloader (hold down the power when hitting the - reset button, continuing to hold onto the power until the bootloader screen - is displayed), then put it in the cradle with the ipaq driver loaded, open - a terminal on /dev/ttyUSB0, it gives you a "USB Reflash" terminal, which can - be used to flash the ROM, as well as the microP code.. so much for needing - Toshiba's $350 serial cable for flashing!! :D - NOTE: This has NOT been tested. Use at your own risk. - - For any questions or problems with the driver, please contact Ganesh - Varadarajan - - -Keyspan PDA Serial Adapter --------------------------- - - Single port DB-9 serial adapter, pushed as a PDA adapter for iMacs (mostly - sold in Macintosh catalogs, comes in a translucent white/green dongle). - Fairly simple device. Firmware is homebrew. - This driver also works for the Xircom/Entrega single port serial adapter. - - Current status: - - Things that work: - - basic input/output (tested with 'cu') - - blocking write when serial line can't keep up - - changing baud rates (up to 115200) - - getting/setting modem control pins (TIOCM{GET,SET,BIS,BIC}) - - sending break (although duration looks suspect) - - Things that don't: - - device strings (as logged by kernel) have trailing binary garbage - - device ID isn't right, might collide with other Keyspan products - - changing baud rates ought to flush tx/rx to avoid mangled half characters - - Big Things on the todo list: - - parity, 7 vs 8 bits per char, 1 or 2 stop bits - - HW flow control - - not all of the standard USB descriptors are handled: - Get_Status, Set_Feature, O_NONBLOCK, select() - - For any questions or problems with this driver, please contact Brian - Warner at warner@lothar.com - - -Keyspan USA-series Serial Adapters ----------------------------------- - - Single, Dual and Quad port adapters - driver uses Keyspan supplied - firmware and is being developed with their support. - - Current status: - - The USA-18X, USA-28X, USA-19, USA-19W and USA-49W are supported and - have been pretty thoroughly tested at various baud rates with 8-N-1 - character settings. Other character lengths and parity setups are - presently untested. - - The USA-28 isn't yet supported though doing so should be pretty - straightforward. Contact the maintainer if you require this - functionality. - - More information is available at: - - http://www.carnationsoftware.com/carnation/Keyspan.html - - For any questions or problems with this driver, please contact Hugh - Blemings at hugh@misc.nu - - -FTDI Single Port Serial Driver ------------------------------- - - This is a single port DB-25 serial adapter. - - Devices supported include: - - - TripNav TN-200 USB GPS - - Navis Engineering Bureau CH-4711 USB GPS - - For any questions or problems with this driver, please contact Bill Ryder. - - -ZyXEL omni.net lcd plus ISDN TA -------------------------------- - - This is an ISDN TA. Please report both successes and troubles to - azummo@towertech.it - - -Cypress M8 CY4601 Family Serial Driver --------------------------------------- - - This driver was in most part developed by Neil "koyama" Whelchel. It - has been improved since that previous form to support dynamic serial - line settings and improved line handling. The driver is for the most - part stable and has been tested on an smp machine. (dual p2) - - Chipsets supported under CY4601 family: - - CY7C63723, CY7C63742, CY7C63743, CY7C64013 - - Devices supported: - - - DeLorme's USB Earthmate GPS (SiRF Star II lp arch) - - Cypress HID->COM RS232 adapter - - Note: - Cypress Semiconductor claims no affiliation with the - hid->com device. - - Most devices using chipsets under the CY4601 family should - work with the driver. As long as they stay true to the CY4601 - usbserial specification. - - Technical notes: - - The Earthmate starts out at 4800 8N1 by default... the driver will - upon start init to this setting. usbserial core provides the rest - of the termios settings, along with some custom termios so that the - output is in proper format and parsable. - - The device can be put into sirf mode by issuing NMEA command:: - - $PSRF100,,,,,*CHECKSUM - $PSRF100,0,9600,8,1,0*0C - - It should then be sufficient to change the port termios to match this - to begin communicating. - - As far as I can tell it supports pretty much every sirf command as - documented online available with firmware 2.31, with some unknown - message ids. - - The hid->com adapter can run at a maximum baud of 115200bps. Please note - that the device has trouble or is incapable of raising line voltage properly. - It will be fine with null modem links, as long as you do not try to link two - together without hacking the adapter to set the line high. - - The driver is smp safe. Performance with the driver is rather low when using - it for transferring files. This is being worked on, but I would be willing to - accept patches. An urb queue or packet buffer would likely fit the bill here. - - If you have any questions, problems, patches, feature requests, etc. you can - contact me here via email: - - dignome@gmail.com - - (your problems/patches can alternately be submitted to usb-devel) - - -Digi AccelePort Driver ----------------------- - - This driver supports the Digi AccelePort USB 2 and 4 devices, 2 port - (plus a parallel port) and 4 port USB serial converters. The driver - does NOT yet support the Digi AccelePort USB 8. - - This driver works under SMP with the usb-uhci driver. It does not - work under SMP with the uhci driver. - - The driver is generally working, though we still have a few more ioctls - to implement and final testing and debugging to do. The parallel port - on the USB 2 is supported as a serial to parallel converter; in other - words, it appears as another USB serial port on Linux, even though - physically it is really a parallel port. The Digi Acceleport USB 8 - is not yet supported. - - Please contact Peter Berger (pberger@brimson.com) or Al Borchers - (alborchers@steinerpoint.com) for questions or problems with this - driver. - - -Belkin USB Serial Adapter F5U103 --------------------------------- - - Single port DB-9/PS-2 serial adapter from Belkin with firmware by eTEK Labs. - The Peracom single port serial adapter also works with this driver, as - well as the GoHubs adapter. - - Current status: - - The following have been tested and work: - - - Baud rate 300-230400 - - Data bits 5-8 - - Stop bits 1-2 - - Parity N,E,O,M,S - - Handshake None, Software (XON/XOFF), Hardware (CTSRTS,CTSDTR) [1]_ - - Break Set and clear - - Line control Input/Output query and control [2]_ - - .. [1] - Hardware input flow control is only enabled for firmware - levels above 2.06. Read source code comments describing Belkin - firmware errata. Hardware output flow control is working for all - firmware versions. - - .. [2] - Queries of inputs (CTS,DSR,CD,RI) show the last - reported state. Queries of outputs (DTR,RTS) show the last - requested state and may not reflect current state as set by - automatic hardware flow control. - - TO DO List: - - Add true modem control line query capability. Currently tracks the - states reported by the interrupt and the states requested. - - Add error reporting back to application for UART error conditions. - - Add support for flush ioctls. - - Add everything else that is missing :) - - For any questions or problems with this driver, please contact William - Greathouse at wgreathouse@smva.com - - -Empeg empeg-car Mark I/II Driver --------------------------------- - - This is an experimental driver to provide connectivity support for the - client synchronization tools for an Empeg empeg-car mp3 player. - - Tips: - * Don't forget to create the device nodes for ttyUSB{0,1,2,...} - * modprobe empeg (modprobe is your friend) - * emptool --usb /dev/ttyUSB0 (or whatever you named your device node) - - For any questions or problems with this driver, please contact Gary - Brubaker at xavyer@ix.netcom.com - - -MCT USB Single Port Serial Adapter U232 ---------------------------------------- - - This driver is for the MCT USB-RS232 Converter (25 pin, Model No. - U232-P25) from Magic Control Technology Corp. (there is also a 9 pin - Model No. U232-P9). More information about this device can be found at - the manufacturer's web-site: http://www.mct.com.tw. - - The driver is generally working, though it still needs some more testing. - It is derived from the Belkin USB Serial Adapter F5U103 driver and its - TODO list is valid for this driver as well. - - This driver has also been found to work for other products, which have - the same Vendor ID but different Product IDs. Sitecom's U232-P25 serial - converter uses Product ID 0x230 and Vendor ID 0x711 and works with this - driver. Also, D-Link's DU-H3SP USB BAY also works with this driver. - - For any questions or problems with this driver, please contact Wolfgang - Grandegger at wolfgang@ces.ch - - -Inside Out Networks Edgeport Driver ------------------------------------ - - This driver supports all devices made by Inside Out Networks, specifically - the following models: - - - Edgeport/4 - - Rapidport/4 - - Edgeport/4t - - Edgeport/2 - - Edgeport/4i - - Edgeport/2i - - Edgeport/421 - - Edgeport/21 - - Edgeport/8 - - Edgeport/8 Dual - - Edgeport/2D8 - - Edgeport/4D8 - - Edgeport/8i - - Edgeport/2 DIN - - Edgeport/4 DIN - - Edgeport/16 Dual - - For any questions or problems with this driver, please contact Greg - Kroah-Hartman at greg@kroah.com - - -REINER SCT cyberJack pinpad/e-com USB chipcard reader ------------------------------------------------------ - - Interface to ISO 7816 compatible contactbased chipcards, e.g. GSM SIMs. - - Current status: - - This is the kernel part of the driver for this USB card reader. - There is also a user part for a CT-API driver available. A site - for downloading is TBA. For now, you can request it from the - maintainer (linux-usb@sii.li). - - For any questions or problems with this driver, please contact - linux-usb@sii.li - - -Prolific PL2303 Driver ----------------------- - - This driver supports any device that has the PL2303 chip from Prolific - in it. This includes a number of single port USB to serial converters, - more than 70% of USB GPS devices (in 2010), and some USB UPSes. Devices - from Aten (the UC-232) and IO-Data work with this driver, as does - the DCU-11 mobile-phone cable. - - For any questions or problems with this driver, please contact Greg - Kroah-Hartman at greg@kroah.com - - -KL5KUSB105 chipset / PalmConnect USB single-port adapter --------------------------------------------------------- - -Current status: - - The driver was put together by looking at the usb bus transactions - done by Palm's driver under Windows, so a lot of functionality is - still missing. Notably, serial ioctls are sometimes faked or not yet - implemented. Support for finding out about DSR and CTS line status is - however implemented (though not nicely), so your favorite autopilot(1) - and pilot-manager -daemon calls will work. Baud rates up to 115200 - are supported, but handshaking (software or hardware) is not, which is - why it is wise to cut down on the rate used is wise for large - transfers until this is settled. - - See http://www.uuhaus.de/linux/palmconnect.html for up-to-date - information on this driver. - -Winchiphead CH341 Driver ------------------------- - - This driver is for the Winchiphead CH341 USB-RS232 Converter. This chip - also implements an IEEE 1284 parallel port, I2C and SPI, but that is not - supported by the driver. The protocol was analyzed from the behaviour - of the Windows driver, no datasheet is available at present. - - The manufacturer's website: http://www.winchiphead.com/. - - For any questions or problems with this driver, please contact - frank@kingswood-consulting.co.uk. - -Moschip MCS7720, MCS7715 driver -------------------------------- - - These chips are present in devices sold by various manufacturers, such as Syba - and Cables Unlimited. There may be others. The 7720 provides two serial - ports, and the 7715 provides one serial and one standard PC parallel port. - Support for the 7715's parallel port is enabled by a separate option, which - will not appear unless parallel port support is first enabled at the top-level - of the Device Drivers config menu. Currently only compatibility mode is - supported on the parallel port (no ECP/EPP). - - TODO: - - Implement ECP/EPP modes for the parallel port. - - Baud rates higher than 115200 are currently broken. - - Devices with a single serial port based on the Moschip MCS7703 may work - with this driver with a simple addition to the usb_device_id table. I - don't have one of these devices, so I can't say for sure. - -Generic Serial driver ---------------------- - - If your device is not one of the above listed devices, compatible with - the above models, you can try out the "generic" interface. This - interface does not provide any type of control messages sent to the - device, and does not support any kind of device flow control. All that - is required of your device is that it has at least one bulk in endpoint, - or one bulk out endpoint. - - To enable the generic driver to recognize your device, provide:: - - echo >/sys/bus/usb-serial/drivers/generic/new_id - - where the and is replaced with the hex representation of your - device's vendor id and product id. - If the driver is compiled as a module you can also provide one id when - loading the module:: - - insmod usbserial vendor=0x#### product=0x#### - - This driver has been successfully used to connect to the NetChip USB - development board, providing a way to develop USB firmware without - having to write a custom driver. - - For any questions or problems with this driver, please contact Greg - Kroah-Hartman at greg@kroah.com - - -Contact -======= - - If anyone has any problems using these drivers, with any of the above - specified products, please contact the specific driver's author listed - above, or join the Linux-USB mailing list (information on joining the - mailing list, as well as a link to its searchable archive is at - http://www.linux-usb.org/ ) - - -Greg Kroah-Hartman -greg@kroah.com diff --git a/Documentation/usb/usbip_protocol.rst b/Documentation/usb/usbip_protocol.rst new file mode 100644 index 000000000000..988c832166cd --- /dev/null +++ b/Documentation/usb/usbip_protocol.rst @@ -0,0 +1,411 @@ +=============== +USB/IP protocol +=============== + +PRELIMINARY DRAFT, MAY CONTAIN MISTAKES! +28 Jun 2011 + +The USB/IP protocol follows a server/client architecture. The server exports the +USB devices and the clients imports them. The device driver for the exported +USB device runs on the client machine. + +The client may ask for the list of the exported USB devices. To get the list the +client opens a TCP/IP connection towards the server, and sends an OP_REQ_DEVLIST +packet on top of the TCP/IP connection (so the actual OP_REQ_DEVLIST may be sent +in one or more pieces at the low level transport layer). The server sends back +the OP_REP_DEVLIST packet which lists the exported USB devices. Finally the +TCP/IP connection is closed. + +:: + + virtual host controller usb host + "client" "server" + (imports USB devices) (exports USB devices) + | | + | OP_REQ_DEVLIST | + | ----------------------------------------------> | + | | + | OP_REP_DEVLIST | + | <---------------------------------------------- | + | | + +Once the client knows the list of exported USB devices it may decide to use one +of them. First the client opens a TCP/IP connection towards the server and +sends an OP_REQ_IMPORT packet. The server replies with OP_REP_IMPORT. If the +import was successful the TCP/IP connection remains open and will be used +to transfer the URB traffic between the client and the server. The client may +send two types of packets: the USBIP_CMD_SUBMIT to submit an URB, and +USBIP_CMD_UNLINK to unlink a previously submitted URB. The answers of the +server may be USBIP_RET_SUBMIT and USBIP_RET_UNLINK respectively. + +:: + + virtual host controller usb host + "client" "server" + (imports USB devices) (exports USB devices) + | | + | OP_REQ_IMPORT | + | ----------------------------------------------> | + | | + | OP_REP_IMPORT | + | <---------------------------------------------- | + | | + | | + | USBIP_CMD_SUBMIT(seqnum = n) | + | ----------------------------------------------> | + | | + | USBIP_RET_SUBMIT(seqnum = n) | + | <---------------------------------------------- | + | . | + | : | + | | + | USBIP_CMD_SUBMIT(seqnum = m) | + | ----------------------------------------------> | + | | + | USBIP_CMD_SUBMIT(seqnum = m+1) | + | ----------------------------------------------> | + | | + | USBIP_CMD_SUBMIT(seqnum = m+2) | + | ----------------------------------------------> | + | | + | USBIP_RET_SUBMIT(seqnum = m) | + | <---------------------------------------------- | + | | + | USBIP_CMD_SUBMIT(seqnum = m+3) | + | ----------------------------------------------> | + | | + | USBIP_RET_SUBMIT(seqnum = m+1) | + | <---------------------------------------------- | + | | + | USBIP_CMD_SUBMIT(seqnum = m+4) | + | ----------------------------------------------> | + | | + | USBIP_RET_SUBMIT(seqnum = m+2) | + | <---------------------------------------------- | + | . | + | : | + | | + | USBIP_CMD_UNLINK | + | ----------------------------------------------> | + | | + | USBIP_RET_UNLINK | + | <---------------------------------------------- | + | | + +The fields are in network (big endian) byte order meaning that the most significant +byte (MSB) is stored at the lowest address. + + +OP_REQ_DEVLIST: + Retrieve the list of exported USB devices. + ++-----------+--------+------------+---------------------------------------------------+ +| Offset | Length | Value | Description | ++===========+========+============+===================================================+ +| 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0 | ++-----------+--------+------------+---------------------------------------------------+ +| 2 | 2 | 0x8005 | Command code: Retrieve the list of exported USB | +| | | | devices. | ++-----------+--------+------------+---------------------------------------------------+ +| 4 | 4 | 0x00000000 | Status: unused, shall be set to 0 | ++-----------+--------+------------+---------------------------------------------------+ + +OP_REP_DEVLIST: + Reply with the list of exported USB devices. + ++-----------+--------+------------+---------------------------------------------------+ +| Offset | Length | Value | Description | ++===========+========+============+===================================================+ +| 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0.| ++-----------+--------+------------+---------------------------------------------------+ +| 2 | 2 | 0x0005 | Reply code: The list of exported USB devices. | ++-----------+--------+------------+---------------------------------------------------+ +| 4 | 4 | 0x00000000 | Status: 0 for OK | ++-----------+--------+------------+---------------------------------------------------+ +| 8 | 4 | n | Number of exported devices: 0 means no exported | +| | | | devices. | ++-----------+--------+------------+---------------------------------------------------+ +| 0x0C | | | From now on the exported n devices are described, | +| | | | if any. If no devices are exported the message | +| | | | ends with the previous "number of exported | +| | | | devices" field. | ++-----------+--------+------------+---------------------------------------------------+ +| | 256 | | path: Path of the device on the host exporting the| +| | | | USB device, string closed with zero byte, e.g. | +| | | | "/sys/devices/pci0000:00/0000:00:1d.1/usb3/3-2" | +| | | | The unused bytes shall be filled with zero | +| | | | bytes. | ++-----------+--------+------------+---------------------------------------------------+ +| 0x10C | 32 | | busid: Bus ID of the exported device, string | +| | | | closed with zero byte, e.g. "3-2". The unused | +| | | | bytes shall be filled with zero bytes. | ++-----------+--------+------------+---------------------------------------------------+ +| 0x12C | 4 | | busnum | ++-----------+--------+------------+---------------------------------------------------+ +| 0x130 | 4 | | devnum | ++-----------+--------+------------+---------------------------------------------------+ +| 0x134 | 4 | | speed | ++-----------+--------+------------+---------------------------------------------------+ +| 0x138 | 2 | | idVendor | ++-----------+--------+------------+---------------------------------------------------+ +| 0x13A | 2 | | idProduct | ++-----------+--------+------------+---------------------------------------------------+ +| 0x13C | 2 | | bcdDevice | ++-----------+--------+------------+---------------------------------------------------+ +| 0x13E | 1 | | bDeviceClass | ++-----------+--------+------------+---------------------------------------------------+ +| 0x13F | 1 | | bDeviceSubClass | ++-----------+--------+------------+---------------------------------------------------+ +| 0x140 | 1 | | bDeviceProtocol | ++-----------+--------+------------+---------------------------------------------------+ +| 0x141 | 1 | | bConfigurationValue | ++-----------+--------+------------+---------------------------------------------------+ +| 0x142 | 1 | | bNumConfigurations | ++-----------+--------+------------+---------------------------------------------------+ +| 0x143 | 1 | | bNumInterfaces | ++-----------+--------+------------+---------------------------------------------------+ +| 0x144 | | m_0 | From now on each interface is described, all | +| | | | together bNumInterfaces times, with the | +| | | | the following 4 fields: | ++-----------+--------+------------+---------------------------------------------------+ +| | 1 | | bInterfaceClass | ++-----------+--------+------------+---------------------------------------------------+ +| 0x145 | 1 | | bInterfaceSubClass | ++-----------+--------+------------+---------------------------------------------------+ +| 0x146 | 1 | | bInterfaceProtocol | ++-----------+--------+------------+---------------------------------------------------+ +| 0x147 | 1 | | padding byte for alignment, shall be set to zero | ++-----------+--------+------------+---------------------------------------------------+ +| 0xC + | | | The second exported USB device starts at i=1 | +| i*0x138 + | | | with the busid field. | +| m_(i-1)*4 | | | | ++-----------+--------+------------+---------------------------------------------------+ + +OP_REQ_IMPORT: + Request to import (attach) a remote USB device. + ++-----------+--------+------------+---------------------------------------------------+ +| Offset | Length | Value | Description | ++===========+========+============+===================================================+ +| 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0 | ++-----------+--------+------------+---------------------------------------------------+ +| 2 | 2 | 0x8003 | Command code: import a remote USB device. | ++-----------+--------+------------+---------------------------------------------------+ +| 4 | 4 | 0x00000000 | Status: unused, shall be set to 0 | ++-----------+--------+------------+---------------------------------------------------+ +| 8 | 32 | | busid: the busid of the exported device on the | +| | | | remote host. The possible values are taken | +| | | | from the message field OP_REP_DEVLIST.busid. | +| | | | A string closed with zero, the unused bytes | +| | | | shall be filled with zeros. | ++-----------+--------+------------+---------------------------------------------------+ + +OP_REP_IMPORT: + Reply to import (attach) a remote USB device. + ++-----------+--------+------------+---------------------------------------------------+ +| Offset | Length | Value | Description | ++===========+========+============+===================================================+ +| 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0 | ++-----------+--------+------------+---------------------------------------------------+ +| 2 | 2 | 0x0003 | Reply code: Reply to import. | ++-----------+--------+------------+---------------------------------------------------+ +| 4 | 4 | 0x00000000 | Status: | +| | | | | +| | | | - 0 for OK | +| | | | - 1 for error | ++-----------+--------+------------+---------------------------------------------------+ +| 8 | | | From now on comes the details of the imported | +| | | | device, if the previous status field was OK (0), | +| | | | otherwise the reply ends with the status field. | ++-----------+--------+------------+---------------------------------------------------+ +| | 256 | | path: Path of the device on the host exporting the| +| | | | USB device, string closed with zero byte, e.g. | +| | | | "/sys/devices/pci0000:00/0000:00:1d.1/usb3/3-2" | +| | | | The unused bytes shall be filled with zero | +| | | | bytes. | ++-----------+--------+------------+---------------------------------------------------+ +| 0x108 | 32 | | busid: Bus ID of the exported device, string | +| | | | closed with zero byte, e.g. "3-2". The unused | +| | | | bytes shall be filled with zero bytes. | ++-----------+--------+------------+---------------------------------------------------+ +| 0x128 | 4 | | busnum | ++-----------+--------+------------+---------------------------------------------------+ +| 0x12C | 4 | | devnum | ++-----------+--------+------------+---------------------------------------------------+ +| 0x130 | 4 | | speed | ++-----------+--------+------------+---------------------------------------------------+ +| 0x134 | 2 | | idVendor | ++-----------+--------+------------+---------------------------------------------------+ +| 0x136 | 2 | | idProduct | ++-----------+--------+------------+---------------------------------------------------+ +| 0x138 | 2 | | bcdDevice | ++-----------+--------+------------+---------------------------------------------------+ +| 0x139 | 1 | | bDeviceClass | ++-----------+--------+------------+---------------------------------------------------+ +| 0x13A | 1 | | bDeviceSubClass | ++-----------+--------+------------+---------------------------------------------------+ +| 0x13B | 1 | | bDeviceProtocol | ++-----------+--------+------------+---------------------------------------------------+ +| 0x13C | 1 | | bConfigurationValue | ++-----------+--------+------------+---------------------------------------------------+ +| 0x13D | 1 | | bNumConfigurations | ++-----------+--------+------------+---------------------------------------------------+ +| 0x13E | 1 | | bNumInterfaces | ++-----------+--------+------------+---------------------------------------------------+ + +USBIP_CMD_SUBMIT: + Submit an URB + ++-----------+--------+------------+---------------------------------------------------+ +| Offset | Length | Value | Description | ++===========+========+============+===================================================+ +| 0 | 4 | 0x00000001 | command: Submit an URB | ++-----------+--------+------------+---------------------------------------------------+ +| 4 | 4 | | seqnum: the sequence number of the URB to submit | ++-----------+--------+------------+---------------------------------------------------+ +| 8 | 4 | | devid | ++-----------+--------+------------+---------------------------------------------------+ +| 0xC | 4 | | direction: | +| | | | | +| | | | - 0: USBIP_DIR_OUT | +| | | | - 1: USBIP_DIR_IN | ++-----------+--------+------------+---------------------------------------------------+ +| 0x10 | 4 | | ep: endpoint number, possible values are: 0...15 | ++-----------+--------+------------+---------------------------------------------------+ +| 0x14 | 4 | | transfer_flags: possible values depend on the | +| | | | URB transfer type, see below | ++-----------+--------+------------+---------------------------------------------------+ +| 0x18 | 4 | | transfer_buffer_length | ++-----------+--------+------------+---------------------------------------------------+ +| 0x1C | 4 | | start_frame: specify the selected frame to | +| | | | transmit an ISO frame, ignored if URB_ISO_ASAP | +| | | | is specified at transfer_flags | ++-----------+--------+------------+---------------------------------------------------+ +| 0x20 | 4 | | number_of_packets: number of ISO packets | ++-----------+--------+------------+---------------------------------------------------+ +| 0x24 | 4 | | interval: maximum time for the request on the | +| | | | server-side host controller | ++-----------+--------+------------+---------------------------------------------------+ +| 0x28 | 8 | | setup: data bytes for USB setup, filled with | +| | | | zeros if not used | ++-----------+--------+------------+---------------------------------------------------+ +| 0x30 | | | URB data. For ISO transfers the padding between | +| | | | each ISO packets is not transmitted. | ++-----------+--------+------------+---------------------------------------------------+ + + + +-------------------------+------------+---------+-----------+----------+-------------+ + | Allowed transfer_flags | value | control | interrupt | bulk | isochronous | + +=========================+============+=========+===========+==========+=============+ + | URB_SHORT_NOT_OK | 0x00000001 | only in | only in | only in | no | + +-------------------------+------------+---------+-----------+----------+-------------+ + | URB_ISO_ASAP | 0x00000002 | no | no | no | yes | + +-------------------------+------------+---------+-----------+----------+-------------+ + | URB_NO_TRANSFER_DMA_MAP | 0x00000004 | yes | yes | yes | yes | + +-------------------------+------------+---------+-----------+----------+-------------+ + | URB_ZERO_PACKET | 0x00000040 | no | no | only out | no | + +-------------------------+------------+---------+-----------+----------+-------------+ + | URB_NO_INTERRUPT | 0x00000080 | yes | yes | yes | yes | + +-------------------------+------------+---------+-----------+----------+-------------+ + | URB_FREE_BUFFER | 0x00000100 | yes | yes | yes | yes | + +-------------------------+------------+---------+-----------+----------+-------------+ + | URB_DIR_MASK | 0x00000200 | yes | yes | yes | yes | + +-------------------------+------------+---------+-----------+----------+-------------+ + + +USBIP_RET_SUBMIT: + Reply for submitting an URB + ++-----------+--------+------------+---------------------------------------------------+ +| Offset | Length | Value | Description | ++===========+========+============+===================================================+ +| 0 | 4 | 0x00000003 | command | ++-----------+--------+------------+---------------------------------------------------+ +| 4 | 4 | | seqnum: URB sequence number | ++-----------+--------+------------+---------------------------------------------------+ +| 8 | 4 | | devid | ++-----------+--------+------------+---------------------------------------------------+ +| 0xC | 4 | | direction: | +| | | | | +| | | | - 0: USBIP_DIR_OUT | +| | | | - 1: USBIP_DIR_IN | ++-----------+--------+------------+---------------------------------------------------+ +| 0x10 | 4 | | ep: endpoint number | ++-----------+--------+------------+---------------------------------------------------+ +| 0x14 | 4 | | status: zero for successful URB transaction, | +| | | | otherwise some kind of error happened. | ++-----------+--------+------------+---------------------------------------------------+ +| 0x18 | 4 | n | actual_length: number of URB data bytes | ++-----------+--------+------------+---------------------------------------------------+ +| 0x1C | 4 | | start_frame: for an ISO frame the actually | +| | | | selected frame for transmit. | ++-----------+--------+------------+---------------------------------------------------+ +| 0x20 | 4 | | number_of_packets | ++-----------+--------+------------+---------------------------------------------------+ +| 0x24 | 4 | | error_count | ++-----------+--------+------------+---------------------------------------------------+ +| 0x28 | 8 | | setup: data bytes for USB setup, filled with | +| | | | zeros if not used | ++-----------+--------+------------+---------------------------------------------------+ +| 0x30 | n | | URB data bytes. For ISO transfers the padding | +| | | | between each ISO packets is not transmitted. | ++-----------+--------+------------+---------------------------------------------------+ + +USBIP_CMD_UNLINK: + Unlink an URB + ++-----------+--------+------------+---------------------------------------------------+ +| Offset | Length | Value | Description | ++===========+========+============+===================================================+ +| 0 | 4 | 0x00000002 | command: URB unlink command | ++-----------+--------+------------+---------------------------------------------------+ +| 4 | 4 | | seqnum: URB sequence number to unlink: | +| | | | | +| | | | FIXME: | +| | | | is this so? | ++-----------+--------+------------+---------------------------------------------------+ +| 8 | 4 | | devid | ++-----------+--------+------------+---------------------------------------------------+ +| 0xC | 4 | | direction: | +| | | | | +| | | | - 0: USBIP_DIR_OUT | +| | | | - 1: USBIP_DIR_IN | ++-----------+--------+------------+---------------------------------------------------+ +| 0x10 | 4 | | ep: endpoint number: zero | ++-----------+--------+------------+---------------------------------------------------+ +| 0x14 | 4 | | seqnum: the URB sequence number given previously | +| | | | at USBIP_CMD_SUBMIT.seqnum field | ++-----------+--------+------------+---------------------------------------------------+ +| 0x30 | n | | URB data bytes. For ISO transfers the padding | +| | | | between each ISO packets is not transmitted. | ++-----------+--------+------------+---------------------------------------------------+ + +USBIP_RET_UNLINK: + Reply for URB unlink + ++-----------+--------+------------+---------------------------------------------------+ +| Offset | Length | Value | Description | ++===========+========+============+===================================================+ +| 0 | 4 | 0x00000004 | command: reply for the URB unlink command | ++-----------+--------+------------+---------------------------------------------------+ +| 4 | 4 | | seqnum: the unlinked URB sequence number | ++-----------+--------+------------+---------------------------------------------------+ +| 8 | 4 | | devid | ++-----------+--------+------------+---------------------------------------------------+ +| 0xC | 4 | | direction: | +| | | | | +| | | | - 0: USBIP_DIR_OUT | +| | | | - 1: USBIP_DIR_IN | ++-----------+--------+------------+---------------------------------------------------+ +| 0x10 | 4 | | ep: endpoint number | ++-----------+--------+------------+---------------------------------------------------+ +| 0x14 | 4 | | status: This is the value contained in the | +| | | | urb->status in the URB completition handler. | +| | | | | +| | | | FIXME: | +| | | | a better explanation needed. | ++-----------+--------+------------+---------------------------------------------------+ +| 0x30 | n | | URB data bytes. For ISO transfers the padding | +| | | | between each ISO packets is not transmitted. | ++-----------+--------+------------+---------------------------------------------------+ diff --git a/Documentation/usb/usbip_protocol.txt b/Documentation/usb/usbip_protocol.txt deleted file mode 100644 index 988c832166cd..000000000000 --- a/Documentation/usb/usbip_protocol.txt +++ /dev/null @@ -1,411 +0,0 @@ -=============== -USB/IP protocol -=============== - -PRELIMINARY DRAFT, MAY CONTAIN MISTAKES! -28 Jun 2011 - -The USB/IP protocol follows a server/client architecture. The server exports the -USB devices and the clients imports them. The device driver for the exported -USB device runs on the client machine. - -The client may ask for the list of the exported USB devices. To get the list the -client opens a TCP/IP connection towards the server, and sends an OP_REQ_DEVLIST -packet on top of the TCP/IP connection (so the actual OP_REQ_DEVLIST may be sent -in one or more pieces at the low level transport layer). The server sends back -the OP_REP_DEVLIST packet which lists the exported USB devices. Finally the -TCP/IP connection is closed. - -:: - - virtual host controller usb host - "client" "server" - (imports USB devices) (exports USB devices) - | | - | OP_REQ_DEVLIST | - | ----------------------------------------------> | - | | - | OP_REP_DEVLIST | - | <---------------------------------------------- | - | | - -Once the client knows the list of exported USB devices it may decide to use one -of them. First the client opens a TCP/IP connection towards the server and -sends an OP_REQ_IMPORT packet. The server replies with OP_REP_IMPORT. If the -import was successful the TCP/IP connection remains open and will be used -to transfer the URB traffic between the client and the server. The client may -send two types of packets: the USBIP_CMD_SUBMIT to submit an URB, and -USBIP_CMD_UNLINK to unlink a previously submitted URB. The answers of the -server may be USBIP_RET_SUBMIT and USBIP_RET_UNLINK respectively. - -:: - - virtual host controller usb host - "client" "server" - (imports USB devices) (exports USB devices) - | | - | OP_REQ_IMPORT | - | ----------------------------------------------> | - | | - | OP_REP_IMPORT | - | <---------------------------------------------- | - | | - | | - | USBIP_CMD_SUBMIT(seqnum = n) | - | ----------------------------------------------> | - | | - | USBIP_RET_SUBMIT(seqnum = n) | - | <---------------------------------------------- | - | . | - | : | - | | - | USBIP_CMD_SUBMIT(seqnum = m) | - | ----------------------------------------------> | - | | - | USBIP_CMD_SUBMIT(seqnum = m+1) | - | ----------------------------------------------> | - | | - | USBIP_CMD_SUBMIT(seqnum = m+2) | - | ----------------------------------------------> | - | | - | USBIP_RET_SUBMIT(seqnum = m) | - | <---------------------------------------------- | - | | - | USBIP_CMD_SUBMIT(seqnum = m+3) | - | ----------------------------------------------> | - | | - | USBIP_RET_SUBMIT(seqnum = m+1) | - | <---------------------------------------------- | - | | - | USBIP_CMD_SUBMIT(seqnum = m+4) | - | ----------------------------------------------> | - | | - | USBIP_RET_SUBMIT(seqnum = m+2) | - | <---------------------------------------------- | - | . | - | : | - | | - | USBIP_CMD_UNLINK | - | ----------------------------------------------> | - | | - | USBIP_RET_UNLINK | - | <---------------------------------------------- | - | | - -The fields are in network (big endian) byte order meaning that the most significant -byte (MSB) is stored at the lowest address. - - -OP_REQ_DEVLIST: - Retrieve the list of exported USB devices. - -+-----------+--------+------------+---------------------------------------------------+ -| Offset | Length | Value | Description | -+===========+========+============+===================================================+ -| 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0 | -+-----------+--------+------------+---------------------------------------------------+ -| 2 | 2 | 0x8005 | Command code: Retrieve the list of exported USB | -| | | | devices. | -+-----------+--------+------------+---------------------------------------------------+ -| 4 | 4 | 0x00000000 | Status: unused, shall be set to 0 | -+-----------+--------+------------+---------------------------------------------------+ - -OP_REP_DEVLIST: - Reply with the list of exported USB devices. - -+-----------+--------+------------+---------------------------------------------------+ -| Offset | Length | Value | Description | -+===========+========+============+===================================================+ -| 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0.| -+-----------+--------+------------+---------------------------------------------------+ -| 2 | 2 | 0x0005 | Reply code: The list of exported USB devices. | -+-----------+--------+------------+---------------------------------------------------+ -| 4 | 4 | 0x00000000 | Status: 0 for OK | -+-----------+--------+------------+---------------------------------------------------+ -| 8 | 4 | n | Number of exported devices: 0 means no exported | -| | | | devices. | -+-----------+--------+------------+---------------------------------------------------+ -| 0x0C | | | From now on the exported n devices are described, | -| | | | if any. If no devices are exported the message | -| | | | ends with the previous "number of exported | -| | | | devices" field. | -+-----------+--------+------------+---------------------------------------------------+ -| | 256 | | path: Path of the device on the host exporting the| -| | | | USB device, string closed with zero byte, e.g. | -| | | | "/sys/devices/pci0000:00/0000:00:1d.1/usb3/3-2" | -| | | | The unused bytes shall be filled with zero | -| | | | bytes. | -+-----------+--------+------------+---------------------------------------------------+ -| 0x10C | 32 | | busid: Bus ID of the exported device, string | -| | | | closed with zero byte, e.g. "3-2". The unused | -| | | | bytes shall be filled with zero bytes. | -+-----------+--------+------------+---------------------------------------------------+ -| 0x12C | 4 | | busnum | -+-----------+--------+------------+---------------------------------------------------+ -| 0x130 | 4 | | devnum | -+-----------+--------+------------+---------------------------------------------------+ -| 0x134 | 4 | | speed | -+-----------+--------+------------+---------------------------------------------------+ -| 0x138 | 2 | | idVendor | -+-----------+--------+------------+---------------------------------------------------+ -| 0x13A | 2 | | idProduct | -+-----------+--------+------------+---------------------------------------------------+ -| 0x13C | 2 | | bcdDevice | -+-----------+--------+------------+---------------------------------------------------+ -| 0x13E | 1 | | bDeviceClass | -+-----------+--------+------------+---------------------------------------------------+ -| 0x13F | 1 | | bDeviceSubClass | -+-----------+--------+------------+---------------------------------------------------+ -| 0x140 | 1 | | bDeviceProtocol | -+-----------+--------+------------+---------------------------------------------------+ -| 0x141 | 1 | | bConfigurationValue | -+-----------+--------+------------+---------------------------------------------------+ -| 0x142 | 1 | | bNumConfigurations | -+-----------+--------+------------+---------------------------------------------------+ -| 0x143 | 1 | | bNumInterfaces | -+-----------+--------+------------+---------------------------------------------------+ -| 0x144 | | m_0 | From now on each interface is described, all | -| | | | together bNumInterfaces times, with the | -| | | | the following 4 fields: | -+-----------+--------+------------+---------------------------------------------------+ -| | 1 | | bInterfaceClass | -+-----------+--------+------------+---------------------------------------------------+ -| 0x145 | 1 | | bInterfaceSubClass | -+-----------+--------+------------+---------------------------------------------------+ -| 0x146 | 1 | | bInterfaceProtocol | -+-----------+--------+------------+---------------------------------------------------+ -| 0x147 | 1 | | padding byte for alignment, shall be set to zero | -+-----------+--------+------------+---------------------------------------------------+ -| 0xC + | | | The second exported USB device starts at i=1 | -| i*0x138 + | | | with the busid field. | -| m_(i-1)*4 | | | | -+-----------+--------+------------+---------------------------------------------------+ - -OP_REQ_IMPORT: - Request to import (attach) a remote USB device. - -+-----------+--------+------------+---------------------------------------------------+ -| Offset | Length | Value | Description | -+===========+========+============+===================================================+ -| 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0 | -+-----------+--------+------------+---------------------------------------------------+ -| 2 | 2 | 0x8003 | Command code: import a remote USB device. | -+-----------+--------+------------+---------------------------------------------------+ -| 4 | 4 | 0x00000000 | Status: unused, shall be set to 0 | -+-----------+--------+------------+---------------------------------------------------+ -| 8 | 32 | | busid: the busid of the exported device on the | -| | | | remote host. The possible values are taken | -| | | | from the message field OP_REP_DEVLIST.busid. | -| | | | A string closed with zero, the unused bytes | -| | | | shall be filled with zeros. | -+-----------+--------+------------+---------------------------------------------------+ - -OP_REP_IMPORT: - Reply to import (attach) a remote USB device. - -+-----------+--------+------------+---------------------------------------------------+ -| Offset | Length | Value | Description | -+===========+========+============+===================================================+ -| 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0 | -+-----------+--------+------------+---------------------------------------------------+ -| 2 | 2 | 0x0003 | Reply code: Reply to import. | -+-----------+--------+------------+---------------------------------------------------+ -| 4 | 4 | 0x00000000 | Status: | -| | | | | -| | | | - 0 for OK | -| | | | - 1 for error | -+-----------+--------+------------+---------------------------------------------------+ -| 8 | | | From now on comes the details of the imported | -| | | | device, if the previous status field was OK (0), | -| | | | otherwise the reply ends with the status field. | -+-----------+--------+------------+---------------------------------------------------+ -| | 256 | | path: Path of the device on the host exporting the| -| | | | USB device, string closed with zero byte, e.g. | -| | | | "/sys/devices/pci0000:00/0000:00:1d.1/usb3/3-2" | -| | | | The unused bytes shall be filled with zero | -| | | | bytes. | -+-----------+--------+------------+---------------------------------------------------+ -| 0x108 | 32 | | busid: Bus ID of the exported device, string | -| | | | closed with zero byte, e.g. "3-2". The unused | -| | | | bytes shall be filled with zero bytes. | -+-----------+--------+------------+---------------------------------------------------+ -| 0x128 | 4 | | busnum | -+-----------+--------+------------+---------------------------------------------------+ -| 0x12C | 4 | | devnum | -+-----------+--------+------------+---------------------------------------------------+ -| 0x130 | 4 | | speed | -+-----------+--------+------------+---------------------------------------------------+ -| 0x134 | 2 | | idVendor | -+-----------+--------+------------+---------------------------------------------------+ -| 0x136 | 2 | | idProduct | -+-----------+--------+------------+---------------------------------------------------+ -| 0x138 | 2 | | bcdDevice | -+-----------+--------+------------+---------------------------------------------------+ -| 0x139 | 1 | | bDeviceClass | -+-----------+--------+------------+---------------------------------------------------+ -| 0x13A | 1 | | bDeviceSubClass | -+-----------+--------+------------+---------------------------------------------------+ -| 0x13B | 1 | | bDeviceProtocol | -+-----------+--------+------------+---------------------------------------------------+ -| 0x13C | 1 | | bConfigurationValue | -+-----------+--------+------------+---------------------------------------------------+ -| 0x13D | 1 | | bNumConfigurations | -+-----------+--------+------------+---------------------------------------------------+ -| 0x13E | 1 | | bNumInterfaces | -+-----------+--------+------------+---------------------------------------------------+ - -USBIP_CMD_SUBMIT: - Submit an URB - -+-----------+--------+------------+---------------------------------------------------+ -| Offset | Length | Value | Description | -+===========+========+============+===================================================+ -| 0 | 4 | 0x00000001 | command: Submit an URB | -+-----------+--------+------------+---------------------------------------------------+ -| 4 | 4 | | seqnum: the sequence number of the URB to submit | -+-----------+--------+------------+---------------------------------------------------+ -| 8 | 4 | | devid | -+-----------+--------+------------+---------------------------------------------------+ -| 0xC | 4 | | direction: | -| | | | | -| | | | - 0: USBIP_DIR_OUT | -| | | | - 1: USBIP_DIR_IN | -+-----------+--------+------------+---------------------------------------------------+ -| 0x10 | 4 | | ep: endpoint number, possible values are: 0...15 | -+-----------+--------+------------+---------------------------------------------------+ -| 0x14 | 4 | | transfer_flags: possible values depend on the | -| | | | URB transfer type, see below | -+-----------+--------+------------+---------------------------------------------------+ -| 0x18 | 4 | | transfer_buffer_length | -+-----------+--------+------------+---------------------------------------------------+ -| 0x1C | 4 | | start_frame: specify the selected frame to | -| | | | transmit an ISO frame, ignored if URB_ISO_ASAP | -| | | | is specified at transfer_flags | -+-----------+--------+------------+---------------------------------------------------+ -| 0x20 | 4 | | number_of_packets: number of ISO packets | -+-----------+--------+------------+---------------------------------------------------+ -| 0x24 | 4 | | interval: maximum time for the request on the | -| | | | server-side host controller | -+-----------+--------+------------+---------------------------------------------------+ -| 0x28 | 8 | | setup: data bytes for USB setup, filled with | -| | | | zeros if not used | -+-----------+--------+------------+---------------------------------------------------+ -| 0x30 | | | URB data. For ISO transfers the padding between | -| | | | each ISO packets is not transmitted. | -+-----------+--------+------------+---------------------------------------------------+ - - - +-------------------------+------------+---------+-----------+----------+-------------+ - | Allowed transfer_flags | value | control | interrupt | bulk | isochronous | - +=========================+============+=========+===========+==========+=============+ - | URB_SHORT_NOT_OK | 0x00000001 | only in | only in | only in | no | - +-------------------------+------------+---------+-----------+----------+-------------+ - | URB_ISO_ASAP | 0x00000002 | no | no | no | yes | - +-------------------------+------------+---------+-----------+----------+-------------+ - | URB_NO_TRANSFER_DMA_MAP | 0x00000004 | yes | yes | yes | yes | - +-------------------------+------------+---------+-----------+----------+-------------+ - | URB_ZERO_PACKET | 0x00000040 | no | no | only out | no | - +-------------------------+------------+---------+-----------+----------+-------------+ - | URB_NO_INTERRUPT | 0x00000080 | yes | yes | yes | yes | - +-------------------------+------------+---------+-----------+----------+-------------+ - | URB_FREE_BUFFER | 0x00000100 | yes | yes | yes | yes | - +-------------------------+------------+---------+-----------+----------+-------------+ - | URB_DIR_MASK | 0x00000200 | yes | yes | yes | yes | - +-------------------------+------------+---------+-----------+----------+-------------+ - - -USBIP_RET_SUBMIT: - Reply for submitting an URB - -+-----------+--------+------------+---------------------------------------------------+ -| Offset | Length | Value | Description | -+===========+========+============+===================================================+ -| 0 | 4 | 0x00000003 | command | -+-----------+--------+------------+---------------------------------------------------+ -| 4 | 4 | | seqnum: URB sequence number | -+-----------+--------+------------+---------------------------------------------------+ -| 8 | 4 | | devid | -+-----------+--------+------------+---------------------------------------------------+ -| 0xC | 4 | | direction: | -| | | | | -| | | | - 0: USBIP_DIR_OUT | -| | | | - 1: USBIP_DIR_IN | -+-----------+--------+------------+---------------------------------------------------+ -| 0x10 | 4 | | ep: endpoint number | -+-----------+--------+------------+---------------------------------------------------+ -| 0x14 | 4 | | status: zero for successful URB transaction, | -| | | | otherwise some kind of error happened. | -+-----------+--------+------------+---------------------------------------------------+ -| 0x18 | 4 | n | actual_length: number of URB data bytes | -+-----------+--------+------------+---------------------------------------------------+ -| 0x1C | 4 | | start_frame: for an ISO frame the actually | -| | | | selected frame for transmit. | -+-----------+--------+------------+---------------------------------------------------+ -| 0x20 | 4 | | number_of_packets | -+-----------+--------+------------+---------------------------------------------------+ -| 0x24 | 4 | | error_count | -+-----------+--------+------------+---------------------------------------------------+ -| 0x28 | 8 | | setup: data bytes for USB setup, filled with | -| | | | zeros if not used | -+-----------+--------+------------+---------------------------------------------------+ -| 0x30 | n | | URB data bytes. For ISO transfers the padding | -| | | | between each ISO packets is not transmitted. | -+-----------+--------+------------+---------------------------------------------------+ - -USBIP_CMD_UNLINK: - Unlink an URB - -+-----------+--------+------------+---------------------------------------------------+ -| Offset | Length | Value | Description | -+===========+========+============+===================================================+ -| 0 | 4 | 0x00000002 | command: URB unlink command | -+-----------+--------+------------+---------------------------------------------------+ -| 4 | 4 | | seqnum: URB sequence number to unlink: | -| | | | | -| | | | FIXME: | -| | | | is this so? | -+-----------+--------+------------+---------------------------------------------------+ -| 8 | 4 | | devid | -+-----------+--------+------------+---------------------------------------------------+ -| 0xC | 4 | | direction: | -| | | | | -| | | | - 0: USBIP_DIR_OUT | -| | | | - 1: USBIP_DIR_IN | -+-----------+--------+------------+---------------------------------------------------+ -| 0x10 | 4 | | ep: endpoint number: zero | -+-----------+--------+------------+---------------------------------------------------+ -| 0x14 | 4 | | seqnum: the URB sequence number given previously | -| | | | at USBIP_CMD_SUBMIT.seqnum field | -+-----------+--------+------------+---------------------------------------------------+ -| 0x30 | n | | URB data bytes. For ISO transfers the padding | -| | | | between each ISO packets is not transmitted. | -+-----------+--------+------------+---------------------------------------------------+ - -USBIP_RET_UNLINK: - Reply for URB unlink - -+-----------+--------+------------+---------------------------------------------------+ -| Offset | Length | Value | Description | -+===========+========+============+===================================================+ -| 0 | 4 | 0x00000004 | command: reply for the URB unlink command | -+-----------+--------+------------+---------------------------------------------------+ -| 4 | 4 | | seqnum: the unlinked URB sequence number | -+-----------+--------+------------+---------------------------------------------------+ -| 8 | 4 | | devid | -+-----------+--------+------------+---------------------------------------------------+ -| 0xC | 4 | | direction: | -| | | | | -| | | | - 0: USBIP_DIR_OUT | -| | | | - 1: USBIP_DIR_IN | -+-----------+--------+------------+---------------------------------------------------+ -| 0x10 | 4 | | ep: endpoint number | -+-----------+--------+------------+---------------------------------------------------+ -| 0x14 | 4 | | status: This is the value contained in the | -| | | | urb->status in the URB completition handler. | -| | | | | -| | | | FIXME: | -| | | | a better explanation needed. | -+-----------+--------+------------+---------------------------------------------------+ -| 0x30 | n | | URB data bytes. For ISO transfers the padding | -| | | | between each ISO packets is not transmitted. | -+-----------+--------+------------+---------------------------------------------------+ diff --git a/Documentation/usb/usbmon.rst b/Documentation/usb/usbmon.rst new file mode 100644 index 000000000000..b0bd51080799 --- /dev/null +++ b/Documentation/usb/usbmon.rst @@ -0,0 +1,375 @@ +====== +usbmon +====== + +Introduction +============ + +The name "usbmon" in lowercase refers to a facility in kernel which is +used to collect traces of I/O on the USB bus. This function is analogous +to a packet socket used by network monitoring tools such as tcpdump(1) +or Ethereal. Similarly, it is expected that a tool such as usbdump or +USBMon (with uppercase letters) is used to examine raw traces produced +by usbmon. + +The usbmon reports requests made by peripheral-specific drivers to Host +Controller Drivers (HCD). So, if HCD is buggy, the traces reported by +usbmon may not correspond to bus transactions precisely. This is the same +situation as with tcpdump. + +Two APIs are currently implemented: "text" and "binary". The binary API +is available through a character device in /dev namespace and is an ABI. +The text API is deprecated since 2.6.35, but available for convenience. + +How to use usbmon to collect raw text traces +============================================ + +Unlike the packet socket, usbmon has an interface which provides traces +in a text format. This is used for two purposes. First, it serves as a +common trace exchange format for tools while more sophisticated formats +are finalized. Second, humans can read it in case tools are not available. + +To collect a raw text trace, execute following steps. + +1. Prepare +---------- + +Mount debugfs (it has to be enabled in your kernel configuration), and +load the usbmon module (if built as module). The second step is skipped +if usbmon is built into the kernel:: + + # mount -t debugfs none_debugs /sys/kernel/debug + # modprobe usbmon + # + +Verify that bus sockets are present: + + # ls /sys/kernel/debug/usb/usbmon + 0s 0u 1s 1t 1u 2s 2t 2u 3s 3t 3u 4s 4t 4u + # + +Now you can choose to either use the socket '0u' (to capture packets on all +buses), and skip to step #3, or find the bus used by your device with step #2. +This allows to filter away annoying devices that talk continuously. + +2. Find which bus connects to the desired device +------------------------------------------------ + +Run "cat /sys/kernel/debug/usb/devices", and find the T-line which corresponds +to the device. Usually you do it by looking for the vendor string. If you have +many similar devices, unplug one and compare the two +/sys/kernel/debug/usb/devices outputs. The T-line will have a bus number. + +Example:: + + T: Bus=03 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 0 + D: Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 + P: Vendor=0557 ProdID=2004 Rev= 1.00 + S: Manufacturer=ATEN + S: Product=UC100KM V2.00 + +"Bus=03" means it's bus 3. Alternatively, you can look at the output from +"lsusb" and get the bus number from the appropriate line. Example: + +Bus 003 Device 002: ID 0557:2004 ATEN UC100KM V2.00 + +3. Start 'cat' +-------------- + +:: + + # cat /sys/kernel/debug/usb/usbmon/3u > /tmp/1.mon.out + +to listen on a single bus, otherwise, to listen on all buses, type:: + + # cat /sys/kernel/debug/usb/usbmon/0u > /tmp/1.mon.out + +This process will read until it is killed. Naturally, the output can be +redirected to a desirable location. This is preferred, because it is going +to be quite long. + +4. Perform the desired operation on the USB bus +----------------------------------------------- + +This is where you do something that creates the traffic: plug in a flash key, +copy files, control a webcam, etc. + +5. Kill cat +----------- + +Usually it's done with a keyboard interrupt (Control-C). + +At this point the output file (/tmp/1.mon.out in this example) can be saved, +sent by e-mail, or inspected with a text editor. In the last case make sure +that the file size is not excessive for your favourite editor. + +Raw text data format +==================== + +Two formats are supported currently: the original, or '1t' format, and +the '1u' format. The '1t' format is deprecated in kernel 2.6.21. The '1u' +format adds a few fields, such as ISO frame descriptors, interval, etc. +It produces slightly longer lines, but otherwise is a perfect superset +of '1t' format. + +If it is desired to recognize one from the other in a program, look at the +"address" word (see below), where '1u' format adds a bus number. If 2 colons +are present, it's the '1t' format, otherwise '1u'. + +Any text format data consists of a stream of events, such as URB submission, +URB callback, submission error. Every event is a text line, which consists +of whitespace separated words. The number or position of words may depend +on the event type, but there is a set of words, common for all types. + +Here is the list of words, from left to right: + +- URB Tag. This is used to identify URBs, and is normally an in-kernel address + of the URB structure in hexadecimal, but can be a sequence number or any + other unique string, within reason. + +- Timestamp in microseconds, a decimal number. The timestamp's resolution + depends on available clock, and so it can be much worse than a microsecond + (if the implementation uses jiffies, for example). + +- Event Type. This type refers to the format of the event, not URB type. + Available types are: S - submission, C - callback, E - submission error. + +- "Address" word (formerly a "pipe"). It consists of four fields, separated by + colons: URB type and direction, Bus number, Device address, Endpoint number. + Type and direction are encoded with two bytes in the following manner: + + == == ============================= + Ci Co Control input and output + Zi Zo Isochronous input and output + Ii Io Interrupt input and output + Bi Bo Bulk input and output + == == ============================= + + Bus number, Device address, and Endpoint are decimal numbers, but they may + have leading zeros, for the sake of human readers. + +- URB Status word. This is either a letter, or several numbers separated + by colons: URB status, interval, start frame, and error count. Unlike the + "address" word, all fields save the status are optional. Interval is printed + only for interrupt and isochronous URBs. Start frame is printed only for + isochronous URBs. Error count is printed only for isochronous callback + events. + + The status field is a decimal number, sometimes negative, which represents + a "status" field of the URB. This field makes no sense for submissions, but + is present anyway to help scripts with parsing. When an error occurs, the + field contains the error code. + + In case of a submission of a Control packet, this field contains a Setup Tag + instead of an group of numbers. It is easy to tell whether the Setup Tag is + present because it is never a number. Thus if scripts find a set of numbers + in this word, they proceed to read Data Length (except for isochronous URBs). + If they find something else, like a letter, they read the setup packet before + reading the Data Length or isochronous descriptors. + +- Setup packet, if present, consists of 5 words: one of each for bmRequestType, + bRequest, wValue, wIndex, wLength, as specified by the USB Specification 2.0. + These words are safe to decode if Setup Tag was 's'. Otherwise, the setup + packet was present, but not captured, and the fields contain filler. + +- Number of isochronous frame descriptors and descriptors themselves. + If an Isochronous transfer event has a set of descriptors, a total number + of them in an URB is printed first, then a word per descriptor, up to a + total of 5. The word consists of 3 colon-separated decimal numbers for + status, offset, and length respectively. For submissions, initial length + is reported. For callbacks, actual length is reported. + +- Data Length. For submissions, this is the requested length. For callbacks, + this is the actual length. + +- Data tag. The usbmon may not always capture data, even if length is nonzero. + The data words are present only if this tag is '='. + +- Data words follow, in big endian hexadecimal format. Notice that they are + not machine words, but really just a byte stream split into words to make + it easier to read. Thus, the last word may contain from one to four bytes. + The length of collected data is limited and can be less than the data length + reported in the Data Length word. In the case of an Isochronous input (Zi) + completion where the received data is sparse in the buffer, the length of + the collected data can be greater than the Data Length value (because Data + Length counts only the bytes that were received whereas the Data words + contain the entire transfer buffer). + +Examples: + +An input control transfer to get a port status:: + + d5ea89a0 3575914555 S Ci:1:001:0 s a3 00 0000 0003 0004 4 < + d5ea89a0 3575914560 C Ci:1:001:0 0 4 = 01050000 + +An output bulk transfer to send a SCSI command 0x28 (READ_10) in a 31-byte +Bulk wrapper to a storage device at address 5:: + + dd65f0e8 4128379752 S Bo:1:005:2 -115 31 = 55534243 ad000000 00800000 80010a28 20000000 20000040 00000000 000000 + dd65f0e8 4128379808 C Bo:1:005:2 0 31 > + +Raw binary format and API +========================= + +The overall architecture of the API is about the same as the one above, +only the events are delivered in binary format. Each event is sent in +the following structure (its name is made up, so that we can refer to it):: + + struct usbmon_packet { + u64 id; /* 0: URB ID - from submission to callback */ + unsigned char type; /* 8: Same as text; extensible. */ + unsigned char xfer_type; /* ISO (0), Intr, Control, Bulk (3) */ + unsigned char epnum; /* Endpoint number and transfer direction */ + unsigned char devnum; /* Device address */ + u16 busnum; /* 12: Bus number */ + char flag_setup; /* 14: Same as text */ + char flag_data; /* 15: Same as text; Binary zero is OK. */ + s64 ts_sec; /* 16: gettimeofday */ + s32 ts_usec; /* 24: gettimeofday */ + int status; /* 28: */ + unsigned int length; /* 32: Length of data (submitted or actual) */ + unsigned int len_cap; /* 36: Delivered length */ + union { /* 40: */ + unsigned char setup[SETUP_LEN]; /* Only for Control S-type */ + struct iso_rec { /* Only for ISO */ + int error_count; + int numdesc; + } iso; + } s; + int interval; /* 48: Only for Interrupt and ISO */ + int start_frame; /* 52: For ISO */ + unsigned int xfer_flags; /* 56: copy of URB's transfer_flags */ + unsigned int ndesc; /* 60: Actual number of ISO descriptors */ + }; /* 64 total length */ + +These events can be received from a character device by reading with read(2), +with an ioctl(2), or by accessing the buffer with mmap. However, read(2) +only returns first 48 bytes for compatibility reasons. + +The character device is usually called /dev/usbmonN, where N is the USB bus +number. Number zero (/dev/usbmon0) is special and means "all buses". +Note that specific naming policy is set by your Linux distribution. + +If you create /dev/usbmon0 by hand, make sure that it is owned by root +and has mode 0600. Otherwise, unprivileged users will be able to snoop +keyboard traffic. + +The following ioctl calls are available, with MON_IOC_MAGIC 0x92: + + MON_IOCQ_URB_LEN, defined as _IO(MON_IOC_MAGIC, 1) + +This call returns the length of data in the next event. Note that majority of +events contain no data, so if this call returns zero, it does not mean that +no events are available. + + MON_IOCG_STATS, defined as _IOR(MON_IOC_MAGIC, 3, struct mon_bin_stats) + +The argument is a pointer to the following structure:: + + struct mon_bin_stats { + u32 queued; + u32 dropped; + }; + +The member "queued" refers to the number of events currently queued in the +buffer (and not to the number of events processed since the last reset). + +The member "dropped" is the number of events lost since the last call +to MON_IOCG_STATS. + + MON_IOCT_RING_SIZE, defined as _IO(MON_IOC_MAGIC, 4) + +This call sets the buffer size. The argument is the size in bytes. +The size may be rounded down to the next chunk (or page). If the requested +size is out of [unspecified] bounds for this kernel, the call fails with +-EINVAL. + + MON_IOCQ_RING_SIZE, defined as _IO(MON_IOC_MAGIC, 5) + +This call returns the current size of the buffer in bytes. + + MON_IOCX_GET, defined as _IOW(MON_IOC_MAGIC, 6, struct mon_get_arg) + MON_IOCX_GETX, defined as _IOW(MON_IOC_MAGIC, 10, struct mon_get_arg) + +These calls wait for events to arrive if none were in the kernel buffer, +then return the first event. The argument is a pointer to the following +structure:: + + struct mon_get_arg { + struct usbmon_packet *hdr; + void *data; + size_t alloc; /* Length of data (can be zero) */ + }; + +Before the call, hdr, data, and alloc should be filled. Upon return, the area +pointed by hdr contains the next event structure, and the data buffer contains +the data, if any. The event is removed from the kernel buffer. + +The MON_IOCX_GET copies 48 bytes to hdr area, MON_IOCX_GETX copies 64 bytes. + + MON_IOCX_MFETCH, defined as _IOWR(MON_IOC_MAGIC, 7, struct mon_mfetch_arg) + +This ioctl is primarily used when the application accesses the buffer +with mmap(2). Its argument is a pointer to the following structure:: + + struct mon_mfetch_arg { + uint32_t *offvec; /* Vector of events fetched */ + uint32_t nfetch; /* Number of events to fetch (out: fetched) */ + uint32_t nflush; /* Number of events to flush */ + }; + +The ioctl operates in 3 stages. + +First, it removes and discards up to nflush events from the kernel buffer. +The actual number of events discarded is returned in nflush. + +Second, it waits for an event to be present in the buffer, unless the pseudo- +device is open with O_NONBLOCK. + +Third, it extracts up to nfetch offsets into the mmap buffer, and stores +them into the offvec. The actual number of event offsets is stored into +the nfetch. + + MON_IOCH_MFLUSH, defined as _IO(MON_IOC_MAGIC, 8) + +This call removes a number of events from the kernel buffer. Its argument +is the number of events to remove. If the buffer contains fewer events +than requested, all events present are removed, and no error is reported. +This works when no events are available too. + + FIONBIO + +The ioctl FIONBIO may be implemented in the future, if there's a need. + +In addition to ioctl(2) and read(2), the special file of binary API can +be polled with select(2) and poll(2). But lseek(2) does not work. + +* Memory-mapped access of the kernel buffer for the binary API + +The basic idea is simple: + +To prepare, map the buffer by getting the current size, then using mmap(2). +Then, execute a loop similar to the one written in pseudo-code below:: + + struct mon_mfetch_arg fetch; + struct usbmon_packet *hdr; + int nflush = 0; + for (;;) { + fetch.offvec = vec; // Has N 32-bit words + fetch.nfetch = N; // Or less than N + fetch.nflush = nflush; + ioctl(fd, MON_IOCX_MFETCH, &fetch); // Process errors, too + nflush = fetch.nfetch; // This many packets to flush when done + for (i = 0; i < nflush; i++) { + hdr = (struct ubsmon_packet *) &mmap_area[vec[i]]; + if (hdr->type == '@') // Filler packet + continue; + caddr_t data = &mmap_area[vec[i]] + 64; + process_packet(hdr, data); + } + } + +Thus, the main idea is to execute only one ioctl per N events. + +Although the buffer is circular, the returned headers and data do not cross +the end of the buffer, so the above pseudo-code does not need any gathering. diff --git a/Documentation/usb/usbmon.txt b/Documentation/usb/usbmon.txt deleted file mode 100644 index b0bd51080799..000000000000 --- a/Documentation/usb/usbmon.txt +++ /dev/null @@ -1,375 +0,0 @@ -====== -usbmon -====== - -Introduction -============ - -The name "usbmon" in lowercase refers to a facility in kernel which is -used to collect traces of I/O on the USB bus. This function is analogous -to a packet socket used by network monitoring tools such as tcpdump(1) -or Ethereal. Similarly, it is expected that a tool such as usbdump or -USBMon (with uppercase letters) is used to examine raw traces produced -by usbmon. - -The usbmon reports requests made by peripheral-specific drivers to Host -Controller Drivers (HCD). So, if HCD is buggy, the traces reported by -usbmon may not correspond to bus transactions precisely. This is the same -situation as with tcpdump. - -Two APIs are currently implemented: "text" and "binary". The binary API -is available through a character device in /dev namespace and is an ABI. -The text API is deprecated since 2.6.35, but available for convenience. - -How to use usbmon to collect raw text traces -============================================ - -Unlike the packet socket, usbmon has an interface which provides traces -in a text format. This is used for two purposes. First, it serves as a -common trace exchange format for tools while more sophisticated formats -are finalized. Second, humans can read it in case tools are not available. - -To collect a raw text trace, execute following steps. - -1. Prepare ----------- - -Mount debugfs (it has to be enabled in your kernel configuration), and -load the usbmon module (if built as module). The second step is skipped -if usbmon is built into the kernel:: - - # mount -t debugfs none_debugs /sys/kernel/debug - # modprobe usbmon - # - -Verify that bus sockets are present: - - # ls /sys/kernel/debug/usb/usbmon - 0s 0u 1s 1t 1u 2s 2t 2u 3s 3t 3u 4s 4t 4u - # - -Now you can choose to either use the socket '0u' (to capture packets on all -buses), and skip to step #3, or find the bus used by your device with step #2. -This allows to filter away annoying devices that talk continuously. - -2. Find which bus connects to the desired device ------------------------------------------------- - -Run "cat /sys/kernel/debug/usb/devices", and find the T-line which corresponds -to the device. Usually you do it by looking for the vendor string. If you have -many similar devices, unplug one and compare the two -/sys/kernel/debug/usb/devices outputs. The T-line will have a bus number. - -Example:: - - T: Bus=03 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 0 - D: Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 - P: Vendor=0557 ProdID=2004 Rev= 1.00 - S: Manufacturer=ATEN - S: Product=UC100KM V2.00 - -"Bus=03" means it's bus 3. Alternatively, you can look at the output from -"lsusb" and get the bus number from the appropriate line. Example: - -Bus 003 Device 002: ID 0557:2004 ATEN UC100KM V2.00 - -3. Start 'cat' --------------- - -:: - - # cat /sys/kernel/debug/usb/usbmon/3u > /tmp/1.mon.out - -to listen on a single bus, otherwise, to listen on all buses, type:: - - # cat /sys/kernel/debug/usb/usbmon/0u > /tmp/1.mon.out - -This process will read until it is killed. Naturally, the output can be -redirected to a desirable location. This is preferred, because it is going -to be quite long. - -4. Perform the desired operation on the USB bus ------------------------------------------------ - -This is where you do something that creates the traffic: plug in a flash key, -copy files, control a webcam, etc. - -5. Kill cat ------------ - -Usually it's done with a keyboard interrupt (Control-C). - -At this point the output file (/tmp/1.mon.out in this example) can be saved, -sent by e-mail, or inspected with a text editor. In the last case make sure -that the file size is not excessive for your favourite editor. - -Raw text data format -==================== - -Two formats are supported currently: the original, or '1t' format, and -the '1u' format. The '1t' format is deprecated in kernel 2.6.21. The '1u' -format adds a few fields, such as ISO frame descriptors, interval, etc. -It produces slightly longer lines, but otherwise is a perfect superset -of '1t' format. - -If it is desired to recognize one from the other in a program, look at the -"address" word (see below), where '1u' format adds a bus number. If 2 colons -are present, it's the '1t' format, otherwise '1u'. - -Any text format data consists of a stream of events, such as URB submission, -URB callback, submission error. Every event is a text line, which consists -of whitespace separated words. The number or position of words may depend -on the event type, but there is a set of words, common for all types. - -Here is the list of words, from left to right: - -- URB Tag. This is used to identify URBs, and is normally an in-kernel address - of the URB structure in hexadecimal, but can be a sequence number or any - other unique string, within reason. - -- Timestamp in microseconds, a decimal number. The timestamp's resolution - depends on available clock, and so it can be much worse than a microsecond - (if the implementation uses jiffies, for example). - -- Event Type. This type refers to the format of the event, not URB type. - Available types are: S - submission, C - callback, E - submission error. - -- "Address" word (formerly a "pipe"). It consists of four fields, separated by - colons: URB type and direction, Bus number, Device address, Endpoint number. - Type and direction are encoded with two bytes in the following manner: - - == == ============================= - Ci Co Control input and output - Zi Zo Isochronous input and output - Ii Io Interrupt input and output - Bi Bo Bulk input and output - == == ============================= - - Bus number, Device address, and Endpoint are decimal numbers, but they may - have leading zeros, for the sake of human readers. - -- URB Status word. This is either a letter, or several numbers separated - by colons: URB status, interval, start frame, and error count. Unlike the - "address" word, all fields save the status are optional. Interval is printed - only for interrupt and isochronous URBs. Start frame is printed only for - isochronous URBs. Error count is printed only for isochronous callback - events. - - The status field is a decimal number, sometimes negative, which represents - a "status" field of the URB. This field makes no sense for submissions, but - is present anyway to help scripts with parsing. When an error occurs, the - field contains the error code. - - In case of a submission of a Control packet, this field contains a Setup Tag - instead of an group of numbers. It is easy to tell whether the Setup Tag is - present because it is never a number. Thus if scripts find a set of numbers - in this word, they proceed to read Data Length (except for isochronous URBs). - If they find something else, like a letter, they read the setup packet before - reading the Data Length or isochronous descriptors. - -- Setup packet, if present, consists of 5 words: one of each for bmRequestType, - bRequest, wValue, wIndex, wLength, as specified by the USB Specification 2.0. - These words are safe to decode if Setup Tag was 's'. Otherwise, the setup - packet was present, but not captured, and the fields contain filler. - -- Number of isochronous frame descriptors and descriptors themselves. - If an Isochronous transfer event has a set of descriptors, a total number - of them in an URB is printed first, then a word per descriptor, up to a - total of 5. The word consists of 3 colon-separated decimal numbers for - status, offset, and length respectively. For submissions, initial length - is reported. For callbacks, actual length is reported. - -- Data Length. For submissions, this is the requested length. For callbacks, - this is the actual length. - -- Data tag. The usbmon may not always capture data, even if length is nonzero. - The data words are present only if this tag is '='. - -- Data words follow, in big endian hexadecimal format. Notice that they are - not machine words, but really just a byte stream split into words to make - it easier to read. Thus, the last word may contain from one to four bytes. - The length of collected data is limited and can be less than the data length - reported in the Data Length word. In the case of an Isochronous input (Zi) - completion where the received data is sparse in the buffer, the length of - the collected data can be greater than the Data Length value (because Data - Length counts only the bytes that were received whereas the Data words - contain the entire transfer buffer). - -Examples: - -An input control transfer to get a port status:: - - d5ea89a0 3575914555 S Ci:1:001:0 s a3 00 0000 0003 0004 4 < - d5ea89a0 3575914560 C Ci:1:001:0 0 4 = 01050000 - -An output bulk transfer to send a SCSI command 0x28 (READ_10) in a 31-byte -Bulk wrapper to a storage device at address 5:: - - dd65f0e8 4128379752 S Bo:1:005:2 -115 31 = 55534243 ad000000 00800000 80010a28 20000000 20000040 00000000 000000 - dd65f0e8 4128379808 C Bo:1:005:2 0 31 > - -Raw binary format and API -========================= - -The overall architecture of the API is about the same as the one above, -only the events are delivered in binary format. Each event is sent in -the following structure (its name is made up, so that we can refer to it):: - - struct usbmon_packet { - u64 id; /* 0: URB ID - from submission to callback */ - unsigned char type; /* 8: Same as text; extensible. */ - unsigned char xfer_type; /* ISO (0), Intr, Control, Bulk (3) */ - unsigned char epnum; /* Endpoint number and transfer direction */ - unsigned char devnum; /* Device address */ - u16 busnum; /* 12: Bus number */ - char flag_setup; /* 14: Same as text */ - char flag_data; /* 15: Same as text; Binary zero is OK. */ - s64 ts_sec; /* 16: gettimeofday */ - s32 ts_usec; /* 24: gettimeofday */ - int status; /* 28: */ - unsigned int length; /* 32: Length of data (submitted or actual) */ - unsigned int len_cap; /* 36: Delivered length */ - union { /* 40: */ - unsigned char setup[SETUP_LEN]; /* Only for Control S-type */ - struct iso_rec { /* Only for ISO */ - int error_count; - int numdesc; - } iso; - } s; - int interval; /* 48: Only for Interrupt and ISO */ - int start_frame; /* 52: For ISO */ - unsigned int xfer_flags; /* 56: copy of URB's transfer_flags */ - unsigned int ndesc; /* 60: Actual number of ISO descriptors */ - }; /* 64 total length */ - -These events can be received from a character device by reading with read(2), -with an ioctl(2), or by accessing the buffer with mmap. However, read(2) -only returns first 48 bytes for compatibility reasons. - -The character device is usually called /dev/usbmonN, where N is the USB bus -number. Number zero (/dev/usbmon0) is special and means "all buses". -Note that specific naming policy is set by your Linux distribution. - -If you create /dev/usbmon0 by hand, make sure that it is owned by root -and has mode 0600. Otherwise, unprivileged users will be able to snoop -keyboard traffic. - -The following ioctl calls are available, with MON_IOC_MAGIC 0x92: - - MON_IOCQ_URB_LEN, defined as _IO(MON_IOC_MAGIC, 1) - -This call returns the length of data in the next event. Note that majority of -events contain no data, so if this call returns zero, it does not mean that -no events are available. - - MON_IOCG_STATS, defined as _IOR(MON_IOC_MAGIC, 3, struct mon_bin_stats) - -The argument is a pointer to the following structure:: - - struct mon_bin_stats { - u32 queued; - u32 dropped; - }; - -The member "queued" refers to the number of events currently queued in the -buffer (and not to the number of events processed since the last reset). - -The member "dropped" is the number of events lost since the last call -to MON_IOCG_STATS. - - MON_IOCT_RING_SIZE, defined as _IO(MON_IOC_MAGIC, 4) - -This call sets the buffer size. The argument is the size in bytes. -The size may be rounded down to the next chunk (or page). If the requested -size is out of [unspecified] bounds for this kernel, the call fails with --EINVAL. - - MON_IOCQ_RING_SIZE, defined as _IO(MON_IOC_MAGIC, 5) - -This call returns the current size of the buffer in bytes. - - MON_IOCX_GET, defined as _IOW(MON_IOC_MAGIC, 6, struct mon_get_arg) - MON_IOCX_GETX, defined as _IOW(MON_IOC_MAGIC, 10, struct mon_get_arg) - -These calls wait for events to arrive if none were in the kernel buffer, -then return the first event. The argument is a pointer to the following -structure:: - - struct mon_get_arg { - struct usbmon_packet *hdr; - void *data; - size_t alloc; /* Length of data (can be zero) */ - }; - -Before the call, hdr, data, and alloc should be filled. Upon return, the area -pointed by hdr contains the next event structure, and the data buffer contains -the data, if any. The event is removed from the kernel buffer. - -The MON_IOCX_GET copies 48 bytes to hdr area, MON_IOCX_GETX copies 64 bytes. - - MON_IOCX_MFETCH, defined as _IOWR(MON_IOC_MAGIC, 7, struct mon_mfetch_arg) - -This ioctl is primarily used when the application accesses the buffer -with mmap(2). Its argument is a pointer to the following structure:: - - struct mon_mfetch_arg { - uint32_t *offvec; /* Vector of events fetched */ - uint32_t nfetch; /* Number of events to fetch (out: fetched) */ - uint32_t nflush; /* Number of events to flush */ - }; - -The ioctl operates in 3 stages. - -First, it removes and discards up to nflush events from the kernel buffer. -The actual number of events discarded is returned in nflush. - -Second, it waits for an event to be present in the buffer, unless the pseudo- -device is open with O_NONBLOCK. - -Third, it extracts up to nfetch offsets into the mmap buffer, and stores -them into the offvec. The actual number of event offsets is stored into -the nfetch. - - MON_IOCH_MFLUSH, defined as _IO(MON_IOC_MAGIC, 8) - -This call removes a number of events from the kernel buffer. Its argument -is the number of events to remove. If the buffer contains fewer events -than requested, all events present are removed, and no error is reported. -This works when no events are available too. - - FIONBIO - -The ioctl FIONBIO may be implemented in the future, if there's a need. - -In addition to ioctl(2) and read(2), the special file of binary API can -be polled with select(2) and poll(2). But lseek(2) does not work. - -* Memory-mapped access of the kernel buffer for the binary API - -The basic idea is simple: - -To prepare, map the buffer by getting the current size, then using mmap(2). -Then, execute a loop similar to the one written in pseudo-code below:: - - struct mon_mfetch_arg fetch; - struct usbmon_packet *hdr; - int nflush = 0; - for (;;) { - fetch.offvec = vec; // Has N 32-bit words - fetch.nfetch = N; // Or less than N - fetch.nflush = nflush; - ioctl(fd, MON_IOCX_MFETCH, &fetch); // Process errors, too - nflush = fetch.nfetch; // This many packets to flush when done - for (i = 0; i < nflush; i++) { - hdr = (struct ubsmon_packet *) &mmap_area[vec[i]]; - if (hdr->type == '@') // Filler packet - continue; - caddr_t data = &mmap_area[vec[i]] + 64; - process_packet(hdr, data); - } - } - -Thus, the main idea is to execute only one ioctl per N events. - -Although the buffer is circular, the returned headers and data do not cross -the end of the buffer, so the above pseudo-code does not need any gathering. diff --git a/Documentation/usb/wusb-design-overview.rst b/Documentation/usb/wusb-design-overview.rst new file mode 100644 index 000000000000..dc5e21609bb5 --- /dev/null +++ b/Documentation/usb/wusb-design-overview.rst @@ -0,0 +1,457 @@ +================================ +Linux UWB + Wireless USB + WiNET +================================ + + Copyright (C) 2005-2006 Intel Corporation + + Inaky Perez-Gonzalez + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License version + 2 as published by the Free Software Foundation. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA. + + +Please visit http://bughost.org/thewiki/Design-overview.txt-1.8 for +updated content. + + * Design-overview.txt-1.8 + +This code implements a Ultra Wide Band stack for Linux, as well as +drivers for the USB based UWB radio controllers defined in the +Wireless USB 1.0 specification (including Wireless USB host controller +and an Intel WiNET controller). + +.. Contents + 1. Introduction + 1. HWA: Host Wire adapters, your Wireless USB dongle + + 2. DWA: Device Wired Adaptor, a Wireless USB hub for wired + devices + 3. WHCI: Wireless Host Controller Interface, the PCI WUSB host + adapter + 2. The UWB stack + 1. Devices and hosts: the basic structure + + 2. Host Controller life cycle + + 3. On the air: beacons and enumerating the radio neighborhood + + 4. Device lists + 5. Bandwidth allocation + + 3. Wireless USB Host Controller drivers + + 4. Glossary + + +Introduction +============ + +UWB is a wide-band communication protocol that is to serve also as the +low-level protocol for others (much like TCP sits on IP). Currently +these others are Wireless USB and TCP/IP, but seems Bluetooth and +Firewire/1394 are coming along. + +UWB uses a band from roughly 3 to 10 GHz, transmitting at a max of +~-41dB (or 0.074 uW/MHz--geography specific data is still being +negotiated w/ regulators, so watch for changes). That band is divided in +a bunch of ~1.5 GHz wide channels (or band groups) composed of three +subbands/subchannels (528 MHz each). Each channel is independent of each +other, so you could consider them different "busses". Initially this +driver considers them all a single one. + +Radio time is divided in 65536 us long /superframes/, each one divided +in 256 256us long /MASs/ (Media Allocation Slots), which are the basic +time/media allocation units for transferring data. At the beginning of +each superframe there is a Beacon Period (BP), where every device +transmit its beacon on a single MAS. The length of the BP depends on how +many devices are present and the length of their beacons. + +Devices have a MAC (fixed, 48 bit address) and a device (changeable, 16 +bit address) and send periodic beacons to advertise themselves and pass +info on what they are and do. They advertise their capabilities and a +bunch of other stuff. + +The different logical parts of this driver are: + + * + + *UWB*: the Ultra-Wide-Band stack -- manages the radio and + associated spectrum to allow for devices sharing it. Allows to + control bandwidth assignment, beaconing, scanning, etc + + * + + *WUSB*: the layer that sits on top of UWB to provide Wireless USB. + The Wireless USB spec defines means to control a UWB radio and to + do the actual WUSB. + + +HWA: Host Wire adapters, your Wireless USB dongle +------------------------------------------------- + +WUSB also defines a device called a Host Wire Adaptor (HWA), which in +mere terms is a USB dongle that enables your PC to have UWB and Wireless +USB. The Wireless USB Host Controller in a HWA looks to the host like a +[Wireless] USB controller connected via USB (!) + +The HWA itself is broken in two or three main interfaces: + + * + + *RC*: Radio control -- this implements an interface to the + Ultra-Wide-Band radio controller. The driver for this implements a + USB-based UWB Radio Controller to the UWB stack. + + * + + *HC*: the wireless USB host controller. It looks like a USB host + whose root port is the radio and the WUSB devices connect to it. + To the system it looks like a separate USB host. The driver (will) + implement a USB host controller (similar to UHCI, OHCI or EHCI) + for which the root hub is the radio...To reiterate: it is a USB + controller that is connected via USB instead of PCI. + + * + + *WINET*: some HW provide a WiNET interface (IP over UWB). This + package provides a driver for it (it looks like a network + interface, winetX). The driver detects when there is a link up for + their type and kick into gear. + + +DWA: Device Wired Adaptor, a Wireless USB hub for wired devices +--------------------------------------------------------------- + +These are the complement to HWAs. They are a USB host for connecting +wired devices, but it is connected to your PC connected via Wireless +USB. To the system it looks like yet another USB host. To the untrained +eye, it looks like a hub that connects upstream wirelessly. + +We still offer no support for this; however, it should share a lot of +code with the HWA-RC driver; there is a bunch of factorization work that +has been done to support that in upcoming releases. + + +WHCI: Wireless Host Controller Interface, the PCI WUSB host adapter +------------------------------------------------------------------- + +This is your usual PCI device that implements WHCI. Similar in concept +to EHCI, it allows your wireless USB devices (including DWAs) to connect +to your host via a PCI interface. As in the case of the HWA, it has a +Radio Control interface and the WUSB Host Controller interface per se. + +There is still no driver support for this, but will be in upcoming +releases. + + +The UWB stack +============= + +The main mission of the UWB stack is to keep a tally of which devices +are in radio proximity to allow drivers to connect to them. As well, it +provides an API for controlling the local radio controllers (RCs from +now on), such as to start/stop beaconing, scan, allocate bandwidth, etc. + + +Devices and hosts: the basic structure +-------------------------------------- + +The main building block here is the UWB device (struct uwb_dev). For +each device that pops up in radio presence (ie: the UWB host receives a +beacon from it) you get a struct uwb_dev that will show up in +/sys/bus/uwb/devices. + +For each RC that is detected, a new struct uwb_rc and struct uwb_dev are +created. An entry is also created in /sys/class/uwb_rc for each RC. + +Each RC driver is implemented by a separate driver that plugs into the +interface that the UWB stack provides through a struct uwb_rc_ops. The +spec creators have been nice enough to make the message format the same +for HWA and WHCI RCs, so the driver is really a very thin transport that +moves the requests from the UWB API to the device [/uwb_rc_ops->cmd()/] +and sends the replies and notifications back to the API +[/uwb_rc_neh_grok()/]. Notifications are handled to the UWB daemon, that +is chartered, among other things, to keep the tab of how the UWB radio +neighborhood looks, creating and destroying devices as they show up or +disappear. + +Command execution is very simple: a command block is sent and a event +block or reply is expected back. For sending/receiving command/events, a +handle called /neh/ (Notification/Event Handle) is opened with +/uwb_rc_neh_open()/. + +The HWA-RC (USB dongle) driver (drivers/uwb/hwa-rc.c) does this job for +the USB connected HWA. Eventually, drivers/whci-rc.c will do the same +for the PCI connected WHCI controller. + + +Host Controller life cycle +-------------------------- + +So let's say we connect a dongle to the system: it is detected and +firmware uploaded if needed [for Intel's i1480 +/drivers/uwb/ptc/usb.c:ptc_usb_probe()/] and then it is reenumerated. +Now we have a real HWA device connected and +/drivers/uwb/hwa-rc.c:hwarc_probe()/ picks it up, that will set up the +Wire-Adaptor environment and then suck it into the UWB stack's vision of +the world [/drivers/uwb/lc-rc.c:uwb_rc_add()/]. + + * + + [*] The stack should put a new RC to scan for devices + [/uwb_rc_scan()/] so it finds what's available around and tries to + connect to them, but this is policy stuff and should be driven + from user space. As of now, the operator is expected to do it + manually; see the release notes for documentation on the procedure. + +When a dongle is disconnected, /drivers/uwb/hwa-rc.c:hwarc_disconnect()/ +takes time of tearing everything down safely (or not...). + + +On the air: beacons and enumerating the radio neighborhood +---------------------------------------------------------- + +So assuming we have devices and we have agreed for a channel to connect +on (let's say 9), we put the new RC to beacon: + + * + + $ echo 9 0 > /sys/class/uwb_rc/uwb0/beacon + +Now it is visible. If there were other devices in the same radio channel +and beacon group (that's what the zero is for), the dongle's radio +control interface will send beacon notifications on its +notification/event endpoint (NEEP). The beacon notifications are part of +the event stream that is funneled into the API with +/drivers/uwb/neh.c:uwb_rc_neh_grok()/ and delivered to the UWBD, the UWB +daemon through a notification list. + +UWBD wakes up and scans the event list; finds a beacon and adds it to +the BEACON CACHE (/uwb_beca/). If he receives a number of beacons from +the same device, he considers it to be 'onair' and creates a new device +[/drivers/uwb/lc-dev.c:uwbd_dev_onair()/]. Similarly, when no beacons +are received in some time, the device is considered gone and wiped out +[uwbd calls periodically /uwb/beacon.c:uwb_beca_purge()/ that will purge +the beacon cache of dead devices]. + + +Device lists +------------ + +All UWB devices are kept in the list of the struct bus_type uwb_bus_type. + + +Bandwidth allocation +-------------------- + +The UWB stack maintains a local copy of DRP availability through +processing of incoming *DRP Availability Change* notifications. This +local copy is currently used to present the current bandwidth +availability to the user through the sysfs file +/sys/class/uwb_rc/uwbx/bw_avail. In the future the bandwidth +availability information will be used by the bandwidth reservation +routines. + +The bandwidth reservation routines are in progress and are thus not +present in the current release. When completed they will enable a user +to initiate DRP reservation requests through interaction with sysfs. DRP +reservation requests from remote UWB devices will also be handled. The +bandwidth management done by the UWB stack will include callbacks to the +higher layers will enable the higher layers to use the reservations upon +completion. [Note: The bandwidth reservation work is in progress and +subject to change.] + + +Wireless USB Host Controller drivers +==================================== + +*WARNING* This section needs a lot of work! + +As explained above, there are three different types of HCs in the WUSB +world: HWA-HC, DWA-HC and WHCI-HC. + +HWA-HC and DWA-HC share that they are Wire-Adapters (USB or WUSB +connected controllers), and their transfer management system is almost +identical. So is their notification delivery system. + +HWA-HC and WHCI-HC share that they are both WUSB host controllers, so +they have to deal with WUSB device life cycle and maintenance, wireless +root-hub + +HWA exposes a Host Controller interface (HWA-HC 0xe0/02/02). This has +three endpoints (Notifications, Data Transfer In and Data Transfer +Out--known as NEP, DTI and DTO in the code). + +We reserve UWB bandwidth for our Wireless USB Cluster, create a Cluster +ID and tell the HC to use all that. Then we start it. This means the HC +starts sending MMCs. + + * + + The MMCs are blocks of data defined somewhere in the WUSB1.0 spec + that define a stream in the UWB channel time allocated for sending + WUSB IEs (host to device commands/notifications) and Device + Notifications (device initiated to host). Each host defines a + unique Wireless USB cluster through MMCs. Devices can connect to a + single cluster at the time. The IEs are Information Elements, and + among them are the bandwidth allocations that tell each device + when can they transmit or receive. + +Now it all depends on external stimuli. + +New device connection +--------------------- + +A new device pops up, it scans the radio looking for MMCs that give out +the existence of Wireless USB channels. Once one (or more) are found, +selects which one to connect to. Sends a /DN_Connect/ (device +notification connect) during the DNTS (Device Notification Time +Slot--announced in the MMCs + +HC picks the /DN_Connect/ out (nep module sends to notif.c for delivery +into /devconnect/). This process starts the authentication process for +the device. First we allocate a /fake port/ and assign an +unauthenticated address (128 to 255--what we really do is +0x80 | fake_port_idx). We fiddle with the fake port status and /hub_wq/ +sees a new connection, so he moves on to enable the fake port with a reset. + +So now we are in the reset path -- we know we have a non-yet enumerated +device with an unauthorized address; we ask user space to authenticate +(FIXME: not yet done, similar to bluetooth pairing), then we do the key +exchange (FIXME: not yet done) and issue a /set address 0/ to bring the +device to the default state. Device is authenticated. + +From here, the USB stack takes control through the usb_hcd ops. hub_wq +has seen the port status changes, as we have been toggling them. It will +start enumerating and doing transfers through usb_hcd->urb_enqueue() to +read descriptors and move our data. + +Device life cycle and keep alives +--------------------------------- + +Every time there is a successful transfer to/from a device, we update a +per-device activity timestamp. If not, every now and then we check and +if the activity timestamp gets old, we ping the device by sending it a +Keep Alive IE; it responds with a /DN_Alive/ pong during the DNTS (this +arrives to us as a notification through +devconnect.c:wusb_handle_dn_alive(). If a device times out, we +disconnect it from the system (cleaning up internal information and +toggling the bits in the fake hub port, which kicks hub_wq into removing +the rest of the stuff). + +This is done through devconnect:__wusb_check_devs(), which will scan the +device list looking for whom needs refreshing. + +If the device wants to disconnect, it will either die (ugly) or send a +/DN_Disconnect/ that will prompt a disconnection from the system. + +Sending and receiving data +-------------------------- + +Data is sent and received through /Remote Pipes/ (rpipes). An rpipe is +/aimed/ at an endpoint in a WUSB device. This is the same for HWAs and +DWAs. + +Each HC has a number of rpipes and buffers that can be assigned to them; +when doing a data transfer (xfer), first the rpipe has to be aimed and +prepared (buffers assigned), then we can start queueing requests for +data in or out. + +Data buffers have to be segmented out before sending--so we send first a +header (segment request) and then if there is any data, a data buffer +immediately after to the DTI interface (yep, even the request). If our +buffer is bigger than the max segment size, then we just do multiple +requests. + +[This sucks, because doing USB scatter gatter in Linux is resource +intensive, if any...not that the current approach is not. It just has to +be cleaned up a lot :)]. + +If reading, we don't send data buffers, just the segment headers saying +we want to read segments. + +When the xfer is executed, we receive a notification that says data is +ready in the DTI endpoint (handled through +xfer.c:wa_handle_notif_xfer()). In there we read from the DTI endpoint a +descriptor that gives us the status of the transfer, its identification +(given when we issued it) and the segment number. If it was a data read, +we issue another URB to read into the destination buffer the chunk of +data coming out of the remote endpoint. Done, wait for the next guy. The +callbacks for the URBs issued from here are the ones that will declare +the xfer complete at some point and call its callback. + +Seems simple, but the implementation is not trivial. + + * + + *WARNING* Old!! + +The main xfer descriptor, wa_xfer (equivalent to a URB) contains an +array of segments, tallys on segments and buffers and callback +information. Buried in there is a lot of URBs for executing the segments +and buffer transfers. + +For OUT xfers, there is an array of segments, one URB for each, another +one of buffer URB. When submitting, we submit URBs for segment request +1, buffer 1, segment 2, buffer 2...etc. Then we wait on the DTI for xfer +result data; when all the segments are complete, we call the callback to +finalize the transfer. + +For IN xfers, we only issue URBs for the segments we want to read and +then wait for the xfer result data. + +URB mapping into xfers +^^^^^^^^^^^^^^^^^^^^^^ + +This is done by hwahc_op_urb_[en|de]queue(). In enqueue() we aim an +rpipe to the endpoint where we have to transmit, create a transfer +context (wa_xfer) and submit it. When the xfer is done, our callback is +called and we assign the status bits and release the xfer resources. + +In dequeue() we are basically cancelling/aborting the transfer. We issue +a xfer abort request to the HC, cancel all the URBs we had submitted +and not yet done and when all that is done, the xfer callback will be +called--this will call the URB callback. + + +Glossary +======== + +*DWA* -- Device Wire Adapter + +USB host, wired for downstream devices, upstream connects wirelessly +with Wireless USB. + +*EVENT* -- Response to a command on the NEEP + +*HWA* -- Host Wire Adapter / USB dongle for UWB and Wireless USB + +*NEH* -- Notification/Event Handle + +Handle/file descriptor for receiving notifications or events. The WA +code requires you to get one of this to listen for notifications or +events on the NEEP. + +*NEEP* -- Notification/Event EndPoint + +Stuff related to the management of the first endpoint of a HWA USB +dongle that is used to deliver an stream of events and notifications to +the host. + +*NOTIFICATION* -- Message coming in the NEEP as response to something. + +*RC* -- Radio Control + +Design-overview.txt-1.8 (last edited 2006-11-04 12:22:24 by +InakyPerezGonzalez) diff --git a/MAINTAINERS b/MAINTAINERS index 57f496cff999..8e9d6ea73c35 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -3751,7 +3751,7 @@ F: scripts/extract-cert.c CERTIFIED WIRELESS USB (WUSB) SUBSYSTEM: L: linux-usb@vger.kernel.org S: Orphan -F: Documentation/usb/WUSB-Design-overview.txt +F: Documentation/usb/wusb-design-overview.rst F: Documentation/usb/wusb-cbaf F: drivers/usb/host/hwa-hc.c F: drivers/usb/host/whci/ @@ -16238,7 +16238,7 @@ USB ACM DRIVER M: Oliver Neukum L: linux-usb@vger.kernel.org S: Maintained -F: Documentation/usb/acm.txt +F: Documentation/usb/acm.rst F: drivers/usb/class/cdc-acm.* USB AR5523 WIRELESS DRIVER @@ -16291,7 +16291,7 @@ USB EHCI DRIVER M: Alan Stern L: linux-usb@vger.kernel.org S: Maintained -F: Documentation/usb/ehci.txt +F: Documentation/usb/ehci.rst F: drivers/usb/host/ehci* USB GADGET/PERIPHERAL SUBSYSTEM @@ -16365,7 +16365,7 @@ USB OHCI DRIVER M: Alan Stern L: linux-usb@vger.kernel.org S: Maintained -F: Documentation/usb/ohci.txt +F: Documentation/usb/ohci.rst F: drivers/usb/host/ohci* USB OTG FSM (Finite State Machine) @@ -16381,7 +16381,7 @@ M: Shuah Khan M: Shuah Khan L: linux-usb@vger.kernel.org S: Maintained -F: Documentation/usb/usbip_protocol.txt +F: Documentation/usb/usbip_protocol.rst F: drivers/usb/usbip/ F: tools/usb/usbip/ F: tools/testing/selftests/drivers/usb/usbip/ @@ -16429,7 +16429,7 @@ M: Johan Hovold L: linux-usb@vger.kernel.org T: git git://git.kernel.org/pub/scm/linux/kernel/git/johan/usb-serial.git S: Maintained -F: Documentation/usb/usb-serial.txt +F: Documentation/usb/usb-serial.rst F: drivers/usb/serial/ F: include/linux/usb/serial.h diff --git a/drivers/usb/Kconfig b/drivers/usb/Kconfig index e4b27413f528..94573fb68304 100644 --- a/drivers/usb/Kconfig +++ b/drivers/usb/Kconfig @@ -74,7 +74,7 @@ config USB After choosing your HCD, then select drivers for the USB peripherals you'll be using. You may want to check out the information provided in and especially the links given in - . + . To compile this driver as a module, choose M here: the module will be called usbcore. diff --git a/drivers/usb/class/Kconfig b/drivers/usb/class/Kconfig index 52f3a531a82f..f8a798900093 100644 --- a/drivers/usb/class/Kconfig +++ b/drivers/usb/class/Kconfig @@ -10,7 +10,7 @@ config USB_ACM ---help--- This driver supports USB modems and ISDN adapters which support the Communication Device Class Abstract Control Model interface. - Please read for details. + Please read for details. If your modem only reports "Cls=ff(vend.)" in the descriptors in /sys/kernel/debug/usb/devices, then your modem will not work with this diff --git a/drivers/usb/gadget/Kconfig b/drivers/usb/gadget/Kconfig index ec189d7855a0..02ff850278b1 100644 --- a/drivers/usb/gadget/Kconfig +++ b/drivers/usb/gadget/Kconfig @@ -228,7 +228,7 @@ config USB_CONFIGFS specified simply by creating appropriate directories in configfs. Associating functions with configurations is done by creating appropriate symbolic links. - For more information see Documentation/usb/gadget_configfs.txt. + For more information see Documentation/usb/gadget_configfs.rst. config USB_CONFIGFS_SERIAL bool "Generic serial bulk in/out" @@ -441,7 +441,7 @@ config USB_CONFIGFS_F_HID The HID function driver provides generic emulation of USB Human Interface Devices (HID). - For more information, see Documentation/usb/gadget_hid.txt. + For more information, see Documentation/usb/gadget_hid.rst. config USB_CONFIGFS_F_UVC bool "USB Webcam function" @@ -466,7 +466,7 @@ config USB_CONFIGFS_F_PRINTER receive or send printer data. It can use ioctl calls to the device file to get or set printer status. - For more information, see Documentation/usb/gadget_printer.txt + For more information, see Documentation/usb/gadget_printer.rst which includes sample code for accessing the device file. config USB_CONFIGFS_F_TCM diff --git a/drivers/usb/gadget/function/f_mass_storage.c b/drivers/usb/gadget/function/f_mass_storage.c index 043f97ad8f22..29cc5693e05c 100644 --- a/drivers/usb/gadget/function/f_mass_storage.c +++ b/drivers/usb/gadget/function/f_mass_storage.c @@ -47,7 +47,7 @@ * * For more information about MSF and in particular its module * parameters and sysfs interface read the - * file. + * file. */ /* diff --git a/drivers/usb/gadget/legacy/Kconfig b/drivers/usb/gadget/legacy/Kconfig index 94fc3c462930..69ff7f8c86f5 100644 --- a/drivers/usb/gadget/legacy/Kconfig +++ b/drivers/usb/gadget/legacy/Kconfig @@ -287,7 +287,7 @@ config USB_G_SERIAL Say "y" to link the driver statically, or "m" to build a dynamically linked module called "g_serial". - For more information, see Documentation/usb/gadget_serial.txt + For more information, see Documentation/usb/gadget_serial.rst which includes instructions and a "driver info file" needed to make MS-Windows work with CDC ACM. @@ -321,7 +321,7 @@ config USB_G_PRINTER Say "y" to link the driver statically, or "m" to build a dynamically linked module called "g_printer". - For more information, see Documentation/usb/gadget_printer.txt + For more information, see Documentation/usb/gadget_printer.rst which includes sample code for accessing the device file. if TTY @@ -436,7 +436,7 @@ config USB_G_HID The HID gadget driver provides generic emulation of USB Human Interface Devices (HID). - For more information, see Documentation/usb/gadget_hid.txt which + For more information, see Documentation/usb/gadget_hid.rst which includes sample code for accessing the device files. Say "y" to link the driver statically, or "m" to build a diff --git a/drivers/usb/host/Kconfig b/drivers/usb/host/Kconfig index fb3406ea8592..40b5de597112 100644 --- a/drivers/usb/host/Kconfig +++ b/drivers/usb/host/Kconfig @@ -114,7 +114,7 @@ config USB_EHCI_HCD Controller Driver or UHCI (for Via motherboards) Host Controller Driver too. - You may want to read . + You may want to read . To compile this driver as a module, choose M here: the module will be called ehci-hcd. diff --git a/drivers/usb/misc/Kconfig b/drivers/usb/misc/Kconfig index c97f270338bf..a829cd0ef5f3 100644 --- a/drivers/usb/misc/Kconfig +++ b/drivers/usb/misc/Kconfig @@ -51,7 +51,7 @@ config USB_RIO500 tristate "USB Diamond Rio500 support" help Say Y here if you want to connect a USB Rio500 mp3 player to your - computer's USB port. Please read + computer's USB port. Please read for more information. To compile this driver as a module, choose M here: the diff --git a/drivers/usb/mon/Kconfig b/drivers/usb/mon/Kconfig index 48f1b2dadb24..ffc7cd422874 100644 --- a/drivers/usb/mon/Kconfig +++ b/drivers/usb/mon/Kconfig @@ -8,6 +8,6 @@ config USB_MON help If you select this option, a component which captures the USB traffic between peripheral-specific drivers and HC drivers will be built. - For more information, see . + For more information, see . If unsure, say Y, if allowed, otherwise M. diff --git a/drivers/usb/serial/Kconfig b/drivers/usb/serial/Kconfig index 7d031911d04e..67279c6bce33 100644 --- a/drivers/usb/serial/Kconfig +++ b/drivers/usb/serial/Kconfig @@ -11,7 +11,7 @@ menuconfig USB_SERIAL ports, or acts like a serial device, and you want to connect it to your USB bus. - Please read for more + Please read for more information on the specifics of the different devices that are supported, and on how to use them. @@ -47,7 +47,7 @@ config USB_SERIAL_GENERIC bool "USB Generic Serial Driver" help Say Y here if you want to use the generic USB serial driver. Please - read for more information on + read for more information on using this driver. It is recommended that the "USB Serial converter support" be compiled as a module for this driver to be used properly. @@ -163,7 +163,7 @@ config USB_SERIAL_EMPEG help Say Y here if you want to connect to your Empeg empeg-car Mark I/II mp3 player via USB. The driver uses a single ttyUSB{0,1,2,...} - device node. See for more + device node. See for more tidbits of information. To compile this driver as a module, choose M here: the @@ -199,7 +199,7 @@ config USB_SERIAL_IPAQ Say Y here if you want to connect to your Compaq iPAQ, HP Jornada or any other PDA running Windows CE 3.0 or PocketPC 2002 using a USB cradle/cable. For information on using the driver, - read . + read . To compile this driver as a module, choose M here: the module will be called ipaq. @@ -334,7 +334,7 @@ config USB_SERIAL_KLSI adapter sold by Palm Inc. for use with their Palm III and Palm V series PDAs. - Please read for more + Please read for more information. To compile this driver as a module, choose M here: the diff --git a/drivers/usb/serial/belkin_sa.c b/drivers/usb/serial/belkin_sa.c index c1235d5b9fba..9bb123ab9bc9 100644 --- a/drivers/usb/serial/belkin_sa.c +++ b/drivers/usb/serial/belkin_sa.c @@ -10,7 +10,7 @@ * and associated source files. Please see the usb/serial files for * individual credits and copyrights. * - * See Documentation/usb/usb-serial.txt for more information on using this + * See Documentation/usb/usb-serial.rst for more information on using this * driver * * TODO: diff --git a/drivers/usb/serial/belkin_sa.h b/drivers/usb/serial/belkin_sa.h index 51bc06287603..a13a98d284f2 100644 --- a/drivers/usb/serial/belkin_sa.h +++ b/drivers/usb/serial/belkin_sa.h @@ -9,7 +9,7 @@ * and associated source files. Please see the usb/serial files for * individual credits and copyrights. * - * See Documentation/usb/usb-serial.txt for more information on using this + * See Documentation/usb/usb-serial.rst for more information on using this * driver * * 12-Mar-2001 gkh diff --git a/drivers/usb/serial/cypress_m8.c b/drivers/usb/serial/cypress_m8.c index 72d3ae1ebc64..216edd5826ca 100644 --- a/drivers/usb/serial/cypress_m8.c +++ b/drivers/usb/serial/cypress_m8.c @@ -7,7 +7,7 @@ * Copyright (C) 2003,2004 * Neil Whelchel (koyama@firstlight.net) * - * See Documentation/usb/usb-serial.txt for more information on using this + * See Documentation/usb/usb-serial.rst for more information on using this * driver * * See http://geocities.com/i0xox0i for information on this driver and the diff --git a/drivers/usb/serial/empeg.c b/drivers/usb/serial/empeg.c index d680bec62547..405e835e93dd 100644 --- a/drivers/usb/serial/empeg.c +++ b/drivers/usb/serial/empeg.c @@ -8,7 +8,7 @@ * Copyright (C) 1999 - 2001 * Greg Kroah-Hartman (greg@kroah.com) * - * See Documentation/usb/usb-serial.txt for more information on using this + * See Documentation/usb/usb-serial.rst for more information on using this * driver */ diff --git a/drivers/usb/serial/ftdi_sio.c b/drivers/usb/serial/ftdi_sio.c index 1d8461ae2c34..8b15bbf545d4 100644 --- a/drivers/usb/serial/ftdi_sio.c +++ b/drivers/usb/serial/ftdi_sio.c @@ -10,7 +10,7 @@ * Copyright (C) 2002 * Kuba Ober (kuba@mareimbrium.org) * - * See Documentation/usb/usb-serial.txt for more information on using this + * See Documentation/usb/usb-serial.rst for more information on using this * driver * * See http://ftdi-usb-sio.sourceforge.net for up to date testing info diff --git a/drivers/usb/serial/ir-usb.c b/drivers/usb/serial/ir-usb.c index 7643716b5299..302eb9530859 100644 --- a/drivers/usb/serial/ir-usb.c +++ b/drivers/usb/serial/ir-usb.c @@ -16,7 +16,7 @@ * was written by Roman Weissgaerber , Dag Brattli * , and Jean Tourrilhes * - * See Documentation/usb/usb-serial.txt for more information on using this + * See Documentation/usb/usb-serial.rst for more information on using this * driver */ diff --git a/drivers/usb/serial/keyspan_pda.c b/drivers/usb/serial/keyspan_pda.c index 38d43c4b7ce5..bf988f77d400 100644 --- a/drivers/usb/serial/keyspan_pda.c +++ b/drivers/usb/serial/keyspan_pda.c @@ -6,7 +6,7 @@ * Copyright (C) 1999, 2000 Brian Warner * Copyright (C) 2000 Al Borchers * - * See Documentation/usb/usb-serial.txt for more information on using this + * See Documentation/usb/usb-serial.rst for more information on using this * driver */ diff --git a/drivers/usb/serial/omninet.c b/drivers/usb/serial/omninet.c index e51c9464ea42..5b6e982a9376 100644 --- a/drivers/usb/serial/omninet.c +++ b/drivers/usb/serial/omninet.c @@ -4,7 +4,7 @@ * * Copyright (C) 2013,2017 Johan Hovold * - * See Documentation/usb/usb-serial.txt for more information on using this + * See Documentation/usb/usb-serial.rst for more information on using this * driver * * Please report both successes and troubles to the author at omninet@kroah.com diff --git a/drivers/usb/serial/oti6858.c b/drivers/usb/serial/oti6858.c index 38ae0fc826cc..8151dd7a45e8 100644 --- a/drivers/usb/serial/oti6858.c +++ b/drivers/usb/serial/oti6858.c @@ -22,7 +22,7 @@ * So, THIS CODE CAN DESTROY OTi-6858 AND ANY OTHER DEVICES, THAT ARE * CONNECTED TO IT! * - * See Documentation/usb/usb-serial.txt for more information on using this + * See Documentation/usb/usb-serial.rst for more information on using this * driver * * TODO: diff --git a/drivers/usb/serial/pl2303.c b/drivers/usb/serial/pl2303.c index d7abde14b3cf..9d27b76c5c6e 100644 --- a/drivers/usb/serial/pl2303.c +++ b/drivers/usb/serial/pl2303.c @@ -7,7 +7,7 @@ * * Original driver for 2.2.x by anonymous * - * See Documentation/usb/usb-serial.txt for more information on using this + * See Documentation/usb/usb-serial.rst for more information on using this * driver */ diff --git a/drivers/usb/serial/usb-serial.c b/drivers/usb/serial/usb-serial.c index 676c296103a2..a3179fea38c8 100644 --- a/drivers/usb/serial/usb-serial.c +++ b/drivers/usb/serial/usb-serial.c @@ -10,7 +10,7 @@ * This driver was originally based on the ACM driver by Armin Fuerst (which was * based on a driver by Brad Keryan) * - * See Documentation/usb/usb-serial.txt for more information on using this + * See Documentation/usb/usb-serial.rst for more information on using this * driver */ diff --git a/drivers/usb/serial/visor.c b/drivers/usb/serial/visor.c index 8ddbecc25d89..4412834db21c 100644 --- a/drivers/usb/serial/visor.c +++ b/drivers/usb/serial/visor.c @@ -6,7 +6,7 @@ * Copyright (C) 1999 - 2004 * Greg Kroah-Hartman (greg@kroah.com) * - * See Documentation/usb/usb-serial.txt for more information on using this + * See Documentation/usb/usb-serial.rst for more information on using this * driver * */ diff --git a/drivers/usb/serial/visor.h b/drivers/usb/serial/visor.h index fe290243f1ce..4bd69d047036 100644 --- a/drivers/usb/serial/visor.h +++ b/drivers/usb/serial/visor.h @@ -5,7 +5,7 @@ * Copyright (C) 1999 - 2003 * Greg Kroah-Hartman (greg@kroah.com) * - * See Documentation/usb/usb-serial.txt for more information on using this + * See Documentation/usb/usb-serial.rst for more information on using this * driver. * */ diff --git a/drivers/usb/serial/whiteheat.c b/drivers/usb/serial/whiteheat.c index aefd84f88b59..79314d8c94a4 100644 --- a/drivers/usb/serial/whiteheat.c +++ b/drivers/usb/serial/whiteheat.c @@ -8,7 +8,7 @@ * Copyright (C) 1999 - 2001 * Greg Kroah-Hartman (greg@kroah.com) * - * See Documentation/usb/usb-serial.txt for more information on using this + * See Documentation/usb/usb-serial.rst for more information on using this * driver */ diff --git a/drivers/usb/serial/whiteheat.h b/drivers/usb/serial/whiteheat.h index 72c1b0cf4063..00398149cd8d 100644 --- a/drivers/usb/serial/whiteheat.h +++ b/drivers/usb/serial/whiteheat.h @@ -8,7 +8,7 @@ * Copyright (C) 1999, 2000 * Greg Kroah-Hartman (greg@kroah.com) * - * See Documentation/usb/usb-serial.txt for more information on using this + * See Documentation/usb/usb-serial.rst for more information on using this * driver * */ -- cgit v1.2.3-59-g8ed1b From 51cc0da52e16ef487e3b9f73ad0ba8243684e73d Mon Sep 17 00:00:00 2001 From: Lubomir Rintel Date: Thu, 20 Jun 2019 13:46:36 +0200 Subject: dt-bindings: phy-pxa-usb: add bindings This is the PHY chip for USB OTG on PXA platforms. Signed-off-by: Lubomir Rintel Acked-by: Pavel Machek Signed-off-by: Kishon Vijay Abraham I --- Documentation/devicetree/bindings/phy/phy-pxa-usb.txt | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 Documentation/devicetree/bindings/phy/phy-pxa-usb.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/phy/phy-pxa-usb.txt b/Documentation/devicetree/bindings/phy/phy-pxa-usb.txt new file mode 100644 index 000000000000..93fc09c12954 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/phy-pxa-usb.txt @@ -0,0 +1,18 @@ +Marvell PXA USB PHY +------------------- + +Required properties: +- compatible: one of: "marvell,mmp2-usb-phy", "marvell,pxa910-usb-phy", + "marvell,pxa168-usb-phy", +- #phy-cells: must be 0 + +Example: + usb-phy: usbphy@d4207000 { + compatible = "marvell,mmp2-usb-phy"; + reg = <0xd4207000 0x40>; + #phy-cells = <0>; + status = "okay"; + }; + +This document explains the device tree binding. For general +information about PHY subsystem refer to Documentation/phy.txt -- cgit v1.2.3-59-g8ed1b From 00fcc69d6e52643fc5ecd04ff7e2d560ed3e2ec0 Mon Sep 17 00:00:00 2001 From: Guido Günther Date: Thu, 20 Jun 2019 21:42:36 +0200 Subject: dt-bindings: phy: Add documentation for mixel dphy MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add support for the MIXEL DPHY IP as found on NXP's i.MX8MQ SoCs. Signed-off-by: Guido Günther Reviewed-by: Sam Ravnborg Reviewed-by: Rob Herring Reviewed-by: Fabio Estevam Signed-off-by: Kishon Vijay Abraham I --- .../devicetree/bindings/phy/mixel,mipi-dsi-phy.txt | 29 ++++++++++++++++++++++ 1 file changed, 29 insertions(+) create mode 100644 Documentation/devicetree/bindings/phy/mixel,mipi-dsi-phy.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/phy/mixel,mipi-dsi-phy.txt b/Documentation/devicetree/bindings/phy/mixel,mipi-dsi-phy.txt new file mode 100644 index 000000000000..9b23407233c0 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/mixel,mipi-dsi-phy.txt @@ -0,0 +1,29 @@ +Mixel DSI PHY for i.MX8 + +The Mixel MIPI-DSI PHY IP block is e.g. found on i.MX8 platforms (along the +MIPI-DSI IP from Northwest Logic). It represents the physical layer for the +electrical signals for DSI. + +Required properties: +- compatible: Must be: + - "fsl,imx8mq-mipi-dphy" +- clocks: Must contain an entry for each entry in clock-names. +- clock-names: Must contain the following entries: + - "phy_ref": phandle and specifier referring to the DPHY ref clock +- reg: the register range of the PHY controller +- #phy-cells: number of cells in PHY, as defined in + Documentation/devicetree/bindings/phy/phy-bindings.txt + this must be <0> + +Optional properties: +- power-domains: phandle to power domain + +Example: + dphy: dphy@30a0030 { + compatible = "fsl,imx8mq-mipi-dphy"; + clocks = <&clk IMX8MQ_CLK_DSI_PHY_REF>; + clock-names = "phy_ref"; + reg = <0x30a00300 0x100>; + power-domains = <&pd_mipi0>; + #phy-cells = <0>; + }; -- cgit v1.2.3-59-g8ed1b From 235e6e0a8d5fd1d0285a8d13fbaa3b92112b877a Mon Sep 17 00:00:00 2001 From: Greg Kroah-Hartman Date: Fri, 21 Jun 2019 15:28:35 +0200 Subject: remove Documentation/index.rst.rej It got added accidentally by a previous patch that I had to "hand apply". Reported-by: Stephen Rothwell Signed-off-by: Greg Kroah-Hartman --- Documentation/index.rst.rej | 10 ---------- 1 file changed, 10 deletions(-) delete mode 100644 Documentation/index.rst.rej (limited to 'Documentation') diff --git a/Documentation/index.rst.rej b/Documentation/index.rst.rej deleted file mode 100644 index b1af6eab22f3..000000000000 --- a/Documentation/index.rst.rej +++ /dev/null @@ -1,10 +0,0 @@ ---- Documentation/index.rst -+++ Documentation/index.rst -@@ -103,6 +103,7 @@ needed). - vm/index - bpf/index - PCI/index -+ usb/index - misc-devices/index - - Architecture-specific documentation -- cgit v1.2.3-59-g8ed1b From e8a8b40cc8922b38f91c6562d525f21f312f235c Mon Sep 17 00:00:00 2001 From: Pawel Laszczak Date: Tue, 2 Jul 2019 14:37:57 +0100 Subject: dt-bindings: add binding for USBSS-DRD controller. This patch aim at documenting USB related dt-bindings for the Cadence USBSS-DRD controller. Signed-off-by: Pawel Laszczak Reviewed-by: Rob Herring Signed-off-by: Felipe Balbi --- .../devicetree/bindings/usb/cdns-usb3.txt | 45 ++++++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 Documentation/devicetree/bindings/usb/cdns-usb3.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/usb/cdns-usb3.txt b/Documentation/devicetree/bindings/usb/cdns-usb3.txt new file mode 100644 index 000000000000..b7dc606d37b5 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/cdns-usb3.txt @@ -0,0 +1,45 @@ +Binding for the Cadence USBSS-DRD controller + +Required properties: + - reg: Physical base address and size of the controller's register areas. + Controller has 3 different regions: + - HOST registers area + - DEVICE registers area + - OTG/DRD registers area + - reg-names - register memory area names: + "xhci" - for HOST registers space + "dev" - for DEVICE registers space + "otg" - for OTG/DRD registers space + - compatible: Should contain: "cdns,usb3" + - interrupts: Interrupts used by cdns3 controller: + "host" - interrupt used by XHCI driver. + "peripheral" - interrupt used by device driver + "otg" - interrupt used by DRD/OTG part of driver + +Optional properties: + - maximum-speed : valid arguments are "super-speed", "high-speed" and + "full-speed"; refer to usb/generic.txt + - dr_mode: Should be one of "host", "peripheral" or "otg". + - phys: reference to the USB PHY + - phy-names: from the *Generic PHY* bindings; + Supported names are: + - cdns3,usb2-phy + - cdns3,usb3-phy + + - cdns,on-chip-buff-size : size of memory intended as internal memory for endpoints + buffers expressed in KB + +Example: + usb@f3000000 { + compatible = "cdns,usb3"; + interrupts = , + , + ; + interrupt-names = "host", "peripheral", "otg"; + reg = <0xf3000000 0x10000>, /* memory area for HOST registers */ + <0xf3010000 0x10000>, /* memory area for DEVICE registers */ + <0xf3020000 0x10000>; /* memory area for OTG/DRD registers */ + reg-names = "xhci", "dev", "otg"; + phys = <&usb2_phy>, <&usb3_phy>; + phy-names = "cdns3,usb2-phy", "cnds3,usb3-phy"; + }; -- cgit v1.2.3-59-g8ed1b From 8cf8bde284b7a25229cbf119cbf8be8149132a5c Mon Sep 17 00:00:00 2001 From: Peter Chen Date: Mon, 24 Jun 2019 10:02:51 +0800 Subject: doc: dt-binding: mxs-usb-phy: add compatible for 7ulp Add compatible for 7ulp USB PHY. Reviewed-by: Rob Herring Signed-off-by: Peter Chen Signed-off-by: Felipe Balbi --- Documentation/devicetree/bindings/phy/mxs-usb-phy.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/phy/mxs-usb-phy.txt b/Documentation/devicetree/bindings/phy/mxs-usb-phy.txt index 6ac98b3b5f57..c9f5c0caf8a9 100644 --- a/Documentation/devicetree/bindings/phy/mxs-usb-phy.txt +++ b/Documentation/devicetree/bindings/phy/mxs-usb-phy.txt @@ -7,6 +7,7 @@ Required properties: * "fsl,imx6sl-usbphy" for imx6sl * "fsl,vf610-usbphy" for Vybrid vf610 * "fsl,imx6sx-usbphy" for imx6sx + * "fsl,imx7ulp-usbphy" for imx7ulp "fsl,imx23-usbphy" is still a fallback for other strings - reg: Should contain registers location and length - interrupts: Should contain phy interrupt @@ -23,7 +24,7 @@ Optional properties: the 17.78mA TX reference current. Default: 100 Example: -usbphy1: usbphy@20c9000 { +usbphy1: usb-phy@20c9000 { compatible = "fsl,imx6q-usbphy", "fsl,imx23-usbphy"; reg = <0x020c9000 0x1000>; interrupts = <0 44 0x04>; -- cgit v1.2.3-59-g8ed1b From 65d71f0095f611eb090bb9c1cca086a8967936e5 Mon Sep 17 00:00:00 2001 From: Greg Kroah-Hartman Date: Thu, 4 Jul 2019 13:02:18 +0200 Subject: Revert "dt-bindings: add binding for USBSS-DRD controller." This reverts commit e8a8b40cc8922b38f91c6562d525f21f312f235c. It's broken. Reported-by: Stephen Rothwell Cc: Felipe Balbi Cc: Pawel Laszczak Signed-off-by: Greg Kroah-Hartman --- .../devicetree/bindings/usb/cdns-usb3.txt | 45 ---------------------- 1 file changed, 45 deletions(-) delete mode 100644 Documentation/devicetree/bindings/usb/cdns-usb3.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/usb/cdns-usb3.txt b/Documentation/devicetree/bindings/usb/cdns-usb3.txt deleted file mode 100644 index b7dc606d37b5..000000000000 --- a/Documentation/devicetree/bindings/usb/cdns-usb3.txt +++ /dev/null @@ -1,45 +0,0 @@ -Binding for the Cadence USBSS-DRD controller - -Required properties: - - reg: Physical base address and size of the controller's register areas. - Controller has 3 different regions: - - HOST registers area - - DEVICE registers area - - OTG/DRD registers area - - reg-names - register memory area names: - "xhci" - for HOST registers space - "dev" - for DEVICE registers space - "otg" - for OTG/DRD registers space - - compatible: Should contain: "cdns,usb3" - - interrupts: Interrupts used by cdns3 controller: - "host" - interrupt used by XHCI driver. - "peripheral" - interrupt used by device driver - "otg" - interrupt used by DRD/OTG part of driver - -Optional properties: - - maximum-speed : valid arguments are "super-speed", "high-speed" and - "full-speed"; refer to usb/generic.txt - - dr_mode: Should be one of "host", "peripheral" or "otg". - - phys: reference to the USB PHY - - phy-names: from the *Generic PHY* bindings; - Supported names are: - - cdns3,usb2-phy - - cdns3,usb3-phy - - - cdns,on-chip-buff-size : size of memory intended as internal memory for endpoints - buffers expressed in KB - -Example: - usb@f3000000 { - compatible = "cdns,usb3"; - interrupts = , - , - ; - interrupt-names = "host", "peripheral", "otg"; - reg = <0xf3000000 0x10000>, /* memory area for HOST registers */ - <0xf3010000 0x10000>, /* memory area for DEVICE registers */ - <0xf3020000 0x10000>; /* memory area for OTG/DRD registers */ - reg-names = "xhci", "dev", "otg"; - phys = <&usb2_phy>, <&usb3_phy>; - phy-names = "cdns3,usb2-phy", "cnds3,usb3-phy"; - }; -- cgit v1.2.3-59-g8ed1b