Atari: what changed

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

Old	New		Line
1	1		This page is about the Atari TOS version of Free Pascal, which means [[m68k\|Motorola 680x0]] CPU based Atari systems running TOS and compatibles.
2	2
3	3		## Status
4	4
5	5		The initial port was done by Károly Balogh, maintainer of the [[m68k]] and [[Amiga]] ports, based on some existing bits from FPC 0.x and 1.x times done by Carl Eric Codere and others. The port was further improved thanks to the extensive contributions by Thorsten Otto. The Atari TOS port lacks a maintainer currently. This means although we try to keep it working and do minor fixes to it, the port receives no new features. Contact the [[m68k]] port maintainer, if you are interested in stepping up as an Atari maintainer.
6	6
7	7		The Atari port is in a low support tier, which means we don't really support "stable" compiler versions. This document reflects the status in the "main" branch.
8	8
9	9		The RTL support is reasonably advanced, and it's sufficient to run the compiler itself on Atari TOS, but - given the real hardware's constraints - it's not extensively tested. Most of the System, Sysutils and DOS units are implemented, some parts of it are not, or not very well tested though. The "tosunits" package is available for direct OS call bindings, and are fairly complete at this point. See section OS Bindings for details. The Atari TOS port doesn't support MiNT long file names at this point.
10	10
11	11		## Identification
12	12
13	13		To identify Atari TOS during compile-time, use {\$IFDEF ATARI}.
14	14
15	15		## AppType directive
16	16
17	17		Atari is among the few platforms actually support the \$APPTYPE directive, originating from Delphi and Windows. There are currently two states:
18	18
19	19		- \$APPTYPE CONSOLE - the resulting executable will have .TTP extension
20	20		- \$APPTYPE GUI - the resulting executable will have .PRG extension
21	21
22	22		The default is CONSOLE, so compiled programs will have .TTP extension. The directive doesn't affect any other code generation or run-time behavior, except the resulting executable name.
23	23
24	24		## SysCalls
25	25
26	26		Free Pascal supports generating Atari TOS-style system calls, also known as traps. It's not required to use inline assembly to do system calls. However, you must declare every function you're going to use in the following way:
27	27
28	28		``` pascal
29	29		function gemdos_fwrite(handle: smallint; count: longint; buf: pointer): longint; syscall 1 64;
30	30		```
31	31
32	32		Note the syscall modifier in the function declaration. The first argument to the syscall modifier is the trap number to call, and the second one is the trap opcode. All syscall parameters are passed on the stack and they're word (2 byte) aligned. For further examples, see rtl/atari/gemdos.inc in the RTL source.
33	33
34	34		## Linker
35	35
36	36		For Atari, some versions of GNU ld linker available online is known to be problematic when working together with Free Pascal. It's recommended to use vlink by Frank Wille, while compiling to Atari TOS with FPC. Specifying -XV argument enables vlink for cross compilers. The native compiler defaults to vlink, to switch the linker back to GNU ld use -XV- argument.
37	37
38	38		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). For advanced features like named sections and section garbage collection, use vlink 0.15d or newer.
39	39
40	40		Due to TOS executable format limitations, code compiled for 68020 and newer CPUs might not work at this time, so use the option -Cp68000 to force the compiler to 68000 only mode. See the additional notes about 68000 constraints on the [[m68k]] page.
41	41
42	42		## Assembler
43	43
44	44		The Atari TOS 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.
45	45
46	46		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.
47	47
48	48		WARNING: vasm versions between 1.9a and 1.9c - these versions inclusive - contain a bug, which makes it impossible to use these versions with Free Pascal on any [[m68k]] platform. Please stick to vasm versions 1.8 (any letter), 1.9 (no letter) or 1.9d, or newer.
49	49
50	50		#### Building vasm for FPC
51	51
52	52		Note that vasm for m68k needs to be built with the standard syntax module to work with FPC. This is not the default, as most coders and compilers (like vbcc itself) prefer the Motorola syntax module. A vasm version with the standard syntax module can be built with the following command, issued in the root of the vasm source tree:
53	53
54	54		``` bash
55	55		make CPU=m68k SYNTAX=std
56	56		```
57	57
58	58		The resulting vasmm68k_std executable file is the assembler is the one FPC needs.
59	59
60	60		## Cross compiling
61	61
62	62		### Dependencies
63	63
64	64		Free Pascal requires cross-binutils for the target platform. Additionally, the TOS version also needs vlink and optionally vasm. For Atari TOS/MiNT cross-binutils for various platforms, also as binary downloads, [see this page by Vincent Rivière](http://vincent.riviere.free.fr/soft/m68k-atari-mint/). For vlink and vasm see the relevant sections above.
65	65
66	66		### Building
67	67
68	68		To build an Atari cross-compiler, use the following steps:
69	69
70	70		1. Install the latest stable FPC version, at the time of the writing of this article this is FPC 3.2.2. This will be used as the startup compiler.
71	71		2. Clone the FPC git repository.
72	72		3. Make sure you have Atari TOS cross-binutils and vlink, and optionally vasm in the PATH.
73	73		4. Go to the repository's directory, make sure you are on the main branch and use the following command to build an FPC cross-compiler:
74	74
75	75		``` bash
76	76		make clean crossall crossinstall OS_TARGET=atari CPU_TARGET=m68k CROSSOPT="-Cp68000" INSTALL_PREFIX="<path/to/install>"
77	77		```
78	78
79	79		Or, to build everything with vasm instead, use:
80	80
81	81		``` bash
82	82		make clean crossall crossinstall OS_TARGET=atari CPU_TARGET=m68k CROSSOPT="-Avasm -Cp68000" INSTALL_PREFIX="<path/to/install>"
83	83		```
84	84
85	85		If you've done everything right, you should find a working Atari cross-compiler in the install path you've specified.
86	86
87	87		Now, lets create a default fpc.cfg for Atari 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:
88	88
89		-	~~```~~
	89	+	```text
90	90		#IFDEF CPUM68K
91	91		-Fu<path/to/install>/lib/fpc/$fpcversion/units/$FPCTARGET
92	92		-Fu<path/to/install>/lib/fpc/$fpcversion/units/$FPCTARGET/*
93	93		#IFDEF ATARI
94	94		-FD</path/to/atari-cross-binutils>
95	95		-Cp68000
96	96		-XV
97	97		#ENDIF
98	98		#ENDIF
99	99		```
100	100
101	101		Optionally add \<path/to/install\>/lib/fpc/3.3.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 Atari executables:
102	102
103		-	~~```~~
	103	+	```text
104	104		ppcross68k -Tatari <source.pas>
105	105		```
106	106
107	107		## OS Bindings
108	108
109	109		The "tosunits" package contains the direct OS bindings, and it's fairly complete at this point. It provides AES, VDI, GEMDOS and XBIOS bindings. The bindings were developed using the [tos.hyp documentation](http://toshyp.atari.org/en/index.html), and various other bits of information available around the net. The still missing bindings should be very easy to add, using the existing ones as a template. Some work has been included to be compatible with Pure Pascal OS bindings, therefore support compiling of existing code.
110	110
111	111		### Naming differences
112	112
113	113		The bindings try to follow the established function names for OS functions. However, there are some differences compared to the C language, to avoid confusion caused by collisions in the global namespace. The most important are:
114	114
115	115		- All GEMDOS functions start with the prefix gemdos_. For example fwrite() becomes gemdos_fwrite().
116	116		- All XBIOS functions start with the prefix xbios_. For example random() becomes xbios_random().
117	117		- As a de-facto convention with Pascal, all type names are prefixed with T and all pointers to those types are prefixed with P. For example the AES MFORM structure is named TMFORM in Free Pascal, and a pointer to TMFORM is defined as PMFORM. Additionally, the AES OBJECT structure is named TAESOBJECT to avoid conflict with the TObject class type defined in the System unit.
118	118
119	119		Note that most of these naming differences are not mandated, but simply there for practical reasons: to avoid confusion and cryptic error messages during compilation, in case a wrong type or function gets referenced with an overlapping name. If necessary to compile some older code, aliases with the regular naming can be added easily.
120	120
121	121		### Examples
122	122
123	123		The "tosunits" package provides a few examples which show the bindings and TOS/GEM API used natively. Further contributions are welcomed.
124	124
125	125		## Missing features
126	126
127	127		### Truncate
128	128
129	129		It's not possible to trivially implement a truncate() procedure on the original Atari TOS. This function is not supported by FPC on TOS. It might be implemented for a future MiNT support though.
130	130
131	131		---
132	132		From the Free Pascal wiki, page "Atari", as it stood on 2023-04-23 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).
133	133		Category: Operating Systems and Platforms

Back to history