Difference between revisions of "AmigaOS"

From Lazarus wiki
Jump to navigationJump to search
(68k manual URL added)
(removed my e-mail and link to User:Chain-Q page instead)
 
(30 intermediate revisions by 8 users not shown)
Line 1: Line 1:
This page is about how to realize a recent Free Pascal port to Hyperion's AmigaOS4 and possibly also to classic Amiga computers. This page was done by [mailto:charlie@NOSPAM.scenergy.dfmk.hu Karoly 'Chain-Q' Balogh], author of [[MorphOS]] port.
+
{{Platform only|AmigaOS|AmigaOS|AmigaOS 4.x}}
  
==Frequently Asked Questions==
+
This page contains information about the AmigaOS4 on PowerPC port, which is in an '''experimental''' stage. About classic [[Amiga]] (OS 3.x, Motorola 680x0) port, please see the [[Amiga|relevant page]]. About other Amiga-like systems supported by Free Pascal, see [[AROS]] and [[MorphOS]] pages. '''The AmigaOS4 port has no official maintainer at this point, which means no new features are being added.'''
  
*Q: '''Is it possible to port Free Pascal Compiler to AmigaOS4?'''<br>A: Yes.  
+
The initial AmigaOS4 port was done by [[User:Chain-Q|Karoly 'Chain-Q' Balogh]], maintainer of [[MorphOS]] and classic [[Amiga]] ports.
  
