This is release v0.6.5 of XCopilot (12-Aug-98)
	    
This release was done by Gene McCulley <mcculley@cuspy.com>.  The last
"official" release from Ivan Curtis was v0.2. Release v0.3b was an
interim release by Jeff Dionne.  A lot of stuff was added in the
v0.4-iang series by Ian Goldberg <iang@cs.berkeley.edu>.

Please note that this is still very ALPHA software, so expect
problems. Please send me any bug reports (or better yet, fixes) you
discover.

Thanks to Kresten Krab Thorup <krab@daimi.aau.dk> for the endian patches
Thanks to Andrew Pfiffer <andyp@co.intel.com> for 16bpp and keyboard patches

Building
========

Building should be straightforward. You will need the Xpm and Xext
libraries

In the xcopilot-vxx directory, do

./configure
make

this will make the libmc68k.a library in the mc68k directory, libmx in
the mx directory, and leave the executable xcopilot in the current
directory.

Running
=======

You will need a Pilot rom image file installed in ~/.xcopilot as
"pilot.rom". Please see the original copilot documentation for details
on how to get this file.

do

xcopilot -u 

for a brief command line synopsis.

The emulated serial port can be hooked to any device.  eg. if your
modem is on /dev/cua1, then do

xcopilot -serial /dev/cua1

Debugging
=========

To enable debug mode, run with the command switch -debug.  This will
start the debugger listening to socket port number 2000. To connect to
the debugger, use telnet e.g.

telnet localhost 2000

The debugger starts with the cpu stopped. You must explicitly start
the cpu for anything to happen (use the "start" command).

You should not issue the "load" command until after the welcome screen
has gone away.

Since the ram state is saved from run to run, once an app is loaded it
persists until deleted, or the pilot.ram file is removed.

In this version, the -debug flag is deprecated.  You should really be
using the -gdebug flag, described below.

Potential problems
==================

  * The default ram size is 1MB.  This can be changed by using the
    -ramsize option, but be careful as you don't want to use a RAM
    file for the wrong size.

  * Some systems don't have the ftruncate function. There is a crude
    ftruncate function in memory.c, but I think it clobbers the file
    as well as truncating it. You might want to find a better ftruncate
   (or get a libc with more functionality)

  * The debugger uses port 2000 by default. If this port is not good for you,
    the port number can be changed by changing the symbol DEBUG_PORTNUM
    in main.c

  * Applications larger than 64k will not load.  If you want to
    install larger databases or apps, hotsync them over.  Use:

      xcopilot -serial /dev/ptyqe

    and in another window:

      pilot-xfer /dev/ttyqe -i hugefile.pdb

  * X shm should be auto-detected.  People have had problems with the
    X shared memory extensions. If you have problems running from a
    remote CPU, try using the -noxshm to option.

  * People have had problems with the pixmap code. This could be
    because I am using an older version of Xpm than most people. If
    you have problems, check the code in display.c and the docs for
    your version of xpm.
 
Shortcomings
============

Debugging, breakpointing, tracing support is still very rudimentary.
Expect more in the next release.

I have developed this under i386-linux and SunOS 4.1.1, so there may
be some portability problems, which I will rely on others to point
out.

I would like to coordinate further efforts on this port (certainly I
will be continuing work on it), so if anyone else out there would like
to help out, please contact me.

Anyone interested in modifying this code will benefit from studying
Greg Hewgill's copilot sources, which will need to be obtained
separately.

Ivan Curtis
icurtis@radlogic.com.au

Loading Databases and Programs, and Quitting xcopilot
=====================================================

Holding down the right mouse button while pointing to the xcopilot window
will bring up a little menu.  Drag the pointer to the item of choice and
release the button to select it.  Here are the options in the menu:

