AmigaOS: what changed

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

Back to history