*Q: '''Is it possible to port Free Pascal Compiler to AmigaOS4, with simple recompilation?'''<br>A: No. A lot of additional steps needed. [[#Steps_needed_to_port_Free_Pascal_to_PowerPC_AmigaOS|See below]].
+
==Identification==
 +
To identify AmigaOS4 exclusively during compile-time, use '''{$IFDEF AMIGAOS4}'''. To identify classic Amiga or AmigaOS4, use '''{$IFDEF AMIGA}'''. To identify any Amiga-like system, including [[AROS]] and [[MorphOS]], use '''{$IFDEF HASAMIGA}'''. This is similar to '''HASUNIX''' which is defined across Unix systems. Please note that '''HASAMIGA''' define is only available in Free Pascal 3.0 and up.
  
*Q: '''Don't you want to do the port?'''<br>A: I'd like to create the port, but I don't have any hardware capable of running AmigaOS4. If you want me to do the port, send me hardware to run OS4 on. Currently this can be an AmigaOne mainboard, or also a phase5/DCE CyberstormPPC accelerator for Commodore Amiga 3000/4000 computers, with valid OS4 license. [mailto:charlie@NOSPAM.scenergy.dfmk.hu Contact me] if you're interrested.
+
==Stack==
 +
On AmigaOS4, the default stack is set to 256 KiB. Stack size can be set directly by the programmer with a compiler switch (-Cs), or with the '''{$MEMORY}''' directive. On AmigaOS4 this feature just sets the "stack cookie" in the executable, [http://wiki.amigaos.net/wiki/Controlling_Application_Stack as described here]. You can also reduce the stack size, but note that AmigaOS4 won't allow stack sizes below 32 KiB.
  
*Q: '''What if I'd like to do the port?'''<br>A: Great! Welcome in the team. Start with reading the the steps required to do it [[#Steps_needed_to_port_Free_Pascal_to_PowerPC_AmigaOS|below]]. If you've more questions, feel free to [mailto:charlie@NOSPAM.scenergy.dfmk.hu ask me in private e-mail], or on any Free Pascal Mailing List.
+
==Naming conventions==
 +
This section describes the differences between the official AmigaOS4 SDK, which is for C language, and the AmigaOS4-specific units in FPC RTL.
  
*Q: '''Can i do the AmigaOS4 port using Free Pascal 2.0.0 for MorphOS?'''<br>A: Yes. Any version of 2.0.0 will do for whatever platform you like, on x86 or PowerPC processors.
+
===Constants===
 +
System constants are named exactly like in the AmigaOS4 SDK.
  
*Q: '''Can i do the AmigaOS4 port using Free Pascal 1.0.10a for AmigaOS/m68k?'''<br>A: No. And again: NO. That compiler is very old, and doesn't support quite a lot of things needed to compile the recent compiler sources, having PowerPC support. Simply forget about it.
+
===Structures and types===
 +
System structures are named similar like in the AmigaOS4 SDK, but follows the Pascal convention about type naming, so structure names has a T before, and each type has a pointer to type with P before the name. The following example should make things trivial:
 +
  struct Task equals to TTask
 +
  struct Task * equals to PTask
  
*Q: '''MorphOS sucks and it's dead. You should concentrate on OS4!'''<br>A: You seriously need to get a life.
+
==Threading==
 +
Threading is supported on Amiga-like systems since Free Pascal 3.0, using the [[AThreads]] unit. Read there for possible caveats and unsupported features.
  
==Equipment and knowledge needed==
+
==Cross compiling==
 +
While the following sections describe cross-compiling from Linux, you can use Mac OS X and Windows as well, as long as you can provide the required cross-binutils. Also on other systems some paths might be different from the ones described below.
  
* '''Any computer capable of running AmigaOS4.''' Basic OS4 compiler port might be possible on MorphOS, using [http://os4emu.amigazeux.net OS4Emu], but this is only recommended for sado-mazochists.
+
===Cross compiling from Linux===
 +
It's possible to cross-build the AmigaOS4 compiler from Linux/i386 and Linux/x86-64 (probably other CPUs too, but it was not tested). To do that, you need Linux to AmigaOS4 cross-binutils, mainly GNU as, ld, and optionally ar and strip. It's best if you build these from GNU sources, along with the rest of cross-build GNU toolchain.
  
* '''Any computer capable of running 2.0.0 version of Free Pascal Compiler.''' Linux/i386 or Linux/PPC recommended. This will be our ''host platform'', while OS4 will be referred as ''target platform''.
+
To build an AmigaOS4 cross-compiler, use the following steps:
  
* '''Recent GNU LD/AS for AmigaOS4''', or any linker capable of creating ELF32-Amiga executables. An example is the great [http://sun.hasenbraten.de/vlink/ vlink by Frank Wille]. Of course, you also need to know how to use such tools. OS4 targetted cross-AS and cross-LD would be nice as well, and makes life easier, but not required.
+
# Install FPC the latest stable compiler, at the time of the writing of this article this is FPC 3.0.0. This will be used as the startup compiler.
 +
# Check out FPC SVN trunk into a directory.
 +
# Make sure the aforementioned cross-binutils are actually in the PATH.
 +
# Go to the trunk's main directory and use the following command to build an FPC to AmigaOS4 cross-compiler running on Linux:
 +
<syntaxhighlight lang="bash">
 +
  make clean crossall crossinstall OS_TARGET=amiga CPU_TARGET=powerpc BINUTILSPREFIX=ppc-amigaos- INSTALL_PREFIX="<path/to/install>"
 +
</syntaxhighlight>
 +
If you've done everything right, you should find a working AmigaOS4 cross-compiler in the install path you've specified.
  
* '''Knowledge about compiler internals''', since you'll probably need to modify the very internals of the compiler.
+
Now, lets create a default fpc.cfg for AmigaOS4 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:
  
* '''PowerPC assembly knowledge, and understanding of SysV ABI'''. You need to know how arguments passed between OS functions and the application programs. You need to know how libraries and devices work on the very low level, and you also need some PowerPC assembly knowledge, because at least when starting, you'll do quite a lot of manual hacks into the generated assembler files.
+
#IFDEF CPUPOWERPC
 +
-Fu<path/to/install>/lib/fpc/$fpcversion/units/$FPCTARGET
 +
-Fu<path/to/install>/lib/fpc/$fpcversion/units/$FPCTARGET/*
 +
#IFDEF AMIGAOS4
 +
-FD</path/to/amigaos4-cross-binutils>
 +
-XPppc-amigaos-
 +
#ENDIF
 +
#ENDIF
  
* '''Understanding of C language'''. Since most software for AmigaOS-like systems are written using C language, you'll only find examples in C. It's nice if you understand C language quite well, because in other case you will not be able to rewrite such code to Pascal.
+
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 AmigaOS4 executables from Pascal source on Linux the following way:
  
* '''Read the [[MorphOS|FPC/MorphOS]] wiki page''', hopefully it will make a lot of things more clear.
+
ppcrossppc -Tamiga <source.pas>
  
==Steps needed to port Free Pascal to PowerPC AmigaOS==
+
Copy the resulting executable to AmigaOS4, and that's it!
  
# '''First you need to add AmigaOS4 target support to the compiler'''. This can be done by creating ''i_aos4.pas'' and ''t_aos4.pas'' units, or extending ''i_amiga.pas'' and ''t_amiga.pas'' units to support PowerPC. The units are in ''/compiler/systems'' directory.
+
===Bootstrapping a compiler from Linux===
# '''The hardest part is to provide API support for OS4.''' The current function declaration syntax is heavily tied to MorphOS, and it will generate calls to dynamic libraries using MorphOS ABI. (Check ''/rtl/morphos/execf.inc'' for an example.) To modify this, you need to add support code into ''/compiler/pdecsub.pas'', '''pd_syscall''' function, ''/compiler/powerpc/nppccal.pas'' '''tppccallnode.do_syscall''' function, and ''/compiler/powerpc/cpupara.pas'' '''tppcparamanager.parseparaloc''' function. Be prepared to repeat this step a few times, since others may modify parts of compiler which may broke your code.
+
To bootstrap a Free Pascal Compiler from Linux to AmigaOS4, first please complete the [[#Cross compiling from Linux|previous section]].
# '''Create startup code for AmigaOS4'''. This is a short stub, written in assembly language, which allocates stack, boots the RTL (runtime-libraries), then the program itself. A trivial solution would be to modify MorphOS version, which is available in ''/rtl/morphos/prt0.as''. It's currently using MorphOS API to allocate stack, but it's not that hard to solve this problem.
 
# '''Bootstrap a simple System unit'''. System unit skeletons are available, but it's possible to modify existing System units as well. Try to make a simple ''hello world!'' running. Use host platform to build units and executables, while test them on OS4.
 
# '''Extend System, DOS and Sysutils unit''' until you're able to compile the compiler itself. When doing MorphOS port, this was the hardest step, because the old 68k version was in really bad shape, had a huge amount of 68k assembly hacks, and it was really a nightmare to clean up and port. In case of OS4 port, your job is easy, simply reuse most of the MorphOS version, while extend it with AmigaOS4-specific functions and optimizations.
 
# '''Build an OS4 hosted compiler'''. If you did everything right, you will be able to compile the compiler then on OS4, and voila', you got Free Pascal Compiler on AmigaOS4.
 
# '''Extend the RTL to have more system-specific parts''', and also to support more of the standard Pascal constructs like on other systems. This is more or less an endless step, since FPC is a moving target, and it's recommended to keep up with the developments.
 
  
==Steps needed to port Free Pascal to Motorola 680x0-based AmigaOS==
+
After you have a working cross compiler, go to the SVN '''trunk/compiler''' directory, and issue the following commands:
 +
<syntaxhighlight lang="bash">
 +
make compiler OS_TARGET=amiga CPU_TARGET=powerpc FPC="<path/to/install>/lib/fpc/3.1.1/ppcrossppc"
 +
</syntaxhighlight>
  
# '''Implement and finish the currently broken 68k code-generator''' for 2.0.0 series. It can be found in ''/compiler/m68k'' directory.
+
Copy the resulting '''ppcppc''' executable to AmigaOS4. On the OS4 box, try to cycle a compiler the following way in the SVN's '''trunk/compiler''' directory:
# '''Once you've finished''', you need to follow steps very similar to [[#Steps_needed_to_port_Free_Pascal_to_PowerPC_AmigaOS|AmigaOS/PowerPC port]].
 
  
Hint: If you need manual about m68k instruction set, you can find the official Motorola manual [http://www.freescale.com/files/archives/doc/ref_manual/M68000PRM.pdf here].
+
set PATH=/SDK/Local/C
 +
gmake cycle FPC=/path/to/ppcppc
 +
 
 +
Please note you need to use '''gmake''' not '''make''', on AmigaOS4. The resulting required compiler is '''trunk/compiler/ppcppc''', the RTL files are in '''rtl/units/powerpc-amiga'''.
 +
 
 +
At the end of the cycle, you might an error, but this is caused by a linker or an assembler problem and it doesn't affects the compiler's functionality. Read the relevant [[#Assembler and Linker|section below]]. Congratulations, you've just successfully bootstrapped Free Pascal on AmigaOS4!
 +
 
 +
 
 +
==Assembler and Linker==
 +
Free Pascal for AmigaOS4 uses '''vlink''' by Frank Wille as the default linker, when running natively on AmigaOS4. The cross-compilers still default to '''GNU ld'''. '''vlink''' is open source, and it is available [http://sun.hasenbraten.de/vlink here]. Binaries are available as part of the [http://sun.hasenbraten.de/vbcc vbcc compiler package].
 +
 
 +
You can change the linker back to '''GNU ld''' by adding ''-XV-'' argument when compiling. For cross compilers ''-XV'' argument enables vlink.
 +
 
 +
===Linker problems===
 +
The native GNU LD on AmigaOS4 has a problem, which prevents FPC's '''make cycle''' to succeed natively. To fulfill some requirements of the system, it pads sections in unstriped executables, but it does so using random memory data. This means the binaries will be different, depending on the memory state during compile time. This makes the final binary verification of '''make cycle''' to fail. Note that the resulting ''ppcppc'' binary is still fully functional. Note that the AmigaOS4 developers know about this problem, but they consider it "harmless". For us, it's a blocker. Also the AmigaOS4 port doesn't support striping with GNU LD currently, which is a missing feature on our side.
 +
 
 +
===Assembler problems===
 +
Some native GNU AS versions distributed in binary might have an issue, which causes the branch-prediction hint bits of some PowerPC branch instructions to change randomly. This causes no directly observable functional differences, but might cause a penalty hit with time critical code, and might cause FPC's own build process to fail (due to binary sanity checks). GNU AS 2.18 as distributed with Hyperion's SDK is not affected.
 +
 
 +
==Preliminary information about language elements to support the port==
 +
'''BIG FAT WARNING!''' All information below this line is preliminary, and subject to change without any further notice. OK, you've been warned.
 +
 
 +
===Library interfaces and Syscalls===
 +
Syscalls are used in AmigaOS4, to provide calls to libraries through OS4 interfaces. Syntax is proposed to be the following:
 +
 
 +
<syntaxhighlight lang=pascal>var
 +
  myLibBase: PLibrary;
 +
 +
type
 +
  TmyLibIface = record
 +
    Data: TInterface;
 +
 +
    Obtain: function(self as hidden): longword; SysCall;
 +
    Release: function(self as hidden): longword; SysCall;
 +
    Expunge: procedure(self as hidden); SysCall;
 +
    Clone: function(self as hidden): POS4Interface; SysCall;
 +
   
 +
    myCallFoo: function(self as hidden; a: longint; b: pointer): pointer; SysCall;
 +
    myCallBar: procedure(self as hidden; c: pchar; d: byte); SysCall;
 +
  end;
 +
  PmyLibIface = ^TmyLibIface;
 +
 +
var
 +
  ImyLib: PmyLibIface;
 +
begin
 +
  // here the opening the library and interface, blah...
 +
 
 +
  ImyLib^.myCallFoo(0,nil);
 +
  ImyLib^.myCallBar('a',1); 
 +
 
 +
  // releasing stuff
 +
end;</syntaxhighlight>
 +
 
 +
The above example calls will pass pointer pointer to the interface in <b>r3</b>, pass the remaining arguments according to SysV ABI. Syscall is needed to enable the passing of the hidden argument, which is only supported for syscalls. A hidden argument can be any integer or pointer variable. They're not need to be specified in the actual calls in the code, but they're still passed to called function. On AmigaOS4, identifier "Self" has a special meaning, and means a pointer to the actual interface.
 +
 
 +
An utility which helps creating a Pascal headers from interface definition files for existing libraries, similar to what IDLTool does for C language, would be highly recommended.
 +
 
 +
==More information==
 +
More information regarding Free Pascal and AmigaOS can be read on the [http://fpcamigawiki.alb42.de Free Pascal 4 Amiga wiki]. This wiki also contains links to (unofficial) nightly downloads and other (additional) information for AmigaOS.
 +
 
 +
[[Category:Operating Systems and Platforms]]
 +
[[Category:AmigaOS]]

Latest revision as of 05:49, 21 July 2020

AmigaOS-boingball.png

This article applies to AmigaOS 4.x only.

See also: Multiplatform Programming Guide

This page contains information about the AmigaOS4 on PowerPC port, which is in an experimental stage. About classic Amiga (OS 3.x, Motorola 680x0) port, please see the relevant page. About other Amiga-like systems supported by Free Pascal, see AROS and MorphOS pages. The AmigaOS4 port has no official maintainer at this point, which means no new features are being added.

The initial AmigaOS4 port was done by Karoly 'Chain-Q' Balogh, maintainer of MorphOS and classic Amiga ports.

Identification

To identify AmigaOS4 exclusively during compile-time, use {$IFDEF AMIGAOS4}. To identify classic Amiga or AmigaOS4, use {$IFDEF AMIGA}. To identify any Amiga-like system, including AROS and MorphOS, use {$IFDEF HASAMIGA}. This is similar to HASUNIX which is defined across Unix systems. Please note that HASAMIGA define is only available in Free Pascal 3.0 and up.

Stack

On AmigaOS4, the default stack is set to 256 KiB. Stack size can be set directly by the programmer with a compiler switch (-Cs), or with the {$MEMORY} directive. On AmigaOS4 this feature just sets the "stack cookie" in the executable, as described here. You can also reduce the stack size, but note that AmigaOS4 won't allow stack sizes below 32 KiB.

Naming conventions

This section describes the differences between the official AmigaOS4 SDK, which is for C language, and the AmigaOS4-specific units in FPC RTL.

Constants

System constants are named exactly like in the AmigaOS4 SDK.

Structures and types

System structures are named similar like in the AmigaOS4 SDK, but follows the Pascal convention about type naming, so structure names has a T before, and each type has a pointer to type with P before the name. The following example should make things trivial:

 struct Task equals to TTask
 struct Task * equals to PTask

Threading

Threading is supported on Amiga-like systems since Free Pascal 3.0, using the AThreads unit. Read there for possible caveats and unsupported features.

Cross compiling

While the following sections describe cross-compiling from Linux, you can use Mac OS X and Windows as well, as long as you can provide the required cross-binutils. Also on other systems some paths might be different from the ones described below.

Cross compiling from Linux

It's possible to cross-build the AmigaOS4 compiler from Linux/i386 and Linux/x86-64 (probably other CPUs too, but it was not tested). To do that, you need Linux to AmigaOS4 cross-binutils, mainly GNU as, ld, and optionally ar and strip. It's best if you build these from GNU sources, along with the rest of cross-build GNU toolchain.

To build an AmigaOS4 cross-compiler, use the following steps:

  1. Install FPC the latest stable compiler, at the time of the writing of this article this is FPC 3.0.0. This will be used as the startup compiler.
  2. Check out FPC SVN trunk into a directory.
  3. Make sure the aforementioned cross-binutils are actually in the PATH.
  4. Go to the trunk's main directory and use the following command to build an FPC to AmigaOS4 cross-compiler running on Linux:
  make clean crossall crossinstall OS_TARGET=amiga CPU_TARGET=powerpc BINUTILSPREFIX=ppc-amigaos- INSTALL_PREFIX="<path/to/install>"

If you've done everything right, you should find a working AmigaOS4 cross-compiler in the install path you've specified.

Now, lets create a default fpc.cfg for AmigaOS4 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 CPUPOWERPC
-Fu<path/to/install>/lib/fpc/$fpcversion/units/$FPCTARGET
-Fu<path/to/install>/lib/fpc/$fpcversion/units/$FPCTARGET/*
#IFDEF AMIGAOS4
-FD</path/to/amigaos4-cross-binutils>
-XPppc-amigaos-
#ENDIF
#ENDIF

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 AmigaOS4 executables from Pascal source on Linux the following way:

ppcrossppc -Tamiga <source.pas>

Copy the resulting executable to AmigaOS4, and that's it!

Bootstrapping a compiler from Linux

To bootstrap a Free Pascal Compiler from Linux to AmigaOS4, first please complete the previous section.

After you have a working cross compiler, go to the SVN trunk/compiler directory, and issue the following commands:

 make compiler OS_TARGET=amiga CPU_TARGET=powerpc FPC="<path/to/install>/lib/fpc/3.1.1/ppcrossppc"

Copy the resulting ppcppc executable to AmigaOS4. On the OS4 box, try to cycle a compiler the following way in the SVN's trunk/compiler directory:

set PATH=/SDK/Local/C
gmake cycle FPC=/path/to/ppcppc

Please note you need to use gmake not make, on AmigaOS4. The resulting required compiler is trunk/compiler/ppcppc, the RTL files are in rtl/units/powerpc-amiga.

At the end of the cycle, you might an error, but this is caused by a linker or an assembler problem and it doesn't affects the compiler's functionality. Read the relevant section below. Congratulations, you've just successfully bootstrapped Free Pascal on AmigaOS4!


Assembler and Linker

Free Pascal for AmigaOS4 uses vlink by Frank Wille as the default linker, when running natively on AmigaOS4. The cross-compilers still default to GNU ld. vlink is open source, and it is available here. Binaries are available as part of the vbcc compiler package.

You can change the linker back to GNU ld by adding -XV- argument when compiling. For cross compilers -XV argument enables vlink.

Linker problems

The native GNU LD on AmigaOS4 has a problem, which prevents FPC's make cycle to succeed natively. To fulfill some requirements of the system, it pads sections in unstriped executables, but it does so using random memory data. This means the binaries will be different, depending on the memory state during compile time. This makes the final binary verification of make cycle to fail. Note that the resulting ppcppc binary is still fully functional. Note that the AmigaOS4 developers know about this problem, but they consider it "harmless". For us, it's a blocker. Also the AmigaOS4 port doesn't support striping with GNU LD currently, which is a missing feature on our side.

Assembler problems

Some native GNU AS versions distributed in binary might have an issue, which causes the branch-prediction hint bits of some PowerPC branch instructions to change randomly. This causes no directly observable functional differences, but might cause a penalty hit with time critical code, and might cause FPC's own build process to fail (due to binary sanity checks). GNU AS 2.18 as distributed with Hyperion's SDK is not affected.

Preliminary information about language elements to support the port

BIG FAT WARNING! All information below this line is preliminary, and subject to change without any further notice. OK, you've been warned.

Library interfaces and Syscalls

Syscalls are used in AmigaOS4, to provide calls to libraries through OS4 interfaces. Syntax is proposed to be the following:

var
  myLibBase: PLibrary;
 
type
  TmyLibIface = record
    Data: TInterface;
 
    Obtain: function(self as hidden): longword; SysCall;
    Release: function(self as hidden): longword; SysCall;
    Expunge: procedure(self as hidden); SysCall;
    Clone: function(self as hidden): POS4Interface; SysCall;
     
    myCallFoo: function(self as hidden; a: longint; b: pointer): pointer; SysCall;
    myCallBar: procedure(self as hidden; c: pchar; d: byte); SysCall;
  end;
  PmyLibIface = ^TmyLibIface;
 
var
  ImyLib: PmyLibIface;
begin
  // here the opening the library and interface, blah...
  
  ImyLib^.myCallFoo(0,nil);
  ImyLib^.myCallBar('a',1);   

  // releasing stuff
end;

The above example calls will pass pointer pointer to the interface in r3, pass the remaining arguments according to SysV ABI. Syscall is needed to enable the passing of the hidden argument, which is only supported for syscalls. A hidden argument can be any integer or pointer variable. They're not need to be specified in the actual calls in the code, but they're still passed to called function. On AmigaOS4, identifier "Self" has a special meaning, and means a pointer to the actual interface.

An utility which helps creating a Pascal headers from interface definition files for existing libraries, similar to what IDLTool does for C language, would be highly recommended.

More information

More information regarding Free Pascal and AmigaOS can be read on the Free Pascal 4 Amiga wiki. This wiki also contains links to (unofficial) nightly downloads and other (additional) information for AmigaOS.