Difference between revisions of "Target"
From MSX Game Library
(→Plain ROM program) |
(→Mapped ROM program) |
||
(74 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
+ | The choice of the target determines the final format of the game: ROM, disk, etc. | ||
+ | |||
+ | It is a parameter used by the [[Build Tool]] to adapt your code to the target during the construction of the final program and to assemble the data to be compatible with the target. | ||
+ | |||
+ | The choice of the format is made in the project configuration file (<tt>project_config.js</tt>). | ||
+ | |||
+ | Here is a description of the different target formats available in MSXgl. | ||
+ | |||
== Basic program == | == Basic program == | ||
− | + | Binary program to be executed from the BASIC environment using <tt>bload</tt> function. | |
{| class="wikitable" | {| class="wikitable" | ||
! Target !! Description | ! Target !! Description | ||
|- | |- | ||
− | | <tt> | + | | <tt>BIN_DISK</tt> || BASIC binary program (starting at 8000h) on disk |
+ | |- | ||
+ | | <tt>BIN_TAPE</tt> || BASIC binary program (starting at 8000h) on tape | ||
|- | |- | ||
− | | <tt> | + | | <tt>BIN_USR</tt> || BASIC USR binary driver (starting at C000h) |
|- | |- | ||
− | | <tt> | + | | <tt>BIN</tt> || Alias for BIN_DISK |
|- | |- | ||
− | | <tt> | + | | <tt>BAS</tt> || Alias for BIN_DISK |
|} | |} | ||
− | == | + | <u>Note</u>: ''The maximum size of a BASIC program is about 24 KB (including variables).'' |
+ | |||
+ | The [[Build tool]] deployment step places your final program in several formats: | ||
+ | * <tt>.bin</tt> format in <tt>emul/bin/</tt> folder | ||
+ | * <tt>.dsk</tt> format in <tt>emul/dsk/</tt> folder (image of a floppy disk containing your program) | ||
+ | * <tt>.cas</tt> format in <tt>emul/cas/</tt> folder (image of a tape cassette containing your program) | ||
+ | |||
+ | == MSX-DOS program == | ||
+ | Binary program to be executed from the MSX-DOS environment. | ||
+ | |||
{| class="wikitable" | {| class="wikitable" | ||
! Target !! Description | ! Target !! Description | ||
|- | |- | ||
− | | <tt> | + | | <tt>DOS1</tt> || MSX-DOS 1 program (starting at 0100h) |
|- | |- | ||
− | | <tt> | + | | <tt>DOS2</tt> || MSX-DOS 2 program (starting at 0100h) |
|- | |- | ||
− | | <tt> | + | | <tt>DOS0</tt> || Direct program boot from disk (starting at 0100h) |
|- | |- | ||
− | | <tt> | + | | <tt>DOS</tt> || Alias for <tt>DOS1</tt> |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
|- | |- | ||
− | | <tt> | + | | <tt>BOOT</tt> || Alias for <tt>DOS0</tt> |
|} | |} | ||
+ | <u>Note</u>: | ||
+ | * ''The maximum size of a MSX-DOS program is about 53 KB (including variables).'' | ||
+ | * ''For "DOS0" target, maximum is 48 KB (excluding variables).'' | ||
+ | |||
+ | The [[Build tool]] deployment step places your final program in two formats: | ||
+ | * <tt>.com</tt> format in <tt>emul/dosX/</tt> folder (<tt>dos1</tt>, <tt>dos2</tt> ou <tt>dos0</tt>) | ||
+ | * <tt>.dsk</tt> format in <tt>emul/dsk/</tt> folder (image of a disk containing your program) | ||
+ | |||
+ | == Plain ROM program == | ||
+ | {{IMG|raw.githubusercontent.com/aoineko-fr/MSXgl/main/engine/doc/img/target/rom_slot_32k.png|height:240px; margin:0.5em; float:right;|Exemple of default slot selection for a 32 KB plain ROM.}} | ||
+ | |||
+ | Binary program to be written into a ROM from 8 to 64 KB and executed from a cartridge. | ||
+ | {{:Target/Plain ROM }} | ||
+ | |||
+ | See also: [[Create a plain ROM]]. | ||
+ | |||
+ | The [[Build tool]] deployment step places your final program in <tt>emul/rom/</tt> folder. | ||
== Mapped ROM program == | == Mapped ROM program == | ||
+ | {{IMG|raw.githubusercontent.com/aoineko-fr/MSXgl/main/engine/doc/img/target/rom_slot_ascii8_128.png|height:240px; margin:0.5em; float:right;|Example of slot and segment selection for a 128 KB ASCII-8 mapped ROM.}} | ||
− | <u>Note</u>: ''"MegaROM" refers to a ROM of | + | <u>Note</u>: ''"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.'' |
− | |||
You can create program using one of the ROM mappers supported by MSXgl: | You can create program using one of the ROM mappers supported by MSXgl: | ||
{| class="wikitable" | {| class="wikitable" | ||
! Target !! Description | ! Target !! Description | ||
|- | |- | ||
− | | <tt>ROM_ASCII8</tt> || ASCII-8: | + | | <tt>ROM_ASCII8</tt> || ASCII-8: 8 KB segments for a total of 64 KB to 2 MB |
|- | |- | ||
− | | <tt>ROM_ASCII16</tt> || ASCII-16: | + | | <tt>ROM_ASCII16</tt> || ASCII-16: 16 KB segments for a total of 64 KB to 4 MB |
|- | |- | ||
− | | <tt>ROM_KONAMI</tt> || Konami MegaROM (aka Konami4) | + | | <tt>ROM_KONAMI</tt> || Konami MegaROM (aka Konami4): 8 KB segments for a total of 64 KB to 2 MB |
|- | |- | ||
− | | <tt>ROM_KONAMI_SCC</tt> || Konami MegaROM SCC (aka Konami5): | + | | <tt>ROM_KONAMI_SCC</tt> || Konami MegaROM SCC (aka Konami5): 8 KB segments for a total of 64 KB to 2 MB |
+ | |- | ||
+ | | <tt>ROM_NEO8</tt> || [[NEO mapper]]: 8 KB segments for a total up to 32 MB | ||
+ | |- | ||
+ | | <tt>ROM_NEO16</tt> || [[NEO mapper]]: 16 KB segments for a total up to 64 MB | ||
|} | |} | ||
− | In your <tt> | + | In your <tt>project_config.js</tt>, chose as <tt>target</tt> one of the above target type. |
You can specify the ROM size (in KB) in the <tt>ROMSize</tt> variable. Default value is 128 (KB). | You can specify the ROM size (in KB) in the <tt>ROMSize</tt> variable. Default value is 128 (KB). | ||
− | Any multiple value of the mapper's segment size is valid, but | + | Any multiple value of the mapper's segment size is valid, but we recommend using powers of 2 values (64, 128, 256, etc.) to help emulators to autodetect the right mapper. |
− | Some Build Tool configuration examples: | + | Some [[Build Tool]] configuration examples: |
+ | <syntaxhighlight lang="js"> | ||
+ | //-- 128 KB ASCII-8 mapped-ROM | ||
+ | target = "ROM_ASCII8"; | ||
+ | </syntaxhighlight> | ||
− | + | <syntaxhighlight lang="js"> | |
− | + | //-- 4 MB ASCII-16 mapped-ROM | |
− | + | target = "ROM_ASCII16"; | |
− | + | ROMSize = 4096; | |
− | + | </syntaxhighlight> | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | + | <syntaxhighlight lang="js"> | |
+ | //-- 512 KB Konami SCC mapped-ROM | ||
+ | target = "ROM_KONAMI_SCC"; | ||
+ | ROMSize = 512; | ||
+ | </syntaxhighlight> | ||
− | + | For more detail: | |
− | + | * [[Create a mapped ROM]] article. | |
− | + | * <tt>[[Samples#VGM|projects/samples/s_vgm]]</tt> sample for a concrete use case. | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | The Build | + | The [[Build tool]] deployment step places your final program in <tt>emul/rom/</tt> folder. |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
== Targets overview == | == Targets overview == | ||
Line 122: | Line 121: | ||
!rowspan="2"| Description | !rowspan="2"| Description | ||
|- | |- | ||
− | ! | + | ! P0 !! P1 !! P2 !! P3 |
|- | |- | ||
− | | <tt>ROM_8K</tt> || BIOS || Cart || RAM || RAM || | + | | <tt>ROM_8K</tt> || BIOS || Cart || RAM || RAM || 8 KB ROM in page 1 (4000h ~ 5FFFh) |
|- | |- | ||
− | | <tt>ROM_8K_P2</tt> || BIOS || RAM || Cart || RAM || | + | | <tt>ROM_8K_P2</tt> || BIOS || RAM || Cart || RAM || 8 KB ROM in page 2 (8000h ~ 9FFFh) |
|- | |- | ||
− | | <tt>ROM_16K</tt> || BIOS || Cart || RAM || RAM || | + | | <tt>ROM_16K</tt> || BIOS || Cart || RAM || RAM || 16 KB ROM in page 1 (4000h ~ 7FFFh) |
|- | |- | ||
− | | <tt>ROM_16K_P2</tt> || BIOS || RAM || Cart || RAM || | + | | <tt>ROM_16K_P2</tt> || BIOS || RAM || Cart || RAM || 16 KB ROM in page 2 (8000h ~ BFFFh) |
|- | |- | ||
− | | <tt>ROM_32K</tt> || BIOS || Cart || Cart || RAM || | + | | <tt>ROM_32K</tt> || BIOS || Cart || Cart || RAM || 32 KB ROM in page 1&2 (4000h ~ BFFFh) |
|- | |- | ||
− | | <tt>ROM_48K</tt> || BIOS || Cart || | + | | <tt>ROM_48K</tt> || BIOS || Cart || Cart || RAM || 48 KB ROM in page 0-2 (0000h ~ BFFFh) |
|- | |- | ||
− | | <tt>ROM_48K_ISR</tt> || Cart || Cart || Cart || RAM || | + | | <tt>ROM_48K_ISR</tt> || Cart || Cart || Cart || RAM || 48 KB ROM in page 0-2 (0000h ~ BFFFh) with ISR replacement |
|- | |- | ||
− | | <tt>ROM_64K</tt> || BIOS || Cart || Cart || RAM || | + | | <tt>ROM_64K</tt> || BIOS || Cart || Cart || RAM || 64 KB ROM in page 0-3 (0000h ~ FFFFh) |
|- | |- | ||
− | | <tt>ROM_64K_ISR</tt> || Cart || Cart || Cart || RAM || | + | | <tt>ROM_64K_ISR</tt> || Cart || Cart || Cart || RAM || 64 KB ROM in page 0-3 (0000h ~ FFFFh) with ISR replacement |
|- | |- | ||
− | | <tt>ROM_ASCII8</tt> || BIOS || Cart || Cart || RAM || ASCII-8: 8KB segments for a total of | + | | <tt>ROM_ASCII8</tt> || BIOS || Cart || Cart || RAM || ASCII-8: 8KB segments for a total of 64 KB to 2 MB |
|- | |- | ||
− | | <tt>ROM_ASCII16</tt> || BIOS || Cart || Cart || RAM || ASCII-16: 16KB segments for a total of | + | | <tt>ROM_ASCII16</tt> || BIOS || Cart || Cart || RAM || ASCII-16: 16KB segments for a total of 64 KB to 4 MB |
|- | |- | ||
− | | <tt>ROM_KONAMI</tt> || BIOS || Cart || Cart || RAM || Konami MegaROM (aka Konami4) | + | | <tt>ROM_KONAMI</tt> || BIOS || Cart || Cart || RAM || Konami MegaROM (aka Konami4): 8 KB segments for a total of 64 KB to 2 MB |
|- | |- | ||
− | | <tt>ROM_KONAMI_SCC</tt> || BIOS || Cart || Cart || RAM || Konami MegaROM SCC (aka Konami5): | + | | <tt>ROM_KONAMI_SCC</tt> || BIOS || Cart || Cart || RAM || Konami MegaROM SCC (aka Konami5): 8 KB segments for a total of 64 KB to 2 MB |
|- | |- | ||
| <tt>DOS1</tt> || RAM || RAM || RAM || RAM || MSX-DOS 1 program (starting at 0100h) | | <tt>DOS1</tt> || RAM || RAM || RAM || RAM || MSX-DOS 1 program (starting at 0100h) | ||
Line 154: | Line 153: | ||
| <tt>DOS2</tt> || RAM || RAM || RAM || RAM || MSX-DOS 2 program (starting at 0100h) | | <tt>DOS2</tt> || RAM || RAM || RAM || RAM || MSX-DOS 2 program (starting at 0100h) | ||
|- | |- | ||
− | | <tt> | + | | <tt>DOS0</tt> || RAM || RAM || RAM || RAM || Direct program boot from disk (starting at 0100h) |
+ | |- | ||
+ | | <tt>BIN_DISK</tt> || BIOS || BASIC || RAM || RAM || BASIC binary on disk (starting at 8000h) | ||
+ | |- | ||
+ | | <tt>BIN_TAPE</tt> || BIOS || BASIC || RAM || RAM || BASIC binary on tape (starting at 8000h) | ||
|- | |- | ||
− | | <tt> | + | | <tt>BIN_USR</tt> || BIOS || BASIC || RAM || RAM || BASIC USR binary driver (starting at C000h) |
|} | |} | ||
+ | |||
+ | == Main == | ||
+ | |||
+ | For ROM or Basic program, the main function prototype is: | ||
+ | <syntaxhighlight lang="c"> | ||
+ | void main(); | ||
+ | </syntaxhighlight> | ||
+ | |||
+ | For DOS1 target, this prototype can also be used to get command-line arguments (set <tt>DOSParseArg</tt> to allow arguments parsing): | ||
+ | <syntaxhighlight lang="c"> | ||
+ | void main(u8 argc, const c8** argv); | ||
+ | </syntaxhighlight> | ||
+ | |||
+ | For DOS2 target, this prototype can also be used to return a value du MSX-DOS: | ||
+ | <syntaxhighlight lang="c"> | ||
+ | u8 main(); | ||
+ | u8 main(u8 argc, const c8** argv); | ||
+ | </syntaxhighlight> | ||
+ | |||
+ | * <tt>argc</tt>: Integer that contains the number of arguments present in <tt>argv</tt>. The <tt>argc</tt> parameter can be 0 if no parameter have been added to the command line. | ||
+ | * <tt>argv</tt>: Array of null-terminated strings representing command-line arguments entered by the user of the program. | ||
+ | * <tt>return</tt>: The return value can be catch by MSX-DOS 2 as an error code to know if program process succeeded or not. |
Latest revision as of 22:40, 6 March 2024
The choice of the target determines the final format of the game: ROM, disk, etc.
It is a parameter used by the Build Tool to adapt your code to the target during the construction of the final program and to assemble the data to be compatible with the target.
The choice of the format is made in the project configuration file (project_config.js).
Here is a description of the different target formats available in MSXgl.
Contents
Basic program
Binary program to be executed from the BASIC environment using bload function.
Target | Description |
---|---|
BIN_DISK | BASIC binary program (starting at 8000h) on disk |
BIN_TAPE | BASIC binary program (starting at 8000h) on tape |
BIN_USR | BASIC USR binary driver (starting at C000h) |
BIN | Alias for BIN_DISK |
BAS | Alias for BIN_DISK |
Note: The maximum size of a BASIC program is about 24 KB (including variables).
The Build tool deployment step places your final program in several formats:
- .bin format in emul/bin/ folder
- .dsk format in emul/dsk/ folder (image of a floppy disk containing your program)
- .cas format in emul/cas/ folder (image of a tape cassette containing your program)
MSX-DOS program
Binary program to be executed from the MSX-DOS environment.
Target | Description |
---|---|
DOS1 | MSX-DOS 1 program (starting at 0100h) |
DOS2 | MSX-DOS 2 program (starting at 0100h) |
DOS0 | Direct program boot from disk (starting at 0100h) |
DOS | Alias for DOS1 |
BOOT | Alias for DOS0 |
Note:
- The maximum size of a MSX-DOS program is about 53 KB (including variables).
- For "DOS0" target, maximum is 48 KB (excluding variables).
The Build tool deployment step places your final program in two formats:
- .com format in emul/dosX/ folder (dos1, dos2 ou dos0)
- .dsk format in emul/dsk/ folder (image of a disk containing your program)
Plain ROM program
Binary program to be written into a ROM from 8 to 64 KB and executed from a cartridge.
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 |
See also: Create a plain ROM.
The Build tool deployment step places your final program in emul/rom/ folder.
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.
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 |
ROM_NEO8 | NEO mapper: 8 KB segments for a total up to 32 MB |
ROM_NEO16 | NEO mapper: 16 KB segments for a total up to 64 MB |
In your project_config.js, 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 we 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;
For more detail:
- Create a mapped ROM article.
- projects/samples/s_vgm sample for a concrete use case.
The Build tool deployment step places your final program in emul/rom/ folder.
Targets overview
Target | Selected at boot | Description | |||
---|---|---|---|---|---|
P0 | P1 | P2 | P3 | ||
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) |
DOS0 | RAM | RAM | RAM | RAM | Direct program boot from disk (starting at 0100h) |
BIN_DISK | BIOS | BASIC | RAM | RAM | BASIC binary on disk (starting at 8000h) |
BIN_TAPE | BIOS | BASIC | RAM | RAM | BASIC binary on tape (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 (set DOSParseArg to allow arguments parsing):
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);
- argc: Integer that contains the number of arguments present in argv. The argc parameter can be 0 if no parameter have been added to the command line.
- argv: Array of null-terminated strings representing command-line arguments entered by the user of the program.
- return: The return value can be catch by MSX-DOS 2 as an error code to know if program process succeeded or not.