Pila News

29 Apr 00
I have not been maintaining/enhancing Pila for several years now. Fortunately, others have picked up the torch and continue to improve Pila. Mikael Klasson and Michael Dreher as well as others have made numerous valuable improvements you'll want to have. Mikael Klasson's web site hosts the newest, most fully featured version that I'm aware of (Pila 1 beta 3 Fluff 7).

18 Jul 99
Al D sent me this tip on a highly relevant site for Pila programmers so I'm passing it along:

> From: Al D [mailto:al_887@hotmail.com]
> Sent: Thursday, July 15, 1999 11:29 PM
> To: darrin@massena.com
> Subject: A site chock full of 680x0 related stuff!(The Pila community
> will love it!)
> 
> 
> This site has disassemblers, compilers, a few tutorials, 
> optimization tips, 
> source code, 8086 to 68k asm converter and much more! Sorry its not 
> specifically pilot related.
> http://www.programmersheaven.com/zone5/cat123/index.htm

1 Jan 98
I received this mail from Benoit Germain pointing out that, contrary to the guess I put forth in the Pila documentation, PalmOS APIs trash not only D0, D1, A0, and A1 but D2 as well. So make sure you're preserving it yourself before calling system routines.

>From: Benoit Germain <bgermain@ubisoft.fr>
>To: Darrin Massena <darrin@massena.com>
>Date: Wednesday, December 10, 1997 1:06 AM
>Subject: API bug
>
>Hi.
>
>In the Pila documentation you state that APIs preserve all registers
>except D0, D1, A0, and A1.
>
>I have however found out that at least one, FntCharsWidth, trashes d2
>without restoring it, which causes all calling APIs (such as
>WinDrawChars) to trash it as well.
>I dont know if this is a bug in PalmOS or if you just did not notice the
>fact when you developed Pila, but I thought it was worth mentioning
>anyway.
>
>Regards.
>
>> Benoit
>> 
>> ---
>> When confronted by a difficult problem, you can solve it more easily
>> by reducing it to the question, "How would the Lone Ranger have
>> handled this?"
>>

1 Feb 97
Wes Cherry has released a new version (1.1) of his Pilot Resource Compiler. This version includes a couple of bug fixes (large numbers of controls), portability enhancements, support for tables, plus some documentation tweaks.

1 Feb 97
Damien Neil has ported Pila to Unix (actually Linux) and I've posted the source code on my Tools and Articles page. Thanks Damien!

1 Feb 97
Andrew Howlett has set up a Pila Source Code Page with example code for Pila programmers. Check there for new samples and send him any code you're willing to share. We all benefit!

