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 ] 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 for the endian patches Thanks to Andrew Pfiffer 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 . 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 ) Use the -double option for a big xcopilot. o Solaris/AIX portability in libmx (from Brandon Long ) o Backlight emulation (from Kenneth Albanowski ) 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 ). - Ian Goldberg