Load database...

   This will bring up a menu of the .prc (resource databases or programs),
   .pdb (regular databases), and directories in your current directory
   (as well as ..).  Choosing a directory will bring up a similar menu
   for that directory, etc.  Choosing a .pdb or .prc file will cause
   that database or program to be installed.  You can click on the title
   bar of the menu ("Select File") to cancel the operation.  Note that
   if you are installing a program, an older version of that same
   program should not be running at the time (nor should the
   "Applications" screen).  Also, the xcopilot should not be "off", and it
   should not be still displaying its title screen.  Databases and
   programs that can be installed via this menu are limited in size to
   just under 64K.  If you need to install a larger database, use
   pilot-xfer to install it, as outlined in a previous section.
   If you are using a Palm III ROM, make sure to set the memversion to "2",
   either using the "-memversion 2" option, or by setting the
   XCOPILOTMEMVERSION environment variable to "2".  If you do not do this,
   the Load database... command will not work at all.  If you do this,
   however, it should be able to load databases larger than 64K.

Load file...

   This is just like the previous menu option, but it lists all files, not
   just .prc and .pdb files.  This is useful in case you named your database
   or program with an odd name.

About...

   This just shows some version and credit information.

Quit

   Choosing this option is the recommended way to quit xcopilot.


Debugging with gdb
==================

If you compile a program with gcc, and link it with the -g flag, then you
can debug the program on xcopilot in the same way as on the real Pilot,
but with the added advantage that the debugger doesn't take up the serial
port (so you can debug serial and TCP/IP apps!).

Start xcopilot with the -serial and -gdebug options:

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

The arguments to these options are the ptys to which to attach; the defaults
are shown above.  Make sure you have the "gdb panel" app installed on the
xcopilot; it comes with prctools,and you can install it, as with any app
smaller than 64K, with the menu on the right mouse button.  Install your
program as well.

In another window, run:

  m68k-palmos-coff-gdb progname

Note that you don't enter the .prc suffix here.  You will be given a gdb
prompt, where you 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.


Release Notes
=============

Version 0.4 changes:

  * support for BIG endian machines

  * support for 16bpp displays (only on little endian machines, although it
    will be easy for someone with a big endian 16bpp machine to add that).

  * menu user interface allows loading of .prc files without the debugger

  * keyboard input

  * working serial port

  * debug via a socket

Version v0.4-iang changes:

o Support for Palm Pilot Pro added
   To use it, set the environment variable XCOPILOTROM to point to your
   (1MB) Palm Pilot ROM (not included).  Alternately, if you never want
   to simulate an old Pilot, just name the new ROM "pilot.rom".
o Logging of flow traces
   From the debug prompt ("xcopilot -debug"), "log on" and "log off" will
   toggle logging of major changes in the PC (program counter).  This will
   catch function calls, traps, and returns, but not conditional branches.
o Improved sound support
   Instead of just beeping, the correct frequency/duration/amplitude is used.
o Parameter changes
   The default RAM size is now 1024K, the scratch space is 64K, and
   the time between screen updates is 1/20 second.

Version 0.4-iang2 changes:

o Support for debugging programs with gdb
   To use it, run

   xcopilot -gdebug /dev/ptyqf

   You can, of course, choose a different pty.  You can also just say

   xcopilot -gdebug

   to default to ptyqf.  Then, from gdb, do

   (gdb) target remote /dev/ttyqf

   Note that here you use ttyqf, not ptyqf.  This support should not interfere
   with the virtual serial port, so you can debug programs that use the
   serial port by invoking xcopilot with

   xcopilot -gdebug <> /dev/cua0

   for example.  Try _that_ with a real Pilot!

   NOTE: in order to get the above to work, I needed to know where the debugger
   lived in ROM.  I figured it out for the old Pilot and the Palm Pilot Pro,
   but I don't have access to a Palm Pilot Personal ROM image, so you won't
   be able to use this feature with that ROM (yet).
o Support for multiple RAM files
   Set the environment variable XCOPILOTRAM to the name of your RAM image.
   If it contains a "%d", it will be substituted with the size of the RAM
   (currently 1024).
o Added SO_REUSEADDR to the old (TCP-based) debugging interface.

Version 0.4-iang3 changes:

o Support for greyscale and hardware panning
   Apps that use the 2-bit mode should now work.  I've tested it using my
   "mapview" greyscale and panning demo.

Version 0.4-iang4 changes:

o Support for pixel doubling (from Brian Grossman <brian@SoftHome.net>)
   Use the -double option for a big xcopilot.
