.if n .ds Q \&".if t .ds Q ``.if n .ds U \&".if t .ds U ''.TH "xcopilot" 1 .tr \&.nr bi 0.nr ll 0.nr el 0.de DS...de DE...de Pp.ie \\n(ll>0 \{\.ie \\n(bi=1 \{\.nr bi 0.if \\n(t\\n(ll=0 \{.IP \\(bu\}.if \\n(t\\n(ll=1 \{.IP \\n+(e\\n(el.\}.\}.el .sp .\}.el \{\.ie \\nh=1 \{\.LP.nr h 0.\}.el .PP .\}...SH NAME.PpXCopilot - A Pilot Emulator for Unix/X11, v0.6.5 (12-Aug-98).Pp.SH SYNOPSIS.Ppxcopilot [lsqb  ]-uU[rsqb  ] [lsqb  ]-debug [lsqb  ]args[rsqb  ][rsqb  ][lsqb  ]-gdebug [lsqb  ]args[rsqb  ][rsqb  ][lsqb  ]-bg \fIcolor\fP[rsqb  ][lsqb  ]-bbg \fIcolor\fP[rsqb  ][lsqb  ]-noxshm[rsqb  ][lsqb  ]-serial \fIptyname\fP[rsqb  ][lsqb  ]-ramsize \fIsize\fP[rsqb  ][lsqb  ]-magfactor \fIfactor\fP[rsqb  ][lsqb  ]-double[rsqb  ][lsqb  ]-private[rsqb  ][lsqb  ]-memversion \fIversion\fP[rsqb  ][lsqb  ]-reset[rsqb  ].Pp.SH DESCRIPTION.PpXCopilot 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 \fI-debug\fP 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 \fI-gdebug\fP command-line option..Pp.SH OPTIONS.Pp.nr ll +1.nr t\n(ll 2.if \n(ll>1 .RS.IP "-u/-U".nr bi 1.PpDisplay usage information.IP "-debug [lsqb  ]args[rsqb  ]".nr bi 1.PpEnter debug mode.  No current arguments are supported..IP "-gdebug [lsqb  ]args[rsqb  ]".nr bi 1.PpEnter gdb debug mode, where the optional argument is the TCP port or ttythat gdb will connect to.  Default is /dev/ptyqf.IP "-bg \fIcolor\fP".nr bi 1.PpSpecify the display background color.IP "-bbg \fIcolor\fP".nr bi 1.PpSpecify the display color for the backlight.IP "-noxshm".nr bi 1.PpDon't use X Shared Memory Extension even if available.IP "-serial \fIptyname\fP".nr bi 1.PpSpecify a pty for serial I/O.IP "-ramsize \fIsize\fP".nr bi 1.PpSpecify the size of the Pilot RAM in kilobytes.IP "-magfactor \fIfactor\fP".nr bi 1.PpSpecify the factor by which to magnify the display.IP "-double".nr bi 1.PpEquivalent to -magfactor 2.IP "-private".nr bi 1.PpUse a private colormap.IP "-memversion \fIversion\fP".nr bi 1.PpSpecify the memory layout version (1 for ROM <= 2.x, 2 for ROM 3.x).IP "-reset".nr bi 1.PpClear pilot.ram to reset XCopilot.if \n(ll>1 .RE.nr ll -1.Pp.SH ENVIRONMENT.Pp.nr ll +1.nr t\n(ll 2.if \n(ll>1 .RS.IP "XCOPILOTDIR".nr bi 1.PpDirectory where files generated/used by XCopilot are created or lookedfor if the corresponding environment varialbes don't specify a fullpath.  Default is [tilde ]/.xcopilot/.IP "XCOPILOTROM".nr bi 1.PpLocation of the ROM file to use, default is \fIpilot.rom\fP.IP "XCOPILOTRAM".nr bi 1.PpLocation of the RAM file to use, default is \fIpilot.ram\fP.IP "XCOPILOTSCRATCH".nr bi 1.PpLocation of the Scratch file to use, default is \fIpilot.scratch\fP.IP "XCOPILOTMEMVERSION".nr bi 1.PpType of memory, the default is 1 (for Pilot I/II).  Pilot III is type 2..IP "XCOPILOTLOG".nr bi 1.PpLog file of the XCopilot run for debugging, defaults to \fIxcopilot.log\fP.if \n(ll>1 .RE.nr ll -1.Pp.SH FILES.Pp.nr ll +1.nr t\n(ll 2.if \n(ll>1 .RS.IP "[tilde ]/.xcopilot/".nr bi 1.PpDefault directory for location of Pilot memory files (ROM/RAM/SCRATCH).IP "pilot.rom".nr bi 1.PpPilot ROM File.  See pi-getrom(3) or.DS.sp.ft RR.nfhttp://palmpilot.3com.com/devzone/rom3/debugrom.html.DE.fi .ec.ft P.sp.IP "pilot.ram".nr bi 1.PpSaved copy of the Pilot RAM.IP "pilot.scratch".nr bi 1.PpSaved copy of the Pilot Scratch File.IP "xcopilot.log".nr bi 1.PpFile usd to log the execution of code in the emulator, for debugging.You can activate logging via the built-in debugger..if \n(ll>1 .RE.nr ll -1.Pp.SH USAGE.Pp\fBGetting Started\fP.PpSimplest 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.  .PpThe 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..Pp\fBThe Right Mouse Menu\fP.PpClicking 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.  \fBNOTE:\fP This method is limited to 64k on ROM <= 2.x.nr ll +1.nr t\n(ll 2.if \n(ll>1 .RS.IP "Load database...".nr bi 1.PpThis 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..IP "Load file...".nr bi 1.PpIdentical to Load database, except all files are displayed in case youdidn't use a .pdb or .prc extension on your database..IP "About...".nr bi 1.PpVersion/Credit information.IP "Quit".nr bi 1.PpThis is the recommended way to quit XCopilot..if \n(ll>1 .RE.nr ll -1.Pp\fBThe Built-in Debugger\fP.PpWhen XCopilot is run with the \fI-debug\fP command-line option, it startsa third process that acts as a debug server.  This server runs on port2000 (as set by the [num   ]define DEBUG[lowbar]PORTNUM in main.c).  You can accessthis port by using telnet, ie:.DS.sp .ft RR.nflinux:[tilde ] [gt    ] telnet localhost 2000Trying 127.0.0.1...Connected to localhost.Escape character is ''.command [gt    ].DE.fi .ec.ft P.spThe available commands are:.nr ll +1.nr t\n(ll 0.if \n(ll>1 .RS.nr bi 1.Pphelp  - Give brief help on commands.nr bi 1.Ppstart - start the CPU running.nr bi 1.Ppstop  - Stop CPU running.nr bi 1.Pppc    - Show current Program Counter (PC).nr bi 1.Pplog \fIon[verbar]off\fP - Turn logging to ``xcopilot.log'' on or off.nr bi 1.Ppload \fIprcfile\fP - Load the application \fIprcfile\fP.nr bi 1.Ppquit - Quit XCopilot.if \n(ll>1 .RE.nr ll -1The built-in debugger is now deprecated in favor of using gdb..Pp\fBDebugging with GDB\fP.PpIf 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:.DS.sp .ft RR.nfxcopilot -serial [lsqb  ]/dev/ptyqe[rsqb  ] -gdebug [lsqb  ]/dev/ptyqf[rsqb  ].DE.fi .ec.ft P.spThe 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:.DS.sp .ft RR.nfm68k-palmos-coff-gdb progname.DE.fi .ec.ft P.spNote that you don't enter the .prc suffic here.  You will be given a gdbprompt, enter:.DS.sp .ft RR.nftarget pilot /dev/ttyqf.DE.fi .ec.ft P.spNote 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..PpOn 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..Pp.SH BUGS.PpThere have been some reported problems using XCopilot with the DEBUG ROM3 available from 3COM.  You are better off downloading the ROM from yourown Pilot..PpThere 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..PpYou can not use the right mouse button menu to load anapplication/database larger than 64k.  Instead, use:.DS.sp .ft RR.nfxcopilot -serial /dev/ptyqepilot-xfer /dev/ttyqe -i hugefile.pdb.DE.fi .ec.ft P.spfrom separate windows..PpSome systems may not have the ftruncate function.  There is oneincluded, but it may not work..Pp.Pp.SH SEE ALSO.Pppilot-xfer(1).PpXCopilot Home Page: http://xcopilot.cuspy.com/.PpUnix Amiga Emulator: http://www.freiburg.linux.de/[tilde ]uae/.Pp.SH DEVELOPMENT.PpOriginal MC68000 Emulation Code from the Unix Amiga Emulator Copyright (C) 1995  Bernd Schmidt.PpOriginal Copilot for Microsoft Windows 95 Copyright (C) 1996 Greg Hewgill [lt    ]greg@hewgill.com[gt    ].Pphttp://www.hewgill.com/pilot/copilot/index.html.PpOfficially Supported Palm OS Emulator from 3COMhttp://palmpilot.3com.com/devzone/pose/seed.html.PpThe Original port of Copilot to X Copyright (C) 1997 Ivan A. Curtis [lt    ]icurtis@radlogic.com.au[gt    ].PpColormap support isCopyright (C) 1998 Cuspy Solutions, Inc..PpDevelopers include Ian Goldberg, Brian Grossman, Chris Bare, BrandonLong, C. Chan-Nui, Eric Howe and Gene McCulley..PpThe current maintainer of XCopilot is Gene McCulley[lt    ]mcculley@cuspy.com[gt    ].PpBug Reports to [lt    ]xcopilot@cuspy.com[gt    ].Pp.Pp