PalmOS port

│ English (en) │ español (es) │ português (pt) │

Currently, the PalmOS port is a retro, "just for fun" port of the compiler and runtime libraries, based on an earlier, incomplete effort from over a decade ago. The port was originally started by Mazen Neifer. Peter Vreman ported PalmOS API headers. m68k port and 3.1.x+ compiler support and maintenance by Károly Balogh. The PalmOS port is a crosscompiler-only target.

Status

• The 3.1.x compiler has compiler support (very experimental) for PalmOS.
• m68k CPU is supported, including syscall generation support. Only small code is supported at the moment.
• ARM CPU is not yet supported
• Base RTL units are buildable but functionality is minimal.
• There's a palmunits package, basic functionality was tested successfully.
• Resource compilation is broken at the moment.

CPU Defaults

The m68k PalmOS port defaults to 68000 CPU subarchitecture and no FPU. Note that by default, the PalmOS port doesn't include the RTL's SoftFPU. For floating point calculations, one can use the OS supplied floating point unit helper API, or recompile the RTL with the SoftFPU included, using argument -CfSOFT.

Identification

To identify PalmOS exclusively during compile-time, use {$IFDEF PALMOS}.

SysCalls

It's not required to use inline assembly to do system calls. Any trap function can be defined the following way:

function MemPtrNew(size: UInt32): MemPtr; syscall $A013;

Note the syscall modifier in the function declaration. The argument to the syscall modifier is the trap number to call. The arguments to a syscall function are always passed on the stack and they're word (2 byte) aligned. Optionally, the numerical trap ID (here shown in hexadecimal) can be defined by a constant. For further examples, see the file rtl/palmos/palmos.inc in the RTL source or the palmunits package.

Building Tutorial

The section below details building an m68k-palmos Free Pascal cross compiler. The ARM building process is the same with the different CPU name. Note that the ARM PalmOS support is non functional at the moment.

Cross binutils

The older version of GNU binutils included in prc-tools is difficult to build on modern systems, like macOS/Darwin 10.12+ or any 64-bit Linux. It is recommended to use the prc-tools-remix repository instead. This supports both m68k and ARM prc tools, and it is fixed to build and work on current systems. It also provides up to date installation instructions, see there.

Cross compiler

PalmOS is a cross-compiler only target. The following steps build a PalmOS cross-compiler:

1. Install the latest stable Free Pascal Compiler. This will be used as the startup compiler.
2. Check out FPC SVN trunk into a directory.
3. Make sure the cross-binutils are properly built, and its binaries are actually in the PATH.
4. Go to the SVN trunk root directory and use the following command to build an m68k-palmos cross-compiler:

  make clean crossall crossinstall OS_TARGET=palmos CPU_TARGET=m68k CROSSOPT="-XX -CX" INSTALL_PREFIX="<path/to/install>"

If everything went correctly, you should find a working PalmOS cross-compiler at the install path you specified.

Now, lets create a default fpc.cfg for PalmOS cross compiling. Create a file called <path/to/install>/lib/fpc/etc/fpc.cfg. Put the following lines into that file, and fix up the paths:

#IFDEF CPUM68K
-Fu<path/to/install>/lib/fpc/$fpcversion/units/$FPCTARGET
-Fu<path/to/install>/lib/fpc/$fpcversion/units/$FPCTARGET/*
#IFDEF PALMOS
-FD</path/to/m68k-palmos-binutils>
-XPm68k-palmos-
-XX
-CX
#ENDIF
#ENDIF

Note the -CX and -XX options used for both the build and the config file. They enable smartlinking by default.

Due to the size constraints PalmOS puts on the executables, and the limitations of the old prc-tools binutils, building and compiling without smartlinking is not supported.

Optionally add <path/to/install>/lib/fpc/3.1.1/ directory to the PATH, so you'll have direct access to the cross compiler. If you've done everything right, you now should be able to build PalmOS executables from a Pascal source the following way:

ppcross68k -Tpalmos <source.pas>

Copy the resulting .prc executable to your PalmOS device using HotSync or your preferred method.

Compiling a Test Project

You compiled the compiler! Now, what can I do with it? This is a tutorial to create a hello world like software with your new compiler.

Installing and Configuring the Emulator

First of all, you need to install the Palm Device Emulator. This is a windows binary, but works well with WINE on a Debian Linux (sid) box. TODO

Compiling

A example file to compile:

program test;

{$apptype console}

var
  Str: string;
begin
  WriteLn('Software Developed with:');
  WriteLn('The Free Pascal Compiler');
  WriteLn('');
  WriteLn('Please, enter your name:');
  ReadLn(Str);
  WriteLn('Your name is: ' + Str);
end.

Sample command line to compile test.pas:

ppcrossarm test.pas

You should get test.prc executable file. Copy it to your Palm device and run it.

Debugging PalmOS applications

This section is not yet available

Building FPC libraries

If you want to build libraries available with FPC, for example you want to build FCL then execute the commands above.

*
cd ${FPC_SRC}/fpc
make OS_TARGET=palmos CPU_TARGET=arm PP=ppcrossarm fcl

You will get FCL units in ${FPC_SRC}/fpc/fcl/units/arm-palmos.

Documentation

PalmOS port notes

• PalmOS does not have support for console applications by default. But you can install console support by yourself. Please note that FPC creates GUI applications for PalmOS target by default. To create console application you should use -WC compiler switch or put {$APPTYPE CONSOLE} directive to source code.

Links

• Buildfaq is a general FAQ about how to build and configure FPC.

Here are some links related to ARM CPU Architecture

• ARM Core Developers Forum Not that much active though.
• GCC ARM Improvement Project
• ARM ASSEMBLER Good information and codes related to arm assembly language.
• GNU ARM toolchain for Cygwin, Linux and MacOS
• ARM Instruction Sets & Programs Very good and consice information about arm architecture
• The ARM Instruction Set Another fine power point file about arm

Contacts

Mazen NEIFER