Documentation/usb/gadget-testing.txt

   1 This file summarizes information on basic testing of USB functions
   2 provided by gadgets.
   3
   4 1. ACM function
   5 2. ECM function
   6 3. ECM subset function
   7 4. EEM function
   8 5. FFS function
   9 6. HID function
  10
  11
  12 1. ACM function
  13 ===============
  14
  15 The function is provided by usb_f_acm.ko module.
  16
  17 Function-specific configfs interface
  18 ------------------------------------
  19
  20 The function name to use when creating the function directory is "acm".
  21 The ACM function provides just one attribute in its function directory:
  22
  23         port_num
  24
  25 The attribute is read-only.
  26
  27 There can be at most 4 ACM/generic serial/OBEX ports in the system.
  28
  29
  30 Testing the ACM function
  31 ------------------------
  32
  33 On the host: cat > /dev/ttyACM<X>
  34 On the device : cat /dev/ttyGS<Y>
  35
  36 then the other way round
  37
  38 On the device: cat > /dev/ttyGS<Y>
  39 On the host: cat /dev/ttyACM<X>
  40
  41 2. ECM function
  42 ===============
  43
  44 The function is provided by usb_f_ecm.ko module.
  45
  46 Function-specific configfs interface
  47 ------------------------------------
  48
  49 The function name to use when creating the function directory is "ecm".
  50 The ECM function provides these attributes in its function directory:
  51
  52         ifname          - network device interface name associated with this
  53                         function instance
  54         qmult           - queue length multiplier for high and super speed
  55         host_addr       - MAC address of host's end of this
  56                         Ethernet over USB link
  57         dev_addr        - MAC address of device's end of this
  58                         Ethernet over USB link
  59
  60 and after creating the functions/ecm.<instance name> they contain default
  61 values: qmult is 5, dev_addr and host_addr are randomly selected.
  62 Except for ifname they can be written to until the function is linked to a
  63 configuration. The ifname is read-only and contains the name of the interface
  64 which was assigned by the net core, e. g. usb0.
  65
  66 Testing the ECM function
  67 ------------------------
  68
  69 Configure IP addresses of the device and the host. Then:
  70
  71 On the device: ping <host's IP>
  72 On the host: ping <device's IP>
  73
  74 3. ECM subset function
  75 ======================
  76
  77 The function is provided by usb_f_ecm_subset.ko module.
  78
  79 Function-specific configfs interface
  80 ------------------------------------
  81
  82 The function name to use when creating the function directory is "geth".
  83 The ECM subset function provides these attributes in its function directory:
  84
  85         ifname          - network device interface name associated with this
  86                         function instance
  87         qmult           - queue length multiplier for high and super speed
  88         host_addr       - MAC address of host's end of this
  89                         Ethernet over USB link
  90         dev_addr        - MAC address of device's end of this
  91                         Ethernet over USB link
  92
  93 and after creating the functions/ecm.<instance name> they contain default
  94 values: qmult is 5, dev_addr and host_addr are randomly selected.
  95 Except for ifname they can be written to until the function is linked to a
  96 configuration. The ifname is read-only and contains the name of the interface
  97 which was assigned by the net core, e. g. usb0.
  98
  99 Testing the ECM subset function
 100 -------------------------------
 101
 102 Configure IP addresses of the device and the host. Then:
 103
 104 On the device: ping <host's IP>
 105 On the host: ping <device's IP>
 106
 107 4. EEM function
 108 ===============
 109
 110 The function is provided by usb_f_eem.ko module.
 111
 112 Function-specific configfs interface
 113 ------------------------------------
 114
 115 The function name to use when creating the function directory is "eem".
 116 The EEM function provides these attributes in its function directory:
 117
 118         ifname          - network device interface name associated with this
 119                         function instance
 120         qmult           - queue length multiplier for high and super speed
 121         host_addr       - MAC address of host's end of this
 122                         Ethernet over USB link
 123         dev_addr        - MAC address of device's end of this
 124                         Ethernet over USB link
 125
 126 and after creating the functions/eem.<instance name> they contain default
 127 values: qmult is 5, dev_addr and host_addr are randomly selected.
 128 Except for ifname they can be written to until the function is linked to a
 129 configuration. The ifname is read-only and contains the name of the interface
 130 which was assigned by the net core, e. g. usb0.
 131
 132 Testing the EEM function
 133 ------------------------
 134
 135 Configure IP addresses of the device and the host. Then:
 136
 137 On the device: ping <host's IP>
 138 On the host: ping <device's IP>
 139
 140 5. FFS function
 141 ===============
 142
 143 The function is provided by usb_f_fs.ko module.
 144
 145 Function-specific configfs interface
 146 ------------------------------------
 147
 148 The function name to use when creating the function directory is "ffs".
 149 The function directory is intentionally empty and not modifiable.
 150
 151 After creating the directory there is a new instance (a "device") of FunctionFS
 152 available in the system. Once a "device" is available, the user should follow
 153 the standard procedure for using FunctionFS (mount it, run the userspace
 154 process which implements the function proper). The gadget should be enabled
 155 by writing a suitable string to usb_gadget/<gadget>/UDC.
 156
 157 Testing the FFS function
 158 ------------------------
 159
 160 On the device: start the function's userspace daemon, enable the gadget
 161 On the host: use the USB function provided by the device
 162
 163 6. HID function
 164 ===============
 165
 166 The function is provided by usb_f_hid.ko module.
 167
 168 Function-specific configfs interface
 169 ------------------------------------
 170
 171 The function name to use when creating the function directory is "hid".
 172 The HID function provides these attributes in its function directory:
 173
 174         protocol        - HID protocol to use
 175         report_desc     - data to be used in HID reports, except data
 176                         passed with /dev/hidg<X>
 177         report_length   - HID report length
 178         subclass        - HID subclass to use
 179
 180 For a keyboard the protocol and the subclass are 1, the report_length is 8,
 181 while the report_desc is:
 182
 183 $ hd my_report_desc
 184 00000000  05 01 09 06 a1 01 05 07  19 e0 29 e7 15 00 25 01  |..........)...%.|
 185 00000010  75 01 95 08 81 02 95 01  75 08 81 03 95 05 75 01  |u.......u.....u.|
 186 00000020  05 08 19 01 29 05 91 02  95 01 75 03 91 03 95 06  |....).....u.....|
 187 00000030  75 08 15 00 25 65 05 07  19 00 29 65 81 00 c0     |u...%e....)e...|
 188 0000003f
 189
 190 Such a sequence of bytes can be stored to the attribute with echo:
 191
 192 $ echo -ne \\x05\\x01\\x09\\x06\\xa1.....
 193
 194 Testing the HID function
 195 ------------------------
 196
 197 Device:
 198 - create the gadget
 199 - connect the gadget to a host, preferably not the one used
 200 to control the gadget
 201 - run a program which writes to /dev/hidg<N>, e.g.
 202 a userspace program found in Documentation/usb/gadget_hid.txt:
 203
 204 $ ./hid_gadget_test /dev/hidg0 keyboard
 205
 206 Host:
 207 - observe the keystrokes from the gadget