Android USB Gadget » History » Version 4
laforge, 12/18/2016 12:25 PM
1 | 1 | laforge | h1. Android USB Gadget |
---|---|---|---|
2 | |||
3 | 2 | laforge | The Android Linux kernel has an incredibly versatile USB gadget that is not present in mainline linux. |
4 | |||
5 | Using sysfs, you can configure a USB device that has a large number of interfaces, each exposing one particular function. |
||
6 | |||
7 | Each function (class) is implemented by a _gadget_ driver. In the source code they are prefixed with "f_", so the serial function is called @f_serial@ |
||
8 | |||
9 | h2. Using sysfs to configure |
||
10 | |||
11 | Each USB device is exposed as a @/sys/devices/virtual/android_usb/androidX@ interface where @X@ corresponds to the logical number. Most devices these days have only one or two USB ports, so it is mostly @android0@ or @android1@ that you will see. |
||
12 | |||
13 | Below this sysfs directory ad a number of different files. They can only be modified/written to if the USB port is disabled by means of |
||
14 | <pre> |
||
15 | echo 0 > sys/devices/virtual/android_usb/android0/enable |
||
16 | </pre> |
||
17 | It will disconnect from the USB host at this point. |
||
18 | |||
19 | After modifying what you want to modify, you can use |
||
20 | <pre> |
||
21 | echo 1 > sys/devices/virtual/android_usb/android0/enable |
||
22 | </pre> |
||
23 | to re-enable the USB port. It will re-enumerate to the host at this point. |
||
24 | |||
25 | 1 | laforge | |
26 | 3 | laforge | h3. @/sys/devices/virtual/android_usb/androidX/idVendor@ |
27 | 2 | laforge | |
28 | 1 | laforge | Allows you to set the USB Vendor ID |
29 | 2 | laforge | |
30 | 3 | laforge | h3. @/sys/devices/virtual/android_usb/androidX/idProduct@ |
31 | 1 | laforge | |
32 | Allows you to set the USB Device ID |
||
33 | 2 | laforge | |
34 | 3 | laforge | h3. @/sys/devices/virtual/android_usb/androidX/iManufacturer@ |
35 | 2 | laforge | |
36 | 3 | laforge | Allows you to set the USB Manufacturer string. You enter it in ASCII, it will be converted to a USB String automatically. |
37 | 2 | laforge | |
38 | 3 | laforge | h3. @/sys/devices/virtual/android_usb/androidX/Product@ |
39 | 1 | laforge | |
40 | 3 | laforge | Allows you to set the USB Product string. You enter it in ASCII, it will be converted to a USB String automatically. |
41 | 2 | laforge | |
42 | 3 | laforge | h3. @/sys/devices/virtual/android_usb/androidX/functions@ |
43 | 1 | laforge | |
44 | 3 | laforge | Allows you to configure which functions compose the interfaces of your USB device |
45 | 1 | laforge | |
46 | 3 | laforge | The default on Quectel modems seems to be @diag,serial,rmnet@ |
47 | 1 | laforge | |
48 | 3 | laforge | A more generally useful setup for developers is something like @adb,diag,serial,rmnet@ which adds ADB access. |
49 | |||
50 | You can also add further functions like MBIM, CCID, MTP, PTP, or even mass_storage. Please note that most of them require additional configuration to do anything useful. |
||
51 | |||
52 | The order of functions in the string you write to @functions@ will determine the order of those interfaces in the interface descriptor. |
||
53 | |||
54 | Please note that some functions can themselves implement multiple interfaces. Even in the Quectel default you will see that the @serial@ function offers three virtual serial ports: One for GPS and two for AT-Commands. |
||
55 | |||
56 | This is due to the fact that something like @tty,smd,smd@ is written into the @/sys/class/android_usb/androidX/f_serial/transports@ file (see below) |
||
57 | |||
58 | |||
59 | |||
60 | |||
61 | h2. Gadgets / kernel code |
||
62 | |||
63 | 'struct android_usb_function' implements a given function |
||
64 | |||
65 | 1 | laforge | h3. ffs (function FS) |
66 | |||
67 | * userspace process can implement USB functions |
||
68 | * used e.g. by adbd |
||
69 | |||
70 | h3. acm (CDC "astract control model") |
||
71 | |||
72 | * USB-IF standardized version of serial-type ports |
||
73 | * exposed via /dev/ttyGS* device |
||
74 | |||
75 | h3. rmnet |
||
76 | |||
77 | usb gadget driver to implement a rmnet gadget, f_rmnet.c |
||
78 | Documentation/usb/gadget_rmnet.txt |
||
79 | |||
80 | * drivers/net/ethernet/msm/msm_rmnet_mhi.c |
||
81 | * interface descriptor: class/subclass/proto = 0xff, numEP=3 |
||
82 | ** stringdescriptor en-us, string 0 == "RmNet" |
||
83 | ** full speed descriptors (notify/in/out) |
||
84 | ** high speed descriptors (notify/in/out) |
||
85 | ** super speed descriptors (notify/in/out + comp) |
||
86 | |||
87 | * rmnet has ports |
||
88 | 4 | laforge | ** control ports can map to SMD, QTI, HSIC, HSUART |
89 | *** SMD: Shared Memory Device towards modem |
||
90 | *** QTI: ? |
||
91 | *** HSIC: High-speed Inter-IC USB variant |
||
92 | *** HSUART: High-speed UART |
||
93 | ** data ports can map to BAM2BAM, BAM_DMUX, BAM2BAM_IPA, HSIC, HSUART, ETHER |
||
94 | *** BAM2BAM is normal case? Replaced by BAM_DMUX in more recent kernels? |
||
95 | *** BAM2BAM_IPA via internet packet accelerator? |
||
96 | *** HSIC: High-speed Inter-IC USB variant |
||
97 | *** HSUART: High-speed UART |
||
98 | *** ETHER exposes the data pipe as usb_rmnet%d device on Linux (EC25 only) |
||
99 | 1 | laforge | * frmnet_init_port() establishes connections |
100 | |||
101 | h3. gps |
||
102 | |||
103 | * IF class/sub/proto = 0xff |
||
104 | * only one endpoint (notify) |
||
105 | * string[0] (en-us) is "GPS" |
||
106 | |||
107 | h3. ncm (CDC Netowrk (NCM) link function) |
||
108 | |||
109 | h3. ecm_qc (CDC Ethernet) |
||
110 | |||
111 | h3. usb_mbim (Mobile Broadband Interface Model) |
||
112 | |||
113 | h3. audio (uac1?) |
||
114 | |||
115 | h3. diag |
||
116 | |||
117 | * class/sub/proto = 0xff |
||
118 | * num-ep 2 |
||
119 | * max-packet 512 |
||
120 | * some special assumption only if bInterfaceNumber==0 |
||
121 | |||
122 | h3. qdss (Qualcomm Debug Sub-System) |
||
123 | |||
124 | * has QDSS DATA / QDSS CTRL string descriptor |
||
125 | * somehow connects to BAM |
||
126 | |||
127 | h3. serial |
||
128 | |||
129 | 3 | laforge | Offers a @f_serial/transports@ file that determines the number of virtual serial ports and the low-level transport to use for them |
130 | |||
131 | A maximum of four instances is supported, but one could change @MAX_SERIAL_INSTANCES@ if more were needed. |
||
132 | |||
133 | 1 | laforge | * class=0xff, sub/proto = 0 |
134 | * num_endpoints = 3 |
||
135 | * string descroptor "Generic Serial" |
||
136 | * transports |
||
137 | 3 | laforge | ** tty (-> gserial, i.e. geenrates a /dev/ttyGSx device for use by local processes) |
138 | ** smd (shared memory [to baseband]) |
||
139 | ** char_bridge (unknown) |
||
140 | ** hsic (a inter-chip version of USB in case of multi-chip modems) |
||
141 | 1 | laforge | |
142 | h3. ccid (chipcard reader) |
||
143 | |||
144 | * /dev/ccid_ctrl |
||
145 | * /dev/ccid_bulk |
||
146 | * probably intended to be used with userspace progam translating USB CCID requests into QMI requests to access SIM card(s) |
||
147 | |||
148 | h3. charging |
||
149 | |||
150 | * usb charger support |
||
151 | |||
152 | h3. mtp |
||
153 | |||
154 | h3. ptp |
||
155 | |||
156 | h3. rndis |
||
157 | |||
158 | h3. rndis_qc |
||
159 | |||
160 | h3. ecm |
||
161 | |||
162 | h3. mass_storage |
||
163 | |||
164 | h3. accessory |
||
165 | |||
166 | h3. audio_source |
||
167 | |||
168 | h3. midi |
||
169 | |||
170 | h3. rndis_gsi |
||
171 | |||
172 | h3. rmnet_gsi |
||
173 | |||
174 | h3. ecm_gsi |
||
175 | |||
176 | h3. mbim_gsi |
||
177 | |||
178 | h3. dpl_gsi |
||
179 | |||
180 | |||
181 | h2. modem detection / EC20 re-using same usb device id / interface numbers |
||
182 | |||
183 | The idea here is to dynamically detect which interface number exposes a certain interface, |
||
184 | regardless what order / qty / interface number |
||
185 | |||
186 | * ADB: 255/66/1, 2 EP |
||
187 | * Diag: 255/255/255, 2 EP |
||
188 | * TTY: 255/0/0, 3 EP, unrecognized descriptors |
||
189 | * RMNET: 255/255/255, 3EP |