Commit | Line | Data |
---|---|---|
1da177e4 LT |
1 | |
2 | Linux Gadget Serial Driver v2.0 | |
3 | 11/20/2004 | |
a7707adf | 4 | (updated 8-May-2008 for v2.3) |
1da177e4 LT |
5 | |
6 | ||
7 | License and Disclaimer | |
8 | ---------------------- | |
9 | This program is free software; you can redistribute it and/or | |
10 | modify it under the terms of the GNU General Public License as | |
11 | published by the Free Software Foundation; either version 2 of | |
12 | the License, or (at your option) any later version. | |
13 | ||
14 | This program is distributed in the hope that it will be useful, | |
15 | but WITHOUT ANY WARRANTY; without even the implied warranty of | |
16 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
17 | GNU General Public License for more details. | |
18 | ||
19 | You should have received a copy of the GNU General Public | |
20 | License along with this program; if not, write to the Free | |
21 | Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, | |
22 | MA 02111-1307 USA. | |
23 | ||
d533f671 | 24 | This document and the gadget serial driver itself are |
1da177e4 LT |
25 | Copyright (C) 2004 by Al Borchers (alborchers@steinerpoint.com). |
26 | ||
27 | If you have questions, problems, or suggestions for this driver | |
28 | please contact Al Borchers at alborchers@steinerpoint.com. | |
29 | ||
30 | ||
31 | Prerequisites | |
32 | ------------- | |
33 | Versions of the gadget serial driver are available for the | |
34 | 2.4 Linux kernels, but this document assumes you are using | |
a7707adf | 35 | version 2.3 or later of the gadget serial driver in a 2.6 |
1da177e4 LT |
36 | Linux kernel. |
37 | ||
38 | This document assumes that you are familiar with Linux and | |
39 | Windows and know how to configure and build Linux kernels, run | |
40 | standard utilities, use minicom and HyperTerminal, and work with | |
41 | USB and serial devices. It also assumes you configure the Linux | |
42 | gadget and usb drivers as modules. | |
43 | ||
a7707adf DB |
44 | With version 2.3 of the driver, major and minor device nodes are |
45 | no longer statically defined. Your Linux based system should mount | |
46 | sysfs in /sys, and use "mdev" (in Busybox) or "udev" to make the | |
47 | /dev nodes matching the sysfs /sys/class/tty files. | |
48 | ||
49 | ||
1da177e4 LT |
50 | |
51 | Overview | |
52 | -------- | |
53 | The gadget serial driver is a Linux USB gadget driver, a USB device | |
54 | side driver. It runs on a Linux system that has USB device side | |
55 | hardware; for example, a PDA, an embedded Linux system, or a PC | |
56 | with a USB development card. | |
57 | ||
58 | The gadget serial driver talks over USB to either a CDC ACM driver | |
59 | or a generic USB serial driver running on a host PC. | |
60 | ||
61 | Host | |
62 | -------------------------------------- | |
63 | | Host-Side CDC ACM USB Host | | |
64 | | Operating | or | Controller | USB | |
65 | | System | Generic USB | Driver |-------- | |
66 | | (Linux or | Serial | and | | | |
67 | | Windows) Driver USB Stack | | | |
68 | -------------------------------------- | | |
69 | | | |
70 | | | |
71 | | | |
72 | Gadget | | |
73 | -------------------------------------- | | |
74 | | Gadget USB Periph. | | | |
75 | | Device-Side | Gadget | Controller | | | |
76 | | Linux | Serial | Driver |-------- | |
77 | | Operating | Driver | and | | |
78 | | System USB Stack | | |
79 | -------------------------------------- | |
80 | ||
81 | On the device-side Linux system, the gadget serial driver looks | |
82 | like a serial device. | |
83 | ||
84 | On the host-side system, the gadget serial device looks like a | |
85 | CDC ACM compliant class device or a simple vendor specific device | |
86 | with bulk in and bulk out endpoints, and it is treated similarly | |
87 | to other serial devices. | |
88 | ||
89 | The host side driver can potentially be any ACM compliant driver | |
90 | or any driver that can talk to a device with a simple bulk in/out | |
91 | interface. Gadget serial has been tested with the Linux ACM driver, | |
92 | the Windows usbser.sys ACM driver, and the Linux USB generic serial | |
93 | driver. | |
94 | ||
95 | With the gadget serial driver and the host side ACM or generic | |
96 | serial driver running, you should be able to communicate between | |
97 | the host and the gadget side systems as if they were connected by a | |
98 | serial cable. | |
99 | ||
100 | The gadget serial driver only provides simple unreliable data | |
101 | communication. It does not yet handle flow control or many other | |
102 | features of normal serial devices. | |
103 | ||
104 | ||
105 | Installing the Gadget Serial Driver | |
106 | ----------------------------------- | |
107 | To use the gadget serial driver you must configure the Linux gadget | |
108 | side kernel for "Support for USB Gadgets", for a "USB Peripheral | |
109 | Controller" (for example, net2280), and for the "Serial Gadget" | |
110 | driver. All this are listed under "USB Gadget Support" when | |
111 | configuring the kernel. Then rebuild and install the kernel or | |
112 | modules. | |
113 | ||
1da177e4 | 114 | Then you must load the gadget serial driver. To load it as an |
a7707adf | 115 | ACM device (recommended for interoperability), do this: |
1da177e4 LT |
116 | |
117 | modprobe g_serial use_acm=1 | |
118 | ||
119 | To load it as a vendor specific bulk in/out device, do this: | |
120 | ||
121 | modprobe g_serial | |
122 | ||
123 | This will also automatically load the underlying gadget peripheral | |
124 | controller driver. This must be done each time you reboot the gadget | |
125 | side Linux system. You can add this to the start up scripts, if | |
126 | desired. | |
127 | ||
a7707adf DB |
128 | Your system should use mdev (from busybox) or udev to make the |
129 | device nodes. After this gadget driver has been set up you should | |
130 | then see a /dev/ttyGS0 node: | |
131 | ||
132 | # ls -l /dev/ttyGS0 | cat | |
133 | crw-rw---- 1 root root 253, 0 May 8 14:10 /dev/ttyGS0 | |
134 | # | |
135 | ||
136 | Note that the major number (253, above) is system-specific. If | |
137 | you need to create /dev nodes by hand, the right numbers to use | |
138 | will be in the /sys/class/tty/ttyGS0/dev file. | |
139 | ||
140 | When you link this gadget driver early, perhaps even statically, | |
141 | you may want to set up an /etc/inittab entry to run "getty" on it. | |
142 | The /dev/ttyGS0 line should work like most any other serial port. | |
143 | ||
144 | ||
1da177e4 LT |
145 | If gadget serial is loaded as an ACM device you will want to use |
146 | either the Windows or Linux ACM driver on the host side. If gadget | |
147 | serial is loaded as a bulk in/out device, you will want to use the | |
148 | Linux generic serial driver on the host side. Follow the appropriate | |
149 | instructions below to install the host side driver. | |
150 | ||
151 | ||
152 | Installing the Windows Host ACM Driver | |
153 | -------------------------------------- | |
154 | To use the Windows ACM driver you must have the files "gserial.inf" | |
155 | and "usbser.sys" together in a folder on the Windows machine. | |
156 | ||
157 | The "gserial.inf" file is given here. | |
158 | ||
159 | -------------------- CUT HERE -------------------- | |
160 | [Version] | |
161 | Signature="$Windows NT$" | |
162 | Class=Ports | |
163 | ClassGuid={4D36E978-E325-11CE-BFC1-08002BE10318} | |
164 | Provider=%LINUX% | |
165 | DriverVer=08/17/2004,0.0.2.0 | |
166 | ; Copyright (C) 2004 Al Borchers (alborchers@steinerpoint.com) | |
167 | ||
168 | [Manufacturer] | |
169 | %LINUX%=GSerialDeviceList | |
170 | ||
171 | [GSerialDeviceList] | |
172 | %GSERIAL%=GSerialInstall, USB\VID_0525&PID_A4A7 | |
173 | ||
174 | [DestinationDirs] | |
175 | DefaultDestDir=10,System32\Drivers | |
176 | ||
177 | [GSerialInstall] | |
178 | CopyFiles=GSerialCopyFiles | |
179 | AddReg=GSerialAddReg | |
180 | ||
181 | [GSerialCopyFiles] | |
182 | usbser.sys | |
183 | ||
184 | [GSerialAddReg] | |
185 | HKR,,DevLoader,,*ntkern | |
186 | HKR,,NTMPDriver,,usbser.sys | |
187 | HKR,,EnumPropPages32,,"MsPorts.dll,SerialPortPropPageProvider" | |
188 | ||
189 | [GSerialInstall.Services] | |
190 | AddService = usbser,0x0002,GSerialService | |
191 | ||
192 | [GSerialService] | |
193 | DisplayName = %GSERIAL_DISPLAY_NAME% | |
194 | ServiceType = 1 ; SERVICE_KERNEL_DRIVER | |
195 | StartType = 3 ; SERVICE_DEMAND_START | |
196 | ErrorControl = 1 ; SERVICE_ERROR_NORMAL | |
197 | ServiceBinary = %10%\System32\Drivers\usbser.sys | |
198 | LoadOrderGroup = Base | |
199 | ||
200 | [Strings] | |
201 | LINUX = "Linux" | |
202 | GSERIAL = "Gadget Serial" | |
203 | GSERIAL_DISPLAY_NAME = "USB Gadget Serial Driver" | |
204 | -------------------- CUT HERE -------------------- | |
205 | ||
206 | The "usbser.sys" file comes with various versions of Windows. | |
207 | For example, it can be found on Windows XP typically in | |
208 | ||
209 | C:\WINDOWS\Driver Cache\i386\driver.cab | |
210 | ||
211 | Or it can be found on the Windows 98SE CD in the "win98" folder | |
212 | in the "DRIVER11.CAB" through "DRIVER20.CAB" cab files. You will | |
213 | need the DOS "expand" program, the Cygwin "cabextract" program, or | |
214 | a similar program to unpack these cab files and extract "usbser.sys". | |
215 | ||
216 | For example, to extract "usbser.sys" into the current directory | |
217 | on Windows XP, open a DOS window and run a command like | |
218 | ||
219 | expand C:\WINDOWS\Driver~1\i386\driver.cab -F:usbser.sys . | |
220 | ||
221 | (Thanks to Nishant Kamat for pointing out this DOS command.) | |
222 | ||
223 | When the gadget serial driver is loaded and the USB device connected | |
224 | to the Windows host with a USB cable, Windows should recognize the | |
225 | gadget serial device and ask for a driver. Tell Windows to find the | |
226 | driver in the folder that contains "gserial.inf" and "usbser.sys". | |
227 | ||
228 | For example, on Windows XP, when the gadget serial device is first | |
229 | plugged in, the "Found New Hardware Wizard" starts up. Select | |
230 | "Install from a list or specific location (Advanced)", then on | |
231 | the next screen select "Include this location in the search" and | |
232 | enter the path or browse to the folder containing "gserial.inf" and | |
233 | "usbser.sys". Windows will complain that the Gadget Serial driver | |
234 | has not passed Windows Logo testing, but select "Continue anyway" | |
235 | and finish the driver installation. | |
236 | ||
237 | On Windows XP, in the "Device Manager" (under "Control Panel", | |
238 | "System", "Hardware") expand the "Ports (COM & LPT)" entry and you | |
239 | should see "Gadget Serial" listed as the driver for one of the COM | |
240 | ports. | |
241 | ||
242 | To uninstall the Windows XP driver for "Gadget Serial", right click | |
243 | on the "Gadget Serial" entry in the "Device Manager" and select | |
244 | "Uninstall". | |
245 | ||
246 | ||
247 | Installing the Linux Host ACM Driver | |
248 | ------------------------------------ | |
249 | To use the Linux ACM driver you must configure the Linux host side | |
250 | kernel for "Support for Host-side USB" and for "USB Modem (CDC ACM) | |
251 | support". | |
252 | ||
253 | Once the gadget serial driver is loaded and the USB device connected | |
254 | to the Linux host with a USB cable, the host system should recognize | |
255 | the gadget serial device. For example, the command | |
256 | ||
257 | cat /proc/bus/usb/devices | |
258 | ||
259 | should show something like this: | |
260 | ||
261 | T: Bus=01 Lev=01 Prnt=01 Port=01 Cnt=02 Dev#= 5 Spd=480 MxCh= 0 | |
262 | D: Ver= 2.00 Cls=02(comm.) Sub=00 Prot=00 MxPS=64 #Cfgs= 1 | |
263 | P: Vendor=0525 ProdID=a4a7 Rev= 2.01 | |
264 | S: Manufacturer=Linux 2.6.8.1 with net2280 | |
265 | S: Product=Gadget Serial | |
266 | S: SerialNumber=0 | |
267 | C:* #Ifs= 2 Cfg#= 2 Atr=c0 MxPwr= 2mA | |
268 | I: If#= 0 Alt= 0 #EPs= 1 Cls=02(comm.) Sub=02 Prot=01 Driver=acm | |
269 | E: Ad=83(I) Atr=03(Int.) MxPS= 8 Ivl=32ms | |
270 | I: If#= 1 Alt= 0 #EPs= 2 Cls=0a(data ) Sub=00 Prot=00 Driver=acm | |
271 | E: Ad=81(I) Atr=02(Bulk) MxPS= 512 Ivl=0ms | |
272 | E: Ad=02(O) Atr=02(Bulk) MxPS= 512 Ivl=0ms | |
273 | ||
274 | If the host side Linux system is configured properly, the ACM driver | |
275 | should be loaded automatically. The command "lsmod" should show the | |
276 | "acm" module is loaded. | |
277 | ||
278 | ||
279 | Installing the Linux Host Generic USB Serial Driver | |
280 | --------------------------------------------------- | |
281 | To use the Linux generic USB serial driver you must configure the | |
282 | Linux host side kernel for "Support for Host-side USB", for "USB | |
283 | Serial Converter support", and for the "USB Generic Serial Driver". | |
284 | ||
285 | Once the gadget serial driver is loaded and the USB device connected | |
286 | to the Linux host with a USB cable, the host system should recognize | |
287 | the gadget serial device. For example, the command | |
288 | ||
289 | cat /proc/bus/usb/devices | |
290 | ||
291 | should show something like this: | |
292 | ||
293 | T: Bus=01 Lev=01 Prnt=01 Port=01 Cnt=02 Dev#= 6 Spd=480 MxCh= 0 | |
294 | D: Ver= 2.00 Cls=ff(vend.) Sub=00 Prot=00 MxPS=64 #Cfgs= 1 | |
295 | P: Vendor=0525 ProdID=a4a6 Rev= 2.01 | |
296 | S: Manufacturer=Linux 2.6.8.1 with net2280 | |
297 | S: Product=Gadget Serial | |
298 | S: SerialNumber=0 | |
299 | C:* #Ifs= 1 Cfg#= 1 Atr=c0 MxPwr= 2mA | |
300 | I: If#= 0 Alt= 0 #EPs= 2 Cls=0a(data ) Sub=00 Prot=00 Driver=serial | |
301 | E: Ad=81(I) Atr=02(Bulk) MxPS= 512 Ivl=0ms | |
302 | E: Ad=02(O) Atr=02(Bulk) MxPS= 512 Ivl=0ms | |
303 | ||
304 | You must explicitly load the usbserial driver with parameters to | |
305 | configure it to recognize the gadget serial device, like this: | |
306 | ||
307 | modprobe usbserial vendor=0x0525 product=0xA4A6 | |
308 | ||
309 | If everything is working, usbserial will print a message in the | |
310 | system log saying something like "Gadget Serial converter now | |
311 | attached to ttyUSB0". | |
312 | ||
313 | ||
314 | Testing with Minicom or HyperTerminal | |
315 | ------------------------------------- | |
316 | Once the gadget serial driver and the host driver are both installed, | |
317 | and a USB cable connects the gadget device to the host, you should | |
318 | be able to communicate over USB between the gadget and host systems. | |
319 | You can use minicom or HyperTerminal to try this out. | |
320 | ||
321 | On the gadget side run "minicom -s" to configure a new minicom | |
322 | session. Under "Serial port setup" set "/dev/ttygserial" as the | |
323 | "Serial Device". Set baud rate, data bits, parity, and stop bits, | |
324 | to 9600, 8, none, and 1--these settings mostly do not matter. | |
325 | Under "Modem and dialing" erase all the modem and dialing strings. | |
326 | ||
327 | On a Linux host running the ACM driver, configure minicom similarly | |
328 | but use "/dev/ttyACM0" as the "Serial Device". (If you have other | |
329 | ACM devices connected, change the device name appropriately.) | |
330 | ||
331 | On a Linux host running the USB generic serial driver, configure | |
332 | minicom similarly, but use "/dev/ttyUSB0" as the "Serial Device". | |
333 | (If you have other USB serial devices connected, change the device | |
334 | name appropriately.) | |
335 | ||
336 | On a Windows host configure a new HyperTerminal session to use the | |
337 | COM port assigned to Gadget Serial. The "Port Settings" will be | |
338 | set automatically when HyperTerminal connects to the gadget serial | |
339 | device, so you can leave them set to the default values--these | |
340 | settings mostly do not matter. | |
341 | ||
342 | With minicom configured and running on the gadget side and with | |
343 | minicom or HyperTerminal configured and running on the host side, | |
344 | you should be able to send data back and forth between the gadget | |
345 | side and host side systems. Anything you type on the terminal | |
346 | window on the gadget side should appear in the terminal window on | |
347 | the host side and vice versa. | |
348 | ||
349 |