ASDK Overview

Darrin Massena (darrin@massena.com)
9 Nov 96

 Introduction

In late June I wrote an article titled Writing Pilot Applications Under Windows in which I detailed what I imagined as the dream PC-based software development kit for building Pilot applications. Then I compared it against what was available at the time -- only some crude tools I wrote that required Visual C++ Macintosh Cross Development Edition ($1999). I included a handful of ideas on how this might be remedied and invited others to join the effort to create tools everyone could afford and use on their PC.

Since then a number of people have combined efforts to create several tools which are now being used to create Pilot applications. These tools and their documentation are bundled here into what has become known as the Alternative Software Development Kit (ASDK). The ASDK includes an assembler, a resource compiler, a Pilot emulator and debugger, a disassembler, header files, API documentation, and a handful of utilities to aid in the development of Pilot applications. In the future we expect to add a C compiler and other languages to the kit as well as more enhancements to make Pilot software development easier.

For PC owners the ASDK is the alternative to purchasing a Macintosh and the USRobotics/MetroWerks SDK. If you have a Macintosh or are willing to spend the money to buy one the USRobotics/MetroWerks still has a number of advantages over the ASDK, chiefly a complete C compiler, source-level debugger, and an integrated development environment.

Contributors

The ASDK would not be possible without the great contributions of the following people. Each provided one or more essential ASDK components.

Wes Cherry (wesc@ricochet.net) PilRC, PilRCUI, Pila enhancements, HackMaster sample
Greg Hewgill (gregh@lightspeed.net) Copilot, getrom
Bill Hunt (bhunt@ix.netcom.com) PilDis
Scott Ludwig (scottlu@eskimo.com) prc2bmp, exe2prc enhancements
Darrin Massena (darrin@massena.com ) Pila, exe2prc, PilotHack, prc2bin, ASDK organization
Matt Peterson (mattp@usa.net) PilotAPI.hlp
USRobotics (devsupp@palm.com) SDK C header files, MemoPad sample

NOTE: USRobotics has given me permission to redistribute their header files and MemoPad sample in the ASDK. However, they retain the copyright to those files so if you are creating an SDK or development tool of your own and wish to redistribute any USRobotics copyrighted files you must contact them (devsupp@palm.com).

Installation

Create a directory on your hard disk to contain the ASDK files and subdirectories. I recommend naming the directory "ASDK". Extract the ASDK .ZIP file into this directory. IMPORTANT: make sure your unzip program correctly handles long filenames and creates subdirectories as it unzips. For PKUNZIP users this means you must specify the '-d' switch. WinZIP users make sure the "Use Folder Names" checkbox is checked. The 32-bit WinZIP 5.0 or newer running on Windows 95 or Windows NT will do the job.

Before using Copilot you must create a Pilot.ROM file and place it in the bin directory. This involves using the GetROM utilities to copy the ROM code and data from your Pilot. See doc\Copilot.htm for details.

For your convenience, you may want to add the ASDK bin directory to your PATH. This is not required by any of the tools currently included in the ASDK.

Contents

This section briefly describes each of the major components of the ASDK and points to their documentation and World Wide Web support sites for more information.

