	    This is release v0.4 of XCopilot (9-Apr-1997)
	    
[ This is actually version v0.4-iang8.  My comments to this file are in
  square brackets.  See the end of this file for release notes since v0.4.
  The current version of the v0.4-iang series can be found on

  http://www.isaac.cs.berkeley.edu/pilot/

  - Ian <iang@cs.berkeley.edu> ]

The last "official" release was v0.2. Release v0.3b was an interim
release by Jeff Dionne.

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

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

Improvements over v0.2
======================

  * 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

Building under Linux
====================

Building under linux with gcc should be straightforward. You will need
the Xpm and Xext libraries

In the xcopilot-vxx directory, do

make xcopilot

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.

Building with other systems
===========================

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

You will need to modify the Makefile in each directory (./, mx/ and
mc68k/). There are already alternate definitions for some compiler
flags for SunOS 4.1.4. Those of you on other systems, you will need to
do a little work.

Once the Makefiles have been edited, do

make xcopilot

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 the current
directory 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 serial port simply connects to stdin and stdout, so you can use
redirection to connect to any other port. eg. if your modem is on
/dev/cua1, then do

xcopilot < /dev/cua1 > /dev/cua1

[ Actually, you should now do:

   xcopilot -serial /dev/cua1

 - Ian ]

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 the v0.4-iang series, the -debug flag is deprecated.  You should really
  be using the -gdebug flag, described below.  - Ian ]

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

  * The ram size is 128k. This can be changed by changing the symbol
    RAMSIZE in main.c

[ It's now 1MB. - Ian ]

  * 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 32k will not load unless the scratch size
    is increased. This can be done by changing the SCRATCH_SIZE symbol
    in mc68k/memory.h

[ This has been increased to 64k, and it can't get any larger.  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

  - Ian ]

  * People have had problems with the X shared memory extensions. If
    you have problems, try using the -noxshm option. This is definitely
    a problem when running from a remote cpu.

[ X shm should now be auto-detected.  You can still use -noxshm to _force_
  no shared memory.  - Ian]

  * 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

------------------------
Stuff from here on has to do with the v0.4-iang series, by Ian Goldberg
<iang@cs.berkeley.edu>.

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.

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

   - Ian Goldberg <iang@cs.berkeley.edu>
