pkg://xcopilot-0.6.6.tgz:146646/
man/
man1/xcopilot.1
downloads
.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
.Pp
XCopilot - A Pilot Emulator for Unix/X11, v0.6.5 (12-Aug-98)
.Pp
.SH SYNOPSIS
.Pp
xcopilot [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
.Pp
XCopilot is an emulator for the 3Com/USRobotics Pilot/PalmPilot/PalmIII
that runs on Unix systems Under X11. There are two ways to ``connect''
to the emulator to assist in debugging your programs. The first is a
bit in debugger enabled with the \fI-debug\fP command-line option. See the
USAGE section for more information on the built-in debugger. In
addition, you can attach to XCopilot using the GNU Debugger (gdb) with
the \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
.Pp
Display usage information
.IP "-debug [lsqb ]args[rsqb ]"
.nr bi 1
.Pp
Enter debug mode. No current arguments are supported.
.IP "-gdebug [lsqb ]args[rsqb ]"
.nr bi 1
.Pp
Enter gdb debug mode, where the optional argument is the TCP port or tty
that gdb will connect to. Default is /dev/ptyqf
.IP "-bg \fIcolor\fP"
.nr bi 1
.Pp
Specify the display background color
.IP "-bbg \fIcolor\fP"
.nr bi 1
.Pp
Specify the display color for the backlight
.IP "-noxshm"
.nr bi 1
.Pp
Don't use X Shared Memory Extension even if available
.IP "-serial \fIptyname\fP"
.nr bi 1
.Pp
Specify a pty for serial I/O
.IP "-ramsize \fIsize\fP"
.nr bi 1
.Pp
Specify the size of the Pilot RAM in kilobytes
.IP "-magfactor \fIfactor\fP"
.nr bi 1
.Pp
Specify the factor by which to magnify the display
.IP "-double"
.nr bi 1
.Pp
Equivalent to -magfactor 2
.IP "-private"
.nr bi 1
.Pp
Use a private colormap
.IP "-memversion \fIversion\fP"
.nr bi 1
.Pp
Specify the memory layout version (1 for ROM <= 2.x, 2 for ROM 3.x)
.IP "-reset"
.nr bi 1
.Pp
Clear 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
.Pp
Directory where files generated/used by XCopilot are created or looked
for if the corresponding environment varialbes don't specify a full
path. Default is [tilde ]/.xcopilot/
.IP "XCOPILOTROM"
.nr bi 1
.Pp
Location of the ROM file to use, default is \fIpilot.rom\fP
.IP "XCOPILOTRAM"
.nr bi 1
.Pp
Location of the RAM file to use, default is \fIpilot.ram\fP
.IP "XCOPILOTSCRATCH"
.nr bi 1
.Pp
Location of the Scratch file to use, default is \fIpilot.scratch\fP
.IP "XCOPILOTMEMVERSION"
.nr bi 1
.Pp
Type of memory, the default is 1 (for Pilot I/II). Pilot III is type 2.
.IP "XCOPILOTLOG"
.nr bi 1
.Pp
Log 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
.Pp
Default directory for location of Pilot memory files (ROM/RAM/SCRATCH)
.IP "pilot.rom"
.nr bi 1
.Pp
Pilot ROM File. See pi-getrom(3) or
.DS
.sp
.ft RR
.nf
http://palmpilot.3com.com/devzone/rom3/debugrom.html
.DE
.fi
.ec
.ft P
.sp
.IP "pilot.ram"
.nr bi 1
.Pp
Saved copy of the Pilot RAM
.IP "pilot.scratch"
.nr bi 1
.Pp
Saved copy of the Pilot Scratch File
.IP "xcopilot.log"
.nr bi 1
.Pp
File 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
.Pp
Simplest way to get started is to create a directory [tilde ]/.xcopilot and
copy your pilot.rom file to that directory. Then, run xcopilot. You
should see a shaped window resembling the Pilot appear on your X
display. You should briefly see the ``Welcome to Pilot'' or similar
start-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 be
in the Preferences application, and you can use XCopilot just like the
real Pilot.
.Pp
The left mouse button acts as the stylus of the real pilot. You can use
it 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 to
XCopilot, making input easier.
.Pp
\fBThe Right Mouse Menu\fP
.Pp
Clicking the right mouse button on the running XCopilot brings up a
limited menu. This menu allows you to load a database or file into the
pilot 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
.Pp
This entry will bring up a file listing of the .prc (resource databases
or programs) and .pdb (regular databases) in the current directory,
allowing you to browse the filesystem to the files you want. Selecting
a database will load it into the Pilot. Selecting the title bar will
cancel the menu.
.IP "Load file..."
.nr bi 1
.Pp
Identical to Load database, except all files are displayed in case you
didn't use a .pdb or .prc extension on your database.
.IP "About..."
.nr bi 1
.Pp
Version/Credit information
.IP "Quit"
.nr bi 1
.Pp
This is the recommended way to quit XCopilot.
.if \n(ll>1 .RE
.nr ll -1
.Pp
\fBThe Built-in Debugger\fP
.Pp
When XCopilot is run with the \fI-debug\fP command-line option, it starts
a third process that acts as a debug server. This server runs on port
2000 (as set by the [num ]define DEBUG[lowbar]PORTNUM in main.c). You can access
this port by using telnet, ie:
.DS
.sp
.ft RR
.nf
linux:[tilde ] [gt ] telnet localhost 2000
Trying 127.0.0.1...
Connected to localhost.
Escape character is ''.
command [gt ]
.DE
.fi
.ec
.ft P
.sp
The available commands are:
.nr ll +1
.nr t\n(ll 0
.if \n(ll>1 .RS
.nr bi 1
.Pp
help - Give brief help on commands
.nr bi 1
.Pp
start - start the CPU running
.nr bi 1
.Pp
stop - Stop CPU running
.nr bi 1
.Pp
pc - Show current Program Counter (PC)
.nr bi 1
.Pp
log \fIon[verbar]off\fP - Turn logging to ``xcopilot.log'' on or off
.nr bi 1
.Pp
load \fIprcfile\fP - Load the application \fIprcfile\fP
.nr bi 1
.Pp
quit - Quit XCopilot
.if \n(ll>1 .RE
.nr ll -1
The built-in debugger is now deprecated in favor of using gdb.
.Pp
\fBDebugging with GDB\fP
.Pp
If you compile a program with gcc and link it with the -g flag, you can
then 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
.nf
xcopilot -serial [lsqb ]/dev/ptyqe[rsqb ] -gdebug [lsqb ]/dev/ptyqf[rsqb ]
.DE
.fi
.ec
.ft P
.sp
The arguments to these options are the ptys attach to, the defaults are
shown above. Make sure you have the ``gdb panel'' app installed on the
XCopilot (``gdb panel'' comes with prctools). In another window, run:
.DS
.sp
.ft RR
.nf
m68k-palmos-coff-gdb progname
.DE
.fi
.ec
.ft P
.sp
Note that you don't enter the .prc suffic here. You will be given a gdb
prompt, enter:
.DS
.sp
.ft RR
.nf
target pilot /dev/ttyqf
.DE
.fi
.ec
.ft P
.sp
Note that you use "ttyqf" here, whereas you used "ptyqf" in the xcopilot
command line. Of course, if you used something else there, make the
appropriate change here.
.Pp
On xcopilot, run the "gdb panel" app and turn on gdb debugging. Then
run your app. gdb will stop your program at its beginning. You can
then set other breakpoints, and continue.
.Pp
.SH BUGS
.Pp
There have been some reported problems using XCopilot with the DEBUG ROM
3 available from 3COM. You are better off downloading the ROM from your
own Pilot.
.Pp
There have also been problems reported using XCopilot on SunOS 4.x and
Solaris 2.x, specifically a very long delay before mouse clicks are
registered by XCopilot. This is under investigation.
.Pp
You can not use the right mouse button menu to load an
application/database larger than 64k. Instead, use:
.DS
.sp
.ft RR
.nf
xcopilot -serial /dev/ptyqe
pilot-xfer /dev/ttyqe -i hugefile.pdb
.DE
.fi
.ec
.ft P
.sp
from separate windows.
.Pp
Some systems may not have the ftruncate function. There is one
included, but it may not work.
.Pp
.Pp
.SH SEE ALSO
.Pp
pilot-xfer(1)
.Pp
XCopilot Home Page: http://xcopilot.cuspy.com/
.Pp
Unix Amiga Emulator: http://www.freiburg.linux.de/[tilde ]uae/
.Pp
.SH DEVELOPMENT
.Pp
Original MC68000 Emulation Code from the Unix Amiga Emulator
Copyright (C) 1995 Bernd Schmidt
.Pp
Original Copilot for Microsoft Windows 95
Copyright (C) 1996 Greg Hewgill [lt ]greg@hewgill.com[gt ]
.Pp
http://www.hewgill.com/pilot/copilot/index.html
.Pp
Officially Supported Palm OS Emulator from 3COM
http://palmpilot.3com.com/devzone/pose/seed.html
.Pp
The Original port of Copilot to X
Copyright (C) 1997 Ivan A. Curtis [lt ]icurtis@radlogic.com.au[gt ]
.Pp
Colormap support is
Copyright (C) 1998 Cuspy Solutions, Inc.
.Pp
Developers include Ian Goldberg, Brian Grossman, Chris Bare, Brandon
Long, C. Chan-Nui, Eric Howe and Gene McCulley.
.Pp
The current maintainer of XCopilot is Gene McCulley
[lt ]mcculley@cuspy.com[gt ]
.Pp
Bug Reports to [lt ]xcopilot@cuspy.com[gt ]
.Pp
.Pp
