Writing Space Invaders for Pilot v1.0 on a PC

-by Scott Ludwig (a.k.a. PilotHacker) (scott@massena.com)
28 Jun 96

Space Invaders for the Pilot was written in C on a PC running WindowsNT, Microsoft's Visual C++ Cross-Development Edition for Macintosh, and Darrin's PC based Pilot SDK, before USRobotic's SDK was available. This SDK makes writing Pilot apps on a PC a reality. Everything about Darrin's SDK was reversed engineered by Darrin with no documentation; I hope he describes everything he went through. I was able to enjoy the fruits of that work in order to create Invaders.

I'm going to document some of the issues I worked through and the tools & tricks I used to do it, in case you plan to develop Pilot apps on your PC with Darrin's SDK.

The first significant issue was debugging. With the PC based SDK there currently is no way to debug instruction by instruction. If you're running on the Pilot, the best case at this point is to use the DbgTrace() calls, which will output strings from the Pilot's com port. If you have a terminal program running, you can insert trace calls and know when things are breaking. Unfortunately this is clumsy - the equivalent to debugging with printf. This also makes HotSync-ing clumsy: you need to close down the HotSync manager and the Pilot Install Tool before using terminal and vice-versa if you are using both off the same com port. To be really fancy here, get a switch box so you can switch your Pilot between com1and com2, or get 2 pilot cradles, one connected to each com port (I didn't have to do this). For quick output, make a macro that calls WinDrawChars() and output strings that way (I did this for most Pilot debugging). The PC SDK includes a printf-style FormatString() that you can use for fancy formatting.

I approached the majority of the debugging problem by making Invaders target both Win32 and Pilot. VC++ includes this nice feature where you can select the output target. By setting all this up, I could select Win32 and build and debug major Invaders functionality under Windows. Once working, I recompiled for Pilot and for the most part this worked great. This required separating the OS specific part into a separate section; I have a version of that section for both Win32 and Pilot. I would do this again for any major app I write, at least until debugging the Pilot directly (either hardware or emulator) is fast and easy.

Most of the Pilot debugging required for Invaders was debugging this OS specific piece. This piece was made as small as possible and was debugged mostly using WinDrawChars() to output strings on the Pilot screen. There were a few other other issues to work around that were not in the OS specific piece:

• Exe2prc doesn't currently support code or data fixups, and VC++ generates them in some cases. This means, for example, if you have a global array of initialized string pointers, the array won't be initialized. If you have a global array of function pointers, it won't be initialized. These are usually fixed up when an application loads (on the Mac or on Windows for example). On Pilot this isn't done, At execution time you'll get mysterious crashes.
• Divide and Mod. When you use / or %, the Microsoft VC++ environment ALWAYS makes references to the library functions __LDIV and/or __ULDIV even if your operands are 16 bit. It wants to call these functions; unfortunately they get called through a globally initialized function array, which needs to be fixedup to work. Oops. I wrote my own versions of these which used a 32 bit dividend and 16 bit divisor and used the 68000 divs instruction which worked for me, and less code as well. Another option is to disassemble the library functions into source code with correctly labeled names and directly link to them. A few notes: the compiler is smart about divide by powers of two, and uses shift instructions to do this: no extra code required. On the retail build, I had a problem where an LDIV reference was being created because of a loop optimization the compiler performed! This required a workaround.
• See Darrin's SDK docs for more standard issues (such as the size of int!)

Spotting these required looking at the 68000 code generated by VC++. I used pem (part of the PC SDK) to do this. Pem acts as a debug target to VC++, and allows you then to use VC++ (while in debug mode) to inspect code, look at mixed C / 68K asm, find a place in your C code and say "go to disassembly" ,etc. Very useful (pem does not allow you to execute your Pilot application, at least at this point in time).

• Another issue was bitmap resources. After some inspection of existing bitmap resources and some work, there is now support in exe2prc to directly translate 1bpp Windows bmp's to pilot bitmap resources, which means you can use the bitmap resource editing tools built into VC++ to make bitmap resources (or any other bitmap editing tool). Simple and convenient! Two hints: The Pilot likes word aligned bitmaps, so try to make your bitmaps a multiple of 16 bits wide to conserve space. Also, exe2prc converts white bits to 0 and black bits to 1 to offer you wysiwyg editing of Pilot bitmaps (since on the pilot, "on" means a black pixel). One last note: if your bitmap resource id is 0x7ffe (32766), exe2prc will make this bitmap resource your Pilot app icon. Note that your icon bitmap should be 32 pixels wide and 32 tall, although only 22 vertical pixel of this icon actually appear in the Application dialog. Check out pilhack to get a nice empty Pilot "black circle" icon to start from the Pilot standard.

Adding sound effects for Invaders was challenging with no documentation. My algorithm: Decode SndPlaySystemSound(), then spend a day goofing around with SndDoCmd() to make reasonably sounding effects by hand. If you have a better way, I'd love to hear it. Even after getting the Pilot SDK directly from USR, it's pretty much a mystery the exact meaning of the SndCommandType structure fields. I have decoded some of it however, and am willing to share with anyone interested.

PilHack was very useful as well. I used it to decode some of the traps I needed (in the Pilot ROM, Darrin discovered that all routines are followed by a zero terminated string which is the name of the routine!), used it to determine the TimGetTicks() timer rate, and used it to determine the event ids and key ids that flowed through an application when various buttons where hit. All very much needed by Invaders.

There you have (most of) the Pilot specific aspects of creating Invaders. I used all aspects of Darrin's SDK (PilHack, Exe2Prc, Pem, and headers) to get Invaders working, and will continue to use it for future Pilot apps.

- Scott Ludwig (scott@massena.com)

Back to Pilot Software Development