Tool: Pila -- 68328 Cross-Assembler
Docs: doc\PilaUM.htm
Support: Pila News Page (http://www.massena.com/darrin/pilot/pila.htm), pilot.programmer.pila newsgroup (news://news.massena.com/pilot.programmer.pila)
Description: Pila assembles 68000 assembly language programs, incorporates resources (inline or binary) and writes Pilot-compatible PRC files. It has a number of extensions to make assembly language programming easier, particularly PalmOS API calling, but using it does require knowledge of 68000 assembly language programming.

 

Tool: PilRC -- Pilot Resource Compiler
PilRCUI -- GUI Resource Previewer
Docs: doc\PilRC.htm
Support: ASDK News Page (http://www.massena.com/darrin/pilot/asdk/asdknews.htm)
Description: PilRC processes a resource script file containing text descriptions of Pilot forms, menus, aleters and other Pilot resources and generates binary resource files. The generated binary files are then included in Pila assembly language programs or the resource file of a VC/Mac C program.

 

Tool: Copilot -- Pilot Emulator and Debugger
Docs: doc\Copilot.htm
Support: Copilot Page (http://userzweb.lightspeed.net/~gregh/pilot/copilot/)
Description: Copilot is a Windows-based emulator for the Pilot. It has near-100% hardware emulation, uses the existing Pilot ROM software, and runs unmodified PRC files. The RAM memory size is configurable from 128K to 4MB. Supports Graffiti, hardware buttons, zoom display, backlight, communications, speaker emulation, and PC keyboard input. Copilot also has a built-in assembly level debugger, with support for Pila-compatible symbols.

  

Tool: PilotAPI.hlp -- Pilot API documentation
Docs: <none> 
Support: ASDK News Page (http://www.massena.com/darrin/pilot/asdk/asdknews.htm)
Description: PilotAPI.hlp is a Windows help file containing the Pilot function reference from USRobotic's SDK. All Pilot API functions are documented with hyperlinks between associated topics.

 

Tool: PilDis -- 68000 Disassembler
Docs: doc\Read this first for PilDis.txt
Support: ASDK News Page (http://www.massena.com/darrin/pilot/asdk/asdknews.htm) 
Description: After you extract the code resource from a PRC file, PilDis will decode it into 68000 assembly language instructions. PilDis is PalmOS smart and labels API trap calls with the name of the API.

 

Tool: exe2prc -- utility for converting a Win32 EXE into a Pilot PRC file
Docs: doc\exe2prc.txt
Support: ASDK News Page (http://www.massena.com/darrin/pilot/asdk/asdknews.htm)
Description: Converts a Win32 .EXE file (produced by Microsoft's Visual C++ Macintosh Cross Development Editin) into a Pilot (PalmOS) .PRC file.

 

Tool: getrom.exe and getrom.prc -- Pilot ROM transfer utilities
Docs: doc\Copilot.htm
Support: Copilot Page (http://userzweb.lightspeed.net/~gregh/pilot/copilot/)
Description: The getrom pair of applications are used to create a Pilot ROM file for the Copilot Pilot emulator to execute.

 

Tool: PilotHack -- utility for viewing the contents of a Pilots address space
Docs: doc\pilhack.txt
Support: ASDK News Page (http://www.massena.com/darrin/pilot/asdk/asdknews.htm) 
Description: With Pilot Hack you can view memory in hex, ASCII or as stirngs. Pilot Hack can also translate an API TRAP code into thte corresponding API address, dump input events as they're received, and display the CPU's current registers.

 

Tool: prc2bin -- utility for extracting each individual resource from a PRC file
Docs: doc\prc2bin.txt
Support: ASDK News Page (http://www.massena.com/darrin/pilot/asdk/asdknews.htm)
Description: Prc2bin takes a Pilot resource database (PRC) file and extracts each resource into a separate file.

 

Tool: prc2bmp -- utility for extracting the icon from a PRC file
Docs: doc\Read this first for prc2bmp.txt
Support: ASDK News Page (http://www.massena.com/darrin/pilot/asdk/asdknews.htm)
Description: Prc2bmp extracts application icons from .PRC files and saves them as Widnows .BMP files. 

 

Additional Documentation

USRobotics provides, via FTP, fairly complete API documentation as well as some step-by-step instruction on building a Pilot application (with their SDK tools). This information is essential. Download it from their FTP site, ftp://ftp.netcom.com/pub/pa/palm. You'll need Adobe Acrobat to read it.

Motorola makes the MC68328 "DragonBall" integrated processor that is the heart of the Pilot and they have some great documentation online in PDF form. I highly recommend downloading and digesting the documentation on Motorola's DragonBall page particularly the Motorola M68000 Family Programmer's Reference Manual and the MC68328 (DragonBall) Integrated Processor User's Manual. You'll need Adobe Acrobat to read them.

You should definitely check out the great Pilot Software Development site (http://www.massena.com/darrin/pilot/index.html) hosted by me for the latest dirt on the ASDK and for other Pilot programming tools, tips and tidbits, etc. There's a new page devoted to the latest ASDK News (http://www.massena.com/darrin/pilot/asdk/asdknews.htm).

Some newsgroups for discussing Pilot software development topics are hosted on Pilot Software Development (news.massena.com). Please join us! You can read these newsgroups with your favorite news reader or most Web browsers (Netscape 2.0 or newer, Internet Explorer 3.0 or newer). With a browser, follow these links:

pilot.programmer news://news.massena.com/pilot.programmer
pilot.programmer.gcc news://news.massena.com/pilot.programmer.gcc
pilot.programmer.pila news://news.massena.com/pilot.programmer.pila

Files

This packing list gives a breakdown, by directory, of the files included in the ASDK package.

bin                     - Tool binaries
    Copilot.exe         - Pilot Emulator/Debugger (ver b8)
    debugger.hlp        - Copilot's debugger commands
    exe2prc.exe         - Convert Win32 EXE to PRC (ver
    getrom.exe          - Receives ROM file from Pilot
    getrom.prc          - Sends ROM file from Pilot to PC
    Pila.exe            - Pilot Assembler (ver b3)
    PilDis.exe          - Pilot Disassembler (ver a2)
    PilHack.prc         - Hacking aid (ver 1.1)
    PilotCPU.dll        - Copilot DLL
    PilRC.exe           - Resource Compiler (ver 1.0)
    PilRCUI.exe         - GUI Resource Previewer
    prc2bin.exe         - Resource Extractor
    prc2bmp.exe         - PRC icon extractor/converter

doc                     - Tool documentation
    Copilot.htm         - Copilot documentation
    exe2prc.txt         - exe2prc documentation
    PilaUM.htm          - Pila documentation
    PilHack.txt         - PilotHack documentation
    PilotAPI.hlp        - PalmOS API help file
    PilRC.htm           - PilRC documentation
    prc2bin.txt         - prc2bin documentation
    Read this first for Copilot.txt  - Copilot readme
    Read this first for Pila.txt     - Pila readme
    Read this first for PilDis.txt   - PilDis readme
    Read this first for PilRC.txt    - PilRC readme
    Read this first for prc2bmp.txt  - prc2bmp readme

inc
|   AppBuildRules.h     - USRobotics header file
|   BuildRules.h        - USRobotics header file
|   Common.h            - USRobotics header file
|   Pilot.h             - USRobotics header file
|   Pilot.inc           - Pila header file
|   Pilot.pch           - USRobotics header file
|   Startup.inc         - Pila standard startup file
|   SysBuildRules.h     - USRobotics header file
|
+---Hardware            - USRobotics header files
+---System              - USRobotics header files
+---UI                  - USRobotics header files

lib                     - empty (for now)

Samples
+---MemoPad             - USRobotics MemoPad sample
|       memopad.c
|       memopadr.h
|
+---Pila                - Pila samples
|   +---Sample          -
|           SAMPLE.ASM
|           SAMPLE.BMP
|           SAMPLE.RCP
|   +---HackMaster      - HackMaster extensions using VC/Mac
|           ahack.asm
|           ahack.inc
|           ahack.rcp
|           ahack2.prc
|           mk.bat
|           readme.txt
|           sndtrap.asm
|
+---PilRC               - PilRC samples
|       alhack.rcp
|       resource.h
|       resource.inc
|       resource.rc
+---VCMac               - Visual C++ Macintosh Cross Development Edition samples

src                     - Source code to tools
+---prc2bmp             - prc2bmp source code
        prc2bmp.cpp
        prc2bmp.mak
        swapper.h