<!doctype linuxdoc system><manpage title="xcopilot" sectnum="1"><sect1>NAME<p>XCopilot - A Pilot Emulator for Unix/X11, v0.6.5 (12-Aug-98)<sect1>SYNOPSIS<p>xcopilot &lsqb;-uU&rsqb; &lsqb;-debug &lsqb;args&rsqb;&rsqb;&lsqb;-gdebug &lsqb;args&rsqb;&rsqb;&lsqb;-bg <em/color/&rsqb;&lsqb;-bbg <em/color/&rsqb;&lsqb;-noxshm&rsqb;&lsqb;-serial <em/ptyname/&rsqb;&lsqb;-ramsize <em/size/&rsqb;&lsqb;-magfactor <em/factor/&rsqb;&lsqb;-double&rsqb;&lsqb;-private&rsqb;&lsqb;-memversion <em/version/&rsqb;&lsqb;-reset&rsqb;<sect1>DESCRIPTION<p>XCopilot is an emulator for the 3Com/USRobotics Pilot/PalmPilot/PalmIIIthat runs on Unix systems Under X11.  There are two ways to ``connect''to the emulator to assist in debugging your programs.  The first is abit in debugger enabled with the <em/-debug/ command-line option.  See theUSAGE section for more information on the built-in debugger.  Inaddition, you can attach to XCopilot using the GNU Debugger (gdb) withthe <em/-gdebug/ command-line option.<sect1>OPTIONS<p><descrip><tag>-u/-U<p>Display usage information<tag>-debug &lsqb;args&rsqb;<p>Enter debug mode.  No current arguments are supported.<tag>-gdebug &lsqb;args&rsqb;<p>Enter gdb debug mode, where the optional argument is the TCP port or ttythat gdb will connect to.  Default is /dev/ptyqf<tag>-bg <em/color/<p>Specify the display background color<tag>-bbg <em/color/<p>Specify the display color for the backlight<tag>-noxshm<p>Don't use X Shared Memory Extension even if available<tag>-serial <em/ptyname/<p>Specify a pty for serial I/O<tag>-ramsize <em/size/<p>Specify the size of the Pilot RAM in kilobytes<tag>-magfactor <em/factor/<p>Specify the factor by which to magnify the display<tag>-double<p>Equivalent to -magfactor 2<tag>-private<p>Use a private colormap<tag>-memversion <em/version/<p>Specify the memory layout version (1 for ROM <= 2.x, 2 for ROM 3.x)<tag>-reset<p>Clear pilot.ram to reset XCopilot</descrip><sect1>ENVIRONMENT<p><descrip><tag>XCOPILOTDIR<p>Directory where files generated/used by XCopilot are created or lookedfor if the corresponding environment varialbes don't specify a fullpath.  Default is &tilde/.xcopilot/<tag>XCOPILOTROM<p>Location of the ROM file to use, default is <em/pilot.rom/<tag>XCOPILOTRAM<p>Location of the RAM file to use, default is <em/pilot.ram/<tag>XCOPILOTSCRATCH<p>Location of the Scratch file to use, default is <em/pilot.scratch/<tag>XCOPILOTMEMVERSION<p>Type of memory, the default is 1 (for Pilot I/II).  Pilot III is type 2.<tag>XCOPILOTLOG<p>Log file of the XCopilot run for debugging, defaults to <em/xcopilot.log/</descrip><sect1>FILES<p><descrip><tag>&tilde;/.xcopilot/<p>Default directory for location of Pilot memory files (ROM/RAM/SCRATCH)<tag>pilot.rom<p>Pilot ROM File.  See pi-getrom(3) or<code>http://palmpilot.3com.com/devzone/rom3/debugrom.html</code><tag>pilot.ram<p>Saved copy of the Pilot RAM<tag>pilot.scratch<p>Saved copy of the Pilot Scratch File<tag>xcopilot.log<p>File usd to log the execution of code in the emulator, for debugging.You can activate logging via the built-in debugger.</descrip><sect1>USAGE<p><bf/Getting Started/<p>Simplest way to get started is to create a directory &tilde;/.xcopilot andcopy your pilot.rom file to that directory.  Then, run xcopilot.  Youshould see a shaped window resembling the Pilot appear on your Xdisplay.  You should briefly see the ``Welcome to Pilot'' or similarstart-up message, and then you will be asked to calibrate your pointer.Use the left mouse button to click on the cross hairs.  You will then bein the Preferences application, and you can use XCopilot just like thereal Pilot.  The left mouse button acts as the stylus of the real pilot.  You can useit to tap the power button, any of the other buttons, or on the screen.You can use it to write in graffiti in the appropriate area of the LCD.Additionally, you can type, and what you type will be passed toXCopilot, making input easier.<bf/The Right Mouse Menu/<p>Clicking the right mouse button on the running XCopilot brings up alimited menu.  This menu allows you to load a database or file into thepilot directly.  <bf/NOTE:/ This method is limited to 64k on ROM <= 2.x<descrip><tag>Load database...<p>This entry will bring up a file listing of the .prc (resource databasesor programs) and .pdb (regular databases) in the current directory,allowing you to browse the filesystem to the files you want.  Selectinga database will load it into the Pilot.  Selecting the title bar willcancel the menu.<tag>Load file...<p>Identical to Load database, except all files are displayed in case youdidn't use a .pdb or .prc extension on your database.<tag>About...<p>Version/Credit information<tag>Quit<p>This is the recommended way to quit XCopilot.</descrip><p><bf/The Built-in Debugger/<p>When XCopilot is run with the <em/-debug/ command-line option, it startsa third process that acts as a debug server.  This server runs on port2000 (as set by the #define DEBUG_PORTNUM in main.c).  You can accessthis port by using telnet, ie:<verb>linux:&tilde; &gt; telnet localhost 2000Trying 127.0.0.1...Connected to localhost.Escape character is ''.command &gt;</verb>The available commands are:<itemize><item>help  - Give brief help on commands<item>start - start the CPU running<item>stop  - Stop CPU running<item>pc    - Show current Program Counter (PC)<item>log <em/on|off/ - Turn logging to ``xcopilot.log'' on or off<item>load <em/prcfile/ - Load the application <em/prcfile/<item>quit - Quit XCopilot</itemize>The built-in debugger is now deprecated in favor of using gdb.<p><bf/Debugging with GDB/<p>If you compile a program with gcc and link it with the -g flag, you canthen debug the program on XCopilot in the same way as on the real Pilot,with the advantage that the debugger doesn't take up the serial port.To start, start with the -serial and -gdebug options:<verb>xcopilot -serial &lsqb;/dev/ptyqe&rsqb; -gdebug &lsqb;/dev/ptyqf&rsqb;</verb>The arguments to these options are the ptys attach to, the defaults areshown above.  Make sure you have the ``gdb panel'' app installed on theXCopilot (``gdb panel'' comes with prctools).  In another window, run:<verb>m68k-palmos-coff-gdb progname</verb>Note that you don't enter the .prc suffic here.  You will be given a gdbprompt, enter:<verb>target pilot /dev/ttyqf</verb>Note that you use "ttyqf" here, whereas you used "ptyqf" in the xcopilotcommand line.  Of course, if you used something else there, make theappropriate change here.On xcopilot, run the "gdb panel" app and turn on gdb debugging.  Thenrun your app.  gdb will stop your program at its beginning.  You canthen set other breakpoints, and continue.<sect1>BUGS<p>There have been some reported problems using XCopilot with the DEBUG ROM3 available from 3COM.  You are better off downloading the ROM from yourown Pilot.<p>There have also been problems reported using XCopilot on SunOS 4.x andSolaris 2.x, specifically a very long delay before mouse clicks areregistered by XCopilot.  This is under investigation.<p>You can not use the right mouse button menu to load anapplication/database larger than 64k.  Instead, use:<verb>xcopilot -serial /dev/ptyqepilot-xfer /dev/ttyqe -i hugefile.pdb</verb>from separate windows.<p>Some systems may not have the ftruncate function.  There is oneincluded, but it may not work.<sect1>SEE ALSO<p>pilot-xfer(1)<p>XCopilot Home Page: http://xcopilot.cuspy.com/<p>Unix Amiga Emulator: http://www.freiburg.linux.de/&tilde;uae/<sect1>DEVELOPMENT<p>Original MC68000 Emulation Code from the Unix Amiga Emulator Copyright (C) 1995  Bernd SchmidtOriginal Copilot for Microsoft Windows 95 Copyright (C) 1996 Greg Hewgill &lt;greg@hewgill.com&gt;http://www.hewgill.com/pilot/copilot/index.htmlOfficially Supported Palm OS Emulator from 3COMhttp://palmpilot.3com.com/devzone/pose/seed.htmlThe Original port of Copilot to X Copyright (C) 1997 Ivan A. Curtis &lt;icurtis@radlogic.com.au&gt;Colormap support isCopyright (C) 1998 Cuspy Solutions, Inc.Developers include Ian Goldberg, Brian Grossman, Chris Bare, BrandonLong, C. Chan-Nui, Eric Howe and Gene McCulley.The current maintainer of XCopilot is Gene McCulley&lt;mcculley@cuspy.com&gt;Bug Reports to &lt;xcopilot@cuspy.com&gt;<p></manpage>