MSX-DOS: what changed

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

Old	New		Line
1	1		MSX-DOS is a CP/M-DOS-like operating system developed by Microsoft for the Z80 based MSX computer.
2	2
3	3		Starting with revision r45600 Free Pascal has initial support for generating code for MSX-DOS.
4	4
5	5		## Overview
6	6
7	7		The compiler generates flat COM files which reside in the Transient Program Area (TPA) of the memory that reaches from \$100 to the address of the DOS (which might start at something like \$DEF0 or so). The top of the TPA is the place of the stack (at program start the top of the stack points below the start of the DOS) and FPC reserves an area for the heap inside the TPA as well. Thus the size for the program code and data is currently restricted to the remaining size. Mechanisms for (transparently) utilizing the slot mechanisms of the MSX need yet to be researched. Due to this restriction extreme care needs to be taken when linking in code as the limit can be reached quickly and quietly.
8	8
9	9		At least MSX-DOS 2.0 or newer is required.
10	10
11	11		In addition FPC produces rather verbose code compared to e.g. Turbo Pascal 3.0. It needs to be seen whether this can be improved in the future.
12	12
13	13		As of revision r45600 the System unit is supported, but neither the DOS nor the SysUtils unit are. The ObjPas and ISO7185 units are compiled though not yet tested. Console as well as File I/O are implemented, though only the former is tested due to apparent bugs in the code generator.
14	14
15	15		## Building the compiler
16	16
17	17		First of you need the ihxutil utility. For this simply do a build of FPC for your host target which will build the utility as well and the resulting binary will then reside in utils/ihxutil/bin/\<HOSTCPU\>-\<HOSTOS\>.
18	18
19	19		Currently a make all in the top level directory of the FPC sources does not fully succeed, but it works enough that the resulting compiler and RTL can be used, so use the following:
20	20
21		-	~~`make all OS_TARGET=msxdos CPU_TARGET=z80 OPT=-CX`~~
	21	+	```text
	22	+	make all OS_TARGET=msxdos CPU_TARGET=z80 OPT=-CX
	23	+	```
22	24
23	25		## Building a program
24	26
25	27		Once you've build the compiler and RTL you can then build programs using the following command:
26	28
27		-	~~`./compiler/ppcrossz80 -n -Tmsxdos -Furtl/units/z80-msxdos -viwn -FE<OUTPUTDIR> -FDutils/ihxutil/bin/<HOSTCPU>-<HOSTOS> -CX -XX file.pp`~~
	29	+	```text
	30	+	./compiler/ppcrossz80 -n -Tmsxdos -Furtl/units/z80-msxdos -viwn -FE<OUTPUTDIR> -FDutils/ihxutil/bin/<HOSTCPU>-<HOSTOS> -CX -XX file.pp
	31	+	```
28	32
29	33		The options -CX -XX are very important to enable smartlinking to have even remotely a chance to fit the program into the available space.
30	34
31	35		If you place the ihxutil utility into a directory reachable by the PATH environment variable you can leave out the -FD... parameter.
32	36
33	37		## Setting heap and stack size
34	38
35	39		The default heap size is 256 Byte and the default stack size is 1024. This can be changed using the \$MEMORY directive as documented [here](https://www.freepascal.org/docs-html/current/prog/progsu102.html#x110-1110001.3.19). The format of the directive is
36	40
37		-	~~`{$MEMORY StackSize,HeapSize}`~~
	41	+	```text
	42	+	{$MEMORY StackSize,HeapSize}
	43	+	```
38	44
39	45		## Known problems
40	46
41	47		This is a list of currently known problems:
42	48
43	49		- Parameters are not correctly initialized (code generator problem?)
44	50		- [[Assign]]() does not correctly set the filename (code generator problem?)
45	51		- HexStr() does not result in correct hex strings (code generator problem?)
46	52		- MkDir(), ChDir(), RmDir() are not implemented (MSX-DOS does not seem to support these?)
47	53
48	54		## Differences to Turbo Pascal 3.0
49	55
50	56		A common Pascal compiler for MSX is Turbo Pascal 3.0. There are a few significant differences between FPC and that version of Turbo Pascal (even if mode TP is used). In general a look at the [Language Reference Guide](https://www.freepascal.org/docs-html/current/ref/ref.html) and maybe also the [Programmer's Guide](https://www.freepascal.org/docs-html/current/prog/prog.html) of FPC is suggested.
51	57
52	58		### Support for units
53	59
54	60		Turbo Pascal 3.0 did not yet support the concept of units that premiered in newer versions of Turbo Pascal. FPC however does support them, so you can put your code into separate units. Though you can still use include files if you want to, but units like System will be used automatically.
55	61
56	62		See also [here](https://www.freepascal.org/docs-html/current/ref/refse106.html#x216-23800016.2)
57	63
58	64		### Inline assembly
59	65
60	66		FPC does not support Turbo Pascal's Inline() intrinsic to provide inline assembly. Instead FPC provides a mnemonic based inline assembly that is started with asm and ended with end. Whole functions can be declared such if they're marked with the assembler directive (plus probably nostackframe to avoid the compiler setting up a stackframe).
61	67
62	68		See also [here](https://www.freepascal.org/docs-html/current/ref/refch18.html#x232-25400018)
63	69
64	70		### Inlining
65	71
66	72		FPC can inline functions declared with the inline directive (there are some restrictions though, e.g. no assembly blocks allowed, no open array parameters and a few others), meaning that a call is avoided at the expense of potentially bloating the binary size, though it might lead to better optimized code (especially if constant parameters are used).
67	73
68	74		See also [here](https://www.freepascal.org/docs-html/current/ref/refsu73.html#x191-21300014.10.4)
69	75
70	76		---
71	77		From the Free Pascal wiki, page "MSX-DOS", as it stood on 2022-09-07 after a change by Alextp, 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).

Back to history