Target

Target type description.

Basic program

Target	Description
BIN	BASIC binary program (starting at 8000h)
BIN_USR	BASIC USR binary driver (starting at C000h)
BAS	Alias for BIN

Note: The maximum size of a BASIC program is about 24 KB (including variables).

MSX-DOS program

Target	Description
DOS1	MSX-DOS 1 program (starting at 0100h)
DOS2	MSX-DOS 2 program (starting at 0100h)
DOS	Alias for DOS1

Note: The maximum size of a MSX-DOS program is about 53 KB (including variables).

Plain ROM program

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

Mapped ROM program

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.

Setup

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

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

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:

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

//-- 512 KB Konami SCC mapped-ROM
target = ROM_KONAMI_SCC;
ROMSize = 512;

See projects/samples/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:

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

The Build Tool build the first 32 KB of the mapped-ROM like a 32 KB plain ROM. This represents the first 4 segments for a 8 KB mapper and the first 2 for a 16 KB 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 128 KB:

program.c          | Main program including segment #0~#3 (4*8 KB)
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:

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

Targets overview

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

Main

For ROM or Basic program, the main function prototype is:

void main();

For DOS1 target, this prototype can also be used to get command-line arguments:

void main(u8 argc, const c8** argv);

For DOS2 target, this prototype can also be used to return a value du MSX-DOS:

u8 main();
u8 main(u8 argc, const c8** argv);