You can install it in your device (cell phone or computer)!
I recommend Installing it because you'll have a better experience: notifications when there's new content, direct access from your home screen, and faster loading times.
MapperHeap
Project sheet
Year
2026
Status
Type
Software library (memory allocator)
Platforms
Any MSX computer running MSX-DOS2 or Nextor
Language
Z80 assembly
License
Apache License, Version 2.0
Summary
This is a general-purpose mapper memory allocator library for MSX-DOS2/Nextor that I wrote to use in my own projects. I'm making it freely available (under the Apache 2.0 license) for anybody else who may find it useful.
Description
MSX computers use the Z80 CPU (and also the Z80-compatible R800 in the case of MSX turbo R computers). The address space in these CPUs is only 16 bits, so they can only see up to 64 KB of RAM at any given time.
To work around this limitation, the MSX standard uses several techniques, which I won't describe here. Visit the article I wrote about this if you want to get into the technical details: How memory works in MSX computers
Functionality
This library provides similar functionality to the alloc() and free() calls in modern C language, but under assembly language for MSX computers equipped with one or more memory mappers.
The code works under MSX-DOS2 or Nextor, because it uses the operating system's mapper support routines.
It makes memory management semi-transparent to the programmer, by introducing a new concept: far pointers.
The far pointer format
Far pointers are 4-byte descriptors that identify not only a memory address, but also a mapper slot and mapper segment:
Using these far pointers, the programmer can use as much mapper memory as availble in the computer, without having to worry about detecting and managing it: the programmer requests a block of memory of size X, and (if there's enough free memory available), the library finds one and returns a far pointer to the block.
These far pointers can be stored anywhere in memory, but the library uses CPU page 2 (memory addresses 8000h to BFFFh) to map into memory the blocks they point to. Because of this, when the pointers live in allocated blocks themselves they need to be copied to pages 0, 1 or 3 of the Z80 address space before operating with them.
The library offers several assembly routines and macros to perform these operations.
Example programs
Included in the GitHub distribution there are five small example programs to help the programmer understand how to use the library:
- meminfo.as: the smallest possible program: start the library, ask how much mapper RAM the machine has
- fillheap.as: allocate until the heap is exhausted, then free everything and watch hblocks return to zero
- strlist.as: a linked list whose links live inside the blocks, in mapper RAM
- bigarray.as: data larger than one block: a 64 KB array spread over eight 8 KB blocks
- coalesce.as: freeing two blocks that touch, and seeing them merge
Visualization
The library comes with a test program that allocates 8 MB of random-sized memory blocks (1, 2, 4, 8, or 12 KB), frees 25% of them, and then allocates 8 MBs worth of small memory blocks of random sizes up to 2047 bytes each.
There's an HTML/Javascript visualization of the blocks allocated, assuming this memory configuration:
- Internal mapper of 512 KB on slot 3-0
- External mapper (1 MB) on slot 1-0
- Exernal mapper (4 MB) on slot 1-1
- External mapper (4 MB) on slot 1-2
- External mapper (4 MB) on slot 1-3
The visualization is here.
Documentation
The latest documentation will always be in the GitHub repository:
Other
This library was written to assemble under the AS.COM/LD.COM tools written by SOLID (Egor Voznesensky), which used to be available for free on his website (novatec.com, no longer online).
Unfortunately, Egor passed away in 2014 and the Novatec site disappeared some time afterwards, and the AS/LD binaries are no longer available.
Because of that, I'm making both programs downloadable in this page:
Both of them are copyright (C) 1995 by SOLID (Egor Voznesensky).
The library should work with Microsoft's M80/L80 assembler and linker, but I haven't confirmed personally.