|
Tcpusb - Using PalmOS USB devices with m68k-palmos-gdb
|
Name Last modified Size
[ ] tcpusb-0.2.tar.bz2 30-May-2005 00:40 38k
Tcpusb - A bridge between Palm OS USB devices and m68k-palmos-gdb
-----------------------------------------------------------------
This is the README file for tcpusb version 0.2. Tcpusb is a program to
make it possible to use m68k-palmos-gdb with PalmOS devices via the USB
bus.
Changes since tcpusb-0.1
------------------------
- Fixed Treo 600. Thanks to Deepak Singh for reporting and testing and
Florent Pillet for helping.
Introduction
------------
I did not want to make large changes/additions to m68k-palmos-gdb itself
untill things stabilize.
There are many different variants of PalmOS USB devices (original Visor,
Tungsten series, the new NVFS devices, Treos, Sony variants, TapWave etc.)
and they all need slightly different ways of alking to them via USB.
So I followed the idea of Florent Pillet's MacOS USB-TCP bridge
(http://osx-palm-tools.sourceforge.net) to keep the new code isolated from
m68k-palmos-gdb for the time being.
Using tcpusb on Windows/Cygwin
------------------------------
To use tcpusb need to have installed both libpopt and libusb-win32.
libpopt is included in the standard Cygwin distribution. You need
the libpopt0 package (= the dll containing the library). The current
(May 2005) Cygwin package version is 1.6.4-4.
libusb-win32 can be obtained from http://libusb-win32.sourceforge.net .
The version I used is 0.1.10.1 from 2005-03-09.
You need to install the filter driver: libusb-win32-filter-bin-0.10.1.exe.
Using tcpusb on Linux
---------------------
To use tcpusb you need the packages for libpopt and libusb or equivalent
for your distribution. For libusb see http://libusb.sourceforge.net .
I have used libusb version 0.1.10a.
Note that there is a problem when using this version with the 2.6.11-rcx
kernel versions (usb_bulk_write fails). The major distribution affected by
this is Knoppix 3.8 (Cebit 2005) and Knoppix 3.8.1 which use the 2.6.11-rc3
kernel as far as I know (cost me a few days of searching ....).
Using tcpusb, general description
---------------------------------
The bridge listens to tcp port 2000 (same as the Emulator and Simulator)
and waits for a PalmOS USB device to connect using either the console
or debug port. When both USB and TCP sides are connected all traffic
is forwarded from TCP to USB and vice versa. It is possible to log all
traffic going through the bridge.
The bridge is invoked as: tcpusb [options].
The options are:
-d, --debug=level set debuglevel for libusb
-l, --log=filename log all bridge traffic to file (use '-' for stdout)
-v, --verbose be verbose during device handshake
-p, --port=INT TCP port to listen on (default 2000)
One of my goals is to have the same source code for both Linux and
Windows/Cygwin. This is now feasible by using libusb under Linux
(http://sourceforge.net/projects/libusb) and its Windows equivalent
libusb-win32 (http://sourceforge.net/projects/libusb-win32).
A great thanks to the libusb and libusb-win32 developers.
A lot of the USB device detection code was inspired/copied/stolen from the
pilot-link libpisock code (both the libusb code and the darwin usb code.
Many thanks to David Desrosiers and Florent Pillet).
See http://cvs.pilot-link.org and http://www.pilot-link.org.
I have only been able to test my code with a Tungsten T and a Tungsten T3
on Windows 2000, Windows XP/SP2, Linux 2.4.27, 2.6.8 and 2.6.11,
since those are the only PalmOS USB devices I have available.
Some limited testing was also done with a Handspring Visor.
For tcpusb version 0.2 also some limited testing was done with a borrowed
Treo 600 on Windows XP/SP2 and Linux 2.6.11.
Any help/feedback for other PalmOS USB devices is appreciated.
Comments and suggestions to improve the code are welcome.
If you have problems, please run tcpusb with the '-v' option
and post the output and other details (device, OS version, etc.)
to either the prc-tools-devel list on sourceforge (mail to
prc-tools_devel@lists.sourceforge.net) or to the PalmSource tools
forum http://news.palmos.com/read/?forum=tools-forum or mail to
tools-forum@news.palmos.com if you are subscribed.
Some Usage Tips
---------------
Under Windows/Cygwin there is no need to terminate HotSync.
It should work with HotSync active. At least it does for me.
Under Linux it should work with the visor module active. The code unloads
the visor module when it detects it. If you do not need the visor module
you can disable it in the hotplug blacklist, typically /etc/hotplug/blacklist.
It is always a good idea to first soft reset the PalmOS device before
running tcpusb, so the USB hardware is in a known state.
On the device you need gdbpanel to enable the 'gdbS' feature and
optionally the DevNub or DotDotTwo application to put the device in
console mode.
Of course you can also use shortcut 2 (console mode) or shortcut 1 (debug
mode).
Debugging with Tcpusb
---------------------
Here is a typical debugging scenario. Only gdbpanel and the application to
be debugged are needed on the device.
1. Start the bridge in a terminal window:
$ tcpusb
Tcpusb - A bridge between Palm OS USB devices and m68k-palmos-gdb
Version: 0.2 2005-05-29
Options chosen:
debuglevel = 0
log = <None>
verbose = 0
port = 2000
Waiting ...
2. Start m68k-palmos-gdb in an other terminal window:
$ m68k-palmos-gdb multiapp
....
(gdb) target palmos
The bridge will show a TCP connection:
....
Waiting ...
TCP connection from host 127.0.0.1, port 1186
m68k-palmos-gdb will show:
....
Remote debugging under PalmOS using localhost:2000
Waiting... (Press Ctrl-C to connect to halted machine)
3. On the device run gdbpanel to enable the gdbS feature by selecting
the 'Enable stub' checkbox. Return to the Launcher and start your application.
The app should break in the runtime startup and connect to the USB.
The device display will be blank.
The bridge should now show the device connected:
....
TCP connection from host 127.0.0.1, port 1186
PalmOS PDA connected via USB on debug port
Palm Tungsten series (T, T2, T3), Zire 71
Vendorid = 0x830, Productid = 0x60
Device reports:
Vendor: Palm, Inc.
Product: Palm Handheld
Serial: 00V5A8T31WTW
OSvers: 5.2.1
***** Starting Bridge *****
m68k-palmos-gdb should show a break at PilotMain:
Waiting... (Press Ctrl-C to connect to halted machine)
Program received signal SIGSTOP, Stopped (signal).
PilotMain (cmd=0, cmdPBP=0x0, launchFlags=174) at multiapp.c:61
61 if (cmd == sysAppLaunchCmdNormalLaunch) {
(gdb)
4. Now debug as usual ...
That should be all there is to it ....
Building on Windows/Cygwin
--------------------------
To build tcpusb from source you need to have installed both libpopt
and libusb-win32.
libpopt is included in the standard Cygwin distribution. You need both
the libpopt0 (the dll containing the library) and the popt (docs + include file)
packages. The current (May 2005) cygwin version of both is 1.6.4-4.
libusb-win32 can be obtained from http://libusb-win32.sourceforge.net .
The version I used is 0.1.10.1 from 2005-03-09.
You need the filter driver: libusb-win32-filter-bin-0.10.1.exe.
After installing you have to copy or make a link to the include file usb.h
from typically /cygdrive/c/Program\ Files/LibUSB-Win32-0.1.10.1/include/usb.h
to /usr/include/usb.h .
Similarly for the link library, copy or make a link from
/cygdrive/c/Program\ Files/LibUSB-Win32-0.1.10.1/lib/gcc/libusb.a to
/usr/local/lib/libusb.a or /usr/lib/libusb.a .
A typical commandline for building tcpusb.exe is:
gcc -g -Wall tcpusb.c tcpusb.c usbside.c slk.c logtraffic.c \
-L/usr/local/lib -lpopt -lusb
Building on Linux
-----------------
To build tcpusb from source you need the packages for libpopt, libpopt-devel
libusb and libusb-devel or equivalent for your distribution. For libusb see
http://libusb.sourceforge.net. I have used version 0.1.10a.
A typical commandline for building tcpusb is:
gcc -g -Wall tcpusb.c tcpusb.c usbside.c slk.c logtraffic.c -lpopt -lusb
Note, I have only build and tested it on Linux-ix86 2.4.27, 2.6.8 and 2.6.11.
Licensing
---------
This code is free software and may be redistributed and/or modified
under the terms of the GNU General Public License, either version 2, or
(at your option) any later version. See the file COPYING.
That is all.
Ton van Overbeek, 2005-05-29
tvoverbe@users.sourceforge.net