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