DOS: what changed

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

Old	New		Line
1	1		> Note: This page has outdated information. Somebody is updating the information but you can help.
2	2
3	3		## Overview
4	4
5	5		A DOS (8086) cross compiler is currently being developed in FPC trunk (the development version). It started as a hobby project meant to explore how to port FPC to a new platform.
6	6
7	7		The number of (FPC on) DOS users is probably quite low, especially since there is an FPC compiler for the more capable [[GO32V2]] DOS extender available which runs on 80386+ processors.
8	8
9	9		### Advantages over FPC for GO32V2
10	10
11	11		- Generated code can run on 16-bit processors. Since these processors are obsolete and out of production, this is mostly useful for [retrocomputing](http://en.wikipedia.org/wiki/Retrocomputing) purposes. Note also that the 80186 is still in use in embedded devices: [1](http://www.cpushack.com/2013/01/12/the-intel-80186-gets-turbocharged-vautomation-turbo186/)
12	12		- It's possible to write [TSRs](http://en.wikipedia.org/wiki/Terminate_and_Stay_Resident).
13	13		- It's possible to write DOS .SYS device drivers. (Not ready yet, but should be easy to implement)
14	14		- It allows writing a bootloader in Pascal.
15	15		- It allows writing 16-bit BIOS code in Pascal (e.g. you can now do a project like [SeaBIOS](http://www.seabios.org) but in Pascal).
16	16		- It can compile Turbo Pascal 7 code with less changes needed, compared to GO32V2 (no need to port the inline assembly code, for example).
17	17		- Real mode DOS programs are less sensitive to bugs in virtual DOS environments, since they're immune to DPMI bugs and in fact require no DPMI at all. (Provided that your program fits within the memory constraints, of course.)
18	18		- Compiled binaries are smaller and you don't have to ship CWSDPMI.EXE in order for your program to work under real DOS.
19	19
20	20		### Advantages over Turbo Pascal
21	21
22	22		- Compiler is Free/Open Source software and is in active development.
23	23		- Supports long file names.
24	24		- Not affected (just like FPC for GO32v2) by the infamous CRT unit bug, that causes runtime error 200 on startup when the program is run on a fast CPU.
25	25		- Multiple memory models are supported.
26	26		- Supports huge pointers.
27	27		- Heap manager supports allocating blocks larger than 64 KB (only in the memory models with far data, such as compact, large or huge).
28	28		- All the extra Object Pascal features supported by FPC should work. This includes ansistrings, classes, interfaces, exceptions, generics, etc.
29	29		- Crosscompilation is doable without running the development system in a dosbox/VM (compile/build on Windows 64-bit, only need 16-bit capable OS for running)
30	30
31	31		### Limitations
32	32
33	33		The DOS platforms brings some limitations, like
34	34
35	35		- data structures cannot be larger than 64KB
36	36		- no simple way of pre-emptive multitasking.
37	37		- it is unlikely the Lazarus LCL GUI will be ported to the DOS environment
38	38		- However, an [OpenGEM](http://en.wikipedia.org/wiki/OpenGEM) widget set is possible
39	39		- Since the large memory model of the i8086 code generator have matured, [[Win16]] support has also been started in FPC trunk
40	40
41	41		## Requirements
42	42
43	43		### FPC 3.0.x
44	44
45	45		The compiler is a cross compiler that runs at least on Windows (both x86 and x64), Linux, and macOS. For compiling programs, it needs:
46	46
47	47		- the Open Watcom linker - WLINK
48	48		- the Open Watcom library manager - WLIB
49	49		- the Netwide Assembler - [NASM](http://www.nasm.us/)
50	50
51	51		In theory it should be able to run on any platform, supported by FPC, where NASM and the Open Watcom tools are available. This includes DOS via the GO32V2 extender. However, because the Watcom tools for DOS are compiled with a different extender, there are some issues related to long file names and the passing of long command line arguments. This is resolved in FPC trunk, where there's an internal assembler and linker implemented in the compiler itself.
52	52
53	53		### FPC trunk
54	54
55	55		FPC trunk contains an internal assembler and linker for DOS, so the Open Watcom tools are no longer required. NASM is still required for building an i8086-msdos snapshot, because of the msdos startup code in the rtl.
56	56
57	57		## Releases
58	58
59	59		### 3.0.4
60	60
61	61		The crosscompiler packages for Windows, Linux - i386 and Linux - x86_64 are also available at the official Free Pascal website: <http://freepascal.org/download.var>
62	62
63	63		- Crosscompiler package for Windows:
64	64		- <ftp://ftp.freepascal.org/pub/fpc/dist/3.0.4/i386-win32/fpc-3.0.4.i386-win32.cross.i8086-msdos.exe>
65	65		- Crosscompiler package for Linux - i386
66	66		- .tar.xz: <ftp://ftp.freepascal.org/pub/fpc/dist/3.0.4/i386-linux/fpc-3.0.4.i386-linux.cross.i8086-msdos.tar.xz>
67	67		- RPM: <ftp://ftp.freepascal.org/pub/fpc/dist/3.0.4/i386-linux/fpc-i8086-msdos-3.0.4-1.i686.rpm>
68	68		- SRPM: <ftp://ftp.freepascal.org/pub/fpc/dist/3.0.4/i386-linux/fpc-i8086-msdos-3.0.4-1.src.rpm>
69	69		- Crosscompiler package for Linux - x86_64
70	70		- .tar.xz: <ftp://ftp.freepascal.org/pub/fpc/dist/3.0.4/x86_64-linux/fpc-3.0.4.x86_64-linux.cross.i8086-msdos.tar.xz>
71	71		- RPM: <ftp://ftp.freepascal.org/pub/fpc/dist/3.0.4/x86_64-linux/fpc-i8086-msdos-3.0.4-1.x86_64.rpm>
72	72		- SRPM: <ftp://ftp.freepascal.org/pub/fpc/dist/3.0.4/x86_64-linux/fpc-i8086-msdos-3.0.4-1.src.rpm>
73	73
74	74		### 3.0.2
75	75
76	76		- Crosscompiler package for Windows:
77	77		- <ftp://ftp.freepascal.org/pub/fpc/dist/3.0.2/i386-win32/fpc-3.0.2.i386-win32.cross.i8086-msdos.exe>
78	78		- Crosscompiler package for Linux - i386
79	79		- .tar.xz: <ftp://ftp.freepascal.org/pub/fpc/dist/3.0.2/i386-linux/fpc-3.0.2.i386-linux.cross.i8086-msdos.tar.xz>
80	80		- RPM: <ftp://ftp.freepascal.org/pub/fpc/dist/3.0.2/i386-linux/fpc-i8086-msdos-3.0.2-1.i686.rpm>
81	81		- SRPM: <ftp://ftp.freepascal.org/pub/fpc/dist/3.0.2/i386-linux/fpc-i8086-msdos-3.0.2-1.src.rpm>
82	82		- Crosscompiler package for Linux - x86_64
83	83		- .tar.xz: <ftp://ftp.freepascal.org/pub/fpc/dist/3.0.2/x86_64-linux/fpc-3.0.2.x86_64-linux.cross.i8086-msdos.tar.xz>
84	84		- RPM: <ftp://ftp.freepascal.org/pub/fpc/dist/3.0.2/x86_64-linux/fpc-i8086-msdos-3.0.2-1.x86_64.rpm>
85	85		- SRPM: <ftp://ftp.freepascal.org/pub/fpc/dist/3.0.2/x86_64-linux/fpc-i8086-msdos-3.0.2-1.src.rpm>
86	86
87	87		### 3.0.0
88	88
89	89		- Crosscompiler package for Windows:
90	90		- <ftp://ftp.freepascal.org/pub/fpc/dist/3.0.0/i8086-msdos/fpc-3.0.0.i386-win32.cross.i8086-msdos.exe>
91	91		- Crosscompiler package for Linux - i386
92	92		- .tar.xz: <ftp://ftp.freepascal.org/pub/fpc/dist/3.0.0/i386-linux/fpc-3.0.0.i386-linux.cross.i8086-msdos.tar.xz>
93	93		- RPM: <ftp://ftp.freepascal.org/pub/fpc/dist/3.0.0/i386-linux/rpm/fpc-i8086-msdos-3.0.0-1.i686.rpm>
94	94		- SRPM: <ftp://ftp.freepascal.org/pub/fpc/dist/3.0.0/i386-linux/rpm/fpc-i8086-msdos-3.0.0-1.src.rpm>
95	95		- Crosscompiler package for Linux - x86_64
96	96		- .tar.xz: <ftp://ftp.freepascal.org/pub/fpc/dist/3.0.0/x86_64-linux/fpc-3.0.0.x86_64-linux.cross.i8086-msdos.tar.xz>
97	97		- RPM: <ftp://ftp.freepascal.org/pub/fpc/dist/3.0.0/x86_64-linux/rpm/fpc-i8086-msdos-3.0.0-1.x86_64.rpm>
98	98		- SRPM: <ftp://ftp.freepascal.org/pub/fpc/dist/3.0.0/x86_64-linux/rpm/fpc-i8086-msdos-3.0.0-1.src.rpm>
99	99
100	100		### 3.0.0rc2
101	101
102	102		- Crosscompiler package for Windows:
103	103		- <ftp://ftp.freepascal.org/pub/fpc/beta/3.0.0-rc2/i386-win32/fpc-3.0.0rc2.i386-win32.cross.i8086-msdos.exe>
104	104		- Crosscompiler package for Linux - i386
105	105		- .tar.xz: <ftp://ftp.freepascal.org/pub/fpc/beta/3.0.0-rc2/i386-linux/fpc-3.0.0rc2.i386-linux.cross.i8086-msdos.tar.xz>
106	106		- RPM: <ftp://ftp.freepascal.org/pub/fpc/beta/3.0.0-rc2/i386-linux/rpm/fpc-i8086-msdos-3.0.0-0.rc2.i686.rpm>
107	107		- Crosscompiler package for Linux - x86_64
108	108		- .tar.xz: <ftp://ftp.freepascal.org/pub/fpc/beta/3.0.0-rc2/x86_64-linux/fpc-3.0.0rc2.x86_64-linux.cross.i8086-msdos.tar.xz>
109	109		- RPM: <ftp://ftp.freepascal.org/pub/fpc/beta/3.0.0-rc2/x86_64-linux/rpm/fpc-i8086-msdos-3.0.0-0.rc2.x86_64.rpm>
110	110
111	111		### 3.0.0rc1
112	112
113	113		- Crosscompiler package for Windows:
114	114		- <ftp://ftp.freepascal.org/pub/fpc/beta/3.0.0-rc1/i386-win32/fpc-3.0.0rc1.i8086-msdos.exe>
115	115		- Crosscompiler package for Linux - i386
116	116		- .tar.xz: <ftp://ftp.freepascal.org/pub/fpc/beta/3.0.0-rc1/i386-linux/i8086-msdos-fpc-3.0.0rc1.i386-linux.tar.xz>
117	117		- RPM: <ftp://ftp.freepascal.org/pub/fpc/beta/3.0.0-rc1/i386-linux/rpm/fpc-i8086-msdos-3.0.0-0.rc1.i686.rpm>
118	118		- Crosscompiler package for Linux - x86_64
119	119		- .tar.xz: <ftp://ftp.freepascal.org/pub/fpc/beta/3.0.0-rc1/x86_64-linux/i8086-msdos-fpc-3.0.0rc1.x86_64-linux.tar.xz>
120	120		- RPM: <ftp://ftp.freepascal.org/pub/fpc/beta/3.0.0-rc1/x86_64-linux/rpm/fpc-i8086-msdos-3.0.0-0.rc1.x86_64.rpm>
121	121
122	122		## Snapshots
123	123
124	124		There are daily snapshots available here:
125	125
126	126		<ftp://ftp.freepascal.org/pub/fpc/snapshot/trunk/i8086-msdos/>
127	127
128	128		There's also a snapshot available here, but it's quite outdated, so it's better to simply use the above snapshot or to build your own:
129	129
130	130		<http://www.bttr-software.de/forum/forum_entry.php?id=12985>
131	131
132	132		### Building a snapshot manually
133	133
134	134		- make sure nasm is in your path (the fixes-3.0 branch also requires wlink and wlib)
135	135		- checkout fpc trunk:
136	136
137		-	~~`svn checkout `[`http://svn.freepascal.org/svn/fpc/trunk`](http://svn.freepascal.org/svn/fpc/trunk)` fpc`~~
	137	+	```text
	138	+	svn checkout http://svn.freepascal.org/svn/fpc/trunk fpc
	139	+	```
138	140
139	141		- enter the fpc directory and build the compiler with the following command (replace /usr/bin/ppc386 with the full path to the stable (3.0.4) FPC compiler binary; replace -WmSmall with -WmTiny, -WmMedium, -WmCompact, -WmLarge or -WmHuge if you want to use another memory model):
140	142
141		-	`make clean all OS_TARGET=msdos CPU_TARGET=i8086 OPT="-CX -XXs" CROSSOPT=``-WmSmall`` BINUTILSPREFIX= PP=``/usr/bin/ppc386`
	143	+	```text
	144	+	make clean all OS_TARGET=msdos CPU_TARGET=i8086 OPT="-CX -XXs" CROSSOPT=-WmSmall BINUTILSPREFIX= PP=/usr/bin/ppc386
	145	+	```
142	146
143	147		- install the snapshot (replace linux and i386 with the OS and CPU you're using; replace INSTALL_PREFIX with the directory you want the snapshot installed):
144	148
145		-	~~`make crossinstall OS_SOURCE=``linux`` CPU_SOURCE=``i386`` OS_TARGET=msdos CPU_TARGET=i8086 PP=compiler/ppcross8086 CROSSOPT=``-WmSmall`` \`\~~
146		-	~~` BINUTILSPREFIX= INSTALL_PREFIX=``/home/blablabla/fpc-i8086/snapshot/small`` OPT="-CX -XXs"`~~
	149	+	```text
	150	+	make crossinstall OS_SOURCE=linux CPU_SOURCE=i386 OS_TARGET=msdos CPU_TARGET=i8086 PP=compiler/ppcross8086 CROSSOPT=-WmSmall \
	151	+	BINUTILSPREFIX= INSTALL_PREFIX=/home/blablabla/fpc-i8086/snapshot/small OPT="-CX -XXs"
	152	+	```
147	153
148	154		### Updating your fpc.cfg
149	155
150	156		Add the following to your fpc.cfg to enable smartlinking and disable the default binutils prefix (so that you don't have to rename nasm, wlink and wlib to msdos-nasm, msdos-wlink and msdos-wlib):
151	157
152		-	~~`#ifdef cpui8086`\~~
153		-	~~`-CX`\~~
154		-	~~`-XX`\~~
155		-	~~`-XP`\~~
156		-	~~`#endif`~~
	158	+	```text
	159	+	#ifdef cpui8086
	160	+	-CX
	161	+	-XX
	162	+	-XP
	163	+	#endif
	164	+	```
157	165
158	166		To enable building for all the memory models, build snapshots for the tiny, small, medium, compact, large and huge memory model, and then find the lines in your fpc.cfg that specify the path to the RTL:
159	167
160		-	~~`-Fu/usr/lib/fpc/$fpcversion/units/$fpctarget`\~~
161		-	~~`-Fu/usr/lib/fpc/$fpcversion/units/$fpctarget/*`\~~
162		-	~~`-Fu/usr/lib/fpc/$fpcversion/units/$fpctarget/rtl`~~
	168	+	```text
	169	+	-Fu/usr/lib/fpc/$fpcversion/units/$fpctarget
	170	+	-Fu/usr/lib/fpc/$fpcversion/units/$fpctarget/*
	171	+	-Fu/usr/lib/fpc/$fpcversion/units/$fpctarget/rtl
	172	+	```
163	173
164	174		And update them to something similar to:
165	175
166		-	~~`#IFDEF CPUI8086`\~~
167		-	~~`-Fu/home/blablabla/fpc-i8086/snapshot/$fpcmemorymodel/lib/fpc/$fpcversion/units/$fpctarget`\~~
168		-	~~`-Fu/home/blablabla/fpc-i8086/snapshot/$fpcmemorymodel/lib/fpc/$fpcversion/units/$fpctarget/*`\~~
169		-	~~`-Fu/home/blablabla/fpc-i8086/snapshot/$fpcmemorymodel/lib/fpc/$fpcversion/units/$fpctarget/rtl`\~~
170		-	~~`#ELSE`\~~
171		-	~~`-Fu/usr/lib/fpc/$fpcversion/units/$fpctarget`\~~
172		-	~~`-Fu/usr/lib/fpc/$fpcversion/units/$fpctarget/*`\~~
173		-	~~`-Fu/usr/lib/fpc/$fpcversion/units/$fpctarget/rtl`\~~
174		-	~~`#ENDIF`~~
	176	+	```text
	177	+	#IFDEF CPUI8086
	178	+	-Fu/home/blablabla/fpc-i8086/snapshot/$fpcmemorymodel/lib/fpc/$fpcversion/units/$fpctarget
	179	+	-Fu/home/blablabla/fpc-i8086/snapshot/$fpcmemorymodel/lib/fpc/$fpcversion/units/$fpctarget/*
	180	+	-Fu/home/blablabla/fpc-i8086/snapshot/$fpcmemorymodel/lib/fpc/$fpcversion/units/$fpctarget/rtl
	181	+	#ELSE
	182	+	-Fu/usr/lib/fpc/$fpcversion/units/$fpctarget
	183	+	-Fu/usr/lib/fpc/$fpcversion/units/$fpctarget/*
	184	+	-Fu/usr/lib/fpc/$fpcversion/units/$fpctarget/rtl
	185	+	#ENDIF
	186	+	```
175	187
176	188		This should enable you to build programs in any of the supported memory models with just a compiler switch:
177	189
178		-	~~`ppcross8086 -WmTiny -Wtcom hello.pas`\~~
179		-	~~`ppcross8086 -WmTiny -Wtexe hello.pas`\~~
180		-	~~`ppcross8086 -WmSmall hello.pas`\~~
181		-	~~`ppcross8086 -WmMedium hello.pas`\~~
182		-	~~`ppcross8086 -WmCompact hello.pas`\~~
183		-	~~`ppcross8086 -WmLarge hello.pas`\~~
184		-	~~`ppcross8086 -WmHuge hello.pas`~~
	190	+	```text
	191	+	ppcross8086 -WmTiny -Wtcom hello.pas
	192	+	ppcross8086 -WmTiny -Wtexe hello.pas
	193	+	ppcross8086 -WmSmall hello.pas
	194	+	ppcross8086 -WmMedium hello.pas
	195	+	ppcross8086 -WmCompact hello.pas
	196	+	ppcross8086 -WmLarge hello.pas
	197	+	ppcross8086 -WmHuge hello.pas
	198	+	```
185	199
186	200		And in case you're wondering - it doesn't matter which ppcross8086 compiler binary you use (i.e. from the tiny, small, medium, compact, large or huge model snapshot). They are identical. Only the compiled units differ.
187	201
188	202		## Status
189	203
190	204		The compiler has been enabled as a CPU/OS target in FPC.exe since revision 25792 (CPU: i8086, OS: msdos).
191	205
192	206		The RTL compiles. Most units from Go32v2 have been ported. Just like Go32v2, the RTL supports long file names when run under a Windows 95+/2000+ DOS box or under plain DOS with a long file names driver such as doslfn.exe. FPC demo programs such as fpctris and samegame work in all supported memory models.
193	207
194	208		### Internal linker
195	209
196	210		The internal linker does not support all records and features of the OMF object file format. It was designed to support only the records produced by the NASM assembler and FPC's own internal object writer. You may encounter problems if you try to link object modules produced by other compilers and assemblers.
197	211
198	212		### Floating point support
199	213
200	214		Floating point operations require an FPU. Software FPU emulation is not yet implemented and using floating point operations on a real machine without an FPU will lead to a hang.
201	215
202	216		### Nil pointer assignment checking
203	217
204	218		The small and medium memory models offer rudimentary nil pointer assignment checking. The system RTL puts a pattern of 32 bytes equal to \$01 at the beginning of the data segment (DS:0000). At the end of program execution, this pattern is checked and if turns out it has changed, the message:
205	219
206		-	~~`Nil pointer assignment`~~
	220	+	```text
	221	+	Nil pointer assignment
	222	+	```
207	223
208	224		is printed on the screen. This indicates that a nil pointer assignment has happened at some time during the program execution. Unfortunately, we can't tell when exactly, only that it has happened.
209	225
210	226		### New pointer types
211	227
212	228		To reflect the i8086 segmented memory model, FPC supports several pointer types:
213	229
214	230		#### Near pointers
215	231
216	232		This is the default pointer type in the tiny, small and medium memory models.
217	233
218	234		Near pointers can be declared in any memory model, using the near keyword. For example:
219	235
220	236		``` pascal
221	237		type
222	238		PNearInteger = ^Integer; near;
223	239		```
224	240
225	241		There's also an untyped near pointer, predefined in the system unit, called NearPointer.
226	242
227	243		#### Special versions of near pointers
228	244
229	245		Near pointers are declared using the near keyword, followed by a segment register, enclosed in single quotes. For example:
230	246
231	247		``` pascal
232	248		type
233	249		PNearCSInteger = ^Integer; near 'CS';
234	250		PNearDSInteger = ^Integer; near 'DS';
235	251		PNearESInteger = ^Integer; near 'ES';
236	252		PNearSSInteger = ^Integer; near 'SS';
237	253		PNearFSInteger = ^Integer; near 'FS';
238	254		PNearGSInteger = ^Integer; near 'GS';
239	255		```
240	256
241	257		There are also untyped versions, predefined in the system unit:
242	258
243		-	~~` NearCSPointer`\~~
244		-	~~` NearDSPointer`\~~
245		-	~~` NearESPointer`\~~
246		-	~~` NearSSPointer`\~~
247		-	~~` NearFSPointer`\~~
248		-	~~` NearGSPointer`~~
	259	+	```text
	260	+	NearCSPointer
	261	+	NearDSPointer
	262	+	NearESPointer
	263	+	NearSSPointer
	264	+	NearFSPointer
	265	+	NearGSPointer
	266	+	```
249	267
250	268		#### Far pointers
251	269
252	270		This is the default pointer type in the compact, large and huge memory models.
253	271
254	272		Far pointers can be declared in any memory model, using the far keyword. For example:
255	273
256	274		``` pascal
257	275		type
258	276		PFarInteger = ^Integer; far;
259	277		```
260	278
261	279		There's also an untyped far pointer, predefined in the system unit, called FarPointer.
262	280
263	281		#### Huge pointers
264	282
265	283		Huge pointers are like far pointers that support pointer arithmetic without the 64kb segment wraparound. That means they will automatically switch to a different segment if the offset exceeds 64k or becomes less than 0. Thus, they are very useful for accessing blocks of memory that exceed 64kb. Additionally, they support normalization, which is explained in the next section. Their main disadvantage is that they are quite a bit slower compared to far pointers.
266	284
267	285		Huge pointers are declared using the huge keyword. For example:
268	286
269	287		``` pascal
270	288		type
271	289		PHugeInteger = ^Integer; huge;
272	290		```
273	291
274	292		There's also an untyped huge pointer, predefined in the system unit, called HugePointer.
275	293
276	294		##### Huge pointer normalization
277	295
278	296		In real mode it is possible for several different pointers to point to the same memory address. For example, the following different pointers point to the same memory location:
279	297
280	298		``` pascal
281	299		Ptr($1000, $2345)
282	300		Ptr($1200, $0345)
283	301		Ptr($1234, $0005)
284	302		```
285	303
286	304		This is because they resolve to the same linear address via the formula (segment * 16 + offset):
287	305
288	306		``` pascal
289	307		Ptr($1000, $2345) // -> $1000 * 16 + $2345 = $12345
290	308		Ptr($1200, $0345) // -> $1200 * 16 + $0345 = $12345
291	309		Ptr($1234, $0005) // -> $1234 * 16 + $0005 = $12345
292	310		```
293	311
294	312		A Pointer whose offset is between \$0 and \$F is called a normalized pointer. That's the pointer with the lowest possible offset among all the pointers that point to the same linear address.
295	313
296	314		Huge pointers can be automatically normalized by the compiler when doing pointer arithmetic on them or when comparing them. This is controlled by the \$HugePointerNormalization, \$HugePointerArithmeticNormalization and \$HugePointerComparisonNormalization directives. All three of them are local switches, so you can change the modes in the middle of the program.
297	315
298	316		###### \$HugePointerArithmeticNormalization
299	317
300	318		This directive controls whether huge pointers are automatically normalized by the compiler after doing pointer arithmetic on them.
301	319
302	320		###### \$HugePointerComparisonNormalization
303	321
304	322		This directive controls whether huge pointers are normalized before comparing them.
305	323
306	324		###### \$HugePointerNormalization
307	325
308	326		This sets both \$HugePointerArithmeticNormalization and \$HugePointerComparisonNormalization:
309	327
310	328		\| mode \| arithmetic normalization \| comparison normalization \| description \|
311	329		\|----\|----\|----\|----\|
312	330		\| {\$HugePointerNormalization BorlandC} \| On \| On \| Like Borland C \|
313	331		\| {\$HugePointerNormalization MicrosoftC} \| Off \| Off \| Like Microsoft C \|
314	332		\| {\$HugePointerNormalization WatcomC} \| Off \| On \| Like Watcom C \|
315	333
316	334		### Tested machines
317	335
318	336		Compiled programs have been tested and known to work on the following machines:
319	337
320	338		- [IBM PC 5150](http://oldcomputers.net/ibm5150.html) (the first PC model ever), with a 4.77 MHz 8088 CPU, 512 KB RAM and a CGA card, running IBM DOS 3.30
321	339		- [HP 200LX](http://en.wikipedia.org/wiki/HP_200LX), with a 7.91 MHz 80186 CPU, running MS-DOS 5.0
322	340		- IBM PS/2 Model 30-286, with a 10 MHz 80286 CPU and an AMD 287 FPU, running MS-DOS 6.22
323	341		- various boring 32-bit and 64-bit machines :)
324	342		- [DOSBox](http://en.wikipedia.org/wiki/DOSBox)
325	343
326	344		### Supported memory models
327	345
328	346		#### Tiny
329	347
330	348		- Activated by the `-WmTiny` compiler option
331	349		- Code + Data + Heap + Stack \<= 64KB
332	350		- CS = DS = SS
333	351		- Pointer = NearPointer
334	352		- CodePointer = NearPointer
335	353		- Code starts at offset \$100
336	354		- Can produce both .com and .exe files. The binary format can be chosen with the `-Wtcom` and `-Wtexe` compiler options. The default format is .exe
337	355		- The compiler defines: FPC_MM_TINY
338	356
339	357		#### Small
340	358
341	359		- Activated by the `-WmSmall` compiler option. This is the default memory model, so it is chosen if you don't specify a memory model.
342	360		- Code \<= 64KB, Data + Heap + Stack \<= 64KB (Code and data are in separate segments, so programs can use up to 128KB in total)
343	361		- DS = SS
344	362		- Pointer = NearPointer
345	363		- CodePointer = NearPointer
346	364		- Can produce only .exe files
347	365		- The compiler defines: FPC_MM_SMALL
348	366
349	367		#### Medium
350	368
351	369		- Activated by the `-WmMedium` compiler option
352	370		- Code \<= 1MB, Data + Heap + Stack \<= 64KB
353	371		- DS = SS
354	372		- Pointer = NearPointer
355	373		- CodePointer = FarPointer
356	374		- Can produce only .exe files
357	375		- The compiler defines: FPC_MM_MEDIUM
358	376
359	377		#### Compact
360	378
361	379		- Activated by the `-WmCompact` compiler option
362	380		- Code \<= 64KB, Data \<= 64KB, Stack \<= 64KB, Heap \<= 1MB
363	381		- Data structures cannot exceed 64KB
364	382		- Pointer = FarPointer
365	383		- CodePointer = NearPointer
366	384		- Can produce only .exe files
367	385		- The compiler defines: FPC_MM_COMPACT
368	386
369	387		#### Large
370	388
371	389		- Activated by the `-WmLarge` compiler option. This is the memory model used by Turbo Pascal version 4 and above
372	390		- Code \<= 1MB, Data \<= 64KB, Stack \<= 64KB, Heap \<= 1MB
373	391		- Data structures cannot exceed 64KB
374	392		- Pointer = FarPointer
375	393		- CodePointer = FarPointer
376	394		- Can produce only .exe files
377	395		- The compiler defines: FPC_MM_LARGE
378	396
379	397		#### Huge
380	398
381	399		- Activated by the `-WmHuge` compiler option
382	400		- Code \<= 1MB, Data \<= 1MB, Stack \<= 64KB, Heap \<= 1MB
383	401		- Static data of a single pascal module (i.e. unit or program) cannot exceed 64KB
384	402		- Data structures cannot exceed 64KB
385	403		- Pointer = FarPointer
386	404		- CodePointer = FarPointer
387	405		- Can produce only .exe files
388	406		- The compiler defines: FPC_MM_HUGE
389	407
390	408		### Units and programs exceeding 64KB of code
391	409
392	410		Although the medium, large and huge memory models support up to 1MB of code for the whole program+units, there's still a limit of 64kb code per pascal module (i.e. unit or program). If this limit is exceeded, you can overcome this by splitting the unit or program that exceeded 64KB into smaller units, so that each of them stays within the 64KB limit. But there's also an easier solution. You can put the following directive in the module that exceeds 64KB:
393	411
394		-	~~`{$HUGECODE on}`~~
	412	+	```text
	413	+	{$HUGECODE on}
	414	+	```
395	415
396	416		This forces each procedure and function to be in a separate segment. Note that since the code of the unit is no longer in a single segment, this also disallows mixing near and far procedures in the same unit, so in this mode, 'near' and {\$F-} are ignored.
397	417
398	418		Using {\$HUGECODE on} does not count as using a different memory model, because you can freely mix units with {\$HUGECODE on} and {\$HUGECODE off} in the same program.
399	419
400	420		### Supported calling conventions
401	421
402	422		Currently, only the Pascal calling convention is supported. All the other calling conventions are entirely untested and should not be used, because they may or may not work and may change at any time.
403	423
404	424		#### Pascal
405	425
406	426		This is the default calling convention. It strives for compatibility with Turbo Pascal 7.
407	427
408	428		- Parameters are pushed on the stack left to right.
409	429		- The callee cleans the parameters from the stack.
410	430		- Procedures and functions must preserve DS, SS and BP and may destroy AX, BX, CX, DX, SI, DI and ES.
411	431		- 16-bit results are returned in AX, 32-bit results in DX:AX
412	432		- 64-bit ints are returned in AX:BX:CX:DX. Note that Turbo Pascal doesn't support int64, so this behavior is borrowed from Open Watcom's 'pascal' calling convention.
413	433
414	434		## Troubleshooting
415	435
416	436		### Compile error: missing .o files
417	437
418	438		Problem: If you see errors/warnings like this during compiling & linking:
419	439
420	440		```text
421	441		test.pas(12,24) Warning: Object system.o not found, Linking may fail !
422	442		Error! E2008: cannot open system.o : No such file or directory
423	443		```
424	444
425	445		(and indeed there don't appear to be any .o files in your msdos units directory)
426	446
427	447		Solution: You haven't used smartlinking. You should always compile i8086-msdos programs with smartlinking, i.e. use the -XX and -CX options. Smartlinking uses .a files, nonsmartlinking uses .o files.
428	448
429	449		The reason the .o files aren't generated is because the system unit exceeds the 64kb code limit for the small and tiny memory models and is therefore impossible to compile even 'hello world' without smartlinking, so creating the .o files is a waste of time. It might work for the medium model, but then you have to build the snapshot without -CX. However, with the tight memory constraints of real mode DOS, there is little reason not to use smartlinking in every memory model. Also, the medium model still has a limit of 64k code per unit, so even there it might not work without smartlinking. It certainly hasn't been tested.
430	450
431	451		Hint: You can add these options to your fpc.cfg file, as described in the "Updating your fpc.cfg" section.
432	452
433	453		## Running the testsuite
434	454
435	455		### Using DOSBox
436	456
437	457		- build a snapshot for the memory model you want to test
438	458		- it is recomended to use a 32-bit x86 build of DOSBox, because the 64-bit one has inaccurate FPU emulation
439	459		- compile fpc/tests/utils/dosbox/dosbox_wrapper.pas for your native platform
440	460		- prepare and run a script like this:
441	461
442	462		``` bash
443	463		#!/bin/sh
444	464
445	465		FPCDIR=/home/blablabla/fpc-i8086/fpc
446	466		MEMMODEL=Small
447	467
448	468		export FPCMAKE=$FPCDIR/utils/fpcm/fpcmake
449	469		export DOSBOX=/usr/bin/dosbox
450	470		export SDL_VIDEODRIVER=dummy
451	471		export SDL_AUDIODRIVER=dummy
452	472
453	473		cd $FPCDIR/tests/
454	474
455	475		ulimit -m 256000
456	476		#ulimit -v 256000
457	477		ulimit -d 256000
458	478
459	479		echo running testsuite
460	480		make full FPCFPMAKE=$FPCDIR/compiler/ppcx64 TEST_FPC=$FPCDIR/compiler/ppcross8086 TEST_OPT=-Wm$MEMMODEL EMULATOR=$FPCDIR/tests/utils/dosbox/dosbox_wrapper
461	481		```
462	482
463	483		## See also
464	484
465	485		- [[GO32V2]] - DOS Extender
466	486		- [[go32v2 development]]
467	487
468	488		---
469	489		From the Free Pascal wiki, page "DOS", as it stood on 2021-04-14 after a change by Ñuño Martínez, 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).
470	490		Category: Cross compilation
471	491		Category: DOS
472	492		Category: FPC
473	493		Category: FPC internals
474	494		Category: Historical
475	495		Category: Operating Systems and Platforms

Back to history