o Solaris/AIX portability in libmx (from Brandon Long <blong@uiuc.edu>)
o Backlight emulation (from Kenneth Albanowski <kjahds@kjahds.com>)
o "Load app.." renamed to "Load file.."
o New menu option "Load database.." which is the same as "Load file.."
   except that it only shows .prc, .pdb, and directory files in the list
o Support for sending serial I/O to a pty (-serial option)
   Now, in one window, you can do

   xcopilot -gdebug -serial

   Note that -gdebug defaults to /dev/ptyqf, and -serial defaults
   to /dev/ptyqe.  In a second window, do

   /usr/sbin/pppd /dev/ttyqe 38400 crtscts -detach local passive \
      10.0.0.1:10.0.0.2

   You can use other local:remote IP address pairs if you want.  In fact,
   if your kernel does automatic packet forwarding and you're on a broadcast
   subnet (like most ethernets), make the first address your machine's real
   IP address, and make the second an unused address on its subnet.  Then
   your simulated Pilot will be able to speak TCP/IP to the real world.
   Don't forget to set the phone number to dial to "00" on the simulator,
   and make sure to give it a valid DNS address.  It is rumored that
   the -serial option gives error messages on Solaris (ioctl() returns ENOTTY).

   If you like, in a third window, run m68k-palmos-coff-gdb and attach
   to /dev/ttyqf.  In this way, you can debug TCP/IP apps.

Version 0.4-iang5 changes:

o Added shaped screen and a more realistic background colur (from Chris Bare)
o Automatic determination of whether to use X shared mem (from Chris Bare)
o The display should now look correct on big-endian machines
   (from Brandon Long)
o New options: -bg color (background color), -bbg color (backlight color)
o Added support for gdb debugging via TCP (from Jeff Dionne)
   To use this, pick a port number (say 5432).  Invoke xcopilot as
   (note the colon):

   xcopilot -gdebug :5432

   From m68k-palmos-coff-gdb, do "target pilot hostname:5432", where hostname
   is the name of the machine on which xcopilot is running (usually
   "localhost", but it could be something else).

Version 0.4-iang6 changes:

o XCOPILOTRAM variable is a filename instead of a toggle (from Brian Grossman)
o fixed pixeldoubling colors (from Brian Grossman)
o Smarter screen updates (from Christopher Chan-Nui)
o Added support for gdb debugging for a Palm Pilot Personal ROM
o Trap window closes from the window manager, and shut down cleanly
   (from Eric Howe)
o Alternate icon: icon2.xpm (from Eric Howe)
o File/path environment variable changes (based on a patch from Eric Howe):
   
   File           Default name       Env. var. to override
   -------------------------------------------------------
   ROM file       pilot.rom          XCOPILOTROM
   RAM file       pilot.ram          XCOPILOTRAM
   scratch file   pilot.scratch      XCOPILOTSCRATCH
   log file       xcopilot.log       XCOPILOTLOG

   In addition, if the variable XCOPILOTDIR is set, and any of the above
   variables are _relative_ paths (not starting with '/'), they are taken
   relative to the $XCOPILOTDIR directory.  Note especially that there is
   no longer a number in the RAM file name.

Version 0.4-iang6a changes:

o Bug fixes: power off/on now redisplays properly, menus go away when they're
   supposed to, window manager "Delete Window" should now work

Version 0.4-iang7 changes:

o xcopilot now (finally) supports bus errors: writes to database memory or ROM,
   or misaligned memory accesses will report a bus error (just like the real
   Pilot would); this should be the last major difference in behaviour between 
   xcopilot and the real hardware.  These changes were merged in from the
   sources to the original Copilot.

Version 0.4-iang8 changes:

o The serial port and gdb interfaces have been totally rewritten, so as to be
  _much_ faster.  It is now possible to use pilot-xfer to talk to xcopilot
  over the virtual serial port.  This means you can upload large (>64K)
  programs or databases to xcopilot at speeds higher than 10 characters/sec.
  Running PPP programs on xcopilot is no longer painfully slow.
o Changing the serial port's baud rate now actually works, for most baud rates,
  as do settings for 7/8 bit chars, 1/2 stop bits, E/N/O parity.
o Files ending in .PRC and .PDB (in caps) are now also displayed in the
  "Load Database..." menu.
