xcopilot(1) · carta

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.

DEVELOPMENT

http://www.hewgill.com/pilot/copilot/index.html

Officially Supported Palm OS Emulator from 3COM http://palmpilot.3com.com/devzone/pose/seed.html

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 ][email protected][gt ]

Bug Reports to [lt ][email protected][gt ]