Subversion Repositories or1k

StrongARM SA-1100 USB function Driver

Ward Willats  -  08Mar01

1. History

''''''''''

Brad Parker  ported the DEC/Compaq "Itsy"

SA-1100 USB Function driver to the 2.4.x code base in late 2000, for

use as an "ethernet over usb" link. His original notes are here in

section 4. Nicolas Pitre  rewrote the transmitter and

reciver (endpoints 1 and 2) in late 2000 to use the standard SA DMA

API and I added a bulk character interface and reworked the control

control module code and rewrote endpoint zero in early 2001.

This release (22Feb01) is the first that completely separates

client modules (usb-eth.c and usb-char.c) from the SA-1100 USB core.

(usb_ctl, usb_ep0, usb_send and usb_receive)and makes the whole

mess a module. Oleg Drokin has done a huge amount of work, fixing

things I break and adding support for the generic usbnet driver

from the AC tree.

2. Usage

''''''''

Turn on CONFIG_SA1100_USB_NETLINK to use the "ethernet over usb"

functionality. Turn it off to use the character oriented

interface. The character driver currently uses mknod c 10 240.

Programming:

The public interface is in sa1100_usb.h. For a client USB service

to use the SA-1100 USB core driver it should:

1. Call sa1100_usb_open() to get the usb core assigned to it.

2. Setup descriptors as appropriate for the task at hand. Esp.

important are endpoint max packet lengths, vendor and product IDs,

and type of endpoint (bulk or interrupt). Call

sa1100_get_descriptor_ptr() to get this.

3. Call sa1100_usb_start() to actually start the usb hardware.

At this time the host will configure the device.

...at shutdown...

4. Call sa1100_usb_stop() to stop the USB core.

5. Call sa1100_usb_close() to free the core for use by another

client.

3. Netlink Usage

''''''''''''''''

StrongARM SA-1100 USB function "ethernet over usb driver"

Brad Parker 

I ported the DEC "Itsy" usb "ethernet over usb driver" code to the 2.4.x

base and made some enhacements and bug fixes.  This code has 2 sides and

implements a simple "ethernet over usb" functionality.

function (SA1100) side:

- the driver has two endpoints and uses interrupt and bulk transfer to

receive/send packets.  the driver does not require any other usb code

and should work on most any sa1100.

host (SA1111) side:

- because the SA1111 usb host is not working yet I tested this driver

(usb-net-host.c) on a 2.2.14 based PC with the latest usb backport.

It has been fully converted to use URBs and worked well with my UHCI

based controller.

TESTING:

To test you need an assabet on the 'function' side, a PC on the 'host'

side and a USB A-B cable to connect them together.

Boot a kernel on the assabet with "USB function and net-host support"

(CONFIG_SA1100_USB) turned on.  This will define an interface named

"usbf".  Once it's booted you can setup the interface with

        mount -t proc /proc /proc

        /sbin/ifconfig usbf 1.1.1.2

I used a 2.2.14 kernel on a x86 PC for the host side.  It has a built

in UHCI usb controller chip.  I installed the latest USB backport from

http://www.linux-usb.org onto the 2.2.14 kernel sources and turned on

"USB net-host" (CONFIG_USB_NET_HOST) as a module.  Load the module

"usb-net-host.o" and connect the USB cable to the assabet.  Configure

the usb network interface with

        /sbin/ifconfig usb0 1.1.1.1

You should be able to "ping" the assabet now with

        ping -c 1 1.1.1.2

If the assabet is running inetd the usual network services such as

telnet and ftp should work.

Oleg Drokin in 2.4.2-rmk1-np2 (08Mar01) added module config params for

read and write size to the usb-eth.c client to allow dynamic setting

of the DATA0/DATA1 packet size on the usb wire:

usb_rsize - number of bytes in OUT packets from host to SA1100

usb_wsize - number of bytes in IN packets from SA1100 to host

This allows dynamic tuning for performance or to prevent overruning

the the host with data.

4. Known Issues

'''''''''''''''

- We are fiddling with various ways to set the IMP register in

usb_send.c. A small percentage of the time, this value does not

"take."

- I've started to bring back the /proc interface, but clients

of the sa-usb core currently don't have a directory or something

to put their stats into.

- Only a useful subset of ep0 setup calls have been implemented.

5. Mysteries of the Universe

''''''''''''''''''''''''''''

