Appendix G
Memory

TATARA and TANREN keep their tables, and TANREN keeps the program it builds, in the MSX’s memory mapper, not in the 64 KB that the Z80 can see. This appendix describes how the tools use memory, how much they need to build a program, and what to do when there is not enough. It is about the memory the tools need while they work, not about the memory the finished program needs when it runs.

G.1 The memory map

A memory mapper is RAM divided into segments of 16 KB. The Z80 sees four of them at a time, one in each quarter of its 64 KB, which are called pages. Figure G.1 shows how the four pages are used while TATARA or TANREN runs:

• 0000h–3FFFh and 4000h–7FFFh: MSX-DOS uses the bytes below 0100h; from 0100h, the tool itself, its code and the data it needs all the time.
• 8000h–BFFFh: the window. The tool brings one segment of the mapper at a time into this page, to read or write what it keeps there, and gives the page back to MSX-DOS before each call to it.
• C000h–FFFFh: MSX-DOS and the stack.

G.2 What goes into the mapper

The segments that MSX-DOS2 has not given to anything else are free, and the tools ask MSX-DOS2 for them as they need them:

• TATARA keeps there the names and their values, the bodies of macros, and the records it will write into the object file.
• TANREN keeps there the segments and names of every module, and the program it is building. The program takes one segment for each 16 KB of addresses it covers: a program from 0100h to A0FFh covers three. Addresses that nothing is written to take no segment.

So the size of a program is limited by the free memory of the mapper, not by the memory that MSX-DOS leaves for programs below C000h.

G.3 How much memory the tools need to build a program

What counts is the free memory, not the total. MSX-DOS2 takes part of the mapper for itself: 112 KB on an MSX2 or MSX2+ and 176 KB on an MSX turbo R, in the tests below, without a RAM disk. A RAM disk takes more.

Table G.1 shows what fitted in the free memory of several machines. Each source defined names of 16 characters with EQU, and the program was 40 KB of data, linked as a .COM program.

These rules of thumb follow from it:

• Each 16 KB of free memory holds about 495 names of 16 characters, so a name takes about 33 bytes. Shorter names take less.
• TANREN needs one free segment for each 16 KB of addresses the program covers, as well as room for its tables.
• With 16 KB free, the least that MSX-DOS2 leaves on an MSX with 128 KB, the tools run, but can build only small programs.
• With 80 KB free, the tools build themselves (chapter 35): a program of 27 modules and some 30 KB. An MSX2 with 192 KB, or a turbo R with 256 KB, has that much.
• With 336 KB free or more, everything in the table fits. A mapper of 512 KB is comfortable for any program that fits in an MSX.

Most cartridges that give an MSX2 the MSX-DOS2 kernel bring a mapper of their own: ASCII’s MSX-DOS2 cartridge has 128 KB, the SD-512 and the MegaFlashRom SCC+ SD 512 KB, and the Carnivore2 1 MB. A cartridge with only a mapper, such as the MEGA-MAPPER with up to 4 MB or the 16 MB memory cartridge V3, adds memory to any MSX. Appendix H lists these cartridges and where to get them.

How much memory an MSX has

The startup screen of an MSX shows how much memory it has, but some models show only the memory of the mapper inside the computer, not of one in a cartridge. MAPPER.COM, from https://github.com/javilm/msx-mapper, shows every mapper that MSX-DOS2 found, with how much of each MSX-DOS2 uses and how much is free:

A:\>mapper 
Total 256Kb (176Kb sys, 0Kb user, 80Kb free). 
Memory mappers detected by MSX-DOS2: 
[PRIMARY] Expanded slot 3-0: 176Kb sys, 0Kb user, 80Kb free.
 

The free figure is the one that the tools can use.

G.4 When the mapper is full

When there is no free segment left, the tool stops with out of mapper memory. To get more room:

• Remove the RAM disk, if there is one: ramdisk 0 gives its memory back to MSX-DOS2. Programs that stay in memory take mapper segments too.
• Split the program into more modules (chapter 28). TATARA needs room for the names of one module at a time.
• Add memory: a mapper cartridge, as above.