USB driver hints for Solaris
When putting together my
Wacom tablet driver and others,
I hit a few conceptual walls in understanding USB better.
So I thought I would distill a few critical points here as I go.
Sure, you could read the full
USB 1.1 specification
but that would most likely give you a headache ;-) So read the tips here to
get you oriented.
Assumptions
I assume that you have had SOME exposure to solaris driver writing.
If not, you should probably first go read Sun's
"Writing Device Drivers" document. Search the online docs at oracle,
or see if the link on my TIPS page is up to date.
For a slightly condensed version, you might try
Sun's
Driver writer orientation.
(This is actually titled
"Solaris OS on x86 Platforms - Device Driver Writer's Orientation", and
the link is still valid as of Oct 2011)
You might also want to read my
Solaris driver developer tips
Data Transfer Types
The key thing to keep in mind is that there are specific types of data
transfer allowed with a USB device. Not all devices support all types of
transfer. In fact, most devices will only
- Control data
- Stuff to tweak the device with, or get special info about it.
All devices must support control messages
- Bulk data
- For when you want to move "large" chunks of data.
You don't care too much when it gets there, as long as it gets
there.
- "isochronos" data
- Basically, real-time and/or non-critical data. Think of it as
streaming life video. You dont care too much if you drop a frame
or two, you just want the data to keep coming
- Interrupt data
- "Interrupt-driven". EG: the user presses the "abort" key on the
device.
Data Pipes
To use one of the above data transfer types, you first
have to open a pipe
. A "Pipe" is sort of like a TCP socket
connection. You have to open up a connection before you can start sending
data. You cannot just start poking at registers somewhere.
To open a pipe, you have to first know which endpoint
on the
device to
use. (with the exception of a control pipe, which is special).
When first starting to write a
USB device driver, if you do not already know the endpoint idenfiers, you
must query the device for which endpoints it has,
check the type of each and use the appropriate one. Make sure that you
check that the one you want is available. For example, a graphics tablet
will probably not offer a "bulk transfer" endpoint at all.
Interfaces and 'Alt'ernate settings
Every USB device has at least one 'interface'. An interface is anything
that has a unique USB ID, even though it has a single physical packaging.
For example, a combined keyboard+mouse may be a single physical box, but
there would be two 'interfaces'.
Any particular 'interface', may have multiple 'alternate' settings
(Although most devices only have 1 setting). If you configure an interface
to a non-default 'alternate' setting, you may have a completely new set of
endpoints available to you.
Unfortunately, it is not a simple thing to configure an alternate config
under the current Solaris USB framework.
Tips for Solaris 8 USB
(as of June 2002)
The following tips are all specific to the "current" solaris USB framework.
The Sun USB team has announced that there is a new USB framework coming
down the pike. No official date for it has been set, so it seems safe to
assume it will not be released for a few months.
Getting an endpoint
Currently with solaris 8, you have to use usb_parse_endpoint_descr() to get
an "endpoint descriptor". Once you have that, you can pass the descriptor
to usb_pipe_open() to open up a pipe to use. If you want a control pipe,
you pass in a NULL endpoint descriptor.
Note: the upcoming new solaris USB API does not use usb_parse_endpoint_descr().
Reading data
You should read the comments in /usr/include/sys/usb/usbai.h, particularly
the "Data Transfer Management
" section. Some critical
excerpts:
- "ALL data transfer[s] are asynchronous"
- Bulk input pipes must be prodded by usb_pipe_receive_bulk_data(),
after which the callback will be called when the data is ready.
- Isoc and intr pipes will automatically trigger the callback as soon
as any data is ready. No prodding required. But you will have had to
call usb_pipe_start_polling() already.
Writing data
The same comment from above is still true:
"ALL data transfer[s] are asynchronous"
You first call the appropriate send function, and then wait for a
callback to trigger if you care about the result of the send.
- For Isoc endpoints, use usb_pipe_send_isoc_data()
- For Bulk endpoints, use usb_pipe_send_bulk_data()
- For Control endpoints, use usb_pipe_device_ctrl_send(). There
is actually a sync version of it, I guess because
control data isnt officially a "data transfer"
- Unfortunately, there is no official way to write through
an "out" interrupt pipe with the initial solaris USB framework.
Note: It appears that the "*bulk*" routines do byteswapping as appropriate.
However, the other ones (eg: xxx_ctrl_xxx) do not.
Written by:Philip Brown
Visit the Solaris driver pages
at bolthole.com.
Or Search Bolthole.com