Palm OS Architecture

By
Kevin Kazmierczak

1
Table of Contents

Introduction – Page 3
Memory – Page 4
The Memory Manager – Page 6
Data Manager – Page 10
Processor – Page 12
Programming the Palm OS – Page 13
Sample Code – Page 14
Conclusion – Page 15
Bibliography – Page 17

2
Introduction

As we move through the years and technology changes, computers become faster
and smaller. The current trend is now in handheld computing. More and more
businesspeople own handheld pc’s to organize their information and their lives. These
small pc’s appeal to people on the go because they are small, easy to use, and extremely
powerful. A person can store all their appointments, tasks, emails, and even browse the
web using a wireless modem on these little devices. When you get home you can sync up
your handheld with your computer and whether you are at home or at a meeting, you will
have the same information available to you.
Currently, there are two different kinds of operating systems run on handheld
pc’s, the Palm OS and Windows CE. The major difference between the Palm
architecture and the Windows CE architecture is that Palm provides free software such as
their development kit and documentation to develop new applications on their devices.
They provide programs for different platforms, so that development is not just limited to
Windows or Linux. One other thing that Palm provides is a Palm emulator. This
program allows you do dump the architecture off your device into a ROM file and then
use the emulator to simulate your actual device. Regardless, some people are loyal to
their Palm and some swear by their Windows CE device. This document will be
introducing the architecture behind the Palm OS, the memory structure, the uses of
databases, a little about the Motorola Dragonball processor, and a small intro on how to
program them.

Memory

The Palm OS system software is designed around a 32-bit architecture. The 32-
bit addresses make the palm able to use up to 4 GB of address space for applications, but
they are designed to work more efficiently with smaller amounts of RAM. For example,
the first commercial Palm OS device had less than 1 MB of memory, or 0.025% of this
address space (Introduction to Palm OS Memory Use).
In the Palm OS, all memory is considered part of a card (Figure 1-1). The card
can have RAM and ROM on the same card. To date, the Palm OS can support up to 256
cards. The ROM contains the operating system, built-in applications, and default
databases, the average size ranges from 512 K to 2M. The RAM contains add-on
applications, system preferences, user data, and run time storage. Ram sizes range from
128K to 2M. The architecture uses 8-bit access on 128K and 512K cards, and 16-bit on
the larger ones. As you can see the bus accesses are reduced on larger cards, which
allows for faster memory access. Currently there are 1-4 additional wait states per bus
access used, for a total of 5-8 CPU cycles per memory read or write (Palm OS Memory
Architecture).
Figure (1-1)

3
 The Palm OS uses various ways of maintaining the memory when the device is
turned off. For the majority of the time, the memory is constantly stored because the
system uses a low power standby mode that keeps it stored. When you remove the
batteries, a super-capacitor maintains the memory for up to 1 minute, after that all the
data is lost. One interesting note is that Palm’s philosophy is that memory loss is not
catastrophic because all necessary user data is regularly backed up to a desktop machine
(Palm OS Memory Architecture).
On the memory cards, RAM and ROM can be mixed together among each other
on the card, it does not need to be all in a row. The entire RAM is considered one store
and the ROM is another. A store is a largely invisible abstraction that is simply a
container for an identifier, a list of heaps, and a database directory (Palm OS Memory
Architecture). The header in the store determines if the RAM is valid to use, if it is
invalid, it needs to be reformatted. RAM and ROM are divided into heaps. There is also
a small amount of RAM that is outside of the heaps that is reserved for low memory
globals, store headers, and other things. Low memory globals are used for different
reasons on different releases.

The Memory Manager

The memory manager is something that is responsible for managing allocations

from the heap. There are three heaps that are controlled by the memory manager;
dynamic, storage, and ROM (Figure 1-2). Heaps contain four different elements, a
header, a master pointer table, chunks, and a terminator (Figure 1-3). The header
contains a unique heap ID, status flags, the heap size, and the master pointer table. It also
contains the information on the size of the heap. The master pointer table is a
dynamically-built table of persistent handles which map to the location for each chunk.
Chunks fill up the remainder of the heap. There are three different kinds of chunks, free,
movable, and fixed. A chunk is a variable sized block of memory that is referenced by a
handle or a pointer. The chunk header contains information on the size of the chunk and
a flag that identifies it as allocated or free and an owner ID. The terminator is just a zero-
length chunk that is used to detect the end of the heap when iterating through the chunks
(Palm OS Memory Architecture).
Figure 1-2

