Target

MSX-DOS program

Target	Description
DOS1	MSX-DOS 1 program (starting at 0100h)
DOS2	MSX-DOS 2 program (starting at 0100h)
DOS2_ARG	MSX-DOS 2 program with command line arguments (starting at 0100h) WIP

Plain ROM program

Target	Description
ROM_8K	8KB ROM in page 1 (4000h ~ 5FFFh)
ROM_8K_P2	8KB ROM in page 2 (8000h ~ 9FFFh)
ROM_16K	16KB ROM in page 1 (4000h ~ 7FFFh)
ROM_16K_P2	16KB ROM in page 2 (8000h ~ BFFFh)
ROM_32K	32KB ROM in page 1&2 (4000h ~ BFFFh)
ROM_48K	48KB ROM in page 0-2 (0000h ~ BFFFh)
ROM_48K_ISR	48KB ROM in page 0-2 (0000h ~ BFFFh) with ISR replacement
ROM_64K	64KB ROM in page 0-3 (0000h ~ FFFFh)
ROM_64K_ISR	64KB ROM in page 0-3 (0000h ~ FFFFh) with ISR replacement

Mapped ROM program

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

Setup

You can create program using one of the ROM mappers supported by MSXgl:

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

In your build.bat, chose as target one of the above target type. You can specify the ROM size (in KB) in the ROMSize variable. Default value is 128 (KB). Any multiple value of the mapper's segment size is valid, but I recommend using powers of 2 values (64, 128, 256, etc.) to help emulators to autodetect the right mapper.

Some Build Tool configuration examples:

REM -- 128KB ASCII-8 mapped-ROM
set target=ROM_ASCII8
 
REM -- 4MB ASCII-16 mapped-ROM
set target=ROM_ASCII16
set ROMSize=4096

REM -- 512KB Konami SCC mapped-ROM
set target=ROM_KONAMI_SCC
set ROMSize=512

See s_vgm sample for a concrete use case.

Build

Mapped-ROM use a system of sub-page (called "bank" here) the user can redirect to any segment of the ROM. Those banks are mapped to page #1 and #2 (4000h~BFFFh) of the memory space. The number of banks depends on the size of the mapper:

• 8KB mappers have 4 banks:
  • bank 0: 4000h~5FFFh
  • bank 1: 6000h~7FFFh
  • bank 2: 8000h~9FFFh
  • bank 3: A000h~BFFFh
• 16KB mappers have 2 banks:
  • bank 0: 4000h~7FFFh
  • bank 1: 8000h~BFFFh

The Build Tool build the first 32KB of the mapped-ROM like a 32KB plain ROM. This represents the first 4 segments for a 8KB mapper and the first 2 for a 16KB mapper.

The following segments are added to the ROM by the Build Tool by searching for files with a particular nomenclature: <project_name>_s<segment_number>_b<target_bank>.c.

For example with a ASCII-8 ROM of 128KB:

program.c          | Main program including segment #0~#3 (4*8KB)
program_s4_b2.c    | Segment #4 to be used in bank #2 (8000h~9FFFh)
program_s5_b3.c    | Segment #5 to be used in bank #3 (A000h~BFFFh)
                   | No files found for segment #6 to #14: padding data added to the ROM
program_s15_b2.c   | Segment #15, the last one, to be used in bank #2 (8000h~9FFFh)

Segment selection

In your program, you can then select what segment is visible from what bank using the SET_BANK_SEGMENT(bank, seg) macro. For example, to put segment 15 of the above example in bank 2, just use SET_BANK_SEGMENT(2, 15);

For information, at startup, the following segments are selected:

• 8KB mappers:
  • bank 0: segment 0
  • bank 1: segment 1
  • bank 2: segment 2
  • bank 3: segment 3
• 16KB mappers:
  • bank 0: segment 0
  • bank 1: segment 1

Targets overview

Target	0	1	2	3 Description
ROM_8K	BIOS	Cart	RAM	RAM	8KB ROM in page 1 (4000h ~ 5FFFh)
ROM_8K_P2	BIOS	RAM	Cart	RAM	8KB ROM in page 2 (8000h ~ 9FFFh)
ROM_16K	BIOS	Cart	RAM	RAM	16KB ROM in page 1 (4000h ~ 7FFFh)
ROM_16K_P2	BIOS	RAM	Cart	RAM	16KB ROM in page 2 (8000h ~ BFFFh)
ROM_32K	BIOS	Cart	Cart	RAM	32KB ROM in page 1&2 (4000h ~ BFFFh)
ROM_48K	BIOS	Cart	RAM	RAM	48KB ROM in page 0-2 (0000h ~ BFFFh)
ROM_48K_ISR	Cart	Cart	Cart	RAM	48KB ROM in page 0-2 (0000h ~ BFFFh) with ISR replacement
ROM_64K	BIOS	Cart	Cart	RAM	64KB ROM in page 0-3 (0000h ~ FFFFh)
ROM_64K_ISR	Cart	Cart	Cart	RAM	64KB ROM in page 0-3 (0000h ~ FFFFh) with ISR replacement
ROM_ASCII8	BIOS	Cart	Cart	RAM	ASCII-8: 8KB segments for a total of 64KB to 2MB
ROM_ASCII16	BIOS	Cart	Cart	RAM	ASCII-16: 16KB segments for a total of 64KB to 4MB
ROM_KONAMI	BIOS	Cart	Cart	RAM	Konami MegaROM (aka Konami4) 8KB segments for a total of 64KB to 2MB
ROM_KONAMI_SCC	BIOS	Cart	Cart	RAM	Konami MegaROM SCC (aka Konami5): 8KB segments for a total of 64KB to 2MB
DOS1	RAM	RAM	RAM	RAM	MSX-DOS 1 program (starting at 0100h)
DOS2	RAM	RAM	RAM	RAM	MSX-DOS 2 program (starting at 0100h)
DOS2_ARG	RAM	RAM	RAM	RAM	MSX-DOS 2 program with command line arguments (starting at 0100h) WIP
BIN	BIOS	BASIC	RAM	RAM	BASIC binary program (starting at 8000h)