This driver has been hard to develop because the documentation

provided by Intel is incomplete, and the UDC itself seems to have a

variety of bugs. The errata for the part is particularly scary! This

section is an attempt to document some of the discoveries and

questions I have come across while working on this thing.

pp 11-63 of the "Intel Strong ARM SA-1110 Microprocessor Advanced

Developer Information" give an ominous warning about how "due to

internal synchronization required by the UDC configuration registers,

it is possible for the procesor to write the UDC refisters and FIFOs

too fast." This has led to a variety of approaches that attempt to

bang on the hardware repeatedly and read it back until the write

"sticks."

All of these approaches have been problematic. Currently some macros

in udc_ctl.h that Nicolas wrote are being used. My hardware guy told

me that writes would never be "lost" but stuck on some internal bus in

the UDC module and propagated to the rest of the circuit when the time

was right. Indeed this seemed to be the case, for example, it seems

impossible to reliably read back the interrupt mask register of the UDC when in

the interrupt service routine. Often times the state was not reflected

on a read until after pending interrupt sources were cleared.

I was feeling prety good about this and was ripping out the looping

macros right and left until I came upon a situation where, while

receiving a continuous set of 1 character packets, ep1 (usb_receive.c)

could not clear receive packet complete (RPC). After much desperate

faliling about it turns out changing the UDC_flip() macro to bang like

crazy on the RPC bit did in fact clear it, and clear it

consistently. So go figure.

Other items of interest:

- Upon emerging from a reset, the UDC will clear the mask register except

for a mask on suspend.

- USB 1.0 spec says maximum size of a DATA0/1 packet is 64 bytes,

which is what the character driver is using. However, the UDC can do

256 bytes and every host I've tried can handle it, even though they

are not required to. (Perhaps it is a problem when hubs are on the

line, but the SA UDC has other problems in a hub environment -- like

even getting the correct address -- per the errata).

- Endpoint zero FIFOs: ARGHHH! Just leave those routines alone.

Believe me, I have tried every other variation you can think of.

Probably.

- Sometimes I get a setup request of 0x80 from Windows hosts. I have

not determined if this is a read_fifo error (none is reported) or if

this is some undocumented secret Redmond handshake only known to

initiates of the inner-order.

6. Test Program

'''''''''''''''

This is now in the /proc interface. (For good or ill, probably don't

actually need to dump all this stuff..)

7. Errors and Notes on Intel's 1110 Documentation

'''''''''''''''''''''''''''''''''''''''''''''''''

These corrections apply to "Intel StrongARM SA-1110 Microprocessor,

Advanced Developer's Manual of December 1999" Some of these have been

corrected in later editions, some not. There have been several updates

to this document published through 2000. Always use the latest

available on http://developer.intel.com/design/strong/collateral.htm.

pp 11-65 section 11.8.3.8 bit 2, reserved is now the resume interrupt

mask. SRM is now SUSIM on SA-1110, and masks only the suspend

interrupt.

pp 11-67 section 11.8.6, Max IN register, end should be 9 _bytes_

not 9 bits.

pp 11-68 section 11.8.7.3, SST. This is set by the CPU _not_ the UDC.

And it looks like you don't get a SST if you FST yourself.

pp 11-68 section 11.8.7.5, DE. This is set by the CPU _not_ the UDC.

pp 11-73 section 11.8.9.7, UDCCS2 table, bit 2, Should be "valid only

when _TPC_ (not RPC) is set.

pp 11-74 section 11.8.10, should end with a GET_DESCRIPTOR _or

similar_ command. (Like, for example, GET_CONFIGURATION).

8. Change History

'''''''''''''''''

Following are current chages  8Mar01 (released in 2.4.2-rmk1-np2?)

- Resetting UDC when coming out of suspend helped enumeration get

going considerably.

- Added support for client-supplied notify routine to be called

by the USB core when core reaches "configured" state.

- Added error returns from interrupt reads and buffer flush ioctl

calls to usb-char. Added usb-char.h file for ioctl calls.

- Fixed bug that kept usb-char transmitter from working the second

time the module was loaded.

- Turned off a lot of the noise in /proc

- Added specialty routines in ep0 to set and clear bits.

- More enumeration fiddling.

- There are horrible hacks to set max IN length in usb_send

  that ARE GOING AWAY SOON! REALLY!