4
Figure 1-3

The memory manager allows clients to allocate two different types of memory,
movable chunks and fixed chunks. They are also known as handles and pointers,
respectively (Figure 1-5). With movable chunks, the OS can deal easily with low and
badly fragmented memory (Albanowski, Kenneth). The difference between pointers and
handles is that pointers stay at a fixed address for their entire existence, and handles are
moved throughout the heap and they must be locked in order to use them. The memory
manager does a lot to keep the heap in order. It keeps fixed chunks at the end of the
heap, which are at higher addresses and the movable chunks at the beginning of the heap.
The result of this is that it allows the memory manager to facilitate heap compaction.
Handles are allocated from the table in the beginning of the heap that stores the master
pointer table. The master pointer is fixed in memory and will not move.
Figure 1-4

5
 Locking your memory is essential for the architecture to function properly.
Without locking, you could be overwriting other application’s memory or corrupting it.
By locking the handle you can make sure that the data is locked and it will return the
pointer to the address for unlocking the memory when necessary. For movable chunks,
which are referenced by handles, the header contains an offset to the master pointer with
a 4-bit lock count. As handles are locked, the lock count increases. The maximum
number of locks is 14, if there are more than 14 an over lock error occurs. As handles are
unlocked, the lock count decreases to a minimum of 0. A lock count of 15 is reserved for
fixed chunks of memory. If a handle is not locked then it is allowed to be resized. In a
special case, a handle can be resized in place without having to move the data around.
This occurs if the size is decreasing, or if there is enough free space in the “pad” at the
end of the chunk, or more rarely if the chunk in the heap is free then the resize can
happen with no change in address, and the handle does not need to be unlocked (Palm
OS Memory Architecture). In most cases the handle is relocated by allocating a new
chunk with the new size, copying the data, fixing up the master pointer to point to the
new chunk, and then releasing the old spaces as free.
In allocation, memory chunks can fail for mainly two different reasons. They will
fail if there is not enough memory or if the memory is scattered around the heap in pieces
that are too small to use. When the memory is scattered, this is referred to as
fragmentation. The solution to a fragmented heap is to compact the heap. Compaction
will place all the free memory into a single big chunk. You can think of this like when
you are de-fragmenting your hard drive and you press the view details button. You can
see all the nutty little colored boxes separated by white space. The disk defragmenter
moves the data boxes around to get rid of the white space between them. As the heap
becomes more fragmented and separated, the overall performance of the device
decreases. One thing that the memory manger uses to make sure that the heaps are
reliable is the use of a semaphore. A semaphore is a kernel structure that is used to
prevent more than one task from entering a protected block of code or using a protected
resource (Palm OS Memory Architecture).
Also on the RAM card is the dynamic heap. This is one of the most important
pieces of memory for the developer because the goal of any application should be how
little memory I can use with this program since memory space on the devices is so
limited. The dynamic heap is used as a temporary storage for all run-time applications on
the device. When the device is reset or powered off, you will lose the heap. The heap
contains a lot of information; it holds the global data for the operating system to run font
tables or kernel structures, the TCP/IP stack for networking issues, the library data for the
serial communications or the infrared device, application UI data structures like windows
and forms, the buffers for pen strokes or key presses, the application global variables, the
application constant data, the application stack, and finally the dynamically allocated
program memory. The dynamic heap does not have any write protection on it so
developers must take care when they are changing anything in the heap. This is one of
the most common Palm developing errors. Chunks in the heap each have an owner that
has an ownerID associated with it. The id is used for file cleanup when the application
exits.
Another heap is called the storage heap. This heap is used for persistent storage.
The storage heaps contains add-on applications, shared libraries, system patches, user

6
data, and preferences. The storage heap is copied to the desktop during synchronization
so that it can be restored if necessary. If the batteries are removed from the device for
longer than a minute the capacitors will drain and cause the memory to be wiped out
including the storage heap.

