MorphOS: what changed

Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		(MorphOS only)
2	2
3	3		This page contains platform specific notes about the MorphOS port of Free Pascal. MorphOS is a massively enhanced, independent AmigaOS-clone, featuring ABI and API compatibility with classic [[Amiga]], running on various PowerPC platforms. For more information, [see its homepage](http://www.morphos-team.net).
4	4
5	5		## Identification
6	6
7	7		To identify MorphOS exclusively during compile-time, use {\$IFDEF MORPHOS}. To identify any Amiga-like systems, 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, and the AMIGA define is NOT defined on MorphOS.
8	8
9	9		## Stack
10	10
11	11		Under MorphOS, 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. The memory area for the stack is dynamically allocated on program startup, so if you set this value too high, in low memory situations your program may exit immediately on startup without any further notice.
12	12
13	13		Note to classic Amiga programmers: Increasing stack size with the 'stack' utility provided with MorphOS will not work because it sets the size of the 68k stack for applications running in 68k emulation.
14	14
15	15		## SysCalls
16	16
17	17		### Introduction to SysCalls
18	18
19	19		Free Pascal supports ABox style legacy, and four new calling conventions based on SysV ABI on MorphOS. Before that, only ABox style calls were supported. You don't need to use additional hand-written assembly to call any library function. However, you must declare every function you're going to use in the following way:
20	20
21	21		``` pascal
22	22		Var
23	23		my_LibBase: Pointer;
24	24
25	25		function my_OldCall(param1: LongInt location 'd0',
26	26		param2: LongInt location 'd1'): LongInt;
27	27		SysCall Legacy my_LibBase 1234; { ABox-style call }
28	28
29	29		function my_SysVCall(param1: LongInt;
30	30		param2: LongInt): LongInt;
31	31		SysCall SysV my_LibBase 1240; { SysV ABI call }
32	32
33	33		function my_BaseSysVCall(param1: LongInt;
34	34		param2: LongInt): LongInt;
35	35		SysCall BaseSysV my_LibBase 1246; { Base,SysV ABI call }
36	36
37	37		function my_SysVBaseCall(param1: LongInt;
38	38		param2: LongInt): LongInt;
39	39		SysCall SysVBase my_LibBase 1252; { SysV,Base ABI call }
40	40
41	41		function my_R12BaseCall(param1: LongInt;
42	42		param2: LongInt): LongInt;
43	43		SysCall R12Base my_LibBase 1258; { SysV,r12Base ABI call }
44	44		```
45	45
46	46		Where my_LibBase is the library base returned by exec's OpenLibrary() call, and 1234 is the call offset. Please note that offset values in Free Pascal must be specified as positive values, and not negative as shown in MorphOS SDK. Since compiler version 2004/08/22, my_LibBase can be a typed pointer, beside a dword and a void pointer. It's recommended to use PLibrary or the library's own type if one exists or possible.
47	47
48	48		In case of ABox style calls, the value after location can be any 68k register from d0-d7/a0-a5. Register a6 is used internally to pass my_LibBase in it. Register a7/sp cannot be used. Register names are not case sensitive. In ABox-style SysCalls you must specify a location for every argument explicitly.
49	49
50	50		If you don't want to specify SysCall method explicitly for every call, you can set a default SysCall method, using the {\$SYSCALL} directive. {\$SYSCALL LEGACY} (which is the built-in default) sets ABox-style, {\$SYSCALL SYSV} sets SysV style calls as default. Other possible arguments for {\$SYSCALL} directive are SYSVBASE, BASESYSV and R12BASE. Please note that the calling convention rules are not strict inside a library, so you might found different kinds of it inside a single library.
51	51
52	52		### What different kinds of SysCalls do?
53	53
54	54		Old libraries like exec and dos mostly using Legacy and SysV, newer PowerPC-native libs using SysV and BaseSysV, most current libs are using SysV and R12Base calls. SysVBase calls are rare, but do exist, so check for them when you create your own units for external libraries. If you want to figure out which calling convention a library uses, you can search its SDK for some fd/*.fd files, where this information is stored.
55	55
56	56		#### Legacy
57	57
58	58		Legacy calling convention puts arguments into the 68k emulation structure, which is pointed by register r2. 0(r2) equals to 68k register d0, 4(r2) to d1, and so on. It puts libbase into 56(r2) which equals to 68k register a6, then puts call offset into r3, and jumps to address stored at \$64(r2), which is the emulation entry point. On return it returns arguments in register r3. This calling convention is used to provide compatibility with existing 68k and classic Amiga PowerPC (WarpOS and PowerUP) apps.
59	59
60	60		#### SysV
61	61
62	62		SysV calling convention stores arguments according to SysV.4 ABI, then jumps to address stored at (LibBase - Offset). This calling convention is often used where no LibBase is needed.
63	63
64	64		#### BaseSysV
65	65
66	66		BaseSysV is a variation of SysV. It stores LibBase as first argument according to SysV.4 ABI, then puts all other arguments, then jumps to address stored at (LibBase - Offset). This calling convention also can be considered as legacy, R12Base convention replaced it, but still many libraries using it.
67	67
68	68		#### SysVBase
69	69
70	70		SysVBase is a variation of SysV. It stores all arguments according to SysV.4 ABI, then stores LibBase as last argument, then jumps to address stored at (LibBase - Offset). This calling convention also can be considered as legacy, as R12Base convention replaced it. This one is rare, not many libraries using it.
71	71
72	72		#### R12Base
73	73
74	74		R12Base is a variation of SysV. It stores all arguments according to SysV.4 ABI, then stores LibBase into register r12, then jumps to address stored at (LibBase - Offset). This calling convention superseeded BaseSysV and SysVBase, and should be used in new libraries.
75	75
76	76		### Other hints about libraries and Syscalls
77	77
78	78		MOST IMPORTANT: You must open the libraries you're going to use explicitly before using any function from them, because the compiler will not do it for you. Don't forget to close all libraries before you exit.
79	79
80	80		Before declaring a SysCall function, please check the units provided with FPC, the function you want to use might already be declared in one of the units, ready to be used.
81	81
82	82		## Naming conventions
83	83
84	84		This section describes the differences between the official MorphOS SDK, which is for C language, and MorphOS-specific units in FPC RTL.
85	85
86	86		### Constants
87	87
88	88		System constants are named exactly like in MorphOS SDK.
89	89
90	90		### Structures
91	91
92	92		System structures are named similar like in MorphOS 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:
93	93
94		-	~~` struct Task equals to TTask`\~~
95		-	~~` struct Task * equals to PTask`~~
	94	+	```text
	95	+	struct Task equals to TTask
	96	+	struct Task * equals to PTask
	97	+	```
96	98
97	99		### Function calls
98	100
99	101		System calls are named like in MorphOS SDK, but there are a few exceptions. Unfortunately MorphOS legacy (Amiga compatible) API has some name conflicts with Free Pascal RTL functions, and this issue cannot be solved with function overloading. These calls are available with a name prefixed by their library's name. So for example, exec.library's FreeMem() is available under the name execFreeMem(), and FreeMem() means the FreeMem() call of FPC's own heap manager. The following functions are known to be affected:
100	102
101	103		- exec.library
102	104		- AllocMem() (only causes trouble inside System unit),
103	105		- FreeMem()
104	106		- Insert()
105	107		- dos.library
106	108		- Close()
107	109		- Read()
108	110		- Write()
109	111		- Input()
110	112		- Output()
111	113		- Seek()
112	114		- Rename()
113	115		- Exit()
114	116		- Flush()
115	117		- System()
116	118		- DeleteFile() (conflicts with SysUtils)
117	119		- CreateDir() (conflicts with SysUtils)
118	120		- graphics.library
119	121		- Move() (conflicts with Video)
120	122
121	123		Be prepared for more...
122	124
123	125		#### MUI
124	126
125	127		In the following section there are a few hints about using MUI with Free Pascal.
126	128
127	129		1. set() and get() MUI macros available under name MUIset() and MUIget(), to avoid name conflicts with Pascal language. These are wrappers to the appropriate Intuition functions just like in C.
128	130		2. To avoid unnecessary typecasting, MUI_TRUE and MUI_FALSE declared instead of plain True and False. Using these is recommended.
129	131		3. There are various helper functions in MUIHelper unit, to make Pascal code using MUI much simpler and more readable. Use them.
130	132		4. Pascal preprocessor won't preparse strings like C does. So text formatting sequences widely used in MUI applications like \033c and so won't work. You have to use the defined constants instead. Example:
131	133
132	134		C version:
133	135
134	136		``` c
135	137		"\033cCentered \033bBold Text"
136	138		```
137	139
138	140		Pascal version:
139	141
140	142		``` pascal
141	143		MUIX_C+'Centered '+MUIX_B+'Bold Text'
142	144		```
143	145
144	146		or
145	147
146	148		``` pascal
147	149		#27'cCentered '#27'bBold Text'
148	150		```
149	151
150	152		- Note: these constants are there in official mui.h includes as well, they're just rarely used.
151	153
152	154		## Alignment
153	155
154	156		Record elements are aligned to DWORD (4 bytes) under MorphOS by default. Use {\$PACKRECORDS 2} if you need word aligned structures. For byte aligned records, use a packed record.
155	157
156	158		## Threading
157	159
158	160		Threading is supported on MorphOS since Free Pascal 3.0, using the [[AThreads]] unit. Read there for possible caveats and unsupported features.
159	161
160	162		## Things good to know
161	163
162	164		Here are a few hints, which I think are good to remember, when using FPC on MorphOS.
163	165
164	166		- On program exit, System unit will close all files opened via its own functions, so it's recommended to use them in most cases.
165	167		- Do not mix FPC and OS file functions on a single file. It may work in some cases, but that's purely a coincidence. It's bad programming and can stop working anytime without notice.
166	168		- On program exit, the heap manager will free all memory allocated via its own functions. It uses a memory pool to avoid fragmentation. It also makes debugging easier when using heaptrc unit. Using OS memory functions directly is not recommended.
167	169
168	170		- Scribble, which is a programmer's editor based on [Scintilla](http://www.scintilla.org) is included in MorphOS SDK 2.x and part of MorphOS 3.x itself, and supports Pascal syntax highlighting out of box.
169	171		- Another option for syntax highlighted editing is GoldEd, [also known as Cubic IDE](http://www.softwareandcircuits.com/division/amiga/products/cubic/index.html) (or the lite version MorphEd, which was available as part of older MorphOS SDKs). A very nice Pascal syntax highlight addon was made for it by Rafal Zabdyr. The original site is down, but a backup is available here: <http://obligement.free.fr/files/ged5morphed_pas075.lha>
170	172
171	173		- You can find some MorphOS specific examples in the SVN, directly accessible here: <http://svn.freepascal.org/cgi-bin/viewvc.cgi/trunk/demo/morphos/?root=fpcbuild>
172	174
173	175		## Cross compiling
174	176
175	177		Cross compiling to MorphOS is supported since version 3.0.0 and up.
176	178
177	179		### Cross compiling from Linux
178	180
179	181		It's possible to cross-build the MorphOS compiler from Linux/i386 and Linux/x86-64 (probably other CPUs too, but it was not tested). To do that, you need Linux to MorphOS 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. Mark "bigfoot" Olsen kindly provided a script for this, [available here](http://bigfoot.morphos-team.net/files/setup-cross-sdk.sh).
180	182
181	183		Optionally, the binutils required by FPC are [available here as binary](http://charlie.amigaspirit.hu/software/fpc/morphos/cross-binutils-linux-i386.tar.gz) for Linux/i386 (works on Linux/x86-64 too, if you install the required 32 bit environment). It was only tested on Ubuntu and Debian Linuxes, but may work on other distributions too. This package is provided "as-is" without any kind of support. Use it at your own risk.
182	184
183	185		To build a MorphOS cross-compiler, use the following steps:
184	186
185	187		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.
186	188		2. Check out FPC SVN trunk into a directory (see version info above)
187	189		3. Make sure the aforementioned cross-binutils are actually in the PATH.
188	190		4. Go to the trunk's main directory and use the following command to build an FPC to MorphOS cross-compiler running on Linux:
189	191
190	192		``` bash
191	193		make clean crossall crossinstall OS_TARGET=morphos CPU_TARGET=powerpc INSTALL_PREFIX="<path/to/install>"
192	194		```
193	195
194	196		If you've done everything right, you should find a working MorphOS cross-compiler in the install path you've specified.
195	197
196	198		Now, lets create a default fpc.cfg for MorphOS 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:
197	199
198		-	~~`#IFDEF CPUPOWERPC`\~~
199		-	~~`-Fu<path/to/install>/lib/fpc/$fpcversion/units/$FPCTARGET`\~~
200		-	~~`-Fu<path/to/install>/lib/fpc/$fpcversion/units/$FPCTARGET/*`\~~
201		-	~~`#IFDEF MORPHOS`\~~
202		-	~~`-FD</path/to/morphos-cross-binutils>`\~~
203		-	~~`-XPpowerpc-morphos-`\~~
204		-	~~`#ENDIF`\~~
205		-	~~`#ENDIF`~~
	200	+	```text
	201	+	#IFDEF CPUPOWERPC
	202	+	-Fu<path/to/install>/lib/fpc/$fpcversion/units/$FPCTARGET
	203	+	-Fu<path/to/install>/lib/fpc/$fpcversion/units/$FPCTARGET/*
	204	+	#IFDEF MORPHOS
	205	+	-FD</path/to/morphos-cross-binutils>
	206	+	-XPpowerpc-morphos-
	207	+	#ENDIF
	208	+	#ENDIF
	209	+	```
206	210
207	211		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 MorphOS executables from Pascal source on Linux the following way:
208	212
209		-	~~`ppcrossppc -Tmorphos <source.pas>`~~
	213	+	```text
	214	+	ppcrossppc -Tmorphos <source.pas>
	215	+	```
210	216
211	217		Copy the resulting executable to MorphOS, and that's it!
212	218
213	219		### Cross compiling from OSX
214	220
215	221		In general, the same rules and steps apply as for Linux cross compiling. To build the binutils from sources using Mark Olsen's script (see in the previous section) some slight modifications to the script and/or additional GNU tools might be required.
216	222
217	223		For convenience, a binutils package required by FPC are [available here as binary](http://charlie.amigaspirit.hu/software/fpc/morphos/cross-binutils-darwin-i386.tar.gz) for Darwin/i386. This package is provided "as-is" without any kind of support. Use it at your own risk.
218	224
219	225		### Cross compiling from Windows
220	226
221	227		In general, the same rules and steps apply as for Linux cross compiling. It's also possible to cross-build the binutils with [Cygwin](http://cygwin.com) using Mark Olsen's script, as linked in the previous section.
222	228
223	229		For convenience, a binutils package required by FPC are [available here as binary](http://charlie.amigaspirit.hu/software/fpc/morphos/cross-binutils-cygwin-i686.zip) for Windows/x86 (Cygwin/i686). This package is provided "as-is" without any kind of support. Use it at your own risk.
224	230
225	231		As FPC on Windows use a bit different directory structure the place to put our fpc.cfg is: \<path/to/install\>/bin/i386-win32/fpc.cfg. Also, for easy access, make sure directory \<path/to/install\>/bin/i386-win32/ is part of the PATH.
226	232
227	233		The cross-build from Windows/x64 was not tested, but should work with the obvious differences in paths and tools.
228	234
229	235		## Bootstrapping a compiler from Linux
230	236
231	237		To bootstrap a Free Pascal Compiler from Linux to MorphOS, first please complete the previous section. In order to have all the tools available, it's easiest to install the latest FPC compiler archive [available here.](http://charlie.amigaspirit.hu/software/fpc/morphos/)
232	238
233	239		After you have a working cross compiler, go to the SVN trunk/compiler directory, and issue the following command:
234	240
235	241		``` bash
236	242		make compiler OS_TARGET=morphos CPU_TARGET=powerpc FPC="<path/to/install>/lib/fpc/2.7.1/ppcrossppc"
237	243		```
238	244
239	245		Copy the resulting ppcppc executable to MorphOS. On the MorphOS box, try to cycle a compiler the following way in the SVN's trunk/compiler directory:
240	246
241		-	~~`make cycle FPC=/path/to/ppcppc`~~
	247	+	```text
	248	+	make cycle FPC=/path/to/ppcppc
	249	+	```
242	250
243	251		Congratulations, you've just successfully bootstrapped Free Pascal on MorphOS! Now, copy everything in place by hand to your FPC: assign, build more stuff, etc... :)
244	252
245	253		## Linker
246	254
247	255		Some version of Free Pascal on MorphOS, including latest SVN trunk versions default to vlink by Frank Wille as the default linker, when running natively on MorphOS. 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).
248	256
249	257		You can change the linker back to GNU ld by adding -XV- argument when compiling. For cross compilers -XV argument enables vlink.
250	258
251	259		## Assembler
252	260
253	261		The MorphOS port supports both GNU as assembler and vasm. Advanced features like named sections support are only available with vasm. To compile with vasm, you need to specify the argument -Avasm compile time. Please note that mixing GNU as and vasm compiled objects might cause issues during linking.
254	262
255	263		vasm is open source, and it is available [here](http://sun.hasenbraten.de/vasm). Binaries are available as part of the [vbcc compiler package](http://sun.hasenbraten.de/vbcc). Only vasm versions 1.7h and newer were tested, older versions might not work.
256	264
257	265		If -Avasm is set as default, for example in the config file, one can switch back to GNU as by using the -Aas-legacy command line argument. Please note that since the MorphOS SDK has a very old GNU as bundled, there could be problems with some of the assembly code generated by using the normal GNU as argument -Aas.
258	266
259	267		## More information
260	268
261	269		More information regarding Free Pascal and MorphOS 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 MorphOS.
262	270
263	271		## Thanks
264	272
265	273		The initial [MorphOS](http://www.morphos-team.net) port of Free Pascal Compiler was possible, because [Genesi](http://genesi.pegasosppc.com) provided a free [Pegasos II/G4](http://en.wikipedia.org/wiki/Pegasos) machine to do the development on.
266	274
267	275		---
268	276		From the Free Pascal wiki, page "MorphOS", as it stood on 2023-12-11 after a change by Polluks, 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).
269	277		Category: AmigaOS
270	278		Category: Operating Systems and Platforms

Back to history