This document accompanies the Copilot source code, and gives an outline of each module and its function. This information is intended to assist developers who wish to port Copilot to platforms other than Win32.

Copilot is divided into two major modules: The user interface and debugger module, and the CPU emulation module. Under Win32, the user interface and debugger reside in copilot.exe, and the CPU emulation is found in pilotcpu.dll. There is a well-defined interface between the user interface and the CPU emulator. This interface can be found in pilotcpu.h. There is no particular reason that the CPU emulation code is in a different executable module (it could be linked into the main code module).

The CPU emulation code is based on the DOS port of the Un*x Amiga Emulator (UAE) by Bernd Schmidt. None of the detailed CPU emulation code needed to be changed, which was good because it is non-trivial.

There will be three major problems encountered when porting Copilot to a different platform: User interface code, byte order, and threading.

The user interface code in Copilot is obviously Windows-centric. Most of the interaction with the user can be found in lcd.cpp. The window presented to the user is a fairly straightforward user interface window - it draws some pretty graphics on the screen, refreshes the LCD display on a timer tick, and passes mouse clicks and hardware button press information to pilotcpu.dll. Also in this module is the Properties page for persistent settings, and other miscellaneous user interface stuff.

The byte order on Win32 machines is little-endian (the least significant byte in a multi-byte numeric value is stored in at the lowest memory address). The byte order on the DragonBall CPU is big-endian. This means there is all kinds of byte swapping in various places in the CPU emulation code (mostly in memory.cpp). When porting Copilot to a big-endian machine, all the byte swapping will have to be undone. Note that both the RAM and ROM areas are stored with each word already swapped. This is done so that instruction fetches (the most common memory operation) can be performed without swapping bytes.

• Main process thread. Doesn't actually do anything right now, but it's there for future GUI debugger support.
• LCD display thread. This thread maintains the Copilot display window.
• CPU thread. Inside pilotcpu.dll, there is a thread whose sole purpose is to run the CPU emulation. This thread is suspended and resumed as functions in pilotcpu.h are called.
• Debugger thread. When the user requests the debugger, a new thread is created for the debugger user interface. This thread runs in the process' console window (the process console is created if it does not already exist).
• Serial communications receive thread. The Win32 serial communication architecture requires that a new thread be created to receive comm input. This thread performs that function.

Depending on the type of thread support provided by your target operating system, this arrangement may work for you, or it may need to be changed. The synchronization between threads is done using various Win32 synchronization mechanisms, drop me a note if you have any particular questions about this.

Miscellaneous Notes

The Pilot RAM area is automatically stored on disk using a memory mapped file. Changes made in memory are updated in the file on disk by the operating system. There is no explicit "save RAM area" operation in Copilot; if your environment does not provide an equivalent to memory mapped files, an explicit save will need to be performed somewhere.

All the code in pilotcpu.dll does not rely explicitly on the Win32 header files. However, several Win32 functions were needed and they have been prototyped in win.h. The main reason the Win32 header files are not included is the original UAE code defined types like WORD as a signed 16-bit integer, which is different from the Win32 WORD (unsigned 16-bit integer). Very bad things would happen to the CPU emulation code if WORD were changed to an unsigned integer.

In custom.cpp, accesses to DragonBall registers that are not explicitly handled cause an "__asm int 3" instruction to be executed. This is a breakpoint on Intel CPUs, and will terminate the program immediately unless a debugger is running. I don't know of any currently available Pilot applications that trigger this case.

I have included a copilot.mdp file (Visual C++ project file) if you want to compile Copilot on a Windows machine. The copilot.mak file is automatically generated by VC++ and is a real pain to read. There aren't any complicated dependencies in Copilot; if you need to create a make file, just compile everything and link it all together.

The debugger was written by Darrin Massena (Pilot Software Development). I don't know all the details about how the debugger works, specific debugger questions should probably be directed to Darrin.

The Source Modules

User Interface and Debugger (copilot.exe)

api.cpp

Contains a table which lists all the PalmOS API traps and their human readable names.

collect.cpp

Debugger support code (collection classes).

copilot.cpp

Main program module. Doesn't do much except kick off other threads.

cpudefs.cpp

Definitions for MC68000 assembly language instructions. Used by the disassembler.

dbgcmd.cpp

Debugger support module.

debug.cpp

Main debugger module. The main entry point here is StartDebugger(). This function creates the debugger thread and returns immediately.

lcd.cpp

Main Copilot display module. This handles the LCD display as well as mouse clicks and hardware buttons.

readcpu.cpp

Disassembler support module.

registry.cpp

Win32 registry routines for saving and loading persistent settings.

rip.cpp

One of Darrin's handy support modules.

romprocnames.cpp

Contains a table which lists all the known ROM functions and their entry points.

settings.cpp

Save and load persistent settings for Copilot.

CPU emulation (pilotcpu.dll)

cpu0.cpp to cpuF.cpp

CPU emulation code for MC68000 instructions.

cputbl.cpp

Dispatch table for all 65536 CPU instruction words.

custom.cpp

Contains all the DragonBall emulation code. This handles all the DragonBall specific registers, as well as subsystems like serial communications.

memory.cpp

Memory emulation code. Will definitely need to be changed if ported to a big-endian machine.

newcpu.cpp

Main loop for the CPU emulation code. Fetches instructions and calls the instruction handler routines through the dispatch table.

pilotcpu.cpp

Glue code that implements the pilotcpu.h interface. This module runs the CPU as a separate thread, so functions like CPU_run() will not block.