13 Jan 97
Motorola is at again moving files around. If you're looking for the 68000 Family Programmer's Reference Manual (and if you don't have it, you should be) you can find it here.

Andrew Grangaard sent me mail informing me that another set of Motorola documentation for the 68328 has moved as well. You can now find it here (better get it quick before they move it again).

1 Jan 97
I'm catching up on some old mail and ran across this good one from Andrew Howlett. Andrew wrote Scribble using Pila and is distributing it along with the source code for curious developers. You can find Scribble and its source on the Pilot Software Archive (scrib10.zip). Thanks Andrew!

> From: Laura and Andrew Howlett <howlett@iosphere.net>
> To: darrin@massena.com
> Subject: Thanks for the help!
> Date: Saturday, December 14, 1996 7:30 AM
> 
> Thanks for your tools for Pilot development. Here's a copy of my 
> first distributable PRC, based on your sample.asm code. I'm
> sending it to Adam's software archive today.
> 
> I thought it was cool how you can pass a pointer to LCD memory
> to SysAppSetPreferences and SysAppGetPreferences. Makes for
> elegant code.
> 
> Hope you find it useful,
> Andrew Howlett.

24 Nov 96
Whoops! I forgot to update this news page when the ASDK Alpha 1 was released (10 Nov 96). The ASDK includes an updated version of Pila (Beta 3) that contains a few minor enhancements.

incorporated Pila into the ASDK package. No more separate Pila releases
added '-t' command line switch to set PRC type
fixed problems in Pilot.inc where fields containing small enumerations
were incorrectly sized as words instead of bytes
added an 'align 2' directive to be emitted after each debug symbol ('-s' switch)
fixed DATA 0 resource format to be compatible with future PalmOS upgrades
fixed other small bugs

The most important change to note is that from now on Pila will only be distributed as part of the ASDK, not a stand-alone package. This minimizes some maintenance headaches for me and provides a more complete, more integrated package of tools for you.

20 Oct 96
Check out the Pila news and discussion group pilot.programmer.pila (news://news.massena.com/pilot.programmer.pila). It's a great place to get help with your programming problems (or help others!). NOTE: this is not a Usenet newsgroup, it is only available from news.massena.com.

20 Oct 96
Wes Cherry has found a few malformed structures in Pilot.inc. They'll be fixed for the next release. The root of the problem is that, bizarrely, MetroWerks C compiler treats small enumerations (values <128) as byte-sized quantities as opposed to the word-sized quantities it uses for larger value enumerations. Wacky. Here's the details:

Wes Cherry <wesc@microsoft.com> wrote in article
<01bbbf19$ab5e6b40$1819369d@tao23>...
> the struct should be changed in pilot.inc to:
> 
> struct SndCommandType
> 	cmd.b
> 	padding.b
> 	param1.l
> 	param2.w
> 	param3.w
> endstruct
> 
> Darrin:  Will you change this in pilot.inc?
> 
> Some other structs in pilot.inc which have similar problems:
> 
> GraphicsStateType: -- fontId should be .b followed by a padding.b.
> ControlType: controlAttr should be .b followed by a padding .b.  
> all the Form*Types w/ attr.w should be attr.b w/ padding.b
> FieldType.fontID: .b w/ padding .b
> TableType.attr: .b w/ padding .b
> ListTYpe.attr: .b w/ padding .b
> MenuBarType.attr: .b w/ pading .b
> FormType:  attr.w w/ padding .w (usr screwed up and defined FormAttrType
to
> be 17 bits)
> Also: the equates for the FormAttrType weren't generated correctly. 
should
> be:
> 
> FormAttrType_usable_shift        equ 0
> FormAttrType_usable_count 	equ 1
> FormAttrType_usable_mask	equ $00000001
> FormAttrType_visible_shift        equ 1
> FormAttrType_visible_count 	equ 1
> FormAttrType_visible_mask	equ $00000002
> FormAttrType_dirty_shift        equ 2
> FormAttrType_dirty_count 	equ 1
> FormAttrType_dirty_mask	equ $00000004
> FormAttrType_saveBehind_shift        equ 3
> FormAttrType_saveBehind_count 	equ 1
> FormAttrType_saveBehind_mask	equ $00000008
> FormAttrType_graffitiShift_shift        equ 4
> FormAttrType_graffitShift_count 	equ 1
> FormAttrType_graffitiShift_mask	equ $00000010
> 
> -Wes

20 Oct 96
Bill Westerman tells me that in Spanish "Pila" means "battery". Well, that's better than the Finnish meaning.

9 Oct 96
A couple of bugs have been found in Pila Beta 2. They are:

The Pila documentation mistakenly omits the "proc" directive in front of the PilotMain procedure definition in section 1.8 (Creating A Minimal Pilot Application With Pila).
Hex constants (actually the '$' character) are not recognized by the new directives ("unknown character"). One workaround is to define an equate for the constant and use it instead.
Not really a bug, but something not covered in the Pila documentation: instructions and directives must be preceeded by at least one whitespace character. Otherwise Pila will assume you're specifying a label and most likely toss a syntax error in your face.
In the Pila documentation (Appendix C: PalmOS API Calling Conventions) I stated that I was unsure whether the register D1 was preserved by PalmOS APIs or not. Greg Hewgill reports that it is not and is trashed almost immediately by the PalmOS trap dispatcher.
On certain syntax errors Pila reports the line the error is in (twice!) but fails to show the erroneous line itself.
If you forget the '#' when passing a numeric constant to one of the call directives (call, systrap, libtrap) then Pila will generate an incorrect instruction. For example, "systrap MemSet(a0.l,4.l,#0.b)" will generate a "move.l ,-(a7)" for the second argument. In this case an assembly error will be printed, just not the one you might expect.

Thanks to Jean-Paul Gavani, Daniel Reznick, and Greg Hewgill for the bug reports. I plan to have all these bugs fixed by the next release.

9 Oct 96
It didn't take long for the first application written with Pila Beta 2 to appear. The day I released Pila Beta 2 I received this mail from Sam Neth regarding his new Hanabi program (download):

> From: Sam Neth <sam@neth.com>
> To: darrin@massena.com
> Subject: Pila Beta 2
> Date: Saturday, October 05, 1996 11:30 PM
> 
> I just wanted to let you know how very cool the new features of Pila
> are.  My code has been transformed dramatically into something
> absolutely readable!  Now that's an assembler.  Thanks so much
> for your contributions to Pilot developers everywhere.
> 
> I'm attaching the alpha of my application, if you're interested.
> I've sent it around, and I'm trying to get it posted to some of
> the better archives.  Post it yourself if you like.  Otherwise,
> I just thought you might like to see what people are doing
> with your work.  I know I would.

Sam's right, I love to hear about the things people are doing with Pila. If you have a Pila application in the works, tell me about it! I'll post it here in the News (unless you mention it's secret).

5 Oct 96
Beta 2 released! Download your copy today [obsolete! Get the ASDK Alpha 1]. You can read the online documentation. New in this release:

added 'align' directive for aligning code/data on user-defined boundaries
added 'list' directive for enabling/disabling listing output
added include path support via PILAINC environment variable
added Copilot-compatible code symbol generation. Specify "-s" and your
app's code symbols will be available while debugging under Copilot
updated Startup.inc to use Wes' new directives (see below)
updated documentation
changed all errors to be output to stdout, rather than a mix of stdout/stderr
added Wes Cherry's PilRCUI, a tool for previewing Pilot form resources, to the Pila package
updated to Wes Cherry's PilRC version .8

Wes Cherry has been extending Pila and has added many new features to make assembly language programming easier and less bug-prone. His new directives and syntax support procedure parameter definition, procedure calling, trap calling, local and global variable definition, and structure definition and
usage. Wow!

the new directives are: call, systrap, syslibtrap, local, global, proc, beginproc, endproc, struct, endstruct, and sizeof
added documentation for new directives to PilaUM.htm! Updated examples, etc to show new syntax
Pila names (e.g., labels, equates) are now case sensitive. Instructions and directives remain case insensitive
updated Pilot.inc to use the new structure syntax. Several incorrect structure member offsets were fixed in the process
updated Sample.asm to use the new directives
fixed the 'end' directive to work as it should and be optional

11 Sep 96
Oops, the first 14 or so downloads (before 9:00AM PST, 11 Sep 96) received a version of Pila Beta 1 with the EXE incorrectly stamped as "Alpha 2". I've updated pila1b1.zip with the correct EXE stamped "Beta 1". The version string is the only difference between the two EXEs.

10 Sep 96
Beta 1 is released! Download your copy today [obsolete! Get Pila Beta 2]. New in this release:

added Wes Cherry's PilRC (0.71), a tool for creating Pilot resources
added Bill Hunt's PilDis (Alpha 1), a tool for disassembling Pilot code resources
added Sample.rcp file to demonstrate resource creation. Sample.rcp replaces mbar1.bin and tfrm1.bin which are removed
added Sample.bat file to build Sample.prc
added special equates to Pilot.inc for the serial library APIs
implemented source file name printing in error messages
implemented a statistics dump after successful assembly. Displays sizes for code, data, resource, and the entire PRC. Keep those PRCs small!
implemented a very minor Startup.inc optimization
fixed bug that was causing line numbers to be offset by one inside include files and off by another one in the 'including' file
fixed a HUGE bug that caused the data section and A5 register to be improperly initialized
updated Sample.asm to demonstrate data section access (amongst other things)
updated PilaUM.htm to incorporate various suggestions I received from Alpha testers, including a new section on the PalmOS API calling convention and a pointer to an online version of the Motorola 680x0 Programmer's Reference Manual -- get it!

15 Aug 96
I received mail from Tuomo Tarvainen in Finland informing me that "Pila" in finnish means "joke"! Swell.

15 Aug 96
I have gone over the 'missing' APIs (as reported below by Stephan Gehring) in detail and here are my findings:

> WinPtr WinGetWindowPointer (WinHandle winHandle)

This is not really an API but one of two macros that convert between window handles and pointers which are secretly the same thing!

#define WinGetWindowPointer(winHandle) ((WinPtr) winHandle)
#define WinGetWindowHandle(winPtr) ((WinHandle) winPtr)

> short FntAccentHeight (void)
> short FntAscent (void)
> Boolean FntProportionalFont (void)

As near as I can tell these APIs don't exist!

> void SysCardImageDeleted (UInt cardNo)
> Ptr SysCardImageInfo (UInt cardNo, ULongPtr sizeP)
> void SysPowerOn (Ptr card0P, ULong card0Size, Ptr card1P, ULong
> DWord sysCardHeaderOffset, Boolean reFormat)
> DWord KeyBootKeys (void)

These APIs are either only available under emulation on the Mac or they're part of a code LIB I don't know anything about. They are not API traps and are only listed in guide1.pdf as "Functions for System Use Only".

> SysCurAppInfoPtr SysCurrAppInfoP (void)

This API is really named SysCurAppInfoP (one 'r').

> void ErrDisplay (char* message)
> void ErrFatalDisplayIf (Boolean condition, char* message)
> void ErrNonFatalDisplayIf (Boolean condition, char* message)

These aren't APIs, they're macros that call the ErrDisplayFileLineMsg API thusly:

#define ErrFatalDisplayIf(condition, msg) \
if (condition) ErrDisplayFileLineMsg(__FILE__, __LINE__, msg)

#define ErrNonFatalDisplayIf(condition, msg) \
if (condition) ErrDisplayFileLineMsg(__FILE__, __LINE__, msg)

#define ErrDisplay(msg) \
ErrDisplayFileLineMsg(__FILE__, __LINE__, msg)

> void SysGrfShortCutListDialog (void)

No trap is defined for this. Does it really exist?

> Err MemPtrFree (VoidPtr p)

Another macro:

#define MemPtrFree( p) \
MemChunkFree(p)

> Err SerClearErr (UInt refNum)
> Err SerClose (UInt refNum)
> Err SerGetSettings (UInt refNum, SerSettingsPtr settingsP)
> Word SerGetStatus (UInt refNum, BooleanPtr ctsOnP, BooleanPtr dsrOnP)
> Err SerOpen (UInt refNum, UInt port, ULong baud)
> Err SerReceive (UInt refNum, VoidPtr bufP, ULong bytes, Long timeout)
> Err SerReceiveCheck(UInt refNum, ULongPtr numBytesP)
> void SerReceiveFlush (UInt refNum, Long timeout)
> Err SerReceiveWait (UInt refNum, ULong bytes, Long timeout)
> Err SerSend (UInt refNum, VoidPtr bufP, ULong size)
> Err SerSendWait (UInt refNum, Long timeout)
> Err SerSetReceiveBuffer(UInt refNum, VoidPtr bufP, UInt bufSize)
> Err SerSetSettings (UInt refNum, SerSettingsPtr settingsP)
> Err SerSleep (UInt refNum)
> Err SerWake (UInt refNum)

The serial APIs to not have unique trap numbers. They're called by first getting the serial library's 'refNum' (call SysLibFind("Serial Library", ...)) then passing it along with other arguments to one of the 'LibTrap' traps. Every library (actually, the serial library seems to be the only PalmOS library so far) supports a common set of traps (Open, Close, Sleep, and Wake) as well as an arbitrary number of custom traps. For example, SerSetSettings is called by issuing a trap #15 followed by the word value sysLibTrapCustom+1. To help with this I've created a new set of equates for the serial library that are prefixed with 'sysLibTrapSer'. So you can call SerSetSettings by issuing a trap #15 followed by sysLibTrapSerSetSettings.

You'll find these new trap values the Pila Beta 1 Pilot.inc file.

12 Aug 96
I received this great bug report from Stephan Gehring regarding APIs that can be found in Pilot's Guide1.pdf and Guide2.pdf documentation but cannot be found in Pilot.inc!

> From: Stephan Gehring <gehring@inf.ethz.ch>
> To: darrin@wherry.com
> Subject: Pila include files
> Date: Monday, August 12, 1996 2:16 PM
> 
> Darrin,
> 
> I have checked the Pila include (PILOT.INC) file against the PalmOS
> documentation (Guide1.pdf/Guide2.pdf). I have found a number of missing
> functions in the Pila include file which should perhaps be added to the
> file in a next version.
> 
> All the best, Stephan
> 
> -------------------------
> 
> Functions I found documented in Guide1/2.pdf but not in PILOT.INC:
> 
> WinPtr WinGetWindowPointer (WinHandle winHandle)
> short FntAccentHeight (void)
> short FntAscent (void)
> Boolean FntProportionalFont (void)
> void SysCardImageDeleted (UInt cardNo)
> Ptr SysCardImageInfo (UInt cardNo, ULongPtr sizeP)
> SysCurAppInfoPtr SysCurrAppInfoP (void)
> void SysPowerOn (Ptr card0P, ULong card0Size, Ptr card1P, ULong
card1Size,
> DWord sysCardHeaderOffset, Boolean reFormat)
> void ErrDisplay (char* message)
> void ErrFatalDisplayIf (Boolean condition, char* message)
> void ErrNonFatalDisplayIf (Boolean condition, char* message)
> DWord KeyBootKeys (void)
> void SysGrfShortCutListDialog (void)
> Err MemPtrFree (VoidPtr p)
> Err SerClearErr (UInt refNum)
> Err SerClose (UInt refNum)
> Err SerGetSettings (UInt refNum, SerSettingsPtr settingsP)
> Word SerGetStatus (UInt refNum, BooleanPtr ctsOnP, BooleanPtr dsrOnP)
> Err SerOpen (UInt refNum, UInt port, ULong baud)
> Err SerReceive (UInt refNum, VoidPtr bufP, ULong bytes, Long timeout)
> Err SerReceiveCheck(UInt refNum, ULongPtr numBytesP)
> void SerReceiveFlush (UInt refNum, Long timeout)
> Err SerReceiveWait (UInt refNum, ULong bytes, Long timeout)
> Err SerSend (UInt refNum, VoidPtr bufP, ULong size)
> Err SerSendWait (UInt refNum, Long timeout)
> Err SerSetReceiveBuffer(UInt refNum, VoidPtr bufP, UInt bufSize)
> Err SerSetSettings (UInt refNum, SerSettingsPtr settingsP)
> Err SerSleep (UInt refNum)
> Err SerWake (UInt refNum)
> 
> ----------------------------------------------------------------------
> Stephan Gehring                            Email:  gehring@inf.ethz.ch
> Institute for Computer Systems             Phone:  +41 1 632 73 15
> ETH-Zentrum                                Fax:    +41 1 632 12 20
> CH-8092 Zurich, Switzerland
>

7 Aug 96

Errors don't report which file the error is encountered in and can be confusing if the error is in an include file.
Line numbers reported within an include file are off by one. This is most apparent in .LIS listing files.
The _sizeof values in Pilot.inc appear to be two bytes too small when the last member of the structure is a pointer. I'm looking into why my Pilot.inc generator is doing this but in the meantime, WATCH OUT!

Back to Pilot Software Development