MSX-DOS

│ English (en) │

MSX-DOS is a CP/M-DOS-like operating system developed by Microsoft for the Z80 based MSX computer.

Starting with revision r45600 Free Pascal has initial support for generating code for MSX-DOS.

Overview

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.

At least MSX-DOS 2.0 or newer is required.

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.

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.

Building the compiler

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>.

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:

make all OS_TARGET=msxdos CPU_TARGET=z80 OPT=-CX

Building a program

Once you've build the compiler and RTL you can then build programs using the following command:

./compiler/ppcrossz80 -n -Tmsxdos -Furtl/units/z80-msxdos -viwn -FE<OUTPUTDIR> -FDutils/ihxutil/bin/<HOSTCPU>-<HOSTOS> -CX -XX file.pp

The options -CX -XX are very important to enable smartlinking to have even remotely a chance to fit the program into the available space.

If you place the ihxutil utility into a directory reachable by the PATH environment variable you can leave out the -FD... parameter.

Setting heap and stack size

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. The format of the directive is

{$MEMORY StackSize,HeapSize}

Known problems

This is a list of currently known problems:

• Parameters are not correctly initialized (code generator problem?)
• Assign() does not correctly set the filename (code generator problem?)
• HexStr() does not result in correct hex strings (code generator problem?)
• MkDir(), ChDir(), RmDir() are not implemented (MSX-DOS does not seem to support these?)

Differences to Turbo Pascal 3.0

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 and maybe also the Programmer's Guide of FPC is suggested.

Support for units

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.

See also here

Inline assembly

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).

See also here

Inlining

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).

See also here