xcopilot(1)

NAME
XCopilot - A Pilot Emulator for Unix/X11, v0.6.5 (12-Aug-98)

SYNOPSIS
xcopilot [lsqb ]-uU[rsqb ] [lsqb ]-debug [lsqb ]args[rsqb ][rsqb ] [lsqb ]-gdebug [lsqb ]args[rsqb ][rsqb ] [lsqb ]-bg color[rsqb ] [lsqb ]-bbg color[rsqb ] [lsqb ]-noxshm[rsqb ] [lsqb ]-serial ptyname[rsqb ] [lsqb ]-ramsize size[rsqb ] [lsqb ]-magfactor factor[rsqb ] [lsqb ]-double[rsqb ] [lsqb ]-private[rsqb ] [lsqb ]-memversion version[rsqb ] [lsqb ]-reset[rsqb ]

DESCRIPTION
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 -debug 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 -gdebug command-line option.

OPTIONS

-u/-U
    Display usage information

-debug [lsqb  ]args[rsqb  ]
    Enter debug mode. No current arguments are supported.

-gdebug [lsqb  ]args[rsqb  ]
    Enter gdb debug mode, where the optional argument is the TCP port or tty that gdb will connect to. Default is /dev/ptyqf

-bg color
    Specify the display background color

-bbg color
    Specify the display color for the backlight

-noxshm
    Don't use X Shared Memory Extension even if available

-serial ptyname
    Specify a pty for serial I/O

-ramsize size
    Specify the size of the Pilot RAM in kilobytes

-magfactor factor
    Specify the factor by which to magnify the display

-double
    Equivalent to -magfactor 2

-private
    Use a private colormap

-memversion version
    Specify the memory layout version (1 for ROM <= 2.x, 2 for ROM 3.x)

-reset
    Clear pilot.ram to reset XCopilot

ENVIRONMENT

XCOPILOTDIR
    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/

XCOPILOTROM
    Location of the ROM file to use, default is pilot.rom

XCOPILOTRAM
    Location of the RAM file to use, default is pilot.ram

XCOPILOTSCRATCH
    Location of the Scratch file to use, default is pilot.scratch

XCOPILOTMEMVERSION
    Type of memory, the default is 1 (for Pilot I/II). Pilot III is type 2.

XCOPILOTLOG
    Log file of the XCopilot run for debugging, defaults to xcopilot.log

FILES

[tilde ]/.xcopilot/
    Default directory for location of Pilot memory files (ROM/RAM/SCRATCH)

pilot.rom
    Pilot ROM File. See pi-getrom(3) or

    http://palmpilot.3com.com/devzone/rom3/debugrom.html

pilot.ram
    Saved copy of the Pilot RAM

pilot.scratch
    Saved copy of the Pilot Scratch File

xcopilot.log
    File usd to log the execution of code in the emulator, for debugging. You can activate logging via the built-in debugger.

USAGE
Getting Started 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. 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. The Right Mouse Menu 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. NOTE: This method is limited to 64k on ROM <= 2.x

Load database...
    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.

Load file...
    Identical to Load database, except all files are displayed in case you didn't use a .pdb or .prc extension on your database.

About...
    Version/Credit information

Quit
    This is the recommended way to quit XCopilot. The Built-in Debugger When XCopilot is run with the -debug 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:

    linux:[tilde ] [gt    ] telnet localhost 2000
    Trying 127.0.0.1...
    Connected to localhost.
    Escape character is ''.
    command [gt    ]

    The available commands are: help - Give brief help on commands start - start the CPU running stop - Stop CPU running pc - Show current Program Counter (PC) log on[verbar]off - Turn logging to ``xcopilot.log'' on or off load prcfile - Load the application prcfile quit - Quit XCopilot The built-in debugger is now deprecated in favor of using gdb. Debugging with GDB 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:

    xcopilot -serial [lsqb  ]/dev/ptyqe[rsqb  ] -gdebug [lsqb  ]/dev/ptyqf[rsqb  ]

    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:

    m68k-palmos-coff-gdb progname

    Note that you don't enter the .prc suffic here. You will be given a gdb prompt, enter:

    target pilot /dev/ttyqf

    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. 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.

BUGS
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. 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. You can not use the right mouse button menu to load an application/database larger than 64k. Instead, use:

xcopilot -serial /dev/ptyqe
pilot-xfer /dev/ttyqe -i hugefile.pdb

from separate windows. Some systems may not have the ftruncate function. There is one included, but it may not work.

SEE ALSO
pilot-xfer(1) XCopilot Home Page: http://xcopilot.cuspy.com/ Unix Amiga Emulator: http://www.freiburg.linux.de/[tilde ]uae/

DEVELOPMENT
Original MC68000 Emulation Code from the Unix Amiga Emulator Copyright (C) 1995 Bernd Schmidt Original Copilot for Microsoft Windows 95 Copyright (C) 1996 Greg Hewgill [lt ]greg@hewgill.com[gt ] http://www.hewgill.com/pilot/copilot/index.html Officially Supported Palm OS Emulator from 3COM http://palmpilot.3com.com/devzone/pose/seed.html The Original port of Copilot to X Copyright (C) 1997 Ivan A. Curtis [lt ]icurtis@radlogic.com.au[gt ] Colormap support is Copyright (C) 1998 Cuspy Solutions, Inc. Developers include Ian Goldberg, Brian Grossman, Chris Bare, Brandon Long, 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 ]