o Loading files with spaces in their names now works (bug pointed out by
  Diego Zamboni <zamboni@cs.purdue.edu>).

Version 0.5 changes:

* Now defaults to reading and writing files in ~/.xcopilot.  Can still
  be forced to use other directories and filenames with the
  environment variables.

Version 0.5.1 changes:

* ramsize can be set on the command line.

Version 0.5.2 changes:

* Makefile is more clear about where icons go.

Version 0.6 changes:

* XCopilot now uses Autoconf for trouble free portability to many
Unixoid systems.

* Now gets explicitly sized types so that it can work on 64-bit
platforms.  Go Alpha!

* Replaced the strsep function with the one from glibc as the old one
had a small bug with regard to the beginning of the string being a
delimiter.

* Fixed a few small bugs that prevented compilation with the native
compiler under Digital Unix, Irix, and Solaris.

Version 0.6.1 changes:

* Fixed a bug in 2-bit mode while running with pixel doubling on a 16-bit X
  display.

* Goodbye pixel doubling.  Hello arbitrary pixel magnification.

* Added simple dirty rectangle optimization to LCD udpate code.  This
  makes the update a little smoother when using XShm and a lot
  smoother otherwise.

* Fix Makefiles to use ranlib again.  This was accidentally knocked out
  during the autoconfiscation.  Thanks to Dave Glowacki <dglo@SSEC.WISC.EDU>
  for reporting this.

* Autoconf now picks the install program to use.  Thanks to Dave Glowacki for
  pointing this one out too.

* Now minimally requests and handles Expose events.

* Doesn't give an error message when user specifies -noxshm.

* Fixes small signed char bug on AIX 4.1.  Thanks to Peter Trommler
  <trp@zurich.ibm.com> for pointing this out.

* --prefix now works with configure.  Dave Glowacki pointed this one out.

* On HP-UX, it appears that the attached shared memory segments are inherited
  over fork.  This caused errors for the children who were trying to
  attach to the segment that was already attached.  Now we drop the
  segment before forking off the children and reattach it afterward.
  Dave Glowacki provided clues here.

* Now checks for sys/select.h.  Thanks to Peter Trommler for pointing this
  out.

Version 0.6.2 changes:

* Merged Ian Goldberg's patches for Palm III ROM compatibility.

* Can now use a private colormap.

Version 0.6.3 changes (from Ian Goldberg <iang@cs.berkeley.edu>):

* Various fixes for Palm III ROM:
  o gdb debugging
  o Load database...
  o -ramsize 2048 works

* New command-line option: "-memversion vers".  vers should be 1 if you
  are using a ROM <= version 2.x, and it should be 2 for version 3.x.
  The default value is 1, unless overridden by the new XCOPILOTMEMVERSION
  environment variable.

Version 0.6.4 changes:

* Fancy new case supplied by Jon Abbott <muaddib@magicnet.net>.

* Fix for "About" popup race condition on SunOS from Bill Janssen
  <janssen@parc.xerox.com>.

* Lots of good stuff from Brandon Long <blong@fiction.net>:

  * A manpage derived from newly created SGML documentation.

  * A distclean target in the Makefiles.

  * A configure flag to disable XShm completely.

  * A command-line flag to reset the .ram file.

* Fix for case where power was switched off before Quit button hit from Felix
  Croes <felix@simplex.nl>.  In this case, all processes except the CPU
  process would exit.

* Fix for Sparc GUI slowness from Brandon Long <blong@fiction.net>.

Version 0.6.5 changes:

* First steps toward reunification with UAE core and using threads from Max
  Okumoto <okumoto@ucsd.edu>.

* Bail out and give an error diagnostic if we have too low a version of Xpm.

* Fixes so that we may load debug ROMS from Anders Hammarquist
  <iko@iko.pp.se>.  A new option, '-nocheck' exists to inhibit the entrypoint
  checking so that other types of ROMs may be used (e.g. Linux!).

* We now do all option parsing using Xt.  This is the first step in the
  process of doing more stuff in Xt.  We no longer have the XCOPILOT*
  environment variables.  We have only XCOPILOTARGS, which contains a string
  of command line options.  This will unfortunately cause people pain on
  upgrade, but makes it easier to add options in the future.