AmigaOS: what changed

Revision 2 to 3. 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		-	~~` struct Task equals to TTask`\~~
28		-	~~` struct Task * equals to PTask`~~
	27	+	```
	28	+	struct Task equals to TTask
	29	+	struct Task * equals to PTask
	30	+	```
29	31
30	32		## Threading
31	33
32	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.
33	35
34	36		## Cross compiling
35	37
36	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.
37	39
38	40		### Cross compiling from Linux
39	41
40	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.
41	43
42	44		To build an AmigaOS4 cross-compiler, use the following steps:
43	45
44	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.
45	47		2. Check out FPC SVN trunk into a directory.
46	48		3. Make sure the aforementioned cross-binutils are actually in the PATH.
47	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:
48	50
49	51		``` bash
50	52		make clean crossall crossinstall OS_TARGET=amiga CPU_TARGET=powerpc BINUTILSPREFIX=ppc-amigaos- INSTALL_PREFIX="<path/to/install>"
51	53		```
52	54
53	55		If you've done everything right, you should find a working AmigaOS4 cross-compiler in the install path you've specified.
54	56
55	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:
56	58
57		-	~~`#IFDEF CPUPOWERPC`\~~
58		-	~~`-Fu<path/to/install>/lib/fpc/$fpcversion/units/$FPCTARGET`\~~
59		-	~~`-Fu<path/to/install>/lib/fpc/$fpcversion/units/$FPCTARGET/*`\~~
60		-	~~`#IFDEF AMIGAOS4`\~~
61		-	~~`-FD</path/to/amigaos4-cross-binutils>`\~~
62		-	~~`-XPppc-amigaos-`\~~
63		-	~~`#ENDIF`\~~
64		-	~~`#ENDIF`~~
	59	+	```
	60	+	#IFDEF CPUPOWERPC
	61	+	-Fu<path/to/install>/lib/fpc/$fpcversion/units/$FPCTARGET
	62	+	-Fu<path/to/install>/lib/fpc/$fpcversion/units/$FPCTARGET/*
	63	+	#IFDEF AMIGAOS4
	64	+	-FD</path/to/amigaos4-cross-binutils>
	65	+	-XPppc-amigaos-
	66	+	#ENDIF
	67	+	#ENDIF
	68	+	```
65	69
66	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:
67	71
68		-	~~`ppcrossppc -Tamiga <source.pas>`~~
	72	+	```
	73	+	ppcrossppc -Tamiga <source.pas>
	74	+	```
69	75
70	76		Copy the resulting executable to AmigaOS4, and that's it!
71	77
72	78		### Bootstrapping a compiler from Linux
73	79
74	80		To bootstrap a Free Pascal Compiler from Linux to AmigaOS4, first please complete the previous section.
75	81
76	82		After you have a working cross compiler, go to the SVN trunk/compiler directory, and issue the following commands:
77	83
78	84		``` bash
79	85		make compiler OS_TARGET=amiga CPU_TARGET=powerpc FPC="<path/to/install>/lib/fpc/3.1.1/ppcrossppc"
80	86		```
81	87
82	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:
83	89
84		-	~~`set PATH=/SDK/Local/C`\~~
85		-	~~`gmake cycle FPC=/path/to/ppcppc`~~
	90	+	```
	91	+	set PATH=/SDK/Local/C
	92	+	gmake cycle FPC=/path/to/ppcppc
	93	+	```
86	94
87	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.
88	96
89	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!
90	98
91	99		## Assembler and Linker
92	100
93	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).
94	102
95	103		You can change the linker back to GNU ld by adding -XV- argument when compiling. For cross compilers -XV argument enables vlink.
96	104
97	105		### Linker problems
98	106
99	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.
100	108
101	109		### Assembler problems
102	110
103	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.
104	112
105	113		## Preliminary information about language elements to support the port
106	114
107	115		BIG FAT WARNING! All information below this line is preliminary, and subject to change without any further notice. OK, you've been warned.
108	116
109	117		### Library interfaces and Syscalls
110	118
111	119		Syscalls are used in AmigaOS4, to provide calls to libraries through OS4 interfaces. Syntax is proposed to be the following:
112	120
113	121		``` pascal
114	122		var
115	123		myLibBase: PLibrary;
116	124
117	125		type
118	126		TmyLibIface = record
119	127		Data: TInterface;
120	128
121	129		Obtain: function(self as hidden): longword; SysCall;
122	130		Release: function(self as hidden): longword; SysCall;
123	131		Expunge: procedure(self as hidden); SysCall;
124	132		Clone: function(self as hidden): POS4Interface; SysCall;
125	133
126	134		myCallFoo: function(self as hidden; a: longint; b: pointer): pointer; SysCall;
127	135		myCallBar: procedure(self as hidden; c: pchar; d: byte); SysCall;
128	136		end;
129	137		PmyLibIface = ^TmyLibIface;
130	138
131	139		var
132	140		ImyLib: PmyLibIface;
133	141		begin
134	142		// here the opening the library and interface, blah...
135	143
136	144		ImyLib^.myCallFoo(0,nil);
137	145		ImyLib^.myCallBar('a',1);
138	146
139	147		// releasing stuff
140	148		end;
141	149		```
142	150
143	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.
144	152
145	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.
146	154
147	155		## More information
148	156
149	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.
150	158
151	159		---
152	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).
153	161		Category: AmigaOS
154	162		Category: Operating Systems and Platforms

Back to history