diff options
Diffstat (limited to 'Documentation')
14 files changed, 358 insertions, 252 deletions
diff --git a/Documentation/ABI/testing/sysfs-bus-thunderbolt b/Documentation/ABI/testing/sysfs-bus-thunderbolt index d7f09d011b6d..c41c68f64693 100644 --- a/Documentation/ABI/testing/sysfs-bus-thunderbolt +++ b/Documentation/ABI/testing/sysfs-bus-thunderbolt @@ -1,31 +1,3 @@ -What: /sys/bus/thunderbolt/devices/<xdomain>/rx_speed -Date: Feb 2021 -KernelVersion: 5.11 -Contact: Isaac Hazan <isaac.hazan@intel.com> -Description: This attribute reports the XDomain RX speed per lane. - All RX lanes run at the same speed. - -What: /sys/bus/thunderbolt/devices/<xdomain>/rx_lanes -Date: Feb 2021 -KernelVersion: 5.11 -Contact: Isaac Hazan <isaac.hazan@intel.com> -Description: This attribute reports the number of RX lanes the XDomain - is using simultaneously through its upstream port. - -What: /sys/bus/thunderbolt/devices/<xdomain>/tx_speed -Date: Feb 2021 -KernelVersion: 5.11 -Contact: Isaac Hazan <isaac.hazan@intel.com> -Description: This attribute reports the XDomain TX speed per lane. - All TX lanes run at the same speed. - -What: /sys/bus/thunderbolt/devices/<xdomain>/tx_lanes -Date: Feb 2021 -KernelVersion: 5.11 -Contact: Isaac Hazan <isaac.hazan@intel.com> -Description: This attribute reports number of TX lanes the XDomain - is using simultaneously through its upstream port. - What: /sys/bus/thunderbolt/devices/.../domainX/boot_acl Date: Jun 2018 KernelVersion: 4.17 @@ -162,6 +134,13 @@ Contact: thunderbolt-software@lists.01.org Description: This attribute contains name of this device extracted from the device DROM. +What: /sys/bus/thunderbolt/devices/.../maxhopid +Date: Jul 2021 +KernelVersion: 5.13 +Contact: Mika Westerberg <mika.westerberg@linux.intel.com> +Description: Only set for XDomains. The maximum HopID the other host + supports as its input HopID. + What: /sys/bus/thunderbolt/devices/.../rx_speed Date: Jan 2020 KernelVersion: 5.5 diff --git a/Documentation/devicetree/bindings/connector/usb-connector.yaml b/Documentation/devicetree/bindings/connector/usb-connector.yaml index b6daedd62516..32509b98142e 100644 --- a/Documentation/devicetree/bindings/connector/usb-connector.yaml +++ b/Documentation/devicetree/bindings/connector/usb-connector.yaml @@ -197,6 +197,16 @@ properties: $ref: /schemas/types.yaml#/definitions/uint32 enum: [1, 2, 3] + slow-charger-loop: + description: Allows PMIC charger loops which are slow(i.e. cannot meet the 15ms deadline) to + still comply to pSnkStby i.e Maximum power that can be consumed by sink while in Sink Standby + state as defined in 7.4.2 Sink Electrical Parameters of USB Power Delivery Specification + Revision 3.0, Version 1.2. When the property is set, the port requests pSnkStby(2.5W - + 5V@500mA) upon entering SNK_DISCOVERY(instead of 3A or the 1.5A, Rp current advertised, during + SNK_DISCOVERY) and the actual currrent limit after reception of PS_Ready for PD link or during + SNK_READY for non-pd link. + type: boolean + required: - compatible diff --git a/Documentation/devicetree/bindings/usb/dwc3-xilinx.txt b/Documentation/devicetree/bindings/usb/dwc3-xilinx.txt index a668f43bedf5..04813a46e5d0 100644 --- a/Documentation/devicetree/bindings/usb/dwc3-xilinx.txt +++ b/Documentation/devicetree/bindings/usb/dwc3-xilinx.txt @@ -1,32 +1,56 @@ Xilinx SuperSpeed DWC3 USB SoC controller Required properties: -- compatible: Should contain "xlnx,zynqmp-dwc3" +- compatible: May contain "xlnx,zynqmp-dwc3" or "xlnx,versal-dwc3" +- reg: Base address and length of the register control block - clocks: A list of phandles for the clocks listed in clock-names - clock-names: Should contain the following: "bus_clk" Master/Core clock, have to be >= 125 MHz for SS operation and >= 60MHz for HS operation "ref_clk" Clock source to core during PHY power down +- resets: A list of phandles for resets listed in reset-names +- reset-names: + "usb_crst" USB core reset + "usb_hibrst" USB hibernation reset + "usb_apbrst" USB APB reset Required child node: A child node must exist to represent the core DWC3 IP block. The name of the node is not important. The content of the node is defined in dwc3.txt. +Optional properties for snps,dwc3: +- dma-coherent: Enable this flag if CCI is enabled in design. Adding this + flag configures Global SoC bus Configuration Register and + Xilinx USB 3.0 IP - USB coherency register to enable CCI. +- interrupt-names: Should contain the following: + "dwc_usb3" USB gadget mode interrupts + "otg" USB OTG mode interrupts + "hiber" USB hibernation interrupts + Example device node: usb@0 { #address-cells = <0x2>; #size-cells = <0x1>; compatible = "xlnx,zynqmp-dwc3"; + reg = <0x0 0xff9d0000 0x0 0x100>; clock-names = "bus_clk", "ref_clk"; clocks = <&clk125>, <&clk125>; + resets = <&zynqmp_reset ZYNQMP_RESET_USB1_CORERESET>, + <&zynqmp_reset ZYNQMP_RESET_USB1_HIBERRESET>, + <&zynqmp_reset ZYNQMP_RESET_USB1_APB>; + reset-names = "usb_crst", "usb_hibrst", "usb_apbrst"; ranges; dwc3@fe200000 { compatible = "snps,dwc3"; reg = <0x0 0xfe200000 0x40000>; - interrupts = <0x0 0x41 0x4>; + interrupt-names = "dwc_usb3", "otg", "hiber"; + interrupts = <0 65 4>, <0 69 4>, <0 75 4>; + phys = <&psgtr 2 PHY_TYPE_USB3 0 2>; + phy-names = "usb3-phy"; dr_mode = "host"; + dma-coherent; }; }; diff --git a/Documentation/devicetree/bindings/usb/fsl,imx8mp-dwc3.yaml b/Documentation/devicetree/bindings/usb/fsl,imx8mp-dwc3.yaml index cb4c6f6d3a33..974032b1fda0 100644 --- a/Documentation/devicetree/bindings/usb/fsl,imx8mp-dwc3.yaml +++ b/Documentation/devicetree/bindings/usb/fsl,imx8mp-dwc3.yaml @@ -52,11 +52,8 @@ properties: # Required child node: patternProperties: - "^dwc3@[0-9a-f]+$": - type: object - description: - A child node must exist to represent the core DWC3 IP block - The content of the node is defined in dwc3.txt. + "^usb@[0-9a-f]+$": + $ref: snps,dwc3.yaml# required: - compatible @@ -87,7 +84,7 @@ examples: dma-ranges = <0x40000000 0x40000000 0xc0000000>; ranges; - dwc3@38100000 { + usb@38100000 { compatible = "snps,dwc3"; reg = <0x38100000 0x10000>; clocks = <&clk IMX8MP_CLK_HSIO_AXI>, diff --git a/Documentation/devicetree/bindings/usb/generic-ehci.yaml b/Documentation/devicetree/bindings/usb/generic-ehci.yaml index cf83f2d9afac..8089dc956ba3 100644 --- a/Documentation/devicetree/bindings/usb/generic-ehci.yaml +++ b/Documentation/devicetree/bindings/usb/generic-ehci.yaml @@ -122,6 +122,12 @@ properties: description: Set this flag to force EHCI reset after resume. + spurious-oc: + $ref: /schemas/types.yaml#/definitions/flag + description: + Set this flag to indicate that the hardware sometimes turns on + the OC bit when an over-current isn't actually present. + companion: $ref: /schemas/types.yaml#/definitions/phandle description: diff --git a/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.yaml b/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.yaml index 14f40efb3b22..240882b12565 100644 --- a/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.yaml +++ b/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.yaml @@ -30,6 +30,7 @@ properties: - mediatek,mt7629-xhci - mediatek,mt8173-xhci - mediatek,mt8183-xhci + - mediatek,mt8192-xhci - const: mediatek,mtk-xhci reg: @@ -45,7 +46,18 @@ properties: - const: ippc # optional, only needed for case 1. interrupts: - maxItems: 1 + description: + use "interrupts-extended" when the interrupts are connected to the + separate interrupt controllers + minItems: 1 + items: + - description: xHCI host controller interrupt + - description: optional, wakeup interrupt used to support runtime PM + + interrupt-names: + items: + - const: host + - const: wakeup power-domains: description: A phandle to USB power domain node to control USB's MTCMOS @@ -99,9 +111,9 @@ properties: vbus-supply: description: Regulator of USB VBUS5v - usb3-lpm-capable: - description: supports USB3.0 LPM - type: boolean + usb3-lpm-capable: true + + usb2-lpm-disable: true imod-interval-ns: description: @@ -127,10 +139,13 @@ properties: - description: The second cell represents the register base address of the glue layer in syscon - - description: + - description: | The third cell represents the hardware version of the glue layer, - 1 is used by mt8173 etc, 2 is used by mt2712 etc - enum: [1, 2] + 1 - used by mt8173 etc, revision 1 without following IPM rule; + 2 - used by mt2712 etc, revision 2 following IPM rule; + 101 - used by mt8183, specific 1.01; + 102 - used by mt8192, specific 1.02; + enum: [1, 2, 101, 102] mediatek,u3p-dis-msk: $ref: /schemas/types.yaml#/definitions/uint32 diff --git a/Documentation/devicetree/bindings/usb/mediatek,mtu3.yaml b/Documentation/devicetree/bindings/usb/mediatek,mtu3.yaml index f5c04b9d2de9..dbc7876e0a0b 100644 --- a/Documentation/devicetree/bindings/usb/mediatek,mtu3.yaml +++ b/Documentation/devicetree/bindings/usb/mediatek,mtu3.yaml @@ -24,6 +24,7 @@ properties: - mediatek,mt2712-mtu3 - mediatek,mt8173-mtu3 - mediatek,mt8183-mtu3 + - mediatek,mt8192-mtu3 - const: mediatek,mtu3 reg: @@ -126,7 +127,7 @@ properties: Any connector to the data bus of this controller should be modelled using the OF graph bindings specified, if the "usb-role-switch" property is used. See graph.txt - type: object + $ref: /schemas/graph.yaml#/properties/port enable-manual-drd: $ref: /schemas/types.yaml#/definitions/flag @@ -152,10 +153,13 @@ properties: - description: The second cell represents the register base address of the glue layer in syscon - - description: + - description: | The third cell represents the hardware version of the glue layer, - 1 is used by mt8173 etc, 2 is used by mt2712 etc - enum: [1, 2] + 1 - used by mt8173 etc, revision 1 without following IPM rule; + 2 - used by mt2712 etc, revision 2 with following IPM rule; + 101 - used by mt8183, specific 1.01; + 102 - used by mt8192, specific 1.02; + enum: [1, 2, 101, 102] mediatek,u3p-dis-msk: $ref: /schemas/types.yaml#/definitions/uint32 diff --git a/Documentation/devicetree/bindings/usb/qcom,dwc3.yaml b/Documentation/devicetree/bindings/usb/qcom,dwc3.yaml index c3cbd1fa9944..413299b5fe2b 100644 --- a/Documentation/devicetree/bindings/usb/qcom,dwc3.yaml +++ b/Documentation/devicetree/bindings/usb/qcom,dwc3.yaml @@ -16,6 +16,7 @@ properties: - qcom,msm8996-dwc3 - qcom,msm8998-dwc3 - qcom,sc7180-dwc3 + - qcom,sc7280-dwc3 - qcom,sdm845-dwc3 - qcom,sdx55-dwc3 - qcom,sm8150-dwc3 diff --git a/Documentation/devicetree/bindings/usb/snps,dwc3.yaml b/Documentation/devicetree/bindings/usb/snps,dwc3.yaml index 2247da77eac1..41416fbd92aa 100644 --- a/Documentation/devicetree/bindings/usb/snps,dwc3.yaml +++ b/Documentation/devicetree/bindings/usb/snps,dwc3.yaml @@ -87,13 +87,19 @@ properties: minItems: 1 snps,usb2-lpm-disable: - description: Indicate if we don't want to enable USB2 HW LPM + description: Indicate if we don't want to enable USB2 HW LPM for host + mode. type: boolean snps,usb3_lpm_capable: description: Determines if platform is USB3 LPM capable type: boolean + snps,usb2-gadget-lpm-disable: + description: Indicate if we don't want to enable USB2 HW LPM for gadget + mode. + type: boolean + snps,dis-start-transfer-quirk: description: When set, disable isoc START TRANSFER command failure SW work-around diff --git a/Documentation/devicetree/bindings/usb/usb-device.yaml b/Documentation/devicetree/bindings/usb/usb-device.yaml index d4c99809ee9a..b77960a7a37b 100644 --- a/Documentation/devicetree/bindings/usb/usb-device.yaml +++ b/Documentation/devicetree/bindings/usb/usb-device.yaml @@ -82,9 +82,9 @@ required: additionalProperties: true examples: - #hub connected to port 1 - #device connected to port 2 - #device connected to port 3 + # hub connected to port 1 + # device connected to port 2 + # device connected to port 3 # interface 0 of configuration 1 # interface 0 of configuration 2 - | diff --git a/Documentation/devicetree/bindings/usb/usb-nop-xceiv.txt b/Documentation/devicetree/bindings/usb/usb-nop-xceiv.txt deleted file mode 100644 index 4dc6a8ee3071..000000000000 --- a/Documentation/devicetree/bindings/usb/usb-nop-xceiv.txt +++ /dev/null @@ -1,43 +0,0 @@ -USB NOP PHY - -Required properties: -- compatible: should be usb-nop-xceiv -- #phy-cells: Must be 0 - -Optional properties: -- clocks: phandle to the PHY clock. Use as per Documentation/devicetree - /bindings/clock/clock-bindings.txt - This property is required if clock-frequency is specified. - -- clock-names: Should be "main_clk" - -- clock-frequency: the clock frequency (in Hz) that the PHY clock must - be configured to. - -- vcc-supply: phandle to the regulator that provides power to the PHY. - -- reset-gpios: Should specify the GPIO for reset. - -- vbus-detect-gpio: should specify the GPIO detecting a VBus insertion - (see Documentation/devicetree/bindings/gpio/gpio.txt) -- vbus-regulator : should specifiy the regulator supplying current drawn from - the VBus line (see Documentation/devicetree/bindings/regulator/regulator.txt). - -Example: - - hsusb1_phy { - compatible = "usb-nop-xceiv"; - clock-frequency = <19200000>; - clocks = <&osc 0>; - clock-names = "main_clk"; - vcc-supply = <&hsusb1_vcc_regulator>; - reset-gpios = <&gpio1 7 GPIO_ACTIVE_LOW>; - vbus-detect-gpio = <&gpio2 13 GPIO_ACTIVE_HIGH>; - vbus-regulator = <&vbus_regulator>; - #phy-cells = <0>; - }; - -hsusb1_phy is a NOP USB PHY device that gets its clock from an oscillator -and expects that clock to be configured to 19.2MHz by the NOP PHY driver. -hsusb1_vcc_regulator provides power to the PHY and GPIO 7 controls RESET. -GPIO 13 detects VBus insertion, and accordingly notifies the vbus-regulator. diff --git a/Documentation/devicetree/bindings/usb/usb-nop-xceiv.yaml b/Documentation/devicetree/bindings/usb/usb-nop-xceiv.yaml new file mode 100644 index 000000000000..2824c17285ee --- /dev/null +++ b/Documentation/devicetree/bindings/usb/usb-nop-xceiv.yaml @@ -0,0 +1,64 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/usb/usb-nop-xceiv.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: USB NOP PHY + +maintainers: + - Rob Herring <robh@kernel.org> + +properties: + compatible: + const: usb-nop-xceiv + + clocks: + maxItems: 1 + + clock-names: + const: main_clk + + clock-frequency: true + + '#phy-cells': + const: 0 + + vcc-supply: + description: phandle to the regulator that provides power to the PHY. + + reset-gpios: + maxItems: 1 + + vbus-detect-gpio: + description: Should specify the GPIO detecting a VBus insertion + maxItems: 1 + + vbus-regulator: + description: Should specifiy the regulator supplying current drawn from + the VBus line. + $ref: /schemas/types.yaml#/definitions/phandle + +required: + - compatible + - '#phy-cells' + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + hsusb1_phy { + compatible = "usb-nop-xceiv"; + clock-frequency = <19200000>; + clocks = <&osc 0>; + clock-names = "main_clk"; + vcc-supply = <&hsusb1_vcc_regulator>; + reset-gpios = <&gpio1 7 GPIO_ACTIVE_LOW>; + vbus-detect-gpio = <&gpio2 13 GPIO_ACTIVE_HIGH>; + vbus-regulator = <&vbus_regulator>; + #phy-cells = <0>; + }; + +... diff --git a/Documentation/driver-api/usb/usb.rst b/Documentation/driver-api/usb/usb.rst index 078e981e2b16..543e70434da2 100644 --- a/Documentation/driver-api/usb/usb.rst +++ b/Documentation/driver-api/usb/usb.rst @@ -109,15 +109,16 @@ well as to make sure they aren't relying on some HCD-specific behavior. USB-Standard Types ================== -In ``<linux/usb/ch9.h>`` you will find the USB data types defined in -chapter 9 of the USB specification. These data types are used throughout -USB, and in APIs including this host side API, gadget APIs, usb character -devices and debugfs interfaces. +In ``drivers/usb/common/common.c`` and ``drivers/usb/common/debug.c`` you +will find the USB data types defined in chapter 9 of the USB specification. +These data types are used throughout USB, and in APIs including this host +side API, gadget APIs, usb character devices and debugfs interfaces. -.. kernel-doc:: include/linux/usb/ch9.h - :internal: +.. kernel-doc:: drivers/usb/common/common.c + :export: -.. _usb_header: +.. kernel-doc:: drivers/usb/common/debug.c + :export: Host-Side Data Types and Macros =============================== diff --git a/Documentation/usb/usbip_protocol.rst b/Documentation/usb/usbip_protocol.rst index 988c832166cd..0b8541fda4d8 100644 --- a/Documentation/usb/usbip_protocol.rst +++ b/Documentation/usb/usbip_protocol.rst @@ -2,15 +2,15 @@ USB/IP protocol =============== -PRELIMINARY DRAFT, MAY CONTAIN MISTAKES! -28 Jun 2011 +Architecture +============ 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 devices and the clients import 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 +client opens a TCP/IP connection to 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 @@ -30,7 +30,7 @@ TCP/IP connection is closed. | | 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 +of them. First the client opens a TCP/IP connection to 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 @@ -84,17 +84,61 @@ server may be USBIP_RET_SUBMIT and USBIP_RET_UNLINK respectively. | <---------------------------------------------- | | . | | : | + +For UNLINK, note that after a successful USBIP_RET_UNLINK, the unlinked URB +submission would not have a corresponding USBIP_RET_SUBMIT (this is explained in +function stub_recv_cmd_unlink of drivers/usb/usbip/stub_rx.c). + +:: + + virtual host controller usb host + "client" "server" + (imports USB devices) (exports USB devices) + | | + | USBIP_CMD_SUBMIT(seqnum = p) | + | ----------------------------------------------> | | | | USBIP_CMD_UNLINK | + | (seqnum = p+1, unlink_seqnum = p) | | ----------------------------------------------> | | | | USBIP_RET_UNLINK | + | (seqnum = p+1, status = -ECONNRESET) | + | <---------------------------------------------- | + | | + | Note: No USBIP_RET_SUBMIT(seqnum = p) | + | <--X---X---X---X---X---X---X---X---X---X---X--- | + | . | + | : | + | | + | USBIP_CMD_SUBMIT(seqnum = q) | + | ----------------------------------------------> | + | | + | USBIP_RET_SUBMIT(seqnum = q) | + | <---------------------------------------------- | + | | + | USBIP_CMD_UNLINK | + | (seqnum = q+1, unlink_seqnum = q) | + | ----------------------------------------------> | + | | + | USBIP_RET_UNLINK | + | (seqnum = q+1, status = 0) | | <---------------------------------------------- | | | The fields are in network (big endian) byte order meaning that the most significant byte (MSB) is stored at the lowest address. +Protocol Version +================ + +The documented USBIP version is v1.1.1. The binary representation of this +version in message headers is 0x0111. + +This is defined in tools/usb/usbip/configure.ac + +Message Format +============== OP_REQ_DEVLIST: Retrieve the list of exported USB devices. @@ -102,7 +146,7 @@ OP_REQ_DEVLIST: +-----------+--------+------------+---------------------------------------------------+ | Offset | Length | Value | Description | +===========+========+============+===================================================+ -| 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0 | +| 0 | 2 | | USBIP version | +-----------+--------+------------+---------------------------------------------------+ | 2 | 2 | 0x8005 | Command code: Retrieve the list of exported USB | | | | | devices. | @@ -116,7 +160,7 @@ OP_REP_DEVLIST: +-----------+--------+------------+---------------------------------------------------+ | Offset | Length | Value | Description | +===========+========+============+===================================================+ -| 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0.| +| 0 | 2 | | USBIP version | +-----------+--------+------------+---------------------------------------------------+ | 2 | 2 | 0x0005 | Reply code: The list of exported USB devices. | +-----------+--------+------------+---------------------------------------------------+ @@ -165,8 +209,8 @@ OP_REP_DEVLIST: | 0x143 | 1 | | bNumInterfaces | +-----------+--------+------------+---------------------------------------------------+ | 0x144 | | m_0 | From now on each interface is described, all | -| | | | together bNumInterfaces times, with the | -| | | | the following 4 fields: | +| | | | together bNumInterfaces times, with the following | +| | | | 4 fields: | +-----------+--------+------------+---------------------------------------------------+ | | 1 | | bInterfaceClass | +-----------+--------+------------+---------------------------------------------------+ @@ -177,7 +221,7 @@ OP_REP_DEVLIST: | 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. | +| i*0x138 + | | | with the path field. | | m_(i-1)*4 | | | | +-----------+--------+------------+---------------------------------------------------+ @@ -187,7 +231,7 @@ OP_REQ_IMPORT: +-----------+--------+------------+---------------------------------------------------+ | Offset | Length | Value | Description | +===========+========+============+===================================================+ -| 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0 | +| 0 | 2 | | USBIP version | +-----------+--------+------------+---------------------------------------------------+ | 2 | 2 | 0x8003 | Command code: import a remote USB device. | +-----------+--------+------------+---------------------------------------------------+ @@ -206,7 +250,7 @@ OP_REP_IMPORT: +-----------+--------+------------+---------------------------------------------------+ | Offset | Length | Value | Description | +===========+========+============+===================================================+ -| 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0 | +| 0 | 2 | | USBIP version | +-----------+--------+------------+---------------------------------------------------+ | 2 | 2 | 0x0003 | Reply code: Reply to import. | +-----------+--------+------------+---------------------------------------------------+ @@ -254,158 +298,156 @@ OP_REP_IMPORT: | 0x13E | 1 | | bNumInterfaces | +-----------+--------+------------+---------------------------------------------------+ -USBIP_CMD_SUBMIT: - Submit an URB +The following four commands have a common basic header called +'usbip_header_basic', and their headers, called 'usbip_header' (before +transfer_buffer payload), have the same length, therefore paddings are needed. -+-----------+--------+------------+---------------------------------------------------+ -| 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. | -+-----------+--------+------------+---------------------------------------------------+ +usbip_header_basic: ++-----------+--------+---------------------------------------------------+ +| Offset | Length | Description | ++===========+========+===================================================+ +| 0 | 4 | command | ++-----------+--------+---------------------------------------------------+ +| 4 | 4 | seqnum: sequential number that identifies requests| +| | | and corresponding responses; | +| | | incremented per connection | ++-----------+--------+---------------------------------------------------+ +| 8 | 4 | devid: specifies a remote USB device uniquely | +| | | instead of busnum and devnum; | +| | | for client (request), this value is | +| | | ((busnum << 16) | devnum); | +| | | for server (response), this shall be set to 0 | ++-----------+--------+---------------------------------------------------+ +| 0xC | 4 | direction: | +| | | | +| | | - 0: USBIP_DIR_OUT | +| | | - 1: USBIP_DIR_IN | +| | | | +| | | only used by client, for server this shall be 0 | ++-----------+--------+---------------------------------------------------+ +| 0x10 | 4 | ep: endpoint number | +| | | only used by client, for server this shall be 0; | +| | | for UNLINK, this shall be 0 | ++-----------+--------+---------------------------------------------------+ - +-------------------------+------------+---------+-----------+----------+-------------+ - | 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_CMD_SUBMIT: + Submit an URB ++-----------+--------+---------------------------------------------------+ +| Offset | Length | Description | ++===========+========+===================================================+ +| 0 | 20 | usbip_header_basic, 'command' shall be 0x00000001 | ++-----------+--------+---------------------------------------------------+ +| 0x14 | 4 | transfer_flags: possible values depend on the | +| | | URB transfer_flags (refer to URB doc in | +| | | Documentation/driver-api/usb/URB.rst) | +| | | but with URB_NO_TRANSFER_DMA_MAP masked. Refer to | +| | | function usbip_pack_cmd_submit and function | +| | | tweak_transfer_flags in drivers/usb/usbip/ | +| | | usbip_common.c. The following fields may also ref | +| | | to function usbip_pack_cmd_submit and URB doc | ++-----------+--------+---------------------------------------------------+ +| 0x18 | 4 | transfer_buffer_length: | +| | | use URB transfer_buffer_length | ++-----------+--------+---------------------------------------------------+ +| 0x1C | 4 | start_frame: use URB start_frame; | +| | | initial frame for ISO transfer; | +| | | shall be set to 0 if not ISO transfer | ++-----------+--------+---------------------------------------------------+ +| 0x20 | 4 | number_of_packets: number of ISO packets; | +| | | shall be set to 0xffffffff if not ISO transfer | ++-----------+--------+---------------------------------------------------+ +| 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 | n | transfer_buffer. | +| | | If direction is USBIP_DIR_OUT then n equals | +| | | transfer_buffer_length; otherwise n equals 0. | +| | | For ISO transfers the padding between each ISO | +| | | packets is not transmitted. | ++-----------+--------+---------------------------------------------------+ +| 0x30+n | m | iso_packet_descriptor | ++-----------+--------+---------------------------------------------------+ 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. | -+-----------+--------+------------+---------------------------------------------------+ ++-----------+--------+---------------------------------------------------+ +| Offset | Length | Description | ++===========+========+===================================================+ +| 0 | 20 | usbip_header_basic, 'command' shall be 0x00000003 | ++-----------+--------+---------------------------------------------------+ +| 0x14 | 4 | status: zero for successful URB transaction, | +| | | otherwise some kind of error happened. | ++-----------+--------+---------------------------------------------------+ +| 0x18 | 4 | actual_length: number of URB data bytes; | +| | | use URB actual_length | ++-----------+--------+---------------------------------------------------+ +| 0x1C | 4 | start_frame: use URB start_frame; | +| | | initial frame for ISO transfer; | +| | | shall be set to 0 if not ISO transfer | ++-----------+--------+---------------------------------------------------+ +| 0x20 | 4 | number_of_packets: number of ISO packets; | +| | | shall be set to 0xffffffff if not ISO transfer | ++-----------+--------+---------------------------------------------------+ +| 0x24 | 4 | error_count | ++-----------+--------+---------------------------------------------------+ +| 0x28 | 8 | padding, shall be set to 0 | ++-----------+--------+---------------------------------------------------+ +| 0x30 | n | transfer_buffer. | +| | | If direction is USBIP_DIR_IN then n equals | +| | | actual_length; otherwise n equals 0. | +| | | For ISO transfers the padding between each ISO | +| | | packets is not transmitted. | ++-----------+--------+---------------------------------------------------+ +| 0x30+n | m | iso_packet_descriptor | ++-----------+--------+---------------------------------------------------+ 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. | -+-----------+--------+------------+---------------------------------------------------+ ++-----------+--------+---------------------------------------------------+ +| Offset | Length | Description | ++===========+========+===================================================+ +| 0 | 20 | usbip_header_basic, 'command' shall be 0x00000002 | ++-----------+--------+---------------------------------------------------+ +| 0x14 | 4 | unlink_seqnum, of the SUBMIT request to unlink | ++-----------+--------+---------------------------------------------------+ +| 0x18 | 24 | padding, shall be set to 0 | ++-----------+--------+---------------------------------------------------+ 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. | -+-----------+--------+------------+---------------------------------------------------+ ++-----------+--------+---------------------------------------------------+ +| Offset | Length | Description | ++===========+========+===================================================+ +| 0 | 20 | usbip_header_basic, 'command' shall be 0x00000004 | ++-----------+--------+---------------------------------------------------+ +| 0x14 | 4 | status: This is similar to the status of | +| | | USBIP_RET_SUBMIT (share the same memory offset). | +| | | When UNLINK is successful, status is -ECONNRESET; | +| | | when USBIP_CMD_UNLINK is after USBIP_RET_SUBMIT | +| | | status is 0 | ++-----------+--------+---------------------------------------------------+ +| 0x18 | 24 | padding, shall be set to 0 | ++-----------+--------+---------------------------------------------------+ + +EXAMPLE +======= + + The following data is captured from wire with Human Interface Devices (HID) + payload + +:: + + CmdIntrIN: 00000001 00000d05 0001000f 00000001 00000001 00000200 00000040 ffffffff 00000000 00000004 00000000 00000000 + CmdIntrOUT: 00000001 00000d06 0001000f 00000000 00000001 00000000 00000040 ffffffff 00000000 00000004 00000000 00000000 + ffffffff860008a784ce5ae212376300000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 + RetIntrOut: 00000003 00000d06 00000000 00000000 00000000 00000000 00000040 ffffffff 00000000 00000000 00000000 00000000 + RetIntrIn: 00000003 00000d05 00000000 00000000 00000000 00000000 00000040 ffffffff 00000000 00000000 00000000 00000000 + ffffffff860011a784ce5ae2123763612891b1020100000400000000000000000000000000000000000000000000000000000000000000000000000000000000 |