PalmOS port: what changed

Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		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.
2	2
3	3		## Status
4	4
5	5		- The 3.1.x compiler has compiler support (very experimental) for PalmOS.
6	6		- [[m68k]] CPU is supported, including syscall generation support. Only small code is supported at the moment.
7	7		- [[ARM]] CPU is not yet supported
8	8		- Base RTL units are buildable but functionality is minimal.
9	9		- There's a palmunits package, basic functionality was tested successfully.
10	10		- Resource compilation is broken at the moment.
11	11
12	12		## CPU Defaults
13	13
14	14		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.
15	15
16	16		## Identification
17	17
18	18		To identify PalmOS exclusively during compile-time, use {\$IFDEF PALMOS}.
19	19
20	20		## Calling conventions
21	21
22	22		### Registers
23	23
24	24		As a difference to the standard [[m68k\|m68k register layout]], on PalmOS also d2 and a2 registers are used as scratch registers, and their contents are not preserved. This is dictated by the ABI used by the C compilers and the syscall convention of the platform. Additionally, register a5 is used as a pointer to the global data. On PalmOS, register a5 points to the end of the global data.
25	25
26	26		### SysCalls
27	27
28	28		It's not required to use inline assembly to do system calls. Any trap function can be defined the following way:
29	29
30	30		``` pascal
31	31		function MemPtrNew(size: UInt32): MemPtr; syscall $A013;
32	32		```
33	33
34	34		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.
35	35
36	36		## Building Tutorial
37	37
38	38		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. The tutorial below uses PATHs tuned for Linux and macOS systems. The FPC directory structure on Windows can be slightly different to these.
39	39
40	40		### Cross binutils
41	41
42	42		The older version of GNU binutils included in [prc-tools](http://prc-tools.sourceforge.net) 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](https://github.com/chainq/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.
43	43
44	44		From prc-tools, Free Pascal uses the followings:
45	45
46	46		- as
47	47		- ld
48	48		- ar
49	49		- build-prc
50	50
51	51		Make sure they're all on the path or in the specified tools directory, and they all share the same prefix, like m68k-palmos-.
52	52
53	53		### Cross compiler
54	54
55	55		PalmOS is a cross-compiler only target. The following steps can be used build a PalmOS cross-compiler:
56	56
57	57		1. Install the latest stable Free Pascal Compiler. This will be used as the startup compiler.
58	58		2. Check out FPC SVN trunk into a directory.
59	59		3. Make sure the cross-binutils are properly built, and its binaries are actually in the PATH.
60	60		4. Go to the SVN trunk root directory and use the following command to build an m68k-palmos cross-compiler:
61	61
62	62		``` bash
63	63		make clean crossall crossinstall OS_TARGET=palmos CPU_TARGET=m68k CROSSOPT="-XX -CX" INSTALL_PREFIX="<path/to/install>"
64	64		```
65	65
66	66		If everything went correctly, you should find a working PalmOS cross-compiler at the install path you specified.
67	67
68	68		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:
69	69
70	70		`#IFDEF CPUM68K`\
71	71		`-Fu<path/to/install>/lib/fpc/$fpcversion/units/$FPCTARGET`\
72	72		`-Fu<path/to/install>/lib/fpc/$fpcversion/units/$FPCTARGET/*`\
73	73		`#IFDEF PALMOS`\
74	74		`-FD</path/to/m68k-palmos-binutils>`\
75	75		`-XPm68k-palmos-`\
76	76		`-XX`\
77	77		`-CX`\
78	78		`#ENDIF`\
79	79		`#ENDIF`
80	80
81	81		Note the -CX and -XX options used for both the build and the config file. They enable smartlinking by default.
82	82
83		-	<font color="red">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.</font>
	83	+	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.
84	84
85	85		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:
86	86
87	87		`ppcross68k -Tpalmos <source.pas>`
88	88
89	89		Copy the resulting .prc executable to your PalmOS device using HotSync or your preferred method.
90	90
91	91		## Examples
92	92
93	93		The 'palmunits package contains a few examples, which are a good starting point. They should be directly buildable from the command line. They're all GUI applications. Console applications are not supported at this moment.
94	94
95	95		## Running binaries
96	96
97	97		### Emulator
98	98
99	99		The old POSE Emulator of 68k-based Palm devices is Windows only, but works great with WINE on macOS and Linux. You will also need a set of Palm ROMs and skins for the emulator. These are available from various locations over the internet, preserving old Palm software and developer tools. Due to the uncertain nature of these redistributions, we cannot directly link these here, sadly.
100	100
101		-	~~<figure>~~
102	101		<img src="fpc_cube_on_pose.png" title="FPC Cube! example program running on POSE" width="240" />
103		-	~~<figcaption>FPC Cube! example program running on POSE</figcaption>~~
104		-	~~</figure>~~
105	102
106	103		### Real Device
107	104
108	105		On Linux and macOS, the open source command line pilot-link was tested and works for uploading FPC generated binaries. pilot-link is still available from most distributions' package manager, [or in source from here](https://github.com/jichu4n/pilot-link). There are also various GUI front-ends for pilot-link, like [JPilot](http://jpilot.org).
109	106
110	107		On Windows or macOS, the original Palm Desktop software should work as well.
111	108
112	109		## Debugging PalmOS applications
113	110
114	111		This section is not yet available
115	112
116	113		## Links
117	114
118	115		- [Buildfaq](http://www.stack.nl/~marcov/buildfaq.pdf) is a general FAQ about how to build and configure FPC.
119	116
120	117		Various Palm related information sources
121	118
122	119		- [PRC format](http://web.mit.edu/tytso/www/pilot/prc-format.html) describes the Palm executable and resource format
123	120		- [pilot-link howto](http://www.tldp.org/HOWTO/PalmOS-HOWTO/pilotlink.html) describes the usage of pilot-link and transferring files and data to/from the device
124	121
125	122		Here are some links related to ARM CPU Architecture
126	123
127	124		- [GCC ARM Improvement Project](http://www.inf.u-szeged.hu/gcc-arm/)
128	125		- [ARM ASSEMBLER](http://www.heyrick.co.uk/assembler/index.html) Good information and codes related to arm assembly language.
129	126		- [ARM Instruction Sets & Programs](http://soc.csie.ndhu.edu.tw/source/intro_embedded/ch2-arm-2.ppt) Very good and consice information about arm architecture
130	127		- [The ARM Instruction Set](http://web.njit.edu/~baltrush/arm_stuff/ARMInst.ppt) Another fine power point file about arm
131	128
132	129		## Contacts
133	130
134	131		Current maintainer: Károly Balogh
135	132
136	133		Original author: [Mazen NEIFER](mailto:mazen@freepascal.org)
137	134
138	135		---
139	136		From the Free Pascal wiki, page "PalmOS port", as it stood on 2018-01-13 after a change by Chain-Q, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).
140	137		Category: Palm OS and Garnet OS

Back to history