1 StrongARM SA-1100 USB function Driver
2 Ward Willats <ward.willats@extenex.com> - 08Mar01
6 Brad Parker <brad@parker.boston.ma.us> ported the DEC/Compaq "Itsy"
7 SA-1100 USB Function driver to the 2.4.x code base in late 2000, for
8 use as an "ethernet over usb" link. His original notes are here in
9 section 4. Nicolas Pitre <nico@cam.org> rewrote the transmitter and
10 reciver (endpoints 1 and 2) in late 2000 to use the standard SA DMA
11 API and I added a bulk character interface and reworked the control
12 control module code and rewrote endpoint zero in early 2001.
14 This release (22Feb01) is the first that completely separates
15 client modules (usb-eth.c and usb-char.c) from the SA-1100 USB core.
16 (usb_ctl, usb_ep0, usb_send and usb_receive)and makes the whole
17 mess a module. Oleg Drokin has done a huge amount of work, fixing
18 things I break and adding support for the generic usbnet driver
23 Turn on CONFIG_SA1100_USB_NETLINK to use the "ethernet over usb"
24 functionality. Turn it off to use the character oriented
25 interface. The character driver currently uses mknod c 10 240.
28 The public interface is in sa1100_usb.h. For a client USB service
29 to use the SA-1100 USB core driver it should:
31 1. Call sa1100_usb_open() to get the usb core assigned to it.
33 2. Setup descriptors as appropriate for the task at hand. Esp.
34 important are endpoint max packet lengths, vendor and product IDs,
35 and type of endpoint (bulk or interrupt). Call
36 sa1100_get_descriptor_ptr() to get this.
38 3. Call sa1100_usb_start() to actually start the usb hardware.
39 At this time the host will configure the device.
43 4. Call sa1100_usb_stop() to stop the USB core.
44 5. Call sa1100_usb_close() to free the core for use by another
49 StrongARM SA-1100 USB function "ethernet over usb driver"
50 Brad Parker <brad@parker.boston.ma.us>
52 I ported the DEC "Itsy" usb "ethernet over usb driver" code to the 2.4.x
53 base and made some enhacements and bug fixes. This code has 2 sides and
54 implements a simple "ethernet over usb" functionality.
56 function (SA1100) side:
57 - the driver has two endpoints and uses interrupt and bulk transfer to
58 receive/send packets. the driver does not require any other usb code
59 and should work on most any sa1100.
62 - because the SA1111 usb host is not working yet I tested this driver
63 (usb-net-host.c) on a 2.2.14 based PC with the latest usb backport.
64 It has been fully converted to use URBs and worked well with my UHCI
69 To test you need an assabet on the 'function' side, a PC on the 'host'
70 side and a USB A-B cable to connect them together.
72 Boot a kernel on the assabet with "USB function and net-host support"
73 (CONFIG_SA1100_USB) turned on. This will define an interface named
74 "usbf". Once it's booted you can setup the interface with
76 mount -t proc /proc /proc
77 /sbin/ifconfig usbf 1.1.1.2
79 I used a 2.2.14 kernel on a x86 PC for the host side. It has a built
80 in UHCI usb controller chip. I installed the latest USB backport from
81 http://www.linux-usb.org onto the 2.2.14 kernel sources and turned on
82 "USB net-host" (CONFIG_USB_NET_HOST) as a module. Load the module
83 "usb-net-host.o" and connect the USB cable to the assabet. Configure
84 the usb network interface with
86 /sbin/ifconfig usb0 1.1.1.1
88 You should be able to "ping" the assabet now with
92 If the assabet is running inetd the usual network services such as
93 telnet and ftp should work.
95 Oleg Drokin in 2.4.2-rmk1-np2 (08Mar01) added module config params for
96 read and write size to the usb-eth.c client to allow dynamic setting
97 of the DATA0/DATA1 packet size on the usb wire:
99 usb_rsize - number of bytes in OUT packets from host to SA1100
100 usb_wsize - number of bytes in IN packets from SA1100 to host
102 This allows dynamic tuning for performance or to prevent overruning
103 the the host with data.
107 - We are fiddling with various ways to set the IMP register in
108 usb_send.c. A small percentage of the time, this value does not
111 - I've started to bring back the /proc interface, but clients
112 of the sa-usb core currently don't have a directory or something
113 to put their stats into.
115 - Only a useful subset of ep0 setup calls have been implemented.
118 5. Mysteries of the Universe
119 ''''''''''''''''''''''''''''
120 This driver has been hard to develop because the documentation
121 provided by Intel is incomplete, and the UDC itself seems to have a
122 variety of bugs. The errata for the part is particularly scary! This
123 section is an attempt to document some of the discoveries and
124 questions I have come across while working on this thing.
126 pp 11-63 of the "Intel Strong ARM SA-1110 Microprocessor Advanced
127 Developer Information" give an ominous warning about how "due to
128 internal synchronization required by the UDC configuration registers,
129 it is possible for the procesor to write the UDC refisters and FIFOs
130 too fast." This has led to a variety of approaches that attempt to
131 bang on the hardware repeatedly and read it back until the write
134 All of these approaches have been problematic. Currently some macros
135 in udc_ctl.h that Nicolas wrote are being used. My hardware guy told
136 me that writes would never be "lost" but stuck on some internal bus in
137 the UDC module and propagated to the rest of the circuit when the time
138 was right. Indeed this seemed to be the case, for example, it seems
139 impossible to reliably read back the interrupt mask register of the UDC when in
140 the interrupt service routine. Often times the state was not reflected
141 on a read until after pending interrupt sources were cleared.
143 I was feeling prety good about this and was ripping out the looping
144 macros right and left until I came upon a situation where, while
145 receiving a continuous set of 1 character packets, ep1 (usb_receive.c)
146 could not clear receive packet complete (RPC). After much desperate
147 faliling about it turns out changing the UDC_flip() macro to bang like
148 crazy on the RPC bit did in fact clear it, and clear it
149 consistently. So go figure.
151 Other items of interest:
153 - Upon emerging from a reset, the UDC will clear the mask register except
154 for a mask on suspend.
156 - USB 1.0 spec says maximum size of a DATA0/1 packet is 64 bytes,
157 which is what the character driver is using. However, the UDC can do
158 256 bytes and every host I've tried can handle it, even though they
159 are not required to. (Perhaps it is a problem when hubs are on the
160 line, but the SA UDC has other problems in a hub environment -- like
161 even getting the correct address -- per the errata).
163 - Endpoint zero FIFOs: ARGHHH! Just leave those routines alone.
164 Believe me, I have tried every other variation you can think of.
167 - Sometimes I get a setup request of 0x80 from Windows hosts. I have
168 not determined if this is a read_fifo error (none is reported) or if
169 this is some undocumented secret Redmond handshake only known to
170 initiates of the inner-order.
174 This is now in the /proc interface. (For good or ill, probably don't
175 actually need to dump all this stuff..)
177 7. Errors and Notes on Intel's 1110 Documentation
178 '''''''''''''''''''''''''''''''''''''''''''''''''
179 These corrections apply to "Intel StrongARM SA-1110 Microprocessor,
180 Advanced Developer's Manual of December 1999" Some of these have been
181 corrected in later editions, some not. There have been several updates
182 to this document published through 2000. Always use the latest
183 available on http://developer.intel.com/design/strong/collateral.htm.
185 pp 11-65 section 11.8.3.8 bit 2, reserved is now the resume interrupt
186 mask. SRM is now SUSIM on SA-1110, and masks only the suspend
189 pp 11-67 section 11.8.6, Max IN register, end should be 9 _bytes_
192 pp 11-68 section 11.8.7.3, SST. This is set by the CPU _not_ the UDC.
193 And it looks like you don't get a SST if you FST yourself.
195 pp 11-68 section 11.8.7.5, DE. This is set by the CPU _not_ the UDC.
197 pp 11-73 section 11.8.9.7, UDCCS2 table, bit 2, Should be "valid only
198 when _TPC_ (not RPC) is set.
200 pp 11-74 section 11.8.10, should end with a GET_DESCRIPTOR _or
201 similar_ command. (Like, for example, GET_CONFIGURATION).
206 Following are current chages 8Mar01 (released in 2.4.2-rmk1-np2?)
208 - Resetting UDC when coming out of suspend helped enumeration get
211 - Added support for client-supplied notify routine to be called
212 by the USB core when core reaches "configured" state.
214 - Added error returns from interrupt reads and buffer flush ioctl
215 calls to usb-char. Added usb-char.h file for ioctl calls.
217 - Fixed bug that kept usb-char transmitter from working the second
218 time the module was loaded.
220 - Turned off a lot of the noise in /proc
222 - Added specialty routines in ep0 to set and clear bits.
224 - More enumeration fiddling.
226 - There are horrible hacks to set max IN length in usb_send
227 that ARE GOING AWAY SOON! REALLY!
229 *** Following changes 26Feb01 (released in 2.4.2-rmk1-np1)
231 - usb-eth integration with generic usbnet from AC tree.
233 - Creation of public interface for usb clients in sa1100_usb.h
234 and final separation into a "core" driver (usb_ctl.c, usb_ep0.c
235 usb_recv.c usb_send.c) and "client" services (usb-eth.c and
236 usb-char.c). Modularized.
238 - Descriptor handling rewritten. Support for string descriptors
239 added. More bugs in ep0 fixed. More setup packets handled.
241 - /proc interface in usb_ctl returning
243 - removed client specific stuff from usbd_info_t and hid the
244 structure in usb_ctl. Removed RAM-backing of address and pktsize
245 in this structure. Now the descriptor values are gospel.
247 - usb_dbg.h eliminated
249 - Many bugs fixed in usb-char.c
251 - Fiddled startup sequence so should start everytime.
253 - Arch specific "soft connect" hook in usb_ctl.c
255 - Bumped the interation count in write/set/clear macros
256 in usb_ctl.h up to 10000. This seemed to help various bit
257 setting in ep0 and usb_send.c.
259 *** Following changes 10Feb01 release:
261 - endpoint zero entirely rewitten
263 - Various changes by Oleg to make Netlink work again after the
264 2.4.1-rmk1-np1 release.
266 - Resetting of new max packet length done after clearing TPC
267 in usb_send, per Nicolas Pitre.
270 *** Following changes 23Jan01 (came out in 2.4.1-rmk1-np1):
272 - Moved host initiated SET/GET feature stall into endpoint code of
273 usb_send.c and usb_receive.c and removed stallep from usb_ctl.c
274 Opposite of a SET_FEATURE stall is a reset, so no code to unstall is
277 - Added explicit USB state machine to usb_ctl so driver and device
278 state can be tracked closely and explicitly. Added hard-wired
279 notification routines in endpoints 1 and 2 so they can track device
280 state changes as required. State machine has notion of "zombie" state
281 the covers USB states NONATTACHED, ATTACHED and POWERED since these
282 are murky, and USB driver currently has no way to differentiate
285 - Reworked ISR in usb_ctl so reset has higher priority than any other
286 event. Stopped using sync macros to clear interrupt pending flags and set
287 mask registers since it appears mask register changes are not
288 always reflected on a mask register read until the pending flag is
289 cleared (yet other tests show they are always cleared
290 eventually). Toggle suspend/resume interrupt masks back and forth during
291 suspend and resume to debounce and keep UDC internal state machine in
292 sync per Intel documentation.
294 - Flipped UDC flip, clear, write and set macros from do{}while to
295 while() loops. Theory is you might save a loop iteration if value
296 becomes valid immediately. Also, my hardware guy says writes are never
297 "lost", just pipelined and not executed immediately depending on
298 internal device conditions (like setting int masks when ints
299 pending), so moved write cycles in macros outside of loops.
301 - Added #defines to SA-1110.h for suspend and resume interrupt mask
302 bits per Intel eratta. Submitted to ARM patch system (444/1).
304 - Removed task queue and defered execution of configure() from
307 - Removed usb_write_reg() from usb_ctl.c, and various cruft from
310 - Added sa1100_usb_xmitter_avail() to usb_send.c. Makes implementing
311 poll() fileop easier.
313 - Added sa1100_usb_send_reset() to usb_send.c. Makes implementing
314 transmitter timeout easier.
316 - Added API to usb_ctl to set vendor and product ID
318 - Changed BMATTR descriptor fron int to bulk, when not using netlink. (All
319 the docs say UDC does not support INT xfers -- though, at the protocol
320 level I don't see why not, since bulk and int are both just
321 IN-DATA-ACK. I figure netlink may rely on this, and not just a
322 continuous pending read from the host, but for "pure bulk" host
323 polling may not be generally correct.)
325 - Removed unused rx_lock and tx_lock from usb_ctl
327 - Converted everyone to SA-1100.h and nuked hardware defines in usb_ctl.h
329 - Removed udc_init() in usb_ctl.c and folded functionality into udc_start().
331 - Clear force stall (FST) in udc_start and reset so UDC actually runs when
334 - Emit NAK in receiver until ep1_start() for error (RPE) case too.
336 - Remove enable/disable UDC from reset handler in udc_ctl. The UDC has
337 already been reset, so no need to do this again.
339 - Explicitly set address to zero in ep0_reset()
341 - Added "naking" boolean to usb_receiv.c. An attempt to solve a
342 hypothetical race condition where we are in the critical section
343 initiating a read from base-level code, a RPC happens, and start()
344 might clear the condition before the packet is handled by the ISR.