Create a mapped ROM

To create cartridges larger than 64 KB, MSXGL allows to use 4 types of ROM mappers.

Principles

A mapped ROM is visible in pages 1 and 2 of the Z80 memory space (address 4000h-7FFFh and 8000h-BFFFh).
This 32 KB space is divided into either 4 banks of 8 KB or 2 banks of 16 KB. This is why mappers are often categorized as 8 KB mapper and 16 KB mapper.

ROMs using these mappers can be for example 128 KB, 256 KB, 512 KB, 1 MB, 2 MB or 4 MB in size (4 MB, only for 16 KB mapper).
The total content of the ROM is divided into blocks of the mapper size (8 or 16 KB). These blocks are called segments.

The concept of using mappers is to associate a given segment with a bank to make it visible to the Z80.
By changing the segments visible in each bank during the course of the program, we can thus access the entire contents of the ROM.

128 KB ROM using an 8 KB mapper (ASCII-8) in slot 2. The ROM is composed of 16 segments, visible to the Z80 through 4 banks.
In the example above, segment #0 is visible in bank #0, segment #1 in bank #1, segment #3 in bank #2 and segment #5 in bank #3.

To change the visible segment in a bank, you just have to write the segment number to a given address (different depending on the mappers).
Write in a ROM, yes, you read it right!
In fact, mapped ROMs have special mechanisms (mappers) that intercept write signals at certain addresses and use the written value to select the segment.
Using MSXgl, you don't need to know the addresses or write because you only need to use the SET_BANK_SEGMENT(bank, seg) macro which takes care of associating a segment to a bank.

The supported mappers are:

Target	Description
ROM_ASCII8	ASCII-8: 8 KB segments for a total of 64 KB to 2 MB
ROM_ASCII16	ASCII-16: 16 KB segments for a total of 64 KB to 4 MB
ROM_KONAMI	Konami MegaROM (aka Konami4) 8 KB segments for a total of 64 KB to 2 MB
ROM_KONAMI_SCC	Konami MegaROM SCC (aka Konami5): 8 KB segments for a total of 64 KB to 2 MB

More details on the different mappers:

• https://www.msx.org/wiki/MegaROM_Mappers
• http://bifi.msxnet.org/msxnet/tech/megaroms

Note: "MegaROM" refers to a ROM of 128 KB or more. Even though they are not widely supported, there is nothing to prevent you from creating a 64 KB ROM using a mapper. We therefore prefer to use the term Mapped ROM here rather than MegaROM.

How to

Setup

First, you need to decide which mapper you want to use and what size you need.
If you have no idea, start with a 128 KB ROM using ASCII-8 mapper.

The choice of ROM is made in the configuration file of the build tool (build.bat).

Example:

set target=ROM_ASCII8
set ROMSize=128

See the details of the configuration of the build tool: Targets#Mapped_ROM_program.

Example

A sample program is available to demonstrate the use of ROM mappers.

In this example, we create a 128 KB mapped ROM in ASCII-8 format (16 segments). The first 4 segments are defined in the main program and 2 others in separate files.

Sample files:

MSXgl
└ projects
  └ samples
    ├ [https://github.com/aoineko-fr/MSXgl/blob/main/projects/samples/s_mapper.c s_mapper.c] (main program)
    ├ [https://github.com/aoineko-fr/MSXgl/blob/main/projects/samples/s_mapper.cmd s_mapper.cmd] (build tool configuration)
    ├ [https://github.com/aoineko-fr/MSXgl/blob/main/projects/samples/s_mapper_s4_b2.c s_mapper_s4_b2.c] (segment #4 C source)
    └ [https://github.com/aoineko-fr/MSXgl/blob/main/projects/samples/s_mapper_s5_b3.asm s_mapper_s5_b3.asm] (segment #5 assembler source)

In the Build Tool:

• s_mapper.c will be compile as a 32 KB plain ROM (which represents the first 4 segments).
• Then, the Build Tool will search for source files for segment #5 to #15 starting with s_mapper_. 3 files extensions are supported: .c, .asm and .s.
  • s_mapper_s4_b2.c will be find, compile and added to link list.
  • s_mapper_s5_b3.asm will be find, compile and added to link list. Assembler segment source file must include the .area directive with the segment name _SEG{num} (_SEG5 here).
• All the source will be linked together (and symbols will be "resolved").
• The final binary file will be create by MSXhex,