Data Manager

One of the most interesting things about the Palm OS is the fact that it uses a big
database to store everything on the device. All your appointments, contacts, and memos
aren’t in files, but in tables of a large database. The reason why Palm did this is because
a database can be divided into discreet pieces that the system knows about and can help
manage better than other separate files. Palm databases are interesting because they have
no fields, indexes, or other typical database attributes. There are two different kinds of
databases for the Palm, record and resource. Record databases access records by an
index or a unique ID, can sort records by a key field, and data can be retrieved either
directly using the index or via a search on the unique ID or key (Palm OS Memory
Architecture). Resource databases index resources by a 4-byte resource type and a 2-byte
resource ID, and resources are retrieved using the type/id combination (Palm OS Memory
Architecture). Each database has a header that contains the name, attributes, version
number, modification/creation/backup dates, local ids for AppInfo and Sort Info, type and
creator, unique id seed for records, and record or resource lists (Figure 1-5).
Figure 1-5

The data manger uses something called a local id, which is a protected, card-
relative handle rather than handles or pointers to manage links among the structures. The
localID is generated by a handle by un-protecting it by clearing the high bit, subtracting
the card’s base address, and then protecting it by setting the low bit (Palm OS Memory
Architecture).
Record databases are used for data storage because they are more structured than
resource databases. A record in a record database contains the localID, attributes,
category, and uniqueID. The records in the database are accessed by the array index of
the record header in the list. This guarantees that in a lookup it will take O(1) time.
Records can also be located by a uniqueID. When using the uniqueID, you use a linear
search which is in Big-O notation O(n) time because you must go through all the records
until you find the right one and if you don’t find it, it goes through the whole database
taking a longer time. The answer to this is to keep the record index in a sorted order.

7
Insertion sort and quick sort are used to sort the records. The Big-O for the insertion and
the quick are O(n log n) which is a lot faster than using the linear search.
Records in the database are associated with categories that describe what data
they are holding, for example whether it is a note or an appointment. You can also mark
records public or private and set a password for the private ones so that only the owner
can look at the private records. When a record is changed, the database is marked dirty
and needs to be compared with the one on the desktop to keep both of them in sync. If
the database isn’t dirty, there is no reason to sync it with the desktop unless the copy on
the desktop is marked dirty. You want to avoid unnecessary transfer of data during sync
for many reasons. For example, you want the time during the sync to be as low as
possible because when the device is syncing the batteries are used faster than it is during
normal use.
Resource databases are used for the majority of the system data, because they
have less overhead than record databases. Usually the user interfaces, resources, and the
OS applications data are stored in this database. The resource list of the database consists
of a type, resource id, and a local id.

Processor

The heart of the Palm OS is the processor. Some Palms have different processors
than others. For my Palm pilot, the m100 uses the DragonBall EZ processor from the
Motorola family. This processor has a 32-bit internal address bus and a 24-bit external
address bus. It contains a System Integration Module, a DRAM Controller, UART,
Serial Peripheral Interface Port, 16-bit general purpose counter/timer, real time clock,
LCD controller, pulse width modulation module, built-in emulation function, boot strap
mode function, and power management (MC68EZ328 : DragonBall EZ Integrated
Processor).

Programming the Palm OS

Many developers like the Palm OS because it is open to the developers. The SDK
is free for anyone to download that accepts the licensing agreement. Most code written
for the palm is in C and the conduit development is in C++. Right now, the best program
to get for palm development is Metrowerks Code Warrior for the Palm. This tool
includes an IDE and a visual tool for creating forms for the programs you write. The
palm libraries can be built into the program so that you can compile the programs in the
software. Once compiled, you can test them out on a palm emulator using a ROM file
from your palm and try it out without really loading it onto your physical palm. This
allows you to break the emulated palm instead of your real one. You won’t waste time
loading it onto your palm pilot if it doesn’t work. If you don’t want to purchase the Code
Warrior program you can use GCC.
Palm lists some programming guidelines that it wants developers to use when
creating applications. Some of the guidelines are avoiding reading and writing to NULL,
avoiding allocating zero-length objects, don’t make assumptions about the screen, avoid
directly accessing globals or hardware, don’t overfill the stack, and that built-in
applications can change. (Programming Guidelines)

