PalmPilot software development using Pila

PalmPilot software development
ASDK - Alternative Software Development Kit
(Pila - the assembler for the PalmPilot)

27 Jan 1998 Alan Jay Weiner

Assembly language has fallen out of favor. While modern compilers provide advanced tools for software development, writing in assembly language will almost always provide a smaller, faster program - it is very difficult to beat a well-optimized program written by a good assembler programmer.
Given the nature of the Pilot - limited memory and a relatively slow processor - assembly language should again be considered as a suitable tool.

The ASDK is a collection of user-written tools for developing assembly-language programs for the PalmPilot. The heart of it is Pila; the assembler. Along with several utilities, the ASDK includes:

Pila assembler
Pilrc resource compiler
Pilrcui resource previewer
Copilot Pilot emulator and debugger
PilDis disassembler

Unfortunately, the tools have not been updated; as the PalmPilot evolves the ASDK will be increasingly out-of-date and more difficult to use.
Pilrc and Pilrcui are used in the GCC Pilot development, and are actively maintained and enhanced by Wes Cherry. Copilot is also used with GCC, but has not had much improvement. Hopefully any future changes will remain compatible with Pila. Despite some interest in enhancing Pila, it has had few changes, and none for over a year.

Advantages to assembler:

small code - can be tightly optimized
fast code - eliminate extraneous operations. Compilers often waste a few bytes here and there with standardized entry and exit code to functions, inefficient register movement and data recalculations, etc. Even the best optimizing compilers are no match to a top assembler programmer.
requires a less-powerful development machine - a 486/33 is quite acceptable

Disadvantages to assembler:

more difficult to develop programs; more instructions to write; more chance of errors
more difficult to manage complex algorithms and data structures
more difficult to debug - lack of debugging aids (asserts, data types, etc.)
Documentation is all C-relative; obscuring the exact arguments for APIs
include files haven’t been updated for OS2, and likely won’t be for OS3

Much of this is a result of primitive tools, but in truth, there is little likelihood the assembler will be improved.

Pila’s built-in function call directives

Pila includes several built-in directives that ease PalmPilot coding. These allow defining and calling functions using C-like argument lists.

As an example, this defines a rectangle structure (locally; on the stack) and calls a system API to draw the rectangle in gray:

proc DrawGreyRectangle()
local rr.RectangleType
beginproc
movem.l d0-d4/a0-a4,-(a7) ;preserve regs

;draw the gray rectangle

move.w #2, rr+RectangleType.topLeft+PointType.x(a6)
move.w #3, rr+RectangleType.topLeft+PointType.y(a6)
move.w #156, rr+RectangleType.extent+PointType.x(a6)
move.w #20, rr+RectangleType.extent+PointType.y(a6)
systrap WinDrawGrayRectangleFrame(#$04FF.w, &rr(a6))

movem.l (a7)+,d0-d4/a0-a4
endproc

Note the systrap line - this is the actual sequence of instructions:

;;systrap WinDrawGrayRectangleFrame(#$04FF.w, &rr(a6))
pea -8(a6)
move.w #$04ff,-(a7)
trap #15
dc.w sysTrapWinDrawGrayRectangleFrame
addq.l #6,a7

The call directive works similarly with user-defined functions.

Note that there is no parameter checking on any of these calls - if you call with the wrong arguments, you will not get any errors or warnings.

Glitches and problems with Pila

Some Palm OS APIs use byte values as arguments. These should be pushed as bytes - not as a word as you’d expect. The systrap and call directives push the byte, and recognizes that the stack will be adjusted by 2 bytes, so cleans up properly when the call returns. It’s important to push the value as a byte since the 68000 is a big-endian machine; pushing a byte puts it into the address of the high-byte of a word.

Pila has several known bugs. Among these are:

Pila has two expression parsers; this is a result of some enhancements that were done by another developer. Darrin intended to merge them together into a single parser, but as development lagged this has never been done. As a result, some expressions will work in one place but fail in others. Embedded spaces cause problems with equates - and will often fail without any warning; they will simply define the wrong value. Don’t use spaces in equates!

Instead of:

foo equ some_len / 2

use:

foo equ some_len/2

The following will crash Pila:

movem.l (a7+),d0-d3/a0-a2

The problem is the plus sign; it should be outside the parenthesis.

The following code crashes Pila:

Appl "Test", 'abcd'

include "Pilot.inc"
include "startup.inc"

NNUM equ 8

struct struc1
val.NNUM
endstruct

data

global xxx.struc1

The bug appears to be a combination of defining a structure size based on an equate, and allocating a global of that structure

Despite the negative tone to much of this document, a number of applications have been developed using Pila and the ASDK - my own AlCalc among them.

The lack of source-code-debugging in Copilot is less of a concern with assembly language - after all, the debugger’s disassembly is the same as your source-code instructions (less comments and some built-in macro expansions)

Pila is suitable for programmers already familiar with assembly language, or who are interested in providing the smallest possible code size. It would be an acceptable environment for learning assembler, however dealing with glitches such as API arguments that aren’t clear, or Pila token-parsing issues would be extremely difficult for beginning programmers.

After working with Pila for a while, most of the problems become second nature - it evolves into a quite comfortable development system.

Internet resources:

Darrin Massena’s Pilot development pages - http://www.massena.com/darrin/pilot
Pila (and other tools) are on http://www.massena.com/darrin/pilot/tanda.htm

Documentation for the Motorola Dragonball is at http://www.mot.com/SPS/ADC/pps/_subpgs/_documentation/328/index.html

Return to my home page