10
10
Why do I want to use libusb?
11
11
--------------------------------------------------------------------------
12
12
libusb is an alternative way of communicating with USB devices
13
on Linux, Unix, Mac OS X and Windows machines.
13
on Linux, Unix, Mac OS X and Windows machines.
15
15
In the Linux world, Palm devices using USB would require the
16
Linux kernel's "visor" driver, written and maintained by Greg
17
Kroah-Hartman. A lot of work and testing has been put into the
18
visor driver over the years and it is very solid, but making
19
sure that it remains current with released Palm devices can be
22
The current version of the visor driver allows you to insert it
16
Linux kernel's "visor" module, written and maintained by Greg
19
A lot of work and testing has been put into the visor module
20
over the years and it is very solid, but making sure that it
21
remains current with released Palm devices can be problematic,
22
because the devices coming out are always different and some
23
can require special handling.
25
The current version of the visor module allows you to insert it
23
26
into the kernel namespace with the proper Palm product and
24
vendor values, so modifying the driver's source code and
25
rebuilding it is no longer necessary as it was early on.
27
vendor values at runtime (described in README.usb), so
28
modifying the module's source code and rebuilding it is no
29
longer necessary as it was with earlier versions of the visor
27
Using libusb, you no longer have to use the visor driver, and
28
you can talk directly to the device. In short, libusb requires
29
less maintenance overhead, and is MUCH faster to use with
32
Using libusb, you no longer have to use the visor module, and
33
you can talk "directly" to the device. In short, libusb
34
requires less maintenance overhead, and is MUCH faster to use
35
with current Palm devices (roughly 200% to 600% faster,
36
depending on your Palm's processor speed and the type of
37
records you are syncronizing across. YMMV, of course.).
33
40
Why is visor so slow? Why is libusb so much faster?
34
41
--------------------------------------------------------------------------
35
42
In testing, syncronizing a Palm device with libusb has been
36
43
shown to be anywhere from 200% to 600% faster vs. using the
37
kernel visor driver. The kernel visor driver itself is not
38
"slow", there are just more kernel interfaces to pass through,
39
which slows down the communication between kernel and Palm.
46
The kernel visor module itself is not "slow", there are just
47
more kernel interfaces to pass through, which slows down the
48
communication between kernel and Palm.
41
50
It has never been optimized for speed, and certainly could be,
42
if someone was interested in doing so.
51
if someone was interested in doing so. The primary maintainer
45
55
Does it work with every device?
46
56
--------------------------------------------------------------------------
47
It works with every device I've personally tested it with. Some
48
devices behave very differently with respect to the "timing"
49
between the point where you hit HotSync and the time libusb
50
recognizes it on the bus, but everything I've used with it
57
It works with every device I've personally tested it with,
58
which isn't saying much. This includes an m505, T2, T3, Treo650
59
and Treo680 device. They all work over libusb without too much
62
Some devices behave very differently with respect to the
63
"timing" between the point where you hit HotSync and the time
64
libusb recognizes it on the bus, but everything I've used with
65
it seems to work once I get a feel for the right timing.
53
67
Does that mean it will work with every device? No. We need
54
testers to make sure it works reliably.
68
testers to make sure it works reliably.
70
If you have a device that doesn't work with libusb, we want to
57
74
How do I use libusb, assuming I have all the pieces?
58
75
--------------------------------------------------------------------------
59
76
Simply pass the port of 'usb:' (without the quotes) as the port
60
designation when using any userland conduit found in
61
pilot-link. Some examples of that are:
77
designation when using any pilot-link or GUI conduits or tools.
78
Some examples of that are:
63
80
pilot-xfer -p usb: -b $HOME/Palm/backups
88
109
You'll also need the 60-libpisock.rules file included in the
89
110
latest pilot-link release. A copy of the current file can be
90
found at the following URL:
92
http://code.pilot-link.org/60-libpisock.rules
94
Let's go through each program and see what we need here:
111
found at the following URL, and will always be updated to
112
reflect the latest changes or additions:
114
http://cvs.pilot-link.org/index.cgi/doc/60-libpisock.rules
116
Let's go through each item above and see what we need here:
97
119
---------------------------------------------------
98
120
First, you'll need to grab a copy of the latest release
99
of pilot-link 0.12.0 or later. libusb does not work
100
with pilot-link v0.11.8, and there's no code in
101
pilot-link 0.11.8 to use libusb, so you can't use that
102
version or anything earlier than that.
104
You MUST use 0.12.0 or later to use libusb.
121
of pilot-link 0.12.0 or later. libusb does NOT work
122
with pilot-link v0.11.8 or previous versions. There is
123
no code in pilot-link 0.11.8 to use libusb, so you
124
can't use that version or anything earlier than that.
126
You MUST use 0.12.0 or later to use libusb. Stick with
127
the latest public release (and not CVS versions) and
130
CVS versions tend to include some unstable code being
131
put there for other developers to test, and may
132
sometimes break, so its best to stick with a public,
107
136
---------------------------------------------------
108
137
libusb should be a part of your current Linux or
109
138
FreeBSD distribution. If it isn't, you can install it
110
139
with the standard Linux package management tools for
140
your distribution (apt-get, yast2, yum, etc.)
113
142
On Debian, this is as simple as:
136
171
LEAST 0.70 or later. Anything earlier will cause
137
172
problems, and we cannot support it.
174
BIG FAT WARNING: Do not... I repeat, do NOT try to
175
build and install udev from source. The documentation
176
that comes with it warns against it, and it WILL break
177
things. Don't do it. Use your distributions package for
178
it and you'll be fine.
140
181
How do I configure these pieces on Linux?
141
182
--------------------------------------------------------------------------
144
185
Assuming you have all of the prerequisites above, and have
145
compiled (but NOT installed) pilot-link 0.12.0 against libusb,
146
and that it reported a successful libusb implementation at
147
configure time, you can proceed.
186
compiled (but NOT installed!) pilot-link 0.12.0 against libusb
187
(described below, don't worry), and that it reported a
188
successful libusb implementation at configure time, you can
149
191
setting up the rules file for udev
150
192
---------------------------------------------------
151
193
We need to configure and restart udev first, and since
152
194
its the easiest of the pieces, we'll start there.
154
Put the 60-libpisock.rules file in
155
/etc/udev/rules.d/ and restart udev.
196
Put the 60-libpisock.rules file that came with your
197
pilot-link release in '/etc/udev/rules.d/' and restart
157
Check that the file was read by udev by looking at the
158
udev logs in /var/log (if you log, if not, enable
159
logging in /etc/udev/udev.conf and restart udev to
160
verify), or use the following to enable logging at
200
Check that the file was read and parsed by udev by
201
looking at the udev logs in /var/log (if you log, if
202
not, enable logging in /etc/udev/udev.conf and restart
203
udev to verify), or use the following to enable logging
163
206
udevcontrol log_priority="debug"
208
Check that it saw the new file and has correctly parsed
165
211
mount the kernel's usbfs
166
212
---------------------------------------------------
167
213
Make sure you have usbfs mounted, which can be found in
176
222
applications still use /proc/bus/usb, so we'll mount it
177
223
until that gets deprecated.
179
blacklist the kernel visor driver
225
blacklist the kernel visor module
180
226
---------------------------------
181
227
In order to use libusb, you'll want to make sure the
182
kernel "visor" driver does NOT load when it sees a Palm
183
device connecting to the USB root hub on your system.
228
kernel "visor" module does not automatically load when
229
it sees a Palm device connecting to the USB root hub on
185
232
udev method (for newer udev versions, no hotplug)
186
233
-------------------------------------------------
187
234
If your udev is new enough and you no longer use
188
235
hotplug, you can use the following process to blacklist
191
Simply add 'blacklist visor' to
192
/etc/modprobe.d/blacklist-palm. If that file doesn't
238
Simply add the two words 'blacklist visor' (without
239
quotes) to a new file called:
241
/etc/modprobe.d/blacklist-palm
243
If that file doesn't exist, create it and put the
244
one-line entry into it.
195
246
older method (for systems still using hotplug)
196
247
-------------------------------------------------
197
248
You can blacklist list by adding 'visor' to the
198
249
/etc/hotplug/blacklist file to stop hotplug from
199
loading it at connect time. Restart hotplug to re-read
250
loading it at connect time.
252
Don't forget to restart hotplug to re-read the
203
256
---------------------------------------------------
209
262
Direct USB support...... : yes, libusb
211
264
If you do not see that, you are missing some critical
212
build dependency. Check config.log, search for libusb
213
and see what went wrong. Remember, you'll need the
214
libusb headers to build the support into pilot-link for
215
it, not the runtime. This will be a libusb-dev or
216
libusb-devel package on most distributions.
265
build dependency (such as the libusb development
266
package, which includes the necessary header files to
267
provide this support).
269
Check config.log, search for libusb and see what went
270
wrong. Remember, you'll need the libusb headers to
271
build the support into pilot-link for it, not the
272
runtime. This will be a libusb-dev or libusb-devel
273
package on most distributions.
218
276
How do I configure these pieces on OS X?
219
277
--------------------------------------------------------------------------
317
376
Florent Pillet, "fpillet" on irc, for helping fix up libpisock
318
377
to work on OSX and doing testing on newer devices to work out
319
the various Heisenbergs found in there.
378
the various Heisenbergs found in there. His work has been
379
invaluable over the last year or two with usb, devices and OS X
321
382
Zephania Hull, "Mercury" on irc for spending the time and
322
383
effort to get libusb worked out on the Linux side. Without his
323
384
effort, libusb wouldn't be where it is today.
386
Other thanks go to Knghtbird, Nicholas Piper, Adriaan de Groot,
387
John Marshall, Kenneth Albanowski and many others through the
388
years for helping bring this to where it is today. If I've
389
forgotten to mention you, just let me know.
added
removed
doc/README.libusb
