AmigaOS: what changed

Revision 3 to 4. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		(AmigaOS only)
2	2
3	3		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.
4	4
5	5		The initial AmigaOS4 port was done by Karoly 'Chain-Q' Balogh, maintainer of [[MorphOS]] and classic [[Amiga]] ports.
6	6
7	7		## Identification
8	8
9	9		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.
10	10
11	11		## Stack
12	12
13	13		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](http://wiki.amigaos.net/wiki/Controlling_Application_Stack). You can also reduce the stack size, but note that AmigaOS4 won't allow stack sizes below 32 KiB.
14	14
15	15		## Naming conventions
16	16
17	17		This section describes the differences between the official AmigaOS4 SDK, which is for C language, and the AmigaOS4-specific units in FPC RTL.
18	18
19	19		### Constants
20	20
21	21		System constants are named exactly like in the AmigaOS4 SDK.
22	22
23	23		### Structures and types
24	24
25	25		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:
26	26
27		-	~~```~~
	27	+	```text
28	28		struct Task equals to TTask
29	29		struct Task * equals to PTask
30	30		```
31	31
32	32		## Threading
33	33
34	34		Threading is supported on Amiga-like systems since Free Pascal 3.0, using the [[AThreads]] unit. Read there for possible caveats and unsupported features.
35	35
36	36		## Cross compiling
37	37
38	38		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.
39	39
40	40		### Cross compiling from Linux
41	41
42	42		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.
43	43
44	44		To build an AmigaOS4 cross-compiler, use the following steps:
45	45
46	46		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.
47	47		2. Check out FPC SVN trunk into a directory.
48	48		3. Make sure the aforementioned cross-binutils are actually in the PATH.
49	49		4. Go to the trunk's main directory and use the following command to build an FPC to AmigaOS4 cross-compiler running on Linux:
50	50
51	51		``` bash
52	52		make clean crossall crossinstall OS_TARGET=amiga CPU_TARGET=powerpc BINUTILSPREFIX=ppc-amigaos- INSTALL_PREFIX="<path/to/install>"
53	53		```
54	54
55	55		If you've done everything right, you should find a working AmigaOS4 cross-compiler in the install path you've specified.
56	56
57	57		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:
58	58
59		-	~~```~~
	59	+	```text
60	60		#IFDEF CPUPOWERPC
61	61		-Fu<path/to/install>/lib/fpc/$fpcversion/units/$FPCTARGET
62	62		-Fu<path/to/install>/lib/fpc/$fpcversion/units/$FPCTARGET/*
63	63		#IFDEF AMIGAOS4
64	64		-FD</path/to/amigaos4-cross-binutils>
65	65		-XPppc-amigaos-
66	66		#ENDIF
67	67		#ENDIF
68	68		```
69	69
70	70		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:
71	71
72		-	~~```~~
	72	+	```text
73	73		ppcrossppc -Tamiga <source.pas>
74	74		```
75	75
76	76		Copy the resulting executable to AmigaOS4, and that's it!
77	77
78	78		### Bootstrapping a compiler from Linux
79	79
80	80		To bootstrap a Free Pascal Compiler from Linux to AmigaOS4, first please complete the previous section.
81	81
82	82		After you have a working cross compiler, go to the SVN trunk/compiler directory, and issue the following commands:
83	83
84	84		``` bash
85	85		make compiler OS_TARGET=amiga CPU_TARGET=powerpc FPC="<path/to/install>/lib/fpc/3.1.1/ppcrossppc"
86	86		```
87	87
88	88		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:
89	89
90		-	~~```~~
	90	+	```text
91	91		set PATH=/SDK/Local/C
92	92		gmake cycle FPC=/path/to/ppcppc
93	93		```
94	94
95	95		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.
96	96
97	97		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!
98	98
99	99		## Assembler and Linker
100	100
101	101		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](http://sun.hasenbraten.de/vlink). Binaries are available as part of the [vbcc compiler package](http://sun.hasenbraten.de/vbcc).
102	102
103	103		You can change the linker back to GNU ld by adding -XV- argument when compiling. For cross compilers -XV argument enables vlink.
104	104
105	105		### Linker problems
106	106
107	107		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.
108	108
109	109		### Assembler problems
110	110
111	111		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.
112	112
113	113		## Preliminary information about language elements to support the port
114	114
115	115		BIG FAT WARNING! All information below this line is preliminary, and subject to change without any further notice. OK, you've been warned.
116	116
117	117		### Library interfaces and Syscalls
118	118
119	119		Syscalls are used in AmigaOS4, to provide calls to libraries through OS4 interfaces. Syntax is proposed to be the following:
120	120
121	121		``` pascal
122	122		var
123	123		myLibBase: PLibrary;
124	124
125	125		type
126	126		TmyLibIface = record
127	127		Data: TInterface;
128	128
129	129		Obtain: function(self as hidden): longword; SysCall;
130	130		Release: function(self as hidden): longword; SysCall;
131	131		Expunge: procedure(self as hidden); SysCall;
132	132		Clone: function(self as hidden): POS4Interface; SysCall;
133	133
134	134		myCallFoo: function(self as hidden; a: longint; b: pointer): pointer; SysCall;
135	135		myCallBar: procedure(self as hidden; c: pchar; d: byte); SysCall;
136	136		end;
137	137		PmyLibIface = ^TmyLibIface;
138	138
139	139		var
140	140		ImyLib: PmyLibIface;
141	141		begin
142	142		// here the opening the library and interface, blah...
143	143
144	144		ImyLib^.myCallFoo(0,nil);
145	145		ImyLib^.myCallBar('a',1);
146	146
147	147		// releasing stuff
148	148		end;
149	149		```
150	150
151	151		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.
152	152
153	153		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.
154	154
155	155		## More information
156	156
157	157		More information regarding Free Pascal and AmigaOS can be read on the [Free Pascal 4 Amiga wiki](http://fpcamigawiki.alb42.de). This wiki also contains links to (unofficial) nightly downloads and other (additional) information for AmigaOS.
158	158
159	159		---
160	160		From the Free Pascal wiki, page "AmigaOS", as it stood on 2020-07-21 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).
161	161		Category: AmigaOS
162	162		Category: Operating Systems and Platforms

Back to history