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