8
Sample Code

Below is some sample code taken from Palm Programming, The Developer’s
Guide. This file is used for creating the Hello World application on the palm. There are
more files to this program but this is the main C file for the application.

#include <Pilot.h>
#include "HelloRsc.h"
#ifdef __GNUC__
#include "Callbacks.h"
#endif
#include <CharAttr.h>
#include <SysEvtMgr.h>
static Err StartApplication(void){
FrmGotoForm(HelloWorldForm);
return 0;
}
static void StopApplication(void){}
static Boolean MyFormHandleEvent(EventPtr event){
Boolean handled;
#ifdef __GNUC__
CALLBACK_PROLOGUE
#endif
handled = false;
switch (event->eType){
case ctlSelectEvent:
FrmAlert(GoodnightMoonAlert);
handled = true;
break;
case frmOpenEvent:
FrmDrawForm(FrmGetActiveForm());
handled = true;
break;
case menuEvent:
if (event->data.menu.itemID == FirstBeep)
SndPlaySystemSound(sndInfo);
else
SndPlaySystemSound(sndStartUp);
handled = true;
break;
}
#ifdef __GNUC__
CALLBACK_EPILOGUE
#endif
return(handled);
}
static Boolean ApplicationHandleEvent(EventPtr event){
FormPtr frm;
Int formId;
Boolean handled = false;
if (event->eType == frmLoadEvent){
formId = event->data.frmLoad.formID;
frm = FrmInitForm(formId);
FrmSetActiveForm(frm);
switch (formId)
{

9
 case HelloWorldForm:
FrmSetEventHandler(frm, MyFormHandleEvent);
break;
}
handled = true;
}
return handled;
}
static void EventLoop(void){
EventType event;
Word error;
do{
EvtGetEvent(&event, evtWaitForever);
if (! SysHandleEvent(&event))
if (! MenuHandleEvent(0, &event, &error))
if (! ApplicationHandleEvent(&event))
FrmDispatchEvent(&event);
}
while (event.eType != appStopEvent);
}
DWord PilotMain(Word cmd, Ptr cmdPBP, Word launchFlags){
Err err = 0;
if (cmd == sysAppLaunchCmdNormalLaunch){
if ((err = StartApplication()) == 0){
EventLoop();

StopApplication();
}
}
return err;
}

Conclusion

The Palm OS is very popular right now because of the large developer base and
the ease of creating new applications. Handhelds devices are the wave of the feature and
I see Palm being a big part of it. As more and more devices become wirelessly connected
to the internet, I see handhelds devices becoming more important for everyone in the
future. There are some things that handheld devices can’t do that a normal machine can
do, but the goal of this revolution is to move away from the desktop and to a smaller
computer, or maybe just using home computer for backup and recovery purposes, either
way, Palm is leading us into the future.

10
Bibliography

Albanowski, Kenneth. Palm OS Memory and Database Management. Internet, at URL:

http://oasis.palm.com/dev/kb/papers/2029.cfm?print=true (accessed October 3, 2001).

Bachmann, Glenn. Palm Programming, The Authoritative Solution. Sam’s Publishing,

1999.

Introduction to Palm OS Memory Use. Internet, at URL:

http://oasis.palm.com/dev/kb/manuals/1748.cfm?print=true (accessed October 3, 2001).

MC68EZ328 : DragonBall EZ Integrated Processor. Internet, at URL: http://e-

www.motorola.com/webapp/sps/site/prod_summary.jsp?
code=MC68EZ328&nodeId=01M934310090795 (accessed October 3, 2001).

Palm OS Memory Architecture. Internet, at URL:

http://oasis.palm.com/dev/kb/papers/1145.cfm?print=true (accessed October 3, 2001).

Programming Guidelines. Internet, at URL:

http://oasis.palm.com/dev/kb/papers/1134.cfm?print=true (accessed October 3, 2001).

Rhodes, Neil and Julie McKeehan. Palm Programming, The Developer’s Guide.
O’Reilly and Associates, Inc., 1999.

11