Difference between revisions of "PalmOS port"

From Lazarus wiki
Jump to navigationJump to search
(→‎Links: one more link)
 
(41 intermediate revisions by 7 users not shown)
Line 1: Line 1:
−
PalmOs port is in its early beginning stage. The port is started and will be maintained by Mazen Neifer. Peter Vreman ported PalmOs API headers.
+
{{PalmOS port}}
  
−
== Status ==
+
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 [[User:Chain-Q|Károly Balogh]]. The PalmOS port is a crosscompiler-only target.
−
* The 2.1.x compiler has compiler support (very experimental) for PalmOs.
 
−
* [[ARM]] CPU is supported.
 
−
* The following platforms will be supported:
 
−
** Zire72 – PalmOs version: 3.0
 
−
* Base RTL units are not yet ported.
 
  
−
== Building Tutorial==
+
==Status==
  
−
During the tutorial some paths will be supposed to demonstrate the build process. Just substitute those paths with the ones on your system.
+
* 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==
  
−
'''Step 1''' - Cross binutils
+
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'''.
  
−
These are the basic tools necessary to create executables, such as:
+
==Identification==
−
* '''arm-palmos-ld''' : Linker
 
−
* '''arm-palmos-as''' : Assembler
 
−
* '''arm-palmos-ar''' : Archiver (Creates smartlinking .a files)
 
−
* '''arm-palmos-strip''' and some others.
 
  
−
You need cross binutils for arm-palmos, debian linux (sid) provides a ready to use package '''[http://packages.debian.org/unstable/otherosfs/prc-tools prc-tools-utils]'''. Just "apt-get install prc-tools-utils" will do the job. Otherwise, you need to get them from http://www.palmos.com/dev/dl/dl_tools/.
+
To identify PalmOS exclusively during compile-time, use '''{$IFDEF PALMOS}'''.
  
−
Extract them to some dir in the path on your machine. In a debian machine these are installed to <tt>/usr/bin/arm-palmos-*</tt>
+
==Calling conventions==
  
 +
===Registers===
  
−
'''Step 2''' - Cross compiler
+
As a difference to the standard [[m68k#Registers|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.
  
−
We will suppose that your are using debian linux installation (sid) and fpc compiler is already installed and correctly configured.  Under debian linux (sid) you may install the '''[http://packages.debian.org/unstable/devel/fp-compiler fp-compiler]''' package ("apt-get install fp-compiler")
+
===SysCalls===
  
−
Now you need to build fpc cross compiler for ARM processor. To do that you need latest fpc 2.1.x sources in addition to your working installation of fpc 2.0.2 or 2.0 already mentioned. Get the latest 2.1.x source repository from Subversion: http://www.freepascal.org/develop.html#svn
+
It's not required to use inline assembly to do system calls. Any trap function can be defined the following way:
 +
 +
<syntaxhighlight lang="pascal">function MemPtrNew(size: UInt32): MemPtr; syscall $A013;
 +
</syntaxhighlight>
 +
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.
  
−
We will suppose your Free Pascal 2.1.x source code is located here: <tt>${FPC_SRC}</tt>
+
==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. The tutorial below uses PATHs tuned for Linux and macOS systems. The FPC directory structure on Windows can be slightly different to these.
  
−
'''Step 3''' - The Build process
+
===Cross binutils===
  
−
In order to build the cross compiler it is necessary to have a correct <tt>PATH</tt> environment variable. Please ensure that your path is correct:
+
The older version of GNU binutils included in [http://prc-tools.sourceforge.net 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 [https://github.com/chainq/prc-tools-remix 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.
  
−
<pre>
+
From prc-tools, Free Pascal uses the followings:
−
make cycle PATH="/bin:/usr/bin:/usr/bin/X11:/usr/local/bin" CPU_TARGET=arm OS_TARGET=palmos
 
−
</pre>
 
  
−
On the end of the compile you should not see any errors.
+
* as
 +
* ld
 +
* ar
 +
* build-prc
  
−
You should have a <tt>ppccrossarm</tt> in <tt>${FPC_SRC}/compiler</tt> and some <tt>.o</tt> and <tt>.ppu</tt> files in <tt>${FPC_SRC}/rtl/units/arm-palmos</tt>
+
Make sure they're all on the path or in the specified tools directory, and they all share the same prefix, like '''m68k-palmos-'''.
  
−
Now copy those files to your Free Pascal installation. The cross compiler <tt>ppccrossarm</tt> should go to <tt>/usr/local/bin/arm-palmos</tt> and the units to <tt>/usr/local/lib/fpc/units/arm-palmos</tt>
+
===Cross compiler===
  
 +
PalmOS is a cross-compiler only target. The following steps can be used build a PalmOS cross-compiler:
  
−
'''Step 4''' - Configuration file
+
# Install the latest stable Free Pascal Compiler. This will be used as the startup compiler.
 +
# Check out FPC SVN trunk into a directory.
 +
# Make sure the [[#Cross binutils|cross-binutils]] are properly built, and its binaries are actually in the '''PATH'''.
 +
# Go to the SVN trunk root directory and use the following command to build an m68k-palmos cross-compiler:
 +
<syntaxhighlight lang="bash">
 +
  make clean crossall crossinstall OS_TARGET=palmos CPU_TARGET=m68k CROSSOPT="-XX -CX" INSTALL_PREFIX="<path/to/install>"
 +
</syntaxhighlight>
  
−
Now you need to create <tt>fpc.cfg</tt> configuration file in <tt>C:\Programas\fpc\bin\arm-PalmOs</tt> folder in order to use <tt>ppccrossarm.exe</tt> easy.
+
If everything went correctly, you should find a working PalmOS cross-compiler at the install path you specified.
  
−
Create empty <tt>fpc.cfg</tt> file in <tt>C:\Programas\fpc\bin\arm-PalmOs</tt> folder and add the following lines to it:
+
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:
−
<pre>
 
−
-TPalmOs
 
−
-FuC:\Programas\fpc\units\arm-PalmOs
 
−
-XParm-PalmOs-
 
−
-FDC:\Programas\arm
 
−
</pre>
 
  
−
Finally add <tt>C:\Programas\fpc\bin\arm-PalmOs</tt> and <tt>C:\Programas\fpc\bin\i386-win32</tt> to your <tt>PATH</tt> environment variable.
+
#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
  
−
'''Remember to substitute the paths with the ones on your system.'''
+
Note the '''-CX''' and '''-XX''' options used for both the build and the config file. They enable smartlinking by default.
  
−
== Compiling a Test Project ==
+
'''<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>'''
  
−
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.
+
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:
  
−
'''Step 1''' - Installing and Configuring the Emulator
+
ppcross68k -Tpalmos <source.pas>
  
−
??
+
Copy the resulting '''.prc''' executable to your PalmOS device using HotSync or your preferred method.
  
−
'''Step 2''' - Installing the command line
+
==Examples==
  
−
??
+
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.
  
−
'''Step 3''' - Compiling
+
==Running binaries==
  
−
A example file to compile:
+
===Emulator===
  
−
<pre>
+
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.
−
program test;
 
  
−
{$apptype console}
+
[[File:fpc_cube_on_pose.png|240px|thumb|none|FPC Cube! example program running on POSE]]
  
−
var
+
===Real Device===
−
  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.
 
−
</pre>
 
  
−
Sample command line to compile <tt>test.pas</tt>:
+
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, [https://github.com/jichu4n/pilot-link or in source from here]. There are also various GUI front-ends for '''pilot-link''', like [http://jpilot.org JPilot].
  
−
<tt>ppcrossarm test.pas</tt>
+
On Windows or macOS, the original Palm Desktop software should work as well.
  
−
You will get <tt>test.exe</tt> executable file. Copy it to your Windows CE device and run.
+
==Debugging PalmOS applications==
  
−
[http://wiki.lazarus.freepascal.org/index.php/Windows_CE_Interface Here] is a screenshot of a software created this way.
+
This section is not yet available
  
−
== Debugging PalmOs applications ==
+
==Links==
−
 
+
* [http://www.stack.nl/~marcov/buildfaq.pdf Buildfaq] is a general FAQ about how to build and configure FPC.
−
GDB can be used to debug your PalmOs applications remotely via ActiveSync. Download GDB 6.4 for Win32 host and arm-PalmOs target here: ftp://ftp.freepascal.org/pub/fpc/contrib/cross/gdb-6.4-win32-arm-PalmOs.zip
 
−
 
 
−
'''Some hints:'''
 
−
 
 
−
* Pass <tt>--tui</tt> parameter to GDB to enable TUI interface which makes debugging more comfortable.
 
−
* Use unix line endings (LF only) in your pascal source files. Otherwise GDB will show sources incorrctly.
 
  
−
'''How to use:'''
+
Various Palm related information sources
  
−
First, make ActiveSync connection to your Pocket PC device.
+
* [http://web.mit.edu/tytso/www/pilot/prc-format.html PRC format] describes the Palm executable and resource format
−
 
+
* [http://www.tldp.org/HOWTO/PalmOS-HOWTO/pilotlink.html pilot-link howto] describes the usage of pilot-link and transferring files and data to/from the device
−
Then launch gdb:  
 
−
 
 
−
<tt>gdb --tui <your_executable_at_local_pc></tt>
 
−
 
 
−
On gdb prompt type:
 
−
 
 
−
<tt>run</tt> or just <tt>r</tt>
 
−
 
 
−
GDB will copy your executable to the device in <tt>\gdb</tt> folder and run it.
 
−
 
 
−
Here is a short list of most needed GDB commands:
 
−
* <tt>s</tt> - step into.
 
−
* <tt>n</tt> - step over.
 
−
* <tt>c</tt> - continue execution.
 
−
* <tt>br <function_name></tt> - set a breakpoint at <tt>function_name</tt>. Use <tt>PASCALMAIN</tt> to set a breakpoint at program start.
 
−
* <tt>br <source_file>:<line_number></tt> - set a breakpoint at specified source line.
 
−
 
 
−
To learn more how to use GDB read its documentation here: http://www.gnu.org/software/gdb/documentation
 
−
 
 
−
== Building FPC libraries ==
 
−
 
 
−
If you want to build libraries available with FPC just go to library folder and execute:
 
−
<pre>
 
−
PATH=C:\Programas\fpc\bin\i386-win32;C:\Programas\fpc\compiler;C:\Programas\arm
 
−
make OS_TARGET=PalmOs CPU_TARGET=arm PP=ppcrossarm.exe
 
−
</pre>
 
−
 
 
−
For example you want to build FCL. Go to <tt>fpc\fcl</tt> folder and execute the command above. You will get FCL compiled units in <tt>fpc\fcl\units\arm-PalmOs</tt>.
 
−
 
 
−
== Documentation ==
 
−
 
 
−
=== PalmOs port notes ===
 
−
* <tt>'''chdir'''</tt> procedure always produces an error (PalmOs does not support setting of current directory).
 
−
* All file/dir paths must be absolute (started with \).
 
−
* PalmOs is unicode OS. All string parameters to API calls must be PWideChar.
 
−
* PalmOs does not have support for environment strings.
 
−
* 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 <tt>-WC</tt> compiler switch or put <tt>{$APPTYPE CONSOLE}</tt> directive to source code.<br>To enable console in PalmOs install one of the following programs:
 
−
 
 
−
== Links ==
 
−
* [http://www.stack.nl/~marcov/buildfaq.pdf Buildfaq] is a general FAQ about how to build and configure FPC.
 
  
 
Here are some links related to ARM CPU Architecture
 
Here are some links related to ARM CPU Architecture
  
−
* [http://www.armcorepro.com/ ARM Core Developers Forum] Not that much active though.
 
 
* [http://www.inf.u-szeged.hu/gcc-arm/ GCC ARM Improvement Project]
 
* [http://www.inf.u-szeged.hu/gcc-arm/ GCC ARM Improvement Project]
 
* [http://www.heyrick.co.uk/assembler/index.html ARM ASSEMBLER] Good information and codes related to arm assembly language.
 
* [http://www.heyrick.co.uk/assembler/index.html ARM ASSEMBLER] Good information and codes related to arm assembly language.
−
* [http://www.gnuarm.com/ GNU ARM toolchain for Cygwin, Linux and MacOS]
 
 
* [http://soc.csie.ndhu.edu.tw/source/intro_embedded/ch2-arm-2.ppt ARM Instruction Sets & Programs] Very good and consice information about arm architecture
 
* [http://soc.csie.ndhu.edu.tw/source/intro_embedded/ch2-arm-2.ppt ARM Instruction Sets & Programs] Very good and consice information about arm architecture
 
* [http://web.njit.edu/~baltrush/arm_stuff/ARMInst.ppt The ARM Instruction Set ] Another fine power point file about arm
 
* [http://web.njit.edu/~baltrush/arm_stuff/ARMInst.ppt The ARM Instruction Set ] Another fine power point file about arm
  
−
== Contacts ==
+
==Contacts==
 +
 
 +
Current maintainer: [[User:Chain-Q|Károly Balogh]]
 +
 
 +
Original author: [mailto:mazen@freepascal.org Mazen NEIFER]
 +
 
 +
[[Category: Palm OS and Garnet OS]]

Latest revision as of 21:21, 13 January 2018

│ 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}.

Calling conventions

Registers

As a difference to the standard 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.

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. The tutorial below uses PATHs tuned for Linux and macOS systems. The FPC directory structure on Windows can be slightly different to these.

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.

From prc-tools, Free Pascal uses the followings:

  • as
  • ld
  • ar
  • build-prc

Make sure they're all on the path or in the specified tools directory, and they all share the same prefix, like m68k-palmos-.

Cross compiler

PalmOS is a cross-compiler only target. The following steps can be used 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.

Examples

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.

Running binaries

Emulator

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.

FPC Cube! example program running on POSE

Real Device

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. There are also various GUI front-ends for pilot-link, like JPilot.

On Windows or macOS, the original Palm Desktop software should work as well.

Debugging PalmOS applications

This section is not yet available

Links

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

Various Palm related information sources

  • PRC format describes the Palm executable and resource format
  • pilot-link howto describes the usage of pilot-link and transferring files and data to/from the device

Here are some links related to ARM CPU Architecture

Contacts

Current maintainer: Károly Balogh

Original author: Mazen NEIFER

Retrieved from "http://wiki.freepascal.org/index.php?title=PalmOS_port&oldid=115098"