*** Following changes 26Feb01 (released in 2.4.2-rmk1-np1)

- usb-eth integration with generic usbnet from AC tree.

- Creation of public interface for usb clients in sa1100_usb.h

and final separation into a "core" driver (usb_ctl.c, usb_ep0.c

usb_recv.c usb_send.c) and "client" services (usb-eth.c and

usb-char.c). Modularized.

- Descriptor handling rewritten. Support for string descriptors

added. More bugs in ep0 fixed. More setup packets handled.

- /proc interface in usb_ctl returning

- removed client specific stuff from usbd_info_t and hid the

structure in usb_ctl. Removed RAM-backing of address and pktsize

in this structure. Now the descriptor values are gospel.

- usb_dbg.h eliminated

- Many bugs fixed in usb-char.c

- Fiddled startup sequence so should start everytime.

- Arch specific "soft connect" hook in usb_ctl.c

- Bumped the interation count in write/set/clear macros

in usb_ctl.h up to 10000. This seemed to help various bit

setting in ep0 and usb_send.c.

*** Following changes 10Feb01 release:

- endpoint zero entirely rewitten

- Various changes by Oleg to make Netlink work again after the

  2.4.1-rmk1-np1 release.

- Resetting of new max packet length done after clearing TPC

in usb_send, per Nicolas Pitre.

*** Following changes 23Jan01 (came out in 2.4.1-rmk1-np1):

- Moved host initiated SET/GET feature stall into endpoint code of

usb_send.c and usb_receive.c and removed stallep from usb_ctl.c

Opposite of a SET_FEATURE stall is a reset, so no code to unstall is

provided.

- Added explicit USB state machine to usb_ctl so driver and device

state can be tracked closely and explicitly. Added hard-wired

notification routines in endpoints 1 and 2 so they can track device

state changes as required. State machine has notion of "zombie" state

the covers USB states NONATTACHED, ATTACHED and POWERED since these

are murky, and USB driver currently has no way to differentiate

between the two.

- Reworked ISR in usb_ctl so reset has higher priority than any other

event. Stopped using sync macros to clear interrupt pending flags and set

mask registers since it appears mask register changes are not

always reflected on a mask register read until the pending flag is

cleared (yet other tests show they are always cleared

eventually). Toggle suspend/resume interrupt masks back and forth during

suspend and resume to debounce and keep UDC internal state machine in

sync per Intel documentation.

- Flipped UDC flip, clear, write and set macros from do{}while to

while() loops. Theory is you might save a loop iteration if value

becomes valid immediately. Also, my hardware guy says writes are never

"lost", just pipelined and not executed immediately depending on

internal device conditions (like setting int masks when ints

pending), so moved write cycles in macros outside of loops.

- Added #defines to SA-1110.h for suspend and resume interrupt mask

bits per Intel eratta. Submitted to ARM patch system (444/1).

- Removed task queue and defered execution of configure() from

usb_ctl.

- Removed usb_write_reg() from usb_ctl.c, and various cruft from

usb_ctl.h.

- Added sa1100_usb_xmitter_avail() to usb_send.c. Makes implementing

poll() fileop easier.

- Added sa1100_usb_send_reset() to usb_send.c. Makes implementing

transmitter timeout easier.

- Added API to usb_ctl to set vendor and product ID

- Changed BMATTR descriptor fron int to bulk, when not using netlink. (All

the docs say UDC does not support INT xfers -- though, at the protocol

level I don't see why not, since bulk and int are both just

IN-DATA-ACK. I figure netlink may rely on this, and not just a

continuous pending read from the host, but for "pure bulk" host

polling may not be generally correct.)

- Removed unused rx_lock and tx_lock from usb_ctl

- Converted everyone to SA-1100.h and nuked hardware defines in usb_ctl.h

- Removed udc_init() in usb_ctl.c and folded functionality into udc_start().

- Clear force stall (FST) in udc_start and reset so UDC actually runs when

first turned on.

- Emit NAK in receiver until ep1_start() for error (RPE) case too.

- Remove enable/disable UDC from reset handler in udc_ctl. The UDC has

already been reset, so no need to do this again.

- Explicitly set address to zero in ep0_reset()

- Added "naking" boolean to usb_receiv.c. An attempt to solve a

hypothetical race condition where we are in the critical section

initiating a read from base-level code, a RPC happens, and start()

might clear the condition before the packet is handled by the ISR.